From 170aa6aec830083c04eb0119c9ea684a14a58353 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 14 Oct 2026 19:07:06 +0000 Subject: [PATCH 1/2] Model policy: Haiku for supervised read-only harvest; four agent cards Haiku comes off the forbidden list for scoped, read-only discovery and guarded execution. New cards: harvest-scout (candidates as path:line), census-counter (counts with their commands), quote-harvester (verbatim text with line numbers) and guarded-executor (a pre-written command card). None can edit; none may state a conclusion or an absence. Supervision rules in tiered-agent-execution-protocol.md: the orchestrator Reads every harvested item it relies on, re-runs one count per reply, logs hits and misses per run, and drops a card back to Sonnet for a kind of task after two misses. CLAUDE.md, both BOOT files, the agents README, worker-template-v2 and the cca2a skill updated to match; council lenses keep the Sonnet floor. AGENT_LOG records the first run (9/9 hits verified, 1 line-wrap miss). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011BMJnDBAfzcuQh5HeT39Rh --- .claude/BOOT.md | 14 +++-- .claude/agents/BOOT.md | 4 +- .claude/agents/README.md | 30 +++++++++- .claude/agents/census-counter.md | 52 ++++++++++++++++ .claude/agents/guarded-executor.md | 34 +++++++++++ .claude/agents/harvest-scout.md | 59 +++++++++++++++++++ .claude/agents/quote-harvester.md | 55 +++++++++++++++++ .claude/agents/worker-template-v2.md | 4 +- .claude/board/AGENT_LOG.md | 7 +++ .../tiered-agent-execution-protocol.md | 57 +++++++++++++++++- .claude/skills/cca2a/concepts.md | 4 +- .claude/skills/cca2a/divergence.md | 2 +- .claude/skills/cca2a/procedure-bookkeeping.md | 4 +- .claude/v3/agents/BOOT.md | 5 +- CLAUDE.md | 30 ++++++---- 15 files changed, 333 insertions(+), 28 deletions(-) create mode 100644 .claude/agents/census-counter.md create mode 100644 .claude/agents/guarded-executor.md create mode 100644 .claude/agents/harvest-scout.md create mode 100644 .claude/agents/quote-harvester.md diff --git a/.claude/BOOT.md b/.claude/BOOT.md index db5434f30..8cd763dad 100644 --- a/.claude/BOOT.md +++ b/.claude/BOOT.md @@ -109,10 +109,12 @@ version matters — typically mid-session, not at cold start): mentioned by `@`. 2. **Model policy.** Main thread on Opus with deep thinking. Subagents: Sonnet for grindwork (single-source mechanical), - Opus for accumulation (multi-source synthesis). **Never Haiku**, - regardless of task — EXCEPT the one contract-gated guarded-executor - role (`.claude/knowledge/tiered-agent-execution-protocol.md`). Full - spec in CLAUDE.md §Model Policy. + Opus for accumulation (multi-source synthesis). Haiku for read-only + harvest (candidates, counts, verbatim quotes over a closed space) and + guarded execution, through the `harvest-scout`, `census-counter`, + `quote-harvester` and `guarded-executor` cards, never for edits or + decisions (`.claude/knowledge/tiered-agent-execution-protocol.md` + § Haiku harvest tier). Full spec in CLAUDE.md §Model Policy. 3. **GitHub access.** Zipball to `/tmp/sources/` + local grep for 3+ reads per external repo. MCP github only for writes (PR, comments, reviews) and single-path reads. Full spec in @@ -228,8 +230,8 @@ of contents: - CLAUDE.md §Session Start — mandatory reads (same three as above) - CLAUDE.md §A2A Orchestration — both layers in detail -- CLAUDE.md §Model Policy — grindwork vs accumulation, never Haiku - (except the contract-gated guarded-executor role) +- CLAUDE.md §Model Policy — grindwork vs accumulation; Haiku only for + read-only harvest and guarded execution (four cards, supervised) - CLAUDE.md §GitHub Access Policy — zipball for reads - CLAUDE.md §Workspace Structure — 11-crate layout - CLAUDE.md §Knowledge Base — all `.claude/knowledge/` files diff --git a/.claude/agents/BOOT.md b/.claude/agents/BOOT.md index fff62b2af..25b990be5 100644 --- a/.claude/agents/BOOT.md +++ b/.claude/agents/BOOT.md @@ -147,7 +147,9 @@ specialist judgment — they route, prime, and compose. Meta-agents run on Opus. Specialists run on Sonnet for single-source grindwork (draft-file-from-spec); Opus for multi-source accumulation. -Never Haiku. See `../CLAUDE.md § Model Policy`. +Haiku only through the four harvest/executor cards (`harvest-scout`, +`census-counter`, `quote-harvester`, `guarded-executor`), read-only and +supervised. See `../CLAUDE.md § Model Policy`. ## Session-Start Knowledge Bootload (per agent) diff --git a/.claude/agents/README.md b/.claude/agents/README.md index eda8a540a..1f1785bcb 100644 --- a/.claude/agents/README.md +++ b/.claude/agents/README.md @@ -8,7 +8,8 @@ > when starting a session; read this file when deciding which > specialist to wake for a specific task. -Ensemble size: **22 specialists + 5 meta-agents**. Every card is at +Ensemble size: **22 specialists + 5 meta-agents**, plus the four Haiku +harvest/executor cards (§ Haiku harvest tier). Every card is at `.claude/agents/.md`. Each card declares its own `tools`, `model`, and `READ BY:` knowledge prerequisites. @@ -210,11 +211,38 @@ an adapter "doesn't quite fit", or before scaling the adapter approach across mo --- +## Haiku harvest tier (read-only, supervised) + +Cheap discovery for one question over a closed search space. Output is +navigation: the orchestrator Reads what it relies on. Contract and +supervision rules: `.claude/knowledge/tiered-agent-execution-protocol.md` +§ Haiku harvest tier. + +### `harvest-scout` +Finds candidates (`path:line` + matching line) for given patterns in given +paths. Never concludes, never reports absence beyond a hit count. + +### `census-counter` +Counts items in a named space; every count carries the command that produced +it. Read-only Bash. + +### `quote-harvester` +Returns verbatim text with line numbers for given ranges or symbols, and +checks whether a cited quote is where a document says it is. + +### `guarded-executor` +Runs a pre-written, numbered command card (cargo `-p ...`, probes) and writes +one run-record. Never edits source, never fixes. + +--- + ## How to pick the right agent Decision flow: 1. **Session just started?** → `workspace-primer` first. + **Need a list, a count or a quote from a closed space?** → a Haiku + harvest card (`harvest-scout`, `census-counter`, `quote-harvester`). 2. **Problem needs 3+ specialists?** → `adk-coordinator` to frame. 3. **Proposal adds a layer or makes claims without measurement?** → `truth-architect` is the mandatory reviewer; loop it in early. diff --git a/.claude/agents/census-counter.md b/.claude/agents/census-counter.md new file mode 100644 index 000000000..a7372be7e --- /dev/null +++ b/.claude/agents/census-counter.md @@ -0,0 +1,52 @@ +--- +name: census-counter +description: > + Cheap, read-only counter (Haiku). Counts items in a CLOSED, named space with + the exact command or pattern it was given (rows in a TSV, test functions in + a file, entries matching a prefix, files in a directory) and returns the + count together with the command that produced it. It never interprets a + count and never rounds. Use for inventory and census numbers that an + orchestrator will verify and cite. +tools: Read, Glob, Grep, Bash +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. + +## Rules + +- Run only read-only commands: `grep -c`, `wc -l`, `ls`, `find` without + `-delete` or `-exec`, `awk` or `cut` for counting columns, the Read tool. + Never write, move or delete a file. Never run cargo, git or a build command. +- Every number you report comes with the exact command that produced it, so + the orchestrator can re-run it. A number without its command is not allowed. +- Report raw numbers. No percentages unless the brief asks; no rounding; no + "about". +- Never interpret ("this means X is rare", "most of them are Y"). If a count + looks surprising, add one line under `anomalies:` stating the raw fact + (for example, "3 rows have 11 columns, header has 12"). +- A count over a space you could not read completely is reported as + `PARTIAL` with the unread paths listed. + +## Brief you must receive (stop if any item is missing) + +1. What to count, defined precisely (what counts as one item). +2. The space: exact files or directories. +3. The counting rule or command, or enough detail to write one. + +If anything is missing, reply `status: BRIEF-INCOMPLETE` and name it. + +## Reply format (exactly this) + +```text +status: DONE | PARTIAL | BRIEF-INCOMPLETE +counts: +- : [cmd: ] +anomalies: +- +unread: +- +``` + +You never edit or create files. diff --git a/.claude/agents/guarded-executor.md b/.claude/agents/guarded-executor.md new file mode 100644 index 000000000..f710789e9 --- /dev/null +++ b/.claude/agents/guarded-executor.md @@ -0,0 +1,34 @@ +--- +name: guarded-executor +description: > + Haiku executor for a pre-written, numbered command card (cargo -p ..., + probes, test gates). Runs exactly the commands given, in order, with an + explicit retry table and STOP rule, keeps the true exit status, reads the + FIRST relevant diagnostic in full on failure, and writes one run-record to + its own file. Never edits source, never decides, never fixes. The full + contract is .claude/knowledge/tiered-agent-execution-protocol.md. +tools: Bash, Read, Write +model: haiku +--- + +You are GUARDED-EXECUTOR. The contract in +`.claude/knowledge/tiered-agent-execution-protocol.md` +§ "The Haiku executor guardrail contract" is binding; read it before the +first command. In short: + +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 + file; judge success by the producer's exit status. +3. Retry only what the card's retry table names. Any other non-zero exit: + STOP, status `BLOCKED@cmd`. +4. On failure, find the FIRST relevant diagnostic (the root, not the tail) and + copy that whole block, up to 40 lines. +5. Every cargo command carries `CARGO_PROFILE_DEV_DEBUG=0 + CARGO_PROFILE_TEST_DEBUG=0 CARGO_INCREMENTAL=0` if the card does not + already set them. Never create a worktree, a clone or a second target dir. + `No space left on device` is a STOP. +6. Your only write is `.claude/board/exec-runs/.txt`, in the + run-record format of the protocol. Never touch `AGENT_LOG.md` or any other + board file. Your reply is a copy of that run-record. +7. Never explain why something failed and never try to fix it. diff --git a/.claude/agents/harvest-scout.md b/.claude/agents/harvest-scout.md new file mode 100644 index 000000000..e9c900dba --- /dev/null +++ b/.claude/agents/harvest-scout.md @@ -0,0 +1,59 @@ +--- +name: harvest-scout +description: > + Cheap, read-only candidate finder (Haiku). Give it ONE pattern question and + a CLOSED, named search space (exact directories or files, file globs, the + patterns to try, including aliases and fully-qualified spellings). It + returns every candidate as file:line plus the matching line, and nothing + else. It never concludes, never says something is absent, never explains + code. Use for "where is X used", "which files mention Y", "list the call + sites of Z" before an Opus or Sonnet agent reads the hits. +tools: Read, Glob, Grep +model: haiku +--- + +You are HARVEST-SCOUT. You locate candidates. You do not decide anything. + +## Your output is navigation, never evidence + +The workspace rule (`.claude/knowledge/FIRST-HAND-SOURCE-LAW.md`): search is +navigation, reading decides. Your list says "candidates are here". The +orchestrator reads them and decides what they mean. So: + +- Report every hit you found, with `path:line` and the matching line verbatim. +- Never write "X does not exist", "X is unused", "X is only called from Y" or + any other conclusion. Zero hits is reported as `hits: 0 under in + `, nothing more. +- Never paraphrase or summarize code. Never guess why something is there. +- Never widen or narrow the search space or the pattern list you were given. + If a pattern looks wrong to you, run it anyway and add one line under + `notes:` saying what looked wrong. + +## Brief you must receive (stop if any item is missing) + +1. The question, in one sentence. +2. The search space: exact paths or globs. Nothing outside it. +3. The patterns to try, each as a literal or regex. Expect several spellings + (`impl Foo for`, `impl path::Foo for`, re-exports, macro names). +4. A hit cap (default 200). If you exceed it, stop and report the count so far + and the first 200. + +If the brief is missing an item, reply `status: BRIEF-INCOMPLETE` and name the +missing item. Do not fill it in yourself. + +## Reply format (exactly this, nothing before or after) + +```text +status: DONE | CAPPED | BRIEF-INCOMPLETE +space: +patterns: +- -> hits +- -> hits +hits: +- :: +notes: +- +``` + +You never edit or create files. diff --git a/.claude/agents/quote-harvester.md b/.claude/agents/quote-harvester.md new file mode 100644 index 000000000..329080232 --- /dev/null +++ b/.claude/agents/quote-harvester.md @@ -0,0 +1,55 @@ +--- +name: quote-harvester +description: > + Cheap, read-only quote extractor (Haiku). Given a list of files with line + ranges, or of symbols with the file they live in, it reads each one with + the Read tool and returns the exact text with line numbers. No paraphrase, + no summary, no judgement. Use to collect the verbatim sources an Opus agent + will reason over, or to check that a quote cited in a PR or plan actually + appears at the stated place. +tools: Read, Grep, Glob +model: haiku +--- + +You are QUOTE-HARVESTER. You copy text exactly, with its location. + +## Rules + +- Use the Read tool for every quote. Never reconstruct text from memory or + from a search line; a search hit only tells you where to Read. +- Quote verbatim, with the original line numbers. Keep indentation. Do not fix + typos, do not reformat, do not shorten inside a requested range. +- For a symbol, quote its whole definition: from the doc comment above it to + the end of its body. Say which lines that was. +- For a "does this quote appear here" check, answer `FOUND at :`, + `FOUND ELSEWHERE at :` or `NOT FOUND in `, and quote what + is actually at the stated lines. +- Never explain what the code does. Never compare two quotes. +- A file longer than one Read: read it in pages until the requested range is + complete; never stop at the first page. + +## Brief you must receive + +1. A list of targets: `path:start-end`, `path` + symbol name, or + `path:lines` + the text to check. +2. Optional: a maximum length per quote (default: none). + +If a target cannot be found, report it under `missing:`; do not search for a +substitute. + +## Reply format (exactly this) + +```text +status: DONE | PARTIAL +quotes: +- target: + at: :- + text: | + +checks: +- : FOUND at ... | FOUND ELSEWHERE at ... | NOT FOUND in ... +missing: +- +``` + +You never edit or create files. diff --git a/.claude/agents/worker-template-v2.md b/.claude/agents/worker-template-v2.md index 91437d07c..0934c14c4 100644 --- a/.claude/agents/worker-template-v2.md +++ b/.claude/agents/worker-template-v2.md @@ -338,7 +338,9 @@ The worker MUST NOT, under any circumstance: 7. **Add a new top-level abstraction** without `truth-architect` review per `frankenstein-checklist.md`. New struct / new trait / new layer → flag in CSI section, do not ship without review. -8. **Use `haiku` for any nested sub-spawn.** Sonnet floor per Model Policy. +8. **Use `haiku` for any nested sub-spawn other than the four harvest/executor + cards** (`harvest-scout`, `census-counter`, `quote-harvester`, + `guarded-executor`). Sonnet floor for everything else per Model Policy. 9. **Skip the mandatory reads.** A worker that grep'd before reading `LATEST_STATE.md` is operating without context; the prompt is structurally invalid for that worker. diff --git a/.claude/board/AGENT_LOG.md b/.claude/board/AGENT_LOG.md index 79d47c5bd..ac5169993 100644 --- a/.claude/board/AGENT_LOG.md +++ b/.claude/board/AGENT_LOG.md @@ -1,3 +1,10 @@ +## 2026-10-14 — first Haiku harvest run (harvest-scout card, policy change) + +- Card `harvest-scout`, one run: lines still forbidding Haiku across `.claude/{agents,skills,knowledge,v3}`, `.claude/BOOT.md`, `CLAUDE.md`, 8 patterns. +- Ledger: 9 hits reported, 9 verified by an independent grep and Reads; 0 wrong; 1 missed (`coresearch-council.md:110-111`, the phrase wraps a line), and the card's own notes named that limitation. No conclusions stated. +- Cost: about 444k subagent tokens for 8 tool calls, most of it the loaded workspace context, not the search. Briefs should stay narrow until that is measured per card. +- Outcome: three stale policy lines updated; council lenses keep their Sonnet floor (they synthesize). + ## 2026-10-03 — Explore agent: SurrealQL AST harvest (D-FPW-0) - Read-only map of `/home/user/surrealdb` parser/AST: `Part::Graph(Lookup)` per hop, `Dir::{In,Out,Both}`, edge tables with `in`/`out`, bag flatten at `val/value/get.rs:499`, `Recurse`/`RecurseInstruction`. diff --git a/.claude/knowledge/tiered-agent-execution-protocol.md b/.claude/knowledge/tiered-agent-execution-protocol.md index 3947c507e..53be8f1c3 100644 --- a/.claude/knowledge/tiered-agent-execution-protocol.md +++ b/.claude/knowledge/tiered-agent-execution-protocol.md @@ -1,4 +1,4 @@ -READ BY: any session orchestrating subagent fleets in this workspace. PROPOSES a narrow exception to the Model Policy's blanket "NEVER haiku" line for ONE role (guarded executor); the exception is ratified if and only if the operator merges the PR carrying this doc — the merge is the authorization, not this text. +READ BY: any session orchestrating subagent fleets in this workspace. Defines the three tiers; since 2026-10-14 Haiku is allowed for read-only harvest and guarded execution (§ Haiku harvest tier), no longer only the executor role. The earlier proposal text below is kept as history. > **Provenance (operator request, in-session 2026-07-22, quoted verbatim):** > "can you use opus agents for filigrane and sonnet 5 agents for grindwork @@ -25,7 +25,7 @@ READ BY: any session orchestrating subagent fleets in this workspace. PROPOSES a > disk allowance** it converts "compile the workspace" into "fill the disk > and fail every write." Cheap tokens are worthless if the disk is gone. -# Tiered agent execution — Opus filigree / Sonnet grindwork / Haiku guarded execution +# Tiered agent execution — Opus filigree / Sonnet grindwork / Haiku harvest and guarded execution ## The three tiers @@ -33,7 +33,7 @@ READ BY: any session orchestrating subagent fleets in this workspace. PROPOSES a |---|---|---|---| | Opus (or main thread) | FILIGREE: synthesis, plan authorship, adjudication of probe results vs gates, board rulings, review | read everything; write plans/knowledge/board | be used for mechanical loops | | Sonnet | GRINDWORK: write-file-from-spec, scoped edits, drafting from a complete brief | edit code/docs per brief | synthesize across sources; decide gates; touch board files unless brief says so | -| Haiku | GUARDED EXECUTION ONLY: run a pre-written bash sequence with clear START/STOP, capture output, write its OWN tag-file receipt | run the exact commands in its brief; retry per an explicit retry table | write or edit ANY source file; append to any SHARED file; interpret ambiguous failures; deviate from the command list; run commands not in the brief | +| Haiku | HARVEST (read-only discovery: candidates, counts, verbatim quotes over a closed space) and GUARDED EXECUTION (a pre-written command card) | return what it found, with locations and the commands used; run the exact commands in its card; retry per an explicit retry table | write or edit ANY source or doc file; state a conclusion, an absence or an explanation; append to any SHARED file; interpret ambiguous failures; deviate from the brief | ## The load-bearing invariant — ONE WRITER PER FILE (all tiers) @@ -219,3 +219,54 @@ guardrailed enough"). Haiku remains forbidden for synthesis, drafting, review, and any file edit. This doc is the canonical statement; cite it when spawning. If a future session finds this doc on a branch whose PR was NOT merged, the exception is not in force. + +## Haiku harvest tier (DECISION 2026-10-14) + +DECISION (operator, 2026-10-14): "Use Haiku agents for grindwork and take +Haiku off the guard list, but watch the agents closely and start using them +for very focused and scoped tasks that you use for cheap harvest discovery." +SCOPE: read-only discovery and guarded execution in this workspace; edits +stay with Sonnet. BASIS: harvest output is navigation (FIRST-HAND-SOURCE-LAW), +so a cheap model is enough to find things as long as reading and deciding +stay with a stronger one. REVISIT WHEN: the run ledger below shows the spot +checks costing more than a Sonnet run, or Haiku is proposed for edits. + +### Cards + +| card | returns | tools | +|---|---|---| +| `harvest-scout` | every candidate as `path:line` + the matching line | Read, Glob, Grep | +| `census-counter` | raw counts, each with the exact command | Read, Glob, Grep, read-only Bash | +| `quote-harvester` | verbatim text with line numbers; FOUND / NOT FOUND checks | Read, Grep, Glob | +| `guarded-executor` | a run-record for a pre-written command card | Bash, Read, Write (its own run-record only) | + +### What makes a brief Haiku-sized + +- ONE question, answerable as a list, a count or a quote. +- A CLOSED search space: exact paths or globs. "Somewhere in the repo" is + not a brief. +- The patterns written out by the orchestrator, including aliases, + fully-qualified spellings and re-exports (the measured grep failures in + CLAUDE.md were all spelling misses). +- A hit cap. +- No step that needs holding two sources in mind together. If it does, it is + an Opus task. + +### Watching closely (the supervision rules) + +1. **Harvest is navigation.** The orchestrator Reads every item it relies on + before using it in a claim, board entry, PR body or decision. A Haiku list + is never cited as evidence. +2. **Re-run one count per reply.** For `census-counter`, the orchestrator + re-runs at least one reported command and compares. +3. **Absence is never taken from Haiku.** A `hits: 0` sends the orchestrator + to Read the place the thing would live, as for any search. +4. **Record every run.** The orchestrator's `AGENT_LOG.md` entry for a wave + that used Haiku lists, per card: runs, items spot-checked, items wrong, + items missed (found later by a stronger agent or a Read). +5. **Drop back on repeat failure.** A card that misses a hit, miscounts or + states a conclusion twice on one kind of task is not used for that kind + again; that kind goes to Sonnet, and the case is noted in the ledger. +6. **No edits.** Haiku cards have no Edit tool, and `guarded-executor` + writes only its own run-record. A harvest agent that wants to change a + file reports `notes:` instead. diff --git a/.claude/skills/cca2a/concepts.md b/.claude/skills/cca2a/concepts.md index 81141b27e..1df7a7452 100644 --- a/.claude/skills/cca2a/concepts.md +++ b/.claude/skills/cca2a/concepts.md @@ -117,7 +117,9 @@ rediscovery.** - Main thread: Opus, deep thinking, full `effortLevel: high`. - Subagent grindwork (single-source mechanical): Sonnet. - Subagent accumulation (multi-source synthesis): Opus. -- NEVER Haiku — quality floor for this pattern is Sonnet. +- Haiku only for read-only harvest and guarded execution, through the four + cards in `.claude/agents/` (harvest-scout, census-counter, quote-harvester, + guarded-executor); Sonnet is the floor for edits, drafting and review. Concrete test before spawning a subagent: > "Does this agent have to read N sources and produce something that diff --git a/.claude/skills/cca2a/divergence.md b/.claude/skills/cca2a/divergence.md index 2e2056c31..667ac6d59 100644 --- a/.claude/skills/cca2a/divergence.md +++ b/.claude/skills/cca2a/divergence.md @@ -11,7 +11,7 @@ conventions prescribe. Per the 2026-04-19 audit of | Agent cards location | `.claude/agents/.md` with YAML frontmatter | | Frontmatter fields | `name`, `description`, `tools`, `model` | | Settings files | `.claude/settings.json` (project, committed) + `.claude/settings.local.json` (local, gitignored) | -| Model values | `sonnet`, `opus` (CCA2A excludes `haiku` by policy) | +| Model values | `sonnet`, `opus`, `haiku` (haiku only on the four harvest/executor cards) | | CLAUDE.md location | Project root or `.claude/CLAUDE.md` | | Permissions arrays | `permissions.ask`, `permissions.allow`, `permissions.deny` | | Hook events | `SessionStart`, `PostCompact`, etc. all official | diff --git a/.claude/skills/cca2a/procedure-bookkeeping.md b/.claude/skills/cca2a/procedure-bookkeeping.md index 2861996b2..c010e900d 100644 --- a/.claude/skills/cca2a/procedure-bookkeeping.md +++ b/.claude/skills/cca2a/procedure-bookkeeping.md @@ -66,8 +66,8 @@ table rows (one per prompt file). Literal filename match — will miss semantic overlap (that's Pass 2's job). **Governance:** Haiku is acceptable *here* because the work is -single-source-mechanical with a known output shape. The "never Haiku" -rule (see `concepts.md` § Model policy) targets synthesis; this pass +single-source-mechanical with a known output shape. The Haiku limits +(see `concepts.md` § Model policy) target synthesis and edits; this pass does zero synthesis. ### Pass 2 — Opus meta-synthesizer (one-shot, ledger-only inputs) diff --git a/.claude/v3/agents/BOOT.md b/.claude/v3/agents/BOOT.md index 624b7ede3..9595eefc2 100644 --- a/.claude/v3/agents/BOOT.md +++ b/.claude/v3/agents/BOOT.md @@ -56,7 +56,10 @@ Every V3 card reads, in order: Sonnet 5 for grindwork (mechanical wiring, greps, censuses, doc stubs from spec); Fable/Opus tier for decisions, plans needing nuance, reviews, and -anything accumulating multiple sources. Never Haiku. +anything accumulating multiple sources. Haiku (since 2026-10-14) only for +read-only harvest and guarded execution through the four cards in +`.claude/agents/` (harvest-scout, census-counter, quote-harvester, +guarded-executor): greps and censuses can go there, edits cannot. **Sonnet footgun-proofing (operator, 2026-07-02):** every Sonnet worker brief MUST paste the §1 preamble of diff --git a/CLAUDE.md b/CLAUDE.md index de8da0b59..71bdd6388 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1104,23 +1104,31 @@ the runtime Blackboard. Keep them architecturally distinct. - **`Explore` subagent:** Sonnet default. Search is pattern matching. If the explore requires synthesis across many files (mapping an architecture), escalate to Opus. -- **NEVER `haiku` for any subagent in this workspace** — with ONE narrow, - contract-gated exception: the **guarded-executor** role (run a pre-written, - `-p`-scoped bash/cargo card with explicit START/STOP, retry table, root- - diagnostic output discipline (true exit status preserved, complete output - retained, the FIRST relevant diagnostic block read in full — a short tail - is display only), one shared `target/`, and a mandatory append-only log - entry; never authors, decides, or edits any file but the log). See - `.claude/knowledge/tiered-agent-execution-protocol.md` for the full - contract. Outside that role the quality floor is Sonnet regardless of task - simplicity — Haiku remains forbidden for synthesis, drafting, review, and - any file edit. +- **`haiku` for scoped, read-only harvest grindwork and guarded execution.** + 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. Four cards carry the contract: + `harvest-scout` (find candidates), `census-counter` (count, with the + command), `quote-harvester` (verbatim text with line numbers) and + `guarded-executor` (run a pre-written `-p`-scoped command card). Haiku + still does not edit or write source or docs, draft, review, synthesize or + decide; those stay with Sonnet and Opus. The orchestrator watches closely: + it Reads every harvested item it relies on, re-runs at least one reported + count per reply, and records hits and misses per run; a card that misses or + concludes twice on one kind of task is dropped back to Sonnet for that + kind. Full contract and supervision rules: + `.claude/knowledge/tiered-agent-execution-protocol.md` § Haiku harvest tier. + SCOPE: this workspace. REVISIT WHEN: the run ledger shows a miss rate that + makes the spot checks cost more than a Sonnet run, or Haiku is proposed for + edits. **Concrete test before spawning a subagent:** > "Does this agent have to read N sources and produce something that > only makes sense when those sources are held in mind together?" > > **Yes → Opus.** No (one source in, one shape out) → Sonnet. +> Read-only and the answer is a list, a count or a quote → Haiku harvest card. **Settings baseline** (`.claude/settings.local.json`, gitignored): `alwaysThinkingEnabled: true`, `effortLevel: high`, From f4e5d95bdc9ebab30e044fc544d0dc4fb914f0de Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 14 Oct 2026 19:51:14 +0000 Subject: [PATCH 2/2] Haiku cards for deep mapping and exact spec edits; record #1551 Two more cards: substrate-mapper (a fact map of one bounded unit, written to one file, so the orchestrator reads the map instead of the source) and spec-editor (exact edits to one file, each applied only if its anchor occurs once). Supervision gains map spot-checks and a diff read per edit. Policy text in CLAUDE.md, both BOOT files, the agents README, worker-template-v2, cca2a and the protocol now names six cards. AGENT_LOG: two more scout runs, 2/2 and 7/7 verified. Board: #1551 arc and LATEST_STATE entries. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011BMJnDBAfzcuQh5HeT39Rh --- .claude/BOOT.md | 10 +-- .claude/agents/BOOT.md | 6 +- .claude/agents/README.md | 18 +++-- .claude/agents/spec-editor.md | 47 ++++++++++++ .claude/agents/substrate-mapper.md | 71 +++++++++++++++++++ .claude/agents/worker-template-v2.md | 6 +- .claude/board/AGENT_LOG.md | 1 + .claude/board/LATEST_STATE.md | 4 ++ .claude/board/PR_ARC_INVENTORY.md | 7 ++ .../tiered-agent-execution-protocol.md | 27 +++++-- .claude/skills/cca2a/concepts.md | 7 +- .claude/skills/cca2a/divergence.md | 2 +- .claude/v3/agents/BOOT.md | 7 +- CLAUDE.md | 21 ++++-- 14 files changed, 200 insertions(+), 34 deletions(-) create mode 100644 .claude/agents/spec-editor.md create mode 100644 .claude/agents/substrate-mapper.md diff --git a/.claude/BOOT.md b/.claude/BOOT.md index 8cd763dad..f7780a925 100644 --- a/.claude/BOOT.md +++ b/.claude/BOOT.md @@ -110,10 +110,10 @@ version matters — typically mid-session, not at cold start): 2. **Model policy.** Main thread on Opus with deep thinking. Subagents: Sonnet for grindwork (single-source mechanical), Opus for accumulation (multi-source synthesis). Haiku for read-only - harvest (candidates, counts, verbatim quotes over a closed space) and - guarded execution, through the `harvest-scout`, `census-counter`, - `quote-harvester` and `guarded-executor` cards, never for edits or - decisions (`.claude/knowledge/tiered-agent-execution-protocol.md` + harvest, deep substrate mapping, exact spec edits and guarded execution, + through the six Haiku cards (`harvest-scout`, `census-counter`, + `quote-harvester`, `substrate-mapper`, `spec-editor`, + `guarded-executor`), never for authoring or decisions (`.claude/knowledge/tiered-agent-execution-protocol.md` § Haiku harvest tier). Full spec in CLAUDE.md §Model Policy. 3. **GitHub access.** Zipball to `/tmp/sources/` + local grep for 3+ reads per external repo. MCP github only for writes (PR, @@ -231,7 +231,7 @@ of contents: - CLAUDE.md §Session Start — mandatory reads (same three as above) - CLAUDE.md §A2A Orchestration — both layers in detail - CLAUDE.md §Model Policy — grindwork vs accumulation; Haiku only for - read-only harvest and guarded execution (four cards, supervised) + harvest, deep mapping, spec edits and execution (six cards, supervised) - CLAUDE.md §GitHub Access Policy — zipball for reads - CLAUDE.md §Workspace Structure — 11-crate layout - CLAUDE.md §Knowledge Base — all `.claude/knowledge/` files diff --git a/.claude/agents/BOOT.md b/.claude/agents/BOOT.md index 25b990be5..d83da05cd 100644 --- a/.claude/agents/BOOT.md +++ b/.claude/agents/BOOT.md @@ -147,9 +147,9 @@ specialist judgment — they route, prime, and compose. Meta-agents run on Opus. Specialists run on Sonnet for single-source grindwork (draft-file-from-spec); Opus for multi-source accumulation. -Haiku only through the four harvest/executor cards (`harvest-scout`, -`census-counter`, `quote-harvester`, `guarded-executor`), read-only and -supervised. See `../CLAUDE.md § Model Policy`. +Haiku only through the six supervised cards (`harvest-scout`, +`census-counter`, `quote-harvester`, `substrate-mapper`, `spec-editor`, +`guarded-executor`). See `../CLAUDE.md § Model Policy`. ## Session-Start Knowledge Bootload (per agent) diff --git a/.claude/agents/README.md b/.claude/agents/README.md index 1f1785bcb..c228be0ca 100644 --- a/.claude/agents/README.md +++ b/.claude/agents/README.md @@ -8,8 +8,8 @@ > when starting a session; read this file when deciding which > specialist to wake for a specific task. -Ensemble size: **22 specialists + 5 meta-agents**, plus the four Haiku -harvest/executor cards (§ Haiku harvest tier). Every card is at +Ensemble size: **22 specialists + 5 meta-agents**, plus the six Haiku +cards (§ Haiku harvest tier). Every card is at `.claude/agents/.md`. Each card declares its own `tools`, `model`, and `READ BY:` knowledge prerequisites. @@ -230,6 +230,15 @@ it. Read-only Bash. Returns verbatim text with line numbers for given ranges or symbols, and checks whether a cited quote is where a document says it is. +### `substrate-mapper` +Turns one bounded unit (module, crate `src/`, doc folder) into a fact map in +one named file: items, verbatim signatures and doc lines, names each body +mentions, candidate callers. The tool for outsourcing deep mapping. + +### `spec-editor` +Applies exact (old, new) edits to one file, each only if its anchor occurs +exactly once. The orchestrator writes every edit in full and reads the diff. + ### `guarded-executor` Runs a pre-written, numbered command card (cargo `-p ...`, probes) and writes one run-record. Never edits source, never fixes. @@ -241,8 +250,9 @@ one run-record. Never edits source, never fixes. Decision flow: 1. **Session just started?** → `workspace-primer` first. - **Need a list, a count or a quote from a closed space?** → a Haiku - harvest card (`harvest-scout`, `census-counter`, `quote-harvester`). + **Need a list, a count, a quote or a map of a closed space?** → a Haiku + card (`harvest-scout`, `census-counter`, `quote-harvester`, + `substrate-mapper`). 2. **Problem needs 3+ specialists?** → `adk-coordinator` to frame. 3. **Proposal adds a layer or makes claims without measurement?** → `truth-architect` is the mandatory reviewer; loop it in early. diff --git a/.claude/agents/spec-editor.md b/.claude/agents/spec-editor.md new file mode 100644 index 000000000..5bdeb3fa7 --- /dev/null +++ b/.claude/agents/spec-editor.md @@ -0,0 +1,47 @@ +--- +name: spec-editor +description: > + Haiku editor for ONE file and an exact edit spec: a list of + (old text, new text) replacements or anchored insertions written out in + full by the orchestrator. Applies each edit only if its anchor occurs + exactly once, applies nothing else, and reports per edit APPLIED or + REFUSED. No cargo, no git, no judgement about what the text should say. + The orchestrator reads the diff of every edit. +tools: Read, Edit +model: haiku +--- + +You are SPEC-EDITOR. You apply exact edits to one file. You do not write +content of your own. + +## Rules + +- Read the whole target file first (every page). +- For each edit in order: the old text (or anchor) must occur EXACTLY ONCE in + the current file. If it occurs zero times or more than once, REFUSE that + edit and continue with the next; never pick one of several matches, never + approximate. +- Apply the new text exactly as given: same whitespace, same line breaks. + Do not fix typos, reflow, reformat, or "improve" anything in the spec or + around it. +- Touch only the one file named in the brief. No other edits, no new files. +- Never run commands. Never commit. +- If the spec looks wrong to you, apply it anyway if its anchor matches, and + add one line under `notes:`. + +## Brief you must receive + +1. The target file path. +2. The numbered edits, each as `old:` / `new:` blocks (or `after:` / `insert:` + for an insertion), written in full. + +## Reply (exactly this) + +```text +status: DONE | PARTIAL +file: +edits: +- 1: APPLIED | REFUSED (anchor found times) +notes: +- +``` diff --git a/.claude/agents/substrate-mapper.md b/.claude/agents/substrate-mapper.md new file mode 100644 index 000000000..191192185 --- /dev/null +++ b/.claude/agents/substrate-mapper.md @@ -0,0 +1,71 @@ +--- +name: substrate-mapper +description: > + Haiku mapper for ONE bounded unit of the substrate (a module file, a crate's + src/ directory, a plan or knowledge folder). Reads every file in the unit in + full and writes a structured fact map to ONE output file the orchestrator + names: public items with kind, location, signature line and the first line + of their doc comment; what each item names in its body; who in a given + caller space mentions it. Facts copied from source, never interpretation. + Use to outsource deep mapping of large surfaces so the orchestrator reads a + compact map instead of the source. +tools: Read, Glob, Grep, Write +model: haiku +--- + +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. + +## Rules + +- Read every file in the unit with the Read tool, every page of it. A file + you did not finish reading is listed under `unread` in the map, never + mapped from a search hit. +- Copy, do not describe. A signature is the source line verbatim. A purpose + is the first line of the doc comment verbatim, or `—` if there is none. + Never write your own summary of what an item does. +- "Mentions" are names that appear in an item's body (types, functions, + constants), copied as written. Do not resolve them, do not guess where they + are defined. +- "Mentioned by" comes from a search over the caller space you were given, + and is a candidate list (`path:line`), not a call graph. Say so in the map + 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. + +## Brief you must receive (stop if any item is missing) + +1. The unit: exact files or one directory (with a file glob). +2. The caller space for "mentioned by": exact directories, or `none`. +3. The output path (under the session scratchpad or + `.claude/board/exec-runs/`). +4. Which item kinds to map (default: every `pub` item; for markdown units, + every heading with its line). + +If anything is missing, reply `status: BRIEF-INCOMPLETE` and name it. + +## Map file format + +```markdown +# Map: +read: files, all pages | unread: +mentioned-by is a search over ; candidates, not a call graph. + +## +| item | kind | at | signature (verbatim) | doc, first line (verbatim) | mentions | mentioned by | +|---|---|---|---|---|---|---| +``` + +## Reply (exactly this) + +```text +status: DONE | PARTIAL | BRIEF-INCOMPLETE +map: +files: / +items: +unread: +- +``` diff --git a/.claude/agents/worker-template-v2.md b/.claude/agents/worker-template-v2.md index 0934c14c4..a5f388972 100644 --- a/.claude/agents/worker-template-v2.md +++ b/.claude/agents/worker-template-v2.md @@ -338,9 +338,9 @@ The worker MUST NOT, under any circumstance: 7. **Add a new top-level abstraction** without `truth-architect` review per `frankenstein-checklist.md`. New struct / new trait / new layer → flag in CSI section, do not ship without review. -8. **Use `haiku` for any nested sub-spawn other than the four harvest/executor - cards** (`harvest-scout`, `census-counter`, `quote-harvester`, - `guarded-executor`). Sonnet floor for everything else per Model Policy. +8. **Use `haiku` for any nested sub-spawn other than the six Haiku cards** + (`harvest-scout`, `census-counter`, `quote-harvester`, `substrate-mapper`, + `spec-editor`, `guarded-executor`). Sonnet floor for everything else per Model Policy. 9. **Skip the mandatory reads.** A worker that grep'd before reading `LATEST_STATE.md` is operating without context; the prompt is structurally invalid for that worker. diff --git a/.claude/board/AGENT_LOG.md b/.claude/board/AGENT_LOG.md index ac5169993..5c4087679 100644 --- a/.claude/board/AGENT_LOG.md +++ b/.claude/board/AGENT_LOG.md @@ -4,6 +4,7 @@ - Ledger: 9 hits reported, 9 verified by an independent grep and Reads; 0 wrong; 1 missed (`coresearch-council.md:110-111`, the phrase wraps a line), and the card's own notes named that limitation. No conclusions stated. - Cost: about 444k subagent tokens for 8 tool calls, most of it the loaded workspace context, not the search. Briefs should stay narrow until that is measured per card. - Outcome: three stale policy lines updated; council lenses keep their Sonnet floor (they synthesize). +- Two more harvest-scout runs (ndarray, tesseract-rs `haiku` lines): 2/2 and 7/7 hits verified by grep; 0 wrong, 0 missed; ~434k and ~437k subagent tokens. ## 2026-10-03 — Explore agent: SurrealQL AST harvest (D-FPW-0) diff --git a/.claude/board/LATEST_STATE.md b/.claude/board/LATEST_STATE.md index 666185905..8e05023b6 100644 --- a/.claude/board/LATEST_STATE.md +++ b/.claude/board/LATEST_STATE.md @@ -1,3 +1,7 @@ +## 2026-10-14 — main after #1551 (merged) + +- **On `main` (#1551, merged `9337da49`):** D-HOLO H11 and H12 pre-registered, H6b amended with connectedness; plan only, nothing run. + ## 2026-10-14 — main after #1550 (merged) - **On `main` (#1550, merged `5cbb3fd5`):** D-HOLO H1/H5/H6 measured (examples only, no production change): symbolic interval closure cheapest; K-branch evaluation flat in K but orientation-dependent; coordinate-native prefix counting wins only once its build is amortized. Plan `d-holo-address-indexed-algebra-v1.md`; entry `2026-10-14-d-holo-falsifiers.md`. diff --git a/.claude/board/PR_ARC_INVENTORY.md b/.claude/board/PR_ARC_INVENTORY.md index 2084b5c92..49be75a56 100644 --- a/.claude/board/PR_ARC_INVENTORY.md +++ b/.claude/board/PR_ARC_INVENTORY.md @@ -1,3 +1,10 @@ +## 2026-10-14 — lance-graph PR #1551 (merged `9337da49`, branch `ccr-9f3b8075-74u47l-holo-prereg`, head `d56f2581`, 1 commit) — D-HOLO: pre-register H11 and H12, connectedness in H6b + +- **Added:** plan sections H11 (stacked logic: answers no single brick gives, == oracle; cost below separate runs at d = 4; no confidence inflation, gate disable must inflate) and H12 (semantic map of inference functions across OpenNARS, ONA and the NAL polyfill; stability rule: the last system adds zero nodes in both orders). STATUS rows D-HOLO-H11/H12; the #1550 arc and LATEST_STATE entries. +- **Locked:** H6b amended before any run with a connected-component column and a doughnut fixture; connectedness is a selector input to test, never a constraint (Haspelmath 2003 as basis). +- **Deferred / open:** nothing run; H13 (saccades) and meta-level inertness tests unregistered (need a named focus signal and a stated meaning). +- **Confidence:** n/a (pre-registration only). + ## 2026-10-14 — lance-graph PR #1550 (merged `5cbb3fd5`, branch `ccr-9f3b8075-74u47l-holo`, head `91ca4359`, 10 commits) — D-HOLO: falsifiers H1, H5, H6 for the address-indexed algebra - **Added:** plan `d-holo-address-indexed-algebra-v1.md` (pre-registered before any probe); three examples in `lance-graph-mask-risc`: `holo_k_branch_probe` (H1), `holo_coord_probe` (H5), `holo_interval_probe` (H6), each with row-oracle tests. Board entry `2026-10-14-d-holo-falsifiers.md`; rows D-HOLO-H1/H5/H6 and the pre-registrations H6b/H8/H9. Also the owed #1548 board reconciliation. diff --git a/.claude/knowledge/tiered-agent-execution-protocol.md b/.claude/knowledge/tiered-agent-execution-protocol.md index 53be8f1c3..acb668b19 100644 --- a/.claude/knowledge/tiered-agent-execution-protocol.md +++ b/.claude/knowledge/tiered-agent-execution-protocol.md @@ -225,8 +225,11 @@ merged, the exception is not in force. DECISION (operator, 2026-10-14): "Use Haiku agents for grindwork and take Haiku off the guard list, but watch the agents closely and start using them for very focused and scoped tasks that you use for cheap harvest discovery." -SCOPE: read-only discovery and guarded execution in this workspace; edits -stay with Sonnet. BASIS: harvest output is navigation (FIRST-HAND-SOURCE-LAW), +SCOPE: read-only discovery, deep mapping, exact spec edits and guarded +execution in this workspace; authoring stays with Sonnet. Follow-up +(operator, same day): "Goal is to outsource deeper mapping due to enormous +token equivalent of the substrate", and Haiku may apply exact edits from a +written spec. BASIS: harvest output is navigation (FIRST-HAND-SOURCE-LAW), so a cheap model is enough to find things as long as reading and deciding stay with a stronger one. REVISIT WHEN: the run ledger below shows the spot checks costing more than a Sonnet run, or Haiku is proposed for edits. @@ -238,6 +241,8 @@ checks costing more than a Sonnet run, or Haiku is proposed for edits. | `harvest-scout` | every candidate as `path:line` + the matching line | Read, Glob, Grep | | `census-counter` | raw counts, each with the exact command | Read, Glob, Grep, read-only Bash | | `quote-harvester` | verbatim text with line numbers; FOUND / NOT FOUND checks | Read, Grep, Glob | +| `substrate-mapper` | a fact map of one bounded unit, written to one named file | Read, Glob, Grep, Write (its map only) | +| `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) | ### What makes a brief Haiku-sized @@ -267,6 +272,18 @@ checks costing more than a Sonnet run, or Haiku is proposed for edits. 5. **Drop back on repeat failure.** A card that misses a hit, miscounts or states a conclusion twice on one kind of task is not used for that kind again; that kind goes to Sonnet, and the case is noted in the ledger. -6. **No edits.** Haiku cards have no Edit tool, and `guarded-executor` - writes only its own run-record. A harvest agent that wants to change a - file reports `notes:` instead. +6. **No authored content.** Only `spec-editor` edits, and only text the + orchestrator wrote out in full; the orchestrator reads its diff before + committing. `substrate-mapper` writes only its map, `guarded-executor` + only its run-record. Other cards have no write tool. +7. **Maps are checked against source.** For every map, the orchestrator + Reads at least two mapped items at their stated locations before relying + on the map, and treats `mentioned by` as candidates, never as a call graph. + +### Mapping a large surface + +Split the surface into units small enough to read in full (one module file, +or one directory of a few thousand lines). Run one `substrate-mapper` per +unit, in parallel only over disjoint units, each with its own output file. +The orchestrator reads the maps, not the source, and Reads source only where +a decision rests on it. diff --git a/.claude/skills/cca2a/concepts.md b/.claude/skills/cca2a/concepts.md index 1df7a7452..a7be1f96d 100644 --- a/.claude/skills/cca2a/concepts.md +++ b/.claude/skills/cca2a/concepts.md @@ -117,9 +117,10 @@ rediscovery.** - Main thread: Opus, deep thinking, full `effortLevel: high`. - Subagent grindwork (single-source mechanical): Sonnet. - Subagent accumulation (multi-source synthesis): Opus. -- Haiku only for read-only harvest and guarded execution, through the four - cards in `.claude/agents/` (harvest-scout, census-counter, quote-harvester, - guarded-executor); Sonnet is the floor for edits, drafting and review. +- Haiku only through the six cards in `.claude/agents/` (harvest-scout, + census-counter, quote-harvester, substrate-mapper, spec-editor, + guarded-executor): harvest, deep mapping, exact spec edits, execution. + Sonnet is the floor for authoring, drafting and review. Concrete test before spawning a subagent: > "Does this agent have to read N sources and produce something that diff --git a/.claude/skills/cca2a/divergence.md b/.claude/skills/cca2a/divergence.md index 667ac6d59..dff2e335b 100644 --- a/.claude/skills/cca2a/divergence.md +++ b/.claude/skills/cca2a/divergence.md @@ -11,7 +11,7 @@ conventions prescribe. Per the 2026-04-19 audit of | Agent cards location | `.claude/agents/.md` with YAML frontmatter | | Frontmatter fields | `name`, `description`, `tools`, `model` | | Settings files | `.claude/settings.json` (project, committed) + `.claude/settings.local.json` (local, gitignored) | -| Model values | `sonnet`, `opus`, `haiku` (haiku only on the four harvest/executor cards) | +| Model values | `sonnet`, `opus`, `haiku` (haiku only on the six Haiku cards) | | CLAUDE.md location | Project root or `.claude/CLAUDE.md` | | Permissions arrays | `permissions.ask`, `permissions.allow`, `permissions.deny` | | Hook events | `SessionStart`, `PostCompact`, etc. all official | diff --git a/.claude/v3/agents/BOOT.md b/.claude/v3/agents/BOOT.md index 9595eefc2..9239495ff 100644 --- a/.claude/v3/agents/BOOT.md +++ b/.claude/v3/agents/BOOT.md @@ -57,9 +57,10 @@ Every V3 card reads, in order: Sonnet 5 for grindwork (mechanical wiring, greps, censuses, doc stubs from spec); Fable/Opus tier for decisions, plans needing nuance, reviews, and anything accumulating multiple sources. Haiku (since 2026-10-14) only for -read-only harvest and guarded execution through the four cards in -`.claude/agents/` (harvest-scout, census-counter, quote-harvester, -guarded-executor): greps and censuses can go there, edits cannot. +harvest, deep mapping, exact spec edits and guarded execution through the six +cards in `.claude/agents/` (harvest-scout, census-counter, quote-harvester, +substrate-mapper, spec-editor, guarded-executor): greps, censuses and maps +go there; authoring does not. **Sonnet footgun-proofing (operator, 2026-07-02):** every Sonnet worker brief MUST paste the §1 preamble of diff --git a/CLAUDE.md b/CLAUDE.md index 71bdd6388..47fd8738b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1108,27 +1108,34 @@ 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. Four cards carry the contract: + locations — never a conclusion. 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: `harvest-scout` (find candidates), `census-counter` (count, with the - command), `quote-harvester` (verbatim text with line numbers) and + command), `quote-harvester` (verbatim text with line numbers), + `substrate-mapper` (a fact map of one module, crate or folder, written to + one file), `spec-editor` (exact edits to one file from a written spec) and `guarded-executor` (run a pre-written `-p`-scoped command card). Haiku - still does not edit or write source or docs, draft, review, synthesize or - decide; those stay with Sonnet and Opus. The orchestrator watches closely: + still does not author content, draft, review, synthesize or decide; those + stay with Sonnet and Opus. The orchestrator watches closely: it Reads every harvested item it relies on, re-runs at least one reported - count per reply, and records hits and misses per run; a card that misses or + count per reply, spot-checks every map against its source, reads the diff + of every `spec-editor` edit, and records hits and misses per run; a card that misses or concludes twice on one kind of task is dropped back to Sonnet for that kind. Full contract and supervision rules: `.claude/knowledge/tiered-agent-execution-protocol.md` § Haiku harvest tier. SCOPE: this workspace. REVISIT WHEN: the run ledger shows a miss rate that makes the spot checks cost more than a Sonnet run, or Haiku is proposed for - edits. + edits that author content. **Concrete test before spawning a subagent:** > "Does this agent have to read N sources and produce something that > only makes sense when those sources are held in mind together?" > > **Yes → Opus.** No (one source in, one shape out) → Sonnet. -> Read-only and the answer is a list, a count or a quote → Haiku harvest card. +> Read-only and the answer is a list, a count, a quote or a fact map, or an +> edit fully written out in the brief → Haiku card. **Settings baseline** (`.claude/settings.local.json`, gitignored): `alwaysThinkingEnabled: true`, `effortLevel: high`,