@mmerterden/multi-agent-pipeline 17.4.0 → 17.5.0

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

@@ -1,6 +1,6 @@
 ### Phase 0: Init
 
-> **TLDR**  -  8 sequential steps: load prefs → parse input (Jira/GitHub/free-text) → select project → detect remote + pick base branch → optional design input → branch name → git identity → instruction files → create worktree/local branch + agent-state.json. Every input type (Jira URL, GitHub issue, free-text) flows through the same 8 steps.
+> **TLDR**  -  every input type flows through the same numbered steps below, in order, and ends at the exit gate.
 
 #### Step −1  -  Bootstrap the cross-CLI tracker (FIRST thing in every run)
 
@@ -9,13 +9,17 @@ Before anything else  -  initialize the visual tracker so the user sees the pipe
 ```bash
 TASK_ID="${INPUT_TASK_ID:-pipeline-$(date +%Y%m%d-%H%M%S)}"
 $HOME/.claude/scripts/phase-tracker.sh init "$TASK_ID"
-for p in 0:Init 1:Analysis 2:Planning 3:Dev 4:Review 5:Test 6:Commit 7:Report; do
-  $HOME/.claude/scripts/phase-tracker.sh add "${p%%:*}" "${p#*:}"
-done
+$HOME/.claude/scripts/phase-tracker.sh add 0 Init
 $HOME/.claude/scripts/phase-tracker.sh tiles
 $HOME/.claude/scripts/phase-tracker.sh update 0 in_progress
 ```
 
+**Phase 0 only.** `/multi-agent` and `:local` do not know their phase set yet -
+depth decides it, and depth is Step 7.5 - so they register the rest there rather
+than drawing eight tiles the user has not chosen. Every other mode registers its
+whole set here, in phase-number order. Contract: `tracker-contract.md`,
+"Deferred registration".
+
 `tiles` prints this host's widget-registration calls: **make them before continuing.** The card alone lands in collapsed tool output, so a run that skips them runs in silence. Contract: `tracker-contract.md`, "The card is not the widget".
 
 If `INPUT_TASK_ID` isn't known yet (free-text, project not selected), use a placeholder; rename later via `mv` once parsed in Step 1.
@@ -26,7 +30,7 @@ Every subsequent phase (1-7) MUST call `phase-tracker.sh update <N> in_progress`
 
 ##### TaskCreate ordering on Claude Code (strict)
 
-On Claude Code, fire all `TaskCreate` calls in strict phase-number order (0 → 7) BEFORE any `TaskUpdate` - which is the order `tiles` prints them in. Full contract: `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
+On Claude Code, fire every `TaskCreate` in a registration batch in strict phase-number order BEFORE any `TaskUpdate` in that batch - which is the order `tiles` prints them in - and never register a phase whose number is below one already registered. A deferred batch (Step 7.5) therefore appends, it does not interleave. Full contract: `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
 
 ---
 
@@ -261,58 +265,76 @@ Scan `$HOME` (maxdepth 2) for project markers (`.xcodeproj`, `Package.swift`, `b
 
 **Test policy (once per project).** Resolve `prefs.projects[{slug}].testPolicy` → `state.testPolicy`; missing → native picker "Should development write tests here?" (`header`: "Tests"): `tdd` (recommended) / `tests-after` / `none`; persist. Autopilot without a record: `tdd`, noted.
 
+#### Step 2b  -  Dev context (extra repos)
+
+Run `$HOME/.claude/multi-agent-refs/_dev-context.md`: `.gitmodules` submodules
+plus `prefs.projects[{project}].webRepos[]`, editable ones pre-selected,
+read-only siblings listed. It runs on every input type, direct-ID included, and
+an empty submit is a valid answer meaning primary repo only. Here rather than
+later because a base branch is a property of a repo set (`picker-contract.md`,
+"Order: project, then repo, then branch").
+
+Persist `state.siblings[]` even when empty: the empty array is the record that
+the step ran. Absent, Phase 4's parity cross-check cannot tell "no siblings"
+from "never asked", and the exit gate below fails.
+
 #### Step 3  -  Remote Detection + Branch Selection
 
 1. **Check preferences first**: If `prefs.projects[{project}].remoteType` exists, use cached value.
 2. Read remote: `git -C $PROJECT_ROOT remote get-url origin`
 3. Detect type: `github.com` → github (`gh` CLI), `{BITBUCKET_HOST}` → bitbucket (API + `keychainMapping.bitbucket_token`), other → generic-git. Save to `prefs.projects[{project}].remoteType`.
 4. **Skip if baseBranch already set** (from Step 1). Otherwise:
-5. Fetch + list PR-targetable branches:
+5. Fetch + list PR-targetable branches. **Capture the exit code** - it decides
+   whether the list may be called the remote's answer:
    ```bash
-   git -C $PROJECT_ROOT fetch origin
+   git -C $PROJECT_ROOT fetch origin; FETCH_RC=$?
    git -C $PROJECT_ROOT branch -r --sort=-committerdate \
-     | grep -E '(develop|release|main|master)' \
-     | grep -v -E '(feature/|bugfix/|fix/|hotfix/|chore/)'
+     | grep -v -E '(feature/|bugfix/|fix/|hotfix/|chore/)' \
+     | grep -E '([0-9]+[._][0-9]+|develop|release|main|master)'
    ```
-6. Sort: `develop*` first, then `release/*`, then `main`/`master`. Surface through the
-   **native picker** per `picker-contract.md`, recent branch first and marked
-   `(Recommended)`:
+   **Keep the version alternative.** A branch carrying a version token is a
+   candidate whatever it is called; the family words only RANK. Why that
+   distinction matters: `features/base-branch-evidence.md`, "A filter is not a
+   ranking".
+5b. With `prefs.global.baseBranchEvidence` on, pipe that list plus the issue's
+   version fields and links through `$HOME/.claude/scripts/base-branch-candidates.mjs`,
+   which ranks the candidates and records the evidence behind each. It is pure, so
+   Step 3 owns every git and network call. Contract - autopilot resolution order and
+   the fenced ask-on-the-issue path included:
+   `$HOME/.claude/multi-agent-refs/features/base-branch-evidence.md`. Off: rule 6 alone.
+6. Sort: `develop*` first, then `release/*`, then `main`/`master` (the collector's
+   order when it ran). Surface through the **native picker** per `picker-contract.md`,
+   recent branch first and marked `(Recommended)`, each row carrying its evidence:
 
    ```
    header: "Base branch"
    options: origin/develop (Recommended, reused from last run) | origin/main | release/8.4.0 | Other
    ```
-7. User picks → store as `baseBranch`, and append `{branch, lastUsed, count?}` to
+7. User picks → store as `baseBranch` with `baseBranchSource: "asked"`, and append `{branch, lastUsed, count?}` to
    `prefs.global.recentBranches[{projectKey}]` (dedup by `branch`, cap 10) - what the TTL
    filter below reads. Key is `branch`, not `name`. Never the legacy
    `projects[{project}].branches`.
 
 **MUST: this step is not skippable (BLOCKING).** The only legitimate skip is rule 4
-above - `baseBranch` already supplied in the input. Everything else asks. A run once
-took a Jira ID and implemented straight onto whatever the local checkout was pointing
-at, with neither the project nor the branch picker ever shown; nothing failed, so
-nothing surfaced it. `phase0-exit-gate.mjs` now refuses to close Phase 0 unless
-`agent-state.json` carries `baseBranch` and `baseFetchStatus`, so a skipped picker is a
-gate failure rather than a silent default.
+above, recorded as `baseBranchSource: "input"`. Everything else asks, and
+`phase0-exit-gate.mjs` refuses to close Phase 0 without `baseBranch`,
+`baseFetchStatus` and `baseBranchSource` - a skipped picker fails the gate.
 
-One row is a normal outcome of the rule-5 filter and is **still asked** - see
-`picker-contract.md` "A single candidate is still a question".
+One row is a normal outcome of the rule-5 filter and is **still asked**, with a
+real second option - `picker-contract.md`, "Two options or it is not a question".
 
 This holds in every mode. A Short run skips the *LLM* phases (Analysis, Planning); it
 does not skip Phase 0's pickers. Autopilot resolves them without prompting, which still
-writes the fields. For the base branch it reads `recentBranches[{projectKey}]` (most
-recent inside the TTL, still on the remote) before the rule-6 order, recording which
-fired in `state.baseBranchSource`.
+writes the fields; its base-branch resolution order is in `features/base-branch-evidence.md`.
 
 **TTL filter for recent branches**:
 
-- `prefs.global.recentBranches[{projectKey}][]` carries `{branch, lastUsed, count?}`. Filter to those whose `lastUsed` is within `settings.branchTtlDays` (default 15).
-- Stale entries (>TTL) are pruned in-place during the read  -  keeps the picker uncluttered without a separate cleanup pass.
+- `prefs.global.recentBranches[{projectKey}][]` carries `{branch, lastUsed, count?}`. Keep those whose `lastUsed` is within `settings.branchTtlDays` (default 15); prune the rest in place during the read.
 - The filtered "Recent" list precedes the fresh `git branch -r` list; cap at 5 visible recent entries.
 
 **Fetch-fail handling** (replaces silent `git fetch origin` failure):
 
-The legacy `git -C $PROJECT_ROOT fetch origin` step (line 110 above) MUST not silently fall back to a stale cached ref. On non-zero exit, surface the **native picker** (per `picker-contract.md`) with 4 options:
+`FETCH_RC` non-zero MUST not silently fall back to a stale cached ref. Surface the **native picker** (per `picker-contract.md`) with 4 options:
 
 ```
 question:    "git fetch failed for {project} - the base ref may be stale. How should I proceed?"
@@ -325,19 +347,13 @@ options:
   Abort                                     no worktree, no branch, no state file
 ```
 
-**Say which is which.** The question must name the corporate host when the remote points
-at one - a `{BITBUCKET_HOST}` remote failing to resolve is almost always the VPN, and
-telling the user that is the difference between a five-second fix and a run built on a
-month-old ref. "Connect VPN and retry" re-runs the fetch and re-enters this picker if it
-fails again; it is a real retry, not a label.
+**Say which is which.** Name the host when the remote points at one - an unresolvable
+`{BITBUCKET_HOST}` is almost always the VPN - and make the retry real: it re-runs the
+fetch and re-enters this picker on a second failure.
 
-Persist user choice in `agent-state.json.baseFetchStatus` ∈ `"fresh" | "cached-stale" | "local-branch" | "aborted"`. On any non-fresh choice, log:
-```
-⚠️ Base ref stale (fetch fail @ {ts}, choice: {cached-stale|local-branch})
-```
-Phase 6 (commit/push) MUST re-attempt `git fetch origin` before push; if successful, prompt to rebase before pushing.
+Persist the choice in `agent-state.json.baseFetchStatus` ∈ `"fresh" | "cached-stale" | "local-branch" | "aborted"`, and on any non-fresh one log `⚠️ Base ref stale (fetch fail @ {ts}, choice: {status})`. Phase 6 re-attempts `git fetch origin` before push and prompts to rebase if it succeeds.
 
-In multi-repo mode, the prompt fires per-repo. Choosing `[4] Abort` for any single repo aborts the entire task (atomic  -  no partial worktrees).
+In multi-repo mode the prompt fires per repo, and Abort on any one aborts the whole task (atomic - no partial worktrees).
 
 #### Step 4  -  Branch Naming (automatic)
 
@@ -365,10 +381,8 @@ Branch name is deterministic  -  no user confirmation needed.
 
 **Collision handling** (automatic  -  no prompt):
 - Probe local + remote for existing branch. **Distinguish "no such ref" from "the
-  probe failed"**: with `2>/dev/null` and an empty-output test they look identical,
-  so an auth or network failure reads as "no collision" and the run creates a
-  branch that already exists on the remote  -  surfacing as a rejected push at
-  Phase 6, far from its cause.
+  probe failed"**: with `2>/dev/null` and an empty-output test a failed probe reads
+  as "no collision", and the duplicate branch surfaces as a rejected push at Phase 6.
   ```bash
   LOCAL_HIT=$(git -C "$root" rev-parse --verify --quiet "refs/heads/$branch")
   REMOTE_ERR=$(git -C "$root" ls-remote --exit-code --heads origin "$branch" 2>&1 >/dev/null)
@@ -395,6 +409,21 @@ Branch name is deterministic  -  no user confirmation needed.
 3. Map instruction files to `"instructionFiles": { "start": "...", "validate": "...", "dev": "...", "commit": "..." }`
 4. Instruction-driven → later phases read SKILL.md; no instructions → standard phases
 
+#### Step 5b  -  Workspace (worktree or local)
+
+Ask where the branch lives - the wording, the two options and what local costs
+are in `modes.md`, "Local Mode". Here because Step 4 named the branch, Step 6b
+acts on the answer, and Step 7.5 needs the phase set it implies.
+
+**Who is asked.** `/multi-agent` only (`workspaceSource: "asked"`). `:local` and
+`--local` state it up front (`command`).
+Every autopilot entry resolves it to a worktree and never asks (`autopilot`).
+
+**Persist** `state.localMode` (semantics unchanged) and `state.workspaceSource`,
+which is what separates a worktree the user chose from one nothing asked about.
+
+Log: `Phase 0 Step 5b: workspace = {worktree|local} (source {asked|command|autopilot})`
+
 #### Step 6  -  Branch + Workspace Setup
 
 **6a. Resolve git identity** (automatic, no prompt):
@@ -419,7 +448,7 @@ Log: `Identity: {identity.name} <{identity.email}>`
 
 1. `git -C $PROJECT_ROOT fetch origin`
 
-**If `--local` mode** (no worktree):
+**If local** (Step 5b answered local, by question, by `:local` / `--local`):
 
 ```bash
 if [ -n "$(git -C $PROJECT_ROOT status --porcelain)" ]; then
@@ -430,9 +459,10 @@ git -C $PROJECT_ROOT config user.name "{identity.name}"
 git -C $PROJECT_ROOT config user.email "{identity.email}"
 ```
 
-`worktreePath` = `$PROJECT_ROOT`, `localMode` = `true`.
+`worktreePath` = `$PROJECT_ROOT`, `localMode` = `true`. Step 5b already recorded
+`workspaceSource`; this step does not decide, it applies.
 
-**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:
+**If worktree** (Step 5b answered worktree, or autopilot resolved it): 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`.
 
@@ -484,7 +514,7 @@ done
 
 State file in multi-repo mode:
 - Single shared `agent-state.json` lives at `$HOME/.claude/logs/multi-agent/{first-project}/{task-id}/agent-state.json` (anchored on the first repo for back-compat with `multi-agent log`/`status` commands)
-- **One shared file + per-repo writers is exactly the race `write-state.mjs` exists for.** Every update to it (here and in every later phase) goes through `node $HOME/.claude/scripts/write-state.mjs` per the required mechanism in `operations.md` "Writing `agent-state.json`". A read-modify-write from two repos in the same loop drops one repo's `projects[]` entry.
+- Every update to it, here and in every later phase, goes through `node $HOME/.claude/scripts/write-state.mjs`  -  the required mechanism in `operations.md` "Writing `agent-state.json`", and the race a per-repo read-modify-write loses `projects[]` entries to.
 - `state.projects[]` holds per-repo `{name, root, worktreePath, branch, baseBranch, identity, platform, baseFetchStatus, commit, pr, pushAttempts, buildStatus}`  -  see `agent-state.schema.json`
 - Scalar fields (`project`, `projectRoot`, `worktreePath`, `branch`, `baseBranch`, `identity`) mirror `projects[0]` so legacy phases that read scalars keep working
 - Atomicity: if any repo's worktree creation fails (collision aborted, fetch aborted, disk full), roll back already-created worktrees: `git -C $proj worktree remove --force $WT_PATH; git -C $proj branch -D $BRANCH`. Never leave a partial multi-repo state.
@@ -562,7 +592,7 @@ Ask the depth question from `$HOME/.claude/multi-agent-refs/phases/modes.md` "Pi
 
 When the intake carried an analysis document or a Figma reference, say so **inside** the question: Short skips the only two phases that would turn that document into a task breakdown, and the user should learn that before choosing, not after.
 
-**Pass the default explicitly, as an index.** `ask-choice.sh` picks the FIRST option on a non-TTY, so relying on option order breaks the first time someone reorders them for readability, on the host where nobody is watching. The default must be the 1-based index, never the label: labels follow `outputLanguage` (`rules.md` matrix), so `ASK_CHOICE_DEFAULT="Full"` matches nothing once the options render as `Tam` / `Kisa`, falls through, and silently takes option 1 on a non-TTY  -  the exact failure this step exists to prevent.
+**Pass the default as a 1-based index, never a label.** `ask-choice.sh` takes the first option on a non-TTY, and a label-valued default matches nothing once the options render in `outputLanguage`. Reasoning: `modes.md`, "Pipeline depth".
 
 ```bash
 # Full is option 1, Short is option 2 (modes.md "Pipeline depth")
@@ -572,7 +602,9 @@ ASK_CHOICE_DEFAULT="$DEPTH_DEFAULT_INDEX" \
   "<localized: 'Full'>" "<localized: 'Short'>"
 ```
 
-**Persist.** Short sets `state.onlyDevelop = true`; Full leaves it `false`. The key is unchanged - only who sets it changed - so every downstream reader keeps working. Short also flips the Phase 1 and Phase 2 tiles to `skipped` (tracker-contract.md, "Late skip"); pre-marking is forbidden.
+**Persist.** Short sets `state.onlyDevelop = true`; Full leaves it `false`. The key is unchanged - only who sets it changed - so every downstream reader keeps working.
+
+**Now register the rest of the widget.** This answer is the first moment the phase set is known, so the remaining tiles are created here and not before - Full `1 2 3 4 5 6 7`, Short `3 4 5 6 7`, `:local` dropping 5 from either. `add` each, then `phase-tracker.sh tiles --new`, which emits TaskCreate only for phases that carry no tile yet. Contract: `tracker-contract.md`, "Deferred registration".
 
 Log: `Phase 0 Step 7.5: depth = {full|short} (recommended {full|short}, source {user|autopilot|default})`
 
@@ -585,7 +617,7 @@ BASELINE_LOG="$WORKTREE/.baseline-test.log"
 timeout "${prefs_testBaseline_timeoutSeconds:-600}" <same-test-command-as-Phase-4-Gate-3> 2>&1 | tee "$BASELINE_LOG"
 ```
 
-Persist `state.baseline.tests` with `command`, `capturedAt`, `logPath` and exactly one status: `green` (passed), `red` + `failing[]` (failed, names parsed), `red` + empty `failing[]` (failed, names unparseable), `unknown` (no test command, `timeout` fired, or flag off). Folding `unknown` into `green` would let a skipped baseline read as a clean tree, which is the failure this record exists to prevent.
+Persist `state.baseline.tests` with `command`, `capturedAt`, `logPath` and exactly one status: `green` (passed), `red` + `failing[]` (failed, names parsed), `red` + empty `failing[]` (failed, names unparseable), `unknown` (no test command, `timeout` fired, or flag off). Never fold `unknown` into `green`: a skipped baseline would read as a clean tree.
 
 Log: `Phase 0 Step 7.6: test baseline = {green|red|unknown} ({N} pre-existing failures)`
 
@@ -606,9 +638,7 @@ if [ -n "$EVIDENCE_PLATFORM" ]; then
 fi
 ```
 
-Empty is an outcome, not a failure: backend has no device, so the probe does not run and `evidenceCapability.skippedReason` says so. Web does: the browser the runner drives is the device (4.6). No `--changed` yet, by the same token.
-
-One run, both forms: stdout is `EVIDENCE_*` (shell-quoted, so the eval is safe), and the same measurement lands as JSON.
+Empty is an outcome, not a failure: backend has no device, so the probe does not run and `evidenceCapability.skippedReason` says so. Web does  -  the browser the runner drives is the device (4.6). No `--changed` yet. One run, both forms: stdout is `EVIDENCE_*` (shell-quoted, so the eval is safe), and the same measurement lands as JSON.
 
 Persist that file as `state.evidenceCapability`, then build the menu from it, never from a reading of the repo: `1. Sadece unit test` / `2. Unit + UI test, ekran kaydiyla` (tier 1) / `3. Unit + MCP ile akis kaydi` (tier 2).
 
@@ -647,11 +677,7 @@ Log: `Phase 0 Step 7.7: testDepth = {unit|unit+ui|unit+mcp} (source {user|autopi
 
 5. Phase 1 Analysis reads `state.clarification.userAnswers` (when present) as additional context  -  fold answers into the Explore prompt so downstream phases inherit the resolution.
 
-**Cost:** ~$0.0025 per Haiku call. The pipeline's other expensive phases (Phase 4 reviewers, Phase 3 Sonnet codegen) far outweigh this  -  the value is avoiding the ~30 min wasted when Phase 3 builds the wrong thing because Phase 0 didn't ask.
-
-**Reference:** see `$HOME/.claude/agents/task-clarifier.md` for the full scoring rubric and question-quality rules.
-
-**Why this fits Phase 0 (not a new phase):** clarification doesn't change what code gets written  -  it changes what gets understood before code is written. Phase 0 already collects identity / project / branch / maturity; ambiguity scoring fits naturally as the last contextual gate.
+**Reference:** `$HOME/.claude/agents/task-clarifier.md`  -  scoring rubric, question-quality rules and the ~$0.0025-per-call cost note.
 
 #### Telemetry
 
@@ -686,20 +712,19 @@ node "$HOME/.claude/scripts/usage-report.mjs" --task-id "$TASK_ID" >/dev/null 2>
 The second line reports the run as started: reporting only from Phase 7 reported
 only runs that finish, and few do. Phase 7 upserts the same key over it.
 
-It asserts three things, each of which has failed silently in a real run:
+It asserts five things, each of which has failed silently in a real run:
 
-1. **`agent-state.json` exists.** A run once reported Phase 0 `completed` with only
-   `tracker-state.json` on disk. Every later phase then reasons from fields that are
-   not there.
-2. **`taskType` is set.** Phase 3 branches on it (Step 7). Absent, a Figma-driven
-   screen is dispatched as generic development, skipping the stack plugin's
-   token-compliance check, Code Connect publish and component review. That run
-   guessed `16` where the frame said `Spacing/12`, and half its commits were rework.
+1. **`agent-state.json` exists.** Every later phase reasons from it.
+2. **`taskType` is set.** Phase 3 branches on it (Step 7).
 3. **A Figma reference forces `taskType: "component"`, and `figmaAccess.tier` is
-   recorded.** Without the tier, a later phase cannot tell "the design was confirmed"
-   from "the design was never fetched"  -  which is exactly when spacing gets guessed.
+   recorded**, so a later phase can tell a confirmed design from an unfetched one.
+4. **`baseBranchSource` is recorded**, and an interactive run recorded `asked` or
+   `input`  -  the only field that separates a branch that was chosen from one that
+   was announced.
+5. **`siblings` is an array**, empty included: Step 2b's record that it ran.
+
+Each failed silently in a real run; the script header names which.
 
-A failure is a halt, not a warning. Fix the state and re-run the gate; the phase
-stays `in_progress` until it passes. **Never** mark Phase 0 completed on the grounds
-that its steps ran  -  the gate checks the output, and the output is what Phase 3
-consumes.
+A failure is a halt, not a warning: fix the state, re-run the gate, and leave the phase
+`in_progress` until it passes. Never close Phase 0 on the grounds that its steps ran -
+the gate checks the output, which is what Phase 3 consumes.

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"