@opengsd/gsd-core 1.11.0 → 1.13.0

package/gsd-core/bin/lib/state-command-router.cjs

@@ -53,8 +53,19 @@ function routeStateCommand({ state, args, cwd, raw, error }) {
         handlers: {
             load: () => state.cmdStateLoad(cwd, raw),
             json: () => state.cmdStateJson(cwd, raw),
-            get: () => state.cmdStateGet(cwd, args[2], raw),
-            update: () => state.cmdStateUpdate(cwd, args[2], args[3]),
+            // ADR-3473 §8.4 / #3358 gap: these two read args[2]/args[3] positionally
+            // without ever calling parseNamedArgsOrExit, so an unrecognized flag or
+            // stray positional was silently dropped instead of rejected. No flags
+            // are declared — none are documented for these subcommands
+            // (docs/CLI-TOOLS.md:86,89) and no shipped workflow passes any.
+            get: () => {
+                (0, command_arg_projection_cjs_1.parseNamedArgsOrExit)(args, { positionals: 3 }, error);
+                state.cmdStateGet(cwd, args[2], raw);
+            },
+            update: () => {
+                (0, command_arg_projection_cjs_1.parseNamedArgsOrExit)(args, { positionals: 4 }, error);
+                state.cmdStateUpdate(cwd, args[2], args[3]);
+            },
             patch: () => {
                 const patches = {};
                 if (args.length === 3 && typeof args[2] === 'string' && args[2].trim().startsWith('{')) {
@@ -90,7 +101,7 @@ function routeStateCommand({ state, args, cwd, raw, error }) {
             },
             'advance-plan': () => state.cmdStateAdvancePlan(cwd, raw),
             'record-metric': () => {
-                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['phase', 'plan', 'duration', 'tasks', 'files']);
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgsOrExit)(args, { valueFlags: ['phase', 'plan', 'duration', 'tasks', 'files'], positionals: 2 }, error);
                 state.cmdStateRecordMetric(cwd, {
                     phase: strArg(a, 'phase'),
                     plan: strArg(a, 'plan'),
@@ -101,7 +112,7 @@ function routeStateCommand({ state, args, cwd, raw, error }) {
             },
             'update-progress': () => state.cmdStateUpdateProgress(cwd, raw),
             'add-decision': () => {
-                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['phase', 'summary', 'summary-file', 'rationale', 'rationale-file']);
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgsOrExit)(args, { valueFlags: ['phase', 'summary', 'summary-file', 'rationale', 'rationale-file'], positionals: 2 }, error);
                 state.cmdStateAddDecision(cwd, {
                     phase: strArg(a, 'phase'),
                     summary: strArg(a, 'summary'),
@@ -111,11 +122,11 @@ function routeStateCommand({ state, args, cwd, raw, error }) {
                 }, raw);
             },
             'add-blocker': () => {
-                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['text', 'text-file']);
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgsOrExit)(args, { valueFlags: ['text', 'text-file'], positionals: 2 }, error);
                 state.cmdStateAddBlocker(cwd, { text: strArg(a, 'text'), text_file: strArg(a, 'text-file') }, raw);
             },
             'add-roadmap-evolution': () => {
-                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['phase', 'action', 'after', 'note', 'note-file'], ['urgent']);
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgsOrExit)(args, { valueFlags: ['phase', 'action', 'after', 'note', 'note-file'], booleanFlags: ['urgent'], positionals: 2 }, error);
                 state.cmdStateAddRoadmapEvolution(cwd, {
                     phase: strArg(a, 'phase'),
                     action: strArg(a, 'action'),
@@ -125,51 +136,69 @@ function routeStateCommand({ state, args, cwd, raw, error }) {
                     urgent: a['urgent'] === true,
                 }, raw);
             },
-            'resolve-blocker': () => state.cmdStateResolveBlocker(cwd, strArg((0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['text']), 'text'), raw),
+            'resolve-blocker': () => state.cmdStateResolveBlocker(cwd, strArg((0, command_arg_projection_cjs_1.parseNamedArgsOrExit)(args, { valueFlags: ['text'], positionals: 2 }, error), 'text'), raw),
             'record-session': () => {
-                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['stopped-at', 'resume-file']);
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgsOrExit)(args, { valueFlags: ['stopped-at', 'resume-file'], positionals: 2 }, error);
                 // Pass resume_file as-is (undefined when --resume-file was not provided) so
                 // cmdStateRecordSession can distinguish "caller explicitly passed a value" from
                 // "option was not supplied" and apply the template-default-only replacement guard.
                 state.cmdStateRecordSession(cwd, { stopped_at: strArg(a, 'stopped-at'), resume_file: strArg(a, 'resume-file') }, raw);
             },
             'begin-phase': () => {
-                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['phase', 'name', 'plans']);
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgsOrExit)(args, { valueFlags: ['phase', 'name', 'plans'], positionals: 2 }, error);
                 state.cmdStateBeginPhase(cwd, strArg(a, 'phase'), strArg(a, 'name'), parsePlans(strArg(a, 'plans')), raw);
             },
             'signal-waiting': () => {
-                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['type', 'question', 'options', 'phase']);
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgsOrExit)(args, { valueFlags: ['type', 'question', 'options', 'phase'], positionals: 2 }, error);
                 state.cmdSignalWaiting(cwd, strArg(a, 'type'), strArg(a, 'question'), strArg(a, 'options'), strArg(a, 'phase'), raw);
             },
             'signal-resume': () => state.cmdSignalResume(cwd, raw),
             'planned-phase': () => {
-                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['phase', 'name', 'plans']);
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgsOrExit)(args, { valueFlags: ['phase', 'name', 'plans'], positionals: 2 }, error);
                 // #3395: --name was parsed here but never forwarded (the StateModule
                 // signature had no channel for it), so the argument was silently
                 // dropped. It now persists into the Current Position `Phase:` line and
                 // the authoritative current_phase_name, mirroring begin-phase.
                 state.cmdStatePlannedPhase(cwd, strArg(a, 'phase'), strArg(a, 'name'), parsePlans(strArg(a, 'plans')), raw);
             },
-            validate: () => state.cmdStateValidate(cwd, raw),
+            validate: () => {
+                // #3696: --strict makes the verdict gateable by exit status. The
+                // default stays exit 0 — the exit code is Tier-2 observable output
+                // reaching unenumerable downstream consumers (ADR-3180 Decision 3).
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgsOrExit)(args, { booleanFlags: ['strict'], positionals: 2 }, error);
+                state.cmdStateValidate(cwd, raw, { strict: a['strict'] === true });
+            },
             sync: () => {
-                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, [], ['verify']);
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgsOrExit)(args, { booleanFlags: ['verify'], positionals: 2 }, error);
                 state.cmdStateSync(cwd, { verify: a['verify'] }, raw);
             },
             prune: () => {
-                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['keep-recent'], ['dry-run']);
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgsOrExit)(args, { valueFlags: ['keep-recent'], booleanFlags: ['dry-run'], positionals: 2 }, error);
                 state.cmdStatePrune(cwd, { keepRecent: strArg(a, 'keep-recent') || '3', dryRun: a['dry-run'] === true }, raw);
             },
             rebuild: () => {
-                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, [], ['dry-run', 'verbose']);
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgsOrExit)(args, { booleanFlags: ['dry-run', 'verbose'], positionals: 2 }, error);
                 state.cmdStateRebuild(cwd, { dryRun: a['dry-run'] === true, verbose: a['verbose'] === true }, raw);
             },
-            // complete-phase: CJS-only — no SDK counterpart.
+            // complete-phase: CJS-only — no SDK counterpart. Supports two shapes:
+            // the documented `--phase N` flag (docs/COMMANDS.md:2207) and an
+            // undocumented-but-preserved bare positional `state complete-phase N`
+            // (N3). A single static `positionals` count cannot represent both: if
+            // args[2] is the flag `--phase`, the boundary must be 2 so the generic
+            // flag/value walk (which starts at the boundary) recognizes `--phase`
+            // and consumes its value; only when args[2] is itself a bare, non-flag
+            // token does the boundary widen to 3 to accept it as the positional
+            // phase. Getting this wrong either breaks the documented flag form
+            // (boundary 3 treats `--phase`'s value as an unexpected trailing
+            // positional) or silently re-admits unknown flags (a static boundary
+            // of 3 with an empty args[2] never validates anything past it).
             'complete-phase': () => {
-                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['phase']);
+                const bareTrailingPositional = args[2] !== undefined && !args[2].startsWith('--');
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgsOrExit)(args, { valueFlags: ['phase'], positionals: bareTrailingPositional ? 3 : 2 }, error);
                 state.cmdStateCompletePhase(cwd, raw, strArg(a, 'phase') || args[2]);
             },
             'milestone-switch': () => {
-                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['milestone', 'name']);
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgsOrExit)(args, { valueFlags: ['milestone', 'name'], positionals: 2 }, error);
                 state.cmdStateMilestoneSwitch(cwd, strArg(a, 'milestone'), strArg(a, 'name'), raw);
             },
         },

package/gsd-core/bin/lib/state-contract.cjs

@@ -0,0 +1,359 @@
+"use strict";
+/**
+ * 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).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PUBLISH_REASON = exports.PHASE_STATUS = exports.PHASE_KEY_ORDER = exports.CONTRACT_KEY_ORDER = exports.STATE_CONTRACT_FLAVOR = exports.STATE_CONTRACT_VERSION = void 0;
+exports.buildStateContract = buildStateContract;
+exports.publishStateContract = publishStateContract;
+const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = __importDefault(require("node:fs"));
+// ─── Public wire vocabulary ────────────────────────────────────────────────
+exports.STATE_CONTRACT_VERSION = '1.0.0';
+exports.STATE_CONTRACT_FLAVOR = 'core';
+/** Key order of the emitted contract object — an observable, pinned by test. */
+exports.CONTRACT_KEY_ORDER = Object.freeze(['contract', 'flavor', 'milestone', 'phases', 'next', 'updated_at']);
+/** Key order of each emitted phase object — an observable, pinned by test. */
+exports.PHASE_KEY_ORDER = Object.freeze(['number', 'name', 'status']);
+/** Frozen three-value phase status vocabulary. Conservative in what we send (Postel's Law). */
+exports.PHASE_STATUS = Object.freeze({
+    COMPLETE: 'complete',
+    IN_PROGRESS: 'in_progress',
+    PENDING: 'pending',
+});
+/** Frozen `publishStateContract` result reasons. */
+exports.PUBLISH_REASON = Object.freeze({
+    PUBLISHED: 'published',
+    NO_PLANNING_DIR: 'no_planning_dir',
+    WRITE_FAILED: 'write_failed',
+});
+let _owners = 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() {
+    if (_owners)
+        return _owners;
+    /* eslint-disable @typescript-eslint/no-require-imports */
+    const planningWorkspaceMod = require('./planning-workspace.cjs');
+    const shellCommandProjectionMod = require('./shell-command-projection.cjs');
+    const phaseLifecycleMod = require('./phase-lifecycle.cjs');
+    const phaseIdMod = require('./phase-id.cjs');
+    const roadmapParserMod = require('./roadmap-parser.cjs');
+    const markdownSectionizerMod = require('./markdown-sectionizer.cjs');
+    const stateDocumentMod = require('./state-document.cjs');
+    const frontmatterMod = require('./frontmatter.cjs');
+    const smartEntryMod = require('./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) {
+    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) {
+    const normalized = (raw ?? '').trim().toLowerCase().replace(/\s+/g, ' ');
+    if (normalized === 'complete')
+        return exports.PHASE_STATUS.COMPLETE;
+    if (normalized === 'in progress')
+        return exports.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 exports.PHASE_STATUS.PENDING;
+}
+function phasesFromProgressTable(table) {
+    const { isSentinelPhaseId } = owners();
+    const phases = [];
+    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) {
+    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, cwd, statePath) {
+    const { collectSection, isSentinelPhaseId } = owners();
+    const section = collectSection(roadmapContent, (h) => /^phases$/i.test(h.text.trim()));
+    if (!section)
+        return [];
+    const currentPhase = currentPhaseFromState(statePath);
+    const phases = [];
+    let match;
+    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
+            ? exports.PHASE_STATUS.COMPLETE
+            : (currentPhase !== null && number === currentPhase ? exports.PHASE_STATUS.IN_PROGRESS : exports.PHASE_STATUS.PENDING);
+        phases.push({ number, name: name.length > 0 ? name : null, status });
+    }
+    return phases;
+}
+function buildPhases(cwd, paths) {
+    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, deps) {
+    try {
+        const classify = deps?.classify ?? 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.
+ */
+function buildStateContract(cwd, deps) {
+    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;
+    try {
+        paths = owners().planningPaths(cwd);
+    }
+    catch {
+        paths = null;
+    }
+    if (!paths) {
+        return {
+            contract: exports.STATE_CONTRACT_VERSION,
+            flavor: exports.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: exports.STATE_CONTRACT_VERSION,
+        flavor: exports.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.
+ */
+function publishStateContract(cwd, deps) {
+    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;
+        try {
+            paths = planningPaths(cwd);
+        }
+        catch {
+            return { published: false, reason: exports.PUBLISH_REASON.NO_PLANNING_DIR };
+        }
+        if (!node_fs_1.default.existsSync(paths.planning)) {
+            return { published: false, reason: exports.PUBLISH_REASON.NO_PLANNING_DIR };
+        }
+        const snapshot = buildStateContract(cwd, deps);
+        const statePath = node_path_1.default.join(paths.planning, 'state.json');
+        try {
+            platformWriteSync(statePath, JSON.stringify(snapshot, null, 2) + '\n');
+        }
+        catch {
+            return { published: false, reason: exports.PUBLISH_REASON.WRITE_FAILED };
+        }
+        return { published: true, reason: exports.PUBLISH_REASON.PUBLISHED };
+    }
+    catch {
+        return { published: false, reason: exports.PUBLISH_REASON.WRITE_FAILED };
+    }
+}