@mmerterden/multi-agent-pipeline 17.3.0 → 17.5.0

package/pipeline/multi-agent-refs/features/code-intelligence.md

@@ -0,0 +1,80 @@
+## Code Intelligence (multi-agent-toolkit `code_*`)
+
+Compiler-grade answers about Swift and Kotlin source, from the language server
+each platform already ships. Eight tools in the companion MCP server
+(`@mmerterden/multi-agent-toolkit-mcp` 3.10.0 and later), all read-only except
+`code_server_reset`.
+
+### What it is for, and what `code-graph.md` already covers
+
+These two answer different questions and neither replaces the other.
+
+| Question | Use |
+|---|---|
+| Where does this concept live in a repo I do not know | `code-graph.md` - one cheap pass over the whole tree, token-budgeted |
+| What depends on this area, roughly | `graph-affected` |
+| Is THIS exact symbol referenced, and where | `mcp__multi-agent-toolkit__code_references` |
+| What type is this, really | `mcp__multi-agent-toolkit__code_hover` |
+| Does this file compile, without a full build | `mcp__multi-agent-toolkit__code_diagnostics` |
+
+`docs/adr/0010-own-code-graph.md` states the trade the graph makes in as many
+words: *"Regex over comment-stripped source is not a parser. Definitions and
+imports survive that trade; call graphs and type resolution do not."* It names
+two consequences - a name declared in two files is dropped rather than fanned
+out, so `affected` under-reports on duplicated names, and only type-like symbols
+are reference targets. Those are exactly the two the language server answers
+exactly. So the graph stays the wide, cheap first pass, and `code_*` is what a
+specific claim is checked against.
+
+### The one thing to know before trusting an answer
+
+An empty result is not the same as a negative result, and on a cold repository
+it is the likelier of the two. Measured on Swift 6.3.1 against a two-file
+package: the same `references` query answered 0 at 0.7s and 3 at 5.8s, with
+nothing changed except that the background index had finished. On a 658-file
+package with dependencies the first index had not finished at 70s.
+
+Every index-backed result therefore carries `indexReady`, and the tools wait for
+the index rather than answering early. When `indexReady` is false, an empty list
+means "not indexed yet". Never report it as "unused".
+
+`code_index_status` answers whether this machine can answer at all, and it
+succeeds even when nothing is installed - it is the tool to run first on an
+unfamiliar machine.
+
+### Root decides what an answer is worth
+
+`semantic` and `buildSettingsSource` come back on every result.
+
+| Root | definition | references | diagnostics |
+|---|---|---|---|
+| `Package.swift` | yes | yes, after the index settles | yes |
+| `buildServer.json` | yes | yes | yes |
+| `.xcodeproj`, no build server | same-file only | no, `semantic: false` | misleading, marked non-semantic |
+
+A modular app is mostly packages, so this matters less than it reads: the iOS
+app measured here has 41 `Package.swift` roots and a single `.swift` file under
+the umbrella project.
+
+### Where a run uses them
+
+All three are opt-in and none is on by default.
+
+1. **Phase 4, checking a citation's claim.** `verify-citations.mjs` already
+   proves a cited `file:line` exists. `code_hover` at that position proves the
+   line holds what the finding says it holds, and `code_references` falsifies a
+   "nothing handles this" claim.
+2. **Phase 1, sharpening an impact estimate.** When `graph-affected` reports on
+   a name that the graph itself flagged as ambiguous, `code_references` on the
+   one symbol the task names resolves it exactly.
+3. **Phase 3, fast feedback.** `code_diagnostics` on the file just edited,
+   without waiting for `xcodebuild`.
+
+### Kotlin
+
+Runs on JetBrains `kotlin-lsp`: Alpha, partially closed source, Android Gradle
+Plugin support experimental, and installed separately
+(`brew tap JetBrains/utils && brew install kotlin-lsp`, JVM 17+). Answers carry
+`confidence: "alpha"`, and the toolkit's own README states that no gate in that
+repository exercises the Kotlin server. Treat Kotlin answers as a lead, not as
+evidence, until that changes.

package/pipeline/multi-agent-refs/features/design-conformance.md

@@ -1,6 +1,7 @@
 # Design conformance  -  the component walk, and why a glance is not a pass
 
 <!-- toc -->
+- [0. Why this runs as a gate](#0-why-this-runs-as-a-gate)
 - [1. Enumerate first, then fill every cell](#1-enumerate-first-then-fill-every-cell)
 - [2. Measure, never read the token](#2-measure-never-read-the-token)
 - [3. Adaptive per-component convergence](#3-adaptive-per-component-convergence)
@@ -24,6 +25,19 @@ Consumers: `/multi-agent:design-check` (the runner), Phase 4 review when a UI
 diff is under review, and `features/visual-evidence.md` when a capture has to
 prove a fix. Gate: `smoke-design-conformance.sh`.
 
+## 0. Why this runs as a gate
+
+`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.
+
+The reason it cannot be advice is structural, not historical: a reviewer reading a diff
+cannot see spacing. Every other Phase 4 check reads text and reasons about text; this
+one is the only thing in the pipeline that compares a rendered result against the
+design it was drawn from. Left optional, it is the check that gets skipped on exactly
+the runs that are in a hurry, which are the runs that produce drift.
+
 ## 1. Enumerate first, then fill every cell
 
 Do **not** walk by finding, and do not walk by headline. Build the inventory

package/pipeline/multi-agent-refs/features/review-file-set.md

@@ -0,0 +1,132 @@
+# The review file set  -  what was read, and what was not, on the record
+
+<!-- toc -->
+- [Why this exists](#why-this-exists)
+- [The set is fixed before the reviewer sees the diff](#the-set-is-fixed-before-the-reviewer-sees-the-diff)
+- [Every exclusion names the pattern that produced it](#every-exclusion-names-the-pattern-that-produced-it)
+- [The reviewer answers for each file](#the-reviewer-answers-for-each-file)
+- [Invocation](#invocation)
+- [What this is not](#what-this-is-not)
+<!-- /toc -->
+
+> The denominator for Phase 4's other axis. Loaded on demand by
+> `/multi-agent:review` and by pipeline Phase 4.
+
+## Why this exists
+
+Phase 4 had a size cap and no exclusion list. When the diff exceeds the phase
+token allowance the cap truncates the LARGEST files first, so a regenerated
+lockfile or a snapshot dump is not merely wasted budget: it is the thing that
+survives while real code is cut.
+
+The second half is worse and quieter. A reviewer that opened one file of ten and
+a reviewer that read all ten and found nothing return the identical
+`{"findings": [], "approved": true}`. Nothing in the pipeline could tell them
+apart, so "no findings" has been carrying two meanings at once.
+
+Both halves are one fix: decide what is worth reading BEFORE the cap decides
+what fits, and make the reviewer answer for each file it was given.
+
+## The set is fixed before the reviewer sees the diff
+
+The same rule `selectedRules[]` follows, for the same reason. After a model has
+seen the diff, "I did not open that one" and "there was nothing there" become
+the same sentence, and whichever one is cheaper to say is the one that gets
+said. So the set is computed from `git diff --name-only`, written to
+`.pipeline/review-files.json`, and never recomputed inside the round.
+
+```bash
+git -C "$WORKTREE" diff --name-only "$BASE_BRANCH"...HEAD \
+  | node $HOME/.claude/scripts/review-file-filter.mjs \
+  > "$WORKTREE/.pipeline/review-files.json"
+```
+
+Report shape:
+
+```json
+{
+  "reviewed": ["src/App.swift"],
+  "excluded": [
+    {
+      "path": "package-lock.json",
+      "reason": "lockfile - resolved by the package manager, not written by hand",
+      "pattern": "**/package-lock.json"
+    }
+  ],
+  "total": 2,
+  "patternsSource": ".../schemas/review-file-exclusions.json",
+  "patternCount": 45
+}
+```
+
+`reviewed` is what goes into the diff cap and into the reviewer prompt, as a
+`${REVIEW_FILES}` block beside `${CRITERIA}` in the shared cache prefix. It has to
+be in the prompt: a reviewer asked to account for a set it was never shown can
+only guess, and `fileCoverage` would then fail on every single dispatch - a gate
+that always fires is a gate that gets switched off. `excluded` goes into the run
+report, never into silence.
+
+## Every exclusion names the pattern that produced it
+
+A file that disappears between the diff and the review is indistinguishable from
+a file nobody found anything in - which is the exact confusion this whole
+feature exists to remove, so reintroducing it in the filter would be
+self-defeating. Each excluded row carries both the human reason and the glob
+that matched, so a reviewer, a PR reader or a future maintainer can dispute the
+call rather than discover it.
+
+The pattern list is data, in `schemas/review-file-exclusions.json`, and it is
+generic: generated trees, lockfiles, recorded snapshots, vendored source, build
+output, binary assets. No stack, project or company name appears in it. A
+pattern with no reason invalidates the whole list rather than being defaulted -
+the default would be exactly the sentence the caller is supposed to print.
+
+**It fails open, on purpose.** An unreadable or malformed pattern file yields
+every file reviewed, the reason on stderr, and exit 2. Failing closed would
+review nothing and report a clean run.
+
+## The reviewer answers for each file
+
+`reviewer-output.schema.json` (v1.3.0) carries `fileCoverage[]`: one row per
+path in `reviewed`, `{path, verdict: reviewed|skipped, reason}`. There is
+deliberately no `partial` - a file read in part is read, and what was not
+understood belongs in a finding.
+
+`validate-reviewer.mjs --coverage <report>` enforces it, catching the same three
+failures the conformance checklist catches on the rule axis:
+
+| Failure | Why it matters |
+|---|---|
+| a file in the set with no row | silently unread, and the empty `findings[]` reads as clean |
+| a row for a path outside the set | an answer about something the reviewer was not given, the same shape as a hallucinated rule ID |
+| `skipped` with no reason | a drop with no cause is indistinguishable from a read |
+
+`skipped` is legitimate and expected: a file past the diff cap, a file whose
+content the host truncated. What it may not be is unexplained. "Not relevant" is
+a review decision and belongs in a verdict of `reviewed`, not a skip.
+
+An empty `reviewed` set (a diff that is entirely lockfiles) demands no checklist
+at all. Requiring an empty array there would fail honest output, and the
+filter's `excluded[]` is what carries that information onward.
+
+## Invocation
+
+```bash
+node $HOME/.claude/scripts/validate-reviewer.mjs "$REVIEWER_FILE" \
+  --criteria "$WORKTREE/.pipeline/criteria-manifest.json" \
+  --coverage "$WORKTREE/.pipeline/review-files.json"
+```
+
+Without `--coverage` the field stays optional, so every existing caller keeps
+working unchanged. With it, the checklist is enforced and exit 1 takes the same
+single self-correction rework the rest of the validator gate takes.
+
+## What this is not
+
+It is not a relevance filter. Nothing here decides that a file is uninteresting;
+it decides that a file is not human-authored source, which is a mechanical
+question with a mechanical answer. The moment a pattern starts encoding "we
+probably do not care about this directory", the list has become a way to hide
+work, and the near-miss assertions in `smoke-review-file-filter.sh`
+(`CodeGenerator.swift`, `generated-report.md`, `distribution/`, `buildSrc/`) are
+what fail when it does.

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

@@ -93,7 +93,7 @@ Phase 0: Init -> Phase 3: Dev (self-contained) -> Phase 4: Review -> Phase 5: Te
 | Phase               | Full                                            | Short                                                                              | Short + `--local`                             |
 | ------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------- |
 | Phase 0 (Init)      | Full setup                                      | Same  -  worktree, branch, state, and the depth question itself                      | Same  -  no worktree, branch on `$PROJECT_ROOT` |
-| Phase 1 (Analysis)  | Parallel Explore agents + analysis document     | **SKIP**  -  tile flips to `skipped` at Step 7.5                                     | **SKIP**                                      |
+| Phase 1 (Analysis)  | Parallel Explore agents + analysis document     | **SKIP**  -  no tile is ever drawn for it (registration is deferred to 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 (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 |
@@ -111,7 +111,7 @@ The **Opus** agent receives the task description (from Jira, GitHub issue, or fr
 
 No separate task breakdown  -  the agent handles scope autonomously.
 
-**State tracking**: `agent-state.json` gets `"onlyDevelop": true`. Because the tracker boots at Step -1 and the answer arrives at Step 7.5, Phases 1 and 2 are registered `pending` with everything else and flipped to `skipped` when the answer lands; pre-marking is forbidden and would scramble the tile order. Full contract: `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "Late skip".
+**State tracking**: `agent-state.json` gets `"onlyDevelop": true`. The tracker boots at Step -1 with Phase 0 alone and the rest of the tiles are registered at Step 7.5, once this answer says which phases the run actually has - so a Short run never draws an Analysis tile it will not use. Full contract: `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "Deferred registration".
 
 ### Intake warnings for a Short run
 
@@ -161,7 +161,22 @@ Phase 0: Init -> Phase 1: Analysis -> Phase 2: Planning -> Phase 4: Review -> Ph
 
 Local mode skips worktree creation  -  works directly on a local branch in the project root. Useful for single-task workflows or when worktrees cause issues.
 
-**Activation**: the `:local` entries, or `--local` on the base command:
+**Activation**: answer the Phase 0 Step 5b workspace question, or state it up
+front so the question resolves without being asked.
+
+```
+Bu is nerede kossun? / Where should this task run?
+  1. Worktree       .worktrees/{id}/ - your current checkout stays untouched
+  2. Lokal / Local  the project root, on a new branch - no Phase 5
+```
+
+Two genuine options, so it meets the two-option floor in `picker-contract.md` on
+its own. **Say what local costs inside the question**: Phase 5 is not in a local
+run's set (the user-test gate checks the change out of a worktree, and there is
+none), and uncommitted work in the project root is in the way of the checkout. A
+user choosing local should learn both before choosing, not after.
+
+The ways to state it up front:
 
 ```
 /multi-agent:local "PROJ-12345"
@@ -171,6 +186,11 @@ Local mode skips worktree creation  -  works directly on a local branch in the p
 /multi-agent "PROJ-12345" --local
 ```
 
+Every autopilot entry resolves this to **worktree** and never asks. That is not a
+skipped question: an unattended run commits and pushes from wherever it stands,
+and doing that in the user's own checkout is what worktrees exist to prevent.
+`:local-autopilot` is the explicit opt-out.
+
 **What changes in local mode:**
 
 | Phase          | Normal (worktree)                                | Local                                                          |

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.