@mmerterden/multi-agent-pipeline 17.4.0 → 17.5.0

package/pipeline/commands/multi-agent/autopilot-off/SKILL.md

@@ -45,9 +45,11 @@ pkill -f "$HOME/.claude/autopilot/bin/menubar" 2>/dev/null || true
 
 Without `--now` nothing here runs. With it, the child session is stopped and the
 run is marked `abandoned`, its worktree is removed **unless it holds uncommitted
-work**, in which case the work is stashed to `autopilot/abandoned/<task-id>` and
-the worktree is kept. Same contract as `gc-abandoned.sh`; losing a day of edits
-is worse than 750 MB.
+work**, in which case the work goes into a stash entry labelled
+`autopilot/abandoned/<task-id>` (find it with `git stash list`) and the worktree
+is kept. Same contract as `gc-abandoned.sh` and `autopilot-runner.mjs`; losing a
+day of edits is worse than 750 MB. No branch is created - one made after
+`stash push` would point at HEAD and contain none of the work.
 
 ### 5. Keep the selection
 

package/pipeline/commands/multi-agent/garbage-collect/SKILL.md

@@ -115,7 +115,7 @@ deletes nothing until you confirm.
    | Line | Meaning |
    |---|---|
    | `would remove` / `would remove worktree` | reapable: stopped past its age limit, or finished with its worktree left behind |
-   | `would stash` | uncommitted work found - it is stashed to `autopilot/abandoned/<task-id>` and the worktree is **kept** |
+   | `would stash` | uncommitted work found - it goes into a stash entry labelled `autopilot/abandoned/<task-id>` (`git stash list`) and the worktree is **kept** |
    | `would mark abandoned` | the state is stale but there is no worktree left to remove |
    | `unattributed` | a worktree with no run state. **Never removed, whatever the flags.** `.worktrees/` is not exclusively ours, and nothing distinguishes a hand-made worktree from a pipeline one whose log was pruned. Report the list and its size; the user decides |
 

package/pipeline/commands/multi-agent/local/SKILL.md

@@ -67,10 +67,21 @@ Two channels run in parallel at every phase boundary:
 ```bash
 # Phase 0, very first shell call (every CLI):
 bash $HOME/.claude/scripts/phase-tracker.sh init "$TASK_ID"
-for p in "0:Init" "1:Analysis" "2:Planning" "3:Dev" "4:Review" "6:Commit" "7:Report"; do
+bash $HOME/.claude/scripts/phase-tracker.sh add 0 "Init"
+bash $HOME/.claude/scripts/phase-tracker.sh tiles
+bash $HOME/.claude/scripts/phase-tracker.sh update 0 in_progress
+
+# Phase 0 Step 7.5, immediately after the depth answer - the first moment this
+# mode knows its phase set. Full:
+for p in "1:Analysis" "2:Planning" "3:Dev" "4:Review" "6:Commit" "7:Report"; do
   bash $HOME/.claude/scripts/phase-tracker.sh add "${p%%:*}" "${p#*:}"
 done
-bash $HOME/.claude/scripts/phase-tracker.sh update 0 in_progress
+# Short (Analysis and Planning are not run, so they get no tile at all):
+for p in "3:Dev" "4:Review" "6:Commit" "7:Report"; do
+  bash $HOME/.claude/scripts/phase-tracker.sh add "${p%%:*}" "${p#*:}"
+done
+# Then the widget, narrowed to the phases that do not have a tile yet:
+bash $HOME/.claude/scripts/phase-tracker.sh tiles --new
 
 # Every phase boundary (every CLI):
 bash $HOME/.claude/scripts/phase-tracker.sh update <N> in_progress|completed|failed|skipped
@@ -83,11 +94,11 @@ bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out> [cached]
 
 In Claude Code the agent MUST also drive the native TaskList widget so the user sees a sticky phase tile stack  -  this is the only progress signal Claude Code surfaces. Skipping these calls is the #1 source of "I don't see any phases" complaints.
 
-**TaskCreate ordering (strict)**: All TaskCreate calls 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, 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)".
+**TaskCreate ordering (strict)**: All TaskCreate calls in a registration batch fire in strict phase-number order BEFORE any TaskUpdate in that batch, and a later batch only ever appends phases numbered above everything already registered. This mode registers in two batches (Step -1, then Step 7.5), so `tiles --new` narrows the second one and the Phase 0 tile is never created twice. 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, 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)".
 
 ```text
-# Phase 0 startup  -  register one tile per phase (0..N), capture the taskId, persist it:
-for each phase in 0:Init, 1:Analysis, 2:Planning, 3:Dev, 4:Review, 6:Commit, 7:Report:
+# Register one tile per phase, capture the taskId, persist it:
+for each phase in 0:Init at Step -1, then 1:Analysis, 2:Planning, 3:Dev, 4:Review, 6:Commit, 7:Report (Full) or 3:Dev, 4:Review, 6:Commit, 7:Report (Short) at Step 7.5:
   TaskCreate({ subject: "Phase <N>: <Name>", activeForm: "<doing-form>" })
     -> returns taskId
   bash $HOME/.claude/scripts/phase-tracker.sh meta <N> tasklist_id "<taskId>"
@@ -108,7 +119,7 @@ bash $HOME/.claude/scripts/phase-tracker.sh update <N> completed
 
 #### TaskCreate ordering (strict)
 
-**All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is applied.** For `--local` that means: Phase 0 → Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 6 → Phase 7. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks. Full ordering contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
+**All TaskCreate calls in a batch fire in strict phase-number order BEFORE any TaskUpdate is applied.** For `--local` that means: Phase 0 at Step -1, then the rest in ascending order at Step 7.5 (Phase 0 → Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 6 → Phase 7 minus whatever the depth answer drops). The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks. Full ordering contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
 
 ### Visual channel  -  Copilot CLI / plain shell
 

package/pipeline/commands/multi-agent/local-autopilot/SKILL.md

@@ -104,10 +104,10 @@ bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out> [cached]
 
 In Claude Code the agent MUST also drive the native TaskList widget so the user sees a sticky phase tile stack  -  this is the only progress signal Claude Code surfaces. Skipping these calls is the #1 source of "I don't see any phases" complaints.
 
-**TaskCreate ordering (strict)**: All TaskCreate calls 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, 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)".
+**TaskCreate ordering (strict)**: All TaskCreate calls in a registration batch fire in strict phase-number order BEFORE any TaskUpdate in that batch, and a later batch only ever appends phases numbered above everything already registered. 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, 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)".
 
 ```text
-# Phase 0 startup  -  register one tile per phase (0..N), capture the taskId, persist it:
+# Register one tile per phase, capture the taskId, persist it:
 for each phase in 0:Init, 1:Analysis, 2:Planning, 3:Dev, 4:Review, 6:Commit, 7:Report:
   TaskCreate({ subject: "Phase <N>: <Name>", activeForm: "<doing-form>" })
     -> returns taskId
@@ -129,7 +129,7 @@ bash $HOME/.claude/scripts/phase-tracker.sh update <N> completed
 
 #### TaskCreate ordering (strict)
 
-**All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is applied.** For `--local autopilot` that means: Phase 0 → Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 6 → Phase 7. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks. Full ordering contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
+**All TaskCreate calls in a batch fire in strict phase-number order BEFORE any TaskUpdate is applied.** For `--local autopilot` that means: Phase 0 → Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 6 → Phase 7. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks. Full ordering contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
 
 ### Visual channel  -  Copilot CLI / plain shell
 

package/pipeline/lib/multi-repo-pipeline.sh

@@ -292,6 +292,12 @@ agent_state = {
     "worktreePath":  os.path.join(worktree_root, primary["name"]),
     "branch":        state["branch"],
     "baseBranch":    state.get("baseBranch", "develop"),
+    "baseBranchSource": state.get("baseBranchSource", "asked"),
+    # The multi-repo bridge always builds worktrees - that is what it is for -
+    # so the workspace was never in question here. It is recorded anyway,
+    # because phase0-exit-gate.mjs refuses to close Phase 0 on a state file
+    # that cannot say who decided.
+    "workspaceSource": state.get("workspaceSource", "command"),
     "remoteType":    primary.get("provider", "github"),
     "currentPhase":  0,
     "status":        "in_progress",
@@ -308,6 +314,26 @@ related = issue.get("relatedIssues") or []
 if isinstance(related, list) and related:
     agent_state["relatedIssues"] = related
 
+# Always written, `[]` included: the empty array is the record that the
+# dev-context step ran, and phase0-exit-gate.mjs refuses to close Phase 0
+# without it. Only repos this run will NOT modify belong here - the extras that
+# get a worktree are already in projects[].
+STACKS = {"ios", "android", "node", "python", "go"}
+worktreed = {r.get("name") for r in all_repos}
+siblings = []
+for r in (state.get("readonlySiblings") or []) + extras:
+    name = r.get("name")
+    if not name or name in worktreed:
+        continue
+    stack = r.get("stack", "unknown")
+    siblings.append({
+        "name":    name,
+        "root":    r.get("localPath") or None,
+        "stack":   stack if stack in STACKS else "unknown",
+        "canPush": bool(r.get("canPush", False)),
+    })
+agent_state["siblings"] = siblings
+
 logs_dir = os.path.expanduser(os.path.join("~/.claude/logs/multi-agent", primary["name"], state["taskId"]))
 os.makedirs(logs_dir, exist_ok=True)
 out_path = os.path.join(logs_dir, "agent-state.json")

package/pipeline/multi-agent-refs/features/base-branch-evidence.md

@@ -0,0 +1,222 @@
+# Feature: Base-Branch Evidence
+
+<!-- toc -->
+- [1. The fetch is a fact, not a formality](#1-the-fetch-is-a-fact-not-a-formality)
+- [2. Evidence sources](#2-evidence-sources)
+- [2b. A filter is not a ranking](#2b-a-filter-is-not-a-ranking)
+- [3. The convention is learned from the remote](#3-the-convention-is-learned-from-the-remote)
+- [4. The picker](#4-the-picker)
+- [5. Autopilot](#5-autopilot)
+- [6. State](#6-state)
+<!-- /toc -->
+
+**Pattern**: Phase 0 Step 3 used to ask one question with a list it could not
+vouch for. `git fetch origin` ran, its exit code was ignored, and `git branch -r`
+printed the remote-tracking cache either way - so on a restricted network a
+weeks-old local list was presented as the remote's answer, with nothing in the
+output saying so. And the answer was usually derivable: an issue that carries a
+target version, or that links a separate issue representing the release, already
+names the branch on a repo whose release branches encode the version. Nothing
+derived it.
+
+The shape here is **evidence collection, then a picker** - deliberately not a
+rule engine. Every candidate carries why it is a candidate; the ranking orders
+them; a human chooses. A rule engine would have to be right, and the inputs
+(field names, branch spellings, board conventions) differ per repo and change
+under it. An evidence list only has to be honest.
+
+Implemented by `$HOME/.claude/scripts/base-branch-candidates.mjs` (pure, no git,
+no network - it is handed ref lists and issue evidence). Gated by `prefs.global.baseBranchEvidence.enabled`
+(default `true`; off falls back to the rule-6 sort order, still through the picker). Asserted by `smoke-base-branch-evidence.sh`
+and `test/base-branch-candidates.test.mjs`.
+
+## 1. The fetch is a fact, not a formality
+
+```bash
+git -C "$PROJECT_ROOT" fetch origin; FETCH_RC=$?
+```
+
+`FETCH_RC` decides `refProvenance`, which is a required input to the collector
+and rides on every candidate as its own evidence row:
+
+| `FETCH_RC` | `refProvenance` | Ref list | What the user is told |
+|---|---|---|---|
+| 0 | `remote` | `git branch -r` | nothing extra; the list is current |
+| non-zero | `local` | `git branch -r` (cache) **and** `git branch` | the picker question itself says the fetch failed and these refs may be stale |
+
+A degraded list is still a list - falling back is correct, hiding it is not. The
+degraded picker gains a **Retry the fetch** row, and the fetch-fail picker
+already in Step 3 (Connect VPN / cached / local branch / abort) still owns the
+`baseFetchStatus` value. The two fit together: that picker records *what the run
+is working from*, this one records *what the candidate list is worth*.
+
+Local-only refs never silently become remote ones. `state.baseBranchEvidence.refProvenance`
+must be `local` whenever `baseFetchStatus` is `cached-stale` or `local-branch`,
+and `phase0-exit-gate.mjs` refuses to close Phase 0 otherwise. That assertion is
+the whole of problem 1: the run may degrade, it may not misreport.
+
+## 2. Evidence sources
+
+| Kind | Where it comes from | Weight |
+|---|---|---|
+| `issue-version` | a version-typed field on the issue whose value matches a branch on the ref list | 100 exact, 60 same major.minor, x0.6 for an affects-version field |
+| `linked-release` | a linked issue or parent whose own fix-version or summary names a version that matches a branch | 90 exact (110 when `baseBranchEvidence.preferLinkedRelease`) |
+| `version-convention` | the release-branch template inferred from the ref list | annotation only, no points |
+| `recent` | `prefs.global.recentBranches[{projectKey}]`, inside `settings.branchTtlDays` | 40 + up to 10 for recency |
+| `repo-default` | `origin/HEAD` | 20 |
+| `sort-order` | the develop / release / main families Step 3 always sorted by | 15 / 10 / 5 |
+| `ref-provenance` | the fetch outcome above | annotation only, on every candidate |
+
+### Field discovery, not a field table
+
+No field id is hardcoded, and none can be: a board's "target version" is a
+custom field whose id differs per Jira instance. What is stable is the *schema*.
+`GET /rest/api/2/field` returns `[{id, name, custom, schema: {type, items, custom}}]`,
+and any field whose schema resolves to `version` - directly, or as `array` with
+`items: "version"` - is read, whatever it is called. The two system fields
+(`fixVersions`, `versions`) are read unconditionally; an affects-version field
+is weighted lower than a fix-version one because it describes where the bug was
+seen, not where the fix lands.
+
+`GET /rest/api/2/issue/<key>?expand=names` returns the same display names inline
+and saves the second call when only labels are needed.
+
+### The linked release issue
+
+`fields.issuelinks[]` carries `{type: {inward, outward}, inwardIssue, outwardIssue}`
+and `fields.parent` carries the parent of a sub-task. On a board where opening a
+development sub-task requires selecting the related release issue, the link is
+the authoritative answer and the version field is the corroboration - so
+`prefs.global.baseBranchEvidence.preferLinkedRelease` (default `false`) raises the
+linked-release weight above the version-field one rather than adding a second rule. A linked issue counts as
+a release issue when a version can be read out of its own fix-version field or
+its summary; the issue *type name* is not consulted, because type names are
+per-board copy.
+
+GitHub's analogue is the milestone title, read the same way.
+
+## 2b. A filter is not a ranking
+
+Step 3's rule-5 list used to be narrowed with `grep -E '(develop|release|main|master)'`,
+which is the prefix table this whole feature exists not to have - and worse than a
+table, because it DISCARDS. A repo whose release branches read `stabilise-2.7`
+matched none of the four words, so none of its branches reached the picker, the
+convention-learner had nothing to learn from, and the version on the issue could
+never match anything. The feature would have been inert on exactly the repos it
+was written for.
+
+The rule is the distinction: **a word list that ranks is fine, a word list that
+filters is not.** Ranking only reorders rows the user can still see past; filtering
+removes answers with nothing saying so. So the four family words stay where they
+belong - rule 6's sort and this collector's 15/10/5 `sort-order` weights - and the
+filter gained a version alternative that admits any branch carrying a version
+token, whatever it is called.
+
+The excluded prefixes (`feature/`, `bugfix/`, `fix/`, `hotfix/`, `chore/`) are a
+different thing again: those are the task branches **this pipeline creates itself**,
+in Step 4. Excluding your own output is not a convention assumption.
+
+## 3. The convention is learned from the remote
+
+A table of branch prefixes would be wrong for most repos the day it was written.
+So the template is inferred from the refs that exist: every branch carrying a
+version token is reduced to its shape by replacing the token with `<version>`,
+and the most common shape is this repo's convention. A repo whose release
+branches read `<prefix>/develop_<version>` produces that template; a repo that
+spells them `release-<version>` produces that one; a repo with no versioned
+branches produces `null` and the whole source goes quiet.
+
+The inference is reported with its member count (`learned from 4 branch(es)`),
+because an inference from one branch and an inference from a dozen are different
+claims and the picker row should not flatten them.
+
+**A predicted branch is never offered.** When the learned template predicts a
+name that is not on the ref list, that is a note, not an option:
+
+```
+version 1.51.0 (field "Target Version") has no branch on the remote;
+the convention <prefix>/develop_<version> learned from 4 branch(es) would spell it
+<prefix>/develop_1.51.0
+```
+
+That sentence is more useful than a candidate would be - it tells the user the
+release branch has not been cut yet, which is a real answer to "which base?" -
+and an option the user picks has to be checkoutable. Offering a name that does
+not exist just moves the failure to Step 8, where it reads as a git error.
+
+## 4. The picker
+
+`toPickerOptions()` builds the rows, and the **evidence is the description**. A
+row reading `matches version 1.51.0 from the issue field "Target Version"` and a
+row reading `the repository's default branch` are different answers to the same
+question; a picker that hides which one it is cannot be chosen on its merits.
+
+The two-option floor is enforced inside that function rather than left to the
+caller: it never returns fewer than two rows, because `AskUserQuestion` refuses a
+question with fewer than two declared options *and discards every question
+batched with it*, and the host's injected Other row does not count toward the
+schema minimum. The escape row (`Show all branches`) is a genuine second choice,
+not an `OK` button - see picker-contract.md, "Two options or it is not a
+question".
+
+**Interactive runs always ask.** A derived candidate is a better-ordered list,
+never a skipped question. `baseBranchSource` stays `asked`, because a human
+answered; the derivation is recorded separately in `state.baseBranchEvidence` so
+it stays readable afterwards.
+
+## 5. Autopilot
+
+Autopilot cannot be asked anything, so it resolves in this order and records
+which rule fired in `baseBranchSource`:
+
+1. `remembered` - `recentBranches` inside the TTL and still on the ref list (memory outranks the default, per the picker contract).
+2. `derived` - the top candidate carries `issue-version` or `linked-release` evidence **and** no other candidate ties its score. Ambiguity is not resolved by coin-flip.
+3. `default` - the sort order.
+
+`derived` is an autopilot-only value, exactly like `remembered` and `default`;
+an interactive run recording it has skipped its picker, and the exit gate fails
+it. The gate additionally refuses `derived` unless `state.baseBranchEvidence`
+actually contains issue-derived evidence for the chosen branch - a `derived` that
+derived from nothing is `default` wearing a hat.
+
+### Asking on the issue (`prefs.global.baseBranchEvidence.autopilotAsksOnIssue`, default OFF)
+
+When the derivation is **ambiguous** and nothing is remembered, autopilot can
+post one comment on the Jira issue or GitHub issue asking which branch to
+develop from, then halt.
+
+This is an outward-facing write, so it is fenced:
+
+- **Off by default.** Nothing posts unless the user turned it on for this project.
+- **A question, never a state change.** No transition, no resolution, no assignee change, no label change, no close - ever. The standing rule that the pipeline never auto-closes an issue is not relaxed by this feature, and a comment is the only write it is allowed to make.
+- **Human-facing copy follows `outputLanguage`**, like every other comment the pipeline writes.
+- **`Ref:`, never `Closes:`/`Fixes:`/`Resolves:`** in the body, so no platform-side automation reads it as an instruction.
+- **It renders the same evidence the picker would have shown**, candidate by candidate, so the person answering sees what the run saw.
+- **Then the run halts.** Posting a question and continuing on a guess is worse than not asking: the guess lands in a branch while the question sits unanswered. So the comment trips the circuit breaker (trigger 6), which is the sanctioned autopilot pause - state recorded, one actionable line printed, waiting for an explicit `resume`. Phase 0 does not close and no worktree is created.
+
+The nearest-safe reading of "post a comment asking which branch" is therefore:
+ask once, change nothing, stop. An autopilot that posts a question and then
+answers it itself has not asked anything.
+
+## 6. State
+
+```jsonc
+"baseBranchSource": "asked" | "input" | "remembered" | "default" | "derived",
+"baseBranchEvidence": {
+  "refProvenance": "remote" | "local",   // required whenever this object exists
+  "chosen": "<branch>",
+  "ambiguous": false,
+  "convention": { "template": "<prefix>/develop_<version>", "members": 4 },
+  "candidates": [
+    { "branch": "<branch>", "score": 115,
+      "evidence": [{ "kind": "issue-version", "detail": "..." }] }
+  ],
+  "notes": ["..."],
+  "askedOnIssue": { "target": "PROJ-1234", "url": "...", "at": "..." }
+}
+```
+
+`baseBranchEvidence` is required when `baseBranchSource` is `derived`, and when
+`baseFetchStatus` is `cached-stale` or `local-branch`. Everywhere else it is
+optional: a run that took the base from the task reference has no evidence to
+record and should not be made to invent some.

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/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                                                          |