@mmerterden/multi-agent-pipeline 20.2.0 → 20.3.0

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

@@ -27,9 +27,9 @@ Pre-flight steps (run in order, abort on failure).
 
 5b. **Test plan handoff (the RED input)**: read `analysis Section 15` into `state.dev.testPlan[]` (15.1 unit rows with name/arrange/act/expected/`BR-` id, 15.2 snapshot variants, 15.6 UI flows, 15.7 manual scenarios). **RED writes these tests, not invented ones** - development is TDD, so the analysis matrix is literally the first thing written. A row too vague to write from is an analysis defect: open a Section 20 question, do not improvise.
 
-6. **Conventions handoff**: read `analysis Section 13.1 Concept Table` (Pass B output with footnotes). Persist concept-to-realization mapping into `state.dev.conventions[<concept>]`. Phase 2 implementation uses these names verbatim, and a non-empty `sharedUtilities` bucket is binding: bind those formatters/rule-facades/tokens, never hand-roll a duplicate (e.g., if Section 13.1 says "State holder: PassengerFlightViewModel", Phase 2 names the class exactly `PassengerFlightViewModel`).
+6. **Conventions handoff**: read `analysis Section 13.1 Concept Table` (Pass B output with footnotes). Persist concept-to-realization mapping into `state.dev.conventions[<concept>]`. Phase 2 implementation uses these names verbatim, and a non-empty `sharedUtilities` bucket is binding: bind those formatters/rule-facades/tokens, never hand-roll a duplicate (e.g., if Section 13.1 says "State holder: OrderSummaryViewModel", Phase 2 names the class exactly `OrderSummaryViewModel`).
 
-7. **MCP forbidden**: calling `mcp__claude_ai_Figma__*` in Phase 2 is a violation. `smoke-no-mcp-in-dev-phases.sh` reads `state.telemetry.mcpCalls[]` after the run and fails if Phase 2 contributed an entry.
+7. **MCP forbidden**: calling `mcp__claude_ai_Figma__*` in Phase 2 is a violation. Record any call in `state.telemetry.mcpCalls[]` with its phase; the maintainer regression check `smoke-no-mcp-in-dev-phases.sh` flags a Figma entry at phase 2 or later.
 
 8. **Criteria ledger (required, every mode)**: the moment this phase consults a skill, a marketplace plugin skill, a stack guide or a module `CLAUDE.md` in order to write code, append an entry to `state.telemetry.skillCalls[]`:
 
@@ -41,6 +41,8 @@ Pre-flight steps (run in order, abort on failure).
 
 9. **Stack skill routing (every `taskType`, when a stack toolkit plugin is enabled)**: ask each enabled toolkit's own `index` skill which skills govern this task, load them BEFORE writing code, and record each into `state.telemetry.skillCalls[]` with `routedBy: "<toolkit>:index@<version>"`. Candidates are the effective `enabledPlugins`, not a stack table. The routing table stays in the plugin  -  a copy here would be the stale one, and `rules/outside-the-pipeline.md` runs the same routing outside a run. A screen-creation task loads the routed toolkit's `workflow/create-screen` when one exists. No toolkit, or none enabled, is a recorded no-op, not a halt. Contract: [`features/stack-skill-routing.md`]($HOME/.claude/multi-agent-refs/features/stack-skill-routing.md).
 
+10. **Autopilot** (or `MULTI_AGENT_UNATTENDED=1`): a run that Phase 1's `open-questions-gate.mjs` parked (`waitingFor: "question"`), or that `spec-consistency-gate.mjs` or `plan-critique-gate.mjs` failed (`verificationFailed.gate: spec-consistency` / `plan-critique`), does not enter this phase. When `state.research.md` exists, read it before writing code: what research closed, each answer with its source ([`features/research.md`]($HOME/.claude/multi-agent-refs/features/research.md)).
+
 The analysis document is the SOLE design source in Phase 2. Variant choices, padding values, color tokens, copy strings, accessibility identifiers, and test method names all come from the rendered Pass B cells. If something is missing in the analysis doc, the fix is to re-run `/multi-agent:analysis`, not to fetch from Figma.
 
 <!-- progress-contract: applied -->
@@ -124,23 +126,17 @@ For each task (respecting dependency order):
      - `describe` / `it` → Quick/Nimble
    - Test naming: `test{Scenario}_{Expected}` (e.g. `testKeychainReturnsNil_doesNotCrash`)
    - One test per behavior change  -  not one test per file
-   - Run test to confirm RED  -  the command is the platform's, one arm per stack:
+   - Run test to confirm RED with the stack's command. ios, under the build lock:
      ```bash
-     case "$STACK" in
-       ios)     acquire_build_lock "$TASK_ID"
-                xcodebuild test -scheme "{scheme}" -destination "platform=iOS Simulator,name={simulator}" \
-                  -derivedDataPath "{worktreePath}/.DerivedData" -only-testing:"{testTarget}/{testClass}/{testMethod}" 2>&1 | tail -5
-                release_build_lock ;;
-       android) ./gradlew test --tests "{testClass}.{testMethod}" 2>&1 | tail -5 ;;
-       backend) pytest "{test_file}::{test_name}" 2>&1 | tail -5 ;;
-       web) CMD=$(node $HOME/.claude/scripts/package-manager.mjs test \
-              --dir "{worktreePath}" --pattern "--testPathPattern={file}") \
-            && eval "$CMD" 2>&1 | tail -5 || echo "no test script declared" ;;
-     esac
+     bash $HOME/.claude/scripts/build-lock.sh acquire "$TASK_ID"
+     xcodebuild test -scheme "{scheme}" -destination "platform=iOS Simulator,name={simulator}" \
+       -derivedDataPath "{worktreePath}/.DerivedData" -only-testing:"{testTarget}/{testClass}/{testMethod}" 2>&1 | tail -5
+     bash $HOME/.claude/scripts/build-lock.sh release "$TASK_ID"
      ```
-   - The node arm resolves the manager instead of typing `npm`; exit 3 means the repo
-     declares no such script - say so, never substitute one, and never let the empty
-     command substitution pass for a pass (`features/package-manager.md`).
+     android: `./gradlew test --tests "{testClass}.{testMethod}" 2>&1 | tail -5` (same lock); backend: `pytest "{test_file}::{test_name}" 2>&1 | tail -5`; web: `node $HOME/.claude/scripts/package-manager.mjs test --dir "{worktreePath}" --pattern "--testPathPattern={file}"` prints the manager's command, then run that command `2>&1 | tail -5`.
+   - The web step resolves the manager instead of typing `npm`; exit 3 means the repo
+     declares no such script - say so, never substitute one, and never let an empty
+     command pass for a pass (`features/package-manager.md`).
 
    - Must fail for the RIGHT reason (expected assertion, not compilation error)
 
@@ -150,13 +146,13 @@ For each task (respecting dependency order):
    - Run the same test again → must PASS
    - Run full test suite → no regressions:
      ```bash
-     acquire_build_lock "$TASK_ID"
+     bash $HOME/.claude/scripts/build-lock.sh acquire "$TASK_ID"
      xcodebuild test \
        -scheme "{scheme}" \
        -destination "platform=iOS Simulator,name={simulator}" \
        -derivedDataPath "{worktreePath}/.DerivedData" \
        2>&1 | tail -20
-     release_build_lock
+     bash $HOME/.claude/scripts/build-lock.sh release "$TASK_ID"
      ```
 
    **REFACTOR (if needed):**
@@ -165,20 +161,18 @@ For each task (respecting dependency order):
    - **Stability (required):** run every test added or changed in this diff `prefs.global.testStability.repeatCount` times (default 3; 1 disables) with the single-test invocation above. Disagreeing outcomes are not GREEN: log `test.flake_signal file=<f> passed=<k> of=<N>` and fix the test or the code first. A pass only on retry is a flake signal, not a pass. Same rule on the Phase 3 rework re-entry.
 
    **Target resolution** (auto-detect once per project, cache in `agent-state.json`; ios resolves scheme + simulator, android resolves module + variant, backend/web need none):
+   ios (prefer the scheme matching the project name, then the first non-test scheme):
    ```bash
-   case "$STACK" in
-     ios)     xcodebuild -list -json -project "{projectPath}" 2>/dev/null || xcodebuild -list -json -workspace "{workspacePath}" 2>/dev/null
-              # prefer the scheme matching the project name, then the first non-test scheme
-              xcrun simctl list devices available -j | jq '.devices | to_entries[] | select(.key | contains("iOS")) | .value[0].name' ;;
-     android) ./gradlew projects 2>/dev/null | grep -E "^\+--- Project" ; ./gradlew tasks --all 2>/dev/null | grep -m5 "assemble.*Debug" ;;
-   esac
+   xcodebuild -list -json -project "{projectPath}" 2>/dev/null || xcodebuild -list -json -workspace "{workspacePath}" 2>/dev/null
+   xcrun simctl list devices available -j | jq '.devices | to_entries[] | select(.key | contains("iOS")) | .value[0].name'
    ```
+   android: `./gradlew projects 2>/dev/null | grep -E "^\+--- Project"` and `./gradlew tasks --all 2>/dev/null | grep -m5 "assemble.*Debug"`.
 
 4. **Build verification** (per stack; ios/android under the build queue lock, see below):
-   - **ios, preferred (MCP, multi-agent-toolkit >= 3.0.0)**: `acquire_build_lock` → `mcp__multi-agent-toolkit__ios_xcodebuild({project|workspace, scheme, configuration: "Release", destination: "generic/platform=iOS", derived_data_path: "{worktreePath}/.DerivedData"})` → `release_build_lock`. Returns one line `Build: SUCCESS|FAILURE (E errors, W warnings) [xcresult-<id>]`; on failure drill in via `mcp__multi-agent-toolkit__ios_xcresult({id, mode: "errors"})`, never dump the full log.
+   - **ios, preferred (MCP, multi-agent-toolkit >= 3.0.0)**: `build-lock.sh acquire "$TASK_ID"` → `mcp__multi-agent-toolkit__ios_xcodebuild({project|workspace, scheme, configuration: "Release", destination: "generic/platform=iOS", derived_data_path: "{worktreePath}/.DerivedData"})` → `build-lock.sh release "$TASK_ID"`. Returns one line `Build: SUCCESS|FAILURE (E errors, W warnings) [xcresult-<id>]`; on failure drill in via `mcp__multi-agent-toolkit__ios_xcresult({id, mode: "errors"})`, never dump the full log.
    - **ios, fallback (raw)**: same lock pair around `xcodebuild build -scheme "{scheme}" -destination "generic/platform=iOS" -derivedDataPath "{worktreePath}/.DerivedData" 2>&1 | tail -5`.
    - **android**: lock pair around `./gradlew assembleDebug 2>&1 | tail -5` (the Gradle daemon and `build/` outputs contend across parallel worktrees exactly as DerivedData does  -  the lock applies).
-   - **backend / web**: `python -m compileall .` / `CMD=$(node $HOME/.claude/scripts/package-manager.mjs run --dir "{worktreePath}" --script build) && eval "$CMD" 2>&1 | tail -5 || echo "no build script"`; no lock.
+   - **backend / web**: `python -m compileall .` / run the command `node $HOME/.claude/scripts/package-manager.mjs run --dir "{worktreePath}" --script build` prints, `2>&1 | tail -5` (exit 3: no build script); no lock.
 5. If build fails → fix → rebuild (max 3 attempts, track `retryCount` in state).
 6. **Intermediate commit** (after each completed task in the plan):
    ```bash
@@ -195,40 +189,29 @@ For each task (respecting dependency order):
 
 **Problem**: Multiple parallel worktrees may reach build/test phase simultaneously. `xcodebuild` cannot run in parallel  -  DerivedData, simulators, and project locks cause conflicts.
 
-**Solution**: Lock-file based queue using `mkdir` atomicity. Before ANY `xcodebuild` call, acquire the lock; release after completion.
+**Solution**: Lock-file based queue using `mkdir` atomicity (`build-lock.sh`). Before ANY `xcodebuild` call, acquire the lock; release after completion:
 
 ```bash
-BUILD_LOCK="/tmp/claude-xcodebuild.lock"
-
-acquire_build_lock() {
-  local TASK_ID="${1:-unknown}"
-  while ! mkdir "$BUILD_LOCK" 2>/dev/null; do
-    OWNER=$(cat "$BUILD_LOCK/owner" 2>/dev/null || echo "unknown")
-    LOCK_AGE=$(( $(date +%s) - $(stat -f "%m" "$BUILD_LOCK/owner" 2>/dev/null || echo 0) ))
-    [ "$LOCK_AGE" -gt 900 ] && { echo "Stale lock (${LOCK_AGE}s)  -  removing"; rm -rf "$BUILD_LOCK"; continue; }
-    echo "Build queue: waiting ($OWNER, ${LOCK_AGE}s)"; sleep 5
-  done
-  echo "$TASK_ID" > "$BUILD_LOCK/owner"
-}
-
-release_build_lock() { rm -rf "$BUILD_LOCK"; }
+bash $HOME/.claude/scripts/build-lock.sh acquire "{jiraId}"
+xcodebuild -derivedDataPath "{worktreePath}/.DerivedData" ...
+bash $HOME/.claude/scripts/build-lock.sh release "{jiraId}"
 ```
 
-**Usage**: `acquire_build_lock "{jiraId}"` → `xcodebuild -derivedDataPath "{worktreePath}/.DerivedData" ...` → `release_build_lock`
-
 **Key details:**
 
-- Lock path: `/tmp/claude-xcodebuild.lock` (shared across all Claude instances)
+- Lock path: `/tmp/claude-xcodebuild.lock` (shared across all Claude instances; `MA_BUILD_LOCK` overrides)
 - Stale lock timeout: 15 minutes (auto-cleanup if a session crashes)
 - Each worktree uses its OWN `-derivedDataPath` to avoid cache poisoning
 - `sleep 5` between retries  -  not aggressive polling
 - Lock owner tracked for visibility: which task is currently building
+- `release` takes the same task id and leaves a lock held by another task in place
+- A lock whose owner file is missing is taken over only after a 5-second grace window; with `MA_BUILD_LOCK_PID` set, a lock whose recorded process is gone is taken over at once
 
 **This applies to ALL xcodebuild calls in the pipeline:**
 
 - Phase 2 Step 4 (build after development)
-- Phase 3 Step 1 Gate 1 (build gate before review)
-- Phase 3 Step 1 Gate 3 (test gate before review)
+- Exit gate Step 1 Gate 1 (build gate before review)
+- Exit gate Step 1 Gate 3 (test gate before review)
 
 **Android**: same lock discipline  -  the Gradle daemon and `build/` outputs contend across parallel worktrees. **Backend/web** (Python, Node.js): no lock needed  -  these build/test in parallel without conflicts.
 
@@ -330,11 +313,11 @@ If a todo has no `repo` tag in multi-repo mode → log warning + ask user, do no
 
 **Recording a pass (default-FAIL evidence gate):** before setting `buildStatus.ok = true`, the build output must be tee'd to a log and that log must substantiate the success  -  a zero exit code alone is not trusted. Run the evidence gate; on exit 1, do NOT record a pass:
 ```bash
-<build-command> 2>&1 | tee "$WORKTREE/.build.log" \
+<build-command> 2>&1 | tee "{worktreePath}/.build.log" \
   | bash $HOME/.claude/scripts/offload-ref.sh --phase 3 --label build --root "$WORKTREE"
-node $HOME/.claude/scripts/evidence-gate.mjs --claim build --status passed --evidence "$WORKTREE/.build.log" \
-  || { echo "build pass unverified  -  treat as failure"; /* keep buildStatus.ok=false */ }
+node $HOME/.claude/scripts/evidence-gate.mjs --claim build --status passed --evidence "$WORKTREE/.build.log"
 ```
+Non-zero from the gate: the build pass is unverified, so treat it as a failure and keep `buildStatus.ok=false`.
 This closes the gap where an agent records "built" without ever producing build output.
 
 **Why the pipe (opt-in via `prefs.global.contextOffload.enabled`).** `tee` decides where the log is written, not how much of it the model reads. The filter parks the full text at `.multi-agent/refs/<node_id>.md` and prints a stub plus the tail, where a failing build's error already is; read that file before re-running a failed build. The evidence gate still reads the whole `.build.log`, so what counts as a verified pass is unchanged. Pref off = pass-through.
@@ -412,10 +395,10 @@ If any gate fails → fix first, don't waste AI tokens reviewing broken code.
 
 ```bash
 # Gate 1: Build (xcodebuild/gradle assemble/tsc/py compile  -  stack-dependent; Xcode uses the build queue lock, see Phase 2)  -  tee output to a log
-<build-command> 2>&1 | tee "$WORKTREE/.build.log"
+<build-command> 2>&1 | tee "{worktreePath}/.build.log"
 # Gate 2: Lint (swiftlint/ktlint/ruff/eslint  -  stack-dependent)
 # Gate 3: Tests pass (xcodebuild/gradle/pytest/the resolved node command)  -  tee output to a log
-<test-command> 2>&1 | tee "$WORKTREE/.test.log"
+<test-command> 2>&1 | tee "{worktreePath}/.test.log"
 # Gate 4: Secrets  -  run the scanner against the staged diff
 bash $HOME/.claude/scripts/pre-commit-check.sh
 ```
@@ -429,6 +412,10 @@ node $HOME/.claude/scripts/evidence-gate.mjs --claim test  --status passed --evi
 
 This prevents a false "it built" claim with no log behind it. On exit 1, treat the gate as failed (do NOT proceed to AI review) and surface the gate's `reason`.
 
+**Autopilot runs** (`state.autopilot` or `MULTI_AGENT_UNATTENDED=1`; interactive runs skip this paragraph) also run the stack-aware checks, each recording its verdict in `state.gates[]`: `evidence-gate.mjs --stack`, `test-summary.mjs` (zero tests executed parks the run as `verification-failed` instead of reworking), `test-strength.mjs --head worktree` and `symbol-existence-gate.mjs`. With the variable set, the Phase 4 commit hook refuses a commit whose ledger lacks them. Commands and verdicts: `$HOME/.claude/multi-agent-refs/features/unattended-gates.md` section 4.
+
+**Scaffolded repo** (`.scaffold.json` at the worktree root): at this phase's entry and exit, `scaffold-gate.mjs --dir "$WORKTREE" --phase story --story <id>`; exit 1 or 3 halts and the next story does not start; 2 is a call error, never a pass (`$HOME/.claude/multi-agent-refs/features/scaffold.md`).
+
 **Inherited failures (when `state.baseline.tests` exists).** Phase 0 Step 7.6 recorded whether the suite was already red, so Gate 3 blocks on what this work broke, not what it walked into:
 
 | baseline status | Gate 3 |
@@ -451,22 +438,11 @@ The subtraction never widens: match on identifier only, and when identifiers can
 If the task description referenced a Fortify version, or named a bare issue instance id, `~/.claude/lib/fetch-fortify.sh` already populated `state.fortifyFinding` in Phase 0 (`alwaysCheck` needs `prefs.global.fortify.versionIds` to know what to scan). Phase 3 reuses that payload and applies the deterministic gate:
 
 ```bash
-gate=$(jq -r '.fortifyFinding.gateOutcome // empty' "$STATE_FILE")
-if [ -z "$gate" ]; then
-  # No fortify entry in contextLinks; gate is N/A.
-  echo "→ fortify gate: n/a (no Fortify URL referenced)"
-elif [ "$(jq -r '.fortifyFinding.gateOutcome.blocking' "$STATE_FILE")" = "true" ]; then
-  reason=$(jq -r '.fortifyFinding.gateOutcome.reason' "$STATE_FILE")
-  critical=$(jq -r '.fortifyFinding.severityCounts.Critical' "$STATE_FILE")
-  echo "→ fortify gate: BLOCKED ($reason, critical=$critical)"
-  # Treat as a deterministic gate failure  -  fix the critical findings before AI review.
-  exit 1
-else
-  high=$(jq -r '.fortifyFinding.severityCounts.High // 0' "$STATE_FILE")
-  echo "→ fortify gate: pass (high=$high warnings carry into the channel summary)"
-fi
+jq -r '.fortifyFinding as $f | if ($f.gateOutcome // null) == null then "n/a (no Fortify URL referenced)" elif $f.gateOutcome.blocking == true then "BLOCKED (\($f.gateOutcome.reason), critical=\($f.severityCounts.Critical))" else "pass (high=\($f.severityCounts.High // 0) warnings carry into the channel summary)" end' "$STATE_FILE"
 ```
 
+Print it as `→ fortify gate: <line>`. `BLOCKED` is a deterministic gate failure: fix the critical findings before AI review.
+
 Gate semantics:
 
 | `gateOutcome.reason` | Phase 3 action |

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

@@ -101,7 +101,7 @@ Persist the totals as `state.diffRisk` (Phase 4 `risk` section, Phase 5, `run-me
 
 **Reviewer prompt injection**: when `$RISK_JSON` is non-empty, the orchestrator builds a `${PRIORITY_FILES}` block (numbered list of top-N files with their score + signals) and injects it once per reviewer. Reviewer prompt template (`code-reviewer.md`) treats it as advisory and does not echo it back. Triage does not see the priority list  -  its job is to filter the merged findings, not the diff.
 
-**Gate behavior**: this step is **never blocking**. If risk scoring fails (git error, parse error, validator rejection), continue with no priority hint  -  reviewers receive the full diff in their default order. Failures are logged via metrics:
+**Gate behavior**: **never blocking**. If risk scoring fails (git, parse, validator), continue with no priority hint: reviewers get the full diff in default order. Failures are logged:
 
 ```bash
 [ -z "$RISK_JSON" ] && $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 3 review.diff_risk_skipped reason=$REASON
@@ -118,21 +118,22 @@ $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 3 review.diff_risk \
   files=$(jq '.totals.files' <<< "$RISK_JSON")
 ```
 
-**Opt-out**: `prefs.global.diffRiskAdvisory = false` skips this step entirely (no script invocation, no priority block injection). Default `true` because the cost is bounded and the signal-to-noise has been measured against the golden-task fixture set.
+**Opt-out**: `prefs.global.diffRiskAdvisory = false` skips this step (no script, no priority block). Default `true`: the cost is bounded and the signal-to-noise is measured against the golden-task fixtures.
 
 #### Step 1.76  -  Test-integrity gate (produces BLOCKING findings)
 
-Step 1.75 uses `test_lines_removed` as an advisory hint only  -  too weak for what it detects: a suite made green by deleting tests instead of fixing code. This turns the signal into blocking findings triage must adjudicate. Pure function of the full report, no git, no LLM.
+Step 1.75's `test_lines_removed` hint is too weak for what it detects: a suite made green by deleting tests. This makes it blocking findings triage must adjudicate. Pure function of the full report. `--out` always writes the file, the empty result included.
 
 ```bash
-TEST_INTEGRITY_JSON=$(printf '%s' "$RISK_FULL" | node $HOME/.claude/scripts/test-integrity-gate.mjs 2>/dev/null || echo "")
-TI_COUNT=$(jq -r '.count // 0' <<< "${TEST_INTEGRITY_JSON:-{\}}" 2>/dev/null || echo 0)
+TI_FILE="$WORKTREE/.pipeline/test-integrity.json"
+printf '%s' "$RISK_FULL" | node $HOME/.claude/scripts/test-integrity-gate.mjs --out "$TI_FILE" 2>/dev/null
+TI_COUNT=$(jq -r '.count // 0' "$TI_FILE" 2>/dev/null || echo 0)
 [ "$TI_COUNT" -gt 0 ] && $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 3 review.test_integrity findings="$TI_COUNT"
 ```
 
 `findings[]` are reviewer-shaped (`test_integrity`, `blocking`), so they merge into the reviewer findings at Step 3.0 and need no triage-prompt or `validate-triage.mjs` change. Triage keeps each blocking unless the removal is justified per the immutable-test rule (spec changed AND commit body names the test) → `deferred[]`.
 
-The gate never blocks the phase; it *emits* blocking findings. Empty or unreadable input yields zero findings and the phase continues. Feed it the FULL report  -  `--top` hides a shrinking test file below the cut. **No opt-out**: a run that can switch off its own anti-reward-hacking control cannot be trusted to report a pass.
+The gate never blocks the phase; it *emits* blocking findings (unreadable input: zero). Feed it the FULL report: `--top` hides a shrinking test file below the cut. **No opt-out**: a run that can switch off its own anti-reward-hacking control cannot be trusted to report a pass.
 
 #### Step 1.77  -  Reviewer scope (cost gate)
 
@@ -200,7 +201,7 @@ Decides what the reviewers read before the cap decides what fits: the cap trunca
 ```bash
 git -C "$WORKTREE" diff --name-only "$BASE_BRANCH"...HEAD \
   | node $HOME/.claude/scripts/review-file-filter.mjs \
-  > "$WORKTREE/.pipeline/review-files.json"
+  > "{worktreePath}/.pipeline/review-files.json"
 ```
 
 `reviewed[]` is the denominator, fixed here for the same reason `selectedRules[]` is. `excluded[]` reaches the run report with its reason and the glob that matched. Exit 2 means the pattern list is unreadable and everything is reviewed: continue, logging `review.file_filter_failed`.
@@ -315,9 +316,9 @@ Runs when Step 1.75 scored `security_path`, on a release branch, or when `/multi
 
 **Required: validator gate (deterministic)  -  run immediately after each reviewer returns, before merging findings.** Persist each reviewer's output and validate the file  -  the validator's exit code decides, not the LLM turn:
 
+Write it with the Write tool to `$REVIEWER_FILE` = `$WORKTREE/.pipeline/reviewer-$N.json`, then:
+
 ```bash
-REVIEWER_FILE="$WORKTREE/.pipeline/reviewer-$N.json"
-printf '%s' "$REVIEWER_JSON" > "$REVIEWER_FILE"
 node $HOME/.claude/scripts/validate-reviewer.mjs "$REVIEWER_FILE" \
   --criteria "$WORKTREE/.pipeline/criteria-manifest.json" \
   --coverage "$WORKTREE/.pipeline/review-files.json" \
@@ -337,23 +338,12 @@ Exit 0 = valid. Exit 2 = contradiction (approved=true with blocking findings)  -
 
 #### Step 2.5  -  Disagreement-round loop (opt-in)
 
-**Rationale:** When reviewers disagree (e.g. 1 blocker vs 2 pass), straight-to-triage discards potential insight  -  the minority reviewer might see something real, or the majority reviewers might all miss a subtle issue. One rebuttal round lifts signal quality without adding a new phase.
-
-**Gated by `prefs.global.reviewDisagreementRound`** (default: `false`). When enabled:
-
-1. Compute disagreement: reviewers agree iff all return `approved=true` with no `blocking` findings, OR all return `approved=false` with overlapping `blocking` findings. Anything else is disagreement.
-2. Agreement → skip the rebuttal round, go straight to Step 3 triage.
-3. Disagreement → one rebuttal round:
-   - For each reviewer, re-prompt with: (a) their original output, (b) the OTHER reviewers' blocker findings **anonymized** through `node $HOME/.claude/scripts/anonymize-findings.mjs` (labels `Source A/B/C`, no model name, order deterministic per `taskId:iteration`), (c) instruction: *"Given the opposing arguments, keep / withdraw / modify each of your findings. You may also newly agree with a finding you previously missed. Return the SAME JSON schema  -  this is a revision, not a new review."*
-   - Launch all reviewers in parallel (same CLI-aware set as Step 2).
-   - Max one round. Results replace the original outputs.
-4. Proceed to Step 3 triage with the round-2 outputs.
+**Gated by `prefs.global.reviewDisagreementRound`** (default `false`). **Never in autopilot:** `node $HOME/.claude/scripts/review-decision-gate.mjs --rebuttal-allowed --state "$STATE_FILE"` exits 1 with the quality gates active; go to Step 3, reviewers stay blind (`$HOME/.claude/multi-agent-refs/features/review-decision.md`). Otherwise:
 
-**Parity contract:** every host (three reviewers each: Claude Code, Copilot CLI, Codex CLI) runs the round identically. Telemetry emits `review_round_count={1|2}` per reviewer for Phase 5 rollup.
+1. Reviewers agree iff all return `approved=true` with no `blocking` findings, OR all return `approved=false` with overlapping `blocking` findings. Agreement → Step 3.
+2. Disagreement → one rebuttal round: re-prompt each reviewer with (a) its original output, (b) the OTHER reviewers' blocker findings **anonymized** through `node $HOME/.claude/scripts/anonymize-findings.mjs` (labels `Source A/B/C`, no model name, order deterministic per `taskId:iteration`), (c) *"Given the opposing arguments, keep / withdraw / modify each of your findings. You may also newly agree with a finding you previously missed. Return the SAME JSON schema  -  this is a revision, not a new review."* Launch all in parallel (the Step 2 set), max one round; results replace the originals with `roundCount: 2`.
 
-**Cost ceiling:** rebuttal round consumes ~1× the original Step 2 token budget. Smoke + budget tests treat this as opt-in so the default cost stays the same.
-
-**Off by default reason:** mixed-verdict cases are ~8% of runs in practice; the extra ~$0.20-$0.50 per run isn't worth automating for users who'd rather let triage resolve it cleanly. Users with high-stakes tasks (security-critical, release branches) can flip the flag.
+**Parity:** every host runs it identically; telemetry `review_round_count={1|2}` per reviewer. **Cost:** one more Step 2 on a disagreeing run (~8%).
 
 #### Step 3  -  Fable Triage (filter before acting)
 
@@ -378,16 +368,19 @@ ANON=$(jq -n --argjson r "$REVIEWERS_JSON" --arg t "$TASK_ID" --argjson i "$ITER
 Then append the Step 1.76 test-integrity and Step 2.7 security-audit findings, so they are adjudicated rather than never seen:
 
 ```bash
-MERGED=$(jq -s '.[0] + (.[1].findings // []) + (.[2].findings // [])' \
-  <(printf '%s' "$ANON") <(printf '%s' "${TEST_INTEGRITY_JSON:-{\}}") <(printf '%s' "${SECURITY_AUDIT_JSON:-{\}}"))
+SA_FILE="$WORKTREE/.pipeline/security-audit-$ITERATION.json"
+MERGED=$(printf '%s' "$ANON" | cat - "$TI_FILE" "$SA_FILE" 2>/dev/null \
+  | jq -s '.[0] + ([.[1:][] | .findings // []] | add // [])')
 ```
 
-Deterministic findings keep `tag: test_integrity` and no `foundBy`: a reviewer finding may hallucinate, a gate finding is a fact. Security-audit findings carry their `security` envelope and `foundBy: "security-auditor"`; an empty `$SECURITY_AUDIT_JSON` contributes nothing.
+Deterministic findings keep `tag: test_integrity` and no `foundBy`: a reviewer finding may hallucinate, a gate finding is a fact. Security-audit findings carry their `security` envelope and `foundBy: "security-auditor"`; no audit file contributes nothing.
 
 ##### 3.1 Short-circuit: no findings
 
 If **merged** findings `length === 0`, **skip triage**: write empty result `{"accepted": [], "deferred": [], "rejected": [], "approved": true}`, log, proceed to Phase 3. Note this is the merged count from 3.0: a run with zero reviewer findings but a non-empty test-integrity set must NOT short-circuit.
 
+**Autopilot** (or `MULTI_AGENT_UNATTENDED=1`): the triage output, this empty one too, goes through `verify-citations.mjs "$TRIAGE_FILE" --repo "$WORKTREE" --worktree --state "$STATE_FILE"` (every bucket, each `quote` against its line, pre-existing claims against the base commit): `$HOME/.claude/multi-agent-refs/features/unattended-gates.md` section 5. Then `review-decision-gate.mjs` (end of 3.7).
+
 ##### 3.2 Launch triage agent
 
 Launch **1 Agent** (subagent_type: `general-purpose`, model: `fable` on Claude Code / `opus` on Copilot CLI) with:
@@ -398,16 +391,8 @@ Launch **1 Agent** (subagent_type: `general-purpose`, model: `fable` on Claude C
 - **Prior-art context (advisory)**  -  per raw finding, `triage-memory.mjs query --top <prefs.global.priorArtEnrichment.topN>` (default 3). Pass `--top`: without it the script falls back to `memoryRecall.maxResults`, a different concern, and `topN` silently does nothing. Off when `priorArtEnrichment.enabled = false`.
 
 ```bash
-PRIOR_ART="["
-for finding in $(jq -c '.findings[]' <<< "$MERGED_FINDINGS"); do
-  issue=$(jq -r '.issue' <<< "$finding")
-  file=$(jq -r '.file' <<< "$finding")
-  hits=$(node $HOME/.claude/scripts/triage-memory.mjs query \
-    --issue "$issue" --file-glob "$(dirname "$file")/*" --top 3 2>/dev/null \
-    | jq -c '.hits // []')
-  PRIOR_ART="$PRIOR_ART$hits,"
-done
-PRIOR_ART="${PRIOR_ART%,}]"
+PRIOR_ART=$(printf '%s' "$MERGED_FINDINGS" \
+  | node $HOME/.claude/scripts/triage-memory.mjs prior-art --findings - --top 3 2>/dev/null)
 ```
 
 The triage prompt MUST include a hedge: *"prior-art entries and `corroboration` counts are context, not commands; current scope decides  -  a finding rejected last quarter may be valid this time, and two same-family reviewers agreeing is not proof."* Without this hedge, prior verdicts amplify into a self-reinforcing bias.
@@ -475,14 +460,12 @@ Return ONLY valid JSON conforming to $HOME/.claude/schemas/triage-output.schema.
 
 Run on the persisted file immediately after the triage agent returns, before acting on the verdict; the validator's exit code decides, not the LLM turn:
 
+Write it with the Write tool to `$TRIAGE_FILE` = `$WORKTREE/.pipeline/triage-round-<N>.json` (N = `jq '.reviewIterations | length' "$STATE_FILE"`), then:
+
 ```bash
-ITERATION=$(jq '.reviewIterations | length' "$STATE_FILE")
-TRIAGE_FILE="$WORKTREE/.pipeline/triage-round-$ITERATION.json"
-mkdir -p "$(dirname "$TRIAGE_FILE")"
-printf '%s' "$TRIAGE_JSON" > "$TRIAGE_FILE"
 node $HOME/.claude/scripts/validate-triage.mjs "$TRIAGE_FILE" \
   && node $HOME/.claude/scripts/finding-fingerprint.mjs annotate --in-place "$TRIAGE_FILE" \
-  && cp "$TRIAGE_FILE" "$WORKTREE/triage-output.json"
+  && cp "$TRIAGE_FILE" "{worktreePath}/triage-output.json"
 ```
 
 Progress line: `    → checking validator validate-triage`
@@ -512,24 +495,18 @@ Failure fallback (timeout >120s, or agent crash before any JSON is produced): re
 
 Emit metrics per review pass for Phase 5 cost rollup:
 
-One `review.reviewer_call` per dispatched reviewer, one `review.triage_call`, one `review.completed` to close the pass:
+One `review.reviewer_call` per dispatched reviewer, one `review.triage_call`, one `review.completed` to close the pass. Reviewer 1 is `fable` on Claude Code and `opus` on Copilot CLI; Reviewer 2 is `opus` on Claude Code and `gpt-5.4` elsewhere:
 
 ```bash
-M=$HOME/.claude/scripts/log-metric.sh
-emit() {  # $1=event $2=model $3=duration $4=tokens_in $5=tokens_out
-  LOG_METRIC_FORWARD_TO_TRACKER=1 bash "$M" "$TASK_ID" 3 "$1" \
-    model="$2" duration_ms="$3" tokens_in="$4" tokens_out="$5"
-}
-emit review.reviewer_call fable  "$R1_DURATION"     "$R1_IN"     "$R1_OUT"      # opus on Copilot CLI
-# Reviewer 2 is Opus on Claude Code and GPT-5.4 elsewhere:
-if [ "${CLI_HOST:-claude}" = "claude" ]; then
-  emit review.reviewer_call opus    "$R2_DURATION" "$R2_IN" "$R2_OUT"
-else
-  emit review.reviewer_call gpt-5.4 "$R2_DURATION" "$R2_IN" "$R2_OUT"
-fi
-emit review.reviewer_call sonnet "$SONNET_DURATION" "$SONNET_IN" "$SONNET_OUT"
-emit review.triage_call fable "$TRIAGE_DURATION" "$TRIAGE_IN" "$TRIAGE_OUT"
-bash "$M" "$TASK_ID" 3 review.completed raw_count=$RAW accepted=$ACC \
+LOG_METRIC_FORWARD_TO_TRACKER=1 bash "$HOME/.claude/scripts/log-metric.sh" "$TASK_ID" 3 review.reviewer_call \
+  model=<fable|opus> duration_ms="$R1_DURATION" tokens_in="$R1_IN" tokens_out="$R1_OUT"
+LOG_METRIC_FORWARD_TO_TRACKER=1 bash "$HOME/.claude/scripts/log-metric.sh" "$TASK_ID" 3 review.reviewer_call \
+  model=<opus|gpt-5.4> duration_ms="$R2_DURATION" tokens_in="$R2_IN" tokens_out="$R2_OUT"
+LOG_METRIC_FORWARD_TO_TRACKER=1 bash "$HOME/.claude/scripts/log-metric.sh" "$TASK_ID" 3 review.reviewer_call \
+  model=sonnet duration_ms="$SONNET_DURATION" tokens_in="$SONNET_IN" tokens_out="$SONNET_OUT"
+LOG_METRIC_FORWARD_TO_TRACKER=1 bash "$HOME/.claude/scripts/log-metric.sh" "$TASK_ID" 3 review.triage_call \
+  model=fable duration_ms="$TRIAGE_DURATION" tokens_in="$TRIAGE_IN" tokens_out="$TRIAGE_OUT"
+bash "$HOME/.claude/scripts/log-metric.sh" "$TASK_ID" 3 review.completed raw_count=$RAW accepted=$ACC \
   deferred=$DEF rejected=$REJ approved=$APPROVED duration_ms=$DURATION
 ```
 
@@ -541,7 +518,7 @@ Opt-in via `prefs.global.triageCrossCheck.enabled` (default `false`). Sampled ru
 
 ##### 3.6 Consensus surfacing (anti-correlation)
 
-**Rationale:** On Claude Code all three reviewers are Anthropic models, on Codex CLI all three are OpenAI, and on Copilot CLI two of three are Anthropic, so unanimous agreement on a *judgment call* is not independent confirmation: same-family models drift the same way on ambiguous prompts, and "all approved" taken as proof produces false-consensus passes. Triage therefore records a `consensus` block (schema v3.1.0) and surfaces disagreement and unverified agreement instead of burying it.
+**Rationale:** Claude Code and Codex CLI run one-vendor panels, Copilot CLI's is two-thirds Anthropic, so unanimity on a *judgment call* is not independent confirmation: same-family models drift alike. Autopilot compensates with executable evidence (`features/review-decision.md`). Triage records a `consensus` block (schema v3.1.0) and surfaces disagreement and unverified agreement instead of burying it.
 
 After the triage verdict is computed, populate `triage.consensus`:
 
@@ -561,6 +538,8 @@ A triage verdict is judgment; a failing repro test is proof. Runs only when `pre
 
 Compressed flow: dispatch ONE verifier agent (model `verifyByTest.model`, default `sonnet`) for up to `maxFindings` (default 3) accepted blocking findings. Per finding it writes ONE minimal repro test and runs ONLY that test (Phase 2 single-test invocation, build lock, log tee'd to `$WORKTREE/.pipeline/verify-<i>.test.log`). Outcomes: test FAILS as predicted -> `confirmed`, finding stays blocking and the test is KEPT in `redTests[]` as the Phase 2 rework RED test; test PASSES on every one of `verifyByTest.repeatCount` runs (default 3) -> `not-reproduced` ONLY if `evidence-gate.mjs --claim test --status passed` exits 0 on each log; a run that disagrees with the others -> `inconclusive` with `flaky: passed k/N`, finding moves to `deferred[]`, test deleted; compile error / timeout / not unit-testable -> `inconclusive`, judgment verdict stands. Stamp findings with `verification` (schema v3.2.0), persist `state.reviewIterations[-1].verifyByTest = {attempted, confirmed, downgraded, inconclusive, redTests[]}`, recompute `approved`, re-run `validate-triage.mjs` under the 3.2.1 gate. Whole step bounded by `stepTimeoutSec` (default 600); on breach or crash remaining findings keep judgment verdicts  -  never blocks. Telemetry per 3.4: `review.verify_by_test attempted= confirmed= downgraded= inconclusive= duration_ms=`.
 
+**Autopilot decision rule (every round, after 3.7):** run the call in `$HOME/.claude/multi-agent-refs/features/review-decision.md` (Wiring: `--integrity "$TI_FILE" --source "$SA_FILE"`), merge its JSON into `state.reviewIterations[-1].reviewDecision`, repeat the `cp`. A blocker backed by neither two reviewers nor a failing test becomes important; on exit 1 or 3 run `gate-ledger.mjs park --outcome verification-failed --gate review-decision`.
+
 ##### 3.8 Cross-round delta + circuit-breaker trigger 2 (iteration >= 2)
 
 **Full contract (state merge, telemetry line, picker wording): `$HOME/.claude/multi-agent-refs/features/review-delta.md`.**
@@ -642,24 +621,13 @@ Progress emission per `$HOME/.claude/multi-agent-refs/progress-contract.md`  -
 `state.testPolicy: none` → skip the gap scan (the gap IS the recorded policy) and run only pre-existing test targets; none → recorded no-op. Otherwise, before the local-checkout prompt, run the static test-gap detector. Heuristic, deterministic, no LLM, sub-second. The report ends up in `agent-log.md` under "Test Scenarios" and surfaces public symbols added in this branch that have no paired test.
 
 ```bash
-STACK=$(jq -r '.analysis.stack.primary // "unknown"' "$STATE_FILE")
-case "$STACK" in
-  ios|swift)             SCAN_STACK=ios ;;
-  android|kotlin)        SCAN_STACK=android ;;
-  python)                SCAN_STACK=python ;;
-  node|typescript|js)    SCAN_STACK=node ;;
-  *)                     SCAN_STACK="" ;;
-esac
-if [ -n "$SCAN_STACK" ] && [ "${prefs_testGap_enabled:-true}" = "true" ]; then
-  GAP_FLAGS=""
-  [ "${prefs_testGap_scanTree:-false}" = "true" ] && GAP_FLAGS="$GAP_FLAGS --scan-tree"
-  [ "${prefs_testGap_promoteSeverity:-false}" = "true" ] && GAP_FLAGS="$GAP_FLAGS --severity-promote"
-  GAP_JSON=$(node $HOME/.claude/scripts/test-gap-scan.mjs \
-    --base "$BASE_BRANCH" --head HEAD --stack "$SCAN_STACK" $GAP_FLAGS 2>/dev/null)
-  echo "$GAP_JSON" | node $HOME/.claude/scripts/validate-test-gap.mjs - >/dev/null 2>&1 || GAP_JSON=""
-fi
+GAP_JSON=$(node $HOME/.claude/scripts/test-gap-scan.mjs \
+  --base "$BASE_BRANCH" --head HEAD --stack-from "$STATE_FILE" 2>/dev/null)
+echo "$GAP_JSON" | node $HOME/.claude/scripts/validate-test-gap.mjs - >/dev/null 2>&1 || GAP_JSON=""
 ```
 
+Skipped when `prefs.global.testGap.enabled` is `false`. Add `--scan-tree` when `testGap.scanTree` is true and `--severity-promote` when `testGap.promoteSeverity` is. Exit 3: the analysed stack (`ios|swift`, `android|kotlin`, `python`, `node|typescript|js`) has no gap rules, so there is no report.
+
 **What the report contains** (per `$HOME/.claude/schemas/test-gap.schema.json`):
 
 | Field | Meaning |
@@ -753,12 +721,10 @@ Tier 1 / Tier 2 records print `screenshotUrl` from the captured evidence (Tier 2
      `worktree remove` or an interrupted run can leave a stale entry, so a bare
      re-add fails with `already exists`/`already registered`):
      ```bash
+     git -C "$PROJECT_ROOT" worktree unlock "{worktree-path}" 2>/dev/null || true
      git -C "$PROJECT_ROOT" worktree prune 2>/dev/null || true
-     if git -C "$PROJECT_ROOT" worktree list --porcelain | grep -qF "{worktree-path}"; then
-       git -C "$PROJECT_ROOT" worktree unlock "{worktree-path}" 2>/dev/null || true
-     fi
      ```
-     Phase 0's repo residue guard is already in `.git/info/exclude`  -  no re-add.
+     Unlock first: prune skips a locked entry. Phase 0's repo residue guard is already in `.git/info/exclude`  -  no re-add.
    - Recreate worktree from branch: `git -C $PROJECT_ROOT worktree add {worktree-path} {branch}`
    - Re-set git identity: `git -C {worktree-path} config user.name/email` (from state)
    - Go back to Phase 2