@mmerterden/multi-agent-pipeline 16.29.0 → 16.31.0

package/pipeline/multi-agent-refs/channels/pr.md

@@ -63,7 +63,9 @@ Multi-repo PRs (one PR per repo) emit verification commands for that repo's stac
 - Rollback: feature flag <name> | git revert <sha> | none, and why
 ```
 
-**`visuals`**  -  only when `state.visualEvidence.required`. The images live on the Jira issue as attachments; this section exists so a reviewer opening the PR knows they are there and what each one shows. Filenames, not raw URLs - a Jira attachment URL is auth-gated and renders as a broken image for anyone reading the PR outside a Jira session.
+**`visuals`**  -  only when `state.visualEvidence.required`. What this section can show depends on where the artefacts are hosted, which Phase 6 resolves into `state.visualEvidence.host`. Render the form for that host and no other.
+
+**`host: jira`.** Filenames, never URLs. A Jira attachment URL is auth-gated and renders as a broken image for anyone reading the PR outside a Jira session, and a broken image is worse than a filename because it looks like the evidence is missing.
 
 ```markdown
 ## Visual Evidence
@@ -73,6 +75,40 @@ Multi-repo PRs (one PR per repo) emit verification commands for that repo's stac
 - Flow video: `<flow-filename>`, tier <N> (attached to PROJ-XXXXX)
 ```
 
+**`host: github-public`.** The stills are on the `evidence/<task-id>` branch, so they embed and the reviewer sees them without leaving the PR:
+
+```markdown
+## Visual Evidence
+
+**Before**
+
+![before](https://raw.githubusercontent.com/<owner>/<repo>/evidence/<task-id>/<before-filename>)
+
+**After**
+
+![after](https://raw.githubusercontent.com/<owner>/<repo>/evidence/<task-id>/<after-filename>)
+```
+
+**`host: github-private`.** Same branch, but a link rather than an embed. GitHub renders markdown images through its own proxy, which has no credentials for a private repo, so an embedded raw URL renders broken for every reader including the author. A blob link opens the image for anyone who can already see the repo:
+
+```markdown
+## Visual Evidence
+
+- Before: [<before-filename>](https://github.com/<owner>/<repo>/blob/evidence/<task-id>/<before-filename>)
+- After: [<after-filename>](https://github.com/<owner>/<repo>/blob/evidence/<task-id>/<after-filename>)
+```
+
+**`host: none`.** Filenames plus the artefact directory, and the reason there is no host:
+
+```markdown
+## Visual Evidence
+
+- After: `<after-filename>` (run artefacts: `<artifactsPath>`)
+- Not published: <hostReason>
+```
+
+**Video is Jira-only.** On a GitHub-hosted run no recording is made and none is published: an mp4 behind a blob link is a download, not something a reviewer opens mid-review, and paying for a recording nobody watches is worse than saying plainly that there is none. The gap line carries that reason.
+
 Every `state.visualEvidence.gaps[]` entry becomes its own line with the reason instead of a filename (`- Before: none  -  the ticket carries no image attachment`). Phase 6 Step 3 blocks on a required artefact that is neither listed nor explained. Contract: `$HOME/.claude/multi-agent-refs/features/visual-evidence.md`.
 
 **`dependencies`**  -  only when `Package.swift` / `Podfile` / `build.gradle` / `package.json` changed. Each entry: `package@old → new  -  reason`.

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

@@ -195,3 +195,15 @@ read the registration and stopped would have called that healthy.
 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.
+
+### worktree-residue
+
+Worktrees left under `<repo>/.worktrees/` in the repository the caller is
+standing in. WARN at five or more, or at 2 GB. A finished task removes its own
+worktree at PR time, but a run that stops before Phase 6 never reaches that
+step and nothing else collects it: the finalizer only runs on success, and
+`gc-worktrees` only sweeps entries git has already forgotten. Each survivor is
+a full second checkout, so the total is measured in gigabytes rather than
+megabytes. SKIP outside a git repository - a project name in prefs is a name,
+not a path, and guessing checkout locations to produce a number is how a
+diagnostic starts lying.

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

@@ -121,10 +121,10 @@ evidence, and there is now one fewer of them. Triage also runs on `opus`, which
 makes it the same model as Reviewer 1; the Step 3 anonymisation requirement
 already covers that case and is not optional here.
 
-**Cost accounting.** `prefs.global.costBudget.priceAt` defaults to `fable` to
+**Cost accounting.** `prefs.global.costBudget.pricingModel` defaults to `fable` to
 keep the estimate an upper bound. With the rung off, that default prices every
 call above what it can cost and trips the budget ceiling early, which then
-triggers a downgrade nobody needed. Set `priceAt` to `opus` alongside
+triggers a downgrade nobody needed. Set `pricingModel` to `opus` alongside
 `fableEnabled: false`.
 
 No log line is emitted per dispatch for this: it is a configured absence, not a

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/keychain.md

@@ -158,6 +158,7 @@ The shell driver auto-delegates to `~/.claude/scripts/keychain.py` on macOS / Li
 | `graylog_test`     | Graylog (test)     | `${USER}_Graylog_Test_Access_Token` | API Token, optional  -  unset falls back to `graylog` | Same page on the TEST instance; optional |
 | `firebase`         | Firebase           | `${USER}_Firebase_Access_Json`     | Service-account JSON, as issued. One key per Firebase project; extras are named `..._Json_<projectId>` and listed in `global.firebase.accounts[]` | Firebase Console -> Project settings -> Service accounts -> Generate new private key |
 | `jenkins`          | Jenkins CI         | `${USER}_Jenkins_Access_Token`     | API Token | Jenkins -> User -> Configure -> API Token |
+| `vercel`           | Vercel deploys     | `${USER}_Vercel_Access_Token`      | Access Token | Vercel -> Account Settings -> Tokens. Read by `vercel-deploy.sh`; never passed on argv |
 | `appstore_connect_key_id` | App Store Connect | `${USER}_AppStoreConnect_Key_Id` | Identifier, not a secret | App Store Connect -> Users and Access -> Integrations -> App Store Connect API |
 | `appstore_connect_issuer_id` | App Store Connect | `${USER}_AppStoreConnect_Issuer_Id` | Identifier, not a secret | Same page as the key id; one issuer id per team |
 | `appstore_connect_apple_id` | App Store Connect | `${USER}_AppStoreConnect_Apple_Id` | Email address | The Apple ID itself; no generation step |

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

@@ -63,7 +63,7 @@ Knowledge files grow over time. Maintenance rules:
   and a rebuild is seconds, so age is the wrong question to ask of it.
 - Stale entries are added to the prompt with a "STALE  -  verify before relying" tag
 - `prune-logs` does not touch knowledge  -  only deletes logs and state
-- `purge` does not touch knowledge either  -  separate command: `/multi-agent clear-knowledge {project}`
+- `purge` does not touch knowledge either. Today the only removal path is `/multi-agent:uninstall --all-data`, which drops every project's knowledge at once; there is no per-project clear yet
 
 ---
 

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

@@ -447,14 +447,15 @@ fi
 
 If the path is still registered and healthy after the heal, enter + pull instead of re-adding (existing behavior). Only when `worktree add` still fails after the heal do the rollback / collision flow in the multi-repo block below.
 
-**Worktree residue guard (required once per repo, idempotent):** every worktree dir holds a `.git` file, so a blanket `git add -A` in the parent tree records `.worktrees/{id}` as a gitlink that pollutes the branch. Keep `.worktrees/` out of the index via the clone-local exclude file (never committed, so no PR noise):
+**Repo residue guard (required once per repo, idempotent):** keep every path the pipeline writes - `.worktrees/`, `.pipeline/`, `.multi-agent/` and the loose logs - out of the index via the clone-local exclude file (never committed, so no PR noise). One call; the rationale is in the lib header:
 
 ```bash
-ex="$(git -C "$PROJECT_ROOT" rev-parse --path-format=absolute --git-common-dir)/info/exclude"
-mkdir -p "$(dirname "$ex")"
-grep -qxF '.worktrees/' "$ex" 2>/dev/null || printf '.worktrees/\n' >> "$ex"
+. "$HOME/.claude/lib/repo-hygiene.sh"
+ma_hygiene_ensure_exclusions "$PROJECT_ROOT"
 ```
 
+Rewritten on each call, so an older checkout picks up new entries; lines a human added are never touched.
+
 **Traversal-prune contract:** the exclude guard covers only the git INDEX, not
 filesystem scans. Since each worktree is a full checkout, an unpruned tree walk
 double-processes every file and can re-stage gitlinks. So `.worktrees` joins the
@@ -468,14 +469,13 @@ scan, `shadow-git.sh` excludes, and the shared walkers (`extract-conventions.sh`
 When `state.projects[].length > 1`, repeat steps 2-4 **serially per repo** (worktrees are cheap; serial keeps git index sane and surfaces collisions one at a time):
 
 ```bash
+. "$HOME/.claude/lib/repo-hygiene.sh"
 for proj in "${PROJECTS[@]}"; do
   WT_PATH="$proj/.worktrees/$BRANCH_DIR/"
   git -C "$proj" worktree prune 2>/dev/null || true               # heal stale admin state
   git -C "$proj" worktree list --porcelain | grep -qF "$WT_PATH" \
     && git -C "$proj" worktree unlock "$WT_PATH" 2>/dev/null || true
-  ex="$(git -C "$proj" rev-parse --path-format=absolute --git-common-dir)/info/exclude"
-  mkdir -p "$(dirname "$ex")"
-  grep -qxF '.worktrees/' "$ex" 2>/dev/null || printf '.worktrees/\n' >> "$ex"   # residue guard
+  ma_hygiene_ensure_exclusions "$proj"                             # residue guard
   git -C "$proj" worktree add "$WT_PATH" -b "$BRANCH" "origin/$BASE_BRANCH"
   git -C "$WT_PATH" config user.name  "${proj_identity_name}"
   git -C "$WT_PATH" config user.email "${proj_identity_email}"
@@ -589,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-2-planning.md

@@ -120,7 +120,7 @@ Based on Phase 1 `detectedStack`, assign relevant skills:
 
 #### Output contract
 
-Phase 2 produces an object conforming to `$HOME/.claude/schemas/planning-output.schema.json`  -  `tasks[]` with `id`, `subject`, `targetFiles`, `complexity`, `blockedBy`, plus optional `architectureNotes` and `mode`. Phase 3 reads `tasks[]` in dependency order; the schema's `blockedBy` field drives the ready-task picker.
+Phase 2 produces an object conforming to `$HOME/.claude/schemas/planning-output.schema.json`  -  `tasks[]` with `id`, `title`, `type`, `files`, plus optional `dependsOn` and `acceptanceCriteria`. Phase 3 reads `tasks[]` in dependency order; the schema's `dependsOn` field drives the ready-task picker.
 
 **Required: validator gate (deterministic)  -  run on the persisted file before the approval gate renders the plan; the validator's exit code decides, not the LLM turn:**
 

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

@@ -49,7 +49,7 @@ The analysis document is the SOLE design source in Phase 3. Variant choices, pad
 
 #### Input contract
 
-Phase 3 consumes the Phase 2 output object conforming to `$HOME/.claude/schemas/planning-output.schema.json`  -  the task graph (`tasks[]` with `id`, `subject`, `targetFiles`, `complexity`, `blockedBy`) plus the architecture review notes. Tasks execute in dependency order; the schema's `blockedBy` field drives the ready-task picker. In a Short run (no Phase 2), Opus generates the equivalent task list inline before entering the loop below.
+Phase 3 consumes the Phase 2 output object conforming to `$HOME/.claude/schemas/planning-output.schema.json`  -  the task graph (`tasks[]` with `id`, `title`, `type`, `files`, and optional `dependsOn` / `acceptanceCriteria`) plus the architecture review notes. Tasks execute in dependency order; the schema's `dependsOn` field drives the ready-task picker. In a Short run (no Phase 2), Opus generates the equivalent task list inline before entering the loop below.
 
 **Plan Todo iteration (opt-in)**: gated by `prefs.global.planTodos.enabled` (default: `false`). When enabled and Phase 2 Step 4.5 emitted a `plan.todos[]`, Phase 3 iterates via `$HOME/.claude/lib/plan-todos.sh next/start/complete/fail` instead of walking `tasks[]` directly. When disabled, the loop walks `tasks[]` from `planning-output`  -  TDD contract is unchanged. Full helper loop + state semantics: `$HOME/.claude/multi-agent-refs/features/plan-todos.md`. A todo with `sourceTag: Reuse` binds the file analysis already found; `Modify` edits in place. Writing a new file over a `Reuse` step is a Locked 11 violation and Phase 4 flags it.
 
@@ -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
@@ -124,7 +126,7 @@ Tier 1 / Tier 2 records print `screenshotUrl` from the captured evidence (Tier 2
        git -C "$PROJECT_ROOT" worktree unlock "{worktree-path}" 2>/dev/null || true
      fi
      ```
-     Phase 0's `.worktrees/` residue guard is already in `.git/info/exclude`  -  no re-add.
+     Phase 0's repo residue guard is already in `.git/info/exclude`  -  no re-add.
    - Recreate worktree from branch: `git -C $PROJECT_ROOT worktree add {worktree-path} {branch}`
    - Re-set git identity: `git -C {worktree-path} config user.name/email` (from state)
    - Go back to Phase 3
@@ -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/preferences-template.json

@@ -15,7 +15,8 @@
       "graylog_test": null,
       "usage_ingest": null,
       "firebase": null,
-      "jenkins": null
+      "jenkins": null,
+      "vercel": null
     },
     "tokenScripts": {},
     "platformIdentityRouting": {},

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

@@ -1122,6 +1122,71 @@
       "type": ["string", "null"],
       "description": "Directory the worktree's artefacts were salvaged into before removal (agent-state, phase-tracker, triage-output, .pipeline/, build+test logs, review diff). Phase 7 and :resume read from here when worktreePath is gone."
     },
+    "testDepth": {
+      "type": ["string", "null"],
+      "enum": ["unit", "unit+ui", "unit+mcp", null],
+      "description": "How far the run tests, answered at intake because Phase 5 is absent from four of the eight modes and a question asked where it cannot be reached is a question nobody answers. `unit+ui` runs the repo's own UI test and records the screen around it; `unit+mcp` drives the flow through the toolkit MCP instead. The options offered are built from evidenceCapability, never from the model's reading of the repo."
+    },
+    "testDepthSource": {
+      "type": ["string", "null"],
+      "enum": ["user", "autopilot", "default", "forced", null],
+      "description": "Who chose. `forced` means only one option was open, so nothing was asked - recorded rather than passed off as the user's answer."
+    },
+    "evidenceCapability": {
+      "type": ["object", "null"],
+      "additionalProperties": true,
+      "description": "What this machine and this repo can actually produce, measured by probe-evidence-capability.sh BEFORE the test-depth question. Every absent value carries its reason, so a closed option can say why instead of vanishing from the menu; a value that could not be measured is null with a reason, never false, because a probe that did not look and a probe that found nothing are different facts. Contract: multi-agent-refs/features/visual-evidence.md.",
+      "properties": {
+        "platform": { "type": "string", "enum": ["ios", "android", "web", "other"] },
+        "uiTestTarget": {
+          "type": ["string", "null"],
+          "description": "The single chosen target, empty while several candidates exist and no match picks one."
+        },
+        "uiTestTargets": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Every candidate. A real app has many: the reference iOS app has one XCUITest bundle among 477 files that merely sit under a *UITests path, and the reference Android app has eight instrumentation source sets."
+        },
+        "uiTestTargetReason": { "type": ["string", "null"] },
+        "matchingTests": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Tests that mention a changed file's name. A heuristic, and treated as one: an empty set falls to the next tier rather than concluding the screen is untested."
+        },
+        "matchingTestsReason": { "type": ["string", "null"] },
+        "device": { "type": ["string", "null"] },
+        "deviceReason": {
+          "type": ["string", "null"],
+          "description": "'no booted simulator, but one is available to boot' and 'no iOS simulator available on this machine' are different problems with different fixes, and the user can act on only one of them."
+        },
+        "recorder": { "type": ["boolean", "null"] },
+        "recorderReason": { "type": ["string", "null"] },
+        "mcp": { "type": ["boolean", "null"] },
+        "mcpReason": { "type": ["string", "null"] },
+        "tier1": {
+          "type": "string",
+          "enum": ["open", "closed", "unknown"],
+          "description": "Whether the depth menu may offer tier 1. `unknown` means the target was not probed (a --only device re-check), which is not the same as closed and must not be rendered as one."
+        },
+        "tier2": { "type": "string", "enum": ["open", "closed", "unknown"] }
+      }
+    },
+    "uiTest": {
+      "type": ["object", "null"],
+      "additionalProperties": true,
+      "description": "The UI test run that produced the tier 1 recording. Subject to the same default-FAIL rule as the build: a zero exit code alone is not a pass, the log is the evidence, and evidence-gate.mjs reads it.",
+      "properties": {
+        "ran": { "type": "boolean" },
+        "target": { "type": ["string", "null"] },
+        "selected": { "type": "array", "items": { "type": "string" } },
+        "status": { "type": ["string", "null"], "enum": ["passed", "failed", "not-run", null] },
+        "notRunReason": {
+          "type": ["string", "null"],
+          "description": "Why it did not run: no target, no matching test, no device. Each is a reason to fall to the next video tier, never a phase failure."
+        },
+        "logPath": { "type": ["string", "null"] }
+      }
+    },
     "visualEvidence": {
       "type": ["object", "null"],
       "additionalProperties": false,
@@ -1198,10 +1263,23 @@
           },
           "description": "Captured in Phase 3 after the build+test gate, because Phase 5 is dropped by every autopilot and --local entry."
         },
+        "host": {
+          "type": ["string", "null"],
+          "enum": ["jira", "github-public", "github-private", "none", null],
+          "description": "Where the artefacts are published, resolved in Phase 6. `jira` attaches both stills and video. `github-public` pushes the stills to the evidence branch and embeds them in the PR body. `github-private` pushes the same stills but the PR carries a blob permalink instead of an inline image, because GitHub's image proxy cannot fetch a private repo's raw URL and an embedded one renders broken for every reader. `none` publishes nothing and records the gap. Video is Jira-only by decision: without an attachment host there is nothing a recording can be attached to."
+        },
+        "hostReason": {
+          "type": ["string", "null"],
+          "description": "Why this host and not the one above it in the order. A host of `none` with no reason is the silence the Phase 6 blocker exists to catch."
+        },
         "videoTier": {
           "type": ["integer", "null"],
           "enum": [1, 2, 3, null],
-          "description": "1 = the repo's own UI test target drove the flow, 2 = MCP-driven flow, 3 = no runnable build."
+          "description": "1 = the repo's own UI test target drove the flow, 2 = MCP-driven flow, 3 = no recording. Resolved from the capability probe, then RE-CHECKED at capture time: a device booted at intake can be gone by Phase 3, and a tier recorded from a stale measurement is a promise the run cannot keep."
+        },
+        "videoTierReason": {
+          "type": ["string", "null"],
+          "description": "Which rule produced the tier, and the tier it came down from when it was downgraded at capture time, e.g. 'tier 1 -> 2: simulator no longer booted'."
         },
         "video": {
           "type": "object",

package/pipeline/schemas/prefs.schema.json

@@ -198,6 +198,10 @@
               "type": ["string", "null"],
               "description": "NPM registry token (npm.pkg.github.com or npmjs.com). Used by package publish flow."
             },
+            "vercel": {
+              "type": ["string", "null"],
+              "description": "Keychain item holding the Vercel access token. vercel-deploy.sh resolves it through credential-store.sh so the value never reaches argv, where the CLI would leak it on a retry. Absent = deploys need VERCEL_TOKEN in the environment."
+            },
             "appstore_connect_key_id": {
               "type": ["string", "null"],
               "description": "App Store Connect API key ID. Tier 1 of the App Store Connect access chain, used by /multi-agent:store-ready Gate 2 (and its iOS alias /multi-agent:testflight-validation). An identifier rather than a secret; mapped anyway so every credential is read through the same layer. Creating an API key needs an Admin or App Manager role, which is why Tier 2 exists."
@@ -1865,7 +1869,26 @@
               "minimum": 5,
               "maximum": 300,
               "default": 60,
-              "description": "Recording cap. A flow needing longer is a debugging session, not a review artefact."
+              "description": "Recording cap. A flow needing longer is a debugging session, not a review artefact. Android's `screenrecord` has its own ceiling of 180s that no setting can lift, so capture-evidence.sh 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."
+            },
+            "githubHost": {
+              "type": "string",
+              "enum": ["branch", "off"],
+              "default": "branch",
+              "description": "Where stills go on a run with no Jira. `branch` pushes them to an orphan `evidence/<task-id>` branch so the PR body can show them; GitHub has no API that attaches a file to an issue or a PR, and the web uploader needs a browser session, so a branch is the only mechanism a script has. `off` means no upload, the PR names the artefact directory, and the absence is recorded as a gap. Video is never pushed here: an mp4 behind a blob link is a download, not evidence a reviewer will open."
+            }
+          }
+        },
+        "testDepth": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "How far a run tests by default. The question is asked at intake (Phase 0), not in Phase 5, because Phase 5 is not in the phase set for autopilot or either local mode. Autopilot never asks and reads `default` instead; the run records which rule fired.",
+          "properties": {
+            "default": {
+              "type": "string",
+              "enum": ["unit", "unit+ui", "unit+mcp"],
+              "default": "unit+ui",
+              "description": "Used by both autopilot entries, and as the preselected option for everyone else. An option the capability probe found closed is never taken from here: a default that cannot run is not a default."
             }
           }
         },