@therocketcode/gsd-core 1.4.0

package/gsd-core/bin/lib/update-context.cjs

@@ -0,0 +1,218 @@
+"use strict";
+/**
+ * Update-context resolver (issue #498, candidate 3).
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/update-context.cjs
+ * collapsed to a TypeScript source of truth. Behaviour is preserved
+ * byte-for-behaviour from the prior hand-written .cjs; only types are added.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RUNTIME_DIRS = void 0;
+exports.inferPreferredRuntime = inferPreferredRuntime;
+exports.envRuntimeDirs = envRuntimeDirs;
+exports.resolveUpdateContext = resolveUpdateContext;
+exports.loadUpdateContext = loadUpdateContext;
+const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+// Runtime -> candidate relative dir. Order matters: it is the probe order, and
+// mirrors the RUNTIME_DIRS array the bash used (a runtime may have several
+// candidate dirs). Kept here, not derived from the installer's getDirName,
+// because update detection probes ALL historical dirs per runtime.
+exports.RUNTIME_DIRS = [
+    ['claude', '.claude'],
+    ['opencode', '.config/opencode'],
+    ['opencode', '.opencode'],
+    ['antigravity', '.gemini/antigravity-ide'],
+    ['antigravity', '.gemini/antigravity-cli'],
+    ['antigravity', '.gemini/antigravity'],
+    ['antigravity', '.agent'], // local Antigravity install dir (#503; bin/install.js getDirName('antigravity'))
+    ['gemini', '.gemini'],
+    ['kilo', '.config/kilo'],
+    ['kilo', '.kilo'],
+    ['codex', '.codex'],
+];
+const SEMVER_PREFIX = /^\d+\.\d+\.\d+/;
+function expandHome(p, home) {
+    if (!p)
+        return '';
+    return p.startsWith('~/') ? node_path_1.default.join(home, p.slice(2)) : p;
+}
+function versionFile(dir) { return node_path_1.default.join(dir, 'gsd-core', 'VERSION'); }
+function markerFile(dir) { return node_path_1.default.join(dir, 'gsd-core', 'workflows', 'update.md'); }
+// Detection: a dir "has GSD" if it carries a VERSION file or the update.md
+// workflow marker.
+function hasInstall(fs, dir) {
+    return fs.exists(versionFile(dir)) || fs.exists(markerFile(dir));
+}
+// Read VERSION at dir; return a trimmed semver string, or null if missing/invalid.
+function validVersionAt(fs, dir) {
+    const raw = fs.readFile(versionFile(dir));
+    if (raw == null)
+        return null;
+    const trimmed = String(raw).trim();
+    return SEMVER_PREFIX.test(trimmed) ? trimmed : null;
+}
+// A version is TRUSTED only when BOTH the VERSION file and the update.md marker
+// exist (and VERSION is valid semver).
+function trustedVersionAt(fs, dir) {
+    return dir && fs.exists(markerFile(dir)) ? validVersionAt(fs, dir) : null;
+}
+// Infer the preferred runtime from preferredConfigDir config files, then env.
+function inferPreferredRuntime({ fs, env, preferredConfigDir }) {
+    if (preferredConfigDir) {
+        if (fs.exists(node_path_1.default.join(preferredConfigDir, 'kilo.json')) ||
+            fs.exists(node_path_1.default.join(preferredConfigDir, 'kilo.jsonc')))
+            return 'kilo';
+        if (fs.exists(node_path_1.default.join(preferredConfigDir, 'opencode.json')) ||
+            fs.exists(node_path_1.default.join(preferredConfigDir, 'opencode.jsonc')))
+            return 'opencode';
+        if (fs.exists(node_path_1.default.join(preferredConfigDir, 'config.toml')))
+            return 'codex';
+    }
+    if (env['CODEX_HOME'])
+        return 'codex';
+    if (env['ANTIGRAVITY_CONFIG_DIR'])
+        return 'antigravity';
+    if (env['GEMINI_CONFIG_DIR'])
+        return 'gemini';
+    if (env['KILO_CONFIG_DIR'] || env['KILO_CONFIG'])
+        return 'kilo';
+    if (env['OPENCODE_CONFIG_DIR'] || env['OPENCODE_CONFIG'])
+        return 'opencode';
+    if (env['CLAUDE_CONFIG_DIR'])
+        return 'claude';
+    return 'claude';
+}
+// Absolute env-override candidates, mirroring the bash ENV_RUNTIME_DIRS block.
+function envRuntimeDirs({ env, home }) {
+    const out = [];
+    const ex = (v) => expandHome(v, home);
+    if (env['CLAUDE_CONFIG_DIR'])
+        out.push(['claude', ex(env['CLAUDE_CONFIG_DIR'])]);
+    if (env['ANTIGRAVITY_CONFIG_DIR'])
+        out.push(['antigravity', ex(env['ANTIGRAVITY_CONFIG_DIR'])]);
+    if (env['GEMINI_CONFIG_DIR'])
+        out.push(['gemini', ex(env['GEMINI_CONFIG_DIR'])]);
+    if (env['KILO_CONFIG_DIR'])
+        out.push(['kilo', ex(env['KILO_CONFIG_DIR'])]);
+    else if (env['KILO_CONFIG'])
+        out.push(['kilo', node_path_1.default.dirname(ex(env['KILO_CONFIG']))]);
+    else if (env['XDG_CONFIG_HOME'])
+        out.push(['kilo', node_path_1.default.join(ex(env['XDG_CONFIG_HOME']), 'kilo')]);
+    if (env['OPENCODE_CONFIG_DIR'])
+        out.push(['opencode', ex(env['OPENCODE_CONFIG_DIR'])]);
+    else if (env['OPENCODE_CONFIG'])
+        out.push(['opencode', node_path_1.default.dirname(ex(env['OPENCODE_CONFIG']))]);
+    else if (env['XDG_CONFIG_HOME'])
+        out.push(['opencode', node_path_1.default.join(ex(env['XDG_CONFIG_HOME']), 'opencode')]);
+    if (env['CODEX_HOME'])
+        out.push(['codex', ex(env['CODEX_HOME'])]);
+    return out;
+}
+// Stable reorder: entries whose runtime === preferred first, original order kept.
+function preferFirst(entries, preferred) {
+    const pref = entries.filter(([rt]) => rt === preferred);
+    const rest = entries.filter(([rt]) => rt !== preferred);
+    return [...pref, ...rest];
+}
+/**
+ * Pure resolver. Returns { installedVersion, scope, runtime, gsdDir }.
+ */
+function resolveUpdateContext({ home, cwd, env = {}, fs, preferredConfigDir = '', preferredRuntime = '', }) {
+    // Expand a leading `~/` before any probe.
+    preferredConfigDir = expandHome(preferredConfigDir, home);
+    const preferred = preferredRuntime || inferPreferredRuntime({ fs, env, preferredConfigDir });
+    // Fast path: a validated preferredConfigDir (custom --config-dir install).
+    if (preferredConfigDir && hasInstall(fs, preferredConfigDir)) {
+        const resolvedPref = node_path_1.default.resolve(preferredConfigDir);
+        let scope = 'GLOBAL';
+        for (const [, reldir] of exports.RUNTIME_DIRS) {
+            if (node_path_1.default.resolve(cwd, reldir) === resolvedPref) {
+                scope = 'LOCAL';
+                break;
+            }
+        }
+        return {
+            installedVersion: trustedVersionAt(fs, preferredConfigDir) ?? '0.0.0',
+            scope,
+            runtime: preferred,
+            gsdDir: preferredConfigDir,
+        };
+    }
+    const orderedEnv = preferFirst(envRuntimeDirs({ env, home }), preferred);
+    const orderedRuntime = preferFirst(exports.RUNTIME_DIRS, preferred);
+    // LOCAL probe (relative to cwd).
+    let localRuntime = '', localDir = '';
+    for (const [rt, reldir] of orderedRuntime) {
+        const cand = node_path_1.default.resolve(cwd, reldir);
+        if (hasInstall(fs, cand)) {
+            localRuntime = rt;
+            localDir = cand;
+            break;
+        }
+    }
+    // GLOBAL probe: absolute env candidates first, then $HOME-relative.
+    let globalRuntime = '', globalDir = '';
+    for (const [rt, absdir] of orderedEnv) {
+        if (hasInstall(fs, absdir)) {
+            globalRuntime = rt;
+            globalDir = node_path_1.default.resolve(absdir);
+            break;
+        }
+    }
+    if (!globalRuntime) {
+        for (const [rt, reldir] of orderedRuntime) {
+            const cand = node_path_1.default.resolve(home, reldir);
+            if (hasInstall(fs, cand)) {
+                globalRuntime = rt;
+                globalDir = cand;
+                break;
+            }
+        }
+    }
+    const localValid = trustedVersionAt(fs, localDir);
+    const isLocal = !!localValid && (!globalDir || localDir !== globalDir);
+    if (isLocal) {
+        return { installedVersion: localValid, scope: 'LOCAL', runtime: localRuntime, gsdDir: localDir };
+    }
+    const globalValid = trustedVersionAt(fs, globalDir);
+    if (globalValid) {
+        return { installedVersion: globalValid, scope: 'GLOBAL', runtime: globalRuntime, gsdDir: globalDir };
+    }
+    // A runtime dir was detected (VERSION or marker present) but is not a
+    // complete, valid install: keep scope/runtime/dir and report 0.0.0 so the
+    // caller re-installs.
+    if (localRuntime && (!globalDir || localDir !== globalDir)) {
+        return { installedVersion: '0.0.0', scope: 'LOCAL', runtime: localRuntime, gsdDir: localDir };
+    }
+    if (globalRuntime) {
+        return { installedVersion: '0.0.0', scope: 'GLOBAL', runtime: globalRuntime, gsdDir: globalDir };
+    }
+    return { installedVersion: '0.0.0', scope: 'UNKNOWN', runtime: 'claude', gsdDir: '' };
+}
+/**
+ * CLI wiring: resolve against the real filesystem.
+ */
+function loadUpdateContext(opts = {}) {
+    const fs = {
+        exists: (p) => node_fs_1.default.existsSync(p),
+        readFile: (p) => { try {
+            return node_fs_1.default.readFileSync(p, 'utf8');
+        }
+        catch {
+            return null;
+        } },
+    };
+    return resolveUpdateContext({
+        home: opts.home ?? node_os_1.default.homedir(),
+        cwd: opts.cwd ?? process.cwd(),
+        env: opts.env ?? process.env,
+        fs,
+        preferredConfigDir: opts.preferredConfigDir ?? '',
+        preferredRuntime: opts.preferredRuntime ?? '',
+    });
+}

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

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * Manifest-backed validate subcommand router.
+ * Keeps gsd-tools.cjs thin while preserving existing command semantics.
+ *
+ * Phase 6: validate.consistency, validate.health, validate.agents are
+ * dispatched via executeForCjs when the SDK is available. CJS fallback
+ * retained when:
+ * - GSD_WORKSTREAM is active (workstream-scoped requests fall through to CJS).
+ * - SDK is unavailable (build not present).
+ *
+ * CJS-only subcommands:
+ * - context: complex inline logic using classifyContextUtilization and
+ *   output formatting that has no direct SDK counterpart. Remains CJS-native.
+ *
+ * SDK-only (unsupported in CJS router): none.
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/validate-command-router.cjs
+ * collapsed to a TypeScript source of truth. Behaviour is preserved byte-for-behaviour
+ * from the prior hand-written .cjs; only types are added.
+ */
+const command_aliases_cjs_1 = require("./command-aliases.cjs");
+const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const cjsCommandRouterAdapter = require("./cjs-command-router-adapter.cjs");
+const { routeCjsCommandFamily } = cjsCommandRouterAdapter;
+const command_arg_projection_cjs_1 = require("./command-arg-projection.cjs");
+const context_utilization_cjs_1 = require("./context-utilization.cjs");
+// ─── Implementation ───────────────────────────────────────────────────────────
+function routeValidateCommand({ verify, args, cwd, raw, output: outputFn, error }) {
+    routeCjsCommandFamily({
+        args,
+        subcommands: command_aliases_cjs_1.VALIDATE_SUBCOMMANDS,
+        unsupported: {},
+        error,
+        unknownMessage: (_subcommand, available) => `Unknown validate subcommand. Available: ${available.join(', ')}`,
+        handlers: {
+            consistency: () => verify.cmdValidateConsistency(cwd, raw),
+            // Keep health on CJS for now so fix hints are rendered via runtime-slash
+            // helpers (codex expects $gsd-* command shape).
+            health: () => {
+                const repairFlag = args.includes('--repair');
+                const backfillFlag = args.includes('--backfill');
+                verify.cmdValidateHealth(cwd, { repair: repairFlag, backfill: backfillFlag }, raw);
+            },
+            agents: () => verify.cmdValidateAgents(cwd, raw),
+            // context: CJS-only — complex inline logic using classifyContextUtilization
+            // with custom output formatting that has no direct SDK counterpart.
+            context: () => {
+                const opts = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['tokens-used', 'context-window']);
+                if (opts['tokens-used'] === null) {
+                    error('--tokens-used <integer> is required for `validate context`');
+                    return;
+                }
+                if (opts['context-window'] === null) {
+                    error('--context-window <integer> is required for `validate context`');
+                    return;
+                }
+                const threadCmd = String((0, runtime_slash_cjs_1.formatGsdSlash)('thread', (0, runtime_slash_cjs_1.resolveRuntime)(cwd)));
+                const RECOMMENDATIONS = {
+                    [context_utilization_cjs_1.STATES.HEALTHY]: null,
+                    [context_utilization_cjs_1.STATES.WARNING]: `Context is approaching the fracture zone — consider ${threadCmd} to continue in a fresh window.`,
+                    [context_utilization_cjs_1.STATES.CRITICAL]: `Reasoning quality may degrade past 70% utilization (fracture point). Run ${threadCmd} now to preserve output quality.`,
+                };
+                let classified;
+                try {
+                    classified = (0, context_utilization_cjs_1.classifyContextUtilization)(Number(opts['tokens-used']), Number(opts['context-window']));
+                }
+                catch (e) {
+                    const msg = e.message;
+                    const flag = /tokensUsed/.test(msg) ? '--tokens-used' : '--context-window';
+                    error(`${flag} must be a non-negative integer (window > 0), got the values supplied`);
+                    return;
+                }
+                const result = { ...classified, recommendation: RECOMMENDATIONS[classified.state] };
+                if (args.includes('--json')) {
+                    outputFn(result, raw);
+                }
+                else {
+                    const lines = [`Context utilization: ${result.percent}% (${result.state})`];
+                    if (result.recommendation)
+                        lines.push(result.recommendation);
+                    outputFn(result, true, lines.join('\n'));
+                }
+            },
+        },
+    });
+}
+module.exports = {
+    routeValidateCommand,
+};

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

@@ -0,0 +1,112 @@
+"use strict";
+/**
+ * Validate Helpers — pure computation helpers and regex constants extracted from
+ * sdk/src/query/validate.ts (ADR-457 build-at-publish: the hand-written
+ * bin/lib/validate.cjs collapsed to a TypeScript source of truth). Behaviour is
+ * preserved byte-for-behaviour from the prior hand-written .cjs; only types are
+ * added.
+ *
+ * No I/O. No async. No filesystem operations.
+ *
+ * Issue #6 drift items (three helpers):
+ *   1. phaseVariants() — replaces parseInt-based padded/unpadded check in verify.cjs
+ *      Check 8 (W006 disk-existence and W007 roadmap-membership checks).
+ *   2. buildRoadmapPhaseVariants() — replaces raw roadmapPhases set in W007 loop.
+ *   3. buildNotStartedPhaseVariants() — replaces raw+zero-padded notStartedPhases
+ *      in W006 skip logic.
+ *
+ * Issue #26 drift items (four constants/helpers):
+ *   4. phaseDirNameRe — W005 phase directory naming regex (was inline in verify.cjs Check 6).
+ *   5. PHASE_TOKEN_FROM_DIR_RE — extracts phase token from dir name (was inline in
+ *      verify.cjs forEachArchivedPhaseToken / collectDiskPhases).
+ *   6. MILESTONE_ARCHIVE_DIR_RE — identifies milestone archive directories (was inline).
+ *   7. canonicalPlanStem() — I001 PLAN/SUMMARY stem canonicalization (was inline in Check 7).
+ *
+ * I/O adapter pattern (ADR-3524 §4): pure transforms extracted from the SDK.
+ *
+ * References:
+ *   - ADR-3524 (docs/adr/3524-cjs-sdk-hard-seam.md)
+ *   - Issue #6 (TheRocketCodeMX/gsd-core)
+ *   - Issue #26 (TheRocketCodeMX/gsd-core)
+ *   - PR #154 (issue #4) — generator pattern precedent
+ *   - PR #156 (issue #6) — validate.ts generator that #26 extends
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MILESTONE_ARCHIVE_DIR_RE = exports.PHASE_TOKEN_FROM_DIR_RE = exports.phaseDirNameRe = void 0;
+exports.canonicalPlanStem = canonicalPlanStem;
+exports.phaseVariants = phaseVariants;
+exports.buildRoadmapPhaseVariants = buildRoadmapPhaseVariants;
+exports.buildNotStartedPhaseVariants = buildNotStartedPhaseVariants;
+// ── Issue #26: regex constants (W005, W006-archived) ────────────────────────
+// Matches legacy numeric dirs (01-setup), milestone-prefixed dirs (02-01-setup),
+// deep dirs (02-04-01-deep), and project-code-prefixed variants (GSD-02-01-setup).
+exports.phaseDirNameRe = /^(?:[A-Z]{1,6}-)?\d{2,}(?:-\d+)*(?:\.\d+)*-[\w-]+$/i;
+// Extracts the full phase token from a directory name, including milestone-prefixed
+// multi-segment tokens like "02-01" from "02-01-setup" or "GSD-02-01-setup".
+// Greedily captures all leading all-digit segments before the first letter-start segment.
+exports.PHASE_TOKEN_FROM_DIR_RE = /^(?:[A-Z]{1,6}-)?(\d+(?:-\d+)*[A-Z]?(?:\.\d+)*)(?:-[a-z]|$)/i;
+exports.MILESTONE_ARCHIVE_DIR_RE = /^v\d+.*-phases$/i;
+// ── Issue #26: I001 canonicalization ────────────────────────────────────────
+function canonicalPlanStem(stem) {
+    const m = stem.match(/^(\d+[A-Z]?(?:\.\d+)*-\d+)/i);
+    return m ? m[1] : stem;
+}
+// ── Issue #6: phase variant helpers (W006/W007) ──────────────────────────────
+function phaseVariants(phase) {
+    const variants = new Set([phase]);
+    const dotIdx = phase.indexOf('.');
+    const head = dotIdx === -1 ? phase : phase.slice(0, dotIdx);
+    const tail = dotIdx === -1 ? '' : phase.slice(dotIdx);
+    // Milestone-prefixed IDs: M-NN or M-N-N. Add padding-normalized variant.
+    // e.g. "2-01" → also "02-01"; "02-01" → also "2-01"
+    const milestoneHeadMatch = head.match(/^(\d+)((?:-\d+)+)([A-Z]?)$/i);
+    if (milestoneHeadMatch) {
+        const major = milestoneHeadMatch[1];
+        const subSegs = milestoneHeadMatch[2]; // e.g. "-01" or "-04-01"
+        const letter = milestoneHeadMatch[3] || '';
+        const paddedMajor = major.padStart(2, '0');
+        const unpaddedMajor = String(parseInt(major, 10));
+        // Pad/unpad sub-segments individually
+        const paddedSubs = subSegs.slice(1).split('-').map(s => s.padStart(2, '0')).join('-');
+        const unpaddedSubs = subSegs.slice(1).split('-').map(s => String(parseInt(s, 10))).join('-');
+        variants.add(`${paddedMajor}-${paddedSubs}${letter}${tail}`);
+        variants.add(`${unpaddedMajor}-${unpaddedSubs}${letter}${tail}`);
+        variants.add(`${unpaddedMajor}-${paddedSubs}${letter}${tail}`);
+        variants.add(`${paddedMajor}-${unpaddedSubs}${letter}${tail}`);
+        return variants;
+    }
+    // Plain numeric/decimal IDs: "1", "01", "12A", "12.1"
+    const headMatch = head.match(/^(\d+)([A-Z]?)$/i);
+    if (!headMatch)
+        return variants;
+    const numericHead = headMatch[1];
+    const letterSuffix = headMatch[2] || '';
+    variants.add(`${String(parseInt(numericHead, 10))}${letterSuffix}${tail}`);
+    variants.add(`${numericHead.padStart(2, '0')}${letterSuffix}${tail}`);
+    return variants;
+}
+function buildRoadmapPhaseVariants(roadmapContent) {
+    const roadmapPhases = new Set();
+    const roadmapPhaseVariants = new Set();
+    // Matches both legacy numeric (Phase 1:), decimal (Phase 2.1:), milestone-prefixed (Phase 2-01:),
+    // and bracket-prefixed (### [GSD] Phase 2-01:) headings.
+    const phasePattern = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+([\w][\w.-]*)\s*:/gi;
+    let m;
+    while ((m = phasePattern.exec(roadmapContent)) !== null) {
+        roadmapPhases.add(m[1]);
+        for (const variant of phaseVariants(m[1]))
+            roadmapPhaseVariants.add(variant);
+    }
+    return { roadmapPhases, roadmapPhaseVariants };
+}
+function buildNotStartedPhaseVariants(roadmapContent) {
+    const notStartedPhases = new Set();
+    // Also matches milestone-prefixed and bracket-prefixed checklist items.
+    const uncheckedPattern = /-\s*\[\s\]\s*\*{0,2}Phase\s+([\w][\w.-]*)[:\s*]/gi;
+    let um;
+    while ((um = uncheckedPattern.exec(roadmapContent)) !== null) {
+        for (const variant of phaseVariants(um[1]))
+            notStartedPhases.add(variant);
+    }
+    return notStartedPhases;
+}

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

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * Verification-status subcommand router.
+ * Routes `verification.status <phaseDir>` to verification.cmdVerificationStatus.
+ *
+ * Note: `verification` (reads verifier-emitted status) is distinct from `verify`
+ * (runs verification checks like plan-structure/artifacts). Keep them separate.
+ *
+ * ADR-457 build-at-publish: source in src/verification-command-router.cts,
+ * compiled to gsd-core/bin/lib/verification-command-router.cjs (gitignored).
+ */
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const cjsCommandRouterAdapter = require("./cjs-command-router-adapter.cjs");
+const { routeCjsCommandFamily } = cjsCommandRouterAdapter;
+// ─── Implementation ───────────────────────────────────────────────────────────
+const VERIFICATION_SUBCOMMANDS = ['status'];
+function routeVerificationCommand({ verification, args, cwd, raw, error, }) {
+    routeCjsCommandFamily({
+        args,
+        subcommands: VERIFICATION_SUBCOMMANDS,
+        unsupported: {},
+        error,
+        unknownMessage: (_subcommand, available) => `Unknown verification subcommand. Available: ${available.join(', ')}`,
+        handlers: {
+            status: () => verification.cmdVerificationStatus(cwd, args[2], raw),
+        },
+    });
+}
+module.exports = {
+    routeVerificationCommand,
+};

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

@@ -0,0 +1,193 @@
+"use strict";
+/**
+ * Verification Status — single queryable home for verification-status routing.
+ *
+ * Issue #651: consolidate the pass/gaps_found/human_needed routing that was
+ * previously scattered across ship.md and execute-phase.md into a single
+ * tested module. Both workflow files will later consume this module's routing
+ * table as the single source of truth.
+ *
+ * ADR-457 build-at-publish: source in src/verification.cts, compiled to
+ * gsd-core/bin/lib/verification.cjs (gitignored).
+ *
+ * DEFECT.FRONTMATTER-SCALAR-BROAD-GREP fix: status extraction is scoped to
+ * the leading YAML frontmatter block only. A `status:` line in the body (e.g.
+ * inside a fenced code block) is ignored — this is the exact failure mode that
+ * issue #586 / PR #650 identified. The shared extractFrontmatter parser anchors
+ * its regex at byte 0 of the document, which provides this guarantee.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- core.cjs is an export= CommonJS module
+const core = require("./core.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- frontmatter.cjs is an export= CommonJS module
+const frontmatterMod = require("./frontmatter.cjs");
+const { output, extractPhaseToken } = core;
+const { extractFrontmatter } = frontmatterMod;
+// ─── Constants ────────────────────────────────────────────────────────────────
+/** The set of status values that the gsd-verifier agent emits. */
+const VERIFIER_STATUSES = ['passed', 'gaps_found', 'human_needed'];
+/**
+ * Canonical routing table for verification statuses.
+ *
+ * This is the single source of truth — ship.md and execute-phase.md will
+ * later import from here instead of embedding their own message strings.
+ *
+ * INTERNAL SENTINELS: 'missing' and 'unknown' are operational states constructed
+ * internally — the verifier (gsd-verifier.md) never emits them. The verifier only
+ * emits values in VERIFIER_STATUSES (passed|gaps_found|human_needed). The guard in
+ * readVerificationStatus excludes 'missing' and 'unknown' from raw-status table
+ * lookup so they can only be reached via internal construction paths.
+ *
+ * For 'gaps_found', next_command is built at call time in readVerificationStatus
+ * by substituting the phase number — it is NOT stored as a function in the table.
+ */
+const VERIFICATION_ROUTING_TABLE = {
+    passed: {
+        status: 'passed',
+        next_action: 'Verification passed — continue.',
+        next_command: '',
+    },
+    gaps_found: {
+        status: 'gaps_found',
+        next_action: 'Gaps found. Plan the fixes, then re-run execute-phase before shipping.',
+        // next_command is computed at call time; this entry is never returned directly.
+        next_command: '',
+    },
+    human_needed: {
+        status: 'human_needed',
+        next_action: "Human verification required. Complete the manual tests in the phase's *-UAT.md, then re-run the verify step until status is passed.",
+        next_command: '',
+    },
+    // INTERNAL SENTINEL: constructed when no *-VERIFICATION.md file exists or when
+    // the file has no parseable frontmatter status. Never emitted by the verifier.
+    missing: {
+        status: 'missing',
+        next_action: 'No verification report found — the verify step never completed. Re-run execute-phase.',
+        next_command: '/gsd:execute-phase',
+    },
+    // INTERNAL SENTINEL: constructed when the file has a status value not in
+    // VERIFIER_STATUSES. Never emitted by the verifier.
+    unknown: {
+        status: 'unknown',
+        next_action: '', // filled in dynamically with the raw value
+        next_command: '/gsd:execute-phase',
+    },
+};
+/**
+ * Build a 'missing' result from the routing table.
+ * Used for two early-return paths: no *-VERIFICATION.md file found, and
+ * file present but no parseable frontmatter status.
+ */
+function missingResult() {
+    const route = VERIFICATION_ROUTING_TABLE['missing'];
+    return {
+        status: route.status,
+        next_action: route.next_action,
+        next_command: route.next_command,
+    };
+}
+/**
+ * Read the verification status from the first `*-VERIFICATION.md` file in
+ * phaseDir and return the routing result.
+ *
+ * Behavior:
+ * 1. Find the first file matching `*-VERIFICATION.md` (sorted, take first).
+ *    If none → status 'missing'.
+ * 2. Extract `status` from FRONTMATTER ONLY via the shared extractFrontmatter
+ *    parser (DEFECT.FRONTMATTER-SCALAR-BROAD-GREP fix — parser anchors at byte 0).
+ *    If no frontmatter block or no `status` key → status 'missing'.
+ * 3. Map to routing table. Unknown non-empty value → status 'unknown'.
+ *
+ * @param phaseDir - Absolute path to the phase directory.
+ * @param opts     - Options. `opts.fs` allows test injection (defaults to node:fs).
+ */
+function readVerificationStatus(phaseDir, opts = {}) {
+    const fsImpl = opts.fs ?? node_fs_1.default;
+    // Phase token for the gaps_found command
+    const baseName = node_path_1.default.basename(phaseDir);
+    const phaseToken = extractPhaseToken(baseName);
+    const phaseNumber = phaseToken.length > 0 ? phaseToken : baseName;
+    // 1. Find *-VERIFICATION.md
+    let verificationFile = null;
+    try {
+        const entries = fsImpl.readdirSync(phaseDir);
+        const candidates = entries.filter((f) => f.endsWith('-VERIFICATION.md')).sort();
+        verificationFile = candidates.length > 0 ? candidates[0] : null;
+    }
+    catch {
+        // Directory unreadable → treat as missing
+        verificationFile = null;
+    }
+    if (!verificationFile) {
+        return missingResult();
+    }
+    // 2. Read and parse frontmatter using the shared parser.
+    // extractFrontmatter anchors at byte 0, so body `status:` lines are ignored.
+    const filePath = node_path_1.default.join(phaseDir, verificationFile);
+    let rawStatus = null;
+    try {
+        const content = fsImpl.readFileSync(filePath, 'utf-8');
+        const fm = extractFrontmatter(content);
+        const statusVal = fm['status'];
+        // status is always a scalar string in a well-formed VERIFICATION.md frontmatter;
+        // only accept string values — arrays and objects are not valid status values.
+        if (typeof statusVal === 'string') {
+            const trimmed = statusVal.trim();
+            rawStatus = trimmed.length > 0 ? trimmed : null;
+        }
+    }
+    catch {
+        rawStatus = null;
+    }
+    if (!rawStatus) {
+        return missingResult();
+    }
+    // 3. Route — exclude internal sentinels from raw-file lookup (they are
+    // constructed internally above, never written by the verifier).
+    if (rawStatus in VERIFICATION_ROUTING_TABLE && rawStatus !== 'missing' && rawStatus !== 'unknown') {
+        const entry = VERIFICATION_ROUTING_TABLE[rawStatus];
+        // gaps_found: build the phase-specific command here rather than in the table.
+        const next_command = rawStatus === 'gaps_found'
+            ? `/gsd:plan-phase ${phaseNumber} --gaps`
+            : entry.next_command;
+        return {
+            status: entry.status,
+            next_action: entry.next_action,
+            next_command,
+        };
+    }
+    // Unknown value
+    const unknownRoute = VERIFICATION_ROUTING_TABLE['unknown'];
+    return {
+        status: unknownRoute.status,
+        next_action: `Unexpected verification status '${rawStatus}'. Re-run execute-phase verification.`,
+        next_command: unknownRoute.next_command,
+    };
+}
+/**
+ * CLI command handler: resolve phaseDir against cwd, call readVerificationStatus,
+ * emit via core.output().
+ *
+ * @param cwd         - Current working directory (used to resolve phaseDirArg).
+ * @param phaseDirArg - Phase directory path (absolute or relative to cwd).
+ * @param raw         - Whether to emit raw (non-JSON) output.
+ */
+function cmdVerificationStatus(cwd, phaseDirArg, raw) {
+    if (!phaseDirArg) {
+        core.error('phase directory required for verification.status');
+        return;
+    }
+    const phaseDir = node_path_1.default.resolve(cwd, phaseDirArg);
+    const result = readVerificationStatus(phaseDir);
+    output(result, raw);
+}
+module.exports = {
+    VERIFIER_STATUSES,
+    VERIFICATION_ROUTING_TABLE,
+    readVerificationStatus,
+    cmdVerificationStatus,
+};