@mmerterden/multi-agent-pipeline 8.6.0 → 8.6.1

package/README.md

@@ -18,7 +18,7 @@
 | Figma skills (iOS + Android + Common) | 37 |
 | External skill catalog (`shared/external/`) | 127 |
 | Total `SKILL.md` files across all groups | 196 |
-| Smoke suites | 87 |
+| Smoke suites | 88 |
 | Golden-task fixtures (`pipeline/eval/golden-tasks/`) | 2 |
 | Eval-triage fixtures | 11 |
 | JSON schemas | 13 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "8.6.0",
+  "version": "8.6.1",
   "description": "8-phase AI development pipeline. Full orchestration on Claude Code + Copilot CLI; knowledge layer (rules + skills) ports to Cursor, Windsurf, and Cline. Analysis, planning, TDD, CLI-aware parallel review with Opus triage, wiki generation, commit automation. Token-preserving uninstall.",
   "type": "module",
   "main": "index.js",
@@ -46,6 +46,9 @@
   ],
   "author": "Mert Erden",
   "license": "MIT",
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/mmerterden/multi-agent-pipeline.git"

package/pipeline/commands/multi-agent/refs/features/dev-critic.md

@@ -0,0 +1,44 @@
+# Feature: Dev Critic (Phase 3 Step 3.5 Evaluator-Optimizer)
+
+**Pattern**: Anthropic's evaluator-optimizer from "Building Effective Agents" (Dec 2024). Generator (Phase 3 Dev) and critic (`agents/dev-critic.md`) loop on deterministic criteria already written in `rules/*.md` before any Phase 4 reviewer call.
+
+**Gated by `prefs.global.devCritic.enabled`** (default: `false`). When enabled, after the generator's last edit and BEFORE Phase 4:
+
+1. Dispatch `dev-critic` sub-agent (Sonnet by default, tools: `Read, Grep, Glob, Bash`).
+2. Critic runs 4 deterministic gates (build / lint / test / secrets) — failure of any → `pass: false` with `blocking` finding.
+3. If gates green, critic walks the platform checklist (iOS 13-item / Android Kotlin / Backend generic — selected by Phase 1 `detectedStack`).
+4. Returns schema-validated JSON (`pipeline/schemas/dev-critic-output.schema.json`): `{pass, iteration, gates, findings[], escalate}`.
+
+## Loop cap (STRICT) — max 2 iterations
+
+| Round | Behavior |
+|---|---|
+| 1 | Full critic pass — all gates + full checklist |
+| 2 | Re-check only round-1 failures. No new findings allowed (scope creep prevention) |
+| 3+ | NOT ALLOWED. Critic returns `escalate: true`; orchestrator pauses (interactive) or proceeds to Phase 4 with logged failure (autopilot) |
+
+## Action by severity
+
+- `blocking` → generator MUST fix; another Dev iteration before re-critic
+- `important` → generator SHOULD fix; if skipped, pass through to Phase 4 (legitimate reviewer ground)
+- `suggestion` → generator's judgement; never blocks round 2
+
+## Telemetry
+
+Each critic call emits `dev_critic.call` with `iteration`, `pass`, `gates_failed`, `blocking`, `important`, `duration_ms`, `tokens_in/out`. Phase 7 cost rollup lists these as `phase 3.5` line items so the net saving (Phase 4 reviewer/triage calls avoided) is measurable.
+
+## Off by default reason
+
+Introduces ~1× Sonnet call per Dev iteration. On simple bug fixes the cost outweighs the benefit (Phase 4 would have caught the same thing for similar cost). Recommended on:
+
+- Feature work (≥200 LOC diff)
+- Security-touching paths (auth, keychain, network)
+- Multi-file refactors where rule violations compound
+
+## Why this fits orchestrator-workers + evaluator-optimizer hybrid
+
+Phase 4 is parallelization-with-voting — good for *adversarial* perspectives (security, architecture). Phase 3.5 is evaluator-optimizer — good for *deterministic* criteria (build, tests, checklists). Sending failing builds into Phase 4 wastes 2–3 reviewer calls + Opus triage; Phase 3.5 absorbs that cost at one Sonnet call.
+
+## Reference
+
+See `pipeline/agents/dev-critic.md` for the full agent specification (gates, checklist enumeration, output schema, severity semantics).

package/pipeline/commands/multi-agent/refs/features/external-context-injection.md

@@ -0,0 +1,63 @@
+# Feature: External Context Injection (Phase 1 Step 1.5)
+
+Phase 0 Step 1b catalogued every typed external link from the task description into `state.contextLinks[]`. Phase 1 dispatches each entry to its matching fetcher and prepends the result to the analysis prompt under a **Referenced External Sources** section, so the agent doesn't re-discover what the ticket already pointed at.
+
+```bash
+jq -c '.contextLinks // []' "$STATE_FILE" \
+  | python3 -c '
+import json, sys, os
+links = json.loads(sys.stdin.read() or "[]")
+by_type = {}
+for l in links:
+    by_type.setdefault(l["type"], []).append(l)
+print(json.dumps(by_type))
+' > /tmp/context-by-type-${TASK_ID}.json
+```
+
+## Dispatch table
+
+One fetcher per type. Each fetcher emits a normalized JSON view that the analysis prompt consumes as ground truth for the referenced source.
+
+| Type | Fetcher | Output stored in |
+|---|---|---|
+| `crashlytics` | `~/.claude/lib/fetch-crashlytics.sh <url>` (already invoked in Phase 0 Step 1b.1 for the legacy `state.crashContext` field; Phase 1 reads that field directly) | `state.crashContext` |
+| `fortify` | `~/.claude/lib/fetch-fortify.sh <url>` (already invoked in Phase 0 Step 1b.2 for the legacy `state.fortifyFinding` field; Phase 1 reads that field, Phase 4 reads the full payload for the security gate) | `state.fortifyFinding` |
+| `swagger` | `~/.claude/lib/fetch-swagger.sh <url>` → endpoints[], request/response examples | `state.fetchedContext.swagger[]` |
+| `confluence` | `~/.claude/lib/fetch-confluence.sh <url>` → page body, code blocks, extracted API contracts | `state.fetchedContext.confluence[]` |
+| `figma` | `~/.claude/lib/fetch-figma.sh <url>` (via existing MCP / REST fallback path) when the task is a component; otherwise advisory only | `state.fetchedContext.figma[]` |
+| `generic-doc` | no automatic fetcher — surfaced as advisory; the agent uses WebFetch on demand when the URL turns out to be load-bearing | n/a |
+
+## Exit code handling
+
+- `0` (success) → output appended to `state.fetchedContext.<type>[]` and injected into the prompt.
+- `2` (blocked / missing token) → run the inline Token Save Flow per `setup.md`; on skip, mark the entry as `{status: "skipped", reason: "missing-token"}` and continue.
+- `3` (network/auth) → mark as `{status: "failed", reason: "<exit-msg>"}`, continue.
+- `4`/`5`/`6` (config errors) → mark as `{status: "failed", reason: "<exit-msg>"}`, continue and log a setup hint.
+
+Failures are never fatal at Phase 1 — the agent still runs analysis, just without the referenced source.
+
+## Prompt injection shape
+
+Added immediately after the knowledge-injection block, before codebase exploration:
+
+```
+## Referenced External Sources
+
+(when fetchers populated `state.fetchedContext.<type>`)
+### <type> — <url>
+<fetched content, scoped to relevance>
+
+(when fetcher pending)
+### Pending references
+- <type>: <url> — <one-line metadata>
+```
+
+The agent treats fetched content as **ground truth** for the referenced source (no re-discovery, no contradiction). Pending references are advisories — the agent decides whether to fetch via WebFetch on demand when the task hinges on that source.
+
+## Log line shape
+
+```
+→ context injection: total=<N>, fetched=<n>, pending=<n>, by-type={swagger:F/P, confluence:F/P, ...}
+```
+
+`F` = fetched, `P` = pending. Empty contextLinks → `total=0`, skip the section entirely.

package/pipeline/commands/multi-agent/refs/features/plan-todos.md

@@ -0,0 +1,20 @@
+# Feature: Plan Todos Iteration (Phase 3)
+
+**Gated by `prefs.global.planTodos.enabled`** (default: `false`). When enabled and Phase 2 Step 4.5 emitted a `plan.todos[]` (conforming to `pipeline/schemas/plan-todos.schema.json`), Phase 3 iterates with the helper instead of walking `tasks[]` directly:
+
+```bash
+while next=$(bash "$HOME/.claude/lib/plan-todos.sh" next "$TASK_ID"); [ -n "$next" ]; do
+  id=$(printf '%s' "$next" | cut -f1)
+  task=$(printf '%s' "$next" | cut -f2)
+  bash "$HOME/.claude/lib/plan-todos.sh" start "$TASK_ID" "$id"
+  # ... TDD cycle for "$task" ...
+  if build_passed; then
+    bash "$HOME/.claude/lib/plan-todos.sh" complete "$TASK_ID" "$id" "${COMMIT_HASH} · tests:${TEST_COUNT}"
+  else
+    bash "$HOME/.claude/lib/plan-todos.sh" fail "$TASK_ID" "$id" "build failed after 3 retries"
+    break
+  fi
+done
+```
+
+When disabled, the loop still walks `tasks[]` from `planning-output` — `plan-todos.sh` adds visibility (status, notes, deps-respecting `next`) but the underlying TDD contract is unchanged.

package/pipeline/commands/multi-agent/refs/features/prior-fix-detection.md

@@ -0,0 +1,49 @@
+# Feature: Prior Fix Detection (Phase 1 Step 0)
+
+Before any analysis, check if this issue was already fixed by someone else.
+
+## Check order
+
+1. **Git commit search** — look for commits referencing this issue ID across all branches:
+
+   ```bash
+   git -C $PROJECT_ROOT log --all --oneline --grep="{jiraId}" --since="8 weeks ago"
+   ```
+
+2. **Affected file history** — after identifying key files (from issue description keywords), check recent changes:
+
+   ```bash
+   git -C $PROJECT_ROOT log --oneline --since="4 weeks ago" -- {affected_file_paths}
+   ```
+
+3. **Jira comments/status** — fetch latest comments to see if someone reported a fix:
+
+   ```bash
+   curl -s -H "Authorization: Bearer $JIRA_TOKEN" \
+     "$JIRA_BASE/issue/{jiraId}?fields=status,comment&expand=changelog" \
+     | jq '.fields.status.name, .fields.comment.comments[-3:][]?.body'
+   ```
+
+## If prior fix commit(s) found
+
+```
+This issue appears to already have been addressed:
+  {hash} — {message} (by {author}, {date})
+
+Options:
+  1. Verify fix (check if cherry-pick/merge to base branch is needed)
+  2. Stop pipeline (already resolved)
+  3. Continue anyway (different fix needed)
+```
+
+- Option 1 → Check if the commit exists on `baseBranch`. If not, suggest cherry-pick. Pipeline pauses.
+- Option 2 → Cleanup and exit:
+  1. Checkout back to base branch: `git -C $PROJECT_ROOT checkout {baseBranch}`
+  2. Delete the created branch: `git -C $PROJECT_ROOT branch -D {branch}`
+  3. If worktree was used: `git -C $PROJECT_ROOT worktree remove {worktreePath} --force`
+  4. Set `agent-state.json` status to `"stopped_already_fixed"`. Log and exit.
+- Option 3 → Continue to Step 1 as normal.
+
+## If no prior fix found
+
+Continue to Step 1 (Knowledge Injection).

package/pipeline/commands/multi-agent/refs/features/repo-map.md

@@ -0,0 +1,30 @@
+# Feature: Repo Map Injection (Phase 1 Step 2.5)
+
+**Gated by `prefs.global.repoMap.enabled`** (default: `false`). Pattern source: <https://aider.chat/docs/repomap.html>.
+
+Before launching Explore agents, run the deterministic repo map renderer and inject the result into each Explore prompt as `${REPO_MAP}`. This gives every explorer a token-budgeted overview of the most-referenced files in the repo — ranked via cross-file declaration references with TF-IDF-style credit splitting so universally-shared helper names (`pass`, `fail`, `init`) don't dominate.
+
+```bash
+REPO_MAP=""
+if [ "$(jq -r '.global.repoMap.enabled // false' "$PREFS")" = "true" ]; then
+  BUDGET=$(jq -r '.global.repoMap.tokenBudget // 1500' "$PREFS")
+  TOP=$(jq -r '.global.repoMap.topFiles // 25' "$PREFS")
+  INCLUDE=$(jq -r '.global.repoMap.include // empty' "$PREFS")
+  EXCLUDE=$(jq -r '.global.repoMap.exclude // empty' "$PREFS")
+  args=(--root "$WORKTREE" --budget "$BUDGET" --top "$TOP" --format md)
+  [ -n "$INCLUDE" ] && args+=(--include "$INCLUDE")
+  [ -n "$EXCLUDE" ] && args+=(--exclude "$EXCLUDE")
+  REPO_MAP=$(node pipeline/scripts/repo-map.mjs "${args[@]}" 2>/dev/null || echo "")
+fi
+```
+
+## Properties
+
+- **Deterministic** — same worktree state → same map. No embeddings, no network. Sub-second on monorepos.
+- **Advisory** — Explore agents may ignore the map if they have stronger signals (Phase 0 knowledge cache, explicit user context). Never gates the pipeline.
+- **Truncation-safe** — output is capped at `tokenBudget`; the script falls back to "no files extracted within budget" rather than over-spending.
+- **Cost ledger** — emit `phase-1.repo_map_emitted bytes=$(wc -c <<<"$REPO_MAP") budget=$BUDGET` so Phase 7 cost summary can show the size injected.
+
+## When to enable
+
+Large repos (>200 source files) where Explore otherwise spends multiple rounds finding the right starting files. Skip on small repos — the overhead exceeds the gain.

package/pipeline/commands/multi-agent/refs/features/shadow-git.md

@@ -0,0 +1,24 @@
+# Feature: Shadow-Git Checkpoints (Phase 3)
+
+**Gated by `prefs.global.shadowGit.enabled`** (default: `false`). The orchestrator snapshots the worktree via `pipeline/lib/shadow-git.sh` so sub-phase rollback is possible without polluting the project's real `.git` history. Pattern source: Cline checkpoints (<https://docs.cline.bot/features/checkpoints>).
+
+```bash
+# Phase 0 (one-time per task): initialize shadow repo + baseline snapshot.
+bash "$HOME/.claude/lib/shadow-git.sh" init "$TASK_ID" "$WORKTREE"
+
+# Per-step (mode: per-todo-step — default): snapshot AFTER each plan-todos
+# step completes successfully, so restore lands on a known-good state.
+bash "$HOME/.claude/lib/plan-todos.sh" complete "$TASK_ID" "$id" "$notes"
+bash "$HOME/.claude/lib/shadow-git.sh" snapshot "$TASK_ID" "$WORKTREE" "step $id: $task"
+
+# Per-mutation (mode: per-tool-call): the orchestrator hooks into every Edit/
+# Write/MultiEdit/Bash-mutation tool call. Higher fidelity, ~50ms × tool-call
+# overhead — recommended only for security-critical paths or experimental
+# refactors where the user values fine-grained rollback over speed.
+
+# Rollback on demand (interactive helper):
+bash "$HOME/.claude/lib/shadow-git.sh" list "$TASK_ID"
+bash "$HOME/.claude/lib/shadow-git.sh" restore "$TASK_ID" "$WORKTREE" <sha> --files
+```
+
+Shadow repo location: `~/.claude/state/shadow-git/<task-id>/.git/`. Storage cap: `prefs.shadowGit.pruneAfterDays` (default 14). `/multi-agent:purge` honors this prune; manual cleanup via `shadow-git.sh prune <task-id>`.

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

@@ -65,7 +65,7 @@ Used for: input parsing, branch naming, commit messages.
 
 **Save rule**: After EVERY selection, append chosen value to relevant array (dedup, most recent first, max 10). Save prefs after Phase 0 and Phase 7.
 
-**Recents update map** (which selection writes to which prefs path):
+**v2.1.0+ Recents update map** (which selection writes to which prefs path):
 
 | Selection event | Prefs path | Shape | Cap |
 |---|---|---|---|
@@ -208,7 +208,7 @@ Scan `$HOME` (maxdepth 2) for project markers (`.xcodeproj`, `Package.swift`, `b
 
 **Otherwise**: Present discovered projects as numbered list (standard UX pattern). Stack tag (`[iOS]`, `[Android]`, etc.) auto-detected from project files. Set `PROJECT_ROOT` to selected directory — all subsequent commands use `git -C $PROJECT_ROOT`. Save to `prefs.global.recentProjects` (dedup, max 10). If bare `#N` was given, now fetch GitHub issue from project's remote.
 
-**Multi-Repo Mode** (gated by `prefs.global.settings.multiRepoEnabled`):
+**v2.1.0+ Multi-Repo Mode** (gated by `prefs.global.settings.multiRepoEnabled`):
 
 - The picker accepts space-separated numbers (`1 3 4`) for multi-select.
 - `prefs.global.recentGroups[]` (set in setup.md Step 6) surfaces at the top: pressing the group's number selects all its repos in one keystroke.
@@ -354,7 +354,7 @@ git -C $PROJECT_ROOT config user.email "{identity.email}"
 
 **If normal mode** (worktree — default): 2. Worktree path: Jira → `.worktrees/{jiraId}/`, GitHub → `.worktrees/GH{issueNo}/`, free-text → `.worktrees/task-{shortId}/` 3. `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`:
 
-**Multi-Repo Worktree Setup**:
+**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):
 

package/pipeline/commands/multi-agent/refs/phases/phase-1-analysis.md

@@ -7,50 +7,7 @@ Progress emission per `refs/progress-contract.md` — lines for each Explore dis
 
 #### Step 0 — Prior Fix Detection
 
-Before any analysis, check if this issue was already fixed by someone else.
-
-**Check order:**
-
-1. **Git commit search** — look for commits referencing this issue ID across all branches:
-
-   ```bash
-   git -C $PROJECT_ROOT log --all --oneline --grep="{jiraId}" --since="8 weeks ago"
-   ```
-
-2. **Affected file history** — after identifying key files (from issue description keywords), check recent changes:
-
-   ```bash
-   git -C $PROJECT_ROOT log --oneline --since="4 weeks ago" -- {affected_file_paths}
-   ```
-
-3. **Jira comments/status** — fetch latest comments to see if someone reported a fix:
-   ```bash
-   curl -s -H "Authorization: Bearer $JIRA_TOKEN" \
-     "$JIRA_BASE/issue/{jiraId}?fields=status,comment&expand=changelog" \
-     | jq '.fields.status.name, .fields.comment.comments[-3:][]?.body'
-   ```
-
-**If prior fix commit(s) found:**
-
-```
-This issue appears to already have been addressed:
-  {hash} — {message} (by {author}, {date})
-
-Options:
-  1. Verify fix (check if cherry-pick/merge to base branch is needed)
-  2. Stop pipeline (already resolved)
-  3. Continue anyway (different fix needed)
-```
-
-- Option 1 → Check if the commit exists on `baseBranch`. If not, suggest cherry-pick. Pipeline pauses.
-- Option 2 → Cleanup and exit:
-  1. Checkout back to base branch: `git -C $PROJECT_ROOT checkout {baseBranch}`
-  2. Delete the created branch: `git -C $PROJECT_ROOT branch -D {branch}`
-  3. If worktree was used: `git -C $PROJECT_ROOT worktree remove {worktreePath} --force`
-  4. Set `agent-state.json` status to `"stopped_already_fixed"`. Log and exit.
-- Option 3 → Continue to Step 1 as normal.
-
-**If no prior fix found** → continue to Step 1.
+Before any analysis, check if this issue was already fixed by someone else. Three signals (git commit grep on issue ID over 8 weeks, recent file-path history over 4 weeks, Jira/issue comments). On hit → prompt: Verify (cherry-pick path) / Stop (cleanup + `stopped_already_fixed` state) / Continue. Miss → Step 1. Full check commands, prompt block, and cleanup commands: `refs/features/prior-fix-detection.md`.
 
 #### Step 1 — Knowledge Injection (cached context)
 
@@ -90,63 +47,14 @@ Exit 0 with empty output = pref off or no memory on disk — skip. Otherwise the
 
 #### Step 1.5 — External Context Injection (`state.contextLinks[]`)
 
-Phase 0 Step 1b catalogued every typed external link from the task description into `state.contextLinks[]`. Phase 1 now dispatches each entry to its matching fetcher and prepends the result to the analysis prompt under a **Referenced External Sources** section, so the agent doesn't re-discover what the ticket already pointed at.
-
-```bash
-jq -c '.contextLinks // []' "$STATE_FILE" \
-  | python3 -c '
-import json, sys, os
-links = json.loads(sys.stdin.read() or "[]")
-by_type = {}
-for l in links:
-    by_type.setdefault(l["type"], []).append(l)
-print(json.dumps(by_type))
-' > /tmp/context-by-type-${TASK_ID}.json
-```
-
-Dispatch table — one fetcher per type. Each fetcher emits a normalized JSON view that the analysis prompt consumes as ground truth for the referenced source.
-
-| Type | Fetcher | Output stored in |
-|---|---|---|
-| `crashlytics` | `~/.claude/lib/fetch-crashlytics.sh <url>` (already invoked in Phase 0 Step 1b.1 for the legacy `state.crashContext` field; Phase 1 reads that field directly) | `state.crashContext` |
-| `fortify` | `~/.claude/lib/fetch-fortify.sh <url>` (already invoked in Phase 0 Step 1b.2 for the legacy `state.fortifyFinding` field; Phase 1 reads that field, Phase 4 reads the full payload for the security gate) | `state.fortifyFinding` |
-| `swagger` | `~/.claude/lib/fetch-swagger.sh <url>` → endpoints[], request/response examples | `state.fetchedContext.swagger[]` |
-| `confluence` | `~/.claude/lib/fetch-confluence.sh <url>` → page body, code blocks, extracted API contracts | `state.fetchedContext.confluence[]` |
-| `figma` | `~/.claude/lib/fetch-figma.sh <url>` (via existing MCP / REST fallback path) when the task is a component; otherwise advisory only | `state.fetchedContext.figma[]` |
-| `generic-doc` | no automatic fetcher — surfaced as advisory; the agent uses WebFetch on demand when the URL turns out to be load-bearing | n/a |
+Phase 0 Step 1b catalogued every typed external link from the task description into `state.contextLinks[]`. Phase 1 dispatches each entry to its matching fetcher (crashlytics, fortify, swagger, confluence, figma, generic-doc) and prepends results under a **Referenced External Sources** section in the analysis prompt — so the agent doesn't re-discover what the ticket already pointed at. Failures never fatal; pending refs are advisories. Full dispatch table, exit-code handling, prompt injection shape, log line shape: `refs/features/external-context-injection.md`.
 
-Each fetcher exit code is treated as follows:
-- `0` (success) → output appended to `state.fetchedContext.<type>[]` and injected into the prompt.
-- `2` (blocked / missing token) → run the inline Token Save Flow per `setup.md`; on skip, mark the entry as `{status: "skipped", reason: "missing-token"}` and continue.
-- `3` (network/auth) → mark as `{status: "failed", reason: "<exit-msg>"}`, continue.
-- `4`/`5`/`6` (config errors) → mark as `{status: "failed", reason: "<exit-msg>"}`, continue and log a setup hint.
-
-Failures are never fatal at Phase 1 — the agent still runs analysis, just without the referenced source.
-
-**Prompt injection shape** (added immediately after the knowledge-injection block, before codebase exploration):
-
-```
-## Referenced External Sources
-
-(when fetchers populated `state.fetchedContext.<type>`)
-### <type> — <url>
-<fetched content, scoped to relevance>
-
-(when fetcher pending)
-### Pending references
-- <type>: <url> — <one-line metadata>
-```
-
-The agent treats fetched content as **ground truth** for the referenced source (no re-discovery, no contradiction). Pending references are advisories — the agent decides whether to fetch via WebFetch on demand when the task hinges on that source.
-
-**Log line shape**:
+**Log line shape** (progress contract):
 
 ```
 → context injection: total=<N>, fetched=<n>, pending=<n>, by-type={swagger:F/P, confluence:F/P, ...}
 ```
 
-`F` = fetched, `P` = pending. Empty contextLinks → `total=0`, skip the section entirely.
-
 #### Step 2 — Stack Detection
 
 Detect the project's tech stack to load appropriate skills and tooling throughout the pipeline. Auto-detect by scanning `$PROJECT_ROOT` (maxdepth 2) for project markers:
@@ -171,32 +79,7 @@ This informs:
 
 #### Step 2.5 — Repo Map Injection (advisory, opt-in)
 
-**Gated by `prefs.global.repoMap.enabled`** (default: `false`). Pattern source: <https://aider.chat/docs/repomap.html>.
-
-Before launching Explore agents, run the deterministic repo map renderer and inject the result into each Explore prompt as `${REPO_MAP}`. This gives every explorer a token-budgeted overview of the most-referenced files in the repo — ranked via cross-file declaration references with TF-IDF-style credit splitting so universally-shared helper names (`pass`, `fail`, `init`) don't dominate.
-
-```bash
-REPO_MAP=""
-if [ "$(jq -r '.global.repoMap.enabled // false' "$PREFS")" = "true" ]; then
-  BUDGET=$(jq -r '.global.repoMap.tokenBudget // 1500' "$PREFS")
-  TOP=$(jq -r '.global.repoMap.topFiles // 25' "$PREFS")
-  INCLUDE=$(jq -r '.global.repoMap.include // empty' "$PREFS")
-  EXCLUDE=$(jq -r '.global.repoMap.exclude // empty' "$PREFS")
-  args=(--root "$WORKTREE" --budget "$BUDGET" --top "$TOP" --format md)
-  [ -n "$INCLUDE" ] && args+=(--include "$INCLUDE")
-  [ -n "$EXCLUDE" ] && args+=(--exclude "$EXCLUDE")
-  REPO_MAP=$(node pipeline/scripts/repo-map.mjs "${args[@]}" 2>/dev/null || echo "")
-fi
-```
-
-**Properties:**
-
-- **Deterministic** — same worktree state → same map. No embeddings, no network. Sub-second on monorepos.
-- **Advisory** — Explore agents may ignore the map if they have stronger signals (Phase 0 knowledge cache, explicit user context). Never gates the pipeline.
-- **Truncation-safe** — output is capped at `tokenBudget`; the script falls back to "no files extracted within budget" rather than over-spending.
-- **Cost ledger** — emit `phase-1.repo_map_emitted bytes=$(wc -c <<<"$REPO_MAP") budget=$BUDGET` so Phase 7 cost summary can show the size injected.
-
-**When to enable:** large repos (>200 source files) where Explore otherwise spends multiple rounds finding the right starting files. Skip on small repos — the overhead exceeds the gain.
+Gated by `prefs.global.repoMap.enabled` (default: `false`). When enabled, runs `pipeline/scripts/repo-map.mjs` and injects the budgeted result into each Explore prompt as `${REPO_MAP}`. Aider-style: deterministic, no embeddings, sub-second, advisory only. Full wiring (helper invocation, properties, when-to-enable): `refs/features/repo-map.md`.
 
 #### Step 3 — Codebase Exploration
 

package/pipeline/commands/multi-agent/refs/phases/phase-3-dev.md

@@ -10,47 +10,9 @@
 
 Phase 3 consumes the Phase 2 output object conforming to `pipeline/schemas/planning-output.schema.json` — the task graph (`tasks[]` with `id`, `subject`, `targetFiles`, `complexity`, `blockedBy`) plus the architecture review notes. Tasks execute in dependency order; the schema's `blockedBy` field drives the ready-task picker. In `--dev` mode (no Phase 2), Sonnet/Opus generates the equivalent task list inline before entering the loop below.
 
-**Plan Todo iteration (opt-in)**: when `prefs.global.planTodos.enabled` is true and Phase 2 Step 4.5 emitted a `plan.todos[]` (conforming to `pipeline/schemas/plan-todos.schema.json`), Phase 3 iterates with the helper instead of walking `tasks[]` directly:
+**Plan Todo iteration (opt-in)**: gated by `prefs.global.planTodos.enabled` (default: `false`). When enabled and Phase 2 Step 4.5 emitted a `plan.todos[]`, Phase 3 iterates via `pipeline/lib/plan-todos.sh next/start/complete/fail` instead of walking `tasks[]` directly. When disabled, the loop walks `tasks[]` from `planning-output` — TDD contract is unchanged. Full helper loop + state semantics: `refs/features/plan-todos.md`.
 
-```bash
-while next=$(bash "$HOME/.claude/lib/plan-todos.sh" next "$TASK_ID"); [ -n "$next" ]; do
-  id=$(printf '%s' "$next" | cut -f1)
-  task=$(printf '%s' "$next" | cut -f2)
-  bash "$HOME/.claude/lib/plan-todos.sh" start "$TASK_ID" "$id"
-  # ... TDD cycle for "$task" ...
-  if build_passed; then
-    bash "$HOME/.claude/lib/plan-todos.sh" complete "$TASK_ID" "$id" "${COMMIT_HASH} · tests:${TEST_COUNT}"
-  else
-    bash "$HOME/.claude/lib/plan-todos.sh" fail "$TASK_ID" "$id" "build failed after 3 retries"
-    break
-  fi
-done
-```
-
-When disabled, the loop still walks `tasks[]` from `planning-output` — `plan-todos.sh` adds visibility (status, notes, deps-respecting `next`) but the underlying TDD contract is unchanged.
-
-**Shadow-Git checkpoints (opt-in)**: when `prefs.global.shadowGit.enabled` is true, the orchestrator snapshots the worktree via `pipeline/lib/shadow-git.sh` so sub-phase rollback is possible without polluting the project's real `.git` history. Pattern source: Cline checkpoints (<https://docs.cline.bot/features/checkpoints>).
-
-```bash
-# Phase 0 (one-time per task): initialize shadow repo + baseline snapshot.
-bash "$HOME/.claude/lib/shadow-git.sh" init "$TASK_ID" "$WORKTREE"
-
-# Per-step (mode: per-todo-step — default): snapshot AFTER each plan-todos
-# step completes successfully, so restore lands on a known-good state.
-bash "$HOME/.claude/lib/plan-todos.sh" complete "$TASK_ID" "$id" "$notes"
-bash "$HOME/.claude/lib/shadow-git.sh" snapshot "$TASK_ID" "$WORKTREE" "step $id: $task"
-
-# Per-mutation (mode: per-tool-call): the orchestrator hooks into every Edit/
-# Write/MultiEdit/Bash-mutation tool call. Higher fidelity, ~50ms × tool-call
-# overhead — recommended only for security-critical paths or experimental
-# refactors where the user values fine-grained rollback over speed.
-
-# Rollback on demand (interactive helper):
-bash "$HOME/.claude/lib/shadow-git.sh" list "$TASK_ID"
-bash "$HOME/.claude/lib/shadow-git.sh" restore "$TASK_ID" "$WORKTREE" <sha> --files
-```
-
-Shadow repo location: `~/.claude/state/shadow-git/<task-id>/.git/`. Storage cap: `prefs.shadowGit.pruneAfterDays` (default 14). `/multi-agent:purge` honors this prune; manual cleanup via `shadow-git.sh prune <task-id>`.
+**Shadow-Git checkpoints (opt-in)**: gated by `prefs.global.shadowGit.enabled` (default: `false`). When enabled, the orchestrator snapshots the worktree via `pipeline/lib/shadow-git.sh` so sub-phase rollback is possible without touching the project's real `.git` history. Cline-style. Lifecycle: `shadow-git.sh init` (Phase 0 baseline), `shadow-git.sh snapshot` (per step after `plan-todos complete`), `shadow-git.sh restore <sha> --files` (rollback). Modes: `per-todo-step` (default) or `per-tool-call`. Full wiring + storage cap: `refs/features/shadow-git.md`.
 
 #### Component tasks — delegated dispatch (taskType === "component")
 
@@ -239,40 +201,7 @@ release_build_lock() { rm -rf "$BUILD_LOCK"; }
 
 #### Step 3.5 — Dev Critic (Evaluator-Optimizer, opt-in)
 
-**Pattern**: Anthropic's evaluator-optimizer from "Building Effective Agents" (Dec 2024). Generator (Phase 3 Dev) and critic (`agents/dev-critic.md`) loop on deterministic criteria already written in `rules/*.md` before any Phase 4 reviewer call.
-
-**Gated by `prefs.global.devCritic.enabled`** (default: `false`). When enabled, after the generator's last edit and BEFORE Phase 4:
-
-1. Dispatch `dev-critic` sub-agent (Sonnet by default, tools: `Read, Grep, Glob, Bash`).
-2. Critic runs 4 mandatory deterministic gates (build / lint / test / secrets) — failure of any → `pass: false` with `blocking` finding.
-3. If gates green, critic walks the platform checklist (iOS 13-item / Android Kotlin / Backend generic — selected by Phase 1 `detectedStack`).
-4. Returns schema-validated JSON (`pipeline/schemas/dev-critic-output.schema.json`): `{pass, iteration, gates, findings[], escalate}`.
-
-**Loop cap (STRICT)**: max **2** iterations.
-
-| Round | Behavior |
-|---|---|
-| 1 | Full critic pass — all gates + full checklist |
-| 2 | Re-check only round-1 failures. No new findings allowed (scope creep prevention) |
-| 3+ | NOT ALLOWED. Critic returns `escalate: true`; orchestrator pauses (interactive) or proceeds to Phase 4 with logged failure (autopilot) |
-
-**Action by severity:**
-
-- `blocking` → generator MUST fix; another Dev iteration before re-critic
-- `important` → generator SHOULD fix; if skipped, pass through to Phase 4 (legitimate reviewer ground)
-- `suggestion` → generator's judgement; never blocks round 2
-
-**Telemetry**: each critic call emits `dev_critic.call` with `iteration`, `pass`, `gates_failed`, `blocking`, `important`, `duration_ms`, `tokens_in/out`. Phase 7 cost rollup lists these as `phase 3.5` line items so the net saving (Phase 4 reviewer/triage calls avoided) is measurable.
-
-**Off by default reason**: introduces ~1× Sonnet call per Dev iteration. On simple bug fixes the cost outweighs the benefit (Phase 4 would have caught the same thing for similar cost). Recommended on:
-
-- Feature work (≥200 LOC diff)
-- Security-touching paths (auth, keychain, network)
-- Multi-file refactors where rule violations compound
-
-**Reference**: see `pipeline/agents/dev-critic.md` for the full agent specification (mandatory gates, checklist enumeration, output schema, severity semantics).
-
-**Why this fits orchestrator-workers + evaluator-optimizer hybrid**: Phase 4 is parallelization-with-voting — good for *adversarial* perspectives (security, architecture). Phase 3.5 is evaluator-optimizer — good for *deterministic* criteria (build, tests, checklists). Sending failing builds into Phase 4 wastes 2–3 reviewer calls + Opus triage; Phase 3.5 absorbs that cost at one Sonnet call.
+Gated by `prefs.global.devCritic.enabled` (default: `false`). When enabled, after the generator's last edit and BEFORE Phase 4: dispatch `dev-critic` sub-agent (Sonnet), run 4 deterministic gates (build / lint / test / secrets), then platform checklist. STRICT loop cap — **max 2 iterations** (round 2 re-checks round-1 failures only); round 3+ returns `escalate: true`. Severity routing: `blocking` → generator must fix; `important` → SHOULD fix or pass through to Phase 4; `suggestion` → generator's judgement. Full agent contract, schema, telemetry, when-to-enable: `refs/features/dev-critic.md` + `pipeline/agents/dev-critic.md`.
 
 ---
 
@@ -302,7 +231,7 @@ When `agent-state.json.onlyDevelop === true`, Phase 3 runs self-contained with *
 
 ---
 
-#### Multi-Repo Mode
+#### v2.1.0+ Multi-Repo Mode
 
 Active when `state.projects[].length > 1` (set by Phase 0 multi-select). Single-repo flow above is preserved verbatim — this section adds the deltas.
 

package/pipeline/commands/multi-agent/refs/phases/phase-6-commit.md

@@ -216,7 +216,7 @@ Before creating PR, ask: "DRAFT or READY? [1/2], default 1" — DRAFT blocks mer
 
 ---
 
-#### Multi-Repo Mode
+#### v2.1.0+ Multi-Repo Mode
 
 Active when `state.projects[].length > 1`. The single-repo flow above is preserved verbatim — multi-repo is an extension, not a replacement.
 

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

@@ -259,19 +259,23 @@ pbcopy < /dev/null
 
 (The shell driver auto-delegates to `~/.claude/scripts/keychain.py` on macOS / Linux, which writes both `-l` (label) and `-s` (service) attributes so callers using either convention find the same entry.)
 
-For JSON file (Firebase):
+For JSON file (Firebase) — same clipboard flow, JSON content never lands in argv or shell history:
 ```
-  Download the JSON file, then press Enter.
-  (File will be base64-encoded and saved to Keychain automatically)
+  Open the Service Account JSON, copy its FULL contents to your clipboard,
+  then press Enter.
+  (Contents will be base64-encoded and saved to Keychain automatically)
 
-  Path to JSON file [~/Downloads/firebase-sa.json]: ___
+  Press Enter when ready...
 ```
 
 Pipeline runs silently:
 ```bash
-~/.claude/lib/credential-store.sh set "<KEY_NAME>" "$(base64 < <PATH>)"
+pbpaste | base64 | ~/.claude/lib/credential-store.sh set "<KEY_NAME>" "$(cat)"
+pbcopy < /dev/null   # clear clipboard
 ```
 
+Linux substitutes: `xclip -selection clipboard -o` or `wl-paste` for `pbpaste`; matching clear command for `pbcopy < /dev/null`. The shell driver detects platform and routes accordingly (see `~/.claude/lib/credential-store.sh`).
+
 For GitHub (special case):
 ```
   ! gh auth login
@@ -699,7 +703,11 @@ pbcopy < /dev/null  # clear clipboard
 # Plain text (direct value)
 ~/.claude/lib/credential-store.sh set "<SERVICE_NAME>" "<VALUE>"
 
-# JSON file (base64 encode)
+# JSON file from clipboard (preferred — no file path leaks into history)
+pbpaste | base64 | ~/.claude/lib/credential-store.sh set "<SERVICE_NAME>" "$(cat)"
+pbcopy < /dev/null
+
+# JSON file from disk (fallback when clipboard backend unavailable)
 ~/.claude/lib/credential-store.sh set "<SERVICE_NAME>" "$(base64 < /path/to/file.json)"
 
 # Read