diff --git a/docs/tickets/ticket-000044-autocount-doc-drift-discipline.md b/docs/tickets/ticket-000044-autocount-doc-drift-discipline.md index 6f6881b..fc90ef0 100644 --- a/docs/tickets/ticket-000044-autocount-doc-drift-discipline.md +++ b/docs/tickets/ticket-000044-autocount-doc-drift-discipline.md @@ -280,7 +280,86 @@ As of 2026-05-10 landing of `3b30126`: --- -## 10. References +## 10. Sibling discipline — §-status section drift + +AUTOCOUNT catches numeric drift. A parallel drift class showed +up in the same 2026-05-10 audit wave: prose §-status sections +inside ticket bodies (typically §7 Status or §11 Status) freeze +at landing time while file headers update inline as new phases +land. The §-section becomes a point-in-time snapshot that +diverges from the load-bearing surface fox actually refreshes. + +The 2026-05-10 audit caught this in 5 of 6 in-progress tickets: + +| Ticket | §-section | Drift caught | +|----------|----------------------|-------------------------------| +| #000034 | §7 lead | "Open · awaiting" / body said "Phase 1a landed" | +| #000035 | §7 lead | clean (no drift) | +| #000036 | §7 lead + closure(c) | "Awaits fox review" / file: "in flight with dav1d" | +| #000037 | §20 + §17.1 | "open · awaiting go/no-go" / file: Phase 0+1+2 landed | +| #000025 | §11 lead | "Open · awaiting" / file: 1a + 1b.2 + 1c + 1d + 1e landed | +| #000012 | §7 lead + Phase 1a tests | Phase 1a only / file: 1a + 1b landed; test file renamed | + +The discipline has **two different rules** depending on ticket +state: + +### 10.1 In-progress tickets + +Body §-status sections must match the file header. Refresh in +place when the file header changes. The header is the +load-bearing surface (it's what TICKETS.md index rows mirror); +body sections that lag are pure drift. + +Walk pattern when amending an in-progress ticket: + +1. Update file header status line. +2. Walk §-status body section. If it disagrees with the header, + refresh in the same commit. +3. Walk TICKETS.md index row. If it's a condensed version of + the header, refresh that too. + +### 10.2 Closed tickets + +Body §-status sections are **archival**. They record the state +at landing time and stay frozen. Do NOT rewrite a closed +ticket's §-status section when later phases land — even if the +ticket is still being amended with B-1 / B-2 follow-ups under +the same ticket number. + +Subsequent phases on a closed ticket go in: + +- The file header (consolidated across all phases) +- A NEW section appended below (e.g. "§8.b Subsequent phases" + or "Phase B follow-ups"), not by rewriting §8 + +Rewriting §8 of #000031 with Phase 2 content would erase the +Phase 1 landing record. That record is the design log; future +readers tracing how the textbook substrate evolved need to see +what landed at Phase 1 vs what was added later. + +### 10.3 The rule in one line + +**In-progress §-status must match header. Closed §-status is +archival and stays frozen.** + +This rule is NOT machine-checked. No regression test enforces +it; the audit pattern is manual + periodic. Worth a sweep when: + +- Any ticket flips from in-progress to closed (final §-section + refresh before freezing) +- Any in-progress ticket gains a new phase landing (refresh § + to match) +- Quarterly housekeeping pass on all in-progress tickets + +Long-term, this could become a tagged claim (e.g. an AUTOCOUNT +metric like `ticket-header-status-matches-section` that +asserts §-status text matches header text up to whitespace +normalization). Deferred until the audit pattern recurs enough +to justify the surface. + +--- + +## 11. References - `tests/test_doc_counts.py` — the harness module (docstring is the canonical format reference).