@mmerterden/multi-agent-pipeline 20.37.0 → 20.37.1

package/pipeline/multi-agent-refs/phases/phase-1-plan.md

@@ -221,7 +221,7 @@ Progress line: `→ analysis doc: <produced|reused|not-applicable> (<N> platform
 
 Two artefacts, both read downstream: `state.analysis` (the object below, for Phase 1 decomposition) and the Step 4 document (Phase 1 pre-flight + Phase 2's sole design source, Locked 29).
 
-Phase 1 produces an object conforming to `$HOME/.claude/schemas/analysis-output.schema.json` and persists it to `state.analysis`. Required fields (exact names per the schema): `stack` (detected stack identifier + primary language), `touchedAreas[]` (path + why), `risks[]` (existing-code hazards/observations the planner must respect  -  each `{risk, severity, mitigation}`; use an empty array when none), `summary` (one-paragraph human-readable). Phase 1 reads this object as its sole input  -  see `phase-1-plan.md`'s Input contract.
+Phase 1 produces an object conforming to `$HOME/.claude/schemas/analysis-output.schema.json` and persists it to `state.analysis`. Required fields (exact names per the schema): `stack` (detected stack identifier + primary language), `touchedAreas[]` (path + why), `risks[]` (existing-code hazards/observations the planner must respect  -  each `{risk, severity, mitigation}`; use an empty array when none), `summary` (one-paragraph human-readable). The planning half reads this object as its sole input (Input contract below).
 
 **Required: validator gate (deterministic)  -  run on the persisted file immediately after the analysis object is produced; the validator's exit code decides, not the LLM turn:**
 
@@ -273,7 +273,7 @@ Contract and rationale: `progress-contract.md` -> Token telemetry forwarding.
 
 ## Mid-phase checkpoint (BLOCKING)
 
-The planning half consumes what the analysis half just produced. This was a cross-phase pre-flight while Analysis and Planning were separate phases; it is now a checkpoint inside one phase, so there is no serialization boundary to defend - only a contract to honour. **Figma** MCP / REST forbidden; the toolkit MCP is not.
+The planning half consumes what the analysis half just produced. **Figma** MCP / REST forbidden; the toolkit MCP is not.
 
 1. **Analysis document presence**: read `state.analysis.docStatus`, which Step 4 above set.
    - `produced` | `reused` -> the file is at `state.analysis.docPath[]`; continue with steps 2-4.
@@ -469,9 +469,9 @@ reasons=$(jq -r '.reasons[] | "• \(.rule) (+\(.weight)): \(.detail)"' <<< "$ve
 | `false` | Skip 5a/5b as before  -  autopilot proceeds to Phase 2. Log `🧠 Phase 1: Safety classifier  -  score {N}, autopilot proceeds`. |
 | `true`  | Inject a one-time manual approval prompt even though we are in autopilot. Render the plan (5b shape) with the `reasons[]` list prepended. User sees `⚠️ Autopilot safety gate tripped (score {N})` banner and must explicitly choose Approve / Cancel (or edit via Other) in the 5b `AskUserQuestion` picker. Log `🧠 Phase 1: Safety classifier  -  score {N}, autopilot paused, reasons={rules}`. |
 
-**Why opt-out instead of opt-in:** the asymmetry favors pausing. A pause on a high-blast-radius plan costs seconds; a silent auto-merge of a bad one costs hours of rollback or a revert PR. Users running tightly-scoped batch workflows (e.g. figma component iteration over known-safe components) can set `prefs.global.autopilotSafetyGate = false` if they've validated the task class is safe.
+**Opt-out by design:** a pause on a high-blast-radius plan costs seconds, a silent merge of a bad one costs a revert. `prefs.global.autopilotSafetyGate = false` is for task classes the user has validated as safe.
 
-**Rules + weights**  -  see `classify-plan-safety.mjs` header comment for the canonical list. Summary: `file-count-high` (30) / `destructive-verb` (25) / `security-path` (35) / `delete-without-test` (30) / `schema-migration` (25) / `infrastructure` (20). Threshold: score ≥ 50 flips `recommendPause` true. Tuned so any single heavy signal or any two medium signals trigger the pause.
+**Rules, weights and the trigger** live in the `classify-plan-safety.mjs` header, the only copy: it pauses on any single heavy signal (weight 30+), on two signals of weight 20+, or on a total score of 50.
 
 **Telemetry:** emit `phase.plan.safety` OTel span (when `MULTI_AGENT_OTEL_SPANS=1`) with `{score, recommendPause, rules}` so post-hoc analysis can tune weights.
 

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

@@ -173,7 +173,7 @@ For each task (respecting dependency order), on start and on end: `bash $HOME/.c
    git -C "{worktreePath}" commit -F "/tmp/wip-message-$TASK_ID.txt"
    ```
    Write `wip({scope}): {task summary} [{jiraId}]` to `/tmp/wip-message-$TASK_ID.txt` with the file tool first. The summary comes from the issue, and inside a double-quoted `-m` the shell would run any `$(...)` in it.
-   WIP commits are squashed in Phase 4 before PR. This prevents work loss if a later task fails or the session crashes.
+   Standard path item 3 of Phase 4 Step 2 folds these back before the real commit. Keep the subject shape: that step recognises a checkpoint by it. This prevents work loss if a later task fails or the session crashes.
 7. Update task status: `completed` (apply the same verify rule  -  re-read the Status field and retry once on mismatch)
 8. Log: "Phase 2: {task}  -  Test + Build passed"
 
@@ -279,53 +279,11 @@ Exit 1 lists `unjustified[]`: complete the record, re-run once. A second exit 1
 
 #### v2.1.0+ Multi-Repo Mode
 
-Active when `state.projects[].length > 1` (set by Phase 0 multi-select). Single-repo flow above is preserved verbatim  -  this section adds the deltas.
+**Only when `state.projects[].length > 1`.** Load `$HOME/.claude/multi-agent-refs/features/dev-multi-repo.md` and follow it: the per-todo `repo` tag and worktree switch, one status update per todo, build serialization across worktrees, per-repo failure isolation with the evidence-gated `buildStatus`, and per-repo telemetry. A single-repo run skips it.
 
-**Todo tagging**: Phase 1 plan items in multi-repo mode carry a `repo` field naming the target project root. The dev agent uses this tag to dispatch each todo:
+#### Token forwarding
 
-```json
-{
-  "id": "T-3",
-  "title": "Add tokenResolver public API",
-  "repo": "common",                         // ← matches state.projects[i].name
-  "files": ["Sources/Common/TokenResolver.swift"],
-  "tdd": { "test": "...", "code": "..." }
-}
-```
-
-If a todo has no `repo` tag in multi-repo mode → log warning + ask user, do not auto-pick.
-
-**Per-todo worktree switch**: Before each todo's TDD cycle, resolve `WT_PATH = state.projects[ findIndex(name === todo.repo) ].worktreePath` and run **all** subsequent commands with `git -C "$WT_PATH"` and `cd "$WT_PATH"` for build/test. Identity (`user.name`/`user.email`) was already pinned per worktree by Phase 0 Step 8  -  no re-config needed here.
-
-**Status update (single ticket, multi-repo)**: The Jira/GitHub issue is shared across all repos in the group  -  call the status-update API exactly **once per todo** (not once per repo per todo). The post-mutation verify rule still applies.
-
-**Build serialization**:
-- Xcode worktrees still share `BUILD_LOCK = /tmp/claude-xcodebuild.lock`  -  multi-repo just means more callers contending for the same lock; the existing `mkdir`-based queue handles it correctly.
-- Non-Xcode repos may build in parallel across worktrees  -  but ONLY when builds are independent. If repo B's build depends on repo A's freshly-published artifact (e.g. SPM local path dependency), serialize them in dependency order. Plan items declare dependencies via Phase 1's `dependsOn` field; multi-repo dispatch respects that order.
-
-**Failure isolation**: A build/test failure in one repo's worktree must NOT silently leave the other repos in a half-built state. On failure:
-1. Capture the failure into `state.projects[i].buildStatus = { ok: false, attempts: N, lastError: "..." }`
-2. The ENTIRE Phase 2 retries within that repo's worktree (max 3, same as single-repo)
-3. After 3 attempts, escalate; do NOT proceed to Phase 3 with any unbuilt repo
-
-**Recording a pass (default-FAIL evidence gate):** before setting `buildStatus.ok = true`, the build output must be tee'd to a log and that log must substantiate the success  -  a zero exit code alone is not trusted. Run the evidence gate; on exit 1, do NOT record a pass:
-```bash
-<build-command> 2>&1 | tee "{worktreePath}/.build.log" \
-  | bash $HOME/.claude/scripts/offload-ref.sh --phase 3 --label build --root "$WORKTREE"
-node $HOME/.claude/scripts/evidence-gate.mjs --claim build --status passed --evidence "$WORKTREE/.build.log"
-```
-Non-zero from the gate: the build pass is unverified, so treat it as a failure and keep `buildStatus.ok=false`.
-This closes the gap where an agent records "built" without ever producing build output.
-
-**Why the pipe (opt-in via `prefs.global.contextOffload.enabled`).** `tee` decides where the log is written, not how much of it the model reads. The filter parks the full text at `.multi-agent/refs/<node_id>.md` and prints a stub plus the tail, where a failing build's error already is; read that file before re-running a failed build. The evidence gate still reads the whole `.build.log`, so what counts as a verified pass is unchanged. Pref off = pass-through.
-
-**Telemetry**: Per-repo metrics in addition to per-task metrics:
-```bash
-$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 2 build.completed repo=common duration_ms=$D status=ok
-$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 2 build.completed repo=uicomponents duration_ms=$D status=ok
-```
-
-**Token forwarding:** every TDD round (red, green, refactor) that hits the dev model MUST forward token totals into the tracker so Phase 5's Cost Breakdown captures Phase 2:
+Every TDD round (red, green, refactor) that hits the dev model MUST forward token totals into the tracker so Phase 5's Cost Breakdown captures Phase 2:
 
 ```bash
 LOG_METRIC_FORWARD_TO_TRACKER=1 $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 2 dev.tdd_round \
@@ -399,7 +357,8 @@ Review inherits the logs instead of regenerating them.
 # Gate 0: Owned paths (repo profile), before the build
 node $HOME/.claude/scripts/owned-path-gate.mjs --repo "$WORKTREE" --base "origin/$BASE_BRANCH" --state "$STATE_FILE"
 # Gate 1: Build (xcodebuild/gradle assemble/tsc/py compile  -  stack-dependent; Xcode uses the build queue lock, see Phase 2)  -  tee output to a log
-<build-command> 2>&1 | tee "{worktreePath}/.build.log"
+<build-command> 2>&1 | tee "{worktreePath}/.build.log" \
+  | bash $HOME/.claude/scripts/offload-ref.sh --phase 2 --label build --root "$WORKTREE"
 # Gate 2: Lint (swiftlint/ktlint/ruff/eslint  -  stack-dependent)
 # Gate 3: Tests pass (xcodebuild/gradle/pytest/the resolved node command)  -  tee output to a log
 <test-command> 2>&1 | tee "{worktreePath}/.test.log"
@@ -419,6 +378,8 @@ node $HOME/.claude/scripts/evidence-gate.mjs --claim test  --status passed --evi
 
 This prevents a false "it built" claim with no log behind it. On exit 1, treat the gate as failed (do NOT proceed to AI review) and surface the gate's `reason`.
 
+**Why the pipe (opt-in via `prefs.global.contextOffload.enabled`).** `tee` decides where the log is written, not how much of it the model reads. The filter parks the full text at `.multi-agent/refs/<node_id>.md` and prints a stub plus the tail, where a failing build's error already is; read that file before re-running a failed build. The evidence gate still reads the whole `.build.log`, so what counts as a verified pass is unchanged. Pref off = pass-through.
+
 **Autopilot runs** (`state.autopilot` or `MULTI_AGENT_UNATTENDED=1`) also run the stack-aware checks, each recording its verdict in `state.gates[]`: `evidence-gate.mjs --stack`, `test-summary.mjs` (zero tests executed parks the run as `verification-failed` instead of reworking), `test-strength.mjs --head worktree` and `symbol-existence-gate.mjs`. With the variable set, the Phase 4 commit hook refuses a commit whose ledger lacks them. Commands and verdicts: `$HOME/.claude/multi-agent-refs/features/unattended-gates.md` section 4.
 
 **Scaffolded repo** (`.scaffold.json` at the worktree root): at this phase's entry and exit, `scaffold-gate.mjs --dir "$WORKTREE" --phase story --story <id>`; exit 1 or 3 halts and the next story does not start; 2 is a call error, never a pass (`$HOME/.claude/multi-agent-refs/features/scaffold.md`).

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

@@ -437,7 +437,7 @@ bash $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 3 memory.hit rows=$CITED_COU
 **Bulky payloads (opt-in via `prefs.global.contextOffload.enabled`).** Test output and whole-file diffs go through the offload filter, which leaves a `[[ref:<node_id>]]` line plus the tail in context and the full text under `.multi-agent/refs/`. Read that file when the tail is not enough; with the pref off it is a pass-through.
 
 ```bash
-<test-command> 2>&1 | bash $HOME/.claude/scripts/offload-ref.sh --phase 4 --label tests
+<test-command> 2>&1 | bash $HOME/.claude/scripts/offload-ref.sh --phase 3 --label tests
 ```
 
 **Triage prompt skeleton:**
@@ -497,7 +497,7 @@ One file per round; `triage-output.json` is the latest copy every reader expects
 | ----- | ---------------------------- | ------------------------------------------------- |
 | **0** | Valid and clean              | Act on triage output as-is                        |
 | **1** | Invalid structure            | Gate protocol (strict, fails CLOSED): (a) emit the validator's stderr and `errors[]` JSON into the log verbatim; (b) attempt ONE self-correction rework  -  re-prompt triage with the errors quoted, overwrite `$TRIAGE_FILE`; (c) re-run the validator. Second failure -> HALT the phase with the recovery hint: `ERR: triage output failed validate-triage.mjs twice. Inspect $TRIAGE_FILE against $HOME/.claude/schemas/triage-output.schema.json, fix or regenerate it, then resume with /multi-agent:resume #N.` |
-| **2** | Over-rejection guard tripped | Pause for human confirm (autopilot: log + accept) |
+| **2** | Over-rejection guard tripped | Pause for human confirm (autopilot: log + accept); act on `result.corrected` when set |
 | **3** | Contradiction auto-corrected | Proceed with `result.corrected`                   |
 
 Capture stdout into `state.reviewIterations[-1].validatorResult` for Phase 5 audit.
@@ -649,36 +649,7 @@ echo "$GAP_JSON" | node $HOME/.claude/scripts/validate-test-gap.mjs - >/dev/null
 
 Skipped when `prefs.global.testGap.enabled` is `false`. Add `--scan-tree` when `testGap.scanTree` is true and `--severity-promote` when `testGap.promoteSeverity` is. Exit 3: the analysed stack (`ios|swift`, `android|kotlin`, `python`, `node|typescript|js`) has no gap rules, so there is no report.
 
-**What the report contains** (per `$HOME/.claude/schemas/test-gap.schema.json`):
-
-| Field | Meaning |
-|---|---|
-| `gaps[].sourcePath` | source file with the unprotected symbol |
-| `gaps[].symbol` | symbol name |
-| `gaps[].kind` | rule id (e.g. `public_func`, `composable_fun`, `named_export`) |
-| `gaps[].severity` | `blocking` / `important` / `suggestion` (see severity table below) |
-| `gaps[].expectedTestPaths` | likely test paths the user should land at, in priority order |
-| `gaps[].hint` | stack-specific testing reminder (e.g. swiftui-qa.md 3-layer) |
-
-**Severity defaults**:
-
-| Symbol kind | Severity |
-|---|---|
-| `composable_fun`, `view_struct`, `config_struct`, `interface`, `objc_export`, `public_proto` | important |
-| Other public API additions (`public_func`, `open_fun`, `named_export`, `default_export`, ...) | suggestion |
-
-**Gating** (opt-in): if `prefs.testGap.blockingThreshold` is set and `gapBySeverity.important + gapBySeverity.blocking` exceeds it, Phase 3 surfaces the report as a Phase 3 rework finding and loops back. **Default off**  -  gaps render as advisory under "Test Gap Report" only.
-
-**Telemetry**:
-
-```bash
-LOG_METRIC_FORWARD_TO_TRACKER=0 $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 3 test_gap.scanned \
-  stack=$SCAN_STACK \
-  sources=$(jq '.totals.sourcesScanned' <<< "$GAP_JSON") \
-  gaps=$(jq '.totals.gapCount' <<< "$GAP_JSON")
-```
-
-(No tracker forwarding  -  the scanner has no token cost.)
+When a report came back, load `$HOME/.claude/multi-agent-refs/features/test-gap.md` for its fields, severity defaults, the opt-in `prefs.testGap.blockingThreshold` gate (default off, advisory only) and the `test_gap.scanned` metric.
 
 **Figma reference panel (when `state.evidence.figma[]` is non-empty).** Before the local-checkout prompt, print a single block listing each captured frame so the user has a side-by-side reference during manual test:
 
@@ -700,22 +671,19 @@ Tier 1 / Tier 2 records print `screenshotUrl` from the captured evidence (Tier 2
      - `{ label: "Skip", description: "Stay in the worktree and go to Phase 4" }`
    - **Skip** → set `state.phases["3"].status = "skipped"` (so Phase 4 can offer the local-checkout prompt) → Phase 4
    - **Test now** → set `state.phases["3"].status = "in_progress"` → continue:
-2. **Commit changes in worktree BEFORE removing** (WIP commit to preserve work):
-   ```
-   git -C {worktree-path} add -A
-   git -C {worktree-path} commit -m "WIP: {jiraId}  -  changes for user test"
-   ```
-3. Remove worktree, checkout branch in main repo:
-   ```
-   git worktree remove .worktrees/{jiraId} --force
-   git checkout {branch-name}
+2. **Hand the branch over.** Make the WIP commit yourself, so it passes the same approval and secret-scan hooks as any commit (Standard path item 3 of Phase 4 Step 2 folds it back with Phase 2's checkpoints). The script then holds the run artefacts and the main repo's current branch, removes the worktree and checks the branch out in the main repo. `{worktree-path}` and `{jiraId}` come from the state (`worktreePath`, `jiraId`):
+   ```bash
+   git -C "{worktree-path}" add -A
+   git -C "{worktree-path}" diff --cached --quiet || git -C "{worktree-path}" commit -m "WIP: {jiraId}  -  changes for user test"
+   bash $HOME/.claude/scripts/user-test-handoff.sh checkout --task "{jiraId}" --worktree "{worktree-path}" --root "$PROJECT_ROOT" --branch "{branch-name}"
    ```
-   Branch now has the WIP commit  -  all changes are preserved.
+   A refused commit stops here with nothing moved. Script exits: 3 the main repo has uncommitted changes; 5 the worktree or a submodule holds uncommitted, unpushed or stashed work (a submodule with no remote needs one added); both move nothing. 6 a handoff is already held, or git refused part way: run `restore` below (if it answers 7, nothing had moved). 1 the worktree is not on the branch.
+3. On any failure report the reason and stop.
 4. Show test instructions:
    ```
    Switched to branch: {branch-name}
    To test: Xcode -> build -> run -> manual test
-   "ok" -> proceeds to Phase 4 (WIP commit will be replaced via git reset HEAD~1 + proper commit)
+   "ok" -> proceeds to Phase 4 (the checkpoint commits are folded into one proper commit)
    "fix: ..." -> worktree is recreated, returns to Phase 2
    ```
 5. Mark the tracker and the state as waiting (`local-test`, operations.md "Attended waits"), then wait for the user response:
@@ -725,6 +693,12 @@ Tier 1 / Tier 2 records print `screenshotUrl` from the captured evidence (Tier 2
    ```
    The waiting state persists in `tracker-state.json` across the handoff; `/multi-agent:resume` and `/multi-agent:manual-test` CONTINUE this state file and never re-init it (`$HOME/.claude/multi-agent-refs/tracker-contract.md` "Continuation runs").
 
+   **Either answer starts by handing the branch back**, which puts the main repo on the branch it was on, re-adds the worktree and returns the held artefacts:
+   ```bash
+   bash $HOME/.claude/scripts/user-test-handoff.sh restore --task "{jiraId}" --worktree "{worktree-path}" --root "$PROJECT_ROOT" --branch "{branch-name}"
+   ```
+   Exit 3: the user edited files on the branch in the main repo. Ask them to `git stash`, run `restore` again, then `git -C "{worktree-path}" stash pop`; a commit made there instead would stop Phase 4 from folding the checkpoints. Exit 6: the main repo could not leave the branch (an untracked file in the way) or the worktree could not be re-added; the message names the cause, the hold is kept, and `restore` runs again once it is cleared. Exit 7: nothing was held, so the worktree was never removed.
+
    **"ok" is a structured result, not a word.** Before "ok" is accepted, the run writes `$WORKTREE/.pipeline/manual-test.json`: one entry per acceptance criterion, the criteria taken from the analysis doc test plan (Section 15 / 20), the plan tasks, and the user's own words in the reply. Every criterion records what was seen; a criterion that was not tried says so with a reason.
    ```json
    {"criteria":[{"spec":"<quote>","source":"analysis 15.2 | plan task 3 | user","observed":"<what was seen>","verdict":"pass|fail|not-tested","reason":"<required when not-tested>","screenshot":"<path or null>"}],"verdict":"passed|failed"}
@@ -735,23 +709,13 @@ Tier 1 / Tier 2 records print `screenshotUrl` from the captured evidence (Tier 2
    ```
    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 3 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
-   - **Heal stale admin state first** (same contract as Phase 0  -  step 3's
-     `worktree remove` or an interrupted run can leave a stale entry, so a bare
-     re-add fails with `already exists`/`already registered`):
-     ```bash
-     git -C "$PROJECT_ROOT" worktree unlock "{worktree-path}" 2>/dev/null || true
-     git -C "$PROJECT_ROOT" worktree prune 2>/dev/null || true
-     ```
-     Unlock first: prune skips a locked entry. 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}`
+   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 3 completed with `Result "local test passed (user)"`.
+6. If fix needed (the worktree is back after the restore above):
    - Re-set git identity: `git -C {worktree-path} config user.name/email` (from state)
    - Go back to Phase 2
 7. Log: "Phase 3: Review (user test)  -  {result}"
 
-**CRITICAL**: Never remove a worktree with uncommitted changes. Always WIP commit first.
+**CRITICAL**: Never remove the worktree by hand. `user-test-handoff.sh` is the only path: it refuses whenever work would be lost.
 
 #### Automated Device Checks (on-demand)
 
@@ -767,18 +731,10 @@ 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 2 produced none
-
-Phase 2 Step 3.55 is the primary host and runs in every mode. Phase 3 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 3 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.
+When `visualEvidence.required` is true and `visualEvidence.video.file` is empty, record the UI flow video now: load `$HOME/.claude/multi-agent-refs/audit-guide.md` "Phase 3 evidence flows", which also carries the snapshot regression flow.
 
 Results included in Phase 5 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.
-
 #### Telemetry  -  token forwarding
 
 When the security-auditor or any other Phase 3 sub-agent runs, forward its token totals so Phase 5's Cost Breakdown captures Phase 3:

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

@@ -104,7 +104,11 @@ Branch **deterministically**, no implicit fallback. Read `agent-state.json` and
    - Default: option 1 (by index, not by label  -  the label is localized)
    - If the user picks option 2 (WIP checkout): follow Phase 3 Steps 2-6. On `"fix:"` → Phase 2. On `"ok"` → resume Phase 4.
 2. Commit confirm prompt (skip in autopilot), in `outputLanguage`: "Commit now?" with "Commit" / "Pause and resume later", branched on the option index. No → pause (`resume` later). Yes → continue; where prompts are off, record it with `confirm-command.mjs --command '<the exact commit>'` (agent-guard asks on the run's commit).
-3. If WIP commit exists from Phase 3 or Step 1: `git reset HEAD~1` to unstage, then re-commit properly
+3. Fold the run's checkpoint commits back into the working tree: Phase 2's `wip(...): ... [{jiraId}]` commits and the user-test `WIP: {jiraId}` commit, counted from HEAD down and stopping at the first commit that is neither, so earlier commits on the branch are never touched. Item 4 stages and commits properly.
+   ```bash
+   bash $HOME/.claude/scripts/checkpoint-fold.sh --repo "$WORKTREE" --task "{jiraId}" --base "{baseBranch}"
+   ```
+   Exit 6: every commit down to the root is a checkpoint; stop and ask.
 4. Stage changes: `git add` with specific files (NOT `git add -A`  -  avoid sensitive files, `.worktrees/`, agent files)
 5. **Multi-submodule check**: If project has submodules (e.g. uicomponents + common):
    - Detect which submodules have changes: `git -C {worktree} diff --name-only | cut -d'/' -f1-3 | sort -u`
@@ -113,7 +117,7 @@ Branch **deterministically**, no implicit fallback. Read `agent-state.json` and
 6. Commit with convention: `{type}({scope}): {description} [{jiraId}]` or `[#{shortId}]`. When `node $HOME/.claude/scripts/repo-profile.mjs resolve commit.format --repo "$PROJECT_ROOT"` returns `use: true`, its `ticketPosition` places the ticket (`prefix` first, `suffix` last; `none` keeps this default unless confirmed or manual), `ticketStyle` its form and `scopeRequired` the scope. A profile hook with `amends-commit` or `writes-files` rewrites the commit: re-read the SHA after committing ([`features/repo-profile.md`]($HOME/.claude/multi-agent-refs/features/repo-profile.md)). **Local-only repos** (`projects[i].provider == "local"`) have no ticket, and that wins over any profile placement: the subject keeps the conventional prefix with no ticket, and the taskId (`LOCAL-...`) goes in the body footer: `Local-Task: {taskId}`.
 6a. **Valven (required):** `features/valven.md`.
 6b. **Record the commit**: operations.md "Completion evidence".
-7. Push to remote  -  **skip per-repo when `projects[i].provider == "local"`** (no `git push`, no upstream config). Log `Phase 4: local-only commit {sha} (no push)` for that repo.
+7. Push to remote through the Push-must-succeed policy below  -  **skip per-repo when `projects[i].provider == "local"`** (no `git push`, no upstream config). Log `Phase 4: local-only commit {sha} (no push)` for that repo.
 8. Ask: "Want to open a Pull Request?" (attended wait, as in step 1)
    - **Skip the prompt entirely when `state.offlineOnly == true`** (all repos local  -  no PR target exists). Proceed to Phase 5 with `pr.status = "skipped-offline"` for each project.
    - In mixed mode (some local, some remote), only prompt for the remote-backed repos; local ones auto-skip.
@@ -257,25 +261,9 @@ Before creating PR, ask: "READY or DRAFT? [1/2], default `defaultPrMode` or 1"
 
 #### v2.1.0+ Multi-Repo Mode
 
-Active when `state.projects[].length > 1`. The single-repo flow above is preserved verbatim  -  multi-repo is an extension, not a replacement.
-
-##### Per-repo commit (shared message, per-repo scope)
-
-For each repo in `state.projects[]` (sequentially, in dependency order from Phase 1):
+**Only when `state.projects[].length > 1`.** Load `$HOME/.claude/multi-agent-refs/features/commit-multi-repo.md` and follow it: per-repo commit (shared subject, per-repo scope), per-repo PR with sibling cross-links and the serial worktree finalize, the issue-body PR list, and the `recentGroups` LRU bump. A single-repo run skips it; the push policy below applies to every run.
 
-1. `cd "$WT_PATH"`  -  switch into the repo's worktree.
-2. Build the commit message using the **shared subject** + **per-repo scope** rule:
-   ```
-   {type}({repo-scope}): {shared subject} [{tracker-id}]
-
-   Part of multi-repo change  -  see sibling PR(s) in repo `{other repo names}`.
-   ```
-   `repo-scope` is the repo's short name (e.g. `common`, `uicomponents`). The subject and `[tracker-id]` are identical across all repos.
-3. `git add` (specific files only  -  same rules as single-repo Step 5)
-4. `git -C "$WT_PATH" commit -m "$MESSAGE"` (heredoc body)  -  using identity already pinned in Phase 0 Step 8.
-5. Capture `state.projects[i].commit = {"sha": "<sha>"}`.
-
-##### Push-must-succeed policy (gated by `prefs.global.settings.pushMustSucceed`, default `true`)
+#### Push-must-succeed policy (gated by `prefs.global.settings.pushMustSucceed`, default `true`)
 
 The build passed → the commit MUST reach the remote. Silent push failures are unacceptable.
 
@@ -305,45 +293,7 @@ Persist `state.projects[i].pushStatus` ∈ `"pushed" | "rebase-pushed" | "skippe
 
 The legacy single-repo path uses the same loop with `state.projects[].length === 0`; semantics unchanged.
 
-##### Per-repo PR with cross-links
-
-After all repos are pushed, open PRs sequentially, one per `state.projects[]` entry, each through its remote's usual path (gh / Bitbucket REST) with the per-stack body template (Standard / UI Component / etc). Append to each body:
-
-```
-## Sibling PRs (multi-repo task)
-This PR is part of a multi-repo change. Sibling PRs (review together):
-- <url of each PR opened before this one>
-```
-
-After the last PR opens, `update_sibling_links`: go back to the first N-1 PRs and add the sibling URLs that were not yet known when they were created.
-
-**Then finalize each repo's worktree**, serially and only now  -  `update_sibling_links` updates one PR per repo and the loop `cd`s per repo, so removing repo 1's worktree mid-loop breaks 2..N. Run `worktree-finalize.sh` once per repo with that repo's `--worktree` / `--project-root` / `--project`; each skips or removes independently.
-
-`update_sibling_links` does an UPDATE call per PR (Bitbucket: the `channels/pr.md` PUT payload, current `version`; GitHub: `gh pr edit --body-file`). Idempotent.
-
-##### GitHub issue body  -  list all PRs
-
-Step 10's "Issue body update" extends to multi-repo: instead of a single `### Pull Requests` line, write one row per repo:
-
-```
-### Pull Requests
-- **common:** {pr-1-url}
-- **uicomponents:** {pr-2-url}
-```
-
-Match the existing template's table/list shape  -  do not introduce new markers (per existing single-repo rule).
-
-##### `recentGroups` update on success
-
-After ALL repos in the task have `pushStatus ∈ {"pushed", "rebase-pushed"}`:
-
-1. Find the matching `recentGroups[]` entry by **order-independent compare** of `repos` array (sort + JSON.stringify).
-2. If found: `entry.count += 1`, `entry.lastUsed = ISO timestamp`, bump to front of array (LRU).
-3. If not found: prepend a new entry `{ label: <auto-generated>, repos: [...], count: 1, lastUsed: ... }`. Cap the array at 10 (drop oldest).
-
-A task ending with one or more `pushStatus === "skipped"` repos does NOT bump `recentGroups` count  -  only fully-successful multi-repo tasks earn LRU bumps.
-
-##### Telemetry
+#### Telemetry
 
 Per `state.projects[]` entry (`{name}`), then once for the task:
 

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

@@ -380,37 +380,6 @@ Append to every Phase 5 report (knowledge-capture pass) a **Quality & Metrics**
 
 The block is generated by `output-quality-check.sh` + `token-budget-report.mjs --task $TASK_ID --json` and pasted verbatim. If either script is missing, that subsection is omitted (best-effort).
 
-#### metrics.jsonl schema extension
-
-Telemetry events may carry an `outputQuality` object inside `details`, plus a `channels` sub-object with per-adapter status:
-
-```json
-{
-  "ts": "2026-04-21T...",
-  "task_id": "PROJ-12345",
-  "phase": "7",
-  "event": "task.completed",
-  "details": {
-    "phases": 8,
-    "review_cycles": 2,
-    "channels": {
-      "pr":         "posted",
-      "jira":       "posted",
-      "confluence": "skipped",
-      "wiki":       "posted"
-    },
-    "outputQuality": {
-      "commitFormat": "pass",
-      "prBody": "pass",
-      "jiraComment": "pass",
-      "reviewerJsonValid": true,
-      "triageJsonValid": true,
-      "severityRatio": "1:2:4"
-    }
-  }
-}
-```
-
 #### Final metrics report appended to PR body at release time
 
 When the pipeline cuts a release, append the latest 30-day rollup to the release PR body:

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

@@ -189,7 +189,7 @@ Same rule applies to any future provider wrapper (e.g. `cloudflare-deploy.sh`, `
 
 These rules govern when and how the pipeline asks the user, and when it must NOT ask.
 
-- **No auto-commit.** Never run `git commit` without explicit user approval, even when build + review pass. The Phase 4 commit step pauses and asks ("commit message X, OK?"); only on `yes` does the commit run. Applies to checkpoint / WIP commits during Dev (Phase 3) and to the orchestrator's own state-save commits. Enforced on Claude Code: agent-guard asks on a `git commit` from the session driving an attended run, and pre-commit-check refuses it without the run's build, test and (from Phase 4) review evidence.
+- **No auto-commit.** Never run `git commit` without explicit user approval, even when build + review pass. The Phase 4 commit step pauses and asks ("commit message X, OK?"); only on `yes` does the commit run. Applies to checkpoint / WIP commits during Dev (Phase 2) and to the orchestrator's own state-save commits. Enforced on Claude Code: agent-guard asks on a `git commit` from the session driving an attended run, and pre-commit-check refuses it without the run's build, test and (from Phase 4) review evidence.
 - **No micro-confirmations for reversible local work.** Local edits, lint fixes, test additions, scaffold files, in-worktree rewrites  -  just do them. Ask only for irreversible or shared-state actions: `git push`, `git push --force`, tag, third-party POST (Confluence, Jira, Slack), publish, deletes spanning many files, branch deletion. The threshold is "can the user undo this in 30 seconds via Cmd+Z or `git restore`?"  -  if yes, do not ask.
 - **Empty `AskUserQuestion` answer is not consent.** When the user submits without picking any option (empty answers map), do NOT silently apply the "Recommended" default. Re-ask the question, or proceed treating each item as unselected. On Claude Code the `answer-check.sh` PostToolUse hook names each unanswered question back to the model. Future-behavior preference questions are not preemptive  -  only ask when the answer changes what happens NOW.
 - **Question phrasing in Plan Mode.** Don't reference "the plan" in `AskUserQuestion` text while in plan mode  -  the user cannot see the plan until `ExitPlanMode`. Use `ExitPlanMode` for approval; `AskUserQuestion` only for choosing between concrete options.