@mmerterden/multi-agent-pipeline 11.4.0 → 12.0.0

package/pipeline/scripts/gc-tmp.sh

@@ -6,8 +6,15 @@
 # never cleaned up automatically (review.md traps its own, the rest linger), so
 # a long-lived machine accumulates them. This sweeps the known prefixes.
 #
-# SAFE BY DEFAULT: dry-run. It lists what WOULD be removed and the space it
-# would free, and deletes nothing until you pass --yes.
+# SAFE BY DEFAULT:
+#   - dry-run: lists what WOULD be removed and the space it would free, and
+#     deletes nothing until you pass --yes.
+#   - root guard: the scratch root must be an existing directory and is
+#     refused when it resolves to /, $HOME, or a git work tree, so a stray
+#     GC_TMP_ROOT can never sweep a home dir or a repo checkout.
+#   - fresh-scratch grace: items touched in the last GC_TMP_GRACE_MIN minutes
+#     (default 10) are spared, so a sweep during an in-flight run cannot pull
+#     scratch out from under it. GC_TMP_GRACE_MIN=0 disables the grace.
 #
 # Usage:
 #   gc-tmp.sh                      # dry-run: list matches + total size
@@ -16,13 +23,16 @@
 #   gc-tmp.sh --older-than=60 --yes
 #
 # Env:
-#   GC_TMP_ROOT   override the scratch root (default /tmp; tests set this)
+#   GC_TMP_ROOT       override the scratch root (default /tmp; tests set this)
+#   GC_TMP_GRACE_MIN  fresh-scratch grace window in minutes (default 10, 0 = off)
 #
-# Exit: 0 on success, 2 on usage error. Always exits 0 when nothing matches.
+# Exit: 0 on success, 2 on usage error or refused scratch root. Always exits 0
+# when nothing matches.
 
 set -uo pipefail
 
 ROOT="${GC_TMP_ROOT:-/tmp}"
+GRACE_MIN="${GC_TMP_GRACE_MIN:-10}"
 DELETE=0
 OLDER_MIN=0
 
@@ -51,9 +61,35 @@ for arg in "$@"; do
   esac
 done
 
+if ! printf '%s' "$GRACE_MIN" | grep -qE '^[0-9]+$'; then
+  echo "gc-tmp: GC_TMP_GRACE_MIN needs a whole number of minutes, got: $GRACE_MIN" >&2
+  exit 2
+fi
+
+if [ ! -d "$ROOT" ]; then
+  echo "gc-tmp: no scratch root at $ROOT  -  nothing to do"
+  exit 0
+fi
+
+# Root guard: resolve symlinks (macOS /tmp -> /private/tmp), then refuse
+# roots that can never be a scratch root. Sweeping $HOME by mistake would
+# match real dirs like ~/multi-agent-pipeline via the name prefixes below.
+ROOT="$(cd "$ROOT" 2>/dev/null && pwd -P)"
+if [ -z "$ROOT" ]; then
+  echo "gc-tmp: cannot resolve scratch root" >&2
+  exit 2
+fi
+HOME_REAL="$(cd "$HOME" 2>/dev/null && pwd -P || printf '%s' "$HOME")"
+if [ "$ROOT" = "/" ] || [ "$ROOT" = "$HOME_REAL" ] || [ -e "$ROOT/.git" ]; then
+  echo "gc-tmp: refusing scratch root $ROOT (/, \$HOME, or a git work tree is never a scratch root)" >&2
+  exit 2
+fi
+
 # Scratch prefixes the pipeline writes under $ROOT (see jira.md, review.md,
 # update-issue-progress.sh, channels/*.md, external-context-injection.md,
-# analysis.md). maxdepth 1 so we never descend into unrelated trees.
+# analysis.md). mindepth 1 so the root itself is never a candidate even when
+# its own name matches a prefix; maxdepth 1 so we never descend into
+# unrelated trees.
 NAME_ARGS=(
   -name 'multi-agent-*'
   -o -name 'issue-progress-*'
@@ -69,12 +105,24 @@ if [ "$OLDER_MIN" -gt 0 ]; then
 fi
 
 matches=()
+skipped_active=0
 while IFS= read -r -d '' p; do
+  # Fresh-scratch grace: spare items an in-flight run touched recently
+  # (checks the item and, for dirs, anything inside it).
+  if [ "$GRACE_MIN" -gt 0 ] &&
+    find "$p" -mmin "-$GRACE_MIN" -print 2>/dev/null | head -1 | grep -q .; then
+    skipped_active=$((skipped_active + 1))
+    continue
+  fi
   matches+=("$p")
-done < <(find "$ROOT" -maxdepth 1 \( "${NAME_ARGS[@]}" \) ${MTIME_ARGS[@]+"${MTIME_ARGS[@]}"} -print0 2>/dev/null)
+done < <(find "$ROOT" -mindepth 1 -maxdepth 1 \( "${NAME_ARGS[@]}" \) ${MTIME_ARGS[@]+"${MTIME_ARGS[@]}"} -print0 2>/dev/null)
 
 if [ "${#matches[@]}" -eq 0 ]; then
-  echo "gc-tmp: no leftover scratch under $ROOT  -  nothing to do"
+  if [ "$skipped_active" -gt 0 ]; then
+    echo "gc-tmp: only fresh scratch matched (touched in the last ${GRACE_MIN}m)  -  spared, nothing to do"
+  else
+    echo "gc-tmp: no leftover scratch under $ROOT  -  nothing to do"
+  fi
   exit 0
 fi
 
@@ -90,13 +138,24 @@ human="${total_kb} KB"
 if [ "$DELETE" -eq 0 ]; then
   echo "DRY-RUN  -  would remove ${#matches[@]} item(s) under $ROOT (frees ~${human}):"
   for p in "${matches[@]}"; do echo "  $p"; done
+  [ "$skipped_active" -gt 0 ] && echo "Spared $skipped_active fresh item(s) touched in the last ${GRACE_MIN}m."
   echo "Re-run with --yes to delete."
   exit 0
 fi
 
 removed=0
 for p in "${matches[@]}"; do
+  # Containment guard: only ever delete direct children of the resolved root.
+  case "$p" in
+    "$ROOT"/*) ;;
+    *)
+      echo "gc-tmp: skipping path outside scratch root: $p" >&2
+      continue
+      ;;
+  esac
   rm -rf "$p" 2>/dev/null && removed=$((removed + 1))
 done
-echo "══ garbage-collect: removed ${removed}/${#matches[@]} item(s), freed ~${human} ══"
+spared_note=""
+[ "$skipped_active" -gt 0 ] && spared_note=", spared $skipped_active fresh"
+echo "══ garbage-collect: removed ${removed}/${#matches[@]} item(s)${spared_note}, freed ~${human} ══"
 exit 0

package/pipeline/scripts/gc-worktrees.sh

@@ -0,0 +1,140 @@
+#!/usr/bin/env bash
+# gc-worktrees.sh  -  sweep worktree residue in the current project repo.
+#
+# Complements gc-tmp.sh (which only touches /tmp scratch). This handles the
+# leftovers a worktree lifecycle can strand inside the repo itself:
+#
+#   1. stale worktree admin entries   -> git worktree prune
+#   2. orphan .worktrees/* dirs       -> dirs no longer registered as
+#      worktrees (killed mid-run, manual deletes). Listed in dry-run,
+#      removed only with --yes.
+#   3. gitlink residue in the index   -> .worktrees/{id} recorded as a
+#      "Subproject commit" entry by a blanket `git add -A` before the
+#      residue guard existed. --yes runs `git rm --cached` (the commit
+#      itself stays yours to make).
+#   4. missing residue guard          -> ensures `.worktrees/` is in
+#      .git/info/exclude so the gitlink class cannot re-occur.
+#
+# Registered, healthy worktrees are NEVER touched - finishing or killing a
+# task is /multi-agent:finish / /multi-agent:kill territory.
+#
+# SAFE BY DEFAULT: dry-run. Deletes nothing until you pass --yes.
+#
+# Usage:
+#   gc-worktrees.sh                     # dry-run in the current repo
+#   gc-worktrees.sh --yes               # apply
+#   gc-worktrees.sh --repo <path>       # operate on another repo
+#   gc-worktrees.sh --older-than=60     # only orphan dirs idle > 60 min
+#
+# Exit: 0 on success (including "nothing to do"), 2 on usage error.
+
+set -uo pipefail
+
+REPO="$PWD"
+DELETE=0
+OLDER_MIN=0
+
+usage() {
+  grep -E '^#( |$)' "$0" | sed -E 's/^# ?//'
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --yes | --force) DELETE=1; shift ;;
+    --repo)
+      REPO="${2:-}"
+      [ -z "$REPO" ] && { echo "gc-worktrees: --repo needs a path" >&2; exit 2; }
+      shift 2
+      ;;
+    --older-than=*)
+      OLDER_MIN="${1#*=}"
+      if ! printf '%s' "$OLDER_MIN" | grep -qE '^[0-9]+$'; then
+        echo "gc-worktrees: --older-than needs a whole number of minutes, got: $OLDER_MIN" >&2
+        exit 2
+      fi
+      shift
+      ;;
+    -h | --help) usage; exit 0 ;;
+    *) echo "gc-worktrees: unknown argument: $1" >&2; exit 2 ;;
+  esac
+done
+
+if ! git -C "$REPO" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  echo "gc-worktrees: $REPO is not a git work tree  -  nothing to do"
+  exit 0
+fi
+REPO="$(cd "$REPO" && pwd -P)"
+WT_ROOT="$REPO/.worktrees"
+
+changed=0
+
+# 1. Stale admin entries (safe on a clean repo, no confirmation needed:
+#    prune only drops bookkeeping for dirs that are already gone).
+pruned=$(git -C "$REPO" worktree prune -v 2>&1 | grep -c . || true)
+[ "$pruned" -gt 0 ] && echo "→ pruned $pruned stale worktree admin entr$( [ "$pruned" -eq 1 ] && echo y || echo ies)"
+
+# 2. Orphan dirs: present under .worktrees/ but not registered as worktrees.
+orphans=()
+if [ -d "$WT_ROOT" ]; then
+  registered=$(git -C "$REPO" worktree list --porcelain 2>/dev/null | sed -n 's/^worktree //p')
+  for d in "$WT_ROOT"/*/; do
+    [ -d "$d" ] || continue
+    dir="$(cd "$d" && pwd -P)"
+    # Path guard: only ever consider dirs strictly inside <repo>/.worktrees/.
+    case "$dir" in "$WT_ROOT"/*) ;; *) continue ;; esac
+    if printf '%s\n' "$registered" | grep -qxF "$dir"; then
+      continue  # healthy registered worktree - kill/finish territory
+    fi
+    if [ "$OLDER_MIN" -gt 0 ] && find "$dir" -type f -mmin "-$OLDER_MIN" 2>/dev/null | head -1 | grep -q .; then
+      continue  # recently touched - spare it
+    fi
+    orphans+=("$dir")
+  done
+fi
+for dir in ${orphans+"${orphans[@]}"}; do
+  size=$(du -sh "$dir" 2>/dev/null | cut -f1)
+  if [ "$DELETE" -eq 1 ]; then
+    rm -rf "$dir" && { echo "→ removed orphan worktree dir: ${dir#"$REPO"/} (${size:-?})"; changed=$((changed + 1)); }
+  else
+    echo "would remove orphan worktree dir: ${dir#"$REPO"/} (${size:-?})"
+  fi
+done
+
+# 3. Gitlink residue in the index ("Subproject commit" entries under
+#    .worktrees/ from a pre-guard `git add -A`).
+gitlinks=$(git -C "$REPO" ls-files -s -- .worktrees 2>/dev/null | awk '$1 == "160000" { print $4 }')
+if [ -n "$gitlinks" ]; then
+  while IFS= read -r path; do
+    [ -z "$path" ] && continue
+    if [ "$DELETE" -eq 1 ]; then
+      git -C "$REPO" rm --cached --ignore-unmatch -q -- "$path" \
+        && { echo "→ unstaged gitlink residue: $path (commit the removal yourself)"; changed=$((changed + 1)); }
+    else
+      echo "would unstage gitlink residue from the index: $path"
+    fi
+  done <<EOF
+$gitlinks
+EOF
+fi
+
+# 4. Residue guard: keep .worktrees/ out of the index from now on.
+ex="$(git -C "$REPO" rev-parse --path-format=absolute --git-common-dir 2>/dev/null)/info/exclude"
+if [ -n "${ex%/info/exclude}" ] && ! grep -qxF '.worktrees/' "$ex" 2>/dev/null; then
+  if [ "$DELETE" -eq 1 ]; then
+    mkdir -p "$(dirname "$ex")" \
+      && printf '.worktrees/\n' >> "$ex" \
+      && { echo "→ added .worktrees/ to .git/info/exclude (residue guard)"; changed=$((changed + 1)); }
+  else
+    echo "would add .worktrees/ to .git/info/exclude (residue guard)"
+  fi
+fi
+
+total=$(( ${#orphans[@]} + $(printf '%s' "$gitlinks" | grep -c . || true) ))
+if [ "$DELETE" -eq 1 ]; then
+  echo "══ gc-worktrees: applied $changed change(s) in $REPO ══"
+elif [ "$total" -eq 0 ] && [ "$pruned" -eq 0 ] && { [ -z "${ex%/info/exclude}" ] || grep -qxF '.worktrees/' "$ex" 2>/dev/null; }; then
+  echo "gc-worktrees: no worktree residue in $REPO  -  nothing to do"
+else
+  echo "══ gc-worktrees: dry-run  -  re-run with --yes to apply ══"
+fi
+exit 0

package/pipeline/scripts/keychain-save.sh

@@ -17,11 +17,11 @@ fi
 echo "Ne tür bir secret kaydedeceksin?"
 echo "  1) Personal Access Token / API Key"
 echo "  2) JSON dosyası (service account vb.)"
-read -p "Seçim (1/2): " CHOICE
+read -rp "Seçim (1/2): " CHOICE
 
 case "$CHOICE" in
     1)
-        read -sp "Token'ı yapıştır (gizli yazılır): " SECRET
+        read -rsp "Token'ı yapıştır (gizli yazılır): " SECRET
         echo ""
         if [ -z "$SECRET" ]; then
             echo "Hata: Token boş olamaz."
@@ -29,7 +29,7 @@ case "$CHOICE" in
         fi
         ;;
     2)
-        read -p "JSON dosya yolunu gir: " JSON_PATH
+        read -rp "JSON dosya yolunu gir: " JSON_PATH
         # Kullanıcının girdiği tırnak işaretlerini temizle
         JSON_PATH="${JSON_PATH//\'/}"
         JSON_PATH="${JSON_PATH//\"/}"
@@ -53,20 +53,24 @@ case "$CHOICE" in
         ;;
 esac
 
-CRED="$HOME/.claude/lib/credential-store.sh"
+# Locate the credential helper via the resolver so Copilot-only installs work.
+# shellcheck disable=SC1090,SC1091
+. "$HOME/.claude/lib/credential-store-resolver.sh" 2>/dev/null \
+  || . "$HOME/.copilot/lib/credential-store-resolver.sh" 2>/dev/null \
+  || { echo "Hata: credential-store bulunamadi. Kurulum: npx @mmerterden/multi-agent-pipeline install"; exit 1; }
+CRED="$CRED_STORE"
 
 "$CRED" delete "$SERVICE_NAME" >/dev/null 2>&1 || true
-"$CRED" set "$SERVICE_NAME" "$SECRET"
-
-if [ $? -eq 0 ]; then
+# Secret goes through stdin ("set <key> -") so it never appears on argv.
+if printf '%s' "$SECRET" | "$CRED" set "$SERVICE_NAME" -; then
     echo "Kaydedildi: $SERVICE_NAME (platform: $("$CRED" platform))"
     echo ""
     echo "Okumak icin:"
-    echo "  ~/.claude/lib/credential-store.sh get \"$SERVICE_NAME\""
+    echo "  $CRED get \"$SERVICE_NAME\""
     if [ "$CHOICE" = "2" ]; then
         echo ""
         echo "JSON'a geri cevirmek icin:"
-        echo "  ~/.claude/lib/credential-store.sh get \"$SERVICE_NAME\" | base64 -d"
+        echo "  $CRED get \"$SERVICE_NAME\" | base64 -d"
     fi
 else
     echo "Hata: Kaydedilemedi."

package/pipeline/scripts/lint-skills.mjs

@@ -1,19 +1,27 @@
 #!/usr/bin/env node
 // Frontmatter linter for every SKILL.md shipped by the pipeline.
 //
-// Until v10.0.0 the 217 SKILL.md files were counted by smokes but never
+// Until v10.0.0 the shipped SKILL.md files were counted by smokes but never
 // content-checked, so a skill could ship without the frontmatter that
 // Claude Code / Copilot CLI need to register it. This gate enforces the
 // minimal contract; it is zero-dependency (line-based YAML subset) so it
 // runs inside `npm test` and ci-lite without installs.
 //
-// Contract per SKILL.md:
+// Contract per SKILL.md (errors - fail the gate):
 //   - frontmatter block present (--- ... ---) starting at line 1
 //   - name: required, lowercase kebab-case (underscores tolerated for
 //     legacy skills already published under a snake_case name)
 //   - description: required, non-empty, single line, <= 1024 chars
 //   - user-invocable: when present, must be true or false
 //   - platform: when present, must be ios | android | common | all
+//
+// Spec-conformance signals (warnings - never fail the gate):
+//   - name should match the agent-skills spec pattern
+//     (lowercase letters/digits/hyphens, <= 64 chars)
+//   - description should carry a routing/trigger clause ("use when ...")
+//     so the model can decide when to load the skill
+//   - a body over ~500 lines with no companion-file reference should be
+//     split into references/ files loaded on demand
 
 import { readFileSync } from "node:fs";
 import { execSync } from "node:child_process";
@@ -61,6 +69,16 @@ for (const file of files) {
     fail(file, "missing required field: name");
   } else if (!/^[a-z0-9]+([-_][a-z0-9]+)*$/.test(fields.name)) {
     fail(file, `name is not lowercase kebab/snake-case: "${fields.name}"`);
+  } else {
+    // Spec conformance (warn-only): the agent-skills spec allows lowercase
+    // letters, digits, and hyphens, max 64 chars. Snake_case passes the
+    // legacy error check above but is out of spec.
+    if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(fields.name)) {
+      warn(file, `name is outside the agent-skills spec pattern (hyphens only): "${fields.name}"`);
+    }
+    if (fields.name.length > 64) {
+      warn(file, `name exceeds the spec's 64-char limit (${fields.name.length})`);
+    }
   }
 
   if (!("description" in fields)) {
@@ -81,6 +99,26 @@ for (const file of files) {
     if (!isBlockScalar && words < 6) {
       warn(file, `description is terse (${words} words) - say what it does AND when to use it`);
     }
+    // Routing quality (warn-only): without a trigger clause the model has no
+    // signal for WHEN to load the skill. Heuristic phrase match; block
+    // scalars are skipped for the same parser reason as above.
+    const ROUTING_RE = /\b(use (this|it|when|for|whenever)|when (the|a|an|you|asked|working|building|implementing|writing|reviewing)|triggers?|invoked?( when| for)?|applies when|activated?)\b/i;
+    if (!isBlockScalar && !ROUTING_RE.test(desc)) {
+      warn(file, "description has no routing/trigger clause (e.g. \"use when ...\")");
+    }
+  }
+
+  // Body size (warn-only): the agent-skills guidance is to keep SKILL.md
+  // lean and push detail into companion files loaded on demand. A ~500+
+  // line body that references no companion file loads whole every time.
+  const body = raw.slice(end + 4);
+  const bodyLines = body.split("\n").length;
+  if (bodyLines > 500) {
+    const referencesCompanion =
+      /\]\((?!https?:|mailto:|#)[^)]+\)/.test(body) || /`[^`\n]*\/[^`\n]*\.(md|sh|mjs|json|py|txt)`/.test(body);
+    if (!referencesCompanion) {
+      warn(file, `body is ${bodyLines} lines with no companion-file reference - consider splitting into references/`);
+    }
   }
 
   if ("user-invocable" in fields && !["true", "false"].includes(fields["user-invocable"])) {

package/pipeline/scripts/localize-commands.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+/**
+ * localize-commands.mjs - swap slash-command picker descriptions between
+ * English and the outputLanguage variant in an INSTALLED command tree.
+ *
+ * The repo (and the npm package) always keeps English `description:` values;
+ * files that ship a `description-tr:` frontmatter line can be localized in
+ * place after install. The original English text is preserved in a
+ * `description-en:` sidecar line so the swap is fully reversible.
+ *
+ *   apply    description-en <- description, description <- description-tr
+ *   restore  description <- description-en, sidecar line removed
+ *
+ * Both modes are idempotent and only touch the three description* lines of
+ * the YAML frontmatter; every other byte is preserved. Files without a
+ * description-tr line are left untouched.
+ *
+ * Usage:
+ *   node localize-commands.mjs apply   [--dir <commandsDir>]
+ *   node localize-commands.mjs restore [--dir <commandsDir>]
+ *
+ * Default dir: $HOME/.claude/commands/multi-agent
+ * Exit: 0 on success (including missing dir), 2 on usage error.
+ */
+
+import { readFileSync, writeFileSync, readdirSync, existsSync, statSync } from "fs";
+import { join } from "path";
+
+const DESC = /^description:[ \t]*(.*)$/;
+const DESC_TR = /^description-tr:[ \t]*(.*)$/;
+const DESC_EN = /^description-en:[ \t]*(.*)$/;
+
+/**
+ * Swap the description of one SKILL.md. Returns true when the file changed.
+ *
+ * @param {string} file
+ * @param {"apply"|"restore"} mode
+ */
+export function localizeFile(file, mode) {
+  const original = readFileSync(file, "utf-8");
+  const lines = original.split("\n");
+  // Only operate inside the first frontmatter block.
+  if (lines[0] !== "---") return false;
+  const end = lines.indexOf("---", 1);
+  if (end < 0) return false;
+
+  let descIdx = -1;
+  let trIdx = -1;
+  let enIdx = -1;
+  for (let i = 1; i < end; i++) {
+    if (descIdx < 0 && DESC.test(lines[i])) descIdx = i;
+    else if (trIdx < 0 && DESC_TR.test(lines[i])) trIdx = i;
+    else if (enIdx < 0 && DESC_EN.test(lines[i])) enIdx = i;
+  }
+  if (descIdx < 0) return false;
+
+  if (mode === "apply") {
+    if (trIdx < 0) return false;
+    const trValue = lines[trIdx].match(DESC_TR)[1];
+    const current = lines[descIdx].match(DESC)[1];
+    if (current === trValue) return false; // already applied
+    if (enIdx < 0) {
+      // Preserve the English original right after the description line.
+      lines.splice(descIdx + 1, 0, `description-en: ${current}`);
+    }
+    lines[descIdx] = `description: ${trValue}`;
+  } else {
+    if (enIdx < 0) return false;
+    const enValue = lines[enIdx].match(DESC_EN)[1];
+    lines[descIdx] = `description: ${enValue}`;
+    lines.splice(enIdx, 1);
+  }
+  const next = lines.join("\n");
+  if (next === original) return false;
+  writeFileSync(file, next);
+  return true;
+}
+
+/**
+ * Localize every SKILL.md directly in `dir` and one level below it.
+ *
+ * @param {string} dir
+ * @param {"apply"|"restore"} mode
+ * @returns {number} count of changed files
+ */
+export function localizeCommands(dir, mode) {
+  if (!existsSync(dir)) return 0;
+  const files = [];
+  const rootSkill = join(dir, "SKILL.md");
+  if (existsSync(rootSkill)) files.push(rootSkill);
+  for (const entry of readdirSync(dir)) {
+    const sub = join(dir, entry, "SKILL.md");
+    try {
+      if (statSync(join(dir, entry)).isDirectory() && existsSync(sub)) files.push(sub);
+    } catch {
+      // unreadable entry - skip
+    }
+  }
+  let changed = 0;
+  for (const f of files) {
+    try {
+      if (localizeFile(f, mode)) changed++;
+    } catch {
+      // never fail the whole run over one file
+    }
+  }
+  return changed;
+}
+
+const invokedDirectly =
+  process.argv[1] && import.meta.url.endsWith(process.argv[1].split("/").pop());
+if (invokedDirectly) {
+  const args = process.argv.slice(2);
+  const mode = args[0];
+  if (mode !== "apply" && mode !== "restore") {
+    console.error("usage: localize-commands.mjs <apply|restore> [--dir <commandsDir>]");
+    process.exit(2);
+  }
+  let dir = join(process.env.HOME || process.env.USERPROFILE || "", ".claude", "commands", "multi-agent");
+  const dirFlag = args.indexOf("--dir");
+  if (dirFlag >= 0) {
+    if (!args[dirFlag + 1]) {
+      console.error("localize-commands: --dir needs a path");
+      process.exit(2);
+    }
+    dir = args[dirFlag + 1];
+  }
+  const changed = localizeCommands(dir, mode);
+  console.log(`localize-commands: ${mode} -> ${changed} file(s) changed in ${dir}`);
+}

package/pipeline/scripts/migrate-prefs.mjs

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
-// migrate-prefs.mjs  -  migrates multi-agent-preferences.json v2.0.0 → v2.1.0
+// migrate-prefs.mjs  -  migrates multi-agent-preferences.json to the current
+// target schema (see TARGET_VERSION below).
 //
 // Usage:
 //   node migrate-prefs.mjs [--dry-run] [--file <path>]
 //
-// - Idempotent: safe to run multiple times. v2.1.0 files pass through unchanged.
+// - Idempotent: safe to run multiple times. Target-version files pass through unchanged.
 // - Atomic: writes to a .tmp file and rename()s. No partial writes.
 // - Non-destructive: renames gitIdentities → identities, preserves everything else.
 // - Fills defaults for new v2.1.0 fields.
@@ -15,15 +16,33 @@ import os from "node:os";
 
 const DEFAULT_FILE = path.join(os.homedir(), ".claude", "multi-agent-preferences.json");
 
+// Single source of truth for the migration target version. Referenced by the
+// migrate() bump chain AND every user-facing message, so they cannot drift.
+const TARGET_VERSION = "2.3.0";
+
+const USAGE = "Usage: migrate-prefs.mjs [--dry-run] [--file <path>]";
+
 function parseArgs(argv) {
   const args = { file: DEFAULT_FILE, dryRun: false };
   for (let i = 2; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--dry-run") args.dryRun = true;
-    else if (a === "--file") args.file = argv[++i];
-    else if (a === "--help" || a === "-h") {
-      console.log("Usage: migrate-prefs.mjs [--dry-run] [--file <path>]");
+    else if (a === "--file") {
+      const v = argv[++i];
+      if (v === undefined) {
+        console.error("ERROR: --file requires a path argument");
+        console.error(USAGE);
+        process.exit(64);
+      }
+      args.file = v;
+    } else if (a === "--help" || a === "-h") {
+      console.log(USAGE);
       process.exit(0);
+    } else {
+      // A typo like --dry-rnu must never fall through to a real write.
+      console.error(`ERROR: unknown argument: ${a}`);
+      console.error(USAGE);
+      process.exit(64);
     }
   }
   return args;
@@ -142,7 +161,7 @@ function migrate(prefs) {
   // v2.3.0 is the v7.4.0 target  -  adds optional `accounts[]` (per-account host
   // overrides) and `recentAccounts[]` (LRU for autopilot account picker).
   // Both default to empty arrays; old prefs continue to validate without them.
-  const TARGET = "2.3.0";
+  const TARGET = TARGET_VERSION;
   if (out.schemaVersion === TARGET) {
     // already on target  -  skip version bump, but still run sub-migrations below
   } else if (out.schemaVersion === "2.2.0") {
@@ -371,7 +390,7 @@ function main() {
   const { out, changes, alreadyMigrated } = migrate(prefs);
 
   if (alreadyMigrated) {
-    console.log(`✓ already v2.1.0  -  no changes: ${args.file}`);
+    console.log(`✓ already v${TARGET_VERSION}  -  no changes: ${args.file}`);
     process.exit(0);
   }