agent-bios 0.9.7 → 0.9.9

package/DEPENDENCIES.md

@@ -8,12 +8,12 @@ Korean: [`ko/DEPENDENCIES.md`](ko/DEPENDENCIES.md). Dates = verification time; u
 
 | Tool | Required by | Required capability | Verified |
 | --- | --- | --- | --- |
-| `codex` (codex-cli) | `scripts/codex-run.sh`, `scripts/codex-helm.sh`, `scripts/agent-launch.py`; guide "Codex direct-drive" + "Session relocation" bindings | existing `codex exec` contract plus `agents.<name>.description/config_file` config projection; final output on stdout and progress on stderr; honors `CODEX_HOME`; `codex resume` cwd-filtered | 0.144.1 · 2026-07-13 |
-| `bash` | `scripts/*.sh` | POSIX + arrays; runs on macOS system bash | 3.2.57 · 2026-07 |
-| `python3` | `scripts/session-cost.py`, `scripts/agent-launch.py` | stdlib for every direct / non-TTY / numbered path; Python 3.11+ (`tomllib`). The interactive preflight additionally needs `textual` (next row) | 3.14.5 · 2026-07-13 |
-| `textual` (managed venv) | `scripts/agent-launch.py` interactive preflight; provisioned by `scripts/provision-venv.sh` | Textual TUI framework in `~/.local/share/agent-launch/venv` (override `AGENT_LAUNCH_VENV`); the launcher re-execs into it on the interactive TTY path only. Absent/broken venv, non-TTY, or `TERM` `dumb`/unset falls back to numbered prompts and never blocks | 8.2.8 · py 3.14.5 · 2026-07-13 |
-| `jsonschema` (system python) | `scripts/check-learning.py` (learning record gate; chained from `scripts/check-parity.sh`) | JSON Schema Draft 2020-12 validator executing `config/learning.schema.json` as the SSOT | 4.26.0 · 2026-07-20 |
-| `zsh` | `shell/agent-launch.zsh` | functions, TTY tests, argument-preserving dispatch | 5.9 · 2026-07-13 |
+| `codex` (codex-cli) | `wrappers/codex-run.sh`, `wrappers/codex-helm.sh`, `launch/agent-launch.py`; guide "Codex direct-drive" + "Session relocation" bindings | existing `codex exec` contract plus `agents.<name>.description/config_file` config projection; final output on stdout and progress on stderr; honors `CODEX_HOME`; `codex resume` cwd-filtered | 0.144.1 · 2026-07-13 |
+| `bash` | `install.sh`, `*/*.sh` | POSIX + arrays; runs on macOS system bash | 3.2.57 · 2026-07 |
+| `python3` | `session-cost.py`, `launch/agent-launch.py` | stdlib for every direct / non-TTY / numbered path; Python 3.11+ (`tomllib`). The interactive preflight additionally needs `textual` (next row) | 3.14.5 · 2026-07-13 |
+| `textual` (managed venv) | `launch/agent-launch.py` interactive preflight; provisioned by `launch/provision-venv.sh` | Textual TUI framework in `~/.local/share/agent-launch/venv` (override `AGENT_LAUNCH_VENV`); the launcher re-execs into it on the interactive TTY path only. Absent/broken venv, non-TTY, or `TERM` `dumb`/unset falls back to numbered prompts and never blocks | 8.2.8 · py 3.14.5 · 2026-07-13 |
+| `jsonschema` (system python) | `learn/check-learning.py` (learning record gate; chained from `gates/check-parity.sh`) | JSON Schema Draft 2020-12 validator executing `learn/learning.schema.json` as the SSOT | 4.26.0 · 2026-07-20 |
+| `zsh` | `launch/agent-launch.zsh` | functions, TTY tests, argument-preserving dispatch | 5.9 · 2026-07-13 |
 | `git` | scripts, workflow (`origin/<base>..HEAD`, worktrees) | modern git; worktree support | 2.50.1 · 2026-07 |
 | coreutils (`mktemp`, `cp`) | `codex-run.sh` hermetic home; `codex-helm.sh` managed home | BSD or GNU | 2026-07 |
 
@@ -21,7 +21,7 @@ Korean: [`ko/DEPENDENCIES.md`](ko/DEPENDENCIES.md). Dates = verification time; u
 
 | CLI | Role | Required capability | Version owner |
 | --- | --- | --- | --- |
-| Claude Code | primary host; loads `CLAUDE.md` + `guides/`; `agent-launch` backend | `--model`; effort `low/medium/high/xhigh/max`; `--agents` JSON with per-agent `model`/`effort`; `--append-system-prompt`; `--mcp-config`; permission modes `acceptEdits/auto/bypassPermissions/manual/dontAsk/plan` | Environment Binding (v2.1.207) |
+| Claude Code | primary host; loads `CLAUDE.md` + `guides/`; `agent-launch` backend | `--model`; effort `low/medium/high/xhigh/max`; `--agents` JSON with per-agent `model`/`effort`; `--append-system-prompt`; `--mcp-config`; permission modes `acceptEdits/auto/bypassPermissions/manual/dontAsk/plan` | Environment Binding (v2.1.220 — the version whose behaviour is verified here) |
 | Codex CLI | mirror host; loads `AGENTS.md` + `guides/`; worker/reviewer runtime | see codex row above | Environment Binding + this file |
 
 ## LLM models & providers — owned by `Environment Binding`
@@ -33,19 +33,19 @@ Concrete role-slot→model bindings live only in each guide's `Environment Bindi
 
 ## Deployed Codex assets
 
-- **Codex custom agents** (`codex/agents/*.toml`) — installed role templates for `frontier`, `workhorse`, `sweep`, and `reviewer`; optional at runtime, but part of the Restore contract and activated by `scripts/codex-helm.sh` when Codex subagent fan-out is explicitly authorized.
+- **Codex custom agents** (`codex/agents/*.toml`) — installed role templates for `frontier`, `workhorse`, `sweep`, and `reviewer`; optional at runtime, but part of the Restore contract and activated by `wrappers/codex-helm.sh` when Codex subagent fan-out is explicitly authorized.
 
 ## Referenced / optional — not required by the core repo
 
-- **ultracode-for-codex** (0.5.0) — the `$ultracode-for-codex` Codex skill / CLI (Codex-backed, gpt). In cross-family review it is the **ultracode** route a **Claude** main dispatches (gpt review); a Codex main instead uses `claude --effort ultracode -p` (Claude Code's headless `/workflows` ultracode mode). Required only when the ultracode/hybrid route is selected and the main is Claude.
-- **Cross-family review reviewers** — with `review_family=cross` (default), each main routes review to the opposite family. A Claude main dispatches gpt review via `$CODEX_HOME/bin/codex-run --profile hermetic` (and `codex-helm --mode review` for hybrid fan-out); a Codex main dispatches Claude review via the `claude` CLI (`claude -p --permission-mode plan` for native/onto, and `claude --effort ultracode -p` for the ultracode workflow-orchestration route — the `ultracode` effort value is accepted by claude 2.1.210 though not listed in `--help`). The reviewer command, resolved path, and opposite-family tier bindings are named in the launch contract; an absent or unauthenticated route degrades to same-family native (PROPOSED). `review_family=same` restores same-family review.
-- **codex-plugin-cc** (1.0.6; re-evaluated 2026-07-16) — spawns `codex app-server` with inherited env and no `--ignore-user-config`/`--profile`, so every run reads the real `~/.codex` (config.toml, auth, its MCP servers); it has no per-invocation hermetic reach, which is what makes it unfit as a **review** route: the reviewer would inherit the same config and AGENTS.md as the main, undercutting the independent lens `review_family=cross` exists to provide. The model *is* selectable (`--model`/`--effort`); what is dated is the bundled `gpt-5-4-prompting` skill, so passing a current model does not resolve it. **Not adopted**; `scripts/codex-run.sh` is preferred for controlled reach. It does not touch Claude Code's `/code-review` (no `code-review.md`; it adds namespaced `/codex:*`), so it never made that route cross-family. Capability we lack and may still want independently: its opt-in `Stop` hook review gate.
+- **ultracode-for-codex** (0.5.0) — the `$ultracode-for-codex` Codex skill / CLI (Codex-backed, gpt). In cross-family review it is the **ultracode** route a **Claude** main dispatches (gpt review); a Codex main instead uses the **ultracode** capability, which is the `claude` backend itself run headless with the keyword `ultracode` in the prompt — that keyword is what opens the Workflow tool for the turn (`workflowKeywordTriggerEnabled`, default true, read in the installed 2.1.220 bundle). Required only when the ultracode/hybrid route is selected and the main is Claude.
+- **Cross-family review reviewers** — with `review_family=cross` (default), each main routes review to the opposite family. A Claude main dispatches gpt review via `$CODEX_HOME/bin/codex-run --profile hermetic` (and `codex-helm --mode review` for hybrid fan-out); a Codex main dispatches Claude review via the `claude` CLI (`claude -p --permission-mode plan` for native/onto, and, for the workflow-orchestration route, the same `claude` CLI headless with the keyword `ultracode` in the prompt — the keyword trigger is what the injected contract names, so this is the mechanism to follow). The reviewer command, resolved path, and opposite-family tier bindings are named in the launch contract; an absent or unauthenticated route degrades to same-family native (PROPOSED). `review_family=same` restores same-family review.
+- **codex-plugin-cc** (1.0.6; re-evaluated 2026-07-16) — spawns `codex app-server` with inherited env and no `--ignore-user-config`/`--profile`, so every run reads the real `~/.codex` (config.toml, auth, its MCP servers); it has no per-invocation hermetic reach, which is what makes it unfit as a **review** route: the reviewer would inherit the same config and AGENTS.md as the main, undercutting the independent lens `review_family=cross` exists to provide. The model *is* selectable (`--model`/`--effort`); what is dated is the bundled `gpt-5-4-prompting` skill, so passing a current model does not resolve it. **Not adopted**; `wrappers/codex-run.sh` is preferred for controlled reach. It does not touch Claude Code's `/code-review` (no `code-review.md`; it adds namespaced `/codex:*`), so it never made that route cross-family. Capability we lack and may still want independently: its opt-in `Stop` hook review gate.
 - **MCP servers** (onto, clickhouse, node_repl, …) — environment-specific; referenced by Environment Binding (VERIFIER-A; coding-staged guide's structured multi-lens review slot), not a core dependency. For cross-family review, agent-launch mounts `onto` and instructs the main to call `onto_review` with `llmOverride={provider,model}` (from `[hosts.*].onto_review`, an onto review-role registered pair) so onto runs the opposite family; onto's own model seats are not launcher-controllable, so the family is set per call.
 - **spreadsheet-processing** (skill) — referenced by the global spreadsheet rule; present in the author's Claude Code and Codex environments. If absent, the rule's inline fallback (plain tools/code + real Excel-engine validation) applies.
 
 ## Untracked — dependencies, but excluded by design
 
-Host `config.toml` and `settings.json` — machine-specific trust lists, hook paths, and MCP secrets. The tracked `config/agent-launch.toml` contains launch bindings but no secrets. See README Scope.
+Host `config.toml` and `settings.json` — machine-specific trust lists, hook paths, and MCP secrets. The tracked `launch/agent-launch.toml` contains launch bindings but no secrets. See README Scope.
 
 ## Re-verify
 
@@ -61,13 +61,13 @@ printf '%s\n' "$codex_help" | grep -Eq '(^|[[:space:]])-p([,[:space:]]|$)' || {
 printf '%s\n' "$codex_help" | grep -Eq '(^|[[:space:]])-s([,[:space:]]|$)' || { echo "missing codex flag: -s"; exit 1; }
 claude --version; claude --help | grep -E -- '--model|--effort|--agents|--append-system-prompt|--mcp-config'
 bash --version | head -1; zsh --version; python3 --version; git --version
-AGENT_LAUNCH_VENV="${AGENT_LAUNCH_VENV:-$HOME/.local/share/agent-launch/venv}" bash scripts/provision-venv.sh
+AGENT_LAUNCH_VENV="${AGENT_LAUNCH_VENV:-$HOME/.local/share/agent-launch/venv}" bash launch/provision-venv.sh
 "${AGENT_LAUNCH_VENV:-$HOME/.local/share/agent-launch/venv}/bin/python" -c 'import textual, sys; print("textual", textual.__version__, "py", sys.version.split()[0])'
-bash -n scripts/codex-run.sh scripts/codex-helm.sh scripts/check-parity.sh scripts/check-prompting-targets.sh scripts/provision-venv.sh scripts/install.sh
-zsh -n shell/agent-launch.zsh
-python3 -c 'compile(open("scripts/agent-launch.py").read(), "scripts/agent-launch.py", "exec")'
-./scripts/check-parity.sh
-./scripts/check-prompting-targets.sh
+bash -n wrappers/codex-run.sh wrappers/codex-helm.sh gates/check-parity.sh launch/check-prompting-targets.sh launch/provision-venv.sh install.sh
+zsh -n launch/agent-launch.zsh
+python3 -c 'compile(open("launch/agent-launch.py").read(), "launch/agent-launch.py", "exec")'
+./gates/check-parity.sh
+./launch/check-prompting-targets.sh
 python3 - <<'PY'
 import os, pathlib, tomllib
 roots = [pathlib.Path("codex/agents"), pathlib.Path(os.environ.get("CODEX_HOME", pathlib.Path.home() / ".codex")) / "agents"]
@@ -79,7 +79,7 @@ for root in roots:
         tomllib.loads(path.read_text())
     print(f"agent TOML ok: {root}")
 PY
-scripts/codex-helm.sh --dry-run --mode review "probe"
+wrappers/codex-helm.sh --dry-run --mode review "probe"
 ```
 
 ## Ownership

package/README.md

@@ -2,6 +2,10 @@
 
 Single source of truth for the global instructions and scoped guides that drive multiple LLM CLI agents (Claude Code, Codex CLI) under one working discipline. Edit once; it applies to every agent in every environment.
 
+A deployable instruction corpus for coding agents, plus the CLI that
+installs, verifies, and evolves it. The npm package ships the corpus; `install.sh` is both the
+`agent-bios` CLI entry and the deployer.
+
 Korean reference: [`ko/`](ko/) mirrors every doc below — reference only, never installed or loaded.
 
 ## Model
@@ -14,9 +18,13 @@ Two layers:
 ## Principles
 
 - **Rule bodies never name concrete models or tools** — only role slots and tiers. Bindings live in each guide's `Environment Binding` (dated; expire ~8 weeks or on a newer model). New model → update that row + date; leave rules alone. Declared exceptions: sections whose subject is a concrete tool surface (the cli guide's Codex direct-drive section) and optional-capability names inventoried in `DEPENDENCIES.md` (e.g. the `spreadsheet-processing` skill) — the Adopting checklist below covers swapping both.
-- **The two CLIs' files are mirrors** — differing only in title and config-home variable (`$CLAUDE_CONFIG_DIR` ↔ `$CODEX_HOME`), plus one declared Codex-only standing-dispatch authorization required by Codex's trigger contract. `scripts/check-parity.sh` enforces that exact exception, mirror parity, pointer resolvability, frontmatter, shared anchor phrases on the global↔guide restatement pairs that remain, and Codex role-binding / wrapper-default projections. Parity enforces content synchronization only; it does not guarantee both harnesses respond to the same wording with the same strength.
+- **The Codex tree is generated, not mirrored by hand** — `gates/emit-mirrors.py` projects `claude/` → `codex/` and `ko/claude/` → `ko/codex/`, differing only in title and config-home variable (`$CLAUDE_CONFIG_DIR` ↔ `$CODEX_HOME`), plus one declared Codex-only standing-dispatch authorization required by Codex's trigger contract, inserted at a pinned position. It owns the projection rule; `gates/check-parity.sh` runs its `--check` and adds pointer resolvability, frontmatter, shared anchor phrases on the global↔guide restatement pairs that remain, and Codex role-binding / wrapper-default projections. Parity enforces content synchronization only; it does not guarantee both harnesses respond to the same wording with the same strength.
 - **The global is a per-session token budget** — it is re-sent every session and to every subagent, and each added bullet dilutes every other rule. A new global bullet must name the bullet it displaces (or why none does); procedures, tables, numbers, and worked examples belong in guides.
-- **`Evidence Base` (per guide) is the single owner of numbers.** Measure with `scripts/session-cost.py`.
+- **Deploying is not loading** — file presence cannot detect a declined import approval or a broken entry import line, so `onboard` ends with an activation canary and `verify` checks the entry import line. A corpus that landed but is not read has changed nothing.
+- **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`.
 - **English is canonical and installed; Korean (`ko/`) is reference only.** The harness loads only fixed-name English files; the installer deploys English only.
 
 ## Layout
@@ -27,8 +35,20 @@ Two layers:
 | `claude/guides/*.md`, `codex/guides/*.md` | scoped guides (en) — installed |
 | `codex/agents/*.toml` | Codex custom subagent role templates — installed |
 | `ko/**` | Korean mirror of every doc above + this README + DEPENDENCIES (reference only) |
-| `config/agent-launch.toml`, `scripts/agent-launch.py`, `shell/agent-launch.zsh` | shared Codex/Claude launch profile, preflight TUI, and zero-argument shell interception |
-| `scripts/` | parity/cost tooling plus internal Codex wrappers deployed to `$CODEX_HOME/bin/` |
+| `launch/` | launch profile, preflight TUI, zero-argument shell interception, the managed Textual venv, and the prompting-target check that guards the profile's model bindings |
+| `compose/` | corpus classification and per-selection assembly — domain manifest and its gate, assembler, package identity, hook registration, activation canary, deployed-corpus state |
+| `learn/` | the collection loop — capture, record schema and its validator, curation intake, promotion manifest, redistribution, and the secret-redaction floor |
+| `session-distill/` | the heavy curator pipeline that mines many sessions into corpus-grade items |
+| `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 |
+| `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` |
+| `SURFACES.md` | where knowledge and tools reach a model, and what each place admits — every entry names the code that realizes it |
+| `FINDINGS.md` | open implementation defects, live; closing one deletes its entry |
+| `design/`, `benchmarks/` | design records and the instruction-behavior benchmark |
 | `DEPENDENCIES.md` | external tools / host CLIs / model providers + verified versions |
 
 `config.toml` and `settings.json` are machine-specific (trust lists, hook paths, secrets) and intentionally untracked.
@@ -46,10 +66,9 @@ Two layers:
 
 ## Edit workflow
 
-1. Edit the English canonical (`claude/`). Regenerate the Codex mirror, then preserve the single `Codex-only standing authorization` bullet under `Multi-Model Workflow`:
-   `sed -e '1s/# CLAUDE.md/# AGENTS.md/' -e 's|${CLAUDE_CONFIG_DIR:-$HOME/.claude}|${CODEX_HOME:-$HOME/.codex}|g' claude/CLAUDE.md > codex/AGENTS.md`, and copy guides to `codex/guides/`.
-2. Update the Korean mirror under `ko/` the same way (globals under `ko/claude`→`ko/codex`, guides `ko/claude/guides`→`ko/codex/guides`, config-home swap for the codex side).
-3. `./scripts/check-parity.sh` must pass.
+1. Edit the English canonical (`claude/`), and the Korean canonical (`ko/claude/`) when the change is user-facing.
+2. `python3 gates/emit-mirrors.py` — regenerates `codex/` and `ko/codex/` from those two canonicals. Never hand-edit the Codex side: it is a generated projection, and `--check` (which the parity gate runs) fails on any file that is not exactly what the generator emits.
+3. `./gates/check-parity.sh` must pass.
 4. Commit, then deploy: `agent-bios install` (or `agent-bios update` from a clone).
 
 ## Install (deploy)
@@ -59,16 +78,16 @@ The `agent-bios` CLI deploys this SSOT into your environment by copy — idempot
 ```bash
 npm install -g agent-bios
 agent-bios install     # deploy, back up replaced files, then verify
-agent-bios onboard     # pick domain packages, packaged install, activation canary
+agent-bios onboard     # pick domain packages, install, activation canary
 agent-bios verify      # re-check the deployed state matches the source
 agent-bios status      # show what is installed and where
 agent-bios update      # git pull + reinstall (clone), or print the npm update line
 agent-bios uninstall   # remove deployed files and the zsh hook
 ```
 
-From a git clone, run `./scripts/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. The published npm package ships only the deploy set (never `settings.json`, `config.toml`, `ko/`, or `benchmarks/`).
+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 (`scripts/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, onto, and ultracode — 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`, onto via an `llmOverride` to the configured openai seat, ultracode via the `$ultracode-for-codex` Codex skill); a Codex main dispatches Anthropic/Claude review (native via `claude -p --permission-mode plan`, onto via an `llmOverride` to the anthropic seat, ultracode via `claude --effort ultracode -p` — Claude Code's headless `/workflows` ultracode mode, verified accepted on claude 2.1.210). The concrete reviewer command, resolved absolute path, `llmOverride`, 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. 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, onto, and ultracode — 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`, onto via an `llmOverride` to the configured openai seat, ultracode via the `$ultracode-for-codex` Codex skill); a Codex main dispatches Anthropic/Claude review (native via `claude -p --permission-mode plan`, onto via an `llmOverride` to the anthropic seat, ultracode 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, `llmOverride`, 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.
 
 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.
 
@@ -76,6 +95,10 @@ Direct `agent-launch` calls still require a valid profile to resolve the backend
 
 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.
 
+`claude-run` is the Claude-side adapter, deployed to `$CLAUDE_DIR/bin`, and it takes `--model` and `--effort` to pin the seat. Omitting either warns and dispatches anyway, matching `codex-run`: refusing outright turned "the review ran unpinned" into "the review did not run", which is the worse of the two. The honest signal is downstream instead — an unpinned dispatch can name no seat, so it emits no receipt and the method adjudicates to UNKNOWN rather than to a clean pass. Its default denies the mutating tools, which is not the OS-level sandbox its Codex twin gets — do not read the two defaults as equivalent guarantees.
+
+**Review receipts.** A launch reports what it *projected*, because at launch no review has run — so a clean verdict without a receipt is PROPOSED, never ACHIEVED. Given `REVIEW_RECEIPT_DIR`, both adapters record what they observed of the dispatch they just performed: exit status, a hash of the packet fed in, a hash of the bytes returned, and the seat actually sent. Unset, they behave exactly as they would otherwise and write nothing. `agent-launch --fold-receipts DIR PACKET MAIN_DISPATCH_ID` folds a run into a `ReviewReceipts/v1` bundle — several passes of one method become the one record it is judged on — and `agent-launch --verify-receipts PLAN BUNDLE` adjudicates it, exiting non-zero unless every selected method verified. Adapting another tool needs no change here: call `agent-launch --emit-receipt` from your adapter and prove it conforms with `agent-launch --check-adapter SEAT -- CMD`, which is adjudicated by the same code that credits a real review. A receipt is still written by whoever ran the review, so this buys drift rather than honesty: what it stops is a reviewer that quietly never ran, returned nothing, or exited non-zero reading as a clean pass.
+
 `agent-bios verify` runs the post-deploy gate (also run at the end of `install`): every `guides/*.md` referenced by the deployed global exists in that environment's `guides/`; required agent files `frontier.toml`, `workhorse.toml`, `sweep.toml`, and `reviewer.toml` exist under `$CODEX_DIR/agents/` and parse as TOML; `frontier.toml` deliberately omits `model_reasoning_effort` for native surfaces that accept per-spawn effort; each required `codex exec --help` flag in `DEPENDENCIES.md` is present; and `$CODEX_DIR/bin/codex-helm --dry-run --mode review "probe"` succeeds as a credential-free assembly check (not a live Codex call). `install` overwrites each guide's `Environment Binding`; keep per-environment binding edits in the repo copy or an untracked file.
 
 ## Adopting elsewhere

package/claude/CLAUDE.md

@@ -94,7 +94,7 @@
 - Use static checks broadly: typecheck, lint, build, format, schema/config validation, graph validation, workbook structure checks, import boundaries, and security checks when available.
 - Add the narrowest reliable runtime or semantic test that proves the changed behavior, meaning, or contract.
 - Pick each domain's verification mix (code, ontology, config/data, spreadsheets, docs) from the Verification Menus in the coding-staged-workflow guide.
-- Let the LLM derive scenarios from the diff, user impact, concept impact, and failure modes; let tools/code execute and verify them.
+- Let the LLM derive scenarios from the diff, user impact, concept impact, and failure modes; let tools/code execute and verify them. Where an artifact already defines the case space — a config, a schema, a route table — enumerate the cases from it rather than from judgment, and record real output as the expectation instead of typing one: a hand-listed set of cases silently stops covering as the artifact grows past it.
 - Keep E2E stable with deterministic data, resilient selectors, isolated external dependencies, and explicit waits.
 - Report the checks run, results, and any unverified risk before calling the work done.
 - Trust a green check only when it traversed the actual changed code through the real dispatch and real calls (not a mock, dry-run, or bypass), and remember that "it ran" is not "quality met" — a fallback, floor, or mock run is not done; treat a zero-findings verdict as suspect until you confirm the harness ran rather than silently crashed, and make PASS mean concrete assertions on real output from the real path.
@@ -122,6 +122,7 @@
 - For work spanning multiple models or CLI agents, context resets and handoffs, unattended LLM batches (including orchestrated subagent fleets), or parallel worktree branches, read and use `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/cli-multi-model-workflow.md` as a scoped extension of this section.
 - For composing a prompt, packet, or tool description aimed at a specific model family — including cross-family review dispatch, porting a prompt written for an older model, or choosing a reasoning-effort level for a model family — read and use `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/gpt-prompting.md` for gpt-family targets and `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/claude-prompting.md` for claude-family targets as scoped extensions of this section.
 - Allocate models by difficulty × blast radius, not phase name; when implementation ran on a cheaper tier, compensate by raising reviewer effort or adding a reviewer kind — never economize on implementation and verification at once.
+- Judge a review by how much independence it actually bought, per reviewer and in this order: different provider, then different model, then strictly higher effort, then the two-perspective floor. A lower effort earns nothing — cheaper is not another perspective. Isolation is a gate rather than a rung: a reviewer you cannot show ran in a fresh context is not a weak review but no review, so exclude it instead of grading it low. Several ready methods are coverage, not proof the perspectives differed; and a clean verdict is PROPOSED until a receipt evidences a fresh dispatch of the declared packet on the exact seat, since a model echo is not evidence.
 - When the user asks for design AND two or more providers are reachable at frontier tier, run dual-provider frontier design drafts: two independent drafts from the same blind packet, one per provider, compared and synthesized into the working draft. The consent gate is about metered spend, not the fan-out: a provider reached via an OAuth session (subscription-covered, no marginal cost) proceeds WITHOUT asking — if a non-main-context OAuth frontier provider exists, just run the dual-provider design; do not ask. Explicit per-request approval (never standing) is required ONLY before dispatching to a provider reachable solely via a metered API key, and it approves that spend. If withholding un-approved API spend leaves fewer than two providers, run single-provider rather than blocking the design on approval. Inject the corpus design principles (concept economy, LLM/capability boundary, staged workflow) into every dispatched design packet — an external model does not load this corpus.
 - Never retry-storm a live rate limit: give unattended batches you author a code-level circuit breaker with per-item completion tracking (thresholds, backoff, and dead-letter rules in the guide); for third-party dispatchers, confirm equivalent protection exists or attend the run.
 - On any resumed, cleared, or relocated session, re-verify where you are (pwd; in a repo, branch and HEAD) before acting on prior-session assumptions — against the pinned handoff state when one exists.

package/claude/guides/claude-prompting.md

@@ -137,5 +137,5 @@ pick the path.
 Derived from the vendor's published guidance for the `targets` models above.
 When a `targets` model changes, re-derive this guide from current vendor
 guidance rather than editing around the old rules — prompting guidance is
-version-bound. `scripts/check-prompting-targets.sh` fails when the launch config
+version-bound. `launch/check-prompting-targets.sh` fails when the launch config
 binds a model this guide does not list.

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

@@ -108,6 +108,23 @@ Instruction/config reach is per invocation. A rule in AGENTS.md cannot bind a he
 - A silent/dead lens is incomplete, never clean. Confirm liveness from usage/error/report evidence; rerun, swap provider, or report PROPOSED.
 - Kind labels do not guarantee distinct backends: wrappers and rate-limit fallbacks can silently route two "different-kind" verifiers to the same model/provider. Before trusting diversity on a high-stakes verdict, confirm each verifier's actual backing model from live process or usage evidence; on collapse, treat the pair as one kind and label PROPOSED.
 
+### Review Independence
+
+How much independence a review actually bought, as an ordinal grade per reviewer rather than a global cross/same flag. Given the main seat `M` and the reviewer seat `R`:
+
+| Grade | When |
+|---|---|
+| `provider_difference` | `R.provider != M.provider` |
+| `model_difference` | same provider, `R.model != M.model` |
+| `higher_effort` | same provider and model, `R.effort` strictly above `M.effort` |
+| `perspective_floor` | otherwise — still a real review |
+
+- Only upward counts. A different-but-**lower** effort earns nothing and lands on the floor: cheaper is not another perspective.
+- **Isolation is a gate, not a rung.** A reviewer that cannot be shown to run in a fresh context is excluded entirely (`NOT_REVIEW`), never graded low — an in-context "review" is the failure this ladder exists to make visible, so it must not appear as a weak pass. Isolation is realised per mechanism: a fresh read-only subprocess, a hermetic profile, a stdio tool call in a fresh session, a headless host workflow, or a stateless API call. If none of these can deliver the required seat, the review did not happen.
+- The floor still requires **at least two distinct perspectives**; one pass on the main's own seat is self-review with extra steps.
+- Multiple ready methods are **coverage, not diversity**. Distinct labels do not prove the perspectives differed.
+- **Achieved is not available.** What can be projected before a review runs is `projected`; a clean verdict without a receipt evidencing a fresh dispatch, the declared packet, a non-empty result and the exact seat is `PROPOSED`, never ACHIEVED. A model echo is not a receipt.
+
 ## Dual-Provider Design Drafts
 
 - Trigger: the task is design (the staged-workflow guide's design stages) AND two or more providers are reachable at frontier tier. Reachability via an OAuth session is subscription-covered — no marginal spend, so no approval and no question: if a non-main-context OAuth frontier provider exists, proceed with the dual-provider design directly. The consent gate applies ONLY to a provider reachable solely via a metered API key: dispatching to it needs the user's explicit per-request approval of that spend (per-request, not standing — an old approval does not carry to the next design). If the only way to reach a second provider is un-approved metered API spend, stay single-provider rather than blocking the design.
@@ -154,7 +171,7 @@ Write for the next agent and re-verification, not narrative. Required content:
 
 ## Environment Binding (edit per environment)
 
-This is the human-readable projection of concrete models/tools; `config/agent-launch.toml` is the machine launch authority and parity checks keep them aligned. Re-probe when the binding is older than ~8 weeks or a newer observable model/tool changes the surface. `agent-bios install` overwrites deployed bindings, so edit the repo copy.
+This is the human-readable projection of concrete models/tools; `launch/agent-launch.toml` is the machine launch authority and parity checks keep them aligned. Re-probe when the binding is older than ~8 weeks or a newer observable model/tool changes the surface. `agent-bios install` overwrites deployed bindings, so edit the repo copy.
 
 Binding (2026-07-25):
 
@@ -178,6 +195,7 @@ Codex direct-drive (verified 0.144.1, 2026-07-12):
 - HELM is instructed to dispatch tiers through internal `codex-run`, which pins model/effort/sandbox. FRONTIER uses a separate `gpt-5.6-sol`, read-only root: max by default, Ultra for divisible work, lower effort when cost/latency dominates. Nested multi-agent is enabled only for Ultra. Native `codex exec` spawn cannot pin role/effort.
 - This is an instruction-backed, live-E2E-verified default, not a security boundary: main bypass and arbitrary expert `-c` remain available by design. `frontier.toml` omits fixed effort for native surfaces that accept overrides.
 - `codex-run` owns reach, stdin, schema, profiles, expert `-c`, channel preservation, and exit status. Keep it internal.
+- `claude-run` is its Claude-side twin and the command a composable review contract names for a panel dispatch on that host. Same shape: prompt on stdin, final message on stdout, exit status mirrored, `--model`/`--effort` pinning the seat, everything it does not recognise forwarded to `claude`. It denies the mutating tools by default, which is not the OS-level sandbox `codex-run` gets — do not read the two defaults as equivalent guarantees. Dispatch whatever command the contract names rather than the bare CLI: only the adapter can report what the dispatch actually did, and a review with no receipt stays PROPOSED.
 
 Dispatch packets:
 

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

@@ -60,6 +60,38 @@ Per-domain menus for the global Verification Discipline loop; pick the narrowest
 - Branch/version test builds against real data: explicitly separate every state sink the app touches (files, DB, OS-level stores that ignore env overrides), confirm the launch path propagates the isolation to child processes, and back up live data before the first run — a mismatched schema that drops unknown fields on write is data loss, not a no-op.
 - Irreversible capture switches: when activation itself has unreproducible cost (a capture window that cannot be replayed), prove the downstream consumption path against existing samples before enabling — reversibility of the code path alone is not enough.
 
+### Deriving the case space
+
+A check has two authored halves, and they rot differently. The **verdict** — what the
+answer should be — rots by encoding a belief that was wrong from the start. The
+**space** — which cases exist — rots by staying still while the thing it covers grows.
+Recording the verdict is common practice; deriving the space is the half usually left
+hand-written, and a suite can have every expectation derived and still cover a set
+someone typed once.
+
+- Record the verdict, do not type it. Run the real path and store what came back;
+  drift then shows as a diff instead of as a belief someone has to re-justify.
+- Enumerate the space from the artifact that defines it — the config's entries, the
+  schema's fields, the router's routes, the installer's call sites. Adding one there
+  should widen coverage with no edit here.
+- Derive the exemption rule too. If some cases legitimately have no answer, decide that
+  from a property the artifact carries, never from a list of names: the list is the
+  authored space coming back through a side door, and it absorbs the regression where
+  a case that should have an answer stops having one.
+- Dedupe on the tuple that actually determines the outcome, and report how many
+  collapsed. A coverage count that hides its own truncation reads as more than it is.
+- Split by cost, not by space. When the real path needs money, credentials, or a
+  network, run a cheap stand-in on every commit and the real one on demand — both from
+  the **same enumeration**, so the two can never disagree about which cases exist.
+- Derivation moves authorship rather than removing it: the extractor and the invariants
+  are still written by hand. Give them a negative control, or the derived suite is just
+  a larger unfalsifiable one.
+- Planting a violation to prove a control fires is a write into the working tree, and
+  the restore is not atomic with it: if the probe can time out, abort, or be
+  interrupted, a restore sitting after it never runs and the plant survives into a
+  commit. Plant in a copy where the shape allows it, and when it must be in place, snapshot
+  first and restore from the snapshot as its own step rather than trusting the probe to finish.
+
 ## Stop Conditions
 
 - If the issue boundary expands compared with the previous review, stop and ask the user to choose redesign/rework or continuing the current iteration.

package/claude/guides/gpt-prompting.md

@@ -114,5 +114,5 @@ Derived from the vendor's published prompting guidance for the `targets` models
 above. When a `targets` model changes, re-derive this guide from current vendor
 guidance rather than editing around the old rules — prompting guidance is
 version-bound, and the previous generation's advice inverted on this one.
-`scripts/check-prompting-targets.sh` fails when the launch config binds a model
+`launch/check-prompting-targets.sh` fails when the launch config binds a model
 this guide does not list.

package/claude/guides/learning-flow.md

@@ -18,9 +18,9 @@ The **light**, per-user, single-session capture flow: turn a lesson from the
 current session into a **learning** (prose + a JSON record) that (a) applies to
 the user's own next session and (b) reaches the org for curation. This is the
 counterpart of the **heavy** session-distill pipeline (`distill!`), which mines
-many sessions and is curator/power-user only. Terms follow the agent-bios
-`LEXICON.md`; the full routing framework is
-`design/session-distill/PLACEMENT-FRAMEWORK.md` (agent-bios repo).
+many sessions and is curator/power-user only. Terminology and the full routing
+framework are maintained in the agent-bios repo; the criteria this flow applies
+are stated below.
 
 Defer to the preset mission: if this session runs the **Session distill** preset
 (trigger `distill!`), that mission owns capture — do not also run this flow.
@@ -62,7 +62,7 @@ still-valid candidates are surfaced for the user's approval.
 
 ## Domain tagging (the curation join key)
 
-Suggest a `domain` from the registered vocabulary in `config/domains.json`
+Suggest a `domain` from the registered vocabulary in `compose/domains.json`
 (domain keys for domain-specific lessons, or a tier name like `core`/`infra`
 for a genuinely cross-cutting lesson); the user **confirms**. If unsure, use
 `unclassified` (never blocks capture — the curator assigns later). If no
@@ -86,7 +86,7 @@ match your host):
       | agent-bios learn --host <claude|codex>
 
 The script (capability boundary) owns `learning_id` / `created` / `schema_version`,
-validates against `config/learning.schema.json`, logs the JSON record, and writes
+validates against `learn/learning.schema.json`, logs the JSON record, and writes
 the lesson prose where THIS host loads it next session:
 - **Claude**: appended to the automation-owned personal learnings file, pulled in
   by the entry file's `@personal/learnings.md` import.

package/claude/guides/llm-capability-boundary.md

@@ -204,7 +204,12 @@ Use it per field or operation, not as a blanket replacement for LLM judgment.
 Use this procedure when designing a new LLM-assisted artifact or revising an
 existing one.
 
-1. Identify the canonical artifact and downstream consumers.
+1. Identify the canonical artifact and downstream consumers. When the consumer already
+   exists, read its **acceptance predicate**, not only its schema: the schema says which
+   fields may appear, and the predicate says which combinations are credited. A producer
+   designed against the schema alone can emit records that are valid and never
+   accepted — one record per event where the consumer judges one record per subject is
+   the common shape of this, and it survives every field-level check.
 2. Split fields into semantic fields, deterministic fields, provenance fields,
    and side-effect operations.
 3. Assign each field or operation one primary authority.

package/claude/guides/session-distill-workflow.md

@@ -2,13 +2,14 @@
 guide_id: session-distill-workflow
 language: en
 status: active
+audience: author
 use_when:
   - a session was launched with the Session distill preset (mission-injected)
   - the launcher nudge says enough sessions accumulated for a mining window
   - mining local Claude/Codex sessions for learnings absent from the corpus
   - promoting, incubating, or retiring items in the session-distill ledger
 core_rules:
-  - the ledger and HANDOFF are the SSOT; read them before touching the pipeline
+  - the ledger is the SSOT for state; read it before touching the pipeline
   - placement follows PLACEMENT-FRAMEWORK.md, never ad-hoc judgment
   - every promotion passes an explicit user-approval gate
   - global growth per round is hard-capped (~500 tokens) by a measured gate
@@ -17,19 +18,28 @@ core_rules:
 
 # Session-Distill Workflow
 
+**Requires an agent-bios checkout.** This runbook edits the corpus itself, so it
+names repo paths and runs repo scripts. On a packaged install those do not exist:
+say so and stop rather than following steps you cannot execute.
+
 Runbook for a session-distill run: mine recent main-context sessions,
 verify candidates, place them through the framework, and apply with the user.
 Everything durable lives in the agent-bios repo.
 
 ## Read first (SSOT)
 
-1. `design/session-distill/HANDOFF.md` — initiative state, prior decisions,
-   open threads. 2. `design/session-distill/PLACEMENT-FRAMEWORK.md` — the
-   placement authority (typology A–G, layers, admission bars, lifecycle).
-3. `design/session-distill/ledger.json` — cumulative item states
-   (placed / incubating / absorbed / retired) with provenance.
+1. `design/session-distill/ledger.json` — the initiative's state. Every item
+   carries its status (placed / incubating / incubating-G / absorbed /
+   adopted-no-text), strength, and provenance, so what is open, what was
+   promoted, and what is still incubating are all queries against this file.
+   Read state here and nowhere else: a count or a status written into prose is
+   correct on the day it is written and silently wrong afterwards.
+2. `design/session-distill/versions.json` — which closed mining window maps to
+   which commit, and therefore what a rollback restores.
+3. `design/session-distill/PLACEMENT-FRAMEWORK.md` — the placement authority
+   (typology A–G, layers, admission bars, lifecycle).
 
-## Stage 1 — Mine (pipeline in `scripts/session-distill/`)
+## Stage 1 — Mine (pipeline in `session-distill/`)
 
 Run in order; each stage reads the previous stage's `out/`:
 
@@ -73,7 +83,7 @@ Run in order; each stage reads the previous stage's `out/`:
   stdout/stderr channel contracts) → codex/ + ko/ mirrors.
 - Verify per layer, not just by diff: enforcement/gate fixture tests
   (non-vacuous — known-bad must fire), hook trigger positive/negative sets,
-  `scripts/check-parity.sh` exit 0 unpiped, prompting-target gate, then
+  `gates/check-parity.sh` exit 0 unpiped, prompting-target gate, then
   `agent-bios install` to activate and re-verify.
 
 ## Stage 4 — G-pass (principles, not directives)
@@ -95,6 +105,6 @@ Run in order; each stage reads the previous stage's `out/`:
 3. Register the corpus version: append {version = window end, commit = the
    corpus-close commit} to `design/session-distill/versions.json` — this is
    what the launcher's Versions & rollback screen offers — then run
-   `python3 scripts/session-distill/update-state.py --window-end <date>`
+   `python3 session-distill/update-state.py --window-end <date>`
    (nudge baseline) and `corpus-state.py project` (launcher status panel).
 4. Merge the branch, push, and confirm deployed state (`agent-bios verify`).

package/claude/guides/tooling-gotchas.md

@@ -62,6 +62,15 @@ depends on it, pin it explicitly instead of trusting the environment.
   early-exit consumers (`cmd | head -1` → SIGPIPE 141), so it is a per-command
   choice, not a global default. Does not apply when the final stage IS the
   assertion (`cmd | grep -q pattern`).
+- **Passthrough arguments in a CLI you author**: an option meant to carry
+  another command's own flags cannot use a greedy-but-dash-stopping arity —
+  Python's `nargs="+"` ends at the first token starting with `-`, so the
+  wrapped command's `--model x` lands on the next positional and the error
+  names a parameter the caller never mentioned. Use the parser's
+  everything-after form (`argparse.REMAINDER`). A bare `--` separator is a
+  second, separate trap: argparse consumes it as its own positional marker
+  before the remainder sees it, so the form every caller reaches for first is
+  the one that breaks — normalize it out of `argv` before parsing.
 - **Reserved parameter names**: assigning to reserved shell names (`UID`,
   `EUID`, `GID`, `PPID`) can invoke the bound system behavior instead of
   storing a value — silently changing process credentials mid-script. Use
@@ -105,6 +114,13 @@ depends on it, pin it explicitly instead of trusting the environment.
   diffs use `git diff origin/base...HEAD` (merge-base form); suspect this
   mechanism first when a diff looks too large or shows deletions in untouched
   files.
+- **Reverting a path is not undoing your edit**: `git checkout <path>` and
+  `git restore <path>` discard *every* uncommitted change in that file. Used
+  to remove a planted probe it also removes whatever else was in flight there,
+  and the loss is silent. Check `git diff <path>` first, or plant in a copy and
+  restore from that. The same asymmetry makes the restore step fragile: if the
+  probe can time out or abort, the restore must not be the next command in the
+  same invocation — put it where a failure cannot skip it.
 - **Dirty-worktree pulls**: before pulling into a worktree with
   staged/unstaged/untracked changes, fetch first and compare incoming paths
   against every dirty path; on overlap or a non-fast-forward, stop and clear

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

@@ -34,6 +34,13 @@ RULES = [
      re.compile(r"\$\?"),
      "A pipeline's $? reflects only the last stage — capture the tested "
      f"stage's own status (unpiped run, PIPESTATUS, per-command pipefail) ({GUIDE})."),
+    # Path-shaped argument only: `git checkout main` is a branch switch and needs no
+    # warning, while `git checkout src/x.py` silently discards every uncommitted edit in
+    # that file — including ones the caller did not put there.
+    ("git-checkout-path",
+     re.compile(r"\bgit\s+(checkout|restore)\b[^|;&]*(--\s|[\w.-]*[./][\w./-]*)"),
+     "Reverting a path discards ALL uncommitted edits in that file, not just the one "
+     f"you planted — check `git diff <path>` first, or restore from a copy ({GUIDE})."),
     ("grep-binary-heuristic",
      re.compile(r"(^|[;&(]\s*|&&\s*|\|\|\s*)grep\s"),
      "grep can misread text with heavy non-ASCII/NUL as binary and return a "

package/codex/AGENTS.md

@@ -94,7 +94,7 @@
 - Use static checks broadly: typecheck, lint, build, format, schema/config validation, graph validation, workbook structure checks, import boundaries, and security checks when available.
 - Add the narrowest reliable runtime or semantic test that proves the changed behavior, meaning, or contract.
 - Pick each domain's verification mix (code, ontology, config/data, spreadsheets, docs) from the Verification Menus in the coding-staged-workflow guide.
-- Let the LLM derive scenarios from the diff, user impact, concept impact, and failure modes; let tools/code execute and verify them.
+- Let the LLM derive scenarios from the diff, user impact, concept impact, and failure modes; let tools/code execute and verify them. Where an artifact already defines the case space — a config, a schema, a route table — enumerate the cases from it rather than from judgment, and record real output as the expectation instead of typing one: a hand-listed set of cases silently stops covering as the artifact grows past it.
 - Keep E2E stable with deterministic data, resilient selectors, isolated external dependencies, and explicit waits.
 - Report the checks run, results, and any unverified risk before calling the work done.
 - Trust a green check only when it traversed the actual changed code through the real dispatch and real calls (not a mock, dry-run, or bypass), and remember that "it ran" is not "quality met" — a fallback, floor, or mock run is not done; treat a zero-findings verdict as suspect until you confirm the harness ran rather than silently crashed, and make PASS mean concrete assertions on real output from the real path.
@@ -123,6 +123,7 @@
 - For work spanning multiple models or CLI agents, context resets and handoffs, unattended LLM batches (including orchestrated subagent fleets), or parallel worktree branches, read and use `${CODEX_HOME:-$HOME/.codex}/guides/cli-multi-model-workflow.md` as a scoped extension of this section.
 - For composing a prompt, packet, or tool description aimed at a specific model family — including cross-family review dispatch, porting a prompt written for an older model, or choosing a reasoning-effort level for a model family — read and use `${CODEX_HOME:-$HOME/.codex}/guides/gpt-prompting.md` for gpt-family targets and `${CODEX_HOME:-$HOME/.codex}/guides/claude-prompting.md` for claude-family targets as scoped extensions of this section.
 - Allocate models by difficulty × blast radius, not phase name; when implementation ran on a cheaper tier, compensate by raising reviewer effort or adding a reviewer kind — never economize on implementation and verification at once.
+- Judge a review by how much independence it actually bought, per reviewer and in this order: different provider, then different model, then strictly higher effort, then the two-perspective floor. A lower effort earns nothing — cheaper is not another perspective. Isolation is a gate rather than a rung: a reviewer you cannot show ran in a fresh context is not a weak review but no review, so exclude it instead of grading it low. Several ready methods are coverage, not proof the perspectives differed; and a clean verdict is PROPOSED until a receipt evidences a fresh dispatch of the declared packet on the exact seat, since a model echo is not evidence.
 - When the user asks for design AND two or more providers are reachable at frontier tier, run dual-provider frontier design drafts: two independent drafts from the same blind packet, one per provider, compared and synthesized into the working draft. The consent gate is about metered spend, not the fan-out: a provider reached via an OAuth session (subscription-covered, no marginal cost) proceeds WITHOUT asking — if a non-main-context OAuth frontier provider exists, just run the dual-provider design; do not ask. Explicit per-request approval (never standing) is required ONLY before dispatching to a provider reachable solely via a metered API key, and it approves that spend. If withholding un-approved API spend leaves fewer than two providers, run single-provider rather than blocking the design on approval. Inject the corpus design principles (concept economy, LLM/capability boundary, staged workflow) into every dispatched design packet — an external model does not load this corpus.
 - Never retry-storm a live rate limit: give unattended batches you author a code-level circuit breaker with per-item completion tracking (thresholds, backoff, and dead-letter rules in the guide); for third-party dispatchers, confirm equivalent protection exists or attend the run.
 - On any resumed, cleared, or relocated session, re-verify where you are (pwd; in a repo, branch and HEAD) before acting on prior-session assumptions — against the pinned handoff state when one exists.

package/codex/guides/claude-prompting.md

@@ -137,5 +137,5 @@ pick the path.
 Derived from the vendor's published guidance for the `targets` models above.
 When a `targets` model changes, re-derive this guide from current vendor
 guidance rather than editing around the old rules — prompting guidance is
-version-bound. `scripts/check-prompting-targets.sh` fails when the launch config
+version-bound. `launch/check-prompting-targets.sh` fails when the launch config
 binds a model this guide does not list.

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

@@ -108,6 +108,23 @@ Instruction/config reach is per invocation. A rule in AGENTS.md cannot bind a he
 - A silent/dead lens is incomplete, never clean. Confirm liveness from usage/error/report evidence; rerun, swap provider, or report PROPOSED.
 - Kind labels do not guarantee distinct backends: wrappers and rate-limit fallbacks can silently route two "different-kind" verifiers to the same model/provider. Before trusting diversity on a high-stakes verdict, confirm each verifier's actual backing model from live process or usage evidence; on collapse, treat the pair as one kind and label PROPOSED.
 
+### Review Independence
+
+How much independence a review actually bought, as an ordinal grade per reviewer rather than a global cross/same flag. Given the main seat `M` and the reviewer seat `R`:
+
+| Grade | When |
+|---|---|
+| `provider_difference` | `R.provider != M.provider` |
+| `model_difference` | same provider, `R.model != M.model` |
+| `higher_effort` | same provider and model, `R.effort` strictly above `M.effort` |
+| `perspective_floor` | otherwise — still a real review |
+
+- Only upward counts. A different-but-**lower** effort earns nothing and lands on the floor: cheaper is not another perspective.
+- **Isolation is a gate, not a rung.** A reviewer that cannot be shown to run in a fresh context is excluded entirely (`NOT_REVIEW`), never graded low — an in-context "review" is the failure this ladder exists to make visible, so it must not appear as a weak pass. Isolation is realised per mechanism: a fresh read-only subprocess, a hermetic profile, a stdio tool call in a fresh session, a headless host workflow, or a stateless API call. If none of these can deliver the required seat, the review did not happen.
+- The floor still requires **at least two distinct perspectives**; one pass on the main's own seat is self-review with extra steps.
+- Multiple ready methods are **coverage, not diversity**. Distinct labels do not prove the perspectives differed.
+- **Achieved is not available.** What can be projected before a review runs is `projected`; a clean verdict without a receipt evidencing a fresh dispatch, the declared packet, a non-empty result and the exact seat is `PROPOSED`, never ACHIEVED. A model echo is not a receipt.
+
 ## Dual-Provider Design Drafts
 
 - Trigger: the task is design (the staged-workflow guide's design stages) AND two or more providers are reachable at frontier tier. Reachability via an OAuth session is subscription-covered — no marginal spend, so no approval and no question: if a non-main-context OAuth frontier provider exists, proceed with the dual-provider design directly. The consent gate applies ONLY to a provider reachable solely via a metered API key: dispatching to it needs the user's explicit per-request approval of that spend (per-request, not standing — an old approval does not carry to the next design). If the only way to reach a second provider is un-approved metered API spend, stay single-provider rather than blocking the design.
@@ -154,7 +171,7 @@ Write for the next agent and re-verification, not narrative. Required content:
 
 ## Environment Binding (edit per environment)
 
-This is the human-readable projection of concrete models/tools; `config/agent-launch.toml` is the machine launch authority and parity checks keep them aligned. Re-probe when the binding is older than ~8 weeks or a newer observable model/tool changes the surface. `agent-bios install` overwrites deployed bindings, so edit the repo copy.
+This is the human-readable projection of concrete models/tools; `launch/agent-launch.toml` is the machine launch authority and parity checks keep them aligned. Re-probe when the binding is older than ~8 weeks or a newer observable model/tool changes the surface. `agent-bios install` overwrites deployed bindings, so edit the repo copy.
 
 Binding (2026-07-25):
 
@@ -178,6 +195,7 @@ Codex direct-drive (verified 0.144.1, 2026-07-12):
 - HELM is instructed to dispatch tiers through internal `codex-run`, which pins model/effort/sandbox. FRONTIER uses a separate `gpt-5.6-sol`, read-only root: max by default, Ultra for divisible work, lower effort when cost/latency dominates. Nested multi-agent is enabled only for Ultra. Native `codex exec` spawn cannot pin role/effort.
 - This is an instruction-backed, live-E2E-verified default, not a security boundary: main bypass and arbitrary expert `-c` remain available by design. `frontier.toml` omits fixed effort for native surfaces that accept overrides.
 - `codex-run` owns reach, stdin, schema, profiles, expert `-c`, channel preservation, and exit status. Keep it internal.
+- `claude-run` is its Claude-side twin and the command a composable review contract names for a panel dispatch on that host. Same shape: prompt on stdin, final message on stdout, exit status mirrored, `--model`/`--effort` pinning the seat, everything it does not recognise forwarded to `claude`. It denies the mutating tools by default, which is not the OS-level sandbox `codex-run` gets — do not read the two defaults as equivalent guarantees. Dispatch whatever command the contract names rather than the bare CLI: only the adapter can report what the dispatch actually did, and a review with no receipt stays PROPOSED.
 
 Dispatch packets: