@mmerterden/multi-agent-pipeline 16.28.0 → 16.30.0

package/pipeline/multi-agent-refs/features/doctor.md

@@ -0,0 +1,197 @@
+# doctor - the check registry
+
+Every check `/multi-agent:doctor` can report has a `### <id>` heading here, and
+`doctor.mjs --list-checks` prints exactly the same set. The equality is checked
+in both directions by `smoke-doctor.sh`: a check that ships without an entry
+cannot be released, and an entry whose check was deleted cannot linger as orphan
+prose. That is the mechanism that keeps this file from rotting into a list of
+things the tool used to do.
+
+## What the exit code means
+
+| Code | Meaning |
+|---|---|
+| 0 | healthy - nothing above INFO |
+| 1 | degraded - at least one WARN, no BLOCK |
+| 2 | blocked - at least one BLOCK |
+| 3 | usage error |
+| 4 | indeterminate - the installed layout could not be resolved, so nothing was checked |
+
+4 exists so that "I could not look" never borrows the exit code of "I looked and
+it is fine". A consumer that treats 0 as healthy would otherwise read a broken
+resolver as a clean bill.
+
+## What BLOCK means, exactly
+
+**A state in which a run will fail or leak. Not a state in which it will merely
+be worse.** Without a closed definition "blocked" grows until nobody respects
+exit 2, so only five checks can produce it: `install-present`, `script-surface`,
+`state-writable`, `prefs-valid` and `embedded-credentials`. Every other check
+tops out at WARN however bad it looks.
+
+## Who calls it, and what they do with the code
+
+| Caller | When | On exit 2 |
+|---|---|---|
+| `/multi-agent:setup` | before the first question, and again at the end | the closing run is the evidence for or against "setup complete" |
+| `/multi-agent:update` | after the install | report that the update left a state a run will fail from, rather than "updated" |
+| `/multi-agent:sync` | step 0 | **stop.** Syncing a blocked install copies one fault onto five surfaces, and the copies are what people then debug |
+
+`/multi-agent:sync` stops on exit 4 as well: the layout did not resolve, so
+nothing was checked, and syncing from an unknown state is worse than not syncing
+at all. Exit 1 never stops anything - a degraded install still syncs correctly,
+and a gate that blocked on every warning would be routed around within a week.
+
+## The four severities
+
+| Severity | Meaning |
+|---|---|
+| BLOCK | a run will fail or leak |
+| WARN | a run will work and be worse: a degraded capability, a stale copy, a rejected credential |
+| INFO | a capability the user chose not to enable; nothing to fix |
+| SKIP | not checked, and why |
+
+`SKIP` is printed in the same list, in the same position, and the summary always
+carries its count (`... 2 not checked, 15 checks`). Absence is a finding: a run
+without `--probe` exits 0 **and** prints `SKIP credential-liveness`, so "healthy"
+and "not looked at" are never the same output.
+
+The INFO / WARN boundary is already decided in `lib/credential-inventory.sh` and
+this tool only renders it: an unmapped key is INFO because it is a capability the
+user chose not to enable, while `auth-rejected`, `malformed` and
+`tier-1-no-grant` are WARN because the configuration made a claim the service
+refused. **A missing optional capability is information; a mapped credential the
+service rejected is a warning. The difference is whether the configuration
+asserted anything.**
+
+## The line shape
+
+```
+<SEV> <id>  -  <what is wrong>  -  <single imperative step>
+```
+
+The third field is one step, and its first word comes from a closed list:
+`run`, `set`, `map`, `revoke`, `install`, `remove`, `free`, `export`, `merge`,
+`record`, `re-run`. `consider`, `may want` and `should probably` are refused by
+the gate. One problem, one step: a reader with five suggestions does nothing.
+
+## It recommends, it never fixes
+
+Nothing here rewrites a remote URL, edits `settings.json` or touches a token.
+A remote whose URL carries a token may be the only credential that repo has, the
+remote may be a mirror a script depends on verbatim, and doctor can run inside a
+checkout the user does not own. Silent repair breaks all three.
+
+For an embedded credential the honest single step is **not** "hide it". A token
+that reached `.git/config` is already burned: it is in the shell history and
+readable by anything that can read the working tree. The step is to revoke it at
+its host; everything after that is behind `--explain`.
+
+---
+
+## Checks
+
+### install-present
+
+The installed tree exists and carries the subtrees a run reads: `commands/`,
+`multi-agent-refs/`, `scripts/`, `lib/`, `schemas/`. BLOCK when any is missing -
+a run cannot start without them.
+
+### install-version
+
+The installed `.pipeline-version` matches the package version resolved from the
+checkout or the published package. WARN on a mismatch: the run works, it just
+is not the version the user thinks they have.
+
+### script-surface
+
+Every script a shipped command names by path exists in the installed tree. BLOCK:
+the failure lands mid-run, at the call, with the phase already half done.
+
+### skill-siblings
+
+Every command has its copies in the host trees this machine installs. WARN, never
+BLOCK: an unsynced host is a fact about the machine, and `skill-siblings.mjs`
+itself reports the installed layout as "authored side not checked" rather than
+claiming a repo verdict it cannot reach.
+
+### state-writable
+
+`$HOME/.claude/logs/multi-agent` exists or can be created, and a file can be
+written there. BLOCK: a run that cannot record its state cannot be resumed,
+reported or priced, and it discovers this at Phase 0 after the pickers.
+
+### prefs-valid
+
+`multi-agent-preferences.json` parses and satisfies `schemas/prefs.schema.json`.
+BLOCK: Phase 0 reads it before anything else, and a malformed file fails the run
+after the user has already answered the pickers.
+
+### identity
+
+A git identity resolves for the account the run would commit as. WARN: the run
+reaches Phase 6 and stops there.
+
+### hook-coverage
+
+The blocking `PreToolUse` gates from `templates/claude-hooks.json` are present in
+`settings.json`. WARN. SKIP when the template is not installed - which was the
+permanent state until the installer began copying `templates/`, and is exactly
+the case this severity exists to make visible.
+
+### credential-mapping
+
+Which logical keys are mapped, and whether each mapped value is well formed.
+Unmapped is INFO. Malformed is WARN.
+
+### credential-liveness
+
+One cheap authenticated request per mapped credential. WARN on `auth-rejected`,
+`tier-1-no-grant` or `unreachable` - but with **different steps**, because a
+refused credential and a host that never answered need different actions.
+`credential-inventory.sh` already draws that line ("unreachable - no response at
+all - on a corporate host, almost always the VPN"), and telling someone to
+re-onboard a token that was never the problem is the exact failure the keychain
+rules warn about one layer up. **SKIP unless `--probe` is passed**, and the
+skip is printed, because a network check is the user's decision to spend.
+
+### embedded-credentials
+
+A token in a git remote URL or a tracked config file. BLOCK: this one leaks
+rather than fails.
+
+The report carries the repo path, the config key, the **host**, a shape label and
+a length bucket. Never the value, and not the prefix either: `ghp_` plus a length
+is already a fingerprint, and this line is printed to a terminal that is often
+shared, which is the whole reason the check exists. The URL is parsed inside a
+`python3` heredoc reading stdin, so no shell variable ever holds it.
+
+### task-tools
+
+Whether this session's model carries `TaskCreate` / `TaskUpdate`. Claude Code
+provides them by default only on Claude 3.x, Opus 4 through 4.7, Sonnet 4 through
+4.6 and Haiku 4.5; on any newer model they are absent unless the user opts in.
+INFO, with the opt-in as the step.
+
+A script cannot answer this - only the agent knows its own tool list - so the
+caller passes `--task-tools=yes|no` and the default is SKIP. Reporting "absent"
+from a script that never looked would be the same defect this check is about.
+
+### mcp-registration
+
+Whether `multi-agent-toolkit` is registered as an MCP server. INFO when it is
+not: the tools it provides are optional and a run without them is smaller, not
+wrong.
+
+**Registered is not the same as working.** With `--probe` the server is started
+and its tools counted; serving none is WARN. Without `--probe` this reports what
+is configured, and says so. The distinction is not theoretical: a half-extracted
+package in the npx cache left the server dying on `Cannot find module` at
+startup, which the client surfaces only as `CONNECTION_CLOSED`, and a check that
+read the registration and stopped would have called that healthy.
+
+### disk-space
+
+Free space on the volume holding `$HOME`. WARN under 2 GB: a worktree plus a
+build is the largest thing a run writes, and ENOSPC mid-run corrupts the state
+file it was writing at the time.

package/pipeline/multi-agent-refs/features/model-fallback.md

@@ -83,7 +83,7 @@ predate this field still get the second downgrade step):
   "premiumTierUntil": null,
   "fallbackModel": "sonnet",
   "floorModel": "haiku",
-  "fableEnabled": true,
+  "fableEnabled": false,
   "onDispatchError": true
 }
 ```
@@ -91,7 +91,7 @@ predate this field still get the second downgrade step):
 | Field | Meaning |
 |---|---|
 | `enabled` | Master switch. `false` = always dispatch the persona's `preferredModel`, fail loudly on error. |
-| `modelFallback.fableEnabled` | Whether the `fable` rung exists at all on Claude Code. `false` starts every `preferredModel: fable` persona on `opus`. See "Turning the fable rung off" below. |
+| `modelFallback.fableEnabled` | Whether the `fable` rung exists at all on Claude Code. **Ships `false`.** `false` starts every `preferredModel: fable` persona on `opus`; set it to `true` to opt the top rung back in. A cost control that defaults to on is not a control. See "Turning the fable rung off" below. |
 | `premiumTierUntil` | ISO date (`YYYY-MM-DD`) or `null`. When set and today is **after** this date, every `preferredModel` dispatch is downgraded to `fallbackModel` unless the user re-confirms (see Date gate). Use when the top tier is included in a plan only until a known date. |
 | `fallbackModel` | Target of the first downgrade step. Default `sonnet` (the next tier below opus). |
 | `modelFallback.floorModel` | Last-resort tier when `fallbackModel` also fails to dispatch. Default `haiku`. Set to the same value as `fallbackModel` (or `null`) to disable the second step and halt after one downgrade. |

package/pipeline/multi-agent-refs/features/visual-evidence.md

@@ -78,32 +78,86 @@ at most 1242px wide, and writes
 A clean status bar is not cosmetic: without it two captures of the same screen
 differ by the clock, which makes every "after" look like a change.
 
-## 4. Video  -  three tiers, resolved once per repo
+## 4. Video  -  the recording rides on a test run
 
-The flow source, in order: a UI test flow written on the ticket wins; otherwise
-the Phase 5 test scenarios are the flow. Human-written beats generated, the same
-rule the "before" follows.
+The flow video is not recorded on its own. It wraps something that drives the
+screen, and what drives it is chosen by the user at intake, because running a UI
+suite costs minutes and that is their time to spend.
 
-The tier is probed once and stored in `state.visualEvidence.videoTier`:
+### 4.1 Probe first
 
-| Tier | Condition | Mechanism |
-|---|---|---|
-| 1 | The repo has a UI test target (XCUITest / Espresso) **and** it can be seeded with test data | Run that test, record the screen for its duration. Most faithful, and it is a test that already runs in CI |
-| 2 | A runnable build exists | Drive the flow with `mcp__multi-agent-toolkit__agent_run_steps` and record with `ios_record_video` / `android_record_screen`. **No test target needed** |
-| 3 | No runnable build (library / SPM package / backend) | Skip, with the reason recorded |
+`probe-evidence-capability.sh` measures, before the question is asked, what this
+machine and this repo can actually do: the UI test target, the tests matching
+this change, the device, the recorder CLI, and whether the toolkit MCP is
+registered. Detection is delegated to `run-ui-tests.sh detect`, which is also
+what runs the tests, so there is one implementation of the answer.
+
+Two rules the probe keeps, and the reason for each:
+
+- **Absence carries a reason.** `no booted simulator, but one is available to
+  boot` and `no iOS simulator available on this machine` close the same menu row
+  and ask the user for completely different things.
+- **Unmeasurable is `null`, never `false`.** With no `adb` on the PATH the probe
+  cannot see whether a device is attached; reporting that as "no device" is a
+  negative nobody looked for, and it reads exactly like one somebody checked.
 
-Tier 2 is why "can every repo do this" answers yes in practice: any app that can
-be launched can be driven. A repo without a UI test target loses fidelity, not
-the recording.
+### 4.2 Then the question
 
-Preferred host is **Phase 5** - the device is already up and a human is present
-to confirm the flow is the right one. In a mode without Phase 5, tier 2 runs at
-the end of Phase 3 instead. Tier 1 always runs where the test runs.
+Phase 0 Step 7.7 asks the depth, with the options built from the probe. A closed
+option stays on the list carrying its reason; when every option but the first is
+closed, nothing is asked and `testDepthSource` records `forced`. The full menu
+rules are in `phases/phase-0-init.md`.
 
-Duration is capped by `visualEvidence.maxVideoSeconds` (default 60), read via
-`capture-evidence.sh limits` so the number lives in one place rather than in two
-documents. A flow that needs longer is not a review artefact, it is a debugging
-session.
+### 4.3 Then the recording
+
+| `testDepth` | Tier | What drives the screen |
+|---|---|---|
+| `unit+ui` | 1 | The repo's own UI test, selected by the changed files. Most faithful, and it is a test that already runs in CI |
+| `unit+mcp` | 2 | `mcp__multi-agent-toolkit__agent_run_steps` drives the flow. No test target needed |
+| `unit` | 3 | Nothing. No recording, and the reason is the user's own answer |
+
+The recorder itself is `capture-evidence.sh video start|stop`, which writes
+`<task-id>[-<label>]-flow.mp4` into the evidence directory. The label is optional
+because one recording per task is the common case, and both renderers cite the
+unlabelled form. It is shell rather than MCP for three reasons: the sibling still capture already shells out,
+a host with no toolkit MCP registered still produces evidence, and Phase 3 and
+Phase 5 are exactly where an MCP call is contested.
+
+**iOS UI test targets are not named, they are detected.** A path containing
+`UITests` is not the signal: in the reference app 477 files sit under such a path
+and exactly 2 drive the UI, the rest being snapshot tests that render a view and
+compare pixels without ever launching the app. The signal is `XCUIApplication`,
+the only API that drives another process's interface, which is precisely the
+precondition a flow recording has. On Android the signal is the `androidTest`
+source set, which is instrumentation by definition.
+
+**A real app has many candidates** - 17 UI test directories on the reference iOS
+app, 8 instrumentation modules on the Android one. Detection reports the whole
+set and lets the changed files choose; taking the first off a `find` is a guess
+wearing a measurement's clothes.
+
+### 4.4 Re-check before recording
+
+The probe runs at intake and the recording happens in Phase 3. A simulator booted
+then can be gone by the time the build goes green, so Phase 3 re-measures the
+device row alone and downgrades the tier if it has to, recording the transition
+(`tier 1 -> 3: simulator no longer booted`). A tier taken from a stale
+measurement is a promise the run cannot keep.
+
+### 4.5 Duration, and the recording that shows nothing
+
+The cap is `visualEvidence.maxVideoSeconds` (default 60), read through
+`capture-evidence.sh limits` so one value serves the phase doc and the recorder.
+Android's `screenrecord` has its own ceiling of 180 seconds that no setting can
+lift, so the script clamps to it and says when it did: one preference honoured on
+one platform and silently halved on the other is worse than a stated limit.
+
+Both recorders encode on change. A flow over a screen that never moved therefore
+produces a valid two-frame mp4 a fraction of a second long - not a broken file,
+but not evidence of a flow either. `video stop` says so on stderr when the result
+is under a second, and the caller records that as a gap reason. The duration is
+never asserted against wall clock anywhere, because doing so fails a correct
+capture of a static screen.
 
 `visualEvidence.enabled` turns the whole feature off - capture, upload, both
 render sections and the Phase 6 blocker with it.
@@ -125,6 +179,35 @@ Order of attempts, each one recorded:
 
 Never silently attach nothing.
 
+## 5b. Where the artefacts live  -  the host
+
+Resolved in Phase 6 Step 2.9, recorded as `state.visualEvidence.host`:
+
+| Order | Host | Condition | Stills | Video |
+|---|---|---|---|---|
+| 1 | `jira` | `jiraId` present | Jira attachments | Jira attachment |
+| 2 | `github-public` | no Jira, GitHub remote, public repo | `evidence/<task-id>` orphan branch, embedded in the PR body | none |
+| 3 | `github-private` | no Jira, GitHub remote, private repo | same branch, blob permalink in the PR body | none |
+| 4 | `none` | anything else, or `githubHost: off` | not published, gap recorded | none |
+
+**GitHub cannot be given a file.** There is no API that attaches an image to an
+issue or a pull request; the web uploader posts to an endpoint that needs a
+browser session, so no token can drive it. The PR body can only point at
+something already hosted, and an orphan branch is the one mechanism a script has
+that neither touches the PR diff nor publishes a release.
+
+**A private repo cannot show an inline image.** GitHub renders markdown images
+through its own proxy, which carries no credentials for a private repo, so an
+embedded `raw.githubusercontent.com` URL renders broken for every reader
+including the author. That is worse than a link, because a broken image looks
+like missing evidence. The private variant therefore links rather than embeds.
+
+**Video is Jira-only, by decision.** On a GitHub-hosted run none is recorded at
+all. An mp4 behind a blob link is a download rather than something a reviewer
+opens mid-review, and paying minutes of UI-test time for a recording nobody
+watches is worse than saying plainly that there is none. The gap line carries
+that reason.
+
 ## 6. Rendering
 
 ### Jira comment (`channels/jira.md`)

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

@@ -275,11 +275,8 @@ Scan `$HOME` (maxdepth 2) for project markers (`.xcodeproj`, `Package.swift`, `b
      | grep -v -E '(feature/|bugfix/|fix/|hotfix/|chore/)'
    ```
 6. Sort: `develop*` first, then `release/*`, then `main`/`master`. Surface through the
-   **native picker** per `picker-contract.md` (`AskUserQuestion` on Claude Code,
-   `ask-choice.sh` on Copilot CLI) - `question` + `description` in `outputLanguage`,
-   `label` = the branch name verbatim (a proper noun, never translated) with the recent
-   branch first and marked `(Recommended)`. The ASCII sketch
-   below is what the options carry, not a menu to print:
+   **native picker** per `picker-contract.md`, recent branch first and marked
+   `(Recommended)`:
 
    ```
    header: "Base branch"
@@ -298,9 +295,14 @@ 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.
 
+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".
+
 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 to their defaults without prompting,
-which still writes the fields - it does not leave them unset.
+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`.
 
 **TTL filter for recent branches**:
 
@@ -587,6 +589,35 @@ Persist `state.baseline.tests` with `command`, `capturedAt`, `logPath` and exact
 
 Log: `Phase 0 Step 7.6: test baseline = {green|red|unknown} ({N} pre-existing failures)`
 
+#### Step 7.7  -  Evidence capability, then test depth
+
+Probe, then ask, then run. Skipped unless `state.visualEvidence.required` and `visualEvidence.enabled` is not `false`. Reasoning: `features/visual-evidence.md` section 4.
+
+```bash
+eval "$(bash $HOME/.claude/scripts/probe-evidence-capability.sh \
+  --platform "$PLATFORM" --repo "$WORKTREE" --changed "$CHANGED_CSV" \
+  --json-out "$WORKTREE/.pipeline/evidence-capability.json")"
+```
+
+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).
+
+A closed option keeps its row and prints the probe's reason verbatim. No `uiTestTargets` closes 2; `mcp` false closes 3; a missing `device` or `recorder` closes both. Targets present with no `matchingTests` leaves 2 open, warning that the whole UI suite will run. **When only option 1 is open, do not ask**: `testDepth = unit`, `testDepthSource = forced`, and the tier 3 gap is written.
+
+Pass the default as the **1-based index**, never the label (`rules.md`: labels render in `outputLanguage`, so a label default matches nothing on a `tr` run and `ask-choice.sh` takes option 1 on a non-TTY):
+
+```bash
+DEPTH_DEFAULT_INDEX=1
+[ "$EVIDENCE_TIER1" = "open" ] && [ -n "$EVIDENCE_MATCHING_TESTS" ] && DEPTH_DEFAULT_INDEX=2
+[ "$DEPTH_DEFAULT_INDEX" = "1" ] && [ "$EVIDENCE_TIER2" = "open" ] && DEPTH_DEFAULT_INDEX=3
+ASK_CHOICE_DEFAULT="$DEPTH_DEFAULT_INDEX" $HOME/.claude/lib/ask-choice.sh ...
+```
+
+Asked by `/multi-agent` and `:local`; autopilot reads `prefs.global.testDepth.default` and degrades to the best open option. Asked here, not Phase 5, which four of the eight modes drop.
+
+Log: `Phase 0 Step 7.7: testDepth = {unit|unit+ui|unit+mcp} (source {user|autopilot|default|forced}), tier1/tier2 = {open|closed}`
+
 #### Step 8  -  Clarification (opt-in, runs AFTER maturity, BEFORE Phase 1)
 
 **Gated by `prefs.global.clarifyAmbiguous.enabled`** (default: `false`). When enabled and `state.maturity.status != "blocker"`:

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

@@ -236,7 +236,19 @@ Gated by `prefs.global.devCritic.enabled` (default: `false`). When enabled, afte
 
 #### Step 3.55  -  Visual evidence capture (UI changes only)
 
-When `state.visualEvidence.required`, capture the fixed state with the build that just went green: `capture-evidence.sh after --task "$TASK_ID" --platform "$PLATFORM" --label <slug>`. Here, not Phase 5, which every autopilot and `--local` entry drops. Exit 4 is a gap, not a failure. See `$HOME/.claude/multi-agent-refs/features/visual-evidence.md`.
+When `state.visualEvidence.required`, capture with the build that just went green. Here, not Phase 5, which every autopilot and `--local` entry drops. Exit 4 anywhere below is a gap, not a failure. Contract: `features/visual-evidence.md`.
+
+1. **Still**: `$HOME/.claude/scripts/capture-evidence.sh after --task "$TASK_ID" --platform "$PLATFORM" --label <slug>`.
+2. **Re-check the device.** `evidenceCapability` was measured at intake; a simulator booted then can be gone now. Re-measure the one volatile row with `$HOME/.claude/scripts/probe-evidence-capability.sh --platform "$PLATFORM" --repo "$WORKTREE" --only device`, which skips the repo scan the full probe does; gone means fall to the next open tier and write `visualEvidence.videoTierReason` as the transition (`tier 1 -> 3: simulator no longer booted`).
+3. **Recording**, by `state.testDepth`:
+   - `unit+ui`: `video start` -> `$HOME/.claude/scripts/run-ui-tests.sh run --platform "$PLATFORM" --repo "$WORKTREE" --changed "$CHANGED_CSV"` -> `video stop`. Runner exit 3 (no matching test) or 4 (no target) -> stop, discard, fall to tier 2. Exit 1 is a red UI test: keep the recording, it shows the failure.
+   - `unit+mcp`: `video start` -> drive with `mcp__multi-agent-toolkit__agent_run_steps` -> `video stop`. The only MCP-dependent path; MCP absent -> tier 3 gap.
+   - `unit`: no recording; the gap reason is the user's own answer.
+4. **Fit**: `$HOME/.claude/scripts/capture-evidence.sh fit --file <path>` per artefact. Quality degrades, the artefact is never dropped.
+
+`video stop` warns when the recording is under a second: both recorders encode on change, so a screen that never moved yields a valid two-frame file. Keep it, record the warning as a gap reason, never present a still as a flow.
+
+Persist `state.uiTest` and the artefact entries. A UI test that ran is subject to the default-FAIL rule like the build: run `evidence-gate.mjs --claim test --status passed --evidence "$WORKTREE/.pipeline/ui-test.log"` first, because a runner that died before reaching the tests also exits non-zero.
 
 #### Step 3.6  -  Code-simplifier pass (required diff shrink, before Phase 4 handoff)
 

package/pipeline/multi-agent-refs/phases/phase-5-test.md

@@ -112,6 +112,8 @@ Tier 1 / Tier 2 records print `screenshotUrl` from the captured evidence (Tier 2
    ```bash
    node $HOME/.claude/scripts/evidence-gate.mjs --claim manual --status passed --evidence "$WORKTREE/.pipeline/manual-test.json"
    ```
+   Add `--require-screenshot` when `state.visualEvidence.required` is true: a passing criterion then has to name a file that exists, because a `screenshot` key pointing nowhere is not evidence.
+
    Exit 1 means the "ok" is not accepted: tell the user which criterion is missing evidence (a `fail` verdict, or `not-tested` without a reason) and wait for the next reply. Exit 0 marks Phase 5 completed with `Result "local test passed (user)"`. The "fix: ..." path below is unchanged.
 6. If fix needed:
    - Branch already has WIP commit (from step 2)  -  changes are safe
@@ -138,7 +140,7 @@ Before or during user testing, run device-level audits via Bash if user requests
 
 | Check               | When              | Command                                   |
 | ------------------- | ----------------- | ----------------------------------------- |
-| UI flow video       | `state.visualEvidence.required` | 3 tiers, cap from `capture-evidence.sh limits` (`visualEvidence.maxVideoSeconds`)  -  `$HOME/.claude/multi-agent-refs/features/visual-evidence.md` |
+| UI flow video       | `state.visualEvidence.required` AND Phase 3 recorded none | `capture-evidence.sh video start` -> drive the flow -> `video stop` -> `fit`. See below |
 | Accessibility audit | UI changes        | `mcp__multi-agent-toolkit__{ios,android}_accessibility_audit` |
 | Biometric test      | Auth flow changes | ios: `mcp__multi-agent-toolkit__ios_biometric` (android: manual) |
 | Launch time         | Perf-sensitive changes | ios: app-launch instrument · android: `mcp__multi-agent-toolkit__android_launch_time` |
@@ -146,6 +148,14 @@ Before or during user testing, run device-level audits via Bash if user requests
 | Snapshot regression | Component / pixel-stable UI changes | ios: `mcp__multi-agent-toolkit__ios_visual_diff` · android: `mcp__multi-agent-toolkit__android_screenshot` + compare |
 | Store screenshots   | `taskType === screenshot` | ios: `ios_status_bar({preset: "clean"})` · android: `android_screenshot` |
 
+##### UI flow video, when Phase 3 produced none
+
+Phase 3 Step 3.55 is the primary host and runs in every mode. Phase 5 is the richer one where it exists: the device is up and a person is watching, so the flow is one somebody confirmed. It adds, never replaces.
+
+Run only when `visualEvidence.required` and `visualEvidence.video.file` is empty: re-check the device with `$HOME/.claude/scripts/probe-evidence-capability.sh --only device`, then `$HOME/.claude/scripts/capture-evidence.sh video start` -> drive the flow (`run-ui-tests.sh run`, or the Phase 5 scenarios by hand) -> `video stop` -> `fit`. The cap is `visualEvidence.maxVideoSeconds`, read through `capture-evidence.sh limits` so one value serves both. Update `videoTier` and `videoTierReason` with what ran.
+
+When the intake answer was `unit` there is no recording here either: overriding it in a phase the user may not be watching makes the question decorative.
+
 Results included in Phase 7 report. MCP tools preferred when available  -  concise structured output, lower token cost.
 
 **Snapshot regression flow (optional):** when the task changes a stable component, capture a screenshot before the change (baseline) and after (current), then call `ios_visual_diff({baseline, current, max_diff_pct: 1.0})`. Threshold can be relaxed for animated / non-deterministic regions  -  keep `max_diff_pct ≤ 1.0` for static layouts.

package/pipeline/multi-agent-refs/phases/phase-6-commit.md

@@ -130,6 +130,29 @@ Branch **deterministically**, no implicit fallback. Read `agent-state.json` and
 11. **NEVER close or resolve the issue**  -  neither GitHub Issue nor Jira. Issues require team review (4 approvals) before closing. Only post a comment with commit/PR URLs.
 12. Log: "Phase 6: Commit {sha}  -  PR #{number}, worktree {removed|kept: <reason>}"
 
+#### Step 2.9  -  Resolve the evidence host (UI changes only)
+
+Runs when `state.visualEvidence.required`, before the PR body is written, because the body renders a different shape per host. Record `state.visualEvidence.host` and `hostReason`:
+
+1. **`jira`** - `state.jiraId` present. Upload stills and video with `jira-attach.sh "$JIRA_ID" <files>`; it prints `<filename>\t<url>` per file into `before[]` / `after[]` / `video`.
+2. **`github-public` / `github-private`** - no Jira, `visualEvidence.githubHost` is `branch`, remote is GitHub. Push the stills to the orphan branch below, then pick the variant from `gh repo view --json isPrivate`.
+3. **`none`** - anything else, including `githubHost: off`. Publish nothing, record the reason, let the `gaps[]` rule carry it.
+
+No API attaches a file to a GitHub issue or PR (the web uploader needs a browser session), so the PR body can only point at something already hosted. An orphan branch is the one mechanism a script has that neither touches the PR diff nor publishes a release.
+
+```bash
+EVB="evidence/$TASK_ID"
+git -C "$WORKTREE" worktree add --detach "$TMP_EV" 2>/dev/null
+git -C "$TMP_EV" checkout --orphan "$EVB" && git -C "$TMP_EV" rm -rf . >/dev/null 2>&1 || true
+cp "$WORKTREE"/.pipeline/evidence/*.png "$TMP_EV"/ 2>/dev/null || true
+git -C "$TMP_EV" add -A && git -C "$TMP_EV" commit -m "evidence: $TASK_ID"
+git -C "$TMP_EV" push -u origin "$EVB"
+```
+
+Stills only. On a GitHub-hosted run no video is recorded (Step 3.55), and an mp4 behind a blob link is a download rather than something a reviewer opens. A failed push is not a phase failure: drop to `host: none` with the error as `hostReason`.
+
+Log: `Phase 6 Step 2.9: evidence host = {jira|github-public|github-private|none} ({reason})`
+
 #### Step 3  -  PR Description (technical detail for reviewers)
 
 **Section set + markup dialect: `channels/pr.md`  -  read it first.** Phase 7 channels replaces this body with that section set, so build to it. Required reading: `payload-contracts.md`.

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

@@ -75,10 +75,45 @@ identifies which option, not what the button said.
 The host injects its own **Other** free-text row in English on every run. Nothing in
 the pipeline can localize it, and no option may depend on its wording.
 
+## Order: project, then repo, then branch
+
+A picker may only be asked once everything it depends on is settled, and the
+dependency runs one way: a base branch is a property of a repo, and a repo is a
+property of a project. Asking for a branch before the dev-context repo set is
+known means the answer was given about a repo the run had not chosen yet, and
+nothing downstream can tell that apart from a correct answer.
+
+So: project selection, then `_dev-context.md`, then the base branch. A step whose
+input is not yet resolved waits; it does not guess and it does not resolve its own
+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.
+
+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.
+
 ## 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.
 
+**Memory outranks the default.** Where the pipeline has recorded what this user chose
+last time for this project - `prefs.global.recentBranches[{projectKey}]` is the one that
+exists today - autopilot resolves from that record first, and only falls back to the
+option order when the record is empty, stale past its TTL, or names something that no
+longer exists. A remembered choice is evidence about this user and this repo; an option
+order is a guess that happens to be sorted. Where the two agree nothing changes, and
+where they disagree the remembered one is the answer with a reason behind it.
+
+The run records which rule fired (`remembered` or `default`). An autopilot run cannot be
+asked anything, so the only thing that keeps it accountable is being readable afterwards.
+
 ## Deterministic gates note
 
 Claude Code's `PreToolUse` exit-2 hooks are the HARD blocking gates. Three ship, none needing run-specific arguments so they are naturally hookable: (1) `pre-commit-check.sh` scans the staged diff on every `git commit` and blocks on a detected secret; (2) `agent-guard.sh` runs on `git commit` + `git push` and blocks AI/assistant attribution in a commit message and force-push to a protected branch (main/master/develop); (3) `check-read-size.sh` runs on `Read` and on the shell commands that read a file whole, and routes an oversized read to a cheap worker (`bulk-read.sh`) instead of the caller's own rung. The first two inspect what a run WRITES; the third inspects what it pays to READ, and it is inert until `bulkRead.mode` is set to `observe` or `enforce`, so merging the block changes nothing until the user opts in. Its `observe` mode blocks nothing and only logs, which is how the baseline is measured before anything is routed. All three are self-contained, fail-open on internal error, and never execute the inspected command. Two capture hooks ship in the same block and block nothing: `SessionEnd` runs `capture-flush.sh --if-stale` (writing a killed run's findings into the per-repo stores, since every durable write used to live in Phase 7 - the phase a run is least likely to reach) plus `note-session.sh` (the mechanical shape of a non-pipeline session: tools used, commands that failed, calls the user refused - never an argument, never any output), and `SessionStart` runs `capture-resume.sh`, at most two lines about an unfinished run and a stale observation queue. Neither calls a model; both exit 0 on every path. The recommended hook block ships at `install/templates/claude-hooks.json`; `multi-agent:setup` offers to merge it into `~/.claude/settings.json`. The other deterministic gates (evidence, consensus, intent, learnings) are invoked by the pipeline phases with per-run arguments (a build-log path, the triage JSON, the free-text input), so they are phase-enforced by contract, not OS-hookable.

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

@@ -32,7 +32,7 @@ Visual mechanism per CLI:
 
 | CLI | What the agent calls at every phase boundary |
 |---|---|
-| **claude-code** | `TaskCreate({subject, activeForm})` then `TaskUpdate({status, activeForm})`. Native sticky widget; ⏺ tiles, spinner header. |
+| **claude-code** | `TaskCreate({subject, activeForm})` then `TaskUpdate({status, activeForm})`. Native sticky widget; ⏺ tiles, spinner header. **Not in every session** - see below. |
 | **copilot** | Inline call: `bash phase-tracker.sh render`. The bordered ANSI card lands as the last tool result in the chat. |
 | **codex** | The native `update_plan` tool: one plan step per phase, `status: pending \| in_progress \| completed`. Rewrite the whole step list on each boundary  -  the tool takes the full plan, not a delta. |
 | **generic** (plain shell, Git Bash, WSL, tmux) | Same bash render  -  the bordered ANSI card prints to terminal stdout in place. |
@@ -41,6 +41,10 @@ Visual mechanism per CLI:
 
 **Claude Code only**: in addition, `TaskCreate` / `TaskUpdate` native tool calls → the sticky widget pins the phase stack in the user's view.
 
+**The task tools depend on the MODEL, not the CLI version.** Claude Code provides `TaskCreate`, `TaskUpdate`, `TaskGet`, `TaskList` and `TodoWrite` by default only on Claude 3.x, Opus 4 through 4.7, Sonnet 4 through 4.6 and Haiku 4.5; on any newer model it leaves them out unless the user opts in. That default arrived in Claude Code v2.1.268, and this contract was written when the tools were universal, so nothing noticed the change: a run wrote its tracker state correctly, advanced every phase, and drew nothing for the whole run.
+
+So the branch is taken by the agent, which knows its own tool list, and never by the shell, which cannot see it. Without the tools the bordered card IS the widget and has to be reprinted inside the reply at every boundary, exactly as on Copilot CLI. Say once, in `outputLanguage`, that the native widget returns with `CLAUDE_CODE_ENABLE_TODO_TOOLS=1 claude` (or `claude --allowedTools TaskCreate`); a user staring at a missing widget needs the command, not the diagnosis. A subagent inherits the session's tool set even when it runs a different model, so this is a session-level fact and not a per-phase one.
+
 ### Codex specifics
 
 Two constraints on `update_plan`, both of which fail quietly if ignored:

package/pipeline/preferences-template.json

@@ -63,7 +63,7 @@
       "premiumTierUntil": null,
       "fallbackModel": "sonnet",
       "floorModel": "haiku",
-      "fableEnabled": true,
+      "fableEnabled": false,
       "onDispatchError": true
     },
     "costBudget": {