@mmerterden/multi-agent-pipeline 20.27.2 → 20.28.0

package/pipeline/commands/multi-agent/test-gen/SKILL.md

@@ -0,0 +1,124 @@
+---
+description: "Write the tests an app lacks, stage by stage, each gated on its artefact: inventory, read-only gap analysis, handles, tests, runs, per-test classification. Use when screens, flows or a change need tests."
+description-tr: "Uygulamada eksik olan testleri üretir: envanter, salt-okunur keşif ve eksik analizi, otomasyon tutamakları, test yazımı, tekrarlı koşum ve test başına sınıflama; her aşama kendi artefaktıyla kapılanan bir subagent'tır. Ekranlar, akışlar ya da son değişiklik için test yazılması gerektiğinde kullan."
+allowed-tools: Agent, Bash, Read, Write, Edit, Grep, Glob, AskUserQuestion, TaskCreate, TaskUpdate, TaskList
+argument-hint: "[scope] [--platform ios|android|web] [--repo <path>]  -  scope: a screen, route or flow, or empty for what changed since the last test-gen run"
+parameters: [{"name":"scope","kind":"text"},{"name":"--platform","kind":"enum","enum":["ios","android","web"]},{"name":"--repo","kind":"path"}]
+gui: form
+destructive: false
+confirm: none
+not-for: test, bug-bash, scenario-audit, manual-test
+---
+
+# multi-agent test-gen
+
+**Input**: $ARGUMENTS
+
+Writes the tests an app is missing, in the repo's own frameworks, and reports
+what they found. Seven stages run as subagents, each leaving one artefact that a
+script gates before the next stage starts: inventory, discovery, gaps, handles,
+write, run, classify. The two analysis stages run as a read-only agent type, so
+nothing they do can change the repository.
+
+Stage contract, read before Step 1:
+
+```
+$HOME/.claude/multi-agent-refs/test-gen/stages.md
+$HOME/.claude/multi-agent-refs/features/test-classification.md
+```
+
+Scripts: `test-gen-gate.mjs` (artefact, handle and write gates),
+`handle-diff-audit.mjs` (handles only), `test-classify.mjs`,
+`test-gen-state.mjs` (change base, revision cap), `evidence-gate.mjs`, all under
+`$HOME/.claude/scripts/`. Schemas: `test-gen-inventory`, `test-gen-gaps`,
+`test-gen-results` under `$HOME/.claude/schemas/`.
+
+> **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
+
+## Gotchas
+
+- An analysis stage that wants to "just fix" something is out of its lane. Discovery and gaps go to `test-gen-analyst`, whose grant is an allowlist of read-only tools.
+- The handle stage adds handles and nothing else. A wrapped view, a renamed element or a changed condition fails `handle-diff-audit.mjs`; revert the hunk, do not argue with the audit.
+- `HANDLES: none-needed` is a claim that the handles exist. It needs the `file:line` of each.
+- A test that passed once is not green. Unstable is a fail, and a red test with no base to compare is `not_measured`, not a regression.
+- Test data is named in `dataNeeds[]`, never filled in by the run. A credential is a `secretRef`.
+- A product bug is reported, never fixed here. In autopilot it parks the run.
+
+## Step 1 - Prepare
+
+1. Repo: `--repo`, else the current directory; confirm it in one line.
+   Platform: `--platform`, else detect as `/multi-agent:test` does. Run id
+   `tg-<timestamp>`; `RUN="$HOME/.claude/logs/test-gen/<repo>/<timestamp>"`,
+   created with `mkdir -p "$RUN"`.
+2. Toolkit: `test_results_classify`, `coverage_gap` and `ui_locator_codegen`
+   need `@mmerterden/multi-agent-toolkit-mcp` >= v3.25.0. Check the tool list
+   once. Each missing tool has a fallback in `stages.md` (classify from the
+   repeats, the analyst matches coverage itself with every match `inferred`,
+   locators written by hand from the handles); say which fallbacks are in use,
+   once.
+3. Change base. `TG_STATE="$HOME/.claude/knowledge/<project>/test-gen-state.json"`:
+
+   ```bash
+   node "$HOME/.claude/scripts/test-gen-state.mjs" base-scan --state "$TG_STATE" --repo "$REPO" \
+     --graph "$HOME/.claude/knowledge/<project>/code-graph.json" > "$RUN/base-scan.json"
+   ```
+
+   Exit 0: the changed files and their dependents narrow an empty scope. Exit 1
+   (`measured: false`, first run or base gone): nothing is narrowed, and the
+   reason goes in the report.
+
+## Step 2 - Inventory and priority
+
+Stage 1 of `stages.md`, then the priority pick: ask which items to cover
+(autopilot: the top three, recorded as `autopilot-top3`). Gate:
+
+```bash
+node "$HOME/.claude/scripts/test-gen-gate.mjs" check --stage inventory --file "$RUN/inventory.json"
+node "$HOME/.claude/scripts/evidence-gate.mjs" --claim artefact --status passed \
+  --evidence "$RUN/inventory.json" --stage-start "$STAGE_START"
+```
+
+## Step 3 - Discovery and gaps (read-only)
+
+Stages 2 and 3, both with `subagent_type: "test-gen-analyst"`. Write each answer
+with the Write tool, then gate each file with `evidence-gate.mjs --claim
+artefact` against its own stage start, and each with `test-gen-gate.mjs check`
+(`--stage discovery`, `--stage gaps`). Show the gaps (bucket, priority,
+expectation) and the `dataNeeds[]`; ask for the data or the credential names
+(autopilot: write only the scenarios whose needs are met).
+
+## Step 4 - Handles
+
+Stage 4. Snapshot first (`test-gen-gate.mjs baseline`), then the subagent, then
+both gates against that snapshot: `test-gen-gate.mjs handles` and
+`handle-diff-audit.mjs --baseline` exit 0. The gates read only the stage's own
+change; the person's uncommitted work is never the stage's to revert. Skip the
+stage when no gap has `handlesNeeded`, and say so.
+
+## Step 5 - Write, run, classify
+
+Stages 5 to 7: a new snapshot, the tests and `written.json`, the
+`test-gen-gate.mjs written --baseline` gate (test files only, inside the repo
+and changed by the stage, no test gaming, a discovered runner, more than zero
+tests run), the repeated runs, then
+`results.json` through `test-classify.mjs` and `test-gen-gate.mjs results`.
+
+## Step 6 - Triage
+
+Stage 8, one verdict per non-pass result, each through `test-gen-state.mjs
+revise`. Exit 3 parks the run: stop, keep every artefact, report why, and record
+no change base, because the run did not finish.
+
+## Step 7 - Report and base
+
+Print, in this order: the tests written (file, scenario, expectation), the
+results table from `results.json` with every `fail` and `not_measured` reason,
+the triage verdicts, the handles added (`handles.md`), the scenarios blocked by
+data, and `gaps.json`'s `unmeasured[]`. State which parts are mechanical (the
+gates, the classification, the handle audit) and which are judgement (the
+inventory, the gaps, the triage). Then record the change base
+(`test-gen-state.mjs base-record`).
+
+Offer, one question: open the product bugs through `/multi-agent` with each
+failing test as the acceptance check, or stop. **No commit, no push, no issue
+from this command.**

package/pipeline/multi-agent-refs/cross-cli-contract.md

@@ -1,7 +1,7 @@
 # Cross-CLI Contract (Claude Code · Copilot CLI · Codex CLI)
 
 <!-- toc -->
-- [1. Command Inventory (65 commands)](#1-command-inventory-65-commands)
+- [1. Command Inventory (66 commands)](#1-command-inventory-66-commands)
 - [2. Canonical Placeholder Vocabulary](#2-canonical-placeholder-vocabulary)
 - [2.6 Intentional structural divergence  -  thin dispatcher vs inlined orchestrator](#26-intentional-structural-divergence---thin-dispatcher-vs-inlined-orchestrator)
 - [2.7 One command, three different meanings: `/multi-agent:model`](#27-one-command-three-different-meanings-multi-agentmodel)
@@ -20,7 +20,7 @@
 
 ---
 
-## 1. Command Inventory (65 commands)
+## 1. Command Inventory (66 commands)
 
 ```
 analysis, analysis-jira, analysis-resolve, autopilot, autopilot-off,
@@ -32,7 +32,7 @@ prune-prompts, purge, refactor, research, resume, review,
 review-analysis, review-issue, review-jira, route-off, route-on,
 route-status, routines, save, scaffold, scan, scenario-audit, search,
 security-review, serve, setup, stack, status, steer, store-ready, sync, test, test-accessibility,
-test-dark-mode, test-dynamic-type, test-screenshots, testflight-validation,
+test-dark-mode, test-dynamic-type, test-gen, test-screenshots, testflight-validation,
 uninstall, update
 ```
 
@@ -42,7 +42,7 @@ Categories:
 - **Issue generator** (one-shot, no worktree, asks type Task/Bug/Story, hard approval gate before create): `create-jira`
 - **Pipeline entries**: `autopilot` (plus the bare `/multi-agent` in the dispatcher). The phase set is a property of the command, and every mode runs its whole set.
 - **Tail path** (the pipeline tail over work already on a branch, no run behind it): `resume`
-- **Ops commands** (one-shot, no worktree): `status`, `log`, `kill`, `steer`, `purge`, `uninstall`, `resume`, `review`, `review-jira`, `review-issue`, `analysis`, `analysis-resolve`, `research`, `scaffold`, `complaint-analysis`, `bug-bash`, `build-optimize`, `channels`, `scan`, `search`, `diff-explain`, `garbage-collect`, `graph`, `postmortem`, `prune-logs`, `prune-prompts`, `serve`
+- **Ops commands** (one-shot, no worktree): `status`, `log`, `kill`, `steer`, `purge`, `uninstall`, `resume`, `review`, `review-jira`, `review-issue`, `analysis`, `analysis-resolve`, `research`, `scaffold`, `complaint-analysis`, `bug-bash`, `test-gen`, `build-optimize`, `channels`, `scan`, `search`, `diff-explain`, `garbage-collect`, `graph`, `postmortem`, `prune-logs`, `prune-prompts`, `serve`
 - **Local audits** (worktree only to build; no commit, push, PR or channels): `design-check`, `testflight-validation`, `ios-coding-standard`. `testflight-validation` additionally never invokes `altool --upload-app`  -  a validation run must not be able to ship a build by accident.
 - **Meta-ops**: `setup`, `sync`, `update`, `help`, `refactor`, `test`, `stack`, `manual-test`, `language`
 - **Routines** (user-defined routine registry; the routines they create are local-only and never synced): `save`, `routines`, `forget`
@@ -102,7 +102,10 @@ Superseded by section 1.1: Claude Code resolves component dispatch to the market
 `e2e-testing` knowledge skill (ai-common-toolkit) call these toolkit tools when
 the server has them, and fall back to UI-tree reads and frame-centre taps when
 it does not. Contracts: `features/exploratory-testing.md`,
-`features/assertion-judge.md`.
+`features/assertion-judge.md`. `/multi-agent:test-gen` and the Phase 2 exit
+gate use the three v3.25.0 tools below; each consumer checks the server's tool
+list once and names the fallback it takes (`test-gen/stages.md`,
+`features/test-classification.md`).
 
 | Capability | Tools / fields | Minimum |
 |---|---|---|
@@ -118,6 +121,9 @@ it does not. Contracts: `features/exploratory-testing.md`,
 | Free-model delegation | `llm_delegate`, `llm_providers`; `ESCALATE_TO_CLAUDE`; the `multi-agent-toolkit-llm` CLI (`delegate`, `providers`, `probe`, `usage`) | ≥ v3.21.0 |
 | Related repositories | `repo_resolve`, `repo_grep`, `repo_read`, `repo_ls`, `repo_log`, `repo_find_keys`; `stale`, `not_found_at_sha` (`features/product-context.md`) | ≥ v3.22.1 |
 | Language-server answers over MCP | `code_references`, `code_definition`, `code_document_symbols`, `code_index_status` as JSON with structured content; `graph-confirm.mjs` reads them (`features/code-graph.md`) | ≥ v3.22.2 |
+| Per-test classification | `test_results_classify` `{head, base?, confirm?, flake_ledger?, format?, now?}` -> `tests[]` of `passed / regression / preexisting / unstable / not_measured` with `reason`, `summary`, `breaker?`; `test-classify.mjs merge` reads it (Phase 2 Gate 3, `/multi-agent:test-gen`; `features/test-classification.md`). Without it: `test-classify.mjs fallback` over the repeat runs | ≥ v3.25.0 |
+| Coverage by identifier | `coverage_gap` `{inventory, test_root}` -> `covered / uncovered / unmatched`, each entry `method: exact / inferred` (`/multi-agent:test-gen` gap stage). Without it: the analyst matches, every match `inferred` | ≥ v3.25.0 |
+| Mobile locator code | `ui_locator_codegen` `{platform: ios / android, node}` -> `{code}` or `{code: null, error: "NO_HANDLE", suggestion}` (`/multi-agent:test-gen` write stage). Without it: locators written from the handles by hand | ≥ v3.25.0 |
 
 ---
 

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

@@ -303,6 +303,19 @@ other outcome (`redirected`, `rejected`, `not-accepted`, `failed`, `skipped`),
 with the status code or reason and the step that fixes it. The emitter runs
 detached from phase-tracker with its output discarded, so this record is the
 only surface on which a reporting path that stopped working shows up.
+
+### usage-register
+
+The outcome `usage-register.mjs` recorded for its last attempt, read from
+`logs/multi-agent/usage-last-register.json`, and whether the failure report
+that attempt may have sent reached the site (`usage-register-beacon.json`).
+SKIP when `usageLog.optOut` is set or nothing was attempted yet; OK after a
+registration or when a token is already onboarded; WARN for every other
+outcome, naming the status, its detail and either "the failure report
+(<reason>) reached the site", "could not be delivered" or "no failure report
+was sent" (no login, a dry run, or a refusal the person chose). Registration
+runs quietly from setup, update and Phase 0, so this is where a machine that
+never registers shows why.
 ### free-models
 
 Can `route-on --free` actually leave Claude. SKIP while routing or its free

package/pipeline/multi-agent-refs/features/test-classification.md

@@ -0,0 +1,76 @@
+# Test result classification
+
+A red test says something about the change only when the base was green and
+the test stayed red when run again. This step measures that per test instead of
+reading one run's exit code, and the gates act on the measured class.
+
+Used at the Phase 2 exit gate (Gate 3), on the Phase 3 rework re-entry, and by
+the classify stage of `/multi-agent:test-gen`.
+
+## Classes
+
+| Class | Means | Gate |
+|---|---|---|
+| `passed` | green | pass |
+| `regression` | green on the base, red in two runs of the head | blocks: fix it |
+| `preexisting` | red on the base too, or listed failing in the Phase 0 baseline | inherited: does not block, is reported |
+| `unstable` | runs disagree, or the test was unstable in two or more separate runs over the last 7 days | blocks: never green. Log `test.flake_signal` and fix the test or the code |
+| `not_measured` | no base to compare, or a setup failure before the test ran; carries a `reason` | blocks: stays red, the reason is reported |
+
+## Inputs
+
+| Input | Source |
+|---|---|
+| `head` | the Gate 3 run's report: JUnit XML, the xcresult bundle, or Playwright JSON. UI tests: `UI_TEST_RESULT` from `run-ui-tests.sh run` (`UI_TEST_RESULT_FORMAT` names the format) |
+| `confirm` | a second run of the red tests: one of the `testStability.repeatCount` repeats Phase 2 already ran |
+| `base` | the Phase 0 baseline's report when it captured one (`state.baseline.tests.logPath`) |
+| `flake_ledger` | `$HOME/.claude/knowledge/<project>/flake-ledger.jsonl`, the project's history of measured unstable results. The toolkit counts only runs that turned green on confirm, never its own earlier `unstable` verdicts, so one flaky result cannot exempt a test for good |
+
+## With the toolkit (`test_results_classify`)
+
+Needs `@mmerterden/multi-agent-toolkit-mcp` >= v3.25.0. When the tool is
+listed, call `mcp__multi-agent-toolkit__test_results_classify` with
+`{head, base, confirm, flake_ledger, format}`, save its answer with the Write
+tool as `$WORKTREE/.pipeline/test-classified.json`, then:
+
+```bash
+node $HOME/.claude/scripts/test-classify.mjs merge \
+  --classified "$WORKTREE/.pipeline/test-classified.json" \
+  --state "$STATE_FILE" --out "$WORKTREE/.pipeline/test-classification.json"
+```
+
+`merge` applies the pipeline's rules on top of the toolkit's answer: `unstable`
+is never green; the Phase 0 baseline joins the preexisting set (a listed test the
+toolkit could not measure becomes `preexisting`; a listed test the toolkit calls
+a `regression` becomes `unstable`, because the base disagreed with itself); a
+tripped breaker is not green; nothing classified is not green.
+
+## Without it (older toolkit, or no server)
+
+Say so once in the run log. When the repeats wrote JUnit XML, classify from them
+alone:
+
+```bash
+node $HOME/.claude/scripts/test-classify.mjs fallback \
+  --run "$WORKTREE/.pipeline/repeat-1.junit.xml" --run "$WORKTREE/.pipeline/repeat-2.junit.xml" \
+  --state "$STATE_FILE" --out "$WORKTREE/.pipeline/test-classification.json"
+```
+
+Runs that disagree, and a run that saw one test both fail and pass (a retry,
+reports from several devices), are `unstable`; red in every run is `not_measured` (there is
+no base run), green in every run is `passed`. With no per-test report at all
+(an xcodebuild log only), Gate 3 keeps its log-and-baseline rule and logs
+`test.classify_skipped reason=<why>`.
+
+## Verdict
+
+| Exit | Gate 3 |
+|---|---|
+| 0 | pass. `inherited[]` is what the "red + `failing[]`" row subtracts; log `test:pass (inherited {N})` when it is not empty |
+| 1 | fail. `blocking[]` names the tests and `tests[].reason` says why. A tripped `breaker` is one environment failure seen across most runs: report its signature; autopilot parks the run as `verification-failed` rather than reworking code that is not at fault |
+| 2 | call error, never a pass |
+| 3 | the classification could not be read: Gate 3 keeps its log-and-baseline rule, and the reason is logged |
+| 4 | the script crashed: a defect to report, never a red verdict; Gate 3 keeps its log-and-baseline rule |
+
+Script: `scripts/test-classify.mjs`. The toolkit tool and its minimum version
+are listed with the other end-to-end testing tools in the cross-CLI contract.

package/pipeline/multi-agent-refs/features/usage-reporting.md

@@ -268,6 +268,23 @@ WARN with one step. `migrate-prefs.mjs` rewrites an endpoint on the platform
 host to the site's domain, so a stored redirecting endpoint does not outlive an
 update.
 
+A registration that ends `unavailable` also sends one failure report, detached
+so it never delays or fails the caller (`usage-register-beacon.mjs`): `POST
+<register URL>/failure` with `{ u, v, reason, os }` and nothing else, no token
+and no header beyond Content-Type. `u` is the login this run had (proven or
+declared; with no login nothing is sent), `v` the installed version, `reason`
+one word from a fixed list (`endpoint-unreachable`, `tls-untrusted`,
+`proxy-refused`, `timeout`, `redirected`, `not-collaborator`,
+`gh-account-mismatch`, `proof-rejected`, `proof-required`, `no-proof`,
+`rate-limited`, `server-error`, `credential-store`, `prefs-write`, `other`) and
+`os` darwin. It is never sent for an opted-out machine (feedback runs
+included), on a dry run, for a decline, or to a register URL the login proof
+may not go to. Each (reason, version) goes at most once a day; one that was not
+delivered is tried again on the next failed registration. The state is
+`~/.claude/logs/multi-agent/usage-register-beacon.json`, and doctor's
+`usage-register` check reads it next to `usage-last-register.json`. The server
+keeps the report only for the owner or a collaborator of the access repository.
+
 `prefs.global.usageLog.endpoint` overrides where both calls go - the register URL
 is derived from it, so a self-hosted ingest gets its own registration rather than
 this one's. Absent means the shipped default, and every shipped default names the

package/pipeline/multi-agent-refs/help/en.md

@@ -188,6 +188,7 @@ UI Testing (standalone  -  not part of pipeline phases):
   /multi-agent:test "store-ready" [path] tag still works and hands off there.
 
   /multi-agent:bug-bash [scope]      Parallel exploratory sessions by charter and persona, each with a budget; a finding is reported only when a repro test fails for its reason
+  /multi-agent:test-gen [scope]      Writes the tests an app lacks: inventory, read-only discovery and gap analysis, handles, tests, repeated runs, per-test classification; each stage gated on its artefact
 
   Uses xcrun simctl / adb (native, no external app needed).
   Booted simulator/emulator required. Auto-detects bundle ID from project.

package/pipeline/multi-agent-refs/help/tr.md

@@ -187,6 +187,7 @@ UI Testing (standalone  -  pipeline fazlarından bağımsız):
   /multi-agent:test "store-ready" [path] etiketi çalışır ve oraya devreder.
 
   /multi-agent:bug-bash [kapsam]     Charter ve persona başına bütçeli paralel keşif oturumları; bulgu, sebebiyle fail olan bir repro testi varsa raporlanır
+  /multi-agent:test-gen [kapsam]     Eksik testleri yazar: envanter, salt-okunur keşif ve eksik analizi, tutamaklar, testler, tekrarlı koşum, test başına sınıflama; her aşama artefaktıyla kapılanır
 
   xcrun simctl / adb kullanır (harici app gerekmez).
   Booted simulator/emulator şart. Bundle ID proje'den otomatik algılanır.

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

@@ -143,13 +143,13 @@ that) is the last-resort ceiling for a PID that has been recycled.
 **Halt visibility (required, autopilot included).** A halt is never silent. Whenever a phase halts on a hard error (validator failed twice, no subagent returned, dispatch error past fallback, lock irrecoverable), in addition to the `agent-log.md` line: (a) write `state.status = "paused"` and `state.haltReason = "<phase>:<cause>"`; (b) record the cause on the tracker via `phase-tracker.sh meta <phase> halt "<cause>"` and `phase-tracker.sh update <phase> failed`; (c) emit one `>&2` alert line `HALT phase <N>: <cause>  -  resume with /multi-agent:resume #<id>`; (d) if `prefs.global.usageLog.enabled` is true, emit the end-of-run report so a run that never reaches Phase 5 is still recorded with the phase it stopped at (`state.currentPhase` + `haltReason`) - the emitter no-ops when it is off or unconfigured:
 
 ```bash
-node $HOME/.claude/scripts/usage-report.mjs --state "$STATE_FILE" --event halted >/dev/null 2>&1 || true
+node $HOME/.claude/scripts/usage-report.mjs --task-id "$TASK_ID" --event halted >/dev/null 2>&1 || true
 ```
 
 **Park visibility.** A run that stops to wait for a person (`state.status = "awaiting_input"`, or `state.waitingFor` set: a maturity decision, an open question, the channels choice) emits the same report with `--event parked` right after the state write, so the panel shows it as waiting rather than abandoned:
 
 ```bash
-node $HOME/.claude/scripts/usage-report.mjs --state "$STATE_FILE" --event parked >/dev/null 2>&1 || true
+node $HOME/.claude/scripts/usage-report.mjs --task-id "$TASK_ID" --event parked >/dev/null 2>&1 || true
 ```
 
 Autopilot suppresses *confirmations*, not *halts*  -  the user must always be able to see why an unattended run stopped without reading the log. The endpoint upserts by run id, so this halt record and a later Phase 5 record (after resume) collapse into one.

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

@@ -156,7 +156,7 @@ For each task (respecting dependency order), on start and on end: `bash $HOME/.c
    **REFACTOR (if needed):**
    - Only if duplication or naming is poor
    - Re-run tests after refactor → still GREEN
-   - **Stability (required):** run every test added or changed in this diff `prefs.global.testStability.repeatCount` times (default 3; 1 disables) with the single-test invocation above. Disagreeing outcomes are not GREEN: log `test.flake_signal file=<f> passed=<k> of=<N>` and fix the test or the code first. A pass only on retry is a flake signal, not a pass. Same rule on the Phase 3 rework re-entry.
+   - **Stability (required):** run every test added or changed in this diff `prefs.global.testStability.repeatCount` times (default 3; 1 disables) with the single-test invocation above. Disagreeing outcomes are not GREEN: log `test.flake_signal file=<f> passed=<k> of=<N>` and fix the test or the code first. Same rule on the Phase 3 rework re-entry. Keep each repeat's `.pipeline/repeat-<k>.junit.xml`.
 
    **Target resolution** (auto-detect once per project, cache in `agent-state.json`; ios resolves scheme + simulator, android resolves module + variant, backend/web need none):
    ios (prefer the scheme matching the project name, then the first non-test scheme):
@@ -393,8 +393,7 @@ Shared localization keys: reuse before minting (`features/localization-reuse.md`
 ## Exit gate: Verify (BLOCKING)
 
 These deterministic gates run once, at this phase's exit, so the build runs once:
-Review inherits the logs instead of regenerating them. A failure here does not
-reach Review at all.
+Review inherits the logs instead of regenerating them.
 
 #### Step 1  -  Deterministic Gates (run BEFORE AI review)
 
@@ -422,20 +421,20 @@ 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`.
 
-**Autopilot runs** (`state.autopilot` or `MULTI_AGENT_UNATTENDED=1`; interactive runs skip this paragraph) 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.
+**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`).
 
-**Inherited failures (when `state.baseline.tests` exists).** Phase 0 Step 7.6 recorded whether the suite was already red, so Gate 3 blocks on what this work broke, not what it walked into:
+**Inherited failures (when `state.baseline.tests` exists).** Gate 3 blocks on what this work broke, not on what Phase 0 Step 7.6 found red:
 
 | baseline status | Gate 3 |
 |---|---|
 | `green` | unchanged; every failure is this run's |
 | `red` + `failing[]` | subtract those ids. Nothing left -> pass, logged `test:pass (inherited {N})`. A NEW failure still blocks. |
 | `red`, empty `failing[]` | do NOT pass and do NOT silently block: report `test:inherited-red (not attributable, <logPath>)` and ask. Inventing a set here masks regressions. |
-| `unknown` / absent | unchanged from today |
+| `unknown` / absent | unchanged |
 
-The subtraction never widens: match on identifier only, and when identifiers cannot be compared fall to the `not attributable` row.
+The subtraction never widens: identifier matches only. Classify a per-test report first (`$HOME/.claude/multi-agent-refs/features/test-classification.md`); `unstable` is never green.
 
 **Gate results:**
 

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

@@ -123,18 +123,18 @@ $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 3 review.diff_risk \
 
 #### Step 1.76  -  Test-integrity gate (produces BLOCKING findings)
 
-Step 1.75's `test_lines_removed` hint is too weak for a suite made green by deleting tests, so this makes it blocking findings triage must adjudicate. Pure function of the full report. `--out` always writes the file, the empty result included.
+Turns Step 1.75's `test_lines_removed` hint into blocking findings triage must adjudicate, and greps the diff for test gaming (`gaming.scanned: false` is not clean). `--out` always writes the file, even empty.
 
 ```bash
 TI_FILE="$WORKTREE/.pipeline/test-integrity.json"
-printf '%s' "$RISK_FULL" | node $HOME/.claude/scripts/test-integrity-gate.mjs --out "$TI_FILE" 2>/dev/null
+printf '%s' "$RISK_FULL" | node $HOME/.claude/scripts/test-integrity-gate.mjs --diff-base "$BASE_BRANCH" --repo "$WORKTREE" --out "$TI_FILE" 2>/dev/null
 TI_COUNT=$(jq -r '.count // 0' "$TI_FILE" 2>/dev/null || echo 0)
 [ "$TI_COUNT" -gt 0 ] && $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 3 review.test_integrity findings="$TI_COUNT"
 ```
 
 `findings[]` are reviewer-shaped (`test_integrity`, `blocking`), so they merge into the reviewer findings at Step 3.0 and need no triage-prompt or `validate-triage.mjs` change. Triage keeps each blocking unless the removal is justified per the immutable-test rule (spec changed AND commit body names the test) → `deferred[]`.
 
-The gate never blocks the phase; it *emits* blocking findings (unreadable input: zero). Feed it the FULL report: `--top` hides a shrinking test file below the cut. **No opt-out**: a run that can switch off its own anti-reward-hacking control cannot be trusted to report a pass.
+The gate never blocks the phase; it *emits* blocking findings. Feed it the FULL report: `--top` hides files below the cut. **No opt-out**: a run that can switch off its own anti-reward-hacking control cannot be trusted to report a pass.
 
 **TDD evidence**: `node $HOME/.claude/lib/tdd-evidence.mjs unverified --state "$STATE_FILE"` lists todos closed without RED/GREEN or by `--no-tests`, as reviewer notes, not findings.
 

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

@@ -211,21 +211,22 @@ $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 5 task.completed \
   duration_ms=$TOTAL_DURATION
 ```
 
-**Operational reporting** (`features/usage-reporting.md`). Mark the run finished in the state, then emit the completed event; both never block the run:
+**Operational reporting** (`features/usage-reporting.md`): mark the run finished, then report it. Neither blocks:
 
 ```bash
+STATE_FILE="${STATE_FILE:-$(node $HOME/.claude/scripts/usage-report.mjs --task-id "$TASK_ID" --print-state)}"
 printf '{"status":"complete","currentPhase":5,"finishedAt":"%s"}' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
   | node $HOME/.claude/scripts/write-state.mjs "$STATE_FILE" >/dev/null 2>&1 || true
-node $HOME/.claude/scripts/usage-report.mjs --state "$STATE_FILE" --event completed >/dev/null 2>&1 || true
+node $HOME/.claude/scripts/usage-report.mjs --task-id "$TASK_ID" --event completed >/dev/null 2>&1 || true
 ```
 
 Parked on the channels choice instead: emit `--event parked` and leave `status` alone.
 
-**Aggregate before reporting**: run `aggregate-metrics.mjs --since=$(date -u -v-30d +%Y-%m-%d)` and embed output in agent-log.md. Use `--json` for Jira. Aggregator handles missing files gracefully.
+**Aggregate before reporting**: run `aggregate-metrics.mjs --since=$(date -u -v-30d +%Y-%m-%d)` and embed output in agent-log.md. Use `--json` for Jira; missing files are skipped.
 
-**Per-run outcome metrics (evidence corpus):** also emit `run-metrics.mjs --state <agent-state.json>` and append/persist its JSON. It records review iterations, first-pass-clean, reviewer signal-to-noise, consensus verdict and build outcome, so quality across real runs is measured, not asserted.
+**Per-run outcome metrics (evidence corpus):** also emit `run-metrics.mjs --state <agent-state.json>` and append/persist its JSON. It records review iterations, first-pass-clean, reviewer signal-to-noise, consensus verdict and build outcome.
 
-**Cost Breakdown emission (mandatory):** as part of agent-log compose, append the per-task cost block produced by `render-agent-log-cost.sh`:
+**Cost Breakdown emission (required):** as part of agent-log compose, append the per-task cost block produced by `render-agent-log-cost.sh`:
 
 ```bash
 bash $HOME/.claude/scripts/render-agent-log-cost.sh "$TASK_ID" --append "$AGENT_LOG" 2>/dev/null