@opengsd/gsd-core 1.15.0 → 1.16.0

package/gsd-core/bin/lib/model-resolver.cjs

@@ -55,24 +55,24 @@ const { planningDir } = planningWorkspaceMod;
 // <install>/gsd-core/bin/lib). Precedence for the gate: project config.runtime →
 // GSD_RUNTIME env (manual/CI override + test seam) → install marker → 'claude'.
 //
-// `claude` is currently the ONLY runtime with nativeModelAliases:true; a
-// registry-parity test guards this set so a future alias-capable runtime fails
-// loudly here instead of silently omitting.
-const RUNTIMES_WITH_NATIVE_ALIASES = new Set(['claude']);
+// Whether a runtime resolves tier aliases natively is a runtime-descriptor fact
+// (`hostBehaviors.nativeModelAliases`, #5169) — `claude` is currently the ONLY
+// runtime that declares it — not a hand-kept set in this module. A label that is
+// not a registered runtime (a future runtime named by env/config) has none.
+function hasNativeModelAliases(runtime) {
+    return (0, runtime_name_policy_cjs_1.hostBehaviorsFor)(runtime).nativeModelAliases === true;
+}
 // #3897 rung 2: the marker reader + its cache and test seams were promoted to
 // the canonical owner, `runtime-slash.cts` (imported above) — this module now
 // consumes that single implementation instead of holding its own copy. N5:
 // behaviour and the seam contract are unchanged by the move; the re-exports
 // below (`export =` at the bottom of this file) preserve every existing
 // caller's `require('./model-resolver.cjs')` surface byte-for-behaviour.
-// The runtime whose install is actually resolving, canonicalized so an alias or
-// case variant (e.g. "claude-code"/"Claude") cannot defeat the native-alias
-// check below (#2297 review). Precedence mirrors resolveRuntime()
-// (runtime-slash.cts): GSD_RUNTIME env → project config.runtime → per-install
-// .gsd-runtime marker → 'claude'.
-function resolveActiveRuntime(config) {
-    return (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)(process.env['GSD_RUNTIME'], config['runtime'], (0, runtime_slash_cjs_1.readInstallRuntimeMarker)()) || 'claude';
-}
+// The runtime whose install is actually resolving — one chain, owned by
+// runtime-slash.cts's `resolveActiveRuntime` (#5169): GSD_RUNTIME env → project
+// config.runtime → per-install .gsd-runtime marker → 'claude', canonicalized so
+// an alias or case variant (e.g. "claude-code"/"Claude") cannot defeat the
+// native-alias check below (#2297 review).
 // Did the PROJECT's own config (root `.planning/config.json` or the active
 // workstream/project override) explicitly set resolve_model_ids to "omit"?
 // Project config takes precedence over the shared ~/.gsd/defaults.json (#2297
@@ -129,7 +129,7 @@ function _resolveRuntimeTier(config, tier) {
         // the per-install marker), and reading it raw made
         // `model_profile_overrides.<runtime>.<tier>` silently inert for every
         // install that did not also write the key by hand.
-        runtime: resolveActiveRuntime(config),
+        runtime: (0, runtime_slash_cjs_1.resolveActiveRuntime)(config),
         tier,
         overrides: config['model_profile_overrides'],
     });
@@ -502,7 +502,7 @@ function resolveModelInternal(cwd, agentType) {
         ? modelOverrides[agentType]
         : undefined;
     if (override) {
-        const mapped = mapClaudeOverrideForRuntime(override, resolveActiveRuntime(config), agentType);
+        const mapped = mapClaudeOverrideForRuntime(override, (0, runtime_slash_cjs_1.resolveActiveRuntime)(config), agentType);
         if (mapped !== null)
             return mapped;
         // Unmappable Claude ID — fall through to tier resolution (matches model_policy).
@@ -528,7 +528,7 @@ function resolveModelInternal(cwd, agentType) {
     // Never undefined, so the "no runtime declared anywhere" case still resolves
     // 'claude' and step 3's deliberate claude skip (#1156/#2297/#4192) is
     // unchanged for every existing install.
-    const activeRuntime = resolveActiveRuntime(config);
+    const activeRuntime = (0, runtime_slash_cjs_1.resolveActiveRuntime)(config);
     if (tier && tier !== 'inherit') {
         const onClaude = activeRuntime === 'claude';
         const effectiveRuntime = activeRuntime;
@@ -582,7 +582,7 @@ function resolveModelInternal(cwd, agentType) {
     // map, but only outranks the omit gate when that key canonicalizes to a
     // recognised non-Claude runtime.
     const omitApplies = config['resolve_model_ids'] === 'omit'
-        && (projectExplicitlySetsOmit(cwd) || !RUNTIMES_WITH_NATIVE_ALIASES.has(activeRuntime));
+        && (projectExplicitlySetsOmit(cwd) || !hasNativeModelAliases(activeRuntime));
     // CANONICALIZED, not the raw field. Comparing the raw value against the literal
     // 'claude' made every spelling that is not exactly that string count as a
     // non-Claude opt-in and outrank the omit gate: `runtime:"Claude"`,
@@ -764,13 +764,13 @@ function resolveModelForTier(cwd, agentType, attempt) {
         ? modelOverrides[agentType]
         : undefined;
     if (override) {
-        const mapped = mapClaudeOverrideForRuntime(override, resolveActiveRuntime(config), agentType);
+        const mapped = mapClaudeOverrideForRuntime(override, (0, runtime_slash_cjs_1.resolveActiveRuntime)(config), agentType);
         if (mapped !== null)
             return mapped;
         // Unmappable Claude ID — fall through to dynamic_routing / model_policy resolution.
     }
     // #4505: same active-runtime rule as resolveModelInternal step 3.
-    if (config['model_policy'] && resolveActiveRuntime(config) !== 'claude') {
+    if (config['model_policy'] && (0, runtime_slash_cjs_1.resolveActiveRuntime)(config) !== 'claude') {
         return resolveModelInternal(cwd, agentType);
     }
     const alias = dynamicRoutingModel(config, agentType, attemptN);

package/gsd-core/bin/lib/observability/event.cjs

@@ -16,7 +16,7 @@
  *                                     (RFC 4122); invalid values are silently coerced to undefined.
  *   command:       string  — the dispatched verb
  *   args?:         unknown — only present when includeArgs === true
- *   result:        { kind: 'ok' | 'UnknownCommand' | 'InvalidArgs' | 'HandlerRefusal' | 'HandlerFailure', ...payload }
+ *   result:        { kind: 'ok' | 'UnknownCommand' | 'InvalidArgs' | 'HandlerRefusal' | 'HandlerFailure' | 'VerificationStatusInvalid', ...payload }
  *   timestamp:     string  — ISO 8601
  */
 Object.defineProperty(exports, "__esModule", { value: true });

package/gsd-core/bin/lib/observability/logger.cjs

@@ -16,6 +16,11 @@
  * No-op logger (createNoOpLogger):
  *   Silent on all events. Used as the Hub default when no logger is injected.
  *
+ * Live-seam gate (resolveDispatchLogger, #4975):
+ *   The one opt-in decision both live createHub() seams share. Resolves
+ *   `audit.enabled` for the seam's cwd and returns the default logger, or
+ *   undefined (inject nothing) when observability is off.
+ *
  * ADR-457 build-at-publish: the hand-written bin/lib/observability/logger.cjs
  * collapsed to a TypeScript source of truth. Behaviour is preserved
  * byte-for-behaviour from the prior hand-written .cjs; only types are added.
@@ -26,6 +31,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const redaction_cjs_1 = require("./redaction.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningWorkspace = require("../planning-workspace.cjs");
+const { readScopedConfigValue } = planningWorkspace;
 const AUDIT_FILE_NAME = '.gsd-trace.jsonl';
 const PLANNING_DIR = '.planning';
 // ─── helpers ─────────────────────────────────────────────────────────────────
@@ -47,6 +55,8 @@ function _safeStringify(value) {
  * inject nothing (the Hub stays byte-for-byte silent, preserving the default
  * dispatch output contract, incl. --json-errors); when on, the caller injects
  * createDefaultLogger and gets the stderr-on-error line + opt-in file audit.
+ * The live seams reach it through resolveDispatchLogger, which supplies the
+ * project config — called bare, only the env var is seen (#4975).
  */
 function _isAuditEnabled(config) {
     if (process.env['GSD_AUDIT'] === '1')
@@ -148,4 +158,39 @@ function createDefaultLogger({ cwd = process.cwd(), config } = {}) {
         },
     };
 }
-module.exports = { createDefaultLogger, createNoOpLogger, isAuditEnabled: _isAuditEnabled };
+/**
+ * Resolve `audit.enabled` for `cwd` as the value `config-get audit.enabled`
+ * reports, through planning-workspace's readScopedConfigValue — the one
+ * scope-aware ladder worktreesOptedOut (#3972) reads too, so the two gates
+ * can never resolve the same config differently. Strict `=== true`, never
+ * coerced.
+ *
+ * Direct file reads, deliberately NOT loadConfig: this runs on every live
+ * dispatch, and loadConfig can rewrite config.json, spawn git, scan the
+ * capability registry, and print warnings — none of which a dispatch that
+ * never opted in may do (the default dispatch output is a stable contract,
+ * ADR-2619). Never throws. An unreadable or unparseable config file sets
+ * nothing, so the ladder moves on: under GSD_WORKSTREAM a broken workstream
+ * config inherits the root's `audit.enabled` (where config-get fails with
+ * CONFIG_PARSE_FAILED); otherwise the GSD_AUDIT env var alone decides.
+ */
+function _readAuditConfig(cwd) {
+    const { present, value } = readScopedConfigValue(cwd, ['audit', 'enabled']);
+    return { audit: { enabled: present && value === true } };
+}
+/**
+ * The DispatchLogger a live createHub() seam injects (#4975). Either
+ * GSD_AUDIT=1 or `audit.enabled: true` in the project config turns the opt-in
+ * audit trail (and the structured stderr line on error) on; neither turns the
+ * other off. When observability is off this returns undefined so the Hub keeps
+ * its no-op fallback and the default dispatch output — including the
+ * --json-errors envelope — stays byte-for-byte unchanged (#2620).
+ *
+ * `cwd` defaults exactly as createDefaultLogger's does, so the config that
+ * decides and the directory that receives the trail are always the same.
+ */
+function resolveDispatchLogger(cwd = process.cwd()) {
+    const config = _readAuditConfig(cwd);
+    return _isAuditEnabled(config) ? createDefaultLogger({ cwd, config }) : undefined;
+}
+module.exports = { createDefaultLogger, createNoOpLogger, isAuditEnabled: _isAuditEnabled, resolveDispatchLogger };

package/gsd-core/bin/lib/pattern.cjs

@@ -44,6 +44,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MAX_USER_PATTERN_LEN = void 0;
 exports.escapeRegex = escapeRegex;
+exports.escapeEre = escapeEre;
 exports.literalPattern = literalPattern;
 exports.compileUserPattern = compileUserPattern;
 // re2js is vendored, not an npm dependency at runtime: gsd-core/bin/** is
@@ -66,6 +67,15 @@ const escapeMetachars = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 function escapeRegex(value) {
     return (escapeBuiltin ?? escapeMetachars)(value);
 }
+/**
+ * Escape `value` for a POSIX extended regular expression (e.g. `git log --extended-regexp
+ * --grep=…`). Always the plain backslash-escape of every ERE metacharacter, never
+ * `RegExp.escape`: that built-in writes a leading digit as `\x31`, which ERE does not read as a
+ * digit. #5139 (a plan id interpolated into a git `--grep` pattern).
+ */
+function escapeEre(value) {
+    return escapeMetachars(value);
+}
 function literalPattern(value, flags) {
     return new RegExp(escapeRegex(value), flags);
 }

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

@@ -22,10 +22,12 @@ const commandRoutingHub = require("./command-routing-hub.cjs");
 const { createHub, ERROR_KINDS, makeInvalidArgs } = commandRoutingHub;
 // #2620 (ADR-0174 §6): inject the reference DispatchLogger on the live phase
 // dispatch path, but only when observability is opt-in enabled; otherwise the
-// Hub stays byte-for-byte silent via its no-op fallback.
+// Hub stays byte-for-byte silent via its no-op fallback. #4975: the opt-in is
+// GSD_AUDIT=1 or `audit.enabled` in the project config — resolveDispatchLogger
+// owns that whole decision for every live seam.
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const observabilityLogger = require("./observability/logger.cjs");
-const { createDefaultLogger, isAuditEnabled } = observabilityLogger;
+const { resolveDispatchLogger } = observabilityLogger;
 // ─── Implementation ───────────────────────────────────────────────────────────
 function routePhaseCommand({ phase, args, cwd, raw, error }) {
     // ── Unsupported subcommands ─────────────────────────────────────────────────
@@ -258,8 +260,8 @@ function routePhaseCommand({ phase, args, cwd, raw, error }) {
     // #175: Hub is CJS-only — no mode param, no sdkLoader.
     // #2620: wire the reference logger (ADR-0174 §6) only when observability is
     // opt-in enabled; otherwise leave it unset so the Hub stays byte-for-byte
-    // silent via its no-op fallback.
-    const hub = createHub({ cjsRegistry, manifest, logger: isAuditEnabled() ? createDefaultLogger({ cwd }) : undefined });
+    // silent via its no-op fallback. #4975: GSD_AUDIT=1 or `audit.enabled`.
+    const hub = createHub({ cjsRegistry, manifest, logger: resolveDispatchLogger(cwd) });
     // ── Dispatch ────────────────────────────────────────────────────────────────
     const result = hub.dispatch({
         family: 'phase',
@@ -282,6 +284,11 @@ function routePhaseCommand({ phase, args, cwd, raw, error }) {
             error(result.reason);
             return;
         }
+        if (result.kind === ERROR_KINDS.VerificationStatusInvalid) {
+            // #5118: typed reason survives to the CLI surface
+            error(result.message, result.reason);
+            return;
+        }
         // HandlerFailure: message field
         error(result.message);
         return;

package/gsd-core/bin/lib/phase-estimation.cjs

@@ -47,6 +47,7 @@ exports.parseCalibrationDocument = parseCalibrationDocument;
 exports.renderCalibrationDocument = renderCalibrationDocument;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- prompt-budget.cjs is an export= CommonJS module
 const promptBudget = require("./prompt-budget.cjs");
+const frontmatter_fence_cjs_1 = require("./frontmatter-fence.cjs");
 const { estimateTokens } = promptBudget;
 /**
  * Assert that a bare number is an UNCORRECTED projection.
@@ -239,11 +240,11 @@ function applyCalibration(rawTokens, factor) {
 function extractFrontmatterBlock(text, key) {
     if (typeof text !== 'string')
         return null;
-    // Anchor at byte 0 — CRLF-tolerant.
-    const fm = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|\r?$)/.exec(text);
-    if (fm === null)
+    // The block is the one the one fence owner finds (`locateFrontmatterFence`).
+    const fence = (0, frontmatter_fence_cjs_1.locateFrontmatterFence)(text);
+    if (!fence?.closed)
         return null;
-    const lines = fm[1].split(/\r?\n/);
+    const lines = text.slice(fence.openEnd, fence.bodyEnd).split(/\r?\n/);
     const startIdx = lines.findIndex((l) => l === `${key}:` || l.startsWith(`${key}:`));
     if (startIdx === -1)
         return null;

package/gsd-core/bin/lib/phase-id.cjs

@@ -1342,7 +1342,7 @@ const unpad = (digits) => digits.replace(/^0+(?=\d)/, '');
  *   candidates (#2237).
  *
  *   TAKE `matches[0]` — `cmdPhasesList`, `cmdInitManager`, `cmdRoadmapAnalyze`,
- *   `cmdVerifySchemaDrift`, `detectVerifyFailed`. Each read a directory to
+ *   the schema-drift gate (`resolvePhaseDirByToken`), `detectVerifyFailed`. Each read a directory to
  *   DECORATE a row they are already emitting; each used `.find()` before this
  *   PR, so first-match is their prior behavior preserved verbatim, and each is
  *   order-stable because the directory list is sorted and this function filters

package/gsd-core/bin/lib/phase-lifecycle.cjs

@@ -31,6 +31,9 @@ const markdown_table_cjs_1 = require("./markdown-table.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-id.cjs is an export= CommonJS module
 const phaseIdMod = require("./phase-id.cjs");
 const { isSentinelPhaseId } = phaseIdMod;
+// #5060: `phase-status.cjs` is a load-time leaf (no top-level requires), safe
+// to import here for the ROADMAP Status-cell reader.
+const phase_status_cjs_1 = require("./phase-status.cjs");
 /**
  * #3227: the single owner of "where is this ROADMAP's Progress table".
  * Lifted verbatim out of deriveProgressFromRoadmap so `state-contract.cts`
@@ -93,8 +96,6 @@ function deriveProgressFromRoadmap(roadmapContent) {
     const table = locateProgressTable(roadmapContent);
     if (table) {
         const allRows = table.rows;
-        const completed = allRows.filter((r) => /^complete$/i.test((r['Status'] ?? '').trim())).length;
-        completedPhases = completed > 0 ? completed : null;
         // Data rows only (exclude sentinel phases 0 and 999.x).
         // #3185: canonical sentinel predicate (SENTINEL_RANGES [0,999]) — this was a local 999-only literal that admitted Phase 0.
         const dataRows = allRows.filter((r) => {
@@ -102,6 +103,12 @@ function deriveProgressFromRoadmap(roadmapContent) {
             return /^\d/.test(phase) && !isSentinelPhaseId(phase);
         });
         totalPhases = dataRows.length > 0 ? dataRows.length : null;
+        // #5060: routed through the Phase Status Module's `parseRoadmapStatusCell`
+        // owner (rather than a local `/^complete$/i` regex) and counted over
+        // `dataRows` (not `allRows`) — a sentinel row's Status cell must never
+        // contribute to `completedPhases`.
+        const completed = dataRows.filter((r) => (0, phase_status_cjs_1.parseRoadmapStatusCell)(r['Status']) === phase_status_cjs_1.WIRE_STATUS.COMPLETE).length;
+        completedPhases = completed > 0 ? completed : null;
         let totalPlansSum = 0;
         for (const r of allRows) {
             const cell = (r['Plans Complete'] ?? '').trim();

package/gsd-core/bin/lib/phase-status.cjs

@@ -0,0 +1,360 @@
+"use strict";
+/**
+ * Phase Status Module — the single owner of "what state is phase P in?"
+ * (ADR-5057 §1/§2, epic #5056 Phase 1, #5060).
+ *
+ * ADR-3180 §7.4 made `isPhaseComplete` the owner of "is phase P complete?".
+ * The richer question the UI, the health rules and the ROADMAP writers ask —
+ * which rung of the lifecycle is this phase on — had no owner: it was derived
+ * at eleven sites in seven vocabularies, and two of them disagreed on a stale
+ * `passed` report. This module is that owner.
+ *
+ *   - `PHASE_STATUS` is a closed, frozen ladder. Its values are the upper-case
+ *     rung names, spelled unlike every projection word, so a display label or
+ *     a wire value can never pass for a status.
+ *   - `phaseStatusFromFacts` is the ladder itself — pure. Callers that already
+ *     hold the §7 owners' answers (the health rules over `PlanningSnapshot`,
+ *     the pure Workstream Inventory builder, `update-plan-progress`'s stricter
+ *     write gate) hand it those facts.
+ *   - `phaseStatus(phaseDir)` gathers the facts from the §7 owners only —
+ *     `scanPhasePlans` (§7.5) for counts and `isPhaseComplete` (§7.4) for
+ *     completion and the verification verdict. It never reads VERIFICATION.md
+ *     frontmatter itself.
+ *   - Every other vocabulary is a projection exported here: display labels,
+ *     the `state.json` / Workstream Inventory wire values, the ROADMAP
+ *     `## Progress` Status cell (both directions), `roadmap analyze` /
+ *     `init manager`'s `disk_status`, `init`'s `completion_status`, and
+ *     `init progress`'s `status`. A consumer never maps raw inputs to a word.
+ *   - Every function that takes a `PhaseStatus` throws `TypeError` on a value
+ *     outside the ladder, so an out-of-vocabulary value fails where it is
+ *     produced (ADR-5057 §1.2).
+ *
+ * LOAD-TIME LEAF. `verification.cjs` and `plan-scan.cjs` are required lazily
+ * inside `phaseStatus()`. `state-contract.cjs` imports this module at top
+ * level for its wire vocabulary, and `state-contract` sits on the documented
+ * `state -> state-contract -> smart-entry -> state` require cycle; keeping this
+ * module import-free at load keeps it off that cycle.
+ *
+ * ADR-457 build-at-publish: source in src/phase-status.cts, compiled to
+ * gsd-core/bin/lib/phase-status.cjs (gitignored).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMPLETION_STATUS = exports.PROGRESS_STATUS = exports.DISK_STATUS = exports.ROADMAP_STATUS_TOKEN = exports.WIRE_STATUS = exports.PHASE_STATUS = void 0;
+exports.phaseStatusFromFacts = phaseStatusFromFacts;
+exports.phaseStatus = phaseStatus;
+exports.foldPhaseStatuses = foldPhaseStatuses;
+exports.toDisplayLabel = toDisplayLabel;
+exports.toWireStatus = toWireStatus;
+exports.toRoadmapStatusCell = toRoadmapStatusCell;
+exports.toDiskStatus = toDiskStatus;
+exports.toCompletionStatus = toCompletionStatus;
+exports.toProgressStatus = toProgressStatus;
+exports.matchRoadmapStatusCell = matchRoadmapStatusCell;
+exports.parseRoadmapStatusCell = parseRoadmapStatusCell;
+// ─── Closed vocabularies ───────────────────────────────────────────────────
+/** The lifecycle ladder, lowest rung first. */
+exports.PHASE_STATUS = Object.freeze({
+    NOT_STARTED: 'NOT_STARTED',
+    PLANNED: 'PLANNED',
+    IN_PROGRESS: 'IN_PROGRESS',
+    EXECUTED: 'EXECUTED',
+    NEEDS_REVIEW: 'NEEDS_REVIEW',
+    COMPLETE: 'COMPLETE',
+});
+/**
+ * The three-value wire vocabulary published by `.planning/state.json`
+ * (`phases[].status`) and the Workstream Inventory (`PhaseStatus.status`).
+ */
+exports.WIRE_STATUS = Object.freeze({
+    COMPLETE: 'complete',
+    IN_PROGRESS: 'in_progress',
+    PENDING: 'pending',
+});
+/**
+ * The ROADMAP `## Progress` table Status-cell vocabulary: the template's
+ * `Not started | In progress | Complete | Deferred` plus the `Planned` word
+ * `roadmap update-plan-progress` writes. `In Progress` is spelled the way the
+ * writers have always written it.
+ */
+exports.ROADMAP_STATUS_TOKEN = Object.freeze({
+    NOT_STARTED: 'Not started',
+    PLANNED: 'Planned',
+    IN_PROGRESS: 'In Progress',
+    COMPLETE: 'Complete',
+    DEFERRED: 'Deferred',
+});
+/** `roadmap analyze` / `init manager`'s `disk_status` vocabulary (ADR-5057 §1.2). */
+exports.DISK_STATUS = Object.freeze({
+    COMPLETE: 'complete',
+    EXECUTED: 'executed',
+    PARTIAL: 'partial',
+    PLANNED: 'planned',
+    RESEARCHED: 'researched',
+    DISCUSSED: 'discussed',
+    EMPTY: 'empty',
+    NO_DIRECTORY: 'no_directory',
+});
+/** `init progress`'s per-phase `status` vocabulary (ADR-5057 §1.2). */
+exports.PROGRESS_STATUS = Object.freeze({
+    COMPLETE: 'complete',
+    EXECUTED: 'executed',
+    IN_PROGRESS: 'in_progress',
+    RESEARCHED: 'researched',
+    PENDING: 'pending',
+    NOT_STARTED: 'not_started',
+});
+/** `init`'s `completion_status` vocabulary (ADR-5057 §1.2). */
+exports.COMPLETION_STATUS = Object.freeze({
+    COMPLETE: 'complete',
+    EXECUTED: 'executed',
+    INCOMPLETE: 'incomplete',
+});
+const LADDER = Object.freeze([
+    exports.PHASE_STATUS.NOT_STARTED,
+    exports.PHASE_STATUS.PLANNED,
+    exports.PHASE_STATUS.IN_PROGRESS,
+    exports.PHASE_STATUS.EXECUTED,
+    exports.PHASE_STATUS.NEEDS_REVIEW,
+    exports.PHASE_STATUS.COMPLETE,
+]);
+const LADDER_RANK = new Map(LADDER.map((s, i) => [s, i]));
+function assertPhaseStatus(value, where) {
+    if (typeof value !== 'string' || !LADDER_RANK.has(value)) {
+        throw new TypeError(`${where}: ${JSON.stringify(value)} is not a PHASE_STATUS value`);
+    }
+}
+function assertCount(value, name) {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+        throw new TypeError(`phaseStatusFromFacts: ${name} must be a non-negative integer, got ${JSON.stringify(value)}`);
+    }
+}
+/**
+ * The ladder. First matching rung wins:
+ *   complete                     → COMPLETE     (disk-strict: no plan precondition, #3168)
+ *   no plans                     → NOT_STARTED
+ *   no summaries                 → PLANNED
+ *   fewer summaries than plans   → IN_PROGRESS
+ *   verification `human_needed`  → NEEDS_REVIEW
+ *   otherwise                    → EXECUTED     (gaps_found, stale, missing, unparseable, phase_dir_not_found)
+ *
+ * `verificationStatus`, when non-null, must be a VerificationStatus member
+ * (#5118) — the same fail-where-produced rule as `assertPhaseStatus`.
+ *
+ * Completion comes ONLY from `complete`. The ladder never restates a
+ * summary-versus-plan completion comparison (scripts/lint-completion-predicate-drift.cjs shape (c)).
+ */
+function phaseStatusFromFacts(facts) {
+    if (facts === null || typeof facts !== 'object') {
+        throw new TypeError('phaseStatusFromFacts: facts object required');
+    }
+    const { planCount, summaryCount, complete, verificationStatus } = facts;
+    assertCount(planCount, 'planCount');
+    assertCount(summaryCount, 'summaryCount');
+    if (typeof complete !== 'boolean') {
+        throw new TypeError(`phaseStatusFromFacts: complete must be a boolean, got ${JSON.stringify(complete)}`);
+    }
+    const { verification } = owners();
+    if (verificationStatus !== null && verificationStatus !== undefined) {
+        // Called through a plain function type: a lazily-required owner's
+        // assertion signature cannot narrow here (TS2775), and needs not to.
+        const assertMember = verification.assertVerificationStatus;
+        assertMember(verificationStatus, 'phaseStatusFromFacts: verificationStatus');
+    }
+    if (complete)
+        return exports.PHASE_STATUS.COMPLETE;
+    if (planCount === 0)
+        return exports.PHASE_STATUS.NOT_STARTED;
+    if (summaryCount === 0)
+        return exports.PHASE_STATUS.PLANNED;
+    if (summaryCount < planCount)
+        return exports.PHASE_STATUS.IN_PROGRESS;
+    if (verificationStatus === verification.VERIFICATION_STATUS.HUMAN_NEEDED)
+        return exports.PHASE_STATUS.NEEDS_REVIEW;
+    return exports.PHASE_STATUS.EXECUTED;
+}
+const SCOPE_SEVERITY = Object.freeze({
+    complete: 0,
+    truncated: 1,
+    unscoped: 2,
+    unreadable: 3,
+});
+let _verification = null;
+let _planScan = null;
+function owners() {
+    /* eslint-disable @typescript-eslint/no-require-imports */
+    if (!_verification)
+        _verification = require('./verification.cjs');
+    if (!_planScan)
+        _planScan = require('./plan-scan.cjs');
+    /* eslint-enable @typescript-eslint/no-require-imports */
+    return { verification: _verification, planScan: _planScan };
+}
+/**
+ * What state is the phase in `phaseDir` in? Composes only ADR-3180's §7
+ * owners. `scope` is the worse of the plan scan's and the completion read's
+ * scopes, so a caller can tell "not started" from "could not look".
+ */
+function phaseStatus(phaseDir, deps = {}) {
+    const { verification, planScan } = owners();
+    const scan = planScan.scanPhasePlans(phaseDir);
+    const completion = verification.isPhaseComplete(phaseDir, {
+        convention: deps.convention,
+        fs: deps.fs,
+        phaseCleanCommitTimesMs: deps.phaseCleanCommitTimesMs,
+    });
+    const status = phaseStatusFromFacts({
+        planCount: scan.planCount,
+        summaryCount: scan.summaryCount,
+        complete: completion.value.complete,
+        verificationStatus: completion.value.verification.status,
+    });
+    const scope = (SCOPE_SEVERITY[completion.scope] ?? 0) > (SCOPE_SEVERITY[scan.scope] ?? 0)
+        ? completion.scope
+        : scan.scope;
+    return {
+        value: {
+            status,
+            planCount: scan.planCount,
+            summaryCount: scan.summaryCount,
+            verification: completion.value.verification,
+            ...(completion.value.statusError ? { statusError: completion.value.statusError } : {}),
+        },
+        scope,
+    };
+}
+// ─── Fold (#2408) ──────────────────────────────────────────────────────────
+/**
+ * Fold two statuses for directories that collide on one phase key (#2408):
+ * the further-along rung wins. Commutative, idempotent and associative, so
+ * `readdirSync` order cannot change the answer.
+ */
+function foldPhaseStatuses(a, b) {
+    assertPhaseStatus(a, 'foldPhaseStatuses');
+    assertPhaseStatus(b, 'foldPhaseStatuses');
+    return LADDER_RANK.get(a) >= LADDER_RANK.get(b) ? a : b;
+}
+const DISPLAY_LABEL = Object.freeze({
+    [exports.PHASE_STATUS.NOT_STARTED]: 'Not Started',
+    [exports.PHASE_STATUS.PLANNED]: 'Planned',
+    [exports.PHASE_STATUS.IN_PROGRESS]: 'In Progress',
+    [exports.PHASE_STATUS.EXECUTED]: 'Executed',
+    [exports.PHASE_STATUS.NEEDS_REVIEW]: 'Needs Review',
+    [exports.PHASE_STATUS.COMPLETE]: 'Complete',
+});
+/**
+ * The label `progress`, `stats`, `init plan-phase` and `gsd-health` show. The
+ * NOT_STARTED word is the caller's display choice (`progress` and `init` say
+ * `Pending`, `stats` and the health rule say `Not Started`).
+ */
+function toDisplayLabel(status, opts = {}) {
+    assertPhaseStatus(status, 'toDisplayLabel');
+    const pendingWord = opts.pendingWord ?? 'Not Started';
+    if (pendingWord !== 'Pending' && pendingWord !== 'Not Started') {
+        throw new TypeError(`toDisplayLabel: pendingWord must be 'Pending' or 'Not Started', got ${JSON.stringify(pendingWord)}`);
+    }
+    return status === exports.PHASE_STATUS.NOT_STARTED ? pendingWord : DISPLAY_LABEL[status];
+}
+/** `pending` means nothing is planned yet; every rung between that and COMPLETE is `in_progress`. */
+function toWireStatus(status) {
+    assertPhaseStatus(status, 'toWireStatus');
+    if (status === exports.PHASE_STATUS.COMPLETE)
+        return exports.WIRE_STATUS.COMPLETE;
+    if (status === exports.PHASE_STATUS.NOT_STARTED)
+        return exports.WIRE_STATUS.PENDING;
+    return exports.WIRE_STATUS.IN_PROGRESS;
+}
+/** The word a ROADMAP writer puts in the Status cell for this rung. */
+function toRoadmapStatusCell(status) {
+    assertPhaseStatus(status, 'toRoadmapStatusCell');
+    switch (status) {
+        case exports.PHASE_STATUS.COMPLETE: return exports.ROADMAP_STATUS_TOKEN.COMPLETE;
+        case exports.PHASE_STATUS.PLANNED: return exports.ROADMAP_STATUS_TOKEN.PLANNED;
+        case exports.PHASE_STATUS.NOT_STARTED: return exports.ROADMAP_STATUS_TOKEN.NOT_STARTED;
+        default: return exports.ROADMAP_STATUS_TOKEN.IN_PROGRESS;
+    }
+}
+/**
+ * `roadmap analyze` / `init manager`'s `disk_status`. Below NOT_STARTED the
+ * word records which pre-planning artifacts exist. (`no_directory` is the
+ * callers' own word for "no directory matched" — there is no phase to ask.)
+ */
+function toDiskStatus(status, artifacts) {
+    assertPhaseStatus(status, 'toDiskStatus');
+    switch (status) {
+        case exports.PHASE_STATUS.COMPLETE: return exports.DISK_STATUS.COMPLETE;
+        case exports.PHASE_STATUS.NEEDS_REVIEW:
+        case exports.PHASE_STATUS.EXECUTED: return exports.DISK_STATUS.EXECUTED;
+        case exports.PHASE_STATUS.IN_PROGRESS: return exports.DISK_STATUS.PARTIAL;
+        case exports.PHASE_STATUS.PLANNED: return exports.DISK_STATUS.PLANNED;
+        default:
+            if (artifacts.hasResearch)
+                return exports.DISK_STATUS.RESEARCHED;
+            if (artifacts.hasContext)
+                return exports.DISK_STATUS.DISCUSSED;
+            return exports.DISK_STATUS.EMPTY;
+    }
+}
+/** `init`'s `completion_status`: complete / executed / incomplete. */
+function toCompletionStatus(status) {
+    assertPhaseStatus(status, 'toCompletionStatus');
+    if (status === exports.PHASE_STATUS.COMPLETE)
+        return exports.COMPLETION_STATUS.COMPLETE;
+    if (status === exports.PHASE_STATUS.EXECUTED || status === exports.PHASE_STATUS.NEEDS_REVIEW)
+        return exports.COMPLETION_STATUS.EXECUTED;
+    return exports.COMPLETION_STATUS.INCOMPLETE;
+}
+/** `init progress`'s per-phase `status`. */
+function toProgressStatus(status, artifacts) {
+    assertPhaseStatus(status, 'toProgressStatus');
+    switch (status) {
+        case exports.PHASE_STATUS.COMPLETE: return exports.PROGRESS_STATUS.COMPLETE;
+        case exports.PHASE_STATUS.NEEDS_REVIEW:
+        case exports.PHASE_STATUS.EXECUTED: return exports.PROGRESS_STATUS.EXECUTED;
+        case exports.PHASE_STATUS.IN_PROGRESS:
+        case exports.PHASE_STATUS.PLANNED: return exports.PROGRESS_STATUS.IN_PROGRESS;
+        default: return artifacts.hasResearch ? exports.PROGRESS_STATUS.RESEARCHED : exports.PROGRESS_STATUS.PENDING;
+    }
+}
+// ─── ROADMAP Status cell reader ────────────────────────────────────────────
+// Leading token of a trimmed cell, case-insensitive, a whitespace run allowed
+// inside the two-word tokens, and `(?!\w)` so `Completed` / `Planning` are not
+// tokens. #4925 lets operator prose follow the token; that prose is ignored.
+const CELL_TOKEN_RE = /^(not\s+started|planned|in\s+progress|complete|deferred)(?!\w)/i;
+const TOKEN_BY_KEY = Object.freeze({
+    'not started': exports.ROADMAP_STATUS_TOKEN.NOT_STARTED,
+    planned: exports.ROADMAP_STATUS_TOKEN.PLANNED,
+    'in progress': exports.ROADMAP_STATUS_TOKEN.IN_PROGRESS,
+    complete: exports.ROADMAP_STATUS_TOKEN.COMPLETE,
+    deferred: exports.ROADMAP_STATUS_TOKEN.DEFERRED,
+});
+/**
+ * Read a Status cell's leading token. Returns the canonical token and the raw
+ * text it matched (writers compare `text` to decide whether a rewrite is a
+ * no-op), or null when the cell has no leading token. Never throws.
+ */
+function matchRoadmapStatusCell(cell) {
+    if (typeof cell !== 'string')
+        return null;
+    const m = CELL_TOKEN_RE.exec(cell.trim());
+    if (!m)
+        return null;
+    const key = m[1].toLowerCase().replace(/\s+/g, ' ');
+    return { token: TOKEN_BY_KEY[key], text: m[1] };
+}
+/**
+ * A Status cell as a wire value. `Deferred`, `Not started`, a cell with no
+ * leading token, and a non-string all read `pending` — an unrecognized cell
+ * never becomes a fourth wire value. Inverse of `toRoadmapStatusCell` under
+ * `toWireStatus` (ADR-5057 Phase 1 property).
+ */
+function parseRoadmapStatusCell(cell) {
+    const m = matchRoadmapStatusCell(cell);
+    if (m === null)
+        return exports.WIRE_STATUS.PENDING;
+    switch (m.token) {
+        case exports.ROADMAP_STATUS_TOKEN.COMPLETE: return exports.WIRE_STATUS.COMPLETE;
+        case exports.ROADMAP_STATUS_TOKEN.IN_PROGRESS:
+        case exports.ROADMAP_STATUS_TOKEN.PLANNED: return exports.WIRE_STATUS.IN_PROGRESS;
+        default: return exports.WIRE_STATUS.PENDING;
+    }
+}