agent-bios 0.1.0

package/DEPENDENCIES.md

@@ -0,0 +1,89 @@
+# Dependencies
+
+What agent-dotfiles' scripts and rules depend on, with required capabilities and verified versions. Role-slot→model bindings are owned by each guide's `Environment Binding`; numeric defaults by each guide's `Evidence Base`. This file does not restate them — it inventories dependency *kinds* and points to their owners, so a version lives in exactly one place.
+
+Korean: [`ko/DEPENDENCIES.md`](ko/DEPENDENCIES.md). Dates = verification time; update a date when the version is re-checked.
+
+## Runtime tools (scripts) — owned here
+
+| 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 |
+| `zsh` | `shell/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 |
+
+## Host agent CLIs
+
+| 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) |
+| 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`
+
+Concrete role-slot→model bindings live only in each guide's `Environment Binding`, dated, expiring ~8 weeks or on a newer model. Not restated here.
+
+- Providers: **Anthropic** (Claude — Fable/Opus/Sonnet/Haiku), **OpenAI** (GPT / Codex).
+- Auth: Anthropic via Claude Code login; OpenAI via ChatGPT subscription or API key (`$CODEX_HOME/auth.json`).
+
+## 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.
+
+## Referenced / optional — not required by the core repo
+
+- **ultracode-for-codex** (0.4.5) — 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** — evaluated (inherits real `~/.codex`; gpt-5.4-era prompting), **not adopted**; `scripts/codex-run.sh` is preferred for controlled reach.
+- **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.
+
+## Re-verify
+
+```bash
+codex --version
+codex_help="$(codex exec --help)"
+for flag in --output-schema --ignore-user-config --ephemeral --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox --cd --sandbox --model --profile; do
+  printf '%s\n' "$codex_help" | grep -q -- "$flag" || { echo "missing codex flag: $flag"; exit 1; }
+done
+printf '%s\n' "$codex_help" | grep -Eq '(^|[[:space:]])-c([,[:space:]]|$)' || { echo "missing codex flag: -c"; exit 1; }
+printf '%s\n' "$codex_help" | grep -Eq '(^|[[:space:]])-C([,[:space:]]|$)' || { echo "missing codex flag: -C"; exit 1; }
+printf '%s\n' "$codex_help" | grep -Eq '(^|[[:space:]])-p([,[:space:]]|$)' || { echo "missing codex flag: -p"; exit 1; }
+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:-$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/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
+python3 - <<'PY'
+import os, pathlib, tomllib
+roots = [pathlib.Path("codex/agents"), pathlib.Path(os.environ.get("CODEX_HOME", pathlib.Path.home() / ".codex")) / "agents"]
+required = {"frontier.toml", "workhorse.toml", "sweep.toml", "reviewer.toml"}
+for root in roots:
+    missing = required - {path.name for path in root.glob("*.toml")}
+    assert not missing, f"missing required agent TOML files in {root}: {sorted(missing)}"
+    for path in sorted(root.glob("*.toml")):
+        tomllib.loads(path.read_text())
+    print(f"agent TOML ok: {root}")
+PY
+scripts/codex-helm.sh --dry-run --mode review "probe"
+```
+
+## Ownership
+
+| Owner | Owns |
+| --- | --- |
+| this file (`DEPENDENCIES.md`) | script runtime tools + required capabilities; the dependency inventory |
+| each guide `Environment Binding` | role-slot→model bindings, host-CLI verified versions |
+| each guide `Evidence Base` | numeric defaults / measurements |

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kangmin Lee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# agent-dotfiles
+
+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.
+
+Korean reference: [`ko/`](ko/) mirrors every doc below — reference only, never installed or loaded.
+
+## Model
+
+Two layers:
+
+- **Global instructions** — `claude/CLAUDE.md` ↔ `codex/AGENTS.md` (mutual mirrors). Loaded every session. Hold only always-on invariants, decision principles, and guide pointers. Admission rule: a rule earns global placement only if it must work **even when the agent fails to recognize the situation** — a rule whose failure mode is recognition failure dies behind a pointer.
+- **Scoped guides** — `claude/guides/`, `codex/guides/`. Loaded when a global pointer fires. All procedures, tables, numbers, and environment-specific content live here.
+
+## 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 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`.
+- **English is canonical and installed; Korean (`ko/`) is reference only.** The harness loads only fixed-name English files; the installer deploys English only.
+
+## Layout
+
+| Path | Role |
+| --- | --- |
+| `claude/CLAUDE.md`, `codex/AGENTS.md` | global instructions (en) — installed & loaded |
+| `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/` |
+| `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.
+
+## Guides
+
+| 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 |
+| `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 |
+
+## 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.
+4. Commit, then deploy: `agent-bios install` (or `agent-bios update` from a clone).
+
+## Install (deploy)
+
+The `agent-bios` CLI deploys this SSOT into your environment by copy — idempotent, backed up before overwrite, then verified. It ships as the npm package `agent-bios`; package and command are the same name. The `$HOME` deployment is always the explicit `install` command, never a postinstall side effect.
+
+```bash
+npm install -g agent-bios
+agent-bios install     # deploy, back up replaced files, then verify
+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/`).
+
+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 preset 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. Choose a preset or select **Custom** 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 review route — native, onto, and ultracode — runs on the opposite family. 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.
+
+At the shell-wrapper boundary, every argument-bearing command (`codex exec ...`, `claude -p ...`) and every non-TTY invocation skips launch-profile projection and preserves caller arguments. The Claude direct path intentionally retains its wrapper default, `--dangerously-skip-permissions`. `codex --no-tui ...` / `claude --no-tui ...` explicitly take that direct path, and `AGENT_LAUNCH_TUI=0` disables zero-argument TUI interception for a process tree.
+
+Direct `agent-launch` calls still require a valid profile to resolve the backend command and its default arguments. `--preset`, `--custom`, or `--dry-run` select the configured-launch path even when non-TTY or combined with `--no-tui`; a non-TTY bare `--dry-run` deterministically uses Balanced, and a custom profile without that preset must pass `--preset NAME`. Forwarded backend arguments are expert overrides appended after projected defaults and may supersede them; the summary discloses this when arguments are present. For scripted configured launches, call `$HOME/.local/bin/agent-launch --preset NAME --yes HOST -- ...` or add `$HOME/.local/bin` to `PATH`. The summary goes to stderr so backend stdout stays machine-consumable.
+
+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.
+
+`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
+
+Keep the rule layers. Swap checklist: each guide's `Environment Binding` (`(private)` entries are the author's examples); the response-language preference and the "설계" design-trigger word in the global file; skill/MCP names inventoried in `DEPENDENCIES.md` (the `spreadsheet-processing` skill, the review MCP). Then re-measure `Evidence Base` numbers in your environment before tuning.
+
+## Scope
+
+Only stable configuration, config-managed credentials, and global agent instructions. No runtime state, logs, sessions, caches, generated artifacts, or temp paths.

package/claude/CLAUDE.md

@@ -0,0 +1,138 @@
+# CLAUDE.md
+
+## Global Preferences
+
+- Prefer concise Korean responses with polite speech unless the user asks otherwise.
+- Keep file changes within the requested scope.
+
+## Problem Solving
+
+- First identify the goal, scope, ambiguities, and likely completion condition.
+- Resolve ambiguity from context when safe; ask only when ambiguity blocks progress or creates risky outcomes.
+- For simple requests, choose the most direct low-risk method and proceed.
+- For non-trivial requests, compare 2-4 methods by goal fit, time, cost, risk, benefit, and "done when".
+- Mark one default method. If the user is silent and the default is safe, proceed with it.
+- Execute the chosen method accurately and stay within scope.
+- Return to understanding if a discovery breaks the user's premise.
+- Reconsider the method if the selected approach becomes infeasible.
+- Log non-blocking discoveries and continue.
+- If the same loopback happens twice, stop and ask the user.
+- Compare the result with the selected "done when" criterion before claiming completion.
+
+## Decision Framing
+
+- Ask decision questions in outcome terms, not jargon terms.
+- When the user may not know the domain, explain choices by resulting behavior, tradeoffs, time, cost, risk, reversibility, and recommended default.
+- Present 2-4 meaningful options. Ask about implementation details only when they directly affect the decision.
+- For each option, state what changes for the user or product, what it costs, what risk it carries, and when it is the right choice.
+- Translate technical terms into plain consequences. Example: prefer "faster setup but harder to scale later" over naming a tool alone.
+- Ask for the user's goal or constraint when that determines the answer; otherwise choose the safest default and proceed.
+- Evaluate user suggestions for goal fit, risk, complexity, and verification before turning them into implementation plans; if a suggestion does not fit the user's goal, say so clearly and recommend a better path.
+- Distinguish implementation feasibility from recommendation.
+- Treat user suggestions, inherited premises, prior diagnoses, handoff and design claims, reviewer findings, and your own earlier conclusions as hypotheses, not facts; re-derive each load-bearing claim from real code or data before building on it, and record a dated correction in the source doc or memory when a finding overturns it.
+
+## LLM And Capability Boundary
+
+- For structured-output, runtime-authority, capability-surface, or MCP/tool-definition and tool-schema design, read and use `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/llm-capability-boundary.md` as a scoped extension of this section.
+- Use instructions to describe intended work, semantic criteria, decision principles, and completion criteria.
+- Use the LLM for semantic work: clarify intent, define meaning, choose tradeoffs, judge materiality or causality, draft prose, and reduce evidence into decisions.
+- Use the capability surface for structural constraints: accessible context, available tools, permissions, execution routes, artifact paths, accepted output channels, validators, and required gates.
+- Enforce constraints through the capability surface. When a behavior must not happen, make it unavailable, invalid, or unaccepted instead of repeating prohibitions.
+- Use tools/code for deterministic work: inspect, search, parse, count, calculate, edit, format, call APIs, merge by explicit rules, serialize artifacts, validate schemas, run tests, and compare diffs.
+- When exactness, freshness, scale, repeatability, side effects, or canonical artifacts matter, use tools/code to produce evidence or perform the action.
+- Let the LLM design merge, projection, and validation rules; let tools/code apply those rules and report evidence.
+- For required structured or machine-consumed outputs, make a deterministic submit tool or equivalent constrained channel the only accepted output path; the LLM submits bounded semantic payloads, and tools/code create the canonical artifact.
+- Let tools/code own ids, paths, serialization, metadata, validation, and deterministic projections; if the execution path cannot enforce this contract, fail clearly or switch to an enforceable path.
+- Keep deterministic values out of LLM authority when tools/code or the environment can derive them from source artifacts.
+- For simple stable explanations or planning with no evidence requirement, answer directly in prose.
+- Treat a produced field, flag, signal, or code branch as inert until a downstream consumer reads it and the output changes; presence in the repo or in a finished sibling artifact is not runtime authority, so wire or verify the consumer in the same change and confirm the effect on the live path, not just the value's presence.
+- Hard-block only deterministically decidable structural or security violations; route semantic, quality, coverage, and preservation concerns to a non-blocking disclosure for the user to decide, and never act on an unconfirmed automated judgment as if it were confirmed.
+- Runtime/code may enforce the contract but must not reason: reject contract-failing output, and never semantically patch the prompt, re-judge relevance, or salvage/reinterpret a deficient LLM result to make it pass.
+
+## 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.
+- 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 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.
+- 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
+
+- 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.
+- 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.
+- 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.
+- 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.
+
+## Tooling and Operational Safety
+
+- Before relying on any model id, tool flag, API capability, dependency version, or runtime constraint, confirm it empirically against the live or installed artifact (a minimal probe, the binary's registered options, the installed package version) rather than docs, memory, or a version string.
+- Scope destructive actions (kill, rm, force-push, reset --hard) to targets you own, identified by PID, path, or ancestry — never a broad command-line substring or blanket match — and diagnose the actual state before any irreversible git, remote, or process operation.
+- Never accept secrets through transcript- or history-logged channels; 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.
+- 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.
+
+## Multi-Model Workflow
+
+- 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.
+- 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.
+- 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.
+
+## 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.
+
+## Visual Explanations
+
+- For SVG diagrams, service blueprints, pipeline maps, or complex visual decision aids, read and use `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/svg-visualization-guide.md` as a scoped extension of this section.
+- When a concept is easier to understand visually, use compact HTML, a Markdown table, or a diagram.
+- Use HTML for comparisons, flows, state changes, hierarchies, or decision dashboards where layout improves understanding.
+- Keep HTML self-contained, accessible, and minimal; avoid decorative complexity.
+- Use plain text when it is clearer or the user asked for a concise answer.
+
+## Implementation Map
+
+- For the detailed `IMPLEMENTATION_MAP.html` construction rules and the SVG service-blueprint spec, read and use `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/implementation-map.md` as a scoped extension of this section.
+- In repos with implementation code, when architecture, goals, or roadmap context would help future work, maintain `IMPLEMENTATION_MAP.html` as a current-state dashboard — not a changelog, handoff log, or project diary — and update it before committing, when writing a handoff, or after meaningful architecture, roadmap, risk, decision, or verification changes.

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

@@ -0,0 +1,194 @@
+---
+guide_id: cli-multi-model-workflow
+language: en
+status: active
+use_when:
+  - work spans multiple models or CLI agents
+  - a handoff crosses a context reset, or parallel worktree branches run
+  - running unattended LLM batches or orchestrated subagent fleets
+  - allocating tiers, spawning subagents, or planning model switches
+  - resuming a halted staged pipeline or writing a handoff
+---
+
+# CLI Multi-Model Workflow
+
+Scoped extension of the global Multi-Model Workflow rules. Rules use portable role slots; only **Driving Codex CLI Directly** and **Environment Binding** name concrete tools or models.
+
+## When To Use
+
+- Use for multiple models/agents, handoffs across clear/new sessions, unattended fleets, or parallel worktrees. Routine auto-compaction is not a handoff.
+- Skip single-session, single-model work with no handoff.
+
+## Role Slots And Tiers
+
+- FRONTIER: hardest bounded design, authority-changing decisions, triage, final verdicts.
+- HELM: standing main/judgment seat; orchestration and bounded escalation.
+- WORKHORSE: implementation volume and per-item judgments. SWEEP: cheap wide reads, candidate finding, mechanical passes.
+- VERIFIER-A/B: different review kinds, preferably cross-family. INDEPENDENT-PR-REVIEWER: final review from a different family than the author.
+
+- Bind concrete models in Environment Binding and allocate by **difficulty × blast radius**. The main defaults to HELM; first-of-kind/authority-changing mains use FRONTIER at a session boundary; trivial work stays direct.
+- Apply the same allocation to subagents. Prefer spawning a bounded FRONTIER judgment over switching the loaded main; a context cannot switch its own model.
+- Keep architecture, interfaces, scope, tradeoffs, and user-facing decisions in the main. Delegate volume work.
+- A cheaper implementation tier requires stronger verification; never economize on both.
+
+## When To Spawn
+
+Main-context pollution is usually costlier than spawn overhead. Apply these gates in order; the first that fires decides:
+
+1. **Independence:** verification or review always spawns; isolation is the purpose.
+2. **Parallelism:** independent items spawn in parallel with per-item tracking.
+3. **Residual context:** spawn work whose working log is much larger than the conclusion the main needs, such as broad reads, searches, tests, or implementation bursts.
+4. **Specifiability:** keep work local when it needs the main's live context or unresolved round-trips, especially deep debugging. Grind alone is not a FRONTIER reason.
+5. **De-minimis:** do work directly when its dispatch packet would be larger than the work.
+
+- Escalate by spawning FRONTIER first; switch the main only when the judgment is not delegable.
+- Every spawn gets a bounded report contract, artifact paths instead of pasted context, and an explicit model/effort pin. Never dump a worker transcript into the main.
+- Explicit no-fan-out overrides standing authorization.
+
+## Delegation Mechanics And Teammate Persistence
+
+Delegate execution, not decisions. A unit is delegable only when it is decision-complete, self-containedly specifiable, machine-checkable at done-when, and bounded in blast radius.
+
+- Re-cut units containing unresolved choice, discovery-before-spec, untestable completion, or unfrozen interfaces. A worker asking which direction to take is a sizing failure; the decision returns to the main.
+- Bundle related sub-floor tasks up to the decision-complete ceiling. A scout is read-only and reports file:line evidence for named pending decisions, probing the highest kill-risk unknown first.
+- Prompt constants, thresholds, signatures, and judgment criteria are decisions even when stored in code. Discard decision-tainted worker output when review would cost more than a clean re-dispatch.
+- Worker cost grows with request count × transcript prefix. Batch independent reads, minimize edit rounds, and dispatch independent workers/messages together.
+- 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.
+- Review cost scales with the diff, so layered review preserves delegation savings. Lower reviewer tier before dropping a review kind.
+
+## Driving Codex CLI Directly
+
+Instruction/config reach is per invocation. A rule in AGENTS.md cannot bind a hermetic worker; put required hermetic rules in its prompt/schema.
+
+| Profile | Reach | Use |
+|---|---|---|
+| inherit | real `CODEX_HOME`, project cwd | full global/project AGENTS.md and user config |
+| hermetic | temporary home, auth only, user config ignored | independent lens with prompt-owned criteria |
+| custom | caller-populated home | exact curated instructions/config |
+
+- Control instruction home, working directory, config overrides, task prompt, and output schema independently. The repo wrapper owns setup and teardown.
+- Inherit review is discipline-aware; hermetic review is an independent kind. Confirm reach with a contrast phrase from AGENTS.md before trusting independence.
+- Concrete flags, versions, sandbox defaults, and dispatch bindings live in Environment Binding.
+
+## Default Frame
+
+| Stage | Owner | Artifact / exit |
+|---|---|---|
+| 0 Triage | current session | difficulty/blast-radius call; dials fixed |
+| 1 Design | FRONTIER | dated design with measured background, done-when, concept map, allocation; owner approval |
+| 2 Design verify | VERIFIER-A+B | findings union and revision; zero material issues |
+| 3 Implement | WORKHORSE | smallest viable diff; deterministic gates green |
+| 4 Implementation verify | SWEEP → WORKHORSE → FRONTIER | at least two reviewer kinds; strongest model on verdicts |
+| 5 PR review | INDEPENDENT-PR-REVIEWER | clean cross-family review |
+| 6 Merge verify | implementing session | freshly fetched merged state green |
+| 7 Close | current session | docs/handoff synced; no silently parked items |
+
+- A T1+ kickoff names the session model, orchestration authorization, this guide, and main-as-orchestrator delegation mode.
+- T0 mechanical/low-risk uses stages 3→4 (→5 for shared merge); T1 normal work uses the full skeleton with a lightweight design; T2 authority-changing/first-of-kind/release work raises design and verdict review.
+- Put stage transitions on context-reset boundaries so model changes are free and the design doubles as handoff. Keep a loaded session only when live state is load-bearing.
+- Apply the **convergence heuristic by reviewer kind**: same-kind convergence raises confidence but shares blind spots; different-kind divergence is expected, so act on the union.
+- If verification broadens the issue boundary, return to design and re-triage; the second identical loopback stops for owner choice. Halts resume from valid artifacts. Persist per-item outcomes.
+
+## Model Switching And The Prompt Cache
+
+- Prompt caches are per model; each mid-session switch reprocesses the loaded transcript once. Batch work by model and switch at reset boundaries.
+- Prefer a spawned FRONTIER decision. Switch the main only when context fidelity outweighs handoff cost and the judgment cannot be delegated.
+- Avoid unplanned alternation. Planned escalate/return and explicit A/B comparisons are valid when each cache miss is budgeted.
+
+## Cross-Verification Economy
+
+- Once cross-verification is warranted, keep kind diversity and tune effort first. Losing a kind loses an error class.
+- Run deterministic gates before LLM review. Funnel SWEEP finders → WORKHORSE judgments → FRONTIER triage/verdicts.
+- On family collapse, record the downgrade and label clean verdicts PROPOSED until diversity is restored.
+- A silent/dead lens is incomplete, never clean. Confirm liveness from usage/error/report evidence; rerun, swap provider, or report PROPOSED.
+
+## Unattended Batch Safety
+
+- The parent owns per-item completion and a **code-level circuit breaker**. For dispatchers you do not control, verify equivalent protection or attend the run.
+- Default breaker: halt after 3 consecutive cross-item provider limit/auth/transport failures after bounded backoff. Persist undone items and alert or swap provider.
+- Item-specific failures are poison items: cap at 2–3 attempts, then dead-letter them as complete-with-failure. Resume only unfinished/invalid items; whole-batch reruns require cheap idempotence.
+- Persist per-item outcome, token, and cost records for recalibration.
+
+## Halt And Resume
+
+- Resume-first from artifacts that parse, pass schema, and match their recorded source/config/HEAD fingerprint; unverifiable means invalid.
+- Resubmit one invalid unit unless failures are broadly correlated, which is structural and halts the run.
+- Treat halt→continue as normal operation.
+
+## Sessions, Branches, Worktrees
+
+- Sessions bind to their starting directory. Use the CLI's native relocation/resume mechanism; never copy transcript files.
+- For a new worktree, relocate natively or write a handoff and start fresh. Re-integrate branches serially and re-verify after each merge.
+- Mark superseded worktrees/handoffs dead so later resume cannot select them.
+- After resume/clear/relocation, verify pwd, branch, and HEAD against the pinned handoff before acting.
+
+## Handoff Contract
+
+Write for the next agent and re-verification, not narrative. Required content:
+
+1. One-line current state.
+2. Pinned worktree, branch, HEAD, upstream/merge-base, author tier, and active fallback/family collapse.
+3. CONFIRMED claims whose cited command or anchored file evidence independently re-establishes them.
+4. Separate PROPOSED/OPEN items, including inherited claims not re-verified this session.
+5. Ordered next actions and the literal first command: model, orchestration authorization, and guide load for T1+.
+6. Credentials only by env-var/gitignored slot; scrub secrets from excerpts and commands.
+
+- A broken evidence anchor demotes CONFIRMED to PROPOSED. If pinned state fails or no trustworthy handoff exists, rebuild from source artifacts and write a fresh handoff before acting.
+- Store handoffs in the working repo's isolated dated docs path, never this instruction-SSOT repo. Re-verify load-bearing claims on resume.
+
+## 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.
+
+Binding (2026-07-13):
+
+| Slot | Binding | Notes |
+|---|---|---|
+| FRONTIER | Claude Fable 5 · GPT-5.6 Sol (read-only; max default, task-fit effort including Ultra) | bounded hardest decisions and verdicts |
+| HELM | Claude Opus 4.8 (xhigh) · GPT-5.6 Sol (xhigh main; main Ultra requires explicit selection; bounded FRONTIER Ultra allowed) | standing main; Codex defaults bypass, explicit sandbox narrows |
+| WORKHORSE | Claude Sonnet 5 · GPT-5.6 Terra (high) | implementation and per-item judgment |
+| SWEEP | Claude Haiku 4.5 · GPT-5.6 Luna (low) | clear repeatable scans and mechanical work |
+| VERIFIER-A | onto-mcp review | logic/authority kind; tier units per funnel |
+| VERIFIER-B | `ultracode-for-codex` CLI v0.4.5 (Codex-backed; callable from Claude or Codex) | code/execution kind |
+| INDEPENDENT-PR-REVIEWER | Codex CLI | adversarial `gh pr diff` review |
+| Claude relocation | EnterWorktree, `/cd`, `--worktree`; resume is directory-scoped | verified 2.1.207 |
+| Codex relocation | `codex resume` (cwd-filtered; `--all` lifts), fork | verified 0.144.1 |
+| Claude teammate | named mailbox continuation; completed-agent message may cold-rerun on main model | keep resident; avoid completed resume |
+| Rate-limit fallback | OpenAI limited → VERIFIER-A on Anthropic; Claude limited → VERIFIER-B on Codex | record family collapse |
+
+Codex direct-drive (verified 0.144.1, 2026-07-12):
+
+- `codex-helm` defaults the HELM main to `--dangerously-bypass-approvals-and-sandbox`; explicit `--sandbox` wins in any flag order. Non-Ultra defaults native multi-agent off; explicit main Ultra defaults it on.
+- 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.
+
+Dispatch packets:
+
+| Target | Required packet / default |
+|---|---|
+| GPT-5.6 Sol FRONTIER | outcome, evidence, decision boundary, stop/verification; task-fit effort; read-only |
+| GPT-5.6 Terra WORKHORSE | outcome, frozen scope/inputs, authority, done-when, evidence/report, escalation; high |
+| GPT-5.6 Luna SWEEP | exact search space, rules, ambiguity behavior, stop, output; low; no architecture/debugging |
+| Claude Opus 4.8 HELM | xhigh for agentic work; high minimum for sensitive judgment; lower only when bounded/cost-led |
+| Claude Sonnet 5 WORKHORSE | exact scope, apply-to-all rules, tools, verification, report; high default |
+| Claude Haiku 4.5 SWEEP | closed, high-volume, latency-sensitive work with exact schema/examples |
+
+Use only task-relevant tools; parallelize independent calls. Worker report: `status`, `files_or_items_touched`, `evidence`, `verification`, `risks_or_escalations`. Official basis: OpenAI [model](https://developers.openai.com/api/docs/guides/latest-model?model=gpt-5.6), [migration](https://developers.openai.com/api/docs/guides/upgrading-to-gpt-5p6-sol), [prompting](https://developers.openai.com/api/docs/guides/prompt-guidance-gpt-5p6), [Codex models](https://learn.chatgpt.com/docs/models); Anthropic [subagents](https://code.claude.com/docs/en/sub-agents), [model effort](https://code.claude.com/docs/en/model-config).
+
+## Evidence Base
+
+Single owner of numeric defaults; one production environment, 2026-07. Recalibration updates this table and dependent inline thresholds.
+
+| Evidence | Result / rule supported |
+|---|---|
+| 15 sessions, 3,758 requests, 10 switches | switches consumed 13.9% of uncached input; avoid unplanned switching |
+| 285-call limit incident | 208 post-limit dispatches and 34/35 lost items; breaker default 3 |
+| 99 staged reviews | 15.2% halted after most compute; resume-first |
+| three-task delegation probe | batched worker 5 requests/$0.23 vs loaded FRONTIER direct 6/$3.35; cache TTL 5 min; completed resume cost 2–5× |
+| two live delegation sessions | tiering saved ~3.3×; discarded prefixes made fresh respawn cheaper; unpinned reviewers inherited FRONTIER |
+| Codex reach contrast | inherit ~16.5K vs hermetic ~8.7K tokens; schema and stdout/stderr contract verified |
+| Codex native-spawn probe + HELM E2E | requested max/Ultra native children recorded xhigh/role null; separate read-only roots recorded max and Ultra successfully |