@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/commands/multi-agent/refs/tracker-contract.md

@@ -0,0 +1,256 @@
+---
+description: "Phase tracker mandatory contract — every mode depends on this. Native TaskList widget renders the phase tiles to the user; phase-tracker.sh holds the state file (powers :resume / :log / :status)."
+---
+
+# Phase Tracker — Mandatory Contract
+
+> **TLDR** — At every phase boundary the agent does two things: (1) writes to the state file via `phase-tracker.sh` (identical on every CLI), (2) drives the visual channel for the CLI it's running in — `TaskCreate`/`TaskUpdate` in Claude Code, `phase-tracker.sh render` in every other CLI. The state file alone is not enough; the user must see the phases progress.
+
+## Why two channels
+
+| Channel | Job | Lives in |
+|---|---|---|
+| **Visual** (CLI-specific) | The widget or card the user actually sees | CLI-specific (TaskList, chat output, stdout) |
+| **`phase-tracker.sh` state** | JSON state file (`~/.claude/logs/multi-agent/<task_id>/tracker-state.json`) — read by `:resume`, `:log`, `:status` | Disk — survives the session, **identical across CLIs** |
+
+Both channels carry the same state. If one is missing:
+- Visual only → `:resume` does not work; the run history is lost
+- State file only → the user sees no progress, only bash stdout snapshots
+
+## Visual channel — chosen by the agent based on the host CLI
+
+The agent detects which CLI it's running in and uses the appropriate visual mechanism. Detection order:
+
+```
+1. system prompt mentions "Claude Code"             → claude-code
+2. system prompt mentions "Copilot" / "GitHub Copilot" → copilot
+3. system prompt mentions "Cursor"                   → cursor
+4. system prompt mentions "Cascade" / "Windsurf"     → windsurf
+5. None of the above                                 → generic (bash stdout)
+```
+
+Visual mechanism per CLI:
+
+| CLI | What the agent calls at every phase boundary |
+|---|---|
+| **claude-code** | `TaskCreate({subject, activeForm})` then `TaskUpdate({status, activeForm})`. Native sticky widget; ⏺ tiles, spinner header. |
+| **copilot** | Inline call: `bash phase-tracker.sh render`. The bordered ANSI card lands as the last tool result in the chat. |
+| **cursor / windsurf / cline** | Same bash render — Cursor / Windsurf chat panels render the ANSI card cleanly. Do not wrap in markdown; raw output is correct. |
+| **generic** (plain shell, Git Bash, WSL, tmux) | Same bash render — the bordered ANSI card prints to terminal stdout in place. |
+
+**Common to every CLI**: `phase-tracker.sh add/update/meta/tokens` calls run identically → the state file is always correct, and `:resume` / `:log` / `:status` work on every CLI.
+
+**Claude Code only**: in addition, `TaskCreate` / `TaskUpdate` native tool calls → the sticky widget pins the phase stack in the user's view.
+
+## Call pattern
+
+At every phase boundary the agent takes **two steps**:
+
+1. **State**: `phase-tracker.sh add/update/meta/tokens` (identical on every CLI, never changes)
+2. **Visual**: CLI-specific — TaskList API on claude-code, `phase-tracker.sh render` on every other CLI
+
+### Phase 0 startup — pipeline init
+
+```bash
+TASK_ID="<id from input parsing>"   # PROJ-12345 / repo#316 / cwd-derived
+bash $HOME/.claude/scripts/phase-tracker.sh init "$TASK_ID"
+```
+
+Phases by mode:
+
+| Mode | Phases |
+|---|---|
+| Full pipeline | 0,1,2,3,4,5,6,7 |
+| `--dev` | 0,3,6,7 |
+| `--autopilot`, `--dev autopilot` | same as dev, with confirmations skipped |
+
+Register each phase:
+
+```bash
+bash $HOME/.claude/scripts/phase-tracker.sh add 0 "Init"
+bash $HOME/.claude/scripts/phase-tracker.sh add 1 "Analysis"
+# ...
+```
+
+### Claude Code — also register a TaskList tile per phase
+
+```text
+For each phase in the current mode, IN PHASE-NUMBER ORDER (0 → 1 → 2 → … → 7):
+  TaskCreate({
+    subject: "Phase 0: Init",
+    description: "Repo discovery, branch, worktree, identity bind",
+    activeForm: "Initializing pipeline"
+  })
+  → returns taskId
+  bash phase-tracker.sh meta 0 tasklist_id "<taskId>"
+```
+
+The `tasklist_id` meta field is persisted so that `:resume` can rebuild the TaskList from the state file in a fresh session.
+
+#### TaskCreate ordering (strict)
+
+**The native TaskList widget renders tiles in TaskCreate creation order, NOT by phase-number metadata.** Therefore:
+
+> **All TaskCreate calls for the active mode's phase set MUST fire in strict phase-number order BEFORE any TaskUpdate is applied. No "pre-mark skipped phases as completed before Phase 0" reasoning is permitted — even when the agent knows in advance that a phase will be skipped.**
+
+Why: an agent reasoning "this is a `--dev` task, so phases 1/2/4 will be skipped — let me TaskCreate them as completed first" produces tile IDs `1, 2, 3, …` for phases 1/2/4, then the Phase 0 tile gets ID `4` and visually drops below them. The user sees `1, 2, 4 ✓ · 0 ▶ · 3 ☐ · …` instead of `0 ▶ · 1 ✓ · 2 ✓ · 3 ☐ · 4 ✓ · …`.
+
+The correct sequence is **always**:
+
+```text
+# Step A — register every phase tile in the active mode's set, in phase-number order
+TaskCreate(Phase 0)  → taskId₀
+TaskCreate(Phase 1)  → taskId₁     # even if Phase 1 will be skipped in this mode
+TaskCreate(Phase 2)  → taskId₂
+TaskCreate(Phase 3)  → taskId₃
+TaskCreate(Phase 4)  → taskId₄     # even if Phase 4 will be skipped in this mode
+TaskCreate(Phase 5)  → taskId₅
+TaskCreate(Phase 6)  → taskId₆
+TaskCreate(Phase 7)  → taskId₇
+
+# Step B — only AFTER every tile is created, apply status updates
+TaskUpdate(taskId₀, status="in_progress")              # Phase 0 starts
+# `--dev` mode immediately also fires:
+TaskUpdate(taskId₁, status="completed", activeForm="[SKIPPED]")
+TaskUpdate(taskId₂, status="completed", activeForm="[SKIPPED]")
+TaskUpdate(taskId₄, status="completed", activeForm="[SKIPPED]")
+```
+
+Mode-specific phase sets:
+
+| Mode | TaskCreate set (in order) |
+|---|---|
+| Full pipeline (`/multi-agent`, `:autopilot`, `:local`, `:local-autopilot`) | 0 → 1 → 2 → 3 → 4 → 5 → 6 → 7 (all 8) |
+| `:dev`, `:dev-autopilot`, `:dev-local`, `:dev-local-autopilot` | 0 → 3 → 5 → 6 → 7 (5 phases — 1/2/4 omitted entirely) |
+
+Note: in `--dev` modes the omitted phases (1, 2, 4) **do not get TaskCreate calls at all** — they're not part of the mode's phase set. The "[SKIPPED]" pattern above only applies if a normally-included phase is conditionally skipped at runtime.
+
+**Enforcement**: `smoke-tasklist-ordering.sh` scans every mode entry point doc (`commands/multi-agent.md`, `commands/multi-agent/{autopilot,local,local-autopilot,dev,dev-autopilot,dev-local,dev-local-autopilot}.md` + Copilot mirrors) for the explicit "in phase-number order" rule. Inventory drift fails the smoke.
+
+### Other CLIs — call render after every state change
+
+There is no TaskList outside Claude Code. Instead, after each state change the agent calls:
+
+```bash
+bash $HOME/.claude/scripts/phase-tracker.sh render
+```
+
+This prints a bordered ANSI card to the chat. The user sees the up-to-date phase table as the last tool result. Do not wrap in markdown — raw bash output is correct.
+
+### Phase entry
+
+**Claude Code:**
+```text
+TaskUpdate({taskId: <saved>, status: "in_progress"})
+bash phase-tracker.sh update <N> in_progress
+```
+
+**Other CLIs:**
+```bash
+bash $HOME/.claude/scripts/phase-tracker.sh update <N> in_progress
+bash $HOME/.claude/scripts/phase-tracker.sh render
+```
+
+### Phase exit
+
+**Claude Code:**
+```text
+TaskUpdate({taskId: <saved>, status: "completed"})
+bash phase-tracker.sh update <N> completed
+```
+
+**Other CLIs:**
+```bash
+bash $HOME/.claude/scripts/phase-tracker.sh update <N> completed
+bash $HOME/.claude/scripts/phase-tracker.sh render
+```
+
+`failed` and `skipped` follow the same pattern, with the matching status.
+
+### Active phase — "what is it doing right now"
+
+**Claude Code** — `TaskUpdate({activeForm: ...})` updates the spinner header:
+```text
+TaskUpdate({taskId: <dev_task>, activeForm: "Editing TopBarView.swift"})
+TaskUpdate({taskId: <dev_task>, activeForm: "Running xcodebuild test"})
+```
+
+**Other CLIs** — `meta Now` key plus a render call:
+```bash
+bash $HOME/.claude/scripts/phase-tracker.sh meta 3 Now "→ editing TopBarView.swift"
+bash $HOME/.claude/scripts/phase-tracker.sh render
+```
+
+The `Now` meta key shows up in the bordered card as `Now: → editing TopBarView.swift`.
+
+### 5. Token accounting — automatic (manual top-up optional)
+
+The native TaskList header automatically prints `↑Nk tokens · thought for Ns` — Claude Code uses session-level metrics. For per-phase token attribution:
+
+```bash
+bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <input_count> <output_count>
+```
+
+Token counts are additive — multiple calls accumulate. Stored per phase in the state file; surfaced in `:log` reports.
+
+### 6. Phase context — rich summaries via `meta`
+
+Store a per-phase summary in the state file:
+
+```bash
+bash $HOME/.claude/scripts/phase-tracker.sh meta <N> "<key>" "<value>"
+```
+
+`:log` and `:status` reports surface this meta. Suggested keys:
+
+| Phase | Keys |
+|---|---|
+| 0 Init | Account, Source, Repos, Branch, Worktree, Identity, Board |
+| 1 Analysis | Explorers, Findings |
+| 2 Planning | Steps, Risks |
+| 3 Dev | Model, Files, Tests, Build, WIP |
+| 4 Review | Gates, Reviewers, Verdict |
+| 5 Test | Scenarios, Result |
+| 6 Commit | Branch, Push, PR, Jira |
+| 7 Report | Channels, Artifacts |
+
+Meta keys are overwritten — values update as the pipeline progresses.
+
+### 7. Sub-phase (optional, e.g. Phase 1 explorers)
+
+There is no nested TaskList for sub-phases — sub-progress is reflected in `activeForm` plus a `sub` record in the state file.
+
+```bash
+bash $HOME/.claude/scripts/phase-tracker.sh sub <N> <sub_id> "<sub name>" in_progress
+```
+
+```text
+TaskUpdate({taskId: <phase_task>, activeForm: "Running explorer: repo-map"})
+```
+
+## Resume behaviour
+
+When `/multi-agent:resume <task_id>` is called:
+1. The state file is loaded and the phase list is read.
+2. `TaskCreate` is called again for every phase (new task IDs are issued for the new session).
+3. Each phase's status is re-applied via `TaskUpdate` based on the state file.
+4. The active phase is determined and the agent picks up where it left off.
+
+The `tasklist_id` meta from the previous session is replaced with the new IDs during resume.
+
+## Anti-patterns
+
+❌ **TaskList only** → `:resume` will not work; no run history is preserved.
+❌ **`phase-tracker.sh` only** in Claude Code → the user sees no widget, only bash stdout snapshots — the #1 source of "I see no phases" complaints.
+❌ **Wiring `phase-tracker.sh render` to `statusLine` config** → it drops below the screen as a placeholder; the user complained, removed in v7.9.0.
+
+## Verification
+
+`smoke-tracker-contract.sh` greps every mode dispatch file for the contract reference. Adding a new mode means adding the same contract section.
+
+## Cross-reference
+
+- `refs/phases.md` § "Visual Phase Tracker" (canonical spec)
+- `refs/progress-contract.md` (one-line stdout format, runs alongside the tracker)
+- `pipeline/scripts/phase-tracker.sh` (state file CRUD)
+- `pipeline/scripts/run-aggregator.mjs` (post-hoc cost summary)

package/pipeline/commands/multi-agent/refs/wiki-capture.md

@@ -0,0 +1,109 @@
+# Component Wiki Capture (channels.md Wiki adapter)
+
+> **TLDR** — Component tasks can auto-generate wiki docs + Figma screenshots. The Wiki adapter is invoked from `/multi-agent:channels` (Phase 7 delegates, or user invokes post-hoc). Four layouts supported (`submodule`, `in-repo`, `github-wiki`, `separate-repo`) — adapter picked from `figmaConfig.wiki.mode`. Non-blocking: failures log a warning and channels continues to other adapters. The Wiki adapter supports scope multi-select (Case A) and a precondition-failure menu (Case B) — see below.
+
+This doc is referenced from `commands/multi-agent/channels.md` (Wiki adapter) and indirectly from `refs/phases/phase-7-report.md` (which delegates all external delivery to channels). Keeping it separate keeps both files under their token budgets and gives the contract a stable location for Claude-side + Copilot-side implementations.
+
+## Applicability
+
+Step 2 runs only when **both** are true:
+
+1. `state.taskType === "component"` — set by Phase 0 Step 7 when the task originates from a Figma URL or figma-driven instruction.
+2. `figmaConfig.wiki.enabled === true` — enables the capture globally for the project.
+
+Any other taskType skips silently (no prompt, no log) — wiki docs only make sense for UI components.
+
+## Case A — preconditions met (scope multi-select)
+
+When both applicability checks pass, channels opens a scope multi-select BEFORE dispatching:
+
+```
+Wiki'de ne güncelleyeyim? (space = toggle, enter = onay)
+  [x] Ana component sayfası    ({Name}.md — variants, overview, testing IDs,
+                                  localization, a11y, analytics, sub-components)
+  [x] iOS sub-page             ({Name}-iOS.md — initializer, usage, iOS patterns,
+                                  Code Connect, snapshot tests, changelog)
+  [x] Screenshots              (assets/ — Figma LTR+RTL+light+dark + iOS snapshot)
+  [x] Index updates            (_Sidebar.md + ComponentImplementationStatus.md)
+  [ ] Diğer                    (skip adapter dispatch; log "manual wiki override"
+                                  to agent-log, channels.wiki returns skipped)
+```
+
+Pre-ticks from `prefs.global.wikiScope` (array of scope IDs). Saved after selection for next run.
+
+- Selecting a subset (e.g. only Screenshots) → adapter runs with `scope=["screenshots"]`, skipping main/iOS/index writes.
+- Selecting "Diğer" alone → adapter dispatch is skipped entirely. Phase 7 / channels logs `Wiki: manual override — skipped by user`. No git push, no file changes.
+- Selecting nothing and confirming → same as "Diğer" alone (explicit skip).
+
+The adapter receives `scope: string[]` alongside `{componentName, componentPath, figmaConfig, agentState}` and writes only the requested artifacts.
+
+## Case B — preconditions missing (actionable menu)
+
+When preconditions fail, the gap is surfaced with a fix menu instead of a silent no-op:
+
+```
+Phase 7 · Wiki — preconditions not met
+
+  taskType:          {current}     ({component bekleniyor} ✗)
+  figma-config.json: {found/missing}
+  wiki.enabled:      {true/false/undefined}
+
+  Ne yapayım?
+    [1] Figma token + config ekle  (Token Save Flow + figma-config bootstrap)
+    [2] Sadece bu run için atla    (skipped, tekrar sorulur)
+    [3] Bu proje için wiki'yi kalıcı kapat  (writes wiki.enabled=false)
+    [4] Diğer — manuel not         (agent-log'a "user manual wiki path" düşer)
+```
+
+- **[1]** dispatches to `setup.md` Token Save Flow for Figma, then bootstraps `figma-config.json` from `preferences-template.json` `_figmaConfigTemplate`. After success, re-check preconditions — if met, fall into Case A. If user cancels the setup, fall back to [2].
+- **[2]** `phase-tracker.sh sub 7 1 "Channels/Wiki" skipped`, log line: `Wiki skipped — preconditions not met (this run only)`. Next run re-prompts.
+- **[3]** write `figmaConfig.wiki.enabled = false` to the project config. Subsequent runs silently skip Wiki (no menu, no prompt) — exactly the pre-v5.7 behavior for projects that don't want wiki.
+- **[4]** free-text prompt, user's note appended to agent-log under `### Wiki Manual Override`. No adapter action.
+
+Autopilot in Phase 7 pauses at the channels menu (per modes.md contract) — if user selects Wiki and preconditions fail, Case B opens, user picks. Post-hoc `/multi-agent:channels` with `--channels wiki` + failed preconditions: Case B opens non-negotiably (autopilot rules don't apply to post-hoc invocations).
+
+## Legacy prompt + preference flow (pre-v5.7, still supported for backward compat)
+
+Interactive path (normal / `--dev`), ONLY when the schema lacks `wikiScope`:
+
+```
+Generate component wiki docs? (y/n) [previous: {prefs.global.wikiDefault}]
+```
+
+Save the answer to `prefs.global.wikiDefault` for next run. Migration script (`migrate-prefs.mjs`) promotes `wikiDefault=true` → `wikiScope=["main","ios","screenshots","index"]` on first v5.7 run, then removes `wikiDefault`.
+
+## Dispatch
+
+1. Resolve wiki mode from `figmaConfig.wiki.mode` — one of `submodule`, `in-repo`, `github-wiki`, `separate-repo`. Each has a dedicated adapter inside the `figma-component-wiki` skill; see `pipeline/skills/figma-ios/figma-component-wiki/SKILL.md` for per-mode path layout and push semantics.
+2. Emit progress line: `→ writing wiki {componentName} (mode: {mode})`.
+3. Dispatch to `pipeline/skills/figma-ios/figma-component-wiki` (iOS) or `pipeline/skills/figma-android/figma-component-wiki` (Android), passing `{componentName, componentPath, figmaConfig, agentState}`.
+4. Skill returns `{ writtenPaths[], committedSha?, pushedRemote? }`. Write `writtenPaths` to Phase 7 summary's "Files written" section and push metadata (if any) to "External publishes".
+5. On adapter failure — log the adapter + mode + error, continue Phase 7. Wiki is a non-blocking augmentation; the Jira comment in Step 3 already carries the component summary, so the developer is never left in the dark if wiki misfires.
+
+## Skip conditions (explicit log lines)
+
+Explicit logs help the developer understand why wiki did or did not run:
+
+- `state.taskType !== "component"` → skip silently (no log).
+- `figmaConfig.wiki.enabled === false` → log `Phase 7: wiki disabled in figma-config.json`.
+- `figmaConfig` missing entirely → log `Phase 7: wiki skipped (no figma-config for this project)`.
+- User declined at prompt → log `Phase 7: wiki skipped by user`.
+- Autopilot with `wikiDefault=false` → log `Phase 7: wiki skipped (autopilot + wikiDefault=false)`.
+- `--dev` mode: DO prompt — wiki is cheap and keeps docs fresh on fast paths; skip only if user says no.
+
+## Success log
+
+`Phase 7: Component wiki generated — {componentName} via {mode} ({paths.length} files)`
+
+## Cross-CLI parity
+
+Claude Code and Copilot CLI MUST:
+
+- Resolve the adapter the same way (mode enum → adapter module).
+- Emit byte-identical progress lines.
+- Render byte-identical Case A / Case B menus (spacing, brackets, numbering).
+- Respect `prefs.global.wikiScope` array. Legacy `wikiDefault` boolean is migrated on first v5.7 load.
+- Treat adapter failures as non-blocking with the same log shape.
+- Pause the Case A / Case B menu in autopilot — per Phase 7 autopilot exception (`refs/phases/modes.md`). 30-min timeout ends session cleanly; resume re-opens menu.
+
+`smoke-wiki-integration.sh` asserts every contract item documented above.

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

@@ -0,0 +1,28 @@
+---
+description: "Resume a stopped or failed task from the phase where it left off."
+argument-hint: "[#id] — optional: task ID (e.g. #2). If omitted, the most recent paused task is used."
+---
+
+# multi-agent resume — Resume Paused Task
+
+**Input**: $ARGUMENTS
+
+Resume a paused or failed task from the last successful phase.
+
+## Steps
+
+1. **Find the task** — parse `#N` from the argument, or pick the most recent worktree with `status != "done"`.
+
+2. **Read state** — parse `agent-state.json`:
+   - `currentPhase` — last completed phase
+   - `status` — `paused` | `failed` | `in_progress`
+   - `autopilot` — preserve the mode
+
+3. **Load context** — read prior-phase findings from `agent-log.md`:
+   - Phase 1 analysis → use it from Phase 2+
+   - Phase 2 plan → use it from Phase 3+
+   - Phase 3 code → already in the worktree
+
+4. **Continue the pipeline** — start from the next phase (same pipeline as the main multi-agent command).
+
+5. **Log**: `🔄 Resumed {JIRA-KEY}-{id} from Phase {N}`

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

@@ -0,0 +1,228 @@
+---
+description: "Run parallel review on a branch's diff or a Pull Request: 2 models on Claude Code (Opus + Sonnet), 3 models on Copilot CLI (GPT + Opus + Sonnet). On PR input, posts per-finding inline comments and sets approve/needs-work review state."
+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, the current branch is used."
+---
+
+# multi-agent review — Review Only Mode
+
+**Input**: $ARGUMENTS
+
+Skip Phase 0-3 and review a diff only. Five input shapes, two providers:
+
+| Input | Resolution | PR action? |
+|---|---|---|
+| (empty) | Current branch (`HEAD` vs `origin/develop`) | No (chat only) |
+| `feature/foo` | Named local branch | No (chat only) |
+| `#1250` | PR number on the current repo | Yes |
+| `repo#1250` | PR on a specific repo (GitHub `org/repo`) | Yes |
+| `https://github.com/.../pull/1250` | GitHub PR URL | Yes |
+| `https://bitbucket.<host>/projects/<KEY>/repos/<slug>/pull-requests/<N>/...` | Bitbucket Server PR URL | Yes |
+
+Branch-mode runs print to chat only. PR-mode runs print to chat AND post the verdict to the PR per `refs/channels/pr-review-actions.md`: per-finding inline comments + an explicit approve / needs-work state. **No monolithic advisory comment** is ever posted.
+
+## Steps
+
+### 0. Session bootstrap — TASK_ID + tmp cleanup
+
+```bash
+# Standalone /multi-agent:review invocations may not inherit a pipeline TASK_ID.
+# Seed one so /tmp paths don't collide across concurrent reviews.
+: "${TASK_ID:=review-$(date +%s)-$$}"
+export TASK_ID
+
+# Clean up scratch files on exit so /tmp doesn't accumulate diffs and SHAs.
+trap 'rm -f /tmp/multi-agent-review-${TASK_ID}-*' EXIT
+```
+
+### 1. Parse the input — pick a resolution path
+
+```bash
+# Pseudocode — orchestrator implements this:
+input="$ARGUMENTS"
+case "$input" in
+  "")                              kind=branch; provider=local; ref=$(git rev-parse --abbrev-ref HEAD) ;;
+  https://github.com/*/pull/*)     kind=pr; provider=github; org_repo=<extracted>; pr_number=<extracted> ;;
+  https://bitbucket.*/projects/*/repos/*/pull-requests/*)
+                                   kind=pr; provider=bitbucket-server
+                                   bb_server_host=<extracted host>
+                                   bb_project_key=<extracted KEY>
+                                   bb_repo_slug=<extracted slug>
+                                   pr_number=<extracted N>
+                                   ;;
+  *#[0-9]*)                        kind=pr; provider=github; org_repo="${input%%#*}"; pr_number="${input##*#}" ;;
+  '#'[0-9]*)                       kind=pr; provider=github; org_repo=$(gh repo view --json nameWithOwner -q .nameWithOwner); pr_number="${input#'#'}" ;;
+  [0-9]*)                          kind=pr; provider=github; org_repo=$(gh repo view --json nameWithOwner -q .nameWithOwner); pr_number="$input" ;;
+  *)                               kind=branch; provider=local; ref="$input" ;;
+esac
+```
+
+Save to `agent-state.review.input = { kind, provider, ref?, orgRepo?, bbServerHost?, bbProjectKey?, bbRepoSlug?, prNumber?, raw }`.
+
+When `provider=github` and the diff is fetched in Step 2, also persist `agent-state.review.headCommitSha` — GitHub inline-comment posts (`POST /repos/{o}/{r}/pulls/{n}/comments`) require `commit_id`. Bitbucket Server's anchor API does not.
+
+### 2. Fetch the diff — kind-aware
+
+**branch mode:**
+
+```bash
+git diff origin/develop...{ref}
+```
+
+**pr mode — github:**
+
+```bash
+gh pr diff "$pr_number" --repo "$org_repo" > /tmp/multi-agent-review-${TASK_ID}-diff.patch
+# Also capture the head commit SHA for GitHub inline-comment anchors
+# (POST .../pulls/{n}/comments requires commit_id):
+HEAD_SHA=$(gh api "/repos/$org_repo/pulls/$pr_number" --jq .head.sha)
+printf '%s\n' "$HEAD_SHA" > /tmp/multi-agent-review-${TASK_ID}-head.sha
+# Persist into agent-state — post-pr-review.sh reads it from there.
+tmp_state=$(mktemp)
+jq --arg sha "$HEAD_SHA" '.review.headCommitSha = $sha' "$AGENT_STATE" > "$tmp_state" \
+  && mv "$tmp_state" "$AGENT_STATE"
+```
+
+**pr mode — bitbucket-server:**
+
+```bash
+# Resolve credentials via prefs.keychainMapping (never hardcode key names).
+. "$HOME/.claude/lib/credential-store-resolver.sh" \
+  || . "$HOME/.copilot/lib/credential-store-resolver.sh"
+resolve_credential_store
+USER_KEY=$(jq -r '.keychainMapping.bitbucket_user' "$HOME/.claude/multi-agent-preferences.json")
+TOKEN_KEY=$(jq -r '.keychainMapping.bitbucket_token' "$HOME/.claude/multi-agent-preferences.json")
+BB_USER=$("$CRED_STORE" get "$USER_KEY")
+BB_TOKEN=$("$CRED_STORE" get "$TOKEN_KEY")
+
+DIFF_FILE="/tmp/multi-agent-review-${TASK_ID}-diff.patch"
+http=$(curl -sS -m 60 -u "$BB_USER:$BB_TOKEN" -H "Accept: text/plain" \
+  "https://$bb_server_host/rest/api/1.0/projects/$bb_project_key/repos/$bb_repo_slug/pull-requests/$pr_number/diff?contextLines=10" \
+  -o "$DIFF_FILE" -w '%{http_code}')
+if [ "$http" != "200" ]; then
+  echo "review: Bitbucket diff fetch failed (HTTP $http) — error body in $DIFF_FILE" >&2
+  rm -f "$DIFF_FILE"
+  exit 1
+fi
+```
+
+The `credential-store.sh` wrapper handles macOS Keychain (`security`), Linux libsecret (`secret-tool`), and Windows Credential Manager (`gcm`).
+
+Save the diff to `/tmp/multi-agent-review-${TASK_ID}-diff.patch` so reviewers can re-read it.
+
+### 3. Launch parallel reviewers — host-CLI dependent
+
+**Claude Code (2 in parallel):**
+- Agent 1: `claude-opus-4.6` → security + architecture
+- Agent 2: `claude-sonnet-4.6` → general quality
+
+**Copilot CLI (3 in parallel):**
+- Agent 1: `claude-opus-4.6` → security + architecture
+- Agent 2: `gpt-5.4` → edge cases, alternate perspective
+- Agent 3: `claude-sonnet-4.6` → general quality
+
+Each reviewer receives the diff plus the standard reviewer system prompt (see `refs/phases/phase-4-review.md` for the prompt contract). Output: structured `findings[]` per reviewer.
+
+### 4. Store-compliance cross-reference
+
+When release-relevant iOS/Android files change, load the matching catalog:
+
+| Platform | Trigger files | Catalog |
+|---|---|---|
+| iOS | `**/Info.plist`, `**/PrivacyInfo.xcprivacy`, `**/*.entitlements`, `**/*App.swift`, `**/AppDelegate*.swift`, `**/SceneDelegate*.swift`, `**/project.pbxproj` | `pipeline/skills/shared/core/apple-archive-compliance/SKILL.md` — 17 rules + ITMS refs |
+| Android | `**/AndroidManifest.xml`, `**/build.gradle(.kts)`, `**/proguard-rules.pro`, `**/network_security_config.xml` | `pipeline/skills/shared/core/google-play-compliance/SKILL.md` — 21 rules + Play policy refs |
+
+Each finding gets the `ruleID` from the catalog plus the platform policy ref:
+- iOS: `(apple-archive-compliance / info-plist — Guideline 5.1.1)`
+- Android: `(google-play-compliance / dangerous-permissions — Policy — Permissions)`
+
+Catalog-only — does NOT invoke binaries. For a full scan, use `/multi-agent:test "store-ready"`.
+
+### 5. Triage (Opus)
+
+Classify findings into:
+- 🔴 **Blocking** → must fix
+- 🟡 **Important** → fix recommended
+- 🟢 **Suggestion** → optional
+
+Triage also marks each finding as `accepted` (real issue), `deferred` (real but out of scope), or `rejected` (false positive). Only `accepted` findings appear in the body of the PR comment; `deferred` items go in the Triage notes section.
+
+### 6. Print the chat summary (always)
+
+```
+🔍 Review Complete  ·  PR #1250  ·  3 files +120 -45
+| Model    | Verdict   | Blocking | Important | Suggestion |
+|----------|-----------|----------|-----------|------------|
+| Opus     | approved  | 0        | 1         | 3          |
+| Sonnet   | rejected  | 1        | 2         | 5          |
+
+Consensus: ⚠ DISAGREEMENT — Opus triajına bakın
+```
+
+This summary ALWAYS prints, regardless of input mode. The chat is the live conversation; on the PR side, the durable artifacts are inline comments + the review state (Step 7).
+
+### 7. Post to PR — only when input.kind === "pr"
+
+The contract (full spec: `refs/channels/pr-review-actions.md`):
+
+- **Decision** — purely from `accepted` finding counts:
+  - 0 accepted blocking AND 0 accepted important → **APPROVE**
+  - ≥1 accepted blocking OR ≥1 accepted important → **NEEDS WORK / REQUEST CHANGES**
+  - Suggestions never block and never post inline; they stay in chat only.
+
+- **No monolith advisory comment.** "Render one big body and post via `gh pr comment`" is forbidden. Findings that need to surface on the PR become inline comments anchored to `file:line`.
+
+- **Body language follows `outputLanguage`.** Per `refs/rules.md` Language Application matrix, external payloads (PR comment bodies are external) render in `prefs.global.outputLanguage`. The renderer in `lib/post-pr-review.sh` honors this.
+
+Optional opt-out prompt (interactive mode only; autopilot skips and posts):
+
+```
+question (outputLanguage): "PR #{N} için review action gönderilsin mi?"
+header   (English):        "Post review"
+options:
+  - label "Post review",  description (outputLanguage): "Bulgular varsa inline yorum + Request changes; yoksa Approve"
+  - label "Chat only",    description (outputLanguage): "Sadece sohbet özetiyle yetin, PR'a dokunma"
+default: option 1 (Post review)
+```
+
+Defaults:
+- Interactive mode: prompt with default `Post review`
+- Autopilot mode: auto-post (no prompt)
+- `--no-comment` / `--no-post` flag: skip the post entirely
+
+If the user picks "Post review":
+
+```bash
+bash $HOME/.claude/lib/post-pr-review.sh "$TASK_ID"
+```
+
+`post-pr-review.sh` reads `agent-state.review.{input, findings, iterationNumber, headCommitSha}`, decides APPROVE vs NEEDS_WORK from the rule above, posts one inline comment per accepted blocking + important finding (in `outputLanguage`), then sets the review state via the provider's API:
+
+| Provider | Inline comment | State |
+|---|---|---|
+| `github` | `gh api -X POST /repos/{o}/{r}/pulls/{n}/comments` (path + line + commit_id) | `gh pr review --approve` / `--request-changes` |
+| `bitbucket-server` | `POST /pull-requests/{n}/comments` with `anchor: { path, line, lineType:"ADDED", fileType:"TO" }` | `PUT /pull-requests/{n}/participants/{user}` body `{"status":"APPROVED"}` or `{"status":"NEEDS_WORK"}` |
+
+If a finding's `line` lies outside the diff or `headCommitSha` is missing, the comment falls back to a top-level PR comment with the same body.
+
+If the post fails (network, token, harness block), `post-pr-review.sh` exits non-zero and surfaces the failing endpoint on stderr — the chat summary remains the source of truth.
+
+### 8. Token telemetry
+
+Per the `refs/tracker-contract.md` tokens contract, after each reviewer LLM call:
+
+```bash
+bash $HOME/.claude/scripts/phase-tracker.sh tokens 4 <input_count> <output_count>
+```
+
+Standalone `/multi-agent:review` runs use phase id 4 (matches Phase 4 Review in the full pipeline) so cost aggregation stays consistent.
+
+## Input matrix
+
+| Input | Mode | PR action |
+|---|---|---|
+| no args | branch (current) | none — chat only |
+| `feature/foo` | branch (named) | none — chat only |
+| `#N`, `repo#N`, GitHub PR URL | pr (github) | inline comments + approve/needs-work |
+| Bitbucket Server PR URL | pr (bitbucket-server) | inline comments + approve/needs-work |
+
+PR-mode body language honors `prefs.global.outputLanguage`. The orchestrator entry point is `lib/post-pr-review.sh "$TASK_ID"` — it reads `agent-state.review` and handles diff fetch, finding render, comment posts, and review state end-to-end.