Commit the site-audit builder, with the audited notes as its only hand input

[realmarcin]

Closes #238, closes #266, closes #267, closes #268, closes #269, closes #273, closes #274, closes #275, closes #276, closes #277.

_fleet/data/site_audit.json was written by build_site_audit.py, a script that existed only in the #120 session's scratchpad. Each refresh had to rewrite it from the update skill's prose, and nothing checked that the rewrite derived each field the same way. That mattered once #212 made the nightly check depend on the audit's figure_at_pin and pin time.

What changes

• The builder: new scripts/fleet/build_site_audit.py --snapshot "$SNAP". It derives:

  • the pinned sha and commit date, from $SNAP/revisions.json;
  • merged PRs, from mech_stats.json, after checking it was counted at the pins;
  • each source's live figure and figure_at_pin, through check_cards.figure() on the served file and on its committed copy at the pin (read with git show from the snapshot clone);
  • the sha256 of both copies;
  • one generated sentence per source saying whether the live copy still matches the pin.

  It refuses to write when a card differs from its figure at the pin, when a site states fewer records than its card, when stats weren't counted at the pin, when a source has no committed copy and isn't declared in check_cards.NO_PIN_COPY, when notes are missing (naming only those), when the pin time is unreadable or in the future, or when a commit date has no offset (build_site_audit's missing-notes refusal always names culturebotai-claw and the default notes path #267, The update skill no longer specifies pinned_at_utc's format or revisions.json's layout, which the audit builder reads unchecked #269, build_site_audit reads a commit_date with no offset as local time, while pin_time reads one as UTC #274).

• The notes: the audited notes and scope move to the new _fleet/audit_notes.json, the builder's only hand-written input.

• Docs: step 7 of the update skill now runs the builder instead of describing it. Step 1 gives the revisions.json layout the builder reads (The update skill no longer specifies pinned_at_utc's format or revisions.json's layout, which the audit builder reads unchecked #269). _fleet/README.md describes the audit and its builder. The WRONG remedy, in the README and in check_cards.py's closing line, now says to re-derive figure_at_pin, never edit it (The WRONG remedy says to hand-edit figure_at_pin, which the audit builder now derives #268). AUDIT's remedy is split by cause: rebuild for figure_at_pin, the last builder-written audit for the pins, a full refresh for a new Mech (check_cards: AUDIT's remedy says to fix site_audit.json by hand, though figure_at_pin and the pin time are derived #273, The AUDIT remedy loops when the pin time or the audit itself is what is broken #276).

Evidence

• Canary: build() was run in memory, without writing, against the Refresh the X-Mech page from the Mechs as they are now, and add the skill that does it #120 snapshot and the live sites. It reproduces the committed site_audit.json exactly, key order and notes included, for all eleven repositories. The only exception is CellStructureMech's live hash and site_figure_at_check: its site has grown from 577 to 584 since the audit was written. Every pin-derived field matches.
• Tests: python3 -m unittest discover -s tests: 86 tests pass. The new offline SiteAuditBuilderTests use fakes for fetch and git show, and cover:
  • where committed copies are looked for;
  • an unchanged source, a site that grew, a mistyped card, a site below its card, an unreadable figure;
  • an undeclared missing copy, and stats from another revision;
  • a json data source;
  • build() as a whole: key order, UTC commit dates, the CLAW entry, sorting, the notes refusal and bad pin times (build_site_audit.build() has no test: the notes refusal, commit-date conversion, CLAW entry and sort are unchecked #266);
  • local_date under a non-UTC zone, each hash against its own copy, readme_url and merged_prs (Site-audit builder tests: local_date, the at-pin hash, a data source's page hash, readme_url and merged_prs are unchecked #275);
  • a check that every committed note starts with its text in audit_notes.json.
• Page: assemble_page.py --check reports current. site_audit.json itself is unchanged.

🤖 Generated with Claude Code