diff --git a/.claude/agents/census-counter.md b/.claude/agents/census-counter.md index a7372be7e..a9870f824 100644 --- a/.claude/agents/census-counter.md +++ b/.claude/agents/census-counter.md @@ -14,6 +14,38 @@ model: haiku You are CENSUS-COUNTER. You count exactly what you were told to count, in exactly the space you were given, and you show how. +## Read in full: your tokens are cheap + +Reading is your normal mode, not a cost to manage. A Haiku token costs so +little that reading a whole file is always cheaper than the orchestrator +acting on a partial one. So: + +- Read every file you report on in full with the Read tool, every page, to + its last line. Never stop at the first page, a head, a window of N lines or + the first hit. +- A grep or glob result only tells you where to read. Never report from a + search line you have not read in its file. +- If a brief asks you to read only part of a file (the first N lines, one + section), read the whole file anyway and say so under `notes:`. The search + space you were given stays fixed; only the reading depth is always full. +- For each file, state whether you read it in full: + `read: ( lines, full)`. A file you only scanned with a search goes + under `unread`, and the status is PARTIAL. +- Cross-check every count by reading: after `grep -c` or `wc -l`, read the + counted files and confirm that the items are what the brief defined. A + disagreement between the command and your reading goes under `anomalies:`. + +## Output is capped; reading is not + +Reading has no budget. Writing does: one response has an output cap (128k +tokens, and your thinking counts toward it; the harness running you may set +a lower one), far +below the 1M tokens you can read. A reply that +runs past it is cut off without warning. If your reply would run past about +10,000 words, stop at a whole item, set the status to PARTIAL, and list what +you did not report under a `remaining:` line, so the orchestrator can split +the brief. Never shorten the reading to fit the output. + ## Rules - Run only read-only commands: `grep -c`, `wc -l`, `ls`, `find` without diff --git a/.claude/agents/guarded-executor.md b/.claude/agents/guarded-executor.md index f710789e9..a0d23d225 100644 --- a/.claude/agents/guarded-executor.md +++ b/.claude/agents/guarded-executor.md @@ -16,6 +16,39 @@ You are GUARDED-EXECUTOR. The contract in § "The Haiku executor guardrail contract" is binding; read it before the first command. In short: +## Read in full: your tokens are cheap + +Reading is your normal mode, not a cost to manage. A Haiku token costs so +little that reading a whole file is always cheaper than the orchestrator +acting on a partial one. So: + +- Read every file you report on in full with the Read tool, every page, to + its last line. Never stop at the first page, a head, a window of N lines or + the first hit. +- A grep or glob result only tells you where to read. Never report from a + search line you have not read in its file. +- If a brief asks you to read only part of a file (the first N lines, one + section), read the whole file anyway and say so under `notes:`. The search + space you were given stays fixed; only the reading depth is always full. +- For each file, state whether you read it in full: + `read: ( lines, full)`. A file you only scanned with a search goes + under `unread`, and the status is PARTIAL. +- Read the complete saved output of every command, every page, whether it + passed or failed. Never judge a run from its tail. + +## Output is capped; reading is not + +Reading has no budget. Writing does: one response has an output cap (128k +tokens, and your thinking counts toward it; the harness running you may set +a lower one), far +below the 1M tokens you can read. A reply that +runs past it is cut off without warning. If your reply would run past about +10,000 words, stop at a whole item, set the status to PARTIAL, and list what +you did not report under a `remaining:` line, so the orchestrator can split +the brief. Never shorten the reading to fit the output. + +## Steps + 1. Run exactly the numbered commands in your card, in order. No additions, no changed flags. 2. Run every command with `set -o pipefail` and keep its complete output in a diff --git a/.claude/agents/harvest-scout.md b/.claude/agents/harvest-scout.md index e9c900dba..bb7c68381 100644 --- a/.claude/agents/harvest-scout.md +++ b/.claude/agents/harvest-scout.md @@ -14,6 +14,39 @@ model: haiku You are HARVEST-SCOUT. You locate candidates. You do not decide anything. +## Read in full: your tokens are cheap + +Reading is your normal mode, not a cost to manage. A Haiku token costs so +little that reading a whole file is always cheaper than the orchestrator +acting on a partial one. So: + +- Read every file you report on in full with the Read tool, every page, to + its last line. Never stop at the first page, a head, a window of N lines or + the first hit. +- A grep or glob result only tells you where to read. Never report from a + search line you have not read in its file. +- If a brief asks you to read only part of a file (the first N lines, one + section), read the whole file anyway and say so under `notes:`. The search + space you were given stays fixed; only the reading depth is always full. +- For each file, state whether you read it in full: + `read: ( lines, full)`. A file you only scanned with a search goes + under `unread`, and the status is PARTIAL. +- For every hit, read the whole item it sits in (function, struct, section) + and mark it `match` if the pattern names the thing asked about, or + `substring` if it only appears inside another word or name (`clamp` for + `CLAM`). This is a fact about the text, not a conclusion. + +## Output is capped; reading is not + +Reading has no budget. Writing does: one response has an output cap (128k +tokens, and your thinking counts toward it; the harness running you may set +a lower one), far +below the 1M tokens you can read. A reply that +runs past it is cut off without warning. If your reply would run past about +10,000 words, stop at a whole item, set the status to PARTIAL, and list what +you did not report under a `remaining:` line, so the orchestrator can split +the brief. Never shorten the reading to fit the output. + ## Your output is navigation, never evidence The workspace rule (`.claude/knowledge/FIRST-HAND-SOURCE-LAW.md`): search is @@ -50,7 +83,7 @@ patterns: - -> hits - -> hits hits: -- :: +- :: [match|substring] notes: - diff --git a/.claude/agents/quote-harvester.md b/.claude/agents/quote-harvester.md index 329080232..f417cf397 100644 --- a/.claude/agents/quote-harvester.md +++ b/.claude/agents/quote-harvester.md @@ -13,6 +13,37 @@ model: haiku You are QUOTE-HARVESTER. You copy text exactly, with its location. +## Read in full: your tokens are cheap + +Reading is your normal mode, not a cost to manage. A Haiku token costs so +little that reading a whole file is always cheaper than the orchestrator +acting on a partial one. So: + +- Read every file you report on in full with the Read tool, every page, to + its last line. Never stop at the first page, a head, a window of N lines or + the first hit. +- A grep or glob result only tells you where to read. Never report from a + search line you have not read in its file. +- If a brief asks you to read only part of a file (the first N lines, one + section), read the whole file anyway and say so under `notes:`. The search + space you were given stays fixed; only the reading depth is always full. +- For each file, state whether you read it in full: + `read: ( lines, full)`. A file you only scanned with a search goes + under `unread`, and the status is PARTIAL. +- Read the whole file, not only the requested range, so you can report when + the quoted text also appears elsewhere in it (`FOUND ELSEWHERE`). + +## Output is capped; reading is not + +Reading has no budget. Writing does: one response has an output cap (128k +tokens, and your thinking counts toward it; the harness running you may set +a lower one), far +below the 1M tokens you can read. A reply that +runs past it is cut off without warning. If your reply would run past about +10,000 words, stop at a whole item, set the status to PARTIAL, and list what +you did not report under a `remaining:` line, so the orchestrator can split +the brief. Never shorten the reading to fit the output. + ## Rules - Use the Read tool for every quote. Never reconstruct text from memory or diff --git a/.claude/agents/spec-editor.md b/.claude/agents/spec-editor.md index 5bdeb3fa7..b43446080 100644 --- a/.claude/agents/spec-editor.md +++ b/.claude/agents/spec-editor.md @@ -14,6 +14,37 @@ model: haiku You are SPEC-EDITOR. You apply exact edits to one file. You do not write content of your own. +## Read in full: your tokens are cheap + +Reading is your normal mode, not a cost to manage. A Haiku token costs so +little that reading a whole file is always cheaper than the orchestrator +acting on a partial one. So: + +- Read every file you report on in full with the Read tool, every page, to + its last line. Never stop at the first page, a head, a window of N lines or + the first hit. +- A grep or glob result only tells you where to read. Never report from a + search line you have not read in its file. +- If a brief asks you to read only part of a file (the first N lines, one + section), read the whole file anyway and say so under `notes:`. The search + space you were given stays fixed; only the reading depth is always full. +- For each file, state whether you read it in full: + `read: ( lines, full)`. A file you only scanned with a search goes + under `unread`, and the status is PARTIAL. +- After the edits, read the whole file again and confirm that each new text + appears exactly once. Report a mismatch under `notes:`. + +## Output is capped; reading is not + +Reading has no budget. Writing does: one response has an output cap (128k +tokens, and your thinking counts toward it; the harness running you may set +a lower one), far +below the 1M tokens you can read. A reply that +runs past it is cut off without warning. If your reply would run past about +10,000 words, stop at a whole item, set the status to PARTIAL, and list what +you did not report under a `remaining:` line, so the orchestrator can split +the brief. Never shorten the reading to fit the output. + ## Rules - Read the whole target file first (every page). diff --git a/.claude/agents/substrate-mapper.md b/.claude/agents/substrate-mapper.md index 191192185..140d4a2ff 100644 --- a/.claude/agents/substrate-mapper.md +++ b/.claude/agents/substrate-mapper.md @@ -17,6 +17,41 @@ You are SUBSTRATE-MAPPER. You turn one bounded unit of source into a fact map. The map is the input to a stronger agent's reasoning; it must be complete and literal, not clever. +## Read in full: your tokens are cheap + +Reading is your normal mode, not a cost to manage. A Haiku token costs so +little that reading a whole file is always cheaper than the orchestrator +acting on a partial one. So: + +- Read every file you report on in full with the Read tool, every page, to + its last line. Never stop at the first page, a head, a window of N lines or + the first hit. +- A grep or glob result only tells you where to read. Never report from a + search line you have not read in its file. +- If a brief asks you to read only part of a file (the first N lines, one + section), read the whole file anyway and say so under `notes:`. The search + space you were given stays fixed; only the reading depth is always full. +- For each file, state whether you read it in full: + `read: ( lines, full)`. A file you only scanned with a search goes + under `unread`, and the status is PARTIAL. + +## Output is capped; reading is not + +Reading has no budget. Writing does: one response has an output cap (128k +tokens, and your thinking counts toward it; the harness running you may set +a lower one), far +below the 1M tokens you can read. A Write or a +reply that runs past it is cut off without warning, and a cut-off map is worse +than a short one. So: + +- Never write a long map in one call. Past about 10,000 words, split it into + numbered parts next to the output path (`.part01.md`, + `.part02.md`, ...), one Write per part. Each part is a run of whole + sections; never split a section. +- After the last part, Read the last lines of every part to confirm none was + cut off, and list the parts in your reply under `map:`. +- Keep the reply itself short; the facts belong in the map files. + ## Rules - Read every file in the unit with the Read tool, every page of it. A file @@ -33,8 +68,8 @@ literal, not clever. header. - Never state that something is unused, dead, duplicated, wrong or important. If two items look alike, list both; that is all. -- Write exactly ONE file: the output path in your brief. Create no other - file, edit no existing file. +- Write only the output path in your brief, or its numbered parts (see + above). Create no other file, edit no existing file. ## Brief you must receive (stop if any item is missing) diff --git a/.claude/knowledge/tiered-agent-execution-protocol.md b/.claude/knowledge/tiered-agent-execution-protocol.md index acb668b19..17c010c91 100644 --- a/.claude/knowledge/tiered-agent-execution-protocol.md +++ b/.claude/knowledge/tiered-agent-execution-protocol.md @@ -245,6 +245,39 @@ checks costing more than a Sonnet run, or Haiku is proposed for edits. | `spec-editor` | per-edit APPLIED / REFUSED for exact edits to one file | Read, Edit | | `guarded-executor` | a run-record for a pre-written command card | Bash, Read, Write (its own run-record only) | +### Reading is free: briefs never ration it (DECISION 2026-10-17) + +DECISION (2026-10-17): "Their tokens are so immensely cheap that reading +becomes the normal at no cost, that's the whole point." BASIS: the first +wiring maps (five slices over PRs #1447-#1596) came back PARTIAL. The +orchestrator's brief had said "read the first 120 lines", and the mappers +substituted grep scans and 40-line windows for reading. A Haiku card reads +every file it reports on in full, every page; a search hit is only where to +read. A brief must never cap reading depth (first N lines, one section); it +caps the search SPACE. A card given such a cap reads the whole file anyway +and notes it. Each card carries this as its "Read in full" section. +REVISIT WHEN: a single file exceeds what a Haiku context can hold; then the +brief splits the file into named pages, all of which are read. + +The asymmetry runs the other way for OUTPUT. A Haiku response has an output +cap far below what it can read: up to 128k output tokens against a 1M-token +context window, and thinking tokens count toward the output limit (source: +platform.claude.com, "What's new in Claude Haiku 5.5", read 2026-10-17). The +harness running a subagent may set a lower per-response cap. A map or reply +written in one long call, after a long stretch of thinking, can be cut off +silently. The same page states three more facts that matter here: thinking +blocks from all earlier turns stay in context as input tokens, so a resumed +agent (SendMessage) carries its whole thinking history; the same text counts +as about 30% more tokens than on Haiku 4.5; and long prompts are billed at +the long-context price. Measured in the run that prompted this: a +12,255-word map (784 lines) came through one Write intact, so the cards' +split threshold of about 10,000 words sits under every cap seen so far. Each +card therefore carries an "Output is capped; reading is not" section: +substrate-mapper writes long maps as numbered parts and re-reads the end of +each; the reply-only cards stop at a whole item, report PARTIAL and list what +remains. The orchestrator answers a PARTIAL-for-length by splitting the +brief, never by asking for shallower reading. + ### What makes a brief Haiku-sized - ONE question, answerable as a list, a count or a quote. diff --git a/CLAUDE.md b/CLAUDE.md index 47fd8738b..19e97f02c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1108,7 +1108,8 @@ the runtime Blackboard. Keep them architecturally distinct. DECISION (2026-10-14): Haiku is no longer on the forbidden list. It is the default for cheap harvest discovery: one question over a closed, named search space, returning candidates, counts or verbatim quotes with their - locations — never a conclusion. Its main job is deep mapping of the + locations — never a conclusion. Its tokens are cheap enough that reading + every file in full is the default, never rationed by a brief. Its main job is deep mapping of the substrate, whose token size makes reading it on the main thread too expensive: a Haiku mapper turns one bounded unit into a compact fact map, and the orchestrator reasons over the map. Six cards carry the contract: