@opengsd/gsd-core 1.8.0 → 1.9.0

package/gsd-core/bin/lib/host-integration.cjs

@@ -37,7 +37,32 @@ const HOST_INTEGRATION_AXES = Object.freeze({
     stateIO: Object.freeze(['filesystem', 'sandboxed-storage', 'session-log-append']),
     transport: Object.freeze(['mcp', 'native-extension']),
     runtime: Object.freeze(['node', 'bun', 'sandboxed-web', 'python', 'go', 'rust', 'electron', 'other']),
-    subagentToolkit: Object.freeze(['full', 'read-only']),
+    subagentToolkit: Object.freeze(['full', 'read-only', 'built-in-only']),
+    // ADR-1239 amendment (#2481): how reasoning effort reaches this host.
+    // `argv` — deliverable as an argument on the host's own invocation.
+    // `none` — the host exposes no reasoning-effort mechanism.
+    // `undocumented` is NOT a member here; it is the corpus-wide sentinel above.
+    // A config-file-only surface deliberately has NO vocabulary member: the only
+    // host that ever had one (Gemini CLI's thinkingConfig) was removed as a sunset
+    // runtime in #1928/#1996, and neither its successor Antigravity CLI nor ZCode
+    // documents a reasoning setting. Adding a member with no host would be a guess.
+    effortSurface: Object.freeze(['argv', 'none']),
+    // ADR-1239 Codex-binding amendment (#2584): a `dispatch` sub-field — not a new
+    // axis — declaring how a host isolates concurrent same-wave executors.
+    // `harness-worktree` — the host's own harness creates + binds a git worktree
+    // per executor; GSD passes the host's own isolation flag and calls no git
+    // itself (host-driven fan-out).
+    // `orchestrator-worktree` — GSD itself process-spawns each executor with an
+    // explicit working directory into a worktree GSD created, validated, and
+    // merges (GSD-driven fan-out; concurrency is OS-level, not the host's).
+    // `none` — no isolation primitive; same-wave plans run inline/sequentially
+    // (the #853 flatten rule).
+    // `undocumented` is NOT a member here; it is the corpus-wide sentinel above.
+    // Mechanism-specific ("worktree"), not abstract — same "name only what a
+    // host actually has" rule that kept effortSurface from guessing a
+    // config-file member above. A future non-worktree isolation mechanism adds a
+    // `*-container` member then, evidence-backed.
+    isolation: Object.freeze(['harness-worktree', 'orchestrator-worktree', 'none']),
 });
 const INTERFACE_POINTS = Object.freeze(['command', 'dispatch', 'model', 'hooks', 'state', 'artifact']);
 // ---------------------------------------------------------------------------
@@ -47,43 +72,47 @@ const INTERFACE_POINTS = Object.freeze(['command', 'dispatch', 'model', 'hooks',
 const SAFE_DEFAULTS = {
     embeddingMode: 'declarative',
     commandSurface: 'prose-only',
-    dispatch: { namedDispatch: false, nested: false, maxDepth: 0, background: false, subagentToolkit: 'read-only', backgroundDispatch: false },
+    dispatch: { namedDispatch: false, nested: false, maxDepth: 0, background: false, subagentToolkit: 'read-only', backgroundDispatch: false, isolation: 'none' },
     modelMode: 'passive',
     hookBus: 'none',
     stateIO: 'session-log-append',
     transport: 'mcp',
     runtime: 'node',
+    effortSurface: 'none',
 };
 const PROFILE_BASELINES = Object.freeze({
     'programmatic-cli': Object.freeze({
         embeddingMode: 'imperative',
         commandSurface: 'slash-file',
-        dispatch: Object.freeze({ namedDispatch: true, nested: true, maxDepth: -1, background: true, subagentToolkit: 'full', backgroundDispatch: true }),
+        dispatch: Object.freeze({ namedDispatch: true, nested: true, maxDepth: -1, background: true, subagentToolkit: 'full', backgroundDispatch: true, isolation: 'none' }),
         modelMode: 'passive',
         hookBus: 'host',
         stateIO: 'filesystem',
         transport: 'mcp',
         runtime: 'node',
+        effortSurface: 'none',
     }),
     'declarative-cli': Object.freeze({
         embeddingMode: 'declarative',
         commandSurface: 'slash-file',
-        dispatch: Object.freeze({ namedDispatch: true, nested: false, maxDepth: 1, background: false, subagentToolkit: 'full', backgroundDispatch: false }),
+        dispatch: Object.freeze({ namedDispatch: true, nested: false, maxDepth: 1, background: false, subagentToolkit: 'full', backgroundDispatch: false, isolation: 'none' }),
         modelMode: 'passive',
         hookBus: 'host',
         stateIO: 'filesystem',
         transport: 'mcp',
         runtime: 'node',
+        effortSurface: 'none',
     }),
     'ide': Object.freeze({
         embeddingMode: 'imperative',
         commandSurface: 'palette',
-        dispatch: Object.freeze({ namedDispatch: true, nested: true, maxDepth: 5, background: true, subagentToolkit: 'full', backgroundDispatch: true }),
+        dispatch: Object.freeze({ namedDispatch: true, nested: true, maxDepth: 5, background: true, subagentToolkit: 'full', backgroundDispatch: true, isolation: 'none' }),
         modelMode: 'active',
         hookBus: 'engine',
         stateIO: 'sandboxed-storage',
         transport: 'mcp',
         runtime: 'sandboxed-web',
+        effortSurface: 'none',
     }),
 });
 // ---------------------------------------------------------------------------
@@ -136,6 +165,13 @@ function degradationFor(point, axes) {
             return { level: 'degraded', fallback: 'flat dispatch — waves run inline' };
         }
         case 'model': {
+            // NOTE (#2481): the effortSurface axis is deliberately NOT folded into this
+            // level. `modelMode` has graded interface point 3 since Phase A, and every
+            // existing consumer reads it as "can GSD drive model selection". Widening it
+            // to also mean "…and deliver effort" silently redefines an established
+            // contract — an `active` host with no declared effort surface would flip
+            // from `full` to `absent`. Effort is negotiated on its own axis and read
+            // from `effective.effortSurface` by the consumers that care.
             const mm = axes.modelMode;
             if (mm === 'active')
                 return { level: 'full', fallback: '' };
@@ -199,12 +235,13 @@ const DEFAULT_ENGINE = {
     axes: {
         embeddingMode: 'imperative',
         commandSurface: 'slash-file',
-        dispatch: { namedDispatch: true, nested: true, maxDepth: -1, background: true, subagentToolkit: 'full', backgroundDispatch: true },
+        dispatch: { namedDispatch: true, nested: true, maxDepth: -1, background: true, subagentToolkit: 'full', backgroundDispatch: true, isolation: 'none' },
         modelMode: 'active',
         hookBus: 'host',
         stateIO: 'filesystem',
         transport: 'mcp',
         runtime: 'node',
+        effortSurface: 'argv',
     },
     known: HOST_INTEGRATION_AXES,
 };
@@ -264,6 +301,15 @@ function negotiateHostCapabilities(host, engine = DEFAULT_ENGINE) {
             if (hostVal === 'active' && engineVal === 'passive')
                 return 'passive';
         }
+        // For effortSurface: 'argv' > 'none'. An engine that cannot deliver the
+        // host's richer channel caps the result to what it can drive.
+        if (axis === 'effortSurface') {
+            const RANK = { argv: 1, none: 0 };
+            const hr = RANK[hostVal] ?? 0;
+            const er = RANK[engineVal] ?? 0;
+            if (hr > er)
+                return engineVal;
+        }
         return hostVal;
     }
     // Negotiate all scalar axes
@@ -274,6 +320,7 @@ function negotiateHostCapabilities(host, engine = DEFAULT_ENGINE) {
     const effectiveStateIO = negotiateScalar('stateIO');
     const effectiveTransport = negotiateScalar('transport');
     const effectiveRuntime = negotiateScalar('runtime');
+    const effectiveEffortSurface = negotiateScalar('effortSurface');
     // ---------------------------------------------------------------------------
     // Dispatch struct negotiation
     // ---------------------------------------------------------------------------
@@ -287,6 +334,7 @@ function negotiateHostCapabilities(host, engine = DEFAULT_ENGINE) {
     let effectiveBackgroundDispatch;
     let effectiveSubagentToolkit;
     let effectiveMaxDepth;
+    let effectiveIsolation;
     if (hostDispatch === null) {
         // Host didn't declare dispatch at all — fail-closed to most-restrictive values
         warnings.push(`host did not declare 'dispatch'`);
@@ -296,6 +344,7 @@ function negotiateHostCapabilities(host, engine = DEFAULT_ENGINE) {
         effectiveBackgroundDispatch = false;
         effectiveSubagentToolkit = 'read-only';
         effectiveMaxDepth = 0;
+        effectiveIsolation = 'none';
     }
     else {
         // N1: observability warnings for 'undocumented' sentinel on dispatch fields
@@ -314,6 +363,16 @@ function negotiateHostCapabilities(host, engine = DEFAULT_ENGINE) {
         if (hostDispatch.backgroundDispatch === 'undocumented') {
             warnings.push(`dispatch.backgroundDispatch is undocumented — degraded closed`);
         }
+        if (hostDispatch.isolation === 'undocumented') {
+            warnings.push(`dispatch.isolation is undocumented — degraded closed (none)`);
+        }
+        if (hostDispatch.maxDepth === UNDOCUMENTED) {
+            // #2603: maxDepth was the one dispatch sub-axis with no sentinel-specific
+            // warning, so a descriptor carrying the documented fail-closed sentinel was
+            // reported as `missing or not a number` — indistinguishable from a genuinely
+            // malformed descriptor. Six shipped runtimes use the sentinel here.
+            warnings.push(`dispatch.maxDepth is undocumented — degraded closed (0)`);
+        }
         effectiveNamedDispatch = (hostDispatch.namedDispatch === true) && engineDispatch.namedDispatch;
         effectiveNested = (hostDispatch.nested === true) && engineDispatch.nested;
         effectiveBackground = (hostDispatch.background === true) && engineDispatch.background;
@@ -323,10 +382,22 @@ function negotiateHostCapabilities(host, engine = DEFAULT_ENGINE) {
         const hostToolkit = hostDispatch.subagentToolkit === 'full' ? 'full' : 'read-only';
         const engineToolkit = engineDispatch.subagentToolkit === 'read-only' ? 'read-only' : 'full';
         effectiveSubagentToolkit = (hostToolkit === 'read-only' || engineToolkit === 'read-only') ? 'read-only' : 'full';
-        // maxDepth: missing/non-number/non-finite → 0 + warning
+        // isolation: effective = the host's declared value only if it is a known
+        // valid vocabulary member; otherwise 'none'. NOT host && engine gated —
+        // GSD owns the vocabulary, so "engine-known" == "in the valid set" (this
+        // still satisfies effective ⊆ host-declared ∩ engine-known).
+        const hostIso = hostDispatch.isolation;
+        effectiveIsolation = (typeof hostIso === 'string' && HOST_INTEGRATION_AXES.isolation.includes(hostIso))
+            ? hostIso
+            : 'none';
+        // maxDepth: missing/non-number/non-finite → 0 + warning. The documented
+        // 'undocumented' sentinel also degrades to 0, but is reported by the
+        // sentinel-specific warning above rather than as a malformed value (#2603).
         let hostMaxDepth;
         if (typeof hostDispatch.maxDepth !== 'number' || !Number.isFinite(hostDispatch.maxDepth)) {
-            warnings.push(`host dispatch.maxDepth is missing or not a number — treating as 0`);
+            if (hostDispatch.maxDepth !== UNDOCUMENTED) {
+                warnings.push(`host dispatch.maxDepth is missing or not a number — treating as 0`);
+            }
             hostMaxDepth = 0;
         }
         else {
@@ -352,6 +423,7 @@ function negotiateHostCapabilities(host, engine = DEFAULT_ENGINE) {
         background: effectiveBackground,
         subagentToolkit: effectiveSubagentToolkit,
         backgroundDispatch: effectiveBackgroundDispatch,
+        isolation: effectiveIsolation,
     };
     // ---------------------------------------------------------------------------
     // Assemble effective axes
@@ -365,6 +437,7 @@ function negotiateHostCapabilities(host, engine = DEFAULT_ENGINE) {
         stateIO: effectiveStateIO,
         transport: effectiveTransport,
         runtime: effectiveRuntime,
+        effortSurface: effectiveEffortSurface,
     };
     // ---------------------------------------------------------------------------
     // Compute points (fresh objects — mutation-safe)
@@ -395,6 +468,63 @@ function shouldFlattenDispatch(dispatch) {
     return !canBackground;
 }
 // ---------------------------------------------------------------------------
+// resolveDispatchType — ADR-1239 / epic #2505 Phase 4 (Option A)
+//
+// Maps a requested GSD subagent name (e.g. "gsd-planner") to the type an
+// Agent() call should actually use on the CURRENT runtime. On runtimes whose
+// descriptor declares `hostIntegration.dispatch.namedDispatch: true` (Claude,
+// OpenCode, Cursor, …), the requested name is returned unchanged — those hosts
+// can dispatch GSD's named subagents directly. On runtimes with
+// `namedDispatch: false` (kimi-code — only three built-in subagents
+// `coder`/`explore`/`plan`, per moonshotai.github.io/kimi-code/en/customization/
+// agents), the name is mapped to the closest built-in by role-suffix
+// heuristic. The persona rides the existing `${AGENT_SKILLS_*}` prompt
+// injection (Phase 3 / #2510) regardless of the resolved type, so the
+// dispatcher does not need to know the persona — only the toolkit tier.
+//
+// This is Option A of the Phase 4 design (per-workflow runtime detection via
+// `gsd_run query resolve-dispatch-type`), not Option B (PreToolUse mutation) —
+// Kimi Code's documented hook API supports only allow/deny on PreToolUse, not
+// tool_input rewriting, so a hook-based remap is infeasible (see #2508).
+//
+// Fail-closed: unknown dispatch shape or missing namedDispatch axis ⇒ return
+// the requested name unchanged (named-dispatch is the GSD default; degrading
+// to it on unknown runtimes preserves behavior for every runtime already in
+// the field).
+// ---------------------------------------------------------------------------
+// Role-suffix → built-in mapping. Order matters: the first match wins.
+// `plan`-tier agents plan/design without touching files; `explore`-tier agents
+// are read-only; everything else (executors, writers, fixers, debuggers) maps
+// to `coder` (the general-purpose built-in with the full tool set).
+const DISPATCH_TYPE_SUFFIX_MAP = Object.freeze([
+    [/-?(planner|roadmapper|selector|spec)$/i, 'plan'],
+    [/-?(researcher|mapper|checker|verifier|auditor|analyzer|synthesizer|profiler|curator|classifier|reviewer)$/i, 'explore'],
+]);
+// Names that are already generic (not gsd-*) and should map to the
+// general-purpose built-in on built-in-only runtimes.
+const GENERIC_NAMES_TO_CODER = Object.freeze(new Set([
+    'general-purpose', 'general', 'default', 'sonnet', 'opus', 'haiku',
+]));
+function resolveDispatchType(requested, dispatch) {
+    if (typeof requested !== 'string' || requested.length === 0)
+        return 'coder';
+    // Built-in-only runtime (EXPLICIT namedDispatch: false, e.g. kimi-code):
+    // map to coder/explore/plan by suffix heuristic.
+    if (dispatch && typeof dispatch === 'object' && dispatch.namedDispatch === false) {
+        if (GENERIC_NAMES_TO_CODER.has(requested))
+            return 'coder';
+        for (const [pattern, builtin] of DISPATCH_TYPE_SUFFIX_MAP) {
+            if (pattern.test(requested))
+                return builtin;
+        }
+        return 'coder';
+    }
+    // Named-dispatch runtime (namedDispatch: true OR unknown/absent): use the
+    // requested name unchanged. Absent namedDispatch degrades to named-dispatch
+    // (the GSD default) so every runtime already in the field keeps working.
+    return requested;
+}
+// ---------------------------------------------------------------------------
 // Managed-hook event surface per hookEvents dialect (ADR-1239 / ADR-1016)
 // ---------------------------------------------------------------------------
 // Host-fireable MANAGED-hook events per `hookEvents` dialect. `hookEvents` is the
@@ -492,6 +622,81 @@ function extensionEventSurfaceFor(extensionEvents) {
         return null;
     return EXTENSION_EVENT_SURFACES[extensionEvents] || null;
 }
+/**
+ * Resolve an `orchestratorExec` descriptor + target cwd (+ optional executor
+ * prompt) into a concrete argv/cwd shape for a process-spawn primitive.
+ *
+ * Fail-closed: never throws, always returns a discriminated result. When
+ * `cwdFlag` is a non-empty string, `[cwdFlag, cwd]` is appended to `args`
+ * exactly once (e.g. codex: `exec --cd <cwd>`); when `cwdFlag` is `null` or
+ * absent (e.g. kimi-code, which binds via the spawned process's own cwd —
+ * "process-cwd" case), no flag is appended and `cwd` is returned for the
+ * caller to bind via the subprocess's own working-directory option.
+ *
+ * Prompt passing (Phase 3, #2627) is descriptor data for the same reason the
+ * cwd flag is: the confirmed `orchestrator-worktree` hosts disagree on the
+ * shape. `codex exec "<prompt>"` and `opencode run "<prompt>"` take it
+ * positionally; `kimi --print --prompt "<p>"` and Kimi Code's `kimi -p "<p>"`
+ * take a flag. Encoding that as `promptFlag` keeps the scheduler free of the
+ * per-host branch ADR-1239 exists to remove. Omit `prompt` entirely and the
+ * resolution is byte-identical to Phase 2's (the unconsumed-resolver shape).
+ *
+ * Argv order is base args → cwd flag → prompt, so the prompt stays the final
+ * positional token for the hosts that read it that way.
+ */
+function resolveOrchestratorExec(orchestratorExec, cwd, prompt) {
+    if (!orchestratorExec || typeof orchestratorExec !== 'object' || Array.isArray(orchestratorExec)) {
+        return { ok: false, reason: 'missing_command' };
+    }
+    const oe = orchestratorExec;
+    if (typeof oe.command !== 'string' || oe.command.length === 0) {
+        return { ok: false, reason: 'missing_command' };
+    }
+    if (typeof cwd !== 'string' || cwd.length === 0) {
+        return { ok: false, reason: 'invalid_cwd' };
+    }
+    if (oe.args !== undefined && (!Array.isArray(oe.args) || !oe.args.every((a) => typeof a === 'string'))) {
+        return { ok: false, reason: 'invalid_args' };
+    }
+    if (oe.cwdFlag !== undefined && oe.cwdFlag !== null && typeof oe.cwdFlag !== 'string') {
+        return { ok: false, reason: 'invalid_cwd_flag' };
+    }
+    if (oe.promptFlag !== undefined && oe.promptFlag !== null && typeof oe.promptFlag !== 'string') {
+        return { ok: false, reason: 'invalid_prompt_flag' };
+    }
+    // An executor spawned with no instruction is a hang, not a degraded run —
+    // fail closed rather than launching a prompt-less process.
+    if (prompt !== undefined && (typeof prompt !== 'string' || prompt.length === 0)) {
+        return { ok: false, reason: 'invalid_prompt' };
+    }
+    // Leading-dash guard, mirroring worktree-safety.cts's `unsafe_leading_dash`
+    // check on git arguments. A positional prompt (or a cwd) beginning with '-'
+    // is parsed by the spawned CLI as a FLAG, not a value — the same failure the
+    // git path already rejects, and for the same reason: `--` end-of-options
+    // support is inconsistent across these CLIs, so rejecting outright is the
+    // portable fix rather than relying on a separator. Applied to the resolver
+    // (not just its current caller) because this is a general descriptor->argv
+    // seam: a future caller must not have to rediscover the hazard.
+    if (typeof prompt === 'string' && prompt.startsWith('-')) {
+        return { ok: false, reason: 'unsafe_leading_dash_prompt' };
+    }
+    if (cwd.startsWith('-')) {
+        return { ok: false, reason: 'unsafe_leading_dash_cwd' };
+    }
+    const baseArgs = Array.isArray(oe.args) ? [...oe.args] : [];
+    const args = typeof oe.cwdFlag === 'string' && oe.cwdFlag.length > 0
+        ? [...baseArgs, oe.cwdFlag, cwd]
+        : baseArgs;
+    if (typeof prompt === 'string') {
+        if (typeof oe.promptFlag === 'string' && oe.promptFlag.length > 0) {
+            args.push(oe.promptFlag, prompt);
+        }
+        else {
+            args.push(prompt);
+        }
+    }
+    return { ok: true, command: oe.command, args, cwd };
+}
 module.exports = {
     PROTOCOL_VERSION,
     UNDOCUMENTED,
@@ -505,6 +710,8 @@ module.exports = {
     profileOf,
     negotiateHostCapabilities,
     shouldFlattenDispatch,
+    resolveDispatchType,
     hookEventSurfaceFor,
     extensionEventSurfaceFor,
+    resolveOrchestratorExec,
 };

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

@@ -112,18 +112,6 @@ function listPhaseSummaryFiles(phaseDir) {
 function listPhasePlanFiles(phaseDir) {
     return scanPhasePlans(phaseDir)['planFiles'];
 }
-function verificationNextCommand(status, phaseNumber, slashRuntime) {
-    if (status === 'gaps_found') {
-        return `${(0, runtime_slash_cjs_1.formatGsdSlash)('plan-phase', slashRuntime)} ${phaseNumber} --gaps`;
-    }
-    if (status === 'human_needed' || status === 'stale') {
-        return `${(0, runtime_slash_cjs_1.formatGsdSlash)('verify-work', slashRuntime)} ${phaseNumber}`;
-    }
-    if (status === 'missing' || status === 'unknown') {
-        return `${(0, runtime_slash_cjs_1.formatGsdSlash)('execute-phase', slashRuntime)} ${phaseNumber}`;
-    }
-    return '';
-}
 function projectCompletionStatus(implementationComplete, verificationPassed) {
     if (implementationComplete && verificationPassed)
         return 'complete';
@@ -134,8 +122,14 @@ function projectCompletionStatus(implementationComplete, verificationPassed) {
 function buildPhaseCompletionProjection(cwd, phaseNumber, phaseDir, planCount, summaryCount, slashRuntime) {
     const implementationComplete = planCount > 0 && summaryCount >= planCount;
     const phaseFullDir = phaseDir ? node_path_1.default.join(cwd, phaseDir) : '';
+    // #2617: ONE verification-routing seam. init used to re-derive next_command
+    // from the status with its own projector, which had drifted from the router's
+    // table — it appended the phase number and answered `human_needed`; the table
+    // did neither. The router now owns both the content and the runtime
+    // projection, and init passes the phase number it already knows (its phaseDir
+    // is unresolved in some branches, where the router could not derive one).
     const verificationStatus = implementationComplete
-        ? readVerificationStatus(phaseFullDir)
+        ? readVerificationStatus(phaseFullDir, { runtime: slashRuntime, phaseNumber })
         : { status: 'not_required', next_action: '', next_command: '' };
     const projectedVerificationStatus = verificationStatus.status;
     const projectedVerificationAction = verificationStatus.next_action;
@@ -148,7 +142,7 @@ function buildPhaseCompletionProjection(cwd, phaseNumber, phaseDir, planCount, s
         phase_complete: phaseComplete,
         completion_status: projectCompletionStatus(implementationComplete, verificationPassed),
         verification_next_action: projectedVerificationAction,
-        verification_next_command: verificationNextCommand(projectedVerificationStatus, phaseNumber, slashRuntime),
+        verification_next_command: verificationStatus.next_command,
     };
 }
 function getLatestCompletedMilestone(cwd) {
@@ -1854,7 +1848,38 @@ function cmdAgentSkills(cwd, agentType, raw, jsonMode) {
     const projectRoot = (0, project_root_cjs_1.findProjectRoot)(cwd);
     const { config, source, degraded } = loadConfigResolved(projectRoot);
     const diagnostics = { warnings: [] };
-    const block = buildAgentSkillsBlock(config, agentType, projectRoot, diagnostics);
+    let block = buildAgentSkillsBlock(config, agentType, projectRoot, diagnostics);
+    // #2454: Agent prompt fallback for AGENTS-native runtimes where named
+    // subagents are NOT dispatchable (kimi-code, kimi, opencode, kilo, etc.).
+    // On these runtimes, workflows inject ${AGENT_SKILLS_*} into the dispatch
+    // prompt of a built-in subagent (coder/explore/plan). If no
+    // model_profile_overrides or agent_skills config entry exists, the block
+    // is empty — but the agent's prompt CONTENT is installed on disk at the
+    // runtime's agents directory. Read it as a fallback so the persona survives
+    // the dispatch even without explicit config opt-in.
+    //
+    // GATED to non-claude runtimes: Claude Code supports named subagent dispatch
+    // and its ${AGENT_SKILLS_*} contract is a skills-injection path, not a
+    // persona fallback. Triggering the fallback for claude would change the
+    // documented "unconfigured → empty block" contract that agent-skills tests
+    // pin.
+    if (!block) {
+        const runtime = (config && config['runtime']) || process.env['GSD_RUNTIME'] || 'claude';
+        if (runtime !== 'claude') {
+            const agentCheck = checkAgentsInstalled(runtime);
+            const agentsDir = agentCheck?.agents_dir;
+            if (typeof agentsDir === 'string' && agentsDir.length > 0) {
+                const agentFile = node_path_1.default.join(agentsDir, `${agentType}.md`);
+                try {
+                    const content = (0, shell_command_projection_cjs_1.platformReadSync)(agentFile);
+                    if (content && content.length > 0) {
+                        block = content;
+                    }
+                }
+                catch { /* agent file not found — fall through to empty block */ }
+            }
+        }
+    }
     // Compute configured + reason for diagnostic output.
     const agentSkillsMap = (config && config['agent_skills'] && typeof config['agent_skills'] === 'object')
         ? config['agent_skills']
@@ -2053,8 +2078,8 @@ function buildSkillManifest(cwd, skillsDir = null) {
         // posix-style for cross-platform stability; flat entries use template
         // literals that always produce '/'; nested entries are joined below
         // with explicit '/' separators rather than path.join).
-        relPath, content) {
-            const frontmatter = extractFrontmatter(content);
+        relPath, content, sourcePath) {
+            const frontmatter = extractFrontmatter(content, sourcePath);
             const dirPart = relPath.replace(/\/SKILL\.md$/, '');
             const stem = dirPart.includes('/') ? dirPart.split('/').pop() : dirPart;
             const name = frontmatter['name'] || stem;
@@ -2095,7 +2120,7 @@ function buildSkillManifest(cwd, skillsDir = null) {
             const skillMdPath = node_path_1.default.join(rootPath, entry.name, 'SKILL.md');
             const content = (0, shell_command_projection_cjs_1.platformReadSync)(skillMdPath);
             if (content !== null) {
-                if (pushSkillEntry(`${entry.name}/SKILL.md`, content))
+                if (pushSkillEntry(`${entry.name}/SKILL.md`, content, skillMdPath))
                     skillCount++;
             }
             // Nested layout: <entry>/skills/<stem>/SKILL.md
@@ -2124,7 +2149,7 @@ function buildSkillManifest(cwd, skillsDir = null) {
                 // Use forward-slash separator explicitly so manifest paths are posix-style
                 // on all platforms, matching the flat-layout behaviour above.
                 const relPath = `${entry.name}/skills/${nested.name}/SKILL.md`;
-                if (pushSkillEntry(relPath, nestedContent))
+                if (pushSkillEntry(relPath, nestedContent, nestedSkillMd))
                     skillCount++;
             }
         }

package/gsd-core/bin/lib/install-engine.cjs

@@ -115,6 +115,7 @@ function convertClaudeCommandToKiloSkill(content, skillName) {
 const SKILLS_CONVERTER_REGISTRY = {
     convertClaudeCommandToOpencodeSkill,
     convertClaudeCommandToKiloSkill,
+    convertClaudeCommandToKimiCodeSkill: runtimeArtifactConversion.convertClaudeCommandToKimiCodeSkill,
 };
 // ---------------------------------------------------------------------------
 // User-artifact preservation helpers

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

@@ -282,8 +282,8 @@ function cmdRequirementsReadyIds(cwd, args, raw) {
     catch {
         siblingPlanFiles = [];
     }
-    const parseFrontmatterReqIds = (content) => {
-        const fm = extractFrontmatter(content);
+    const parseFrontmatterReqIds = (content, sourcePath) => {
+        const fm = extractFrontmatter(content, sourcePath);
         const fmReq = fm.requirements;
         if (Array.isArray(fmReq))
             return fmReq.map((r) => String(r).trim()).filter(Boolean);
@@ -309,7 +309,7 @@ function cmdRequirementsReadyIds(cwd, args, raw) {
             catch {
                 continue;
             }
-            const siblingReqIds = parseFrontmatterReqIds(siblingContent);
+            const siblingReqIds = parseFrontmatterReqIds(siblingContent, siblingPath);
             const siblingDeclaresId = siblingReqIds.some((id) => id.toLowerCase() === reqId.toLowerCase());
             if (!siblingDeclaresId)
                 continue;
@@ -531,7 +531,7 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
             for (const s of summaries) {
                 try {
                     const content = node_fs_1.default.readFileSync(node_path_1.default.join(phasesDir, dir, s), 'utf-8');
-                    const fm = extractFrontmatter(content);
+                    const fm = extractFrontmatter(content, node_path_1.default.join(phasesDir, dir, s));
                     const rawOneLiner = fm['one-liner'];
                     const oneLiner = (typeof rawOneLiner === 'string' ? rawOneLiner : '') || extractOneLinerFromBody(content);
                     if (oneLiner) {
@@ -668,7 +668,7 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
             kind: 'milestoneComplete',
             version,
             nextMilestoneCommand: (0, runtime_slash_cjs_1.formatGsdSlash)('new-milestone', (0, runtime_slash_cjs_1.resolveRuntime)(cwd)),
-        }, { clock: clock_cjs_1.realClock, progressProvider: () => null });
+        }, { clock: clock_cjs_1.realClock, progressProvider: () => null, sourcePath: statePath });
         writeStateMd(statePath, result.content, cwd);
     }
     // Archive phase directories if requested

package/gsd-core/bin/lib/model-catalog.cjs

@@ -10,10 +10,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RUNTIMES_WITH_FAST_MODE = exports.EFFORT_RENDERING = exports.KNOWN_PROVIDERS = exports.PROVIDER_PRESETS = exports.RUNTIMES_WITH_REASONING_EFFORT = exports.KNOWN_RUNTIMES = exports.RUNTIME_PROFILE_MAP = exports.MODEL_ALIAS_MAP = exports.AGENT_DEFAULT_TIERS = exports.AGENT_TO_PHASE_TYPE = exports.MODEL_PROFILES = exports.ADAPTIVE_TIER_VALUES = exports.VALID_TIERS = exports.VALID_AGENT_TIERS = exports.VALID_PHASE_TYPES = exports.VALID_PROFILES = exports.catalog = void 0;
+exports.RUNTIMES_WITH_FAST_MODE = exports.EFFORT_ARGV = exports.EFFORT_RENDERING = exports.KNOWN_PROVIDERS = exports.PROVIDER_PRESETS = exports.RUNTIMES_WITH_REASONING_EFFORT = exports.KNOWN_RUNTIMES = exports.RUNTIME_PROFILE_MAP = exports.MODEL_ALIAS_MAP = exports.AGENT_DEFAULT_TIERS = exports.AGENT_TO_PHASE_TYPE = exports.MODEL_PROFILES = exports.ADAPTIVE_TIER_VALUES = exports.VALID_TIERS = exports.VALID_AGENT_TIERS = exports.VALID_PHASE_TYPES = exports.VALID_PROFILES = exports.catalog = void 0;
 exports.nextTier = nextTier;
 exports.formatAgentToModelMapAsTable = formatAgentToModelMapAsTable;
 exports.getAgentToModelMapForProfile = getAgentToModelMapForProfile;
+exports.renderEffortArgv = renderEffortArgv;
 exports.renderEffortForRuntime = renderEffortForRuntime;
 const node_path_1 = __importDefault(require("node:path"));
 // In .cts (CommonJS output) files, `require` is available as a global;
@@ -151,6 +152,55 @@ exports.EFFORT_RENDERING = {
         },
     },
 };
+exports.EFFORT_ARGV = {
+    // Verified against `claude --help`: `--effort <level>`.
+    claude: {
+        render: (level) => ['--effort', level],
+        supported: new Set(['low', 'medium', 'high', 'xhigh', 'max']),
+        clamp: (level) => (level === 'minimal' ? 'low' : level),
+    },
+    // Verified against `opencode run --help`: `--variant` — "model variant
+    // (provider-specific reasoning effort, e.g., high, max, minimal)".
+    opencode: {
+        render: (level) => ['--variant', level],
+        supported: new Set(['minimal', 'low', 'medium', 'high', 'xhigh', 'max']),
+        clamp: (level) => level,
+    },
+    // First-party Codex docs: `model_reasoning_effort` is a config-only key with no
+    // dedicated flag, so the generic `-c key=value` override is the only argv route.
+    codex: {
+        render: (level) => ['-c', `model_reasoning_effort=${level}`],
+        supported: new Set(['minimal', 'low', 'medium', 'high', 'xhigh']),
+        clamp: (level) => (level === 'max' ? 'xhigh' : level),
+    },
+};
+/**
+ * Render the invocation-time effort argument for a host.
+ *
+ * `effortSurface` is the host's negotiated axis value. Only `argv` produces an
+ * argument; `none`, `undocumented`, and anything unrecognised produce nothing.
+ * Never throws.
+ */
+function renderEffortArgv(host, universalEffort, effortSurface) {
+    const empty = { argv: [], value: null, host };
+    if (effortSurface !== 'argv')
+        return empty;
+    // Own-property lookup only. A plain `EFFORT_ARGV[host]` resolves `__proto__`
+    // (and `constructor`/`toString`) to inherited members, which are truthy but
+    // carry no `clamp`/`render` — a hostile host id would throw instead of
+    // degrading. The host id reaches here from a descriptor, i.e. untrusted JSON.
+    if (typeof host !== 'string' || !Object.prototype.hasOwnProperty.call(exports.EFFORT_ARGV, host))
+        return empty;
+    const spec = exports.EFFORT_ARGV[host];
+    if (!spec || typeof spec.clamp !== 'function' || typeof spec.render !== 'function')
+        return empty;
+    if (typeof universalEffort !== 'string' || universalEffort.length === 0)
+        return empty;
+    const clamped = spec.clamp(universalEffort);
+    if (!spec.supported.has(clamped))
+        return empty;
+    return { argv: spec.render(clamped), value: clamped, host };
+}
 /**
  * Render a universal effort string for a specific runtime.
  */

package/gsd-core/bin/lib/observability/logger.cjs

@@ -41,7 +41,12 @@ function _safeStringify(value) {
     }
 }
 /**
- * Determine whether the audit file should be written to.
+ * Determine whether observability is opt-in enabled — via the GSD_AUDIT env var
+ * or config.audit.enabled. Exported (#2620) so the live dispatch seam can decide
+ * whether to inject the reference logger at all: when observability is off we
+ * inject nothing (the Hub stays byte-for-byte silent, preserving the default
+ * dispatch output contract, incl. --json-errors); when on, the caller injects
+ * createDefaultLogger and gets the stderr-on-error line + opt-in file audit.
  */
 function _isAuditEnabled(config) {
     if (process.env['GSD_AUDIT'] === '1')
@@ -143,4 +148,4 @@ function createDefaultLogger({ cwd = process.cwd(), config } = {}) {
         },
     };
 }
-module.exports = { createDefaultLogger, createNoOpLogger };
+module.exports = { createDefaultLogger, createNoOpLogger, isAuditEnabled: _isAuditEnabled };

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

@@ -20,6 +20,12 @@ const command_aliases_cjs_1 = require("./command-aliases.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const commandRoutingHub = require("./command-routing-hub.cjs");
 const { createHub, ERROR_KINDS, makeInvalidArgs } = commandRoutingHub;
+// #2620 (ADR-0174 §6): inject the reference DispatchLogger on the live phase
+// dispatch path, but only when observability is opt-in enabled; otherwise the
+// Hub stays byte-for-byte silent via its no-op fallback.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const observabilityLogger = require("./observability/logger.cjs");
+const { createDefaultLogger, isAuditEnabled } = observabilityLogger;
 // ─── Implementation ───────────────────────────────────────────────────────────
 function routePhaseCommand({ phase, args, cwd, raw, error }) {
     // ── Unsupported subcommands ─────────────────────────────────────────────────
@@ -229,7 +235,10 @@ function routePhaseCommand({ phase, args, cwd, raw, error }) {
     const manifest = { phase: manifestSubcommands };
     // ── Construct hub ──────────────────────────────────────────────────────────
     // #175: Hub is CJS-only — no mode param, no sdkLoader.
-    const hub = createHub({ cjsRegistry, manifest });
+    // #2620: wire the reference logger (ADR-0174 §6) only when observability is
+    // opt-in enabled; otherwise leave it unset so the Hub stays byte-for-byte
+    // silent via its no-op fallback.
+    const hub = createHub({ cjsRegistry, manifest, logger: isAuditEnabled() ? createDefaultLogger({ cwd }) : undefined });
     // ── Dispatch ────────────────────────────────────────────────────────────────
     const result = hub.dispatch({
         family: 'phase',