@opengsd/gsd-core 1.3.1 → 1.4.0-rc.2

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

@@ -26,6 +26,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+const node_os_1 = __importDefault(require("node:os"));
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const installProfiles = require("./install-profiles.cjs");
@@ -33,7 +34,7 @@ const { readActiveProfile, resolveProfile, loadSkillsManifest, } = installProfil
 const clusters_cjs_1 = require("./clusters.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const runtimeArtifactLayout = require("./runtime-artifact-layout.cjs");
-const { findInstallSourceRoot } = runtimeArtifactLayout;
+const { findInstallSourceRoot, getInstallExports } = runtimeArtifactLayout;
 const SURFACE_FILE_NAME = '.gsd-surface.json';
 /**
  * Read the surface state from a runtime config directory.
@@ -210,8 +211,29 @@ function applySurface(runtimeConfigDir, layout, manifest, clusterMap) {
     }
     const skillManifest = normalizeSkillManifest(layout.configDir, manifest);
     const resolved = resolveSurface(layout.configDir, skillManifest, clusterMap);
+    // Mirror installRuntimeArtifacts: skills kinds get per-runtime path rewrites
+    // so SKILL.md bodies reference the install target (pathPrefix), not the
+    // converter's default ~/.claude paths (#813). Computed lazily so command-only
+    // runtimes do not trigger the install.js require.
+    let pathPrefix = null;
     for (const kind of layout.kinds) {
         const staged = kind.stage(resolved);
+        if (kind.kind === 'skills') {
+            const installExports = getInstallExports();
+            if (pathPrefix === null) {
+                const scope = layout.scope ?? 'global';
+                const resolvedTarget = node_path_1.default.resolve(layout.configDir).replace(/\\/g, '/');
+                const homeDir = node_os_1.default.homedir().replace(/\\/g, '/');
+                pathPrefix = installExports.computePathPrefix({
+                    isGlobal: scope === 'global',
+                    isOpencode: layout.runtime === 'opencode',
+                    isWindowsHost: process.platform === 'win32',
+                    resolvedTarget,
+                    homeDir,
+                });
+            }
+            installExports.applyRuntimeContentRewritesInPlace(staged, layout.runtime, pathPrefix);
+        }
         const dest = node_path_1.default.join(layout.configDir, kind.destSubpath);
         _syncGsdDir(staged, dest, kind, skillManifest);
     }
@@ -335,20 +357,41 @@ function _syncGsdDir(stagedDir, destDir, kind, manifest) {
         pruneSkillDirs(destDir, stagedDirs, kindPrefix, manifest);
     }
     else {
-        // commands / agents kind: work with .md files
-        const stagedFiles = new Set(node_fs_1.default.readdirSync(stagedDir).filter(f => f.endsWith('.md')));
-        // Copy files from staged to dest (overwrite to keep content current)
+        // commands / agents kind: mirror installRuntimeArtifacts (_copyStaged /
+        // _removeGsdEntries in bin/install.js) so surface produces the SAME files as a
+        // fresh install (#816). Flat command dirs (opencode/cursor/augment/kilo) take
+        // the gsd- prefix on copy; namespaced command dirs (commands/gsd) and agents
+        // keep their staged names. Copying staged names verbatim previously diverged
+        // from install and orphaned the installed gsd-*.md files, and the unscoped
+        // prune deleted user-owned command files.
+        //
+        // NOTE: the destName rule below intentionally mirrors bin/install.js
+        // `_copyStaged` (the `namespacedByDir` decision). Keep them in sync.
+        const destLast = (typeof kind === 'object' && kind !== null && kind.destSubpath)
+            ? node_path_1.default.basename(kind.destSubpath)
+            : '';
+        const prefixStem = kindPrefix ? kindPrefix.replace(/-$/, '') : '';
+        const namespacedByDir = kindName === 'commands' && destLast === prefixStem;
+        const stagedFiles = node_fs_1.default.readdirSync(stagedDir).filter(f => f.endsWith('.md'));
+        const stagedDestNames = new Set();
         for (const file of stagedFiles) {
-            node_fs_1.default.copyFileSync(node_path_1.default.join(stagedDir, file), node_path_1.default.join(destDir, file));
+            const destName = (kindName === 'agents' || namespacedByDir)
+                ? file
+                : `${kindPrefix}${file.slice(0, -3)}.md`;
+            node_fs_1.default.copyFileSync(node_path_1.default.join(stagedDir, file), node_path_1.default.join(destDir, destName));
+            stagedDestNames.add(destName);
         }
-        // Remove gsd-only files from dest that aren't in staged set
-        // For commands dir: all .md files are gsd skills
-        // For agents dir: only gsd-* files
-        const destEntries = node_fs_1.default.readdirSync(destDir).filter(f => f.endsWith('.md'));
-        for (const file of destEntries) {
+        // Prune stale GSD-owned files not in the staged set, preserving user-owned files
+        // (mirrors install's prefix-scoped _removeGsdEntries):
+        //   - agents: only gsd-* are GSD-owned
+        //   - flat command dirs: only `${kindPrefix}`-prefixed are GSD-owned
+        //   - namespaced command dirs: the whole dir is GSD-owned
+        for (const file of node_fs_1.default.readdirSync(destDir).filter(f => f.endsWith('.md'))) {
             if (kindName === 'agents' && !file.startsWith('gsd-'))
                 continue;
-            if (!stagedFiles.has(file)) {
+            if (kindName === 'commands' && !namespacedByDir && kindPrefix && !file.startsWith(kindPrefix))
+                continue;
+            if (!stagedDestNames.has(file)) {
                 try {
                     node_fs_1.default.unlinkSync(node_path_1.default.join(destDir, file));
                 }

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