model-orchestrator 0.1.35 → 1.0.0

package/templates/intermediate/TIERS.md

@@ -1,93 +1,54 @@
-# TIERS.md: capability tiers and the three cost levers
+# TIERS.md: choose capability, effort and tool reach
 
-The router routes by capability tier, not model name. Each tier maps to a family alias where the vendor offers one, so a routine version bump needs no file change.
+{{STACK_SUMMARY}}
 
-| Tier | Purpose | On {{PRIMARY_NAME}} |
-|---|---|---|
-| deep | ambiguous planning, architecture, strategy, hard debugging | {{PRIMARY_DEEP}} |
-| standard | code writing, code review, execution, live research synthesis | {{PRIMARY_STANDARD}} |
-| fast | classification, extraction, formatting, bulk summarization | {{PRIMARY_FAST}} |
-| escalation | above deep: only when the human asks, or when deep has already run, the call is still unresolved, and the change is irreversible | your vendor's strongest model, if you have one |
-
-Non-primary lanes are owned by `DELEGATION_MATRIX.md`.
-
-## Effort per agent (the third lever)
-
-Tier sets the price per token. Token discipline sets how many tokens. **Effort sets how hard each call thinks.**
-
-`cli-run --effort auto` is a heuristic, not a measurement: prompts below 4,000 characters resolve to medium and longer prompts resolve to high. A codex `--audit` always resolves to high because stakes set the floor. Auto never resolves above high. Name `xhigh` explicitly for a security-critical or irreversible audit.
-
-| Agent | Tier | Effort | Why |
-|---|---|---|---|
-| deep-planner | deep | xhigh | judges every build twice; expensive to get wrong |
-| code-reviewer | standard | high | every endpoint is internet-facing |
-| finding-verifier | standard | high | judging a claim is harder than producing it |
-| builder | standard | high | a botched deploy is the costly failure |
-| live-researcher | standard | medium | tools do the retrieval |
-| bulk-worker | fast | low | the biggest cost win |
-| done-verifier | fast | low | a done-signal check is a lookup, not a judgment call |
-| reader | fast | low | digestion, not judgment |
-
-## Three inputs, not one
-
-Role alone does not decide a route. Two more inputs move it, and they move it in
-opposite directions, so state them separately instead of folding them into the
-role.
+When choosing a model, use the job's required capability and the lane's live roster. A tier names a job; a current family alias or explicit model choice implements it.
 
-**Complexity moves the effort.** The same role does not need the same reasoning
-on every task.
-
-| Complexity | What it looks like | What moves |
+| Tier | Use for | On {{PRIMARY_NAME}} |
 |---|---|---|
-| simple | one file, one obvious edit, no unknowns | drop one effort level |
-| standard | the default | the table above |
-| complex | several surfaces, or an unknown cause | keep effort, add the deep-tier checkpoint |
-| critical | irreversible, or it rewrites a standing rule | the escalation rule below applies |
+| planning model | ambiguous planning, architecture, strategy, unknown causes | {{PRIMARY_DEEP}} |
+| working model | code writing, review, execution and research synthesis | {{PRIMARY_STANDARD}} |
+| cheap model | classification, extraction, formatting and bulk summaries | {{PRIMARY_FAST}} |
 
-The dial that pays for itself: **a worker executing a finished plan needs less
-reasoning than the reviewer judging its output.** When the plan is airtight the
-spec is carrying the thinking, so builder drops to medium. When the plan is
-vague, fix the plan; do not buy reasoning to paper over it.
+When selecting another AI tool, use `DELEGATION_MATRIX.md` and verify its current availability. When data must remain local, choose a local runtime with the required privacy boundary.
 
-**Stakes move the tier and the reader, never just the effort.** These four are
-the ones worth naming, because their failures are not recoverable by editing the
-code afterwards.
+## Model and effort per job
 
-Stakes means what a mistake would cost: a security hole, leaked personal data,
-lost data, or something you can't undo. Most tasks are low-stakes and route
-normally.
+When routing, consider three levers together: tier sets capability and price; scoped context limits token use; effort sets how much reasoning the call applies.
 
-| Stakes | Present when the change touches | What it buys |
-|---|---|---|
-| security | auth, tokens, sessions, routes, untrusted input | the challenge pass, ideally a different model family |
-| privacy | personal data, anything leaving the machine | the local lane, and a named check on what is sent |
-| data loss | deletion, bulk mutation, migrations, overwrites | a reviewed rollback path before the change is written |
-| irreversible | publishing, sending, rotating, anything with an audience | a human yes at Stage 5b, never an agent's |
+| Role | Starting tier | Starting effort | Reassess when |
+|---|---|---|---|
+| {{TIER_PLANNER_ROLE}} | planning model | xhigh where supported | The decision can be resolved from a known plan or needs a new capability |
+| {{TIER_REVIEW_ROLE}} | working model | high | Security, privacy or irreversible effects raise the review scope |
+| {{TIER_FINDING_ROLE}} | working model | high | Reproduction needs another runtime or access path |
+| {{TIER_BUILDER_ROLE}} | working model | high | Architecture, security or irreversible work needs xhigh and suitable model capability |
+| {{TIER_LIVE_ROLE}} | working model | medium | Synthesis becomes complex or sources disagree |
+| {{TIER_BULK_ROLE}} | cheap model | low | The input stops fitting the given categories |
+| {{TIER_DONE_ROLE}} | cheap model | low | The definition of done requires interpretation or unavailable tools |
+| {{TIER_READER_ROLE}} | cheap model | low | The requested result needs judgment across sources |
 
-High stakes raise code-reviewer to xhigh, and a security-shaped diff goes to
-the challenge lane rather than to a second read by the same family. Stakes are
-not a synonym for difficulty: a one-line change to an auth check is simple and
-high-stakes at the same time, and it is the stakes that decide the route.
+When the vendor uses different effort names, choose its equivalent after reading its current capabilities. Before each build, probe the live model roster, compare the configured pin with the lane's default, and record the selected model and effort with a reason. A pin below the current default calls for review; a newer model still needs to fit the job.
 
-**Reserve the top of the ladder for evidence.** xhigh and the escalation tier are
-bought with a named reason: a reproduced failure, a checkpoint that came back
-unresolved, an irreversible change. A task that merely feels hard is a deep-tier
-task, not an escalation.
+## Role, complexity and stakes
 
-## Why split tiers: robustness first, cost second
+- **Role:** choose the agent whose tools and task match the work.
+- **Complexity:** increase reasoning for ambiguity, interacting systems or an unknown cause; lower it for bounded retrieval and mechanical work.
+- **Stakes:** choose the reviewer and verification needed for the consequence of a mistake.
+- **Reach:** choose a lane that can read the required sources, run the relevant checks and hold enough context.
+- **Capacity:** account for context headroom, concurrency and the lane's current usage limits.
 
-The split produces better work. The deep tier steers every build twice, and what it steers is **judgment, never retrieval**: the orchestrator sweeps everything it touches itself and hands the deep tier a finished map. Paying deep-tier rates for a file list is the most expensive routing mistake available.
+When security, personal data, deletion, bulk mutation or irreversible actions are involved, name the boundary and test it. Use a different model family for the build's single audit pass, with a companion reviewer asking scope versus ask in the same step. Reserve authorization for actions outside the user's existing mandate.
 
-Against a baseline of "standard tier with no consults", default checkpoints are a spend increase. That is the accepted trade, not a saving to claim.
+## Effort through the lane runner
 
-## Escalation above deep
+When using `aunx cli-run --effort auto`, treat its result as a prompt-size or audit-scope heuristic. It resolves to medium or high, and an audit lane may impose its own effort floor; check the lane's configuration. For a build, select high explicitly; for security-critical or irreversible work, select xhigh explicitly where the lane supports it.
 
-Fires on exactly two conditions: (a) the human asks for it directly; or (b) all three of: deep has already run on this task, the decision is still unresolved, and the change is irreversible or rewrites a standing rule. (b) is a conjunction, not a mood. A failed attempt is an escalation-ladder event; a hard problem is a deep-tier event; neither reaches the top model alone. It replaces the second deep consult, never adds a third. Say so whenever it fires.
+When a lane lacks an effort flag, choose its model and task scope directly. The runner reports an unsupported effort request as a usage error.
 
-## Slotting a new model
+## Reassess a route
 
-1. Newer version of an existing family: same tier; aliases pick it up.
-2. New family above your deep model: candidate for deep. Confirm with the human before touching agent files.
-3. New family between tiers: slot by the vendor's own positioning; confirm if it would change who handles a task type.
-4. New cheap family below fast: candidate for fast if quality holds.
-5. Deprecation notice on a slotted model: move the tier immediately and note it here.
+- When a check fails, diagnose its failure before another attempt and state any route change.
+- When the lane lacks required access, hand that part to a lane with authorized reach and continue independent work.
+- When a vendor deprecates a model, verify the replacement from the current roster and update the affected configuration.
+- When changing a model would change cost, privacy or authority beyond the approved scope, present the choice to the user.
+- When the strongest eligible route still cannot resolve the task, return the evidence, partial result and needed decision.

package/templates/tools/README.md

@@ -4,7 +4,7 @@ Companion tools: not AIs, but things the AIs call. Each subfolder is written onl
 
 | Folder | Written | Contents |
 |---|---|---|
-| `codecalc/` | when codecalc is selected (recommended, default yes) | `CODECALC.md` (install, per-client registration, the skill) and `mcp/` snippets for the agents its own `setup --write` does not cover |
+| `codecalc/` | when codecalc is selected (optional, default no) | `CODECALC.md` (install, per-client registration, the skill) and `mcp/` snippets for the agents its own `setup --write` does not cover |
 | `obsidian-tc/` | when obsidian-tc is selected (optional, default no; needs an Obsidian vault, Node 24+, Ollama or a cloud embeddings key) | `OBSIDIAN-TC.md` (what you need first, install, per-agent registration, security posture) and `mcp/` snippets |
 | `context7/` | when context7 is selected (optional, default no; needs a network call, a Node 18+ local alternative, an optional API key) | `CONTEXT7.md` (what you need first, install, per-agent registration, security posture) and `mcp/` snippets |
 

package/templates/tools/obsidian-tc/OBSIDIAN-TC.md

@@ -12,7 +12,7 @@ A durable, searchable, governed store that the protocols can call by name:
 |---|---|
 | find what exists before writing (deep research dedupe, gap analysis) | `semantic_search`, `search_text`, `search_regex` |
 | map everything a rename touches (propagate) | `get_backlinks`, `find_unresolved_links`, `rewrite_link` |
-| record the end-to-end doc (build Stage 7) | `write_note` (compare-and-swap, confirmation on overwrite), `patch_note`, `append_note` |
+| record the end-to-end doc (build Record step) | `write_note` (compare-and-swap, confirmation on overwrite), `patch_note`, `append_note` |
 | keep inferred content honest | `write_note` with `provenance: "agent_synthesis"` runs a poison scan before the write lands |
 | keep a shared vault safe for several agents | JWT scopes, per-vault folder ACLs, a read-only kill switch, human-in-the-loop tokens |
 

package/docs/audit-brief.md

@@ -1,148 +0,0 @@
-# AUDIT_BRIEF.md: adversarial audit of model-orchestrator (round 1)
-
-> Historical document. Counts in it (tests, files) are as of the round they describe; `npm test` prints the current number.
-
-Read-only audit. Report findings only; do not modify files. Rank by severity. For each finding: file, line, what breaks, a concrete reproduction. `CLEAN` is a valid answer for any area with no reproducible finding. Skip style.
-
-## Task bundle
-
-**Purpose.** Adversarial, read-only audit of this npm package before it is published, so that reproducible defects are fixed before strangers run it.
-**Task class.** read_only
-
-**Granted scope.**
-- Every file under this repository root: `bin/`, `src/`, `templates/`, `test/`, `scripts/`, `docs/`, `package.json`, `README.md`.
-- Anything outside this repository is out of scope. Do not widen it on your own judgment.
-
-**Capabilities.** read files, run `npm test`, run `node bin/cli.js` with `--dry`, run `node bin/cli-run.mjs` with bad arguments, run scripts against a temp directory under /tmp.
-
-**Denied actions.** Do not modify, create or delete any file in this repository. Do not run `npm install -g`. Do not run any vendor installer. Do not commit, push, or publish. Do not read files outside this repository except /tmp scratch you created. Do not call any network service.
-- Anything absent from Capabilities is denied. Absence is not permission.
-
-**Conventions you do not have.** Report in plain prose with a findings list. No style nitpicks. `CLEAN` is a valid verdict per area. Every finding needs a concrete reproduction (command + observed vs expected). Never print a value that looks like a credential.
-
-**Report contract.** Return: a severity-ranked list of findings (file, line, what breaks, reproduction, suggested fix in one or two sentences), then a `CLEAN` line for each area in "Attack these" that had no reproducible finding, then a short "not covered" list naming anything you did not check or could not verify.
-
-**Exit parameters.** Stop after 12 minutes of wall clock or after reading every file once and running at most 30 commands, whichever comes first. If you hit a bound, report what you have and name what you did not cover. Never return nothing.
-
-## What this is
-An npm package (`npx model-orchestrator`) that asks a user which level (1/2/3) and which AIs they have access to, then writes markdown + config templates into a folder, and optionally runs `npm install -g <pkg>` for known packages after an explicit per-package yes. It also ships `bin/cli-run.mjs`, a wrapper that runs one of five agent CLIs (grok, codex, agy, hermes, qwen) and exits non-zero unless the lane produced a deliverable.
-
-## Runtime
-Node >= 18, ESM, zero dependencies. Runs on a stranger's laptop (macOS/Linux) with their PATH and HOME. Level 3 writes shell/systemd/compose templates the user will run on a Linux box.
-
-## Threat model
-- The user is not an adversary but is careless: runs it in the wrong directory, passes odd flags, has files with the same names.
-- Untrusted input reaches `cli-run.mjs` through CLI stdout (JSON from third-party binaries) and through `lanes.json` on disk.
-- The installer must never: write a secret value anywhere, overwrite a user file without --force, run a remote shell script, escape the target dir (path traversal via template rel paths or --dir), or leave a placeholder unrendered.
-- `cli-run.mjs` must never: throw on malformed CLI output (a throw is misreported as a usage error), pass a secret in argv, leave temp files, hang on stdin, or report success without a deliverable.
-- Generated templates (`vm/setup-vm.sh`, `vm/jobs/weekly-audit.sh`, `docker-compose.yml`, `gateway.config.yaml`) must not put a key in argv, bind to 0.0.0.0, or pipe a remote script into bash.
-
-## Already verified (do not repeat)
-- 60 node --test cases pass, including every judge's failure shapes and a mutation check that turns one case red.
-- Placeholders: every template renders for every level and primary without a leftover `{{KEY}}`.
-- README inside `.claude/agents/` is not installed.
-
-## Attack these
-1. `bin/cli.js` argument parsing: `opt()` takes the next argv token; what happens with `--dir --force`, `--ais ""`, duplicate flags, `--level 2.5`, unicode, a `--dir` that is a file, a `--dir` of `/`?
-2. `src/install.js` `writeFiles`: path traversal if a template rel path or the --dir resolves outside; symlink in the target dir; mode handling on Windows; partial writes.
-3. `src/detect.js` `which`: PATH entries that are files, empty PATH, relative PATH entries, a directory named like the binary.
-4. `bin/cli-run.mjs`: `jsonLines` on huge output; `maxBuffer`; `spawnSync` with `timeout` and `killSignal` behaviour; `enabledLanes()` with a malicious lanes.json; `--brief` pointing at a directory or a huge file; prompt containing newlines; the codex `-o` temp file when the CLI writes elsewhere; the `import.meta.url === pathToFileURL(argv[1])` main guard when invoked via a symlink; rc pass-through logic (`if (r.status !== 0 && code === OK) code = r.status`).
-5. Templates: `vm/setup-vm.sh` (set -euo pipefail, the for loop over {{NPM_PACKAGES}} when empty), `vm/jobs/weekly-audit.sh` (curl --config - header injection if GATEWAY_MASTER_KEY contains a quote or newline), `docker-compose.yml` env pass-through, systemd unit paths.
-6. Anything that could make the installer write outside `--dir` or read a file it should not.
-
-## Design decisions to challenge, with reasoning
-- Zero dependencies (no inquirer): smaller audit surface, but the prompt code is hand-rolled. Is the readline path safe with piped stdin and EOF?
-- Vendor scripts are printed, never run: correct? Or does printing `curl | bash` still encourage the unsafe pattern?
-- `npm install -g` is run after a per-package yes, with the package name from the catalog (never user input). Confirm user input cannot reach that argv.
-- `writeFiles` refuses existing files unless --force but does not check that the target is inside cwd. Deliberate (users may want `~/project`). Is there a traversal risk from template names?
-
-## How to run
-`npm test` · `node bin/cli.js --help` · `node bin/cli.js --yes --level 3 --ais claude-code,codex,agy,grok,hermes,qwen,ollama --dir /tmp/x --dry`
-
-## ROUND 2 (after round-1 fixes)
-
-Re-audit the same scope. Every round-1 finding was reproduced before it was touched. What changed:
-
-| # | Finding | Change |
-|---|---|---|
-| 1 | writeFiles escape / symlink follow | `preflight()` in `src/install.js`: containment under the resolved root, lstat every existing component (symlink or non-directory parent refused), exclusive `wx` create unless `--force`, rollback of files this run created if a later write fails. Tests: escape, symlinked component, conflicting parent leaves nothing behind. Mutation-checked. |
-| 2 | prompt in argv + logged head | argv kept (each vendor's documented headless shape); DEFERRED as a vendor constraint, documented in `CLI-RUN.md` and the file header (no secrets in prompts, ARG_MAX, reference big briefs by path). Log now stores a 12-hex sha256 prefix and length, never text. Test: marker absent from log. |
-| 3 | unknown flags / missing values | strict `parseArgs` in `bin/cli.js`: unknown flag, missing value, empty value, duplicate, positional → exit 2 before planning. Tests for each. |
-| 4 | audit job hardcoded hermes | `auditLane()` picks the first ENABLED cli-run lane (hermes, qwen, codex, agy, grok); none → rendered guard exits 13. Tests. |
-| 5 | audit never received live state | script composes `reports/audit-brief-<date>.md` = task bundle + protocol + DELEGATION_MATRIX + live-state, and passes THAT as `--brief`. Test. |
-| 6 | `--dir` ignored by systemd paths | `INSTALL_DIR` rendered into the service and the script from the resolved `--dir`. Test. |
-| 7 | curl config injection | script refuses a key not matching `^[A-Za-z0-9._-]+$` (exit 2) before any curl; documented in ENVIRONMENT.md and vm/README. Test executes the rendered script with an injecting key. |
-| 8 | malformed lanes.json fail-open | `enabledLanes()` returns null on present-but-invalid; main refuses every lane (13) and says so. Test proves no spawn happens. |
-| 9 | signal → exit 0 | `r.signal || r.status === null` → verdict killed, exit 10, partial output discarded. Test. |
-| 10 | partial install | covered by preflight + rollback (finding 1). Test. |
-| 11 | directory detected as binary | `isFile()` check in both `which()` implementations. Test. |
-| 12 | `curl \| bash` printed | download / read / run form printed instead. |
-
-Also new since round 1: the companion-tool path (`--tools codecalc`, `--no-tools`, `templates/tools/codecalc/`, `protocols/numbers-and-logic.md`, `resolveTools`). Attack it the same way: unknown tool ids, interaction with `--yes`, the extra interactive question, and whether any written snippet could be confused for a file the installer should not touch.
-
-Report only what reproduces on the current tree. `CLEAN` per area is expected where the fix holds.
-
-## New in 0.1.15: two claude-code-only hooks
-
-`route-gate.mjs` (`UserPromptSubmit`) and `subagent-context.mjs` (`SubagentStart`) ship to `.claude/hooks/` only when claude-code is the primary. Both are plain Node, zero deps, and installed with mode `0o755`.
-
-- **Reads.** `route-gate.mjs` reads at most 64 KB from one file: the routing rules file (`ROUTING.md` or `ORCHESTRATOR.md`) at a path rendered in at install time relative to `CLAUDE_PROJECT_DIR`, never a hardcoded absolute path. Before opening it, it `statSync`s the resolved path (following a symlink to its target) and refuses anything that is not `isFile()`, a FIFO, socket, device or directory included, so the read never touches a path that could block on open. The read itself is one `openSync` + one bounded `readSync` into a fixed 64 KB buffer, closed in a `finally`, so neither the time nor the memory this hook uses depends on how large the file on disk actually is. It then extracts the text between `<!-- route-gate:start -->` and `<!-- route-gate:end -->` and nothing else. `subagent-context.mjs` reads nothing from disk; its context is static text plus the same two rendered paths. Neither parses or executes anything it reads; the extracted block is passed through as a string.
-- **Stdin.** Neither hook uses a field from the JSON input Claude Code sends on stdin, but both must still consume the pipe rather than ignore it. Both drain stdin asynchronously against a 250ms hard cap: whichever comes first, the real `end` event or the timeout, the hook proceeds. Neither ever calls a blocking, synchronous read of stdin.
-- **Writes.** Neither writes a file. Both write one JSON object to stdout: `{"hookSpecificOutput":{"hookEventName":"...","additionalContext":"..."}}`, and both exit only after that write's callback fires, so a buffered write to a pipe is not truncated by an exit racing ahead of it.
-- **Fail-open, on purpose.** A missing `CLAUDE_PROJECT_DIR`, a missing rules file, a non-regular file at the rules path, or a missing block each produce a one-line fallback `additionalContext` naming what was found, and the script still exits 0. This is acceptable because a miss here is a stray context string reaching the model, not a security gate: nothing downstream trusts the hook's output for anything but a routing suggestion, and the settings snippet that wires it in is a document the user merges by hand, never written automatically over an existing `settings.json`.
-- **Bounded.** `route-gate.mjs` caps the read at 64 KB regardless of the file's reported size and the injected string at 4000 characters, so a rules file bloated by a bad edit, or truncated to an arbitrary length, cannot balloon the context or the read time on every turn. Both hooks cap stdin drain at 250ms.
-- **Not yet attacked.** Untested here: a rules file with a `route-gate:start` marker but no matching end marker very far into the file (bounded by `MAX_READ`, so the end marker past that point is treated as absent, which is the intended fail-open path, but worth a deliberate case); a `CLAUDE_PROJECT_DIR` pointing at a path with no read permission; behavior under the Windows exec-form `node` + `args` invocation named in the settings snippet; a `statSync` that itself hangs (a stalled network filesystem, for instance) rather than the FIFO-at-open case this round fixed.
-
-### Round 1 (pre-release), fixed before shipping
-
-Three findings reproduced against the 0.1.15 branch before it shipped, none of them ever released:
-
-| # | Finding | Fix |
-|---|---|---|
-| 1 | HIGH. `readFileSync(0)` in both hooks blocked until stdin reached EOF (`sleep 3 \| ... node route-gate.mjs` still running past 1.5s); `route-gate.mjs` also read the whole rules file into memory before bounding it, so a FIFO planted at the rules path blocked forever on open. | Stdin is drained asynchronously against a 250ms hard cap in both hooks. `route-gate.mjs` refuses anything that is not `isFile()` via `statSync` before ever calling open, then reads through one fixed 64 KB buffer via `openSync`/`readSync`. Tests: an open, never-closed stdin pipe exits within 1s for both hooks; a FIFO at the rules path returns the fallback instead of hanging; a 200 MB sparse rules file completes in well under a second with output still capped. |
-| 2 | MEDIUM. `done-verifier`'s description, both agent-folder READMEs, and the root README called it "read-only" without qualification, while its claude-code file carries an unrestricted `Bash` grant; nothing in that grant stops it from running a mutating command. | Every one of those surfaces now says plainly that `done-verifier` carries no file-editing tools and that its Bash use is bound by its own prompt, not by the tool grant; `reader` is named as the one that is read-only by tool grant (no Bash) on both formats. |
-| 3 | MEDIUM. Three generated surfaces still stated the pre-0.1.15 premise on a claude-code install: `builder.md`'s description ("... or the main build itself"), `build-protocol.md`'s roles table and its "why the builder does not hand off" note, and `ROUTING.md`'s "Plan big, execute small" line ("the orchestrator executes"). | All three now render through `subagentsLoadRules(primary)`, the same gate the decision tree and "Who builds" already used; every other primary is unchanged. A semantic-regression test asserts a claude-code install contains none of the old phrasing and a codex install still does. |
-
-## New in 0.1.16: a third hook, route-metrics.mjs
-
-`route-metrics.mjs` ships to `.claude/hooks/` alongside `route-gate.mjs` and `subagent-context.mjs`, only when claude-code is the primary. Same shape as the other two: plain Node, zero deps, mode `0o755`. Unlike them, it is wired to five events at once (`UserPromptSubmit`, `PreToolUse` matched to `Agent|Task`, `SubagentStart`, `SubagentStop`, `Stop`), and it does write, deliberately: one JSON line per event, appended to `~/.ai-orchestrator/route-metrics.jsonl`.
-
-- **Reads.** Only its own stdin (the JSON Claude Code sends per event) and, for `--summary`, its own log file. It never reads `transcript_path` even though that field is present on every event: the documented source for the route marker is `last_assistant_message`, and the docs say the transcript can lag, so a hook that read it instead could log a stale or absent marker as if it were current. It never reads the rules file, the task bundle, or any other project file.
-- **Writes.** `~/.ai-orchestrator/route-metrics.jsonl` (append-only, rotated to `.jsonl.1` above 5 MB) and `~/.ai-orchestrator/route-metrics.state/<sha256(agent_id)>.json`, a small file recording a subagent's start time and type so `SubagentStop` can compute a duration; it is deleted on stop, and anything older than 24h is pruned on the next `SubagentStart`. Nothing outside `~/.ai-orchestrator/`. It never writes to stdout: on `UserPromptSubmit` and `SubagentStart`, stdout becomes model context, and this hook has nothing to say there, so it stays silent on every event, not just those two.
-- **What it never logs.** Prompt text, tool descriptions, the full `tool_input`, `last_assistant_message` itself, or the "why" half of a route marker. Only six named fields ever reach a record: `session_id`, `subagent_type`, `agent_type`, and the parsed `lane`, each stripped to `[A-Za-z0-9_.+-]` and capped at 64 characters (128 for `session_id`) before being written, plus the event name and a `duration_s` number it computed itself. This mirrors `bin/cli-run.mjs`'s own log, which stores a fixed reason code and never a provider-supplied string.
-- **Fail-open, on purpose.** Every code path that can fail (a malformed state file, a full disk, a rotation race, invalid JSON on stdin, an unrecognized event) is caught and produces no record rather than a thrown error or a non-zero exit; the process always exits 0. A miss here is a missing line in a telemetry log, never a blocked turn, so there is nothing to gate.
-- **Bounded.** Stdin is drained asynchronously against a combined 1s time cap and 8 MB size cap; a payload that exceeds either is treated as truncated and parsed as nothing, never partially. `--summary` reads the log directly (never spawns anything, never executes a line in it).
-- **Not yet attacked.** Untested here: two processes racing the same rotation at once (a rename plus an append landing on the same file); a state directory with thousands of leaked files from a long-lived session with a crashed hook (pruning runs, but only on `SubagentStart`, so an install that never starts a subagent again would never prune); behavior if `agent_id` collides across two concurrent subagents (sha256 makes this astronomically unlikely, not impossible).
-
-## New in 0.1.18: the Windows spawn path
-
-`bin/cli-run.mjs` runs a lane's binary through `windowsSpawnPlan()` before every `spawn()` call. On POSIX, and for a plain `.exe` or extensionless binary on Windows, this is a no-op: the same argv reaches `spawn()` with no shell, exactly as before. What changed is the two shapes Windows can hand it that used to reach `spawn()` unchanged and throw `EINVAL` (Node's fix for CVE-2024-27980: a `.bat`/`.cmd` target without `shell: true` is refused rather than run through an unsafely-escaped `cmd.exe`).
-
-- **What runs, in order.** `resolveCmdShim(cmdPath)` reads the `.cmd` file and looks for the exact line npm's `cmd-shim` package writes: `"%_prog%" ... "<path>" %*`, where `<path>` is `%dp0%`-relative (verified against the real, byte-for-byte output of `cmd-shim@9.0.2`, the package npm itself uses to write a shim from a package.json `bin` entry with a `#!/usr/bin/env node` shebang; `test/judges.test.js` pins that exact fixture). If it matches, the `%dp0%`-relative path is resolved against the `.cmd` file's own directory and checked with `statSync` (must exist, must be a file, must end in `.js`/`.mjs`/`.cjs`); on success, `windowsSpawnPlan()` returns `{ command: process.execPath, args: [scriptPath, ...args] }`, and `spawn()` runs `node <script> <args>` directly. A lane's prompt (argv[1] and on) is text this tool does not control the contents of; this path never puts it anywhere a shell parses it.
-- **Why no shell, ever, for a lane.** Every real lane (grok, codex, agy, hermes, qwen) is an npm-installed Node CLI, so on a real Windows install the resolved-shim branch is the one every run takes. If `resolveCmdShim` returns nothing for a lane (an old cmd-shim layout, a hand-written `.cmd`, or a `.bat`), `windowsSpawnPlan()` returns `{ refuse }` and `cli-run` reports the lane unavailable (exit 13) with a message saying how to fix it. It does not fall back to `cmd.exe`: a batch file re-reads its arguments through `%*` after `cmd.exe` has parsed them once, which is the case CVE-2024-27980 is about, and no escaping fully contains user text through both passes. Removing that path was chosen over guarding it.
-- **The one opt-in `cmd.exe` path, and how its arguments are escaped.** Only a caller passing `{ allowCmdFallback: true }` with arguments it fully controls gets the `cmd.exe` path: today that is the installer's own `npm install -g <pinned spec>` (`npm.cmd` is not a cmd-shim, and every argument comes from the catalog, none from a user). For that caller, `windowsSpawnPlan()` builds one command-line string with `escapeCmdArg`/`buildCmdExeCommand` and returns `{ command: <ComSpec>, args: ['/d', '/s', '/c', <built string>], options: { windowsVerbatimArguments: true } }`. The algorithm is the one documented at [qntm.org/cmd](https://qntm.org/cmd) (the reference writeup of `cmd.exe`'s quoting behavior) and used by the widely-deployed `cross-spawn` package: each argument is quoted the way `CommandLineToArgvW` expects (backslash-doubling before an embedded quote or at the end of the string, then wrapped in `"`), and THEN every `cmd.exe` metacharacter in that quoted text (`( ) % ! ^ " < > & | ; ,` and space) is caret-escaped, because `cmd.exe`'s own line scanner reads those characters off the raw command line before the quoting is honored, quote or no quote. `windowsVerbatimArguments: true` tells Node not to re-quote the string a second, conflicting way. `test/judges.test.js` pins exact expected output for `&`, `|`, `^`, `%`, a literal `"`, a trailing backslash and a literal newline (the last one deliberately unescaped: it is not a `cmd.exe` metacharacter).
-- **`killTree` needs no change for which process it targets, either path.** `taskkill /pid <pid> /T /F` walks the whole descendant tree regardless of whether the direct child is `node` (the resolved-shim path) or `cmd.exe` (the fallback); there is no intermediate shell layer to lose track of in the common case, since there is no shell there at all. It DID need a change for how `taskkill` itself is found: `windows-latest` CI caught a bare `spawn('taskkill', ...)` failing `ENOENT` the first time a lane actually ran end to end there (this project's own test harness deliberately narrows PATH to isolate a fake lane, and that narrowed PATH does not include `System32`; a sandboxed or otherwise stripped-down real environment might not either), and the resulting unheard `error` event on the returned process crashed the whole run over what should be a best-effort cleanup step. `taskkillPath()` resolves the executable under `%SystemRoot%` (falling back through `%windir%` to a fixed path) instead of relying on PATH, built with a literal backslash rather than `node:path`'s `join()`, which picks its separator from the HOST running the code, not the OS the path describes; `killTree` now attaches an `error` listener so any future spawn failure stays a missed cleanup, never a crash.
-- **`bin/cli.js`'s own `npm install -g` prompt reuses this, rather than duplicating it.** The installer's opt-in "run `npm install -g <ai>` now?" prompt had the identical `EINVAL`-shaped defect (`spawnSync('npm', ...)` with no shell), found the same way: it failed the moment its own test actually ran on `windows-latest`. It now resolves `npm` with `which()` and calls `windowsSpawnPlan()`, the same function above, instead of a second copy of the fix.
-- **Not yet attacked for real.** `windowsSpawnPlan`, `resolveCmdShim` and the escaping functions are unit-tested (pure string logic, runs on every CI host) and the resolved-shim path is exercised end to end on `windows-latest` through the fake-lane fixtures in `test/cli.test.js` (installed as a real npm-style `.cmd` shim). A lane can no longer reach `cmd.exe` at all (a unit test pins the refusal). The opt-in `cmd.exe` branch, used only by the installer's own `npm install -g`, is not exercised end to end through a live Windows process in this suite; its escaping is proven by exact-string unit tests only, and its arguments never include user text.
-- **A platform limit found the same way, unrelated to the spawn path itself: Windows has no OS-level signals at all.** `cli-run.mjs`'s graceful shutdown (`process.on('SIGTERM', ...)`, kill the lane's process group, then exit 143/130) is a POSIX guarantee only: `ChildProcess.kill(sig)` on Windows calls `TerminateProcess()` unconditionally for SIGTERM AND SIGINT alike, giving the target process no chance to run any handler at all, proven on `windows-latest` CI (the wrapper died as `{code: null, signal: sig}` for both; a hypothesis that SIGINT gets a real, catchable console-control event on Windows was tried first and measured false in this exact scenario, not assumed). `test/cli.test.js`'s `#13` now expects an unhandled termination for either signal on win32, and the original graceful-exit assertion elsewhere.
-- **Two narrow, individually-verified Windows skips remain, neither in the spawn path itself.** (1) A lane dying mid-run from a real POSIX signal cannot be reproduced on win32: a real Windows lane is a plain `node <script>` process, so it cannot die "by signal" any more than the product being tested can, and the only way a test fixture can even simulate one (a nested `sh -c "...; kill -TERM $$"`) puts an extra node process between cli-run.mjs and the dying shell, so cli-run.mjs observes only that node's translated exit code (measured: MSYS bash's self-kill status leaks through as a plain nonzero exit code, 3840, which this tool already handles honestly via `exit_nonzero`). (2) `weekly-audit.sh`'s watchdog (`bounded()`/`killtree()`, `pgrep -P` plus killing a backgrounded subshell's tree) relies on real bash job control this script only ever runs under on the Ubuntu box it targets; actually executing it against a genuinely hanging stub under Git Bash's job-control emulation hung past a 20s outer timeout on `windows-latest` CI, a known class of MSYS/Cygwin limitation (a `kill -KILL` not reliably reaching the underlying Windows process tree of a backgrounded subshell), not a defect in the generated script, which still renders and syntax-checks correctly.
-
-## New in 0.1.23: failure classes in cli-run
-
-`bin/cli-run.mjs` now puts every run in a closed failure class that owns the exit code (`auth` 14, `quota` 15, `rejected` 16, `refused` 17, `cut_short` 18, beside `ok` 0, `empty` 10, `no_output` 11, `timeout` 12, `unavailable` 13), counts refused tool calls per lane (including a read of grok's session transcript, whose `sessionId` comes from lane stdout), and prints redacted problem and fix lines. The durable log gains only `class` and `refused`. Threat model: a false exit 0, provider text or a secret reaching the log or the terminal, a transcript read escaping the sessions root, misclassification that sends a user the wrong way, and anything that throws or stalls.
-
-### Round 1 (pre-release, GPT-6 Astra at xhigh), fixed before shipping
-
-Every finding was reproduced as a failing case in `test/classify.test.js` against the unfixed code (all seven red), then fixed; the suite is green after. One round, by rule; the regression cases verify the fixes.
-
-| # | Sev | Finding | Fix | Test |
-|---|---|---|---|---|
-| 1 | HIGH | qwen's display detail clipped an error message at 120 characters before redaction, so a long JSON password lost its closing quote and printed its prefix | redact before every clip: judge detail, API-error text, denial text, deliverable snippet, problem cause | R1 |
-| 2 | HIGH | the JSON credential pattern ended at an escaped quote and missed unterminated values | match JSON string escapes, run an unterminated value to the end, and accept a JSON body escaped inside a string | R2 |
-| 3 | HIGH | `firstDenialText` scanned 16 MiB with an unbounded `[^)]*`: 1 MiB of unclosed `Permission denied for command(` took 15.6 s after the lane had exited | scan at most 256 KiB of stdout and of stderr, with bounded repeats | R3 |
-| 4 | MEDIUM | transcript containment was a string prefix with both separators, so on POSIX a directory literally named `sessions\outside` passed | `isInsideRoot()` via `path.relative`, rejecting `..`, absolute and cross-drive results; tested with `path.posix` and `path.win32` on every OS | R4 |
-| 5 | MEDIUM | qwen signals were searched in the clipped display detail, so a quota error after 120 characters read as `empty`, and a model name in the detail could fake a signal | classify on `qwenErrorText()`: the terminal event's full error and an API-error result only | R5 |
-| 6 | MEDIUM | hermes fell back to stdout when stderr was empty, so an answer saying "no rate limit" read as `quota` | stderr only | R6 |
-| 7 | MEDIUM | a nonzero vendor exit with a recognised empty shape (agy exit 7, `SUCCESS`, empty response) returned `empty`, contradicting the documented `cut_short` fallback | an unexplained nonzero exit is `cut_short`, except hermes' own exit 2 | R7 |
-
-Reported clean by the same audit: no false exit 0 across 675 malformed probes and five lanes; no provider text or secret fragment in probed log records; the real codex 0.153.4 fixture's non-fatal error item still succeeds; grok traversal, symlink, FIFO, session-match and read-cap guards; timeout, interrupt, overrun, killed lane, JSON contract, `--quiet` and the doctor canary. Not verified by it: native Windows execution, live vendors, filesystem races.

package/scripts/README.md

@@ -1,7 +0,0 @@
-# scripts/
-
-| File | Job |
-|---|---|
-| `gen-catalog.js` | regenerates `docs/catalog.md` AND the vendor compatibility table in `README.md` (between the `vendor-table` markers) from `src/catalog.js`; `npm run gen:catalog`. `test/catalog.test.js` fails if either generated surface disagrees with the catalog. |
-| `record-demo.sh` | re-records `docs/demo.gif` by installing the published package into a temp folder and running it under `asciinema`, then rendering the cast with `agg`. Pass a version to pin one: `bash scripts/record-demo.sh 0.1.27`. Needs `brew install asciinema agg`. The frames are the installer's own output, so the GIF stays true to what the command prints. |
-| `gen-plugin.js` | regenerates the Claude Code plugin bundle in `plugin/` (agents, the two read-only hooks, `plugin.json`, `LICENSE`) from `templates/`, using the plan in `src/plugin.js`; `npm run gen:plugin`. `test/plugin.test.js` fails if the committed bundle disagrees. `plugin/README.md` and `plugin/hooks/hooks.json` are hand-owned. |

package/scripts/gen-catalog.js

@@ -1,81 +0,0 @@
-#!/usr/bin/env node
-// Regenerates docs/catalog.md and the README's vendor compatibility table from
-// src/catalog.js. The test suite checks they agree, so neither can drift (#23).
-import { writeFileSync, readFileSync } from 'node:fs';
-import { AIS, LEVELS, TOOLS, IMAGES, npmSpec } from '../src/catalog.js';
-import { readdirSync } from 'node:fs';
-
-export function protocolCount() {
-  return readdirSync(new URL('../templates/common/protocols/', import.meta.url)).filter((f) => f.endsWith('.md') && f !== 'README.md').length;
-}
-
-export function catalogMarkdown() {
-  let md = '# Catalog\n\nGenerated from `src/catalog.js`. Do not hand-edit; `npm run gen:catalog` rewrites it. Protocols shipped at every level: ' + protocolCount() + ' (counted from `templates/common/protocols/`).\n\n## Levels\n\n| Level | Name | Tagline | Gives |\n|---|---|---|---|\n';
-  for (const l of LEVELS) md += `| ${l.id} | ${l.name} | ${l.tagline} | ${l.gives} |\n`;
-  md += '\n## AIs\n\n';
-  for (const a of AIS) {
-    const how = a.install.npm
-      ? '`npm install -g ' + npmSpec(a) + '`'
-      : a.install.script
-        ? 'vendor script (read it first): `' + a.install.script + '`'
-        : a.install.url + (a.install.brew ? ' (or `brew install ' + a.install.brew + '`)' : '');
-    md += `### \`${a.id}\` · ${a.name}\n\n- **Kind:** ${a.kind} · **Access:** ${a.access} · **Lane:** ${a.lane} · **Level:** ${a.minLevel}+\n- **Wins at:** ${a.role}\n- **Install:** ${how}\n- **Sign in:** ${a.auth}\n`;
-    if (a.rulesFile) md += `- **Reads rules from:** \`${a.rulesFile}\`` + (a.agentsDir ? ` · subagents in \`${a.agentsDir}/\`` : '') + '\n';
-    if (a.cliRun) md += '- **cli-run lane:** yes\n';
-    if (a.plans) {
-      md += '- **Plans:**\n';
-      for (const p of a.plans) md += `  - ${p.name} (${p.headroom} headroom, checked ${p.checked}): ${p.source}\n`;
-    }
-    if (a.builtAgainst) md += `- **Built against:** ${a.builtAgainst}` + (a.install.npm ? ' (the same number the npm pin uses)' : '') + '\n';
-    if (a.note) md += `- **Note:** ${a.note}\n`;
-    md += '\n';
-  }
-  md += '## Companion tools\n\n';
-  for (const t of TOOLS) {
-    md += `### \`${t.id}\` · ${t.name}\n\n- **Repo:** ${t.repo}\n- **Gives:** ${t.role}\n- **Install:** \`${t.install}\` (needs ${t.requires})\n- **Registers itself with:** ${t.autoClients.join(', ')}; snippets for the rest are written to \`mcp/\`\n- **Default:** ${t.recommended ? 'selected' : 'not selected'}\n\n`;
-  }
-  return md;
-}
-
-export const VENDOR_TABLE_START = '<!-- vendor-table:start -->';
-export const VENDOR_TABLE_END = '<!-- vendor-table:end -->';
-
-export function fixtureManifest() {
-  return JSON.parse(readFileSync(new URL('../test/fixtures/manifest.json', import.meta.url), 'utf8'));
-}
-
-// The compatibility table in README.md. Every number comes from `builtAgainst`
-// in src/catalog.js, which is also the npm pin where there is one, so "built
-// against" and "pinned to" are the same number by construction (#23).
-export function vendorTableMarkdown() {
-  const fx = fixtureManifest();
-  const byLane = Object.fromEntries(fx.fixtures.map((f) => [f.lane, f]));
-  let md = VENDOR_TABLE_START + '\n\n| Lane | Vendor | Version this release was built against | Where that number is proved |\n|---|---|---|---|\n';
-  for (const a of AIS) {
-    if (!a.bin || !a.builtAgainst) continue;
-    const proof = byLane[a.id]
-      ? '`test/fixtures/' + byLane[a.id].file + '`, a recorded run'
-      : a.install.npm
-        ? 'the npm pin the installer writes, `' + npmSpec(a) + '`'
-        : a.id === 'ollama'
-          ? 'the pinned image the level 3 box runs, `' + IMAGES.ollama + '`'
-          : "the maintainer's own install";
-    md += `| \`${a.bin}\` | ${a.vendor} | ${a.builtAgainst} | ${proof} |\n`;
-  }
-  md += `\nGenerated from \`src/catalog.js\` by \`npm run gen:catalog\`; \`npm test\` fails if this table and the catalog disagree. Fixtures were captured ${fx.capturedAt}.\n\n` + VENDOR_TABLE_END;
-  return md;
-}
-
-export function readmeWithVendorTable(current) {
-  const a = current.indexOf(VENDOR_TABLE_START);
-  const b = current.indexOf(VENDOR_TABLE_END);
-  if (a === -1 || b === -1) throw new Error('README.md has no vendor-table markers');
-  return current.slice(0, a) + vendorTableMarkdown() + current.slice(b + VENDOR_TABLE_END.length);
-}
-
-if (process.argv[1] && process.argv[1].endsWith('gen-catalog.js')) {
-  writeFileSync(new URL('../docs/catalog.md', import.meta.url), catalogMarkdown());
-  const readmeUrl = new URL('../README.md', import.meta.url);
-  writeFileSync(readmeUrl, readmeWithVendorTable(readFileSync(readmeUrl, 'utf8')));
-  console.log('docs/catalog.md and the README vendor table regenerated');
-}

package/scripts/gen-plugin.js

@@ -1,16 +0,0 @@
-#!/usr/bin/env node
-// Regenerates the Claude Code plugin bundle under plugin/ from the installer's
-// templates (src/plugin.js has the plan). The test suite checks the committed
-// bundle matches, so an agent or hook edited in templates/ cannot ship to npm
-// users and silently not to plugin users.
-import { writeFileSync, mkdirSync } from 'node:fs';
-import { join, dirname } from 'node:path';
-import { planPluginFiles, PLUGIN_DIR } from '../src/plugin.js';
-
-const files = planPluginFiles();
-for (const f of files) {
-  const abs = join(PLUGIN_DIR, ...f.rel.split('/'));
-  mkdirSync(dirname(abs), { recursive: true });
-  writeFileSync(abs, f.content);
-}
-console.log('plugin/ regenerated: ' + files.length + ' files');

package/scripts/record-demo.sh

@@ -1,45 +0,0 @@
-#!/usr/bin/env bash
-# Re-records docs/demo.gif from the PUBLISHED package, so the frames are the
-# program's own output and anyone can reproduce them.
-#
-#   bash scripts/record-demo.sh            # records the current published version
-#   bash scripts/record-demo.sh 0.1.27     # pins a version
-#
-# Needs asciinema (the recorder) and agg (cast to GIF), both from the asciinema
-# project: brew install asciinema agg
-set -euo pipefail
-
-VERSION="${1:-latest}"
-REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-OUT="$REPO_ROOT/docs/demo.gif"
-WORK="$(mktemp -d)"
-trap 'rm -rf "$WORK"' EXIT
-
-for tool in asciinema agg npm; do
-  command -v "$tool" >/dev/null || { echo "missing: $tool (brew install asciinema agg)" >&2; exit 1; }
-done
-
-# Installed locally first, so the recorded npx call resolves from node_modules
-# and never stops on npx's own "Ok to proceed?" prompt mid-take.
-cd "$WORK"
-npm install --silent "model-orchestrator@$VERSION" >/dev/null
-
-cat > "$WORK/take.sh" <<'TAKE'
-#!/bin/bash
-cd "$(dirname "$0")"
-printf '~/my-app $ '
-sleep 0.8
-cmd='npx model-orchestrator --yes --level 2 --ais claude-code,codex,grok --primary claude-code --dry'
-for (( i=0; i<${#cmd}; i++ )); do printf '%s' "${cmd:$i:1}"; sleep 0.022; done
-sleep 0.6; printf '\n'
-npx model-orchestrator --yes --level 2 --ais claude-code,codex,grok --primary claude-code --dry
-printf '~/my-app $ '
-sleep 2.5
-TAKE
-chmod +x "$WORK/take.sh"
-
-asciinema rec --cols 108 --rows 34 --overwrite --command "$WORK/take.sh" "$WORK/demo.cast"
-agg --theme monokai --font-size 16 --speed 1.3 --idle-time-limit 1.2 --last-frame-duration 3 \
-  "$WORK/demo.cast" "$OUT"
-
-echo "wrote $OUT ($(wc -c < "$OUT") bytes)"

package/templates/common/TASK_BUNDLE.md

@@ -1,56 +0,0 @@
-# Task Bundle: the brief every delegation carries
-
-A subagent, a second CLI, or a fresh chat window may hold none of the rules your main session is holding, and that is the default to assume. One exception: a Claude Code subagent loads the project's CLAUDE.md hierarchy at start, so it already carries the standing rules, just not this task's scope. Either way, it cannot see this task's conventions and will read an unspecified edge as an open one.
-
-> A delegate gets an approved, bounded brief. Absence is not permission.
-
-A brief is under-specified if it is missing **purpose**, **denied actions**, **report contract**, or **exit parameters**.
-
-## Template
-
-Copy this into the delegate's prompt. Delete nothing; write `none` where a field is genuinely empty, so a reader can tell "nothing denied" from "nobody thought about it".
-
-```markdown
-## Task bundle
-
-**Purpose.** <one sentence: what this task is for, and why>
-**Task class.** <read_only | draft_only | mutating>  (draft_only = produce, do not apply)
-
-**Granted scope.**
-- <paths, globs, topics, or record sets this brief covers>
-- Anything outside this list is out of scope. Do not widen it on your own judgment.
-
-**Capabilities.** <the actions you MAY take: read, search, write to <path>, run <cmd>>
-
-**Denied actions.** <explicit list: do not commit, push, deploy, delete, send, publish, close a ticket...>
-- Anything absent from Capabilities is denied. Absence is not permission.
-
-**Conventions you do not have.** <restate every house rule this task needs; even a delegate that loaded the standing rules still needs this task's scope, and a second CLI or a fresh chat window may hold none of it>
-
-**Report contract.** Return: <exactly what to hand back>. State plainly what you did NOT do
-and anything you could not verify. "Unverified" is an acceptable answer; a confident guess is not.
-
-**Exit parameters.** <at least one bound: a wall-clock ceiling, a work ceiling ("at most 20 files"),
-or a stop condition. Plus the partial-result clause: if you hit a bound, report what you have and
-name what you did not cover. Never keep going past a bound, never return nothing.>
-```
-
-## When to skip it
-
-A one-line read-only lookup can say so outright:
-
-```
-Task bundle: none (one-line lookup, read-only, no artifact)
-```
-
-The reason is required. A bare `none` is indistinguishable from "forgot".
-
-Never skip it for anything touching secrets, deletion, bulk mutation, deploys, or someone else's data. Better: do not delegate those at all.
-
-## Field notes
-
-- **Purpose** is what makes the rest checkable. "Fix the thing" has no edge to exceed.
-- **Task class** is the cheapest safety win. Most delegation wants `read_only` or `draft_only`.
-- **Denied actions** must be written even when they feel obvious. Nothing is obvious to a delegate with no context.
-- **Report contract** is what turns a result into evidence rather than a claim.
-- **Exit parameters** exist because a delegate that never returns is more expensive than one that returns wrong. A wrong answer is corrected next turn; a hang burns the session while looking like progress. Bound your own shell calls the same way (pass a timeout; scope recursive searches away from `.git`, `node_modules`, build output).