@mmerterden/multi-agent-pipeline 16.19.0 → 16.21.0

package/CHANGELOG.md

@@ -16,6 +16,53 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ## [Unreleased]
 
+## [16.21.0] - 2026-09-08
+
+### Added
+
+- **A read-size gate, and a cheap worker to send an oversized read to.** `offload-ref.sh` took half the machinery bill in 15.10.0 - the build log, the diff, the test output become a pointer plus a tail. The other half was never looked at, because nothing could look at it: only a `PreToolUse` hook sees a tool call before it runs. A phase that reads six 900-line files pays for 5,400 lines at that phase's own rung, and the part it needed was a handful of symbols.
+
+  `check-read-size.sh` (+ `check-read-size.py`, the decision core) is the third hook in `install/templates/claude-hooks.json` and the first on the READ side. `bulk-read.sh` is where a blocked read goes instead: the file reaches a haiku-rung worker over the `bulk-reader` persona, and what comes back is a structured summary with LINE NUMBERS, so the caller's next step is a bounded `Read(offset:limit:)` around the region that matters - which is cheap, exact, and passes the gate. The full text is parked under `.multi-agent/refs/`, the same place and the same promise `offload-ref.sh` makes.
+
+  **`observe` is a real mode, not a debug flag.** It decides and logs, blocks nothing, and it is what `bulkRead.mode` should be set to first: a gate switched straight to `enforce` has no baseline to be compared against, and "we cut tokens" becomes a claim nothing can check. The saving is measured from `metrics.jsonl` (`read.observed` / `read.blocked` / `bulk_read.delegated`), not asserted here - this entry deliberately quotes no percentage.
+
+  **Phase 3 is exempt, and that is load-bearing.** Claude Code's `Edit` requires the same file to have been `Read` first, so a gate that blocks reads while code is being changed blocks the change. So does any file the run itself has touched (`phases[n].files[]`). The gate is for the phases that read to UNDERSTAND. A draft of the decision core read `run.phase` and `dev.editSet` - neither of which `agent-state.schema.json` declares - so the exemption could never have engaged and development would have been blocked by a hook whose message read like advice; `smoke-bulk-read.sh` now asserts the field names against the schema so it cannot come back quietly.
+
+  **A ceiling, because delegation is not free either** (`bulkRead.maxBytes`, default 1 MB). Past some size the worker's own input bill approaches the read it replaced, and a file large enough to strain its window comes back truncated - a partial summary presented as a whole one is the one thing this feature must never produce. Over the ceiling the caller is told to narrow first (grep, then a bounded read). The check runs BEFORE the file is hashed or parked, so the guard is not theatre.
+
+  **The command parser is per-tool, because the flags are not shared.** `cat -n` NUMBERS LINES rather than taking a count, and reading its next token as one swallowed the filename, left no operand, and let `cat -n <bigfile>` through the gate entirely. `sed -n '1,900p'` looked bounded because it carried a flag, when the range in its script IS the bound. An unparseable count reads as UNBOUNDED, never as 1. A `tail -f` is a stream and passes, because blocking it would be a false positive with no cheap alternative to offer.
+
+  Off by default (`bulkRead.mode: "off"`), so merging the hook block is not itself a behaviour change. The worker degrades rather than inventing: no CLI, no auth, a timeout, or a non-JSON answer prints why and tells the caller to do a bounded read. A fabricated summary of a file nobody read is the one outcome worse than paying full price for the file.
+
+### Changed
+
+- **`multi-agent:setup` Step 8 and the picker-contract stop miscounting the hooks.** Both said two gates ship, and the setup step called the secret scan "the only deterministic gate that is OS-enforceable as a hook" - untrue since `agent-guard.sh` landed. Three ship now, and both places say so, along with which side of the run each one inspects.
+- **`smoke-gate-hooks.sh` covers all three gates** rather than two, and asserts the shipped defaults are safe (the read gate off, phase 3 exempt) - a read gate that shipped switched on would have been a breaking change disguised as a merge.
+
+
+## [16.20.0] - 2026-09-07
+
+A comparison against `msitarzewski/agency-agents`, a 150k-star persona catalog, found nothing to copy wholesale and three things to fix: the personas were never registered, the circuit-breaker was prose, and a review finding had no identity from one round to the next. This release gives findings that identity and builds the loop controls, the handoff records and the evidence rules on top of it.
+
+### Added
+
+- **A finding keeps its identity across review rounds.** `finding-fingerprint.mjs` stamps every reviewer, triage and dev-critic finding with `F:xxxxxxxx`, computed from the file and either the cited rule ID or the normalised issue text; the line, the severity and the fix text take no part, so a finding whose line moved after the fix is still the same finding. `review-delta.mjs` compares one round's triage with the previous one and reports `stillPresent`, `resolved`, `downgraded` and `new`, plus how many consecutive rework cycles each survivor has lasted. Phase 4 keeps one `.pipeline/triage-round-<N>.json` per round, injects the previous round's accepted findings into the shared reviewer prefix so reviewers echo instead of rediscover, and stores the delta in `state.reviewIterations[i].delta`. The Phase 3 reflection prompt puts the survivors first, marked `STILL PRESENT`.
+- **The circuit-breaker has two triggers in code.** Trigger 2 (a blocking or important finding that survives `identicalFindingCycles` consecutive rework cycles, default 2) fires from `review-delta.mjs` exit 3 at Phase 4 Step 3.8; trigger 3 (the rework cap) is recorded by the Phase 3 re-entry. Both write `state.circuitBreaker` and halt visibly in autopilot; interactive modes show the survivors and ask. `prefs.global.autopilotCircuitBreaker` and `state.circuitBreaker` now exist in the schemas the feature doc had been naming, `resume` clears the trip, and `smoke-autopilot-circuit-breaker` asserts the schema fields, the scripts and the phase wiring instead of grepping the prose.
+- **Dev states its scope before review reads it.** Phase 3 Step 3.7 writes `.pipeline/scope-check.json`: a reason per touched file, the changes deliberately not made, and the code-simplifier rationales that used to be discarded. `scope-check-gate.mjs` compares it with the real diff; Phase 4 renders it as `<scope-self-check>` so reviewers judge against the stated scope and do not re-propose what was rejected; Phase 6 builds the PR `Changes` bullets and a "Follow-ups not done in this PR" list from it.
+- **PR bodies carry a risk section when the diff earns one.** `channels/pr.md` gains the conditional `## Risk and Security` section (auth flow touched, secret handling changed, data migration, rollback), required whenever `state.diffRisk.signals` carries a high-stakes signal. Phase 4 now persists the diff-risk totals to `state.diffRisk`, and `run-metrics.mjs` reports `diff.filesTouched`, `locAdded`, `locRemoved` and the cross-round delta.
+- **Manual test results are evidence, not a chat reply.** Phase 5 writes `.pipeline/manual-test.json` with one row per acceptance criterion (the quoted spec, the observation, the verdict, the screenshot) and `evidence-gate.mjs --claim manual` refuses an "ok" whose criteria are missing, failed or untested without a reason. The simulator UI report pairs every bug with its spec quote and its before/after captures and ends with a production-readiness verdict that defaults to FAILED.
+- **One green run is not proof.** Verify-by-test re-runs a passing repro test `verifyByTest.repeatCount` times (default 3) before it may downgrade a blocking finding; a run that disagrees makes the verdict `inconclusive` with a `flaky` note. Phase 3 runs every new or changed test `testStability.repeatCount` times (default 3) and records `test.flake_signal` when outcomes disagree: a test that passes only on retry is a flake signal, not a pass.
+- **Persona files round-trip and store readiness asks about symbols and rollout.** `lint-personas.mjs` checks every persona's frontmatter, its `## Output Format` section, and that the Codex TOML rendered from it decodes back to the same description and body byte for byte; the renderer no longer appends a newline the source did not have. The smokes that hardcoded six persona names now derive the list from the directory. `store-ready` flags an archive without dSYMs (or a minified bundle without `mapping.txt`) as blocking, checks that a symbol upload step exists, and ends the report with the phased-rollout thresholds and the rollback owner a release needs written down.
+
+### Changed
+
+- **Token budgets: phase-4-review max 14750 -> 15150, total 58250 -> 60250.** The full contracts for the review delta and the scope self-check live in `multi-agent-refs/features/review-delta.md` and `features/scope-check.md`, outside the budget; the phase docs carry the call, the pref and the exit table, and were compressed twice before the numbers moved. `rules.md` was tightened by 150 bytes to keep the fixed per-run load under its 60000-byte ceiling. Reasoning in `schemas/token-budget.json`.
+
+### Fixed
+
+- **Phase 4 and Phase 7 disagreed on the triage file name.** Phase 4 wrote `.pipeline/triage.json`; Phase 7, `worktree-finalize.sh`, `render-work-summary.sh` and `diff-explain.mjs` read `triage-output.json`. The salvage step bridged it only when the worktree was removed, and everywhere else the triage corpus and the learnings ledger silently stopped being fed. Phase 4 now copies the latest round to `triage-output.json` itself.
+- **The eight personas were never registered as subagents.** `pipeline/agents/*.md` carried `description`, `model`, `preferredModel` and `modelRationale` but no `name:`, and Claude Code drops a subagent file without one silently: no error, no agent. Every `subagent_type: "code-reviewer"`, `"ios-architect"`, `"security-auditor"`, `"dev-critic"` and `"task-clarifier"` dispatch in the phase docs named an agent the host did not have. Each persona now declares `name:` equal to its filename stem, and `smoke-agent-model-routing` fails when a persona lacks it, when the name differs from the stem, or when it is not lowercase kebab-case. Found while comparing the persona format against `msitarzewski/agency-agents`, whose linter treats `name` as a required field.
+
 ## [16.19.0] - 2026-09-02
 
 A review of the three repositories together (pipeline, toolkit MCP, plugin marketplace) with every test suite green found the defects the suites could not see. This release fixes what was found in the pipeline; `@mmerterden/multi-agent-toolkit-mcp` 3.8.0 and the marketplace plugins carry their own halves.

package/README.md

@@ -213,7 +213,7 @@ The pipeline runs natively on **Claude Code**, **Copilot CLI** and **Codex CLI**
 
 | Tool | Flag | What it installs |
 |---|---|---|
-| Claude Code | `--claude` (default) | slash commands + skills + agents + `PreToolUse` secret-scan hook |
+| Claude Code | `--claude` (default) | slash commands + skills + agents + three `PreToolUse` hooks (secret scan, agent-guard, read-size gate) |
 | Copilot CLI | `--copilot` | instructions + 55 sub-command skills + scripts |
 | Codex CLI | `--codex` | one router skill + 55 specs as refs + 8 agent TOML + `AGENTS.md` block + `codex mcp add` |
 

package/README.tr.md

@@ -213,7 +213,7 @@ Pipeline **Claude Code**, **Copilot CLI** ve **Codex CLI** üzerinde native çal
 
 | Araç | Bayrak | Ne kurar |
 |---|---|---|
-| Claude Code | `--claude` (varsayılan) | slash komutları + skill'ler + agent'lar + `PreToolUse` secret-scan hook'u |
+| Claude Code | `--claude` (varsayılan) | slash komutları + skill'ler + agent'lar + üç `PreToolUse` hook'u (secret scan, agent-guard, okuma-boyutu geçidi) |
 | Copilot CLI | `--copilot` | talimatlar + 55 alt-komut skill'i + script'ler |
 | Codex CLI | `--codex` | bir router skill + ref olarak 55 spec + 8 agent TOML + `AGENTS.md` bloğu + `codex mcp add` |
 

package/docs/features.md

@@ -222,6 +222,7 @@ Phase 3 treats the issue-tracker status update as a required step with a post-mu
 ## Safety & Hygiene
 
 - **Pre-Commit Secret Detection** (12 patterns): `PreToolUse` hook scans staged files for API keys/tokens, AWS access keys, private keys, `.env` files, service account JSON. Commit **blocked** if found.
+- **Read-Size Gate** (opt-in, `prefs.global.bulkRead.mode`): a `PreToolUse` hook inspects `Read` and the shell commands that read a file whole. In `observe` it only logs what it would have caught - the baseline you measure before routing anything. In `enforce` a file over `minLines` (default 350) is blocked and delegated to a haiku-rung worker (`bulk-read.sh`), which returns a line-numbered summary so the follow-up is a bounded `Read(offset:limit:)` instead of the whole file; the full text is parked under `.multi-agent/refs/`. The development phase and any file the run has already touched are exempt, because Claude Code's `Edit` requires its own `Read` first.
 - **Build Queue**: All `xcodebuild` calls acquire a lock. Each worktree uses own `-derivedDataPath`. Stale locks auto-clean after 15 min. Non-Xcode builds don't need the lock.
 - **Context Management**: `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=65` - compaction at 65% usage (prevents degradation in 8-phase sessions).
 - **3-Iteration Hard Kill**: Any retry loop stops after 3 attempts, then pauses for user. No infinite loops.

package/install/_codex-agents.mjs

@@ -94,10 +94,10 @@ export function tomlString(s) {
     return JSON.stringify(s);
   }
   if (!s.includes("'''")) {
-    return `'''\n${s}\n'''`;
+    return `'''\n${s}'''`;
   }
   const escaped = s.replace(/\\/g, "\\\\").replace(/"""/g, '\\"\\"\\"');
-  return `"""\n${escaped}\n"""`;
+  return `"""\n${escaped}"""`;
 }
 
 /**

package/install/_dev-only-files.mjs

@@ -59,6 +59,7 @@ const DEV_ONLY_TOOLING = Object.freeze([
   "run-smokes.mjs",
   "scorecard.mjs",
   "lint-skills.mjs",
+  "lint-personas.mjs", // imports install/_codex-agents.mjs, which never ships to scripts/
   "lint-mcp-refs.mjs",
   "check-md-links.mjs",
   "validate-schemas.mjs", // validates the repo's own schema files, needs ajv

package/install/templates/claude-hooks.json

@@ -1,5 +1,5 @@
 {
-  "_readme": "Recommended Claude Code hooks for multi-agent-pipeline. Merge the `hooks` object into your ~/.claude/settings.json to make these deterministic, OS-enforced PreToolUse gates real (exit 2 blocks the tool call) rather than prompt-level hopes. Two gates ship here: (1) a staged-diff secret scan on git commit (pre-commit-check.sh); (2) an agent-guard on git commit + git push (agent-guard.sh) that blocks AI/assistant attribution in commit messages and force-push to a protected branch (main/master/develop). Both scripts are self-contained, fail-open on internal error, never execute the inspected command, and need no run-specific arguments, which is why they are naturally PreToolUse hooks. The other deterministic gates (evidence, consensus, intent, learnings) take run-specific arguments and are phase-enforced by the pipeline instead. multi-agent:setup offers to merge this block.",
+  "_readme": "Recommended Claude Code hooks for multi-agent-pipeline. Merge the `hooks` object into your ~/.claude/settings.json to make these deterministic, OS-enforced PreToolUse gates real (exit 2 blocks the tool call) rather than prompt-level hopes. Three gates ship here: (1) a staged-diff secret scan on git commit (pre-commit-check.sh); (2) an agent-guard on git commit + git push (agent-guard.sh) that blocks AI/assistant attribution in commit messages and force-push to a protected branch (main/master/develop); (3) a read-size gate on Read and Bash (check-read-size.sh), which inspects Read plus the shell commands that read a file whole (cat/head/tail/sed) and returns immediately for everything else, which routes an oversized read to a cheap worker instead of the caller's own rung. The first two inspect what a run WRITES; the third inspects what it pays to READ, and it is inert until `prefs.global.bulkRead.mode` is set to observe or enforce - so merging this block changes nothing until you opt in. All three are self-contained, fail-open on internal error, never execute the inspected command, and need no run-specific arguments, which is why they are naturally PreToolUse hooks. The other deterministic gates (evidence, consensus, intent, learnings) take run-specific arguments and are phase-enforced by the pipeline instead. multi-agent:setup offers to merge this block.",
   "hooks": {
     "PreToolUse": [
       {
@@ -29,6 +29,17 @@
             "statusMessage": "Checking push safety..."
           }
         ]
+      },
+      {
+        "matcher": "Read|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash $HOME/.claude/scripts/check-read-size.sh",
+            "timeout": 10,
+            "statusMessage": "Checking read size..."
+          }
+        ]
       }
     ]
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "16.19.0",
+  "version": "16.21.0",
   "description": "8-phase AI development pipeline with full orchestration on Claude Code, Copilot CLI and Codex CLI. Analysis, planning, TDD, CLI-aware parallel review with consensus surfacing + Fable triage, default-FAIL evidence gates, secret + intent guards, per-phase cost ledger, persistent learnings memory, wiki generation, commit automation. Token-preserving uninstall.",
   "type": "module",
   "main": "index.js",
@@ -14,11 +14,11 @@
   },
   "scripts": {
     "start": "node index.js",
-    "test": "npm run format:check && node --test test/*.test.mjs && node pipeline/scripts/run-smokes.mjs && node pipeline/scripts/lint-skills.mjs && node pipeline/scripts/lint-mcp-refs.mjs && node pipeline/scripts/eval-triage.mjs && node pipeline/scripts/eval-golden-tasks.mjs && node pipeline/scripts/eval-intent.mjs && node pipeline/scripts/eval-recall.mjs && node pipeline/scripts/validate-schemas.mjs && node pipeline/scripts/validate-prefs.mjs && node pipeline/scripts/scorecard.mjs",
+    "test": "npm run format:check && node --test test/*.test.mjs && node pipeline/scripts/run-smokes.mjs && node pipeline/scripts/lint-skills.mjs && node pipeline/scripts/lint-personas.mjs && node pipeline/scripts/lint-mcp-refs.mjs && node pipeline/scripts/eval-triage.mjs && node pipeline/scripts/eval-golden-tasks.mjs && node pipeline/scripts/eval-intent.mjs && node pipeline/scripts/eval-recall.mjs && node pipeline/scripts/validate-schemas.mjs && node pipeline/scripts/validate-prefs.mjs && node pipeline/scripts/scorecard.mjs",
     "test:unit": "node --test test/*.test.mjs",
     "test:smoke": "node pipeline/scripts/run-smokes.mjs",
     "lint:skills": "node pipeline/scripts/lint-skills.mjs",
-    "test:quick": "node --test test/*.test.mjs && node pipeline/scripts/lint-skills.mjs && node pipeline/scripts/lint-mcp-refs.mjs",
+    "test:quick": "node --test test/*.test.mjs && node pipeline/scripts/lint-skills.mjs && node pipeline/scripts/lint-personas.mjs && node pipeline/scripts/lint-mcp-refs.mjs",
     "test:coverage": "c8 --clean --reporter=none node --test test/*.test.mjs && c8 --clean=false --check-coverage --reporter=text --reporter=lcov node pipeline/scripts/run-smokes.mjs",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
@@ -85,6 +85,7 @@
     "!pipeline/scripts/eval-*.mjs",
     "!pipeline/scripts/scorecard.mjs",
     "!pipeline/scripts/lint-skills.mjs",
+    "!pipeline/scripts/lint-personas.mjs",
     "!pipeline/scripts/lint-mcp-refs.mjs",
     "!pipeline/scripts/check-md-links.mjs",
     "!pipeline/scripts/validate-schemas.mjs",

package/pipeline/agents/android-architect.md

@@ -1,4 +1,5 @@
 ---
+name: android-architect
 description: Android architect  -  evaluates design decisions, patterns, and module structure
 model: fable
 preferredModel: fable

package/pipeline/agents/backend-architect.md

@@ -1,4 +1,5 @@
 ---
+name: backend-architect
 description: Backend architect  -  evaluates API design, data modeling, and system architecture
 model: fable
 preferredModel: fable

package/pipeline/agents/bulk-reader.md

@@ -0,0 +1,57 @@
+---
+name: bulk-reader
+description: "Reads ONE large file and returns a structured, line-numbered summary so the full text never enters the caller's context. Dispatched by bulk-read.sh when check-read-size.sh blocks a whole-file read. Haiku by default; a delegated read costs a fraction of a cent."
+model: haiku
+preferredModel: haiku
+modelRationale: "Reading a file and reporting what is in it is extraction, not judgement - the task has a single source, a fixed output shape, and no reasoning chain. Haiku is the right rung and the whole point: the saving is the difference between this rung and the caller's. A worker that reasons is the wrong tool here, and the contract below forbids it explicitly, because a cheap rung's opinion about code is worth less than nothing."
+---
+
+# Bulk Reader
+
+You are given ONE file and ONE question. You return ONE JSON object and nothing
+else: no prose before it, no markdown fence around it, no commentary after it.
+
+The file arrives with its lines numbered. Those numbers are the file's own, so a
+number you report is a number the caller can open directly.
+
+## Rules
+
+- **Every claim carries the line numbers it comes from.** A claim without them is
+  not usable - the caller cannot open it, cannot check it, and ends up reading
+  the file itself, having now paid for it twice. If you cannot cite it, do not
+  claim it.
+- **You describe what IS in the file.** You do not review it, do not judge its
+  quality, do not propose changes, and do not name defects. Judgement about code
+  is the caller's; you are here so the caller has something to judge.
+- **You never guess.** If the question cannot be answered from this file, say
+  exactly that in `answer` and return an empty `regions`. A confident wrong
+  summary is the one outcome worse than the caller paying full price for the
+  file, because nothing downstream can tell it is wrong.
+- **`regions` are where a reader should look next**, most important first, at
+  most 8. Each one is a span worth opening on its own - not the whole file
+  restated as one region.
+- If you did not see the whole file, set `truncated: true`. Do not summarize a
+  part as though it were the whole.
+
+## Output Format
+
+```json
+{
+  "answer": "<direct answer to the question, or why this file cannot answer it>",
+  "summary": "<what this file is and does, 3-6 sentences>",
+  "symbols": [{"name": "<declaration>", "kind": "type|func|var|extension|other", "line": 42}],
+  "regions": [{"why": "<what a reader finds here>", "start": 120, "end": 180}],
+  "truncated": false
+}
+```
+
+Contract: `pipeline/schemas/bulk-read-output.schema.json`.
+
+## What this agent does NOT do
+
+- Does NOT review, rate, or critique the code it reads.
+- Does NOT read a second file, follow an import, or look anything up.
+- Does NOT answer from prior knowledge of a framework - only from this file.
+- Does NOT edit anything. It has no write path by design: a summary has no
+  reliable basis for an edit, which is why the caller comes back with a bounded
+  read before changing a line.

package/pipeline/agents/code-reviewer.md

@@ -1,4 +1,5 @@
 ---
+name: code-reviewer
 description: "Code reviewer for multi-agent Phase 4  -  security, architecture, quality, performance. Default model is fable (opus is the first fallback); Phase 4 orchestrator overrides to sonnet for Reviewer 3."
 model: fable
 preferredModel: fable

package/pipeline/agents/dev-critic.md

@@ -1,4 +1,5 @@
 ---
+name: dev-critic
 description: "Phase 3.5 evaluator  -  runs after Dev's last edit, before Phase 4. Verifies build/test/checklist gates; returns pass | fix-list. Sonnet by default; Phase 3 orchestrator may override."
 model: sonnet
 preferredModel: sonnet
@@ -79,7 +80,7 @@ Apply the platform checklist verbatim. **Cite the rule file + line/section** so
 - **Max 2 critic iterations.** Generator gets feedback, edits, you re-evaluate. If round 2 still fails gates, **escalate**: return `escalate: true` and let the orchestrator decide (pause user / abort / continue with known failures).
 - Round 1 budget: full critic pass with all gates + checklist.
 - Round 2 budget: ONLY re-check the items that failed round 1. Don't re-flag what the generator fixed.
-- Never add new findings in round 2 that weren't in round 1's output  -  that's scope creep, not iteration.
+- Never add new findings in round 2 that weren't in round 1's output  -  that's scope creep, not iteration. Round-2 findings carry the round-1 `fingerprint` (`finding-fingerprint.mjs annotate --kind dev-critic`); a round-2 finding with no round-1 fingerprint is the scope creep this rule forbids.
 
 ## Output Format
 

package/pipeline/agents/explorer.md

@@ -1,4 +1,5 @@
 ---
+name: explorer
 description: "Codebase explorer agent for multi-agent Phase 1  -  scans project structure, patterns, and impact areas"
 model: sonnet
 preferredModel: sonnet

package/pipeline/agents/ios-architect.md

@@ -1,4 +1,5 @@
 ---
+name: ios-architect
 description: iOS architect  -  evaluates design decisions, patterns, and module structure
 model: fable
 preferredModel: fable

package/pipeline/agents/security-auditor.md

@@ -1,4 +1,5 @@
 ---
+name: security-auditor
 description: Security specialist  -  analyzes code for vulnerabilities and compliance issues
 model: opus
 preferredModel: opus

package/pipeline/agents/task-clarifier.md

@@ -1,4 +1,5 @@
 ---
+name: task-clarifier
 description: "Phase 0 Step 9 task ambiguity scorer  -  reads task description, emits clarity score (0-10) and up to N clarifying questions. Haiku by default; cost stays under 1¢ per call."
 model: haiku
 preferredModel: haiku

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

@@ -47,5 +47,9 @@ Lets you switch to the task branch for manual testing in Xcode before the PR is
 5. **Wait for the user's reply**
 
 6. **Branch on the answer**:
-   - **OK** → `phase-tracker.sh update 5 completed` + `phase-tracker.sh meta 5 Result "local test passed (user)"`, recreate the worktree, continue to Phase 6
+   - **OK** → first write `$WORKTREE/.pipeline/manual-test.json` (one entry per acceptance criterion from the analysis doc test plan, the plan tasks, or the user's own words):
+     ```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"}
+     ```
+     then run `node $HOME/.claude/scripts/evidence-gate.mjs --claim manual --status passed --evidence "$WORKTREE/.pipeline/manual-test.json"`. Exit 1 means the "ok" is not accepted: name the criterion that is missing evidence and wait for the next reply. Exit 0 → `phase-tracker.sh update 5 completed` + `phase-tracker.sh meta 5 Result "local test passed (user)"`, recreate the worktree, continue to Phase 6. Full contract: `$HOME/.claude/multi-agent-refs/phases/phase-5-test.md` step 5.
    - **Fix needed** → `phase-tracker.sh now 5 "applying fix: <summary>"`, recreate the worktree, apply the fix

package/pipeline/commands/multi-agent/resume/SKILL.md

@@ -23,6 +23,7 @@ Resume a paused or failed task from the last successful phase.
    - `currentPhase`  -  last completed phase
    - `status`  -  `paused` | `failed` | `in_progress`
    - `haltReason`  -  if set, show it so the user knows why the run stopped; clear it on successful re-entry
+   - `circuitBreaker`  -  if `tripped`, show `trigger` + `detail`, then set `tripped: false` and keep `counters`; if the same trigger fires again at the next checkpoint the breaker re-trips (no silent bypass)
    - `autopilot`  -  preserve the mode
 
 3. **Load context**  -  rebuild working context from durable artifacts, never from conversation memory:

package/pipeline/commands/multi-agent/setup/SKILL.md

@@ -813,13 +813,15 @@ To set up multi-agent on a new machine:
 
 All tokens are optional in the sense that every service can be answered with Skip  -  but the ASKING is not optional: the Step 3 sequential loop still walks every missing service one by one (token → author → host). Phase 0 re-asks at runtime only for tokens the user skipped here.
 
-### Step 8  -  Enforcement hook (optional, Claude Code)
+### Step 8  -  Enforcement hooks (optional, Claude Code)
 
-Offer to make the secret scan a HARD pre-commit gate (a non-zero exit blocks the commit) instead of an advisory step. The recommended block ships at `install/templates/claude-hooks.json`.
+Offer to make the three hookable gates HARD (a non-zero exit blocks the tool call). The block ships at `install/templates/claude-hooks.json`: secret scan, agent-guard, read-size gate.
+
+- Ask (picker): "Install the pipeline's PreToolUse gates into `~/.claude/settings.json`?" Default Yes.
+- On Yes, deep-merge the template's `hooks.PreToolUse` (preserve existing hooks; never duplicate a matcher already calling the same script).
+- Say what the merge does NOT cover: only these three need no run-specific arguments, so only these three are hookable; the rest are phase-enforced.
+- Say what it does not turn on: the read-size gate is inert until `prefs.global.bulkRead.mode` is set. Recommend `observe` first. Why, and the Phase 3 exemption: `$HOME/.claude/multi-agent-refs/picker-contract.md`.
 
-- Ask (picker): "Install the pre-commit secret-scan hook into `~/.claude/settings.json`?" Default Yes.
-- On Yes, deep-merge the template's `hooks.PreToolUse` into the user's `settings.json` (preserve any existing hooks; do not duplicate a matcher that already calls `pre-commit-check.sh`).
-- Honest note to show: this is the only deterministic gate that is OS-enforceable as a hook (it needs no run-specific arguments). The evidence / consensus / intent / learnings gates are invoked by the pipeline phases with per-run arguments, so they are enforced by the phase contract + the installed gate scripts, not by a hook.
 ### Step 9  -  Default stack plugin enablement
 
 Stack skills ship as versioned plugins in the `{owner}/multi-agent-plugins` marketplace. On first setup, wire the stack so the pipeline works out of the box.

package/pipeline/commands/multi-agent/store-ready/SKILL.md

@@ -218,10 +218,22 @@ is a guess the user must be able to correct.
   Use the fallback only when the tool is genuinely absent, and say in the report
   which path ran  -  a rule set that silently differed between two invocations is
   worse than a missing gate.
+
+  Then, whichever path ran, count `<archive>/dSYMs/*.dSYM`. Zero is a blocking
+  finding: `[SYMBOLS] archive carries no dSYM; crash reports will not symbolicate`,
+  with the hint `DEBUG_INFORMATION_FORMAT = dwarf-with-dsym` for the Release
+  configuration. This check runs from the package alone and does not need the
+  MCP tool.
 - **Android**: `android_apk_audit` on the artifact, plus the
   `google-play-compliance` skill's 21 rules  -  `bundletool validate` and manifest
   dump, `aapt2 dump badging`, `apksigner verify`, ABI / native scan.
 
+  Then, when the module has `minifyEnabled true` and the bundle build produced no
+  `mapping.txt`, raise the same class of blocking finding:
+  `[SYMBOLS] minified bundle carries no mapping.txt; crash reports will not
+  deobfuscate`. This check reads the module config and the build output alone
+  and does not need the MCP tool.
+
 `error` findings are blocking; `warning` is advisory. Group by severity and keep
 each finding's ITMS / Play policy code  -  Gate 2 may return the same code on iOS,
 and seeing it in both places tells the user it is real rather than a heuristic.
@@ -259,6 +271,7 @@ that catches what a human reviewer rejects, so it reads source, not the binary.
 | Privacy policy | reachable in-app and in the metadata |
 | IAP | anything unlocking features goes through StoreKit, with no external purchase path |
 | Sign in with Apple | present when a third-party social login is offered |
+| Crash symbolication | a dSYM upload step exists: an Xcode run-script calling `upload-symbols`, or a Crashlytics / Sentry / Datadog upload in CI |
 
 **Android**  -  `ai-android-toolkit:play-store-review`:
 
@@ -272,6 +285,7 @@ that catches what a human reviewer rejects, so it reads source, not the binary.
 | Account deletion | if the app creates accounts, an in-app deletion path exists, plus the web deletion URL Play requires |
 | Content rating | the questionnaire answers match the app's actual content |
 | Signing | Play App Signing configured, upload key distinct from the app signing key |
+| Crash symbolication | a `mapping.txt` upload exists: the Firebase Crashlytics Gradle plugin, or the Play App Bundle deobfuscation file |
 
 For each: `pass` / `fail` / `not-applicable` with the evidence path that justifies
 it. `not-applicable` needs a reason  -  an unexamined area is not a pass.
@@ -303,6 +317,12 @@ Advisory
 
 Not run
   Gate 2: no local Play validator  -  authoritative check is server-side only
+
+Before rollout (human inputs, not verified)
+  Phased rollout: <1% -> 10% -> 50% -> 100% | full>
+  Halt thresholds: crash-free < 99.5% (iOS, Android) or ANR > 0.47% (Android) => pause the rollout
+  Rollback / forward-fix owner: <name>
+  Forward-fix plan: <one line>
 ```
 
 Rules for the report:
@@ -311,6 +331,8 @@ Rules for the report:
   skip. An Android run therefore reads `2 of 3 gates cleared, 1 skipped` at best.
 - Every blocking finding carries a file path or a store code. A finding the user
   cannot act on is noise.
+- The `Before rollout` block is filled by a human, never inferred. When it is
+  left unfilled the verdict line gains the suffix `, rollout plan missing`.
 - Humanize via `--lang en` by default (`promptLanguage` is locked to `"en"`); pass
   `--lang=tr` explicitly to opt into Turkish.
 - No AI or assistant attribution anywhere, per

package/pipeline/commands/sim-test.md

@@ -253,16 +253,18 @@ Then output full report:
 - **Steps**: 1. Open app -> 2. Tap {X} -> 3. Observe {issue}
 - **Expected**: {correct behavior}
 - **Actual**: {what's wrong}
+- **Spec**: "<quoted acceptance criterion from the analysis doc Section 15 / 20, or: no spec, model expectation>" (<source>)
+- **Evidence**: before=<png path> after=<png path>
 
 ### BUG-2: ...
 
 ## Screens Visited ({N})
 
-| #   | Screen   | Light | Dark  | Large Text | Bugs |
-| --- | -------- | ----- | ----- | ---------- | ---- |
-| 1   | Home     | ok    | BUG-1 | ok         | 1    |
-| 2   | Login    | ok    | ok    | BUG-2      | 1    |
-| 3   | Settings | ok    | ok    | ok         | 0    |
+| #   | Screen   | Light | Dark  | Large Text | Bugs | Evidence |
+| --- | -------- | ----- | ----- | ---------- | ---- | -------- |
+| 1   | Home     | ok    | BUG-1 | ok         | 1    | 3        |
+| 2   | Login    | ok    | ok    | BUG-2      | 1    | 4        |
+| 3   | Settings | ok    | ok    | ok         | 0    | 2        |
 
 ## Summary
 
@@ -272,8 +274,11 @@ Then output full report:
 - Critical: {N} | Major: {N} | Minor: {N}
 - Accessibility audit (accessibility scenario): {N} audited, {N} not audited (reason per screen), deep pass: {ran / skipped: reason}
 - Crashes (full scenario): {N} during this run
+- Production readiness: FAILED | NEEDS WORK | READY
 ```
 
+`Evidence` in a bug block is the captures already written to files in Step 4: a tap-driven finding needs both `before` and `after`, a static finding (layout, contrast, dark mode, large text) needs `after` only. The `Evidence` column in Screens Visited is the count of screenshot files written for that screen. Production readiness defaults to FAILED; it is NEEDS WORK when only Minor bugs remain, and READY only when there are zero Critical / Major bugs and every planned screen was visited.
+
 Save to: `$HOME/.claude/logs/sim-test/{bundle_id}/{timestamp}.md`
 
 ### Step 7  -  Fix Offer

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

@@ -14,14 +14,15 @@ The PR description targets code reviewers  -  it stays technical. Every adapter
 | 2 | `changes` | `## Değişiklikler` | `## Changes` | always |
 | 3 | `architecture` | `## Mimari Kararlar` | `## Architecture Decisions` | when a non-trivial design choice was made |
 | 4 | `verification` | `## Doğrulama` | `## Verification` | always |
-| 5 | `dependencies` | `## Bağımlılıklar` | `## Dependencies` | when deps added/removed/bumped |
-| 6 | `related` | `## İlgili` | `## Related` | always (Jira/issue ref; never `Closes/Fixes`) |
+| 5 | `risk` | `## Risk ve Güvenlik` | `## Risk and Security` | when `state.diffRisk.signals` carries a high-stakes signal (`security_path`, `migration`, `public_api`, `no_test_change`, `test_lines_removed`) |
+| 6 | `dependencies` | `## Bağımlılıklar` | `## Dependencies` | when deps added/removed/bumped |
+| 7 | `related` | `## İlgili` | `## Related` | always (Jira/issue ref; never `Closes/Fixes`) |
 
 ### Section content rules
 
 **`summary`**  -  1-3 sentences in `outputLanguage`. The "why" of the change. Past tense, no marketing voice. Code identifiers stay verbatim.
 
-**`changes`**  -  bullet list, one item per logically distinct change. Each bullet starts with the touched component and ends with a one-line "what". Use the stack's native file extensions / module paths  -  the example below shows the **shape**, not a stack lock-in:
+**`changes`**  -  bullet list, one item per logically distinct change. Each bullet starts with the touched component and ends with a one-line "what". The source is `$WORKTREE/.pipeline/scope-check.json` `files[].reason` (Phase 3 Step 3.7): a file the dev could not justify there is a file this list cannot describe either, so the bullet quotes the gate output instead of inventing a reason. Use the stack's native file extensions / module paths  -  the example below shows the **shape**, not a stack lock-in:
 
 ```markdown
 ## Changes
@@ -50,6 +51,17 @@ Skeleton (the adapter fills the body with the actual stack-appropriate lines at
 
 Multi-repo PRs (one PR per repo) emit verification commands for that repo's stack only  -  never mix iOS + Android commands into a single PR body.
 
+**`risk`**  -  only when `state.diffRisk.signals` (Phase 4 Step 1.75) contains a high-stakes signal. Four fixed lines, each answered, never left as a placeholder; the source is Phase 1 `touchedAreas` plus the signals themselves, and when a signal is present the absence of this section is a Phase 6 Step 3 blocker:
+
+```markdown
+## Risk and Security
+
+- Auth flow touched: yes | no
+- Secret handling changed: yes | no
+- Data migration: yes | no
+- Rollback: feature flag <name> | git revert <sha> | none, and why
+```
+
 **`dependencies`**  -  only when `Package.swift` / `Podfile` / `build.gradle` / `package.json` changed. Each entry: `package@old → new  -  reason`.
 
 **`related`**  -  flat list, plain text. Examples:
@@ -61,15 +73,21 @@ Multi-repo PRs (one PR per repo) emit verification commands for that repo's stac
 - Issue: #123
 - Confluence: <page-url> (if work referenced a spec)
 - Figma: <design-url> (if work referenced a design)
+
+Follow-ups not done in this PR:
+- <scope-check.json notDone[].what>  -  <why>
+- <deferred triage finding>  -  <triage reason>
 ```
 
+The follow-up list is present only when `scope-check.json` `notDone[]` or the final triage `deferred[]` is non-empty; the two sources merge into one list.
+
 Never use `Closes #N`, `Fixes #N`, `Resolves PROJ-X`. Issues require 4-approval close, the auto-close keywords break that contract.
 
 ### Assembly order (per run)
 
 ```
 1. Read agent-state.json (taskId, contextLinks, identity, language).
-2. Build section bodies in markdown  -  summary first, then in the table order, skipping conditional sections that don't apply.
+2. Build section bodies in markdown  -  summary first, then in the table order, skipping conditional sections that don't apply. Section order is fixed: `summary` → `changes` → `architecture` (cond.) → `verification` → `risk` (cond.) → `dependencies` (cond.) → `related`.
 3. Run the assembled body through the `humanizer` skill.
 4. Apply Multi-repo cross-links (## Related PRs prepend when projects.length > 1).
 5. Dispatch per the Behaviour-by-remote table.

package/pipeline/multi-agent-refs/features/autopilot-circuit-breaker.md

@@ -2,7 +2,7 @@
 
 **Pattern**: autopilot runs with zero interaction, which is exactly when a silent failure loop is most expensive  -  an agent can burn a budget re-attempting the same broken fix, or thrash between two phases, with nobody watching. A circuit-breaker converts "keep going no matter what" into "keep going until a defined unsafe condition, then halt and hand back to the user." This is the sanctioned autopilot pause (same class as the Phase 7 channels pause): the run stops, records why, and waits for an explicit `resume`.
 
-**Gated by `prefs.global.autopilotCircuitBreaker`** (default: enabled; thresholds tunable). Halting is always safe, so the breaker itself defaults on. Disable per-run only with an explicit override. Complements, does not replace, the existing autopilot safety rules (build-fail max 3 retries, Phase 4 blocking-finding rework, destructive-op confirmations).
+**Gated by `prefs.global.autopilotCircuitBreaker`** (`enabled` default true, `identicalFindingCycles` default 2, `maxReworkCycles` default 3; `schemas/prefs.schema.json`). Halting is always safe, so the breaker itself defaults on. Disable per-run only with an explicit override. Complements, does not replace, the existing autopilot safety rules (build-fail max 3 retries, Phase 4 blocking-finding rework, destructive-op confirmations).
 
 ## Trip conditions
 
@@ -18,12 +18,25 @@ Any one trips the breaker. All are evaluated from `agent-state.json` + telemetry
 
 Trigger 2 is the key addition over the plain build-retry cap: a build can "fail differently" three times (legitimate iteration) or "fail identically" twice (stuck). Only the identical-failure case is a stall; the retry cap catches the rest.
 
+## Wiring status
+
+| Trigger | Evaluated by | Status |
+|---|---|---|
+| 2, finding half | `review-delta.mjs` exit 3 at Phase 4 Step 3.8: a blocking/important finding whose `fingerprint` (finding-fingerprint.mjs) stays in the accepted set for `identicalFindingCycles` consecutive rounds | **code** (v16.20.0) |
+| 3 | Phase 3 re-entry item 6: the `retryCount === 3` hard-kill records the trip | **code** (v16.20.0) |
+| 2, build-error half | needs a build-log signature normaliser | documented behaviour, no script yet |
+| 1 | needs checkpoint-to-checkpoint artifact diffing | documented behaviour, no script yet |
+| 4 | belongs to `cost-budget-check.mjs` | documented behaviour, no script yet |
+| 5 | Phase 6 push | documented behaviour, no script yet |
+
+State shape: `state.circuitBreaker = {tripped, trigger, detail, checkpoint: {phase, step, iteration}, trippedAt, counters: {identicalFindingCycles, reworkCycles}}` (`schemas/agent-state.schema.json`). The per-round classification the finding half reads lives in `state.reviewIterations[i].delta` (`new`, `stillPresent`, `resolved`, `downgraded`, `recurrence`, `plateau`). `smoke-autopilot-circuit-breaker.sh` asserts the schema fields, the scripts and the phase wiring, not only this prose.
+
 ## Action on trip
 
 1. Set `agent-state.json.circuitBreaker = {tripped: true, trigger: <#>, detail, checkpoint}` and flip `autopilot` handling to paused (the run does not continue unattended).
 2. Emit one actionable line per the progress contract: what tripped, the evidence (error signature / cycle count / spend vs ceiling), and the single next action (`resume #N` after a fix, or `kill #N`).
 3. Never auto-resolve the underlying cause  -  no force-anything, no conflict auto-merge, no budget self-raise. The breaker hands control back; it does not paper over the problem.
-4. `resume #N` clears the tripped flag and continues from the recorded checkpoint. If the same trigger fires again immediately, the breaker re-trips (no silent bypass).
+4. `resume #N` clears `circuitBreaker.tripped` (keeping `counters`) and continues from the recorded checkpoint. If the same trigger fires again immediately, the breaker re-trips (no silent bypass).
 
 ## Why this is the right autopilot exception