docs(#1769): ADR-1769 STATE.md Transition Module — Phase 0 (#1770)

Introduce ADR-1769 establishing the STATE.md Transition Module design:
intent-based transitions over scattered RMW callbacks. Seven design
decisions resolved via /improve-codebase-architecture + /grilling +
/domain-modeling:

  1. Module shape: Transition Module owns the full transaction
  2. Method set: 10 transitions (lifecycle + maintenance + milestoneComplete)
  3. I/O shape: pure core (content, intent, deps) -> newContent
  4. Policy model: field-classification table
  5. External writers: 2 migrate (milestone, phase), 1 stays (verify)
  6. Core scope: writes only; body sections as constants
  7. Migration: substrate first, transition-by-transition

Updates CONTEXT.md with the new Module entry; updates docs/adr/README.md
index. No behavior change. Implementation lands in Phases 1-7 per the
ADR's migration sequence.

Closes #1769

Co-authored-by: review-bot <review-bot@gsd>
This commit is contained in:
Tom Boucher
2026-06-27 09:46:07 -04:00
committed by GitHub
parent 4ced0a64cc
commit 4732c704f7
3 changed files with 221 additions and 0 deletions

View File

@@ -52,6 +52,9 @@ Module owning projection from dispatch results/errors to CLI `{ exitCode, stdout
### STATE.md Document Module
Module owning STATE.md parse, field extraction, field replacement, status normalization, and frontmatter reconstruction. It does not scan `.planning/phases` and does not own persistence or locking; phase/plan/summary counts arrive from inventory/progress Modules as inputs, and read-modify-write paths remain Adapters. Source of truth: `gsd-core/bin/lib/state-document.cjs`.
### STATE.md Transition Module [Planned]
Module owning STATE.md lifecycle/maintenance transitions as intent-based methods (`beginPhase`, `advancePlan`, `completePhase`, `plannedPhase`, `milestoneSwitch`, `milestoneComplete`, `patch`, `sync`, `prune`, `update`). Pure core `(content, intent, deps) → newContent` with injected I/O (file read/write, lock, disk scan); consults a field-classification table that names each STATE.md field's class (`derived-from-body` | `derived-from-disk` | `derived-from-external` | `curated` | `free`) and its preservation policy. Supersedes the 14 scattered RMW callbacks in `state.cts` and the direct `writeStateMd` callers in `milestone.cts:352` and `phase.cts:1770`; verify's `regenerateState` factory-reset primitive stays as a direct `writeStateMd` call. Absorbs `syncStateFrontmatter` + `readModifyWriteStateMd`'s post-sync preservation block; Encoding 3 (`cmdStateBuildFrontmatter`) stays separate — read path concern. Sibling/super-module of the STATE.md Document Module; consumes its `stateReplaceField`/`stateExtractField` primitives. Body section structure (`## Current Position`, `## Session`, etc.) lives as a constants block inside the Module. Append-only transitions (`addDecision`, `addBlocker`, etc.) stay on today's RMW seam for now. Targets the #1760/#1761/#1743/#1695/#1264/#1255/#1257/#3242 bug cluster. Migration per ADR-1372 §T6 sequenced as substrate + `beginPhase` first (PR1), then transition-by-transition with characterization tests first per transition. Source of truth: `gsd-core/bin/lib/state-transition.cjs` (planned, generated from `src/state-transition.cts`).
### Query Execution Policy Module
Module owning query transport routing policy projection (`preferNative`, fallback policy, workstream subprocess forcing) at execution seam.