@opengsd/gsd-core 1.6.1 → 1.7.0-rc.2

package/bin/install.js

@@ -37,7 +37,7 @@ const {
 // installer to the runtime-name-policy leaf (ADR-1508 / #1510 Phase 1) so the
 // conversion module's rewrite engine can consume it without importing
 // bin/install.js. Re-exported below for back-compat consumers/tests.
-const { getDirName } = require('../gsd-core/bin/lib/runtime-name-policy.cjs');
+const { getDirName, getRuntimeLabel, getGlobalConfigHomeFragment, runtimeFlags, getRuntimeNewProjectCommand } = require('../gsd-core/bin/lib/runtime-name-policy.cjs');
 const {
   applyWorktreeBaseRef,
   readBaseRefFromSettings,
@@ -364,6 +364,7 @@ const {
   resolveRuntimeArtifactLayout,
 } = require(path.join(_gsdLibDir, 'runtime-artifact-layout.cjs'));
 const {
+  assertDestWithinConfigHome,
   createRuntimeArtifactInstallPlan,
   createRuntimeArtifactUninstallPlan,
 } = require(path.join(_gsdLibDir, 'runtime-artifact-install-plan.cjs'));
@@ -373,8 +374,34 @@ const {
 } = require(path.join(__dirname, '..', 'gsd-core', 'bin', 'lib', 'legacy-cleanup.cjs'));
 const {
   updateCacheFileName,
+  PACKAGE_NAME,
 } = require(path.join(__dirname, '..', 'gsd-core', 'bin', 'lib', 'package-identity.cjs'));
 
+// ADR-1239 Phase B: runtime-artifact install cluster extracted to install-engine.cjs.
+// getCommitAttribution STAYS here (impure install-time config I/O); it is injected
+// into the engine functions via the resolveAttribution parameter at each call site.
+const installEngine = require(path.join(_gsdLibDir, 'install-engine.cjs'));
+const {
+  installRuntimeArtifacts,
+  uninstallRuntimeArtifacts,
+  installOpencodeFamilySkills,
+  _copyStaged,
+  hasExistingSymlinkBetween,
+  preserveUserArtifacts,
+  restoreUserArtifacts,
+  migrateLegacyDevPreferencesToSkill,
+  applyOpencodeFamilyPathPrefix,
+  convertClaudeCommandToOpencodeSkill,
+  convertClaudeCommandToKiloSkill,
+  USER_OWNED_ARTIFACTS,
+  _runLegacyInstallMigrations,
+  _runLegacyUninstallCleanup,
+  _removeGsdEntries,
+  _snapshotDir,
+  _restoreDir,
+  _removeHermesBareStemDirs,
+} = installEngine;
+
 // Parse args
 const args = process.argv.slice(2);
 const hasGlobal = args.includes('--global') || args.includes('-g');
@@ -484,18 +511,11 @@ function getConfigDirFromHome(runtime, isGlobal) {
     // Local installs use the same dir name pattern
     return `'${getDirName(runtime)}'`;
   }
-  // Global installs - OpenCode uses XDG path structure
-  if (runtime === 'copilot') return "'.copilot'";
-  if (runtime === 'opencode') {
-    // OpenCode: ~/.config/opencode -> '.config', 'opencode'
-    // Return as comma-separated for path.join() replacement
-    return "'.config', 'opencode'";
-  }
-  if (runtime === 'gemini') return "'.gemini'";
-  if (runtime === 'kilo') return "'.config', 'kilo'";
-  if (runtime === 'codex') return "'.codex'";
+  // Global installs. antigravity's home is resolved dynamically (env-overridable,
+  // multi-segment via resolveAntigravityGlobalDir + path.relative) — not a table
+  // entry. (The prior inner `if (!isGlobal) return "'.agents'"` was unreachable:
+  // !isGlobal returns at the top of this function.)
   if (runtime === 'antigravity') {
-    if (!isGlobal) return "'.agents'";
     const antigravityDir = resolveAntigravityGlobalDir();
     const rel = path.relative(os.homedir(), antigravityDir);
     const segments = rel.split(path.sep).filter(Boolean);
@@ -506,16 +526,9 @@ function getConfigDirFromHome(runtime, isGlobal) {
     // stable legacy template so generated path.join() calls remain valid.
     return "'.gemini', 'antigravity'";
   }
-  if (runtime === 'cursor') return "'.cursor'";
-  if (runtime === 'windsurf') return "'.windsurf'";
-  if (runtime === 'augment') return "'.augment'";
-  if (runtime === 'trae') return "'.trae'";
-  if (runtime === 'qwen') return "'.qwen'";
-  if (runtime === 'hermes') return "'.hermes'";
-  if (runtime === 'codebuddy') return "'.codebuddy'";
-  if (runtime === 'cline') return "'.cline'";
-  if (runtime === 'kimi') return "'.config', 'agents'";
-  return "'.claude'";
+  // All other runtimes: single source-of-truth fragment table (ADR-1239 Phase B,
+  // #1679). claude/unknown fall through to the table's default '.claude'.
+  return getGlobalConfigHomeFragment(runtime);
 }
 
 /**
@@ -630,6 +643,15 @@ const processAttribution = runtimeArtifactConversion.processAttribution;
 const computePathPrefix = runtimeArtifactConversion._computePathPrefix;
 const applyRuntimeContentRewritesInPlace = runtimeArtifactConversion.applyRuntimeContentRewritesInPlace;
 const applyRuntimeContentRewritesForCommandsInPlace = runtimeArtifactConversion.applyRuntimeContentRewritesForCommandsInPlace;
+// #1675 (ADR-1508): the augment converter family is single-sourced in the
+// conversion module. install.js re-binds (does not re-define) these so there
+// is exactly one body — the generative-drift hazard the dedup removes. The two
+// private helpers (getAugmentSkillAdapterHeader, convertSlashCommandsToAugmentSkillMentions)
+// live only in the conversion module now; they are no longer duplicated here.
+// (All call sites are below this line → no TDZ hazard.)
+const convertClaudeToAugmentMarkdown = runtimeArtifactConversion.convertClaudeToAugmentMarkdown;
+const convertClaudeCommandToAugmentSkill = runtimeArtifactConversion.convertClaudeCommandToAugmentSkill;
+const convertClaudeAgentToAugmentAgent = runtimeArtifactConversion.convertClaudeAgentToAugmentAgent;
 
 function rewriteLegacyManagedNodeHookCommands(settings, absoluteRunner, opts) {
   return hooksSurface.rewriteLegacyManagedNodeHookCommands(settings, absoluteRunner, opts);
@@ -2580,105 +2602,14 @@ const claudeToAugmentTools = {
   TodoWrite: 'add_tasks',
 };
 
-function convertSlashCommandsToAugmentSkillMentions(content) {
-  return content.replace(/gsd:/gi, 'gsd-');
-}
-
-function convertClaudeToAugmentMarkdown(content) {
-  let converted = convertSlashCommandsToAugmentSkillMentions(content);
-  converted = converted.replace(/\bBash\(/g, 'launch-process(');
-  converted = converted.replace(/\bEdit\(/g, 'str-replace-editor(');
-  converted = converted.replace(/\bRead\(/g, 'view(');
-  converted = converted.replace(/\bWrite\(/g, 'save-file(');
-  converted = converted.replace(/\bTodoWrite\(/g, 'add_tasks(');
-  converted = converted.replace(/\bAskUserQuestion\b/g, 'conversational prompting');
-  // Replace subagent_type from Claude to Augment format
-  converted = converted.replace(/subagent_type="general-purpose"/g, 'subagent_type="generalPurpose"');
-  converted = converted.replace(/\$ARGUMENTS\b/g, '{{GSD_ARGS}}');
-  // Replace project-level Claude conventions with Augment equivalents
-  converted = converted.replace(/`\.\/CLAUDE\.md`/g, '`.augment/rules/`');
-  converted = converted.replace(/\.\/CLAUDE\.md/g, '.augment/rules/');
-  converted = converted.replace(/`CLAUDE\.md`/g, '`.augment/rules/`');
-  converted = converted.replace(/\bCLAUDE\.md\b/g, '.augment/rules/');
-  converted = converted.replace(/\.claude\/skills\//g, '.augment/skills/');
-  // Remove Claude Code-specific bug workarounds before brand replacement
-  converted = converted.replace(/\*\*Known Claude Code bug \(classifyHandoffIfNeeded\):\*\*[^\n]*\n/g, '');
-  converted = converted.replace(/- \*\*classifyHandoffIfNeeded false failure:\*\*[^\n]*\n/g, '');
-  // Replace "Claude Code" brand references with "Augment"
-  converted = converted.replace(/\bClaude Code\b/g, 'Augment');
-  return converted;
-}
-
-function getAugmentSkillAdapterHeader(skillName) {
-  return `<augment_skill_adapter>
-## A. Skill Invocation
-- This skill is invoked when the user mentions \`${skillName}\` or describes a task matching this skill.
-- Treat all user text after the skill mention as \`{{GSD_ARGS}}\`.
-- If no arguments are present, treat \`{{GSD_ARGS}}\` as empty.
-
-## B. User Prompting
-When the workflow needs user input, prompt the user conversationally:
-- Present options as a numbered list in your response text
-- Ask the user to reply with their choice
-- For multi-select, ask for comma-separated numbers
-
-## C. Tool Usage
-Use these Augment tools when executing GSD workflows:
-- \`launch-process\` for running commands (terminal operations)
-- \`str-replace-editor\` for editing existing files
-- \`view\` for reading files and listing directories
-- \`save-file\` for creating new files
-- \`grep\` for searching code (or use MCP servers for advanced search)
-- \`web-search\`, \`web-fetch\` for web queries
-- \`add_tasks\`, \`view_tasklist\`, \`update_tasks\` for task management
-
-## D. Subagent Spawning
-When the workflow needs to spawn a subagent:
-- Use the built-in subagent spawning capability
-- Define agent prompts in \`.augment/agents/\` directory
-</augment_skill_adapter>`;
-}
-
-function convertClaudeCommandToAugmentSkill(content, skillName) {
-  const converted = convertClaudeToAugmentMarkdown(content);
-  const { frontmatter, body } = extractFrontmatterAndBody(converted);
-  let description = `Run GSD workflow ${skillName}.`;
-  if (frontmatter) {
-    const maybeDescription = extractFrontmatterField(frontmatter, 'description');
-    if (maybeDescription) {
-      description = maybeDescription;
-    }
-  }
-  description = toSingleLine(description);
-  const shortDescription = description.length > 180 ? `${description.slice(0, 177)}...` : description;
-  const adapter = getAugmentSkillAdapterHeader(skillName);
-
-  return `---\nname: ${yamlIdentifier(skillName)}\ndescription: ${yamlQuote(shortDescription)}\n---\n\n${adapter}\n\n${body.trimStart()}`;
-}
-
-/**
- * Convert Claude Code agent markdown to Augment agent format.
- * Strips frontmatter fields Augment doesn't support (color, skills),
- * converts tool references, and cleans up for Augment agents.
- */
-function convertClaudeAgentToAugmentAgent(content) {
-  let converted = convertClaudeToAugmentMarkdown(content);
-
-  const { frontmatter, body } = extractFrontmatterAndBody(converted);
-  if (!frontmatter) return converted;
-
-  const name = extractFrontmatterField(frontmatter, 'name') || 'unknown';
-  const description = extractFrontmatterField(frontmatter, 'description') || '';
-
-  const cleanFrontmatter = `---\nname: ${yamlIdentifier(name)}\ndescription: ${yamlQuote(toSingleLine(description))}\n---`;
-
-  return `${cleanFrontmatter}\n${body}`;
-}
-
-/**
- * Copy Claude commands as Augment skills — one folder per skill with SKILL.md.
- * Mirrors copyCommandsAsCursorSkills but uses Augment converters.
- */
+// #1675 (ADR-1508): the augment converter family below was a byte-identical
+// duplicate of runtime-artifact-conversion.cjs:
+//   convertSlashCommandsToAugmentSkillMentions, convertClaudeToAugmentMarkdown,
+//   getAugmentSkillAdapterHeader, convertClaudeCommandToAugmentSkill,
+//   convertClaudeAgentToAugmentAgent
+// Deleted here and bound from runtimeArtifactConversion above (single source).
+// The DEFECT.GENERATIVE-FIX parity guard in
+// tests/enh-1511-rewrite-engine-relocation.test.cjs asserts reference identity.
 
 function convertSlashCommandsToTraeSkillMentions(content) {
   return content.replace(/\/gsd:([a-z0-9-]+)/g, (_, commandName) => {
@@ -5710,8 +5641,21 @@ function writeCopilotHookConfig(targetDir) {
  * Reads agent .md files from source, extracts metadata, writes .toml configs.
  */
 function installCodexConfig(targetDir, agentsSrc, sandboxTier = 'codex-agent-sandbox') {
-  const configPath = path.join(targetDir, 'config.toml');
-  const agentsTomlDir = path.join(targetDir, 'agents');
+  // ADR-1239 Phase B write-confinement: every Codex config write stays under targetDir.
+  const configPath = assertDestWithinConfigHome(targetDir, 'config.toml');
+  const agentsTomlDir = assertDestWithinConfigHome(targetDir, 'agents');
+  const resolvedTargetRoot = path.resolve(targetDir);
+  // Symlink-escape guard (parity with _copyStaged / copyWithPathReplacement): the
+  // lexical gate above does not resolve symlinks, so a pre-existing config.toml or
+  // agents/ symlink could redirect writes outside targetDir. Reject those.
+  if (
+    hasExistingSymlinkBetween(resolvedTargetRoot, configPath) ||
+    hasExistingSymlinkBetween(resolvedTargetRoot, path.resolve(agentsTomlDir))
+  ) {
+    throw new Error(
+      `installCodexConfig: a Codex config path under "${targetDir}" contains a symlink escaping the install root — refusing to write`,
+    );
+  }
   fs.mkdirSync(agentsTomlDir, { recursive: true });
 
   const agentEntries = fs.readdirSync(agentsSrc).filter(f => f.startsWith('gsd-') && f.endsWith('.md'));
@@ -5756,7 +5700,16 @@ function installCodexConfig(targetDir, agentsSrc, sandboxTier = 'codex-agent-san
     // follows the same config-driven precedence as the Claude .md effort key.
     const effortCfg = readGsdEffectiveEffortConfig(targetDir);
     const tomlContent = generateCodexAgentToml(name, content, modelOverrides, runtimeResolver, effortCfg, sandboxTier);
-    fs.writeFileSync(path.join(agentsTomlDir, `${name}.toml`), tomlContent);
+    // Confine the per-agent write to the agents/ dir itself: a crafted agent
+    // `name` containing path separators must not escape agents/ (which would let
+    // it clobber config.toml or write elsewhere under the configHome).
+    const agentTomlPath = assertDestWithinConfigHome(agentsTomlDir, `${name}.toml`);
+    if (hasExistingSymlinkBetween(resolvedTargetRoot, agentTomlPath)) {
+      throw new Error(
+        `installCodexConfig: agent toml path "${agentTomlPath}" contains a symlink escaping the install root — refusing to write`,
+      );
+    }
+    fs.writeFileSync(agentTomlPath, tomlContent);
   }
 
   const gsdBlock = generateCodexConfigBlock(agents, targetDir);
@@ -6326,69 +6279,9 @@ function convertClaudeToKiloFrontmatter(content, { isAgent = false } = {}) {
   return `---\n${newFrontmatter}\n---${body}`;
 }
 
-/**
- * Shared SKILL.md writer for the OpenCode-family runtimes (OpenCode + Kilo),
- * which share a config schema (Kilo derives from OpenCode). OpenCode discovers
- * skills as `skills/<name>/SKILL.md` and Kilo follows the same layout
- * (https://opencode.ai/docs/skills, https://kilo.ai/docs/customize/skills).
- *
- * The skill body reuses the runtime's command-frontmatter converter for tool,
- * path, and `/gsd:`→`/gsd-` body rewrites, then rebuilds a minimal skill
- * frontmatter: only `name` (lowercase-hyphen, must match the containing
- * directory) and `description` (1–1024 chars) are emitted, per the OpenCode
- * skill spec. The command's `tools:`/`permission:` block is intentionally
- * dropped — OpenCode skills are loaded on-demand via the native skill tool and
- * inherit the calling agent's permissions.
- *
- * @param {string} content - Claude command markdown (with YAML frontmatter)
- * @param {string} skillName - Skill directory name (e.g. gsd-help)
- * @param {(content: string) => string} frontmatterConverter - runtime command converter
- * @returns {string} SKILL.md content
- */
-function convertClaudeCommandToOpencodeFamilySkill(content, skillName, frontmatterConverter) {
-  const converted = frontmatterConverter(content);
-  const { frontmatter, body } = extractFrontmatterAndBody(converted);
-  let description = `Run GSD workflow ${skillName}.`;
-  if (frontmatter) {
-    const maybeDescription = extractFrontmatterField(frontmatter, 'description');
-    if (maybeDescription) {
-      description = maybeDescription;
-    }
-  }
-  description = toSingleLine(description);
-  // OpenCode skill descriptions must be 1–1024 characters.
-  if (description.length > 1024) {
-    description = `${description.slice(0, 1021)}...`;
-  }
-  // `name` must be lowercase alphanumeric with single-hyphen separators and
-  // match the containing directory name (the staged dir is `${skillName}/`).
-  const name = yamlIdentifier(skillName);
-  return `---\nname: ${name}\ndescription: ${yamlQuote(description)}\n---\n\n${body.trimStart()}`;
-}
-
-/**
- * Convert a Claude command (.md) to an OpenCode skill (SKILL.md).
- * Thin wrapper over the shared OpenCode-family writer.
- */
-function convertClaudeCommandToOpencodeSkill(content, skillName) {
-  return convertClaudeCommandToOpencodeFamilySkill(
-    content,
-    skillName,
-    (c) => convertClaudeToOpencodeFrontmatter(c),
-  );
-}
-
-/**
- * Convert a Claude command (.md) to a Kilo skill (SKILL.md).
- * Thin wrapper over the shared OpenCode-family writer (Kilo shares the schema).
- */
-function convertClaudeCommandToKiloSkill(content, skillName) {
-  return convertClaudeCommandToOpencodeFamilySkill(
-    content,
-    skillName,
-    (c) => convertClaudeToKiloFrontmatter(c),
-  );
-}
+// convertClaudeCommandToOpencodeFamilySkill, convertClaudeCommandToOpencodeSkill,
+// convertClaudeCommandToKiloSkill: moved to src/install-engine.cts (ADR-1239 Phase B).
+// Imported from installEngine above.
 
 /**
  * Convert Claude Code markdown command to Gemini TOML format
@@ -6471,30 +6364,8 @@ function convertClaudeToGeminiToml(content, { commandName = null } = {}) {
  * @param {string} pathPrefix - Path prefix for file references
  * @param {string} runtime - Target runtime ('claude', 'opencode', or 'kilo')
  */
-/**
- * Apply OpenCode-family (`opencode`/`kilo`) `@file` path-prefix rewrites to a
- * RAW Claude command/skill body, BEFORE the frontmatter converter runs.
- *
- * This is the single source of truth shared by copyFlattenedCommands (commands)
- * and installOpencodeFamilySkills (skills) so the two surfaces produce identical
- * path references. Applying pathPrefix pre-conversion (rather than rewriting an
- * already-converted body) is what avoids the converter's hardcoded default
- * config dir leaking into --local / --config-dir installs, and the
- * prefix-overlap double-rewrite hazard for custom dirs like `kilo-alt`. (#784)
- *
- * @param {string} content - raw Claude command markdown
- * @param {string} runtime - 'opencode' or 'kilo'
- * @param {string} pathPrefix - trailing-slash install-target prefix
- * @returns {string}
- */
-function applyOpencodeFamilyPathPrefix(content, runtime, pathPrefix) {
-  content = content.replace(/~\/\.claude\//g, pathPrefix);
-  content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
-  content = content.replace(/\.\/\.claude\//g, `./${getDirName(runtime)}/`);
-  content = content.replace(/~\/\.opencode\//g, pathPrefix);
-  content = content.replace(/~\/\.kilo\//g, pathPrefix);
-  return content;
-}
+// applyOpencodeFamilyPathPrefix: moved to src/install-engine.cts (ADR-1239 Phase B).
+// Imported from installEngine above.
 
 function copyFlattenedCommands(srcDir, destDir, prefix, pathPrefix, runtime) {
   if (!fs.existsSync(srcDir)) {
@@ -6633,688 +6504,140 @@ function writeHermesCategoryDescription(categoryDir) {
  * @param {boolean} isGlobal - Whether this is a global install
  */
 
-/**
- * Single source of truth for user-owned artifacts inside gsd-core/.
- *
- * These files are created/refreshed by user-facing workflows (e.g.
- * /gsd-profile-user) and must be preserved across reinstalls. Critically, they
- * MUST be excluded from gsd-file-manifest.json — otherwise saveLocalPatches()
- * will compare a refreshed file against a stale manifest hash and emit a
- * spurious "locally modified GSD file" warning (bug #2771).
- *
- * Invariant: a file is either distribution (manifest-tracked, diff'd against
- * manifest) or user artifact (preserved across installs, never diff'd). Never
- * both. Both preserveUserArtifacts call sites and writeManifest must agree on
- * this list, which is why it lives here as a single constant.
- *
- * Paths are relative to the gsd-core/ directory.
- */
-const USER_OWNED_ARTIFACTS = ['USER-PROFILE.md'];
-
-/**
- * Save user-generated files from destDir to an in-memory map before a wipe.
- *
- * @param {string} destDir - Directory that is about to be wiped
- * @param {string[]} fileNames - Relative file names (e.g. ['USER-PROFILE.md']) to preserve
- * @returns {Map<string, string>} Map of fileName → file content (only entries that existed)
- */
-function preserveUserArtifacts(destDir, fileNames) {
-  const saved = new Map();
-  for (const name of fileNames) {
-    const fullPath = path.join(destDir, name);
-    if (fs.existsSync(fullPath)) {
-      try {
-        saved.set(name, fs.readFileSync(fullPath, 'utf8'));
-      } catch { /* skip unreadable files */ }
-    }
-  }
-  return saved;
-}
-
-/**
- * Restore user-generated files saved by preserveUserArtifacts after a wipe.
- *
- * @param {string} destDir - Directory that was wiped and recreated
- * @param {Map<string, string>} saved - Map returned by preserveUserArtifacts
- */
-function restoreUserArtifacts(destDir, saved) {
-  for (const [name, content] of saved) {
-    const fullPath = path.join(destDir, name);
-    try {
-      fs.mkdirSync(path.dirname(fullPath), { recursive: true });
-      fs.writeFileSync(fullPath, content, 'utf8');
-    } catch { /* skip unwritable paths */ }
-  }
-}
-
-/**
- * Migrate a legacy dev-preferences.md (saved from commands/gsd/) into the
- * runtime-aware SKILL.md location used by the writer after #2973.
- *
- * For runtimes with a nested skills layout (e.g. Hermes: skills/gsd/<stem>/),
- * the target is <configDir>/skills/gsd/dev-preferences/SKILL.md.
- * For runtimes with a flat skills layout (prefix='gsd-'), the target is
- * <configDir>/skills/gsd-dev-preferences/SKILL.md.
- *
- * Skips silently if no legacy file was preserved, or if a SKILL.md already
- * exists at the new location (don't clobber user-customized skill content
- * — they may have edited the new file directly). Returns true on actual
- * migration so callers can log a one-line confirmation.
- *
- * @param {string} targetDir - Resolved runtime config directory (e.g. ~/.claude)
- * @param {Map<string, string>} saved - Map returned by preserveUserArtifacts
- * @param {string} [runtime] - canonical runtime ID (e.g. 'hermes', 'qwen', 'claude')
- * @param {'global'|'local'} [scope] - install scope
- * @returns {boolean} - true if a file was migrated, false otherwise
- */
-function migrateLegacyDevPreferencesToSkill(targetDir, saved, runtime, scope = 'global') {
-  if (!saved || !saved.has('dev-preferences.md')) return false;
-  let skillDir;
-  if (runtime) {
-    const layout = resolveRuntimeArtifactLayout(runtime, targetDir, scope);
-    const skillsKindEntry = layout.kinds.find((k) => k.kind === 'skills');
-    if (!skillsKindEntry) return false; // runtime has no skills layout at this scope (e.g. cline local)
-    const stemName = skillsKindEntry.prefix === '' ? 'dev-preferences' : 'gsd-dev-preferences';
-    skillDir = path.join(targetDir, skillsKindEntry.destSubpath, stemName);
-  } else {
-    // Legacy fallback for callers that have not yet been updated to pass runtime
-    skillDir = path.join(targetDir, 'skills', 'gsd-dev-preferences');
-  }
-  const skillFile = path.join(skillDir, 'SKILL.md');
-  if (fs.existsSync(skillFile)) return false;
-  try {
-    fs.mkdirSync(skillDir, { recursive: true });
-    fs.writeFileSync(skillFile, saved.get('dev-preferences.md'), 'utf8');
-    return true;
-  } catch {
-    return false;
-  }
-}
+// USER_OWNED_ARTIFACTS, preserveUserArtifacts, restoreUserArtifacts,
+// migrateLegacyDevPreferencesToSkill, _copyStaged, _removeGsdEntries,
+// _runLegacyInstallMigrations, _runLegacyUninstallCleanup, _snapshotDir,
+// _restoreDir, _removeHermesBareStemDirs, installRuntimeArtifacts,
+// installOpencodeFamilySkills, uninstallRuntimeArtifacts:
+// ALL moved to src/install-engine.cts (ADR-1239 Phase B).
+// Imported from installEngine above.
 
 // ---------------------------------------------------------------------------
-// Phase 2 — Layout-driven install/uninstall orchestrators
+// Phase 2 — Layout-driven install/uninstall orchestrators (moved to engine)
+// _applyRuntimeRewrites / _stampNonClaudeRuntimeDefaults remain here for
+// call sites in copyWithPathReplacement (not moved).
 // ---------------------------------------------------------------------------
-
-/**
- * Apply per-runtime content rewrites in place across every SKILL.md inside a
- * staged directory. Reproduces the rewrite scaffolding that the old
- * copyCommandsAs<Runtime>Skills functions applied between read-content and
- * converter-call. Applied AFTER stage (which already called the converter);
- * rewrites target stable path patterns the converter doesn't touch.
- *
- * For Qwen/Hermes, branding rewrites (.claude/ → .qwen/ / .hermes/) run
- * AFTER the slash-form path replacements but they only catch bare `.claude/`
- * patterns (skill-body relative refs) that the slash forms didn't consume.
- * This mirrors the exact ordering in the legacy copyCommandsAsClaudeSkills body.
- *
- * @param {string} stagedDir
- * @param {string} runtime
- * @param {string} pathPrefix  e.g. "~/.codex/" — trailing-slash string
- * @param {boolean} [isGlobal=false]  true when the install is a global (home-dir) install
- */
-// applyRuntimeContentRewritesInPlace: walk loop is now owned by
-// runtimeArtifactConversion.applyRuntimeContentRewritesInPlace (ADR-1508 / #1511 Phase 2).
-// The const binding above (~line 629) delegates here. Call sites in installRuntimeArtifacts
-// pass attribution as the 5th arg (getCommitAttribution(runtime)) per the new contract.
-
-/**
- * Apply per-runtime content rewrites to flat .md files in a staged commands dir.
- * Used for runtimes that have a commandsKind in their layout and need content rewrites
- * (e.g. augment — replaces ~/.claude/ paths and applies branding conversions).
- *
- * IMPORTANT: `stageSkillsForProfile()` returns the original source directory unchanged
- * on a full/default profile (skills === '*'). This function MUST NOT mutate that source
- * directory. It always copies to a temp dir first, rewrites there, and returns the new
- * path so the caller installs from the temp copy, not the source.
- *
- * @param {string} stagedDir  directory of staged flat .md command files (may be source dir)
- * @param {string} runtime
- * @param {string} pathPrefix
- * @param {boolean} [isGlobal=false]  true when the install is a global (home-dir) install
- * @returns {string}  path to a temp dir with rewritten files (caller is responsible for cleanup)
- */
-// applyRuntimeContentRewritesForCommandsInPlace: copy+rewrite loop is now owned by
-// runtimeArtifactConversion.applyRuntimeContentRewritesForCommandsInPlace (ADR-1508 / #1511 Phase 2).
-// The const binding above (~line 630) delegates here. Call sites in installRuntimeArtifacts
-// pass attribution as the 5th arg (getCommitAttribution(runtime)) per the new contract.
-
-/**
- * Apply the per-runtime rewrite table to a single content string.
- * Extracted so it can be unit-tested independently of the filesystem walk.
- *
- * @param {string} content
- * @param {string} runtime
- * @param {string} pathPrefix  trailing-slash string
- * @param {boolean} [isGlobal=false]  true when the install is a global (home-dir) install
- * @returns {string}
- */
-// _applyRuntimeRewrites: single implementation lives in runtimeArtifactConversion
-// (ADR-1508 / #1511 Phase 2). Bound here so install.js call sites and exports are
-// reference-identical to the conversion module (consistent with the walkers above).
-// All call sites are below this line → no TDZ hazard.
 const _applyRuntimeRewrites = runtimeArtifactConversion._applyRuntimeRewrites;
 const _stampNonClaudeRuntimeDefaults = runtimeArtifactConversion._stampNonClaudeRuntimeDefaults;
 
 /**
- * Copy a staged directory's contents into destDir.
- * Additive — does not prune (surface.cjs handles pruning).
- *
- * For skills kind: each child of stagedDir is a `${prefix}${stem}/` dir; copy
- *   the whole dir into destDir.
- * For commands/agents kind: iterate .md files and write them into destDir.
- *   - commands: write as `${prefix}${stem}.md` unless destSubpath already
- *     encodes the GSD namespace as its last segment (e.g. `commands/gsd`), in
- *     which case write as `${stem}.md` (directory IS the namespace).
- *   - agents: write as-is (files already carry their own `gsd-` prefix).
- * For kimi-agents kind: recursively copy generated YAML/prompt files.
- */
-function _copyStaged(stagedDir, destDir, kind) {
-  if (!fs.existsSync(stagedDir)) return;
-  fs.mkdirSync(destDir, { recursive: true });
-
-  if (kind.kind === 'skills') {
-    // Each child of stagedDir is a prefixed skill directory: gsd-help/, etc.
-    for (const entry of fs.readdirSync(stagedDir, { withFileTypes: true })) {
-      if (!entry.isDirectory()) continue;
-      const src = path.join(stagedDir, entry.name);
-      const dest = path.join(destDir, entry.name);
-      fs.cpSync(src, dest, { recursive: true });
-    }
-    return;
-  }
-
-  if (kind.kind === 'kimi-agents') {
-    fs.cpSync(stagedDir, destDir, { recursive: true });
-    return;
-  }
-
-  // commands or agents
-  const entries = fs.readdirSync(stagedDir, { withFileTypes: true });
-  // For commands: apply prefix unless the destSubpath's last segment already
-  // represents the GSD namespace (e.g. 'commands/gsd' → last segment 'gsd').
-  const destLast = path.basename(kind.destSubpath);
-  const prefixStem = kind.prefix ? kind.prefix.replace(/-$/, '') : '';
-  const namespacedByDir = kind.kind === 'commands' && destLast === prefixStem;
-
-  for (const entry of entries) {
-    if (!entry.isFile()) continue;
-    if (!entry.name.endsWith('.md')) continue;
-    const stem = entry.name.slice(0, -3); // strip .md
-
-    let destName;
-    if (kind.kind === 'agents') {
-      // Agent files already carry the gsd- prefix in the source dir
-      destName = entry.name;
-    } else if (namespacedByDir) {
-      // Directory is the namespace; don't double-prefix the filename
-      destName = entry.name;
-    } else {
-      // Flat commands directory (e.g. command/ for opencode/kilo)
-      destName = `${kind.prefix}${stem}.md`;
-    }
-
-    fs.copyFileSync(path.join(stagedDir, entry.name), path.join(destDir, destName));
-  }
-}
-
-/**
- * Remove GSD-prefixed entries from destDir matching kind.prefix.
- * For the prefix='' case: the destSubpath IS the namespace — remove the entire
- * destDir. (No current runtime uses prefix='' after #947 reversed Hermes; kept
- * as a defensive guard for future runtimes.)
- */
-function _removeGsdEntries(destDir, kind) {
-  if (!fs.existsSync(destDir)) return;
-  if (kind.kind === 'kimi-agents') {
-    for (const fileName of ['gsd.yaml', 'gsd.md']) {
-      fs.rmSync(path.join(destDir, fileName), { force: true });
-    }
-    const subagentsDir = path.join(destDir, 'subagents');
-    if (fs.existsSync(subagentsDir)) {
-      for (const entry of fs.readdirSync(subagentsDir, { withFileTypes: true })) {
-        if (!entry.isFile()) continue;
-        if (!entry.name.startsWith('gsd-')) continue;
-        if (!entry.name.endsWith('.yaml') && !entry.name.endsWith('.md')) continue;
-        fs.rmSync(path.join(subagentsDir, entry.name), { force: true });
-      }
-    }
-    return;
-  }
-  if (kind.prefix === '') {
-    // Whole-namespace removal (Hermes nested case — destSubpath is skills/gsd)
-    // The directory itself is the GSD namespace, so remove it entirely.
-    fs.rmSync(destDir, { recursive: true, force: true });
-    return;
-  }
-  for (const entry of fs.readdirSync(destDir, { withFileTypes: true })) {
-    if (!entry.name.startsWith(kind.prefix)) continue;
-    fs.rmSync(path.join(destDir, entry.name), { recursive: true, force: true });
-  }
-}
-
-/**
- * Run legacy install migrations that must execute BEFORE the layout-driven
- * copy so stale artifacts are cleaned up before new ones are written.
- *
- * - Claude/Qwen/Hermes: migrate legacy commands/gsd/dev-preferences.md →
- *   skills/gsd-dev-preferences/SKILL.md if the old file is present.
- *   Also removes the legacy commands/gsd/ directory.
- * - Hermes: remove flat skills/gsd-STAR directories (pre-2841 layout) before
- *   writing the new nested skills/gsd/ layout.
- *
- * @param {string} runtime
- * @param {string} configDir  resolved runtime config directory
- * @param {'global'|'local'} [scope]
- */
-function _runLegacyInstallMigrations(runtime, configDir, scope = 'global') {
-  const legacyCommandsGsd = path.join(configDir, 'commands', 'gsd');
-
-  // Claude / Qwen / Hermes: clean up legacy commands/gsd/ and preserve dev-preferences
-  // for migration. The actual migration call is deferred to after all layout cleanup so
-  // that for Hermes the flat skills/gsd-*/ removal (below) does not delete the freshly
-  // created skills/gsd-dev-preferences/ skill dir.
-  let savedLegacyArtifacts = null;
-  if (runtime === 'claude' || runtime === 'qwen' || runtime === 'hermes') {
-    if (fs.existsSync(legacyCommandsGsd)) {
-      savedLegacyArtifacts = preserveUserArtifacts(legacyCommandsGsd, ['dev-preferences.md']);
-      fs.rmSync(legacyCommandsGsd, { recursive: true });
-    }
-  }
-
-  // Hermes: remove pre-#2841 flat skills/gsd-*/ entries that lived alongside
-  // the new skills/gsd/ nested layout.
-  if (runtime === 'hermes') {
-    const flatSkillsDir = path.join(configDir, 'skills');
-    if (fs.existsSync(flatSkillsDir)) {
-      for (const entry of fs.readdirSync(flatSkillsDir, { withFileTypes: true })) {
-        if (entry.isDirectory() && entry.name.startsWith('gsd-')) {
-          fs.rmSync(path.join(flatSkillsDir, entry.name), { recursive: true });
-        }
-      }
-    }
-
-    // Hermes: bare-stem skills/gsd/<stem>/ cleanup is deferred to AFTER the
-    // layout-driven install loop in installRuntimeArtifacts, where the exact set
-    // of staged gsd-<stem>/ dirs is known. Removing here (before staging) would
-    // require readGsdCommandNames() which misses skills like 'dev-preferences'
-    // that are not in the commands directory. See _removeHermesBareStemDirs().
-  }
-
-  // Migrate dev-preferences.md content → runtime-aware SKILL.md location (#2973).
-  // Done after all layout cleanup so Hermes flat-dir removal does not delete the
-  // newly created skill dir. No-op if skill file already exists.
-  if (savedLegacyArtifacts) {
-    migrateLegacyDevPreferencesToSkill(configDir, savedLegacyArtifacts, runtime, scope);
-  }
-}
-
-/**
- * Run legacy uninstall cleanup that must execute BEFORE the layout-driven
- * removal so old-format entries are also cleaned up.
- *
- * - Claude global/Qwen: remove legacy commands/gsd/ directory if present.
- *   For Claude LOCAL, commands/gsd/ is the current primary location (not
- *   legacy), so we skip removal here and let _removeGsdEntries handle it
- *   with gsd- prefix filtering (preserving user files like dev-preferences.md).
- * - Hermes: remove pre-2841 flat skills/gsd-STAR entries.
- *
- * @param {string} runtime
- * @param {string} configDir  resolved runtime config directory
- * @param {'global'|'local'} [scope]
- */
-function _runLegacyUninstallCleanup(runtime, configDir, scope = 'global') {
-  // commands/gsd/ is a legacy location for Qwen, Hermes, and all Claude installs.
-  // Prior to #1367 fix, Claude-local used commands/gsd/<cmd>.md (colon-namespaced).
-  // After #1367, Claude-local uses flat commands/gsd-<cmd>.md. The inline uninstall
-  // block (1c) handles removal of flat files; this function handles the legacy
-  // commands/gsd/ directory for all Claude scopes (global was already included,
-  // local is now added since that layout is also legacy post-#1367).
-  // #2973 / Codex review (bd1f06c9): preserve user-owned dev-preferences.md
-  // before destructive wipe. Migration to skills/gsd-dev-preferences/SKILL.md
-  // is deferred and returned so the caller can apply it AFTER layout-driven
-  // removal — this prevents the layout's gsd-* prefix removal from wiping the
-  // freshly created skill dir (same pattern as _runLegacyInstallMigrations).
-  let savedLegacyArtifacts = null;
-  // commands/gsd/ is a legacy location for Qwen, Hermes, and Claude global.
-  // Claude local is intentionally excluded: the inline uninstall block (1c) handles
-  // commands/gsd/ for claude local, preserving dev-preferences.md by restoring it
-  // to the same location (#1423). Using migrateLegacyDevPreferencesToSkill here
-  // (which would redirect to skills/) conflicts with the test contract for local installs.
-  const isLegacyCommandsGsd = runtime === 'qwen' || runtime === 'hermes' || (runtime === 'claude' && scope === 'global');
-  if (isLegacyCommandsGsd) {
-    const legacyCommandsGsd = path.join(configDir, 'commands', 'gsd');
-    if (fs.existsSync(legacyCommandsGsd)) {
-      savedLegacyArtifacts = preserveUserArtifacts(legacyCommandsGsd, ['dev-preferences.md']);
-      fs.rmSync(legacyCommandsGsd, { recursive: true });
-    }
-  }
-
-  // Hermes: pre-#2841 flat skills/gsd-*/ entries
-  if (runtime === 'hermes') {
-    const flatSkillsDir = path.join(configDir, 'skills');
-    if (fs.existsSync(flatSkillsDir)) {
-      for (const entry of fs.readdirSync(flatSkillsDir, { withFileTypes: true })) {
-        if (entry.isDirectory() && entry.name.startsWith('gsd-')) {
-          fs.rmSync(path.join(flatSkillsDir, entry.name), { recursive: true });
-        }
-      }
-    }
-
-    // Hermes: pre-#947 bare-stem skills/gsd/<stem>/ entries (dirs that do NOT
-    // start with 'gsd-') — the #3664 layout used prefix='' so GSD-owned skills
-    // had bare names (e.g. skills/gsd/help/). These are stale on uninstall.
-    const nestedGsdDirForUninstall = path.join(configDir, 'skills', 'gsd');
-    if (fs.existsSync(nestedGsdDirForUninstall)) {
-      for (const entry of fs.readdirSync(nestedGsdDirForUninstall, { withFileTypes: true })) {
-        if (entry.isDirectory() && !entry.name.startsWith('gsd-')) {
-          fs.rmSync(path.join(nestedGsdDirForUninstall, entry.name), { recursive: true });
-        }
-      }
-    }
-  }
-
-  // Return saved artifacts so the caller can migrate after layout-driven removal.
-  return savedLegacyArtifacts;
-}
-
-/**
- * Layout-driven install orchestrator.
- * Runs legacy migrations first, then uses resolveRuntimeArtifactLayout to
- * determine what artifact kinds to write and where.
- *
- * @param {string} runtime             canonical runtime ID
- * @param {string} configDir           resolved runtime config directory
- * @param {'global'|'local'} scope
- * @param {Object} resolvedProfile     from resolveProfile() / resolveEffectiveProfile()
- */
-/**
- * Deep-snapshot a directory tree into a Map<relPath, Buffer>.
- * Returns an empty Map if the directory doesn't exist.
- * @param {string} dir
- * @returns {Map<string, Buffer>}
- */
-function _snapshotDir(dir) {
-  const files = new Map();
-  if (!fs.existsSync(dir)) return files;
-  const walk = (relPath, absPath) => {
-    for (const e of fs.readdirSync(absPath, { withFileTypes: true })) {
-      const childRel = relPath ? path.join(relPath, e.name) : e.name;
-      const childAbs = path.join(absPath, e.name);
-      if (e.isDirectory()) walk(childRel, childAbs);
-      else if (e.isFile()) files.set(childRel, fs.readFileSync(childAbs));
-    }
-  };
-  walk('', dir);
-  return files;
-}
-
-/**
- * Restore a directory tree from a Map<relPath, Buffer> produced by _snapshotDir.
- * @param {string} dir
- * @param {Map<string, Buffer>} snapshot
- */
-function _restoreDir(dir, snapshot) {
-  for (const [relPath, buf] of snapshot) {
-    const absPath = path.join(dir, relPath);
-    fs.mkdirSync(path.dirname(absPath), { recursive: true });
-    fs.writeFileSync(absPath, buf);
-  }
-}
-
-/**
- * After the layout-driven install loop writes new gsd-<stem>/ dirs to
- * skills/gsd/, remove any pre-existing bare-stem dirs (skills/gsd/<stem>/)
- * that correspond to the newly installed gsd-<stem> entries.
- *
- * The removal set is derived from the ACTUAL installed skill dirs (every
- * entry starting with 'gsd-' that is a directory), so it covers ALL shipped
- * GSD skills — including 'dev-preferences' and future additions — without
- * relying on readGsdCommandNames() which only enumerates the commands source
- * tree and can miss skills that ship outside that directory.
- *
- * Safety: a bare dir is ONLY removed when a corresponding gsd-<stem>/ dir was
- * installed this run. A user-owned dir 'skills/gsd/my-workflow/' that has no
- * matching 'skills/gsd/gsd-my-workflow/' is never touched.
- *
- * @param {string} nestedGsdDir  absolute path to skills/gsd/ category dir
- */
-function _removeHermesBareStemDirs(nestedGsdDir) {
-  if (!fs.existsSync(nestedGsdDir)) return;
-  const entries = fs.readdirSync(nestedGsdDir, { withFileTypes: true });
-
-  // Collect the set of stems that were installed as gsd-<stem>/ this run.
-  const installedStems = new Set();
-  for (const entry of entries) {
-    if (entry.isDirectory() && entry.name.startsWith('gsd-')) {
-      installedStems.add(entry.name.slice('gsd-'.length)); // e.g. 'quick', 'dev-preferences'
-    }
-  }
-
-  // Remove any bare <stem>/ dir for which gsd-<stem>/ was just installed.
-  for (const entry of entries) {
-    if (entry.isDirectory() && !entry.name.startsWith('gsd-') && installedStems.has(entry.name)) {
-      fs.rmSync(path.join(nestedGsdDir, entry.name), { recursive: true });
-    }
-  }
-}
-
-function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile) {
-  // Legacy cleanup before layout-driven writes
-  _runLegacyInstallMigrations(runtime, configDir, scope);
-
-  const layout = resolveRuntimeArtifactLayout(runtime, configDir, scope);
-  const planResult = createRuntimeArtifactInstallPlan({
-    layout,
-    resolvedProfile,
-    homedir: () => os.homedir(),
-    platform: process.platform,
-    resolveAttribution: getCommitAttribution,
-  });
-
-  const cleanupDirs = planResult.ok ? planResult.plan.cleanupDirs : planResult.cleanupDirs;
-  try {
-    if (!planResult.ok) {
-      throw new Error(planResult.message);
-    }
-
-    const kindsByName = new Map(layout.kinds.map((kind) => [kind.kind, kind]));
-    for (const item of planResult.plan.items) {
-      const kind = kindsByName.get(item.kind);
-      if (!kind) throw new Error(`Install plan returned unknown artifact kind: ${item.kind}`);
-      const dest = item.destDir;
-      fs.mkdirSync(dest, { recursive: true });
-      if (kind.kind === 'skills' && fs.existsSync(dest)) {
-        // Pre-prune: snapshot user-owned content before _removeGsdEntries wipes it,
-        // then restore after. This preserves user dirs across a wipe-and-replace
-        // install (#2973 / #3664).
-        //
-        // All runtimes (incl. Hermes after #947) use prefix='gsd-'.
-        // _removeGsdEntries removes only gsd-* entries; non-gsd-* user dirs are
-        // untouched. Preserve the explicit user-owned GSD-prefixed skill
-        // gsd-dev-preferences, which GSD does not reinstall from source but must
-        // survive the prune (#2973).
-        const toPreserve = new Map(); // dirName -> Map<relPath, Buffer>
-
-        {
-          // Preserve explicitly user-owned GSD-prefixed skill dirs.
-          // gsd-dev-preferences is the sole user-customisable skill in this category.
-          const USER_OWNED_SKILL_DIRS = ['gsd-dev-preferences'];
-          for (const dirName of USER_OWNED_SKILL_DIRS) {
-            const skillDir = path.join(dest, dirName);
-            if (!fs.existsSync(skillDir)) continue;
-            const snap = _snapshotDir(skillDir);
-            if (snap.size > 0) toPreserve.set(dirName, snap);
-          }
-        }
-
-        _removeGsdEntries(dest, kind);
-        _copyStaged(item.sourceDir, dest, kind);
-
-        // Restore user-owned dirs after the prune+copy
-        for (const [dirName, snap] of toPreserve) {
-          _restoreDir(path.join(dest, dirName), snap);
-        }
-      } else {
-        // For non-skills kinds (commands, agents): no user content to preserve;
-        // just prune stale gsd-* entries and copy new ones.
-        _removeGsdEntries(dest, kind);
-        _copyStaged(item.sourceDir, dest, kind);
-      }
-    }
-  } finally {
-    for (const dir of cleanupDirs) {
-      try { fs.rmSync(dir, { recursive: true, force: true }); } catch { /* best-effort */ }
-    }
-  }
-
-  // Hermes: after the install loop has written all gsd-<stem>/ dirs to
-  // skills/gsd/, remove any stale bare-stem dirs (skills/gsd/<stem>/) that
-  // correspond to the newly installed gsd-<stem> entries. This is the robust
-  // replacement for the readGsdCommandNames()-based pre-install cleanup that
-  // missed skills like 'dev-preferences' (#947 adversarial review).
-  //
-  // We run this AFTER the install loop so the installed set is authoritative:
-  // every gsd-<stem>/ present now was written this run (or was there before
-  // with the same prefix). User-owned bare dirs with no gsd-<stem> counterpart
-  // are untouched.
-  if (runtime === 'hermes') {
-    const nestedGsdDirForCleanup = path.join(configDir, 'skills', 'gsd');
-    _removeHermesBareStemDirs(nestedGsdDirForCleanup);
-  }
-}
-
-/**
- * Install the skills layout kind for an OpenCode-family runtime (OpenCode/Kilo).
- *
- * These runtimes do NOT go through installRuntimeArtifacts (their commands use a
- * bespoke flattened-command writer), so this writes ONLY the skills kind
- * alongside their existing command/ + agents/ surfaces. Uninstall is already
- * layout-driven (uninstallRuntimeArtifacts iterates layout.kinds), so the
- * skills/ dir is cleaned up automatically once the layout declares it.
- *
- * `rawCommandsDir` MUST be the SAME staged command directory the flattened
- * command writer consumes (the caller passes its `_stageSkills()` output) so the
- * command/ and skills/ surfaces always cover the identical, profile-resolved set
- * — including the `--minimal`/`--core-only` alias path, which stages differently
- * from a plain `--profile=core`.
- *
- * Mirrors copyFlattenedCommands exactly per file — pathPrefix rewrite →
- * attribution → command→skill conversion — guaranteeing command/ and skills/
- * bodies match byte-for-byte for global, --local, and --config-dir installs.
- * We deliberately do NOT use skillsKindEntry.stage(): that converts before any
- * pathPrefix is known, so its bodies would carry the converter's hardcoded
- * default config dir. (#784)
- *
- * @param {string} runtime - 'opencode' or 'kilo'
- * @param {string} targetDir - resolved runtime config directory
- * @param {string} rawCommandsDir - staged RAW Claude command dir (caller's _stageSkills output)
- * @param {string} pathPrefix - computed config-path prefix for body rewrites
- * @returns {number} number of gsd-* skill directories written
- */
-function installOpencodeFamilySkills(runtime, targetDir, rawCommandsDir, pathPrefix) {
-  const layout = resolveRuntimeArtifactLayout(runtime, targetDir);
-  const skillsKindEntry = layout.kinds.find((k) => k.kind === 'skills');
-  if (!skillsKindEntry) return 0;
-  const rawDir = rawCommandsDir;
-  if (!rawDir || !fs.existsSync(rawDir)) return 0;
-
-  const converter = runtime === 'kilo'
-    ? convertClaudeCommandToKiloSkill
-    : convertClaudeCommandToOpencodeSkill;
-
-  const dest = path.join(targetDir, skillsKindEntry.destSubpath);
-  fs.mkdirSync(dest, { recursive: true });
-
-  // Preserve user-owned GSD-prefixed skill dirs across the gsd-* prune.
-  // gsd-dev-preferences is generated by the user (via generate-dev-preferences)
-  // and lives at <configDir>/skills/gsd-dev-preferences — _removeGsdEntries
-  // would otherwise wipe it. Mirrors the preservation in installRuntimeArtifacts
-  // (#2973).
-  const USER_OWNED_SKILL_DIRS = ['gsd-dev-preferences'];
-  const toPreserve = new Map(); // dirName -> Map<relPath, Buffer>
-  for (const dirName of USER_OWNED_SKILL_DIRS) {
-    const skillDir = path.join(dest, dirName);
-    if (!fs.existsSync(skillDir)) continue;
-    const snap = _snapshotDir(skillDir);
-    if (snap.size > 0) toPreserve.set(dirName, snap);
-  }
-
-  _removeGsdEntries(dest, skillsKindEntry);
-
-  let count = 0;
-  for (const entry of fs.readdirSync(rawDir, { withFileTypes: true })) {
-    if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
-    const stem = entry.name.slice(0, -3);
-    const skillName = `${skillsKindEntry.prefix}${stem}`;
-    let content = fs.readFileSync(path.join(rawDir, entry.name), 'utf8');
-    content = applyOpencodeFamilyPathPrefix(content, runtime, pathPrefix);
-    content = processAttribution(content, getCommitAttribution(runtime));
-    content = converter(content, skillName);
-    const skillDir = path.join(dest, skillName);
-    fs.mkdirSync(skillDir, { recursive: true });
-    fs.writeFileSync(path.join(skillDir, 'SKILL.md'), content);
-    count++;
-  }
-
-  // Restore user-owned dirs after the prune+copy.
-  for (const [dirName, snap] of toPreserve) {
-    _restoreDir(path.join(dest, dirName), snap);
-  }
-
-  return count;
-}
-
-/**
- * Layout-driven uninstall orchestrator.
- * Runs legacy cleanup first, then uses resolveRuntimeArtifactLayout to
- * determine which GSD-owned entries to remove.
- *
- * @param {string} runtime             canonical runtime ID
- * @param {string} configDir           resolved runtime config directory
- * @param {'global'|'local'} scope
- */
-function uninstallRuntimeArtifacts(runtime, configDir, scope) {
-  // Legacy cleanup before layout-driven removal (scope-aware to avoid
-  // removing Claude local commands/gsd/ which is the primary install dir).
-  // Returns saved user artifacts so we can migrate AFTER layout removal
-  // (the layout's gsd-* prefix pass would wipe a skill dir created here).
-  const savedLegacyArtifacts = _runLegacyUninstallCleanup(runtime, configDir, scope);
-
-  const layout = resolveRuntimeArtifactLayout(runtime, configDir, scope);
-  const plan = createRuntimeArtifactUninstallPlan(layout);
-  const kindsByName = new Map(layout.kinds.map((kind) => [kind.kind, kind]));
-  for (const item of plan.items) {
-    const kind = kindsByName.get(item.kind);
-    if (!kind) {
-      throw new Error(`Runtime artifact uninstall plan referenced unknown kind: ${item.kind}`);
-    }
-    _removeGsdEntries(item.destDir, kind);
-  }
-
-  // Hermes: after removing gsd-* skill dirs from skills/gsd/, also remove
-  // the GSD-managed DESCRIPTION.md and then the category dir itself if it
-  // contains no user content (#947). _removeGsdEntries removed gsd-* dirs
-  // but left the category container and DESCRIPTION.md intact.
-  if (runtime === 'hermes') {
-    const nestedGsdDir = path.join(configDir, 'skills', 'gsd');
-    if (fs.existsSync(nestedGsdDir)) {
-      // Remove GSD-owned DESCRIPTION.md (written by writeHermesCategoryDescription)
-      fs.rmSync(path.join(nestedGsdDir, 'DESCRIPTION.md'), { force: true });
-      // Remove the category dir if empty (no user content remaining)
-      const remaining = fs.readdirSync(nestedGsdDir, { withFileTypes: true });
-      if (remaining.length === 0) {
-        fs.rmSync(nestedGsdDir, { recursive: true, force: true });
-      }
-    }
-  }
-
-  // #2973 / Codex review (bd1f06c9): migrate dev-preferences.md to the
-  // runtime-aware SKILL.md location after all layout-driven removal is
-  // complete. Do NOT restore to commands/gsd/ — the user is uninstalling.
-  if (savedLegacyArtifacts) {
-    migrateLegacyDevPreferencesToSkill(configDir, savedLegacyArtifacts, runtime, scope);
-  }
-}
+ * Data-driven dispatch table for copyWithPathReplacement (ADR-1239 Phase B).
+ * Keyed by runtime id. Each entry declares ONLY what that runtime does differently.
+ * The DEFAULT (no entry, or entry with no md/js key) = identity transform after
+ * the uniform steps — covers claude, augment, codebuddy, kimi, etc.
+ *
+ * Entry shape:
+ *   mdSkipGenericRewrite?: boolean  — skip the ~/.claude/ rewrite block (copilot, antigravity)
+ *   md?: (content, ctx) => string   — per-runtime .md transform
+ *   mdReattributeAfter?: boolean    — re-run processAttribution after md() (copilot, antigravity)
+ *   mdTomlRenameOnCommand?: boolean — when isCommand, rename dest .md → .toml (gemini)
+ *   js?: (content, ctx) => string   — per-runtime .cjs/.js transform (absent = plain copyFileSync)
+ *
+ * ctx = { isCommand, isGlobal, dirName, pathPrefix, entryName, runtime }
+ */
+const RUNTIME_CONTENT_DISPATCH = {
+  opencode: {
+    md: (content) => convertClaudeToOpencodeFrontmatter(content),
+  },
+  kilo: {
+    md: (content) => convertClaudeToKiloFrontmatter(content),
+  },
+  gemini: {
+    md: (content, ctx) =>
+      convertClaudeToGeminiMarkdown(content, {
+        isCommand: ctx.isCommand,
+        commandName: ctx.isCommand ? ctx.entryName.replace(/\.md$/, '') : null,
+      }),
+    mdTomlRenameOnCommand: true,
+  },
+  codex: {
+    md: (content) => convertClaudeToCodexMarkdown(content),
+  },
+  copilot: {
+    mdSkipGenericRewrite: true,
+    md: (content, ctx) => convertClaudeToCopilotContent(content, ctx.isGlobal),
+    mdReattributeAfter: true,
+    js: (content, ctx) => convertClaudeToCopilotContent(content, ctx.isGlobal),
+  },
+  antigravity: {
+    mdSkipGenericRewrite: true,
+    md: (content, ctx) => convertClaudeToAntigravityContent(content, ctx.isGlobal),
+    mdReattributeAfter: true,
+    js: (content, ctx) => convertClaudeToAntigravityContent(content, ctx.isGlobal),
+  },
+  cursor: {
+    md: (content) => convertClaudeToCursorMarkdown(content),
+    js: (content) => {
+      content = content.replace(/gsd:/gi, 'gsd-');
+      content = content.replace(/\.claude\/skills\//g, '.cursor/skills/');
+      content = content.replace(/CLAUDE\.md/g, '.cursor/rules/');
+      content = content.replace(/\bClaude Code\b/g, 'Cursor');
+      return content;
+    },
+  },
+  windsurf: {
+    md: (content) => convertClaudeToWindsurfMarkdown(content),
+    js: (content) => {
+      // Workspace skills install to .devin/ (Devin Desktop preferred dir, #1085).
+      content = content.replace(/gsd:/gi, 'gsd-');
+      content = content.replace(/\.claude\/skills\//g, '.devin/skills/');
+      content = content.replace(/CLAUDE\.md/g, '.devin/rules');
+      content = content.replace(/\bClaude Code\b/g, 'Windsurf');
+      return content;
+    },
+  },
+  trae: {
+    md: (content) => convertClaudeToTraeMarkdown(content),
+    js: (content) => {
+      content = content.replace(/\/gsd:([a-z0-9-]+)/g, (_, commandName) => {
+        return `/gsd-${commandName}`;
+      });
+      content = content.replace(/\.claude\/skills\//g, '.trae/skills/');
+      content = content.replace(/CLAUDE\.md/g, '.trae/rules/');
+      content = content.replace(/\bClaude Code\b/g, 'Trae');
+      return content;
+    },
+  },
+  cline: {
+    md: (content) => convertClaudeToCliineMarkdown(content),
+    js: (content) => {
+      content = content.replace(/\.claude\/skills\//g, '.cline/skills/');
+      content = content.replace(/CLAUDE\.md/g, '.clinerules');
+      content = content.replace(/\bClaude Code\b/g, 'Cline');
+      return content;
+    },
+  },
+  qwen: {
+    md: (content) => {
+      content = content.replace(/CLAUDE\.md/g, 'QWEN.md');
+      content = content.replace(/\bClaude Code\b/g, 'Qwen Code');
+      content = content.replace(/\.claude\//g, '.qwen/');
+      return content;
+    },
+    js: (content) => {
+      content = content.replace(/\.claude\/skills\//g, '.qwen/skills/');
+      content = content.replace(/\.claude\//g, '.qwen/');
+      content = content.replace(/CLAUDE\.md/g, 'QWEN.md');
+      content = content.replace(/\bClaude Code\b/g, 'Qwen Code');
+      return content;
+    },
+  },
+  hermes: {
+    md: (content) => {
+      content = content.replace(/CLAUDE\.md/g, 'HERMES.md');
+      content = content.replace(/\bClaude Code\b/g, 'Hermes Agent');
+      content = content.replace(/\.claude\//g, '.hermes/');
+      return content;
+    },
+    js: (content) => {
+      content = content.replace(/\.claude\/skills\//g, '.hermes/skills/');
+      content = content.replace(/\.claude\//g, '.hermes/');
+      content = content.replace(/CLAUDE\.md/g, 'HERMES.md');
+      content = content.replace(/\bClaude Code\b/g, 'Hermes Agent');
+      return content;
+    },
+  },
+};
 
 /**
  * Recursively copy directory, replacing paths in .md files
@@ -7326,22 +6649,28 @@ function uninstallRuntimeArtifacts(runtime, configDir, scope) {
  * @param {boolean} isCommand - Whether the source is a command directory
  * @param {boolean} isGlobal - Whether the install is global
  */
-function copyWithPathReplacement(srcDir, destDir, pathPrefix, runtime, isCommand = false, isGlobal = false) {
-  const isOpencode = runtime === 'opencode';
-  const isKilo = runtime === 'kilo';
-  const isGemini = runtime === 'gemini';
-  const isCodex = runtime === 'codex';
-  const isCopilot = runtime === 'copilot';
-  const isAntigravity = runtime === 'antigravity';
-  const isCursor = runtime === 'cursor';
-  const isWindsurf = runtime === 'windsurf';
-  const isAugment = runtime === 'augment';
-  const isTrae = runtime === 'trae';
-  const isQwen = runtime === 'qwen';
-  const isHermes = runtime === 'hermes';
-  const isCline = runtime === 'cline';
+function copyWithPathReplacement(srcDir, destDir, pathPrefix, runtime, isCommand = false, isGlobal = false, confinementRoot) {
   const dirName = getDirName(runtime);
 
+  // ADR-1239 Phase B write-confinement: refuse to wipe/write a destDir that
+  // escapes the caller-declared install root. Runs BEFORE the rmSync below so a
+  // crafted destDir can never delete or write outside confinementRoot.
+  if (confinementRoot === undefined) {
+    throw new Error(
+      'copyWithPathReplacement: confinementRoot is required to confine writes to the install root — refusing to write',
+    );
+  }
+  const resolvedConfinementRoot = path.resolve(confinementRoot);
+  const resolvedDestDir = assertDestWithinConfigHome(confinementRoot, destDir);
+  if (hasExistingSymlinkBetween(resolvedConfinementRoot, resolvedDestDir)) {
+    throw new Error(
+      `copyWithPathReplacement: destDir "${destDir}" contains a symlink escaping the install root "${confinementRoot}" — refusing to write`,
+    );
+  }
+  // Use the validated absolute path for all writes below so the gate validates
+  // exactly what is written (a relative destDir would otherwise resolve to cwd).
+  destDir = resolvedDestDir;
+
   // Clean install: remove existing destination to prevent orphaned files
   if (fs.existsSync(destDir)) {
     fs.rmSync(destDir, { recursive: true });
@@ -7355,12 +6684,15 @@ function copyWithPathReplacement(srcDir, destDir, pathPrefix, runtime, isCommand
     const destPath = path.join(destDir, entry.name);
 
     if (entry.isDirectory()) {
-      copyWithPathReplacement(srcPath, destPath, pathPrefix, runtime, isCommand, isGlobal);
+      copyWithPathReplacement(srcPath, destPath, pathPrefix, runtime, isCommand, isGlobal, confinementRoot);
     } else if (entry.name.endsWith('.md')) {
+      const dispatch = RUNTIME_CONTENT_DISPATCH[runtime] || {};
+      const ctx = { isCommand, isGlobal, dirName, pathPrefix, entryName: entry.name, runtime };
+
       // Replace ~/.claude/ and $HOME/.claude/ and ./.claude/ with runtime-appropriate paths
-      // Skip generic replacement for Copilot — convertClaudeToCopilotContent handles all paths
+      // Skip generic replacement for Copilot/Antigravity — their converters handle all paths
       let content = fs.readFileSync(srcPath, 'utf8');
-      if (!isCopilot && !isAntigravity) {
+      if (!dispatch.mdSkipGenericRewrite) {
         const globalClaudeRegex = /~\/\.claude\//g;
         const globalClaudeHomeRegex = /\$HOME\/\.claude\//g;
         const localClaudeRegex = /\.\/\.claude\//g;
@@ -7395,112 +6727,25 @@ function copyWithPathReplacement(srcDir, destDir, pathPrefix, runtime, isCommand
       // colon-canonical runtimes (Gemini).
       content = normalizeAgentBodyForRuntime(content, runtime, readGsdCommandNames());
 
-      // Convert frontmatter for opencode compatibility
-      if (isOpencode || isKilo) {
-        content = isKilo
-          ? convertClaudeToKiloFrontmatter(content)
-          : convertClaudeToOpencodeFrontmatter(content);
-        fs.writeFileSync(destPath, content);
-      } else if (isGemini) {
-        // Apply Gemini-specific Markdown transformations (slash commands, TOML).
-        // #778: thread the command name (file stem) so per-command TOML
-        // enrichment (live-state injection) can target a specific command.
-        const geminiCommandName = isCommand ? entry.name.replace(/\.md$/, '') : null;
-        const processed = convertClaudeToGeminiMarkdown(content, { isCommand, commandName: geminiCommandName });
-        const finalPath = isCommand ? destPath.replace(/\.md$/, '.toml') : destPath;
-        fs.writeFileSync(finalPath, processed);
-      } else if (isCodex) {
-        content = convertClaudeToCodexMarkdown(content);
-        fs.writeFileSync(destPath, content);
-      } else if (isCopilot) {
-        content = convertClaudeToCopilotContent(content, isGlobal);
-        content = processAttribution(content, getCommitAttribution(runtime));
-        fs.writeFileSync(destPath, content);
-      } else if (isAntigravity) {
-        content = convertClaudeToAntigravityContent(content, isGlobal);
-        content = processAttribution(content, getCommitAttribution(runtime));
-        fs.writeFileSync(destPath, content);
-      } else if (isCursor) {
-        content = convertClaudeToCursorMarkdown(content);
-        fs.writeFileSync(destPath, content);
-      } else if (isWindsurf) {
-        content = convertClaudeToWindsurfMarkdown(content);
-        fs.writeFileSync(destPath, content);
-      } else if (isTrae) {
-        content = convertClaudeToTraeMarkdown(content);
-        fs.writeFileSync(destPath, content);
-      } else if (isCline) {
-        content = convertClaudeToCliineMarkdown(content);
-        fs.writeFileSync(destPath, content);
-      } else if (isQwen) {
-        content = content.replace(/CLAUDE\.md/g, 'QWEN.md');
-        content = content.replace(/\bClaude Code\b/g, 'Qwen Code');
-        content = content.replace(/\.claude\//g, '.qwen/');
-        fs.writeFileSync(destPath, content);
-      } else if (isHermes) {
-        content = content.replace(/CLAUDE\.md/g, 'HERMES.md');
-        content = content.replace(/\bClaude Code\b/g, 'Hermes Agent');
-        content = content.replace(/\.claude\//g, '.hermes/');
+      // Apply per-runtime .md converter (if any)
+      if (dispatch.md) content = dispatch.md(content, ctx);
+
+      // Re-run attribution after converter for runtimes that need it (copilot, antigravity)
+      if (dispatch.mdReattributeAfter) content = processAttribution(content, getCommitAttribution(runtime));
+
+      // Gemini: rename .md → .toml for command files
+      const finalPath = (dispatch.mdTomlRenameOnCommand && isCommand) ? destPath.replace(/\.md$/, '.toml') : destPath;
+      fs.writeFileSync(finalPath, content);
+    } else if (entry.name.endsWith('.cjs') || entry.name.endsWith('.js')) {
+      const dispatch = RUNTIME_CONTENT_DISPATCH[runtime] || {};
+      if (dispatch.js) {
+        const ctx = { isCommand, isGlobal, dirName, pathPrefix, entryName: entry.name, runtime };
+        let content = fs.readFileSync(srcPath, 'utf8');
+        content = dispatch.js(content, ctx);
         fs.writeFileSync(destPath, content);
       } else {
-        fs.writeFileSync(destPath, content);
+        fs.copyFileSync(srcPath, destPath);
       }
-    } else if (isCopilot && (entry.name.endsWith('.cjs') || entry.name.endsWith('.js'))) {
-      // Copilot: also transform .cjs/.js files for CONV-06 and CONV-07
-      let content = fs.readFileSync(srcPath, 'utf8');
-      content = convertClaudeToCopilotContent(content, isGlobal);
-      fs.writeFileSync(destPath, content);
-    } else if (isAntigravity && (entry.name.endsWith('.cjs') || entry.name.endsWith('.js'))) {
-      // Antigravity: also transform .cjs/.js files for path/command conversions
-      let content = fs.readFileSync(srcPath, 'utf8');
-      content = convertClaudeToAntigravityContent(content, isGlobal);
-      fs.writeFileSync(destPath, content);
-    } else if (isCursor && (entry.name.endsWith('.cjs') || entry.name.endsWith('.js'))) {
-      // For Cursor, also convert Claude references in JS/CJS utility scripts
-      let jsContent = fs.readFileSync(srcPath, 'utf8');
-      jsContent = jsContent.replace(/gsd:/gi, 'gsd-');
-      jsContent = jsContent.replace(/\.claude\/skills\//g, '.cursor/skills/');
-      jsContent = jsContent.replace(/CLAUDE\.md/g, '.cursor/rules/');
-      jsContent = jsContent.replace(/\bClaude Code\b/g, 'Cursor');
-      fs.writeFileSync(destPath, jsContent);
-    } else if (isWindsurf && (entry.name.endsWith('.cjs') || entry.name.endsWith('.js'))) {
-      // For Windsurf/Devin, also convert Claude references in JS/CJS utility scripts.
-      // Workspace skills install to .devin/ (Devin Desktop preferred dir, #1085).
-      let jsContent = fs.readFileSync(srcPath, 'utf8');
-      jsContent = jsContent.replace(/gsd:/gi, 'gsd-');
-      jsContent = jsContent.replace(/\.claude\/skills\//g, '.devin/skills/');
-      jsContent = jsContent.replace(/CLAUDE\.md/g, '.devin/rules');
-      jsContent = jsContent.replace(/\bClaude Code\b/g, 'Windsurf');
-      fs.writeFileSync(destPath, jsContent);
-    } else if (isTrae && (entry.name.endsWith('.cjs') || entry.name.endsWith('.js'))) {
-      let jsContent = fs.readFileSync(srcPath, 'utf8');
-      jsContent = jsContent.replace(/\/gsd:([a-z0-9-]+)/g, (_, commandName) => {
-        return `/gsd-${commandName}`;
-      });
-      jsContent = jsContent.replace(/\.claude\/skills\//g, '.trae/skills/');
-      jsContent = jsContent.replace(/CLAUDE\.md/g, '.trae/rules/');
-      jsContent = jsContent.replace(/\bClaude Code\b/g, 'Trae');
-      fs.writeFileSync(destPath, jsContent);
-    } else if (isCline && (entry.name.endsWith('.cjs') || entry.name.endsWith('.js'))) {
-      let jsContent = fs.readFileSync(srcPath, 'utf8');
-      jsContent = jsContent.replace(/\.claude\/skills\//g, '.cline/skills/');
-      jsContent = jsContent.replace(/CLAUDE\.md/g, '.clinerules');
-      jsContent = jsContent.replace(/\bClaude Code\b/g, 'Cline');
-      fs.writeFileSync(destPath, jsContent);
-    } else if (isQwen && (entry.name.endsWith('.cjs') || entry.name.endsWith('.js'))) {
-      let jsContent = fs.readFileSync(srcPath, 'utf8');
-      jsContent = jsContent.replace(/\.claude\/skills\//g, '.qwen/skills/');
-      jsContent = jsContent.replace(/\.claude\//g, '.qwen/');
-      jsContent = jsContent.replace(/CLAUDE\.md/g, 'QWEN.md');
-      jsContent = jsContent.replace(/\bClaude Code\b/g, 'Qwen Code');
-      fs.writeFileSync(destPath, jsContent);
-    } else if (isHermes && (entry.name.endsWith('.cjs') || entry.name.endsWith('.js'))) {
-      let jsContent = fs.readFileSync(srcPath, 'utf8');
-      jsContent = jsContent.replace(/\.claude\/skills\//g, '.hermes/skills/');
-      jsContent = jsContent.replace(/\.claude\//g, '.hermes/');
-      jsContent = jsContent.replace(/CLAUDE\.md/g, 'HERMES.md');
-      jsContent = jsContent.replace(/\bClaude Code\b/g, 'Hermes Agent');
-      fs.writeFileSync(destPath, jsContent);
     } else {
       fs.copyFileSync(srcPath, destPath);
     }
@@ -7674,19 +6919,7 @@ const GSD_UNINSTALL_HOOKS = [
  * @param {string} runtime - Target runtime ('claude', 'opencode', 'gemini', 'codex', 'copilot')
  */
 function uninstall(isGlobal, runtime = 'claude') {
-  const isOpencode = runtime === 'opencode';
-  const isKilo = runtime === 'kilo';
-  const isGemini = runtime === 'gemini';
-  const isCodex = runtime === 'codex';
-  const isCopilot = runtime === 'copilot';
-  const isAntigravity = runtime === 'antigravity';
-  const isCursor = runtime === 'cursor';
-  const isWindsurf = runtime === 'windsurf';
-  const isAugment = runtime === 'augment';
-  const isTrae = runtime === 'trae';
-  const isQwen = runtime === 'qwen';
-  const isHermes = runtime === 'hermes';
-  const isCodebuddy = runtime === 'codebuddy';
+  const { isOpencode, isKilo, isGemini, isCodex, isCopilot, isAntigravity, isCursor, isWindsurf, isAugment, isTrae, isQwen, isHermes, isCodebuddy, isCline, isKimi } = runtimeFlags(runtime);
   const dirName = getDirName(runtime);
 
   // Get the target directory based on runtime and install type. Cline local
@@ -7702,21 +6935,9 @@ function uninstall(isGlobal, runtime = 'claude') {
     ? targetDir.replace(os.homedir(), '~')
     : targetDir.replace(process.cwd(), '.');
 
-  let runtimeLabel = 'Claude Code';
-  if (runtime === 'opencode') runtimeLabel = 'OpenCode';
-  if (runtime === 'gemini') runtimeLabel = 'Gemini';
-  if (runtime === 'kilo') runtimeLabel = 'Kilo';
-  if (runtime === 'codex') runtimeLabel = 'Codex';
-  if (runtime === 'copilot') runtimeLabel = 'Copilot';
-  if (runtime === 'antigravity') runtimeLabel = 'Antigravity';
-  if (runtime === 'cursor') runtimeLabel = 'Cursor';
-  if (runtime === 'windsurf') runtimeLabel = 'Windsurf';
-  if (runtime === 'augment') runtimeLabel = 'Augment';
-  if (runtime === 'trae') runtimeLabel = 'Trae';
-  if (runtime === 'qwen') runtimeLabel = 'Qwen Code';
-  if (runtime === 'hermes') runtimeLabel = 'Hermes Agent';
-  if (runtime === 'kimi') runtimeLabel = 'Kimi CLI';
-  if (runtime === 'codebuddy') runtimeLabel = 'CodeBuddy';
+  // runtimeLabel is now the single-source getRuntimeLabel lookup (ADR-1239
+  // Phase B / #1679) — collapses the prior 15-line assignment chain.
+  const runtimeLabel = getRuntimeLabel(runtime);
 
   console.log(`  Uninstalling GSD from ${cyan}${runtimeLabel}${reset} at ${cyan}${locationLabel}${reset}\n`);
 
@@ -8096,6 +7317,22 @@ function uninstall(isGlobal, runtime = 'claude') {
     }
   }
 
+  // 4z. Remove the OpenCode native plugin adapter (#1914). Only GSD's own
+  // plugin file is removed; the plugins/ dir is pruned only if it becomes
+  // empty, preserving any user-authored OpenCode plugins.
+  if (isOpencode) {
+    const pluginsDir = path.join(targetDir, 'plugins');
+    const pluginPath = path.join(pluginsDir, 'gsd-core.js');
+    if (fs.existsSync(pluginPath)) {
+      try {
+        fs.unlinkSync(pluginPath);
+        removedCount++;
+        console.log(`  ${green}✓${reset} Removed OpenCode plugin`);
+      } catch (_) { /* best-effort */ }
+      try { fs.rmdirSync(pluginsDir); } catch (_) { /* not empty — user plugins present */ }
+    }
+  }
+
   // 4a. Remove scripts/changeset/ and scripts/lib/ (#935)
   // GSD-managed files only: enumerate the exact set the installer writes.
   // Any file NOT in this set is user-owned and must survive uninstall.
@@ -8140,6 +7377,11 @@ function uninstall(isGlobal, runtime = 'claude') {
   const fixSlashUninstallPath = path.join(targetDir, 'scripts', 'fix-slash-commands.cjs');
   try { fs.unlinkSync(fixSlashUninstallPath); } catch (_) { /* best-effort */ }
 
+  // Remove the capability registry generator scripts (#1920) — before the scripts/ rmdir
+  for (const gen of ['gen-capability-registry.cjs', 'gen-loop-host-contract.cjs']) {
+    try { fs.unlinkSync(path.join(targetDir, 'scripts', gen)); } catch (_) { /* best-effort */ }
+  }
+
   // If scripts/ dir is now empty, remove it too
   const scriptsUninstallDir = path.join(targetDir, 'scripts');
   if (fs.existsSync(scriptsUninstallDir)) {
@@ -8482,7 +7724,7 @@ function configureOpencodePermissions(isGlobal = true, configDir = null) {
     modified = true;
   }
 
-  // Configure external_directory permission (the safety guard for paths outside project)
+  // Configure external_directory permission (the safety guard for paths outside)
   if (!config.permission.external_directory || typeof config.permission.external_directory !== 'object') {
     config.permission.external_directory = {};
   }
@@ -8491,6 +7733,25 @@ function configureOpencodePermissions(isGlobal = true, configDir = null) {
     modified = true;
   }
 
+  // ADR-1239 Phase D / #1682 — register the companion MCP server (Phase 4) so
+  // OpenCode connects to GSD's command (point 1) + state-IO (point 5) surface
+  // with NO bespoke plugin. Idempotent + non-clobbering: only added when
+  // `mcp.gsd` is absent (a user-defined `mcp.gsd` is respected — Hyrum's Law).
+  // Local-stdio schema per OpenCode config (packages/core/src/config/mcp.ts).
+  // `-p @opengsd/gsd-core` resolves the `gsd-mcp-server` bin from this package
+  // (bin name != package name) regardless of global-install state.
+  if (!config.mcp || typeof config.mcp !== 'object') {
+    config.mcp = {};
+  }
+  if (config.mcp.gsd === undefined) {
+    config.mcp.gsd = {
+      type: 'local',
+      command: ['npx', '-y', '-p', PACKAGE_NAME, 'gsd-mcp-server'],
+      enabled: true,
+    };
+    modified = true;
+  }
+
   if (!modified) {
     return; // Already configured
   }
@@ -8676,45 +7937,14 @@ function resolveInstallRelativePath(baseDir, relPath) {
   return { relPath: normalized, fullPath };
 }
 
-function hasExistingSymlinkBetween(root, fullPath) {
-  const resolvedRoot = path.resolve(root);
-  const resolvedFullPath = path.resolve(fullPath);
-  if (resolvedFullPath !== resolvedRoot && !resolvedFullPath.startsWith(resolvedRoot + path.sep)) {
-    return true;
-  }
-
-  let cursor = resolvedRoot;
-  if (fs.existsSync(cursor) && fs.lstatSync(cursor).isSymbolicLink()) {
-    return true;
-  }
-
-  const relative = path.relative(resolvedRoot, resolvedFullPath);
-  for (const segment of relative.split(path.sep)) {
-    if (!segment) continue;
-    cursor = path.join(cursor, segment);
-    if (!fs.existsSync(cursor)) return false;
-    if (fs.lstatSync(cursor).isSymbolicLink()) return true;
-  }
-
-  return false;
-}
+// hasExistingSymlinkBetween: moved to src/install-engine.cts (ADR-1239 Phase B).
+// Imported from installEngine above.
 
 /**
  * Write file manifest after installation for future modification detection
  */
 function writeManifest(configDir, runtime = 'claude', options = {}) {
-  const isOpencode = runtime === 'opencode';
-  const isKilo = runtime === 'kilo';
-  const isGemini = runtime === 'gemini';
-  const isCodex = runtime === 'codex';
-  const isCopilot = runtime === 'copilot';
-  const isAntigravity = runtime === 'antigravity';
-  const isCursor = runtime === 'cursor';
-  const isWindsurf = runtime === 'windsurf';
-  const isTrae = runtime === 'trae';
-  const isCline = runtime === 'cline';
-  const isKimi = runtime === 'kimi';
-  const isHermes = runtime === 'hermes';
+  const { isOpencode, isKilo, isGemini, isCodex, isCopilot, isAntigravity, isCursor, isWindsurf, isAugment, isTrae, isQwen, isHermes, isCodebuddy, isCline, isKimi } = runtimeFlags(runtime);
   const gsdDir = path.join(configDir, 'gsd-core');
   // #1367: Claude local now writes flat gsd-*.md files at commands/ (not commands/gsd/).
   // commandsDir points to the old location for Gemini (which still uses commands/gsd/).
@@ -8875,6 +8105,24 @@ function writeManifest(configDir, runtime = 'claude', options = {}) {
     manifest.files['scripts/fix-slash-commands.cjs'] = fileHash(fixSlashInstallPath);
   }
 
+  // Track the capability registry generator scripts (#1920) — top-level scripts/ files
+  // not covered by the changeset/lib loops.
+  for (const gen of ['gen-capability-registry.cjs', 'gen-loop-host-contract.cjs']) {
+    const genInstallPath = path.join(configDir, 'scripts', gen);
+    if (fs.existsSync(genInstallPath)) {
+      manifest.files['scripts/' + gen] = fileHash(genInstallPath);
+    }
+  }
+
+  // Track the OpenCode native plugin adapter (#1914) so update/drift detection
+  // and uninstall can account for it.
+  if (isOpencode) {
+    const pluginInstallPath = path.join(configDir, 'plugins', 'gsd-core.js');
+    if (fs.existsSync(pluginInstallPath)) {
+      manifest.files['plugins/gsd-core.js'] = fileHash(pluginInstallPath);
+    }
+  }
+
   fs.writeFileSync(path.join(configDir, MANIFEST_NAME), JSON.stringify(manifest, null, 2));
   return manifest;
 }
@@ -8943,7 +8191,7 @@ function populatePristineDir({ packageSrc, pristineDir, modified, runtime, pathP
       const srcDir = path.join(packageSrc, top);
       const stageDir = path.join(stageRoot, top);
       if (!fs.existsSync(srcDir)) continue;
-      copyWithPathReplacement(srcDir, stageDir, pathPrefix, runtime, false, isGlobal);
+      copyWithPathReplacement(srcDir, stageDir, pathPrefix, runtime, false, isGlobal, stageRoot);
     }
 
     for (const relPath of safeModified) {
@@ -9201,21 +8449,7 @@ function reportInstallerMigrationResult(result) {
 }
 
 function install(isGlobal, runtime = 'claude', options = {}) {
-  const isOpencode = runtime === 'opencode';
-  const isGemini = runtime === 'gemini';
-  const isKilo = runtime === 'kilo';
-  const isKimi = runtime === 'kimi';
-  const isCodex = runtime === 'codex';
-  const isCopilot = runtime === 'copilot';
-  const isAntigravity = runtime === 'antigravity';
-  const isCursor = runtime === 'cursor';
-  const isWindsurf = runtime === 'windsurf';
-  const isAugment = runtime === 'augment';
-  const isTrae = runtime === 'trae';
-  const isQwen = runtime === 'qwen';
-  const isHermes = runtime === 'hermes';
-  const isCodebuddy = runtime === 'codebuddy';
-  const isCline = runtime === 'cline';
+  const { isOpencode, isKilo, isGemini, isCodex, isCopilot, isAntigravity, isCursor, isWindsurf, isAugment, isTrae, isQwen, isHermes, isCodebuddy, isCline, isKimi } = runtimeFlags(runtime);
   const plan = resolveInstallPlan(runtime);
   const dirName = getDirName(runtime);
   const src = path.join(__dirname, '..');
@@ -9361,22 +8595,9 @@ function install(isGlobal, runtime = 'claude', options = {}) {
     homeDir,
   });
 
-  let runtimeLabel = 'Claude Code';
-  if (isOpencode) runtimeLabel = 'OpenCode';
-  if (isGemini) runtimeLabel = 'Gemini';
-  if (isKilo) runtimeLabel = 'Kilo';
-  if (isCodex) runtimeLabel = 'Codex';
-  if (isCopilot) runtimeLabel = 'Copilot';
-  if (isAntigravity) runtimeLabel = 'Antigravity';
-  if (isCursor) runtimeLabel = 'Cursor';
-  if (isWindsurf) runtimeLabel = 'Windsurf';
-  if (isAugment) runtimeLabel = 'Augment';
-  if (isTrae) runtimeLabel = 'Trae';
-  if (isQwen) runtimeLabel = 'Qwen Code';
-  if (isHermes) runtimeLabel = 'Hermes Agent';
-  if (isKimi) runtimeLabel = 'Kimi';
-  if (isCodebuddy) runtimeLabel = 'CodeBuddy';
-  if (isCline) runtimeLabel = 'Cline';
+  // runtimeLabel is now the single-source getRuntimeLabel lookup (ADR-1239
+  // Phase B / #1679) — collapses the prior 16-line assignment chain.
+  const runtimeLabel = getRuntimeLabel(runtime);
 
   console.log(`  Installing for ${cyan}${runtimeLabel}${reset} to ${cyan}${locationLabel}${reset}\n`);
 
@@ -9671,7 +8892,7 @@ function install(isGlobal, runtime = 'claude', options = {}) {
   if (_isSkillsRuntime) {
     // Layout-driven install for skills-based runtimes (full and minimal modes)
     const scope = isGlobal ? 'global' : 'local';
-    installRuntimeArtifacts(runtime, targetDir, scope, _resolvedProfile);
+    installRuntimeArtifacts(runtime, targetDir, scope, _resolvedProfile, getCommitAttribution);
 
     // #1326 — Codex only: remove stale agents/openai.yaml sidecars from managed
     // gsd-* skill dirs. Prior installs wrote these files so Codex would show a
@@ -9831,12 +9052,45 @@ function install(isGlobal, runtime = 'claude', options = {}) {
     // Kilo support native, on-demand skills in addition to flat commands — see
     // resolveRuntimeArtifactLayout's opencode/kilo entries. Derive skills from
     // the SAME staged command set (gsdSrc) so both surfaces match exactly. (#784)
-    const _skillCount = installOpencodeFamilySkills(runtime, targetDir, gsdSrc, pathPrefix);
+    const _skillCount = installOpencodeFamilySkills(runtime, targetDir, gsdSrc, pathPrefix, getCommitAttribution);
     if (_skillCount > 0) {
       console.log(`  ${green}✓${reset} Installed ${_skillCount} skills to skills/`);
     } else {
       failures.push('skills/gsd-*');
     }
+
+    // OpenCode-only: install the native plugin adapter (#1914). OpenCode
+    // declares hooksSurface: 'none', so GSD's lifecycle hooks are never
+    // registered as settings.json hooks the way Claude Code does — the hook
+    // *scripts* ship to <configDir>/hooks/ but nothing invokes them. This
+    // plugin bridges OpenCode's event bus onto those existing hook scripts
+    // (prompt guard, read guard, injection scanner, context monitor, ...),
+    // spawning them as subprocesses. OpenCode auto-discovers plugin files under
+    // <configDir>/plugins/ at startup — no opencode.json registration needed
+    // (its `plugin` array is for npm packages, not local file paths).
+    //
+    // The file MUST land as `.js`: OpenCode's loader globs
+    // `{plugin,plugins}/*.{ts,js}` (verified against its source) — a `.cjs`
+    // extension would never be discovered. The config dir carries a
+    // `{"type":"commonjs"}` package.json (written above), so the `.js` file is
+    // interpreted as CommonJS, matching the adapter's module.exports/require.
+    // Kilo has no plugin surface, so this is gated to OpenCode only.
+    if (isOpencode) {
+      const pluginSrc = path.join(src, '.opencode', 'plugins', 'gsd-core.js');
+      const pluginDestDir = path.join(targetDir, 'plugins');
+      const pluginDest = path.join(pluginDestDir, 'gsd-core.js');
+      if (fs.existsSync(pluginSrc)) {
+        fs.mkdirSync(pluginDestDir, { recursive: true });
+        fs.copyFileSync(pluginSrc, pluginDest);
+        if (fs.existsSync(pluginDest)) {
+          console.log(`  ${green}✓${reset} Installed OpenCode plugin (bridges GSD hooks)`);
+        } else {
+          failures.push('plugins/gsd-core.js');
+        }
+      } else {
+        failures.push('plugins/gsd-core.js');
+      }
+    }
   } else if (isCline) {
     // Cline local install: rules-based only — commands are embedded in .clinerules (generated below).
     // No skills/commands directory needed for local installs.
@@ -9886,7 +9140,7 @@ function install(isGlobal, runtime = 'claude', options = {}) {
       fs.mkdirSync(commandsDir, { recursive: true });
       const gsdSrc = _stageSkills(_commandsDir);
       const gsdDest = path.join(commandsDir, 'gsd');
-      copyWithPathReplacement(gsdSrc, gsdDest, pathPrefix, runtime, true, isGlobal);
+      copyWithPathReplacement(gsdSrc, gsdDest, pathPrefix, runtime, true, isGlobal, targetDir);
       if (verifyInstalled(gsdDest, 'commands/gsd')) {
         console.log(`  ${green}✓${reset} Installed commands/gsd`);
       } else {
@@ -9968,7 +9222,7 @@ function install(isGlobal, runtime = 'claude', options = {}) {
   const skillSrc = path.join(src, 'gsd-core');
   const skillDest = path.join(targetDir, 'gsd-core');
   const savedGsdArtifacts = preserveUserArtifacts(skillDest, USER_OWNED_ARTIFACTS);
-  copyWithPathReplacement(skillSrc, skillDest, pathPrefix, runtime, false, isGlobal);
+  copyWithPathReplacement(skillSrc, skillDest, pathPrefix, runtime, false, isGlobal, targetDir);
   restoreUserArtifacts(skillDest, savedGsdArtifacts);
   if (verifyInstalled(skillDest, 'gsd-core')) {
     console.log(`  ${green}✓${reset} Installed workflow assets`);
@@ -9988,7 +9242,7 @@ function install(isGlobal, runtime = 'claude', options = {}) {
     const commandsSrc = path.join(src, 'commands', 'gsd');
     const commandsDest = path.join(skillDest, 'commands', 'gsd');
     if (fs.existsSync(commandsSrc)) {
-      copyWithPathReplacement(commandsSrc, commandsDest, pathPrefix, runtime, true, isGlobal);
+      copyWithPathReplacement(commandsSrc, commandsDest, pathPrefix, runtime, true, isGlobal, targetDir);
       console.log(`  ${green}✓${reset} Installed command bodies to gsd-core/commands/gsd/ (workflow delegation targets)`);
     }
   }
@@ -10030,11 +9284,24 @@ function install(isGlobal, runtime = 'claude', options = {}) {
   agentsSrc = _stageAgents(path.join(src, 'agents'));
   const agentsDest = path.join(targetDir, 'agents');
 
+  // ADR-1235 §1: runtimes that have been migrated to the descriptor-driven agent
+  // path (installRuntimeArtifacts → convertedAgentsKind). The descriptor path
+  // applies path-rewrite + attribution + converter + normalize via
+  // stageAgentsForRuntimeWithConverter (with agentCtx pre-converter threading) in
+  // createRuntimeArtifactInstallPlan. Their agents are already written ABOVE
+  // (by installRuntimeArtifacts at line 8912), which also performs its own
+  // stale-file prune pass. The inline stale-removal + inline loop both skip them.
+  // Trivial group (cursor/windsurf/augment/trae/codebuddy) cut over together.
+  // cline is excluded: it takes a rules-only local branch and has a local/global
+  // complication that the descriptor-driven path does not handle correctly.
+  const _DESCRIPTOR_AGENTS_RUNTIMES = new Set(['cursor', 'windsurf', 'augment', 'trae', 'codebuddy']);
+
   // Always remove stale gsd-* agents first so re-installing with
   // `--minimal` actually shrinks a previously-full install.
   // For Codex this also covers per-agent `.toml` files alongside the `.md`
   // sources so a full → minimal switch doesn't leave stale registrations.
-  if (fs.existsSync(agentsDest)) {
+  // Skipped for descriptor-agent runtimes (installRuntimeArtifacts prunes).
+  if (!_DESCRIPTOR_AGENTS_RUNTIMES.has(runtime) && fs.existsSync(agentsDest)) {
     for (const file of fs.readdirSync(agentsDest)) {
       if (
         file.startsWith('gsd-') &&
@@ -10047,6 +9314,10 @@ function install(isGlobal, runtime = 'claude', options = {}) {
 
   if (isKimi) {
     console.log(`  ${dim}↳${reset} Kimi custom agent YAML/prompt artifacts were installed via runtime artifact layout`);
+  } else if (_DESCRIPTOR_AGENTS_RUNTIMES.has(runtime)) {
+    // installRuntimeArtifacts already wrote agents + handles stale-file cleanup
+    // via its own prune pass. No further action needed.
+    console.log(`  ${dim}↳${reset} Agents installed via descriptor-driven layout (${runtime})`);
   } else if (isMinimalMode(_effectiveInstallMode)) {
     // Codex registers agents in `config.toml` via `[agents.gsd-*]` sections.
     // Without stripping them here, a full → minimal reinstall would leave the
@@ -10372,6 +9643,31 @@ function install(isGlobal, runtime = 'claude', options = {}) {
     }
   }
 
+  // Copy scripts/gen-capability-registry.cjs + scripts/gen-loop-host-contract.cjs —
+  // required by gsd-core/bin/lib/capability-loader.cjs at overlay-composition time via
+  // require('../../../scripts/gen-capability-registry.cjs') (which itself requires
+  // gen-loop-host-contract.cjs). Without these, the loader's never-crash invariant
+  // discards EVERY third-party capability overlay and silently falls back to the frozen
+  // first-party registry, so installed capabilities are inert (#1920). Same class of
+  // gap as #1223 (fix-slash-commands.cjs) and copied unconditionally for the same reason:
+  // any runtime that installs gsd-core/ needs the capability system to compose.
+  {
+    const capGenDestDir = path.join(targetDir, 'scripts');
+    fs.mkdirSync(capGenDestDir, { recursive: true });
+    for (const gen of ['gen-capability-registry.cjs', 'gen-loop-host-contract.cjs']) {
+      const genSrc = path.join(src, 'scripts', gen);
+      const genDest = path.join(capGenDestDir, gen);
+      if (!fs.existsSync(genSrc)) {
+        failures.push(`scripts/${gen} (source missing from package — reinstall from npm)`);
+      } else {
+        fs.copyFileSync(genSrc, genDest);
+        if (!verifyFileInstalled(genDest, `scripts/${gen}`)) {
+          failures.push(`scripts/${gen}`);
+        }
+      }
+    }
+  }
+
   // Remove legacy get-shit-done-cc artifacts and stale update caches (#607).
   // cleanupLegacyGsdCc handles both the legacy shared cache and the per-package
   // cache (formerly an inline unlinkSync here). A cleanup failure must never
@@ -11217,14 +10513,7 @@ function install(isGlobal, runtime = 'claude', options = {}) {
  * Apply statusline config, then print completion message
  */
 function finishInstall(settingsPath, settings, statuslineCommand, shouldInstallStatusline, runtime = 'claude', isGlobal = true, configDir = null, bannerOpts = {}) {
-  const isOpencode = runtime === 'opencode';
-  const isKilo = runtime === 'kilo';
-  const isCodex = runtime === 'codex';
-  const isCopilot = runtime === 'copilot';
-  const isCursor = runtime === 'cursor';
-  const isWindsurf = runtime === 'windsurf';
-  const isTrae = runtime === 'trae';
-  const isCline = runtime === 'cline';
+  const { isOpencode, isKilo, isGemini, isCodex, isCopilot, isAntigravity, isCursor, isWindsurf, isAugment, isTrae, isQwen, isHermes, isCodebuddy, isCline, isKimi } = runtimeFlags(runtime);
   const plan = resolveInstallPlan(runtime);
 
   if (shouldInstallStatusline && plan.writesSharedSettings && !isOpencode) {
@@ -11347,37 +10636,11 @@ function finishInstall(settingsPath, settings, statuslineCommand, shouldInstallS
     }
   }
 
-  let program = 'Claude Code';
-  if (runtime === 'opencode') program = 'OpenCode';
-  if (runtime === 'gemini') program = 'Gemini';
-  if (runtime === 'kilo') program = 'Kilo';
-  if (runtime === 'codex') program = 'Codex';
-  if (runtime === 'copilot') program = 'Copilot';
-  if (runtime === 'antigravity') program = 'Antigravity';
-  if (runtime === 'cursor') program = 'Cursor';
-  if (runtime === 'windsurf') program = 'Windsurf';
-  if (runtime === 'augment') program = 'Augment';
-  if (runtime === 'trae') program = 'Trae';
-  if (runtime === 'cline') program = 'Cline';
-  if (runtime === 'qwen') program = 'Qwen Code';
-  if (runtime === 'hermes') program = 'Hermes Agent';
-  if (runtime === 'kimi') program = 'Kimi CLI';
-
-  let command = '/gsd-new-project';
-  if (runtime === 'opencode') command = '/gsd-new-project';
-  if (runtime === 'kilo') command = '/gsd-new-project';
-  if (runtime === 'gemini') command = '/gsd:new-project';
-  if (runtime === 'codex') command = '$gsd-new-project';
-  if (runtime === 'copilot') command = '/gsd-new-project';
-  if (runtime === 'antigravity') command = '/gsd-new-project';
-  if (runtime === 'cursor') command = 'gsd-new-project (mention the skill name)';
-  if (runtime === 'windsurf') command = '/gsd-new-project';
-  if (runtime === 'augment') command = '/gsd-new-project';
-  if (runtime === 'trae') command = '/gsd-new-project';
-  if (runtime === 'cline') command = '/gsd-new-project';
-  if (runtime === 'qwen') command = '/gsd-new-project';
-  if (runtime === 'hermes') command = '/gsd-new-project';
-  if (runtime === 'kimi') command = '/skill:gsd-new-project';
+  // program + command are now single-source lookups (ADR-1239 Phase B / #1679):
+  // program is the runtime display label; command is the per-host /gsd-new-project
+  // invocation syntax.
+  const program = getRuntimeLabel(runtime);
+  const command = getRuntimeNewProjectCommand(runtime);
 
   // Claude Code global installs use the skills/ format (CC 2.1.88+).
   // Restart is required for CC to pick up newly-installed skills, and the
@@ -12404,6 +11667,8 @@ module.exports = {
     // runtimeArtifactConversion spread (#1559).
     processAttribution,
     applyRuntimeContentRewritesForCommandsInPlace,
+    _copyStaged,
+    copyWithPathReplacement,
   };
 
 // Main logic — only run when not loaded as a module for testing