@mmerterden/multi-agent-pipeline 20.8.1 → 20.8.3

package/install/claude.mjs

@@ -5,46 +5,51 @@
  * `CLAUDE.md` template, preferences template, and the secret-detection
  * pre-commit hook in `settings.json`.
  *
- * Layout MUST stay equivalent to the pre-v8.0.0 monolithic install path -
- * install layout smoke (`smoke-install-layout.sh`) compares before/after
- * trees on every release. (v11.4.1 intentionally changed two behaviours
- * without changing the layout: agents are cleaned per-file instead of wiping
- * the dir, and symlinked install targets are replaced before writing.)
+ * The install layout smoke (`smoke-install-layout.sh`) compares the installed
+ * tree against a committed fixture on every release.
  *
  * @module install/claude
  */
 
-import { existsSync, readFileSync, readdirSync, renameSync, rmSync } from "fs";
+import { cpSync, existsSync, readFileSync, readdirSync, rmSync } from "fs";
 import { join, dirname } from "path";
 import { execSync } from "child_process";
 
 import { localizeCommands } from "../pipeline/scripts/localize-commands.mjs";
 
 import {
+  classifyInstallDir,
   copyDir,
   copyFile,
   copySkillsIndex,
   countFiles,
   dirsIdentical,
+  loadCatalogHistory,
+  matchesShippedVersion,
   ensureDir,
   ensureRealDir,
   isDryRun,
   isLocalOnlySkill,
+  listFiles,
   pruneAbandonedTrees,
   pruneLegacyMultiAgentSkills,
   pruneOrphanSkillFiles,
+  readInstallManifest,
   removePipelineAgentFiles,
+  stageAndSwapTrees,
+  syncTrackedFiles,
   wipeDir,
   writeFile,
+  writeInstallManifest,
 } from "./_common.mjs";
 import { EXTERNAL_SKILLS_MANIFEST } from "./_platform-filter.mjs";
 import { DEV_ONLY_SCRIPTS, countDevOnlyFiles } from "./_dev-only-files.mjs";
 import { registerMcpServer } from "./_mcp-register.mjs";
 
 /**
- * Dead matcher written by pre-v11.4.1 installs. Hook matchers only ever see
- * the tool name, so this string never matched and the hook never ran.
- * Kept so installs can migrate it and uninstall can clean it.
+ * A matcher an older install wrote. Hook matchers only ever see the tool name,
+ * so this string never matches and the hook never runs. Kept so installs can
+ * migrate it and uninstall can clean it.
  */
 export const LEGACY_PRE_COMMIT_MATCHER = "Bash(git commit:*)";
 export const AGENT_GUARD_FILE_MATCHER = "Edit|Write|NotebookEdit";
@@ -87,33 +92,35 @@ export const PIPELINE_LOCAL_SKILLS = ["apple-archive-compliance", "google-play-c
 export function installClaude(ctx) {
   const { home, pipelineSrc, indexOnly, useSymlinks, platformFlag, pruneExternal } = ctx;
 
-  const CLAUDE_COMMANDS = join(home, ".claude", "commands");
-  const CLAUDE_AGENTS = join(home, ".claude", "agents");
-  const PREFS_PATH = join(home, ".claude", "multi-agent-preferences.json");
-  const CLAUDE_SCRIPTS = join(home, ".claude", "scripts");
-  const CLAUDE_RULES = join(home, ".claude", "rules");
-  const CLAUDE_SKILLS = join(home, ".claude", "skills");
-  const CLAUDE_SCHEMAS = join(home, ".claude", "schemas");
-  const CLAUDE_LIB = join(home, ".claude", "lib");
-  const CLAUDE_MA_REFS = join(home, ".claude", "multi-agent-refs");
-  const CLAUDE_TEMPLATES = join(home, ".claude", "templates");
+  const CLAUDE_DIR = join(home, ".claude");
+  const CLAUDE_AGENTS = join(CLAUDE_DIR, "agents");
+  const PREFS_PATH = join(CLAUDE_DIR, "multi-agent-preferences.json");
+  const CLAUDE_RULES = join(CLAUDE_DIR, "rules");
+  const CLAUDE_SKILLS = join(CLAUDE_DIR, "skills");
 
   // Before laying anything down: drop trees an older install created that no
   // current installer manages. Wipe-before-copy only protects trees still being
-  // written, so an abandoned one persists on every existing machine forever.
-  const prunedTrees = pruneAbandonedTrees(join(home, ".claude"));
+  // written, so an abandoned one would otherwise stay on disk indefinitely.
+  const prunedTrees = pruneAbandonedTrees(CLAUDE_DIR);
   if (prunedTrees > 0) {
     console.log(`  [Claude Code] Removed ${prunedTrees} abandoned tree(s) from an older install`);
   }
 
-  installCommands(pipelineSrc, CLAUDE_COMMANDS, useSymlinks);
-  installMultiAgentRefs(pipelineSrc, CLAUDE_MA_REFS, useSymlinks);
-  installScripts(pipelineSrc, CLAUDE_SCRIPTS, useSymlinks);
+  const manifest = readInstallManifest(CLAUDE_DIR);
+  // An install without a manifest overwrote every file it shipped on each run,
+  // so after one (the version stamp says one happened) a file carrying a
+  // shipped name is that installer's copy. On a machine with no prior install
+  // the same file is the user's.
+  const adopt = !manifest.present && existsSync(join(CLAUDE_DIR, ".pipeline-version"));
+
+  if (useSymlinks) {
+    linkOwnedTrees(pipelineSrc, CLAUDE_DIR);
+  } else {
+    installOwnedTrees({ pipelineSrc, claudeDir: CLAUDE_DIR, manifest, adopt });
+    installTopLevelCommands({ pipelineSrc, claudeDir: CLAUDE_DIR, manifest, adopt });
+  }
   installAgents(pipelineSrc, CLAUDE_AGENTS, useSymlinks);
   installRules(pipelineSrc, CLAUDE_RULES, useSymlinks);
-  installSchemas(pipelineSrc, CLAUDE_SCHEMAS, useSymlinks);
-  installLib(pipelineSrc, CLAUDE_LIB, useSymlinks);
-  installTemplates(pipelineSrc, CLAUDE_TEMPLATES, useSymlinks);
   runPreDeployScans(pipelineSrc);
   installSkills({
     pipelineSrc,
@@ -126,72 +133,179 @@ export function installClaude(ctx) {
   ensureClaudeMd(home, pipelineSrc);
   ensurePreferences(PREFS_PATH, pipelineSrc);
   configureSettings(home);
+  if (!useSymlinks) writeInstallManifest(CLAUDE_DIR, manifest);
 
-  // Claude Code was the last target still shipping skills without the tools those
-  // skills call. The multi-agent-toolkit server backs design-check, every ios_* / android_*
-  // simulator call and the archive audits, and its absence is invisible until a run
-  // reaches for one of them. `--scope user` is not optional here: `claude mcp add`
-  // defaults to project scope, which would register the server only for whichever
-  // directory the installer ran in.
+  // The multi-agent-toolkit server backs design-check, every ios_* / android_*
+  // simulator call and the archive audits; the skills fail only when a run
+  // reaches for one of its tools, so the installer registers it up front.
   registerMcpServer("claude", "Claude Code");
 
   console.log("");
 }
 
-function installCommands(pipelineSrc, dest, useSymlinks) {
-  console.log("  [Claude Code] Installing pipeline commands...");
-  const commandsSrc = join(pipelineSrc, "commands");
-  if (!existsSync(commandsSrc)) return;
+/**
+ * The trees under ~/.claude the pipeline owns outright, laid down as one
+ * transaction: each is built beside its destination and all are swapped in
+ * together, so a failed copy leaves the previous install whole.
+ *
+ * `commands/multi-agent` is the pipeline's namespace; local-only alias
+ * wrappers (frontmatter `local-only: true`, written by /multi-agent:save and
+ * never shipped) are carried into the new copy. `lib/` and `templates/` can
+ * hold files the user put there, so they are built from the current copy and
+ * updated file by file against the install manifest.
+ */
+function installOwnedTrees({ pipelineSrc, claudeDir, manifest, adopt }) {
+  const commandsDir = ensureRealDir(join(claudeDir, "commands"), {
+    pipelineSrc,
+    userOwned: true,
+  });
+  const nsDest = join(commandsDir, "multi-agent");
+  const stashDir = join(commandsDir, ".multi-agent-wrapper-stash");
+  const trees = [];
+  const logs = [];
+  const add = (dest, label, src, build) => {
+    if (!src || !existsSync(src)) return;
+    if (classifyInstallDir(dest, pipelineSrc) === "foreign-link") {
+      ensureRealDir(dest, { pipelineSrc });
+      return;
+    }
+    trees.push({ dest, label, build });
+  };
 
-  const ownedCmdDir = join(dest, "multi-agent");
+  console.log(
+    "  [Claude Code] Installing pipeline commands, refs, scripts, schemas, lib, templates...",
+  );
 
-  if (useSymlinks) {
-    // --link (dev) mode: dest becomes a symlink into the repo. Never pre-wipe
-    // or restore wrappers through an existing link; both would delete from or
-    // write into the developer's repo checkout itself.
-    copyDir(commandsSrc, dest, { useSymlinks });
-    console.log(`    -> ${countFiles(commandsSrc)} files linked at ${dest}`);
-    return;
+  const nsSrc = join(pipelineSrc, "commands", "multi-agent");
+  add(nsDest, "commands", nsSrc, (staged) => {
+    copyDir(nsSrc, staged);
+    const restored = carryLocalOnlyWrappers(nsDest, stashDir, staged, pipelineSrc);
+    localizeCommandDescriptions(claudeDir, staged);
+    logs.push(`    -> ${countFiles(nsSrc)} files copied to ${nsDest}`);
+    if (restored > 0) logs.push(`    -> preserved ${restored} local-only alias wrapper(s)`);
+  });
+
+  // refs/ and the internal pickers live outside commands/ so Claude Code does
+  // not register them as `/multi-agent:refs:*` slash commands; commands read
+  // them by absolute path.
+  const refsSrc = join(pipelineSrc, "multi-agent-refs");
+  const refsDest = join(claudeDir, "multi-agent-refs");
+  add(refsDest, "refs", refsSrc, (staged) => {
+    copyDir(refsSrc, staged);
+    logs.push(`    -> ${countFiles(refsSrc)} ref files copied to ${refsDest}`);
+  });
+
+  const scriptsSrc = join(pipelineSrc, "scripts");
+  const scriptsDest = join(claudeDir, "scripts");
+  add(scriptsDest, "scripts", scriptsSrc, (staged) => {
+    copyDir(scriptsSrc, staged, { exclude: DEV_ONLY_SCRIPTS });
+    // DEV_ONLY_SCRIPTS mixes literal names, directories and regexes, so the
+    // excluded count comes from walking the tree.
+    const excluded = countDevOnlyFiles(scriptsSrc);
+    logs.push(
+      `    -> ${countFiles(scriptsSrc) - excluded} files copied to ${scriptsDest} (${excluded} dev-only excluded)`,
+    );
+  });
+
+  const schemasSrc = join(pipelineSrc, "schemas");
+  const schemasDest = join(claudeDir, "schemas");
+  add(schemasDest, "schemas", schemasSrc, (staged) => {
+    copyDir(schemasSrc, staged);
+    logs.push(`    -> ${countFiles(schemasSrc)} files copied to ${schemasDest}`);
+  });
+
+  for (const [name, src] of [
+    ["lib", join(pipelineSrc, "lib")],
+    ["templates", join(dirname(pipelineSrc), "install", "templates")],
+  ]) {
+    const dest = join(claudeDir, name);
+    add(dest, name, src, (staged) => {
+      if (classifyInstallDir(dest, pipelineSrc) === "real") {
+        cpSync(dest, staged, { recursive: true });
+      } else {
+        ensureDir(staged);
+      }
+      const res = syncTrackedFiles({
+        srcDir: src,
+        destDir: staged,
+        displayDir: dest,
+        rels: listFiles(src),
+        prefix: `${name}/`,
+        manifest,
+        adopt,
+        reportUnknown: true,
+        label: "shipped",
+      });
+      logs.push(
+        `    -> ${countFiles(src) - res.kept.length} files in place at ${dest}` +
+          (res.removed ? ` (${res.removed} retired file(s) removed)` : ""),
+      );
+    });
   }
 
-  // After a prior --link install, dest (or the owned subdir) is a symlink
-  // into the repo. Replace it with a real directory before any wipe/copy so
-  // the install can never land inside the repo checkout.
-  ensureRealDir(dest);
-  ensureRealDir(ownedCmdDir);
-
-  // Wipe only our namespace dir so files renamed/removed in the source don't
-  // linger as ghost slash commands. Other namespaces under
-  // `~/.claude/commands/` are untouched.
-  //
-  // Preserve local-only alias wrappers (frontmatter `local-only: true`) across
-  // the wipe. They live ONLY under ~/.claude (never in pipeline/commands, and
-  // never synced), so without this stash+restore they would be destroyed on
-  // every install/update. The stash is an on-disk rename, not an in-memory
-  // snapshot: the only copy of user-authored content stays on disk at every
-  // instant, so an install interrupted between wipe and restore loses nothing,
-  // and the next run adopts any leftover stash.
-  const wrapperStash = stashLocalOnlyWrappers(ownedCmdDir);
-  wipeDir(ownedCmdDir);
-
-  copyDir(commandsSrc, dest, { useSymlinks });
-  const restored = unstashLocalOnlyWrappers(ownedCmdDir, wrapperStash);
-  console.log(`    -> ${countFiles(commandsSrc)} files copied to ${dest}`);
-  if (restored > 0) {
-    console.log(`    -> preserved ${restored} local-only alias wrapper(s)`);
+  stageAndSwapTrees(trees, { swapRoot: join(claudeDir, ".pipeline-swap") });
+  for (const line of logs) console.log(line);
+  if (!isDryRun() && existsSync(stashDir) && trees.some((t) => t.dest === nsDest)) {
+    rmSync(stashDir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Top-level command files (`commands/*.md` outside the multi-agent namespace)
+ * share `~/.claude/commands/` with the user's own commands, so each is written
+ * only when absent or unchanged since the last install (install manifest).
+ */
+function installTopLevelCommands({ pipelineSrc, claudeDir, manifest, adopt }) {
+  const commandsSrc = join(pipelineSrc, "commands");
+  if (!existsSync(commandsSrc)) return;
+  const commandsDir = ensureRealDir(join(claudeDir, "commands"), {
+    pipelineSrc,
+    userOwned: true,
+  });
+  const rels = listFiles(commandsSrc).filter((r) => !r.startsWith("multi-agent/"));
+  if (!isDryRun()) ensureDir(commandsDir);
+  const res = syncTrackedFiles({
+    srcDir: commandsSrc,
+    destDir: commandsDir,
+    rels,
+    prefix: "commands/",
+    manifest,
+    adopt,
+    label: "shipped",
+  });
+  if (res.written || res.removed) {
+    console.log(
+      `    -> ${res.written} top-level command file(s) written, ${res.removed} retired one(s) removed`,
+    );
+  }
+}
+
+/** `--link` (dev) mode: every owned tree becomes a symlink into the checkout. */
+function linkOwnedTrees(pipelineSrc, claudeDir) {
+  const links = [
+    ["commands", join(pipelineSrc, "commands")],
+    ["multi-agent-refs", join(pipelineSrc, "multi-agent-refs")],
+    ["scripts", join(pipelineSrc, "scripts")],
+    ["schemas", join(pipelineSrc, "schemas")],
+    ["lib", join(pipelineSrc, "lib")],
+    ["templates", join(dirname(pipelineSrc), "install", "templates")],
+  ];
+  console.log("  [Claude Code] Linking pipeline trees (--link)...");
+  for (const [name, src] of links) {
+    if (!existsSync(src)) continue;
+    copyDir(src, join(claudeDir, name), { useSymlinks: true });
+    console.log(`    -> ${join(claudeDir, name)} -> ${src}`);
   }
-  localizeCommandDescriptions(pipelineSrc, ownedCmdDir);
 }
 
 // Picker descriptions follow prefs.global.outputLanguage: files shipping a
 // description-tr frontmatter line get their description swapped in the
 // INSTALLED tree only (repo and npm package stay English; /multi-agent:sync
 // restores English before mirroring back). Failure is non-fatal.
-function localizeCommandDescriptions(pipelineSrc, ownedCmdDir) {
+function localizeCommandDescriptions(claudeDir, ownedCmdDir) {
   if (isDryRun()) return;
   try {
-    const home = dirname(dirname(ownedCmdDir));
-    const prefsPath = join(home, "multi-agent-preferences.json");
+    const prefsPath = join(claudeDir, "multi-agent-preferences.json");
     if (!existsSync(prefsPath)) return;
     const prefs = JSON.parse(readFileSync(prefsPath, "utf-8"));
     if (prefs?.global?.outputLanguage !== "tr") return;
@@ -204,87 +318,45 @@ function localizeCommandDescriptions(pipelineSrc, ownedCmdDir) {
   }
 }
 
-// Move command dirs whose SKILL.md declares `local-only: true` into an on-disk
-// stash beside the namespace, so installCommands can restore them after the
-// namespace wipe. Returns the stash path.
-function stashLocalOnlyWrappers(ownedCmdDir) {
-  const stashDir = join(dirname(ownedCmdDir), ".multi-agent-wrapper-stash");
-  if (isDryRun() || !existsSync(ownedCmdDir)) return stashDir;
-  for (const name of readdirSync(ownedCmdDir)) {
-    const dir = join(ownedCmdDir, name);
-    const skill = join(dir, "SKILL.md");
-    if (!existsSync(skill)) continue;
-    if (!/^local-only:\s*true\s*$/m.test(readFileSync(skill, "utf-8"))) continue;
-    ensureDir(stashDir);
-    const target = join(stashDir, name);
-    if (existsSync(target)) rmSync(target, { recursive: true, force: true });
-    renameSync(dir, target);
+const isLocalOnlyDir = (dir) => {
+  const skill = join(dir, "SKILL.md");
+  try {
+    return existsSync(skill) && /^local-only:\s*true\s*$/m.test(readFileSync(skill, "utf-8"));
+  } catch {
+    return false;
   }
-  return stashDir;
-}
-
-// Restore stashed local-only wrappers (including any leftover from an earlier
-// interrupted run), but never clobber a real command the pipeline just
-// installed under the same name. Returns the count restored.
-function unstashLocalOnlyWrappers(ownedCmdDir, stashDir) {
-  if (isDryRun() || !existsSync(stashDir)) return 0;
+};
+
+// Copy local-only wrappers from the current namespace, and from a stash an
+// older installer's interrupted run left beside it, into the staged namespace.
+// A wrapper whose name the release now ships cannot be carried; say whose
+// content is dropped, since /multi-agent:save writes exactly these.
+function carryLocalOnlyWrappers(nsDest, stashDir, staged, pipelineSrc) {
+  const sources = [];
+  if (classifyInstallDir(nsDest, pipelineSrc) === "real") sources.push(nsDest);
+  if (existsSync(stashDir)) sources.push(stashDir);
   let n = 0;
-  for (const name of readdirSync(stashDir)) {
-    const from = join(stashDir, name);
-    const to = join(ownedCmdDir, name);
-    if (existsSync(to)) {
-      // The pipeline now ships a real command under a name the user's wrapper
-      // was using, so the wrapper cannot be restored. Say whose content is
-      // being dropped: /multi-agent:save writes exactly these, and a release
-      // claiming a new name would otherwise delete a saved routine in silence.
-      console.log(
-        `    -> WARNING: dropped local-only wrapper '${name}' - this release ships a command ` +
-          `with that name. Re-save it under a different name if you still need it.`,
-      );
-      rmSync(from, { recursive: true, force: true });
-      continue;
+  for (const from of sources) {
+    for (const name of readdirSync(from)) {
+      const dir = join(from, name);
+      if (from === nsDest && !isLocalOnlyDir(dir)) continue;
+      const to = join(staged, name);
+      if (existsSync(to)) {
+        if (from === nsDest && existsSync(join(pipelineSrc, "commands", "multi-agent", name))) {
+          console.log(
+            `    -> WARNING: dropped local-only wrapper '${name}' - this release ships a command ` +
+              `with that name. Re-save it under a different name if you still need it.`,
+          );
+        }
+        continue;
+      }
+      cpSync(dir, to, { recursive: true });
+      n++;
     }
-    ensureDir(ownedCmdDir);
-    renameSync(from, to);
-    n++;
   }
-  rmSync(stashDir, { recursive: true, force: true });
   return n;
 }
 
-// The pipeline's reference docs (refs/) + internal pickers live OUTSIDE the
-// commands/ tree so Claude Code does NOT register them as invocable
-// `/multi-agent:refs:*` slash commands. Commands read them by absolute path
-// ($HOME/.claude/multi-agent-refs/...). Wipe-before-copy so renamed/removed
-// refs don't linger.
-function installMultiAgentRefs(pipelineSrc, dest, useSymlinks) {
-  const refsSrc = join(pipelineSrc, "multi-agent-refs");
-  if (!existsSync(refsSrc)) return;
-  console.log("  [Claude Code] Installing multi-agent refs (non-command)...");
-  if (!useSymlinks) ensureRealDir(dest);
-  wipeDir(dest);
-  copyDir(refsSrc, dest, { useSymlinks });
-  console.log(`    -> ${countFiles(refsSrc)} ref files copied to ${dest}`);
-}
-
-function installScripts(pipelineSrc, dest, useSymlinks) {
-  console.log("  [Claude Code] Installing scripts...");
-  const scriptsSrc = join(pipelineSrc, "scripts");
-  if (!existsSync(scriptsSrc)) return;
-
-  // Wipe-before-copy - scripts/ is a 100% pipeline-managed tree, so files
-  // removed upstream should not linger.
-  if (!useSymlinks) ensureRealDir(dest);
-  wipeDir(dest);
-  copyDir(scriptsSrc, dest, { exclude: DEV_ONLY_SCRIPTS, useSymlinks });
-  // Count files actually excluded by walking the tree: DEV_ONLY_SCRIPTS mixes
-  // literal names, whole directories, and regexes (the maintainer-smoke rule),
-  // so summing countFiles() over the array reported 0 for every regex entry.
-  const excludedCount = countDevOnlyFiles(scriptsSrc);
-  const scriptCount = countFiles(scriptsSrc) - excludedCount;
-  console.log(`    -> ${scriptCount} files copied to ${dest} (${excludedCount} dev-only excluded)`);
-}
-
 function installAgents(pipelineSrc, dest, useSymlinks) {
   console.log("  [Claude Code] Installing agent definitions...");
   const agentsSrc = join(pipelineSrc, "agents");
@@ -292,11 +364,12 @@ function installAgents(pipelineSrc, dest, useSymlinks) {
   // ~/.claude/agents also holds user-authored agent files. Never wipe the
   // whole dir; remove only the pipeline-shipped agent files (name set derived
   // from the source tree so it cannot go stale), then copy the fresh set in.
+  let target = dest;
   if (!useSymlinks) {
-    ensureRealDir(dest);
-    removePipelineAgentFiles(dest, agentsSrc);
+    target = ensureRealDir(dest, { pipelineSrc, userOwned: true });
+    removePipelineAgentFiles(target, agentsSrc);
   }
-  copyDir(agentsSrc, dest, { useSymlinks });
+  copyDir(agentsSrc, target, { useSymlinks });
   console.log(`    -> ${countFiles(agentsSrc)} files copied to ${dest}`);
 }
 
@@ -304,59 +377,19 @@ function installRules(pipelineSrc, dest, useSymlinks) {
   console.log("  [Claude Code] Installing rules...");
   const rulesSrc = join(pipelineSrc, "rules");
   if (!existsSync(rulesSrc)) return;
-  // rules/ is USER-OWNED: users evolve their global rules locally and the sync
-  // deliberately never pushes rules/ back to the repo (privacy). So an update
-  // must NOT wipe+overwrite them (that reverts local edits, including the git
-  // attribution rule). Install only files that do not already exist; leave the
-  // user's existing rules untouched. (Symlink mode is a dev choice and keeps its
-  // link-replace behavior.)
+  // rules/ is user-owned: users evolve their global rules locally and the sync
+  // never pushes rules/ back to the repo. An update installs only files that
+  // do not exist yet and leaves the user's rules untouched. (Symlink mode is a
+  // dev choice and keeps its link-replace behavior.)
   if (useSymlinks) {
     copyDir(rulesSrc, dest, { useSymlinks });
   } else {
-    ensureRealDir(dest);
-    copyDir(rulesSrc, dest, { skipExisting: true });
+    const target = ensureRealDir(dest, { pipelineSrc, userOwned: true });
+    copyDir(rulesSrc, target, { skipExisting: true });
   }
   console.log(`    -> rules present (existing local rules preserved)`);
 }
 
-function installSchemas(pipelineSrc, dest, useSymlinks) {
-  console.log("  [Claude Code] Installing JSON schemas...");
-  const schemasSrc = join(pipelineSrc, "schemas");
-  if (!existsSync(schemasSrc)) return;
-  // Wipe-before-copy - schemas/ is a 100% pipeline-managed tree, so files
-  // removed upstream should not linger.
-  if (!useSymlinks) ensureRealDir(dest);
-  wipeDir(dest);
-  copyDir(schemasSrc, dest, { useSymlinks });
-  console.log(`    -> ${countFiles(schemasSrc)} files copied to ${dest}`);
-}
-
-function installLib(pipelineSrc, dest, useSymlinks) {
-  console.log("  [Claude Code] Installing shell libraries...");
-  const libSrc = join(pipelineSrc, "lib");
-  if (!existsSync(libSrc)) return;
-  // Wipe-before-copy - lib/ is a 100% pipeline-managed tree.
-  if (!useSymlinks) ensureRealDir(dest);
-  wipeDir(dest);
-  copyDir(libSrc, dest, { useSymlinks });
-  console.log(`    -> ${countFiles(libSrc)} files copied to ${dest}`);
-}
-
-function installTemplates(pipelineSrc, dest, useSymlinks) {
-  // The templates shipped in the tarball but never reached the user tree, so
-  // `setup` told people to merge `install/templates/claude-hooks.json` - a path
-  // that exists only in a checkout. From an install the instruction named a file
-  // the reader did not have, and nothing said so.
-  console.log("  [Claude Code] Installing templates...");
-  const templatesSrc = join(dirname(pipelineSrc), "install", "templates");
-  if (!existsSync(templatesSrc)) return;
-  // Wipe-before-copy - templates/ is a 100% pipeline-managed tree.
-  if (!useSymlinks) ensureRealDir(dest);
-  wipeDir(dest);
-  copyDir(templatesSrc, dest, { useSymlinks });
-  console.log(`    -> ${countFiles(templatesSrc)} files copied to ${dest}`);
-}
-
 function runPreDeployScans(pipelineSrc) {
   // Pre-deploy security scan - warn-only, never halts install on its own.
   const scanScript = join(pipelineSrc, "scripts", "scan-skills.sh");
@@ -398,12 +431,13 @@ function runPreDeployScans(pipelineSrc) {
 }
 
 function installSkills(opts) {
-  const { pipelineSrc, dest, indexOnly, useSymlinks, pruneExternal } = opts;
+  const { pipelineSrc, indexOnly, useSymlinks, pruneExternal } = opts;
   console.log("  [Claude Code] Installing skills...");
 
   // Same symlink guard as the other owned trees: never prune or copy through
-  // a --link-era symlink into the repo checkout.
-  if (!useSymlinks) ensureRealDir(dest);
+  // a --link-era symlink into the repo checkout. The skills root also holds
+  // the user's own skills, so a symlink elsewhere is written through.
+  const dest = useSymlinks ? opts.dest : ensureRealDir(opts.dest, { pipelineSrc, userOwned: true });
 
   if (indexOnly) {
     ensureDir(dest);
@@ -417,12 +451,11 @@ function installSkills(opts) {
 
   let claudeSkillCount = 0;
 
-  // Claude Code no longer receives a local copy of the stack skills. The
-  // marketplace plugins (`ai-<stack>-toolkit`) are its only stack-skill source -
-  // a local copy duplicated ~110 skills against the enabled plugins (~10k
-  // tokens/session) and shadowed the plugin the moment it went stale. Only the
-  // two pipeline-owned compliance catalogs stay local (PIPELINE_LOCAL_SKILLS);
-  // they are deliberately not published to the marketplace.
+  // Claude Code gets its stack skills from the marketplace plugins
+  // (`ai-<stack>-toolkit`) only: a local copy would duplicate them against the
+  // enabled plugins and shadow a plugin once the copy went stale. Only the two
+  // pipeline-owned compliance catalogs stay local (PIPELINE_LOCAL_SKILLS); they
+  // are deliberately not published to the marketplace.
   ensureDir(dest);
   for (const name of PIPELINE_LOCAL_SKILLS) {
     const from = join(sharedCoreSrc, name);
@@ -434,9 +467,8 @@ function installSkills(opts) {
 
   // Single-standard enforcement: Claude Code invokes pipeline commands via
   // the `/multi-agent:*` slash-command namespace, so prune duplicate skill
-  // dirs left by older installs that copied shared/core wholesale. This used
-  // to live inside the external-copy branch; it must run unconditionally or
-  // the 51 multi-agent-* dirs return on the first install after a migration.
+  // dirs left by older installs that copied shared/core wholesale. It runs on
+  // every install, so such dirs cannot survive a migration.
   const pruned = pruneLegacyMultiAgentSkills(dest);
   if (pruned > 0) {
     console.log(
@@ -457,11 +489,13 @@ function installSkills(opts) {
   // Pre-manifest installs (<= v14.x) never wrote that manifest, so the branch
   // above cannot fire for them and the full 151-dir catalog would outlive every
   // upgrade. For those, prune by proof instead of by name: a dir byte-identical
-  // to the shipped catalog contains nothing of the user's and goes now; a dir
+  // to the shipped catalog, or to any version of it ever shipped
+  // (install/catalog-history.json), contains nothing of the user's and goes now; a dir
   // that differs is kept unless --prune-external explicitly opts in (and even
   // then a `local-only: true` SKILL.md keeps it).
   migratePreManifestExternalSkills(dest, join(pipelineSrc, "skills", "shared", "external"), {
     pruneExternal: Boolean(pruneExternal),
+    history: loadCatalogHistory(join(dirname(pipelineSrc), "install", "catalog-history.json")),
   });
 
   // Figma component skills moved to the ai-<platform>-toolkit marketplace
@@ -482,12 +516,9 @@ function installSkills(opts) {
     }
   }
 
-  // The index ships on FULL installs too, not just --index-only. It is what
-  // `match-skills.mjs` reads when prefs.global.dynamicSkillLoading is on, and the
-  // schema has always claimed a full install provides it. It did not: only
-  // --index-only copied it, so flipping the pref on a normal install produced an
-  // exit-1 "cannot read index" on the first dispatch. Two small files, and the
-  // feature is either wired or it is not.
+  // The index ships on full installs too: `match-skills.mjs` reads it when
+  // prefs.global.dynamicSkillLoading is on, and the preferences schema states
+  // that a full install provides it.
   copySkillsIndex(pipelineSrc, dest);
 
   // Same pre-directory-layout leftovers Copilot accumulated. Claude Code's tree is
@@ -570,8 +601,8 @@ function pruneManifestDeliveredSkills(dest) {
 /**
  * Migration for pre-manifest installs (<= v14.x): the external catalog was
  * copied here with no delivery manifest, so ours and the user's are told apart
- * by content, not by name. Byte-identical to the shipped catalog = provably
- * ours, removed. Different = kept, reported, and removable only via the
+ * by content, not by name. Byte-identical to the shipped catalog, or every
+ * file matching a version the catalog once shipped = provably ours, removed. Different = kept, reported, and removable only via the
  * explicit `--prune-external` flag (which still honors `local-only: true`).
  *
  * @param {string} dest - the installed skills directory
@@ -580,7 +611,7 @@ function pruneManifestDeliveredSkills(dest) {
  */
 function migratePreManifestExternalSkills(dest, externalSrc, opts) {
   if (!existsSync(externalSrc) || !existsSync(dest)) return;
-  const { pruneExternal } = opts;
+  const { pruneExternal, history } = opts;
   let identical = 0;
   let flagged = 0;
   const leftover = [];
@@ -608,13 +639,15 @@ function migratePreManifestExternalSkills(dest, externalSrc, opts) {
 
     let provablyOurs;
     try {
-      provablyOurs = dirsIdentical(join(externalSrc, name), stale);
+      provablyOurs =
+        dirsIdentical(join(externalSrc, name), stale) ||
+        matchesShippedVersion(stale, history, name);
     } catch {
       provablyOurs = false;
     }
     if (provablyOurs) {
       if (isDryRun()) {
-        console.log(`    [dry-run] would prune ${name}/ (identical to shipped catalog)`);
+        console.log(`    [dry-run] would prune ${name}/ (matches a shipped catalog version)`);
         identical++;
         continue;
       }
@@ -718,6 +751,39 @@ export function collapseDuplicateHooks(hooks) {
   return changed;
 }
 
+/**
+ * The hook command for a script installed under ~/.claude/scripts. The path is
+ * quoted: Claude Code runs the command through a shell, and an unquoted $HOME
+ * containing a space splits into two words, bash exits 126/127 and the gate
+ * stops running without anyone seeing it.
+ *
+ * @param {string} script file name under ~/.claude/scripts
+ */
+export const pipelineHookCommand = (script) => `bash "$HOME/.claude/scripts/${script}"`;
+
+const UNQUOTED_PIPELINE_HOOK =
+  /^bash (?:\$HOME|\$\{HOME\})\/\.claude\/scripts\/([\w.-]+\.sh)(\s.*)?$/;
+
+// Rewrite pipeline hook commands registered with an unquoted $HOME (by this
+// installer or a merged hooks template) to the quoted form, in place, so a
+// re-install fixes them instead of adding a second copy.
+export function quotePipelineHookCommands(hooks) {
+  if (!hooks || typeof hooks !== "object") return false;
+  let changed = false;
+  for (const groups of Object.values(hooks)) {
+    if (!Array.isArray(groups)) continue;
+    for (const group of groups) {
+      for (const h of Array.isArray(group?.hooks) ? group.hooks : []) {
+        const m = typeof h?.command === "string" ? UNQUOTED_PIPELINE_HOOK.exec(h.command) : null;
+        if (!m) continue;
+        h.command = `${pipelineHookCommand(m[1])}${m[2] || ""}`;
+        changed = true;
+      }
+    }
+  }
+  return changed;
+}
+
 export function configureSettings(home) {
   console.log("  [Claude Code] Configuring hooks + context management...");
   const SETTINGS_PATH = join(home, ".claude", "settings.json");
@@ -736,10 +802,11 @@ export function configureSettings(home) {
 
     if (!settings.hooks) settings.hooks = {};
     if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = [];
+    if (quotePipelineHookCommands(settings.hooks)) settingsChanged = true;
     // PreToolUse matchers are regexes over the TOOL NAME only, so the correct
-    // matcher is "Bash". The pre-v11.4.1 entry used "Bash(git commit:*)",
-    // which never matches any tool name - the secret gate never fired.
-    // Migrate that dead entry in place instead of stacking a duplicate.
+    // matcher is "Bash". A "Bash(git commit:*)" matcher (LEGACY_PRE_COMMIT_MATCHER)
+    // never matches a tool name, so the gate would never fire; such an entry
+    // is migrated in place instead of stacking a duplicate.
     // Command-level filtering (only scan on actual `git commit`) happens
     // inside pre-commit-check.sh via the hook's stdin JSON.
     const isPreCommitEntry = (h) =>
@@ -762,7 +829,7 @@ export function configureSettings(home) {
         hooks: [
           {
             type: "command",
-            command: "bash $HOME/.claude/scripts/pre-commit-check.sh",
+            command: pipelineHookCommand("pre-commit-check.sh"),
             timeout: 15,
             statusMessage: "Scanning staged changes for secrets...",
           },
@@ -813,7 +880,7 @@ export function configureSettings(home) {
         hooks: [
           {
             type: "command",
-            command: "bash $HOME/.claude/scripts/agent-guard.sh",
+            command: pipelineHookCommand("agent-guard.sh"),
             timeout: AGENT_GUARD_TIMEOUT,
             statusMessage,
           },