38e4ce5f62
* fix(#4186): anchored status vocabulary, record-session arg guard, recount pin Three defects from #4186: 1. normalizeStateStatus ran a first-match-wins SUBSTRING chain over the free-prose body Status field, so prose merely mentioning a status word was silently rewritten to a credible wrong token (a .planning/ path in Italian prose -> status: planning; verifica -> verifying; completezza -> completed). Recognition is now an ANCHORED whole-field match against a declared vocabulary (STATUS_EXACT_TOKENS + STATUS_ANCHORED_PATTERNS, state-document.cts) — case/whitespace-tolerant, branch-order artifacts preserved (Planning complete -> planning; Phase complete — ready for verification -> verifying). The recorded lenient fallback (#3873 row 26) stands: unrecognized prose passes through verbatim. Read-side consumers (W011, statusline) ride the same function. 2. The progress recount skew (stray *-SUMMARY.md inflating completed_plans) is already dead on next via #1988/PR #2016 (countMatchedSummaries pairs summaries to plans) — verified live and pinned with regression rows composed against the #4129/#4359 ratchet. 3. state record-session with no args executed and wrote STATE.md; it now errors like state update (stopped-at or resume-file required), handler- side so SDK callers are covered too. Four tests pinning the bare-call write are updated to the new contract. * fix(#4186): update status pins to the anchored vocabulary contract Bench round 1 follow-ups: - Legacy bare 'Milestone complete' kept as reader-side vocabulary (ADR-2207 removed the writers, not recognition of legacy files). - state.test pins updated: 'Paused at Plan 3' and round-trip 'Executing Plan 5' were pins of the substring guessing itself — the round-trip now uses the real handler form 'Executing Phase 5'. - record-session no-op/no-fields tests repurposed to the usage-error contract (CLI + SDK-level ExitError), byte-unchanged assertions kept. - statusline tests repinned: vocabulary values collapse to keywords; narratives render the documented first-word fallback instead of a guessed token. Hook doc comment updated to match. - docs-guard exempt baseline: state.test.cjs now cites docs/CLI-TOOLS.md. - docs/CLI-TOOLS.md: record-session signature notes the required flag. * fix(#4186): repair a dangling sentence in the schema docstring * test(#4186): bound the completed_plans scan regex (#2128 class) * chore(#4186): backfill changeset PR number --------- Co-authored-by: sim <sim@local>
34 lines
3.3 KiB
Markdown
34 lines
3.3 KiB
Markdown
# 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: <version> 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 `<version> 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) → `<version> 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. *(Superseded mechanism, #4186: recognition is now an ANCHORED whole-field vocabulary match — `All phases complete` and `<version> milestone complete` still map to `completed`; prose merely containing "complete" passes through verbatim. The consumer-recognition consequence above is unchanged.)* A `CONTEXT.md` glossary entry enumerating the `Status` lifecycle lands with the #2204 implementation.
|