@mmerterden/multi-agent-pipeline 17.3.0 → 17.5.0

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

@@ -240,8 +240,7 @@ $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 4 review.criteria \
 Output conforms to `$HOME/.claude/schemas/criteria-manifest.schema.json`. The four parts that matter downstream:
 
 - **`selectedRules[]` is the denominator.** Rule IDs from every registry whose declared `scope` matches the diff, persisted BEFORE the reviewers run so the set cannot be renegotiated after one has seen the diff. That is what makes "applied completely" answerable rather than "looks fine": a reviewer finding nothing must still return a verdict per ID. Discovery is declared via `standards-registry:` frontmatter, so no stack-specific skill is named here.
-- **`coverage.declaredGaps[]` + `droppedReasons`.** An uncovered language, and every out-of-scope rule, is reported with a reason. "No rule applied", "every rule passed" and "the rule set was narrowed" must never render the same.
-- **`ledger`.** `state.telemetry.skillCalls[]` corroborates only; `ledger.source` defaults to `derived` and coverage is never computed from self-report. A declared skill the resolver cannot bind is flagged.
+- **`coverage.declaredGaps[]`, `droppedReasons`, `ledger`.** Every gap, dropped rule and unbindable declared skill is reported with a reason; coverage is never computed from self-report. Rationale: the contract above.
 - **`findings[]`.** Reviewer-shaped, merging at Step 3.0 alongside test-integrity: expired / unexplained / unknown-ID exception markers, plus any registry whose delegated linter is not wired here (those rules are unverified, so reporting no violations reports that nothing was measured).
 
 **Any non-zero exit halts** (1 = setup error incl. a bad `--skills-root`; 2 = no root resolved, unparseable registry, or a declared path escaping its skill dir): continuing would drop a rule set from the denominator, and since the reviewer validator skips the checklist when zero rules were selected, the run would report clean over criteria never loaded. A coverage gap halts only under `prefs.global.skillConformance.blockOnCoverageGap`. No opt-out for the stage or the exception-expiry check, on the same grounds as Step 1.76.
@@ -266,13 +265,25 @@ Visual-fidelity mismatches against the captured screenshot are BLOCKING findings
 
 When `state.figmaAccess.tier === 3` (user-attached screenshot, no Code Connect snippet), the reviewer additionally sets `findings[i].severity = "blocking"` and `findings[i].tag = "review_blocking_tier3"` on every UI atom that lacks a confirmed canonical-component mapping. The triage step preserves these findings unless the user has explicitly cleared the open question.
 
+#### Step 1.85  -  Review file set (the denominator, required)
+
+Decides what the reviewers read before the cap decides what fits: the cap truncates the largest files first, so a lockfile survives while real code is cut. Zero LLM. Full contract: `$HOME/.claude/multi-agent-refs/features/review-file-set.md`.
+
+```bash
+git -C "$WORKTREE" diff --name-only "$BASE_BRANCH"...HEAD \
+  | node $HOME/.claude/scripts/review-file-filter.mjs \
+  > "$WORKTREE/.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`.
+
 #### Step 1.9  -  Context economy (cache prefix + diff cap)
 
 Phase 4 sends the same diff to every reviewer and then to triage, so the diff is the dominant token cost. Two measures keep it bounded:
 
-**Shared cache prefix.** Build the reviewer and triage prompts so the large invariant context  -  the full diff, the `${CRITERIA}` block from Step 1.78, the Phase 1 analysis summary, the Phase 2 plan  -  is a byte-identical leading block across all dispatches in this iteration. Only the per-reviewer focus + skill line varies, and it goes AFTER the shared block. `${CRITERIA}` goes in the prefix, identical for every reviewer: subsetting it per reviewer would invalidate the prefix for the whole panel and re-bill the largest block in the phase. Per-reviewer emphasis stays a one-line pointer in the suffix. When the host supports prompt caching, the 2nd/3rd reviewer and the triage call then read that prefix at the discounted cache-read rate instead of re-billing it as fresh input. Forward the host-reported cache-read count as `tokens_cached` per the Token telemetry contract so the saving lands in the cost ledger. The `<scope-self-check>` block and, from iteration 2, the `<previous-round-findings>` block (Step 2.1) close the shared block, after the plan and before the per-reviewer suffix.
+**Shared cache prefix.** Build the reviewer and triage prompts so the large invariant context  -  the full diff, the `${CRITERIA}` block from Step 1.78, the `${REVIEW_FILES}` list from Step 1.85, the Phase 1 analysis summary, the Phase 2 plan  -  is a byte-identical leading block across all dispatches in this iteration. Only the per-reviewer focus + skill line varies, and it goes AFTER the shared block. `${CRITERIA}` goes in the prefix, identical for every reviewer: subsetting it per reviewer would invalidate the prefix for the whole panel and re-bill the largest block in the phase. Per-reviewer emphasis stays a one-line pointer in the suffix. When the host supports prompt caching, the 2nd/3rd reviewer and the triage call then read that prefix at the discounted cache-read rate instead of re-billing it as fresh input. Forward the host-reported cache-read count as `tokens_cached` per the Token telemetry contract so the saving lands in the cost ledger. The `<scope-self-check>` block and, from iteration 2, the `<previous-round-findings>` block (Step 2.1) close the shared block, after the plan and before the per-reviewer suffix.
 
-**Single-repo diff cap.** If the diff exceeds the Phase 4 token allowance (`token-budget.json`), truncate the largest files and append a footer `[truncated  -  full diff in file://$WORKTREE/.review-diff.txt]`, writing the full diff to that path. Reviewers and triage receive the same capped view + the marker so they can flag "review the full diff manually." Log `review.diff_truncated bytes_dropped=<N>`. (Multi-repo already caps the combined diff at 80% of budget; this is the single-repo equivalent.)
+**Single-repo diff cap.** Applied to the Step 1.85 `reviewed[]` set only. If it exceeds the Phase 4 token allowance (`token-budget.json`), truncate the largest files and append a footer `[truncated  -  full diff in file://$WORKTREE/.review-diff.txt]`, writing the full diff to that path. Reviewers and triage receive the same capped view + the marker so they can flag "review the full diff manually." Log `review.diff_truncated bytes_dropped=<N>`. (Multi-repo already caps the combined diff at 80% of budget; this is the single-repo equivalent.)
 
 #### Step 2  -  Parallel AI Review (CLI-aware reviewer set)
 
@@ -291,9 +302,8 @@ Reviewer count per host: **Claude Code 3, Copilot CLI 3, Codex CLI 3**  -  **2**
 
 #### Codex CLI  -  two constraints that fail silently
 
-Both were measured against Codex 0.145, not inferred, and both produce a review that
-looks like it ran. The full statement lives in the managed block at `~/.codex/AGENTS.md`
-(always loaded on that host, so it is not restated here):
+Both measured against Codex 0.145, both produce a review that looks like it ran. Full
+statement: the managed block in `~/.codex/AGENTS.md`, always loaded on that host.
 
 1. **`fork_turns: "none"` on every `spawn_agent` that sets `model` or
    `reasoning_effort`** - a full-history fork discards the override and collapses the
@@ -304,15 +314,10 @@ looks like it ran. The full statement lives in the managed block at `~/.codex/AG
 Sub-agent delegation itself is authorized by that same managed block; without it Phase 4
 degrades to a single in-thread review.
 
-**Single-vendor caveat.** Every Codex reviewer is an OpenAI model, and every Claude
-Code reviewer is an Anthropic model, so the cross-vendor disagreement that Copilot CLI
-gets for free (GPT-5.4 beside two Claude models) is absent on both. The diversity budget
-shifts to model generation, reasoning effort and persona focus: on Codex Reviewer 1 runs
-`xhigh` on security and architecture, Reviewer 2 runs a different model family member
-on edge cases, Reviewer 3 runs `medium` on quality; on Claude Code the three slots are
-three different Claude tiers. Treat consensus among a single-vendor panel as weaker
-evidence than the same consensus on Copilot CLI, and say so in the triage note when all
-three agree on a borderline finding.
+**Single-vendor caveat.** Claude Code and Codex both run a one-vendor panel, so their
+consensus is weaker evidence than Copilot CLI's; say so in the triage note on a
+borderline finding. Where the diversity budget goes instead:
+`cross-cli-contract.md`, "Panel diversity per host".
 
 Each reviewer inherits the `code-reviewer` agent's focus areas (Security, Architecture, Quality, Performance) and output contract. The orchestrator overrides only the model and the stack-specific skill per-reviewer  -  no prompt duplication.
 
@@ -331,7 +336,7 @@ Each reviewer inherits the `code-reviewer` agent's focus areas (Security, Archit
 
 ##### 2.1 Previous-round findings (iteration >= 2) and 2.2 scope self-check (every iteration)
 
-A reviewer has no memory of the round before, so it rediscovers last round's findings in new words. From iteration 2, render the previous round's accepted blocking/important findings (`.pipeline/triage-round-$((ITERATION-1)).json`, max 40) into a `<previous-round-findings>` block at the end of the shared prefix: a still-present issue is reported with the SAME fingerprint and the current line, a fixed one is omitted, anything new leaves `fingerprint` unset. Every iteration also renders `.pipeline/scope-check.json` (Phase 3 Step 3.7) plus `scope-check-gate.mjs --advisory` output as `<scope-self-check>`: file reasons, unjustified files, and `notDone[]` (never re-raised as findings); a missing record logs `review.scope_check=missing`. Block text and recipes: `$HOME/.claude/multi-agent-refs/features/review-delta.md`.
+From iteration 2, render the previous round's accepted blocking/important findings (`.pipeline/triage-round-$((ITERATION-1)).json`, max 40) into a `<previous-round-findings>` block at the end of the shared prefix. Every iteration also renders `.pipeline/scope-check.json` (Phase 3 Step 3.7) plus `scope-check-gate.mjs --advisory` output as `<scope-self-check>`: file reasons, unjustified files, and `notDone[]` (never re-raised as findings); a missing record logs `review.scope_check=missing`. Block text and recipes: `$HOME/.claude/multi-agent-refs/features/review-delta.md`.
 
 #### Step 2.8  -  Visual conformance gate (component / screen work only)
 
@@ -350,11 +355,7 @@ disk with `Code Connect: Not published` in Figma means the binding does not exis
 anyone but the author. Assert the publish step ran; an unpublished binding is a
 blocking finding.
 
-Why this is a gate and not advice: `design-check` existed as a command for a while
-with **no phase invoking it**, so the only thing standing between a build and visual
-drift was the user opening the app and looking. On one run that produced 16pt padding
-where the frame said `Spacing/12`, and a full sheet rebuild afterwards. A reviewer
-reading a diff cannot see spacing; something has to compare against the design.
+Why this is a gate and not advice: `design-conformance.md`, "Why this runs as a gate".
 
 Skip only when the diff has no UI change. Record the outcome in
 `consensus.visualConformance` so Phase 7 reports whether it ran.
@@ -374,10 +375,11 @@ Step 2 produces N reviewer-output objects (one per dispatched reviewer), each co
 ```json
 {"findings":[{"severity":"blocking|important|suggestion","file":"...","line":N,"issue":"...","fix":"...","ruleId":"SEC-01","criteriaSource":"ios-coding-standard"}],
  "conformance":[{"ruleId":"SEC-01","verdict":"conformant|violated|not-applicable","file":"...","line":N,"reason":"..."}],
+ "fileCoverage":[{"path":"src/App.swift","verdict":"reviewed|skipped","reason":"..."}],
  "approved":true|false}
 ```
 
-`ruleId` + `criteriaSource` appear on a finding that cites a rule from `${CRITERIA}`. `conformance` is required whenever Step 1.78 selected at least one rule, with exactly one row per selected ID and none outside the set.
+`ruleId` + `criteriaSource` appear on a finding that cites a rule from `${CRITERIA}`. `conformance` is required whenever Step 1.78 selected at least one rule, and `fileCoverage` whenever Step 1.85 left at least one file in `reviewed[]`: one row per ID, one row per path, none outside either set.
 
 **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:
 
@@ -386,9 +388,15 @@ 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" \
+  && node $HOME/.claude/scripts/verify-citations.mjs "$REVIEWER_FILE" --repo "$WORKTREE" --worktree \
   && node $HOME/.claude/scripts/finding-fingerprint.mjs annotate --in-place "$REVIEWER_FILE"
 ```
 
+`verify-citations.mjs` resolves each finding's `file:line` against the checkout,
+not a commit: a round's fix is uncommitted, and HEAD would call it invented.
+Exit 1 takes the single rework below; exit 2 means not a repository.
+
 Progress line: `    → checking validator validate-reviewer ({reviewer})`
 
 `finding-fingerprint.mjs` stamps each finding with its cross-round id once the validator passes; an echoed one is kept, and anonymization leaves it intact.

package/pipeline/multi-agent-refs/phases/phase-7-report.md

@@ -323,7 +323,7 @@ If user does not respond at the channels multi-select menu within 30 minutes (wa
 1. Channels command aborts its interactive prompt, returns `{status: "timeout"}`.
 2. Phase 7 records `phase-tracker.sh sub 7 1 "Channels dispatch" timeout`.
 3. **Internal capture still runs**  -  Steps 2 + 3 write `agent-log.md` (with `channels: timeout` in summary), emit telemetry, update knowledge base.
-4. Session exits cleanly. State persisted: `state.phase=7, state.waitingFor="user-channels-choice", state.channelsTimeout=true`.
+4. Session exits cleanly. State persisted: `state.currentPhase=7, state.waitingFor="user-channels-choice", state.channelsTimeout=true`.
 5. Resume contract: `/multi-agent:resume <task-id>` re-opens the channels menu with the original state bundle (pipeline log, PR metadata, prefs pre-ticks).
 
 Rationale: silently posting defaults to Jira / Confluence after a timeout would leak wrong-tone content to external systems. Hard-stop + resume is the safer policy.

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

@@ -90,7 +90,7 @@ Two channels run in parallel at every phase boundary. Both are required in their
 
 ### Tracker bootstrap (Phase 0, mandatory)
 
-Phase 0 MUST initialize the tracker and register all 8 phases:
+Phase 0 MUST initialize the tracker and register the active mode's phase set:
 
 ```bash
 $HOME/.claude/scripts/phase-tracker.sh init "$TASK_ID"
@@ -101,6 +101,11 @@ done
 
 This produces an initial card stack printed by both CLIs.
 
+`/multi-agent` and `/multi-agent:local` are the exception: they do not know their
+set here, because depth decides it at Step 7.5. They register `0:Init` alone, then
+the rest once the answer lands, and call `tiles --new` for the second batch. Full
+contract: `tracker-contract.md`, "Deferred registration".
+
 ### Tracker updates (every phase boundary)
 
 As each phase enters/exits:
@@ -162,7 +167,7 @@ TaskUpdate({ taskId: <saved>, status: "completed" })
 bash phase-tracker.sh update <N> completed
 ```
 
-A phase outside the command's set gets no TaskCreate at all. Depth is different: it is not known at registration time, because the tracker boots at Step -1 and the depth question runs at Step 7.5, so a Short run registers Phases 1 and 2 like any other and flips them to `skipped` when the answer lands. Pre-marking them before Phase 0 produces visually scrambled tile stacks  -  see the ordering rule below.
+A phase outside the command's set gets no TaskCreate at all. Depth is different: it is not known at registration time, because the tracker boots at Step -1 and the depth question runs at Step 7.5. So registration splits - Phase 0 alone at Step -1, the rest at Step 7.5 once the answer says which phases the run has. A Short run never draws an Analysis tile it will not use. Registering all eight and flipping 1 and 2 to `skipped` is what this replaced, in v17.5.0: it put an eight-tile widget on screen beside the question asking whether to run two of them  -  see the ordering rule below.
 
 **(strict) TaskCreate ordering**: All TaskCreate calls MUST fire in strict phase-number order BEFORE any TaskUpdate is applied. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks (e.g. `1 ✓ · 2 ✓ · 4 ✓ · 0 ▶ · 3 ☐`) even when the underlying state is correct. Pre-marking phases as completed/skipped before Phase 0 starts is FORBIDDEN  -  register the tile in order with default `pending` status, then flip status via TaskUpdate when the phase actually short-circuits. Full contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
 

package/pipeline/multi-agent-refs/picker-contract.md

@@ -8,6 +8,7 @@
 - [Localized labels: what the caller owns](#localized-labels-what-the-caller-owns)
 - [Order: project, then repo, then branch](#order-project-then-repo-then-branch)
 - [A single candidate is still a question](#a-single-candidate-is-still-a-question)
+- [Two options or it is not a question](#two-options-or-it-is-not-a-question)
 - [Autopilot / non-interactive contract](#autopilot-non-interactive-contract)
 - [Deterministic gates note](#deterministic-gates-note)
 <!-- /toc -->
@@ -102,15 +103,46 @@ input with a second question.
 ## A single candidate is still a question
 
 The number of options never authorises a skip. A filter that leaves one row has
-narrowed the world; it has not decided anything, and the host's **Other** row is a real
-choice on every picker - a branch the filter excluded, an account the probe missed, a
-repo git does not know about. "There was only one option, so I picked it" is a skipped
-picker, and announcing the pick in prose first is the same skip with a sentence in front
-of it.
+narrowed the world; it has not decided anything. "There was only one option, so I
+picked it" is a skipped picker, and announcing the pick in prose first is the same
+skip with a sentence in front of it.
 
 This is the failure that is hardest to see afterwards, because the transcript reads like
 a decision was made. Only the picker's absence records that the user was never asked.
 
+The one row is asked by giving the question a real second option, not by sending a
+one-row picker - see the next section for why that is not the same thing.
+
+## Two options or it is not a question
+
+Claude Code's `AskUserQuestion` refuses a question with fewer than two declared
+options, and it refuses the **whole call**: every other question batched with it is
+discarded unasked, and the host's reply says not to retry and not to invent a filler
+option. The host's **Other** row does not rescue it - the schema counts declared
+options, and Other is injected afterwards.
+
+This has already cost a run. A base-branch question with one remote candidate was
+batched with the maturity, depth and workspace questions; the call was rejected, the
+branch was announced in prose instead ("only candidate, continuing with it"), and the
+three surviving questions had to be re-asked. The section above was followed to the
+letter and produced the skip it exists to prevent.
+
+So a one-candidate picker is asked with a genuine escape as its second option:
+
+| One candidate | Second option that makes it a question |
+|---|---|
+| base branch | "Pick another branch" - re-opens with the unfiltered `git branch -r` list |
+| account, repo, module | "Show all" - re-opens with the filter dropped |
+| a destructive step | "Abort" |
+
+A second option that is not a choice ("OK", "Continue") is worse than not asking: it
+manufactures consent. When nothing genuine can be offered, do not ask - say which
+single path is being taken and continue.
+
+`ask-choice.sh` accepts one option and always has, so this floor is a Claude Code
+fact the shell path does not share. Write the picker to the floor anyway: one spec
+text drives both hosts.
+
 ## Autopilot / non-interactive contract
 
 In autopilot, `ask_choice` resolves to `default` (or the safe first option) without prompting - identical to how the native gates auto-proceed today. A picker is only surfaced for genuinely ambiguous or destructive decisions, matching the maturity-check model.

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

@@ -94,7 +94,7 @@ Phases by mode:
 | `/multi-agent:autopilot`, `/multi-agent:local-autopilot` | 0,1,2,3,4,6,7 (always Full; autopilot drops the interactive Phase 5 gate) |
 | `/multi-agent:analysis` | 0,1,2,4,6,7 (no code is written, so no Dev and no Test) |
 
-What changed in v16.0.0: the two picker entries (`/multi-agent`, `:local`) register their FULL set even when the run turns out to be Short, and there is a timing reason. The tracker boots at Step -1, the first thing in every run, while the depth picker cannot run before Step 7.5 - its recommendation needs `taskType`, which needs the fetched issue and the branch. So Phases 1 and 2 are registered `pending` like any other and flipped to `skipped` at 7.5 if Short is chosen. See "Late skip" below.
+The two picker entries (`/multi-agent`, `:local`) register in two batches, because at Step -1 they do not yet know which set is theirs: see "Deferred registration" below. Every other mode registers its whole set at Step -1.
 
 Register each phase:
 
@@ -199,29 +199,40 @@ Mode-specific phase sets:
 
 | Mode | TaskCreate set (in order) |
 |---|---|
-| `/multi-agent` | 0 → 1 → 2 → 3 → 4 → 5 → 6 → 7 (all 8; 1 and 2 flip to skipped at Step 7.5 if the user picks Short) |
-| `:local` | 0 → 1 → 2 → 3 → 4 → 6 → 7 (same late skip; Phase 5 is not in the set at all) |
+| `/multi-agent` | 0 at Step -1; then at Step 7.5 either 1 → 2 → 3 → 4 → 5 → 6 → 7 (Full) or 3 → 4 → 5 → 6 → 7 (Short) |
+| `:local` | same two batches, with Phase 5 in neither |
 | `:autopilot`, `:local-autopilot` | 0 → 1 → 2 → 3 → 4 → 6 → 7 (7 phases  -  always Full, and the interactive Phase 5 gate is dropped) |
 | `:analysis` | 0 → 1 → 2 → 4 → 6 → 7 (6 phases  -  no code is written, so 3 and 5 are not in the set) |
 
 A phase outside the mode's set gets no TaskCreate at all; the `[SKIPPED]` pattern applies only to a phase that IS in the set and short-circuits at runtime. Phase 4 is in every mode's set as of v14.0.0. The authoritative per-mode set is the `for p in ...` init block in each mode's own entry doc, generated by `gen-mode-dispatch.mjs`; this table mirrors those blocks.
 
-#### Late skip  -  the depth picker
+#### Deferred registration  -  the depth picker
 
-The two picker entries cannot know their phase set at Step -1, and the ordering rule above forbids pre-marking. The contract already has the answer, and it is the only permitted one: register the tile in order with the default `pending` status, then flip it when the phase actually short-circuits.
+`/multi-agent` and `:local` cannot know their phase set at Step -1. Depth decides it, and the depth picker cannot run before Step 7.5: its recommendation needs `taskType`, which needs the fetched issue and the branch.
+
+Until v17.5.0 they registered all eight anyway and flipped 1 and 2 to `skipped` at 7.5. That put a widget reading "8 tasks, 7 open  -  Phase 1 Analysis, Phase 2 Planning, ..." on screen *beside* the question asking whether to run Analysis and Planning at all, and a Short answer then contradicted a list the user had just been shown. The widget was asserting a shape the run had not chosen.
+
+So registration splits at the moment the shape is known:
 
 ```text
-# Step -1, before anything else: all eight, in order, all pending
-TaskCreate(Phase 0) ... TaskCreate(Phase 7)
-
-# Step 7.5, after the depth answer. Short only:
-TaskUpdate(taskId₁, status="completed", activeForm="[SKIPPED]")
-TaskUpdate(taskId₂, status="completed", activeForm="[SKIPPED]")
-bash $HOME/.claude/scripts/phase-tracker.sh update 1 skipped
-bash $HOME/.claude/scripts/phase-tracker.sh update 2 skipped
+# Step -1, first thing in the run: Phase 0 only. It is the one phase that is
+# certain, and the run is never silent while Phase 0 does its work.
+bash $HOME/.claude/scripts/phase-tracker.sh add 0 Init
+bash $HOME/.claude/scripts/phase-tracker.sh tiles        # -> TaskCreate(Phase 0)
+bash $HOME/.claude/scripts/phase-tracker.sh update 0 in_progress
+
+# Step 7.5, immediately after the depth answer:
+#   Full  -> 1 2 3 4 5 6 7        Short -> 3 4 5 6 7
+#   :local drops 5 from either (no worktree to check out from)
+for p in "3:Dev" "4:Review" "5:Test" "6:Commit" "7:Report"; do
+  bash $HOME/.claude/scripts/phase-tracker.sh add "${p%%:*}" "${p#*:}"
+done
+bash $HOME/.claude/scripts/phase-tracker.sh tiles --new   # -> TaskCreate for the new tiles only
 ```
 
-Order holds because every tile was created before any update. Nothing is pre-marked: at creation time the run genuinely does not know, and the flip happens at the moment it learns.
+`tiles --new` emits `TaskCreate` only for phases that carry no `tasklist_id` yet, so the Phase 0 tile is not created twice. It is the same ordering rule, applied per batch: every tile in a batch is created in ascending phase order, and a deferred batch only ever appends phases numbered above everything already registered. Nothing is pre-marked, and a phase the run will not execute never gets a tile at all.
+
+A phase that IS registered and short-circuits later still flips with `[SKIPPED]` - autopilot suppressing Phase 5, for instance. That is a runtime outcome, not an unknown set.
 
 **Enforcement**: `smoke-tasklist-ordering.sh` scans the dispatcher (`commands/multi-agent/SKILL.md`) and every mode entry point doc (`commands/multi-agent/{autopilot,local,local-autopilot,analysis,resume-local}/SKILL.md` + the Copilot full-inline orchestrator mirror) for the explicit "in phase-number order" rule. Inventory drift fails the smoke.
 

package/pipeline/schemas/agent-state.schema.json

@@ -76,10 +76,94 @@
       "type": "string",
       "description": "PR target branch (e.g. develop, main)."
     },
+    "baseFetchStatus": {
+      "type": "string",
+      "enum": ["fresh", "cached-stale", "local-branch", "aborted"],
+      "description": "What the base ref is worth. fresh = git fetch origin succeeded; cached-stale = the fetch failed and the user chose the remote-tracking cache; local-branch = the fetch failed and the user chose the local branch; aborted = the user stopped the run at the fetch-fail picker. phase0-exit-gate.mjs has required this field since v17.0, while this schema forbade it under additionalProperties: false - so a state that satisfied the gate failed validation and vice versa. Declared here as of v17.5.0."
+    },
     "baseBranchSource": {
       "type": "string",
-      "enum": ["asked", "input", "remembered", "default"],
-      "description": "How baseBranch was decided. asked = the user answered the Step 3 picker; input = it arrived with the task reference; remembered = autopilot took the most recent entry in prefs.global.recentBranches still inside the TTL and still on the remote; default = autopilot fell back to the develop/release/main sort order. An autopilot run cannot be asked anything, so recording which rule fired is what keeps it readable afterwards."
+      "enum": ["asked", "input", "remembered", "default", "derived"],
+      "description": "How baseBranch was decided. asked = the user answered the Step 3 picker; input = it arrived with the task reference; remembered = autopilot took the most recent entry in prefs.global.recentBranches still inside the TTL and still on the remote; default = autopilot fell back to the develop/release/main sort order; derived = autopilot took the top base-branch-candidates.mjs candidate, which carried issue-version or linked-release evidence and tied with nothing. The last three are autopilot resolutions: an autopilot run cannot be asked anything, so recording which rule fired is what keeps it readable afterwards, and an interactive run that records one has skipped its picker. A derived branch that a human then confirmed is still asked - the derivation is recorded in baseBranchEvidence, not in this field."
+    },
+    "baseBranchEvidence": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "v17.5.0+ - what Step 3 knew when it chose the base branch (refs/features/base-branch-evidence.md). Required when baseBranchSource is derived, and whenever baseFetchStatus is cached-stale or local-branch: a run may degrade to local refs, it may not report a local-only list as the remote's answer.",
+      "required": ["refProvenance"],
+      "properties": {
+        "refProvenance": {
+          "type": "string",
+          "enum": ["remote", "local"],
+          "description": "Where the candidate ref list came from. local means the fetch failed and the list is the local cache plus local heads - possibly stale, possibly incomplete."
+        },
+        "chosen": { "type": "string" },
+        "ambiguous": {
+          "type": "boolean",
+          "description": "Two or more candidates tied at the top score. Autopilot may not record derived when this is true."
+        },
+        "convention": {
+          "type": ["object", "null"],
+          "additionalProperties": false,
+          "description": "The release-branch template inferred from the refs that exist, never from a built-in table.",
+          "properties": {
+            "template": { "type": "string" },
+            "members": { "type": "integer", "minimum": 0 }
+          }
+        },
+        "candidates": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["branch"],
+            "properties": {
+              "branch": { "type": "string" },
+              "score": { "type": "number" },
+              "refs": { "type": "array", "items": { "type": "string" } },
+              "evidence": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["kind"],
+                  "properties": {
+                    "kind": {
+                      "type": "string",
+                      "enum": [
+                        "issue-version",
+                        "linked-release",
+                        "version-convention",
+                        "recent",
+                        "repo-default",
+                        "sort-order",
+                        "ref-provenance"
+                      ]
+                    },
+                    "detail": { "type": "string" }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "notes": { "type": "array", "items": { "type": "string" } },
+        "askedOnIssue": {
+          "type": ["object", "null"],
+          "additionalProperties": false,
+          "description": "The one comment autopilot is allowed to post when the derivation is ambiguous, gated by prefs.global.baseBranchEvidence.autopilotAsksOnIssue (default false). A question, never a state change: no transition, no close, no assignee. Posting it trips circuit-breaker trigger 6 and the run waits for resume.",
+          "properties": {
+            "target": { "type": "string" },
+            "url": { "type": "string" },
+            "at": { "type": "string", "format": "date-time" }
+          }
+        }
+      }
+    },
+    "workspaceSource": {
+      "type": "string",
+      "enum": ["asked", "command", "autopilot"],
+      "description": "Who decided where the branch lives. asked = the user answered the Step 5b workspace picker; command = :local / --local / :local-autopilot stated it up front, or a flow that only ever builds worktrees; autopilot = resolved to a worktree without asking, because an unattended commit in the user's own checkout is what worktrees prevent. localMode alone cannot say: false is both a chosen worktree and one nothing asked about."
     },
     "remoteType": {
       "type": "string",
@@ -883,7 +967,7 @@
     "circuitBreaker": {
       "type": "object",
       "additionalProperties": false,
-      "description": "Autopilot circuit-breaker record (refs/features/autopilot-circuit-breaker.md). Written only when a trigger trips: trigger 2 by Phase 4 Step 3.8 (a mandate finding survived identicalFindingCycles rework cycles), trigger 3 by the Phase 3 re-entry hard-kill. /multi-agent:resume clears tripped and keeps counters.",
+      "description": "Autopilot circuit-breaker record (refs/features/autopilot-circuit-breaker.md). Written only when a trigger trips: trigger 2 by Phase 4 Step 3.8 (a mandate finding survived identicalFindingCycles rework cycles), trigger 3 by the Phase 3 re-entry hard-kill, trigger 6 by Phase 0 Step 3 when autopilot posted the base-branch question on the issue and must not answer it itself. /multi-agent:resume clears tripped and keeps counters.",
       "required": ["tripped"],
       "properties": {
         "tripped": {
@@ -892,7 +976,7 @@
         "trigger": {
           "type": ["integer", "null"],
           "minimum": 1,
-          "maximum": 5
+          "maximum": 6
         },
         "detail": {
           "type": "string"

package/pipeline/schemas/prefs.schema.json

@@ -969,6 +969,28 @@
             }
           }
         },
+        "baseBranchEvidence": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "v17.5.0+ - Phase 0 Step 3 base-branch evidence collection (refs/features/base-branch-evidence.md). Candidates are collected with the evidence behind them (issue version field, linked release issue, the branch convention learned from the refs that exist, recent branches, repo default), ranked, and shown. Interactive runs always ask; the evidence only reorders the rows.",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": true,
+              "description": "Collect issue-derived candidates at all. Off falls back to the develop/release/main sort order, which is still surfaced through the picker."
+            },
+            "preferLinkedRelease": {
+              "type": "boolean",
+              "default": false,
+              "description": "On boards where opening a development sub-task requires selecting the related release issue, that link is the authoritative base-branch answer and the version field is corroboration. Raises the linked-release weight above the version-field one rather than adding a second rule."
+            },
+            "autopilotAsksOnIssue": {
+              "type": "boolean",
+              "default": false,
+              "description": "OFF by default, and it is an outward-facing write. When on, an autopilot run whose base-branch derivation is ambiguous posts ONE comment on the Jira or GitHub issue asking which branch to develop from, then halts on circuit-breaker trigger 6 and waits for resume. A question, never a state change: no transition, no resolution, no assignee, no close. The body uses Ref:, never Closes:/Fixes:/Resolves:, and its human-facing copy follows outputLanguage. Autopilot never posts the question and then answers it itself."
+            }
+          }
+        },
         "autopilotCircuitBreaker": {
           "type": "object",
           "additionalProperties": false,

package/pipeline/schemas/review-file-exclusions.json

@@ -0,0 +1,137 @@
+{
+  "$comment": "Not a JSON Schema: the data the review file filter reads. Lives beside token-budget.json for the same reason - it is a budget-shaped decision the pipeline owns, versioned with the code that consumes it.",
+  "version": 1,
+  "patterns": [
+    {
+      "glob": "**/*.generated.*",
+      "reason": "generated file - review the generator, not its output"
+    },
+    {
+      "glob": "**/Generated/**",
+      "reason": "generated tree - review the generator, not its output"
+    },
+    {
+      "glob": "**/generated/**",
+      "reason": "generated tree - review the generator, not its output"
+    },
+    { "glob": "**/*.pb.go", "reason": "generated file - review the generator, not its output" },
+    { "glob": "**/*_pb2.py", "reason": "generated file - review the generator, not its output" },
+
+    {
+      "glob": "**/package-lock.json",
+      "reason": "lockfile - resolved by the package manager, not written by hand"
+    },
+    {
+      "glob": "**/yarn.lock",
+      "reason": "lockfile - resolved by the package manager, not written by hand"
+    },
+    {
+      "glob": "**/pnpm-lock.yaml",
+      "reason": "lockfile - resolved by the package manager, not written by hand"
+    },
+    {
+      "glob": "**/Package.resolved",
+      "reason": "lockfile - resolved by the package manager, not written by hand"
+    },
+    {
+      "glob": "**/Podfile.lock",
+      "reason": "lockfile - resolved by the package manager, not written by hand"
+    },
+    {
+      "glob": "**/Gemfile.lock",
+      "reason": "lockfile - resolved by the package manager, not written by hand"
+    },
+    {
+      "glob": "**/poetry.lock",
+      "reason": "lockfile - resolved by the package manager, not written by hand"
+    },
+    {
+      "glob": "**/Cargo.lock",
+      "reason": "lockfile - resolved by the package manager, not written by hand"
+    },
+    {
+      "glob": "**/gradle.lockfile",
+      "reason": "lockfile - resolved by the package manager, not written by hand"
+    },
+
+    {
+      "glob": "**/__snapshots__/**",
+      "reason": "recorded snapshot - the assertion is the test that records it"
+    },
+    {
+      "glob": "**/*.snap",
+      "reason": "recorded snapshot - the assertion is the test that records it"
+    },
+    {
+      "glob": "**/__Snapshots__/**",
+      "reason": "recorded snapshot - the assertion is the test that records it"
+    },
+    {
+      "glob": "**/ReferenceImages/**",
+      "reason": "recorded snapshot - the assertion is the test that records it"
+    },
+
+    {
+      "glob": "vendor/**",
+      "reason": "vendored third-party source - not ours to change in this diff"
+    },
+    {
+      "glob": "**/node_modules/**",
+      "reason": "vendored third-party source - not ours to change in this diff"
+    },
+    {
+      "glob": "Pods/**",
+      "reason": "vendored third-party source - not ours to change in this diff"
+    },
+    {
+      "glob": "**/third_party/**",
+      "reason": "vendored third-party source - not ours to change in this diff"
+    },
+
+    {
+      "glob": "**/*.min.js",
+      "reason": "build output - unreadable by design, and the source is elsewhere in the diff"
+    },
+    {
+      "glob": "**/*.min.css",
+      "reason": "build output - unreadable by design, and the source is elsewhere in the diff"
+    },
+    {
+      "glob": "**/*.map",
+      "reason": "build output - unreadable by design, and the source is elsewhere in the diff"
+    },
+    {
+      "glob": "dist/**",
+      "reason": "build output - unreadable by design, and the source is elsewhere in the diff"
+    },
+    {
+      "glob": "build/**",
+      "reason": "build output - unreadable by design, and the source is elsewhere in the diff"
+    },
+    {
+      "glob": ".build/**",
+      "reason": "build output - unreadable by design, and the source is elsewhere in the diff"
+    },
+    {
+      "glob": "**/DerivedData/**",
+      "reason": "build output - unreadable by design, and the source is elsewhere in the diff"
+    },
+
+    { "glob": "**/*.png", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.jpg", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.jpeg", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.gif", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.webp", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.pdf", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.zip", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.ipa", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.apk", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.aab", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.mp4", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.mov", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.ttf", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.otf", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.woff", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.woff2", "reason": "binary asset - a text reviewer cannot read it" }
+  ]
+}