Files

Tom Boucher 38e4ce5f62 fix(#4186 ): anchored status vocabulary, record-session arg guard, recount pin (#4381 )

* 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>

2026-09-06 17:08:24 -04:00

3.3 KiB

Raw Blame History

ADR-2207: STATE.md `Status` lifecycle — phase-completion writes an intermediate state; milestone-close owns termination

Status: Accepted
Date: 2026-07-12
Issue: #2207
Implements: #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

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.
Milestone termination is owned solely by the milestone-close verb. Only milestoneCompleteCore writes <version> milestone complete / Awaiting next milestone.
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.

3.3 KiB Raw Blame History

ADR-2207: STATE.md Status lifecycle — phase-completion writes an intermediate state; milestone-close owns termination