@opengsd/gsd-core 1.6.0-rc.2 → 1.6.0

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

@@ -43,7 +43,14 @@ const io = require("./io.cjs");
 const coreUtils = require("./core-utils.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const path = require("path");
+// Phase 2 (#1646): route through the Hub per ADR-959 §III(B) line 75.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const commandRoutingHub = require("./command-routing-hub.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const cjsCommandRouterAdapter = require("./cjs-command-router-adapter.cjs");
 const { ERROR_REASON } = io;
+const { makeInvalidArgs } = commandRoutingHub;
+const { routeHubCommandFamily } = cjsCommandRouterAdapter;
 // Default CoreModule implementation assembled from leaf modules.
 // _core seam overrides this entirely for test injection.
 const _defaultCore = { output: io.output, timeAgo: coreUtils.timeAgo };
@@ -52,67 +59,79 @@ function routeIntelCommand({ args, cwd, raw, error, _intel, _core }) {
     // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
     const intel = _intel ?? require('./intel.cjs');
     const c = _core ?? _defaultCore;
-    const subcommand = args[1];
-    if (subcommand === 'query') {
-        const term = args[2];
-        if (!term) {
-            error('Usage: gsd-tools intel query <term>', ERROR_REASON.USAGE);
-            return;
-        }
-        const planningDir = path.join(cwd, '.planning');
-        c.output(intel.intelQuery(term, planningDir), raw);
-    }
-    else if (subcommand === 'status') {
-        const planningDir = path.join(cwd, '.planning');
-        const status = intel.intelStatus(planningDir);
-        if (!raw && status.files) {
-            for (const file of Object.values(status.files)) {
-                if (file.updated_at) {
-                    file.updated_at = c.timeAgo(new Date(file.updated_at));
+    // Phase 2 (#1646): routes through the Command Routing Hub per ADR-959 §III(B)
+    // line 75. Validation handlers return `makeInvalidArgs(...)` Results; the
+    // Hub → adapter translation preserves ERROR_REASON granularity via the
+    // exitReason field (Phase 1, #1644). Success handlers keep direct `c.output()`
+    // calls. The timeAgo mutation in non-raw `status` is preserved. Lazy require
+    // of intel.cjs inside the function is preserved (loads only when dispatched).
+    routeHubCommandFamily({
+        family: 'intel',
+        args,
+        // Alphabetical for stable unknownMessage text; the integration test asserts
+        // inclusion of all 9 subcommands, not order.
+        subcommands: ['api-surface', 'diff', 'extract-exports', 'patch-meta', 'query', 'snapshot', 'status', 'update', 'validate'],
+        handlers: {
+            query: () => {
+                const term = args[2];
+                if (!term) {
+                    return makeInvalidArgs('term', 'Usage: gsd-tools intel query <term>', ERROR_REASON.USAGE);
+                }
+                const planningDir = path.join(cwd, '.planning');
+                c.output(intel.intelQuery(term, planningDir), raw);
+            },
+            status: () => {
+                const planningDir = path.join(cwd, '.planning');
+                const status = intel.intelStatus(planningDir);
+                if (!raw && status.files) {
+                    for (const file of Object.values(status.files)) {
+                        if (file.updated_at) {
+                            file.updated_at = c.timeAgo(new Date(file.updated_at));
+                        }
+                    }
+                }
+                c.output(status, raw);
+            },
+            diff: () => {
+                const planningDir = path.join(cwd, '.planning');
+                c.output(intel.intelDiff(planningDir), raw);
+            },
+            snapshot: () => {
+                const planningDir = path.join(cwd, '.planning');
+                c.output(intel.intelSnapshot(planningDir), raw);
+            },
+            'patch-meta': () => {
+                const filePath = args[2];
+                if (!filePath) {
+                    return makeInvalidArgs('file-path', 'Usage: gsd-tools intel patch-meta <file-path>', ERROR_REASON.USAGE);
+                }
+                c.output(intel.intelPatchMeta(path.resolve(cwd, filePath)), raw);
+            },
+            validate: () => {
+                const planningDir = path.join(cwd, '.planning');
+                c.output(intel.intelValidate(planningDir), raw);
+            },
+            'extract-exports': () => {
+                const filePath = args[2];
+                if (!filePath) {
+                    return makeInvalidArgs('file-path', 'Usage: gsd-tools intel extract-exports <file-path>', ERROR_REASON.USAGE);
                 }
-            }
-        }
-        c.output(status, raw);
-    }
-    else if (subcommand === 'diff') {
-        const planningDir = path.join(cwd, '.planning');
-        c.output(intel.intelDiff(planningDir), raw);
-    }
-    else if (subcommand === 'snapshot') {
-        const planningDir = path.join(cwd, '.planning');
-        c.output(intel.intelSnapshot(planningDir), raw);
-    }
-    else if (subcommand === 'patch-meta') {
-        const filePath = args[2];
-        if (!filePath) {
-            error('Usage: gsd-tools intel patch-meta <file-path>', ERROR_REASON.USAGE);
-            return;
-        }
-        c.output(intel.intelPatchMeta(path.resolve(cwd, filePath)), raw);
-    }
-    else if (subcommand === 'validate') {
-        const planningDir = path.join(cwd, '.planning');
-        c.output(intel.intelValidate(planningDir), raw);
-    }
-    else if (subcommand === 'extract-exports') {
-        const filePath = args[2];
-        if (!filePath) {
-            error('Usage: gsd-tools intel extract-exports <file-path>', ERROR_REASON.USAGE);
-            return;
-        }
-        c.output(intel.intelExtractExports(path.resolve(cwd, filePath)), raw);
-    }
-    else if (subcommand === 'update') {
-        const planningDir = path.join(cwd, '.planning');
-        c.output(intel.intelUpdate(planningDir), raw);
-    }
-    else if (subcommand === 'api-surface') {
-        const planningDir = path.join(cwd, '.planning');
-        c.output(intel.intelApiSurface(planningDir), raw);
-    }
-    else {
-        error('Unknown intel subcommand. Available: query, status, update, diff, snapshot, patch-meta, validate, extract-exports, api-surface', ERROR_REASON.SDK_UNKNOWN_COMMAND);
-    }
+                c.output(intel.intelExtractExports(path.resolve(cwd, filePath)), raw);
+            },
+            update: () => {
+                const planningDir = path.join(cwd, '.planning');
+                c.output(intel.intelUpdate(planningDir), raw);
+            },
+            'api-surface': () => {
+                const planningDir = path.join(cwd, '.planning');
+                c.output(intel.intelApiSurface(planningDir), raw);
+            },
+        },
+        unknownMessage: (subcommand, available) => `Unknown intel subcommand. Available: ${available.join(', ')}`,
+        error,
+        cwd,
+        raw,
+    });
 }
 module.exports = {
     routeIntelCommand,

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

@@ -167,6 +167,7 @@ const ERROR_REASON = Object.freeze({
     SDK_MISSING_ARG: 'sdk_missing_arg',
     // workflow / phase
     PHASE_NOT_FOUND: 'phase_not_found',
+    PHASE_VERIFICATION_INCOMPLETE: 'phase_verification_incomplete',
     SUMMARY_NO_PLANNING: 'summary_no_planning',
     // graphify
     GRAPHIFY_NO_GRAPH: 'graphify_no_graph',

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

@@ -52,6 +52,9 @@ const clock_cjs_1 = require("./clock.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- uat-predicate.cjs is an export= CommonJS module
 const uatPredicate = require("./uat-predicate.cjs");
 const { evaluateUatPassed } = uatPredicate;
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- verification.cjs is an export= CommonJS module
+const verificationMod = require("./verification.cjs");
+const { readVerificationStatus } = verificationMod;
 const { planningDir, withPlanningLock } = planningWorkspace;
 const { extractFrontmatter } = frontmatterMod;
 const { readModifyWriteStateMd, stateExtractField, stateReplaceField, stateReplaceFieldWithFallback, syncStateFrontmatter, withStateLock, updatePerformanceMetricsSection, } = stateMod;
@@ -1077,8 +1080,8 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
         : 0;
     let requirementsUpdated = false;
     const warnings = [];
+    const phaseFullDir = node_path_1.default.join(cwd, phaseInfo['directory']);
     try {
-        const phaseFullDir = node_path_1.default.join(cwd, phaseInfo['directory']);
         const phaseFiles = node_fs_1.default.readdirSync(phaseFullDir);
         for (const file of phaseFiles.filter((f) => f.includes('-UAT') && f.endsWith('.md'))) {
             const content = node_fs_1.default.readFileSync(node_path_1.default.join(phaseFullDir, file), 'utf-8');
@@ -1113,7 +1116,11 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
     let nextPhaseNum = null;
     let nextPhaseName = null;
     let isLastPhase = true;
-    withPlanningLock(cwd, () => {
+    const verificationBlocked = withPlanningLock(cwd, () => {
+        const verificationStatus = readVerificationStatus(phaseFullDir);
+        if (verificationStatus.status !== 'passed') {
+            return verificationStatus;
+        }
         const runPhaseCompleteTransaction = () => {
             const writes = [];
             let roadmapContent = null;
@@ -1381,7 +1388,14 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
         else {
             runPhaseCompleteTransaction();
         }
+        return null;
     });
+    if (verificationBlocked) {
+        const nextStep = verificationBlocked.next_command
+            ? ` Next: ${verificationBlocked.next_command}`
+            : '';
+        error(`Phase ${phaseNum} verification is incomplete: ${verificationBlocked.next_action}${nextStep}`, ERROR_REASON.PHASE_VERIFICATION_INCOMPLETE);
+    }
     let autoPruned = false;
     try {
         const configPath = node_path_1.default.join(planningDir(cwd), 'config.json');

package/gsd-core/bin/lib/plan-scan.cjs

@@ -63,8 +63,8 @@ function scanPhasePlans(phaseDir) {
     if ((0, node_fs_1.existsSync)(nestedDir)) {
         try {
             const nestedFiles = (0, node_fs_1.readdirSync)(nestedDir);
-            nestedPlanFiles = nestedFiles.filter(isNestedPlanFile);
-            nestedSummaryFiles = nestedFiles.filter(isNestedSummaryFile);
+            nestedPlanFiles = nestedFiles.filter(isNestedPlanFile).map((file) => `plans/${file}`);
+            nestedSummaryFiles = nestedFiles.filter(isNestedSummaryFile).map((file) => `plans/${file}`);
             hasNestedPlans = nestedPlanFiles.length > 0;
         }
         catch { /* ignore unreadable nested layout */ }

package/gsd-core/bin/lib/planning-workspace.cjs

@@ -33,6 +33,54 @@ process.on('exit', () => {
         catch { /* already gone */ }
     }
 });
+// ---------------------------------------------------------------------------
+// Lock liveness probe (test seam) — audit M1
+//
+// mtime is a leaky proxy for "the holder is alive". The prior withPlanningLock
+// timeout fallback unconditionally unlinked WHATEVER lock existed — even a fresh,
+// live holder's — and re-acquired it, force-stealing a live writer's critical
+// section. We backport capability-lock.cts's pid-liveness gate: a dead holder is
+// stolen promptly inside the polite loop; a live holder is waited on. The
+// indirection lets unit tests inject a deterministic isPidAlive without real pids.
+// ---------------------------------------------------------------------------
+/** Is `pid` a live process? process.kill(pid, 0) succeeds for a live (signalable) process. */
+function _realIsPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true; // signalable → alive
+    }
+    catch (err) {
+        // EPERM = process exists but we cannot signal it (still ALIVE). ESRCH = gone.
+        return err.code === 'EPERM';
+    }
+}
+const _planningLockProbes = { isPidAlive: _realIsPidAlive };
+function _planningLockIsPidAlive(pid) {
+    return _planningLockProbes.isPidAlive(pid);
+}
+const _planningLockTestHooks = {};
+// Monotonic sequence for unique stale-steal rename targets (no crypto dependency).
+let _planningStealSeq = 0;
+/**
+ * Is the holder recorded in the .lock body VERIFIED-LIVE? The body is JSON
+ * { pid, cwd, acquired }. Returns true ONLY when the body parses AND the recorded
+ * pid signals alive. A garbage / pid-less / unreadable body (or a dead pid) is NOT
+ * verified-live, so the lock stays stealable — corrupt locks never block forever,
+ * and a live holder is never force-stolen.
+ */
+function _planningHolderVerifiedLive(lockPath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(node_fs_1.default.readFileSync(lockPath, 'utf-8'));
+    }
+    catch {
+        return false; // unreadable / unparseable body → cannot verify → not verified-live
+    }
+    const pid = parsed?.pid;
+    if (typeof pid !== 'number' || !Number.isInteger(pid) || pid <= 0)
+        return false;
+    return _planningLockIsPidAlive(pid);
+}
 // Transient errno codes that indicate a temporary filesystem condition under
 // concurrent O_EXCL races — Docker overlay-fs (ENOENT/EINVAL/EIO), NFS
 // (ESTALE), and OS-level interrupt/retry signals (EAGAIN/EINTR).  These are
@@ -97,6 +145,12 @@ function withPlanningLock(cwd, fn, clock) {
         clock = clock_cjs_1.realClock;
     const lockPath = node_path_1.default.join(planningDir(cwd), '.lock');
     const lockTimeout = 10000; // 10 seconds
+    // Deadman ceiling (audit M1 / R4-FIX) — set ABOVE lockTimeout so a holder that reads
+    // as alive but is actually a pid-reuse alias (the .lock body has no startTime, so
+    // liveness alone cannot detect reuse) is still recovered once its lock ages past this
+    // absolute ceiling. Without it, a false-alive holder would make withPlanningLock throw
+    // on every call with no self-heal. Mirrors acquireStateLock's deadmanCeilingMs.
+    const deadmanCeilingMs = 60000;
     const start = clock.now();
     // Ensure .planning/ exists
     try {
@@ -143,31 +197,104 @@ function withPlanningLock(cwd, fn, clock) {
                 continue;
             }
             if (nodeErr.code === 'EEXIST') {
-                // Lock exists — check if stale (>30s old)
+                // Liveness-gated steal (audit M1). Steal the lock PROMPTLY only when its
+                // recorded holder is NOT verified-live (crashed/dead pid or garbage body).
+                // A verified-live holder is waited on — never force-stolen — because nuking
+                // a slow-but-live writer's lock corrupts the .planning/ critical section.
+                // The steal is an ATOMIC rename-then-recreate guarded by an identity re-confirm
+                // so a racer that recreates a fresh lock in the decision→steal gap never has
+                // its replacement deleted (audit M2 / PR #1532 review, window b). The body is
+                // written atomically (writeFileSync …{flag:'wx'}) so there is no empty-body
+                // create window here — only the double-steal needs hardening.
                 try {
-                    const stat = node_fs_1.default.statSync(lockPath);
-                    if (clock.now() - stat.mtimeMs > 30000) {
-                        node_fs_1.default.unlinkSync(lockPath);
-                        continue; // retry
+                    const decisionStat = node_fs_1.default.statSync(lockPath);
+                    // Snapshot the decision-time body too: (dev, ino) alone is defeated by inode
+                    // REUSE (a racer's unlink+recreate can land on the same inode), so the body
+                    // content binds the identity as well — mirrors capability-lock.cts's (dev,
+                    // ino, ts) re-confirm.
+                    let decisionBody;
+                    try {
+                        decisionBody = node_fs_1.default.readFileSync(lockPath, 'utf-8');
+                    }
+                    catch {
+                        decisionBody = null;
+                    }
+                    let stealable = !_planningHolderVerifiedLive(lockPath);
+                    if (!stealable) {
+                        // Verified-live, but recover anyway once the lock crosses the absolute
+                        // deadman ceiling — defeats a pid-reuse false-alive that would otherwise
+                        // block forever (R4-FIX; mtime age is from lock creation, not this call).
+                        const age = clock.now() - decisionStat.mtimeMs;
+                        stealable = age > deadmanCeilingMs;
+                    }
+                    if (stealable) {
+                        if (_planningLockTestHooks.beforeSteal)
+                            _planningLockTestHooks.beforeSteal({ lockPath });
+                        // Identity re-confirm immediately before the steal: a racer that stole +
+                        // recreated a fresh lock in the decision→steal gap changes (dev, ino) → do
+                        // NOT delete the replacement; back off and re-evaluate.
+                        let confirmStat;
+                        try {
+                            confirmStat = node_fs_1.default.statSync(lockPath);
+                        }
+                        catch {
+                            continue; // vanished between decision and steal — retry the create.
+                        }
+                        let confirmBody;
+                        try {
+                            confirmBody = node_fs_1.default.readFileSync(lockPath, 'utf-8');
+                        }
+                        catch {
+                            confirmBody = null;
+                        }
+                        const sameInstance = typeof decisionStat.dev === 'number' && typeof decisionStat.ino === 'number' &&
+                            confirmStat.dev === decisionStat.dev && confirmStat.ino === decisionStat.ino &&
+                            decisionBody !== null && confirmBody === decisionBody;
+                        if (!sameInstance) {
+                            clock.sleep(100); // a racer won the steal + recreated — re-evaluate, don't delete it.
+                            continue;
+                        }
+                        // Atomic steal: rename the inode aside, then remove it. Only ONE racer can
+                        // win the rename; a failed rename means another process already stole it, so
+                        // we must NOT fall through to a delete — back off and retry the create.
+                        const stolen = lockPath + '.stale-' + process.pid + '-' + clock.now() + '-' + (_planningStealSeq++);
+                        let renamed = false;
+                        try {
+                            node_fs_1.default.renameSync(lockPath, stolen);
+                            renamed = true;
+                        }
+                        catch { /* another racer won */ }
+                        if (renamed) {
+                            try {
+                                node_fs_1.default.rmSync(stolen, { force: true });
+                            }
+                            catch { /* best-effort */ }
+                            continue; // dead/garbage/expired holder freed — retry immediately to grab it.
+                        }
+                        clock.sleep(100); // lost the steal race — back off and retry.
+                        continue;
                     }
                 }
                 catch {
                     continue;
                 }
-                // Wait and retry (cross-platform, no shell dependency)
+                // Live holder — wait and retry (cross-platform, no shell dependency).
                 clock.sleep(100);
                 continue;
             }
             throw err;
         }
     }
-    // Timeout — stale-lock recovery, then re-acquire atomically before entering critical section.
-    try {
-        node_fs_1.default.unlinkSync(lockPath);
-    }
-    catch { /* ok */ }
-    acquireLock();
-    return runWithHeldLock();
+    // Timeout against a holder still present at budget exhaustion. The polite loop
+    // already stole any DEAD holder; reaching here means the holder is verified-live
+    // (or a pid-reuse alias we must not corrupt). Do NOT force-steal — the prior
+    // unconditional `unlinkSync(lockPath); acquireLock()` here (audit M1) robbed live
+    // writers, and its re-acquire sat OUTSIDE any try so a concurrent re-create raced
+    // a raw EEXIST out of the helper (audit M2). Surface a clear timeout error instead.
+    const timeoutErr = new Error('withPlanningLock: ' + lockPath + ' held by a live process for ' +
+        (clock.now() - start) + 'ms (exceeded ' + lockTimeout + 'ms budget)');
+    timeoutErr.lockTimeout = true;
+    throw timeoutErr;
 }
 function createPlanningWorkspace(cwd, opts = {}) {
     return {
@@ -242,4 +369,21 @@ module.exports = {
     getActiveWorkstream,
     setActiveWorkstream,
     findContextMdIn,
+    // Test seam (audit M1): inject a deterministic isPidAlive so the liveness-gated
+    // steal decision is exercised without real pids. Mirrors capability-lock.cts.
+    _setLockProbes(probes) {
+        if (typeof probes.isPidAlive === 'function')
+            _planningLockProbes.isPidAlive = probes.isPidAlive;
+    },
+    _resetLockProbes() {
+        _planningLockProbes.isPidAlive = _realIsPidAlive;
+    },
+    // Test seam (PR #1532 review): script the steal decision→steal gap (window b).
+    _setPlanningLockTestHooks(hooks) {
+        if ('beforeSteal' in hooks)
+            _planningLockTestHooks.beforeSteal = hooks.beforeSteal;
+    },
+    _resetPlanningLockTestHooks() {
+        delete _planningLockTestHooks.beforeSteal;
+    },
 };

package/gsd-core/bin/lib/profile-output.cjs

@@ -1010,19 +1010,31 @@ function cmdGenerateClaudeMd(cwd, options, raw) {
     // repo-root `CLAUDE.md`, so generated GSD content does not land next to — or
     // pollute — a hand-crafted repo-root CLAUDE.md. An explicit `claude_md_path`
     // config value or `--output` still wins.
-    let configClaudeMdPath = './.claude/CLAUDE.md';
+    let configClaudeMdPath = '.claude/CLAUDE.md';
     try {
         const config = loadConfig(cwd);
         if (config['claude_md_path'])
             configClaudeMdPath = config['claude_md_path'];
         if (config['claude_md_assembly'])
             assemblyConfig = config['claude_md_assembly'];
-        // #3163: When runtime is codex, override the output target to AGENTS.md
-        // regardless of claude_md_path, so Codex projects never write to CLAUDE.md.
-        // GSD_RUNTIME env var takes precedence over config.runtime, mirroring detectRuntime().
+        // #1529: When no explicit --output is provided, derive the instruction
+        // file from the runtime via the shared `getProjectInstructionFile` policy
+        // (single source of truth in runtime-name-policy.cjs, shared with the
+        // new-project.md bash workflow via `gsd-tools query
+        // project-instruction-file`). Previously this was a codex-only override
+        // (#3163) that left AGENTS-native runtimes (opencode/kilo/kimi) emitting
+        // CLAUDE.md; copilot now resolves to .github/copilot-instructions.md, and
+        // antigravity/gemini to GEMINI.md. GSD_RUNTIME env var takes precedence
+        // over config.runtime, mirroring detectRuntime().
+        //
+        // Non-claude runtimes always win over a stale `claude_md_path` (the #3163
+        // rationale: a Codex/AGENTS-native project must never write to CLAUDE.md
+        // even if a prior Claude setup left a `claude_md_path` behind). For the
+        // claude runtime, `claude_md_path` config is honored — it IS the
+        // Claude-specific output setting (per #1098 and the #3163 non-codex test).
         const effectiveRuntime = (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)(process.env['GSD_RUNTIME'], config['runtime']);
-        if (!options.output && effectiveRuntime === 'codex') {
-            configClaudeMdPath = './AGENTS.md';
+        if (!options.output && effectiveRuntime && effectiveRuntime !== 'claude') {
+            configClaudeMdPath = (0, runtime_name_policy_cjs_1.getProjectInstructionFile)(effectiveRuntime);
         }
     }
     catch { /* use default */ }

package/gsd-core/bin/lib/runtime-artifact-conversion.cjs

@@ -855,20 +855,18 @@ function convertClaudeToWindsurfMarkdown(content) {
     // Replace subagent_type from Claude to Windsurf format
     converted = converted.replace(/subagent_type="general-purpose"/g, 'subagent_type="generalPurpose"');
     converted = converted.replace(/\$ARGUMENTS\b/g, '{{GSD_ARGS}}');
-    // Replace project-level Claude conventions with Windsurf/Devin equivalents
-    // Workspace skills install to .devin/ (Devin Desktop preferred dir, #1085).
-    // Legacy .windsurf/ is still recognized on read but new installs use .devin/.
-    converted = converted.replace(/`\.\/CLAUDE\.md`/g, '`.devin/rules`');
-    converted = converted.replace(/\.\/CLAUDE\.md/g, '.devin/rules');
-    converted = converted.replace(/`CLAUDE\.md`/g, '`.devin/rules`');
-    converted = converted.replace(/\bCLAUDE\.md\b/g, '.devin/rules');
-    converted = converted.replace(/\.claude\/skills\//g, '.devin/skills/');
-    converted = converted.replace(/\.\/\.claude\//g, './.devin/');
-    converted = converted.replace(/\.claude\//g, '.devin/');
+    // Replace project-level Claude conventions with Windsurf equivalents.
+    converted = converted.replace(/`\.\/CLAUDE\.md`/g, '`.windsurf/rules`');
+    converted = converted.replace(/\.\/CLAUDE\.md/g, '.windsurf/rules');
+    converted = converted.replace(/`CLAUDE\.md`/g, '`.windsurf/rules`');
+    converted = converted.replace(/\bCLAUDE\.md\b/g, '.windsurf/rules');
+    converted = converted.replace(/\.claude\/skills\//g, '.windsurf/skills/');
+    converted = converted.replace(/\.\/\.claude\//g, './.windsurf/');
+    converted = converted.replace(/\.claude\//g, '.windsurf/');
     // Bare forms (no trailing slash) — after slash forms to avoid double-rewrite.
     // Use negative lookahead (?![\w-]) to preserve .claude-plugin and .claudeignore.
-    converted = converted.replace(/~\/\.claude(?![\w-])/g, '~/.devin');
-    converted = converted.replace(/\$HOME\/\.claude(?![\w-])/g, '$HOME/.devin');
+    converted = converted.replace(/~\/\.claude(?![\w-])/g, '~/.windsurf');
+    converted = converted.replace(/\$HOME\/\.claude(?![\w-])/g, '$HOME/.windsurf');
     // Environment variable name rewrite
     converted = converted.replace(/\bCLAUDE_CONFIG_DIR\b/g, 'WINDSURF_CONFIG_DIR');
     // Remove Claude Code-specific bug workarounds before brand replacement
@@ -918,6 +916,30 @@ function convertClaudeCommandToWindsurfSkill(content, skillName) {
     const adapter = getWindsurfSkillAdapterHeader(skillName);
     return `---\nname: ${yamlIdentifier(skillName)}\ndescription: ${yamlQuote(shortDescription)}\n---\n\n${adapter}\n\n${body.trimStart()}`;
 }
+function convertClaudeCommandToWindsurfWorkflow(content, commandName) {
+    // #1615 security: commandName flows unsanitized into a markdown body that
+    // Windsurf loads as an LLM-readable workflow. Validate at entry to prevent
+    // (a) prompt injection via newlines / markdown structure in the filename,
+    // (b) path-component injection via .., /, \ in stem → @-reference target.
+    // Pattern: optional gsd- prefix + lowercase alphanumeric + dashes; rejects
+    // everything else. See DEFECT.PROMPT-INJECTION-SCAN-COLLISION and the
+    // PR #1622 security review.
+    if (typeof commandName !== 'string' || !/^(?:gsd-)?[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(commandName)) {
+        const preview = typeof commandName === 'string' ? JSON.stringify(commandName.slice(0, 60)) : String(commandName);
+        throw new Error(`convertClaudeCommandToWindsurfWorkflow: rejected commandName ${preview}; ` +
+            'must match /^(?:gsd-)?[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/ (no slashes, backslashes, spaces, dots, trailing dash, or control chars — prevents prompt injection and path-component injection into the workflow body)');
+    }
+    const converted = convertClaudeToWindsurfMarkdown(content);
+    const { frontmatter } = extractFrontmatterAndBody(converted);
+    const description = frontmatter ? extractFrontmatterField(frontmatter, 'description') : '';
+    const stem = commandName.startsWith('gsd-') ? commandName.slice(4) : commandName;
+    const workflow = `# ${commandName}\n\n${toSingleLine(description || `Run ${commandName}.`)}\n\nRead and execute the GSD command at @~/.claude/gsd-core/commands/gsd/${stem}.md end-to-end. Treat the user's message after /${commandName} as the command arguments.`;
+    const byteLength = Buffer.byteLength(workflow, 'utf8');
+    if (byteLength > 12000) {
+        throw new Error(`Windsurf workflow ${commandName} exceeds 12000 bytes (${byteLength}); extract references before installing`);
+    }
+    return workflow;
+}
 // --- Augment converters ---
 // Augment uses a tool set similar to Cursor/Windsurf.
 // Config lives in .augment/ (local) and ~/.augment/ (global).
@@ -1706,10 +1728,16 @@ function convertGeminiToolName(claudeTool) {
     // Task/Agent: exclude — agents are auto-registered as callable tools.
     // AskUserQuestion: exclude — Gemini CLI does not expose an ask_user tool;
     // emitting it causes frontmatter validation errors (#3362).
+    // Skill/SlashCommand: exclude — Gemini CLI has no 'skill' built-in tool;
+    // the lowercase fallback would emit an invalid 'skill'/'slashcommand' name
+    // that fails frontmatter validation (tools.N: Invalid tool name) and aborts
+    // the entire agent load (#1394).
     if (claudeTool === 'Task' ||
         claudeTool === 'Agent' ||
         claudeTool === 'AskUserQuestion' ||
-        claudeTool === 'ask_user') {
+        claudeTool === 'ask_user' ||
+        claudeTool === 'Skill' ||
+        claudeTool === 'SlashCommand') {
         return null;
     }
     // Check for explicit mapping
@@ -1954,10 +1982,18 @@ function convertClaudeCommandToKiloSkill(content, skillName) {
  * @private — exported as `_computePathPrefix` for tests.
  */
 function computePathPrefix({ isGlobal, isOpencode, isWindowsHost: _isWindowsHost, resolvedTarget, homeDir }) {
-    if (isGlobal && resolvedTarget.startsWith(homeDir) && !isOpencode) {
-        return '$HOME' + resolvedTarget.slice(homeDir.length) + '/';
+    // #1615: normalize Windows backslashes to forward slashes. This prefix is
+    // substituted into markdown @-references (e.g. Windsurf workflow files),
+    // which use POSIX paths universally. Idempotent on POSIX (no backslashes).
+    // Without this, path.join on Windows produces a backslash prefix that
+    // leaks into markdown content and breaks cross-platform substring checks.
+    // See DEFECT.WINDOWS-PATH-LEAK-IN-MARKDOWN-CONTENT in CONTEXT.md.
+    const posixTarget = String(resolvedTarget).replace(/\\/g, '/');
+    const posixHome = homeDir ? String(homeDir).replace(/\\/g, '/') : homeDir;
+    if (isGlobal && posixTarget.startsWith(posixHome) && !isOpencode) {
+        return '$HOME' + posixTarget.slice(posixHome.length) + '/';
     }
-    return `${resolvedTarget}/`;
+    return `${posixTarget}/`;
 }
 /**
  * Canonical list of every non-Claude runtime that gsd-core emits artifacts for.
@@ -2319,6 +2355,7 @@ module.exports = {
     convertClaudeCommandToCursorCommand,
     convertClaudeToWindsurfMarkdown,
     convertClaudeCommandToWindsurfSkill,
+    convertClaudeCommandToWindsurfWorkflow,
     convertClaudeToAugmentMarkdown,
     convertClaudeCommandToAugmentSkill,
     convertClaudeToTraeMarkdown,

package/gsd-core/bin/lib/runtime-artifact-layout.cjs

@@ -130,6 +130,20 @@ function agentsKind(destSubpath, prefix, configDir) {
  * Agent filenames are preserved verbatim (the prefix is already embedded in the
  * agent stem — e.g. `gsd-planner.md`).
  *
+ * #1173 SCOPE — plumbing only (declarations deferred): this provides the
+ * converter dispatch + `isGlobal` scope threading for the descriptor's `agents`
+ * kind, but NO runtime currently declares a converted `agents` kind in its
+ * `capability.json`. The descriptor declarations for the 8 non-Claude runtimes
+ * (copilot/antigravity/cursor/windsurf/augment/trae/codebuddy/cline) are
+ * DEFERRED to a follow-up that first ships the ADR-1235 §0 byte-for-byte parity
+ * harness, because the second `layout.kinds` consumer — `applySurface` /
+ * `/gsd:surface` / `--materialize` (`src/surface.cts`) — does not yet mirror the
+ * legacy agent pipeline (Copilot's `.agent.md` filename rename, the cross-cutting
+ * path-prefix rewrite + attribution, stale-file cleanup, config-reading steps),
+ * so declaring the kind now would regress the surface path. Until then the legacy
+ * `bin/install.js` agent loop remains authoritative for the real install, and
+ * this `convertedAgentsKind` is exercised only by synthetic-descriptor seam tests.
+ *
  * Mirrors the `convertedCommandsKind` pattern (#785).
  *
  * @param destSubpath   destination subpath within configDir (e.g. 'agents')
@@ -137,14 +151,18 @@ function agentsKind(destSubpath, prefix, configDir) {
  * @param converterName name of converter function in Runtime Artifact Conversion exports
  * @param configDir     runtime config dir (for .gsd-source marker resolution)
  */
-function convertedAgentsKind(destSubpath, prefix, converterName, configDir) {
+function convertedAgentsKind(destSubpath, prefix, converterName, configDir, scope = 'global') {
     return {
         kind: 'agents',
         destSubpath,
         prefix,
         stage: (resolved) => {
+            // isGlobal is threaded so scope-aware agent converters (copilot, antigravity)
+            // choose global-home vs workspace-relative paths; converters that only take
+            // (content) ignore the extra positional arg. Mirrors skillsKind's scope
+            // threading (#1173).
             const converter = conversionExports[converterName];
-            return stageAgentsForRuntimeWithConverter(findAgentsSourceRoot(configDir), resolved, converter);
+            return stageAgentsForRuntimeWithConverter(findAgentsSourceRoot(configDir), resolved, converter, scope === 'global');
         },
     };
 }
@@ -267,7 +285,7 @@ function dispatchKindEntry(entry, runtime, configDir, scope) {
             if (converter == null) {
                 return agentsKind(destSubpath, prefix, configDir);
             }
-            return convertedAgentsKind(destSubpath, prefix, converter, configDir);
+            return convertedAgentsKind(destSubpath, prefix, converter, configDir, scope);
         case 'skills':
             if (converter == null) {
                 throw new TypeError(`resolveRuntimeArtifactLayout: skills entry for '${runtime}' has converter=null (converter is required for skills)`);