agent-bios 0.11.0 → 0.12.1

package/README.md

@@ -24,7 +24,7 @@ Two layers:
 - **Every span we write into a file we do not own has a remover** — the Codex config block, the settings hook registrations, the `AGENTS.md` central region and the zsh hook line each sit in a span identifiable as ours (a marker pair, a tagged line, or a manifest name), and `uninstall` removes exactly those and nothing around them. The entry `CLAUDE.md`/`AGENTS.md` are seeded once and then yours: the corpus is assembled under `central/` and the entry file only imports it, so your own additions are never mixed with ours and never removed with them. `uninstall` is a security operation — everything of ours goes, and what it took leaves as one archive you can hand off or delete.
 - **Metadata selects, observation authorizes** — a record of what was promoted can propose an irreversible act but never authorize one; it has never seen the machine it will run on. Clearing a user's personal copy of a promoted learning asks the deployed corpus whether the replacement is really there, excludes the copy being deleted from that evidence, and keeps the copy on any uncertainty: a kept duplicate is redundant, a wrong removal is data loss.
 - **The deployment outlives the act that made it** — a command's success says nothing about which version landed; a cached package can serve the previous one at exit 0. So the deployed state carries its own version marker and `status` reads that marker rather than the source it was launched from. With no marker the answer is `unknown`, never a guess.
-- **`Evidence Base` (per guide) is the single owner of numbers.** Measure with `session-cost.py`.
+- **`Evidence Base` (per guide) is the single owner of numbers.** Measure with `session-cost.py` (`agent-bios cost` on an installed package).
 - **English is canonical and installed; Korean (`ko/`) is reference only.** The harness loads only fixed-name English files; the installer deploys English only.
 
 ## Layout
@@ -42,7 +42,7 @@ Two layers:
 | `wrappers/` | internal Codex wrappers, deployed to `$CODEX_HOME/bin/` |
 | `gates/` | author-side verification (mirror generation, parity, lexicon, payload, assembler scenarios) — reachable only from a repo checkout, and `check-package.sh` fails if any of it enters the npm payload |
 | `ontology/` | what a change obliges elsewhere — entities, obligation edges, and the service's routes, held against real source by `check-ontology.py`. `instances/graph.json` is canonical; `LEXICON.md`, the RDF views, the HTML map, and the competency/extension docs are generated from it |
-| `install.sh`, `session-cost.py` | the CLI and the cost meter — the two things you run directly |
+| `install.sh`, `session-cost.py` | the CLI and the cost meter — the two things you run directly (`agent-bios` and `agent-bios cost` once installed) |
 | `decisions/` | the decision record for developing this repo — what was decided and which alternative it closed; author-side, never shipped |
 | `packages/` | authored corpus packages, organized by package identity rather than by concept home |
 | `.githooks/` | the pre-commit hook that runs the gates against the index, enabled per clone with `core.hooksPath` |
@@ -95,11 +95,11 @@ agent-bios uninstall   # remove deployed files and the zsh hook
 
 From a git clone, run `./install.sh install` directly (the same CLI). `install` respects `CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `AGENT_LAUNCH_VENV`, and `ZDOTDIR`; `--dry-run` prints actions without changing anything. Deploy to **every active environment in one sitting** — a partial deploy leaves a shared global pointing at a guide some environment lacks; globals are English only. Replaced files are backed up under `~/.local/share/agent-bios/backups/<timestamp>/`, and the installed set is recorded in a manifest that `uninstall` consumes. Those copies are **a manual escape hatch, not a restore mechanism**: nothing reads them back, so recovering from one means copying files yourself. The supported paths are the ones `agent-bios help` prints — a clone rolls corpus content back to a registered version, an npm install rolls the whole package back by version — and `uninstall` emits one archive of everything it removed. The backups exist for the case those three do not cover: the exact bytes that were on disk before a particular install. The published npm package ships only the deploy set (never `settings.json`, `config.toml`, `ko/`, or `benchmarks/`).
 
-In a TTY, zero-argument `codex` or `claude` opens the launch preflight. Every arrow-key TUI selection screen keeps the complete current setup in a fixed top panel, followed by the highlighted option's description and then the option list. Move with Up/Down, select with Enter, use Esc to return to the previous menu, and use `q` to cancel; Esc at the mode root also cancels. Each tier's model is chosen from the host's configured catalog, or via **Other** to type any model id the backend accepts; that text input preserves values that start with `q`, so Esc or Ctrl-C cancels immediately there, while submitting `q` cancels after Enter. The Textual preflight reflows to the terminal size, so there is no fixed minimum geometry. The root menu picks a mode — **Software Engineer** (repo-scoped work that defers to the project's own AGENTS.md/CLAUDE.md: **Vanilla**, the bare CLI with no launch contract, tier bindings, or applied permissions, plus **Custom**; SE-specific review defaults arrive later), **Builder** (the tier presets: Balanced, Deep review, Fast batch, Solo with delegation off, plus Custom), **Session distill** — then a preset within it. Select **Custom** (in Software Engineer or Builder) to open a persistent settings hub for the main tier, review setup, host policy, and each tier binding. Every edit returns to that hub; **Start with these settings** is the final launch confirmation, **Save these settings globally and start** additionally persists the setup as a named preset (with host-scoped tier overrides) in your user config for reuse elsewhere, and **Exit without launching** cancels the launch. The rich preflight runs from a managed virtualenv (`launch/provision-venv.sh`, at `~/.local/share/agent-launch/venv`) that the launcher re-execs into on the interactive path; when that venv is unavailable, or the call is non-interactive, or `TERM` is `dumb`/unset, the launcher falls back to numbered prompts, where `b` is the back command. Backend command names are resolved from the calling environment's `PATH`; shell functions are not re-entered. Codex child bindings are materialized as session-selected agent configs under the user cache, while Claude receives model and effort in `--agents` JSON when delegation is enabled. Review runs cross-family by default (`review_family`, default `cross`; `same` restores today's same-family projection): because the main's tiers are one model family, every dispatchable review route — native and the deep route — runs on the opposite family. The exception is `slash-review`, the host's own built-in review command (`/code-review` on Claude, with `ultra` for its deep multi-agent pass; `/review` on Codex): it needs no dependency and always resolves, but being the main's own command it cannot be dispatched cross-family, so under `cross` it runs as the same-family floor and its verdicts are labeled PROPOSED. A Claude main dispatches gpt/codex review (native via the `codex-run` reviewer wrapper resolved under `$CODEX_HOME/bin`, deep via plain `codex exec -m <frontier model> -c model_reasoning_effort="ultra"` with a self-contained packet on stdin — `-c service_tier="fast"` is the explicit faster, shallower opt-in); a Codex main dispatches Anthropic/Claude review (native via `claude -p --permission-mode plan`, deep via the `claude` CLI headless with the keyword `ultracode` in the prompt, which is what opens Claude Code's dynamic workflow for that turn). The concrete reviewer command, resolved absolute path, and opposite-family tier bindings are named in the injected session-start contract; cross-family reviewers are dispatched as read-only subprocesses, not CLI-native subagents, since neither CLI hosts the other family as a native subagent. When a cross-family route is unavailable at launch or unauthenticated at use time it degrades to same-family native subagent review labeled PROPOSED (family collapse) rather than blocking; a requested non-none review with no cross-family route and no same-family fallback (delegation off) stays fail-closed. Review setup means configured/requested; this launcher does not claim that review completed, and unavailable runtimes such as Ultrawork are not offered until integrated.
+In a TTY, zero-argument `codex` or `claude` opens the launch preflight. Every arrow-key TUI selection screen keeps the complete current setup in a fixed top panel, followed by the highlighted option's description and then the option list. Move with Up/Down, select with Enter, use Esc to return to the previous menu, and use `q` to cancel; Esc at the mode root also cancels. Each tier's model is chosen from the host's configured catalog, or via **Other** to type any model id the backend accepts; that text input preserves values that start with `q`, so Esc or Ctrl-C cancels immediately there, while submitting `q` cancels after Enter. The Textual preflight reflows to the terminal size, so there is no fixed minimum geometry. The root menu picks a mode — **Software Engineer** (repo-scoped work that defers to the project's own AGENTS.md/CLAUDE.md: **Vanilla**, the bare CLI with no launch contract, tier bindings, or applied permissions, plus **Custom**; SE-specific review defaults arrive later), **Builder** (the tier presets: Balanced, Deep review, Fast batch, Solo with delegation off, plus Custom), **Session distill** — then a preset within it. Two entries below the modes act on the installation rather than the launch: **Corpus packages** opens a checklist of the optional domain packages (core + infra always install) and, on Apply, hands the exact checked set to `agent-bios onboard --domains` — the installer alone deploys, runs the activation canary, and records the outcome, which the status panel then reports, loudly when an apply failed. **Language** switches the interface text between English, 한국어, and 日本語 and persists the choice in your own `launcher.local.toml`; it changes the launcher's own screens only, since the corpus the models consume is English-unified. Select **Custom** (in Software Engineer or Builder) to open a persistent settings hub for the main tier, review setup, host policy, and each tier binding. Every edit returns to that hub; **Start with these settings** is the final launch confirmation, **Save these settings globally and start** additionally persists the setup as a named preset (with host-scoped tier overrides) in your user config for reuse elsewhere, and **Exit without launching** cancels the launch. The rich preflight runs from a managed virtualenv (`launch/provision-venv.sh`, at `~/.local/share/agent-launch/venv`) that the launcher re-execs into on the interactive path; when that venv is unavailable, or the call is non-interactive, or `TERM` is `dumb`/unset, the launcher falls back to numbered prompts, where `b` is the back command. Backend command names are resolved from the calling environment's `PATH`; shell functions are not re-entered. Codex child bindings are materialized as session-selected agent configs under the user cache, while Claude receives model and effort in `--agents` JSON when delegation is enabled. Review runs cross-family by default (`review_family`, default `cross`; `same` restores today's same-family projection): because the main's tiers are one model family, every dispatchable review route — native and the deep route — runs on the opposite family. The exception is `slash-review`, the host's own built-in review command (`/code-review` on Claude, with `ultra` for its deep multi-agent pass; `/review` on Codex): it needs no dependency and always resolves, but being the main's own command it cannot be dispatched cross-family, so under `cross` it runs as the same-family floor and its verdicts are labeled PROPOSED. A Claude main dispatches gpt/codex review (native via the `codex-run` reviewer wrapper resolved under `$CODEX_HOME/bin`, deep via plain `codex exec -m <frontier model> -c model_reasoning_effort="ultra"` with a self-contained packet on stdin — `-c service_tier="fast"` is the explicit faster, shallower opt-in); a Codex main dispatches Anthropic/Claude review (native via `claude -p --permission-mode plan`, deep via the `claude` CLI headless with the keyword `ultracode` in the prompt, which is what opens Claude Code's dynamic workflow for that turn). The concrete reviewer command, resolved absolute path, and opposite-family tier bindings are named in the injected session-start contract; cross-family reviewers are dispatched as read-only subprocesses, not CLI-native subagents, since neither CLI hosts the other family as a native subagent. When a cross-family route is unavailable at launch or unauthenticated at use time it degrades to same-family native subagent review labeled PROPOSED (family collapse) rather than blocking; a requested non-none review with no cross-family route and no same-family fallback (delegation off) stays fail-closed. A reviewer this launcher has never seen is yours to add: **Register another reviewer…** in the review editor asks for the descriptor a method needs, proves the candidate by running it through the real config reader before a byte is written, and appends it to `review-methods.local.toml` beside your config — a file the installer never deploys, verifies, or overwrites, whose entries face exactly the validation a shipped one does and whose name may not shadow a shipped method. A refusal shows the reader's own message and leaves that file byte-identical. Review setup means configured/requested; this launcher does not claim that review completed, and unavailable runtimes such as Ultrawork are not offered until integrated.
 
 At the shell-wrapper boundary, every argument-bearing command (`codex exec ...`, `claude -p ...`) and every non-TTY invocation skips launch-profile projection and preserves caller arguments. The Claude direct path intentionally retains its wrapper default, `--dangerously-skip-permissions`. `codex --no-tui ...` / `claude --no-tui ...` explicitly take that direct path, and `AGENT_LAUNCH_TUI=0` disables zero-argument TUI interception for a process tree.
 
-Direct `agent-launch` calls still require a valid profile to resolve the backend command and its default arguments. `--preset`, `--custom`, or `--dry-run` select the configured-launch path even when non-TTY or combined with `--no-tui`; a non-TTY bare `--dry-run` deterministically uses Balanced, and a custom profile without that preset must pass `--preset NAME`. Forwarded backend arguments are expert overrides appended after projected defaults and may supersede them; the summary discloses this when arguments are present. For scripted configured launches, call `$HOME/.local/bin/agent-launch --preset NAME --yes HOST -- ...` or add `$HOME/.local/bin` to `PATH`. The summary goes to stderr so backend stdout stays machine-consumable.
+Direct `agent-launch` calls still require a valid profile to resolve the backend command and its default arguments. `--preset`, `--custom`, or `--dry-run` select the configured-launch path even when non-TTY or combined with `--no-tui`; a non-TTY bare `--dry-run` deterministically uses Balanced, and a custom profile without that preset must pass `--preset NAME`. Forwarded backend arguments are appended verbatim after the projected defaults; one that would override a projected option (the seat, the contract, delegation, policy) is refused at launch so the contract keeps describing the run, and the summary discloses forwarded arguments when present. For scripted configured launches, call `$HOME/.local/bin/agent-launch --preset NAME --yes HOST -- ...` or add `$HOME/.local/bin` to `PATH`. The summary goes to stderr so backend stdout stays machine-consumable.
 
 Add `$CODEX_DIR/bin` to `PATH` or invoke the wrappers by absolute path. `codex-helm` follows the local CLI default and launches the HELM main with `--dangerously-bypass-approvals-and-sandbox`; an explicit `--sandbox MODE` disables bypass for that run regardless of flag order. `AGENTS.md` gives root/main local Codex sessions standing ordinary-subagent authorization when the delegation gates fire. A non-Ultra HELM main sets native multi-agent off by default and instructs HELM to send tiered dispatch through the internal `codex-run` adapter, where the selected model, effort, and sandbox are pinned; native multi-agent defaults on only when the HELM main itself is explicitly Ultra. FRONTIER is instructed to run as a separate `gpt-5.6-sol` root that is always read-only, at max by default, Ultra for genuinely divisible complex work, or a lower supported effort when cost or latency dominates. Because the HELM main has bypass authority and arbitrary expert `-c` by design, this dispatch route is an instruction-backed, live-E2E-verified default rather than a security boundary. Keep `codex-run` as the low-level internal adapter, not as a user-facing policy boundary. Both wrappers accept `-c key=value` as an expert override, and that override may intentionally change wrapper defaults for a single run.
 

package/claude/guides/cli-multi-model-workflow.md

@@ -154,6 +154,50 @@ How much independence a review actually bought, as an ordinal grade per reviewer
 - After resume/clear/relocation, verify pwd, branch, and HEAD against the pinned handoff before acting.
 - Attribute a parallel session's action (commit, branch, resource) by execution evidence in that session's own transcript, never by token mentions — shared handoff/memory files inject the same tokens into every session's context.
 
+## Context Budget And Reset
+
+Context growth is a property of the work, not of the host: over 1,075 sessions of 50+
+requests across both CLIs it runs ~2,400 tokens per request (IQR 1,850-2,950), the two
+hosts within 7% of each other (2,280 Claude, 2,450 Codex); the longest sessions (400+
+requests) run lower, ~1,800. One budget therefore serves both, and what differs per host
+is the price of ignoring it. The figure is a prior; the live session is measured below.
+
+- **Automatic compaction fires only when the window is nearly full** — Claude at 84-87%
+  (windows cluster at 200K and 1M), Codex at ~95% of the window its transcript records as
+  `model_context_window` (258,400 on the sessions measured; a later Codex/model pair
+  records 353,400 — read the value, never assume it). Cache read is charged per
+  request against the whole loaded context, so leaving the reset to the host pays the
+  maximum on every request before it. Measured: input is 92-94% of session cost and
+  output 6-8%, at a 95-97% cache hit rate — the context is the bill, and uncached input
+  is 0.0% of it.
+- Reset deliberately instead. Cost per request falls ~4x from an 867K auto-compact point
+  to 200K. The cost-theoretic optimum is ~65K, but it buys a compaction every ~32
+  requests at 2-3 minutes each, so 150-250K is the working range and the tail below it is
+  not worth chasing.
+- **What bounds the budget is what survives the reset, not the token count.** A compaction
+  keeps a ~14K summary plus 3-4 recent messages and discards the rest — unguided when it
+  fires on its own. Anything already written to a file survives every reset, so the
+  earliest safe threshold is the one where durable state is already on disk. That is what
+  decouples cost from loss: without it, resetting more often loses proportionally more.
+- Choose the mechanism by what is known, not by how large the context grew:
+
+| Situation | Mechanism |
+|---|---|
+| Stage finished, what to keep is known | clear + dated handoff file — cheapest, and the loss is not a loss |
+| Mid-stage, what to keep is known | write the handoff first, then compact with explicit instructions |
+| Mid-stage, the needed detail is not yet identifiable | compact with instructions; a summary spans what a file cannot yet name |
+| Original detail likely wanted later | clear, and record the transcript path in the handoff — transcripts persist on disk |
+| The next question is unknown | new session plus messaging; only this keeps a round trip available |
+| Growth is tool output | offload to subagents instead — measured ~20x cheaper (tier ~5x, context isolation ~4x) |
+| The judgement trail itself is load-bearing | keep the session and pay the 2-5x resume |
+
+- Measure rather than estimate: `agent-bios cost --context <transcript>` (the installed
+  entry to `session-cost.py`) reads either
+  host's transcript and reports current context, growth rate, compactions, and requests
+  remaining against a budget. Codex records `model_context_window` directly; Claude does
+  not, so the tool reports its observed auto-compaction point instead of assuming a
+  window.
+
 ## Handoff Contract
 
 Write for the next agent and re-verification, not narrative. Required content:
@@ -223,3 +267,5 @@ Single owner of numeric defaults; one production environment, 2026-07. Recalibra
 | two live delegation sessions | tiering saved ~3.3×; discarded prefixes made fresh respawn cheaper; unpinned reviewers inherited FRONTIER |
 | Codex reach contrast | inherit ~16.5K vs hermetic ~8.7K tokens; schema and stdout/stderr contract verified |
 | Codex native-spawn probe + HELM E2E | requested max/Ultra native children recorded xhigh/role null; separate read-only roots recorded max and Ultra successfully |
+| 1,075 sessions of 50+ requests, both hosts (2026-08-16; the earlier 62-session top-by-size sample gave ~1,800-2,000) | context grows ~2,400 tok/request (IQR 1,850-2,950), hosts within 7%, ~1,800 in 400+-request sessions; auto-compaction fires at 84-95% of window, never earlier |
+| 2 sessions decomposed by cost component (2026-08) | input 92-94% of cost, output 6-8%, cache hit 95-97%, uncached input 0.0%; an 867K→200K budget cuts cost per request ~4x |

package/claude/guides/coding-staged-workflow.md

@@ -80,6 +80,7 @@ patching them one at a time is a queue that refills.
 
 - At each stage, run review loops as appropriate: self review, subagent review when available, and structured multi-lens review when the repository or domain supports one (concrete tool: Environment Binding below).
 - Iterate until material issues reach zero: review, identify material issues, fix them, and review again.
+- "Material issues reach zero" is counted over the declared defect criterion's stop-relevant class; choosing and declaring that criterion is owned by `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/review-defect-criteria.md`.
 - Use the severity contract for materiality — the canonical definition is the ladder below; external review tools map their levels onto it: blocker, high, and medium are material; low and info are non-material.
 - Treat blocker as primary happy-path or core-contract failure.
 - Treat high as supported user, environment, data, or execution path failure.

package/claude/guides/review-defect-criteria.md

@@ -0,0 +1,205 @@
+---
+guide_id: review-defect-criteria
+language: en
+status: active
+use_when:
+  - declaring what counts as a defect before dispatching any review
+  - choosing or writing the defect criterion for a system type × work goal
+  - a review loop plateaus, diverges, or its "material 0" stop never arrives
+  - a finding's class is contested at the boundary, or two lenses class it differently
+core_rules:
+  - choose and declare the criterion before the review starts — undeclared, every reviewer substitutes its own
+  - the severity ladder answers how bad; the criterion answers whether it is a defect, of which class, and what "zero" is counted over
+  - a criterion with an empty cell is a hunch, not a criterion — do not start the review
+  - paste the goldens into the packet verbatim; a definition alone does not classify consistently at the boundary
+  - put the class enum on the accepting channel where one exists; on prose routes, run the fold procedure
+  - a mixed packet is split — never run two observers in one trajectory
+verification_focus:
+  - every dispatched packet names its criterion and carries its goldens
+  - each round audits reported class against post-measurement class; repeated disagreement mints the next golden
+  - the stop condition is evaluated over the stop-relevant class only, never the whole finding count
+---
+
+# Review Defect Criteria
+
+A defect criterion is chosen, not assumed. This guide is a scoped extension of
+`${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/review-request.md`: before that guide's
+request composition starts, this one decides what the review is hunting. The
+evidence: one codebase, two stop criteria, opposite trajectories.
+
+| Rounds | Criterion | Trajectory |
+|---|---|---|
+| early | material = contract violation **or** unprotected contract sentence, small frozen surface | 10 → 4 → 1 → 0 |
+| late | same, scoped to client-observable behavior | 17 → 19 → 21 → 23 → 19 — **plateau** |
+| final | split classes: behavioral_defect / coverage_gap / doc_gap; stop = behavioral 0 | behavioral 10 → 5 — falling again |
+
+The plateau was the criterion, not the code: counting "a contract sentence no test
+protects" as a defect means every fix adds contract rows, each a potential defect
+next round — a self-refilling criterion cannot reach zero while its surface grows.
+Yet that same criterion is exactly right for a library, where an unprotected promise
+is a first-class defect. Neither is wrong; starting without choosing is.
+
+The **severity ladder** (in `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/coding-staged-workflow.md`)
+answers *how bad* a finding is. The **criterion** answers *whether* it is a defect at
+all, of which class, and what "zero" is counted over. The plateau happened entirely
+inside "material" — no severity adjustment could have ended it. Ordering: system type
++ goal → defect criterion → classification → defect? → severity → materiality → stop.
+
+## The criterion schema
+
+One entry carries all of these. An empty cell makes it a hunch, not a criterion — do
+not start the review on it.
+
+| Field | Meaning |
+|---|---|
+| observer | whose eyes judge — client, caller, operator, a model reading the output |
+| defect | what the observer must experience |
+| classes | the enum, exactly ONE class stop-relevant; the others are relief valves that keep the stop class honest |
+| evidence | what one finding must present |
+| non-defects | defect-lookalikes excluded by this criterion — named explicitly |
+| stop condition | what "0" means, counted over the stop class, and WHY it is reachable — how a growing surface is pinned |
+| misclassification cost | which error is expensive — the direction to tell the reviewer to lean |
+| goldens | ≥2 positive, ≥2 negative, ≥1 boundary; each with why, date, and provenance: `measured` (dated incident) or `constructed` (authored to pin a boundary) |
+
+## The catalog
+
+Four system types. A starting set, not a census.
+
+### Web service / API surface (contract compliance)
+
+- **Observer**: the HTTP client.
+- **Defect**: a client today receives a response that differs from the contract — status code, envelope, stream terminal frames, the model actually run, isolation, resource caps.
+- **Classes**: `behavioral_defect` (stop-relevant) · `coverage_gap` · `doc_gap`.
+- **Evidence**: the concrete request and observed vs promised response.
+- **Non-defects**: internal lifecycle (unless a request sequence shows two different responses), absence of a test, documentation wording.
+- **Stop**: behavioral 0 — reachable: the code surface is finite and shrinks monotonically unless a fix creates a new behavioral defect.
+- **Misclassification cost**: false negatives (a client actually breaks); but inflating coverage gaps into defects destroys the stop condition — audit category creep separately.
+- **Goldens** (all `measured`, 2026-08-13–15):
+  - **+** `GET` on a nonexistent path returned 405, not 404 — an existing-method complaint attached to a path that does not exist.
+  - **+** a streaming endpoint's terminal delta carried only `output_tokens`, so cache/input token counts never reach a streaming client — non-streaming was correct, which is why nobody saw it.
+  - **−** "no test catches a one-line flip of this default": today's behavior is correct — `coverage_gap` here, a defect only under the library criterion.
+  - **−** child-process kill grace period — out of scope until a request sequence shows a client-visible difference; pins the observer to the client.
+  - **±** rejecting a documented-as-valid boundary value (compression 100, docs say "below 100 requires jpeg/webp") — the documentation is what makes it a defect; without that sentence it is taste.
+
+### Library / SDK / contract-first system
+
+- **Observer**: the caller **and** the future maintainer.
+- **Defect**: a promise violated today, or a promise unprotected — a one-line change breaks it and nothing catches it. The API criterion's `coverage_gap` is first-class here.
+- **Classes**: `contract_defect` (stop-relevant) · `style_note` · `internal_change`.
+- **Evidence**: for a violation, as above; for an unprotected promise, the promise sentence + the one-line change that breaks it + the absence of any catching test.
+- **Non-defects**: style, internal structure.
+- **Stop**: caution — this criterion self-refills while the contract grows. Declare "0" only over a surface whose growth has stopped; on a growing surface, narrow the stop to "every promise this change added is protected."
+- **Misclassification cost**: balanced — miss an unprotected promise and the next refactor breaks it silently; over-report and the loop never ends.
+- **Goldens**:
+  - **+** a streaming-image event test matched only `.completed`, so an edit stream misnamed `image_generation.completed` still passed — mutation survival showed the promise unprotected. (`measured`, 2026-08-13–15)
+  - **+** the contract promised "storage serves a large image at least once"; the code evicted it on the next request — resolved by fixing the **contract**: the disagreement is the defect, whichever side moves. (`measured`, 2026-08-13–15)
+  - **−** renaming an internal helper no document promises — the observer holds the contract; undocumented internals carry no promise. (`measured`, 2026-08-13–15)
+  - **−** a caller breaking on undocumented iteration order — no promise existed; the rename boundary pinned from the caller's side. (`constructed`, 2026-08-19)
+  - **±** an inventory-listed test turns out vacuous — asserts nothing about its promise. "A test exists" is a claim about names until the assertion is read; hand the reviewer "check the assertion, not the name." (`measured`, 2026-08-13–15)
+
+### AI workbench / harness (agent orchestration, review loops, verification pipelines)
+
+- **Observer**: the operator, and any model consuming the harness's output.
+- **Defect**: **a false signal that looks true** — a wrong PASS, a vacuous test, a silent fallback, a packet missing the call site, a wrong denominator. Being wrong is not the defect; being wrong while *looking right* is. Second form: a run claimed without provable dispatch — no receipt.
+- **Classes**: `false_signal` (stop-relevant) · `detected_miss`. An unproven dispatch — a run or PASS claimed with no receipt — is classed `false_signal`, not given its own relief valve: a signal that cannot be shown true is counted false, or a round could declare completion while every dispatch stayed unproven.
+- **Evidence**: the input on which the instrument gave a false verdict, plus the known correct answer. The standard probe: run the instrument against an input whose answer is known to be the opposite.
+- **Non-defects**: one output's style; a false positive the harness itself **detected** — a caught error is the harness working.
+- **Stop**: every PASS emitted this run survives a known-opposite check and evidences its own dispatch. The unit is "this run's signals are trustworthy," not a standing zero.
+- **Misclassification cost**: false passes dominate. An instrument bug reporting failure dies in minutes because someone looks; one reporting success survives — a selection effect.
+- **Goldens**:
+  - **+** a shell test runner received one nonexistent path (zsh does not word-split an unquoted variable), so every run exited 1 and every mutation reported KILLED — a green instrument that never ran its subject. (`measured`, 2026-08-13–15)
+  - **+** a test-inventory grep matched only `^test('...'` and missed every parameterized name; three reviewers judged a populated file empty — nothing tied the inventory's denominator to the source's own count. (`measured`, 2026-08-13–15)
+  - **+** a negative control kept passing after a faithful revert of the fix it was written against — a guard satisfied by an absence, a false PASS about the gate itself; found only by re-running reverts. (`measured`, 2026-08)
+  - **+** a review round returned "clean" with no receipt evidencing that the declared packet was dispatched on the exact seat — `false_signal` although nothing observed was wrong: what the stop refuses is absence of proof of dispatch, not proof of falsity. (`constructed`, 2026-08-19, pinned after a classification dispute at exactly this boundary)
+  - **−** one reviewer over-classed an item as material; another lens plus measurement filtered it — the harness caught it, so it worked: `detected_miss`, not a defect. (`measured`, 2026-08-13–15)
+  - **−** five review rounds returned 8 → 9 → 10 → 5 → 12 findings, refusing to converge — and every count was true. A truthful unpleasant signal is not a false signal; the defect lived in the undeclared criterion. (`measured`, 2026-08-16–17)
+  - **±** a surviving mutation proved equivalent — the platform already normalized what the mutated guard checked. Neither a harness defect nor a test gap; but a harness that auto-reads "survived = gap" has a defect in that rule. (`measured`, 2026-08-13–15)
+
+### Decision ontology (an ontology a model decides from)
+
+- **Observer**: a model or agent deciding from the ontology alone.
+- **Defect**: a representation that produces a wrong decision or blocks a right one: overlapping concept boundaries, a missing distinction the decision needs, an instance contradicting reality, a wrong relation direction or cardinality, a name implying what the definition does not say.
+- **Classes**: `decision_defect` (stop-relevant) · `representation_note` · `out_of_scope_gap`.
+- **Evidence**: a **decision scenario** — "answered from the ontology alone, this question yields X; reality is Y" — with the question, the path taken, and the ground truth.
+- **Non-defects**: representation format, completeness as such, a question the model would get wrong without the ontology too.
+- **Stop**: zero wrong decisions over the agreed scenario set. The set is the scope — fix it first, or this criterion self-refills like the library one.
+- **Misclassification cost**: situational — feeding a hard gate makes false negatives expensive; exploratory aid makes false positives expensive. Filling this cell is mandatory at declaration.
+- **Goldens** (all `constructed`, 2026-08-19, authored to pin boundaries the source loop's decision-scenario framing left open):
+  - **+** `Customer` and `Account` both define "the paying party"; a refund-routing question resolves through both paths — overlap is a decision defect even when each definition is individually correct.
+  - **+** `Order —hasOne→ Payment` while split payments exist — cardinality is a claim, and a false claim misleads the deciding model.
+  - **−** a verbose concept description — no decision changes; form is outside this observer's sight.
+  - **−** a domain absent that no scenario in the agreed set needs — completeness is scoped by the set, not the world.
+  - **±** the distinction exists but the model cannot find it (name or link missing) — with the observer fixed as "a model seeing only the ontology," unreachable is a representation defect, not a search defect. The observer clause decides the class.
+
+## Before any review
+
+1. Write one sentence: the system type and this work's goal. ("API surface — make the responses clients receive today match the contract." / "Harness — make this run's PASS signals trustworthy.")
+2. Pick a criterion from the catalog, or fill the schema fresh. A cell you cannot fill means the review does not start.
+3. Paste the goldens into the packet verbatim. Never the definition alone.
+4. Declare the stop condition and why it is reachable — or how the scope was pinned to make it so.
+5. Put the classification on the accepting channel (next section).
+6. Audit every round: reported class vs the class confirmed after measurement. A repeated disagreement is the next golden.
+
+## Enforcing the enum, by channel
+
+Ranked by how much the channel refuses for you:
+
+1. **A route with a submit schema**: classification is a required enum field. The
+   measured precedent is anchors — 2,466 of 2,466 findings carried one, because the
+   schema refuses output without it. Where this channel exists, use it.
+2. **Prose-packet routes** (the shipped deep-review methods): the packet header
+   declares `Criterion: <name>` with the goldens pasted verbatim, and the dispatching
+   agent runs this fold procedure on what comes back:
+   1. For each returned finding row, look up its class against the declared enum.
+   2. A row carrying a class from the enum enters the findings ledger under that class.
+   3. A row with no class, or a class outside the enum, is **not admitted**: send it
+      back once for classification, or record it as refused with the reason. Never
+      admit it unclassified, and never guess its class for it.
+   4. Count the stop condition over the stop-relevant class only.
+   5. Record the audit pair (reported class, confirmed class) for procedure step 6.
+
+   Stated honestly: on a prose route this is steering, not control — the fold is
+   performed by an agent following this guide, and nothing structural refuses a
+   class-less row for it. That is the known weaker result of a request-only rule.
+3. A structural criterion slot in the review dispatch machinery is deliberately not
+   part of this guide: a criterion is per-review while dispatch config is per-launch,
+   and a slot with no schema-backed consumer would be an inert value. Until such a
+   channel exists, ranks 1–2 are the real ones.
+
+## Golden lifecycle
+
+- **Admission**: only a golden that decides a boundary the definition leaves open,
+  evidenced by a recorded classification disagreement or an audited misclassification;
+  provenance labeled `measured` or `constructed`, each with its why and date.
+- **Overturn**: only by a measured counterexample. Correct the golden in place — this
+  guide describes the present — plus a dated decision record, in whatever channel the
+  repo keeps decisions, naming the closed golden and the counterexample. Silent
+  deletion is forbidden: a wrong golden makes reviewers systematically wrong, and an
+  untracked fix hides that it ever did.
+
+## Declaring, switching, and mixed packets
+
+- Every dispatched packet names its criterion. A harness round declares `AI harness`;
+  a round whose system type has no catalog entry declares a **task-local criterion**,
+  written in the packet itself, conforming to the schema above and labeled task-local
+  — repeated use is what earns a catalog entry.
+- A mixed packet is split into one packet per criterion. Two observers in one
+  trajectory produce findings no single stop condition can count.
+- When a criterion changes mid-loop: re-classify only the findings still open; rounds
+  already recorded are dated history. Never splice pre- and post-switch counts into
+  one series — they count different things.
+
+## Evidence base
+
+Derived from a 39-round adversarial review loop (3 lenses × a frontier reviewer) on a
+peer OAuth CLI-API adapter, 2026-08-13–15: the same codebase plateaued at
+17→19→21→23→19 findings under a self-refilling criterion and resumed falling
+(behavioral 10→5) the round the classes were split and the stop counted over
+`behavioral_defect` alone. The boundary evidence is from the same loop: a packet
+instruction saying "do not inflate coverage gaps" still left two lenses classing one
+finding `doc_gap` and `behavioral_defect`, both defensibly — one golden would have
+decided it. The non-convergence golden (8→9→10→5→12, every count true) is this
+environment's own launcher-review loop, 2026-08-16–17, run under an undeclared
+"material" criterion; the two series are two populations under two criteria and are
+cited separately for exactly the reason the migration section gives. Re-derive when
+the review routes or the bound models change.

package/claude/guides/review-request.md

@@ -26,7 +26,11 @@ verification_focus:
 This guide is a scoped extension of the global Coding Guidelines. Use it when
 composing what you ask a reviewer for — the request, the evidence bar, the
 verdict shape. It does not cover when to review, how deep, or what counts as
-material (the severity ladder and review loop in `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/coding-staged-workflow.md` own that),
+material — that last question splits in two: the severity ladder and review loop in
+`${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/coding-staged-workflow.md` own *how bad*,
+while whether something is a defect at all, of which class, and what "zero" is
+counted over is the defect criterion, owned by
+`${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/review-defect-criteria.md`. Nor
 which reviewer kind to route to — the convergence heuristic in
 `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/verification-discipline.md` owns that. Phrasing a prompt for a specific model
 family is out of scope here; where that guidance ships, the rule that needs it
@@ -38,6 +42,16 @@ is a per-model claim; these are the failures that persist regardless of who
 reviews. Every rule names the evidence behind it, because a review guide that
 asserts without evidence would fail its own bar.
 
+## Declare the criterion
+
+Before composing anything else, name the defect criterion the review runs under —
+the per-system-type definition of what a defect is, its class enum, and what "zero"
+is counted over. `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/review-defect-criteria.md`
+owns choosing it; this guide assumes one is declared. Put `Criterion: <name>` at the
+top of the packet with that criterion's goldens pasted verbatim — a definition
+without goldens does not classify consistently at the boundary, and an undeclared
+criterion means every reviewer substitutes its own.
+
 ## Demand a failure path, not a gap
 
 The dominant reviewer failure is not hallucination. Across 372 rejected

package/claude/hooks/tooling-gotchas-hook.py

@@ -172,9 +172,19 @@ def main() -> int:
         payload = json.load(sys.stdin)
     except Exception:
         return 0  # never block on malformed input
-    if payload.get("tool_name") != "Bash":
+    # Malformed is a SHAPE, not just a parse failure. The guard above only covered bytes
+    # that are not JSON; a well-formed payload of the wrong shape — a top-level array, a
+    # list-valued tool_input, a non-string command — walked straight into `.get` or into
+    # `re.search` and left this hook exiting 1 with a traceback. That is the one thing
+    # the charter says it never does, and it would do it before EVERY Bash call in every
+    # deployed session, on a payload shape decided by a host this repo does not own.
+    # Advisory means silent on anything it cannot read, so each check returns 0.
+    if not isinstance(payload, dict) or payload.get("tool_name") != "Bash":
+        return 0
+    tool_input = payload.get("tool_input")
+    command = tool_input.get("command") if isinstance(tool_input, dict) else None
+    if not isinstance(command, str) or not command:
         return 0
-    command = (payload.get("tool_input") or {}).get("command") or ""
     hits = matches(command)
     if not hits:
         return 0
@@ -219,6 +229,31 @@ def self_test() -> int:
     if r2.stdout.strip():
         problems.append(f"hook injected on a command that matches nothing: {r2.stdout.strip()[:80]!r}")
 
+    # Never-blocks is a claim about EVERY payload, so the shapes that are valid JSON and
+    # not the expected object are the ones worth naming. Each of these exited 1 with a
+    # traceback before the shape guard existed, and each stands for a different way the
+    # host's payload could move: a different top-level type, a different tool_input type,
+    # a command that is not a string. The two controls above are the other half — a guard
+    # that returns 0 on everything would satisfy this block and nothing else.
+    for label, raw in (
+        ("top-level array", "[1, 2, 3]"),
+        ("top-level null", "null"),
+        ("top-level string", '"hello"'),
+        ("tool_input as a list", '{"tool_name": "Bash", "tool_input": [1, 2]}'),
+        ("tool_input as null", '{"tool_name": "Bash", "tool_input": null}'),
+        ("command as a number", '{"tool_name": "Bash", "tool_input": {"command": 123}}'),
+        ("command as a list", '{"tool_name": "Bash", "tool_input": {"command": ["git", "pull"]}}'),
+        ("command absent", '{"tool_name": "Bash", "tool_input": {}}'),
+        ("empty stdin", ""),
+    ):
+        r3 = subprocess.run([sys.executable, str(here)], input=raw, capture_output=True, text=True)
+        if r3.returncode != 0:
+            problems.append(
+                f"hook exited {r3.returncode} on {label} instead of staying silent: "
+                f"{r3.stderr.strip()[-120:]}")
+        elif r3.stdout.strip():
+            problems.append(f"hook injected context for {label}: {r3.stdout.strip()[:80]!r}")
+
     # Every rule needs a command that must reach it. A nonempty pattern is not evidence: a
     # trigger of `(?!)` can never match, and a rule suppressed by the special-case logic in
     # matches() never reaches the caller either — both leave the rule inert while this file

package/claude/skills/repo-charter/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: repo-charter
+description: Write or overhaul a repository's AGENTS.md (with CLAUDE.md as a one-line shim) for the agents that will work in it. Use when a repo has no agent instructions, when its AGENTS.md is a preamble that names nothing, or when the user asks to set a repo up for coding agents. Reads invariants and traps out of the code rather than pasting a template.
+---
+
+# Repo charter
+
+A repository's AGENTS.md is the repo's own layer of agent instruction — what a global
+corpus cannot know because it is true only here. This skill produces that layer for a real
+repository, and it produces it *from the repository*: the substantive half is reading the
+invariants, the gates and the traps out of the code, and no template can do that part.
+
+The output belongs to the repository — its team, its contributors, its git history. Nothing
+this skill writes carries a marker, a version stamp, or copyable boilerplate, because nothing
+outside that repo will ever update it.
+
+## 0. First decide whether the file is warranted
+
+Many repositories correctly have no instruction file. Content and documentation repos need
+at most a few lines of orientation; a personal repo rarely needs governance; and a one-line
+fix in someone else's project is not the moment to charter it — the file is theirs to create.
+Write one when agents will do repeated, non-trivial work here and the repo carries rules a
+newcomer would otherwise learn by breaking something. If the answer is no, say so and stop;
+an empty file with a heading is worse than none.
+
+Read enough to answer honestly before deciding: the top-level tree, the package or build
+manifest, hook and CI configuration, and the last fifty commit subjects. Steps 0 and 1 are
+provisional; step 3 may revise them. **Draft from the code first** — if the repo already has
+an instruction file, open it only at step 8, because reading it earlier anchors your
+structure to it and the comparison stops being evidence.
+
+## 1. Purpose type, then category mix
+
+Decide what the repo is *for* before writing a line. The type fixes which categories must be
+thick; everything else stays thin or absent.
+
+| Purpose type | Categories that must be thick |
+| --- | --- |
+| Library / framework that accepts outside contribution | contribution protocol, completion gates, hard boundaries |
+| Application / product | project invariants, pitfall warnings, co-change duties |
+| CLI / single-author tool | repo orientation, project invariants, task procedure |
+| Monorepo / platform | context routing, task procedure |
+| Corpus / payload the repo publishes elsewhere (the code is delivery, the content is the product) | hard boundaries, co-change duties, completion gates |
+| Content / docs | repo orientation only, minimal |
+
+A repo may take two rows; take the union and note which row explains each thick category.
+
+The category vocabulary, in one line each: **repo orientation** (what lives where, so nobody
+has to search), **command recipes** (the exact commands), **house form** (the shape of
+outputs), **project invariants** (semantic contracts the code must keep), **context routing**
+(when to open which document, skill or tool), **task procedure** (the order for a kind of
+work), **pitfall warnings** (traps and environment quirks that cause misdiagnosis),
+**contribution protocol** (how a change gets accepted), **completion gates** (what must pass
+before "done"), **co-change duties** (change X, then also Y), **hard boundaries** (never),
+**human authority** (where to stop and hand over), **agent conduct** (how the agent itself
+operates). Across thousands of real files, human authority is the rarest of these — people
+write prohibitions but not escalation paths — so it is asked for explicitly in step 5.
+
+## 2. AGENTS.md is the body; CLAUDE.md is a shim
+
+Write one file: `AGENTS.md`, which Codex reads natively. Where Claude Code is used, add a
+`CLAUDE.md` whose only content is an import of `AGENTS.md` (`@AGENTS.md`), plus at most a
+sentence saying why the shim exists — and if that sentence claims something about a tool's
+behaviour, date it or drop it, because such claims rot into lies. Two bodies drift; one body
+and one pointer cannot. A file's name does not tell an agent which tool it is for — content
+that opens "guidance for tool X" is copied between tools verbatim, so leave the tool's name
+out of the body; the shim sentence is the one exception.
+
+## 3. Read the invariants and traps out of the code
+
+This is the work, and it is done by reading, not by asking the repo's owner to dictate.
+For an existing repo, collect at least these before drafting:
+
+- **What runs before a commit and what it enforces.** Hooks, CI configuration, gate scripts,
+  lint and test entrypoints. For each rule you state, name the file that enforces it, and
+  mark the rules nothing enforces as convention — a reader must be able to tell a gate from
+  a wish.
+- **What a green check does and does not prove.** A test suite that skips a leg, a check that
+  runs against a fixture rather than the real path, a scan whose subject set can be empty.
+  These belong in the file because they are exactly what a newcomer misreads.
+- **Generated paths.** Anything produced from another file must be named as such, with the
+  generator and the command that regenerates it; hand-editing a projection is the most
+  common silent defect.
+- **Where authority lives.** For each value that appears in more than one place, which copy
+  is the source and how the others follow it.
+- **What the history paid for.** Read the recent log and any postmortems or dated design
+  notes for mistakes that cost a real attempt — the deploy that took the wrong tree, the
+  command whose exit status lied, the flag that was rejected rather than implemented. Each
+  becomes a present-tense warning that names the symptom.
+- **Runtime shape that a reader cannot infer.** Which entrypoint is real, which directory
+  is payload versus tooling, which environment the tests assume.
+
+State each finding as a rule about the present, in one or two sentences, and cite the code
+by **file and identifier** — function, constant, leg name — never by line number: a symbol
+survives an edit and is greppable, a line number is wrong within a day. A rule that cannot
+cite its enforcer or its evidence is a candidate for deletion. Stop collecting when a new
+source stops producing rules you would keep — usually after the hooks, the gate entrypoints,
+the packaging manifest, the installer, and the recent commit subjects.
+
+## 4. Choose the sections from the findings, not from a template
+
+Group what step 3 produced under headings that match the repo's thick categories from
+step 1. Order by what an agent hits first: orientation and the pre-commit contract before
+style; traps near the commands that trigger them. The file is re-sent to every session, so it
+is a token budget: if the draft exceeds roughly 2,000 words, the excess is a guide — move the
+longest section behind a pointer and keep the one rule that says when to read it.
+
+## 5. Ask for human authority explicitly
+
+Ask the user, in outcome terms, which decisions an agent must bring to a person rather than
+settle: releases and publishes, schema or data migrations, anything touching credentials or
+production, deleting or rewriting history, spending money, changing a public contract.
+Write the answer as a short list of *stop points* with what to bring (evidence, options),
+not as a prohibition. If the user has no answer yet, record the question as open in the
+file rather than inventing a policy; if the run is unattended, draft the stop points as a
+proposal marked as requiring confirmation, and never infer one the code does not evidence
+as irreversible or outward-facing.
+
+## 6. Refuse the zero-content preamble
+
+Delete any sentence that could open any repository's file: "this file provides guidance to
+agents working in this repository", "follow best practices", "write clean code", restated
+general engineering rules the agent already carries. Read the draft once more asking of each
+line, "what would an agent do differently after reading this?" — a line with no answer goes.
+
+## 7. Directory-scoped files only for the monorepo or platform type
+
+A `CLAUDE.md` or `AGENTS.md` placed inside a subdirectory is loaded when a file beside it is
+touched, which makes it survive the loss of early session context. That is valuable when
+subtrees have genuinely different rules — the monorepo case — and noise everywhere else,
+where it splits one file's authority in two. Default to one root file.
+
+## 8. Before handing it over
+
+Self-review against three constraints, and fix rather than annotate:
+
+- Nothing in the output is boilerplate meant to be pasted elsewhere, and nothing points back
+  to this skill, to a version, or to any tool that would "update it later" — no such
+  mechanism exists, and a stamp that promises one is a lie the repo will carry.
+- Every rule names the code that enforces it, or is marked as convention.
+- The file states current behaviour only. Change narratives, rejected alternatives and
+  handoff logs are pointed to where they live (design notes, the log), not repeated here. A
+  live process that is followed but not enforced is current, not history — it belongs in the
+  file or behind a pointer, and length decides which.
+
+Now read the repo's existing instruction file, if any, and verify each of its claims against
+the code — a stale sentence beside current code reads as fact. Show the user your skeleton
+beside it and name the divergences: a large gap means either the draft or the existing file
+is wrong, and finding out which is the point of the exercise.