docs: close yaml-first governance loop

2026-06-14 18:10:10 +00:00
parent 0970a3656d
commit 9dc277ed16
3 changed files with 13 additions and 6 deletions
@@ -123,6 +123,10 @@ YAML-first cleanup work must not become an open-ended sequence of rounds. Once a

 A shared helper extraction stops when the repeated mechanism has a stable helper, the remaining differences are true domain behavior, or the remaining candidates are outside the frozen scope. Do not continue extracting only to make every domain file look identical. The final audit should list completed changes, kept domain differences, parked risks and validation evidence, then close the issue instead of opening a follow-up round by default.

+Closed governance issues are historical records, not standing queues. A later YAML-first pass must start from a fresh code/config inventory and a new bounded issue instead of reopening or appending phases to an already closed issue. For broad cleanup, the phase list should stay small and fixed before implementation; do not exceed five phases unless the user explicitly requests a different bound.
+
+Each frozen phase must deliver a concrete code, configuration or user-facing CLI behavior change. Validation commands, evidence gathering, issue comments, merge/preflight work, progress reporting and docs-only distillation are closeout activities; they may be recorded, but they are not phases. When all frozen phases are complete, close the parent issue and classify remaining discoveries as in-scope leftovers already handled, true domain differences, or out-of-scope parked risks.
+
 ## Anti-Patterns

 Avoid these patterns:
@@ -138,6 +142,7 @@ Avoid these patterns:
 - using contract tests or hidden guards to freeze policy values that should remain YAML-controlled
 - preserving legacy command branches after the latest YAML-first path supersedes them
 - extending a frozen cleanup issue by appending new rounds instead of classifying discoveries as in-scope, domain-specific or parked
+- treating validation, evidence collection, issue lifecycle work, or docs-only closeout as implementation phases

 ## Documentation Boundary