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

CHANGELOG.md

@@ -14,20 +14,26 @@ The format is inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0
 - Figure contracts: XML well-formedness and text-escaping (Contract 11), mechanical caption rules (Contract 5c), reverse section-figure containment, and an end-to-end check that attached figures appear in rendered pages.
 - The marginalia gestalt shows one card per attachment with the production figcaption, so caption/figure disagreements are visible during review; prototype pages regenerate in `make build` and are covered by `make check-generated`.
 - Behavioral test suite for Turnstile clearance signing, challenge modes, cookie attributes, and HTML cache keys.
-- `scripts/refresh_golden_fixture.py`: regenerates the golden fixture as a structural snapshot and prints a reviewable summary of teaching-structure changes.
-- Security headers on Worker HTML responses and static assets (nosniff, referrer-policy, frame protections); POST body size cap with a friendly 413 page.
+- Security headers on Worker HTML responses and static assets (nosniff, referrer-policy, frame protections, and a full CSP); POST body size cap with a friendly 413 page.
 - An end-to-end "adding a new example" workflow and a complete quality-check table in `CONTRIBUTING.md`.
 
 ### Changed
 
 - The Makefile pins every Python invocation to 3.13 via `uv run`, so `make verify` matches CI regardless of the system interpreter; `make dev`/`deploy` use the workers dependency group.
 - CI workflows: deduplicated PR runs with explicit permissions and concurrency; preview workflow passes inputs through env vars (no shell interpolation next to the Cloudflare token), pins wrangler, and passes the smoke-bypass secret; the regenerate workflow pulls before building and retries with a rebuild on push races.
-- Quality gates got teeth: curated scores are bounded against the criterion heuristic (`--max-delta`), waivers must carry future ISO expiry dates and are flagged when stale, the journey-section average floor is enforced, confusable-pair tokens cannot be satisfied inside a longer sibling token, every `:::note` block is checked, `paired_pages` requires `see_also` discoverability, and the rubric-audit snapshot computes its findings from live registries instead of hardcoding PASS verdicts.
-- The golden parity gate compares the full parsed cell structure (including cell kinds) against the snapshot through the loader, with no dependence on the legacy walkthrough grouping.
+- Quality gates got teeth: curated scores are bounded against the criterion heuristic (`--max-delta`), waivers must carry future ISO expiry dates and are flagged when stale, the journey-section average floor is enforced, confusable-pair tokens must appear inside teaching cells and cannot be satisfied inside a longer sibling token, every `:::note` block is checked, `paired_pages` requires both `see_also` discoverability and registry-named cell evidence, scope-first-pass pages must link registry-named focused neighbors, and the rubric-audit snapshot computes its findings from live registries instead of hardcoding PASS verdicts.
+- Editorial metadata moved from Python literals into `docs/quality-registries.toml`: journeys, see-also edge labels, figure attachments, captions, and curated scores now load through `src/editorial_registry.py`.
+- Removed the migration-era golden fixture and parity/refresh scripts after the Markdown-backed release window; ordinary content edits now rely on verifiers, content gates, generated diffs, and browser/runtime checks rather than snapshot refreshes.
 - ASGI bridge: WebSocket close events reach the close handler (`onclose` was assigned to `onopen`), headers use latin-1 per the ASGI spec, and application lifespan runs once per Worker instead of per request.
 - Unknown `TURNSTILE_CHALLENGE_MODE` values fail closed to requiring a challenge; the smoke-bypass header compares in constant time.
 - Template substitution is single-pass, so submitted code containing `__TOKEN__` text can no longer corrupt the rendered page; embedded JSON escapes `<` so `</script>` in example code cannot break out of the inline script.
-- Small accent-colored text uses `--accent-text` (#C83800) for WCAG AA contrast; the editor textarea has an accessible label.
+- Worker HTML cache keys ignore ordinary query strings (routes ignore them too), so arbitrary `?utm=` or cache-busting params cannot fragment the rendered-page cache.
+- FastAPI GET handlers now call renderers directly instead of delegating to the legacy pure-Python `route()` helper and reparsing URLs.
+- Oversized request bodies are capped in the ASGI bridge before the FastAPI app reads them, so the Worker no longer buffers unbounded POST bodies before rejecting them.
+- Deployment smoke refuses to send the Turnstile smoke-bypass secret to non-HTTPS origins.
+- Worker and static responses now include HSTS alongside CSP, frame, referrer, and nosniff headers.
+- Check-script boilerplate is consolidated through `scripts/_common.py`; quality gates share the canonical loader, registry reader, and frontmatter parser.
+- Small accent-colored text and the primary Run button use WCAG-AA contrast colors; the editor textarea has an accessible label.
 - Content corrections across 29 example pages: dict-iteration RuntimeError scoped to key insertion/removal, PEP 695 `type` statement teaching, NotImplemented-returning operator methods, visible positional-only/keyword-only TypeError demos, divergent broad-except demonstration, honest sandbox-boundary framing for subprocesses/threads/networking, cell-specific prose replacing copied intros, and four broken inline links now rendering as real anchors.
 
 ## 2026-05-16

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
 

Makefile

@@ -2,21 +2,24 @@
 # machine regardless of the system python3 (examples use 3.12+ `type` syntax).
 PY := uv run --python 3.13
 
-.PHONY: test embed-examples build check-generated fingerprint prototypes browser-layout-test seo-cache-lint verify-examples check-registry-integrity check-confusable-pairs check-broad-surface-tours check-footgun-coverage check-notes-supported check-program-covers-cells check-prose-duplication check-inline-links score-example-criteria check-quality-scores check-no-figure-rationales check-journey-outcomes audit-example-graph quality-checks rubric-audit format-examples verify-python-version verify smoke-deployment dev deploy lint
+.PHONY: test embed-examples embed-editorial-registry build check-generated fingerprint prototypes browser-layout-test seo-cache-lint verify-examples check-registry-integrity check-confusable-pairs check-broad-surface-tours check-footgun-coverage check-notes-supported check-program-covers-cells check-prose-duplication check-inline-links score-example-criteria check-quality-scores check-no-figure-rationales check-journey-outcomes audit-example-graph quality-checks rubric-audit format-examples verify-python-version verify smoke-deployment dev deploy lint
 
 test:
 	$(PY) python -m unittest discover -s tests -v
 
 embed-examples:
 	$(PY) scripts/embed_example_sources.py
 
-build: embed-examples fingerprint prototypes
+embed-editorial-registry:
+	$(PY) scripts/embed_editorial_registry.py
+
+build: embed-examples embed-editorial-registry fingerprint prototypes
 
 check-generated: build
-	git diff --exit-code src/example_sources_data.py src/asset_manifest.py public/_headers public/prototyping
+	git diff --exit-code src/example_sources_data.py src/editorial_registry_data.py src/asset_manifest.py public/_headers public/prototyping
 	test -z "$$(git status --porcelain public/prototyping public/*.css public/*.js)"
 
-fingerprint: embed-examples
+fingerprint: embed-examples embed-editorial-registry
 	$(PY) scripts/fingerprint_assets.py
 
 prototypes: embed-examples

README.md

@@ -47,8 +47,8 @@ Python documentation links point to the official [Python documentation](https://
 - `src/example_sources/*.md` contains the human-editable examples.
 - `src/example_loader.py` parses Markdown examples into the runtime catalog.
 - `src/examples.py` is a compatibility shim for the loaded catalog.
-- `src/example_sources_data.py` is generated embedded source data for Cloudflare Workers.
-- `src/marginalia.py` curates the figure registry (paint functions, attachments, scores); `src/marginalia_grammar.py` is the locked SVG drawing grammar.
+- `src/example_sources_data.py` and `src/editorial_registry_data.py` are generated embedded data for Cloudflare Workers.
+- `src/marginalia.py` keeps executable figure paint functions; attachments, captions, scores, journeys, and edge labels live in `docs/quality-registries.toml` and load through `src/editorial_registry.py`.
 - `src/textfmt.py` renders inline prose (code spans and internal links) for pages and figure captions.
 - `public/` contains static assets served by Workers Assets.
 - `python_modules/` is generated by the Workers tooling and intentionally ignored by Git.
@@ -101,7 +101,6 @@ Then run the main checks before deploying or pushing:
 
 ```bash
 make verify
-scripts/check_example_migration_parity.py
 scripts/format_examples.py --check
 make verify-python-version VERSION=3.13
 git diff --check
@@ -142,6 +141,7 @@ public/site.<hash>.css
 public/syntax-highlight.<hash>.js
 public/editor.<hash>.js
 src/asset_manifest.py
+src/editorial_registry_data.py
 ```
 
 Rendered HTML uses only fingerprinted asset URLs. `public/_headers` gives these immutable cache headers:
@@ -160,7 +160,6 @@ Run checks, then deploy:
 
 ```bash
 make verify
-scripts/check_example_migration_parity.py
 scripts/format_examples.py --check
 make deploy
 ```
@@ -190,21 +189,20 @@ make build
 make verify-examples
 make quality-checks
 scripts/format_examples.py --check
-scripts/check_example_migration_parity.py
 make check-generated
 ```
 
-If the parity script reports intentional content differences, regenerate the
-structural snapshot with `uv run python scripts/refresh_golden_fixture.py`,
-review the summary it prints, and commit the fixture with your edit.
+The migration-era golden fixture has been removed; intentional content edits are
+reviewed through the Markdown diff, generated-source diff, verifier output, and
+quality gates rather than a refreshed snapshot.
 
 `make quality-checks` runs the content gates: registry integrity, confusable
 pairs, broad-surface tours, footguns, notes grounding, program-covers-cells,
 prose duplication, inline links, criterion scoring with a curated-score delta
 bound, quality scores (waiver expiry, journey average), no-figure rationales,
 journey outcomes, and the see_also graph audit.
 
-`src/example_sources_data.py` is generated and committed so Cloudflare Workers can load examples in production. Do not edit it by hand.
+`src/example_sources_data.py` and `src/editorial_registry_data.py` are generated and committed so Cloudflare Workers can load examples and editorial registries in production. Do not edit them by hand.
 
 For a Python version migration, update `python_version` and `docs_base_url` in `src/example_sources/manifest.toml`, then run: