model-orchestrator 0.1.13 → 0.1.15

package/templates/agents/claude-code/finding-verifier.md

@@ -0,0 +1,43 @@
+---
+name: finding-verifier
+description: Adversarial verification of review findings. Use after a review or audit returns findings and before any of them trigger a repair. Read-only. Tries to DISPROVE each finding and returns CONFIRMED, NOT_REPRODUCED or INCONCLUSIVE per finding. Do not use to find new problems, and do not use to fix anything.
+tools: Read, Glob, Grep, Bash
+model: sonnet
+effort: high
+---
+
+You are the verification tier of the model router.
+
+A finding is a claim, not a fact. Your job is to try to disprove each one before
+it is allowed to cause a change. A false finding is expensive twice: it buys a
+repair nobody needed, and it teaches everyone to skim the next report.
+
+You are given findings from a review or an audit. For each one, independently:
+
+1. Read the cited file and line yourself. A citation that does not point at what
+   the finding describes is already a failure of the finding, not of the code.
+2. State the exact input, state or sequence that would make it happen.
+3. Look for what makes it impossible: a guard upstream, a type that cannot hold
+   that value, a caller that never passes it, a test that already covers it, a
+   framework guarantee.
+4. Where you can run something cheap and read-only that settles it, run it.
+
+Return one verdict per finding, in the order you were given them:
+
+- **CONFIRMED** you reproduced it, or traced a concrete path to it that nothing
+  prevents. Give the path in one or two sentences.
+- **NOT_REPRODUCED** you found what stops it. Name that thing and where it is.
+  This is a success, not a failure to try.
+- **INCONCLUSIVE** you could not settle it read-only. Say exactly what you would
+  need: a test run, a credential, a live environment, a decision from a human.
+  Never round this up to CONFIRMED to be safe, and never down to
+  NOT_REPRODUCED to be tidy.
+
+Rules:
+- Verify only the findings you were given. New problems you happen to notice go
+  in a separate list at the end, clearly marked as unverified observations.
+- You are read-only. You never repair, and you never soften a finding's wording.
+- Verifying nothing is a real answer. If every finding is NOT_REPRODUCED, say
+  that plainly; a verifier that always confirms something is a rubber stamp
+  facing the other way.
+- Token discipline: read the cited code and its callers, not the repository.

package/templates/agents/claude-code/reader.md

@@ -0,0 +1,26 @@
+---
+name: reader
+description: Reads and digests many files or notes and returns exactly what the brief asks for (facts, quotes with path:line, an index, a digest). Read-only. Use for "read all X line by line", extracting facts or quotes across a folder, indexing or summarizing many notes, or pulling every mention of a topic. Different from bulk-worker, which classifies, tags and transforms items and writes output: reader only reads and reports.
+tools: Read, Glob, Grep
+model: haiku
+effort: low
+---
+
+You are the reading tier of the model router.
+
+You read and digest many files or notes and hand back exactly what the brief
+asked for: facts, quotes, an index, a digest. You do not classify, tag,
+transform or rewrite; that is bulk-worker's job, not yours, and you never
+write a file.
+
+Rules:
+- Read the brief first and answer only what it asks. "Every mention of X"
+  means grep for X and read the hits, not the whole corpus.
+- Cite every fact or quote with its source: `path:line` for code and notes, a
+  URL and a retrieval note for anything fetched.
+- An index or digest is a structured list, one row or bullet per source, not
+  prose that blends sources together.
+- If a source is missing, unreadable, or empty, say so by name; do not
+  silently skip it.
+- Token discipline: read only what the brief needs, never re-read a file,
+  summarize as you go rather than holding full text for later.

package/templates/agents/snippets/claude-code.md

@@ -10,12 +10,16 @@ Routing rules live in `{{RULES_PATH}}/{{ROUTING_FILE}}`. Read them before any bu
 1. Bulk, mechanical, many similar items -> bulk-worker (fast tier).
 2. Needs live data -> live-researcher (standard tier + tools).
 3. Review without changing -> code-reviewer (standard, read-only).
+3a. Holding findings from a review or scanner -> finding-verifier before any repair. Only CONFIRMED findings earn a change.
+3b. Checking a tracker item against its stated done-signal -> done-verifier. It never closes anything itself.
 4. Ambiguous, architectural, or expensive to get wrong -> deep-planner (deep tier), then hand the plan down.
-5. Everything else that changes files -> build it directly. The main build is never handed off whole; bounded sub-parts go to builder.
+5. Everything else that changes files -> builder executes by default. The orchestrator plans, briefs, verifies and talks to you; it stays inline only when (a) the brief would cost as much as the work, (b) the task needs this conversation's own context, or (c) it is your decision, or the final verification of delegated work. Never send rule-bound work to the built-in Explore or Plan agents: they skip CLAUDE.md. general-purpose should not take work a named agent already owns.
+
+A subagent starts with your CLAUDE.md and tool definitions already loaded, so it has a fixed start-up cost before it does anything. Measure yours once: spawn a subagent with a one-line task and read its token count. Work smaller than that stays inline.
 
 Every build runs `{{RULES_PATH}}/protocols/build-protocol.md`: two deep-tier checkpoints, a mechanical scan, one adversarial pass, an explicit human yes before anything irreversible, then the loud negative.
 
-Every delegation carries an `{{RULES_PATH}}/TASK_BUNDLE.md` brief. A subagent holds none of these rules; absence is denial.
+Every delegation carries an `{{RULES_PATH}}/TASK_BUNDLE.md` brief. A Claude Code subagent loads this CLAUDE.md hierarchy, so it holds the standing rules already, just not this task's scope; a second CLI or a fresh chat window may hold none of them. Absence is denial either way.
 
 Never silently retry a failed attempt at the same tier. Escalate once and say so.
 
@@ -24,4 +28,6 @@ Numbers, comparisons, complexity and equivalence claims go through codecalc (or
 Anything durable is searched for before it is written and its folder index is corrected in the same pass; one writer per run: `{{RULES_PATH}}/protocols/memory-and-record.md`.
 ```
 
-Subagents were written to `{{AGENTS_DIR}}` (the project root, which is where Claude Code reads project-level agents; `--project` changes it). Run `claude` from `{{PROJECT_DIR}}` and they are available as `deep-planner`, `builder`, `code-reviewer`, `live-researcher`, `bulk-worker`.
+Subagents were written to `{{AGENTS_DIR}}` (the project root, which is where Claude Code reads project-level agents; `--project` changes it). Run `claude` from `{{PROJECT_DIR}}` and they are available as {{AGENTS_LIST_LINE}}.
+
+Two hooks were written to `{{AGENTS_DIR}}/../hooks/` (`.claude/hooks/`): `route-gate.mjs` injects the routing table on every prompt, and `subagent-context.mjs` reminds a spawned subagent where the rules and the task-bundle format live. Merge `settings.hooks.snippet.json`, written next to this file, into `.claude/settings.json` to wire them in.

package/templates/agents/snippets/route-gate.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+// route-gate.mjs: UserPromptSubmit hook for {{PRIMARY_NAME}}.
+//
+// Reads the route-gate table out of {{RULES_FILE_REL}} and injects it as
+// additionalContext on every turn, so the routing table is read at runtime
+// from the one place it is generated (the rules file), never a second
+// hand-typed copy that can drift from it.
+//
+// Fail-open by design: a miss here is a stray context string, not a gate.
+// This script always exits 0, never blocks on stdin past a short bound,
+// reads at most 64 KB of the rules file through a fixed-size buffer (never
+// a full read of an arbitrarily large or non-regular file), and never
+// executes anything it reads. See docs/audit-brief.md for the threat model.
+import { statSync, openSync, readSync, closeSync, realpathSync } from 'node:fs';
+import { join, isAbsolute } from 'node:path';
+
+// Rendered at install time from the level and directory the user chose.
+// Never hardcoded: a level 1 install points this at ORCHESTRATOR.md, level
+// 2+ at ROUTING.md, and a --dir outside the project resolves to an absolute
+// path instead of a relative one.
+const RULES_FILE_REL = {{RULES_FILE_REL_JSON}};
+
+const MAX_READ = 64 * 1024; // bounded read: this is a rules file, not a log
+const MAX_CONTEXT = 4000; // bounded injection: a table, not the whole file
+const STDIN_DRAIN_MS = 250; // hard cap: never let an open, never-closed stdin pipe hold this hook open
+const START = '<!-- route-gate:start -->';
+const END = '<!-- route-gate:end -->';
+
+function fallback(reason) {
+  return 'route-gate: ' + reason + '. Pick the lane before acting: read ' + RULES_FILE_REL + ' yourself.';
+}
+
+function resolveRulesPath() {
+  if (isAbsolute(RULES_FILE_REL)) return RULES_FILE_REL;
+  const projectDir = process.env.CLAUDE_PROJECT_DIR;
+  if (!projectDir) return null;
+  // Resolve through whatever part of the project dir already exists, so a
+  // symlinked project folder still resolves to the real path the rules file
+  // was written under.
+  let root = projectDir;
+  try {
+    root = realpathSync(projectDir);
+  } catch {
+    /* keep the unresolved value; the read below reports the real failure */
+  }
+  return join(root, RULES_FILE_REL);
+}
+
+// Bounded, regular-file-only read. statSync (not lstatSync) follows a
+// symlink to its target and reports what the target actually is, so a
+// symlinked rules file still reads; a FIFO, socket, device or directory at
+// the resolved path is refused before any open/read call touches it. That
+// check matters: opening a FIFO for reading blocks until a writer opens the
+// other end, and a plain readFileSync on any of these can hang or, for a
+// huge or sparse regular file, allocate far more than this hook needs. The
+// fixed-size buffer plus a single bounded readSync call means the on-disk
+// size of the file never determines how much this hook reads or how long it
+// takes.
+function readBounded(path) {
+  let st;
+  try {
+    st = statSync(path);
+  } catch (e) {
+    throw Object.assign(new Error('could not stat ' + path + ' (' + ((e && e.code) || e) + ')'), { code: e && e.code });
+  }
+  if (!st.isFile()) throw new Error(path + ' is not a regular file');
+  const buf = Buffer.alloc(MAX_READ);
+  let fd;
+  try {
+    fd = openSync(path, 'r');
+    const bytesRead = readSync(fd, buf, 0, MAX_READ, 0);
+    return buf.toString('utf8', 0, bytesRead);
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+function computeContext() {
+  const path = resolveRulesPath();
+  if (!path) return fallback('CLAUDE_PROJECT_DIR is not set, so ' + RULES_FILE_REL + ' could not be located');
+
+  let text;
+  try {
+    text = readBounded(path);
+  } catch (e) {
+    return fallback((e && e.message) || String(e));
+  }
+
+  const s = text.indexOf(START);
+  const e = s === -1 ? -1 : text.indexOf(END, s);
+  if (s === -1 || e === -1) return fallback(path + ' has no route-gate block');
+
+  return text.slice(s, e + END.length).slice(0, MAX_CONTEXT);
+}
+
+// Drain stdin without ever blocking on it. A bare `readFileSync(0)` waits
+// for stdin to reach EOF, so a caller that pipes into this hook and never
+// closes its end of the pipe (or a bare TTY with no redirection at all)
+// left the process running indefinitely. This races the real 'end' event
+// against a hard timeout instead: whichever settles first wins, and the
+// timer is unref'd so it can never itself be the reason the process stays
+// alive past a normal exit.
+function drainStdin(timeoutMs) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try {
+        process.stdin.removeAllListeners('data');
+        process.stdin.removeAllListeners('end');
+        process.stdin.removeAllListeners('error');
+        process.stdin.pause();
+      } catch {
+        /* stdin may already be gone; nothing left to clean up */
+      }
+      resolve();
+    };
+    const timer = setTimeout(finish, timeoutMs);
+    if (timer.unref) timer.unref();
+    try {
+      process.stdin.on('data', () => {});
+      process.stdin.on('end', finish);
+      process.stdin.on('error', finish);
+      process.stdin.resume();
+    } catch {
+      finish();
+    }
+  });
+}
+
+let additionalContext;
+try {
+  additionalContext = computeContext();
+} catch (err) {
+  additionalContext = fallback('route-gate.mjs failed unexpectedly (' + ((err && err.message) || err) + ')');
+}
+
+drainStdin(STDIN_DRAIN_MS).then(() => {
+  const payload = JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'UserPromptSubmit',
+      additionalContext
+    }
+  });
+  // Exit only after the write's callback fires, so a buffered write to a
+  // pipe (the common case on Windows, and possible anywhere output exceeds
+  // one write's worth) is not truncated by an exit that races ahead of it.
+  process.stdout.write(payload, () => process.exit(0));
+});

package/templates/agents/snippets/settings.hooks.snippet.json

@@ -0,0 +1,26 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/route-gate.mjs"]
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/subagent-context.mjs"]
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/agents/snippets/subagent-context.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+// subagent-context.mjs: SubagentStart hook for {{PRIMARY_NAME}}.
+//
+// A Claude Code subagent loads this project's CLAUDE.md hierarchy at start
+// (code.claude.com/docs/en/sub-agents), so it already has the standing
+// rules. What it does not have is this task's scope, and it can be tempted
+// to route further work itself or to mark its own output verified. This
+// hook injects a short, static reminder of where the rest lives and what
+// "delegate" means.
+//
+// Fail-open by design: a miss here is a stray context string, not a gate.
+// This script always exits 0, never executes anything it reads, and never
+// blocks on stdin past a short bound (see drainStdin below).
+import { isAbsolute } from 'node:path';
+
+// Rendered at install time so a --dir outside the project still names an
+// honest path rather than a hardcoded one.
+const RULES_FILE_REL = {{RULES_FILE_REL_JSON}};
+const TASK_BUNDLE_REL = {{TASK_BUNDLE_REL_JSON}};
+const STDIN_DRAIN_MS = 250; // hard cap: never let an open, never-closed stdin pipe hold this hook open
+
+const additionalContext = [
+  'SUBAGENT CONTEXT (model-orchestrator).',
+  'Routing rules: ' + RULES_FILE_REL + (isAbsolute(RULES_FILE_REL) ? '.' : ' (relative to the project root).'),
+  'Task bundle format: ' + TASK_BUNDLE_REL + '.',
+  'Report contract: say what you did, what you did NOT do, and what you could not verify. "Unverified" is acceptable; a confident guess is not. Stop at the bound your brief set, and never claim work you cannot show.',
+  'You are a delegate: do not route further work to another subagent yourself, and do not mark your own output as the final verification of it.'
+].join(' ');
+
+// Drain stdin without ever blocking on it. A bare `readFileSync(0)` waits
+// for stdin to reach EOF, so a caller that pipes into this hook and never
+// closes its end of the pipe left the process running indefinitely. This
+// races the real 'end' event against a hard timeout instead: whichever
+// settles first wins, and the timer is unref'd so it can never itself be
+// the reason the process stays alive past a normal exit.
+function drainStdin(timeoutMs) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try {
+        process.stdin.removeAllListeners('data');
+        process.stdin.removeAllListeners('end');
+        process.stdin.removeAllListeners('error');
+        process.stdin.pause();
+      } catch {
+        /* stdin may already be gone; nothing left to clean up */
+      }
+      resolve();
+    };
+    const timer = setTimeout(finish, timeoutMs);
+    if (timer.unref) timer.unref();
+    try {
+      process.stdin.on('data', () => {});
+      process.stdin.on('end', finish);
+      process.stdin.on('error', finish);
+      process.stdin.resume();
+    } catch {
+      finish();
+    }
+  });
+}
+
+drainStdin(STDIN_DRAIN_MS).then(() => {
+  const payload = JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'SubagentStart',
+      additionalContext
+    }
+  });
+  // Exit only after the write's callback fires, so a buffered write to a
+  // pipe is not truncated by an exit that races ahead of it.
+  process.stdout.write(payload, () => process.exit(0));
+});

package/templates/beginner/ORCHESTRATOR.md

@@ -20,10 +20,10 @@ Robustness first, cost second. Split tiers because the split produces better wor
 2. **Needs live data?** trends, current docs, pricing, recent events → standard tier with tools; freshness comes from tools, not from a bigger model.
 3. **Reviewing without changing?** → standard tier, read-only, findings ranked by severity. Escalate to deep only for security-critical review.
 4. **Ambiguous, strategic, or expensive to get wrong?** "design my…", "figure out…", unknown cause → deep tier. Then hand the plan down.
-5. **Everything else that changes files or executes a known plan** → you build it directly, at standard tier. The main build is never handed off whole; bounded sub-parts (a bulk pass, a wide search, a long audit loop) can go to cheaper tiers.
+{{DECISION_RULE5_L1}}
 
 Modifiers:
-- **Plan big, execute small.** The expensive tier steers, the cheaper tier does the volume. Never make the fast tier design anything; never make the deep tier grind out bulk output.
+- **Plan big, execute small.** The expensive tier steers, the cheaper tier does the volume. Never make the fast tier design anything; never make the deep tier grind out bulk output.{{INLINE_THRESHOLD_NOTE}}
 - **Never silently retry at the same tier after a failure.** Escalate one tier, or consult the deep tier once, and say which you did. If two consults do not unstick it, stop and tell the human.
 - **De-escalate.** If a request sounds deep but is a lookup or a small edit, route down. Default down, escalate on evidence.
 
@@ -36,7 +36,7 @@ Cap: two deep-tier consults per build. The full procedure is `protocols/build-pr
 
 ## Delegating inside one agent
 
-Subagents, a fresh chat, a second window: each one holds none of these rules. Every hand-off carries a `TASK_BUNDLE.md` brief: purpose, task class, granted scope, capabilities, denied actions, conventions it does not have, report contract, exit parameters. Absence is denial.
+{{DELEGATE_RULES_NOTE}} Every hand-off carries a `TASK_BUNDLE.md` brief: purpose, task class, granted scope, capabilities, denied actions, conventions it does not have, report contract, exit parameters. Absence is denial.
 
 ## Numbers and logic go through a tool, never your head
 
@@ -53,3 +53,4 @@ Anything durable is searched for before it is written, its folder index is corre
 ## When you outgrow this
 
 You will know: you keep wanting a second model family to read your diff, a $0 lane for bulk, or a live-data lane your primary does not have. That is level 2. Re-run the installer with `--level 2`.
+{{ROUTE_GATE_SECTION}}

package/templates/common/TASK_BUNDLE.md

@@ -1,6 +1,6 @@
 # Task Bundle: the brief every delegation carries
 
-A subagent, a second CLI, or a fresh chat window holds none of the rules your main session is holding. It cannot see your conventions, it cannot route, and it will read an unspecified edge as an open one.
+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.
 
@@ -25,7 +25,7 @@ Copy this into the delegate's prompt. Delete nothing; write `none` where a field
 **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; the delegate holds none>
+**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.

package/templates/common/protocols/build-protocol.md

@@ -66,7 +66,17 @@ Secret detection, static analysis and dependency scanning, filtered to lines thi
 
 Route by shape: security-shaped diffs (auth, tokens, routes, deletion, bulk mutation, untrusted input) go to an adversarial auditor, ideally a **different model family**. Architecture-shaped diffs go to the judgment tier reviewing build against plan. Never both on one diff.
 
-**Gate:** every finding **reproduced** before it reaches a human. Unreproduced items are dropped, not narrated. Hard cap one re-audit. `CLEAN` is a valid success state; an auditor that is not allowed to say so manufactures something.
+Findings do not go straight to a repair. Hand them to the **finding-verifier**, whose job is to DISPROVE each one: read the cited line, state what would trigger it, then hunt for the guard, caller or test that makes it impossible. It returns one of three verdicts per finding, and rounding between them is the failure mode to watch for.
+
+| Verdict | Meaning | What happens next |
+|---|---|---|
+| CONFIRMED | reproduced, or a concrete path nothing blocks | it earns a repair |
+| NOT_REPRODUCED | something prevents it, named and located | dropped, and not narrated |
+| INCONCLUSIVE | not settleable read-only | say what it would take; never round it to either side |
+
+Use a different model family from the one that produced the finding where you have one: a family asked to check its own claim tends to agree with itself.
+
+**Gate:** every finding **verified** before it reaches a human, and only CONFIRMED findings trigger a change. Hard cap one re-audit. `CLEAN` is a valid success state; an auditor that is not allowed to say so manufactures something, and so does a verifier that is expected to confirm.
 
 ### Stage 5b · Ship gate
 1. What is the rollback target? Record it before shipping.
@@ -94,14 +104,14 @@ Route by shape: security-shaped diffs (auth, tokens, routes, deletion, bulk muta
 
 | Role | Does | Does not |
 |---|---|---|
-| Builder / orchestrator | Routes, maps, writes, verifies, records. Stages 0, 1, 3, 6, 7 | Hand off the main build |
+{{ROLES_BUILDER_ROW}}
 | Judgment tier | Stage 2 and the architectural arm of Stage 5. Argues with a finished map | Perform the retrieval |
 | Adversarial auditor | The security arm of Stage 5. Attacks the diff | Fix anything |
 | Mechanical gates | Stage 4 and any always-on guard | Be overridden without reading |
 | Cheap workers | Bounded sub-parts: bulk passes, wide searches, long loops | Own a stage |
 | Human | Stage 5b, and any irreversible or architectural call | Be the first line of review |
 
-**Why the builder does not hand off the main build:** a delegated agent does not inherit the session's standing rules and usually cannot delegate further. Any brief must restate every convention it needs (see `TASK_BUNDLE.md`), and that cost is itself a reason to build directly when the work fits.
+{{BUILDER_HANDOFF_NOTE}}
 
 ## Checklist
 

package/templates/intermediate/CLI-RUN.md

@@ -18,7 +18,8 @@ Enabled lanes (edit `bin/lanes.json`): {{CLI_RUN_LANES}}
 ```bash
 node bin/cli-run.mjs <grok|codex|agy|hermes|qwen> "<prompt>" [--brief FILE] [--timeout SECS] [--quiet]
 node bin/cli-run.mjs codex --audit "<prompt>"                  # read-only sandbox, the audit shape
-node bin/cli-run.mjs qwen [--model ID] [--safe-mode] "<prompt>"
+node bin/cli-run.mjs codex "<prompt>" --model gpt-6-astra --effort high
+node bin/cli-run.mjs qwen [--safe-mode] "<prompt>"             # qwen-only flag
 ```
 
 Put it on your PATH if you like: `ln -s "$PWD/bin/cli-run.mjs" ~/.local/bin/cli-run`.
@@ -65,13 +66,49 @@ qwen is the lane whose own success flags lie: an upstream 400 comes back as exit
 | 2 | usage error in cli-run itself |
 | N | the lane exited N != 0: passed through unchanged, verdict `exit_nonzero`, even when parseable text came back. The bounded head of the lane's stderr is shown on your terminal so an auth failure reads as one |
 
+## The route: which model, and how hard it thinks
+
+A lane you do not pin runs on **its own config file**, which this tool cannot see. That is the quiet failure this section exists for: a CLI configured months ago at `reasoning_effort = "low"` keeps auditing at low effort while your routing docs describe an adversarial pass, and nothing anywhere says so.
+
+Pin it per call, or per lane:
+
+```bash
+node bin/cli-run.mjs codex "<prompt>" --model gpt-6-astra --effort high   # this call only
+node bin/cli-run.mjs --doctor                                            # prints what each lane is pinned to
+```
+
+```json
+{
+  "enabled": ["codex", "grok"],
+  "defaults": { "codex": { "model": "gpt-6-astra", "effort": "high" } }
+}
+```
+
+A flag beats `defaults`; `defaults` beats nothing. Each vendor spells these differently and `cli-run` translates:
+
+| Lane | Model | Reasoning effort |
+|---|---|---|
+| grok | `-m` | `--reasoning-effort` |
+| codex | `-m` | `-c model_reasoning_effort="LEVEL"` |
+| agy | `--model` | `--effort` (low, medium, high) |
+| hermes | `-m` | `--reasoning` (none, minimal, ...) |
+| qwen | `-m` | none: this lane has no reasoning flag |
+
+Three rules that keep this honest:
+
+- **A level `cli-run` does not recognise is not rejected here.** Levels are the vendor's, they change, and guessing the valid set would date this tool. An unknown level is refused by the lane and surfaces as that lane's own exit code and stderr.
+- **`--effort` on qwen is a usage error, not a silent drop.** A flag that vanishes leaves you believing a route that never ran.
+- **Values are charset-bounded** (letters, digits, and `. _ : @ / + -`, no leading dash, 64 characters). A model id becomes an argv element and, on codex, part of a TOML value; bounding it is what stops either from being escaped.
+
 ## Permissions are a separate layer
 
 `cli-run` never injects permission flags. Each CLI carries its own config, so every caller gets the same behaviour. Use each vendor's deny-list as the base layer; allow-lists only hold if every binary is enumerable in advance.
 
 ## Log
 
-`~/.ai-orchestrator/cli-run.log.jsonl`, one line per run: lane, verdict, rc, the lane's own exit code, signal, seconds, raw bytes, deliverable bytes, a 12-hex sha256 prefix of the prompt and its length, and `reason`: one of a fixed set of codes (`ok`, `not_json`, `bad_stop_reason`, `empty_text`, `no_terminal_event`, `bad_status`, `api_error_in_result`, `total_errors`, `contract_unmet`, `exit_nonzero`, `timeout`, `killed`, `disabled`, `lanes_json_malformed`, ...). Never the prompt text, never a provider-supplied value, never free text: a value the log does not recognise is written as `unknown`. The human-readable detail, which may quote the provider, goes to your terminal only (and nowhere with `--quiet`). "This lane is flaky" becomes a query instead of an argument.
+`~/.ai-orchestrator/cli-run.log.jsonl`, one line per run: lane, verdict, rc, the lane's own exit code, signal, seconds, raw bytes, deliverable bytes, a 12-hex sha256 prefix of the prompt and its length, the route (`model_requested`, `effort_requested`, and `model_source` / `effort_source`, each one of `flag`, `lanes.json` or `lane_default`), and `reason`: one of a fixed set of codes (`ok`, `not_json`, `bad_stop_reason`, `empty_text`, `no_terminal_event`, `bad_status`, `api_error_in_result`, `total_errors`, `contract_unmet`, `exit_nonzero`, `timeout`, `killed`, `disabled`, `lanes_json_malformed`, ...). Never the prompt text, never a provider-supplied value, never free text: a value the log does not recognise is written as `unknown`. The human-readable detail, which may quote the provider, goes to your terminal only (and nowhere with `--quiet`). "This lane is flaky" becomes a query instead of an argument, and so does "we route audits at high effort".
+
+The log records what was **requested**, on every record including a run refused before the lane started. It does not record an actual. Reporting is inconsistent: grok returns a `modelUsage` block naming a model, the other four lanes return nothing of the kind, so an `actual` field would be populated for one lane and empty for four. It would also be a provider-supplied string, and this log holds fixed codes and bounded caller-supplied values only. `model_source: "lane_default"` is the honest way to say this run inherited something invisible from here.
 
 ## The prompt travels in argv
 
@@ -79,7 +116,7 @@ That is each vendor's documented headless shape (`-p`, `exec`). Two consequences
 
 ## lanes.json fails closed
 
-Absent: every lane enabled. Present but malformed or unreadable: every lane refused (exit 13) until it is fixed. A half-written config never re-enables a lane the installer disabled.
+Absent: every lane enabled, nothing pinned. Present but malformed or unreadable: every lane refused (exit 13) until it is fixed. A half-written config never re-enables a lane the installer disabled. `defaults` is optional and held to the same standard: a malformed entry, an unknown lane, an unknown key, a value outside the charset, or an effort pinned on a lane that has no reasoning flag all fail the whole file closed rather than being skipped quietly.
 
 ## A killed lane is not a deliverable
 

package/templates/intermediate/ROUTING.md

@@ -15,18 +15,15 @@ Rule of thumb: never spend a frontier token on a task a cheap tier finishes corr
 0. **Is there a cheaper or better external lane for this?** Check `DELEGATION_MATRIX.md`. Your enabled lanes, every one called through `bin/cli-run.mjs`:
 {{LANE_STEP0}}
 1. **Bulk and mechanical?** → fast tier{{BULK_LANE}}. Many independent items each needing its own agent turn → a concurrent fan-out lane if you have one.
+1a. **Reading or digesting many files or notes, not writing?** → reader. Different from a bulk pass: reader reports, it does not classify, tag or transform.
 2. **Needs live data?** → {{LIVE_LANE}} standard tier with web tools.
 3. **Reviewing without changing?** → standard tier read-only. Security-critical → {{ATTACK_LANE}}.
+3a. **Holding findings from a review or a scanner?** → finding-verifier before any of them cause a repair. A finding is a claim, not a fact.
+3b. **Checking a tracker item or task against its stated done-signal?** → done-verifier. It probes the named artifact and returns MET, NOT_MET or UNVERIFIABLE; it never closes anything itself.
 4. **Ambiguous, strategic, expensive to get wrong?** → deep tier (deep-planner). Then hand the plan down.
-5. **Everything else that changes files** → the orchestrator builds it directly. Bounded sub-parts go to cheaper tiers; the main build is never handed off whole.
+{{DECISION_RULE5}}
 
-## Who builds
-
-**The orchestrator owns the main build.** It is the only surface that holds these rules: a subagent or a second CLI starts with none of them and cannot route. Handing the main build to one hands it to something the router cannot reach.
-
-Delegate: background and long-running tasks, small tasks, scoping, verification, research, bounded sub-parts. Never delegate: the main build, or any step that must carry a house rule (secrets handling, the loud-negative verification, the durable record).
-
-Every delegation carries `TASK_BUNDLE.md`. Its brief must restate every convention the delegate needs.
+{{WHO_BUILDS}}
 
 ## The Build Protocol, with lanes bound
 
@@ -38,6 +35,7 @@ Every delegation carries `TASK_BUNDLE.md`. Its brief must restate every conventi
 | 3 Build | the orchestrator, against the installed dependency's source |
 | 4 Scan | secret + static + dependency scanners, diff-scoped, fail closed |
 | 5 Attack | security-shaped diff → {{ATTACK_LANE}}. Architecture-shaped → deep tier, build against plan. Never both |
+| 5a Verify findings | finding-verifier, a different model family where you have one: CONFIRMED, NOT_REPRODUCED or INCONCLUSIVE per finding. Only CONFIRMED earns a repair |
 | 5b Ship | rollback id recorded, explicit human yes |
 | 6 Verify | real test, negative test seen red, old identifier re-grepped to zero |
 | 7 Record | one end-to-end doc, tracker Done with evidence, plan doc deleted |
@@ -54,12 +52,14 @@ One writer per run; every other lane proposes. Search before writing, index in t
 
 ## Modifier rules
 
-- **Plan big, execute small**, within a build: deep tier plans at Checkpoint 1, the orchestrator executes, bulk and wide searches go down.
+{{PLAN_BIG_LINE}}{{INLINE_THRESHOLD_NOTE}}
 - **Escalation:** never silently retry at the same tier. Escalate one tier or consult deep once, and say which. Two consults that do not unstick it → stop and tell the human.
 - **De-escalation:** a request that sounds deep but is a lookup routes down.
 - **Long context:** mechanical digestion → fast tier in chunks; judgment over a long input → standard tier.
 - **Token discipline on every delegation:** pass only the context the delegate needs, never the conversation.
-- **Effort per agent:** deep xhigh, review and build high, live research medium, bulk low.
+- **Effort per agent:** deep xhigh, review, verification and build high, live research medium, bulk low.
+- **Three inputs, not one:** role picks the agent, complexity moves the effort, risk moves the tier and who reads it. A one-line auth change is simple and high-risk at once, and the risk decides. See `TIERS.md`.
+- **Pin the route when it matters:** a lane with no `--model`/`--effort` and no `defaults` entry in `bin/lanes.json` runs on its own config, which may be nothing like what this file describes. `cli-run --doctor` prints what each lane is pinned to, and every run logs the value requested and where it came from.
 
 ## Example routings
 
@@ -67,7 +67,11 @@ One writer per run; every other lane proposes. Search before writing, index in t
 |---|---|
 | "Design the architecture for X" | deep-planner |
 | "Review this service for bugs" | code-reviewer |
-| "Add an endpoint" | the orchestrator builds it |
+{{ADD_ENDPOINT_ROW}}
 | "Why does this silently drop rows sometimes" | deep-planner (unknown cause), then build the fix directly |
 | "Summarize these 30 notes into one index" | bulk-worker |
+| "Read every note in this folder and pull out every mention of X" | reader |
+| "The audit returned 6 findings" | finding-verifier first; repair only what comes back CONFIRMED |
+| "Is issue #123 actually done" | done-verifier |
 {{LANE_EXAMPLES}}
+{{ROUTE_GATE_SECTION}}

package/templates/intermediate/TIERS.md

@@ -19,11 +19,54 @@ Tier sets the price per token. Token discipline sets how many tokens. **Effort s
 |---|---|---|---|
 | 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 |
 
-Dials: drop builder to medium when the plan is airtight; raise code-reviewer to xhigh for a security-critical audit.
+## 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.
+
+**Complexity moves the effort.** The same role does not need the same reasoning
+on every task.
+
+| Complexity | What it looks like | What moves |
+|---|---|---|
+| 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 |
+
+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.
+
+**Risk moves 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.
+
+| Risk | Present when the change touches | What it buys |
+|---|---|---|
+| security | auth, tokens, sessions, routes, untrusted input | the attack 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 |
+
+A risk raises code-reviewer to xhigh, and a security-shaped diff goes to the
+attack lane rather than to a second read by the same family. Risk is not a
+synonym for difficulty: a one-line change to an auth check is simple and
+high-risk at the same time, and it is the risk that decides the route.
+
+**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.
 
 ## Why split tiers: robustness first, cost second