docs: cumulative-rules narrative (Phase 2b.2)

[raeq]

Summary

Third task of .plans/phase-2b-spec.md — the rules feel arbitrary if you encounter them one at a time without the cumulative narrative; they feel principled if you can see the whole set on one page with the physical justification for each.

Adds docs/the-rules.md — a five-minute single-page index of every user-facing rule the framework enforces. Per entry: the rule itself, the physical-world referent for why, the exception class that fires (link to framework/errors.py), and the demo where users first see the rule caught.

Twelve rules covered:

1. One driver per logical net → ShortCircuitError (first caught: hello_led/)
2. Every BIDIR-only net needs a driver → FloatingNetError (first caught: hello_led/)
3. Mandatory pins must be connected → UnconnectedPinError (first caught: 5v_rail_power/)
4. Signal types stay matched → SignalTypeMismatchError (first caught: li_ion_fuel_gauge/)
5. Ground domains stay isolated → DomainCrossingError (first caught: isolated_rs232/)
6. Connectors mate only with their declared partner → IncompatibleMateError (first caught: fan_cooling/)
7. Pin count + pitch match → PinCountMismatchError / PitchMismatchError (first caught: fan_cooling/)
8. Refdes uniqueness per circuit → RefdesError
9. Forbidden states stay forbidden → ForbiddenStateError (first caught: water_alarm/)
10. wire() doesn't merge pre-existing nets → NodeMergeError
11. Empty wires aren't wires → EmptyWireError
12. A wired chip can't be called standalone → WiredChipCallError

Cross-references

• learning-path.md gains a First catches column on the demo table naming the rule numbers each demo first surfaces. A closing paragraph notes that framework-internal refusals (Rules 8, 10, 11, 12) don't anchor to a single demo.
• Each rule entry in the-rules.md links to the first-caught demo, so the cumulative property is visible: by the time you've worked through hello_led/ + water_alarm/ + 5v_rail_power/ + digital_thermometer/ + fan_cooling/ + isolated_rs232/ + li_ion_fuel_gauge/, you've seen the framework catch eight of the twelve rules in real demos.

Files

• docs/the-rules.md — new, the cumulative-rules narrative.
• docs/learning-path.md — adds First catches column + cross-reference paragraph; also fixes a pre-existing fenced-code-language lint warning along the way.
• mkdocs.yml — adds The rules: the-rules.md to nav between Design principles (the abstract) and Learning path (the graduated exposure).
• tests/docs/test_rules_doc.py — 33 new tests pinning consistency: every curated user-facing rule exception is named in the doc; every XxxError reference resolves to a real class (catches rename typos); every ../demos/<slug>/ link resolves to an actual directory; mkdocs nav orders design-principles → the-rules → learning-path.

Test plan

• uv run pytest — 4795 passed (33 new), 16 skipped
• uv run mypy src/ demos/ — clean
• Markdown lint clean on touched docs (table alignment + fenced-code-language)
• Manual review: cross-links resolve, tone reads as teacher rather than gatekeeper

[Copilot]

Pull request overview

Adds a new “cumulative rules” documentation page and accompanying consistency tests so the user-facing framework rules, their exception classes, and cross-links stay synchronized as the exception hierarchy and demo set evolve.

Changes:

• Add docs/the-rules.md as a single-page index of user-facing enforcement rules (with “why”, exception class, and first-caught demo).
• Update docs/learning-path.md to add a “First catches” column and cross-reference the-rules.md; fix a fenced-code language tag.
• Add tests/docs/test_rules_doc.py plus mkdocs navigation updates to keep docs, exceptions, demo links, and nav ordering consistent.

Reviewed changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/docs/test_rules_doc.py	Adds tests to ensure rule exceptions and doc links are consistent and mkdocs nav includes/ आदेशers the new page.
tests/docs/__init__.py	Establishes tests/docs as a package (empty init).
mkdocs.yml	Inserts “Design principles” and the new “The rules” page into the docs nav in the intended order.
docs/the-rules.md	Introduces the single-page rules index with links to exception classes and demos.
docs/learning-path.md	Adds “First catches” column and cross-references to the new rules page; fixes code-fence language.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[raeq]

Thanks — multiple substantive issues. All fixed in af8808d.

Inaccurate rule→demo mappings. Surveyed every demo README for the exceptions it actually raises and re-mapped each rule to the truly-first demo in learning-path order:

• Rule 3 (UnconnectedPinError) → penfold_light_switch/ (the "floating LDR" near-miss raises UnconnectedPinError because the LDR's terminals are mandatory). Previously 5v_rail_power/, which the doc grep showed raises FloatingNetError (Rule 2), not Rule 3.
• Rule 4 (SignalTypeMismatchError) → penfold_light_switch/ ("mismatched comparator input domain"). Earlier than li_ion_fuel_gauge/.
• Rule 6 (IncompatibleMateError) → water_alarm_split/ ("wrong connector family"). fan_cooling/'s near-miss is PinCountMismatchError (Rule 7), not 6.
• Rule 7 (PinCountMismatchError) stays at fan_cooling/ (correct).

Updated learning-path.md's First catches column to match.

Demo links promised by the spec → README anchors, not folder roots. The spec asked for "link to the demo's what this design is protected from sidebar." Now every First caught at: entry deep-links to the specific README.md#anchor of the near-miss section, computed from the section heading via GitHub's slug algorithm.

Test was permissive — now strict. test_every_demo_cross_link_resolves parses each README's ## … / ### … headings, computes their GitHub anchors, and verifies every #anchor referenced in the rules doc points at a real heading. Catches typos in the slug and silently-renamed headings on the demo side.

Intro overclaim. Softened the cumulative-progress sentence — previously it implied you'd see every rule caught in real demos, but Rules 8, 10, 11, 12 are framework-internal refusals with no demo anchor. Now: "the demo-anchored rules (Rules 1–7, 9)".

Typo. "Mergeing" → "Merging" on Rule 10's Why: line.

Open questions:

• Hard-link to GitHub main vs repository-relative for framework/errors.py? — Kept the GitHub main URLs. Repository-relative paths (../../src/framework/errors.py) don't work on the published mkdocs site (the site root doesn't include src/). A relative ../src/… would resolve in the GitHub-rendered README but not in the published docs. The mkdocs-material repo_url template variable would solve it cleanly but needs the macros plugin. I think pinning main is fine — if it becomes an issue we can revisit with the plugin.

Suite: 4795 passed (same count; 33 docs tests now exercise stronger invariants), mypy clean.