Fix stale verification claims and drop phrase-order doc tests

docs/lessons-learned.md said "54 tests today cover 9 contract
families"; tests/test_marginalia_geometry.py has 31 tests in 13
contract classes. The sentence now points at the classes instead of
quoting a number that drifts. It also said the golden fixture is
"refreshed explicitly by scripts/refresh_golden_fixture.py"; the script
and fixture were deleted in 0929c25, so it now names what catches
loader and parser regressions today.

tests/test_markdown_migration_prereqs.py checked that the finished
migration's spec contained particular phrases, including "Red",
"Green" and "Refactor" in that order, which proves nothing about the
process. Those tests are dropped; the README and CI command contract
stays.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012eisRQmQvg4TphwztxhQGJ

Author: claude

docs/lessons-learned.md

@@ -40,7 +40,7 @@ This document records project lessons that should guide future changes to Python
 - Keep the complete editable program visible because it is the thing that actually runs.
 - When storing examples as Markdown, keep the full editable program in `:::program` and teaching fragments in separate `:::cell` blocks. Do not concatenate cells to recreate the editor source.
 - Fine-grained cells can restate definitions to stay executable. This is better than collapsing class, property, recursion, match, or type-hint examples into one large cell.
-- Preserve a frozen golden catalog while migrating source formats. Full stdout parity is not enough; rendered teaching-cell structure must also match. (After the migration, the fixture's job changed: it is now a reviewed structural snapshot, refreshed explicitly by `scripts/refresh_golden_fixture.py`, that catches loader/parser regressions rather than guarding a migration.)
+- Preserve a frozen golden catalog while migrating source formats. Full stdout parity is not enough; rendered teaching-cell structure must also match. (After the migration the frozen fixture and its refresh script were retired in 0929c25, 2026-06-13; loader and parser regressions are now caught by the frontmatter property tests in `tests/test_parser_properties.py` and the byte-exact output check in `scripts/verify_examples.py`.)
 - Beware broad-surface titles that quietly teach only one narrow slice. Pages named `Testing`, `Packages`, `Regular Expressions`, `Type Hints`, `Async Await`, or `Special Methods` must either cover the forms a reader reasonably expects or explicitly frame themselves as a first pass and link to focused neighbors.
 - Do not let an important syntax form live only in a separate page if another page title strongly implies it. An umbrella `Operators` page should at least point to and lightly show `:=`, even though `Assignment Expressions` remains the focused lesson.
 - Journey order should follow prerequisite thinking, not catalog order. Put booleans before truthiness and conditionals, scope before closures, bytes before networking, and environment boundaries before subprocess/thread boundaries.
@@ -109,7 +109,7 @@ git diff --check
 - **Score what's shipping, not what was designed.** A scoring dict on the gestalt is design-time review. Production figures live in `src/marginalia.py` `FIGURES` and may have been redesigned during promotion. Scoring should track the production version with the gestalt as separate history.
 - **Semantic diagram review has four objects: page, cell, paint function, caption.** Geometry contracts can prove that a figure renders, but not that it still teaches the adjacent cell. On every diagram pass, read the current example cell, the attached paint function, the caption, and the score rationale together. The same audit caught `container-protocols` still showing `iter()/next()` after the page had shifted to `__setitem__`/`__contains__`/`__getitem__`, `structured-data-shapes` over-focusing on `TypedDict` while anchored to a dataclass cell, and `object-lifecycle` mentioning `__del__` after the lesson had been reframed around references.
 - **Some examples should never have figures.** Constraint-shaped, infrastructure-shaped, and aggregator-shaped slugs lack a single mechanism to depict. Force-fitting figures on them scores below the gate. Leave them figure-less and document why rather than ship weak figures.
-- **Audits without contracts rot; bug classes need automated gates.** When you find a bug class — clipping, collision, off-palette colour, drifting twin coordinates, duplicate caption — write a unit test that asserts the invariant across every figure. The geometry contracts in `tests/test_marginalia_geometry.py` started as ad-hoc scripts and were promoted to CI gates after the same bug class recurred. 54 tests today cover 9 contract families; new figures pass them automatically because each test iterates `FIGURES`.
+- **Audits without contracts rot; bug classes need automated gates.** When you find a bug class — clipping, collision, off-palette colour, drifting twin coordinates, duplicate caption — write a unit test that asserts the invariant across every figure. The geometry contracts in `tests/test_marginalia_geometry.py` started as ad-hoc scripts and were promoted to CI gates after the same bug class recurred. Each contract family is a test class there; new figures pass them automatically because each test iterates `FIGURES`. (Count the classes rather than quoting a number here: an earlier "54 tests, 9 families" claim drifted from the file.)
 - **Clipping ≠ collision; padding the viewBox fixes one but not the other.** The `value-types` bug had two components: the first `INT` tag was clipped above the viewBox (geometry escapes its frame), and the `STR`/`LIST`/`DICT` tags overlapped the boxes above them (geometry collides internally). Padding the viewBox solved (1) and disguised (2). Element-element collision needs its own audit that walks every text-rect, text-text, and (for label-on-edge cases) text-line bounding-box pair.
 - **Heuristic audits over-flag; trust the design, not the regex.** Probes for "prose duplication" (SVG text matching caption substring), "text crossing a line" (label bbox bisected by a hairline), and "text overlapping a circle" each surfaced ~3-10 hits — all false positives. Diagrammatic labels naturally appear in captions (`__getattr__`, `yield from inner`); dashed strikes through `.append` are deliberate; text inside node circles is the design. Don't promote heuristic findings to contracts without confirming each is a real bug.
 - **Structural twins must share coordinates exactly.** When two figures depict parallel concepts — `kw-only-separator` and `positional-only-separator`, `class-triangle` and `metaclass-triangle` — they read as a pair. A single-pixel drift in one breaks the visual rhyme. Treat a coordinate change in one as a forced change in both, in the same commit. The audit caught `kw-only-separator` at the old `x=82` after `positional-only-separator` had moved to the corrected `x=75`.

tests/test_markdown_migration_prereqs.py

@@ -2,85 +2,19 @@
 from pathlib import Path
 
 ROOT = Path(__file__).resolve().parents[1]
-SPEC = ROOT / "docs" / "example-source-format-spec.md"
 README = ROOT / "README.md"
 CI = ROOT / ".github" / "workflows" / "verify.yml"
 
 
 class MarkdownMigrationPrereqTests(unittest.TestCase):
-    def test_spec_covers_all_fourteen_migration_prerequisites(self):
-        spec = SPEC.read_text()
-        required_phrases = [
-            "Cloudflare bundling behavior",
-            "Historical golden parity script",
-            "Cell model",
-            "Generated full code",
-            "Verifier correctness",
-            "Line-number reporting",
-            "Formatter behavior",
-            "Build step",
-            "Cache busting",
-            "Worker runtime startup",
-            "POST execution",
-            "Browser layout",
-            "Production smoke test",
-            "Python version migration command",
-        ]
-        for phrase in required_phrases:
-            with self.subTest(phrase=phrase):
-                self.assertIn(phrase, spec)
+    # The Markdown migration shipped (see docs/example-source-format-spec.md).
+    # Tests that only checked the spec's wording, including the order of the
+    # words "Red", "Green" and "Refactor", were removed: they proved nothing
+    # about the process. What remains is the contributor-facing contract.
 
-    def test_spec_defines_red_green_refactor_order(self):
-        spec = SPEC.read_text()
-        self.assertIn("Red", spec)
-        self.assertIn("Green", spec)
-        self.assertIn("Refactor", spec)
-        self.assertLess(spec.index("Red"), spec.index("Green"))
-        self.assertLess(spec.index("Green"), spec.index("Refactor"))
-
-    def test_spec_blocks_deploy_without_full_teaching_parity(self):
-        spec = SPEC.read_text()
-        self.assertIn("100% golden parity", spec)
-        self.assertIn("100% parity", spec)
-        self.assertIn("Do not deploy Markdown-backed examples unless Phase 3 has 100% parity", spec)
-        self.assertIn("No allowlist is permitted for the app switch", spec)
-        self.assertIn("teaching-structure difference", spec)
-
-    def test_spec_names_examples_that_lost_fine_grained_cells(self):
-        spec = SPEC.read_text()
-        for slug in [
-            "match-statements",
-            "recursion",
-            "classes",
-            "properties",
-            "special-methods",
-            "type-hints",
-        ]:
-            with self.subTest(slug=slug):
-                self.assertIn(slug, spec)
-
-    def test_spec_captures_successful_migration_and_rollback_rehearsal(self):
-        spec = SPEC.read_text()
-        self.assertIn("Lessons from the successful parity migration", spec)
-        self.assertIn("100% golden parity", spec)
-        self.assertIn("rollback-rehearsed", spec)
-        self.assertIn("revert the migration, deploy the rollback", spec)
-        self.assertIn("re-apply the migration and repeat verification", spec)
-
-    def test_remaining_operational_lessons_are_documented_and_verified(self):
-        spec = SPEC.read_text()
+    def test_readme_and_ci_keep_the_markdown_workflow_commands(self):
         readme = README.read_text()
         workflow = CI.read_text()
-        for phrase in [
-            "Golden fixture cleanup policy",
-            "CI policy",
-            "Contributor documentation policy",
-            "Native Markdown bundling remains unproven",
-            "reserialize it deterministically",
-            "TOML editorial registries",
-        ]:
-            with self.subTest(phrase=phrase):
-                self.assertIn(phrase, spec)
         for phrase in ["src/example_sources/", ":::program", ":::cell", "make build", "make verify-examples"]:
             with self.subTest(readme=phrase):
                 self.assertIn(phrase, readme)