feat(#3227): publish machine-readable state contract at step boundaries (#3824)

* feat(#3227): publish machine-readable state contract at step boundaries Adds src/state-contract.cts, a best-effort publisher that writes .planning/state.json (contract 1.0.0) at 11 step-boundary commands, so external tools read a versioned contract instead of parsing STATE.md and ROADMAP.md heuristically. Composes existing owners rather than re-deriving: phase rows come from a new locateProgressTable extracted from deriveProgressFromRoadmap (so the snapshot can never disagree with GSD's own progress counters), milestone identity from getMilestoneInfo, and next from classifyProject. Owners are required lazily to avoid the state -> state-contract -> smart-entry -> state require cycle. Also fixes a pre-existing defect in scripts/lint-test-file-count.cjs (maintainer-approved as a second concern): testEffectivePrefix never stripped the suite qualifier, so 65 dotted test files counted against no module and 9 mis-bucketed into a shorter one. Allowlist re-baselined for the 74 files the gate can now see. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * chore(#3227): backfill PR number into the changeset fragment pr:0 -> pr:3824 now that the PR exists. Doc-only. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * test(#3227): shape hostile-name fixtures away from the scan corpus The two hostile-input fixtures used a literal phrase from scripts/prompt-injection-scan.sh's corpus, so CI's Security Scan redded on this file. These tests assert that an arbitrary phase name round-trips into state.json as inert data -- the property holds for any string, so the injection flavor is illustrative, not load-bearing. Reshaped to a hyphenated fake instruction tag, which stays hostile-looking while matching none of the scanner's patterns. Allowlisting the file was rejected: that mechanism is for suites whose subject IS injection defense, and it would blind the scanner to this whole file permanently. See DEFECT.PROMPT-INJECTION-SCAN-COLLISION. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * chore(#3227): ratchet the state-contract mutation floor to its measured score The module was registered at minScore 50, the ratchet's minimum permitted floor for a newly-registered module whose score had not been measured. This PR's own Stryker shard measured 66.25% (run 32769289750, job 97565813640), so the floor moves to floor(measured) - 1 = 65, per the rule the registry documents. 66.25 is below TARGET_MUTATION_SCORE (80), so this stays a ratchet candidate: raise as the tests improve, never lower. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> --------- Co-authored-by: sim <sim@local> Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-08-24 17:56:02 -04:00
parent fb9823e1e1
commit 596540f864
23 changed files with 2739 additions and 25 deletions
--- a/src/artifacts.cts
+++ b/src/artifacts.cts
@@ -27,6 +27,7 @@ export const CANONICAL_EXACT: ReadonlySet<string> = new Set([
  'WINDOWS.md', // #3224: broken-windows ledger (src/broken-windows.cts, LEDGER_FILE_NAME)
  'STATE-ARCHIVE.md', // state.cts's cmdStatePrune writes this at the .planning/ root
  'milestone.lock', // #3311: milestone (phase + session) claim (src/milestone-lock.cts); persistent, unlike the transient STATE.md.lock/WAITING.json
+  'state.json', // #3227: machine-readable state contract published at step boundaries (src/state-contract.cts)
 ]);

 // Pattern-match canonical file names (regex tests on the basename)
--- a/src/milestone.cts
+++ b/src/milestone.cts
@@ -29,6 +29,9 @@ const { resolveQuickTaskSummaryFile } = auditMod;
 import ioMod = require('./io.cjs');
 const { output, error } = ioMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
+import stateContract = require('./state-contract.cjs');
+const { publishStateContract } = stateContract;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
 import phaseIdMod = require('./phase-id.cjs');
 const { normalizePhaseName, matchPhaseDirs, PHASE_NUMBER_TOKEN_SOURCE, isSentinelPhaseId, isSentinelPhaseDir } = phaseIdMod;
 import { escapeRegex } from './pattern.cjs';
@@ -1154,6 +1157,19 @@ function cmdMilestoneComplete(cwd: string, version: string, options: MilestoneCo
  };

  output(result, raw);
+  // #3227 (design doc §40 row 26 / "Not-corruption" rule): a refreshed
+  // state.json `updated_at` must always mean something on disk actually
+  // moved. This site is unconditional because every reachable path either
+  // exits via `error()` (process.exit — refusals like a truncated milestone
+  // window, an unstarted phase, or an invalid version never reach here) or
+  // returns early on `--dry-run` (before any mutation, see the `dry_run:
+  // true` branch above) — the only way execution reaches this line is after
+  // the unconditional MILESTONES.md `platformWriteSync` a few lines above,
+  // which always runs (new file, empty file, or append) once the run is
+  // committed to mutating. Best-effort — cannot throw, cannot change this
+  // command's exit code or output. publishStateContract resolves the
+  // workstream planning root itself via planningPaths.
+  publishStateContract(cwd);
 }

 function cmdPhasesClear(cwd: string, raw: boolean, args: string[]): void {
--- a/src/phase-lifecycle.cts
+++ b/src/phase-lifecycle.cts
@@ -21,6 +21,7 @@
 */

 import { findTableWithColumns } from './markdown-table.cjs';
+import type { MarkdownTable } from './markdown-table.cjs';
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-id.cjs is an export= CommonJS module
 import phaseIdMod = require('./phase-id.cjs');
 const { isSentinelPhaseId } = phaseIdMod;
@@ -33,8 +34,10 @@ export interface RoadmapProgress {
 }

 /**
- * Derive completed_phases, total_phases, and total_plans from ROADMAP content.
- * Root cause fix for issue #4 — see gen-phase-lifecycle.mjs for full documentation.
+ * #3227: the single owner of "where is this ROADMAP's Progress table".
+ * Lifted verbatim out of deriveProgressFromRoadmap so `state-contract.cts`
+ * enumerates phases from THE SAME table this module derives its counts from.
+ * A second copy of this locator is the DEFECT.GENERATIVE-FIX shape.
 *
 * ADR-2143 §3 ("addressed by NAME, never ordinal"): the Progress table is
 * located via the markdown-table seam's `findTableWithColumns`, which is
@@ -53,6 +56,25 @@ export interface RoadmapProgress {
 * to scanning the whole input, preserving the "Progress table not under a
 * `## Progress` heading, or not the first table in the document, still
 * resolves" behaviour.
+ */
+export function locateProgressTable(roadmapContent: string): MarkdownTable | null {
+  const progressMatch = roadmapContent.match(/^##[ \t]+Progress\b/im);
+  let scoped = roadmapContent;
+  if (progressMatch && progressMatch.index !== undefined) {
+    const afterHeading = roadmapContent.slice(progressMatch.index);
+    const nextHeading = afterHeading.search(/\n#{1,2}[ \t]/);
+    scoped = nextHeading >= 0 ? afterHeading.slice(0, nextHeading) : afterHeading;
+  }
+  return findTableWithColumns(scoped, ['Phase', 'Plans Complete', 'Status', 'Completed']);
+}
+
+/**
+ * Derive completed_phases, total_phases, and total_plans from ROADMAP content.
+ * Root cause fix for issue #4 — see gen-phase-lifecycle.mjs for full documentation.
+ *
+ * The Progress table itself is located by `locateProgressTable` (ADR-2143 §3,
+ * lifted out as #3227's single-owner extraction) — this function consumes
+ * that table.
 *
 * Cells are read by column NAME (`r['Status']`, `r['Plans Complete']`,
 * `r['Phase']`), fixing #2137 (the old position-based regex assumed "Status"
@@ -72,20 +94,7 @@ export function deriveProgressFromRoadmap(roadmapContent: string): RoadmapProgre
  // `{ ok: false, reason }`, not an exception — so the catch was masking
  // nothing but dead code paths. Removed per ADR-2143 §5; the public
  // `RoadmapProgress` contract (nulls = absent) is unchanged.
-  //
-  // ADR-2143 §3: read the Progress table by column NAME (order/injection-invariant),
-  // via the markdown-table seam. Scope to the `## Progress` section when present
-  // (#2012 decoy avoidance); a headingless milestone slice (#1445) falls back to the
-  // whole input. Requires the canonical Phase/Plans Complete/Status/Completed columns
-  // in any order (extra columns ignored) — supersedes findTableBySchema's exact-schema lookup.
-  const progressMatch = roadmapContent.match(/^##[ \t]+Progress\b/im);
-  let scoped = roadmapContent;
-  if (progressMatch && progressMatch.index !== undefined) {
-    const afterHeading = roadmapContent.slice(progressMatch.index);
-    const nextHeading = afterHeading.search(/\n#{1,2}[ \t]/);
-    scoped = nextHeading >= 0 ? afterHeading.slice(0, nextHeading) : afterHeading;
-  }
-  const table = findTableWithColumns(scoped, ['Phase', 'Plans Complete', 'Status', 'Completed']);
+  const table = locateProgressTable(roadmapContent);

  if (table) {
    const allRows = table.rows;
--- a/src/phase.cts
+++ b/src/phase.cts
@@ -21,6 +21,9 @@ import path from 'node:path';
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- io.cjs is an export= CommonJS module
 import ioMod = require('./io.cjs');
 const { output, error, ERROR_REASON } = ioMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+import stateContract = require('./state-contract.cjs');
+const { publishStateContract } = stateContract;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- config-loader.cjs is an export= CommonJS module
 import configLoaderMod = require('./config-loader.cjs');
 const { loadConfig } = configLoaderMod;
@@ -1151,6 +1154,18 @@ function cmdPhaseAdd(cwd: string, description: string, raw: boolean, customId?:
  if (titleWarning) result['warning'] = titleWarning;

  output(result, raw, result['padded']);
+  // #3227 (design doc §40 row 26 / "Not-corruption" rule): every
+  // `publishStateContract` call site in this file is audited so a refreshed
+  // state.json `updated_at` always means something on disk actually moved —
+  // a stale-but-refreshed timestamp is worse than no refresh, because it
+  // reads as fresh to a downstream watcher. This site is unconditional
+  // because every reachable path either exits via `error()` (process.exit,
+  // never reaches here) or falls through to the unconditional
+  // `platformEnsureDir`/`platformWriteSync` pair above that always creates
+  // the phase directory and rewrites ROADMAP.md — there is no code path that
+  // reaches this line without having just written to disk. Best-effort —
+  // cannot throw, cannot change this command's exit code or output.
+  publishStateContract(cwd);
 }

 function cmdPhaseAddBatch(cwd: string, descriptions: string[], raw: boolean): void {
@@ -1238,6 +1253,11 @@ function cmdPhaseAddBatch(cwd: string, descriptions: string[], raw: boolean): vo
    return added;
  });
  output({ phases: results, count: results.length }, raw);
+  // #3227: unconditional here because `platformWriteSync(roadmapPath, rawContent)`
+  // above always rewrites ROADMAP.md for every description in the batch before
+  // this line is reached; the only refusal path is the `error('ROADMAP.md not
+  // found')` above, which terminates the process and never reaches here.
+  publishStateContract(cwd);
 }

 function cmdPhaseInsert(cwd: string, afterPhase: string, description: string, raw: boolean): void {
@@ -1431,6 +1451,11 @@ function cmdPhaseInsert(cwd: string, afterPhase: string, description: string, ra
  };

  output(result, raw, decimalPhase);
+  // #3227: unconditional here because `platformWriteSync(roadmapPath, updatedContent)`
+  // above always rewrites ROADMAP.md with the inserted phase before this line is
+  // reached; every refusal along the way (bad args, missing ROADMAP.md, unresolved
+  // target bullet/header) exits via `error()`, which terminates the process.
+  publishStateContract(cwd);
 }

 interface RenameDirInfo {
@@ -2110,6 +2135,12 @@ function cmdPhaseRemove(
    },
    raw,
  );
+  // #3227: unconditional here because `updateRoadmapAfterPhaseRemoval` above
+  // always rewrites ROADMAP.md before this line is reached; every refusal path
+  // (bad target, missing ROADMAP.md, --force-required, renumber failure) exits
+  // via `error()`, and the ambiguous-match case exits via an earlier `return`
+  // before any file is touched.
+  publishStateContract(cwd);
 }

 interface WriteSpec {
@@ -2118,7 +2149,14 @@ interface WriteSpec {
  after: string;
 }

-function writePlanningFileSet(writes: WriteSpec[]): void {
+/**
+ * #3227: returns the count of writes actually applied (entries whose
+ * `before` differed from `after` and were therefore written to disk) — the
+ * caller (`cmdPhaseComplete`) uses this as its publish-gate signal, since a
+ * re-run against an already-completed phase can produce a `writes[]` array
+ * where every entry is byte-identical to what's already on disk.
+ */
+function writePlanningFileSet(writes: WriteSpec[]): number {
  const applied: WriteSpec[] = [];
  try {
    for (const write of writes) {
@@ -2145,6 +2183,7 @@ function writePlanningFileSet(writes: WriteSpec[]): void {
    }
    throw err;
  }
+  return applied.length;
 }

 function phaseDisplayNameFromRoadmap(roadmapContent: string | null, phaseNum: string | null): string | null {
@@ -2415,6 +2454,15 @@ function cmdPhaseComplete(cwd: string, phaseNum: string, raw: boolean): void {
  // verification_stale_check_indeterminate).
  let milestoneConflict: milestoneLockMod.MilestoneConflict | null = null;

+  // #3227: set inside `runPhaseCompleteTransaction` below from
+  // `writePlanningFileSet`'s applied-count return — the transaction always
+  // RUNS (verification passed, the lock was taken, `writes[]` was built),
+  // but a re-run against a phase whose ROADMAP/STATE bytes already reflect
+  // completion produces a `writes[]` where every entry is byte-identical to
+  // disk, so `writePlanningFileSet` applies none of them. That must not
+  // still refresh state.json's `updated_at` (design doc §40 row 26).
+  let anyPlanningWrite = false;
+
  const verificationBlocked = withPlanningLock(cwd, () => {
    // #3311: completing a phase while a live milestone claim (phase + session)
    // holds a DIFFERENT phase means two sessions are working two phases against
@@ -3207,7 +3255,7 @@ function cmdPhaseComplete(cwd: string, phaseNum: string, raw: boolean): void {
        writes.push({ filePath: statePath, before: originalStateContent, after: stateContent });
      }

-      writePlanningFileSet(writes);
+      anyPlanningWrite = writePlanningFileSet(writes) > 0;
    };

    if (fs.existsSync(statePath)) {
@@ -3283,6 +3331,11 @@ function cmdPhaseComplete(cwd: string, phaseNum: string, raw: boolean): void {
  };

  output(result, raw);
+  // #3227: gate on `anyPlanningWrite` (whether `writePlanningFileSet`
+  // actually wrote anything), not on reaching this line — reaching here only
+  // means verification passed and the transaction ran, not that ROADMAP.md
+  // or STATE.md bytes changed (see the `anyPlanningWrite` declaration above).
+  if (anyPlanningWrite) publishStateContract(cwd);
 }

 function cmdPhaseUatPassed(
--- a/src/state-contract.cts
+++ b/src/state-contract.cts
@@ -0,0 +1,407 @@
+/**
+ * State Contract Module — `.planning/state.json` schema v1 (#3227).
+ *
+ * A **best-effort publisher** invoked at 11 step-boundary commands
+ * (`state.*`, `phase.*`, `milestone.complete`). It composes existing
+ * canonical owners; it introduces no second answer to any question GSD
+ * already answers:
+ *   - `planning-workspace.cjs`'s `planningPaths` for every `.planning/` path
+ *     (workstream-aware — never re-derived here).
+ *   - `phase-lifecycle.cjs`'s `locateProgressTable` (this issue's Edit 1) for
+ *     "where is the Progress table" — the SAME table
+ *     `deriveProgressFromRoadmap` counts from, so `phases[]` and
+ *     `deriveProgressFromRoadmap`'s `totalPhases` can never disagree about
+ *     which rows are data rows.
+ *   - `phase-id.cjs`'s `isSentinelPhaseId` / `parsePhaseFromProse` for
+ *     sentinel exclusion and STATE.md phase-token parsing.
+ *   - `roadmap-parser.cjs`'s `getMilestoneInfo` for milestone identity.
+ *   - `markdown-sectionizer.cjs`'s `collectSection` for the `## Phases`
+ *     checkbox fallback.
+ *   - `state-document.cjs`'s `stateFieldValue` + `frontmatter.cjs`'s
+ *     `extractFrontmatter`/`stripFrontmatter` for STATE.md's `current_phase`.
+ *   - `shell-command-projection.cjs`'s `platformReadSync`/`platformWriteSync`
+ *     — the CLAUDE.md-designated single OS-facing I/O seam. `platformWriteSync`
+ *     is ALREADY atomic (sibling tmp + `retryRenameSync`, Windows transient-
+ *     lock retry, EXDEV fallback) — this module adds no sixth atomic-write
+ *     helper (the repo already carries five).
+ *   - `smart-entry.cjs`'s `classifyProject` for `next` — this is what makes
+ *     "`next` equals smart-entry's recommended action" true BY CONSTRUCTION
+ *     rather than by a second copy of the routing table.
+ *
+ * WHY NOT `PlanningSnapshot` / `buildPlanningInspect`. `PlanningSnapshot` is
+ * an explicitly-additive INTERNAL diagnostic shape (ADR-3180 §8.1) still
+ * growing across phases; freezing it as an external contract is the exact
+ * Hyrum's-Law break `planning.inspect` (`src/planning-inspect.cts`) already
+ * refused for the same reason (#2790). `state.json` declares its OWN flat,
+ * minimal, six-key schema instead — see PUBLIC SURFACE below.
+ *
+ * NOT built (Gall's Law / Zawinski's Law — see `.gsd/phase/feat-3227-state-
+ * contract/40-design.md`): a `--watch` mode, a reader API inside gsd-core, a
+ * diff/event stream, a config toggle, milestone-scoping of `phases[]`. This
+ * module answers "where is this project right now" and nothing else — a
+ * request for document *contents* belongs to `planning.inspect`.
+ *
+ * REQUIRE-CYCLE HAZARD (the single most important implementation
+ * constraint). `src/state.cts` imports THIS module, and `src/smart-entry.cts`
+ * imports `state.cjs` and destructures `readStateHeadFreshness` off it at
+ * MODULE LOAD time. A top-level `import smartEntry = require('./smart-entry.cjs')`
+ * here would therefore close the cycle
+ * `state.cjs -> state-contract.cjs -> smart-entry.cjs -> state.cjs`, binding
+ * `readStateHeadFreshness` to `undefined` inside `smart-entry.cjs` and
+ * throwing at its first call. Every owner below is required LAZILY, inside
+ * the function body, via a small cached loader — never at module top level —
+ * which also keeps this module's (and its owners') load cost off every
+ * command that imports `state.cjs` but never reaches a publish boundary.
+ * Someone will be tempted to "tidy" the lazy requires into top-level ones;
+ * doing so reopens the cycle.
+ *
+ * `withPlanningLock` is deliberately NOT taken around the write (Rejected §3
+ * of the design doc): it is not re-entrant, several phase commands already
+ * hold it when they would call this publisher, and `platformWriteSync`'s
+ * tmp+rename already makes each publish all-or-nothing without it.
+ *
+ * ADR-457 build-at-publish: source in src/state-contract.cts, compiled to
+ * gsd-core/bin/lib/state-contract.cjs (gitignored).
+ */
+
+import path from 'node:path';
+import fs from 'node:fs';
+
+// ─── Public wire vocabulary ────────────────────────────────────────────────
+
+export const STATE_CONTRACT_VERSION = '1.0.0';
+export const STATE_CONTRACT_FLAVOR = 'core';
+
+/** Key order of the emitted contract object — an observable, pinned by test. */
+export const CONTRACT_KEY_ORDER = Object.freeze(['contract', 'flavor', 'milestone', 'phases', 'next', 'updated_at']);
+
+/** Key order of each emitted phase object — an observable, pinned by test. */
+export const PHASE_KEY_ORDER = Object.freeze(['number', 'name', 'status']);
+
+/** Frozen three-value phase status vocabulary. Conservative in what we send (Postel's Law). */
+export const PHASE_STATUS = Object.freeze({
+  COMPLETE: 'complete',
+  IN_PROGRESS: 'in_progress',
+  PENDING: 'pending',
+});
+
+/** Frozen `publishStateContract` result reasons. */
+export const PUBLISH_REASON = Object.freeze({
+  PUBLISHED: 'published',
+  NO_PLANNING_DIR: 'no_planning_dir',
+  WRITE_FAILED: 'write_failed',
+});
+
+export interface StateContractDeps {
+  now?: () => number;
+  classify?: (cwd: string) => unknown;
+}
+
+interface StateContractPhase {
+  number: string;
+  name: string | null;
+  status: string;
+}
+
+interface StateContractNext {
+  command: string;
+  label: string;
+  reason: string;
+}
+
+export interface StateContractV1 {
+  contract: string;
+  flavor: string;
+  milestone: string | null;
+  phases: StateContractPhase[];
+  next: StateContractNext | null;
+  updated_at: string;
+}
+
+// ─── Lazy owner loader (breaks the state.cjs <-> smart-entry.cjs cycle) ────
+
+interface Owners {
+  planningPaths: typeof import('./planning-workspace.cjs')['planningPaths'];
+  platformReadSync: typeof import('./shell-command-projection.cjs')['platformReadSync'];
+  platformWriteSync: typeof import('./shell-command-projection.cjs')['platformWriteSync'];
+  locateProgressTable: typeof import('./phase-lifecycle.cjs')['locateProgressTable'];
+  isSentinelPhaseId: typeof import('./phase-id.cjs')['isSentinelPhaseId'];
+  parsePhaseFromProse: typeof import('./phase-id.cjs')['parsePhaseFromProse'];
+  getMilestoneInfo: typeof import('./roadmap-parser.cjs')['getMilestoneInfo'];
+  collectSection: typeof import('./markdown-sectionizer.cjs')['collectSection'];
+  stateFieldValue: typeof import('./state-document.cjs')['stateFieldValue'];
+  extractFrontmatter: typeof import('./frontmatter.cjs')['extractFrontmatter'];
+  stripFrontmatter: typeof import('./frontmatter.cjs')['stripFrontmatter'];
+  classifyProject: typeof import('./smart-entry.cjs')['classifyProject'];
+}
+
+let _owners: Owners | null = null;
+
+/**
+ * Lazily require every owner this module composes. MUST stay lazy — see the
+ * "REQUIRE-CYCLE HAZARD" module-doc comment above. Cached after first call so
+ * repeat invocations within one process (multiple publishes in one command,
+ * or across the several boundary commands in a test run) pay the require
+ * cost once.
+ */
+function owners(): Owners {
+  if (_owners) return _owners;
+  /* eslint-disable @typescript-eslint/no-require-imports */
+  const planningWorkspaceMod = require('./planning-workspace.cjs') as typeof import('./planning-workspace.cjs');
+  const shellCommandProjectionMod = require('./shell-command-projection.cjs') as typeof import('./shell-command-projection.cjs');
+  const phaseLifecycleMod = require('./phase-lifecycle.cjs') as typeof import('./phase-lifecycle.cjs');
+  const phaseIdMod = require('./phase-id.cjs') as typeof import('./phase-id.cjs');
+  const roadmapParserMod = require('./roadmap-parser.cjs') as typeof import('./roadmap-parser.cjs');
+  const markdownSectionizerMod = require('./markdown-sectionizer.cjs') as typeof import('./markdown-sectionizer.cjs');
+  const stateDocumentMod = require('./state-document.cjs') as typeof import('./state-document.cjs');
+  const frontmatterMod = require('./frontmatter.cjs') as typeof import('./frontmatter.cjs');
+  const smartEntryMod = require('./smart-entry.cjs') as typeof import('./smart-entry.cjs');
+  /* eslint-enable @typescript-eslint/no-require-imports */
+  _owners = {
+    planningPaths: planningWorkspaceMod.planningPaths,
+    platformReadSync: shellCommandProjectionMod.platformReadSync,
+    platformWriteSync: shellCommandProjectionMod.platformWriteSync,
+    locateProgressTable: phaseLifecycleMod.locateProgressTable,
+    isSentinelPhaseId: phaseIdMod.isSentinelPhaseId,
+    parsePhaseFromProse: phaseIdMod.parsePhaseFromProse,
+    getMilestoneInfo: roadmapParserMod.getMilestoneInfo,
+    collectSection: markdownSectionizerMod.collectSection,
+    stateFieldValue: stateDocumentMod.stateFieldValue,
+    extractFrontmatter: frontmatterMod.extractFrontmatter,
+    stripFrontmatter: frontmatterMod.stripFrontmatter,
+    classifyProject: smartEntryMod.classifyProject,
+  };
+  return _owners;
+}
+
+// ─── milestone ──────────────────────────────────────────────────────────────
+
+function buildMilestone(cwd: string): string | null {
+  try {
+    const { value } = owners().getMilestoneInfo(cwd);
+    if (!value) return null;
+    // U+2014 EM DASH, spaced on both sides. Never fabricate a name — version
+    // alone when no name-bearing evidence resolved (design row 21).
+    return value.name && value.name.length > 0 ? `${value.version} — ${value.name}` : value.version;
+  } catch {
+    return null;
+  }
+}
+
+// ─── phases: Progress-table (primary) enumerator ───────────────────────────
+
+const PHASE_CELL_RE = /^(\d+(?:\.\d+)*)\s*[.:)–—-]?\s*(.*)$/;
+
+function statusFromProgressCell(raw: string | undefined): string {
+  const normalized = (raw ?? '').trim().toLowerCase().replace(/\s+/g, ' ');
+  if (normalized === 'complete') return PHASE_STATUS.COMPLETE;
+  if (normalized === 'in progress') return PHASE_STATUS.IN_PROGRESS;
+  // Everything else — 'not started', 'deferred' (design row 12, lossy by
+  // design), '', and any unrecognized word — folds to pending. An
+  // unrecognized status must never reach the wire as a 4th value.
+  return PHASE_STATUS.PENDING;
+}
+
+function phasesFromProgressTable(
+  table: { columns: string[]; rows: Record<string, string>[] },
+): StateContractPhase[] {
+  const { isSentinelPhaseId } = owners();
+  const phases: StateContractPhase[] = [];
+  for (const row of table.rows) {
+    const cell = (row['Phase'] ?? '').trim();
+    if (!/^\d/.test(cell)) continue; // stray note row, no leading digit
+    if (isSentinelPhaseId(cell)) continue; // phase 0 / 999.x sentinels
+    const m = PHASE_CELL_RE.exec(cell);
+    const number = m ? m[1] : cell;
+    const name = m && m[2].trim().length > 0 ? m[2].trim() : null;
+    phases.push({ number, name, status: statusFromProgressCell(row['Status']) });
+  }
+  return phases;
+}
+
+// ─── phases: `## Phases` checkbox fallback ─────────────────────────────────
+
+// `- [x] **Phase 1: Foundation**` / `- [ ] **Phase 2.1: Hardening**`.
+const PHASE_BULLET_RE = /^[ \t]*[-*][ \t]+\[([ xX])\][ \t]+\*\*Phase[ \t]+(\d+(?:\.\d+)*)[ \t]*:?[ \t]*([^*\n]*)\*\*/gm;
+
+/**
+ * STATE.md's current phase, via the same frontmatter-then-body chain
+ * `cmdStateCompletePhase` uses (`stateFieldValue` owns the #1760 fallback
+ * ladder). Any failure anywhere in the chain yields `null` — treat current
+ * phase as unknown so every unchecked bullet is PENDING rather than
+ * IN_PROGRESS by a guess.
+ */
+function currentPhaseFromState(statePath: string): string | null {
+  const { platformReadSync, extractFrontmatter, stripFrontmatter, stateFieldValue, parsePhaseFromProse } = owners();
+  try {
+    const raw = platformReadSync(statePath);
+    if (raw === null) return null;
+    const fm = extractFrontmatter(raw, statePath);
+    const body = stripFrontmatter(raw);
+    const { value } = stateFieldValue(fm, body, 'current_phase', 'Current Phase');
+    if (!value) return null;
+    return parsePhaseFromProse(value).phase;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Fallback enumerator when the ROADMAP carries no Progress table.
+ *
+ * Scoping to `## Phases` is load-bearing negative space (design "Not-
+ * corruption" section): it is what keeps `- [x] 01-01: a plan` (a PLAN
+ * bullet under `## Phase Details`) and `- ✅ **v1.0 MVP** - Phases 1-4`
+ * (a MILESTONE bullet under `## Milestones`) from being read as phases. The
+ * `**Phase N` anchor inside `PHASE_BULLET_RE` is the second layer of that
+ * defence — a plan bullet's text never starts with `**Phase`.
+ */
+function phasesFromChecklist(roadmapContent: string, cwd: string, statePath: string): StateContractPhase[] {
+  const { collectSection, isSentinelPhaseId } = owners();
+  const section = collectSection(roadmapContent, (h) => /^phases$/i.test(h.text.trim()));
+  if (!section) return [];
+
+  const currentPhase = currentPhaseFromState(statePath);
+  const phases: StateContractPhase[] = [];
+  let match: RegExpExecArray | null;
+  const pattern = new RegExp(PHASE_BULLET_RE.source, PHASE_BULLET_RE.flags);
+  while ((match = pattern.exec(section.body)) !== null) {
+    const checked = match[1] === 'x' || match[1] === 'X';
+    const number = match[2];
+    if (isSentinelPhaseId(number)) continue;
+    const name = match[3].replace(/\r$/, '').trim();
+    const status = checked
+      ? PHASE_STATUS.COMPLETE
+      : (currentPhase !== null && number === currentPhase ? PHASE_STATUS.IN_PROGRESS : PHASE_STATUS.PENDING);
+    phases.push({ number, name: name.length > 0 ? name : null, status });
+  }
+  return phases;
+}
+
+function buildPhases(cwd: string, paths: { roadmap: string; state: string }): StateContractPhase[] {
+  const { platformReadSync, locateProgressTable } = owners();
+  try {
+    let content = platformReadSync(paths.roadmap);
+    if (content === null) return [];
+    if (content.charCodeAt(0) === 0xfeff) content = content.slice(1); // strip leading BOM
+
+    const table = locateProgressTable(content);
+    if (table) return phasesFromProgressTable(table);
+    return phasesFromChecklist(content, cwd, paths.state);
+  } catch {
+    return [];
+  }
+}
+
+// ─── next ───────────────────────────────────────────────────────────────────
+
+function buildNext(cwd: string, deps?: StateContractDeps): StateContractNext | null {
+  try {
+    const classify = (deps?.classify as Owners['classifyProject'] | undefined) ?? owners().classifyProject;
+    const result = classify(cwd);
+    const action = result.actions.find((a) => a.id === result.recommended);
+    if (!action) return null;
+    return { command: action.command, label: action.label, reason: result.summary };
+  } catch {
+    return null;
+  }
+}
+
+// ─── Entry points ───────────────────────────────────────────────────────────
+
+/**
+ * Build the state-contract snapshot. PURE — writes nothing. Every stage is
+ * independently try/caught (milestone, phases, next) so one bad document
+ * cannot lose the others; `updated_at` and the frozen `contract`/`flavor`
+ * keys always resolve.
+ */
+export function buildStateContract(cwd: string, deps?: StateContractDeps): StateContractV1 {
+  const nowFn = deps?.now ?? Date.now;
+  const updated_at = new Date(nowFn()).toISOString();
+
+  // #2245 shape: `planningPaths` -> `planningDir` throws a plain Error for an
+  // invalid GSD_WORKSTREAM/GSD_PROJECT segment. This call must not be hoisted
+  // outside a try, or that throw escapes uncaught and breaks the invariant
+  // this function is documented as upholding (see `getMilestoneInfo`'s
+  // equivalent guard comment in src/roadmap-parser.cts for the same shape).
+  let paths: { roadmap: string; state: string } | null;
+  try {
+    paths = owners().planningPaths(cwd);
+  } catch {
+    paths = null;
+  }
+
+  if (!paths) {
+    return {
+      contract: STATE_CONTRACT_VERSION,
+      flavor: STATE_CONTRACT_FLAVOR,
+      milestone: null,
+      phases: [],
+      next: null,
+      updated_at,
+    };
+  }
+
+  const milestone = buildMilestone(cwd);
+  const phases = buildPhases(cwd, paths);
+  const next = buildNext(cwd, deps);
+
+  return {
+    contract: STATE_CONTRACT_VERSION,
+    flavor: STATE_CONTRACT_FLAVOR,
+    milestone,
+    phases,
+    next,
+    updated_at,
+  };
+}
+
+/**
+ * Publish the state-contract snapshot to `<planning>/state.json`. NEVER
+ * throws — for any input, ever (acceptance criterion 3: the parent boundary
+ * command's exit code and stdout must be unchanged whatever happens here).
+ *
+ * No `.planning/` directory at all: writes nothing, creates nothing. This
+ * guard is essential — `platformWriteSync` does `mkdirSync(dirname,
+ * {recursive:true})`, so without it the publisher would conjure a
+ * `.planning/` tree inside a non-GSD directory.
+ *
+ * `withPlanningLock` is deliberately NOT taken here — see the module-doc
+ * "REQUIRE-CYCLE HAZARD" section's sibling note: it is not re-entrant and
+ * several phase commands already hold it when they call this publisher, so
+ * acquiring it here would throw in exactly the situation this function must
+ * never perturb. `platformWriteSync`'s sibling-tmp + rename already makes
+ * each publish all-or-nothing without it.
+ */
+export function publishStateContract(cwd: string, deps?: StateContractDeps): { published: boolean; reason: string } {
+  try {
+    const { planningPaths, platformWriteSync } = owners();
+    // Resolve the planning root BEFORE anything else. A resolution failure
+    // (invalid GSD_WORKSTREAM/GSD_PROJECT segment — the #2245 shape) means no
+    // write was ever attempted, so it must map to `no_planning_dir`, not
+    // `write_failed` — that reason is reserved for an attempted-and-failed
+    // write, and reporting it here would send a caller looking at disk
+    // permissions for a problem that isn't there.
+    let paths: { planning: string };
+    try {
+      paths = planningPaths(cwd);
+    } catch {
+      return { published: false, reason: PUBLISH_REASON.NO_PLANNING_DIR };
+    }
+    if (!fs.existsSync(paths.planning)) {
+      return { published: false, reason: PUBLISH_REASON.NO_PLANNING_DIR };
+    }
+
+    const snapshot = buildStateContract(cwd, deps);
+    const statePath = path.join(paths.planning, 'state.json');
+    try {
+      platformWriteSync(statePath, JSON.stringify(snapshot, null, 2) + '\n');
+    } catch {
+      return { published: false, reason: PUBLISH_REASON.WRITE_FAILED };
+    }
+
+    return { published: true, reason: PUBLISH_REASON.PUBLISHED };
+  } catch {
+    return { published: false, reason: PUBLISH_REASON.WRITE_FAILED };
+  }
+}
--- a/src/state.cts
+++ b/src/state.cts
@@ -13,6 +13,9 @@ import { escapeRegex } from './pattern.cjs';
 import ioMod = require('./io.cjs');
 const { output, error } = ioMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
+import stateContract = require('./state-contract.cjs');
+const { publishStateContract } = stateContract;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
 import configLoaderMod = require('./config-loader.cjs');
 const { loadConfig } = configLoaderMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -677,7 +680,7 @@ function cmdStateAdvancePlan(cwd: string, raw: boolean): void {
  // STATE.md lock, so the position read and the claim read cannot interleave
  // with another session's Current Position write.
  let milestoneConflict: milestoneLockMod.MilestoneConflict | null = null;
-  readModifyWriteStateMd(statePath, (content) => {
+  const wrote = readModifyWriteStateMd(statePath, (content) => {
    // advance-plan has no phase argument of its own — the phase it advances is
    // whatever ## Current Position names. Compare that against the milestone
    // claim: a mismatch means another session moved the single-slot position
@@ -717,6 +720,17 @@ function cmdStateAdvancePlan(cwd: string, raw: boolean): void {
  } else {
    output({ ...resultData, updated, milestone_conflict: milestoneConflict }, raw, 'true');
  }
+  // #3227 (design doc §40 row 26 / "Not-corruption" rule): a refreshed
+  // state.json `updated_at` must always mean something on disk actually
+  // moved, in EITHER branch above — so gate on `wrote`
+  // (readModifyWriteStateMd's own return value) rather than assuming both
+  // branches are unconditional mutations. They are not: re-running
+  // advance-plan on a phase already parked in its post-advance state (e.g.
+  // two same-day calls once a phase is "ready for verification") reproduces
+  // byte-identical content, the #948 no-op guard skips the write, and
+  // `resultData`/`updated` still populate normally from the transform's OWN
+  // (unwritten) output — so those are not safe publish signals here either.
+  if (wrote) publishStateContract(cwd);
 }

 function cmdStateRecordMetric(cwd: string, options: StateRecordMetricOptions, raw: boolean): void {
@@ -3762,7 +3776,7 @@ function cmdStateBeginPhase(cwd: string, phaseNumber: string | number, phaseName
  // phase. The check runs INSIDE the STATE.md lock so concurrent begin-phase
  // calls cannot both read "no claim" and both write.
  let milestoneConflict: milestoneLockMod.MilestoneConflict | null = null;
-  readModifyWriteStateMd(statePath, (content) => {
+  const wrote = readModifyWriteStateMd(statePath, (content) => {
    milestoneConflict = milestoneLockMod.claimMilestonePhase(cwd, String(phaseNumber));
    if (milestoneConflict) {
      milestoneLockMod.warnMilestoneConflict(milestoneConflict, `state.begin-phase ${phaseNumber}`);
@@ -3791,6 +3805,26 @@ function cmdStateBeginPhase(cwd: string, phaseNumber: string | number, phaseName
    raw,
    updated.length > 0 ? 'true' : 'false',
  );
+  // #3227 (design doc §40 row 26 / "Not-corruption" rule): gate on `wrote`
+  // (readModifyWriteStateMd's own return value — its #948 no-op guard skips
+  // the write outright when the transform produced no diff), not on
+  // `updated.length > 0`. Confirmed reproducer: an unrecognized-format
+  // STATE.md makes `beginPhaseCore` match zero body fields AND leave
+  // `existingFm` untouched, so the raw transform output is byte-identical to
+  // the input, the RMW guard fires, and `wrote` is false — matching
+  // `updated: []` here. Unlike `cmdStatePlannedPhase` (which must NOT use
+  // this same `wrote` signal — see its comment for why `plannedPhaseCore`
+  // mutates frontmatter in place even on this exact no-op shape),
+  // `beginPhaseCore` never mutates `existingFm`, so `wrote` and
+  // `updated.length > 0` agree on every case audited for this phase; `wrote`
+  // is kept as the gate here (and on `cmdStateAdvancePlan`/
+  // `cmdStateCompletePhase` below, where it is REQUIRED — `updated`/
+  // `reconciled` can be non-empty there even when nothing was written,
+  // confirmed by direct re-invocation) for one consistent rule across every
+  // RMW-backed command in this file: publish iff `readModifyWriteStateMd`
+  // itself reports a write. Best-effort — cannot throw, cannot change this
+  // command's exit code or output.
+  if (wrote) publishStateContract(cwd);
 }

 /**
@@ -4079,6 +4113,29 @@ function cmdStatePlannedPhase(cwd: string, phaseNumber: string | number, phaseNa
    ? { updated, phase: phaseNumber, plan_count: planCount, warning: 'STATE.md Current Position has no recognized labels — transition was a no-op. Verify STATE.md uses the canonical labeled format (Status:, Total Plans in Phase:, etc.).' }
    : { updated, phase: phaseNumber, plan_count: planCount };
  output(result, raw, updated.length > 0 ? 'true' : 'false');
+  // #3227 (design doc §40 row 26 / "Not-corruption" rule): gate on
+  // `updated.length > 0`, NOT on `readModifyWriteStateMd`'s own write-happened
+  // return value. The two are NOT equivalent here: readModifyWriteStateMd's
+  // #948 no-op guard compares the transform's RAW returned string against the
+  // RAW original file content, but `syncStateFrontmatter`'s progress-block
+  // sync and this command's `authoritativeFm: {current_phase_name}` override
+  // both run INSIDE the transform (via `frontmatterMod.reconstructFrontmatter`
+  // over `existingFm`), so an unrecognized-format STATE.md — zero fields the
+  // transition could actually apply, `updated: []`, the "transition was a
+  // no-op" warning above — can still make the raw returned string differ
+  // from the input (frontmatter gets synthesized: `gsd_state_version`,
+  // `last_updated`, a zeroed `progress` block, `current_phase_name`), so the
+  // RMW guard does NOT fire and a real write happens. That write is not a
+  // meaningful state transition by this command's OWN reporting contract
+  // (`updated: []`) — publishing on it would refresh state.json's
+  // `updated_at` for a call this command itself reports did nothing.
+  // `updated.length > 0` is the field-classification-table-backed signal
+  // that actually answers "did plannedPhaseCore itself change anything this
+  // caller asked it to change" — empirically verified: an unrecognized-format
+  // STATE.md reproduces `updated: []` with a genuine (frontmatter-only) disk
+  // write underneath it, and gating on `updated.length > 0` is what makes
+  // this reproducer NOT publish.
+  if (updated.length > 0) publishStateContract(cwd);
 }

 /**
@@ -4104,6 +4161,7 @@ function cmdStateMilestoneSwitch(cwd: string, version: string | undefined, name:
  const intent: StateTransitionIntent = { kind: 'milestoneSwitch', version, name: resolvedName };
  const deps: StateTransitionDeps = { clock: realClock, sourcePath: statePath };

+  let switched = false;
  const lockPath = acquireStateLock(statePath);
  try {
    const content = platformReadSync(statePath) || '';
@@ -4114,9 +4172,15 @@ function cmdStateMilestoneSwitch(cwd: string, version: string | undefined, name:
      raw,
      'true',
    );
+    switched = true;
  } finally {
    releaseStateLock(lockPath);
  }
+  // #3227: publish AFTER releaseStateLock — publishStateContract derives `next`
+  // from classifyProject, which shells out to git (bounded, but up to 3 x 10s).
+  // Holding the STATE.md lock across that would turn a millisecond hold into a
+  // git-bound one for every concurrent GSD process.
+  if (switched) publishStateContract(cwd);
 }

 /**
@@ -4969,7 +5033,7 @@ function cmdStateCompletePhase(cwd: string, raw: boolean, overridePhase?: string
  let preSyncContent = '';
  const divergedFields: string[] = [];

-  readModifyWriteStateMd(statePath, (content) => {
+  const wrote = readModifyWriteStateMd(statePath, (content) => {
    const currentPhase = resolvedPhase;

    // Bug #1255: operate on body only so the YAML frontmatter `status:` key
@@ -5078,6 +5142,14 @@ function cmdStateCompletePhase(cwd: string, raw: boolean, overridePhase?: string
    raw,
    reconciled.length > 0 ? 'true' : 'false',
  );
+  // #3227: gate on `wrote` (readModifyWriteStateMd's own return value), not
+  // `reconciled.length > 0` — a re-run of complete-phase against a phase
+  // that is ALREADY marked complete (same status/date/Current Position
+  // values already on disk) still has `stateReplaceField` report a match for
+  // every field it looks up, so `reconciled` is non-empty even though the
+  // #948 no-op guard skipped the write. Same reasoning as
+  // cmdStateBeginPhase/cmdStatePlannedPhase/cmdStateAdvancePlan above.
+  if (wrote) publishStateContract(cwd);
 }

 export = {