Close remaining audit follow-ups

Author: adewale

.gitattributes

@@ -1,9 +1,11 @@
-# `src/asset_manifest.py` is generated by `scripts/fingerprint_assets.py`
-# and `src/example_sources_data.py` by `scripts/embed_example_sources.py`.
+# `src/asset_manifest.py` is generated by `scripts/fingerprint_assets.py`,
+# `src/example_sources_data.py` by `scripts/embed_example_sources.py`, and
+# `src/editorial_registry_data.py` by `scripts/embed_editorial_registry.py`.
 # On merge/rebase, keep our side of the conflict — the post-merge and
-# post-rewrite hooks regenerate both files deterministically afterwards.
+# post-rewrite hooks regenerate these files deterministically afterwards.
 # This works once `scripts/install-git-hooks.sh` has been run locally,
 # which registers `merge.ours.driver = true` and points `core.hooksPath`
 # at `.githooks/`.
 src/asset_manifest.py merge=ours
 src/example_sources_data.py merge=ours
+src/editorial_registry_data.py merge=ours

.githooks/post-merge

@@ -1,11 +1,10 @@
 #!/usr/bin/env bash
-# Regenerate generated files after a merge or pull so embedded example
-# data and the asset manifest reflect the merged tree, not whichever
-# parent won the conflict.
+# Regenerate generated files after a merge or pull so embedded data,
+# asset manifests, fingerprints, and prototype pages reflect the merged
+# tree, not whichever parent won the conflict.
 set -e
 cd "$(git rev-parse --show-toplevel)"
-uv run --python 3.13 python scripts/embed_example_sources.py >/dev/null
-uv run --python 3.13 python scripts/fingerprint_assets.py >/dev/null
-if ! git diff --quiet src/example_sources_data.py src/asset_manifest.py public/_headers; then
+make build >/dev/null
+if ! git diff --quiet src/example_sources_data.py src/editorial_registry_data.py src/asset_manifest.py public/_headers public/prototyping; then
   echo "post-merge: generated files regenerated; stage and amend if needed"
 fi

.githooks/post-rewrite

@@ -1,11 +1,10 @@
 #!/usr/bin/env bash
-# Regenerate generated files after rebase/amend so embedded example data
-# and the asset manifest match the rewritten history, not whichever
-# commit happened to win each step.
+# Regenerate generated files after rebase/amend so embedded data,
+# asset manifests, fingerprints, and prototype pages match the rewritten
+# history, not whichever commit happened to win each step.
 set -e
 cd "$(git rev-parse --show-toplevel)"
-uv run --python 3.13 python scripts/embed_example_sources.py >/dev/null
-uv run --python 3.13 python scripts/fingerprint_assets.py >/dev/null
-if ! git diff --quiet src/example_sources_data.py src/asset_manifest.py public/_headers; then
+make build >/dev/null
+if ! git diff --quiet src/example_sources_data.py src/editorial_registry_data.py src/asset_manifest.py public/_headers public/prototyping; then
   echo "post-rewrite: generated files regenerated; stage and amend if needed"
 fi

.github/pull_request_template.md

@@ -5,7 +5,6 @@
 ## Verification
 
 - [ ] `make verify`
-- [ ] `scripts/check_example_migration_parity.py`
 - [ ] `scripts/format_examples.py --check`
 - [ ] `make verify-python-version VERSION=3.13`
 - [ ] `git diff --check`

.github/workflows/regenerate-generated-files.yml

@@ -1,8 +1,9 @@
 name: Regenerate generated files
 
 # Merges made through the GitHub UI bypass the local git hooks that keep
-# src/asset_manifest.py and src/example_sources_data.py in sync, so a merge to
-# main can land with stale generated files (and a red Verify run). This
+# src/asset_manifest.py, src/example_sources_data.py, and
+# src/editorial_registry_data.py in sync, so a merge to main can land with
+# stale generated files (and a red Verify run). This
 # workflow regenerates them and pushes a fix-up commit. Pushes made with
 # GITHUB_TOKEN do not trigger other workflows, so the fix-up commit is not
 # re-verified by CI; it only ever contains deterministic `make build` output.
@@ -43,7 +44,7 @@ jobs:
           for attempt in 1 2 3; do
             git pull --rebase origin main
             make build
-            git add -A src/example_sources_data.py src/asset_manifest.py public
+            git add -A src/example_sources_data.py src/editorial_registry_data.py src/asset_manifest.py public
             if git diff --cached --quiet; then
               echo "Generated files are current."
               exit 0

.github/workflows/verify.yml

@@ -51,7 +51,6 @@ jobs:
           CHROME_PATH: /usr/bin/google-chrome
         run: |
           make verify
-          scripts/check_example_migration_parity.py
           scripts/format_examples.py --check
           make verify-python-version VERSION=3.13
           git diff --check

CONTRIBUTING.md

@@ -49,7 +49,6 @@ Then run:
 
 ```bash
 make verify
-scripts/check_example_migration_parity.py
 scripts/format_examples.py --check
 make verify-python-version VERSION=3.13
 git diff --check
@@ -68,9 +67,9 @@ These scripts enforce the catalog-level rules from `docs/example-quality-rubric.
 
 | Script | What it gates |
 | --- | --- |
-| `scripts/check_registry_integrity.py` | Every owner slug in `docs/quality-registries.toml` exists in `manifest.toml`; tokens are present; each `paired_pages` pair is discoverable through `see_also`. |
-| `scripts/check_confusable_pairs.py` | Each confusable pair's owning page contains every token that signals the contrast; a token shadowed inside a longer sibling token (plain `def` inside `async def`) does not count. |
-| `scripts/check_broad_surface_tours.py` | Each broad-title page either covers every required form or sets `scope_first_pass = true` with `see_also` links to focused neighbors. |
+| `scripts/check_registry_integrity.py` | Every owner slug in `docs/quality-registries.toml` exists in `manifest.toml`; tokens are present; each `paired_pages` pair is discoverable through `see_also` and has registry-named cell tokens demonstrated inside a teaching cell. |
+| `scripts/check_confusable_pairs.py` | Each confusable pair's owning page contains every token inside teaching cells; a token shadowed inside a longer sibling token (plain `def` inside `async def`) does not count. |
+| `scripts/check_broad_surface_tours.py` | Each broad-title page either covers every required form or sets `scope_first_pass = true` with registry-named `focused_neighbors` linked through `see_also`. |
 | `scripts/check_footgun_coverage.py` | Each canonical Python footgun has a page that contains both broken-form and fixed-form tokens. |
 | `scripts/check_notes_supported.py` | Every `:::note` bullet (across all note blocks) shares at least one keyword with the page body outside the notes, so notes cannot assert behavior the page never demonstrates. |
 | `scripts/check_program_covers_cells.py` | Every executable cell shares substantive code with the `:::program` block, so the editor reproduces what the cells teach; `standalone_cells = true` opts out visibly. |
@@ -82,16 +81,16 @@ These scripts enforce the catalog-level rules from `docs/example-quality-rubric.
 | `scripts/check_journey_outcomes.py` | Every journey section declares learner outcomes. |
 | `scripts/audit_example_graph.py --check` | The `see_also` graph has no broken targets, self-links, over-linked pages, or orphaned examples. |
 
-The single source of truth for the registries is `docs/quality-registries.toml`. Add a new pair, broad tour, or footgun there, then update the owning page so the tokens appear in cells or prose.
+The single source of truth for the registries is `docs/quality-registries.toml`. Add confusable pairs, broad tours, footguns, journey metadata, figure attachments, captions, and curated scores there, then update the owning page so the tokens appear in cells or prose.
 
 ## Adding a new example end to end
 
 1. Write `src/example_sources/<slug>.md` (frontmatter, intro prose, one `:::program`, cells, notes) and add the slug to `manifest.toml`'s `order`.
 2. Add `see_also` links in both directions — `scripts/audit_example_graph.py --check` fails orphaned pages.
-3. Score the page against `docs/example-quality-rubric.md` and add the entry to `EXAMPLE_QUALITY_SCORES` in `src/marginalia.py`.
-4. Attach a figure in `src/marginalia.py` (or add a `no_figure_rationales` entry with a review date) and score it; review it on `public/prototyping/marginalia-gestalt.html`, which shows the production caption under every figure.
-5. Run `make build`, `make verify-examples`, `make quality-checks`, then `uv run python scripts/refresh_golden_fixture.py` and review the structural summary it prints.
-6. Run the full `make verify` with a local Worker running, then commit — including the regenerated `src/example_sources_data.py` and fixture.
+3. Score the page against `docs/example-quality-rubric.md` and add the `[[example_quality_scores]]` entry to `docs/quality-registries.toml`.
+4. Attach a figure by adding `[[figure_attachments]]` and `[[example_figure_scores]]` entries to `docs/quality-registries.toml` (or add a `no_figure_rationales` entry with a review date); keep only new paint functions in `src/marginalia.py`. Review the result on `public/prototyping/marginalia-gestalt.html`, which shows the production caption under every figure.
+5. Run `make build`, `make verify-examples`, `make quality-checks`, and `scripts/format_examples.py --check`.
+6. Run the full `make verify` with a local Worker running, then commit — including the regenerated `src/example_sources_data.py`, `src/editorial_registry_data.py`, `src/asset_manifest.py`, and fingerprinted assets.
 
 ## Secrets and deploy configuration
 

docs/example-figure-rubric.md

@@ -185,8 +185,8 @@ the figure can merge.
 
 ## Page-level coherence (per slug, multi-figure)
 
-A separate 0-1.0 score applied to slugs whose `ATTACHMENTS[slug]`
-list contains more than one figure. Multi-figure pages must form a
+A separate 0-1.0 score applied to slugs whose `[[figure_attachments]]`
+entries (loaded as `ATTACHMENTS[slug]`) contain more than one figure. Multi-figure pages must form a
 coherent set, not three angles on the same point.
 
 - **1.0** — figures show distinct aspects of the lesson in a

docs/example-source-format-spec.md

@@ -547,26 +547,23 @@ The command should fail if:
 
 `verify-python-version` is only meaningful when `uv` can run the requested Python version. Until Cloudflare exposes the same runtime locally, the migration also requires a Worker smoke test for representative examples and at least one POST execution through Dynamic Workers.
 
-## Golden fixture policy
+## Golden fixture cleanup policy
 
-`tests/fixtures/golden_examples.py` began as migration safety infrastructure and is now a reviewed **structural snapshot** of the parsed catalog: every example's metadata, program, expected output, and full cell sequence (prose, code, output, kind).
+`tests/fixtures/golden_examples.py` began as migration safety infrastructure: a frozen comparison point while the app switched from Python dictionaries to Markdown source files. That rollback window has passed, so the fixture and its refresh/parity scripts are removed rather than refreshed forever.
 
-What the gate proves: an accidental loader/parser/renderer change cannot silently rewrite the teaching structure readers get — it surfaces in `scripts/check_example_migration_parity.py` as snapshot drift across many examples, while a deliberate content edit drifts only the files actually touched. The gate is not a freshness check on content; refreshes are part of editing.
+Current rules:
 
-Rules:
-
-- Never hand-edit the fixture. Regenerate it with `scripts/refresh_golden_fixture.py`, which prints a structural summary (examples changed/added/removed and which fields moved) for review.
-- Commit a refresh together with the content change it reflects, and read the summary before committing — it is the reviewable record of what the edit did to teaching structure.
-- A change to `src/example_loader.py` or the parser must never require a fixture refresh; if it does, the loader change altered parsed structure and that is the regression.
-- `scripts/check_example_migration_parity.py` remains a required verification command.
+- Do not add a new checked-in catalog snapshot for ordinary content edits.
+- Review intentional teaching changes through the Markdown diff, generated-source diff, `verify_examples.py`, content gates, browser layout check, and rubric audit.
+- Parser changes must be justified by focused loader/verifier tests, not by refreshing a broad snapshot until it agrees with the new behavior.
+- If a future source-format migration needs parity again, add a temporary fixture and delete it in the same migration plan once a stable deployment and rollback window have passed.
 
 ## CI policy
 
 GitHub Actions must run the same checks expected locally:
 
 ```bash
 make verify
-scripts/check_example_migration_parity.py
 scripts/format_examples.py --check
 make verify-python-version VERSION=3.13
 git diff --check
@@ -576,7 +573,7 @@ CI must start `pywrangler dev --port 9696` before `make verify` so `browser-layo
 
 ## Contributor documentation policy
 
-The README must describe Markdown example editing, `:::program`, `:::cell`, generated embedded source data, `make build`, `make verify-examples`, and the parity check. Contributors should not need to edit `src/examples.py` or `src/example_sources_data.py` by hand.
+The README must describe Markdown example editing, `:::program`, `:::cell`, generated embedded source data, `make build`, `make verify-examples`, and the TOML editorial registries. Contributors should not need to edit `src/examples.py` or `src/example_sources_data.py` by hand.
 
 ## Worker bundling policy
 
@@ -599,15 +596,15 @@ The attempted migration failed at Worker startup because Markdown files were not
 
 Native Markdown bundling remains unproven and is not on the production path. The accepted solution is embedded source data generated by `scripts/embed_example_sources.py`. A future native bundling change must be isolated as a spike and prove local dev, production deploy, imports, cache fingerprinting, and failure behavior before replacing embedded data.
 
-## Golden parity script
+## Historical golden parity script
 
-Add a dedicated migration script before switching the app:
+During the app switch, add a dedicated migration script before switching the app:
 
 ```text
 scripts/check_example_migration_parity.py
 ```
 
-Required behavior:
+Required migration-time behavior:
 
 - Load the catalog through `src/example_loader.py` and the checked-in structural snapshot.
 - Compare example count and order.
@@ -619,7 +616,7 @@ Required behavior:
 - Fail on every semantic or teaching-structure difference. No allowlist is permitted for the app switch.
 - Print a short table of differences for review.
 
-This script is temporary migration scaffolding. It can be removed only after the old catalog is deleted, one production deployment succeeds, and the rollback window has passed.
+This script was temporary migration scaffolding. The old catalog was deleted, production deployment succeeded, and the rollback window passed; the script and fixture have now been removed.
 
 ## Fourteen prerequisite verification gates
 

docs/journey-visualisation-rubric.md

@@ -88,9 +88,9 @@ Score each section figure on a 10-point scale.
 - **Exactly one figure per section.** Section figures are not stacked.
   If the section needs two figures the section is doing two things.
 - **Caption present.** A figure without a `figcaption` is not allowed.
-- **Section summary aligns with caption.** The summary in
-  `src/app.py`'s `JOURNEYS` list agrees with what the figure caption
-  asserts. Disagreement means one or the other is wrong.
+- **Section summary aligns with caption.** The journey section summary in
+  `docs/quality-registries.toml` agrees with what the figure caption asserts.
+  Disagreement means one or the other is wrong.
 - **Renders within the centered figure block.** The figure obeys the
   width the layout gives it (`clamp(280px, 70vw, 640px)`); design at a
   viewBox whose rendered width fits the shared 640px ceiling.