Repair offline project-docs snapshot head matching

[erinepshovel-code]

Scope

Follow-up to #76 ("Repair clean offline project-docs bootstrap"), repairing Review bot findings 1–4 from its independent review of #76.

Base: this PR targets repair/project-docs-offline-bootstrap-20260923 (#76's head branch), not main. #76 is still open and unmerged, and the code being repaired (unavailableProjection, the offline snapshot test, the unavailable template branches) exists only on that branch. Once #76 merges, this PR should be retargeted to main.

Cause

• Finding 1 (P2): with OFFLINE=1 and a snapshot present, fetch-project-docs.mjs copied the snapshot wholesale and set fallback: true only at the top level. Per-repository entries never carried fallback, so pages rendered "exact-head build observation", and entries whose headSha no longer matched repos.json head_sha were kept. Snapshot head aaaa vs current bbbb rendered "No root README.md…", count 0, exact-head mode.
• Finding 2 (P2): a repository in repos.json missing from the snapshot (or a snapshot without byRepository) got no repoDocs, and repo.njk's final else branches rendered the "copied from the exact repository head" intro and exact-head mode.
• Finding 3 (P3): readSnapshot swallowed every error, so a corrupt snapshot was reported as "no last-known-good snapshot exists".
• Finding 4 (P3): the offline test regex-matched raw repo.njk source instead of rendered HTML, and asserted projectedDocumentCount: 0 for unobserved documentation.

Fix

• scripts/fetch-project-docs.mjs: offline projection now iterates repos.json. A snapshot entry is reused (with per-entry fallback: true) only when it is observed and headSha === repo.head_sha; otherwise the repository gets unavailableProjection with a reason-specific hmmm (different head, unknown current head, no entry in snapshot, or snapshot missing/unreadable/corrupt). readSnapshot now distinguishes missing (ENOENT), unreadable (other read errors) and corrupt (parse error / non-object root). Unavailable projections use projectedDocumentCount: null and projectedBytes: null instead of 0. Top-level fallback/fallbackCount now reflect the per-repository result. BOUNDARIES block updated to match.
• src/projects/repo.njk: separate intro for same-head fallback; the final else branches (intro, content, mode) now say unavailable / hmmm instead of implying an exact-head observation; the count shows a number only when projectedDocumentCount is number, otherwise hmmm.
• tests/offline-project-snapshot.test.mjs: runs the real script in isolated temp trees, then renders the real repo.njk through Eleventy (minimal layout and stand-in filters) and asserts on the rendered HTML. Cases: no snapshot, snapshot at matching head, stale snapshot head (aaaa… vs bbbb…), mixed repositories (one present, one missing), corrupt snapshot, and no emitted projection.
• src/_data/builder.json + tests/generated-site.test.mjs: required By the builder append (website-builder-journal) and the entry-count expectation (5 → 6).

Verification

Node v24.21.0, npm ci, then:

• npm test on Repair clean offline project-docs bootstrap #76 head 96fdf3d (before): 110 tests, 109 pass, 1 fail. The failure is tests/textbook-integrity.test.mjs:19, which fails offline on the base too and is unrelated.
• npm test on this branch (after): 115 tests, 114 pass, 1 fail. Same tests/textbook-integrity.test.mjs:19 offline failure; the 5 added tests pass.
• node --test tests/offline-project-snapshot.test.mjs: 7/7 pass. With this PR's script and template changes reverted and the new tests kept, 6/7 fail, so the tests catch the regressions.
• npm run check:builder -- --base 96fdf3d98864af32bb12e4ac89c823cd0277bfd8: passes.
• OFFLINE=1 npm run build: the refresh step printed project-docs metadata-only offline (missing snapshot), then Eleventy stopped at src/eai/aicontext.11ty.js ("aicontext production requires eight current textbook chapters without fallback"). That is the same offline textbook limitation, so no full-site rendered page was produced locally. Rendered-page behaviour is covered by the Eleventy rendering in the tests. Hosted npm run check is the full-build gate.

hmmm

• The By the builder entry's model field reads hmmm: Grok Bot executor (xAI); the exact runtime model version is not exposed to this runtime. website-builder-journal says the transaction stays blocked at hmmm when the exact model cannot be identified. This PR records that honestly rather than inventing a model name. Whether that is enough is a decision for the maintainer before merge.
• Out of scope, pre-existing and not fixed here: The-Interdependency.github.io_msdmd.ts imports ./.agents/skills/msdmd/collection, and .agents/skills/msdmd/ does not exist in this repository.
• tests/textbook-integrity.test.mjs:19 and the offline full-site build both need current textbook chapters, so neither can run offline. Local verification of a rendered repo page is limited to the test-harness Eleventy render.
• The test render uses stand-in where/statusClass/projectDocMarkdown filters and a minimal layout, not the production .eleventy.js. It checks template branch logic, not production markdown rendering.
• The online (non-offline) refresh path already applied a same-head per-repository rule and is unchanged apart from reading the new snapshot shape. A corrupt snapshot there is simply not reused and gets overwritten by the fresh snapshot.
• Base is Repair clean offline project-docs bootstrap #76's branch. If Repair clean offline project-docs bootstrap #76 changes or merges first, this PR needs a retarget/rebase check.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-26T19:26:26.049507Z	bc28238	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: bc28238523

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Supply the exact runtime model before merging

When this commit is merged, the required builder-journal entry will explicitly record that the model version is unknown rather than providing the exact runtime model mandated by the journal contract. validateModel only rejects a small set of generic labels, so this placeholder passes check:builder despite defeating the provenance requirement; obtain the exact model identity or keep the website-change transaction blocked.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Validate snapshot entries before reusing them

When a snapshot is syntactically valid JSON but an entry is structurally corrupt, a matching headSha is sufficient to enter this branch. For example, an entry with the matching head and "hmmm": {} throws while spreading prior.hmmm, aborting the offline refresh instead of emitting the promised unavailable projection; an entry missing documentation is likewise counted as a successful fallback even though the page renders it as unavailable. Require a valid observed projection shape, including array-valued hmmm and usable documentation, before treating an entry as same-head fallback.

Useful? React with 👍 / 👎.