@opengsd/gsd-core 1.3.0 → 1.4.0-rc.1

package/gsd-core/bin/lib/research-store.cjs

@@ -0,0 +1,167 @@
+"use strict";
+/**
+ * Research Store Module
+ *
+ * Provides deterministic cache key generation, TTL policy, path resolution,
+ * and JSON-backed put/get operations for research entries.
+ *
+ * ADR-457 build-at-publish: authored as TypeScript .cts → emits .cjs via tsc.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const DAY_MS = 86_400_000;
+// ---------------------------------------------------------------------------
+// researchKey
+// ---------------------------------------------------------------------------
+function normalize(x) {
+    if (x === null || x === undefined)
+        return '';
+    if (typeof x === 'object')
+        return JSON.stringify(x).trim().toLowerCase();
+    // After excluding null, undefined, and object, x can only be a primitive —
+    // cast through number | string | boolean to avoid no-base-to-string on unknown.
+    return `${x}`.trim().toLowerCase();
+}
+function researchKey(input) {
+    const parts = {
+        ecosystem: normalize(input.ecosystem),
+        library: normalize(input.library),
+        version: normalize(input.version),
+        query: normalize(input.query),
+        kind: normalize(input.kind),
+    };
+    const serialized = JSON.stringify(parts);
+    return node_crypto_1.default.createHash('sha256').update(serialized).digest('hex');
+}
+// ---------------------------------------------------------------------------
+// ttlForSource
+// ---------------------------------------------------------------------------
+function ttlForSource(source, confidence) {
+    if (source === 'curated' && confidence === 'HIGH')
+        return 30 * DAY_MS;
+    if (source === 'curated' && confidence === 'MEDIUM')
+        return 7 * DAY_MS;
+    return DAY_MS;
+}
+// ---------------------------------------------------------------------------
+// tierForSource / resolveStorePath
+// ---------------------------------------------------------------------------
+const CURATED_SOURCES = new Set(['curated']);
+function tierForSource(source) {
+    return CURATED_SOURCES.has(source) ? 'user' : 'project';
+}
+function resolveStorePath(cwd, source, { homeDir = node_os_1.default.homedir() } = {}) {
+    if (tierForSource(source) === 'user') {
+        return node_path_1.default.join(homeDir, '.gsd', 'research-cache');
+    }
+    return node_path_1.default.join(cwd, '.planning', 'research', '.cache');
+}
+// ---------------------------------------------------------------------------
+// isValidResearchKey
+// ---------------------------------------------------------------------------
+/**
+ * Returns true iff key is a valid 64-character lowercase hexadecimal SHA-256
+ * string (the exact shape produced by researchKey).  Any other shape —
+ * including path-traversal sequences — is rejected.
+ */
+function isValidResearchKey(key) {
+    return typeof key === 'string' && /^[0-9a-f]{64}$/.test(key);
+}
+// ---------------------------------------------------------------------------
+// putResearch
+// ---------------------------------------------------------------------------
+function putResearch(cwd, key, payload, { clock = Date, homeDir = node_os_1.default.homedir() } = {}) {
+    // Defense-in-depth: reject any key that is not a 64-char sha256 hex string.
+    if (!isValidResearchKey(key)) {
+        throw new Error('invalid research key');
+    }
+    const { content, source, provider, confidence, kind, version } = payload;
+    let ttl = ttlForSource(source, confidence);
+    // Cap TTL when version is blank/missing — a versionless curated entry must not
+    // get the long 30-day window since we can't know if it's still current.
+    if (!version) {
+        ttl = Math.min(ttl, DAY_MS);
+    }
+    const fetched_at = new Date(clock.now()).toISOString();
+    const entry = { content, source, provider, confidence, fetched_at, ttl, kind };
+    const dir = resolveStorePath(cwd, source, { homeDir });
+    // Belt-and-suspenders: ensure the resolved file path stays inside the store dir.
+    const resolvedDir = node_path_1.default.resolve(dir);
+    const filePath = node_path_1.default.join(dir, `${key}.json`);
+    const resolvedFile = node_path_1.default.resolve(filePath);
+    if (!resolvedFile.startsWith(resolvedDir + node_path_1.default.sep)) {
+        throw new Error('invalid research key');
+    }
+    node_fs_1.default.mkdirSync(dir, { recursive: true });
+    (0, shell_command_projection_cjs_1.platformWriteSync)(filePath, JSON.stringify(entry));
+    return entry;
+}
+// ---------------------------------------------------------------------------
+// getResearch
+// ---------------------------------------------------------------------------
+function getResearch(cwd, key, { clock = Date, homeDir = node_os_1.default.homedir() } = {}) {
+    // Defense-in-depth: reject any key that is not a 64-char sha256 hex string.
+    if (!isValidResearchKey(key)) {
+        return { hit: false, stale: false, entry: null };
+    }
+    try {
+        // Search both physical tiers: user (curated) and project (web/etc.)
+        const userDir = node_path_1.default.join(homeDir, '.gsd', 'research-cache');
+        const projectDir = node_path_1.default.join(cwd, '.planning', 'research', '.cache');
+        const tierDirs = [userDir, projectDir];
+        const candidates = [];
+        for (const dir of tierDirs) {
+            const resolvedDir = node_path_1.default.resolve(dir);
+            const filePath = node_path_1.default.join(dir, `${key}.json`);
+            // Belt-and-suspenders: ensure path stays inside tier dir
+            if (!node_path_1.default.resolve(filePath).startsWith(resolvedDir + node_path_1.default.sep))
+                continue;
+            if (!node_fs_1.default.existsSync(filePath))
+                continue;
+            let entry;
+            try {
+                entry = JSON.parse(node_fs_1.default.readFileSync(filePath, 'utf8'));
+            }
+            catch {
+                // Corrupt file in this tier — skip it
+                continue;
+            }
+            // Finding 3: validate entry metadata shape before accepting as a candidate.
+            // An entry with missing/invalid fetched_at or ttl must be treated as a miss.
+            const parsedFetchedAt = Date.parse(entry.fetched_at);
+            if (!Number.isFinite(parsedFetchedAt))
+                continue;
+            if (typeof entry.ttl !== 'number' ||
+                !Number.isFinite(entry.ttl) ||
+                entry.ttl <= 0)
+                continue;
+            const age = clock.now() - parsedFetchedAt;
+            const stale = age > entry.ttl;
+            candidates.push({ entry, stale, age });
+        }
+        if (candidates.length === 0) {
+            return { hit: false, stale: false, entry: null };
+        }
+        // Prefer: non-stale over stale; among same-staleness, lowest age (most recent)
+        candidates.sort((a, b) => {
+            if (a.stale !== b.stale)
+                return a.stale ? 1 : -1; // non-stale first
+            return a.age - b.age; // lower age (more recent) first
+        });
+        const best = candidates[0];
+        return { hit: true, stale: best.stale, entry: best.entry };
+    }
+    catch {
+        return { hit: false, stale: false, entry: null };
+    }
+}
+module.exports = { isValidResearchKey, researchKey, ttlForSource, tierForSource, resolveStorePath, putResearch, getResearch };

package/gsd-core/bin/lib/roadmap-upgrade.cjs

@@ -25,8 +25,6 @@ const MIGRATED_PHASE_HEADING_RE = /^#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+\d+-\d{2}
 // Matches milestone section headings: ## v1.0, ## Roadmap v2.0, ## ✅ v1.0, ## [GSD] v1.0, etc.
 // The optional bracket-token prefix (e.g., [GSD]) must be tested before the emoji group.
 const MILESTONE_HEADING_RE = /^##\s+(?:\[[^\]]+\]\s+|Roadmap\s+|[✅🚧]\s*)?v(\d+)\.(\d+)(?:\s|:)/iu;
-// Matches checklist phase references: - [ ] **Phase N:** or - [x] **Phase N:**  (also decimal)
-const CHECKLIST_PHASE_RE = /^(\s*-\s*\[[ x]\]\s*\*{0,2})Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:/gi;
 // ─── Pure computation helpers ─────────────────────────────────────────────────
 /**
  * Parse the ROADMAP.md content and build a list of phase entries with their
@@ -126,19 +124,6 @@ function buildNewDirName(oldDirName, newId, projectCode) {
     const newBase = slug ? `${paddedMilestone}-${subStr}-${slug}` : `${paddedMilestone}-${subStr}`;
     return projectCode ? `${projectCode}-${newBase}` : newBase;
 }
-/**
- * Read project_code from config.json if present.
- */
-function readProjectCode(configPath) {
-    try {
-        const raw = node_fs_1.default.readFileSync(configPath, 'utf8');
-        const parsed = JSON.parse(raw);
-        return typeof parsed['project_code'] === 'string' ? parsed['project_code'] : null;
-    }
-    catch {
-        return null;
-    }
-}
 // ─── computeMigrationPlan ─────────────────────────────────────────────────────
 /**
  * Compute a migration plan without touching the filesystem.
@@ -390,7 +375,7 @@ function applyMigration(cwd, plan, options = {}) {
     // ── Real run: verify clean working tree ───────────────────────────────────
     let gitStatus;
     try {
-        gitStatus = (0, node_child_process_1.execSync)('git status --porcelain', { cwd, encoding: 'utf8' });
+        gitStatus = (0, node_child_process_1.execSync)('git status --porcelain', { cwd, encoding: 'utf8', windowsHide: true });
     }
     catch (err) {
         throw new Error(`git status failed: ${err.message}`);
@@ -401,7 +386,7 @@ function applyMigration(cwd, plan, options = {}) {
     // Capture HEAD sha for rollback
     let headSha;
     try {
-        headSha = (0, node_child_process_1.execSync)('git rev-parse HEAD', { cwd, encoding: 'utf8' }).trim();
+        headSha = (0, node_child_process_1.execSync)('git rev-parse HEAD', { cwd, encoding: 'utf8', windowsHide: true }).trim();
     }
     catch (err) {
         throw new Error(`git rev-parse HEAD failed: ${err.message}`);
@@ -475,8 +460,8 @@ function applyMigration(cwd, plan, options = {}) {
     catch (err) {
         // Rollback via git reset --hard + git clean
         try {
-            (0, node_child_process_1.execSync)(`git reset --hard ${headSha}`, { cwd, stdio: 'pipe' });
-            (0, node_child_process_1.execSync)('git clean -fd .planning/phases/', { cwd, stdio: 'pipe' });
+            (0, node_child_process_1.execSync)(`git reset --hard ${headSha}`, { cwd, stdio: 'pipe', windowsHide: true });
+            (0, node_child_process_1.execSync)('git clean -fd .planning/phases/', { cwd, stdio: 'pipe', windowsHide: true });
         }
         catch {
             // Swallow rollback errors — surface original error

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

@@ -24,6 +24,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MARKDOWN_LINK_PATTERNS = exports.INJECTION_PATTERNS = void 0;
 exports.validatePath = validatePath;
+exports.loadTrustedGlobalRoots = loadTrustedGlobalRoots;
 exports.requireSafePath = requireSafePath;
 exports.scanForInjection = scanForInjection;
 exports.sanitizeForPrompt = sanitizeForPrompt;
@@ -35,6 +36,7 @@ exports.validateFieldName = validateFieldName;
 exports.validatePromptStructure = validatePromptStructure;
 exports.scanEntropyAnomalies = scanEntropyAnomalies;
 const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
 // ─── Path Traversal Prevention ──────────────────────────────────────────────
 /**
@@ -92,6 +94,77 @@ function validatePath(filePath, baseDir, opts = {}) {
     }
     return { safe: true, resolved: resolvedPath };
 }
+/**
+ * Load the opt-in trusted global roots allowlist from config.
+ *
+ * Reads `config.agent_skills_security.trusted_global_roots` (an array of
+ * path strings). Each entry is canonicalized via realpathSync: non-strings
+ * are dropped, leading `~/` is expanded to `os.homedir()`, entries that are
+ * not absolute after expansion are dropped (project-relative paths are
+ * rejected as a security boundary), and entries that do not exist on disk are
+ * dropped (a non-existent root is not trustworthy). The canonical realpath is
+ * used for all subsequent checks and as the stored value — this closes the
+ * case-insensitive bypass on macOS APFS (`/users/alice` vs `/Users/alice`)
+ * and ensures trust doesn't drift across re-invocations if a root is
+ * re-created at a different target. Results are de-duplicated by canonical path.
+ */
+function loadTrustedGlobalRoots(config) {
+    const roots = config?.['agent_skills_security'];
+    const raw = roots?.['trusted_global_roots'];
+    if (!Array.isArray(raw))
+        return [];
+    // Compute canonical homedir once for case-insensitive-safe comparison.
+    let realHome;
+    try {
+        realHome = node_fs_1.default.realpathSync(node_os_1.default.homedir());
+    }
+    catch {
+        realHome = node_os_1.default.homedir();
+    }
+    const seen = new Set();
+    const result = [];
+    for (const entry of raw) {
+        if (typeof entry !== 'string')
+            continue;
+        let expanded;
+        if (entry === '~') {
+            expanded = node_os_1.default.homedir();
+        }
+        else if (entry.startsWith('~/')) {
+            expanded = node_path_1.default.join(node_os_1.default.homedir(), entry.slice(2));
+        }
+        else {
+            expanded = entry;
+        }
+        if (!node_path_1.default.isAbsolute(expanded))
+            continue; // reject project-relative
+        // Canonicalize: resolve symlinks and normalise case. If the path doesn't
+        // exist or can't be read, skip it — a non-existent root is not trustworthy.
+        let real;
+        try {
+            real = node_fs_1.default.realpathSync(expanded);
+        }
+        catch {
+            continue; // non-existent or unreadable — skip
+        }
+        // Reject dangerously broad roots: filesystem root (e.g. '/' or 'C:\' or UNC '\\server\share').
+        // Normalize both sides by stripping trailing path separators before comparing so that
+        // Windows UNC shares (where path.parse().root includes a trailing separator) are caught.
+        const stripTrailingSep = (p) => p.replace(/[\\/]+$/, '');
+        if (stripTrailingSep(node_path_1.default.parse(real).root) === stripTrailingSep(real))
+            continue;
+        // Reject homedir itself (canonical compare closes case-insensitive bypass).
+        // Apply stripTrailingSep for robustness on platforms where realpathSync may
+        // or may not include a trailing separator on the homedir path.
+        if (stripTrailingSep(real) === stripTrailingSep(realHome))
+            continue;
+        if (seen.has(real))
+            continue;
+        seen.add(real);
+        result.push(real);
+    }
+    return result;
+}
 /**
  * Validate a file path and throw on traversal attempt.
  * Convenience wrapper around validatePath for use in CLI commands.

package/gsd-core/bin/lib/shell-command-projection.cjs

@@ -381,6 +381,7 @@ function execGit(args, opts = {}) {
         encoding: 'utf-8',
         stdio: 'pipe',
         timeout: opts.timeout ?? 10_000,
+        windowsHide: true,
     });
     return _spawnResult(result, 'git');
 }
@@ -391,6 +392,7 @@ function execNpm(args, opts = {}) {
         encoding: 'utf-8',
         stdio: ['ignore', 'pipe', 'pipe'],
         timeout: opts.timeout ?? 15_000,
+        windowsHide: true,
     });
     return _spawnResult(result, 'npm');
 }
@@ -401,6 +403,7 @@ function execTool(program, args, opts = {}) {
         encoding: 'utf-8',
         stdio: 'pipe',
         timeout: opts.timeout ?? 30_000,
+        windowsHide: true,
     });
     return _spawnResult(result, program);
 }

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

@@ -90,7 +90,7 @@ function buildRoadmapPhaseVariants(roadmapContent) {
     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.-]*(?:-[\w.-]+)*)\s*:/gi;
+    const phasePattern = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+([\w][\w.-]*)\s*:/gi;
     let m;
     while ((m = phasePattern.exec(roadmapContent)) !== null) {
         roadmapPhases.add(m[1]);
@@ -102,7 +102,7 @@ function buildRoadmapPhaseVariants(roadmapContent) {
 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.-]*(?:-[\w.-]+)*)[:\s*]/gi;
+    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]))

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,
+};

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

@@ -550,13 +550,13 @@ function cmdValidateConsistency(cwd, raw) {
     const roadmapContentRaw = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
     const roadmapContent = extractCurrentMilestone(roadmapContentRaw, cwd);
     const roadmapPhases = new Set();
-    const phasePattern = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+([\w][\w.-]*(?:-[\w.-]+)*)\s*:/gi;
+    const phasePattern = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+([\w][\w.-]*)\s*:/gi;
     let m;
     while ((m = phasePattern.exec(roadmapContent)) !== null) {
         roadmapPhases.add(m[1]);
     }
     const fullRoadmapPhases = new Set();
-    const fullPhasePattern = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+([\w][\w.-]*(?:-[\w.-]+)*)\s*:/gi;
+    const fullPhasePattern = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+([\w][\w.-]*)\s*:/gi;
     let fm;
     while ((fm = fullPhasePattern.exec(roadmapContentRaw)) !== null) {
         fullRoadmapPhases.add(fm[1]);

package/gsd-core/bin/lib/workstream-inventory.cjs

@@ -20,7 +20,7 @@ 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
 const core = require("./core.cjs");
-const { toPosixPath, readSubdirectories } = core;
+const { readSubdirectories } = core;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planScan = require("./plan-scan.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports