From fdf01ba58800843a991472f45d03c5b0d5f753ab Mon Sep 17 00:00:00 2001 From: Tom Boucher Date: Sat, 11 Jul 2026 22:34:04 -0400 Subject: [PATCH] =?UTF-8?q?docs(#2207):=20ADR-2207=20=E2=80=94=20STATE.md?= =?UTF-8?q?=20Status=20lifecycle=20&=20ownership?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../2207-status-field-lifecycle-ownership.md | 33 +++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 docs/adr/2207-status-field-lifecycle-ownership.md diff --git a/docs/adr/2207-status-field-lifecycle-ownership.md b/docs/adr/2207-status-field-lifecycle-ownership.md new file mode 100644 index 000000000..b936815d8 --- /dev/null +++ b/docs/adr/2207-status-field-lifecycle-ownership.md @@ -0,0 +1,33 @@ +# ADR-2207: STATE.md `Status` lifecycle — phase-completion writes an intermediate state; milestone-close owns termination + +- **Status:** Accepted +- **Date:** 2026-07-12 +- **Issue:** [#2207](https://github.com/open-gsd/gsd-core/issues/2207) +- **Implements:** [#2204](https://github.com/open-gsd/gsd-core/issues/2204) (Bug 7b, split from the #2191 batch) + +## Context + +STATE.md's `Status` field is written by two transitions with an **overloaded** value: + +- `completePhaseCore` (phase-completion) writes a bare `Status: Milestone complete` on the last phase, keyed on `isLastPhase`. +- `milestoneCompleteCore` (milestone-close) writes the terminal `Status: milestone complete` and resets `## Current Position` to `Awaiting next milestone`. + +"Milestone complete" therefore spans **two distinct states** — an intermediate "all phases done, awaiting formal close" and the terminal archived state — and a **phase-level verb owns a milestone-level field**. Because `isLastPhase` is derived from the ROADMAP parse, a mis-parse (the bullet-form / membership bugs, #2199 / #2200) can flip the milestone status on the wrong phase. + +## Decision + +1. **Phase-completion writes an intermediate state, not the terminal one.** `completePhaseCore` writes the **existing** `All phases complete` value (already used in `gsd2-import.cts`) on the last phase — not `Milestone complete`. +2. **Milestone termination is owned solely by the milestone-close verb.** Only `milestoneCompleteCore` writes ` milestone complete` / `Awaiting next milestone`. +3. **The coupling is retained, not removed.** "Is this the last phase" stays on the phase-completion path; its correctness is carried by the existing `#2028` checkbox guard, the parse fixes (#2199 / #2200), and the `verify.cts` ship gate that already errors when STATE claims milestone-complete while phases are unstarted. + +**Rejected alternative — decouple** (phase verbs never write milestone `Status`): rejected because `#2028` shows the last-phase signal is deliberately wanted on the phase-completion path; removing it would regress that. + +## The `Status` lifecycle (ubiquitous language) + +`Ready to plan` → `All phases complete` (all phases done, milestone awaiting formal close) → ` milestone complete` → `Awaiting next milestone` (terminal / archived). + +## Consequences + +**Positive:** the overload is removed; the intermediate and terminal "complete" states are distinct; a phase-level verb no longer writes the terminal milestone state; the wrong-phase flip becomes a parse-correctness concern already owned upstream. + +**Cost / follow-through (implemented in #2204):** consumers that key on the `Milestone complete` string must recognize `All phases complete` — `workflows/progress.md` (Route D), `verify.cts`, and `workstream-inventory-builder.cts`. `normalizeStateStatus` already maps any status containing "complete" → `completed`, so it needs no change. A `CONTEXT.md` glossary entry enumerating the `Status` lifecycle lands with the #2204 implementation.