@opengsd/gsd-core 1.16.0 → 1.17.0

package/gsd-core/bin/lib/capability-validator.cjs

@@ -1936,6 +1936,7 @@ const KNOWN_HOST_BEHAVIORS = new Set([
   'managedHookEvents',
   'mcpCompanion',
   'namedSubagentsSupported',
+  'nativeCliPlugin',
   'nativeModelAliases',
   'nativePlugin',
   'noPathRewrite',
@@ -2572,7 +2573,7 @@ function validateLaneProbe(ctx, probe) {
     if (!isPositiveIntegerMs(probe.timeoutMs)) {
       errors.push(
         ctx + ' reviewer.probe.timeoutMs must be a positive integer of milliseconds for kind "' +
-        probe.kind + '" — an unbounded probe hangs every /gsd:review invocation ' +
+        probe.kind + '" — an unbounded probe hangs every /gsd-review invocation ' +
         '(got: ' + describeValue(probe.timeoutMs) + ')',
       );
     }

package/gsd-core/bin/lib/capability-writer.cjs

@@ -50,6 +50,7 @@ const { planningDir } = planningWorkspaceMod;
 const nodefs = require("fs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const nodepath = require("path");
+const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
 // ─── Implementation ───────────────────────────────────────────────────────────
 /**
  * Write-side capability state mutator.
@@ -305,7 +306,7 @@ function setCapabilityState(cwd, runtimeConfigDir, desired, opts) {
         if (entry.enabled === true) {
             const afterCap = after.capabilities.find((c) => c.id === entry.id);
             if (afterCap && afterCap.enabled !== true) {
-                errors.push(`cannot enable "${entry.id}": not in the active surface/profile (widen the profile or use /gsd:surface enable)`);
+                errors.push(`cannot enable "${entry.id}": not in the active surface/profile (widen the profile or use ${(0, runtime_slash_cjs_1.runtimeCommand)(cwd, 'surface enable')})`);
             }
         }
         // Fix B: desired enabled=false — assert it is actually disabled after write.

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

@@ -1233,6 +1233,24 @@ function cmdEffortSyncOpencode(cwd, raw, dryRun, configDir) {
         // null — it would leave an unresolvable `variant: null` key on disk
         // forever. Test presence with its own regex, and only compare values
         // once presence is known.
+        // Native OpenCode 2.x form (ADR-5331 D5): the effort rides on the model reference as
+        // `provider/model#variant`, with no separate `variant:` key. When the agent's `model:` carries a
+        // `#` suffix that suffix IS the effort, so the sync edits the model instead of adding a second,
+        // conflicting `variant:` line.
+        const modelLineMatch = /^model:[ \t]*(.+?)[ \t]*$/m.exec(fmMatch.body);
+        const modelValue = modelLineMatch ? modelLineMatch[1].replace(/\r$/, '').replace(/^(["'])(.*)\1$/, '$2') : null;
+        const hashAt = modelValue === null ? -1 : modelValue.lastIndexOf('#');
+        let modelFormContent = null;
+        let modelFormFrom = null;
+        if (modelValue !== null && hashAt > 0) {
+            const base = modelValue.slice(0, hashAt);
+            modelFormFrom = modelValue.slice(hashAt + 1);
+            if (target !== null && modelFormFrom === target) {
+                skipped++;
+                continue;
+            }
+            modelFormContent = setFrontmatterKeyLine(content, 'model', target === null ? base : `${base}#${target}`);
+        }
         const variantPresent = /^variant:/m.test(fmMatch.body);
         const variantMatch = /^variant:[ \t]*(.+?)[ \t]*$/m.exec(fmMatch.body);
         // `null` (key absent) and `''` (key present, value empty) are distinct
@@ -1241,17 +1259,19 @@ function cmdEffortSyncOpencode(cwd, raw, dryRun, configDir) {
         // "empty key" indistinguishable in the sync output, even though only one
         // of them actually has a `variant:` line to remove.
         const currentVariant = variantPresent ? (variantMatch ? variantMatch[1] : '') : null;
-        if (target === null) {
-            if (!variantPresent) {
+        if (modelFormContent === null) {
+            if (target === null) {
+                if (!variantPresent) {
+                    skipped++;
+                    continue;
+                }
+            }
+            else if (variantPresent && currentVariant === target) {
                 skipped++;
                 continue;
             }
         }
-        else if (variantPresent && currentVariant === target) {
-            skipped++;
-            continue;
-        }
-        changes.push({ agent: agentName, from: currentVariant, to: target });
+        changes.push({ agent: agentName, from: modelFormContent === null ? currentVariant : modelFormFrom, to: target });
         synced++;
         if (!dryRun) {
             // Atomic publish AND mode preservation, same discipline as
@@ -1279,7 +1299,7 @@ function cmdEffortSyncOpencode(cwd, raw, dryRun, configDir) {
             }
             catch { /* non-fatal: fall back to writing without an explicit mode */ }
             try {
-                node_fs_1.default.writeFileSync(tmpPath, target === null ? removeFrontmatterKeyLine(content, 'variant') : setFrontmatterKeyLine(content, 'variant', target), originalMode !== undefined ? { mode: originalMode } : undefined);
+                node_fs_1.default.writeFileSync(tmpPath, modelFormContent ?? (target === null ? removeFrontmatterKeyLine(content, 'variant') : setFrontmatterKeyLine(content, 'variant', target)), originalMode !== undefined ? { mode: originalMode } : undefined);
                 // Not redundant with the `mode` option above: `mode` only applies
                 // when the file is actually created (O_CREAT). A leftover tmp file
                 // from an earlier crashed run would be reused (truncated) at its OLD

package/gsd-core/bin/lib/gate-context-drift.cjs

@@ -28,6 +28,7 @@ const node_path_1 = __importDefault(require("node:path"));
 const gate_verdict_cjs_1 = require("./gate-verdict.cjs");
 const gate_evidence_cjs_1 = require("./gate-evidence.cjs");
 const gate_config_cjs_1 = require("./gate-config.cjs");
+const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
 const gate_phase_context_cjs_1 = require("./gate-phase-context.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-workspace.cjs is an export= CommonJS module
 const planningWorkspace = require("./planning-workspace.cjs");
@@ -45,13 +46,13 @@ const { defaultPhaseCleanCommitTimesMs } = verificationMod;
 function computeContextDrift(contextEffectiveMs, entries) {
     return entries.filter((e) => e.effectiveMs < contextEffectiveMs).map((e) => e.file);
 }
-function buildContextDriftMessage(staleArtifacts, phaseArg) {
+function buildContextDriftMessage(staleArtifacts, phaseArg, projectDir) {
     const parts = [`CONTEXT.md decisions are newer than: ${staleArtifacts.join(', ')}.`];
     if (staleArtifacts.some((f) => f.endsWith('-RESEARCH.md'))) {
-        parts.push(`Regenerate research: /gsd:plan-phase ${phaseArg} --research.`);
+        parts.push(`Regenerate research: ${(0, runtime_slash_cjs_1.runtimeCommand)(projectDir, `plan-phase ${phaseArg} --research`)}.`);
     }
     if (staleArtifacts.some((f) => f.endsWith('-PATTERNS.md'))) {
-        parts.push('Regenerate patterns: delete the PATTERNS.md file, then re-run /gsd:plan-phase.');
+        parts.push(`Regenerate patterns: delete the PATTERNS.md file, then re-run ${(0, runtime_slash_cjs_1.runtimeCommand)(projectDir, 'plan-phase')}.`);
     }
     if (staleArtifacts.some((f) => f.endsWith('-VALIDATION.md') || (f.endsWith('-SPEC.md') && !f.endsWith('-AI-SPEC.md') && !f.endsWith('-UI-SPEC.md')))) {
         parts.push('Regenerate or manually reconcile VALIDATION.md / SPEC.md against the current decisions.');
@@ -114,7 +115,7 @@ function runContextDriftGate(cwd, phaseArg) {
     // missing or malformed config is "key absent", nothing is printed).
     const action = (0, gate_config_cjs_1.readWorkflowConfigValue)(cwd, 'workflow.context_drift_action').value === 'block' ? 'block' : 'warn';
     const block = staleArtifacts.length > 0 && action === 'block';
-    const message = staleArtifacts.length > 0 ? buildContextDriftMessage(staleArtifacts, phaseArg) : '';
+    const message = staleArtifacts.length > 0 ? buildContextDriftMessage(staleArtifacts, phaseArg, cwd) : '';
     return (0, gate_verdict_cjs_1.gateVerdict)(block ? 'block' : (staleArtifacts.length > 0 ? 'advisory' : 'pass'), block, {
         block,
         skipped: false,

package/gsd-core/bin/lib/gate-ui-safety.cjs

@@ -19,6 +19,7 @@ exports.evaluateUiSafetyGate = evaluateUiSafetyGate;
 const gate_verdict_cjs_1 = require("./gate-verdict.cjs");
 const gate_phase_context_cjs_1 = require("./gate-phase-context.cjs");
 const gate_evaluation_scope_cjs_1 = require("./gate-evaluation-scope.cjs");
+const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
 const ui_safety_gate_cjs_1 = require("./ui-safety-gate.cjs");
 const UI_FILE_EXTENSIONS_RE = /\.(tsx|jsx|css|scss|sass|less|vue|svelte|html)$/i;
 const UI_PATH_PATTERNS_RE = /\/(components|pages|views|screens|layouts|ui|frontend)\//i;
@@ -52,7 +53,7 @@ function computeUiSafetyGate(projectDir, phase) {
     const result = { frontend, hasUiFiles, hasUiSpec, block };
     if (block) {
         result.message = `UI files changed in this wave but no UI-SPEC.md exists for Phase ${phase}. ` +
-            `Run /gsd:ui-phase ${phase} to generate the design contract before continuing.`;
+            `Run ${(0, runtime_slash_cjs_1.runtimeCommand)(projectDir, `ui-phase ${phase}`)} to generate the design contract before continuing.`;
     }
     if (phaseLookupFailed)
         result.phaseLookupFailed = true;

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

@@ -13,6 +13,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const capabilityStateMod = require("./capability-state.cjs");
 const { isCapabilityActive } = capabilityStateMod;
@@ -408,7 +409,7 @@ function graphifyQuery(cwd, term, options = {}) {
     const { graphPath, configured } = resolveGraphLocation(cwd, planningDir);
     if (!node_fs_1.default.existsSync(graphPath)) {
         return { error: configured
-                ? `Configured graph not found at ${graphPath}. Set graphify.graph_path or run /gsd:graphify build.`
+                ? `Configured graph not found at ${graphPath}. Set graphify.graph_path or run ${(0, runtime_slash_cjs_1.runtimeCommand)(cwd, 'graphify build')}.`
                 : 'No graph built yet. Run graphify build first.' };
     }
     const graph = safeReadJson(graphPath);
@@ -446,7 +447,7 @@ function graphifyStatus(cwd) {
     const { graphPath, configured } = resolveGraphLocation(cwd, planningDir);
     if (!node_fs_1.default.existsSync(graphPath)) {
         return { exists: false, graph_path: graphPath, message: configured
-                ? `Configured graph not found at ${graphPath}. Set graphify.graph_path or run /gsd:graphify build.`
+                ? `Configured graph not found at ${graphPath}. Set graphify.graph_path or run ${(0, runtime_slash_cjs_1.runtimeCommand)(cwd, 'graphify build')}.`
                 : 'No graph built yet. Run graphify build to create one.' };
     }
     const stat = node_fs_1.default.statSync(graphPath);

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

@@ -157,6 +157,24 @@ function slugifyPhaseName(phaseName) {
     // the same reported phase_slug.
     return phaseName ? coreUtils.generateSlugInternal(phaseName, null) : null;
 }
+/**
+ * #4854: the one place that decides which name an `init` verb emits as
+ * `phase_name`. When a phase directory exists, `searchPhaseInDir` derives
+ * `phaseInfo.phase_name` from the directory-name remainder — already slugified
+ * (`phase.add` writes `${num}-${slug}` dirs), so it comes out byte-identical to
+ * `phase_slug`. The ROADMAP carries the curated display name
+ * (`### Phase N: <Name>`), so it wins; the disk-derived name is the fallback
+ * for a phase the ROADMAP does not describe, then `null`. #3171 fixed this
+ * inline for `init execute-phase` only; plan-phase (whose `phase_name` reaches
+ * STATE.md through `state planned-phase --name`), verify-work, code-review,
+ * discuss-phase-assumptions and phase-op read the raw disk value. `phase_slug`
+ * is deliberately not routed through here — it stays disk-derived.
+ */
+function resolvePhaseDisplayName(phaseInfo, roadmapPhase) {
+    return roadmapPhase?.['phase_name']
+        || phaseInfo?.['phase_name']
+        || null;
+}
 /**
  * #2994 (review finding, DEFECT.GENERATIVE-FIX): shared archived/not-found
  * fallback applied identically by `cmdInitExecutePhase`, `cmdInitPlanPhase`,
@@ -164,10 +182,11 @@ function slugifyPhaseName(phaseName) {
  * `cmdInitDiscussPhaseAssumptions` — 6 call sites previously reproducing the
  * exact same two-branch control flow verbatim (only the synthetic
  * replacement object's field set differs per caller, supplied here via
- * `buildFallback`). `cmdInitPhaseOp` is deliberately left untouched (CRITICAL
- * blast radius, 179 dependents) even though it follows the same shape, since
- * its own fallback object differs by one field (`has_reviews` absent) and is
- * not a byte-identical copy.
+ * `buildFallback`). `cmdInitPhaseOp` does not use this helper (its own fallback
+ * object differs by one field, `has_reviews` absent, so it is not a
+ * byte-identical copy), but since #4854 it resolves `roadmapPhase` once up
+ * front like the others, so `resolvePhaseDisplayName` sees it in the ordinary
+ * case too.
  *
  * Behavior-preserving by construction: every original call site either (a)
  * unconditionally computed `roadmapPhase` once up front and then applied
@@ -924,7 +943,7 @@ function cmdInitExecutePhase(cwd, phase, raw, options = {}) {
         // the human-curated display name (`### Phase N: <Name>`); prefer it,
         // matching the no-disk fallback above. phase_slug stays disk-derived — it
         // correctly feeds branch-name construction below and is unchanged here.
-        phase_name: (roadmapPhase?.['phase_name']) || (phaseInfo?.['phase_name']) || null,
+        phase_name: resolvePhaseDisplayName(phaseInfo, roadmapPhase),
         phase_slug: phaseInfo?.['phase_slug'] || null,
         phase_req_ids,
         plans: phaseInfo?.['plans'] || [],
@@ -1043,7 +1062,7 @@ function cmdInitPlanPhase(cwd, phase, raw, options = {}) {
     const phase_req_ids = reqExtracted && reqExtracted !== 'TBD' ? reqExtracted : null;
     const phaseDirPlan = phaseInfo?.['directory'] || null;
     const phaseNumberPlan = phaseInfo?.['phase_number'] || null;
-    const phaseNamePlan = phaseInfo?.['phase_name'] || null;
+    const phaseNamePlan = resolvePhaseDisplayName(phaseInfo, roadmapPhase);
     const rawProjectCodePlan = config.project_code || '';
     let expectedPhaseDirPlan = null;
     if (!phaseDirPlan && phaseNumberPlan && phaseNamePlan) {
@@ -1689,7 +1708,7 @@ function cmdInitVerifyWork(cwd, phase, raw) {
         // itself stays relative — evaluateUatPassed above still joins it against cwd.
         phase_dir: phaseDir ? toPosixPath(node_path_1.default.join(cwd, phaseDir)) : null,
         phase_number: phaseInfo?.['phase_number'] || null,
-        phase_name: phaseInfo?.['phase_name'] || null,
+        phase_name: resolvePhaseDisplayName(phaseInfo, roadmapPhase),
         // #2376: verify-work.md's plan_gap_closure step reads these instead of
         // hardcoding '.planning/STATE.md' / '.planning/ROADMAP.md' literals.
         state_path: toPosixPath(node_path_1.default.join(planningDir(cwd), 'STATE.md')),
@@ -1761,7 +1780,7 @@ function cmdInitCodeReview(cwd, phase, raw, options = {}) {
     });
     const phaseDir = phaseInfo?.['directory'] || null;
     const phaseNumber = phaseInfo?.['phase_number'] || null;
-    const phaseName = phaseInfo?.['phase_name'] || null;
+    const phaseName = resolvePhaseDisplayName(phaseInfo, roadmapPhase);
     const fallow = detectFallowConfig(cwd);
     const result = {
         commit_docs: config.commit_docs,
@@ -1890,7 +1909,7 @@ function cmdInitDiscussPhaseAssumptions(cwd, phase, raw, options = {}) {
     });
     const phaseDir = phaseInfo?.['directory'] || null;
     const phaseNumber = phaseInfo?.['phase_number'] || null;
-    const phaseName = phaseInfo?.['phase_name'] || null;
+    const phaseName = resolvePhaseDisplayName(phaseInfo, roadmapPhase);
     // #2994: mirrors discuss-phase-assumptions.md's own auto_advance step
     // resolver — `--auto` flag OR the consolidated `check auto-mode --pick
     // active` fact (workflow._auto_chain_active OR workflow.auto_advance).
@@ -1942,8 +1961,10 @@ function cmdInitPhaseOp(cwd, phase, raw) {
         output(withProjectRoot(cwd, result), raw);
         return;
     }
+    // #4854: resolved once, up front (a pure read — guardedGetRoadmapPhase has no side effects),
+    // so the ordinary case (phase dir on disk, not archived) also sees the ROADMAP display name.
+    const roadmapPhase = guardedGetRoadmapPhase(cwd, phase, config.project_code);
     if (phaseInfo?.['archived']) {
-        const roadmapPhase = guardedGetRoadmapPhase(cwd, phase, config.project_code);
         if (roadmapPhase?.['found']) {
             const phaseName = roadmapPhase['phase_name'];
             phaseInfo = {
@@ -1966,7 +1987,6 @@ function cmdInitPhaseOp(cwd, phase, raw) {
         }
     }
     if (!phaseInfo) {
-        const roadmapPhase = guardedGetRoadmapPhase(cwd, phase, config.project_code);
         if (roadmapPhase?.['found']) {
             const phaseName = roadmapPhase['phase_name'];
             phaseInfo = {
@@ -1990,7 +2010,7 @@ function cmdInitPhaseOp(cwd, phase, raw) {
     }
     const phaseDir = phaseInfo?.['directory'] || null;
     const phaseNumber = phaseInfo?.['phase_number'] || null;
-    const phaseName = phaseInfo?.['phase_name'] || null;
+    const phaseName = resolvePhaseDisplayName(phaseInfo, roadmapPhase);
     const rawProjectCode = config.project_code || '';
     let expectedPhaseDir = null;
     if (!phaseDir && phaseNumber && phaseName) {

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

@@ -1741,6 +1741,17 @@ function _installNativePluginIfDeclared(runtime, configDir, behaviors, src) {
             }
         }
     }
+    // OpenCode 2.x terminal-client plugin (ADR-5331 Phase 3): a TUI entrypoint kept in its own directory under
+    // plugins/. OpenCode 1.x scans plugins/*.js|ts only, so it never loads this directory.
+    const cli = behaviors.nativeCliPlugin;
+    if (cli && cli.source) {
+        const cliSrc = node_path_1.default.join(src, cli.source);
+        if (installFs().existsSync(cliSrc)) {
+            const cliDest = runtimeArtifactInstallPlan.assertDestWithinConfigHome(configDir, node_path_1.default.join(cli.dir, cli.file));
+            installFs().mkdirSync(node_path_1.default.dirname(cliDest), { recursive: true });
+            installFs().copyFileSync(cliSrc, cliDest);
+        }
+    }
 }
 // ---------------------------------------------------------------------------
 // _migrateLegacyOpencodeCommandDir

package/gsd-core/bin/lib/install-shadow-report.cjs

@@ -23,6 +23,10 @@
  * (design row #5 / "Not-corruption"). `kindsDiffer` on `ShadowReport` is what
  * lets `renderShadowReport` word the two cases correctly.
  *
+ * Same-scope pairs are not reported: a runtime whose layout installs `commands` and `skills` side by side at one
+ * scope (OpenCode, Kilo, Augment, CodeBuddy, ZCode) writes both on purpose, and `isGenuinelyShadowed` requires the
+ * winner and the loser to sit in different scopes (#5344).
+ *
  * ── Report, don't correct (mirrors the resolver's own law) ─────────────────
  * `mismatches` surfaces a declared runtime/scope that disagrees with the
  * probed one (Postel's Law, design doc: liberal in what is accepted, but the
@@ -218,6 +222,14 @@ function stemFromTrigger(trigger, prefix) {
 function isGenuinelyShadowed(t, scopeRecords, prefixFor) {
     if (t.shadowedBy === null)
         return false;
+    // This is a CROSS-SCOPE report (see the module comment). A winner and a loser in the SAME scope are the two
+    // kinds one install deliberately wrote side by side — OpenCode, Kilo, Augment, CodeBuddy and ZCode install
+    // `commands` and `skills` for every trigger at one scope. GSD wrote both, the operator cannot act on it, and
+    // the host's own dedupe (OpenCode 1.x lists the command and drops the same-named skill; 2.x keeps them on
+    // separate surfaces) is not a loss of reachability. Reporting it printed "72 triggers shadowed" on every
+    // install of those five runtimes (#5344).
+    if (t.shadowedBy.scope === t.scope)
+        return false;
     const winnerRecord = scopeRecords.get(t.shadowedBy.scope);
     const shadowedRecord = scopeRecords.get(t.scope);
     const winnerStem = stemFromTrigger(t.trigger, prefixFor(t.shadowedBy.scope, t.shadowedBy.kind));

package/gsd-core/bin/lib/installer-migrations/011-opencode-mcp-no-prompts.cjs

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * Installer migration: stop the GSD MCP companion from duplicating every GSD command in OpenCode
+ * (#5338; epic #5331, ADR-5331 D6).
+ *
+ * OpenCode turns each MCP prompt into a `<server>:<prompt>` slash command. The GSD companion server
+ * advertised its whole prompt catalog, so with the command files the installer already writes every GSD
+ * command appeared twice (`gsd-plan-phase` and `gsd:plan-phase`; 143 entries against 72 observed on
+ * OpenCode 2.0.27). New installs register the server with `--no-prompts`. This migration converges an
+ * existing install by adding that flag to the `gsd` MCP entry GSD itself wrote — and only that entry: a
+ * `gsd` server the user edited or defined does not match the installer's shape and is never touched.
+ *
+ * It applies to OpenCode on both generations (the entry is the same shape), covers the 1.x `mcp.gsd` and
+ * the 2.x native `mcp.servers.gsd` locations, and edits the config as text so a commented `opencode.jsonc`
+ * keeps its comments and layout (#5334).
+ *
+ * Is the action safe in non-interactive install?
+ *   Yes. `rewrite-json` is non-interactive and journaled; the rewrite is a one-token append to a command
+ *   array the installer wrote.
+ *
+ * See docs/installer-migrations.md#shipped-migrations and the OpenCode row of
+ * docs/installer-migrations.md#runtime-configuration-contract-registry.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const jsonc_edit_cjs_1 = require("../jsonc-edit.cjs");
+const opencode_mcp_entry_cjs_1 = require("../opencode-mcp-entry.cjs");
+/** OpenCode reads `opencode.jsonc` in preference to `opencode.json` when both exist. */
+const CONFIG_CANDIDATES = ['opencode.jsonc', 'opencode.json'];
+function isPlainObject(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+const migration = {
+    id: '2026-10-12-opencode-mcp-no-prompts',
+    title: 'Stop the GSD MCP companion duplicating GSD commands in OpenCode',
+    description: 'Add --no-prompts to the GSD-written `gsd` MCP server entry in opencode.json(c) (mcp.gsd, and the ' +
+        'OpenCode 2.x native mcp.servers.gsd) so OpenCode no longer lists every GSD command a second time as ' +
+        'a `gsd:<name>` MCP-prompt command. Only the entry the installer wrote is changed; comments and ' +
+        'layout in a JSONC config are preserved (#5338, #5334).',
+    introducedIn: '1.17.0',
+    runtimes: ['opencode'],
+    scopes: ['global', 'local'],
+    destructive: false,
+    runtimeContract: 'docs/installer-migrations.md#runtime-configuration-contract-registry OpenCode row',
+    plan: (ctx) => {
+        if (ctx.runtime !== 'opencode')
+            return [];
+        // The file OpenCode (and the installer's resolveOpencodeConfigPath) treats as THE config.
+        const relPath = CONFIG_CANDIDATES.find((name) => node_fs_1.default.existsSync(node_path_1.default.join(ctx.configDir, name)));
+        if (!relPath)
+            return [];
+        let config;
+        try {
+            config = (0, jsonc_edit_cjs_1.parseJsonc)(node_fs_1.default.readFileSync(node_path_1.default.join(ctx.configDir, relPath), 'utf8'));
+        }
+        catch {
+            return []; // unparseable: never touch a config we cannot read (same posture as the installer)
+        }
+        if (!isPlainObject(config) || !isPlainObject(config['mcp']))
+            return [];
+        const mcp = config['mcp'];
+        const edits = [];
+        const next = { ...config, mcp: { ...mcp } };
+        const nextMcp = next['mcp'];
+        const legacy = mcp['gsd'];
+        if ((0, opencode_mcp_entry_cjs_1.isGsdMcpEntry)(legacy) && !(0, opencode_mcp_entry_cjs_1.hasNoPromptsFlag)(legacy)) {
+            const updated = (0, opencode_mcp_entry_cjs_1.withNoPromptsFlag)(legacy);
+            nextMcp['gsd'] = updated;
+            edits.push({ path: ['mcp', 'gsd', 'command'], value: updated.command });
+        }
+        const servers = mcp['servers'];
+        if (isPlainObject(servers)) {
+            const native = servers['gsd'];
+            if ((0, opencode_mcp_entry_cjs_1.isGsdMcpEntry)(native) && !(0, opencode_mcp_entry_cjs_1.hasNoPromptsFlag)(native)) {
+                const updated = (0, opencode_mcp_entry_cjs_1.withNoPromptsFlag)(native);
+                nextMcp['servers'] = { ...servers, gsd: updated };
+                edits.push({ path: ['mcp', 'servers', 'gsd', 'command'], value: updated.command });
+            }
+        }
+        if (edits.length === 0)
+            return [];
+        return [
+            {
+                type: 'rewrite-json',
+                relPath,
+                value: next,
+                edits,
+                reason: 'the GSD MCP companion advertised its prompt catalog, which OpenCode lists as a second set of ' +
+                    '`gsd:<name>` slash commands next to the installed command files',
+                ownershipEvidence: "the entry matches the exact shape configureOpencodePermissions writes: type 'local' and a command " +
+                    "array of `npx … <package> gsd-mcp-server`; a user-edited or user-defined `gsd` server does not match",
+            },
+        ];
+    },
+};
+module.exports = migration;

package/gsd-core/bin/lib/installer-migrations.cjs

@@ -18,6 +18,7 @@ const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs")
 const clock_cjs_1 = require("./clock.cjs");
 const install_scope_cjs_1 = require("./install-scope.cjs");
 const security_cjs_1 = require("./security.cjs");
+const jsonc_edit_cjs_1 = require("./jsonc-edit.cjs");
 // #2874 (ADR-58 cleanup phase): this file is the ~1200-line migration
 // plan/apply/rollback/lock/journal engine — almost none of it is on the
 // installRuntimeArtifacts call tree. Only `readInstallManifest` and
@@ -293,15 +294,25 @@ function readInstallManifest(configDir) {
         scope: (0, install_scope_cjs_1.isInstallScopeId)(m.scope) ? m.scope : null,
     };
 }
+function normalizeHostGeneration(raw) {
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const r = raw;
+    if (r.runtime !== 'opencode' || (r.generation !== 1 && r.generation !== 2))
+        return undefined;
+    return { runtime: 'opencode', generation: r.generation, version: typeof r.version === 'string' ? r.version : null };
+}
 function readInstallState(configDir) {
     const state = readJsonIfPresent(node_path_1.default.join(configDir, INSTALL_STATE_NAME), STRICT_JSON);
     if (!state || typeof state !== 'object') {
         return { schemaVersion: 1, appliedMigrations: [] };
     }
     const s = state;
+    const hostGeneration = normalizeHostGeneration(s.hostGeneration);
     return {
         schemaVersion: typeof s.schemaVersion === 'number' ? s.schemaVersion : 1,
         appliedMigrations: Array.isArray(s.appliedMigrations) ? s.appliedMigrations : [],
+        ...(hostGeneration ? { hostGeneration } : {}),
     };
 }
 // Strict atomic write for the install state: must never be left half-written.
@@ -654,6 +665,31 @@ function journalAction(action, status, extras = {}) {
     const { value: _value, ...safeAction } = action;
     return { ...safeAction, ...extras, status };
 }
+/**
+ * The text a `rewrite-json` action writes. A file with JSONC syntax (comments, trailing commas, or a
+ * `.jsonc` name) is edited in place from the action's `edits`, so the user's annotations survive (#5334);
+ * everything else, and any edit the text editor cannot place, is written as the action's whole `value`.
+ */
+function renderRewrittenJson(fullPath, action) {
+    if (Array.isArray(action.edits) && action.edits.length > 0) {
+        let original = null;
+        try {
+            original = node_fs_1.default.readFileSync(fullPath, 'utf8');
+        }
+        catch { /* fall through to the value rewrite */ }
+        if (original !== null && (fullPath.endsWith('.jsonc') || (0, jsonc_edit_cjs_1.hasJsoncFeatures)(original))) {
+            let text = original;
+            for (const edit of action.edits) {
+                text = (0, jsonc_edit_cjs_1.setJsoncValue)(text, edit.path, edit.value);
+                if (text === null)
+                    break;
+            }
+            if (text !== null)
+                return text;
+        }
+    }
+    return JSON.stringify(action.value, null, 2) + '\n';
+}
 function planInstallerMigrations({ configDir, runtime = null, scope = null, migrations, baselineScan = false, now = () => new Date().toISOString(), }) {
     if (!configDir)
         throw new Error('configDir is required');
@@ -725,6 +761,8 @@ function planInstallerMigrations({ configDir, runtime = null, scope = null, migr
             }
             if (action.type === 'rewrite-json') {
                 action.value = rawAction.value;
+                if (Array.isArray(rawAction.edits))
+                    action.edits = rawAction.edits;
                 action.deleteIfEmpty = rawAction.deleteIfEmpty === true;
             }
             if (rawAction.prompt)
@@ -896,7 +934,7 @@ function applyInstallerMigrationPlan({ configDir, plan, now = () => new Date().t
                     }));
                 }
                 else {
-                    (0, shell_command_projection_cjs_1.platformWriteSync)(fullPath, JSON.stringify(action.value, null, 2) + '\n');
+                    (0, shell_command_projection_cjs_1.platformWriteSync)(fullPath, renderRewrittenJson(fullPath, action));
                     journal.actions.push(journalAction(action, 'rewritten', {
                         rollbackRelPath: node_path_1.default.posix.join(rollbackRootRelPath, normalized),
                     }));
@@ -945,6 +983,7 @@ function applyInstallerMigrationPlan({ configDir, plan, now = () => new Date().t
         writeInstallState(configDir, {
             schemaVersion: 1,
             appliedMigrations: nextApplied,
+            ...(state.hostGeneration ? { hostGeneration: state.hostGeneration } : {}),
         });
         return {
             appliedMigrationIds: journal.appliedMigrationIds,
@@ -1017,6 +1056,7 @@ function markPendingMigrationsApplied({ configDir, plan, now = () => new Date().
         writeInstallState(configDir, {
             schemaVersion: 1,
             appliedMigrations: nextApplied,
+            ...(state.hostGeneration ? { hostGeneration: state.hostGeneration } : {}),
         });
     }
     return newlyApplied;
@@ -1073,6 +1113,18 @@ function runInstallerMigrations({ configDir, runtime = null, scope = null, migra
 // Unused but kept to satisfy eslint — sleepSync is referenced in the original
 // and may be used by test code that patches this module.
 void sleepSync;
+/**
+ * Record which OpenCode generation this install targets (ADR-5331 D2; #5337). Idempotent and
+ * atomic; leaves the applied-migrations journal untouched.
+ */
+function recordHostGeneration(configDir, info) {
+    const state = readInstallState(configDir);
+    const next = { runtime: 'opencode', generation: info.generation, version: info.version ?? null };
+    const prev = state.hostGeneration;
+    if (prev && prev.generation === next.generation && prev.version === next.version)
+        return;
+    writeInstallState(configDir, { ...state, hostGeneration: next });
+}
 module.exports = {
     DEFAULT_MIGRATIONS_DIR,
     INSTALL_MIGRATION_LOCK_NAME,
@@ -1089,6 +1141,7 @@ module.exports = {
     planInstallerMigrations,
     readInstallManifest,
     readInstallState,
+    recordHostGeneration,
     runInstallerMigrations,
     writeInstallState,
 };