agent-bios 0.9.8 → 0.10.0

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,21 @@ 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 |
+| `research/` | corpus research (the 12,749-file AGENTS.md/CLAUDE.md classification): reports, scripts, labeling record; bulk data stays local by `.gitignore` rule |
 | `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.
@@ -38,18 +59,24 @@ Two layers:
 | Guide | Scope |
 | --- | --- |
 | `cli-multi-model-workflow` | multi-model CLI workflow: Default Frame, role slots/tiers, delegation mechanics, driving Codex CLI directly, cache economy, unattended-batch safety, halt/resume, handoff contract, Environment Binding |
-| `coding-staged-workflow` | staged development: design → process → implement, review loop, severity contract, verification menus, stop conditions |
+| `coding-staged-workflow` | staged development: design → process → implement, lightweight path, review loop, severity contract, stop conditions |
+| `verification-discipline` | verification depth and per-domain mix (owns the Verification Menus), case space, what a green result is worth |
+| `concept-economy` | concept-surface economy: reuse / extend / rename / split, split triggers, migration compatibility |
+| `documentation-hygiene` | where comments, history, and handoffs belong; how to phrase rules others follow |
 | `llm-capability-boundary` (+ `-patterns`, `-examples`) | LLM/tool/code authority boundary: field authority, accepted output channels, structural enforcement, worked examples |
 | `mock-realization-boundary` | mock/fixture realization vs product semantic path |
 | `svg-visualization-guide` | SVG diagram / service-blueprint spec |
 | `implementation-map` | IMPLEMENTATION_MAP.html current-state dashboard |
 
+The table names the load-bearing guides; the full inventory and its per-domain
+classification live in `compose/domains.json`, which the domains gate holds against the
+tree.
+
 ## 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 +86,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 +103,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

@@ -52,57 +52,25 @@
 
 ## Concept Economy
 
-- Keep the concept graph compact by reusing existing concepts that clearly cover the behavior.
-- Treat lasting or shared names as concept candidates: features, entities, variables, types, helper modules, artifacts, config keys, CLI flags, MCP/tool fields, public response fields, artifact fields, enum values, failure kinds, retry/recovery tokens, process names, and documentation terms.
-- Before adding or changing a concept, find the nearest existing concept and choose one path explicitly: reuse, extend, rename, or split.
-- Prefer broad, stable concepts with precise properties over narrow near-duplicates.
+- When adding, changing, renaming, splitting, or exposing anything lasting or shared — a feature, entity, type, field, config key, CLI flag, enum value, failure kind, artifact, or documentation term — read and use `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/concept-economy.md` as a scoped extension of this section.
 - Before fixing a review finding or test failure, classify the fix as reducing, preserving, or increasing the active concept surface.
-- Split or promote a concept when it changes runtime behavior, ownership, lifecycle, validation, failure mode, user-visible behavior, audit/replay requirements, authority, persistence, user control, or failure handling.
-- Keep derived values as properties or projections of their source concept when tools/code can derive them from the source authority.
-- Keep internal projections and helper outputs internal unless public exposure is required for user behavior, product contract, or artifact truth.
-- Distinguish authority from visibility: public responses may expose bounded views, while the source concept or artifact remains the truth location.
-- Reuse existing enum values, failure kinds, retry/recovery tokens, and result/failure surfaces before introducing new vocabulary.
-- Use fallback paths, compatibility shims, and deprecated alias normalization when explicit migration compatibility is required.
-- Keep comments and active docs aligned with runtime behavior, failure semantics, retry policy, ownership, and authority.
-- When a split is necessary, name the parent concept, explain the reason for the split, and map aliases or variants back to the canonical concept.
-- In ontology work, check existing entities and relations first, then keep the concept graph compact.
-- In code work, follow existing naming patterns and consolidate variations introduced by the current change.
-- Let the repository's shape mirror its concept graph: keep each shared, lasting concept's canonical name traceable across the layers it appears in — path, module, type/interface, field, and public API — so the structure is navigable by name (grep-findable, path-guessable) without a translation table. This binds shared concepts only; transient locals, generic containers, and framework- or tooling-imposed layout may diverge.
 
 ## Coding Guidelines
 
 - For `.xlsx` editing, generation, reconciliation, validation, or connected spreadsheet processing, use the installed `spreadsheet-processing` skill when present — with plain tools/code as the fallback — and validate formula-dependent Excel results with the real Microsoft Excel engine.
-- For meaningful development work, read and use `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/coding-staged-workflow.md` as a scoped extension of these Coding Guidelines.
+- For development work, read and use `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/coding-staged-workflow.md` as a scoped extension of these Coding Guidelines — a change too narrow to need it is what its lightweight path decides, not a reason to skip the read.
 - For mock, fixture, fake, stub, simulated-provider, or test-realization design, read and use `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/mock-realization-boundary.md` as a scoped extension of these Coding Guidelines.
-- When the user asks to "설계" or design, read the coding-staged-workflow guide and focus on high-level design and implementation-process design; move to implementation only after the user asks to implement or approves the plan.
-- Think before coding: state key assumptions and surface ambiguity early.
-- Build the smallest viable functional path that satisfies the qualitative completion criteria. Minimum limits surface area, configuration, abstractions, optional scope, and implementation spread; it must not reduce required behavior, runtime authority, evidence quality, or verification depth.
-- Treat viability as real behavior against real inputs, real authority, and the intended runtime path. Use mocks only for tests, fixtures, or explicitly requested simulations; mock-backed paths support verification but do not count as product completion.
-- Make surgical changes. Touch only what the request requires, preserve existing style, and avoid casual adjacent refactors.
-- Clean up issues introduced by the current change. Mention unrelated dead code separately.
 - Own the full lifecycle of what you create — spawned processes and handles through teardown, artifacts out of tool-managed temp locations into a durable home — and keep differently-owned state separate: never colocate deploy-managed and user-owned data in one overwrite-managed file.
-- Define success criteria before multi-step coding work, then verify against them.
-- For bugs, prefer a reproducing test before the fix when practical.
-- Every changed line should trace back to the user's request.
-- Fix the root cause at its authority rather than the visible symptom: when downstream patches keep compensating for bad inputs, fix upstream at the source; when each fix only exposes another instance of the same defect, single-source the value and fix the whole class instead of patching instances.
 - Land risky or behavior-changing work behind a default-off path that preserves current behavior when off (proven by diff) and is enabled by an explicit opt-in, so the change stays reversible and the on/off difference is isolated. When a request would weaken a security or authority posture — removing or loosening an authentication/authorization check or access scope, or lowering a protective value such as session/token lifetime, password/crypto strength, rate limit, lockout threshold, or audit retention — treat it as a decision, not a rote edit, even when it is a one-line change and nothing in the code labels the value as security-relevant: state the consequence and at least one safer path to the real goal, and do not apply the weakening in the same turn — proceed only after the user confirms they accept the tradeoff.
 
 ## Verification Discipline
 
 - For composing a review request, packet, or reviewer role — the evidence bar, the verdict shape, and why a review returned noise, nothing, or a clean bill of health — read and use `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/review-request.md` as a scoped extension of this section.
 - After every meaningful code, ontology, config, data, spreadsheet, or documentation change, run a verification loop regardless of commit or handoff status.
-- 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.
-- Keep E2E stable with deterministic data, resilient selectors, isolated external dependencies, and explicit waits.
+- For choosing verification depth, the per-domain mix, the case space, what makes a completion criterion falsifiable, how to keep an E2E stable, or what a green result is worth, read and use `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/verification-discipline.md` as a scoped extension of this section — its Verification Menus carry the per-domain mixes.
 - 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.
-- Make completion criteria falsifiable: prefer signals that fail when the mechanism is wrong (negative or contrast controls), and if no existing gate can judge a criterion, build the executable judge or do not claim the criterion met.
 - Before comparing two of anything (cost, performance, quality, frequency), fix a common basis — units, denominators, population, measurement surface — compare on equivalent output, and exclude or flag non-representative data (promotions, outages, smoke slices).
-- For non-trivial designs or high-risk changes, run independent adversarial review across distinct lenses, ideally on the design before implementation, and re-verify each finding against real code before acting on it. Apply the convergence heuristic by reviewer kind (detailed in the multi-model guide): same-kind convergence is high confidence but same-kind reviewers share blind spots — their shared "clean" is not verification; different-kind divergence is the expected signal — act on the union. Never accept an orchestrated workflow's self-reported all-green as sufficient; independently re-run the diff inspection and verification suite yourself.
-- Proportion verification to cost, risk, and information gain: before expensive or slow live runs, diagnose in code and replay the changed deterministic logic over persisted real artifacts, probe at N=1 with inputs precondition-checked, and reserve full design-review-plus-live verification for first-of-kind or authority-changing work; proportion assurance to the deployment context — a single-user, own-data tool does not warrant production-grade assurance; prefer delivery.
-- Trust a green / zero-findings verdict only if the check could have failed over a real, non-empty subject: assert the entity-under-test set has cardinality > 0 before any "no bad X" or "all X satisfy P" claim (an empty subject set passes vacuously and proves nothing), and for any test touching a branch you add or delete, confirm its inputs satisfy the live branch's entry guard — a copied fixture that fails the new guard silently routes into the about-to-be-deleted dead branch and stays green even after the real behavior breaks. When a check goes green unexpectedly fast or empty, dump what it actually ran over. Checker code itself must assert the expected shape and fail loud — a permissive fallback (`a || b`) inside a gate absorbs wrong assumptions and keeps passing.
 
 ## Tooling and Operational Safety
 
@@ -113,7 +81,6 @@
 - Never accept secrets through transcript- or history-logged channels.
 - When a secret must be supplied, provide a gitignored env slot, read the value only from the environment, verify its presence and format without echoing it, and advise rotating anything already pasted; assume a resource-creating call may echo the secret back in its success output — suppress or discard the response body, and treat an echoed secret as pasted (rotate).
 - Treat a coarse runtime signal — a failure label, a `ps`/process-inspection result, idle CPU with no output — as a hypothesis, and confirm the cause against the authoritative low-level evidence the mechanism emits before attributing blame or intervening: read the raw provider/skill log payload (e.g. `input_tokens:0` proves a pre-dispatch rejection that exonerates your content and your change), and confirm a config/env toggle reached a subprocess via a cheap artifact the gated branch emits rather than an unreliable `ps` env read. A multi-minute LLM or subprocess call at ~0% CPU with an output gap is the normal signature of I/O wait, not a hang — check process state and the call trace's in-flight duration before acting, so you do not abort healthy long-running work.
-- Before reasoning about what a branch contains or opening a PR, run `git fetch` and compute the range as `origin/<base>..HEAD`, never `<base>..HEAD` against the local tracking ref — on a shared repo the local base drifts behind the remote until you pull, silently inflating the diff with already-merged work; if the range is surprisingly large, suspect a stale base before suspecting the branch. Platform "mergeable" flags are computed against the base only — sibling PRs can each look clean yet conflict; before picking a merge order, diff their changed-file sets and simulate the sequence.
 
 ## Multi-Model Workflow
 
@@ -122,6 +89,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.
@@ -129,11 +97,7 @@
 ## Documentation Hygiene
 
 - Keep runtime code, active docs, and execution-facing docs focused on current behavior, current decisions, current contracts, current authority, and current failure handling.
-- Use comments for non-obvious current behavior, invariants, constraints, or risks that still apply.
-- Put backward-compatibility notes, deprecated behavior, migration rationale, historical alternatives, change narratives, and handoff logs in isolated documentation paths such as `docs/`, `design/`, `archive/`, or `deprecated/`.
-- Link from active docs or code to isolated notes only when the current task needs that history or the reference helps future maintainers.
-- Phrase guidelines as desired behavior and preferred patterns.
-- Prefer established docs such as `CHANGELOG.md`, `IMPLEMENTATION_MAP.html`, or handoff notes for change history and implementation context.
+- For where a comment, a compatibility note, deprecated behavior, a rejected alternative, a migration rationale, a change narrative, or a handoff log belongs — how to phrase a rule others will follow, and whether active docs should link to history — read and use `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/documentation-hygiene.md` as a scoped extension of this section.
 
 ## Visual Explanations
 

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

@@ -57,7 +57,7 @@ Delegate execution, not decisions. A unit is delegable only when it is decision-
 - Use a resident teammate only for dependent slices in one burst. Verify that the CLI preserves its model and context; resume-after-completion may silently change both. Retire after the burst or cache TTL, and persist durable knowledge in files.
 - After a discard or direction change, respawn once a routine round costs about as much as a fresh slice. Recover unique in-flight state to files first.
 - Redirects to busy workers may queue rather than preempt. Check artifacts before destructive redirects, phrase them conditionally, and stop an actively harmful worker by scoped PID/worktree authority.
-- Idle/progress notifications are hypotheses; verify repo artifacts before re-dispatch. Cross-reset state belongs in files, not task boards or transcripts. When polling concurrent async jobs, pin the exact id/handle received at dispatch — a "latest" convenience selector can silently point at a sibling job and return plausible-but-wrong results.
+- Idle/progress notifications are hypotheses; verify repo artifacts before re-dispatch. An idle signal is liveness decoupled from the report: a subagent can go idle without ever delivering its result, so idle-without-report is not done — request the report explicitly rather than waiting. Cross-reset state belongs in files, not task boards or transcripts. When polling concurrent async jobs, pin the exact id/handle received at dispatch — a "latest" convenience selector can silently point at a sibling job and return plausible-but-wrong results.
 - Give reviewers/subagents a read-only diff, snapshot, or isolated worktree — not the live tree the main is editing — and forbid destructive git ops (checkout --, reset --hard, stash, clean) on any tree with uncommitted work; re-verify tree integrity before trusting results produced mid-edit.
 - Review cost scales with the diff, so layered review preserves delegation savings. Lower reviewer tier before dropping a review kind.
 
@@ -108,11 +108,28 @@ 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.
+- Trigger: the task is design — high-level shape and implementation process, before any code — 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.
 - Mechanics: compose ONE blind packet (evidence, constraints, rubric, neutral alternatives — the escalation-gate packet shape) and dispatch it unchanged to one frontier-tier model per provider; drafts stay independent — neither sees the other's output. Then adjudicate: compare the two dual-provider frontier design drafts against the rubric, take the winner as the skeleton, graft the loser's superior parts, and record what differed and why the synthesis chose as it did (FRONTIER disposition line).
-- Packet injection: a dispatched designer is hermetic — it reads only its packet and never loads this corpus. Inject the design principles the corpus would have supplied: concept economy (reuse/extend/rename/split, compact concept graph), the LLM/tools-code capability boundary, the staged-workflow design rules (smallest viable path, falsifiable done-when), and any domain-specific principles the design touches. A draft produced without the principles is not comparable to one produced with them.
+- Packet injection: a dispatched designer is hermetic — it reads only its packet and never loads this corpus. Inject the design principles the corpus would have supplied: concept economy (reuse/extend/rename/split, compact concept graph), the LLM/tools-code capability boundary, the staged design rules (smallest viable path, falsifiable done-when), and any domain-specific principles the design touches. A draft produced without the principles is not comparable to one produced with them.
 
 ## Unattended Batch Safety
 
@@ -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

@@ -7,7 +7,7 @@ use_when:
   - architecture changes, new features, cross-module or ontology changes, review-driven fixes
   - the user asks to design ("설계") before implementation
   - judging materiality of review findings and deciding when to stop or redesign
-  - choosing the per-domain verification mix (code, ontology, config/data, spreadsheets, docs)
+  - deciding where a stage's verification points and review gates belong in the work plan
 ---
 
 # Coding Guidelines: Staged Workflow
@@ -16,7 +16,12 @@ This guide is a scoped extension of the global Coding Guidelines. Use it for mea
 
 It operates inside the existing global rules for requested scope, concept economy, LLM/tools/code boundary, verification discipline, and documentation hygiene.
 
-For trivial edits, use the lightweight inspect-edit-verify path from the global Coding Guidelines.
+For trivial edits, use the lightweight inspect-edit-verify path, defined here in full:
+read the surface you are about to touch before changing it; if the request admits more
+than one reading, state the reading you act on; make the surgical edit — every changed
+line traceable to the request, adjacent code left alone; verify with the narrowest
+reliable check that would fail if the edit were wrong; clean up only what your own
+change introduced. The stages below are for work that outgrows that sentence.
 
 When the user asks to "설계" or design, stay in design mode. Focus on high-level design and implementation-process design, then present the plan, tradeoffs, review gates, and implementation trigger. Move to implementation after the user asks to implement or approves the plan.
 
@@ -32,8 +37,45 @@ When the user asks to "설계" or design, stay in design mode. Focus on high-lev
 2. Implementation-process design: turn the design into an ordered work plan with dependencies, verification points, review gates, and redesign triggers.
 3. Implementation: make the smallest viable functional changes that satisfy the approved design and process plan.
 
+**Minimum** limits surface area, configuration, abstractions, optional scope, and implementation spread. It must not reduce required behavior, runtime authority, evidence quality, or verification depth — a change that ships less of those is not smaller, it is less finished, and "smallest viable" becomes the excuse rather than the discipline.
+
+**Viable** means real behavior: the change runs against real inputs, real authority, and the intended runtime path. Mocks belong to tests, fixtures, and explicitly requested simulations — a mock-backed path supports verification but does not count as product completion, even when nothing labels it a mock; the full boundary lives in `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/mock-realization-boundary.md`.
+
+Define the success criteria before multi-step work starts, then verify against those criteria rather than against what you ended up building. Criteria written afterwards describe the implementation, so they cannot fail it.
+
 When simplifying a pipeline, moving processing downstream and dropping captured source fields are separate decisions: relocation is free simplification, but reducing captured information is riskier and needs explicit confirmation — "no current consumer" is not evidence of no future value.
 
+## Making the change
+
+Deciding what to build and building it are different disciplines. This one is about leaving a
+change that reads as the change that was asked for.
+
+**State the assumption before you act on it.** Most wasted implementation is not a wrong answer to
+the question; it is a right answer to a question nobody asked. Where the request admits more than
+one reading, say which one you took and keep going — surfacing it early costs a sentence, and
+surfacing it after the work costs the work.
+
+**Surgical means legible, not minimal.** Touch what the request requires, follow the file's
+existing style rather than your preferred one, and leave adjacent code alone even when it is
+worse than what you are adding. A diff carrying an unrequested refactor forces the reviewer to
+separate the two by hand, and the improvement is the part that gets dropped when they run out of
+patience.
+
+**Clean up what this change introduced, and only that.** Dead code, unused imports, and debris
+your own edit created belong in the same change. Debris you found belongs in a sentence: name it
+so it is visible, and leave it where the person who owns it can decide.
+
+**For a bug, reproduce before you fix, when that is practical.** A test written after the fix
+proves the code does what it now does. A test written before proves you understood the failure —
+and it is the only version that can tell you the fix was unnecessary, or that it addressed a
+different bug than the one reported.
+
+**Fix the cause at its authority, not the symptom where it shows.** Two signals say you are
+patching downstream: compensating code keeps accumulating around bad inputs, and each fix reveals
+another instance of the same defect. The first says go upstream to where the value is produced.
+The second says the instances are a class — single-source the value and fix the class, because
+patching them one at a time is a queue that refills.
+
 ## Review Loop
 
 - 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).
@@ -45,25 +87,17 @@ When simplifying a pipeline, moving processing downstream and dropping captured
 - Treat low and info as non-blocking unless requested or promoted by new evidence.
 - When a document declares sections co-authoritative for a rule (fixture blocks, conformance appendices), treat every occurrence as one replicated value: propagate edits to all declared locations in the same pass and check propagation completeness explicitly in review.
 
-## Verification Menus
-
-Per-domain menus for the global Verification Discipline loop; pick the narrowest reliable mix that proves the changed behavior, meaning, or contract.
+## Verification
 
-- Code: a layered mix of unit tests, integration tests for E2E segments, targeted E2E for changed flows, and full E2E for release or high-risk changes.
-- Ontology: static graph checks, concept economy gates, changed-path integration checks, and competency-question E2E checks.
-- Config or data: real parsers, schema checks, fixture validation, and sample transformations.
-- Spreadsheets: static workbook checks, fixture-based output checks, cross-sheet flow checks, visual/layout checks, and real Microsoft Excel engine recalculation for formula-dependent results.
-- Docs: links, terminology, current behavior alignment, and references to isolated historical notes.
-- Release or distribution: after publishing to multiple independently writable channels (signed manifest, object storage, release host, embedded updater), digest-verify every referenced object against the staging original per channel — publish success and upload order are not evidence — and run the real installer/updater through its default path.
-- A/B or on/off measurements: before accepting a null result, verify the arms actually received different treatment in the mechanism under test — a shared default or unconditional upstream step can silently apply the treatment to both arms.
-- Model-behavior guardrails: verify by changed behavior, not recitation — a staged battery from named-trigger cases through disguised, deconfounded, category-wide, and single-variable framings; a clean pass means "no known defect", so re-run the battery when the model changes.
-- 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.
+Verification is a subject of its own — depth, per-domain menus, deriving the case space, and what
+a green is worth. It lives in `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/verification-discipline.md`.
+Run it at each stage's verification points, and use its Verification Menus to pick the mix.
 
 ## 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.
 - Consider the boundary expanded when review reveals a broader affected purpose, failure condition, impact area, concept boundary, architecture boundary, or severity class.
+- When review rounds keep producing material findings, classify each before fixing: a regression the previous round's own fix introduced, or a fresh instance of one pre-existing root cause. Regressions say tighten the increment and continue; recurring instances with zero regressions say instance-patching is a refilling queue — trigger the redesign-versus-continue stop above.
 - Before calling the work done, report the current stage, review results, remaining material issues, verification results, and any stop reason.
 
 ## Environment Binding (edit per environment)