@mmerterden/multi-agent-pipeline 11.5.0 → 12.1.0

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

@@ -1,42 +1,45 @@
 ---
 description: "⚠️ Wipes every worktree, branch, log, and state file. Irreversible; asks for double confirmation."
+description-tr: "⚠️ Tüm worktree, branch, log ve state dosyalarını siler. Geri alınamaz; çift onay ister."
 ---
 
 # multi-agent purge  -  Full Reset
 
-Reset every multi-agent state. Nuclear option  -  requires double confirmation.
+Reset every multi-agent worktree, its local branch, and the project task
+counter. Nuclear option  -  requires double confirmation. Backed by
+`$HOME/.claude/scripts/purge.sh`, which is safe by default (dry-run, deletes
+nothing until `--yes`), resolves every `rm` target strictly inside
+`<repo>/.worktrees/`, and never touches the main worktree or main/master/develop.
+
+Task log dirs are NOT purge territory  -  use `/multi-agent:prune-logs`. The
+audit trail and metrics corpus at the log root are always preserved.
 
 ## Steps
 
-1. **Scan**  -  find every worktree:
+1. **Preview (dry-run)**  -  list every worktree, branch, and the counter that
+   would be removed in the current repo:
    ```bash
-   find {repo}/.worktrees/ -name "agent-state.json" -maxdepth 2
-   ```
-
-2. **Show the list**:
-   ```
-   ⚠️ WARNING  -  these will be deleted:
-   - .worktrees/{JIRA-KEY}-12345/ (branch: feature/{JIRA-KEY}-12345-...)
-   - .worktrees/{JIRA-KEY}-12345/ (branch: feature/{JIRA-KEY}-12345-...)
-   - $HOME/.claude/logs/multi-agent/{project}/.counter
-   Total: N worktrees, N branches
+   bash $HOME/.claude/scripts/purge.sh
    ```
+   Nothing to remove -> report "nothing to purge" and stop.
 
-3. **First confirmation**: "This is irreversible. Are you sure?"
+2. **First confirmation**  -  native `AskUserQuestion` picker (no typed keyword),
+   in `outputLanguage`, including the dry-run counts:
+   - `question`: "Wipe the listed worktrees, branches, and counter?"
+   - `header`: "Purge" · `options`: `{ label: "Continue", description: "Proceed to the final confirmation" }`, `{ label: "Cancel", description: "Abort, change nothing" }`
+   - **Cancel** → exit.
 
-4. **Second confirmation** (paranoia gate)  -  a native `AskUserQuestion` picker (no typed keyword):
-   - `question`: "This is irreversible. Permanently wipe every worktree, branch, log, and state file now?" (`outputLanguage`)
-   - `header`: "Purge" (English, <=12 chars) · `options`: `{ label: "Purge permanently", description: "Delete all worktrees, branches, logs, and state" }`, `{ label: "Cancel", description: "Abort, change nothing" }`
+3. **Second confirmation** (paranoia gate)  -  a second `AskUserQuestion` picker:
+   - `question`: "This is irreversible. Permanently wipe every worktree, branch, and state now?" (`outputLanguage`)
+   - `header`: "Confirm" · `options`: `{ label: "Purge permanently", description: "Delete all worktrees, branches, and the counter" }`, `{ label: "Cancel", description: "Abort, change nothing" }`
    - Anything other than **Purge permanently** → cancel.
 
-5. **Delete** (per worktree):
+4. **Remote branches**  -  ask once whether to delete the remote branches too;
+   on yes, add `--delete-remote` to the apply command.
+
+5. **Purge**  -  re-run with `--yes` (plus `--delete-remote` if chosen):
    ```bash
-   git worktree remove .worktrees/{JIRA-KEY}-{id} --force
-   git branch -D {branch-name}
+   bash $HOME/.claude/scripts/purge.sh --yes
    ```
 
-6. **Remote branches**  -  ask: "Delete the remote branches too?"
-
-7. **Reset the counter**  -  remove `$HOME/.claude/logs/multi-agent/{project}/.counter`
-
-8. **Confirm**: `🔥 Purge complete`
+6. **Report**  -  echo the script's summary line.

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

@@ -1,5 +1,6 @@
 ---
 description: "Analyse the project: extract adapted best-practices, hunt real bugs + improvement areas, check upstream drift of derived skills, draft one plan, take approval, develop, then ask whether to sync."
+description-tr: "Projeyi analiz eder: uyarlanmış best-practice'leri çıkarır, gerçek bug + iyileştirme alanlarını avlar, türetilmiş skill'lerin upstream drift'ini kontrol eder, tek plan taslağı çıkarır, onay alır, geliştirir, sonra sync isteyip istemediğini sorar."
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion, WebFetch
 ---
 

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

@@ -1,5 +1,6 @@
 ---
 description: "Resume a stopped or failed task from the phase where it left off."
+description-tr: "Durmuş veya hata almış bir görevi kaldığı fazdan devam ettirir."
 argument-hint: "[#id]  -  optional: task ID (e.g. #2). If omitted, the most recent paused task is used."
 ---
 

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

@@ -1,5 +1,6 @@
 ---
 description: "Run parallel review on a branch's diff or a Pull Request: 2 models on Claude Code (Fable + Sonnet), 3 models on Copilot CLI (GPT + Opus + Sonnet). On PR input, posts per-finding inline comments and sets approve/needs-work review state."
+description-tr: "Bir branch diff'i veya Pull Request üzerinde paralel review koşar: Claude Code'da 2 model (Fable + Sonnet), Copilot CLI'da 3 model (GPT + Opus + Sonnet). PR girdisinde bulgu başına inline yorum atar ve approve/needs-work durumunu işaretler."
 argument-hint: "[#N | repo#N | PR-URL | branch]  -  optional: PR by number/URL, repo+number, or local branch. Supports GitHub and Bitbucket Server URLs. If omitted (interactive), open GitHub + Bitbucket PRs are listed for multi-select; autopilot falls back to the current branch."
 ---
 

package/pipeline/commands/multi-agent/review-issue/SKILL.md

@@ -1,5 +1,6 @@
 ---
 description: "Assess whether a GitHub issue is ready for multi-agent development: fetch it, grade scope / acceptance criteria / repro / design / API / stack readiness, then (after confirm) post the gaps as an issue comment. Read-only on code."
+description-tr: "Bir GitHub issue'sunun multi-agent geliştirmeye hazır olup olmadığını değerlendirir: getirir; kapsam / kabul kriterleri / repro / tasarım / API / stack hazırlığını puanlar, sonra (onay sonrası) eksikleri issue yorumu olarak gönderir. Kodda salt-okunur."
 argument-hint: "[#N | repo#N | GitHub issue URL]  -  optional; with no argument, pick from open issues"
 ---
 

package/pipeline/commands/multi-agent/review-jira/SKILL.md

@@ -1,5 +1,6 @@
 ---
 description: "Assess whether a Jira issue is ready for multi-agent development: fetch it, grade scope / acceptance criteria / repro / design / API / stack readiness, then (after confirm) post the gaps as a Jira comment. Read-only on code."
+description-tr: "Bir Jira issue'sunun multi-agent geliştirmeye hazır olup olmadığını değerlendirir: getirir; kapsam / kabul kriterleri / repro / tasarım / API / stack hazırlığını puanlar, sonra (onay sonrası) eksikleri Jira yorumu olarak gönderir. Kodda salt-okunur."
 argument-hint: "[JIRA-KEY | Jira URL]  -  optional; with no argument, pick from your open Jira issues"
 ---
 

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

@@ -1,5 +1,6 @@
 ---
 description: "Skill security scan: walks local skill directories against a tiered pattern catalog."
+description-tr: "Skill güvenlik taraması: yerel skill dizinlerini kademeli desen kataloğuna göre tarar."
 allowed-tools: Bash, Read
 argument-hint: "[--strict] [--threshold critical|high|medium|low] [--json] [--root PATH]"
 ---

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

@@ -1,5 +1,6 @@
 ---
 description: "Log search across every agent-log.md with smart ranking and filters. Optional --semantic flag queries the per-repo triage corpus."
+description-tr: "Tüm agent-log.md dosyalarında akıllı sıralama ve filtrelerle log araması. İsteğe bağlı --semantic bayrağı repo bazlı triyaj korpusunu sorgular."
 allowed-tools: Bash, Read
 argument-hint: "\"query\" [--project NAME] [--since 7d] [--phase N] [--semantic] [--json|--tsv]"
 ---

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

@@ -1,5 +1,6 @@
 ---
 description: "First-run setup wizard: keychain token discovery, Git Identity onboarding, and pipeline preparation."
+description-tr: "İlk kurulum sihirbazı: keychain token keşfi, Git Identity kaydı ve pipeline hazırlığı."
 allowed-tools: Bash, Read, Write, AskUserQuestion, WebFetch
 ---
 

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/lib/multi-repo-pipeline.sh

@@ -67,7 +67,12 @@ cmd_prepare() {
       echo "[$name] worktree already present at $target"
     else
       echo "[$name] cloning into $target"
-      git clone --quiet "$url" "$target" || { echo "ERR: clone failed for $name" >&2; return 3; }
+      # Disable git's `ext::`/`fd::` remote helpers (arbitrary command execution
+      # at clone time) in case a repo URL ever comes from an untrusted
+      # .gitmodules suggestion, and end options with `--` so a URL like
+      # `--upload-pack=...` can't inject a clone option. https/ssh/git@ and
+      # local/file paths all still work.
+      git -c protocol.ext.allow=never -c protocol.fd.allow=never clone --quiet -- "$url" "$target" || { echo "ERR: clone failed for $name" >&2; return 3; }
     fi
     cd "$target"
     if git rev-parse --verify "$BRANCH" >/dev/null 2>&1; then

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/_cost.mjs

@@ -0,0 +1,35 @@
+/**
+ * @file _cost.mjs  -  shared token-cost pricing math for the .mjs cost scripts
+ * (cost-budget-check.mjs, run-aggregator.mjs).
+ *
+ * The single source of the pricing formula for Node callers. Rate DATA still
+ * lives in cost-table.json; this module owns only the arithmetic so the formula
+ * is not copy-pasted across scripts. Zero runtime dependencies (ADR-0004).
+ *
+ * @module pipeline/scripts/_cost
+ */
+
+/**
+ * USD cost for a token trio given a rate object.
+ *
+ * tokensIn is fresh (cache-exclusive) input; tokensCached is priced at the
+ * discounted cacheReadPerMtok rate, falling back to inPerMtok when absent.
+ * Missing per-Mtok rate fields default to 0. Returns null when `rate` is falsy.
+ *
+ * @param {{inPerMtok?:number,outPerMtok?:number,cacheReadPerMtok?:number}|null|undefined} rate
+ * @param {number} [tokensIn]
+ * @param {number} [tokensOut]
+ * @param {number} [tokensCached]
+ * @returns {number|null}
+ */
+export function costUsd(rate, tokensIn = 0, tokensOut = 0, tokensCached = 0) {
+  if (!rate) return null;
+  const rin = rate.inPerMtok || 0;
+  const rout = rate.outPerMtok || 0;
+  const rcache = rate.cacheReadPerMtok ?? rin;
+  return (
+    ((tokensIn || 0) / 1_000_000) * rin +
+    ((tokensCached || 0) / 1_000_000) * rcache +
+    ((tokensOut || 0) / 1_000_000) * rout
+  );
+}

package/pipeline/scripts/agent-guard.py

@@ -40,7 +40,8 @@ def decide(cmd: str) -> str:
         try:
             toks = shlex.split(cmd)
         except Exception:
-            toks = cmd.split()
+            # A force-push we can't tokenize -> can't prove it's safe -> block.
+            return "BLOCK_FORCE"
         if any(t in PROTECTED or t.split(":")[-1] in PROTECTED for t in toks):
             return "BLOCK_FORCE"
         # non-flag args after `push`; only a remote (or nothing) means a bare push
@@ -52,8 +53,12 @@ def decide(cmd: str) -> str:
             if seen and not t.startswith("-"):
                 args.append(t)
         nonremote = [a for a in args if a not in REMOTES]
-        if not nonremote and os.environ.get("CUR_BRANCH", "") in PROTECTED:
-            return "BLOCK_FORCE"
+        if not nonremote:
+            # Bare force-push: the target is the current branch. Block if it's
+            # protected OR undeterminable (fail-closed for a data-loss guard).
+            cur = os.environ.get("CUR_BRANCH", "")
+            if cur in PROTECTED or cur == "":
+                return "BLOCK_FORCE"
 
     return "OK"
 

package/pipeline/scripts/cost-budget-check.mjs

@@ -34,6 +34,7 @@
 import { readFileSync, existsSync } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
+import { costUsd } from "./_cost.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -138,7 +139,7 @@ for (const p of Object.values(tracker.phases || {})) {
   tokensOut += Number(p?.tokens_out || 0);
 }
 
-const usd = (tokensIn * rate.inPerMtok + tokensOut * rate.outPerMtok) / 1_000_000;
+const usd = costUsd(rate, tokensIn, tokensOut);
 const pctOfMax = (usd / cfg.maxUsd) * 100;
 const usdStr = `$${usd.toFixed(2)}`;
 const totalTok = tokensIn + tokensOut;

package/pipeline/scripts/cost-lib.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# cost-lib.sh  -  shared token-cost pricing math, sourced by the bash cost
+# renderers (phase-tracker.sh, render-agent-log-cost.sh, render-cost-summary.sh).
+#
+# The single source of the pricing formula for shell callers. Rate DATA still
+# lives in cost-table.json; this file owns only the arithmetic so the formula
+# is not copy-pasted across scripts.
+#
+# COST_JQ_DEFS is a jq prelude string callers prepend to their own jq program:
+#
+#   cost_usd_of($rate; $tin; $tout; $tcached)
+#     -> USD for one row given a rate object (or null) and token counts.
+#        tokens_in is fresh input (cache-exclusive); tokens_cached is priced at
+#        the discounted cacheReadPerMtok rate (falling back to inPerMtok when
+#        absent). Returns null when $rate is null.
+#   cost_floor_cents($u)
+#     -> floor USD to whole cents; null passes through.
+#
+# cost_usd <rate-json> <tin> <tout> [tcached]  -  scalar convenience wrapper
+# that prints the raw (unrounded) USD via jq. Prints nothing when jq is absent.
+
+COST_JQ_DEFS='
+  def cost_usd_of($rate; $tin; $tout; $tcached):
+    if $rate == null then null
+    else ( ($tin / 1000000) * $rate.inPerMtok
+         + ($tcached / 1000000) * ($rate.cacheReadPerMtok // $rate.inPerMtok)
+         + ($tout / 1000000) * $rate.outPerMtok )
+    end;
+  def cost_floor_cents($u):
+    if $u == null then null else (($u * 100) | floor) / 100 end;
+'
+
+cost_usd() {
+  local rate="$1" tin="$2" tout="$3" tcached="${4:-0}"
+  command -v jq >/dev/null 2>&1 || return 0
+  jq -n \
+    --argjson rate "$rate" \
+    --argjson tin "$tin" \
+    --argjson tout "$tout" \
+    --argjson tcached "$tcached" \
+    "$COST_JQ_DEFS"'
+    cost_usd_of($rate; $tin; $tout; $tcached)'
+}

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	193
 .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	193
 .copilot/skills	467