@mmerterden/multi-agent-pipeline 11.4.0 → 12.0.0

package/CHANGELOG.md

@@ -14,6 +14,178 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ---
 
+## [12.0.0] - 2026-07-20
+
+Command rename (breaking), a full-cleanup uninstall mode, outputLanguage-aware
+picker descriptions, worktree residue cleanup, and cleanup-command hardening.
+
+### Breaking
+
+- **`/multi-agent:delete` renamed to `/multi-agent:uninstall`.** The old name is
+  gone (no alias). The Copilot twin is now `multi-agent-uninstall`. Command
+  count stays 38; the canonical inventory, sync list, help, and cross-cli
+  contract were updated. Per the versioning policy a renamed command forces a
+  major bump.
+
+### Added
+
+- **`uninstall --all-data` full-cleanup mode.** Standard uninstall still keeps
+  settings + logs; `--all-data` additionally removes
+  `multi-agent-preferences.json` and the entire `~/.claude/logs/multi-agent/`
+  tree (task logs, state, metrics, audit). Tokens, `CLAUDE.md`, and the
+  user-owned `rules/` are preserved in both modes. The slash command asks a
+  scope picker (Standard vs Full cleanup) before the double confirmation.
+- **outputLanguage-aware slash-command descriptions.** Every command ships an
+  English `description` plus a `description-tr`; when `outputLanguage=tr`, the
+  installer and the `/multi-agent:language` toggle swap the installed
+  `~/.claude` descriptions to Turkish (reversible via a `description-en`
+  sidecar). Repo and npm files stay English; `/multi-agent:sync` normalizes and
+  gates the round trip so localized text can never leak back into the repo.
+  New `localize-commands.mjs` + `smoke-description-tr.sh`.
+- **`/multi-agent:garbage-collect` worktree phase.** New `gc-worktrees.sh`
+  (dry-run by default) prunes stale worktree admin entries, removes orphan
+  `.worktrees/*` dirs no longer registered as worktrees, unstages gitlink
+  ("Subproject commit") residue from a pre-guard `git add -A`, and ensures the
+  `.worktrees/` `info/exclude` guard. Registered worktrees are never touched.
+- **Worktree residue guard on creation.** Phase 0 (single- and multi-repo) and
+  the Copilot core skill now append `.worktrees/` to the clone-local
+  `.git/info/exclude` before every `worktree add`, so a blanket `git add -A`
+  can no longer record `.worktrees/{id}` gitlinks into shared branches.
+- **update-check reaches npx-only installs.** The installer stamps
+  `~/.claude/.pipeline-version` (and the Copilot equivalent); `update-check.sh`
+  falls back to it when no repo clone is present, so users who never cloned the
+  repo still see the "update available" prompt. Uninstall removes the marker.
+
+### Changed / hardened
+
+- **`/multi-agent:purge` now runs a real backend** (`purge.sh`): dry-run by
+  default, every `rm` target resolved strictly inside `<repo>/.worktrees/`,
+  refuses `/`, `$HOME`, and the project root; main worktree and
+  main/master/develop always preserved. `--delete-remote` gates remote-branch
+  deletion behind `--yes`.
+- **`prune-logs.sh` / `gc-tmp.sh` hardened**: safe id/path validation, the
+  audit trail + metrics corpus never removed, containment guards on deletion
+  roots. New/expanded smokes: `smoke-purge.sh`, plus prune-logs and gc-tmp
+  coverage.
+
+## [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.

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/docs/adr/0007-multi-tool-adapter-framework.md

@@ -64,7 +64,7 @@ Each adapter exports a `{ name, install, uninstall }` contract. New adapters are
 
 ### Token-preserving uninstall
 
-Every install path has a documented opposite via `npx @mmerterden/multi-agent-pipeline uninstall` (or `delete` alias). Slash command: `/multi-agent:delete` with a Copilot CLI peer `multi-agent-delete`.
+Every install path has a documented opposite via `npx @mmerterden/multi-agent-pipeline uninstall`. Slash command: `/multi-agent:uninstall` (renamed from `:delete` in v12.0.0) with a Copilot CLI peer `multi-agent-uninstall`. A `--all-data` flag extends it to also clear pipeline settings and the log root; tokens are never touched.
 
 The uninstaller is **contractually forbidden** from touching:
 
@@ -94,7 +94,7 @@ Positive:
 Negative / costs:
 
 - 6 adapters means 6 places where the format mapping can drift from upstream tool changes. Mitigation: round-trip smoke tests for each adapter exercise install + uninstall on every PR.
-- `--all-tools` writes ~900 files (174 cursor + ~50 windsurf concat + 173 cline + 161 copilot-chat + 161 continue + 1 zed) into the user's repo. Acceptable — `.gitignore` patterns already cover most of these (`.cursor/`, `.continue/`, `.clinerules/`), and `:delete` cleans them all in one step.
+- `--all-tools` writes ~900 files (174 cursor + ~50 windsurf concat + 173 cline + 161 copilot-chat + 161 continue + 1 zed) into the user's repo. Acceptable: `.gitignore` patterns already cover most of these (`.cursor/`, `.continue/`, `.clinerules/`), and `:uninstall` cleans them all in one step.
 - Per-tool format drift across tool versions (e.g. Cursor's `.mdc` format changes in 2027) requires per-adapter maintenance. Insulated from the orchestrator: bumping a Tier 2/3 tool format never touches Phase 1-7 logic.
 
 ## Alternatives Considered

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,30 +5,43 @@
  * `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, readdirSync, rmSync, statSync, writeFileSync } from "fs";
-import { join } from "path";
+import { join, dirname } from "path";
 import { execSync } from "child_process";
 
+import { localizeCommands } from "../pipeline/scripts/localize-commands.mjs";
+
 import {
   copyDir,
   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,10 +85,27 @@ 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
@@ -89,6 +119,28 @@ function installCommands(pipelineSrc, dest, useSymlinks) {
   if (restored > 0) {
     console.log(`    -> preserved ${restored} local-only alias wrapper(s)`);
   }
+  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) {
+  if (isDryRun()) return;
+  try {
+    const home = dirname(dirname(ownedCmdDir));
+    const prefsPath = join(home, "multi-agent-preferences.json");
+    if (!existsSync(prefsPath)) return;
+    const prefs = JSON.parse(readFileSync(prefsPath, "utf-8"));
+    if (prefs?.global?.outputLanguage !== "tr") return;
+    const changed = localizeCommands(ownedCmdDir, "apply");
+    if (changed > 0) {
+      console.log(`    -> localized ${changed} command description(s) to outputLanguage=tr`);
+    }
+  } catch {
+    // advisory only - installed tree simply stays English
+  }
 }
 
 // Snapshot single-level command dirs whose SKILL.md declares `local-only: true`
@@ -133,6 +185,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}`);
@@ -145,6 +198,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
@@ -161,7 +215,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}`);
 }
@@ -179,6 +239,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)`);
@@ -190,6 +251,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}`);
@@ -200,6 +262,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}`);
@@ -249,6 +312,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");
@@ -354,7 +421,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 {
@@ -372,12 +439,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",