@mmerterden/multi-agent-pipeline 11.5.0 → 12.0.0

package/pipeline/commands/multi-agent/stack/SKILL.md

@@ -1,5 +1,6 @@
 ---
 description: "Select the active stack for this repo by enabling the matching marketplace plugin(s) in .claude/settings.json (ios/android/mobile/backend/frontend/fullstack/all)."
+description-tr: "Bu repo için aktif stack'i seçer: eşleşen marketplace plugin'lerini .claude/settings.json'da etkinleştirir (ios/android/mobile/backend/frontend/fullstack/all)."
 allowed-tools: Bash, Read, Edit, Write
 ---
 

package/pipeline/commands/multi-agent/status/SKILL.md

@@ -1,5 +1,6 @@
 ---
 description: "Show every multi-agent task's ID, phase, branch, and status."
+description-tr: "Tüm multi-agent görevlerinin ID, faz, branch ve durumunu gösterir."
 ---
 
 # multi-agent status  -  Task Status Dashboard

package/pipeline/commands/multi-agent/sync/SKILL.md

@@ -1,5 +1,6 @@
 ---
 description: "One-shot sync of the entire multi-agent ecosystem: Claude Code, Copilot CLI, pipeline repo, and website."
+description-tr: "Tüm multi-agent ekosisteminin tek atımlık senkronu: Claude Code, Copilot CLI, pipeline repo ve website."
 argument-hint: "[release] [--platform=<macos|linux|windows>]"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, WebFetch
 ---
@@ -130,6 +131,23 @@ If nothing is stale → report "All targets up to date" and stop.
        ~/multi-agent-pipeline/pipeline/commands/ 2>/dev/null \
        && { echo "ABORT: corporate reference leaked into pipeline/commands"; exit 1; } || true
      ```
+   - **Localized picker descriptions are an installed-tree artifact.** When
+     `outputLanguage=tr`, the installed `description:` values are Turkish and a
+     `description-en:` sidecar holds the English original (see
+     `localize-commands.mjs`). The repo must ALWAYS receive the English form:
+     after copying commands into `pipeline/commands/`, normalize the copy and
+     verify no sidecar or Turkish description leaked:
+     ```bash
+     # normalize: restore English descriptions, strip description-en sidecars
+     node ~/multi-agent-pipeline/pipeline/scripts/localize-commands.mjs restore \
+       --dir ~/multi-agent-pipeline/pipeline/commands/multi-agent
+     # backstop: no sidecar may survive into the repo
+     grep -rl "^description-en:" ~/multi-agent-pipeline/pipeline/commands/ 2>/dev/null \
+       && { echo "ABORT: description-en sidecar leaked into pipeline/commands"; exit 1; } || true
+     # backstop: repo description lines must be English (Turkish-diacritics proxy)
+     grep -rn '^description:.*[çğıöşüÇĞİÖŞÜ]' ~/multi-agent-pipeline/pipeline/commands/ 2>/dev/null \
+       && { echo "ABORT: localized description leaked into pipeline/commands"; exit 1; } || true
+     ```
 
 6. **Cross-platform smoke gate** (final step of the REPO sync, before push):
    ```bash
@@ -242,11 +260,11 @@ This runs on the Claude <-> Copilot axis — the two CLIs the pipeline supports
 **38 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
 
 ```
-analysis, analysis-resolve, autopilot, build-optimize, channels, create-jira, delete, dev,
+analysis, analysis-resolve, autopilot, build-optimize, channels, create-jira, dev,
 dev-autopilot, dev-local, dev-local-autopilot, diff-explain, finish, garbage-collect,
 help, issue, jira, kill, language, local,
 local-autopilot, log, manual-test, prune-logs, purge, refactor, resume, review, review-issue, review-jira,
-scan, search, setup, stack, status, sync, test, update
+scan, search, setup, stack, status, sync, test, uninstall, update
 ```
 
 **NOT synced**: `$HOME/.claude/multi-agent-refs/*`  -  lazy-load references, Claude Code specific

package/pipeline/commands/multi-agent/test/SKILL.md

@@ -1,5 +1,6 @@
 ---
 description: "UI Bug Hunter  -  iOS Simulator (simctl) + Android Emulator (adb). Auto-detects platform. Screenshot + tap + analyze on the booted device. The Phase 5 Manual Test flow lives at /multi-agent:manual-test."
+description-tr: "UI Bug Hunter - iOS Simulator (simctl) + Android Emulator (adb). Platformu otomatik algılar. Açık cihazda screenshot + tap + analiz. Faz 5 Manuel Test akışı /multi-agent:manual-test'te."
 argument-hint: '[scenario]  -  e.g. "dark mode" | "accessibility" | "dynamic type" | "screenshot tr" | "store-ready" | (empty = full sweep)'
 ---
 

package/pipeline/commands/multi-agent/uninstall/SKILL.md

@@ -0,0 +1,87 @@
+---
+description: "Uninstall the pipeline from Claude Code + Copilot CLI. Keychain access tokens are always left untouched; --all-data also clears pipeline settings and logs. Asks for double confirmation."
+description-tr: "Pipeline'ı Claude Code + Copilot CLI'dan kaldırır. Keychain erişim token'larına asla dokunulmaz; --all-data ayrıca pipeline ayarlarını ve loglarını da siler. Çift onay ister."
+argument-hint: "[--dry-run] [--all-data] [--claude] [--copilot] [--target=<path>]"
+---
+
+# multi-agent uninstall  -  Token-Preserving Uninstall
+
+Uninstalls the pipeline itself from the system. **This is different from `:purge`:**
+
+| Command | What it removes |
+|---|---|
+| `:purge` | Active tasks' worktrees / branches / logs / state (development data) |
+| `:uninstall` | The pipeline itself: skills, commands, agents, scripts  -  from every CLI |
+
+## Two modes
+
+| Mode | Flag | Removes | Keeps |
+|---|---|---|---|
+| **Standard** (default) | (none) | distributed files: commands, skills, agents, scripts, refs, schemas, lib | tokens, `CLAUDE.md`, `rules/`, `multi-agent-preferences.json`, all logs |
+| **Full cleanup** | `--all-data` | standard PLUS `multi-agent-preferences.json` + `~/.claude/logs/multi-agent/` (task logs, state, metrics, audit) | tokens, `CLAUDE.md`, `rules/` (user-owned) |
+
+Tokens in the OS credential store are NEVER removed by either mode.
+
+## Never deleted (either mode)
+
+- **Keychain / Credential Manager / libsecret** personal access tokens (GitHub, Jira, Bitbucket, Confluence, Telegram, Vercel, Firebase, etc.)
+- `~/.claude/CLAUDE.md` (user customisations)
+- `~/.claude/rules/` (user-owned; installed write-if-missing, never overwritten)
+- User content OUTSIDE the `<!-- multi-agent-pipeline:begin/end -->` markers (`copilot-instructions.md`)
+
+Settings (`multi-agent-preferences.json`) and the log root (`~/.claude/logs/multi-agent/`) are kept by default and removed only when the user picks full cleanup (`--all-data`).
+
+## Steps
+
+1. **Determine scope**  -  parse `$ARGUMENTS`:
+   - No target flag: every installed target (default)
+   - `--claude / --copilot`: selective
+   - `--all-data`: full cleanup (also removes settings + logs)
+   - `--target=<path>`: adapter target (default: cwd)
+   - `--dry-run`: report only, delete nothing
+
+2. **Ask the cleanup depth** (skip if the user already passed `--all-data` or `--dry-run`)  -  native `AskUserQuestion` picker in `outputLanguage`:
+   - `question`: "How much should uninstall remove? Tokens are preserved either way."
+   - `header`: "Scope" · `options`:
+     `{ label: "Standard", description: "Remove pipeline files; keep settings + logs" }`,
+     `{ label: "Full cleanup", description: "Also remove settings + all task logs/state/metrics" }`
+   - **Full cleanup** adds `--all-data` to the flag set below.
+
+3. **Show a preview** (run the script with `--dry-run`, carrying the chosen flags):
+   ```bash
+   node "$HOME/.claude/scripts/uninstall.mjs" --dry-run --yes <flags>
+   ```
+   Show the output raw to the user. In full-cleanup mode the preview lists the extra settings + log removals.
+
+4. **First confirmation**  -  native `AskUserQuestion` picker (no typed y/N):
+   - `question`: "Remove the pipeline from the listed targets? Tokens are NOT touched." (`outputLanguage`)
+   - `header`: "Uninstall" · `options`: `{ label: "Continue", description: "Proceed to the final confirmation" }`, `{ label: "Cancel", description: "Keep everything installed" }`
+   - **Cancel** → exit.
+
+5. **Second confirmation** (paranoia gate, same pattern as `:purge`)  -  a second `AskUserQuestion` picker:
+   - `question`: full cleanup -> "This also erases settings + all logs and is irreversible. Proceed?"; standard -> "This is irreversible. Permanently remove the pipeline files now?" (`outputLanguage`)
+   - `header`: "Confirm" · `options`: `{ label: "Remove permanently", description: "Run the uninstall; tokens are preserved" }`, `{ label: "Cancel", description: "Abort, change nothing" }`
+   - Anything other than **Remove permanently** → cancel.
+
+6. **Remove**  -  run the real script with `--yes` (and `--all-data` if full cleanup was chosen):
+   ```bash
+   node "$HOME/.claude/scripts/uninstall.mjs" --yes <flags>
+   ```
+
+7. **Confirm**:
+   ```
+   ✓ multi-agent-pipeline removed.
+   ℹ Personal access tokens preserved in Keychain.
+   ```
+   Remind the user how to inspect the tokens (cross-platform  -  same command on every backend):
+   - `~/.claude/lib/credential-store.sh get "<service>"`
+
+8. **Reinstall** (if the user wants to):
+   ```bash
+   npx @mmerterden/multi-agent-pipeline install
+   ```
+
+## Notes
+
+- This command does NOT remove the *installed copy* of the npm package. It only removes the distributed files. `npm uninstall -g @mmerterden/multi-agent-pipeline` is a separate step.
+- `--dry-run` is always safe  -  zero side effects.

package/pipeline/commands/multi-agent/update/SKILL.md

@@ -1,5 +1,6 @@
 ---
 description: "Update the pipeline to the latest version: git pull, install, migrate."
+description-tr: "Pipeline'ı son sürüme günceller: git pull, install, migrate."
 allowed-tools: Bash, Read, Write, AskUserQuestion
 ---
 

package/pipeline/multi-agent-refs/cross-cli-contract.md

@@ -9,11 +9,11 @@
 ## 1. Command Inventory (38 commands)
 
 ```
-analysis, analysis-resolve, autopilot, build-optimize, channels, create-jira, delete, dev,
+analysis, analysis-resolve, autopilot, build-optimize, channels, create-jira, dev,
 dev-autopilot, dev-local, dev-local-autopilot, diff-explain, finish, garbage-collect,
 help, issue, jira, kill, language, local,
 local-autopilot, log, manual-test, prune-logs, purge, refactor, resume, review, review-issue, review-jira,
-scan, search, setup, stack, status, sync, test, update
+scan, search, setup, stack, status, sync, test, uninstall, update
 ```
 
 Categories:
@@ -23,7 +23,7 @@ Categories:
 - **Full 8-phase modes**: `autopilot`, `local`, `local-autopilot`
 - **Fast modes** (Init -> Dev(Opus) -> Commit -> Report): `dev`, `dev-autopilot`, `dev-local`, `dev-local-autopilot`
 - **Tail modes** (run the pipeline tail over already-done local work): `finish`
-- **Ops commands** (one-shot, no worktree): `status`, `log`, `kill`, `purge`, `delete`, `resume`, `review`, `review-jira`, `review-issue`, `analysis`, `analysis-resolve`, `build-optimize`, `channels`, `scan`, `search`, `diff-explain`, `garbage-collect`, `prune-logs`
+- **Ops commands** (one-shot, no worktree): `status`, `log`, `kill`, `purge`, `uninstall`, `resume`, `review`, `review-jira`, `review-issue`, `analysis`, `analysis-resolve`, `build-optimize`, `channels`, `scan`, `search`, `diff-explain`, `garbage-collect`, `prune-logs`
 - **Meta-ops**: `setup`, `sync`, `update`, `help`, `refactor`, `test`, `stack`, `manual-test`, `language`
 
 > **Inventory drift is a contract violation.** Adding a slash command under `pipeline/commands/multi-agent/` without updating this list + its counterpart Copilot dir (`pipeline/skills/shared/core/multi-agent-<cmd>/`) is a merge blocker. `smoke-commands-skills-parity.sh` enforces command ↔ skill directory parity; `smoke-cross-cli-behavior.sh` enforces behavior parity. This doc is the authoritative command list  -  bump the count + table together.
@@ -163,10 +163,10 @@ argument-hint: "<input hint>"
 
 | Direction | Action |
 |---|---|
-| Claude → Copilot | Add `name`, `user-invocable: true`, `argument-hint`; remove `allowed-tools`; may optionally translate `description` into Turkish (existing pattern) |
+| Claude → Copilot | Add `name`, `user-invocable: true`, `argument-hint`; remove `allowed-tools`; `description` stays English (localization happens only in the installed Claude tree via `description-tr` + `localize-commands.mjs`, never in repo or Copilot files) |
 | Copilot → Claude | Remove `name`, `user-invocable`, `argument-hint`; add `allowed-tools` (inferred from command's actual tool calls) |
 
-**Invariant**: the `description` field, after potential translation, must have the same meaning on both sides. Translation is allowed; semantic drift is not.
+**Invariant**: the English `description` must have the same meaning on both sides, and a `description-tr` line (when present) must be a faithful translation of it. Semantic drift is not allowed. `description-en` sidecars are an installed-tree artifact and must never appear in repo or Copilot files.
 
 ---
 

package/pipeline/multi-agent-refs/phases/phase-0-init.md

@@ -425,7 +425,7 @@ git -C $PROJECT_ROOT config user.email "{identity.email}"
 
 `worktreePath` = `$PROJECT_ROOT`, `localMode` = `true`.
 
-**If normal mode** (worktree  -  default): 2. Worktree path: Jira → `.worktrees/{jiraId}/`, GitHub → `.worktrees/GH{issueNo}/`, free-text → `.worktrees/task-{shortId}/` 3. **Heal stale admin state first** (see "Worktree stale-lock heal" below), then `git -C $PROJECT_ROOT worktree add {path} -b {branch} origin/{baseBranch}` (if exists: enter, pull) 4. Set identity: `git -C {worktree-path} config user.name/email` 5. Create log dir + `agent-log.md` + `agent-state.json`:
+**If normal mode** (worktree  -  default): 2. Worktree path: Jira → `.worktrees/{jiraId}/`, GitHub → `.worktrees/GH{issueNo}/`, free-text → `.worktrees/task-{shortId}/` 3. **Heal stale admin state first** (see "Worktree stale-lock heal" below) and **apply the residue guard** (see "Worktree residue guard" below), then `git -C $PROJECT_ROOT worktree add {path} -b {branch} origin/{baseBranch}` (if exists: enter, pull) 4. Set identity: `git -C {worktree-path} config user.name/email` 5. Create log dir + `agent-log.md` + `agent-state.json`:
 
 **Worktree stale-lock heal (required before every `worktree add`):** a run killed mid-`worktree add` (OOM, SIGTERM, disk full) leaves a locked or broken admin entry under `.git/worktrees/{id}/`, so the retry fails with `fatal: '<path>' already exists`. Always run the heal first  -  it is a no-op on a clean repo:
 
@@ -438,6 +438,14 @@ fi
 
 If the path is still registered and healthy after the heal, enter + pull instead of re-adding (existing behavior). Only when `worktree add` still fails after the heal do the rollback / collision flow in the multi-repo block below.
 
+**Worktree residue guard (required once per repo, idempotent):** every worktree dir contains a `.git` file, so a blanket `git add -A` / `git add .` in the parent tree records `.worktrees/{id}` as a gitlink ("Subproject commit ...") that pollutes the branch and later needs a manual removal commit. Keep `.worktrees/` out of the index via the clone-local exclude file (never committed, so no PR noise in shared repos):
+
+```bash
+ex="$(git -C "$PROJECT_ROOT" rev-parse --path-format=absolute --git-common-dir)/info/exclude"
+mkdir -p "$(dirname "$ex")"
+grep -qxF '.worktrees/' "$ex" 2>/dev/null || printf '.worktrees/\n' >> "$ex"
+```
+
 **v2.1.0+ Multi-Repo Worktree Setup**:
 
 When `state.projects[].length > 1`, repeat steps 2-4 **serially per repo** (worktrees are cheap; serial keeps git index sane and surfaces collisions one at a time):
@@ -448,6 +456,9 @@ for proj in "${PROJECTS[@]}"; do
   git -C "$proj" worktree prune 2>/dev/null || true               # heal stale admin state
   git -C "$proj" worktree list --porcelain | grep -qF "$WT_PATH" \
     && git -C "$proj" worktree unlock "$WT_PATH" 2>/dev/null || true
+  ex="$(git -C "$proj" rev-parse --path-format=absolute --git-common-dir)/info/exclude"
+  mkdir -p "$(dirname "$ex")"
+  grep -qxF '.worktrees/' "$ex" 2>/dev/null || printf '.worktrees/\n' >> "$ex"   # residue guard
   git -C "$proj" worktree add "$WT_PATH" -b "$BRANCH" "origin/$BASE_BRANCH"
   git -C "$WT_PATH" config user.name  "${proj_identity_name}"
   git -C "$WT_PATH" config user.email "${proj_identity_email}"

package/pipeline/scripts/fixtures/install-layout.tsv

@@ -1,3 +1,4 @@
+.claude/.pipeline-version	1
 .claude/CLAUDE.md	1
 .claude/agents	8
 .claude/commands	44
@@ -6,12 +7,13 @@
 .claude/multi-agent-refs	51
 .claude/rules	12
 .claude/schemas	23
-.claude/scripts	184
+.claude/scripts	190
 .claude/settings.json	1
 .claude/skills	428
+.copilot/.pipeline-version	1
 .copilot/agents	8
 .copilot/copilot-instructions.md	1
 .copilot/lib	25
 .copilot/schemas	23
-.copilot/scripts	184
+.copilot/scripts	190
 .copilot/skills	467

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/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}`);
+}