@mmerterden/multi-agent-pipeline 16.18.0 → 16.20.0

package/pipeline/lib/shadow-git.sh

@@ -163,10 +163,12 @@ do_list() {
   require_task_id "$task_id"
   local sd; sd=$(shadow_dir "$task_id")
   [ ! -d "$sd/.git" ] && { err "shadow not initialized for $task_id"; exit 1; }
-  # Use the embedded `iso:` line from the commit message body so the listing
+  # Use the embedded `iso:` trailer from the commit message body so the listing
   # carries the snapshot timestamp without relying on committer date (which is
-  # influenced by git env vars).
-  sg "$sd" "$(pwd)" log --pretty=format:'%h  %s' --no-decorate
+  # influenced by git env vars); committer date is the fallback for a snapshot
+  # written without one.
+  sg "$sd" "$(pwd)" log --pretty=format:'%h%x1f%(trailers:key=iso,valueonly,separator=%x20)%x1f%cI%x1f%s' --no-decorate \
+    | awk -F'\037' '{ d = $2; sub(/ .*/, "", d); if (d == "") d = $3; printf "%s  %s  %s\n", $1, d, $4 }'
 }
 
 do_restore() {
@@ -213,7 +215,9 @@ do_prune() {
   local older=""
   while [ "$#" -gt 0 ]; do
     case "$1" in
-      --older-than-days) older="$2"; shift 2 ;;
+      --older-than-days)
+        [ "$#" -ge 2 ] || { err "--older-than-days needs a value"; exit 2; }
+        older="$2"; shift 2 ;;
       *) err "unknown flag: $1"; exit 2 ;;
     esac
   done

package/pipeline/lib/vercel-deploy.sh

@@ -153,10 +153,10 @@ cmd_deploy() {
   if [ "$prod" = true ]; then
     cmd_args+=(--prod)
   fi
-  cmd_args+=("${extra_args[@]}")
+  cmd_args+=(${extra_args[@]+"${extra_args[@]}"})
 
   # Refuse to run if the user is trying to pass --token=... via extra args.
-  for a in "${extra_args[@]}"; do
+  for a in ${extra_args[@]+"${extra_args[@]}"}; do
     case "$a" in
       --token=*|--token)
         echo "ERROR: refused to deploy with --token argv. Pass the token via VERCEL_TOKEN env var instead." >&2

package/pipeline/multi-agent-refs/_dev-context.md

@@ -53,8 +53,11 @@ Selects extra repos the pipeline may touch beyond the primary repo(s)  -  typica
    entry, plus any selected `extras[]` that is not being given a worktree. The
    phases that consume them run hours later and have no access to the picker's
    return value, so a result that is not written here is a result nothing can
-   read - Phase 4's platform-parity cross-check reads `state.siblings[]` and
-   nothing else.
+   read. Phase 4's platform-parity cross-check reads `state.siblings[]` as the
+   fourth of its four counterpart sources, after `--with`,
+   `prefs.projects[<slug>].counterpartRoots[]` and the primary checkout's sibling
+   directories (`platform-parity.md`), so a submodule or a hand-picked repo that
+   is not written here is a candidate the check can never see.
 
    Resolve each entry's `stack` from its local checkout, with the marker table
    in `phases/phase-1-analysis.md` Step 2 (`.xcodeproj` / `Package.swift` →

package/pipeline/multi-agent-refs/analysis/locked.md

@@ -1,14 +1,14 @@
-# Locked decisions (35)
+# Locked decisions (36)
 
-> The 35 Locked decisions of the analysis flow. Loaded by `/multi-agent:analysis`, by `/multi-agent:analysis-resolve` (which inherits them) and by pipeline Phase 1 when it runs the analysis engine. Numbering is canonical: cite as `Locked <n> (<short label>)`.
+> The 36 Locked decisions of the analysis flow. Loaded by `/multi-agent:analysis`, by `/multi-agent:analysis-resolve` (which inherits them) and by pipeline Phase 1 when it runs the analysis engine. Numbering is canonical: cite as `Locked <n> (<short label>)`.
 
 ### Index by category (v9.1.0+)
 
-Browse-friendly grouping of the 35 Locked decisions. Numbering stays canonical (matches the list below); the index is read-only navigation.
+Browse-friendly grouping of the 36 Locked decisions. Numbering stays canonical (matches the list below); the index is read-only navigation.
 
 | Category | Decisions | Concern |
 |---|---|---|
-| **A. Governance** | 1, 5, 6, 7, 10, 26, 27, 32 | Run-level process rules: one feature per run, default output, auto-commit ban, punctuation policy, output picker timing, Pass B preview, evidence digest cache, analysis profile |
+| **A. Governance** | 1, 5, 6, 7, 10, 26, 27, 32, 36 | Run-level process rules: one feature per run, default output, auto-commit ban, punctuation policy, output picker timing, Pass B preview, evidence digest cache, analysis profile, document reviewed before publish |
 | **B. Citation and Evidence** | 3, 4, 8, 11, 24, 30, 34 | Every fact in the doc traces back to a source: citation discipline, forward-looking spec, standards binding, repo-evidence reuse-first, Pass B footnote mandatory, analysis self-contained (pipeline-wide), references built from the evidence record |
 | **C. Output Format and Structure** | 2, 9, 13, 14, 16, 17, 20, 21, 25, 33, 35 | How the document is laid out: section omission rule, per-platform output split, Gherkin user stories, Goals + Non-Goals paired, Files-to-Add tag, API response variants exhaustive, localization mode (ownership-aware), References at the bottom, Lite mode, corporate backbone always renders, stack-optional render |
 | **D. Design Source and Pipeline Architecture** | 12, 22, 23 | Where design comes from and how the pipeline renders: Figma 3-tier access (BLOCKING), platform-agnostic template + Pass B render, convention extraction (Phase 1c) |

package/pipeline/multi-agent-refs/analysis/render.md

@@ -12,7 +12,7 @@
 
    **When `platforms[]` is empty** (Locked 35), the channels come from the evidence instead of from repo stack tags, so this loop runs once per derived channel (`mobile`, `web`, or one channel-agnostic pass). What drops is the development layer (corporate Part C, global Sections 13, 14, 15) and the Pass B projection are skipped, Section 20 carries a row recording that they await a repo selection, and the front-matter `platform` key reads `none`. Everything that does not need a target repository still renders in full.
 
-3. **Humanizer pass (MANDATORY: actually invoke the `ai-common-toolkit:humanizer` skill on the rendered markdown - the punctuation grep alone does NOT satisfy this step)** (`technical-explanatory` tone for the scratch buffer; per-channel re-humanize happens in Phase 4 when actually emitting):
+3. **Humanizer pass (required: actually invoke the `ai-common-toolkit:humanizer` skill on the rendered markdown - the punctuation grep alone does NOT satisfy this step)** (`technical-explanatory` tone for the scratch buffer; per-channel re-humanize happens in Phase 4 when actually emitting):
    ```
    ai-common-toolkit:humanizer skill input:
      language: <tr|en>

package/pipeline/multi-agent-refs/channels/pr.md

@@ -14,14 +14,15 @@ The PR description targets code reviewers  -  it stays technical. Every adapter
 | 2 | `changes` | `## Değişiklikler` | `## Changes` | always |
 | 3 | `architecture` | `## Mimari Kararlar` | `## Architecture Decisions` | when a non-trivial design choice was made |
 | 4 | `verification` | `## Doğrulama` | `## Verification` | always |
-| 5 | `dependencies` | `## Bağımlılıklar` | `## Dependencies` | when deps added/removed/bumped |
-| 6 | `related` | `## İlgili` | `## Related` | always (Jira/issue ref; never `Closes/Fixes`) |
+| 5 | `risk` | `## Risk ve Güvenlik` | `## Risk and Security` | when `state.diffRisk.signals` carries a high-stakes signal (`security_path`, `migration`, `public_api`, `no_test_change`, `test_lines_removed`) |
+| 6 | `dependencies` | `## Bağımlılıklar` | `## Dependencies` | when deps added/removed/bumped |
+| 7 | `related` | `## İlgili` | `## Related` | always (Jira/issue ref; never `Closes/Fixes`) |
 
 ### Section content rules
 
 **`summary`**  -  1-3 sentences in `outputLanguage`. The "why" of the change. Past tense, no marketing voice. Code identifiers stay verbatim.
 
-**`changes`**  -  bullet list, one item per logically distinct change. Each bullet starts with the touched component and ends with a one-line "what". Use the stack's native file extensions / module paths  -  the example below shows the **shape**, not a stack lock-in:
+**`changes`**  -  bullet list, one item per logically distinct change. Each bullet starts with the touched component and ends with a one-line "what". The source is `$WORKTREE/.pipeline/scope-check.json` `files[].reason` (Phase 3 Step 3.7): a file the dev could not justify there is a file this list cannot describe either, so the bullet quotes the gate output instead of inventing a reason. Use the stack's native file extensions / module paths  -  the example below shows the **shape**, not a stack lock-in:
 
 ```markdown
 ## Changes
@@ -50,6 +51,17 @@ Skeleton (the adapter fills the body with the actual stack-appropriate lines at
 
 Multi-repo PRs (one PR per repo) emit verification commands for that repo's stack only  -  never mix iOS + Android commands into a single PR body.
 
+**`risk`**  -  only when `state.diffRisk.signals` (Phase 4 Step 1.75) contains a high-stakes signal. Four fixed lines, each answered, never left as a placeholder; the source is Phase 1 `touchedAreas` plus the signals themselves, and when a signal is present the absence of this section is a Phase 6 Step 3 blocker:
+
+```markdown
+## Risk and Security
+
+- Auth flow touched: yes | no
+- Secret handling changed: yes | no
+- Data migration: yes | no
+- Rollback: feature flag <name> | git revert <sha> | none, and why
+```
+
 **`dependencies`**  -  only when `Package.swift` / `Podfile` / `build.gradle` / `package.json` changed. Each entry: `package@old → new  -  reason`.
 
 **`related`**  -  flat list, plain text. Examples:
@@ -61,15 +73,21 @@ Multi-repo PRs (one PR per repo) emit verification commands for that repo's stac
 - Issue: #123
 - Confluence: <page-url> (if work referenced a spec)
 - Figma: <design-url> (if work referenced a design)
+
+Follow-ups not done in this PR:
+- <scope-check.json notDone[].what>  -  <why>
+- <deferred triage finding>  -  <triage reason>
 ```
 
+The follow-up list is present only when `scope-check.json` `notDone[]` or the final triage `deferred[]` is non-empty; the two sources merge into one list.
+
 Never use `Closes #N`, `Fixes #N`, `Resolves PROJ-X`. Issues require 4-approval close, the auto-close keywords break that contract.
 
 ### Assembly order (per run)
 
 ```
 1. Read agent-state.json (taskId, contextLinks, identity, language).
-2. Build section bodies in markdown  -  summary first, then in the table order, skipping conditional sections that don't apply.
+2. Build section bodies in markdown  -  summary first, then in the table order, skipping conditional sections that don't apply. Section order is fixed: `summary` → `changes` → `architecture` (cond.) → `verification` → `risk` (cond.) → `dependencies` (cond.) → `related`.
 3. Run the assembled body through the `humanizer` skill.
 4. Apply Multi-repo cross-links (## Related PRs prepend when projects.length > 1).
 5. Dispatch per the Behaviour-by-remote table.

package/pipeline/multi-agent-refs/cross-cli-contract.md

@@ -207,7 +207,7 @@ Future changes that break an item in the "stay identical" list must update **bot
 
 Each file has a different frontmatter schema. The sync flow transforms between them:
 
-### 3.1 Claude Code  -  `commands/multi-agent/{cmd}.md`
+### 3.1 Claude Code  -  `commands/multi-agent/{cmd}/SKILL.md`
 
 ```yaml
 ---

package/pipeline/multi-agent-refs/features/autopilot-circuit-breaker.md

@@ -2,7 +2,7 @@
 
 **Pattern**: autopilot runs with zero interaction, which is exactly when a silent failure loop is most expensive  -  an agent can burn a budget re-attempting the same broken fix, or thrash between two phases, with nobody watching. A circuit-breaker converts "keep going no matter what" into "keep going until a defined unsafe condition, then halt and hand back to the user." This is the sanctioned autopilot pause (same class as the Phase 7 channels pause): the run stops, records why, and waits for an explicit `resume`.
 
-**Gated by `prefs.global.autopilotCircuitBreaker`** (default: enabled; thresholds tunable). Halting is always safe, so the breaker itself defaults on. Disable per-run only with an explicit override. Complements, does not replace, the existing autopilot safety rules (build-fail max 3 retries, Phase 4 blocking-finding rework, destructive-op confirmations).
+**Gated by `prefs.global.autopilotCircuitBreaker`** (`enabled` default true, `identicalFindingCycles` default 2, `maxReworkCycles` default 3; `schemas/prefs.schema.json`). Halting is always safe, so the breaker itself defaults on. Disable per-run only with an explicit override. Complements, does not replace, the existing autopilot safety rules (build-fail max 3 retries, Phase 4 blocking-finding rework, destructive-op confirmations).
 
 ## Trip conditions
 
@@ -18,12 +18,25 @@ Any one trips the breaker. All are evaluated from `agent-state.json` + telemetry
 
 Trigger 2 is the key addition over the plain build-retry cap: a build can "fail differently" three times (legitimate iteration) or "fail identically" twice (stuck). Only the identical-failure case is a stall; the retry cap catches the rest.
 
+## Wiring status
+
+| Trigger | Evaluated by | Status |
+|---|---|---|
+| 2, finding half | `review-delta.mjs` exit 3 at Phase 4 Step 3.8: a blocking/important finding whose `fingerprint` (finding-fingerprint.mjs) stays in the accepted set for `identicalFindingCycles` consecutive rounds | **code** (v16.20.0) |
+| 3 | Phase 3 re-entry item 6: the `retryCount === 3` hard-kill records the trip | **code** (v16.20.0) |
+| 2, build-error half | needs a build-log signature normaliser | documented behaviour, no script yet |
+| 1 | needs checkpoint-to-checkpoint artifact diffing | documented behaviour, no script yet |
+| 4 | belongs to `cost-budget-check.mjs` | documented behaviour, no script yet |
+| 5 | Phase 6 push | documented behaviour, no script yet |
+
+State shape: `state.circuitBreaker = {tripped, trigger, detail, checkpoint: {phase, step, iteration}, trippedAt, counters: {identicalFindingCycles, reworkCycles}}` (`schemas/agent-state.schema.json`). The per-round classification the finding half reads lives in `state.reviewIterations[i].delta` (`new`, `stillPresent`, `resolved`, `downgraded`, `recurrence`, `plateau`). `smoke-autopilot-circuit-breaker.sh` asserts the schema fields, the scripts and the phase wiring, not only this prose.
+
 ## Action on trip
 
 1. Set `agent-state.json.circuitBreaker = {tripped: true, trigger: <#>, detail, checkpoint}` and flip `autopilot` handling to paused (the run does not continue unattended).
 2. Emit one actionable line per the progress contract: what tripped, the evidence (error signature / cycle count / spend vs ceiling), and the single next action (`resume #N` after a fix, or `kill #N`).
 3. Never auto-resolve the underlying cause  -  no force-anything, no conflict auto-merge, no budget self-raise. The breaker hands control back; it does not paper over the problem.
-4. `resume #N` clears the tripped flag and continues from the recorded checkpoint. If the same trigger fires again immediately, the breaker re-trips (no silent bypass).
+4. `resume #N` clears `circuitBreaker.tripped` (keeping `counters`) and continues from the recorded checkpoint. If the same trigger fires again immediately, the breaker re-trips (no silent bypass).
 
 ## Why this is the right autopilot exception
 

package/pipeline/multi-agent-refs/features/review-delta.md

@@ -0,0 +1,89 @@
+# Feature: Cross-round review delta (Phase 4 Steps 2.1, 2.2, 3.8)
+
+**Pattern**: reviewers re-read the whole diff every round with no memory of the round before, so they rediscover last round's findings in new words and nothing can tell "still broken" from "new". A finding therefore needs an identity that survives the fix: `finding-fingerprint.mjs` computes `F:xxxxxxxx` from the file and either the cited `ruleId` or the normalised issue text (lowercase, quotes stripped, paths reduced to basenames, digit runs collapsed). The line, the severity, the fix text and the reviewer take no part, because all of them change between rounds without the finding changing. `review-delta.mjs` then compares round N with round N-1 and reports `stillPresent`, `resolved`, `downgraded` (re-reported but no longer accepted by triage) and `new`, plus `recurrence`: how many consecutive rework cycles each survivor has lasted. That count is the autopilot circuit-breaker's trigger 2.
+
+Gated by `prefs.global.autopilotCircuitBreaker` (`enabled` default true, `identicalFindingCycles` default 2). Computed by scripts, never by the model: an older triage JSON gets its fingerprints on the fly, and a reviewer that echoes one is respected but not relied on.
+
+## Files per round
+
+Phase 4 Step 3.2.1 writes `$WORKTREE/.pipeline/triage-round-<N>.json` (N = `state.reviewIterations | length`), validates it, annotates it and copies it to `$WORKTREE/triage-output.json`, the name Phase 7, `worktree-finalize.sh`, `render-work-summary.sh` and `diff-explain.mjs` read. A copy rather than a symlink because the salvage is `cp -R`, and `.pipeline/` is on the salvage list, so every round survives into `artifactsPath`. Step 3.7 rewrites the round file; the copy is repeated after it.
+
+## Step 2.1 block: previous-round findings (iteration >= 2)
+
+```bash
+ITERATION=$(jq '.reviewIterations | length' "$STATE_FILE")
+PREV_ROUND="$WORKTREE/.pipeline/triage-round-$((ITERATION-1)).json"
+PREV_BLOCK=""
+[ "$ITERATION" -ge 2 ] && [ -f "$PREV_ROUND" ] && PREV_BLOCK=$(node $HOME/.claude/scripts/finding-fingerprint.mjs annotate "$PREV_ROUND" 2>/dev/null \
+  | jq -r '[.accepted[] | select(.severity=="blocking" or .severity=="important")] | sort_by(.severity != "blocking") | .[:40][] | "- \(.fingerprint) [\(.severity)] \(.file): \(.issue)"')
+```
+
+Rendered at the end of the shared prefix (Step 1.9), identical for every reviewer and for the triage call of that iteration:
+
+```
+<previous-round-findings>
+Each entry below was accepted last round and sent for rework.
+- If the issue is still present, report it again with the SAME fingerprint value and the current line.
+- If it is fixed, omit it. Omission is how you report resolution; never emit a "resolved" finding.
+- Any finding not listed here is new: leave fingerprint unset.
+{PREV_BLOCK}
+</previous-round-findings>
+```
+
+The cap of 40 entries drops `important` before `blocking` so the prefix stays bounded. The block never enters the repo-stable prefix `prompt-assembly.md` describes: the diff it follows is already per-run. After each reviewer's validator gate, `finding-fingerprint.mjs annotate --in-place` fills in any fingerprint the reviewer left unset; `anonymize-findings.mjs` strips only identity keys, so the fingerprint reaches triage, and the triage prompt tells the model to preserve it verbatim.
+
+## Step 2.2 block: scope self-check (every iteration)
+
+Phase 3 Step 3.7 wrote `$WORKTREE/.pipeline/scope-check.json` (contract: `features/scope-check.md`). Render it so reviewers judge the diff against the dev's stated scope and do not re-propose what was rejected:
+
+```bash
+SCOPE_JSON="$WORKTREE/.pipeline/scope-check.json"
+SCOPE_GATE=$(git -C "$WORKTREE" diff --name-only "origin/$BASE_BRANCH"...HEAD \
+  | node $HOME/.claude/scripts/scope-check-gate.mjs --check "$SCOPE_JSON" --diff-files - --advisory 2>/dev/null)
+```
+
+```
+<scope-self-check>
+Files and the reason the dev gave for touching each:
+{jq -r '.files[] | "- \(.path): \(.reason)"' "$SCOPE_JSON"}
+Files in the diff with no stated reason (flag as scope drift if the change is not obviously required):
+{jq -r '.unjustified[]' <<< "$SCOPE_GATE"}
+Deliberately not done (do not raise these as findings; they are known):
+{jq -r '.notDone[] | "- \(.what) (\(.why))"' "$SCOPE_JSON"}
+</scope-self-check>
+```
+
+A missing record renders the block with `no scope-check.json written` and a `review.scope_check=missing` metric; the review proceeds, and the absence is itself information for the reviewer.
+
+## Step 3.8: delta + trigger 2
+
+```bash
+TRIP=$(jq -r '.global.autopilotCircuitBreaker.identicalFindingCycles // 2' "$PREFS_FILE")
+DELTA_JSON=$(node $HOME/.claude/scripts/review-delta.mjs --rounds-dir "$WORKTREE/.pipeline" --iteration "$ITERATION" --trip-cycles "$TRIP"); DELTA_RC=$?
+jq -c --argjson d "$DELTA_JSON" --argjson i "$((ITERATION-1))" \
+  '{reviewIterations: (.reviewIterations | .[$i] += {delta: ($d + {computedAt: (now | todate)})})}' "$STATE_FILE" \
+  | node $HOME/.claude/scripts/write-state.mjs "$STATE_FILE"
+$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 4 review.delta iteration=$ITERATION \
+  new=$(jq '.counts.new // 0' <<< "$DELTA_JSON") still_present=$(jq '.counts.stillPresent // 0' <<< "$DELTA_JSON") \
+  resolved=$(jq '.counts.resolved // 0' <<< "$DELTA_JSON") plateau=$(jq '.plateau // false' <<< "$DELTA_JSON") tripped=$([ "$DELTA_RC" -eq 3 ] && echo true || echo false)
+```
+
+| Exit | Meaning | Action |
+|---|---|---|
+| 0 | Progress, or nothing to compare (iteration 1, missing previous round) | Continue to Step 4. |
+| 3 | A blocking/important finding survived `identicalFindingCycles` consecutive rework cycles | **Autopilot** with `enabled`: trip the breaker. `state.circuitBreaker = {tripped: true, trigger: 2, detail: "finding <fingerprint> (<file>: <issue>) survived <n> consecutive rework cycles", checkpoint: {phase: 4, step: "3.8", iteration: N}, trippedAt, counters: {identicalFindingCycles: <max recurrence>, reworkCycles: N-1}}`, then the halt-visibility protocol from `phases/operations.md` (`status=paused`, `haltReason="4:circuit-breaker:identical-finding"`, tracker meta, the `>&2 HALT` line, the usage report). **Interactive modes**: do not trip; show `delta.stillPresent` and ask (picker-contract) `Continue rework` / `Escalate to me` / `Accept as deferred`, the last moving those findings to `deferred[]` with reason `circuit-breaker: accepted by user after <n> cycles`. |
+| 1 | Unreadable round file | Log `review.delta_skipped reason=invalid` and continue; the delta is advisory and never blocks on its own failure. |
+
+`plateau` (the still-present set unchanged from the previous delta) is logged, not acted on: at the default threshold it coincides with trigger 2 and with the Phase 3 `retryCount` hard-kill. The rework-storm cap itself is trigger 3, recorded by the Phase 3 re-entry. The Phase 3 reflection prompt names each accepted finding by `fingerprint` and quotes `delta.stillPresent` first, marked `STILL PRESENT after round N-1's fix`.
+
+## Why fingerprints are computed, not stored
+
+Same argument `shortId()` in `_retrieval.mjs` makes for corpus rows: derived from the finding's own content, so existing triage files get ids without a migration and a re-annotated file keeps the ids it had. The known trade-off is over-merging: two findings in one file that differ only by a number share a fingerprint. The delta output prints `file: issue` beside every id and the trip needs two consecutive recurrences, so a merge is visible and cannot halt a run by itself. Under-merging (a reviewer that rewrites rather than echoes) only ever suppresses a trip; it never causes one.
+
+## Telemetry
+
+`review.delta` once per iteration >= 2: `iteration`, `new`, `still_present`, `resolved`, `plateau`, `tripped`. `run-metrics.mjs` reports `reviewDelta.stillPresentFinal`, `resolvedTotal` and `tripped`; Phase 7 renders the three counts per round.
+
+## Reference
+
+Scripts: `$HOME/.claude/scripts/_fingerprint.mjs`, `finding-fingerprint.mjs`, `review-delta.mjs`. Schemas: `reviewer-output` 1.2.0, `triage-output` 3.4.0, `dev-critic-output` (optional `fingerprint`), `agent-state` (`reviewIterations[].delta`, `circuitBreaker`). Breaker: `features/autopilot-circuit-breaker.md`. Smokes: `smoke-review-delta.sh`, `smoke-autopilot-circuit-breaker.sh`.

package/pipeline/multi-agent-refs/features/scope-check.md

@@ -0,0 +1,41 @@
+# Feature: Scope self-check (Phase 3 Step 3.7)
+
+**Pattern**: Phase 4 reconstructs everything from the diff. The one thing it cannot reconstruct is why each file was touched and what was left out on purpose, so Dev states both before the handoff, and a deterministic gate checks the statement against the real diff. The record also carries the code-simplifier rationales (Step 3.6) that used to be discarded, and it feeds two later consumers: the `<scope-self-check>` block in the Phase 4 reviewer prefix and the PR body in Phase 6.
+
+## The record
+
+`$WORKTREE/.pipeline/scope-check.json`, schema `schemas/scope-check.schema.json`:
+
+```json
+{
+  "version": "1.0.0",
+  "taskId": "<taskId>",
+  "files": [{ "path": "<repo-relative path>", "reason": "<why this task needs this exact file>" }],
+  "notDone": [{ "what": "<change considered and not made>", "why": "out-of-scope | follow-up | rejected-abstraction" }],
+  "simplifier": { "applied": 0, "skipped": 0, "rationales": ["<Step 3.6 rationale strings>"] }
+}
+```
+
+Rules:
+
+- One entry per file in the diff, no entry for a file outside it. A reason names the task requirement, never "while I was here".
+- `notDone` carries every hypothetical the dev chose not to defend against and every abstraction it considered and rejected, so review does not re-propose them.
+- Component tasks (`taskType === "component"`) write the record too; the plugin skill's file table is the `files[]` source.
+
+## The gate
+
+```bash
+git -C "$WORKTREE" diff --name-only "origin/$BASE_BRANCH"...HEAD \
+  | node $HOME/.claude/scripts/scope-check-gate.mjs --check "$WORKTREE/.pipeline/scope-check.json" --diff-files -
+```
+
+Output `{ok, justified, unjustified[], unlisted[], notDone}`. Exit 1 lists `unjustified[]` (in the diff, no reason or an empty one); `unlisted[]` (in the record, not in the diff) is reported and never fatal. Complete the record once and re-run. A second exit 1 does not block: log `dev.scope_check=incomplete unjustified=<n>` and hand off; Phase 4 receives the gate output inside `<scope-self-check>`, so reviewers see which files arrived without a stated reason. `--advisory` (used by Phase 4) always exits 0. Progress line: `    → checking scope self-check ({n} files, {m} not done)`.
+
+## Consumers
+
+- Phase 4 Step 2.2 renders file reasons, unjustified files and `notDone[]` into the shared reviewer prefix (`features/review-delta.md`).
+- Phase 6 Step 3 builds the PR `## Changes` bullets from `files[].reason` and lists `notDone[]` under `## Related` as "Follow-ups not done in this PR", merged with the final triage `deferred[]` (`channels/pr.md`).
+
+## Reference
+
+Script: `$HOME/.claude/scripts/scope-check-gate.mjs`. Schema: `$HOME/.claude/schemas/scope-check.schema.json`. Smoke: `smoke-scope-check.sh`. Unit: `test/scope-check-gate.test.mjs`.

package/pipeline/multi-agent-refs/features/verify-by-test.md

@@ -5,7 +5,7 @@
 **Gated by `prefs.global.verifyByTest.enabled`** (default: `false`). When enabled, after triage 3.6 and before Step 4, IF the validated triage output contains at least one `accepted` blocking finding:
 
 1. Dispatch ONE verifier sub-agent for the iteration (model: `verifyByTest.model`, default `sonnet`)  -  never one dispatch per finding. Input: up to `verifyByTest.maxFindings` (default 3) accepted blocking findings, the diff hunks for their files, and the Phase 1 test conventions.
-2. Per finding, the verifier writes ONE minimal repro test asserting the correct behavior the finding claims is broken, then runs ONLY that test via the Phase 3 single-test invocation (`xcodebuild test -only-testing:`, `pytest {file}::{name}`, `npm test -- --testPathPattern=`, `./gradlew test --tests`) under `acquire_build_lock`/`release_build_lock`, log tee'd to `$WORKTREE/.pipeline/verify-<i>.test.log`.
+2. Per finding, the verifier writes ONE minimal repro test asserting the correct behavior the finding claims is broken, then runs ONLY that test via the Phase 3 single-test invocation (`xcodebuild test -only-testing:`, `pytest {file}::{name}`, `npm test -- --testPathPattern=`, `./gradlew test --tests`) under `acquire_build_lock`/`release_build_lock`. One green run is not trusted: the same single-test invocation runs `verifyByTest.repeatCount` times (default 3; value 1 disables the repeat) as a shell loop, each run's log tee'd to `$WORKTREE/.pipeline/verify-<i>-<k>.test.log` for `k` in `1..repeatCount`. ALL runs must pass, and each log must clear `evidence-gate.mjs --claim test --status passed`, before the outcome counts as "passes". A first run that fails as predicted ends the loop early (`confirmed` needs no repeat).
 3. Stamp each processed finding with a `verification` object (triage-output schema v3.2.0) and re-run `validate-triage.mjs` on the mutated triage file under the standard 3.2.1 gate protocol.
 4. Findings beyond `maxFindings` keep their judgment-only verdict (log `verify_by_test=cap-exceeded`).
 5. The whole step is bounded by `verifyByTest.stepTimeoutSec` (default 600); on breach or verifier crash, remaining findings keep judgment-only verdicts and the pipeline proceeds. Never blocks.
@@ -15,7 +15,8 @@
 | Repro test outcome | `verification.result` | Action |
 |---|---|---|
 | Fails as the finding predicts | `confirmed` | Finding stays accepted blocking. Repro test KEPT in the worktree, recorded in `redTests[]`. |
-| Passes (not reproducible) | `not-reproduced` | Downgrade gated by `evidence-gate.mjs --claim test --status passed` on the test log (exit 0 required). Finding moves `accepted[]` -> `deferred[]` with reason `verify-by-test: not reproduced - repro test <testRef> passed`; repro test file deleted. Evidence-gate failure -> treat as `inconclusive`. |
+| Passes (not reproducible) | `not-reproduced` | Only when ALL `verifyByTest.repeatCount` runs pass and every `verify-<i>-<k>.test.log` clears `evidence-gate.mjs --claim test --status passed` (exit 0 required on each). Finding moves `accepted[]` -> `deferred[]` with reason `verify-by-test: not reproduced - repro test <testRef> passed`; repro test file deleted. Evidence-gate failure on any run -> treat as `inconclusive`. |
+| Passes on some runs, fails on others | `inconclusive` | Flake, not proof either way. Finding stays accepted blocking, `verification.note = "flaky: passed k/N"`, repro test file deleted, telemetry line gains `flaky=<count>`. |
 | Compile error / timeout / not unit-testable | `inconclusive` | Finding stays accepted blocking (judgment stands). Partial test deleted, cause in `verification.note`. |
 
 Downgrades go to `deferred`, never `rejected`: triage judged the issue real, and deferred items surface in the Phase 7 report for a human eye.
@@ -30,12 +31,12 @@ After Step 3.7, the only uncommitted verifier artifacts are the confirmed repro
 
 ## Telemetry
 
-One `review.verify_by_test` metric per iteration: `attempted`, `confirmed`, `downgraded`, `inconclusive`, `duration_ms` (plus `tokens_in/out` when available), forwarded to the tracker like all Phase 4 metrics. Timeout emits `triage=verify-by-test-timeout`.
+One `review.verify_by_test` metric per iteration: `attempted`, `confirmed`, `downgraded`, `inconclusive`, `flaky` (findings whose repeat runs disagreed), `duration_ms` (plus `tokens_in/out` when available), forwarded to the tracker like all Phase 4 metrics. Timeout emits `triage=verify-by-test-timeout`.
 
 ## Off by default reason
 
-Adds one Sonnet call plus up to `maxFindings` single-test runs (and build-lock contention on Xcode projects) per review iteration that has accepted blockers. On clean runs it never fires, but on noisy-reviewer repos it can add minutes per iteration. Flip on for security-critical work, release branches, or repos where reviewer false-positive rate is high.
+Adds one Sonnet call plus up to `maxFindings` single-test runs (and build-lock contention on Xcode projects) per review iteration that has accepted blockers. Each passing repro test is re-run `verifyByTest.repeatCount` times (default 3), so a downgrade costs up to `repeatCount` single-test runs rather than one. On clean runs it never fires, but on noisy-reviewer repos it can add minutes per iteration. Flip on for security-critical work, release branches, or repos where reviewer false-positive rate is high.
 
 ## Reference
 
-Wiring: `$HOME/.claude/multi-agent-refs/phases/phase-4-review.md` Step 3.7. Schema: `$HOME/.claude/schemas/triage-output.schema.json` v3.2.0 (`$defs.verification`). Evidence gate: `$HOME/.claude/scripts/evidence-gate.mjs`. Prefs: `prefs.global.verifyByTest` in `$HOME/.claude/schemas/prefs.schema.json`.
+Wiring: `$HOME/.claude/multi-agent-refs/phases/phase-4-review.md` Step 3.7. Schema: `$HOME/.claude/schemas/triage-output.schema.json` v3.2.0 (`$defs.verification`). Evidence gate: `$HOME/.claude/scripts/evidence-gate.mjs`. Prefs: `prefs.global.verifyByTest` (including `repeatCount`) in `$HOME/.claude/schemas/prefs.schema.json`.

package/pipeline/multi-agent-refs/features/worktree-finalize.md

@@ -49,7 +49,7 @@ This is why the removal is safe:
 
 | Consumer | Reads | Without salvage |
 |---|---|---|
-| Phase 7 triage-memory ingest | `triage-output.json` | `[ -f ]`-guarded, so it degrades **silently**: the triage corpus and learnings ledger stop being fed and no error appears |
+| Phase 7 triage-memory ingest | `triage-output.json` | `[ -f ]`-guarded, so it degrades **silently**: the triage corpus and learnings ledger stop being fed and no error appears. Since v16.20.0 Phase 4 writes `triage-output.json` itself (Step 3.2.1, the latest copy of `.pipeline/triage-round-<N>.json`), so the salvage is a second copy, not the only bridge |
 | Phase 7 learnings-ledger distill | same file | same silent degradation |
 | `render-work-summary.sh` | `agent-state.json`, `phase-tracker.json` (falls back to `logs/multi-agent/<task>/tracker-state.json`, which survives removal) | loses the salvaged copies but keeps the tracker via the logs fallback |
 | `:resume` | `agent-state.json` | cannot continue a Phase 7 pause |

package/pipeline/multi-agent-refs/outside-the-pipeline.md

@@ -75,13 +75,13 @@ toolkit. Continue without one rather than guessing which might fit.
 
 ## multi-agent-toolkit MCP
 
-| Family | Reach for it when |
+| Tool | Reach for it when |
 |---|---|
-| `ui-inspect` | you need to know what is actually on screen, not what the code implies |
-| `crash-logs` | a crash happened on a device or simulator |
-| `design-check` | a built screen has to be compared against its design |
-| `ios-app-store-audit` | a package is heading for review |
-| `ios-testflight` | validating a build before upload |
+| `ios_get_ui_tree` / `android_get_ui_tree` | you need to know what is actually on screen, not what the code implies |
+| `ios_list_crashes` / `android_list_crashes` | a crash happened on a device or simulator |
+| `design_*` (`design_visual_compare`, `design_ui_geometry`, `design_report`, ...) | a built screen has to be compared against its design |
+| `ios_app_store_audit` | a package is heading for review |
+| `ios_testflight_validate` | validating a build before upload |
 
 Registered at user scope by the installer, and preserved by uninstall - the tools are
 useful with no pipeline at all. If it is not registered the tools simply are not

package/pipeline/multi-agent-refs/payload-contracts.md

@@ -10,7 +10,7 @@ description: "Canonical required-reading list for outward-facing payloads (PR bo
 
 | Read | Before | Governs |
 |---|---|---|
-| [`channels/pr.md`]($HOME/.claude/multi-agent-refs/channels/pr.md) | assembling the PR body | fixed section set (`summary` → `changes` → `architecture` cond. → `verification` → `dependencies` cond. → `related`), Markdown-only rule, reviewer-preserving Bitbucket PUT payload |
+| [`channels/pr.md`]($HOME/.claude/multi-agent-refs/channels/pr.md) | assembling the PR body | fixed section set (`summary` → `changes` → `architecture` cond. → `verification` → `risk` cond. → `dependencies` cond. → `related`), Markdown-only rule, reviewer-preserving Bitbucket PUT payload |
 | [`phases/phase-6-commit.md`]($HOME/.claude/multi-agent-refs/phases/phase-6-commit.md) | committing | commit convention, default-reviewer fetch, draft/ready prompt, push-must-succeed loop |
 | [`rules.md`]($HOME/.claude/multi-agent-refs/rules.md) "External System Outputs" | any REST payload | real newlines, no HTML entities, no hand-rolled JSON, markup dialect per surface |
 

package/pipeline/multi-agent-refs/phases/log-format.md

@@ -55,7 +55,7 @@ Phase 7: Report █░░░░░░░░░░░░░░░ 2s
 (emit from the last iteration's `triage.consensus` block, schema v3.1.0. One line stating `verdict` + `reviewerCount`; when `verdict` is `split` or `unverified`, list each `disagreements[]` entry so a human can confirm what the reviewers did not independently agree on. Omit the section when triage produced no consensus block.)
 
 ```
-Verdict: unverified (2 reviewers)
+Verdict: unverified (3 reviewers)
 - Auth/KeychainStore.swift:40  -  token persisted without access-control flag
   (both approved a keychain change  -  agreement unverified, confirm manually)
 ```

package/pipeline/multi-agent-refs/phases/modes.md

@@ -89,7 +89,7 @@ Phase 0: Init -> Phase 3: Dev (self-contained) -> Phase 4: Review -> Phase 5: Te
 | Phase 1 (Analysis)  | Parallel Explore agents + analysis document     | **SKIP**  -  tile flips to `skipped` at Step 7.5                                     | **SKIP**                                      |
 | Phase 2 (Planning)  | TaskCreate + architecture review + **Plan Approval Gate** | **SKIP** (no plan means no plan gate)                                    | **SKIP**                                      |
 | Phase 3 (Dev)       | Follows the Phase 2 plan, TDD cycle (Sonnet)    | **Self-contained** (Opus): agent scans relevant files, implements with TDD, builds | Same, on the local branch                     |
-| Phase 4 (Review)    | Parallel review + Fable triage (Claude: 2-model / Copilot: 3-model) | **Same**  -  gates, parallel review, triage; blocking findings return to Phase 3 (cap 3) | **Same**, on the local branch diff |
+| Phase 4 (Review)    | Parallel review + Fable triage (3 reviewers on every host: Claude Code Fable + Opus + Sonnet, Copilot GPT-5.4 + Opus + Sonnet) | **Same**  -  gates, parallel review, triage; blocking findings return to Phase 3 (cap 3) | **Same**, on the local branch diff |
 | Phase 5 (User Test) | Interactive prompt                              | **Interactive prompt**                                                             | Not in the set  -  no worktree to check out    |
 | Phase 6 (Commit)    | Commit + PR                                     | Same  -  still asks                                                                  | Same                                          |
 | Phase 7 (Report)    | Full report + channels multi-select             | Simplified  -  no analysis section, review section IS present, channels menu still pauses | Same                              |

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

@@ -142,7 +142,7 @@ Results are cached in `global.serviceStatus` (existing TTL contract, default 300
 **Figma MCP expired / rejected  -  CRITICAL path.** The `figma_mcp` OAuth token (`figu_`) expires on a schedule (90 days), unlike the PATs. Because a dead MCP token silently degrades every Figma consumer to Tier 2/3 and has cost rebuild rounds, an expired `figma_mcp` is never deferred to mid-run:
 
 1. **Silent renewal first**: run `~/.claude/lib/figma-mcp-refresh.sh` (refresh grant via `<key>_Refresh` + the `.figma-oauth.json` client credentials next to `prefs.global.tokenScripts.figma_mcp`). Exit 0 → re-probe, log `→ figma mcp token renewed silently`, continue. No question asked.
-2. **Renewal impossible/rejected** (exit 1/2) → AskUserQuestion at init (`question`/`description` in `outputLanguage`): "Figma MCP token expired  -  update it now?"
+2. **Renewal impossible/rejected** (exit 1/2) → ask once at init through the native picker (`picker-contract.md`; `question`/`description` in `outputLanguage`): "Figma MCP credential expired  -  update it now?" The answer routes to a script or the clipboard Save Flow; the value itself is never typed in chat.
    - **Regenerate now (script)**  -  shown only when `prefs.global.tokenScripts.figma_mcp` is set: run that script (browser OAuth flow), then re-probe and continue.
    - **Save a new token**  -  Token Save Flow from `setup.md` (clipboard path).
    - **Continue degraded**  -  proceed on Tier 2 (REST PAT) for this run; log the downgrade.
@@ -269,7 +269,7 @@ Scan `$HOME` (maxdepth 2) for project markers (`.xcodeproj`, `Package.swift`, `b
    ```
 6. Sort: `develop*` first, then `release/*`, then `main`/`master`. Surface through the
    **native picker** per `picker-contract.md` (`AskUserQuestion` on Claude Code,
-   `ask_choice.sh` on Copilot CLI) - `question` + `description` in `outputLanguage`,
+   `ask-choice.sh` on Copilot CLI) - `question` + `description` in `outputLanguage`,
    `label` = the branch name verbatim (a proper noun, never translated) with the recent
    branch first and marked `(Recommended)`. The ASCII sketch
    below is what the options carry, not a menu to print:
@@ -425,6 +425,8 @@ 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. **Heal stale admin state first** (see "Worktree stale-lock heal" below) and **apply the residue guard** (see "Worktree residue guard" below), then `git -C $PROJECT_ROOT worktree add {path} -b {branch} origin/{baseBranch}` (if exists: enter, pull) 4. Set identity: `git -C {worktree-path} config user.name/email` 5. Create log dir + `agent-log.md` + `agent-state.json` at `$HOME/.claude/logs/multi-agent/{project}/{task-id}/`, never inside the worktree:
 
+**Worktree location convention (cited by every other command):** always `{projectRoot}/.worktrees/{taskId}`, inside the repo, never under `$HOME`. `{taskId}` is the directory name from the rule above (`DC-<shortId>` for `/multi-agent:design-check`). `.worktrees` is fixed, not a preference: no `worktreeBasePath` key exists, and `gc-worktrees.sh`, `purge.sh`, the cost renderers and `usage-report.mjs` resolve `<repo>/.worktrees/` by name. Multi-repo tasks get one worktree per repo (the loop below); `--local` creates none and `worktreePath` is `$PROJECT_ROOT`.
+
 **Worktree stale-lock heal (required before every `worktree add`):** a run killed mid-`worktree add` (OOM, SIGTERM, disk full) leaves a locked or broken admin entry under `.git/worktrees/{id}/`, so the retry fails with `fatal: '<path>' already exists`. Always run the heal first  -  it is a no-op on a clean repo:
 
 ```bash

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

@@ -1,6 +1,6 @@
-### Phase 1: Analysis (Fable)
+### Phase 1: Analysis (Sonnet)
 
-> **TLDR**  -  Fable-driven codebase exploration (Opus when the fallback ladder engages). Detects if the issue is already fixed (git blame, closed PRs), then launches parallel Explore sub-agents to map the affected code paths. Outputs: impact analysis, stack detection (auto-selects platform guide), relevant files, risk areas. Feeds Phase 2 planning.
+> **TLDR**  -  Sonnet-driven codebase exploration: the `explorer` persona declares `preferredModel: sonnet` (haiku when the fallback ladder engages). Detects if the issue is already fixed (git blame, closed PRs), then launches parallel Explore sub-agents to map the affected code paths. Outputs: impact analysis, stack detection (auto-selects platform guide), relevant files, risk areas. Feeds Phase 2 planning.
 
 <!-- progress-contract: applied -->
 Progress emission per `$HOME/.claude/multi-agent-refs/progress-contract.md`  -  lines for each Explore dispatch, each finish, analyst synthesis start, `analysis.json` write.
@@ -217,7 +217,7 @@ Forward the explorer call's token totals into the tracker so Phase 7's Cost Brea
 
 ```bash
 LOG_METRIC_FORWARD_TO_TRACKER=1 $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 1 analysis.completed \
-  model=opus tokens_in=$IN tokens_out=$OUT duration_ms=$DUR
+  model=sonnet tokens_in=$IN tokens_out=$OUT duration_ms=$DUR
 ```
 
 Best-effort. See `$HOME/.claude/multi-agent-refs/progress-contract.md#token-telemetry-forwarding` for the canonical contract.

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

@@ -215,7 +215,7 @@ Otherwise (normal mode), run the gate. The gate has **two modes** that chain: Cl
 
 ##### 5a  -  Clarification Mode (conditional, max 2 rounds)
 
-Trigger if the plan Opus produced in Step 1-4 carries ANY ambiguity signal from Phase 1 analysis:
+Trigger if the plan Fable produced in Step 1-4 carries ANY ambiguity signal from Phase 1 analysis:
 
 | Signal | Check |
 |---|---|
@@ -300,12 +300,12 @@ Handle the selection:
   - Set `state.status = "paused"`, log `🧠 Phase 2: Plan aborted by user`, stop
 - **Other (free-text edit request)**:
   - Treat the typed text as an edit request. Append to `state.phases["2"].planEditRequests`, bump `planIterations`
-  - Pass the edit request + current plan to Opus; Opus revises and returns a new plan (same schema, same validator)
+  - Pass the edit request + current plan to the planning model (Fable; Opus when the fallback ladder engages); it revises and returns a new plan (same schema, same validator)
   - Re-render the plan (5b), loop
 
 No hard cap on edit iterations  -  the user controls exit via the Approve / Cancel options. Between iterations, keep only the **latest plan** as canonical; previous renders are in the log for audit but do not re-enter the validator.
 
-**Validator**: every revised plan goes through `node $HOME/.claude/scripts/validate-planning.mjs -` before re-render. If validation fails after an edit, log `⚠️ Phase 2: Plan validator failed after edit request #N  -  retrying Opus once` and retry once; on second failure surface the validator error to the user and go back to approval prompt with the pre-edit plan.
+**Validator**: every revised plan goes through `node $HOME/.claude/scripts/validate-planning.mjs -` before re-render. If validation fails after an edit, log `⚠️ Phase 2: Plan validator failed after edit request #N  -  retrying the planning model once` and retry once; on second failure surface the validator error to the user and go back to approval prompt with the pre-edit plan.
 
 #### Step 6  -  Mode-specific short-circuit (reference)
 
@@ -321,11 +321,11 @@ The pipeline shapes interact with the gate as follows. This table is the source
 
 #### Telemetry  -  token forwarding
 
-After plan generation (and after each edit-loop iteration), forward Opus call totals so Phase 7's Cost Breakdown captures Phase 2:
+After plan generation (and after each edit-loop iteration), forward the planning model's call totals so Phase 7's Cost Breakdown captures Phase 2 (`model=` names the rung that actually ran: `fable`, or `opus` after a fallback step):
 
 ```bash
 LOG_METRIC_FORWARD_TO_TRACKER=1 $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 2 plan.generated \
-  model=opus tokens_in=$IN tokens_out=$OUT duration_ms=$DUR iteration=$N
+  model=fable tokens_in=$IN tokens_out=$OUT duration_ms=$DUR iteration=$N
 ```
 
 Best-effort. See `$HOME/.claude/multi-agent-refs/progress-contract.md#token-telemetry-forwarding`.

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

@@ -84,7 +84,8 @@ When re-entering from Phase 4:
 3. `accepted.suggestion` items are applied opportunistically (no TDD loop required) unless the user asked for suggestions to be treated strictly.
 4. `deferred` items are NOT actioned in this re-entry  -  they surface in Phase 7's "Follow-up items" section.
 5. `rejected` items are never touched. Log their IDs + triage reasons for audit only.
-6. After rework, increment `state.phases["3"].retryCount`; hard-kill at `retryCount === 3` and escalate to the user. Do not loop indefinitely.
+6. After rework, increment `state.phases["3"].retryCount`; hard-kill at `retryCount === 3` and escalate to the user. Do not loop indefinitely. When `prefs.global.autopilotCircuitBreaker.enabled` is true (default), record the hard-kill before escalating as `state.circuitBreaker = {tripped: true, trigger: 3, detail: "rework cycles exhausted", checkpoint: {phase: 3, step: "re-entry", iteration: <n>}, trippedAt, counters: {reworkCycles: <n>}}`: the rework-storm trigger; `autopilotCircuitBreaker.maxReworkCycles` (default 3) is bounded above by this cap.
+7. When `state.reviewIterations[-1].delta` exists, `stillPresent[]` findings come first in the task list, quoted `STILL PRESENT after round N-1's fix`; repeating the previous attempt is the loop the circuit-breaker stops.
 
 If the latest iteration has `triage.approved === true` AND `accepted === []`, Phase 3 was entered by mistake  -  log the anomaly and return to Phase 5.
 
@@ -155,6 +156,7 @@ For each task (respecting dependency order):
    **REFACTOR (if needed):**
    - Only if duplication or naming is poor
    - Re-run tests after refactor → still GREEN
+   - **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 4 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):
    ```bash
@@ -243,7 +245,7 @@ After the build/test green step and BEFORE Phase 4 handoff, run one diff-shrink
    - **Over-abstraction**  -  single-call-site protocols/wrappers/helpers from this diff
 
    Progress line: `    → dispatching code-simplifier diff-shrink`
-2. **Return contract**  -  a list of shrink edits `{ "file", "lines", "edit", "rationale", "risk": "safe|unsafe" }`; the subagent never writes files.
+2. **Return contract**  -  a list of shrink edits `{ "file", "lines", "edit", "rationale", "risk": "safe|unsafe" }`; the subagent never writes files. Keep the `rationale` strings: Step 3.7 writes them into `scope-check.json`.
 3. **Apply safe edits only**  -  skip `unsafe` (logged). Zero edits is normal  -  log and continue. Progress line: `    → applying shrink edits ({N} applied, {M} skipped)`
 4. **Re-run build + tests** (same build-queue lock + evidence-gate rule as Step 4). Any breakage -> revert shrink edits wholesale and proceed pre-shrink; the simplifier must never cost a green state.
 5. **Record tokens in the cost ledger** so Phase 7's Cost Breakdown captures the pass:
@@ -258,6 +260,19 @@ Scope guard: a single pass, never looped. Runs in a Short run too; component tas
 
 ---
 
+#### Step 3.7  -  Scope self-check (required handoff artifact)
+
+Phase 4 cannot reconstruct why each file was touched or what was left out on purpose, so Dev states both before the handoff: write `$WORKTREE/.pipeline/scope-check.json` (`schemas/scope-check.schema.json`: one `{path, reason}` per file in the diff, `notDone[]` with `why` in `out-of-scope | follow-up | rejected-abstraction`, and the Step 3.6 `simplifier` rationales), then run the gate. **Record rules, consumers and the full contract: `$HOME/.claude/multi-agent-refs/features/scope-check.md`.**
+
+```bash
+git -C "$WORKTREE" diff --name-only "origin/$BASE_BRANCH"...HEAD \
+  | node $HOME/.claude/scripts/scope-check-gate.mjs --check "$WORKTREE/.pipeline/scope-check.json" --diff-files -
+```
+
+Exit 1 lists `unjustified[]`: complete the record once and re-run. A second exit 1 does not block; log `dev.scope_check=incomplete unjustified=<n>` and hand off, and Phase 4 shows the gate output to reviewers inside `<scope-self-check>`. Progress line: `    → checking scope self-check ({n} files, {m} not done)`.
+
+---
+
 #### Short pipeline (`state.onlyDevelop === true`)
 
 Set by the Phase 0 Step 7.5 depth picker, or by autopilot never (autopilot always runs Full). When it is true, Phase 3 runs self-contained with **Opus** (not Sonnet). No Phase 2 plan exists  -  the agent creates its own scope.