@mmerterden/multi-agent-pipeline 8.6.0 → 8.6.2

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 |
@@ -46,38 +46,24 @@ Full version history lives in [CHANGELOG.md](./CHANGELOG.md). Every release entr
 
 - Node.js 18+
 - Claude Code (https://claude.ai/code) **or** GitHub Copilot CLI
-- macOS/Linux (Keychain-based token storage is available on macOS)
-
-This is a **private package** hosted on GitHub Packages. You need:
-
-1. **Collaborator access** to `mmerterden/multi-agent-pipeline` (granted by the repo owner).
-2. A **Classic** Personal Access Token (fine-grained PATs are not fully supported for GitHub Packages on private repos).
-
-### 1. Create a Classic PAT
-
-Go to https://github.com/settings/tokens/new?scopes=read:packages,repo and create a token with:
-
-- ✅ `read:packages`
-- ✅ `repo` (required for private package access)
-
-If your GitHub account belongs to an SSO-enforced organization, after creating the token click **"Configure SSO" → Authorize** on the token row.
-
-### 2. Configure `~/.npmrc`
-
-```bash
-# Replace ghp_xxx with the token from step 1
-echo "@mmerterden:registry=https://npm.pkg.github.com" >> ~/.npmrc
-echo "//npm.pkg.github.com/:_authToken=ghp_xxx"        >> ~/.npmrc
-```
-
-### 3. Verify access
+- macOS, Linux, or Windows (Git Bash / WSL). Native credential storage everywhere:
+  - **macOS** → Keychain (`security`)
+  - **Linux** → libsecret (`secret-tool` — `apt install libsecret-tools` / `dnf install libsecret`)
+  - **Windows** → Credential Manager (PowerShell `CredentialManager` module — `Install-Module CredentialManager`)
+- Runtime CLIs the pipeline shells out to:
+  - `gh` (GitHub CLI) for issue / PR flows
+  - `jq` for JSON parsing
+  - `python3` (stdlib only, used by the deterministic keychain helper)
+  - `bash` 4+
+
+The package is **public on npmjs.org** — no auth, no PAT, no `~/.npmrc` setup needed:
 
 ```bash
 npm view @mmerterden/multi-agent-pipeline version
-# → prints "3.0.0" (or newer) when everything is wired up
+# → prints "8.6.1" (or newer)
 ```
 
-If this fails, see [Troubleshooting](#troubleshooting) below.
+If `npm view` shows a stale version, run `npm cache clean --force` and retry.
 
 > **New here?** Worked end-to-end transcripts live in [`examples/`](./examples/) — bug fix from Jira, feature in autopilot, `--dev` fast path, and recovery from a broken run. Read one before you run the pipeline on your own code.
 >
@@ -87,9 +73,9 @@ If this fails, see [Troubleshooting](#troubleshooting) below.
 
 ## Quick Start
 
-### Option A — Install from source (recommended, no registry auth)
+### Option A — Install from source (recommended for development)
 
-The simplest path. Works even if you haven't configured `~/.npmrc` yet.
+Clone the repo and run the installer directly — full read access to source files.
 
 ```bash
 git clone git@github.com:mmerterden/multi-agent-pipeline.git
@@ -127,7 +113,7 @@ This discovers your Keychain tokens (Jira, Bitbucket, GitHub, etc.), sets up you
 
 Update later with `git pull && npm install` inside the clone. Pin to a specific version by checking out the corresponding tag (`git tag -l` to list).
 
-### Option B — npx (requires registry setup above)
+### Option B — npx (public registry, no auth)
 
 ```bash
 npx @mmerterden/multi-agent-pipeline install            # Claude Code (default)
@@ -143,7 +129,7 @@ npx @mmerterden/multi-agent-pipeline uninstall          # interactive, all targe
 npx @mmerterden/multi-agent-pipeline uninstall --dry-run # preview only
 ```
 
-### Option C — Global install (requires registry setup above)
+### Option C — Global install (public registry, no auth)
 
 ```bash
 npm install -g @mmerterden/multi-agent-pipeline
@@ -177,32 +163,27 @@ slows down the install.
 
 ### `sh: multi-agent-pipeline: command not found`
 
-npx couldn't fetch the package and fell back to running it as a shell command. Registry auth is missing or wrong — re-check steps 1–3 under [Prerequisites](#prerequisites).
+`npx` couldn't fetch the package. Most common causes:
 
-### `npm error code E401` — "User cannot be authenticated with the token provided"
+- Network blocked or proxy in front of npmjs.org.
+- Stale npx cache — `npx clear-npx-cache` then retry.
+- Wrong package name (it is `@mmerterden/multi-agent-pipeline`, with the scope).
 
-Your token is being rejected by GitHub Packages. Usually one of:
-
-- PAT is fine-grained instead of **Classic**. Recreate as Classic.
-- PAT is missing `repo` scope. Private packages require both `read:packages` **and** `repo`.
-- SSO not authorized. On the token row, click **"Configure SSO" → Authorize** for the relevant org.
-- Token expired or revoked.
+### `npm error code E404` on `registry.npmjs.org`
 
-Quick diagnostic:
+The package wasn't reachable. Quick checks:
 
 ```bash
-curl -I -H "Authorization: Bearer $(grep _authToken ~/.npmrc | tail -1 | cut -d= -f2)" \
-  https://npm.pkg.github.com/@mmerterden%2Fmulti-agent-pipeline
+curl -fsSL "https://registry.npmjs.org/@mmerterden/multi-agent-pipeline" | jq -r '."dist-tags".latest'
+# Should print 8.6.1 (or newer)
 ```
 
-- `200` — auth is fine; likely an npx cache issue (`npx clear-npx-cache`).
-- `401` — token invalid, expired, or not SSO-authorized.
-- `403` — token valid but no repo access. Ask the repo owner to add you as a collaborator.
-- `404` — scope misconfigured in `~/.npmrc`, or package name is wrong.
+- If this prints a version → your local npm cache is stale; run `npm cache clean --force` and retry.
+- If it 404s → registry outage or scope/package-name typo. Verify the URL hits the JSON above.
 
-### `npm error code E404` on `registry.npmjs.org`
+### Older PAT / GitHub Packages docs
 
-Your `~/.npmrc` does not have the `@mmerterden:registry=...` line. npm defaulted to public npm, which doesn't host this package. Redo step 2.
+Earlier README revisions referenced GitHub Packages with a Classic PAT and `~/.npmrc` setup. The package moved to **public npmjs.org** in v8.6.1; no token, no `~/.npmrc` line is needed. If you set one up previously, you can leave it — it just won't be consulted.
 
 ## Tool support
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "8.6.0",
+  "version": "8.6.2",
   "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/_account-picker.md

@@ -75,7 +75,7 @@ was used last and surfaces it first on the next autopilot invocation.
 
 ```json
 {
-  "accountId": "m-erden3",
+  "accountId": "my-account",
   "accountPrefix": "${USER}",
   "tokens": {
     "github": "${USER}_Github_Access_Token",

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