diff --git a/.claude/BOOT.md b/.claude/BOOT.md index db5434f30..f7780a925 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, 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, 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 + 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 fff62b2af..d83da05cd 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 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 eda8a540a..c228be0ca 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 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. @@ -210,11 +211,48 @@ 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. + +### `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. + +--- + ## How to pick the right agent Decision flow: 1. **Session just started?** → `workspace-primer` first. + **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/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/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 91437d07c..a5f388972 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 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 79d47c5bd..5c4087679 100644 --- a/.claude/board/AGENT_LOG.md +++ b/.claude/board/AGENT_LOG.md @@ -1,3 +1,11 @@ +## 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). +- 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) - 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/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 3947c507e..acb668b19 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,71 @@ 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, 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. + +### 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 | +| `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 + +- 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 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 81141b27e..a7be1f96d 100644 --- a/.claude/skills/cca2a/concepts.md +++ b/.claude/skills/cca2a/concepts.md @@ -117,7 +117,10 @@ 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 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 2e2056c31..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` (CCA2A excludes `haiku` by policy) | +| 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/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..9239495ff 100644 --- a/.claude/v3/agents/BOOT.md +++ b/.claude/v3/agents/BOOT.md @@ -56,7 +56,11 @@ 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 +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 de8da0b59..47fd8738b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1104,23 +1104,38 @@ 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. 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), + `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 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, 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 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, 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`,