@mmerterden/multi-agent-pipeline 16.20.0 → 16.21.0

package/CHANGELOG.md

@@ -16,6 +16,30 @@ 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.

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/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.20.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",

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/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/multi-agent-refs/picker-contract.md

@@ -81,6 +81,6 @@ In autopilot, `ask_choice` resolves to `default` (or the safe first option) with
 
 ## Deterministic gates note
 
-Claude Code's `PreToolUse` exit-2 hooks are the HARD blocking gates. Two ship, both needing no run-specific arguments so they are naturally hookable: (1) `pre-commit-check.sh` scans the staged diff on every `git commit` and blocks on a detected secret; (2) `agent-guard.sh` runs on `git commit` + `git push` and blocks AI/assistant attribution in a commit message and force-push to a protected branch (main/master/develop). Both are self-contained, fail-open on internal error, and never execute the inspected command. The recommended hook block ships at `install/templates/claude-hooks.json`; `multi-agent:setup` offers to merge it into `~/.claude/settings.json`. The other deterministic gates (evidence, consensus, intent, learnings) are invoked by the pipeline phases with per-run arguments (a build-log path, the triage JSON, the free-text input), so they are phase-enforced by contract, not OS-hookable.
+Claude Code's `PreToolUse` exit-2 hooks are the HARD blocking gates. Three ship, none needing run-specific arguments so they are naturally hookable: (1) `pre-commit-check.sh` scans the staged diff on every `git commit` and blocks on a detected secret; (2) `agent-guard.sh` runs on `git commit` + `git push` and blocks AI/assistant attribution in a commit message and force-push to a protected branch (main/master/develop); (3) `check-read-size.sh` runs on `Read` and on the shell commands that read a file whole, and routes an oversized read to a cheap worker (`bulk-read.sh`) 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 `bulkRead.mode` is set to `observe` or `enforce`, so merging the block changes nothing until the user opts in. Its `observe` mode blocks nothing and only logs, which is how the baseline is measured before anything is routed. All three are self-contained, fail-open on internal error, and never execute the inspected command. The recommended hook block ships at `install/templates/claude-hooks.json`; `multi-agent:setup` offers to merge it into `~/.claude/settings.json`. The other deterministic gates (evidence, consensus, intent, learnings) are invoked by the pipeline phases with per-run arguments (a build-log path, the triage JSON, the free-text input), so they are phase-enforced by contract, not OS-hookable.
 
 Copilot CLI has no `PreToolUse` equivalent, so the secret scan there is workflow-enforced (run as a phase step, not OS-blocked) plus a CI smoke-gate step.

package/pipeline/schemas/bulk-read-output.schema.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://example.com/pipeline/bulk-read-output.schema.json",
+  "title": "Bulk Read Output",
+  "description": "Schema for the bulk-reader worker's answer. Source: pipeline/agents/bulk-reader.md, invoked by pipeline/scripts/bulk-read.sh when check-read-size.sh blocks a whole-file read. Every positional field is a LINE NUMBER in the file as given to the worker, because a summary the caller cannot open is a summary the caller will pay to replace.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["summary"],
+  "properties": {
+    "answer": {
+      "type": "string",
+      "description": "Direct answer to the question the caller asked, or a plain statement that this file cannot answer it. Never a guess  -  an unanswerable question is reported, not filled in."
+    },
+    "summary": {
+      "type": "string",
+      "description": "What the file is and does, 3-6 sentences. Descriptive only: no review, no judgement, no proposed change."
+    },
+    "symbols": {
+      "type": "array",
+      "description": "Top-level declarations the file contains, in file order.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "line"],
+        "properties": {
+          "name": { "type": "string" },
+          "kind": { "type": "string", "enum": ["type", "func", "var", "extension", "other"] },
+          "line": { "type": "integer", "minimum": 1 }
+        }
+      }
+    },
+    "regions": {
+      "type": "array",
+      "maxItems": 8,
+      "description": "Spans worth opening next, most important first. The intended use is a bounded Read(offset:limit:) over one of these, which is both cheaper than the whole file and exact  -  and which the read gate allows through.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["start", "end"],
+        "properties": {
+          "why": { "type": "string", "description": "What a reader finds in this span." },
+          "start": { "type": "integer", "minimum": 1 },
+          "end": { "type": "integer", "minimum": 1 }
+        }
+      }
+    },
+    "truncated": {
+      "type": "boolean",
+      "description": "True when the worker did not see the whole file. A partial read summarized as a whole one is the failure this flag exists to make visible."
+    }
+  }
+}

package/pipeline/schemas/prefs.schema.json

@@ -365,7 +365,7 @@
         },
         "multiRepoIntegrationHosts": {
           "type": "array",
-          "description": "v5.6.0+. Learn-once registry of host projects that build together with a multi-repo combo (codegen producer → consumer + host integration project). Pipeline checks this registry in Phase 6 before commit; on match, auto-runs the host build. On miss for a ≥2-repo task, prompts the user once and persists the answer. See refs/multi-repo-integration-build.md for the full contract.",
+          "description": "v5.6.0+. Learn-once registry of host projects that build together with a multi-repo combo (codegen producer \u2192 consumer + host integration project). Pipeline checks this registry in Phase 6 before commit; on match, auto-runs the host build. On miss for a \u22652-repo task, prompts the user once and persists the answer. See refs/multi-repo-integration-build.md for the full contract.",
           "items": {
             "type": "object",
             "additionalProperties": false,
@@ -653,12 +653,12 @@
         "reportChannels": {
           "type": "object",
           "additionalProperties": false,
-          "description": "v5.7+ - Phase 7 / /multi-agent:channels kanal seçimi default'ları. Multi-select menüde tick'li gelecek kanallar. Her kanal bağımsız boolean. Autopilot Phase 7'de ALWAYS pauses (30-min timeout) - bu değerler sadece menünün önceden seçili halini belirler.",
+          "description": "v5.7+ - Phase 7 / /multi-agent:channels kanal se\u00e7imi default'lar\u0131. Multi-select men\u00fcde tick'li gelecek kanallar. Her kanal ba\u011f\u0131ms\u0131z boolean. Autopilot Phase 7'de ALWAYS pauses (30-min timeout) - bu de\u011ferler sadece men\u00fcn\u00fcn \u00f6nceden se\u00e7ili halini belirler.",
           "properties": {
             "pr": {
               "type": "boolean",
               "default": true,
-              "description": "PR description update (replace/append). Default ON - en yaygın kanal."
+              "description": "PR description update (replace/append). Default ON - en yayg\u0131n kanal."
             },
             "jira": {
               "type": "boolean",
@@ -668,12 +668,12 @@
             "confluence": {
               "type": "boolean",
               "default": false,
-              "description": "Confluence page creation. Default OFF - bir kez parent page seçince LRU'dan öner."
+              "description": "Confluence page creation. Default OFF - bir kez parent page se\u00e7ince LRU'dan \u00f6ner."
             },
             "wiki": {
               "type": "boolean",
               "default": false,
-              "description": "Component wiki pages (Case A scope multi-select). Default OFF - taskType=component + figmaConfig.wiki.enabled gerekli, yoksa menüde greyed out."
+              "description": "Component wiki pages (Case A scope multi-select). Default OFF - taskType=component + figmaConfig.wiki.enabled gerekli, yoksa men\u00fcde greyed out."
             }
           },
           "default": {
@@ -686,32 +686,32 @@
         "reportContent": {
           "type": "object",
           "additionalProperties": false,
-          "description": "v5.7+ - Phase 7 / /multi-agent:channels içerik seçimi default'ları. Multi-select menüde tick'li gelecek content source'ları.",
+          "description": "v5.7+ - Phase 7 / /multi-agent:channels i\u00e7erik se\u00e7imi default'lar\u0131. Multi-select men\u00fcde tick'li gelecek content source'lar\u0131.",
           "properties": {
             "normalAnalysis": {
               "type": "boolean",
               "default": true,
-              "description": "Phase 1+2+4 pipeline log'undan impact summary + risks + architectural decisions (yüksek seviye). Greyed out post-hoc çağrıda pipeline log yoksa."
+              "description": "Phase 1+2+4 pipeline log'undan impact summary + risks + architectural decisions (y\u00fcksek seviye). Greyed out post-hoc \u00e7a\u011fr\u0131da pipeline log yoksa."
             },
             "technicalAnalysis": {
               "type": "boolean",
               "default": false,
-              "description": "Changes (değişen dosyalar gruplanıp ne/neden), Architecture (structural decisions), Dependencies (yeni import/framework/paket). PR body'deki 'Technical Details' bölümünün özeti; user'ın kanal seçimi PR içermediği durumlarda (ör. sadece Jira/Confluence) teknik içerik aktarmak istiyorsa devreye girer. Source: Phase 2 planning + Phase 3 dev log + PR diff stat."
+              "description": "Changes (de\u011fi\u015fen dosyalar gruplan\u0131p ne/neden), Architecture (structural decisions), Dependencies (yeni import/framework/paket). PR body'deki 'Technical Details' b\u00f6l\u00fcm\u00fcn\u00fcn \u00f6zeti; user'\u0131n kanal se\u00e7imi PR i\u00e7ermedi\u011fi durumlarda (\u00f6r. sadece Jira/Confluence) teknik i\u00e7erik aktarmak istiyorsa devreye girer. Source: Phase 2 planning + Phase 3 dev log + PR diff stat."
             },
             "testScenarios": {
               "type": "boolean",
               "default": true,
-              "description": "Precondition / steps / expected tablosu (4-8 satır, user perspective). Pipeline log source."
+              "description": "Precondition / steps / expected tablosu (4-8 sat\u0131r, user perspective). Pipeline log source."
             },
             "autoDiff": {
               "type": "boolean",
               "default": false,
-              "description": "PR diff'ten auto-generate özet (eski enrich behavior - root cause / solution / changed files / test scenarios). PR linked değilse greyed out."
+              "description": "PR diff'ten auto-generate \u00f6zet (eski enrich behavior - root cause / solution / changed files / test scenarios). PR linked de\u011filse greyed out."
             },
             "manualNote": {
               "type": "boolean",
               "default": false,
-              "description": "Serbest metin paragraf (--message / --message-file). Her durumda seçilebilir."
+              "description": "Serbest metin paragraf (--message / --message-file). Her durumda se\u00e7ilebilir."
             },
             "costSummary": {
               "type": "boolean",
@@ -721,7 +721,7 @@
             "workSummary": {
               "type": "boolean",
               "default": false,
-              "description": "v7.1.0+ - Executive 'Work Done' summary block. Distills the whole pipeline run into a single-screen section: task + branch + base + PR number, scope delivered (✅/⏳ per Phase 2 task), changed files with +/- counts (capped at 20 rows), review outcome (accepted/deferred/rejected counts + approved flag), and a one-line phase tick strip (0 Init ✅ · 1 Analysis ✅ · ...). Source: `agent-state.json` + `phase-tracker.json` + `git diff --numstat` between `baseBranch`...HEAD. Consumed by `render-work-summary.sh`. Greyed out if no state file exists for the task. Opt-in - off by default so baseline PR body stays unchanged."
+              "description": "v7.1.0+ - Executive 'Work Done' summary block. Distills the whole pipeline run into a single-screen section: task + branch + base + PR number, scope delivered (\u2705/\u23f3 per Phase 2 task), changed files with +/- counts (capped at 20 rows), review outcome (accepted/deferred/rejected counts + approved flag), and a one-line phase tick strip (0 Init \u2705 \u00b7 1 Analysis \u2705 \u00b7 ...). Source: `agent-state.json` + `phase-tracker.json` + `git diff --numstat` between `baseBranch`...HEAD. Consumed by `render-work-summary.sh`. Greyed out if no state file exists for the task. Opt-in - off by default so baseline PR body stays unchanged."
             }
           },
           "default": {
@@ -739,7 +739,7 @@
           "default": 1800,
           "minimum": 60,
           "maximum": 7200,
-          "description": "v5.7+ - Phase 7'de autopilot always-pause menüsünde kullanıcı cevap vermezse session'ı sonlandırma süresi (saniye). Default 1800 (30 dk). Timeout'ta external delivery aborted, internal capture (agent-log, telemetry, knowledge) yine çalışır, session /multi-agent:resume ile devam ettirilebilir."
+          "description": "v5.7+ - Phase 7'de autopilot always-pause men\u00fcs\u00fcnde kullan\u0131c\u0131 cevap vermezse session'\u0131 sonland\u0131rma s\u00fcresi (saniye). Default 1800 (30 dk). Timeout'ta external delivery aborted, internal capture (agent-log, telemetry, knowledge) yine \u00e7al\u0131\u015f\u0131r, session /multi-agent:resume ile devam ettirilebilir."
         },
         "wikiScope": {
           "type": "array",
@@ -748,7 +748,7 @@
             "enum": ["main", "ios", "screenshots", "index"]
           },
           "default": ["main", "ios", "screenshots", "index"],
-          "description": "v5.7+ - Wiki Case A scope multi-select default'u. Component wiki dispatch'inde hangi artifact'lar yazılacak: main (ana component sayfası), ios (iOS sub-page), screenshots (assets/ klasörü), index (_Sidebar.md + ComponentImplementationStatus.md). Legacy wikiDefault=true → [main,ios,screenshots,index] migration; wikiDefault=false → [] (empty array = Wiki adapter Case B menüsüne düşer)."
+          "description": "v5.7+ - Wiki Case A scope multi-select default'u. Component wiki dispatch'inde hangi artifact'lar yaz\u0131lacak: main (ana component sayfas\u0131), ios (iOS sub-page), screenshots (assets/ klas\u00f6r\u00fc), index (_Sidebar.md + ComponentImplementationStatus.md). Legacy wikiDefault=true \u2192 [main,ios,screenshots,index] migration; wikiDefault=false \u2192 [] (empty array = Wiki adapter Case B men\u00fcs\u00fcne d\u00fc\u015fer)."
         },
         "autoJiraFromGithubIssue": {
           "type": "string",
@@ -831,7 +831,7 @@
         "reviewDisagreementRound": {
           "type": "boolean",
           "default": false,
-          "description": "v6.1.0+ - Phase 4 Step 2.5 rebuttal round. When reviewers disagree (mixed blocker/approved verdict), each reviewer is re-prompted with the others' opposing arguments for one additional round before triage. Lifts signal quality on ambiguous findings at ~1× Step 2 token cost. Off by default - flip for security-critical or release-branch reviews."
+          "description": "v6.1.0+ - Phase 4 Step 2.5 rebuttal round. When reviewers disagree (mixed blocker/approved verdict), each reviewer is re-prompted with the others' opposing arguments for one additional round before triage. Lifts signal quality on ambiguous findings at ~1\u00d7 Step 2 token cost. Off by default - flip for security-critical or release-branch reviews."
         },
         "analysisProfiles": {
           "type": "array",
@@ -1047,7 +1047,7 @@
               "minimum": 0,
               "maximum": 10,
               "default": 6,
-              "description": "Clarity threshold. Score ≥ threshold → proceed silently. Below → questions fire. 6 is the borderline 'the what is clear but the how is fuzzy' line."
+              "description": "Clarity threshold. Score \u2265 threshold \u2192 proceed silently. Below \u2192 questions fire. 6 is the borderline 'the what is clear but the how is fuzzy' line."
             },
             "maxQuestions": {
               "type": "integer",
@@ -1215,7 +1215,7 @@
               "minimum": 30,
               "maximum": 86400,
               "default": 300,
-              "description": "Polling interval for --watch loop. Clamped to ≥30s to stay polite with GitHub rate limits."
+              "description": "Polling interval for --watch loop. Clamped to \u226530s to stay polite with GitHub rate limits."
             },
             "labelFilter": {
               "type": "string",
@@ -1291,7 +1291,7 @@
         "devCritic": {
           "type": "object",
           "additionalProperties": false,
-          "description": "v8.6+ - Phase 3.5 evaluator-optimizer. After the Dev generator's last edit and BEFORE Phase 4 reviewers, dispatch agents/dev-critic.md (Sonnet by default) to run deterministic gates (build/lint/test/secrets) + the platform checklist (rules/*.md). Max 2 critic iterations, then escalate. Catches gate failures and checklist violations that would otherwise burn 2-3 Phase 4 reviewer calls + Opus triage. Off by default - introduces 1× Sonnet call per Dev iteration; flip on for feature work, security-touching paths, or multi-file refactors. Source: Anthropic 'Building Effective Agents' (Dec 2024) evaluator-optimizer pattern.",
+          "description": "v8.6+ - Phase 3.5 evaluator-optimizer. After the Dev generator's last edit and BEFORE Phase 4 reviewers, dispatch agents/dev-critic.md (Sonnet by default) to run deterministic gates (build/lint/test/secrets) + the platform checklist (rules/*.md). Max 2 critic iterations, then escalate. Catches gate failures and checklist violations that would otherwise burn 2-3 Phase 4 reviewer calls + Opus triage. Off by default - introduces 1\u00d7 Sonnet call per Dev iteration; flip on for feature work, security-touching paths, or multi-file refactors. Source: Anthropic 'Building Effective Agents' (Dec 2024) evaluator-optimizer pattern.",
           "properties": {
             "enabled": {
               "type": "boolean",
@@ -1464,6 +1464,61 @@
             "tailLines": 20
           }
         },
+        "bulkRead": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "v16.21+  -  Route a whole-file read that is too big to be worth the caller's rung to a cheap worker instead, and put its line-numbered summary in context rather than the file. The gate is pipeline/scripts/check-read-size.sh (PreToolUse, installed from install/templates/claude-hooks.json); the worker is pipeline/scripts/bulk-read.sh over the bulk-reader persona. Companion to contextOffload, which does the same for tool OUTPUT rather than for reads.",
+          "properties": {
+            "mode": {
+              "type": "string",
+              "enum": ["off", "observe", "enforce"],
+              "default": "off",
+              "description": "off = the hook is a no-op. observe = decide and log every inspected read, block nothing; this is the BASELINE MEASUREMENT, and running it before enforce is what makes a later saving claim checkable. enforce = block a whole-file read over minLines and tell the model to delegate it."
+            },
+            "minLines": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 100000,
+              "default": 350,
+              "description": "Files shorter than this are never inspected. A delegated read costs a round trip measured in tens of seconds, so a small file is cheaper read directly - the threshold is where that trade turns over."
+            },
+            "exemptPhases": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "default": ["3"],
+              "description": "Phases the gate never blocks in. Phase 3 is the shipped default and removing it breaks development: 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. The gate is for phases that read to UNDERSTAND."
+            },
+            "model": {
+              "type": "string",
+              "default": "haiku",
+              "description": "Rung the delegated read runs on. The saving IS the gap between this rung and the caller's, so a worker raised to the caller's own rung saves nothing."
+            },
+            "timeoutSeconds": {
+              "type": "integer",
+              "minimum": 5,
+              "maximum": 600,
+              "default": 60,
+              "description": "Wall-clock budget for one delegated read. On expiry the worker degrades and the caller is told to do a bounded read instead - never left waiting, and never handed an invented summary."
+            },
+            "maxBytes": {
+              "type": "integer",
+              "minimum": 1024,
+              "maximum": 20971520,
+              "default": 1048576,
+              "description": "Ceiling past which a delegated read degrades instead of running. Delegation is not free: at 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 failure mode this feature must never produce. Over the ceiling the caller is told to narrow first (grep, then a bounded read) rather than handed an expensive round trip to a worse answer."
+            }
+          },
+          "default": {
+            "mode": "off",
+            "minLines": 350,
+            "exemptPhases": ["3"],
+            "model": "haiku",
+            "timeoutSeconds": 60,
+            "maxBytes": 1048576
+          }
+        },
         "testGap": {
           "type": "object",
           "additionalProperties": false,
@@ -1506,7 +1561,7 @@
         "autopilotSafetyGate": {
           "type": "boolean",
           "default": true,
-          "description": "v7.0.0+ - Phase 2 autopilot safety classifier. Before autopilot mode consumes the user's approval skip, run `classify-plan-safety.mjs` over the approved plan. If the heuristic score ≥ 50 (e.g. >15 files touched, or security-path touch, or delete-without-test, or schema migration) inject a ONE-TIME pause asking for explicit manual approval - even in autopilot. Default ON because the risk of skipping this gate is asymmetric: a pause on a high-blast-radius plan costs seconds; a silent auto-merge of a bad one costs hours of rollback. Flip to `false` only for tightly-scoped autopilot workflows (e.g. batch figma component iteration) where the task class is known-safe."
+          "description": "v7.0.0+ - Phase 2 autopilot safety classifier. Before autopilot mode consumes the user's approval skip, run `classify-plan-safety.mjs` over the approved plan. If the heuristic score \u2265 50 (e.g. >15 files touched, or security-path touch, or delete-without-test, or schema migration) inject a ONE-TIME pause asking for explicit manual approval - even in autopilot. Default ON because the risk of skipping this gate is asymmetric: a pause on a high-blast-radius plan costs seconds; a silent auto-merge of a bad one costs hours of rollback. Flip to `false` only for tightly-scoped autopilot workflows (e.g. batch figma component iteration) where the task class is known-safe."
         },
         "dynamicSkillLoading": {
           "type": "boolean",

package/pipeline/scripts/bulk-read.sh

@@ -0,0 +1,277 @@
+#!/usr/bin/env bash
+# bulk-read.sh  -  read a large file on the cheap rung and return a summary.
+#
+# The worker behind `check-read-size.sh`. The gate says a file is too big to be
+# worth reading whole at this phase's rung; this is where that read goes instead.
+# The full text reaches a haiku-rung worker, the worker returns a structured
+# summary WITH LINE NUMBERS, and only the summary enters the caller's context.
+#
+# Line numbers are the whole design, not a nicety. A summary without them is a
+# dead end: the caller cannot edit from it, cannot verify it, and ends up reading
+# the file anyway - having now paid twice. With them, the intended next step is a
+# bounded `Read(file, offset:, limit:)` around the region that matters, which is
+# both cheap and exact, and which the gate lets through.
+#
+# Usage:
+#   bulk-read.sh --file <path> [--question "<what you need>"] [--phase N]
+#                [--model <rung>] [--timeout <seconds>] [--json]
+#
+# Output: a human-readable summary on stdout, plus the ref id that buys the full
+# text back. `--json` prints the worker's raw object instead, for a caller that
+# wants to parse it.
+#
+# Degradation is explicit and always safe. No CLI, no auth, a timeout, or a
+# non-JSON answer -> this prints WHY and tells the caller to fall back to a
+# bounded read. It never invents a summary, and it never silently succeeds: a
+# fabricated summary of a file nobody read is the one outcome worse than paying
+# full price for the file.
+#
+# Exit codes: 0 summary produced · 3 degraded (caller should read it directly)
+#             1 usage error.
+
+set -uo pipefail
+
+FILE=""
+QUESTION="Summarize this file so a reader can decide which regions to open."
+PHASE="${MULTI_AGENT_PHASE:-0}"
+MODEL=""
+TIMEOUT=""
+AS_JSON=0
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --file) FILE="${2:?--file needs a value}"; shift 2 ;;
+    --question) QUESTION="${2:?--question needs a value}"; shift 2 ;;
+    --phase) PHASE="${2:?--phase needs a value}"; shift 2 ;;
+    --model) MODEL="${2:?--model needs a value}"; shift 2 ;;
+    --timeout) TIMEOUT="${2:?--timeout needs a value}"; shift 2 ;;
+    --json) AS_JSON=1; shift ;;
+    -h|--help) sed -n '2,30p' "$0"; exit 0 ;;
+    *) echo "bulk-read: unknown argument '$1'" >&2; exit 1 ;;
+  esac
+done
+
+[ -n "$FILE" ] || { echo "bulk-read: --file is required" >&2; exit 1; }
+[ -f "$FILE" ] || { echo "bulk-read: not a readable file: $FILE" >&2; exit 1; }
+
+HERE="$(cd "$(dirname "$0")" 2>/dev/null && pwd || true)"
+
+degrade() {
+  echo "bulk-read: DEGRADED  -  $1" >&2
+  echo "Read the region you need directly instead: Read('$FILE', offset: <n>, limit: <n>)." >&2
+  [ -x "$HERE/log-metric.sh" ] && \
+    "$HERE/log-metric.sh" "${MULTI_AGENT_TASK_ID:-unknown}" "$PHASE" bulk_read.degraded \
+      reason="$1" >/dev/null 2>&1
+  exit 3
+}
+
+# Resolve the three prefs this script honours - `bulkRead.model` (which rung the
+# delegated read runs on), `bulkRead.timeoutSeconds` (how long it may take) and
+# `bulkRead.maxBytes` (the ceiling past which delegation stops being a saving).
+# Same search order and the same positive-integer rule as offload-ref.sh: a zero
+# or a string takes the default rather than silently disabling the control.
+PREF_MODEL=""
+PREF_TIMEOUT=""
+PREF_MAX_BYTES=""
+if command -v jq >/dev/null 2>&1; then
+  for prefs in \
+    "$HOME/.claude/multi-agent-preferences.json" \
+    "$HOME/.config/multi-agent-pipeline/multi-agent-preferences.json" \
+    "$HOME/.claude/preferences.json" \
+    "$HOME/.config/multi-agent-pipeline/preferences.json"
+  do
+    [ -f "$prefs" ] || continue
+    values=$(jq -r '.global.bulkRead // {} | [(.model // ""), (.timeoutSeconds // ""), (.maxBytes // "")] | @tsv' \
+      "$prefs" 2>/dev/null) || true
+    PREF_MODEL=$(printf '%s' "$values" | cut -f1)
+    PREF_TIMEOUT=$(printf '%s' "$values" | cut -f2)
+    PREF_MAX_BYTES=$(printf '%s' "$values" | cut -f3)
+    break
+  done
+fi
+[ -n "$MODEL" ] || MODEL="${PREF_MODEL:-haiku}"
+case "$TIMEOUT" in "" ) TIMEOUT="$PREF_TIMEOUT" ;; esac
+case "$TIMEOUT" in ""|*[!0-9]*|0) TIMEOUT=60 ;; esac
+
+command -v claude >/dev/null 2>&1 || degrade "the claude CLI is not on PATH"
+
+LINES=$(wc -l < "$FILE" | tr -d ' ')
+BYTES=$(wc -c < "$FILE" | tr -d ' ')
+
+# A ceiling, because delegation is not free either. Past some size the worker's
+# own input bill approaches the read it replaced, and a file large enough to
+# strain the worker's window would come back truncated - a partial summary
+# presented as a whole one is exactly what this must never produce. Degrading
+# here hands the caller a cheaper move (grep for the symbol, then read around it)
+# instead of an expensive round trip to a worse answer.
+case "$PREF_MAX_BYTES" in ""|*[!0-9]*|0) MAX_BYTES=1048576 ;; *) MAX_BYTES="$PREF_MAX_BYTES" ;; esac
+if [ "$BYTES" -gt "$MAX_BYTES" ]; then
+  echo "bulk-read: DEGRADED  -  ${FILE} is ${BYTES} bytes, past the ${MAX_BYTES}-byte ceiling" >&2
+  echo "At this size the delegated read costs about what reading it would, and risks a truncated" >&2
+  echo "summary presented as a whole one. Narrow it first: grep for the symbol you need, then" >&2
+  echo "Read('${FILE}', offset: <n>, limit: <n>) around the hit." >&2
+  [ -x "$HERE/log-metric.sh" ] && \
+    "$HERE/log-metric.sh" "${MULTI_AGENT_TASK_ID:-unknown}" "$PHASE" bulk_read.degraded \
+      reason=over-ceiling file_bytes="$BYTES" >/dev/null 2>&1
+  exit 3
+fi
+
+# Measured and accepted, so park the full text before asking anything: the
+# pointer in the summary is then a promise that is already kept. The caller buys the rest back by reading this file - the same
+# contract offload-ref.sh makes for build logs, and the same directory.
+ROOT=$(git rev-parse --show-toplevel 2>/dev/null || true)
+[ -n "$ROOT" ] || ROOT="$PWD"
+REFS_DIR="$ROOT/.multi-agent/refs"
+NODE_ID=""
+if mkdir -p "$REFS_DIR" 2>/dev/null; then
+  GITIGNORE="$ROOT/.multi-agent/.gitignore"
+  if [ ! -f "$GITIGNORE" ]; then
+    printf '# Local run artefacts  -  never commit.\nmemory/\nrefs/\n' > "$GITIGNORE"
+  elif ! grep -q '^refs/$' "$GITIGNORE" 2>/dev/null; then
+    printf 'refs/\n' >> "$GITIGNORE"
+  fi
+  if command -v shasum >/dev/null 2>&1; then
+    DIGEST=$(shasum -a 256 "$FILE" | awk '{print substr($1,1,8)}')
+  elif command -v sha256sum >/dev/null 2>&1; then
+    DIGEST=$(sha256sum "$FILE" | awk '{print substr($1,1,8)}')
+  else
+    DIGEST=$(cksum < "$FILE" | awk '{print $1}')
+  fi
+  SLUG=$(basename "$FILE" | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9' '-' | sed 's/-\{1,\}/-/g; s/^-//; s/-$//')
+  NODE_ID="p${PHASE}-read-${SLUG:-file}-${DIGEST}"
+  cp "$FILE" "$REFS_DIR/${NODE_ID}.txt" 2>/dev/null || NODE_ID=""
+fi
+
+PROMPT_FILE="$(mktemp -t bulk-read.XXXXXX)"
+OUT_FILE="$(mktemp -t bulk-read-out.XXXXXX)"
+trap 'rm -f "$PROMPT_FILE" "$OUT_FILE"' EXIT
+
+# The worker gets numbered lines because every claim it makes has to be
+# addressable afterwards. `nl -ba` numbers blank lines too, so the numbers match
+# the file's own and an offset computed from them is correct.
+# The worker's contract is the bulk-reader PERSONA, loaded from disk rather than
+# restated here. Two copies of the same prompt is the drift this repo keeps
+# catching elsewhere: the copy that gets edited is never the copy that runs.
+PERSONA=""
+for candidate in \
+  "$HOME/.claude/agents/bulk-reader.md" \
+  "$HERE/../agents/bulk-reader.md"
+do
+  [ -f "$candidate" ] && { PERSONA="$candidate"; break; }
+done
+[ -n "$PERSONA" ] || degrade "the bulk-reader persona is not installed"
+
+# The frontmatter is dispatch metadata for the Agent tool, not instruction text;
+# strip it and send the body.
+{
+  awk 'BEGIN{fm=0} /^---$/{fm++; next} fm>=2{print}' "$PERSONA"
+  printf '\n<question>\n%s\n</question>\n\n' "$QUESTION"
+  printf '<file path="%s" lines="%s">\n' "$FILE" "$LINES"
+  nl -ba "$FILE"
+  printf '\n</file>\n'
+} > "$PROMPT_FILE"
+
+START=$(date +%s)
+# `claude -p` reads the prompt from stdin; the model flag names the rung. A
+# non-zero exit, an empty answer and a non-JSON answer are all degradations, and
+# each one names itself rather than falling through to a generic failure.
+# macOS ships no `timeout`; coreutils installs it as `gtimeout`. Naming only the
+# GNU spelling would leave the budget silently unenforced on the platform most of
+# these runs happen on - a pref that does nothing, which is the class
+# smoke-prefs-consumed exists to catch.
+TIMEOUT_BIN=""
+for candidate in timeout gtimeout; do
+  command -v "$candidate" >/dev/null 2>&1 && { TIMEOUT_BIN="$candidate"; break; }
+done
+if [ -n "$TIMEOUT_BIN" ]; then
+  "$TIMEOUT_BIN" "$TIMEOUT" claude -p --model "$MODEL" < "$PROMPT_FILE" > "$OUT_FILE" 2>/dev/null
+  STATUS=$?
+else
+  # No timeout binary: the budget cannot be enforced, so say so rather than
+  # letting the caller believe timeoutSeconds is holding.
+  echo "bulk-read: no timeout binary found; bulkRead.timeoutSeconds is not enforced on this host" >&2
+  claude -p --model "$MODEL" < "$PROMPT_FILE" > "$OUT_FILE" 2>/dev/null
+  STATUS=$?
+fi
+ELAPSED=$(( $(date +%s) - START ))
+
+[ "$STATUS" -eq 124 ] && degrade "the worker did not answer within ${TIMEOUT}s"
+[ "$STATUS" -ne 0 ] && degrade "the worker exited $STATUS"
+[ -s "$OUT_FILE" ] || degrade "the worker returned nothing"
+
+RENDER=$(FILE="$FILE" LINES="$LINES" BYTES="$BYTES" NODE_ID="$NODE_ID" \
+         MODEL="$MODEL" ELAPSED="$ELAPSED" AS_JSON="$AS_JSON" \
+         python3 - "$OUT_FILE" <<'PYEOF'
+import json, os, re, sys
+
+raw = open(sys.argv[1], encoding="utf-8", errors="replace").read()
+try:
+    data = json.loads(raw)
+except Exception:
+    # A worker that wrapped its object in prose or a fence is still usable; a
+    # worker that answered in prose is not, and falls through to the degrade path.
+    m = re.search(r"\{[\s\S]*\}", raw)
+    if not m:
+        sys.exit(7)
+    try:
+        data = json.loads(m.group(0))
+    except Exception:
+        sys.exit(7)
+
+if not isinstance(data, dict) or "summary" not in data:
+    sys.exit(7)
+
+if os.environ.get("AS_JSON") == "1":
+    print(json.dumps(data, indent=2))
+    sys.exit(0)
+
+out = []
+out.append("bulk-read: %s (%s lines, %s bytes) via %s in %ss"
+           % (os.environ["FILE"], os.environ["LINES"], os.environ["BYTES"],
+              os.environ["MODEL"], os.environ["ELAPSED"]))
+answer = (data.get("answer") or "").strip()
+if answer:
+    out.append("")
+    out.append("ANSWER: " + answer)
+out.append("")
+out.append((data.get("summary") or "").strip())
+
+symbols = [s for s in (data.get("symbols") or []) if isinstance(s, dict)]
+if symbols:
+    out.append("")
+    out.append("Symbols:")
+    for s in symbols[:40]:
+        out.append("  %-6s %s  (line %s)" % (s.get("kind", "?"), s.get("name", "?"), s.get("line", "?")))
+
+regions = [r for r in (data.get("regions") or []) if isinstance(r, dict)]
+if regions:
+    out.append("")
+    out.append("Read next (bounded, and this gate allows it):")
+    for r in regions[:8]:
+        start, end = r.get("start"), r.get("end")
+        span = ""
+        try:
+            span = "  Read(offset: %d, limit: %d)" % (int(start), int(end) - int(start) + 1)
+        except Exception:
+            pass
+        out.append("  %s-%s  %s%s" % (start, end, r.get("why", ""), span))
+
+node = os.environ.get("NODE_ID") or ""
+if node:
+    out.append("")
+    out.append("Full text: .multi-agent/refs/%s.txt  [[ref:%s]]" % (node, node))
+if data.get("truncated"):
+    out.append("")
+    out.append("NOTE: the worker reports it did not see the whole file.")
+print("\n".join(out))
+PYEOF
+) || degrade "the worker's answer was not the requested JSON object"
+
+printf '%s\n' "$RENDER"
+
+[ -x "$HERE/log-metric.sh" ] && \
+  "$HERE/log-metric.sh" "${MULTI_AGENT_TASK_ID:-unknown}" "$PHASE" bulk_read.delegated \
+    file_lines="$LINES" file_bytes="$BYTES" model="$MODEL" duration_ms="$(( ELAPSED * 1000 ))" \
+    >/dev/null 2>&1
+
+exit 0

package/pipeline/scripts/check-read-size.py

@@ -0,0 +1,335 @@
+#!/usr/bin/env python3
+"""check-read-size.py  -  decision core for the read-size PreToolUse gate.
+
+Reads a Claude Code hook payload on stdin and prints ONE line:
+
+    PASS
+    OBSERVE\t<path>\t<lines>\t<why>
+    BLOCK\t<path>\t<lines>\t<why>
+
+It decides only. The wrapper (check-read-size.sh) owns telemetry, the message
+the model sees, and the exit code. Splitting them is what lets the smoke gate
+drive the decision without a hook harness, and it keeps the blocking path in
+shell where the other two gates already live.
+
+Why a gate at all: a phase that reads six 900-line files pays for 5,400 lines of
+Swift at the phase's own rung, and the useful content is a handful of symbols.
+`offload-ref.sh` already caught the other half of that bill - the build log - but
+nothing looked at reads.
+
+Why it must not simply block: in Claude Code, `Edit` requires that the SAME file
+was read first. A gate that blocks reads during development stops the pipeline
+from editing anything. So the development phase is exempt by default, and so is
+any file already in the run's edit set. The gate exists for the phases that read
+to UNDERSTAND (analysis, review), not for the one that reads to change.
+
+Modes (prefs `global.bulkRead.mode`):
+    off       nothing is inspected                      (default)
+    observe   decide, log, never block  -  the baseline measurement
+    enforce   block a read over the threshold
+
+Fail-open everywhere: any error prints PASS. A gate that guesses wrong must cost
+a log line, never a tool call.
+"""
+
+import json
+import os
+import re
+import shlex
+import sys
+
+# Shipped defaults for the two prefs read below: `bulkRead.minLines` and
+# `bulkRead.exemptPhases`. A pref that resolves to anything else - absent, zero,
+# a string - takes these rather than silently turning the gate off.
+DEFAULT_MIN_LINES = 350
+DEFAULT_EXEMPT_PHASES = ["3"]
+
+PREF_PATHS = [
+    "~/.claude/multi-agent-preferences.json",
+    "~/.config/multi-agent-pipeline/multi-agent-preferences.json",
+    "~/.claude/preferences.json",
+    "~/.config/multi-agent-pipeline/preferences.json",
+]
+
+# Commands that read a whole file to stdout. `sed` is here for `sed -n '1,900p'`,
+# which is the spelling an agent reaches for when Read is unavailable.
+READ_COMMANDS = {"cat", "head", "tail", "sed", "bat", "less", "more"}
+
+# `1,900p` / `1,$p` / `900p` - a sed print script with a line range.
+SED_RANGE = re.compile(r"^'?(\d+)(?:,(\d+|\$))?p'?$")
+
+
+def emit(verdict, path="", lines=0, why=""):
+    sys.stdout.write("%s\t%s\t%s\t%s\n" % (verdict, path, lines, why))
+    sys.exit(0)
+
+
+def load_prefs():
+    for raw in PREF_PATHS:
+        p = os.path.expanduser(raw)
+        if not os.path.isfile(p):
+            continue
+        try:
+            with open(p, "r", encoding="utf-8") as fh:
+                return json.load(fh).get("global", {}).get("bulkRead", {}) or {}
+        except Exception:
+            return {}
+    return {}
+
+
+def positive_int(value, default):
+    """A pref counts only as a positive integer; anything else takes the default.
+
+    Same rule as offload-ref.sh: a zero or a string must not silently disable
+    the threshold, because that reads as "the gate is off" when it is broken.
+    """
+    try:
+        n = int(value)
+    except (TypeError, ValueError):
+        return default
+    return n if n > 0 else default
+
+
+def find_state():
+    """Walk up from cwd for the run's agent-state.json.
+
+    A hook runs in the worktree where the tool call happens, so the state file
+    is at cwd or above it. The env override exists for the smoke gate.
+    """
+    override = os.environ.get("MULTI_AGENT_STATE")
+    if override:
+        return override if os.path.isfile(override) else None
+    here = os.path.abspath(os.getcwd())
+    while True:
+        candidate = os.path.join(here, "agent-state.json")
+        if os.path.isfile(candidate):
+            return candidate
+        parent = os.path.dirname(here)
+        if parent == here:
+            return None
+        here = parent
+
+
+def run_context():
+    """(phase, edit_set) for the current run, both best-effort.
+
+    Both come from agent-state.json's REAL shape, checked against
+    pipeline/schemas/agent-state.schema.json: the phase is the top-level
+    `currentPhase` integer, and the files a phase has touched are
+    `phases["<n>"].files[]` - the same list semantic revert uses. An earlier
+    draft of this read `run.phase` and `dev.editSet`, neither of which the
+    schema declares, so the exemption could never have engaged from state and
+    the gate would have blocked development. smoke-bulk-read.sh asserts the
+    field names against the schema now, so that cannot come back quietly.
+    """
+    phase = os.environ.get("MULTI_AGENT_PHASE", "")
+    edit_set = set()
+    path = find_state()
+    if not path:
+        return phase, edit_set
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            state = json.load(fh)
+    except Exception:
+        return phase, edit_set
+    if not phase:
+        current = state.get("currentPhase")
+        phase = str(current) if isinstance(current, int) else ""
+    # Every phase's file list counts, not only the current one: a review that
+    # re-reads what development just wrote is reading the run's own work.
+    phases = state.get("phases")
+    if isinstance(phases, dict):
+        for entry in phases.values():
+            if not isinstance(entry, dict):
+                continue
+            for f in entry.get("files") or []:
+                if isinstance(f, str):
+                    edit_set.add(os.path.basename(f))
+    return phase, edit_set
+
+
+def count_lines(path):
+    """Line count, or -1 when the file cannot be measured.
+
+    Binary-safe and streamed: the gate must not itself load the payload it
+    exists to keep out of memory.
+    """
+    try:
+        total = 0
+        with open(path, "rb") as fh:
+            while True:
+                chunk = fh.read(1 << 20)
+                if not chunk:
+                    break
+                total += chunk.count(b"\n")
+        return total
+    except Exception:
+        return -1
+
+
+def as_count(token):
+    """A flag's numeric argument, or a large sentinel when it is not a number.
+
+    Not-a-number must read as UNBOUNDED, not as 1: treating an unparseable
+    count as a tiny one is how a gate lets through exactly the reads it exists
+    to catch.
+    """
+    try:
+        n = int(token)
+    except (TypeError, ValueError):
+        return 1 << 30
+    return abs(n)
+
+
+def looks_like_sed_script(token):
+    return bool(SED_RANGE.match(token or ""))
+
+
+def sed_span(script):
+    """Lines a `sed` print script covers, or a large sentinel when unclear."""
+    m = SED_RANGE.match(script or "")
+    if not m:
+        return 1 << 30
+    start, end = m.group(1), m.group(2)
+    try:
+        if end in (None, "", "$"):
+            return 1 << 30
+        return abs(int(end) - int(start)) + 1
+    except (TypeError, ValueError):
+        return 1 << 30
+
+
+def read_target(payload):
+    """The file a tool call would read whole, or None.
+
+    Returns None for every call that is already bounded - a Read with a small
+    `limit`, a `head -n 50` - because those are not what this gate is for.
+    """
+    tool = payload.get("tool_name", "")
+    args = payload.get("tool_input", {}) or {}
+
+    if tool == "Read":
+        path = args.get("file_path")
+        if not path:
+            return None
+        limit = args.get("limit")
+        if isinstance(limit, int) and limit > 0:
+            return (path, limit)
+        return (path, None)
+
+    if tool != "Bash":
+        return None
+
+    command = args.get("command", "")
+    if not command:
+        return None
+    # A compound command is not decided here: splitting on shell operators
+    # correctly is the kind of parsing that goes wrong quietly, and a wrong
+    # block is worse than a missed one.
+    for operator in ("&&", "||", "|", ";", "$(", "`", ">", "<"):
+        if operator in command:
+            return None
+    try:
+        tokens = shlex.split(command)
+    except ValueError:
+        return None
+    if not tokens or os.path.basename(tokens[0]) not in READ_COMMANDS:
+        return None
+
+    tool = os.path.basename(tokens[0])
+    bound = None
+    operands = []
+    i = 1
+    while i < len(tokens):
+        token = tokens[i]
+
+        if not token.startswith("-") or token == "-":
+            if tool == "sed" and not operands and looks_like_sed_script(token):
+                # `sed '1,900p' file` - the script, not the file.
+                bound = max(bound or 0, sed_span(token))
+            else:
+                operands.append(token)
+            i += 1
+            continue
+
+        # A following-tail stream is not a bulk read at all; blocking it would
+        # be a false positive with no cheap alternative to offer.
+        if tool == "tail" and token in ("-f", "-F", "--follow"):
+            return None
+
+        # Only head/tail take a separate count operand. `cat -n` NUMBERS LINES -
+        # reading its next token as a count swallowed the filename, left no
+        # operand, and let `cat -n <bigfile>` through the gate entirely.
+        if tool in ("head", "tail") and token in ("-n", "-c"):
+            nxt = tokens[i + 1] if i + 1 < len(tokens) else ""
+            bound = max(bound or 0, as_count(nxt))
+            i += 2
+            continue
+
+        # `sed -n` suppresses default output; the range lives in the script,
+        # which arrives as the next operand and is handled above.
+        if tool == "head" or tool == "tail":
+            attached = token.lstrip("-")
+            if attached.isdigit():
+                bound = max(bound or 0, as_count(attached))
+            elif attached[:1] in ("n", "c") and attached[1:].isdigit():
+                bound = max(bound or 0, as_count(attached[1:]))
+        i += 1
+
+    if len(operands) != 1:
+        return None
+    return (operands[0], bound)
+
+
+def main():
+    try:
+        payload = json.load(sys.stdin)
+    except Exception:
+        emit("PASS", why="unparseable payload")
+
+    # `bulkRead.mode` decides whether this gate does anything at all.
+    prefs = load_prefs()
+    mode = str(prefs.get("mode", "off") or "off").lower()
+    if mode not in ("observe", "enforce"):
+        emit("PASS", why="mode=%s" % mode)
+
+    target = read_target(payload)
+    if target is None:
+        emit("PASS", why="not a whole-file read")
+    path, bound = target
+
+    min_lines = positive_int(prefs.get("minLines"), DEFAULT_MIN_LINES)
+    if bound is not None and bound < min_lines:
+        emit("PASS", path, 0, "bounded read")
+
+    if not os.path.isfile(path):
+        emit("PASS", path, 0, "not a readable file")
+
+    lines = count_lines(path)
+    if lines < 0:
+        emit("PASS", path, 0, "unmeasurable")
+    if lines < min_lines:
+        emit("PASS", path, lines, "under threshold")
+
+    phase, edit_set = run_context()
+    exempt = prefs.get("exemptPhases")
+    if not isinstance(exempt, list) or not exempt:
+        exempt = DEFAULT_EXEMPT_PHASES
+    exempt = [str(x) for x in exempt]
+
+    # The two exemptions that keep Edit working. Both are stated as PASS with a
+    # reason rather than skipped silently, so the telemetry shows how often the
+    # gate declined to act and why.
+    if phase and phase in exempt:
+        emit("PASS", path, lines, "phase %s exempt" % phase)
+    if os.path.basename(path) in edit_set:
+        emit("PASS", path, lines, "in edit set")
+
+    emit("OBSERVE" if mode == "observe" else "BLOCK", path, lines, "over threshold")
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception:
+        emit("PASS", why="internal error")

package/pipeline/scripts/check-read-size.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+# check-read-size.sh  -  PreToolUse read gate for the multi-agent pipeline.
+#
+# The third deterministic hook, and the first on the READ side. The other two
+# (pre-commit-check, agent-guard) inspect what the run writes; this one inspects
+# what it pays to read.
+#
+# The bill it exists for: 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. `offload-ref.sh` already took the other half of that bill - the build
+# log, the diff, the test output - by parking the payload and printing a pointer.
+# Nothing looked at file reads, because nothing could: only a hook sees a tool
+# call before it runs.
+#
+# Contract (Claude Code PreToolUse hook):
+#   - Reads the tool-call JSON on stdin.
+#   - Exit 2  -> BLOCK (reason on stderr, shown to the model).
+#   - Exit 0  -> allow.
+#
+# Modes  -  `prefs.global.bulkRead.mode`:
+#   off       (default) nothing is inspected; the hook is a no-op.
+#   observe   decide and LOG, never block. This is the measurement: run the
+#             pipeline normally and metrics.jsonl carries the read-size
+#             distribution, so the saving can be estimated before anything is
+#             built on top of it.
+#   enforce   block a whole-file read over `minLines` and tell the model to
+#             delegate it to bulk-read.sh instead.
+#
+# Why observe is a real mode and not a debug flag: the honest order is measure,
+# then route. A gate switched straight to enforce has no baseline to be
+# compared against, and "we cut tokens" becomes a claim nothing can check.
+#
+# Why the development phase is exempt by default: in Claude Code, `Edit` requires
+# the same file to have been read first. A gate that blocks reads in Phase 3
+# blocks editing. The gate is for the phases that read to UNDERSTAND.
+#
+# Safety design (fail-OPEN): any internal error, missing python3, missing helper,
+# empty payload -> exit 0. It never executes the inspected command, never writes
+# to the inspected file, makes no network call, and prints no file content.
+
+set -u
+
+HERE="$(cd "$(dirname "$0")" 2>/dev/null && pwd || true)"
+HELPER="$HERE/check-read-size.py"
+[ -f "$HELPER" ] || exit 0
+command -v python3 >/dev/null 2>&1 || exit 0
+
+PAYLOAD="$(cat 2>/dev/null || true)"
+[ -z "$PAYLOAD" ] && exit 0
+
+DECISION="$(printf '%s' "$PAYLOAD" | python3 "$HELPER" 2>/dev/null || true)"
+[ -z "$DECISION" ] && exit 0
+
+VERDICT="$(printf '%s' "$DECISION" | cut -f1)"
+FILE="$(printf '%s' "$DECISION" | cut -f2)"
+LINES="$(printf '%s' "$DECISION" | cut -f3)"
+WHY="$(printf '%s' "$DECISION" | cut -f4)"
+
+# Telemetry is best-effort and never gates the decision. `log-metric.sh` already
+# tolerates an unwritable directory, so the only guard needed here is the
+# script's own presence.
+note() {
+  [ -x "$HERE/log-metric.sh" ] || return 0
+  "$HERE/log-metric.sh" "${MULTI_AGENT_TASK_ID:-unknown}" "${MULTI_AGENT_PHASE:-0}" \
+    "read.$1" lines="${LINES:-0}" reason="${WHY:-}" >/dev/null 2>&1 || true
+}
+
+case "$VERDICT" in
+  OBSERVE)
+    note observed
+    exit 0 ;;
+  BLOCK)
+    note blocked
+    echo "BLOCKED by check-read-size: ${FILE} is ${LINES} lines." >&2
+    echo "Reading it whole costs this phase's rung for a file whose useful part is a few symbols." >&2
+    echo "" >&2
+    echo "Delegate it, then work from what comes back:" >&2
+    echo "  bash \$HOME/.claude/scripts/bulk-read.sh --file '${FILE}' --question '<what you need from it>'" >&2
+    echo "" >&2
+    echo "The summary carries LINE NUMBERS, so a follow-up Read with an offset/limit around the" >&2
+    echo "region you actually need is the intended next step and passes this gate." >&2
+    echo "Full text stays on disk under .multi-agent/refs/ if the summary is not enough." >&2
+    exit 2 ;;
+  *)
+    exit 0 ;;
+esac

package/pipeline/scripts/pre-commit-check.sh

@@ -194,6 +194,7 @@ scan_file() {
           if (s ~ /^[0-9]+$/) next;        # pure digits
           if (s ~ /^[0-9a-f]+$/) next;     # lowercase hex (git sha / md5 / sha-*)
           if (s ~ /^[0-9A-F]+$/) next;     # uppercase hex
+          if (s ~ /^([A-Z][a-z]+)+[A-Z]*$/) next;  # CamelCase words only (label key / type name), never a credential
           delete freq;
           for (i = 1; i <= n; i++) { c = substr(s, i, 1); freq[c]++ }
           H = 0;

package/pipeline/scripts/uninstall.mjs

@@ -67,6 +67,7 @@ const HOME = process.env.HOME || process.env.USERPROFILE;
 export const PIPELINE_AGENT_FILES = [
   "android-architect.md",
   "backend-architect.md",
+  "bulk-reader.md",
   "code-reviewer.md",
   "dev-critic.md",
   "explorer.md",

package/pipeline/skills/shared/external/backlog/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: backlog
 version: 1.0.0
-description: "The engineering backlog registry for deferred-but-approved work in this codebase. Every job the user defers ('defer it', 'add it to the list', 'later', 'not now') lands HERE with its full spec, origin, and unblock condition, so deferral never means loss. Load when the user defers work, asks 'what's on the backlog / the list', says 'work the backlog' / 'pick up <item>', or when completing an item. The bundled BACKLOG.md is the registry; entries move deferred -> ready -> in-progress -> done and are never deleted."
+description: "The engineering backlog registry for deferred-but-approved work in this codebase. Every job the user defers ('defer it', 'add it to the list', 'later', 'not now') lands HERE with its full spec, origin, and unblock condition, so deferral never means loss. Load when the user defers work, asks 'what's on the backlog / the list', says 'work the backlog' / 'pick up <item>', or when completing an item. The bundled BACKLOG.md is the registry; entries move deferred -> ready -> in-progress -> done, and the registry is re-audited against live code - a rotted entry deletes, a done record retires once what it taught is re-homed in the skill that owns it. This records WHAT IS OWED; git history records what happened."
 user-invocable: true
-argument-hint: [list | add | pick <id> | done <id>]
+argument-hint: [list | add | pick <id> | done <id> | re-audit]
 allowed-tools: Read, Grep, Glob, Edit, Write
 ---
 
@@ -13,14 +13,17 @@ allowed-tools: Read, Grep, Glob, Edit, Write
 > **Bundled:** [BACKLOG.md](BACKLOG.md) - the registry. The heart of this skill.
 > **Iron rule:** moving a job onto this list is a MOVE, never a rewrite - the FULL spec
 > travels verbatim. A compressed one-liner is a loss; the point of the backlog is that
-> deferring costs nothing later.
+> deferring costs nothing later. The registry stays honest in the other direction too:
+> entries are re-audited against live code, and an entry whose named types or premises
+> no longer exist is DELETED, never left readable as live.
 
 ## When to load
 
 - The user defers work: "defer it", "add it to the list", "later", "not now", "backlog this".
 - The user asks about it: "what's on the backlog", "what's on the list", "what's owed".
 - The user works it: "work the backlog", "pick up <id>", "do the next one".
-- An item completes: mark it done (never delete).
+- An item completes: mark it done, and retire the record once what it taught has a home.
+- A staleness signal arrives (a rename, a deleted subject, a doubted claim): re-audit.
 
 ## The registry contract
 
@@ -28,7 +31,7 @@ Every entry in `BACKLOG.md` carries, verbatim:
 
 - **id** - short stable slug (`kebab-case`), assigned on add.
 - **title** - one line.
-- **state** - `deferred` -> `ready` -> `in-progress` -> `done`. Entries only move forward; nothing is deleted.
+- **state** - `deferred` -> `ready` -> `in-progress` -> `done`. Entries move forward; they leave the registry only by the two rules below (rot, or a re-homed done record), never by being quietly rewritten.
 - **origin** - where it came from (the task/PR/finding/conversation that spawned it).
 - **spec** - the FULL description, verbatim from when it was deferred. Not a summary.
 - **unblock** - the condition that makes it actionable (a dependency, a decision, a date). `deferred` items without an unblock condition are just `ready`.
@@ -42,7 +45,8 @@ Prefer an append-only markdown table or section list in `BACKLOG.md`; never over
 | `list` | Show entries grouped by state (ready first, then deferred, then in-progress; done collapsed). |
 | `add` | Capture the deferred job with its full spec + origin + unblock condition. Assign an id. |
 | `pick <id>` | Move `ready`/`deferred` -> `in-progress`; surface the full spec so work resumes with zero context loss. |
-| `done <id>` | Move -> `done`. Keep the entry (it becomes the record of what was owed and delivered). |
+| `done <id>` | Move -> `done` with the evidence (PR/commit + date). The record RETIRES from the registry once what it taught is written into the skill or doc that owns it - git history is the archive of what was owed and delivered. A done entry kept past that point is a second place for the same truth to rot. |
+| `re-audit` | Verify every entry's named types, paths and claims against LIVE code (binary-safe: `LC_ALL=C grep -a`, so a repo with binary blobs does not silently return nothing). A subject that no longer exists deletes its entry; a changed fact restates it. **Numbers move by measurement, never by edit** - a count adjusted to match an impression reads as evidence and is worse than no count. |
 
 ## Why keep it whole