@mmerterden/multi-agent-pipeline 11.3.2 → 11.5.0

package/CHANGELOG.md

@@ -14,6 +14,147 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ---
 
+## [11.5.0] - 2026-07-16
+
+Full-project refactor round: 20 verified defect fixes (install lifecycle, shell
+libs, fetchers, gate scripts), an install-time performance overhaul, and new
+supply-chain / validation gates. Driven by a 4-band analysis (best-practices
+research, bug hunt, category scoring, upstream-drift check).
+
+### Fixed - data loss and destructive paths
+
+- **Install no longer wipes user agent files.** `installAgents` wiped the whole
+  `~/.claude/agents` / `~/.copilot/agents` dir on every install/update, deleting
+  user-authored subagents. It now removes only pipeline-owned files (list derived
+  from `pipeline/agents/` so it cannot go stale).
+- **Plain install after `--link` no longer destroys the dev checkout.** Every
+  wipe/copy target now goes through a symlink guard (`ensureRealDir`); a `--link`
+  re-install just re-links instead of wiping through the symlink into the repo.
+- **Unguarded `rm -rf` paths locked down.** `shadow-git.sh` validates task ids
+  (`prune ..` refused); `multi-repo-pipeline.sh teardown` refuses `/`, `$HOME`,
+  the project root, and their ancestors after path resolution.
+- **`update-issue-progress.sh` no longer eats issue bodies.** The Progress-table
+  rewrite is now bounded at the legend comment, the next heading, or EOF; bodies
+  without the legend comment keep all trailing sections.
+- **Copilot instructions merge is now marker-bounded.** An explicit end marker
+  preserves user content appended after the pipeline section across install,
+  update, and uninstall (previously sliced to EOF).
+- **Uninstall actually removes what install creates.** Agent files (dir-vs-file
+  bug meant none were ever removed), `multi-agent-refs/`, `schemas/`, `lib/`,
+  and the compliance core skills are now covered on both targets; token and
+  preferences guarantees unchanged.
+
+### Fixed - security
+
+- **Pre-commit secret-scan hook fired never.** The PreToolUse matcher used
+  permission-rule syntax that can never match the tool name; matcher is now
+  `Bash` with a fast stdin filter in `pre-commit-check.sh`, and existing installs
+  migrate the dead entry in place.
+- **Secrets off argv.** OAuth refresh grants, bearer/PAT headers, Basic auth,
+  and keychain writes across nine call sites (fetchers, repo-cache, issue-fetcher,
+  figma-mcp-refresh, credential-store, keychain-save) moved to `curl -K <(...)`
+  configs and stdin so tokens never appear in `ps`.
+- **Crashlytics service-account key hygiene.** The decoded Firebase SA JSON now
+  lives in a `mktemp` file created under `umask 077` with trap cleanup instead of
+  a predictable world-readable `/tmp` name.
+- **Telemetry honesty.** The "anonymous" install ping no longer sends
+  `githubUser`, `gitEmail`, or `hostname`.
+
+### Fixed - correctness
+
+- **`fetch-confluence.sh` worked never.** An env-prefix-on-assignment bug meant
+  the URL parser always saw empty input; every invocation failed. Parsing now
+  goes through argv and the fetcher honors its documented exit codes.
+- **`diff-risk-score.mjs` default invocation** resolved the diff base after
+  using it (`null...HEAD` fatal, gate fail-open); base now resolves first.
+- **`evidence-gate.mjs`** no longer flags passing logs containing "0 tests
+  failed" as failures.
+- **`grep -c || echo 0` double-output idiom** fixed at ~20 sites via a shared
+  `count-lib.sh` helper (bogus `* PR:` bullets in Jira/Confluence bodies, silently
+  zeroed convention counters in `extract-conventions.sh`).
+- **False-success family.** `multi-repo-pipeline.sh` no longer prints
+  "committed/pushed" on failure; `repo-cache.sh` keeps the previous cache when a
+  refresh fails instead of serving an empty file for the TTL; `review-watch.sh
+  --watch` survives transient gh failures and its cursor can no longer move
+  backwards.
+- **`issue-fetcher.sh`** classifies bare `#316` / `316` correctly (repo picker
+  path instead of a malformed `//issues/` URL).
+- **`phase-tracker.sh`** read-modify-write is now lock-protected; parallel
+  Phase 4 reviewers no longer lose token/cost deltas.
+- **Shadow-git**: forced excludes now land in `info/exclude` (they were dead
+  code, ballooning snapshots with DerivedData), and `restore --files` removes
+  files created after the snapshot instead of keeping half the change.
+- **macOS bash 3.2 portability**: `${URL,,}` in `fetch-swagger.sh`, `date -r
+  <file>` in `audit-log-rotate.sh` (which also rotates atomically now).
+- **Glob translation** in `triage-memory.mjs` / `test-gap-scan.mjs`: `**` no
+  longer breaks after the `*` pass (nested-path filters match again).
+- **`migrate-prefs.mjs`** errors on unknown flags (a `--dry-rnu` typo used to
+  perform a real write) and reports the correct target version.
+- Minor hardening: `write-state.mjs` lock release on early exits,
+  `post-pr-review.sh` / `plan-todos.sh` null-safe jq, `account-resolver.sh`
+  JSON escaping, `scan-skills.sh --json` spurious empty finding removed.
+
+### Performance
+
+- **Install: ~94s -> ~6s.** `scan-skills.sh` rewritten from per-file grep loops
+  to combined single-pass scans (identical findings output, verified by diff);
+  `countFiles` no longer shells out to `find | wc -l`.
+
+### Added - gates and tooling
+
+- **OIDC trusted publishing.** `release.yml` publishes tokenless (no more
+  `NPM_TOKEN`); one-time npmjs.com trusted-publisher setup required before the
+  next release (see workflow header). Release gates now also run the layout
+  smoke, the install leak audit, and the new pack-contents smoke.
+- **New smokes**: `smoke-plugin-validate.sh` (`claude plugin validate --strict`),
+  `smoke-workflow-audit.sh` (zizmor + actionlint, offline, skip-if-missing),
+  `smoke-pack-contents.sh` (packed-payload deny-list derived from package.json
+  negations at runtime + file-count band), `smoke-fetchers-offline.sh`
+  (44 offline assertions covering every fetcher's parse/credential/network
+  stages - the class of hole that let fetch-confluence ship dead).
+- **`check-md-links.mjs` now covers `pipeline/**`** (700+ skill/command files,
+  `$HOME/.claude/multi-agent-refs/` links validated against the repo source).
+- **`lint-skills.mjs` spec-conformance warnings** (agent-skills name pattern,
+  routing-clause descriptions, body size budget).
+- **Coverage floor**: c8 `--check-coverage` at the measured baseline (lines 80).
+- **DevEx**: `test:quick` script, `index.js --version`, unknown commands list
+  valid ones, smoke-runner env knobs documented in CONTRIBUTING, `cache: npm` +
+  strict `npm ci` in all workflows.
+- **Real-module tests**: `test/index.test.mjs` suites now import the actual
+  install helpers instead of inlined copies (the dead hook shipped because the
+  copy-based tests could not fail); new temp-HOME integration tests for the full
+  install -> update -> uninstall lifecycle and the JS gate scripts. Unit tests
+  145 -> 197.
+
+### Docs
+
+- ROADMAP moved to the 11.x line, SECURITY.md supported-versions table updated
+  (11.x active), README Scorecard badge, dead `files[]` negations removed,
+  internal working notes moved to `docs/internal/`.
+
+## [11.4.0] - 2026-07-10
+
+Review PR-picker, two readiness-review commands, and durable local-only wrappers.
+
+- **`/multi-agent:review` no-URL PR picker.** With no argument (interactive), review
+  now lists open GitHub + Bitbucket PRs in one labeled list and multi-selects which
+  to review (per-PR inline comments + approve/needs-work), instead of silently
+  defaulting to the local branch diff. Autopilot / no open PRs falls back to the
+  local diff; explicit URL/`#N`/branch still work. The Copilot twin was brought to
+  parity (input-aware + PR posting).
+- **New `/multi-agent:review-jira` + `/multi-agent:review-issue`.** Grade whether a
+  Jira issue / GitHub issue is ready for the pipeline (scope, acceptance criteria,
+  repro, design reference, API contract, stack signal, dependencies) by reusing the
+  Phase 0 maturity engine (`issue-fetcher.sh`) plus a readiness rubric, then post
+  the gaps back as a comment on the item (confirmed; autopilot auto-posts). Read-only
+  on code: no worktree, no branch, no creation. Command count 36 -> 38.
+- **Corporate alias wrappers survive updates.** `install/claude.mjs` now preserves
+  command dirs whose SKILL.md is `local-only: true` across the namespace wipe, so
+  personal `multi-agent:<name>` aliases that delegate to a private marketplace plugin
+  are no longer destroyed on every install/update (they were, before). Covered by a
+  new `smoke-wrapper-preservation.sh`. (The wrappers themselves are local-only and
+  never ship in this package.)
+
 ## [11.3.2] - 2026-07-10
 
 Command rename + website refresh.

package/README.md

@@ -4,6 +4,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js](https://img.shields.io/badge/Node.js-18%20%7C%2020%20%7C%2022-green)](https://nodejs.org)
 [![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://github.com/mmerterden/multi-agent-pipeline/blob/main/package.json)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/mmerterden/multi-agent-pipeline/badge)](https://scorecard.dev/viewer/?uri=github.com/mmerterden/multi-agent-pipeline)
 
 An 8-phase AI development pipeline for **Claude Code** and **Copilot CLI**. Drives a Jira issue or GitHub URL to a merged PR in one command — analysis → plan → TDD → review → test → commit → PR — with multi-repo orchestration, a plan-approval gate, CLI-aware parallel review, and store-compliance checks. Component and Figma-to-code work is dispatched to the per-stack marketplace plugins (iOS/SwiftUI, Android/Compose) rather than bundled, so component skills live in one place.
 

package/index.js

@@ -12,6 +12,7 @@
 import { pathToFileURL } from "url";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
+import { readFileSync } from "fs";
 
 /** @type {string} */
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -29,7 +30,10 @@ if (noColor) {
   process.env.NO_COLOR = "1";
 }
 
-if (!command || command === "install") {
+if (command === "--version" || command === "-v" || command === "version") {
+  const pkg = JSON.parse(readFileSync(join(__dirname, "package.json"), "utf-8"));
+  console.log(pkg.version);
+} else if (!command || command === "install") {
   await import(pathToFileURL(join(__dirname, "install.js")).href);
 } else if (command === "uninstall" || command === "delete") {
   await import(pathToFileURL(join(__dirname, "pipeline", "scripts", "uninstall.mjs")).href);
@@ -52,6 +56,7 @@ if (!command || command === "install") {
 
   Help:
     npx @mmerterden/multi-agent-pipeline help
+    npx @mmerterden/multi-agent-pipeline --version    Print the installed version
 
   Options:
     --no-color           Disable colored output
@@ -65,6 +70,8 @@ if (!command || command === "install") {
   More info: https://github.com/mmerterden/multi-agent-pipeline
   `);
 } else {
-  console.error(`Unknown command: ${command}. Run with 'help' for usage.`);
+  console.error(`Unknown command: ${command}`);
+  console.error("Valid commands: install, uninstall, delete, help, version (--version/-v)");
+  console.error("Run with 'help' for usage.");
   process.exit(1);
 }

package/install/_common.mjs

@@ -16,12 +16,12 @@ import {
   mkdirSync,
   readdirSync,
   rmSync,
+  statSync,
   symlinkSync,
   unlinkSync,
   writeFileSync,
 } from "fs";
 import { dirname } from "path";
-import { execSync } from "child_process";
 import { join } from "path";
 
 let dryRun = false;
@@ -51,6 +51,85 @@ export function ensureDir(dir) {
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
 }
 
+/**
+ * Replace a symlinked path with a real (empty) directory before installing
+ * into it. After a `--link` install, an owned dir (or a shared parent like
+ * `~/.claude/commands`) can be a symlink into the developer's repo checkout;
+ * wiping or copying through it would land inside the repo and destroy the
+ * pipeline sources. Non-symlink paths are left untouched.
+ *
+ * @param {string} dir
+ * @returns {boolean} true when a symlink was replaced
+ */
+export function ensureRealDir(dir) {
+  let st;
+  try {
+    st = lstatSync(dir);
+  } catch {
+    return false;
+  }
+  if (!st.isSymbolicLink()) return false;
+  if (dryRun) {
+    console.log(`    [dry-run] would replace symlink ${dir} with a real directory`);
+    return true;
+  }
+  unlinkSync(dir);
+  mkdirSync(dir, { recursive: true });
+  console.log(`    -> replaced symlink ${dir} with a real directory (was --link mode)`);
+  return true;
+}
+
+/**
+ * File names of the agent definitions the pipeline ships, derived from the
+ * source tree so the list can never go stale. Includes legacy names shipped
+ * by older releases so their stale installed copies are still cleaned up.
+ *
+ * @param {string} agentsSrc - pipeline/agents source directory
+ * @returns {Set<string>}
+ */
+export function pipelineAgentFileNames(agentsSrc) {
+  const names = new Set();
+  if (existsSync(agentsSrc)) {
+    for (const entry of readdirSync(agentsSrc, { withFileTypes: true })) {
+      if (entry.isFile()) names.add(entry.name);
+    }
+  }
+  // Legacy agent file names from older releases go here when an agent is
+  // renamed or removed upstream (currently none beyond the shipped set).
+  return names;
+}
+
+/**
+ * Remove ONLY pipeline-owned agent files from an installed agents dir.
+ * The dir also holds user-authored agent definitions, so it must never be
+ * wiped wholesale (that destroyed user files pre-v11.4.1).
+ *
+ * @param {string} destDir - installed agents dir (~/.claude/agents etc.)
+ * @param {string} agentsSrc - pipeline/agents source directory
+ * @returns {number} count of files removed
+ */
+export function removePipelineAgentFiles(destDir, agentsSrc) {
+  if (!existsSync(destDir)) return 0;
+  const owned = pipelineAgentFileNames(agentsSrc);
+  let removed = 0;
+  for (const entry of readdirSync(destDir, { withFileTypes: true })) {
+    if (!entry.isFile()) continue;
+    if (!owned.has(entry.name)) continue;
+    if (dryRun) {
+      console.log(`    [dry-run] would remove ${join(destDir, entry.name)}`);
+      removed++;
+      continue;
+    }
+    try {
+      rmSync(join(destDir, entry.name), { force: true });
+      removed++;
+    } catch {
+      /* non-fatal */
+    }
+  }
+  return removed;
+}
+
 /**
  * Recursively copy a directory (or symlink it in `--link` mode).
  *
@@ -85,7 +164,13 @@ export function copyDir(src, dest, opts = {}) {
     recursive: true,
     force: true,
     filter: (source) => {
-      const rel = source.slice(src.length).replace(/^\//, "");
+      // Normalize to forward slashes so exclude patterns (written posix-style)
+      // also match on win32, where cpSync hands back backslash paths.
+      const rel = source
+        .slice(src.length)
+        .split("\\")
+        .join("/")
+        .replace(/^\//, "");
       return !exclude.some((pat) =>
         typeof pat === "string"
           ? rel === pat || rel.startsWith(pat + "/")
@@ -187,17 +272,34 @@ export function writeFile(path, content) {
 }
 
 /**
- * Count files in a directory tree.
+ * Count files in a directory tree (pure fs recursion - works on win32 where
+ * `find` is unavailable, and avoids a subprocess per call). A plain-file path
+ * counts as 1, matching the old `find <path> -type f` behavior relied on by
+ * the DEV_ONLY_SCRIPTS exclusion accounting.
  * @param {string} dir
  * @returns {number}
  */
 export function countFiles(dir) {
+  let st;
+  try {
+    st = statSync(dir);
+  } catch {
+    return 0;
+  }
+  if (st.isFile()) return 1;
+  if (!st.isDirectory()) return 0;
+  let count = 0;
+  let entries;
   try {
-    const out = execSync(`find "${dir}" -type f | wc -l`, { encoding: "utf-8" });
-    return parseInt(out.trim(), 10);
+    entries = readdirSync(dir, { withFileTypes: true });
   } catch {
     return 0;
   }
+  for (const entry of entries) {
+    if (entry.isDirectory()) count += countFiles(join(dir, entry.name));
+    else if (entry.isFile()) count++;
+  }
+  return count;
 }
 
 /**

package/install/_telemetry.mjs

@@ -4,29 +4,17 @@
  * Set `MULTI_AGENT_TELEMETRY=1` to enable. Nothing is sent otherwise.
  * Fire-and-forget; never throws and never delays the install.
  *
+ * The payload is genuinely anonymous: package name, version, install
+ * method, flags, platform/arch, and Node version. No usernames, emails,
+ * hostnames, or other machine/user identifiers are collected.
+ *
  * @module install/_telemetry
  */
 
-import { execSync } from "child_process";
 import { readFileSync } from "fs";
-import { hostname, platform, arch } from "os";
+import { platform, arch } from "os";
 import { join } from "path";
 
-/**
- * Run a shell command silently and return its trimmed stdout, or undefined on error.
- * @param {string} cmd
- * @returns {string|undefined}
- */
-function safe(cmd) {
-  try {
-    return execSync(cmd, { stdio: ["ignore", "pipe", "ignore"], timeout: 3000 })
-      .toString()
-      .trim();
-  } catch {
-    return undefined;
-  }
-}
-
 /**
  * @param {{ packageRoot: string, flags: string[] }} ctx
  * @returns {Promise<void>}
@@ -40,9 +28,6 @@ export async function sendInstallTelemetry(ctx) {
   else if (process.env.npm_config_global === "true") method = "global";
   else if (process.env.npm_lifecycle_event === "install") method = "npm-install";
 
-  const githubUser = safe("gh api user --jq .login");
-  const gitEmail = safe("git config user.email");
-
   let version = "unknown";
   try {
     const pkg = JSON.parse(readFileSync(join(ctx.packageRoot, "package.json"), "utf-8"));
@@ -56,9 +41,6 @@ export async function sendInstallTelemetry(ctx) {
     version,
     method,
     flags: ctx.flags.filter((f) => f.startsWith("--")),
-    githubUser,
-    gitEmail,
-    hostname: hostname(),
     platform: `${platform()} ${arch()}`,
     nodeVersion: process.version,
   };

package/install/claude.mjs

@@ -5,14 +5,16 @@
  * `CLAUDE.md` template, preferences template, and the secret-detection
  * pre-commit hook in `settings.json`.
  *
- * Behaviour MUST stay byte-equivalent to the pre-v8.0.0 monolithic install
- * path — install layout smoke (`smoke-install-layout.sh`) compares before/after
- * trees on every release.
+ * 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.)
  *
  * @module install/claude
  */
 
-import { existsSync, readFileSync, rmSync } from "fs";
+import { existsSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "fs";
 import { join } from "path";
 import { execSync } from "child_process";
 
@@ -21,14 +23,23 @@ import {
   copyFile,
   countFiles,
   ensureDir,
+  ensureRealDir,
   isDryRun,
   pruneLegacyMultiAgentSkills,
+  removePipelineAgentFiles,
   wipeDir,
   writeFile,
 } from "./_common.mjs";
 import { copyExternalSkillsFiltered } from "./_platform-filter.mjs";
 import { DEV_ONLY_SCRIPTS } from "./_dev-only-files.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.
+ */
+export const LEGACY_PRE_COMMIT_MATCHER = "Bash(git commit:*)";
+
 /**
  * @param {{
  *   home: string,
@@ -72,14 +83,73 @@ function installCommands(pipelineSrc, dest, useSymlinks) {
   const commandsSrc = join(pipelineSrc, "commands");
   if (!existsSync(commandsSrc)) return;
 
+  const ownedCmdDir = join(dest, "multi-agent");
+
+  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;
+  }
+
+  // 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.
-  const ownedCmdDir = join(dest, "multi-agent");
+  //
+  // 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 snapshot+restore they would be destroyed on
+  // every install/update. Pipeline never ships these names, so restore is safe.
+  const preservedWrappers = snapshotLocalOnlyWrappers(ownedCmdDir);
   wipeDir(ownedCmdDir);
 
   copyDir(commandsSrc, dest, { useSymlinks });
+  const restored = restoreLocalOnlyWrappers(ownedCmdDir, preservedWrappers);
   console.log(`    -> ${countFiles(commandsSrc)} files copied to ${dest}`);
+  if (restored > 0) {
+    console.log(`    -> preserved ${restored} local-only alias wrapper(s)`);
+  }
+}
+
+// Snapshot single-level command dirs whose SKILL.md declares `local-only: true`
+// (their files are read into memory) so installCommands can restore them after
+// the namespace wipe.
+function snapshotLocalOnlyWrappers(ownedCmdDir) {
+  const out = [];
+  if (!existsSync(ownedCmdDir)) return out;
+  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;
+    const files = readdirSync(dir)
+      .filter((f) => statSync(join(dir, f)).isFile())
+      .map((f) => ({ rel: f, content: readFileSync(join(dir, f), "utf-8") }));
+    out.push({ name, files });
+  }
+  return out;
+}
+
+// Restore snapshotted local-only wrappers, but never clobber a real command the
+// pipeline just installed under the same name. Returns the count restored.
+function restoreLocalOnlyWrappers(ownedCmdDir, preserved) {
+  let n = 0;
+  for (const w of preserved) {
+    const dir = join(ownedCmdDir, w.name);
+    if (existsSync(dir)) continue; // pipeline shipped a real command with this name
+    ensureDir(dir);
+    for (const f of w.files) writeFileSync(join(dir, f.rel), f.content);
+    n++;
+  }
+  return n;
 }
 
 // The pipeline's reference docs (refs/) + internal pickers live OUTSIDE the
@@ -91,6 +161,7 @@ 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}`);
@@ -103,6 +174,7 @@ function installScripts(pipelineSrc, dest, useSymlinks) {
 
   // 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, not the array length: DEV_ONLY_SCRIPTS mixes
@@ -119,7 +191,13 @@ function installAgents(pipelineSrc, dest, useSymlinks) {
   console.log("  [Claude Code] Installing agent definitions...");
   const agentsSrc = join(pipelineSrc, "agents");
   if (!existsSync(agentsSrc)) return;
-  wipeDir(dest);
+  // ~/.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.
+  if (!useSymlinks) {
+    ensureRealDir(dest);
+    removePipelineAgentFiles(dest, agentsSrc);
+  }
   copyDir(agentsSrc, dest, { useSymlinks });
   console.log(`    -> ${countFiles(agentsSrc)} files copied to ${dest}`);
 }
@@ -137,6 +215,7 @@ function installRules(pipelineSrc, dest, useSymlinks) {
   if (useSymlinks) {
     copyDir(rulesSrc, dest, { useSymlinks });
   } else {
+    ensureRealDir(dest);
     copyDir(rulesSrc, dest, { skipExisting: true });
   }
   console.log(`    -> rules present (existing local rules preserved)`);
@@ -148,6 +227,7 @@ function installSchemas(pipelineSrc, dest, useSymlinks) {
   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}`);
@@ -158,6 +238,7 @@ function installLib(pipelineSrc, dest, useSymlinks) {
   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}`);
@@ -207,6 +288,10 @@ function installSkills(opts) {
   const { pipelineSrc, dest, indexOnly, useSymlinks, platformFlag } = 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);
+
   if (indexOnly) {
     ensureDir(dest);
     const indexJson = join(pipelineSrc, "skills", ".skills-index.json");
@@ -312,7 +397,7 @@ function ensurePreferences(prefsPath, pipelineSrc) {
   }
 }
 
-function configureSettings(home) {
+export function configureSettings(home) {
   console.log("  [Claude Code] Configuring hooks + context management...");
   const SETTINGS_PATH = join(home, ".claude", "settings.json");
   try {
@@ -330,12 +415,29 @@ function configureSettings(home) {
 
     if (!settings.hooks) settings.hooks = {};
     if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = [];
-    const hasPreCommitHook = settings.hooks.PreToolUse.some(
-      (h) => h.matcher === "Bash(git commit:*)",
-    );
+    // 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.
+    // Command-level filtering (only scan on actual `git commit`) happens
+    // inside pre-commit-check.sh via the hook's stdin JSON.
+    const isPreCommitEntry = (h) =>
+      Array.isArray(h.hooks) &&
+      h.hooks.some(
+        (sub) => typeof sub.command === "string" && sub.command.includes("pre-commit-check.sh"),
+      );
+    let hasPreCommitHook = false;
+    for (const h of settings.hooks.PreToolUse) {
+      if (!isPreCommitEntry(h)) continue;
+      if (h.matcher === LEGACY_PRE_COMMIT_MATCHER) {
+        h.matcher = "Bash";
+        settingsChanged = true;
+      }
+      if (h.matcher === "Bash") hasPreCommitHook = true;
+    }
     if (!hasPreCommitHook) {
       settings.hooks.PreToolUse.push({
-        matcher: "Bash(git commit:*)",
+        matcher: "Bash",
         hooks: [
           {
             type: "command",