@mmerterden/multi-agent-pipeline 20.27.2 → 20.29.0

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

@@ -25,7 +25,7 @@ Progress emission per `$HOME/.claude/multi-agent-refs/progress-contract.md`  -
 
 #### Input contract
 
-Phase 4 consumes the latest Phase 3 triage output object conforming to `$HOME/.claude/schemas/triage-output.schema.json` (`accepted`, `deferred`, `rejected` buckets) plus the working-tree mutations from Phase 2. The commit body cites only `accepted` findings that were resolved; `deferred` items must be linked in the PR description as follow-up work, never silently dropped. If the triage output reports any unresolved blocking accepted finding, Phase 4 refuses to commit  -  the pipeline returns to Phase 2 for rework.
+Phase 4 consumes the latest Phase 3 triage output (`$HOME/.claude/schemas/triage-output.schema.json` (`accepted`, `deferred`, `rejected` buckets) and the Phase 2 working tree. The commit body cites only `accepted` findings that were resolved; `deferred` items must be linked in the PR description as follow-up work, never silently dropped. An unresolved blocking accepted finding sends the run back to Phase 2.
 
 "Build passes" below is evidence-gated: Phase 4 trusts the `buildStatus.ok` Phase 2 / Phase 3 recorded through `$HOME/.claude/scripts/evidence-gate.mjs` (a pass with no build/test log behind it is unverified and blocks the commit). The secret scanner (`pre-commit-check.sh`) runs on the staged diff as the final pre-commit gate.
 
@@ -44,7 +44,7 @@ Exit 0 passes. Exit 2 with `.verdict` `not-applicable` in `$PC` is `COVERAGE_NA`
 
 A step is accounted for when `completed`, `skipped` + `skipReason`, or `failed` + `failureReason`; a bare `pending` / `in_progress` is the gap. Every Section 14 `Add new` row must name a file in the tree; an empty `docPath[]` reports that half `skipped`, never `passed`.
 
-`COVERAGE_GAP` (a gap, a zero-step plan, unreadable input): show `$PC` verbatim, then return to Phase 2 or have the user mark each step deliberately (`plan-todos.sh` writes the reason); never proceed without that decision. `COVERAGE_NA`: log `plan-coverage: n/a` and continue. Gated runs: `$HOME/.claude/multi-agent-refs/features/unattended-gates.md`.
+`COVERAGE_GAP` (a gap, a zero-step plan, unreadable input): show `$PC` verbatim, then return to Phase 2 or have the user mark each step deliberately (`plan-todos.sh` writes the reason); never proceed without that decision, and re-run the gate once the steps are marked. `COVERAGE_NA`: log `plan-coverage: n/a` and continue. Gated runs: `$HOME/.claude/multi-agent-refs/features/unattended-gates.md`.
 
 #### Step 0  -  Multi-Repo Integration Build
 
@@ -84,7 +84,7 @@ Branch **deterministically**, no implicit fallback. Read `agent-state.json` and
 
 **Instruction-driven path:**
 
-1. Ask: "Want to commit?" (skip in autopilot)
+1. Ask: "Want to commit?" (skip in autopilot; operations.md "Attended waits")
 2. Read commit instruction file (e.g. `.instructions/figma/figma-iteration-commit/SKILL.md`)
 3. Follow its flow (build validation, test, submodule commits, push, PR, issue management)
 4. Log: "Phase 4: instruction-driven commit  -  file={instructionFiles.commit}"
@@ -111,8 +111,9 @@ Branch **deterministically**, no implicit fallback. Read `agent-state.json` and
    - Commit message uses same convention but scope reflects submodule: `{type}({submodule-scope}): {description} [{jiraId}]`
 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.
-8. Ask: "Want to open a Pull Request?"
+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.
    - No -> Phase 5
@@ -126,7 +127,7 @@ Branch **deterministically**, no implicit fallback. Read `agent-state.json` and
      --task-id "$TASK_ID" --project "$PROJECT" --branch "$BRANCH")
    ```
 
-   The script salvages before removing, keeps the branch, and does **not** check it out  -  the user's HEAD and uncommitted work stay put. On success it stamps `worktreeRemovedAt`, `artifactsPath` and `worktreePath: null` into the **salvaged** `agent-state.json` itself. Do NOT write those via `write-state.mjs "$STATE_FILE"`: in single-repo mode that path went away with the worktree, so the write fails, the fields land nowhere, and Phase 5 reads a dead path and silently skips the triage ingest. After a removal re-point `STATE_FILE` at `$(jq -r .artifactsPath <<< "$FIN")/agent-state.json`. Exit 3 is a safe skip (uncommitted changes, unpushed or detached HEAD, `--local`, cwd inside the tree, preference off): report and continue. Never `--force`. Contract: [`features/worktree-finalize.md`]($HOME/.claude/multi-agent-refs/features/worktree-finalize.md).
+   The script salvages before removing, keeps the branch, and does **not** check it out  -  the user's HEAD and uncommitted work stay put. On success it stamps `worktreeRemovedAt`, `artifactsPath` and `worktreePath: null` into the **salvaged** `agent-state.json` itself. Do NOT write those via `write-state.mjs "$STATE_FILE"`: that path left with the worktree, and Phase 5 would skip the triage ingest. After a removal re-point `STATE_FILE` at `$(jq -r .artifactsPath <<< "$FIN")/agent-state.json`. Exit 3 is a safe skip (uncommitted changes, unpushed or detached HEAD, `--local`, cwd inside the tree, preference off): report and continue. Never `--force`. Contract: [`features/worktree-finalize.md`]($HOME/.claude/multi-agent-refs/features/worktree-finalize.md).
 
 10. **Issue body update** (GitHub Issue only): if the issue body has a `### Pull Requests` section and/or a `### Progress` table, fill in the PR URL(s) (one row per submodule  -  e.g. `- **common:** {url}`, `- **uicomponents:** {url}`) and flip the Implementation / Testing / Code Connect flags from Pending to Done using whatever marker the template uses (match in place, do NOT introduce new markers). Apply it with `gh issue edit {issueNo} --body-file <file>`, preserving every other section unchanged.
 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.
@@ -271,7 +272,7 @@ For each repo in `state.projects[]` (sequentially, in dependency order from Phas
    `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>"`.
+5. Capture `state.projects[i].commit = {"sha": "<sha>"}`.
 
 ##### Push-must-succeed policy (gated by `prefs.global.settings.pushMustSucceed`, default `true`)
 

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

@@ -211,21 +211,23 @@ $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
-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
+STATE_FILE="${STATE_FILE:-$(node $HOME/.claude/scripts/usage-report.mjs --task-id "$TASK_ID" --print-state)}"
+TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+WS_ERR=$(printf '{"status":"complete","currentPhase":5,"finishedAt":"%s"}' "$TS" \
+  | node $HOME/.claude/scripts/write-state.mjs "$STATE_FILE" 2>&1 >/dev/null); WS_RC=$?
+[ "$WS_RC" = 0 ] && node $HOME/.claude/scripts/usage-report.mjs --task-id "$TASK_ID" --event completed >/dev/null 2>&1
 ```
 
-Parked on the channels choice instead: emit `--event parked` and leave `status` alone.
+`WS_RC` 6: `$WS_ERR` names what `complete` still lacks; record it (operations.md "Completion evidence") and write again, or halt. 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

package/pipeline/multi-agent-refs/test-gen/stages.md

@@ -0,0 +1,227 @@
+# test-gen stages
+
+<!-- toc -->
+- [Artefacts and gates](#artefacts-and-gates)
+- [Read-only stages](#read-only-stages)
+- [1. Inventory](#1-inventory)
+- [Priority](#priority)
+- [2. Discovery](#2-discovery)
+- [3. Gaps](#3-gaps)
+- [4. Handles](#4-handles)
+- [5. Write](#5-write)
+- [6. Run](#6-run)
+- [7. Classify](#7-classify)
+- [8. Triage](#8-triage)
+- [End: the change base](#end-the-change-base)
+<!-- /toc -->
+
+The contract behind `/multi-agent:test-gen`. Each stage is a subagent with one
+artefact under `$RUN` (`$HOME/.claude/logs/test-gen/<repo>/<timestamp>/`), and
+no stage starts until the previous artefact has passed its gate. A stage that
+says it is done without its artefact on disk is not done.
+
+## Artefacts and gates
+
+| # | Stage | Runs as | Artefact | Gate |
+|---|---|---|---|---|
+| 1 | inventory | orchestrator, with the toolkit inventory tools | `inventory.json` | `test-gen-gate.mjs check --stage inventory`, `evidence-gate.mjs --claim artefact` |
+| - | priority | AskUserQuestion; autopilot takes the top three | `inventory.json` `priority` | `check --stage inventory` again |
+| 2 | discovery | `test-gen-analyst` (read-only) | `discovery.json` | `check --stage discovery`, `evidence-gate.mjs --claim artefact` |
+| 3 | gaps | `coverage_gap`, then `test-gen-analyst` (read-only) | `gaps.json` | `check --stage gaps`, `evidence-gate.mjs --claim artefact` |
+| 4 | handles | general-purpose subagent, product code, handles only | `handles.md` and the stage's delta | `test-gen-gate.mjs handles`, `handle-diff-audit.mjs --baseline` exit 0 |
+| 5 | write | general-purpose subagent, test files only | the test files and `written.json` | `test-gen-gate.mjs written --baseline` |
+| 6 | run | orchestrator | `run-<k>.log` and per-test reports | `evidence-gate.mjs --claim test` |
+| 7 | classify | orchestrator | `results.json` | `check --stage results` |
+| 8 | triage | orchestrator, result by result | `results.json` `triage` | `test-gen-state.mjs revise` |
+
+Before each stage take `STAGE_START=$(date -u +%Y-%m-%dT%H:%M:%SZ)`. The
+artefact gate (`--claim artefact --stage-start "$STAGE_START" --evidence <its own
+file>`) rejects a file written before the stage began and a file that is not
+whole (JSON that does not parse). It is applied to the JSON a model writes
+(inventory, discovery, gaps); the scripts write `results.json` and the
+baselines whole.
+
+The two stages that may edit the repository (handles, write) start with a
+snapshot: `test-gen-gate.mjs baseline` records the working tree, untracked files
+included, as a git tree without touching it or the index. Their gates read only
+what changed after it, so uncommitted work the person had before the stage is
+never taken for the stage's change, and never reverted to satisfy a gate.
+
+## Read-only stages
+
+Discovery and gaps are dispatched with `subagent_type: "test-gen-analyst"`
+(`agents/test-gen-analyst.md`). The persona's grant is an allowlist: Read, Grep,
+Glob and the read-only toolkit tools (`coverage_gap`, the `repo_*` readers, the
+`code_*` language-server queries). No Write, Edit, Bash, Agent or other MCP tool
+is granted, so an analysis stage cannot change the repository however it is
+prompted. It returns JSON; the orchestrator writes it with the Write tool.
+Copilot CLI installs the same persona with the same grant. Codex CLI has no
+per-agent tool grant: there, run the two stages in the main session and change
+nothing during them.
+
+## 1. Inventory
+
+Prefer a tool over reading: `design_scenario_inventory` (a screen's states from
+the design), `web_map` (a web app's routes), the UI tree (`ios_get_ui_tree`,
+`android_get_ui_tree`) of each reachable screen, or the OpenAPI spec. Without a
+tool, read the navigation and routes and set `source: "agent"`. Every item has a
+stable `id`: route, screen id, design node id, endpoint path.
+
+When a change base exists (`test-gen-state.mjs base-scan` measured), keep the
+items whose `path` is among the scan's `files` or `graph.affectedFiles`, and say
+how many fell away. A scan with `measured: false` narrows nothing: the inventory
+stays whole and the reason is reported.
+
+## Priority
+
+Show the items in one table (id, kind, title, existing tests from a quick grep)
+and ask which to cover (AskUserQuestion, multi-select, following
+`multi-agent-refs/picker-contract.md`). Autopilot asks nothing:
+it takes the three items most likely to hide a failure, in this order: no test
+reaches them, they changed since the base, they are flows rather than single
+screens. Record `priority: {mode, selected}`.
+
+## 2. Discovery
+
+`test-gen-analyst`, stage `discovery`, with the selected items. It returns test
+roots and runners, the tests that reach each item (joined by identifier), the
+handles already present, and the conventions for new tests. Save as
+`discovery.json` and gate it with `check --stage discovery`.
+
+## 3. Gaps
+
+With `coverage_gap` (toolkit >= v3.25.0): call it with the inventory and the
+test root from discovery; its `covered`, `uncovered` and `unmatched` buckets go
+into the analyst's prompt, and `coverage.method` is `coverage_gap`. Without it:
+`coverage.method` is `agent` and every match the analyst makes is
+`method: "inferred"`. Then `test-gen-analyst`, stage `gaps`. Save its answer as
+`gaps.json`. The scenario-gap-analysis skill (ai-common-toolkit) defines the
+buckets and the scenario fields when it is enabled.
+
+Before writing any test, show the gaps and the `dataNeeds[]`. Each need is
+named, never filled: the person supplies the value, or names the credential the
+test resolves by `secretRef`. Autopilot writes only the scenarios whose needs
+are already met and lists the rest as blocked by data.
+
+## 4. Handles
+
+Only gaps with `handlesNeeded`. Before dispatch:
+
+```bash
+node "$HOME/.claude/scripts/test-gen-gate.mjs" baseline --repo "$REPO" --out "$RUN/handles-baseline.json"
+```
+
+The subagent adds the missing handles and nothing else: iOS
+`accessibilityIdentifier`, Compose `testTag` (or `testTagsAsResourceId` in a
+semantics block), web `data-testid`. Never a list index, never a renamed or
+moved element, never a handle the accessibility tree cannot see. It writes
+`handles.md`, one line per request: `ADDED file:line`, `ALREADY file:line`,
+`COULD NOT ADD <reason>` (the handle-request skill, when enabled). When nothing
+was missing, the first line is `HANDLES: none-needed` followed by the
+`ALREADY file:line` lines that prove it. Then:
+
+```bash
+node "$HOME/.claude/scripts/test-gen-gate.mjs" handles --repo "$REPO" \
+  --baseline "$RUN/handles-baseline.json" --handles "$RUN/handles.md"
+node "$HOME/.claude/scripts/handle-diff-audit.mjs" --repo "$REPO" \
+  --baseline "$RUN/handles-baseline.json" > "$RUN/handle-audit.json"
+```
+
+`handles` passes when the stage added a handle line, or on
+`HANDLES: none-needed` with at least one cited line, inside the repository, that
+carries a handle. `handle-diff-audit.mjs` must exit 0: 2 means the stage changed
+more than handles (`violations[]` name the file and the lost, extra or
+reordered tokens), so revert those hunks of the stage's own change and rerun; 3
+means it could not read the diff, which is not a pass.
+
+## 5. Write
+
+Take a new snapshot first (`test-gen-gate.mjs baseline --out
+"$RUN/write-baseline.json"`), then one subagent per platform, with the gaps,
+discovery's conventions and the handles. With `ui_locator_codegen` (toolkit >= v3.25.0), locators come from the
+UI tree node: `{platform, node}` returns the XCUITest or Compose code, or
+`NO_HANDLE` with the handle to add, which goes back to stage 4. Without it,
+write locators from the handles by hand. A locator is a handle, never a list
+index or a visible string that is translated.
+
+Each test asserts the gap's `expectation`. Test data comes from `secretRef` or
+the fixtures the person supplied, never a literal secret. The subagent writes
+`written.json`: `{files: [...], command: "<runs exactly these tests>",
+tests: [{id, file}]}`. Then run the command once with a per-test report and:
+
+```bash
+node "$HOME/.claude/scripts/test-gen-gate.mjs" written --repo "$REPO" \
+  --baseline "$RUN/write-baseline.json" --written "$RUN/written.json" \
+  --discovery "$RUN/discovery.json" --junit "$RUN/run-1.junit.xml"
+```
+
+(`--xcresult-json` or `--log` where the runner writes no JUnit.) The gate fails
+when the stage changed anything but test files, when a listed file is outside
+the repository, missing, empty or not changed by the stage, when the stage's
+diff carries test gaming (an environment branch, a swallowed error, an inflated
+wait), when the command is none of the runners discovery found, or when the run
+executed zero tests.
+
+## 6. Run
+
+Run `written.json`'s command `testStability.repeatCount` times (default 3),
+each run's log and per-test report kept as `run-<k>.log` and
+`run-<k>.junit.xml` (or `.xcresult`). A UI suite goes through
+`run-ui-tests.sh run`, whose `UI_TEST_RESULT` names the report. Each log must
+clear `evidence-gate.mjs --claim test --status passed` before a pass is
+recorded; a failing run is evidence too and is kept.
+
+## 7. Classify
+
+`features/test-classification.md`: `test_results_classify` with run 1 as
+`head`, the others as `confirm`, and the project's flake ledger, then
+`test-classify.mjs merge`; without the tool, `test-classify.mjs fallback` over
+the runs. Then:
+
+```bash
+node "$HOME/.claude/scripts/test-gen-gate.mjs" results --classification "$RUN/test-classification.json" \
+  --written "$RUN/written.json" --out "$RUN/results.json"
+node "$HOME/.claude/scripts/test-gen-gate.mjs" check --stage results --file "$RUN/results.json"
+```
+
+`results.json` is three-state: `pass`, `fail` (a regression, an unstable test, a
+preexisting failure), `not_measured` (no base, a setup failure); every non-pass
+carries its reason. `preexisting` is a fail here although Gate 3 inherits it: the
+test is new, so red on the base too means the behaviour it asserts is missing,
+which is a finding for triage, not someone else's failure.
+
+## 8. Triage
+
+Each `fail` and `not_measured` gets one verdict (the test-result-triage skill,
+when enabled): `product-bug`, `stale-test`, `new-scenario`, `valid` or
+`ambiguous`, and `ambiguous` is the default. `stale-test` needs the `file:line`
+in the diff that changed the behaviour on purpose; a locator that found nothing
+goes back to stage 4 before it may be called stale. A green test whose subject
+changed behaviour is questioned too. Record each verdict, then:
+
+```bash
+node "$HOME/.claude/scripts/test-gen-state.mjs" revise --state "$TG_STATE" --run "$RUN_ID" \
+  --test "<id>" --verdict "<verdict>" ${AUTOPILOT:+--autopilot}
+```
+
+| Action | Then |
+|---|---|
+| `apply` | revise the test, rerun from stage 6 for that test |
+| `park` | autopilot stops, because the verdict is `product-bug` (never applied without a person) or the stale-test cap (`prefs.global.testGen.revisionCap`, per run and per day) is reached. Report and end |
+| `ask` | attended `product-bug`: show the evidence and ask whether to open it through `/multi-agent` |
+| `none` | keep the verdict in `results.json` |
+
+The count is read and written under a lock, so parallel triage cannot pass the
+cap. A state or prefs file that does not parse is never counted as empty:
+autopilot parks (exit 3), an attended run stops with exit 4 and records nothing.
+
+## End: the change base
+
+After the report, record where this run ended so the next one diffs from here:
+
+```bash
+node "$HOME/.claude/scripts/test-gen-state.mjs" base-record --state "$TG_STATE" --repo "$REPO" --run "$RUN_ID"
+```
+
+The reason names the run (`test-gen run <id> finished`). It records which code
+the tests were written against, not that the app is understood.

package/pipeline/preferences-template.json

@@ -106,6 +106,16 @@
     },
     "resume": {
       "autoFix": false
+    },
+    "testGen": {
+      "revisionCap": 20
+    },
+    "attendedCommitGate": {
+      "mode": "warn"
+    },
+    "readOnlyRepos": [],
+    "stopGuard": {
+      "enabled": true
     }
   },
   "projects": {},

package/pipeline/rules/figma-pipeline.md

@@ -98,6 +98,8 @@ Re-fetching Figma in dev phases:
 
 The repo carries `pipeline/scripts/smoke-no-mcp-in-dev-phases.sh`, which reads a state file's `state.telemetry.mcpCalls[]`: a Figma tool entry with `phase >= 2` fails it, and a Figma entry with no phase is rejected as unjudgeable. It is a maintainer-side regression check: it runs locally as part of `npm test` and the pre-push hook, not in CI (the CI workflow is dormant) and not after every pipeline run.
 
+During a run on Claude Code the rule is enforced by a hook: `run-scope-guard.sh` is registered on PreToolUse `mcp__.*[Ff]igma.*` (`install/templates/claude-hooks.json`). For the run bound to the session it denies a Figma call above `thresholds.mcpAllowedThroughPhase` of `schemas/phases.json` (Phase 1, where Step 1.4 captures the evidence record) unless the run is in `analysis` mode, and it appends every allowed call to `telemetry.mcpCalls[]` itself. Copilot CLI and Codex have no equivalent hook; there the record is still the phase's own write.
+
 Memory: [[mcp-only-in-analysis]]
 
 ### Phase Order (platform-agnostic)

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

@@ -38,6 +38,10 @@
       "type": ["string", "null"],
       "description": "The Claude Code session id this run was launched under, copied by Phase 0 from MULTI_AGENT_SESSION_ID when the launcher set it. Continuous mode sets it to the id it passed as --session-id, and matches this field to find ITS run's state rather than another run in the same repo. Absent or null on an attended run: nothing sets the variable there."
     },
+    "hostSessionId": {
+      "type": ["string", "null"],
+      "description": "The host session that made this run's last phase transition: write-state.mjs copies CLAUDE_CODE_SESSION_ID from its environment when a write creates the state or sets currentPhase, and never otherwise, so a second session editing the state (steer) does not take the run over. run-stop-guard.mjs and run-scope-guard.mjs match it against a hook payload's session_id to find the run a hook call belongs to. Absent on a host that sets no such variable."
+    },
     "title": {
       "type": ["string", "null"],
       "description": "The issue title Phase 0 fetched (GitHub title, Jira summary). runs-index.mjs carries it as the run's title; absent when the input was free text or nothing was fetched."
@@ -275,9 +279,16 @@
       }
     },
     "waitingFor": {
-      "type": "string",
-      "enum": ["maturity", "user-channels-choice", "question"],
-      "description": "The step a paused run must RE-ENTER, as opposed to the phase it should continue past. resume reads this first and falls back to currentPhase + 1 when it is absent. maturity: Phase 0's maturity step, with the item re-fetched (refs/features/maturity-followup.md). user-channels-choice: Phase 5's channels menu, with the stored channelsInput. question: the step named by pendingQuestion.stepId, answered by `resume <id> --answer <optionId>`; open-questions-gate.mjs writes it as the last step of Phase 1 with stepId phase-1/open-questions."
+      "type": ["string", "null"],
+      "enum": [
+        "maturity",
+        "user-channels-choice",
+        "local-test",
+        "attended-reply",
+        "question",
+        null
+      ],
+      "description": "The step a paused run must RE-ENTER, as opposed to the phase it should continue past. resume reads this first and falls back to currentPhase + 1 when it is absent or null (null is how a wait is cleared through write-state). maturity: Phase 0's maturity step, with the item re-fetched (refs/features/maturity-followup.md). user-channels-choice: Phase 5's channels menu, with the stored channelsInput. local-test: Phase 3's user-test gate. attended-reply: a typed reply asked for in plain text inside currentPhase; resume re-enters currentPhase and asks again. question: the step named by pendingQuestion.stepId, answered by `resume <id> --answer <optionId>`, and never written without that pendingQuestion; open-questions-gate.mjs writes it as the last step of Phase 1 with stepId phase-1/open-questions. write-state clears every value but question when a write advances currentPhase."
     },
     "workspaceSource": {
       "type": "string",
@@ -497,7 +508,7 @@
     "status": {
       "type": "string",
       "enum": ["in_progress", "awaiting_input", "paused", "complete", "failed", "abandoned"],
-      "description": "Overall task status. `abandoned` is written through the locked state writer by the autopilot runner, for a run its session launched that ended with neither a PR nor a parked question, and by a kill; `abandonedBy` names the writer. `awaiting_input` is deliberately distinct from both `in_progress` and `paused`: the run is not broken and not resumable by a retry - it is finished with what it can do alone and is holding for a human answer, which is what Phase 5 does by design after the PR is open. Without a word for it, a run whose work had landed read exactly like one that crashed mid-development, and a state file in the wild had already invented `awaiting-user-test-main-checkout` to say it. `paused` stays what it was: stopped deliberately, resumable, nothing expected from anyone."
+      "description": "Overall task status. `complete` is earned, not claimed: write-state.mjs refuses a write that moves the run into it unless currentPhase is the mode's last phase and, for a mode that commits, Phase 4 left evidence (commit.sha, pr, publish, projects[].commit, or phases.4 skipped with notes) and gates[] holds a passing plan-coverage verdict (lib/run-completion.mjs); the autopilot runner files a complete state without that evidence as stopped-incomplete. `abandoned` is written through the locked state writer by the autopilot runner, for a run its session launched that ended with neither a PR nor a parked question, and by a kill; `abandonedBy` names the writer. `awaiting_input` is deliberately distinct from both `in_progress` and `paused`: the run is not broken and not resumable by a retry - it is finished with what it can do alone and is holding for a human answer, which is what Phase 5 does by design after the PR is open. Without a word for it, a run whose work had landed read exactly like one that crashed mid-development, and a state file in the wild had already invented `awaiting-user-test-main-checkout` to say it. `paused` stays what it was: stopped deliberately, resumable, nothing expected from anyone."
     },
     "abandonedBy": {
       "type": "string",
@@ -2059,7 +2070,7 @@
     },
     "gates": {
       "type": "array",
-      "description": "Gate ledger, written while the quality gates are active (lib/unattended.mjs gatesActive: MULTI_AGENT_UNATTENDED=1, or state.autopilot true): one entry per verdict, appended by gate-ledger.mjs under the write-state lock. With MULTI_AGENT_UNATTENDED=1 in its environment, pre-commit-check.sh blocks a commit unless the latest entry of every mandatory gate for HEAD is pass or not-applicable. Absent in a run with neither.",
+      "description": "Gate ledger, written while the quality gates are active (lib/unattended.mjs gatesActive: MULTI_AGENT_UNATTENDED=1, or state.autopilot true): one entry per verdict, appended by gate-ledger.mjs under the write-state lock. With MULTI_AGENT_UNATTENDED=1 in its environment, pre-commit-check.sh blocks a commit unless the latest entry of every mandatory gate for HEAD is pass or not-applicable. A run with neither records only the gates in gate-ledger.mjs ATTENDED_RECORDED, each entry marked attended: true, which the unattended commit check never counts.",
       "items": {
         "type": "object",
         "additionalProperties": false,
@@ -2082,6 +2093,10 @@
             "type": ["string", "null"],
             "description": "Repository HEAD the gate ran against."
           },
+          "attended": {
+            "type": "boolean",
+            "description": "True on an entry written while the quality gates were off (an attended run). lib/run-completion.mjs and the attended commit check read it; gate-ledger.mjs checkCommit ignores it."
+          },
           "detail": {
             "type": "object",
             "additionalProperties": true

package/pipeline/schemas/phases.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/phases.json",
-  "description": "The phase contract, in one place: the phase ids and names, which phases each mode runs, the per-phase token ceilings and the phase numbers other code compares against. gen-mode-dispatch.mjs, render-work-summary.sh, the autopilot runner, runs-index.mjs, usage-report.mjs and gen-facts.mjs read it; smoke-phase-contract.sh holds every copy that cannot read it (the phase docs and prose counts, agent-state.schema.json, token-budget.json, phase-tracker.sh, phase-banner.sh, gc-abandoned.sh) to it. Adding or merging a phase means editing here. Ceilings are measured against the current phase documents, never summed from earlier ones: smoke-token-budget.sh fails a ceiling more than 25% above the measurement.",
+  "description": "The phase contract, in one place: the phase ids and names, which phases each mode runs, the per-phase token ceilings and the phase numbers other code compares against. gen-mode-dispatch.mjs, render-work-summary.sh, the autopilot runner, runs-index.mjs, usage-report.mjs and gen-facts.mjs read it; smoke-phase-contract.sh holds every copy that cannot read it (the phase docs and prose counts, agent-state.schema.json, token-budget.json, phase-tracker.sh, phase-banner.sh, gc-abandoned.sh) to it. Adding or merging a phase means editing here. A mode with `commits: false` delivers no commit in its Phase 4 (analysis publishes a document), so lib/run-completion.mjs asks it for no commit evidence before `status: complete`; any other mode commits. Ceilings are measured against the current phase documents, never summed from earlier ones: smoke-token-budget.sh fails a ceiling more than 25% above the measurement.",
   "contractVersion": "2.0.0",
   "phaseSchema": 2,
   "phaseSchemaNote": "The phase vocabulary generation. metrics.jsonl is append-only and v19.0.0 renumbered the phases, so every line written from v19.0.0 on carries this number and a line without the field is generation 1. Aggregators pick their name table from it; without it phase 3 means Dev in old rows and Review in new ones and no reader can tell them apart.",
@@ -72,7 +72,8 @@
     },
     "analysis": {
       "phases": [0, 1, 3, 4, 5],
-      "autopilot": false
+      "autopilot": false,
+      "commits": false
     }
   },
   "thresholds": {

package/pipeline/schemas/phases.schema.json

@@ -50,7 +50,11 @@
             "items": { "type": "integer", "minimum": 0 },
             "uniqueItems": true
           },
-          "autopilot": { "type": "boolean" }
+          "autopilot": { "type": "boolean" },
+          "commits": {
+            "type": "boolean",
+            "description": "false when the mode delivers no commit in its Phase 4; lib/run-completion.mjs then asks for no commit evidence before status complete. Absent means the mode commits."
+          }
         }
       }
     },

package/pipeline/schemas/prefs.schema.json

@@ -1123,6 +1123,20 @@
             }
           }
         },
+        "testGen": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "/multi-agent:test-gen knobs. Read by test-gen-state.mjs revise.",
+          "properties": {
+            "revisionCap": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 500,
+              "default": 20,
+              "description": "Stale-test revisions autopilot may apply, counted per run and per calendar day (UTC), whichever is reached first. At the cap the run parks instead of editing more tests. 0 parks on the first one."
+            }
+          }
+        },
         "testStability": {
           "type": "object",
           "additionalProperties": false,
@@ -1858,6 +1872,43 @@
             "enabled": false
           }
         },
+        "stopGuard": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "run-stop-guard.sh, the Claude Code Stop hook that holds the session driving a pipeline run from ending its turn mid-phase with no halt or wait recorded. Read first on every Stop; false lets every stop through. Removing the hook from settings.json works too, and install does not add it back.",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": true,
+              "description": "true = the hook judges a stop as documented. false = it never blocks."
+            }
+          },
+          "default": {
+            "enabled": true
+          }
+        },
+        "readOnlyRepos": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "default": [],
+          "description": "Absolute paths (a leading ~ is expanded) of checkouts kept as read-only references: agent-guard.sh refuses an Edit, Write or NotebookEdit whose target is inside one, and a git commit, push, merge, cherry-pick, revert, am, rebase or tag that runs in one (after any cd or git -C on the line). Attended and unattended alike. Empty means no repository is protected this way."
+        },
+        "attendedCommitGate": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "What pre-commit-check.sh does with an attended `git commit` inside a pipeline run whose gate ledger holds no passing build and test verdict (evidence-gate/build, evidence-gate/test) for HEAD. evidence-gate.mjs records both in an attended run, marked attended. Read by gate-ledger.mjs `evidence`; a commit outside a run, or in a mode that commits nothing, is never checked. Unattended commits are held to the full ledger regardless of this setting.",
+          "properties": {
+            "mode": {
+              "type": "string",
+              "enum": ["off", "warn", "block"],
+              "default": "warn",
+              "description": "warn = say so on stderr and let the commit through. block = refuse the commit (exit 2) until the evidence is recorded. off = no check."
+            }
+          },
+          "default": {
+            "mode": "warn"
+          }
+        },
         "mutationProbe": {
           "type": "object",
           "additionalProperties": false,

package/pipeline/schemas/runs-index.schema.json

@@ -87,7 +87,7 @@
         "waitingFor": {
           "type": ["string", "null"],
           "x-sensitivity": "none",
-          "description": "The step a paused run re-enters (agent-state waitingFor): maturity, user-channels-choice or question. Added in 1.1.0."
+          "description": "The step a paused run re-enters (agent-state waitingFor): maturity, user-channels-choice, local-test, attended-reply or question; null or absent when the run is not waiting. Added in 1.1.0."
         },
         "pendingQuestion": {
           "x-sensitivity": "none",

package/pipeline/schemas/test-gen-discovery.schema.json

@@ -0,0 +1,73 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/test-gen-discovery.schema.json",
+  "title": "Multi-Agent Pipeline  -  test-gen discovery",
+  "description": "What the repository already has for testing the selected inventory items, $RUN/discovery.json of /multi-agent:test-gen (multi-agent-refs/test-gen/stages.md). Returned by the read-only test-gen-analyst persona and written by the orchestrator. testRoots[].command is what the write stage's run command is checked against (test-gen-gate.mjs written --discovery). Existing tests are joined to items by the identifier the test uses, never by a name. test-gen-gate.mjs check --stage discovery checks this shape without a dependency.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["stage", "testRoots", "existing", "handles"],
+  "$defs": {
+    "fileLine": { "type": "string", "pattern": "^[^\\s:]+:[1-9][0-9]*$" }
+  },
+  "properties": {
+    "stage": { "const": "discovery" },
+    "testRoots": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "runner", "command"],
+        "properties": {
+          "path": { "type": "string", "minLength": 1 },
+          "runner": {
+            "enum": [
+              "xcuitest",
+              "xctest",
+              "swift-testing",
+              "espresso",
+              "compose",
+              "junit",
+              "playwright",
+              "cypress",
+              "jest",
+              "vitest",
+              "pytest",
+              "other"
+            ]
+          },
+          "command": { "type": "string", "minLength": 1 },
+          "report": { "enum": ["junit", "xcresult", "none"] }
+        }
+      }
+    },
+    "existing": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["inventoryId", "tests"],
+        "properties": {
+          "inventoryId": { "type": "string", "minLength": 1 },
+          "tests": { "type": "array", "items": { "$ref": "#/$defs/fileLine" } },
+          "joinedBy": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "handles": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["inventoryId", "file", "line", "handle"],
+        "properties": {
+          "inventoryId": { "type": "string", "minLength": 1 },
+          "file": { "type": "string", "minLength": 1 },
+          "line": { "type": "integer", "minimum": 1 },
+          "handle": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "conventions": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "notes": { "type": "array", "items": { "type": "string" } }
+  }
+}