--- name: trim-stages-plan description: "⭐ THE FOUR-STAGE GOVERNANCE TRIM (owner: 'the stages must not be forgotten about', 2026-07-20). Stage 1 landed; stages 2–4 defined here. ⚠ THE GATING RULE IS THE POINT: stage 2 does NOT run until the restructure has been used for real work — staging without observation between stages is just the same amputation in instalments." metadata: node_type: project type: project originSessionId: 1060dea9-0dc3-42b4-958d-2a6f7a6c0c58 modified: 2026-07-20T14:25:54.046Z --- **Origin.** Two blind external reviews (GPT-5.6 Sol adversarial, Gemini 3.1 Pro expansive) on 2026-07-19. GPT argued for deleting or demoting **70–80% of the governance ceremony**. Owner chose STAGED over one amputation; Dispatch's argument, which he accepted: *cut, observe whether it mattered, cut again* — **each step reversible.** Owner, 2026-07-20: *"okay so keep those in mind. maybe fold them in somewhere? the stages must not be forgotten about."* --- ## ⚠ THE GATING RULE — more important than the stages **Stage 2 must NOT run until the path-scoped restructure has been used for real work** — a handful of sessions operating under the new contract-plus-notes model. Without evidence that retrieval actually improved (rather than the problem just moving), **staged trimming collapses into the same big cut delivered slowly**, which is exactly what the staging was meant to avoid. **Dispatch owns flagging when there's enough evidence — do not wait for the owner to ask.** --- ## STAGE 1 — LANDED 2026-07-20 The free stuff: rules that duplicated the harness's own instructions, paragraphs of "why" that no session acted on, and a pending-amendments ledger that was **roadmap state living inside a rule** (relocated to `QUEUE.md`). ⭐ **The sharpest stage-1 lesson: two protocols were CONVERTED into pointers at `library/CODE_MAP.md` because they had gone actively WRONG** — they still named a render file that no longer existed after the render layer was split. *A rule that restates the code map will always drift into a lie; point at the map instead.* **KEPT against the session's own recommendation:** the dispatch-decision protocol — **owner's call**, because it governs dispatch daily. Noted in place so it is not re-litigated. ### ⭐ STAGE-1 CONSEQUENCE — NOT gated on the stage-2 evidence rule A leftover the stage-1 session spotted and deliberately left alone (also in `QUEUE.md`). **It is a consequence of a decision already landed, not a new cut, so it does NOT wait for the "restructure has been used" gate.** Run it in any convenient batch: - The hand-maintained **`// N tests` comments in the diagnostics test file are officially unmaintained**, but still read as fact to a future session. Strip them, or drop the convention. **An unmaintained number that looks authoritative is the exact failure the retirement was meant to end.** ## STAGE 2 — CONVERT PROSE INTO ENFORCEMENT ⭐ highest value Not really a cut. GPT's strongest structural idea: **a rule an agent must remember costs something every session; a guard that fails loudly is free and cannot be skipped.** Every mechanisable rule becomes a check, then its prose shrinks to one line plus a pointer at that check. Candidates from GPT's table: branch discipline → branch-protection settings · the redirect-auth ban → a lint rule · the state-field checklist → a schema round-trip test · render-layering → AST/lint boundary rules once the debt is gone · AI-response handling → runtime schema validation + malformed-response behavioural tests · the deploy protocol → a post-deploy version/SW/offline smoke. ## STAGE 3 — THE CONTENTIOUS ONE (owner must weigh in) Narrowing the **universal ratchets**: today every escaped bug, CSS invariant, harness flaw and testing discovery **permanently enlarges the gate**. GPT wants *"add a test when recurrence would be costly"* instead of always. Also on the table: the per-commit documentation rule, the changelog grammar rule, the universal-requirement framing of the verification protocol, and moving the **UI presentation rules out of the constitution into design docs** — they encode presentation taste, not catastrophic knowledge. ⚠ **This is where cuts start costing something real.** ## STAGE 4 — THE EXPENSIVE MACHINERY (capability calls, not doc cleanup) The Diagnostic Shell's scope · the duplicate Windows CI leg · nightly runs · the browser test page · per-step failure-evidence packaging. **Each needs its own argument.** ⚠ **NOTE: the Diagnostic Shell is on the owner's roadmap as a real in-fiction, user-facing feature. GPT didn't know that; weight its rejection lower.** --- ## KEEP-CASES — never cut (recorded so they aren't re-litigated) - **The architecture-conformance baseline** — the canonical keep-case; its risk stays live until the ES-modules migration makes layering structural. - **The real-device auth rules** — a real production regression is on file. - **UTF-8 integrity** — a real corruption incident is on file, with a commit hash. - **Cloud write safety** — failure is unrecoverable data loss. - **The cache bump** — failure is silent and user-visible. - **The dispatch-decision protocol** — owner overruled the cut list; see Stage 1. - **"Actually render and exercise UI changes"** — **GPT itself withdrew this one**; it addresses a real AI failure mode, *agents reasoning confidently from CSS without looking.* ## ⭐ THE RETIREMENT DISCIPLINE (applies to every stage) Retiring a rule means **removing its enforcement too, not just its prose** — a check policing something no session can read is worse than either. **Retire in place, never renumber, never reuse a number.** And **state what coverage is genuinely lost**: the retired count-tracking protocol cost real drop-detection for a silently-vanishing suite — recorded honestly rather than papered over with a generated number. ⚠ **And the age correction ([[time-and-work-attribution]]):** this project is young. **Almost none of this is entrenched legacy with forgotten reasons** — it was written recently, by us, and the reasoning is still checkable. That makes the stages CHEAPER and FASTER than they'd otherwise be. **Don't treat the rulebook like an old codebase.** Related: [[reframing-review-2026-07-13]], [[workflow-audit-gap-and-fixes]], [[engineering-metrics-log]], [[self-improving-code]].