@opengsd/gsd-core 1.16.0 → 1.17.0

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

@@ -295,6 +295,61 @@ function buildKiloAgentPermissionBlock(claudeTools) {
     }
     return lines;
 }
+// OpenCode agent tool restrictions (#5338, ADR-5331 D4). Claude's `tools:` allowlist and
+// `disallowedTools:` denylist become OpenCode `permission:` entries. The V1 `permission` form is the one
+// written because OpenCode 2.x translates it automatically ("legacy agent frontmatter … is translated"),
+// so one form serves both generations — verified: a `permission: {edit: deny, bash: deny}` agent drops the
+// edit/write/shell tools from the model's tool list on 1.18.29 and 2.0.27. Only denials are emitted: an
+// allowed tool keeps the user's own configured default instead of being forced to `allow`, and MCP tool
+// entries are not restricted.
+const claudeToOpencodePermission = {
+    Read: 'read',
+    Write: 'edit',
+    Edit: 'edit',
+    MultiEdit: 'edit',
+    NotebookEdit: 'edit',
+    Bash: 'bash',
+    Grep: 'grep',
+    Glob: 'glob',
+    WebFetch: 'webfetch',
+    WebSearch: 'websearch',
+    Task: 'task',
+    Agent: 'task',
+    Skill: 'skill',
+    SlashCommand: 'skill',
+    TodoWrite: 'todowrite',
+};
+const opencodeAgentPermissionOrder = ['read', 'edit', 'bash', 'grep', 'glob', 'webfetch', 'websearch', 'task', 'skill', 'todowrite'];
+/**
+ * `permission:` frontmatter lines for an OpenCode agent, or `[]` when the agent declares no tool
+ * restriction (an agent with neither `tools` nor `disallowedTools` inherits everything, as in Claude).
+ */
+function buildOpencodeAgentPermissionBlock(allowedTools, disallowedTools) {
+    const allowed = new Set();
+    for (const tool of allowedTools) {
+        const mapped = claudeToOpencodePermission[tool];
+        if (mapped)
+            allowed.add(mapped);
+    }
+    const denied = new Set();
+    if (allowedTools.length > 0) {
+        for (const permission of opencodeAgentPermissionOrder) {
+            if (!allowed.has(permission))
+                denied.add(permission);
+        }
+    }
+    for (const tool of disallowedTools) {
+        const mapped = claudeToOpencodePermission[tool];
+        if (mapped)
+            denied.add(mapped);
+    }
+    const lines = [];
+    for (const permission of opencodeAgentPermissionOrder) {
+        if (denied.has(permission))
+            lines.push(`  ${permission}: deny`);
+    }
+    return lines.length > 0 ? ['permission:', ...lines] : [];
+}
 function replaceRelativePathReference(content, fromPath, toPath) {
     const escapedPath = (0, pattern_cjs_1.escapeRegex)(fromPath);
     return content.replace(new RegExp(`(^|[^A-Za-z0-9_./-])${escapedPath}`, 'g'), (_, prefix) => `${prefix}${toPath}`);
@@ -1953,7 +2008,11 @@ function convertClaudeToOpencodeFrontmatter(content, { isAgent = false, modelOve
     const newLines = [];
     let inAllowedTools = false;
     let inSkippedArray = false;
+    let inAgentTools = false;
+    let inDisallowedTools = false;
     const allowedTools = [];
+    const agentTools = [];
+    const agentDisallowed = [];
     for (const line of lines) {
         const trimmed = line.trim();
         // For agents: skip commented-out lines (e.g. hooks blocks)
@@ -1965,11 +2024,31 @@ function convertClaudeToOpencodeFrontmatter(content, { isAgent = false, modelOve
             inAllowedTools = true;
             continue;
         }
+        // Agents: collect the `tools:` allowlist and `disallowedTools:` denylist (block-list continuation
+        // lines) so they can be rendered as `permission:` entries below.
+        if (isAgent && (inAgentTools || inDisallowedTools)) {
+            if (trimmed.startsWith('- ')) {
+                const tool = decodeToolScalar(trimmed.substring(2));
+                if (tool !== null)
+                    (inAgentTools ? agentTools : agentDisallowed).push(tool);
+                continue;
+            }
+            if (trimmed && !trimmed.startsWith('-')) {
+                inAgentTools = false;
+                inDisallowedTools = false;
+            }
+        }
         // Detect inline tools: field (comma-separated string)
         if (trimmed.startsWith('tools:')) {
             if (isAgent) {
-                // Agents: strip tools entirely (not supported in OpenCode agent frontmatter)
-                inSkippedArray = true;
+                const toolsValue = trimmed.substring(6).trim();
+                // A comment-only value (`tools: # note`) is not inline content: read the block list instead.
+                if (toolsValue && !toolsValue.startsWith('#')) {
+                    agentTools.push(...splitToolScalars(toolsValue).map(decodeToolScalar).filter((tool) => tool !== null));
+                }
+                else {
+                    inAgentTools = true;
+                }
                 continue;
             }
             const toolsValue = trimmed.substring(6).trim();
@@ -1980,8 +2059,18 @@ function convertClaudeToOpencodeFrontmatter(content, { isAgent = false, modelOve
             }
             continue;
         }
-        // For agents: strip skills:, color:, memory:, maxTurns:, permissionMode:, disallowedTools:
-        if (isAgent && /^(skills|color|memory|maxTurns|permissionMode|disallowedTools):/.test(trimmed)) {
+        if (isAgent && trimmed.startsWith('disallowedTools:')) {
+            const value = trimmed.substring(16).trim();
+            if (value && !value.startsWith('#')) {
+                agentDisallowed.push(...splitToolScalars(value).map(decodeToolScalar).filter((tool) => tool !== null));
+            }
+            else {
+                inDisallowedTools = true;
+            }
+            continue;
+        }
+        // For agents: strip skills:, color:, memory:, maxTurns:, permissionMode:
+        if (isAgent && /^(skills|color|memory|maxTurns|permissionMode):/.test(trimmed)) {
             inSkippedArray = true;
             continue;
         }
@@ -2065,6 +2154,7 @@ function convertClaudeToOpencodeFrontmatter(content, { isAgent = false, modelOve
         if (variant) {
             newLines.push(frontmatterScalar('variant:', variant));
         }
+        newLines.push(...buildOpencodeAgentPermissionBlock(agentTools, agentDisallowed));
     }
     // For commands: add tools object if we had allowed-tools or tools
     if (!isAgent && allowedTools.length > 0) {
@@ -3816,6 +3906,7 @@ module.exports = {
     convertClaudeToOpencodeFrontmatter,
     convertClaudeToKiloFrontmatter,
     _decodeToolScalar: decodeToolScalar,
+    _buildOpencodeAgentPermissionBlock: buildOpencodeAgentPermissionBlock,
     _splitToolScalars: splitToolScalars,
     readGsdCommandNames,
     transformContentToHyphen,

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

@@ -992,7 +992,16 @@ function buildCodexHookWindowsShimIR(scriptAbsPath, absoluteRunnerToken) {
     const scriptQuoted = JSON.stringify(targetAbs);
     const cmdPath = scriptAbsPath.replace(/\.js$/, '.cmd');
     const hookCommand = JSON.stringify(shellCmdProjection.posixNormalize(cmdPath));
-    const runnerQuoted = JSON.stringify(interpreter);
+    // #4838: node is resolved when the hook fires. The install-time path dies when a
+    // version manager (WinGet) removes the versioned directory on upgrade, and a
+    // shim that only knew that path failed silently until the installer re-ran.
+    // Order: explicit GSD_NODE_PATH; the install-time path while it still exists
+    // (keeps the #3662 minimal-PATH guarantee); node.exe on PATH. `where $PATH:`
+    // searches PATH only, never the current directory, so repo content cannot
+    // become the runner. `%` is doubled so cmd.exe cannot expand a variable out
+    // of an install path.
+    const bakedBat = JSON.stringify(interpreter).slice(1, -1).replace(/%/g, '%%');
+    const scriptBat = scriptQuoted.replace(/%/g, '%%');
     return {
         invocation: { interpreter, target: scriptAbsPath },
         cmdPath,
@@ -1000,7 +1009,16 @@ function buildCodexHookWindowsShimIR(scriptAbsPath, absoluteRunnerToken) {
         eol: { cmd: '\r\n' },
         passthroughArgs: true,
         render: {
-            cmd: () => `@ECHO OFF\r\n@SETLOCAL\r\n@${runnerQuoted} ${scriptQuoted} %*\r\n`,
+            cmd: () => [
+                '@ECHO OFF',
+                '@SETLOCAL',
+                '@SET "GSD_NODE="',
+                '@IF DEFINED GSD_NODE_PATH IF EXIST "%GSD_NODE_PATH%" SET "GSD_NODE=%GSD_NODE_PATH%"',
+                `@IF NOT DEFINED GSD_NODE IF EXIST "${bakedBat}" SET "GSD_NODE=${bakedBat}"`,
+                '@IF NOT DEFINED GSD_NODE FOR /F "delims=" %%N IN (\'where $PATH:node.exe 2^>NUL\') DO @IF NOT DEFINED GSD_NODE SET "GSD_NODE=%%N"',
+                `@"%GSD_NODE%" ${scriptBat} %*`,
+                '',
+            ].join('\r\n'),
         },
     };
 }
@@ -2279,6 +2297,35 @@ function pushHookGroup(entries, matcher, command, timeout) {
         hook['timeout'] = timeout;
     entries.push(matcher === undefined ? { hooks: [hook] } : { matcher, hooks: [hook] });
 }
+/** #4840: the hook that reads the statusline's metrics bridge file. */
+const CONTEXT_MONITOR_HOOK = 'gsd-context-monitor.js';
+/**
+ * #4840: remove GSD-managed registrations of `stem` from one event's groups,
+ * leaving user-authored hooks (even in the same group) untouched. Returns
+ * whether anything was removed. A group left with no hooks is dropped.
+ */
+function stripManagedHookRegistrations(entries, stem) {
+    let removed = false;
+    for (let i = entries.length - 1; i >= 0; i--) {
+        const entry = entries[i];
+        if (!entry || !Array.isArray(entry.hooks))
+            continue;
+        const kept = entry.hooks.filter((h) => {
+            const managed = referencesHook(h, stem)
+                && isManagedHookCommand(h.command, { surface: 'settings-json', includeLegacyAliases: true });
+            if (managed)
+                removed = true;
+            return !managed;
+        });
+        if (kept.length === entry.hooks.length)
+            continue;
+        if (kept.length === 0)
+            entries.splice(i, 1);
+        else
+            entry.hooks = kept;
+    }
+    return removed;
+}
 function applySettingsJsonHookTables(settings, opts, tables) {
     const { runtime, postToolEvent, hookEvents, extendedHookEvents, hooksSurface, targetDir, hookOpts } = opts;
     // ADR-857 phase 5f-3: extended hook events are driven by the registry
@@ -2326,6 +2373,12 @@ function applySettingsJsonHookTables(settings, opts, tables) {
             settings.hooks[key] = [];
         }
         const entries = settings.hooks[key];
+        if (row.file === CONTEXT_MONITOR_HOOK && opts.contextWarnings === false) {
+            if (stripManagedHookRegistrations(entries, hookStem(row.file))) {
+                console.log(`  ${green}✓${reset} Removed stale context monitor hook (${_capabilityTitle(runtime)} has no context metrics writer, #4840)`);
+            }
+            continue;
+        }
         const command = resolveRowCommand(row, opts);
         if ('build' in row.command && row.command.build === 'sh')
             shellCommands[row.file] = command;
@@ -2468,7 +2521,8 @@ function buildKimiHooksTomlBlock(targetDir, opts) {
         { event: 'PreToolUse', command: cmd('gsd-workflow-guard.js'), matcher: 'Shell|WriteFile|StrReplaceFile', timeout: kimiBlockingGuardTimeout('gsd-workflow-guard.js') },
         { event: 'PreToolUse', command: cmd('gsd-validate-commit.sh'), matcher: 'Shell', timeout: kimiBlockingGuardTimeout('gsd-validate-commit.sh') },
         // PostToolUse
-        { event: 'PostToolUse', command: cmd('gsd-context-monitor.js'), timeout: 10 },
+        // #4840: no metrics writer on kimi, so the warning registration is skipped (a block from an earlier install is replaced wholesale).
+        { event: 'PostToolUse', command: opts.contextWarnings === false ? null : cmd('gsd-context-monitor.js'), timeout: 10 },
         { event: 'PostToolUse', command: cmd('gsd-phase-boundary.sh'), matcher: 'WriteFile|StrReplaceFile', timeout: 5 },
         { event: 'PostToolUse', command: cmd('gsd-read-injection-scanner.js'), matcher: 'ReadFile', timeout: 5 },
         { event: 'PostToolUse', command: cmd('gsd-graphify-update.sh'), matcher: 'Shell', timeout: 5 },
@@ -2541,6 +2595,7 @@ function stripKimiHooksTomlBlock(content) {
 function writeKimiHooksToml(configPath, targetDir, opts) {
     const configuredEntrypoints = [];
     const trackedOpts = {
+        contextWarnings: opts.contextWarnings,
         hookOpts: {
             ...opts.hookOpts,
             configPath,

package/gsd-core/bin/lib/runtime-slash.cjs

@@ -36,6 +36,7 @@ exports.resolveExplicitRuntime = resolveExplicitRuntime;
 exports.resolveRuntime = resolveRuntime;
 exports.resolveActiveRuntime = resolveActiveRuntime;
 exports.formatGsdSlashFor = formatGsdSlashFor;
+exports.runtimeCommand = runtimeCommand;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const runtime_name_policy_cjs_1 = require("./runtime-name-policy.cjs");
@@ -227,3 +228,15 @@ function resolveActiveRuntime(config, env = process.env) {
 function formatGsdSlashFor(projectDir, commandName) {
     return formatGsdSlash(commandName, resolveRuntime(projectDir));
 }
+/**
+ * #4859: the command as the project's runtime registers it, typed as a string —
+ * for runtime code that builds user-facing guidance. String literals in compiled
+ * runtime code are printed verbatim (the install-time conversion only rewrites
+ * markdown artifact bodies), so a hard-coded `/gsd:<cmd>` names a command no
+ * install route registers. Route every such reference through here:
+ * `runtimeCommand(cwd, 'plan-phase 3 --research')` → `/gsd-plan-phase 3 --research`
+ * (`$gsd-plan-phase …` on Codex). `commandName` is the bare name plus any argument tail.
+ */
+function runtimeCommand(projectDir, commandName) {
+    return String(formatGsdSlashFor(projectDir, commandName));
+}

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

@@ -43,6 +43,7 @@ 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");
+const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
 // #3696: the calendar-validity predicate moved to the STATE.md document module
 // so `state validate` can assert the same `last_activity` invariant this reader
 // already enforces (ADR-227). Two copies would let the two surfaces disagree
@@ -52,7 +53,7 @@ const ioMod = require("./io.cjs");
 const { output } = ioMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
-const { planningPaths } = planningWorkspace;
+const { planningPaths, resolvePhaseIdConvention } = planningWorkspace;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const frontmatter = require("./frontmatter.cjs");
 const { extractFrontmatter, frontmatterBlock } = frontmatter;
@@ -60,6 +61,9 @@ const { extractFrontmatter, frontmatterBlock } = frontmatter;
 const phaseLifecycle = require("./phase-lifecycle.cjs");
 const { deriveProgressFromRoadmap } = phaseLifecycle;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
+const roadmapParser = require("./roadmap-parser.cjs");
+const { extractCurrentMilestone, scanMilestonePhaseIds } = roadmapParser;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
 const stateDocument = require("./state-document.cjs");
 const { stateFieldValue } = stateDocument;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -352,6 +356,7 @@ function detectSignals(cwd, now = Date.now) {
         stale_activity: false,
         roadmap_total_phases: null,
         roadmap_completed_phases: null,
+        milestone_phases: [],
         // No STATE.md (or unreadable) → no stamp to compare. Unknown, not fresh.
         state_commits_behind: null,
         state_commit_stale: null,
@@ -425,12 +430,18 @@ function detectSignals(cwd, now = Date.now) {
     // Progress table — isComplete falls back to the legacy comparison in that case.
     let roadmapTotalPhases = null;
     let roadmapCompletedPhases = null;
+    let milestonePhases = [];
     if (hasRoadmap) {
         try {
             const roadmapContent = node_fs_1.default.readFileSync(paths.roadmap, 'utf8');
             const derived = deriveProgressFromRoadmap(roadmapContent);
             roadmapTotalPhases = derived.totalPhases;
             roadmapCompletedPhases = derived.completedPhases;
+            // #5228: the ordered phase list of the current milestone, from the same
+            // scan the milestone-scoped commands use.
+            milestonePhases = [
+                ...scanMilestonePhaseIds(extractCurrentMilestone(roadmapContent, cwd), resolvePhaseIdConvention(cwd)),
+            ].sort(comparePhaseNum);
         }
         catch {
             /* ROADMAP.md unreadable — leave null; isComplete falls back to legacy. */
@@ -457,6 +468,7 @@ function detectSignals(cwd, now = Date.now) {
         stale_activity: staleActivity,
         roadmap_total_phases: roadmapTotalPhases,
         roadmap_completed_phases: roadmapCompletedPhases,
+        milestone_phases: milestonePhases,
         state_commits_behind: freshness.commits_behind,
         state_commit_stale: freshness.commit_stale,
     };
@@ -488,10 +500,21 @@ function isComplete(s) {
         // Legacy path: STATE.md comparison. It only fires when ROADMAP.md is
         // absent or has no Progress table, and uses canonical phase-id ordering
         // so dotted phase ids are never coerced to JavaScript numbers.
-        if (s.total_phases === null || s.current_phase === null)
-            return false;
-        if (comparePhaseNum(s.current_phase, s.total_phases) < 0)
+        if (s.current_phase === null)
             return false;
+        if (s.milestone_phases.length > 0) {
+            // #5228: compare against the milestone's LAST phase. The phase count is
+            // not a phase number once numbering continues from an earlier milestone.
+            const last = s.milestone_phases[s.milestone_phases.length - 1];
+            if (comparePhaseNum(s.current_phase, last) < 0)
+                return false;
+        }
+        else {
+            if (s.total_phases === null)
+                return false;
+            if (comparePhaseNum(s.current_phase, s.total_phases) < 0)
+                return false;
+        }
     }
     // Status regex: require milestone-level completion language. The pre-fix
     // regex matched any "shipped" / "done" substring (per-phase language).
@@ -558,52 +581,54 @@ function rec(id, label, command) {
     return action(id, label, command, true);
 }
 /** Per-situation ordered action list; recommended action first. */
-function actionsFor(situation, s) {
+function actionsFor(situation, s, runtime = 'claude') {
+    // #4859: commands are printed verbatim, so name them the way this runtime registers them.
+    const cmd = (name) => (0, runtime_slash_cjs_1.formatGsdSlash)(name, runtime);
     const phaseN = s.current_phase ?? '';
     const execLabel = phaseN === '' ? 'Continue executing' : `Continue executing phase ${phaseN}`;
     switch (situation) {
         case 'no-project':
             return [
-                rec('new-project', 'Start a new project', '/gsd:new-project'),
-                action('map-codebase', 'Map an existing codebase', '/gsd:map-codebase'),
-                action('quick', 'Quick task', '/gsd:quick'),
-                action('help', 'Show help', '/gsd:help'),
+                rec('new-project', 'Start a new project', cmd('new-project')),
+                action('map-codebase', 'Map an existing codebase', cmd('map-codebase')),
+                action('quick', 'Quick task', cmd('quick')),
+                action('help', 'Show help', cmd('help')),
             ];
         case 'paused':
             return [
-                rec('resume-work', 'Resume work', '/gsd:resume-work'),
-                action('progress', 'Show progress', '/gsd:progress'),
-                action('quick', 'Quick task', '/gsd:quick'),
-                action('help', 'Show help', '/gsd:help'),
+                rec('resume-work', 'Resume work', cmd('resume-work')),
+                action('progress', 'Show progress', cmd('progress')),
+                action('quick', 'Quick task', cmd('quick')),
+                action('help', 'Show help', cmd('help')),
             ];
         case 'blocked':
             return [
-                rec('debug', 'Debug the blocker', '/gsd:debug'),
-                action('verify-work', 'Verify current work', '/gsd:verify-work'),
-                action('capture', 'Capture a note', '/gsd:capture'),
-                action('progress', 'Show progress', '/gsd:progress'),
+                rec('debug', 'Debug the blocker', cmd('debug')),
+                action('verify-work', 'Verify current work', cmd('verify-work')),
+                action('capture', 'Capture a note', cmd('capture')),
+                action('progress', 'Show progress', cmd('progress')),
             ];
         case 'verify-failed':
             return [
-                rec('verify-work', 'Re-verify work', '/gsd:verify-work'),
-                action('debug', 'Debug the failure', '/gsd:debug'),
-                action('code-review', 'Review recent work', '/gsd:code-review'),
-                action('progress', 'Show progress', '/gsd:progress'),
+                rec('verify-work', 'Re-verify work', cmd('verify-work')),
+                action('debug', 'Debug the failure', cmd('debug')),
+                action('code-review', 'Review recent work', cmd('code-review')),
+                action('progress', 'Show progress', cmd('progress')),
             ];
         case 'needs-first-phase':
             return [
-                rec('discuss-phase', 'Discuss the first phase', '/gsd:discuss-phase'),
-                action('plan-phase', 'Plan phase 1', '/gsd:plan-phase'),
-                action('quick', 'Quick task', '/gsd:quick'),
-                action('progress', 'Show progress', '/gsd:progress'),
+                rec('discuss-phase', 'Discuss the first phase', cmd('discuss-phase')),
+                action('plan-phase', 'Plan phase 1', cmd('plan-phase')),
+                action('quick', 'Quick task', cmd('quick')),
+                action('progress', 'Show progress', cmd('progress')),
             ];
         case 'planning':
             // Forward motion → delegate to the single gated engine (see 'executing').
             return [
-                rec('progress-next', `Advance to the next step (plan phase ${phaseN || 1})`, '/gsd:progress --next'),
-                action('plan-phase', `Plan phase ${phaseN || 1}`, '/gsd:plan-phase'),
-                action('discuss-phase', 'Discuss before planning', '/gsd:discuss-phase'),
-                action('progress', 'Show progress', '/gsd:progress'),
+                rec('progress-next', `Advance to the next step (plan phase ${phaseN || 1})`, cmd('progress --next')),
+                action('plan-phase', `Plan phase ${phaseN || 1}`, cmd('plan-phase')),
+                action('discuss-phase', 'Discuss before planning', cmd('discuss-phase')),
+                action('progress', 'Show progress', cmd('progress')),
             ];
         case 'executing':
             // In-project forward motion delegates to the single gated engine
@@ -612,40 +637,40 @@ function actionsFor(situation, s) {
             // /gsd:execute-phase here — that divergence is why the old flat /gsd-next
             // was removed (#3054). Direct execute stays as an explicit secondary choice.
             return [
-                rec('progress-next', 'Advance to the next step', '/gsd:progress --next'),
-                action('execute-phase', execLabel, '/gsd:execute-phase'),
-                action('quick', 'Quick task', '/gsd:quick'),
-                action('code-review', 'Review recent work', '/gsd:code-review'),
+                rec('progress-next', 'Advance to the next step', cmd('progress --next')),
+                action('execute-phase', execLabel, cmd('execute-phase')),
+                action('quick', 'Quick task', cmd('quick')),
+                action('code-review', 'Review recent work', cmd('code-review')),
             ];
         case 'verify-pending':
             // Forward motion → delegate to the single gated engine (see 'executing').
             return [
-                rec('progress-next', 'Advance to the next step (verify)', '/gsd:progress --next'),
-                action('verify-work', 'Verify work', '/gsd:verify-work'),
-                action('code-review', 'Review recent work', '/gsd:code-review'),
-                action('ship', 'Ship completed work', '/gsd:ship'),
+                rec('progress-next', 'Advance to the next step (verify)', cmd('progress --next')),
+                action('verify-work', 'Verify work', cmd('verify-work')),
+                action('code-review', 'Review recent work', cmd('code-review')),
+                action('ship', 'Ship completed work', cmd('ship')),
             ];
         case 'idle-stranded':
             return [
-                rec('ship', 'Ship committed work', '/gsd:ship'),
-                action('complete-milestone', 'Complete the milestone', '/gsd:complete-milestone'),
-                action('progress', 'Show progress', '/gsd:progress'),
-                action('capture', 'Capture a note', '/gsd:capture'),
+                rec('ship', 'Ship committed work', cmd('ship')),
+                action('complete-milestone', 'Complete the milestone', cmd('complete-milestone')),
+                action('progress', 'Show progress', cmd('progress')),
+                action('capture', 'Capture a note', cmd('capture')),
             ];
         case 'complete':
             return [
-                rec('new-milestone', 'Start a new milestone', '/gsd:new-milestone'),
-                action('extract-learnings', 'Extract learnings', '/gsd:extract-learnings'),
-                action('quick', 'Quick task', '/gsd:quick'),
-                action('progress', 'Show progress', '/gsd:progress'),
+                rec('new-milestone', 'Start a new milestone', cmd('new-milestone')),
+                action('extract-learnings', 'Extract learnings', cmd('extract-learnings')),
+                action('quick', 'Quick task', cmd('quick')),
+                action('progress', 'Show progress', cmd('progress')),
             ];
         case 'unknown':
         default:
             return [
-                rec('progress', 'Show progress', '/gsd:progress'),
-                action('progress-next', 'Advance to the next step', '/gsd:progress --next'),
-                action('quick', 'Quick task', '/gsd:quick'),
-                action('help', 'Show help', '/gsd:help'),
+                rec('progress', 'Show progress', cmd('progress')),
+                action('progress-next', 'Advance to the next step', cmd('progress --next')),
+                action('quick', 'Quick task', cmd('quick')),
+                action('help', 'Show help', cmd('help')),
             ];
     }
 }
@@ -663,7 +688,7 @@ function buildSummary(situation, s) {
         case 'needs-first-phase':
             return 'Project initialized — plan your first phase';
         case 'planning':
-            return `Phase ${s.current_phase ?? '?'} of ${s.total_phases ?? '?'} — needs a plan`;
+            return `${phasePosition(s)} — needs a plan`;
         case 'executing':
             return progressLine('executing', s);
         case 'verify-pending':
@@ -677,10 +702,24 @@ function buildSummary(situation, s) {
             return 'Unsure of state — showing progress';
     }
 }
+/**
+ * "Phase N of M" for the current phase. N is the phase's 1-based position in
+ * the current milestone's ordered phase list (#5228), so a milestone that
+ * continues the numbering of an earlier one (phases 9-17) reads "Phase 1 of 9",
+ * not "Phase 9 of 9". When the phase is not in that list (or the roadmap lists
+ * none) the STATE.md figures are printed as recorded.
+ */
+function phasePosition(s) {
+    const current = s.current_phase;
+    const at = current === null ? -1 : s.milestone_phases.findIndex((id) => comparePhaseNum(id, current) === 0);
+    if (at >= 0)
+        return `Phase ${at + 1} of ${s.milestone_phases.length}`;
+    return `Phase ${s.current_phase ?? '?'} of ${s.total_phases ?? '?'}`;
+}
 function progressLine(tail, s) {
     const parts = [];
     if (s.current_phase !== null && s.total_phases !== null) {
-        parts.push(`Phase ${s.current_phase} of ${s.total_phases}`);
+        parts.push(phasePosition(s));
     }
     else if (s.current_phase !== null) {
         parts.push(`Phase ${s.current_phase}`);
@@ -699,7 +738,7 @@ function progressLine(tail, s) {
 function classifyProject(cwd, now = Date.now) {
     const signals = detectSignals(cwd, now);
     const situation = classify(signals);
-    const actions = actionsFor(situation, signals);
+    const actions = actionsFor(situation, signals, (0, runtime_slash_cjs_1.resolveRuntime)(cwd));
     const recommended = actions.find((a) => a.recommended)?.id ?? 'progress';
     const summary = buildSummary(situation, signals);
     return { situation, recommended, summary, signals, actions };
@@ -718,6 +757,6 @@ function runSmartEntry(cwd, args, raw) {
         return;
     }
     // Human mode: a compact one-liner plus the recommended action.
-    const human = `${result.summary}\nRecommended: ${result.recommended} → ${result.actions.find((a) => a.id === result.recommended)?.command ?? '/gsd:progress'}`;
+    const human = `${result.summary}\nRecommended: ${result.recommended} → ${result.actions.find((a) => a.id === result.recommended)?.command ?? (0, runtime_slash_cjs_1.runtimeCommand)(cwd, 'progress')}`;
     output(null, true, human);
 }