refactor(#1784): ADR-1769 Phase 3 — completePhase migration onto Transition Module (#1785)

Migrate the STATE.md write path inside cmdPhaseComplete (phase.cts) onto the
STATE.md Transition Module substrate (ADR-1769, epic #1769).

- Add {kind: 'completePhase'} to StateTransitionIntent + completePhaseCore in
  src/state-transition.cts. Pure body field mutations (Current Phase shape/name,
  Status, Current Plan, Last Activity + Description, Completed/Total Phases +
  Progress percent), consulting the field-classification table for touched keys.
  Roadmap progress injected via a new optional deps.roadmapProvider.
- Collapse the ~90-line inline STATE.md transform in cmdPhaseComplete to a
  transitionCore dispatch. The adapter retains updatePerformanceMetricsSection
  (section table) + syncStateFrontmatter (disk-scan post-sync) and the
  multi-file atomic transaction (STATE is committed with ROADMAP/REQUIREMENTS,
  so readModifyWriteStateMd is not used here).
- deriveProgressFromRoadmap/clampPercent/stateReplaceFieldWithFallback move from
  the phase.cts call site into the pure core (no circular dep: phase-lifecycle
  and state-document don't import state.cts).
- Characterization tests in tests/state-transition.test.cjs pin the field
  updates, roadmap progress derivation, #1255 frontmatter parity, and the
  'Phase:' fallback. All 44 transition + 193 phase tests pass.

No user-visible behavior change. cmdPhaseComplete CLI output and 'phase complete'
behavior unchanged.

Closes #1784
This commit is contained in:
Tom Boucher
2026-06-27 14:56:51 -04:00
committed by GitHub
parent 1512e6f415
commit 6f80524be1
5 changed files with 635 additions and 90 deletions

View File

@@ -208,9 +208,9 @@ alongside, leave callbacks — parallel worlds don't converge (ADR-857's failure
| Phase | Scope | Closes issue | Bug coverage |
|---|---|---|---|
| 0 | ADR + CONTEXT.md update | #1769 | — |
| 1 | Substrate + `beginPhase` | TBD | #1255, #1257, #3242 |
| 2 | `advancePlan` | TBD | — |
| 3 | `completePhase` + `phase.cts:1770` | TBD | — |
| 1 | Substrate + `beginPhase` | #1771 | #1255, #1257, #3242 |
| 2 | `advancePlan` | #1782 | — |
| 3 | `completePhase` + `phase.cts:1770` | #1784 | — |
| 4 | `plannedPhase` + `milestoneSwitch` | TBD | — |
| 5 | `milestoneComplete` + `milestone.cts:352` | TBD | — |
| 6 | `patch` | TBD | #1743, #1695 |