@opengsd/gsd-core 1.15.0 → 1.17.0

package/gsd-core/bin/lib/smart-entry.cjs

@@ -43,6 +43,7 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_child_process_1 = require("node:child_process");
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
+const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
 // #3696: the calendar-validity predicate moved to the STATE.md document module
 // so `state validate` can assert the same `last_activity` invariant this reader
 // already enforces (ADR-227). Two copies would let the two surfaces disagree
@@ -52,14 +53,17 @@ const ioMod = require("./io.cjs");
 const { output } = ioMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
-const { planningPaths } = planningWorkspace;
+const { planningPaths, resolvePhaseIdConvention } = planningWorkspace;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const frontmatter = require("./frontmatter.cjs");
-const { extractFrontmatter } = frontmatter;
+const { extractFrontmatter, frontmatterBlock } = frontmatter;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-lifecycle.cjs is an export= CommonJS module
 const phaseLifecycle = require("./phase-lifecycle.cjs");
 const { deriveProgressFromRoadmap } = phaseLifecycle;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
+const roadmapParser = require("./roadmap-parser.cjs");
+const { extractCurrentMilestone, scanMilestonePhaseIds } = roadmapParser;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
 const stateDocument = require("./state-document.cjs");
 const { stateFieldValue } = stateDocument;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -71,6 +75,10 @@ const { readStateHeadFreshness } = stateMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const unusableInput = require("./unusable-input.cjs");
 const { warnUnusableInput, UNUSABLE_REASON } = unusableInput;
+// #5118: the verification-status owner's frontmatter-only report check.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const verificationMod = require("./verification.cjs");
+const { findVerificationStatusError } = verificationMod;
 // ─── Constants ────────────────────────────────────────────────────────────────
 /**
  * Staleness threshold for idle-stranded detection. A clean tree whose last
@@ -285,11 +293,20 @@ function detectVerifyFailed(cwd, currentPhaseRaw) {
     catch {
         return false;
     }
+    // #5118: this phase's VERIFICATION report `status` is judged by its owner
+    // (src/verification.cts, the same frontmatter-only, containment-checked
+    // locator every reader shares) — an out-of-set value is the owner's hard
+    // error here as at every other reader, never a silent "not failed". The
+    // body `STATUS:` marker scan below is this probe's own signal.
+    const statusError = findVerificationStatusError([latestDir]);
+    if (statusError)
+        throw statusError;
     const candidates = files.filter((f) => /summary|verif(?:y|ication)|uat/i.test(f));
     for (const name of candidates) {
         let content = '';
+        const filePath = node_path_1.default.join(latestDir, name);
         try {
-            content = node_fs_1.default.readFileSync(node_path_1.default.join(latestDir, name), 'utf-8');
+            content = node_fs_1.default.readFileSync(filePath, 'utf-8');
         }
         catch {
             continue;
@@ -311,7 +328,10 @@ function readStateFile(statePath) {
         return null;
     }
     const fm = extractFrontmatter(content, statePath);
-    const body = content.replace(/^---[\s\S]*?---\s*/, '');
+    // The body starts after the block `extractFrontmatter` just read (the one fence owner), so a
+    // `---` inside a value, a BOM, or an adjacent empty block cannot cut it somewhere else.
+    const block = frontmatterBlock(content);
+    const body = block ? block.rest.replace(/^\s+/, '') : content;
     return { fm, body };
 }
 /** Collect the full signal set from disk for `cwd`. Exported for unit tests. */
@@ -336,6 +356,7 @@ function detectSignals(cwd, now = Date.now) {
         stale_activity: false,
         roadmap_total_phases: null,
         roadmap_completed_phases: null,
+        milestone_phases: [],
         // No STATE.md (or unreadable) → no stamp to compare. Unknown, not fresh.
         state_commits_behind: null,
         state_commit_stale: null,
@@ -409,12 +430,18 @@ function detectSignals(cwd, now = Date.now) {
     // Progress table — isComplete falls back to the legacy comparison in that case.
     let roadmapTotalPhases = null;
     let roadmapCompletedPhases = null;
+    let milestonePhases = [];
     if (hasRoadmap) {
         try {
             const roadmapContent = node_fs_1.default.readFileSync(paths.roadmap, 'utf8');
             const derived = deriveProgressFromRoadmap(roadmapContent);
             roadmapTotalPhases = derived.totalPhases;
             roadmapCompletedPhases = derived.completedPhases;
+            // #5228: the ordered phase list of the current milestone, from the same
+            // scan the milestone-scoped commands use.
+            milestonePhases = [
+                ...scanMilestonePhaseIds(extractCurrentMilestone(roadmapContent, cwd), resolvePhaseIdConvention(cwd)),
+            ].sort(comparePhaseNum);
         }
         catch {
             /* ROADMAP.md unreadable — leave null; isComplete falls back to legacy. */
@@ -441,6 +468,7 @@ function detectSignals(cwd, now = Date.now) {
         stale_activity: staleActivity,
         roadmap_total_phases: roadmapTotalPhases,
         roadmap_completed_phases: roadmapCompletedPhases,
+        milestone_phases: milestonePhases,
         state_commits_behind: freshness.commits_behind,
         state_commit_stale: freshness.commit_stale,
     };
@@ -472,10 +500,21 @@ function isComplete(s) {
         // Legacy path: STATE.md comparison. It only fires when ROADMAP.md is
         // absent or has no Progress table, and uses canonical phase-id ordering
         // so dotted phase ids are never coerced to JavaScript numbers.
-        if (s.total_phases === null || s.current_phase === null)
-            return false;
-        if (comparePhaseNum(s.current_phase, s.total_phases) < 0)
+        if (s.current_phase === null)
             return false;
+        if (s.milestone_phases.length > 0) {
+            // #5228: compare against the milestone's LAST phase. The phase count is
+            // not a phase number once numbering continues from an earlier milestone.
+            const last = s.milestone_phases[s.milestone_phases.length - 1];
+            if (comparePhaseNum(s.current_phase, last) < 0)
+                return false;
+        }
+        else {
+            if (s.total_phases === null)
+                return false;
+            if (comparePhaseNum(s.current_phase, s.total_phases) < 0)
+                return false;
+        }
     }
     // Status regex: require milestone-level completion language. The pre-fix
     // regex matched any "shipped" / "done" substring (per-phase language).
@@ -542,52 +581,54 @@ function rec(id, label, command) {
     return action(id, label, command, true);
 }
 /** Per-situation ordered action list; recommended action first. */
-function actionsFor(situation, s) {
+function actionsFor(situation, s, runtime = 'claude') {
+    // #4859: commands are printed verbatim, so name them the way this runtime registers them.
+    const cmd = (name) => (0, runtime_slash_cjs_1.formatGsdSlash)(name, runtime);
     const phaseN = s.current_phase ?? '';
     const execLabel = phaseN === '' ? 'Continue executing' : `Continue executing phase ${phaseN}`;
     switch (situation) {
         case 'no-project':
             return [
-                rec('new-project', 'Start a new project', '/gsd:new-project'),
-                action('map-codebase', 'Map an existing codebase', '/gsd:map-codebase'),
-                action('quick', 'Quick task', '/gsd:quick'),
-                action('help', 'Show help', '/gsd:help'),
+                rec('new-project', 'Start a new project', cmd('new-project')),
+                action('map-codebase', 'Map an existing codebase', cmd('map-codebase')),
+                action('quick', 'Quick task', cmd('quick')),
+                action('help', 'Show help', cmd('help')),
             ];
         case 'paused':
             return [
-                rec('resume-work', 'Resume work', '/gsd:resume-work'),
-                action('progress', 'Show progress', '/gsd:progress'),
-                action('quick', 'Quick task', '/gsd:quick'),
-                action('help', 'Show help', '/gsd:help'),
+                rec('resume-work', 'Resume work', cmd('resume-work')),
+                action('progress', 'Show progress', cmd('progress')),
+                action('quick', 'Quick task', cmd('quick')),
+                action('help', 'Show help', cmd('help')),
             ];
         case 'blocked':
             return [
-                rec('debug', 'Debug the blocker', '/gsd:debug'),
-                action('verify-work', 'Verify current work', '/gsd:verify-work'),
-                action('capture', 'Capture a note', '/gsd:capture'),
-                action('progress', 'Show progress', '/gsd:progress'),
+                rec('debug', 'Debug the blocker', cmd('debug')),
+                action('verify-work', 'Verify current work', cmd('verify-work')),
+                action('capture', 'Capture a note', cmd('capture')),
+                action('progress', 'Show progress', cmd('progress')),
             ];
         case 'verify-failed':
             return [
-                rec('verify-work', 'Re-verify work', '/gsd:verify-work'),
-                action('debug', 'Debug the failure', '/gsd:debug'),
-                action('code-review', 'Review recent work', '/gsd:code-review'),
-                action('progress', 'Show progress', '/gsd:progress'),
+                rec('verify-work', 'Re-verify work', cmd('verify-work')),
+                action('debug', 'Debug the failure', cmd('debug')),
+                action('code-review', 'Review recent work', cmd('code-review')),
+                action('progress', 'Show progress', cmd('progress')),
             ];
         case 'needs-first-phase':
             return [
-                rec('discuss-phase', 'Discuss the first phase', '/gsd:discuss-phase'),
-                action('plan-phase', 'Plan phase 1', '/gsd:plan-phase'),
-                action('quick', 'Quick task', '/gsd:quick'),
-                action('progress', 'Show progress', '/gsd:progress'),
+                rec('discuss-phase', 'Discuss the first phase', cmd('discuss-phase')),
+                action('plan-phase', 'Plan phase 1', cmd('plan-phase')),
+                action('quick', 'Quick task', cmd('quick')),
+                action('progress', 'Show progress', cmd('progress')),
             ];
         case 'planning':
             // Forward motion → delegate to the single gated engine (see 'executing').
             return [
-                rec('progress-next', `Advance to the next step (plan phase ${phaseN || 1})`, '/gsd:progress --next'),
-                action('plan-phase', `Plan phase ${phaseN || 1}`, '/gsd:plan-phase'),
-                action('discuss-phase', 'Discuss before planning', '/gsd:discuss-phase'),
-                action('progress', 'Show progress', '/gsd:progress'),
+                rec('progress-next', `Advance to the next step (plan phase ${phaseN || 1})`, cmd('progress --next')),
+                action('plan-phase', `Plan phase ${phaseN || 1}`, cmd('plan-phase')),
+                action('discuss-phase', 'Discuss before planning', cmd('discuss-phase')),
+                action('progress', 'Show progress', cmd('progress')),
             ];
         case 'executing':
             // In-project forward motion delegates to the single gated engine
@@ -596,40 +637,40 @@ function actionsFor(situation, s) {
             // /gsd:execute-phase here — that divergence is why the old flat /gsd-next
             // was removed (#3054). Direct execute stays as an explicit secondary choice.
             return [
-                rec('progress-next', 'Advance to the next step', '/gsd:progress --next'),
-                action('execute-phase', execLabel, '/gsd:execute-phase'),
-                action('quick', 'Quick task', '/gsd:quick'),
-                action('code-review', 'Review recent work', '/gsd:code-review'),
+                rec('progress-next', 'Advance to the next step', cmd('progress --next')),
+                action('execute-phase', execLabel, cmd('execute-phase')),
+                action('quick', 'Quick task', cmd('quick')),
+                action('code-review', 'Review recent work', cmd('code-review')),
             ];
         case 'verify-pending':
             // Forward motion → delegate to the single gated engine (see 'executing').
             return [
-                rec('progress-next', 'Advance to the next step (verify)', '/gsd:progress --next'),
-                action('verify-work', 'Verify work', '/gsd:verify-work'),
-                action('code-review', 'Review recent work', '/gsd:code-review'),
-                action('ship', 'Ship completed work', '/gsd:ship'),
+                rec('progress-next', 'Advance to the next step (verify)', cmd('progress --next')),
+                action('verify-work', 'Verify work', cmd('verify-work')),
+                action('code-review', 'Review recent work', cmd('code-review')),
+                action('ship', 'Ship completed work', cmd('ship')),
             ];
         case 'idle-stranded':
             return [
-                rec('ship', 'Ship committed work', '/gsd:ship'),
-                action('complete-milestone', 'Complete the milestone', '/gsd:complete-milestone'),
-                action('progress', 'Show progress', '/gsd:progress'),
-                action('capture', 'Capture a note', '/gsd:capture'),
+                rec('ship', 'Ship committed work', cmd('ship')),
+                action('complete-milestone', 'Complete the milestone', cmd('complete-milestone')),
+                action('progress', 'Show progress', cmd('progress')),
+                action('capture', 'Capture a note', cmd('capture')),
             ];
         case 'complete':
             return [
-                rec('new-milestone', 'Start a new milestone', '/gsd:new-milestone'),
-                action('extract-learnings', 'Extract learnings', '/gsd:extract-learnings'),
-                action('quick', 'Quick task', '/gsd:quick'),
-                action('progress', 'Show progress', '/gsd:progress'),
+                rec('new-milestone', 'Start a new milestone', cmd('new-milestone')),
+                action('extract-learnings', 'Extract learnings', cmd('extract-learnings')),
+                action('quick', 'Quick task', cmd('quick')),
+                action('progress', 'Show progress', cmd('progress')),
             ];
         case 'unknown':
         default:
             return [
-                rec('progress', 'Show progress', '/gsd:progress'),
-                action('progress-next', 'Advance to the next step', '/gsd:progress --next'),
-                action('quick', 'Quick task', '/gsd:quick'),
-                action('help', 'Show help', '/gsd:help'),
+                rec('progress', 'Show progress', cmd('progress')),
+                action('progress-next', 'Advance to the next step', cmd('progress --next')),
+                action('quick', 'Quick task', cmd('quick')),
+                action('help', 'Show help', cmd('help')),
             ];
     }
 }
@@ -647,7 +688,7 @@ function buildSummary(situation, s) {
         case 'needs-first-phase':
             return 'Project initialized — plan your first phase';
         case 'planning':
-            return `Phase ${s.current_phase ?? '?'} of ${s.total_phases ?? '?'} — needs a plan`;
+            return `${phasePosition(s)} — needs a plan`;
         case 'executing':
             return progressLine('executing', s);
         case 'verify-pending':
@@ -661,10 +702,24 @@ function buildSummary(situation, s) {
             return 'Unsure of state — showing progress';
     }
 }
+/**
+ * "Phase N of M" for the current phase. N is the phase's 1-based position in
+ * the current milestone's ordered phase list (#5228), so a milestone that
+ * continues the numbering of an earlier one (phases 9-17) reads "Phase 1 of 9",
+ * not "Phase 9 of 9". When the phase is not in that list (or the roadmap lists
+ * none) the STATE.md figures are printed as recorded.
+ */
+function phasePosition(s) {
+    const current = s.current_phase;
+    const at = current === null ? -1 : s.milestone_phases.findIndex((id) => comparePhaseNum(id, current) === 0);
+    if (at >= 0)
+        return `Phase ${at + 1} of ${s.milestone_phases.length}`;
+    return `Phase ${s.current_phase ?? '?'} of ${s.total_phases ?? '?'}`;
+}
 function progressLine(tail, s) {
     const parts = [];
     if (s.current_phase !== null && s.total_phases !== null) {
-        parts.push(`Phase ${s.current_phase} of ${s.total_phases}`);
+        parts.push(phasePosition(s));
     }
     else if (s.current_phase !== null) {
         parts.push(`Phase ${s.current_phase}`);
@@ -683,7 +738,7 @@ function progressLine(tail, s) {
 function classifyProject(cwd, now = Date.now) {
     const signals = detectSignals(cwd, now);
     const situation = classify(signals);
-    const actions = actionsFor(situation, signals);
+    const actions = actionsFor(situation, signals, (0, runtime_slash_cjs_1.resolveRuntime)(cwd));
     const recommended = actions.find((a) => a.recommended)?.id ?? 'progress';
     const summary = buildSummary(situation, signals);
     return { situation, recommended, summary, signals, actions };
@@ -702,6 +757,6 @@ function runSmartEntry(cwd, args, raw) {
         return;
     }
     // Human mode: a compact one-liner plus the recommended action.
-    const human = `${result.summary}\nRecommended: ${result.recommended} → ${result.actions.find((a) => a.id === result.recommended)?.command ?? '/gsd:progress'}`;
+    const human = `${result.summary}\nRecommended: ${result.recommended} → ${result.actions.find((a) => a.id === result.recommended)?.command ?? (0, runtime_slash_cjs_1.runtimeCommand)(cwd, 'progress')}`;
     output(null, true, human);
 }

package/gsd-core/bin/lib/stale-bake-guard.cjs

@@ -21,22 +21,23 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const capabilityRegistry = require('./capability-registry.cjs');
+const { hostBehaviorsFor } = require('./runtime-name-policy.cjs');
+const { resolveConfigHomeFromDescriptor } = require('./runtime-homes.cjs');
+const { resolveActiveRuntime } = require('./runtime-slash.cjs');
 
 /**
- * Runtimes whose agent config is static frontmatter/TOML baked at install time.
- * MUST stay in sync with the bake paths in bin/install.js. The parity test in
- * tests/stale-bake-guard.test.cjs asserts this matches the runtimes that
- * actually emit a baked model: line id #2256 (opencode), #49/#2256 (codex),
- * and #2093 (kilo).
+ * Runtimes whose agent config is static frontmatter/TOML baked at install time,
+ * DERIVED from the runtime descriptors (`hostBehaviors.bakesStaticAgentModel`,
+ * #5169) instead of a hand-kept list: line id #2256 (opencode), #49/#2256
+ * (codex), and #2093 (kilo) declare it, and a new baking runtime does too.
  */
-const STATIC_FRONTMATTER_RUNTIMES = Object.freeze(['codex', 'kilo', 'opencode']);
+const STATIC_FRONTMATTER_RUNTIMES = Object.freeze(
+  Object.keys(capabilityRegistry.runtimes)
+    .filter((id) => hostBehaviorsFor(id).bakesStaticAgentModel === true)
+    .sort(),
+);
 
-/** Per-runtime `gsd install` flag, for the remediation hint in the warning. */
-const INSTALL_FLAG_BY_RUNTIME = Object.freeze({
-  codex: '--codex',
-  opencode: '--opencode',
-  kilo: '--kilo',
-});
 
 const _warnedKeys = new Set();
 
@@ -64,7 +65,7 @@ function formatStaleBakeWarning({ runtime, configPath, configMtimeMs, agentMtime
   const signal = detectStaleBake({ runtime, configMtimeMs, agentMtimeMs });
   if (!signal) return '';
   const configDate = new Date(configMtimeMs).toISOString();
-  const installFlag = INSTALL_FLAG_BY_RUNTIME[runtime] || `--${runtime}`;
+  const installFlag = `--${runtime}`;
   return [
     `gsd: model config in ${configPath} changed since agents were last baked (${configDate}).`,
     `     Static-frontmatter runtime '${runtime}' ignores the new model_overrides`,
@@ -74,44 +75,27 @@ function formatStaleBakeWarning({ runtime, configPath, configMtimeMs, agentMtime
 }
 
 /**
- * Pure: resolve the active runtime id from a parsed config object.
- * Returns the runtime string, or `'claude'` when unset (the spawn-time default
- * for which the guard is a no-op).
+ * Resolve the active runtime id for the guard: the SAME chain every consumer of
+ * "which runtime is this install" reads — GSD_RUNTIME → config.runtime →
+ * per-install `.gsd-runtime` marker → `'claude'` (#5169, #4690). Returns
+ * `'claude'` when nothing is declared (the spawn-time default for which the
+ * guard is a no-op).
  */
-function resolveRuntimeFromConfig(config) {
-  if (config && typeof config === 'object'
-      && typeof config.runtime === 'string' && config.runtime) {
-    return config.runtime;
-  }
-  return 'claude';
+function resolveRuntimeFromConfig(config, env = process.env) {
+  return resolveActiveRuntime(config, env);
 }
 
 /**
- * Resolve the install root for a runtime's agent files, honoring the same env
- * vars the installer does (CODEX_HOME, OPENCODE_CONFIG_DIR, KILO_CONFIG_DIR).
- * Returns the absolute directory or `null` for unsupported runtimes.
+ * Resolve the install root for a runtime's agent files from the runtime
+ * descriptor's `configHome` (the same resolution the installer uses), then
+ * append `agents` — the installer writes agents to `<configHome>/agents`
+ * (plural; #2093). Returns the absolute directory or `null` for runtimes that
+ * do not bake a static agent model.
  */
 function resolveAgentDir(runtime, { env = process.env, homedir = os.homedir } = {}) {
-  if (runtime === 'opencode') {
-    const base = (env.OPENCODE_CONFIG_DIR && String(env.OPENCODE_CONFIG_DIR).trim()) || path.join(homedir(), '.config', 'opencode');
-    // #2093 fix: the installer writes agents to `<base>/agents` (plural — see
-    // bin/install.js's universal `agentsDest = path.join(targetDir, 'agents')`,
-    // verified against a live `--opencode --global` install). The prior
-    // singular `agent` never matched the real install output, so this guard's
-    // `findOldestAgentMtime` always hit ENOENT and warnIfStaleBake was a
-    // silent no-op for opencode in production — discovered while wiring the
-    // parallel kilo entry below (same bake mechanism, #2093).
-    return path.join(base, 'agents');
-  }
-  if (runtime === 'kilo') {
-    const base = (env.KILO_CONFIG_DIR && String(env.KILO_CONFIG_DIR).trim()) || path.join(homedir(), '.config', 'kilo');
-    return path.join(base, 'agents');
-  }
-  if (runtime === 'codex') {
-    const base = (env.CODEX_HOME && String(env.CODEX_HOME).trim()) || path.join(homedir(), '.codex');
-    return path.join(base, 'agents');
-  }
-  return null;
+  if (!STATIC_FRONTMATTER_RUNTIMES.includes(runtime)) return null;
+  const configHome = capabilityRegistry.runtimes[runtime].runtime.configHome;
+  return path.join(resolveConfigHomeFromDescriptor(configHome, { env, home: homedir() }), 'agents');
 }
 
 /**
@@ -168,8 +152,8 @@ function findOldestAgentMtime(runtime, { env = process.env, homedir = os.homedir
   for (const entry of entries) {
     if (!entry.isFile()) continue;
     if (!entry.name.startsWith('gsd-')) continue;
-    const isAgentFile = ((runtime === 'opencode' || runtime === 'kilo') && entry.name.endsWith('.md'))
-      || (runtime === 'codex' && (entry.name.endsWith('.toml') || entry.name.endsWith('.md')));
+    const bakedExts = hostBehaviorsFor(runtime).bakedAgentFileExtensions;
+    const isAgentFile = Array.isArray(bakedExts) && bakedExts.some((ext) => entry.name.endsWith(ext));
     if (!isAgentFile) continue;
     try {
       const st = fsStatSync(path.join(dir, entry.name));
@@ -209,7 +193,7 @@ function warnIfStaleBake(cwd, options = {}) {
   } = options;
   try {
     const resolvedConfig = config || _readRuntimeConfig(cwd, { fsStatSync });
-    const runtime = resolveRuntimeFromConfig(resolvedConfig);
+    const runtime = resolveRuntimeFromConfig(resolvedConfig, env);
     if (!STATIC_FRONTMATTER_RUNTIMES.includes(runtime)) return false;
 
     const dedupKey = `${runtime}::${path.resolve(cwd || '.')}`;

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

@@ -73,6 +73,12 @@ exports.buildStateContract = buildStateContract;
 exports.publishStateContract = publishStateContract;
 const node_path_1 = __importDefault(require("node:path"));
 const node_fs_1 = __importDefault(require("node:fs"));
+// #5060: `phase-status.cjs` is a LOAD-TIME LEAF — no top-level requires of
+// its own (verification.cjs/plan-scan.cjs are required lazily, only inside
+// `phaseStatus()`) — so importing it here at top level does not reopen the
+// documented `state.cjs -> state-contract.cjs -> smart-entry.cjs -> state.cjs`
+// require cycle the file header warns about.
+const phase_status_cjs_1 = require("./phase-status.cjs");
 // ─── Public wire vocabulary ────────────────────────────────────────────────
 exports.STATE_CONTRACT_VERSION = '1.0.0';
 exports.STATE_CONTRACT_FLAVOR = 'core';
@@ -80,12 +86,14 @@ exports.STATE_CONTRACT_FLAVOR = 'core';
 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 three-value phase status vocabulary. Conservative in what we send
+ * (Postel's Law). #5060: identity-pinned to the Phase Status Module's own
+ * `WIRE_STATUS` — this is not a copy, it IS that frozen object, so
+ * `state-contract`'s `PHASE_STATUS` and `phase-status.cjs`'s `WIRE_STATUS`
+ * can never independently drift.
+ */
+exports.PHASE_STATUS = phase_status_cjs_1.WIRE_STATUS;
 /** Frozen `publishStateContract` result reasons. */
 exports.PUBLISH_REASON = Object.freeze({
     PUBLISHED: 'published',
@@ -146,17 +154,6 @@ function buildMilestone(cwd) {
 }
 // ─── 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 = [];
@@ -169,7 +166,7 @@ function phasesFromProgressTable(table) {
         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']) });
+        phases.push({ number, name, status: (0, phase_status_cjs_1.parseRoadmapStatusCell)(row['Status']) });
     }
     return phases;
 }