@opengsd/gsd-core 1.7.0-rc.6 → 1.8.0

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

@@ -26,6 +26,7 @@ const { readGsdCommandNames, transformContentToHyphen } = commandRoster;
 const runtimeNamePolicy = require("./runtime-name-policy.cjs");
 const { getDirName } = runtimeNamePolicy;
 const capabilityRegistry = require("./capability-registry.cjs");
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 // #1383: resolve GSD's version WITHOUT a top-level
 // `require('../../../package.json')`. That require ran at module load on every
 // gsd-tools invocation (this module sits in the gsd-tools loader chain) and
@@ -867,7 +868,13 @@ function convertClaudeCommandToCursorSkill(content, skillName) {
     description = toSingleLine(description);
     const shortDescription = description.length > 180 ? `${description.slice(0, 177)}...` : description;
     const adapter = getCursorSkillAdapterHeader(skillName);
-    return `---\nname: ${yamlIdentifier(skillName)}\ndescription: ${yamlQuote(shortDescription)}\n---\n\n${adapter}\n\n${body.trimStart()}`;
+    // #2341: mark user-invocable:false so the skill is NOT shown in Cursor's '/'
+    // menu (it defaults to true). Cursor also writes a commands/ surface (#785),
+    // and surfacing both duplicated every /gsd-* entry. This mirrors the #789
+    // CodeBuddy de-dup: the commands/ surface is the sole '/' entry point; skills
+    // stay model-invocable background knowledge. (user-invocable:false hides from
+    // '/' while keeping model invocation — distinct from disable-model-invocation.)
+    return `---\nname: ${yamlIdentifier(skillName)}\ndescription: ${yamlQuote(shortDescription)}\nuser-invocable: false\n---\n\n${adapter}\n\n${body.trimStart()}`;
 }
 /**
  * Convert a Claude Code command to a Cursor 1.6 slash command (#785).
@@ -2143,8 +2150,8 @@ function computePathPrefix({ isGlobal, isOpencode, isWindowsHost: _isWindowsHost
     // 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;
+    const posixTarget = (0, shell_command_projection_cjs_1.posixNormalize)(String(resolvedTarget));
+    const posixHome = homeDir ? (0, shell_command_projection_cjs_1.posixNormalize)(String(homeDir)) : homeDir;
     if (isGlobal && posixTarget.startsWith(posixHome) && !isOpencode) {
         return '$HOME' + posixTarget.slice(posixHome.length) + '/';
     }
@@ -2461,8 +2468,8 @@ function rewriteStagedSkillBodies(stagedDir, opts) {
     const { runtime, configDir, scope = 'global', homedir = () => node_os_1.default.homedir(), platform = process.platform, resolveAttribution, } = opts;
     if (!node_fs_1.default.existsSync(stagedDir))
         return;
-    const resolvedTarget = node_path_1.default.resolve(configDir).replace(/\\/g, '/');
-    const homeDir = homedir().replace(/\\/g, '/');
+    const resolvedTarget = (0, shell_command_projection_cjs_1.posixNormalize)(node_path_1.default.resolve(configDir));
+    const homeDir = (0, shell_command_projection_cjs_1.posixNormalize)(homedir());
     const isGlobal = scope === 'global';
     const isOpencode = false; // #2087: opencode installs via the combined-family engine path, never through the generic rewrite
     const isWindowsHost = platform === 'win32';
@@ -2490,8 +2497,8 @@ function rewriteStagedCommandBodies(stagedDir, opts) {
     const { runtime, configDir, scope = 'global', homedir = () => node_os_1.default.homedir(), platform = process.platform, resolveAttribution, } = opts;
     if (!node_fs_1.default.existsSync(stagedDir))
         return stagedDir;
-    const resolvedTarget = node_path_1.default.resolve(configDir).replace(/\\/g, '/');
-    const homeDir = homedir().replace(/\\/g, '/');
+    const resolvedTarget = (0, shell_command_projection_cjs_1.posixNormalize)(node_path_1.default.resolve(configDir));
+    const homeDir = (0, shell_command_projection_cjs_1.posixNormalize)(homedir());
     const isGlobal = scope === 'global';
     const isOpencode = false; // #2087: opencode installs via the combined-family engine path, never through the generic rewrite
     const isWindowsHost = platform === 'win32';

package/gsd-core/bin/lib/runtime-artifact-install-plan.cjs

@@ -67,9 +67,10 @@ function createRuntimeArtifactInstallPlan(args) {
     // to kind.stage() for agents kind entries with a converter (convertedAgentsKind).
     // NO _stampNonClaudeRuntimeDefaults — agents are NOT stamped in the inline loop.
     const os = _require('node:os');
+    const { posixNormalize } = _require('./shell-command-projection.cjs');
     const homedirFn = homedir ?? (() => os.homedir());
-    const resolvedTarget = path.resolve(layout.configDir).replace(/\\/g, '/');
-    const homeDir = homedirFn().replace(/\\/g, '/');
+    const resolvedTarget = posixNormalize(path.resolve(layout.configDir));
+    const homeDir = posixNormalize(homedirFn());
     const isGlobal = scope === 'global';
     const isOpencode = layout.runtime === 'opencode';
     const isWindowsHost = (platform ?? process.platform) === 'win32';

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

@@ -23,6 +23,7 @@ const { stageSkillsForProfile, stageAgentsForProfile, stageAgentsForRuntimeWithC
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const runtimeArtifactConversion = require("./runtime-artifact-conversion.cjs");
 const conversionExports = runtimeArtifactConversion;
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 // In .cts (CommonJS output) files, `require` is available as a global.
 const _require = require;
 // ---------------------------------------------------------------------------
@@ -192,7 +193,7 @@ function kimiAgentsKind(destSubpath, prefix, configDir) {
                         continue;
                     const agentPath = node_path_1.default.join(stagedAgents, entry.name);
                     subagents.push({
-                        path: node_path_1.default.join('agents', entry.name).replace(/\\/g, '/'),
+                        path: (0, shell_command_projection_cjs_1.posixNormalize)(node_path_1.default.join('agents', entry.name)),
                         content: node_fs_1.default.readFileSync(agentPath, 'utf8'),
                     });
                 }
@@ -226,8 +227,12 @@ function kimiAgentsKind(destSubpath, prefix, configDir) {
  *                       arg so scope-aware converters (antigravity, copilot) can choose
  *                       between global home paths and workspace-relative paths without
  *                       colliding with the `runtime` string at position 3.
+ * @param capabilityRegistry #2322: optional capability registry — captured in the
+ *                       stage() closure so third-party capability skills are bound to
+ *                       their declaring capId at staging time. Absent -> stage() stages
+ *                       nothing third-party (fail closed).
  */
-function skillsKind(destSubpath, prefix, converterName, runtime, configDir, nested = false, scope = 'global') {
+function skillsKind(destSubpath, prefix, converterName, runtime, configDir, nested = false, scope = 'global', capabilityRegistry) {
     return {
         kind: 'skills',
         destSubpath,
@@ -246,7 +251,7 @@ function skillsKind(destSubpath, prefix, converterName, runtime, configDir, nest
                 : [];
             const isGlobal = scope === 'global';
             const wrappedConverter = (content, skillName) => realConverter(content, skillName, runtime, cmdNames, isGlobal);
-            return stageSkillsForRuntimeAsSkills(findInstallSourceRoot(configDir), resolved, wrappedConverter, prefix, nested);
+            return stageSkillsForRuntimeAsSkills(findInstallSourceRoot(configDir), resolved, wrappedConverter, prefix, nested, capabilityRegistry);
         },
     };
 }
@@ -284,7 +289,7 @@ function getRegistry() {
  * Map a single ArtifactKindDescriptor entry to an ArtifactKind using the
  * matching builder function. Mirrors the hand-built calls in the old switch.
  */
-function dispatchKindEntry(entry, runtime, configDir, scope) {
+function dispatchKindEntry(entry, runtime, configDir, scope, capabilityRegistry) {
     const { kind, destSubpath, prefix, nesting, converter } = entry;
     const nested = nesting === 'nested';
     let result;
@@ -303,7 +308,7 @@ function dispatchKindEntry(entry, runtime, configDir, scope) {
             if (converter == null) {
                 throw new TypeError(`resolveRuntimeArtifactLayout: skills entry for '${runtime}' has converter=null (converter is required for skills)`);
             }
-            result = skillsKind(destSubpath, prefix, converter, runtime, configDir, nested, scope);
+            result = skillsKind(destSubpath, prefix, converter, runtime, configDir, nested, scope, capabilityRegistry);
             break;
         case 'kimi-agents':
             result = kimiAgentsKind(destSubpath, prefix, configDir);
@@ -321,11 +326,21 @@ function dispatchKindEntry(entry, runtime, configDir, scope) {
  *
  * ADR-857 phase 5d: driven by the capability-registry artifactLayout descriptor
  * instead of a hardcoded switch statement.
+ *
+ * @param capabilityRegistry #2322: optional — when the caller has a composed
+ *   capability registry in scope (e.g. capability-writer.cts's `capability set`
+ *   path, or a fresh install's registry-aware profile resolution), pass it here
+ *   so the skills kind's stage() closure can materialize installed third-party
+ *   capability skills bound to their declaring capId. Both call paths (surface
+ *   apply AND the installer) must pass their registry here — resolveProfile's
+ *   own `'*'` (full profile) short-circuit never carries a registry, so if it
+ *   is not threaded in at layout-build time a `full`-profile install stages no
+ *   third-party capability skills regardless of registration (#2322 blocker 2).
  */
-function resolveRuntimeArtifactLayout(runtime, configDir, scope = 'global') {
-    return resolveRuntimeArtifactLayoutFromRegistry(getRegistry(), runtime, configDir, scope);
+function resolveRuntimeArtifactLayout(runtime, configDir, scope = 'global', capabilityRegistry) {
+    return resolveRuntimeArtifactLayoutFromRegistry(getRegistry(), runtime, configDir, scope, capabilityRegistry);
 }
-function resolveRuntimeArtifactLayoutFromRegistry(registry, runtime, configDir, scope = 'global') {
+function resolveRuntimeArtifactLayoutFromRegistry(registry, runtime, configDir, scope = 'global', capabilityRegistry) {
     if (typeof configDir !== 'string' || configDir === '') {
         throw new TypeError('configDir must be a non-empty string');
     }
@@ -337,7 +352,7 @@ function resolveRuntimeArtifactLayoutFromRegistry(registry, runtime, configDir,
         throw new TypeError(`Unknown runtime: '${runtime}' — add to runtime-artifact-layout.cjs table`);
     }
     const entries = desc[scope] ?? [];
-    const kinds = entries.map((entry) => dispatchKindEntry(entry, runtime, configDir, scope));
+    const kinds = entries.map((entry) => dispatchKindEntry(entry, runtime, configDir, scope, capabilityRegistry));
     return { runtime, configDir, scope, kinds };
 }
 module.exports = { resolveRuntimeArtifactLayout, resolveRuntimeArtifactLayoutFromRegistry, findInstallSourceRoot };

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

@@ -267,7 +267,7 @@ function normalizeNodePath(execPath, opts) {
         return execPath;
     const env = (opts && opts.env) || process.env;
     const existsSync = (opts && opts.existsSync) || node_fs_1.default.existsSync;
-    const normalizedForMatch = execPath.replace(/\\/g, '/');
+    const normalizedForMatch = shellCmdProjection.posixNormalize(execPath);
     if (/\/fnm_multishells\/[0-9]+_[0-9]+\/node(\.exe)?$/i.test(normalizedForMatch)) {
         const candidates = [];
         if (env.FNM_DIR) {
@@ -283,11 +283,16 @@ function normalizeNodePath(execPath, opts) {
         }
         return execPath;
     }
-    if (/^\/usr\/local\/Cellar\/node(@\d+)?\/[^/]+\/bin\/node(\.exe)?$/.test(execPath)) {
-        return '/usr/local/bin/node';
-    }
-    if (/^\/opt\/homebrew\/Cellar\/node(@\d+)?\/[^/]+\/bin\/node(\.exe)?$/.test(execPath)) {
-        return '/opt/homebrew/bin/node';
+    // Homebrew (macOS Intel /usr/local, Apple Silicon /opt/homebrew, Linuxbrew
+    // /home/linuxbrew/.linuxbrew, and any custom HOMEBREW_PREFIX) pins node at
+    // <prefix>/Cellar/node(<@ver>)?/<ver>/bin/node, then deletes prior versions on
+    // `brew upgrade node`. Rewrite to the stable <prefix>/bin/node symlink, which
+    // survives the upgrade. Derive <prefix> from the path itself (more reliable
+    // than HOMEBREW_PREFIX env — the path IS the install location) so every layout
+    // is covered by one branch instead of one per known prefix (#2185).
+    const homebrewMatch = normalizedForMatch.match(/^(.+)\/Cellar\/node(@\d+)?\/[^/]+\/bin\/node(\.exe)?$/i);
+    if (homebrewMatch) {
+        return `${homebrewMatch[1]}/bin/node${homebrewMatch[3] || ''}`;
     }
     // mise pins a concrete node version at <data>/installs/node/<ver>/bin/node
     // (Windows: <data>/installs/node/<ver>/node.exe). Node realpaths
@@ -304,6 +309,22 @@ function normalizeNodePath(execPath, opts) {
         if (existsSync(shim))
             return shim;
     }
+    // volta pins a concrete node image at <VOLTA_HOME>/tools/image/node/<ver>/bin/node
+    // (Windows: <VOLTA_HOME>/tools/image/node/<ver>/node.exe — volta's own layout
+    // puts node.exe at the image root, no bin/). `volta uninstall node@<ver>` prunes
+    // that image, so a baked hook command 404s — the same ephemeral-path failure
+    // #977 fixed for fnm and #1619 for mise. The stable alias is the shim
+    // <VOLTA_HOME>/bin/node, a symlink to volta-shim that always resolves to the
+    // active pin. Derive <VOLTA_HOME> from execPath rather than the env so a custom
+    // VOLTA_HOME and the Windows %LOCALAPPDATA%\Volta default both work (#2185's
+    // reasoning), and only rewrite when the shim exists — otherwise fall back to
+    // the raw execPath unchanged.
+    const voltaMatch = normalizedForMatch.match(/^(.*)\/tools\/image\/node\/[^/]+\/(?:bin\/)?node(\.exe)?$/);
+    if (voltaMatch) {
+        const shim = `${voltaMatch[1]}/bin/node${voltaMatch[2] || ''}`;
+        if (existsSync(shim))
+            return shim;
+    }
     return execPath;
 }
 function resolveNodeRunner(opts) {
@@ -311,7 +332,7 @@ function resolveNodeRunner(opts) {
     if (!execPath)
         return null;
     const stablePath = normalizeNodePath(execPath, opts);
-    return JSON.stringify(stablePath.replace(/\\/g, '/'));
+    return JSON.stringify(shellCmdProjection.posixNormalize(stablePath));
 }
 function resolveBashRunner(opts) {
     const platform = (opts && opts.platform) || process.platform;
@@ -332,7 +353,7 @@ function resolveBashRunner(opts) {
     }
     for (const candidate of candidates) {
         if (candidate && exists(candidate)) {
-            return JSON.stringify(candidate.replace(/\\/g, '/'));
+            return JSON.stringify(shellCmdProjection.posixNormalize(candidate));
         }
     }
     return null;
@@ -372,7 +393,7 @@ function rewriteLegacyManagedNodeHookCommands(settings, absoluteRunner, opts) {
                 }
                 else {
                     _runnerToken = m[1];
-                    const runnerPath = (m[2] || m[3] || m[4] || '').replace(/\\/g, '/');
+                    const runnerPath = shellCmdProjection.posixNormalize(m[2] || m[3] || m[4] || '');
                     const stableRunner = normalizeNodePath(runnerPath);
                     if (stableRunner === runnerPath && platform !== 'win32')
                         continue;
@@ -562,10 +583,10 @@ function buildCodexHookWindowsShimIR(scriptAbsPath, absoluteRunnerToken) {
     catch {
         interpreter = absoluteRunnerToken;
     }
-    const targetAbs = scriptAbsPath.replace(/\\/g, '/');
+    const targetAbs = shellCmdProjection.posixNormalize(scriptAbsPath);
     const scriptQuoted = JSON.stringify(targetAbs);
     const cmdPath = scriptAbsPath.replace(/\.js$/, '.cmd');
-    const hookCommand = JSON.stringify(cmdPath.replace(/\\/g, '/'));
+    const hookCommand = JSON.stringify(shellCmdProjection.posixNormalize(cmdPath));
     const runnerQuoted = JSON.stringify(interpreter);
     return {
         invocation: { interpreter, target: scriptAbsPath },
@@ -584,7 +605,7 @@ function ensureCodexHooksJsonSessionStart(targetDir, opts = {}) {
     const hooksJsonPath = node_path_1.default.join(targetDir, 'hooks.json');
     if (!absoluteRunner)
         return { changed: false, wrote: false, path: hooksJsonPath };
-    const scriptPath = node_path_1.default.resolve(targetDir, 'hooks', 'gsd-check-update.js').replace(/\\/g, '/');
+    const scriptPath = shellCmdProjection.posixNormalize(node_path_1.default.resolve(targetDir, 'hooks', 'gsd-check-update.js'));
     const cmdShimPath = scriptPath.replace(/\.js$/, '.cmd');
     let managedCommand;
     if (platform === 'win32') {
@@ -614,7 +635,7 @@ function ensureCodexHooksJsonSessionStart(targetDir, opts = {}) {
     if (!managedCommand)
         return { changed: false, wrote: false, path: hooksJsonPath };
     const commandWindows = platform === 'win32'
-        ? JSON.stringify(cmdShimPath.replace(/\\/g, '/'))
+        ? JSON.stringify(shellCmdProjection.posixNormalize(cmdShimPath))
         : undefined;
     return reconcileCodexHooksJsonSessionStart(targetDir, { managedCommand, commandWindows });
 }
@@ -624,7 +645,7 @@ function ensureCodexHooksJsonEvent(targetDir, eventName, opts = {}) {
     const hooksJsonPath = node_path_1.default.join(targetDir, 'hooks.json');
     if (!absoluteRunner)
         return { changed: false, wrote: false, path: hooksJsonPath };
-    const scriptPath = node_path_1.default.resolve(targetDir, 'hooks', 'gsd-context-monitor.js').replace(/\\/g, '/');
+    const scriptPath = shellCmdProjection.posixNormalize(node_path_1.default.resolve(targetDir, 'hooks', 'gsd-context-monitor.js'));
     let managedCommand;
     if (platform === 'win32') {
         const shimIR = buildCodexHookWindowsShimIR(scriptPath, absoluteRunner);
@@ -667,6 +688,7 @@ function buildHookCommand(configDir, hookName, opts) {
         opts = {};
     const platform = opts.platform || process.platform;
     const runtime = opts.runtime || 'generic';
+    const hookShell = opts.hookShell;
     const isShellHook = hookName.endsWith('.sh');
     if (shellHookOmitsBashRunner({ platform, runtime, isShellHook })) {
         if (opts.portableHooks) {
@@ -676,7 +698,7 @@ function buildHookCommand(configDir, hookName, opts) {
             });
             return JSON.stringify(`${portableBaseDir}/hooks/${hookName}`);
         }
-        return JSON.stringify(configDir.replace(/\\/g, '/') + '/hooks/' + hookName);
+        return JSON.stringify(shellCmdProjection.posixNormalize(configDir) + '/hooks/' + hookName);
     }
     const nodeRunner = resolveNodeRunner();
     const runner = isShellHook ? resolveBashRunner(opts) : nodeRunner;
@@ -692,14 +714,16 @@ function buildHookCommand(configDir, hookName, opts) {
             scriptPath: `${portableBaseDir}/hooks/${hookName}`,
             runtime: opts.runtime || 'generic',
             platform,
+            hookShell,
         });
     }
-    const hooksPath = configDir.replace(/\\/g, '/') + '/hooks/' + hookName;
+    const hooksPath = shellCmdProjection.posixNormalize(configDir) + '/hooks/' + hookName;
     return projectManagedHookCommand({
         absoluteRunner: runner,
         scriptPath: hooksPath,
         runtime,
         platform,
+        hookShell,
     });
 }
 // ---------------------------------------------------------------------------
@@ -844,7 +868,7 @@ function writeClineArtifacts(targetDir, isGlobalInstall) {
 function buildCursorHookEntry(scriptPath) {
     return {
         type: 'command',
-        command: scriptPath.replace(/\\/g, '/'),
+        command: shellCmdProjection.posixNormalize(scriptPath),
         [GSD_CURSOR_HOOK_MARKER]: true,
     };
 }

package/gsd-core/bin/lib/schema-detect.cjs

@@ -13,6 +13,7 @@ exports.ORM_INFO = exports.SCHEMA_PATTERNS = void 0;
 exports.detectSchemaFiles = detectSchemaFiles;
 exports.detectSchemaOrm = detectSchemaOrm;
 exports.checkSchemaDrift = checkSchemaDrift;
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 exports.SCHEMA_PATTERNS = [
     { pattern: /^src\/collections\/.*\.ts$/, orm: 'payload' },
     { pattern: /^src\/globals\/.*\.ts$/, orm: 'payload' },
@@ -61,7 +62,7 @@ function detectSchemaFiles(files) {
     const matches = [];
     const orms = new Set();
     for (const rawFile of files) {
-        const file = rawFile.replace(/\\/g, '/');
+        const file = (0, shell_command_projection_cjs_1.posixNormalize)(rawFile);
         for (const { pattern, orm } of exports.SCHEMA_PATTERNS) {
             if (pattern.test(file)) {
                 matches.push(rawFile);

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

@@ -341,7 +341,7 @@ function sanitizeForDisplay(text) {
     let sanitized = sanitizeForPrompt(text);
     const protocolLeakPatterns = [
         /^\s*(?:assistant|user|system)\s+to=[^:\s]+:[^\n]+$/i,
-        /^\s*<\|(?:assistant|user|system)[^|]*\|>\s*$/i,
+        /^\s*<\|(?:assistant|user|system)[^|]*\|>\s*$/i, // allow-adhoc-markdown: not a GFM table-cell scan — matches `<|role|>` protocol-leak marker tokens (prompt-injection sanitization), a false-positive on the table-regex pipe+cell-class fingerprint
     ];
     sanitized = sanitized
         .split('\n')

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

@@ -15,6 +15,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.toPosixPath = toPosixPath;
+exports.toNativePath = toNativePath;
+exports.posixNormalize = posixNormalize;
 exports.hookCommandNeedsPowerShellCallOperator = hookCommandNeedsPowerShellCallOperator;
 exports.formatHookCommandForRuntime = formatHookCommandForRuntime;
 exports.shellHookOmitsBashRunner = shellHookOmitsBashRunner;
@@ -52,26 +55,58 @@ const node_fs_1 = __importDefault(require("node:fs"));
 // can intercept calls from this seam — destructured imports capture references
 // at load time and become un-mockable.
 const node_child_process_1 = __importDefault(require("node:child_process"));
+/**
+ * Convert a filesystem path to POSIX form (forward slashes) by translating the
+ * platform-native separator. Single seam for native→POSIX conversion.
+ *
+ * Prefer this over `p.replace(/\\/g, '/')`: the regex form hardcodes both
+ * separators and corrupts POSIX paths containing a literal backslash (a legal
+ * filename character). Splitting on `path.sep` only ever touches real
+ * separators — a no-op on POSIX, `\`→`/` on Windows.
+ */
+function toPosixPath(p) {
+    return p.split(node_path_1.default.sep).join(node_path_1.default.posix.sep);
+}
+/**
+ * Convert a filesystem path to the platform-native separator form. No-op on
+ * POSIX; `/`→`\` on Windows. Prefer this over a
+ * `process.platform === 'win32' ? p.replace(/\//g, '\\') : p` ternary.
+ */
+function toNativePath(p) {
+    return p.split(node_path_1.default.posix.sep).join(node_path_1.default.sep);
+}
+/**
+ * Normalize ALL backslashes to forward slashes, unconditionally and independent
+ * of the running OS. Use this when emitting a path into a POSIX/bash target
+ * (which may differ from the running platform — e.g. generating a Windows config
+ * on a Linux runner) or when parsing input whose separators are unpredictable.
+ *
+ * Contrast `toPosixPath`, which is running-OS-relative (splits on `path.sep`) and
+ * is for *this machine's* filesystem paths. Do NOT use `toPosixPath` for
+ * target-platform projection — on a Linux runner it would not convert a
+ * Windows-target path's backslashes.
+ */
+function posixNormalize(p) {
+    return p.replace(/\\/g, '/');
+}
 /**
  * Return true when a managed hook command must be prefixed with PowerShell's
  * call operator so a quoted executable token is invokable by the target
  * runtime/shell combination.
  *
- * Current evidence-backed policy:
- * - Claude Code on Windows does NOT need it: its hook commands execute under
- *   bash/Git Bash and `& ` breaks there (#3413).
- * - #1928: Gemini CLI — the ONLY runtime with a verified need for the `& `
- *   prefix on Windows — was removed (Google sunset it 2026-06-18). No currently
- *   supported runtime has a verified need, so this seam is now inert. It is
- *   retained (not deleted) so a future runtime with a verified need is a
- *   one-line re-enable, per the conservative policy below. Note: Antigravity —
- *   the Gemini-backend successor — never matched the old `runtime === 'gemini'`
- *   check, so its behavior (no prefix) is unchanged.
+ * The `&`/no-`&` decision is keyed on the **effective hook-execution shell**
+ * (`opts.hookShell`), not on runtime alone — a single runtime (Claude Code)
+ * can host either Git Bash or PowerShell on Windows, and no single static
+ * command string is valid in both (#2236):
+ * - Git Bash: `"node.exe" "hook.js"` works; `& "node.exe" …` → syntax error.
+ * - PowerShell: `& "node.exe" "hook.js"` works; bare `"node.exe" …` →
+ *   `Unexpected token`.
  *
- * Keep the policy conservative until another runtime has a verified need.
+ * Default is `false` (Git Bash form) for backward compatibility. Set
+ * `opts.hookShell = 'powershell'` to emit the PowerShell call-operator form.
  */
-function hookCommandNeedsPowerShellCallOperator(_opts = {}) {
-    return false;
+function hookCommandNeedsPowerShellCallOperator(opts = {}) {
+    return opts.hookShell === 'powershell';
 }
 /**
  * Project a fully-assembled hook command string for the target runtime.
@@ -122,7 +157,7 @@ function formatManagedHookScriptToken(scriptPath, opts = {}) {
     const platform = opts.platform || process.platform;
     if (platform !== 'win32')
         return null;
-    return JSON.stringify(scriptPath.replace(/\\/g, '/'));
+    return JSON.stringify(posixNormalize(scriptPath));
 }
 function projectLocalHookPrefix({ runtime: _runtime = 'claude', dirName, hookPathStyle }) {
     if (!dirName)
@@ -140,29 +175,30 @@ function projectLocalHookPrefix({ runtime: _runtime = 'claude', dirName, hookPat
         : `"$CLAUDE_PROJECT_DIR"/${dirName}`;
 }
 function projectPortableHookBaseDir({ configDir, homeDir }) {
-    const normalizedConfigDir = String(configDir || '').replace(/\\/g, '/');
-    const normalizedHome = String(homeDir || '').replace(/\\/g, '/');
+    const normalizedConfigDir = posixNormalize(String(configDir || ''));
+    const normalizedHome = posixNormalize(String(homeDir || ''));
     if (!normalizedConfigDir || !normalizedHome)
         return normalizedConfigDir;
     return normalizedConfigDir.startsWith(normalizedHome)
         ? '$HOME' + normalizedConfigDir.slice(normalizedHome.length)
         : normalizedConfigDir;
 }
-function projectShellCommandText({ runnerToken, argTokens = [], runtime = 'generic', platform = process.platform, }) {
+function projectShellCommandText({ runnerToken, argTokens = [], runtime = 'generic', platform = process.platform, hookShell, }) {
     if (!runnerToken)
         return null;
     const parts = [runnerToken, ...argTokens.filter(Boolean)];
-    return formatHookCommandForRuntime(parts.join(' '), { platform, runtime });
+    return formatHookCommandForRuntime(parts.join(' '), { platform, runtime, hookShell });
 }
-function projectManagedHookCommand({ absoluteRunner, scriptPath, runtime = 'generic', platform = process.platform }) {
+function projectManagedHookCommand({ absoluteRunner, scriptPath, runtime = 'generic', platform = process.platform, hookShell }) {
     if (!absoluteRunner || !scriptPath)
         return null;
-    const normalizedScriptPath = platform === 'win32' ? scriptPath.replace(/\\/g, '/') : scriptPath;
+    const normalizedScriptPath = platform === 'win32' ? posixNormalize(scriptPath) : scriptPath;
     return projectShellCommandText({
         runnerToken: absoluteRunner,
         argTokens: [JSON.stringify(normalizedScriptPath)],
         runtime,
         platform,
+        hookShell,
     });
 }
 const MANAGED_HOOK_BASENAMES_BY_SURFACE = {
@@ -255,14 +291,14 @@ function isManagedHookCommand(commandText, opts = {}) {
         for (const arg of opts.args) {
             if (typeof arg !== 'string')
                 continue;
-            const argBasename = arg.replace(/\\/g, '/').split('/').pop() || '';
+            const argBasename = posixNormalize(arg).split('/').pop() || '';
             if (isManagedHookBasename(argBasename, { surface }))
                 return true;
         }
     }
-    const normalizedCommand = commandText.replace(/\\/g, '/');
+    const normalizedCommand = posixNormalize(commandText);
     if (typeof opts.configDir === 'string' && opts.configDir.length > 0) {
-        const normalizedHooksDir = `${node_path_1.default.join(opts.configDir, 'hooks').replace(/\\/g, '/')}/`;
+        const normalizedHooksDir = `${posixNormalize(node_path_1.default.join(opts.configDir, 'hooks'))}/`;
         if (!normalizedCommand.includes(normalizedHooksDir))
             return false;
     }
@@ -292,7 +328,7 @@ const ANCHORED_HOOK_SCRIPT_TOKEN = /^"\$[A-Za-z_][A-Za-z0-9_]*"\//;
 function projectLegacySettingsHookCommand({ absoluteRunner, scriptPath, scriptToken, runtime = 'generic', platform = process.platform, }) {
     if (!absoluteRunner || !scriptPath)
         return null;
-    const normalizedScriptPath = platform === 'win32' ? scriptPath.replace(/\\/g, '/') : scriptPath;
+    const normalizedScriptPath = platform === 'win32' ? posixNormalize(scriptPath) : scriptPath;
     // #1693: a script path already carrying a `"$CLAUDE_PROJECT_DIR"`-anchored
     // quoted prefix (local installs) is already a valid shell token — only the
     // variable is quoted, the rest is bare. JSON.stringify-ing it on Windows
@@ -350,7 +386,7 @@ function projectPathActionProjection({ mode = 'repair', targetDir, platform = pr
     let shellActions;
     if (isWin32) {
         const psTargetDir = escapePowerShellSingleQuoted(targetDir);
-        const bashTargetDir = escapeSingleQuotedShellLiteral(String(targetDir).replace(/\\/g, '/'));
+        const bashTargetDir = escapeSingleQuotedShellLiteral(posixNormalize(String(targetDir)));
         shellActions = [
             {
                 label: 'PowerShell',

package/gsd-core/bin/lib/smart-entry.cjs

@@ -42,6 +42,7 @@ exports.runSmartEntry = runSmartEntry;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_child_process_1 = require("node:child_process");
+const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const ioMod = require("./io.cjs");
 const { output } = ioMod;
@@ -51,6 +52,9 @@ const { planningPaths } = planningWorkspace;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const frontmatter = require("./frontmatter.cjs");
 const { extractFrontmatter } = frontmatter;
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-lifecycle.cjs is an export= CommonJS module
+const phaseLifecycle = require("./phase-lifecycle.cjs");
+const { deriveProgressFromRoadmap } = phaseLifecycle;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const stateDocument = require("./state-document.cjs");
 const { stateExtractField } = stateDocument;
@@ -244,6 +248,8 @@ function detectSignals(cwd, now = Date.now) {
         has_git: git.has_git,
         verify_failed: false,
         stale_activity: false,
+        roadmap_total_phases: null,
+        roadmap_completed_phases: null,
     };
     if (!hasPlanning)
         return empty;
@@ -274,9 +280,9 @@ function detectSignals(cwd, now = Date.now) {
         fmScalar(fm, body, 'progress', 'Progress');
     // Blockers list: `- <text>` items under a `## Blockers` heading.
     const blockers = [];
-    const blockersMatch = body.match(/##\s*Blockers\s*\n([\s\S]*?)(?=\n##|$)/i); // allow-adhoc-markdown: read-only blockers section-collect in smart-entry.cts; mirrors state.cts (#1372), pending collectSection migration
-    if (blockersMatch) {
-        const items = blockersMatch[1].match(/^-\s+(.+)$/gm) || [];
+    const blockersSection = (0, markdown_sectionizer_cjs_1.collectSection)(body, (h) => h.level === 2 && h.text.trim().toLowerCase() === 'blockers', { levelBounded: true });
+    if (blockersSection) {
+        const items = blockersSection.body.match(/^-\s+(.+)$/gm) || [];
         for (const item of items)
             blockers.push(item.replace(/^-\s+/, '').trim());
     }
@@ -290,6 +296,24 @@ function detectSignals(cwd, now = Date.now) {
     // STATUS: marker on the current phase's summary/verify artifact.
     const verifyFailed = /\bverify-fail(ed)?|verification-fail|uat-fail\b/i.test(statusRaw || '') ||
         detectVerifyFailed(cwd, currentPhaseRaw);
+    // #2427: derive global phase counts from ROADMAP.md's Progress table. These
+    // are preferred over STATE.md's cached milestone-scoped `total_phases` (which
+    // goes stale when phases are appended after a milestone switch) for the
+    // completion check. Null when ROADMAP.md is absent or has no parseable
+    // Progress table — isComplete falls back to the legacy comparison in that case.
+    let roadmapTotalPhases = null;
+    let roadmapCompletedPhases = null;
+    if (hasRoadmap) {
+        try {
+            const roadmapContent = node_fs_1.default.readFileSync(paths.roadmap, 'utf8');
+            const derived = deriveProgressFromRoadmap(roadmapContent);
+            roadmapTotalPhases = derived.totalPhases;
+            roadmapCompletedPhases = derived.completedPhases;
+        }
+        catch {
+            /* ROADMAP.md unreadable — leave null; isComplete falls back to legacy. */
+        }
+    }
     return {
         current_phase: parseIntOrNull(currentPhaseRaw),
         total_phases: parseIntOrNull(totalPhasesRaw),
@@ -304,14 +328,56 @@ function detectSignals(cwd, now = Date.now) {
         has_git: git.has_git,
         verify_failed: verifyFailed,
         stale_activity: staleActivity,
+        roadmap_total_phases: roadmapTotalPhases,
+        roadmap_completed_phases: roadmapCompletedPhases,
     };
 }
 // ─── Situation classification ─────────────────────────────────────────────────
-/** True when the workflow has fully completed all phases. */
+/**
+ * True when the workflow has fully completed all phases.
+ *
+ * #2427: completion is grounded in ROADMAP.md's Progress table (global,
+ * authoritative, never stale) when available, with a legacy fallback to
+ * STATE.md's cached `total_phases` when the roadmap has no parseable Progress
+ * table (e.g. a fresh project or a non-standard roadmap layout). The status
+ * regex was tightened to require milestone-level completion language
+ * (`milestone complete` / `all phases complete` / `complete(d)`) and no longer
+ * matches per-phase messages like "Phase X shipped — PR #N" that falsely
+ * satisfied the pre-fix alternation (`\bcomplete(d)?|done|shipped\b`).
+ */
 function isComplete(s) {
-    if (s.total_phases === null || s.current_phase === null)
-        return false;
-    return s.current_phase >= s.total_phases && /\bcomplete(d)?|done|shipped\b/i.test(s.status);
+    // Prefer ROADMAP-derived counts (global, authoritative) over STATE.md's
+    // cached milestone-scoped total_phases (stale-prone). Fall back to legacy
+    // when the roadmap has no Progress table.
+    if (s.roadmap_total_phases !== null && s.roadmap_completed_phases !== null) {
+        if (s.roadmap_total_phases === 0)
+            return false;
+        if (s.roadmap_completed_phases < s.roadmap_total_phases)
+            return false;
+    }
+    else {
+        // Legacy path: STATE.md comparison. Still subject to the two-scale bug,
+        // but only fires when ROADMAP.md is absent or has no Progress table.
+        if (s.total_phases === null || s.current_phase === null)
+            return false;
+        if (s.current_phase < s.total_phases)
+            return false;
+    }
+    // Status regex: require milestone-level completion language. The pre-fix
+    // regex matched any "shipped" / "done" substring (per-phase language).
+    // Tightened to match:
+    //   - "milestone complete" (ADR-2207 terminal status — usually written as
+    //     "<version> milestone complete", e.g. "v1.0 milestone complete"; the
+    //     substring match handles both forms)
+    //   - "all phases complete" (ADR-2207 intermediate terminal)
+    //   - "complete" / "completed" (legacy short form — STATE.md milestone
+    //     status is a single value, not a per-phase log)
+    // Intentionally does NOT match "done" alone even though normalizeStateStatus
+    // (state-document.cts) treats "done" as "completed" — in the milestone
+    // status field, "done" is per-phase noise (e.g. "Phase X done"), not a
+    // milestone-completion signal. Mirrors workstream-inventory-builder.cts's
+    // terminal pattern \bmilestone\s+complete\b.
+    return /\b(milestone\s+complete|all\s+phases\s+complete|complete(d)?)\b/i.test(s.status);
 }
 /** Idle-stranded: clean tree, committed work not shipped, optionally stale. */
 function isIdleStranded(s) {