agent-bios 0.1.0 → 0.2.0

package/DEPENDENCIES.md

@@ -1,6 +1,6 @@
 # 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.
+What agent-bios' 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.
 
@@ -36,9 +36,9 @@ Concrete role-slot→model bindings live only in each guide's `Environment Bindi
 
 ## 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.
+- **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** — evaluated (inherits real `~/.codex`; gpt-5.4-era prompting), **not adopted**; `scripts/codex-run.sh` is preferred for controlled reach.
+- **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.
 - **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.
 
@@ -62,10 +62,11 @@ claude --version; claude --help | grep -E -- '--model|--effort|--agents|--append
 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
+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
 python3 - <<'PY'
 import os, pathlib, tomllib
 roots = [pathlib.Path("codex/agents"), pathlib.Path(os.environ.get("CODEX_HOME", pathlib.Path.home() / ".codex")) / "agents"]

package/README.md

@@ -1,4 +1,4 @@
-# agent-dotfiles
+# agent-bios
 
 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.
 
@@ -67,7 +67,7 @@ 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.
+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 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.
 
 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.
 

package/claude/CLAUDE.md

@@ -87,6 +87,7 @@
 
 ## 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.
@@ -111,6 +112,7 @@
 ## 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.
+- 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.
 - Never retry-storm a live rate limit: give unattended batches you author a code-level circuit breaker with per-item completion tracking (thresholds, backoff, and dead-letter rules in the guide); for third-party dispatchers, confirm equivalent protection exists or attend the run.
 - On any resumed, cleared, or relocated session, re-verify where you are (pwd; in a repo, branch and HEAD) before acting on prior-session assumptions — against the pinned handoff state when one exists.

package/claude/guides/claude-prompting.md

@@ -0,0 +1,123 @@
+---
+guide_id: claude-prompting
+language: en
+status: active
+use_when:
+  - composing a prompt, packet, or tool description for a claude-family model
+  - dispatching cross-family review to the claude side from a Codex main
+  - prompting claude subagents, or prompting yourself when the main is Claude
+  - porting a prompt written for an older claude model
+  - deciding a reasoning-effort level for claude work
+core_rules:
+  - state the goal, the constraints, and the reason behind the request; let the model choose the route
+  - de-prescribe ported prompts — step-by-step scaffolding written for older models reduces output quality on this tier
+  - put the full task specification in the first turn for long-horizon work rather than revealing it across turns
+  - make tool descriptions prescriptive about when to call, not only what the tool does
+  - require progress claims to be audited against a tool result from the same session
+  - name the boundary explicitly — what to do without asking, and what to stop and ask about
+targets:
+  - claude-fable-5
+  - claude-opus-4-8
+  - claude-sonnet-5
+  - claude-haiku-4-5
+verification_focus:
+  - prompt changes are A/B'd against the prior scaffolding rather than assumed
+  - effort changes are swept across levels on a real eval set, not chosen by reputation
+  - per-model constraints are confirmed against the live surface before use
+---
+
+# Claude Prompting Guide
+
+This guide is a scoped extension of the global Coding Guidelines. Use it when
+composing a prompt for a claude-tier model — a review packet dispatched
+cross-family, a subagent brief, or the main's own instructions when the main is
+Claude.
+
+The central shift: this tier is more autonomous and more literal than its
+predecessors, and prompts written for older models are often too prescriptive —
+they measurably reduce output quality. Porting a prompt means removing
+scaffolding, not adding to it. State the goal and the constraints; let the model
+pick the path.
+
+## Default prompt recipe
+
+- `Goal` and the **reason behind it** — this tier connects a task to relevant
+  context when it knows the intent, instead of inferring intent on its own.
+  "I'm doing X for Y, who needs Z; with that in mind: …" outperforms the bare
+  request, most of all for long-running agents holding several workstreams.
+- `Success criteria` — what done means and how it is checked.
+- `Constraints and boundaries` — say what not to do. This tier sometimes takes
+  unrequested-but-adjacent actions; naming the boundary is the fix.
+- `Tools` — each description states **when to call it**, not only what it does.
+  Prescriptive trigger conditions give measurable lift here.
+- `Output` — the artifact shape and the register.
+
+## When to add blocks
+
+- Long-horizon or autonomous work: give the full spec up front in one
+  well-specified turn and run at a high effort. Add an explicit self-check
+  cadence; separate fresh-context verifier subagents beat self-critique.
+- Review: state the evidence bar and the verdict shape. This tier follows
+  severity filters literally, so "only report high-severity" depresses measured
+  recall even as bug-finding improves — ask for every finding with confidence
+  and severity attached, and filter downstream.
+- Delegation: say when to delegate. Left unprompted this tier under-reaches for
+  subagents, file-based memory, and custom tools — it will not spend an
+  expensive capability unless it is reasonably sure the capability is needed.
+- Autonomous runs with no human watching: say so. Otherwise it asks permission
+  it does not need and blocks. Grant autonomy on minor choices (naming,
+  defaults, equivalent approaches) while keeping the ask for scope changes and
+  destructive actions.
+- Progress reporting: require each claim to be traceable to a tool result from
+  the session, and unverified work to be labeled as such.
+
+## How to choose prompt shape
+
+- One bounded question with a self-contained packet → a single run. Default for
+  review.
+- Independent workstreams → delegate, and prefer asynchronous subagents over
+  spawn-and-block: long-lived agents keep their context instead of rebuilding it
+  per subtask, and the orchestrator is not pinned to the slowest one.
+- Effort ladder — `low`, `medium`, `high`, `xhigh`, `max` on the frontier, helm,
+  and workhorse bindings; `xhigh` is the best setting for most coding and
+  agentic work, `high` a sound default, `low` for cheap subagent scans. Sweep the
+  levels on a real eval set rather than reaching for the top: higher effort up
+  front often *reduces* turn count and total cost on agentic work, while some
+  tasks land equally well a level down.
+- Per-model constraints differ across the `targets` bindings — thinking
+  configuration, sampling parameters, and effort support are not uniform, and
+  the sweep binding is the most restricted. Confirm the constraint against the
+  live surface before relying on it in a dispatch; do not assume the frontier
+  binding's rules apply to the sweep one.
+
+## Working rules
+
+- Expect long turns. A single request on a hard task at high effort can run for
+  minutes; plan timeouts, streaming, and progress UX around that rather than
+  treating a quiet call as a hang.
+- Do not add "summarize every N tool calls" scaffolding — this tier narrates on
+  its own. If it narrates too much for a coding agent, set a silence default
+  instead: text only on a finding, a direction change, or a blocker.
+- Give it somewhere to write learnings, tell it to consult that place later, and
+  give the file a format. It performs notably better with a memory surface.
+- Keep the deliverable readable: the final message is the reader's first look at
+  work they did not watch. Lead with the outcome; drop the working shorthand.
+- Do not show a remaining-context countdown. This tier can start conserving and
+  suggest a fresh session instead of finishing.
+
+## Prompt assembly checklist
+
+1. Write the goal, the reason behind it, and the success criteria.
+2. Name the boundaries — what to do freely, what to stop and ask about.
+3. Give each tool a when-to-call description.
+4. Say how progress claims must be grounded, and how the deliverable should read.
+5. Delete the step-by-step scaffolding inherited from older models, then A/B the
+   prompt with it removed before keeping either version.
+
+## Sources
+
+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
+binds a model this guide does not list.

package/claude/guides/gpt-prompting.md

@@ -0,0 +1,118 @@
+---
+guide_id: gpt-prompting
+language: en
+status: active
+use_when:
+  - composing a prompt, packet, or tool description for a gpt-family model
+  - dispatching cross-family review to the gpt side from a Claude main
+  - prompting gpt subagents, or prompting yourself when the main is Codex
+  - porting a prompt written for an older gpt model
+  - deciding a reasoning-effort level for gpt work
+core_rules:
+  - describe the destination, not the route — state outcome, success bar, real constraints, and available evidence
+  - simplify before adding; remove one group of instructions, examples, or tools at a time and re-run the same evals
+  - keep only what changes behavior; cut repeated statements, style rules, and examples that do not
+  - replace blanket ALWAYS/NEVER with decision rules naming the condition each choice applies under
+  - fix the prompt before raising effort — weak output usually means a missing success criterion, dependency rule, tool-routing rule, or verification loop
+  - prompting habits carried from older gpt models cost tokens and can cost accuracy
+targets:
+  - gpt-5.6-sol
+  - gpt-5.6-terra
+  - gpt-5.6-luna
+verification_focus:
+  - prompt changes are validated by re-running the same evals, not by inspection
+  - removals are tested one group at a time so the cause of a delta is known
+  - effort changes are compared against the baseline and one level lower
+---
+
+# GPT Prompting Guide
+
+This guide is a scoped extension of the global Coding Guidelines. Use it when
+composing a prompt for a gpt-tier model — a review packet dispatched
+cross-family, a subagent brief, or the main's own instructions when the main is
+Codex.
+
+The current gpt tier is more concise and more self-directing than its
+predecessors, so the failure mode has inverted: the usual defect is now an
+over-specified prompt, not an under-specified one. Leaner system prompts
+measured roughly +10–15% eval score at 41–66% fewer tokens and 33–67% lower
+cost in the vendor's own coding-agent sample — directional, and worth
+validating on your own workload rather than taking on faith.
+
+## Default prompt recipe
+
+Compose in this order; omit any block that would not change the artifact.
+
+- `Role` and `Personality` — who is acting and in what register. Omit
+  personality when it does not change the output.
+- `Goal` and `Success criteria` — the outcome, and the bar that decides done.
+  This is the block most worth its tokens; write it first. If you cannot state
+  the bar, the prompt is not ready.
+- `Constraints` — safety, business, and scope limits that must hold. Real
+  constraints only; preferences belong in output shape or nowhere.
+- `Tools` — only task-relevant ones. Each description states what it does, when
+  to use it, its important return fields, and its error behavior.
+- `Output` — the artifact shape. `Stop rules` — when to stop looping and answer.
+
+## When to add blocks
+
+- Coding and debugging: name the validation to run after changes — targeted
+  tests for the changed behavior, type/lint checks, build, a minimal smoke test.
+  Require prerequisite lookups before edits.
+- Review: no vendor task guidance exists for review specifically. Carry the
+  general rules and be explicit about the evidence bar and the verdict shape; a
+  reviewer with no stated bar defaults to plausible-sounding findings.
+- Research and grounded work: cite only retrieved sources, attach citations to
+  the claims they support, and label inference separately from supported fact.
+  Say to narrow the answer or report missing evidence rather than guess.
+- Write-capable work: name the safe actions explicitly (read files, edit code,
+  run tests) and require confirmation for external writes, destructive actions,
+  or scope expansion.
+- Implementation plans: requirements, named resources, state transitions,
+  validation checks, failure behavior, privacy/security, open questions.
+
+## How to choose prompt shape
+
+- One bounded question with a self-contained packet → a single hermetic run.
+  This is the default for review.
+- Work that divides into independent workstreams → fan-out. Parallelize
+  independent reads; keep dependent steps sequential.
+- Effort ladder — `none`, `low`, `medium`, `high`, `xhigh`, `max` are all valid.
+  Hold the current binding as the baseline, then test it and one level lower on
+  representative tasks: `low` for latency-sensitive work, `medium` as the
+  balanced default, `high`/`xhigh` only where evals show real gain, `max`
+  reserved for the hardest quality-first work and compared against `xhigh`.
+- Prefer a self-contained packet over resuming a long history: it is cheaper to
+  reason about and cheaper to cache.
+
+## Working rules
+
+- One clear task per run, with an explicit output contract.
+- Keep reusable prefixes stable and avoid churn in large system prompts. Add
+  explicit cache breakpoints only where they measurably improve cache behavior —
+  a cache write costs 1.25× the uncached input rate, so read the cached-token
+  and cache-write counters before adding one.
+- Do not say "be concise" reflexively. This tier is concise by default, and the
+  instruction can push responses past useful into thin.
+- After each tool result, ask whether the core request can now be answered with
+  useful evidence. If yes, answer.
+- Render any visual artifact before finalizing; inspect layout, clipping,
+  spacing, and missing content.
+
+## Prompt assembly checklist
+
+1. Write the success criteria first.
+2. Add role, goal, real constraints, and the output shape.
+3. Add only the tools the task needs, each with when-to-use and error behavior.
+4. Add stop rules and the verification the task must pass.
+5. Delete every line that would not change the artifact if removed, then re-read
+   for instructions inherited from older-model habits.
+
+## Sources
+
+Derived from the vendor's published prompting guidance for the `targets` models
+above. When a `targets` model changes, re-derive this guide from current vendor
+guidance rather than editing around the old rules — prompting guidance is
+version-bound, and the previous generation's advice inverted on this one.
+`scripts/check-prompting-targets.sh` fails when the launch config binds a model
+this guide does not list.

package/claude/guides/review-request.md

@@ -0,0 +1,266 @@
+---
+guide_id: review-request
+language: en
+status: active
+use_when:
+  - writing a review request, packet, or reviewer role for any model
+  - deciding what evidence bar and verdict shape to demand from a reviewer
+  - triaging why a review returned noise, nothing, or a clean bill of health
+  - choosing which perspectives to run and whether to pay for deliberation
+core_rules:
+  - demand a failure path, not a gap — "X is unverified" dies, "X breaks when Y" survives
+  - require every finding to anchor to file:line, and every empty result to cite what was checked
+  - say what the target is and is not — stage, boundary, and what absence means
+  - bundle the consumer the target depends on, or its most load-bearing claim is unreviewable
+  - forbid carry-forward findings — anything phrased "watch" or "document later" is not a finding
+  - read participation before believing a verdict; a crashed harness reports zero findings
+  - treat a finding's causal attribution as the reviewer's weakest claim, not its severity
+verification_focus:
+  - a zero-findings verdict is confirmed against participation, not accepted at face value
+  - findings are checked for a stated failure path before they are acted on
+  - an empty result is trusted only when it cites the evidence it checked
+---
+
+# Review Request Guide
+
+This guide is a scoped extension of the global Coding Guidelines. Use it when
+composing what you ask a reviewer for — the request, the evidence bar, the
+verdict shape. It does not cover when to review, how deep, or what counts as
+material (the staged-workflow guide's severity ladder and review loop own that),
+which reviewer kind to route to (the multi-model guide's convergence heuristic),
+or how to phrase a prompt for a given model family (the per-family prompting
+guides).
+
+The rules below are derived from ~330 real multi-lens review sessions run in
+this environment. That corpus is one model family in practice, so nothing here
+is a per-model claim; these are the failures that persist regardless of who
+reviews. Every rule names the evidence behind it, because a review guide that
+asserts without evidence would fail its own bar.
+
+## Demand a failure path, not a gap
+
+The dominant reviewer failure is not hallucination. Across 372 rejected
+findings, "asserted a gap without demonstrating a failure" accounts for the
+largest share (~34%), while misreading correct code accounts for **one** case
+and speculation for seven. Reviewers do not invent defects — they report
+unverified things and call them findings.
+
+The corpus separates these cleanly by how the finding is framed:
+
+| Framed as | Dropped |
+|---|---|
+| `evidence_gap` — "not covered / not verified" | 94% (n=143) |
+| `needs_evidence` | 93% (n=118) |
+| `document_only` | 92% (n=144) |
+| `root_cause` — a defect with a cause | 3% (n=878) |
+| `fix_now` | 3% (n=1026) |
+
+So say it in the request: **state the input, the branch, and the observable
+wrong behavior. "X is not verified" is not a finding; "X breaks when Y" is.**
+A reviewer that cannot show the failure should say so as a boundary note, not
+file it against the target.
+
+## Set a severity floor, because low never survives
+
+Severity is the single most decisive predictor in the corpus, and it is close to
+deterministic:
+
+| Severity | Reaches the deliverable |
+|---|---|
+| `blocker` (n=16) | 100% |
+| `high` (n=366) | 96% |
+| `medium` (n=1338) | 92% |
+| `info` (n=44) | 5% |
+| `low` (n=226) | **0%** |
+
+Not one low-severity finding out of 226 survived. The tokens that produced them
+were spent for nothing, twice — once writing, once reading.
+
+So state the floor in the request: **do not report a finding you would rate low.
+It will be discarded; spend the effort on a medium-or-above finding instead.**
+This is not a quality bar on the reviewer, it is a cost decision — the corpus
+shows the discard happens regardless, so the only question is whether you pay to
+generate it first. (What counts as each severity is the staged-workflow guide's
+ladder, not this guide's.)
+
+## Forbid carry-forward findings
+
+Every finding the corpus classified as deferrable died: `planned_later` 100%
+(n=104), `watch` 100% (n=36), `defer_watch` 97% (n=71), `out_of_scope` 92%
+(n=26). Not one survived to the deliverable.
+
+Ask only for what must change in this target now. Anything the reviewer would
+phrase as "carry forward", "watch", or "document later" costs tokens to produce,
+tokens to read, and is discarded — say that up front so it is never written.
+
+## Say what the target is, and what absence means
+
+The most common thing reviewers report they lacked is the stage context: they
+review a design and cannot see the implementation, then hedge every finding into
+a design-contract claim. Their own words, recurring across sessions: *"The packet
+reviews a design, not an implemented patch, so the exact future API is not
+visible."*
+
+Name the stage and say what absence means — "this is a pre-implementation
+design; do not treat missing implementation as a defect." A session given exactly
+that instruction returned zero findings and proved it had looked, anchored on
+both sides of the comparison. A session not given it filed unimplemented code as
+blockers, and the user caught it manually.
+
+## Bundle the consumer, not just the artifact
+
+When a target says "see X", X is part of the target. The corpus's sharpest
+example: a reviewer identified the most load-bearing connection in a design and
+then could not review it — *"§6.4 is outside the review boundary, so
+axis-consumption completeness cannot be verified within the artifact."* The
+request bundled the child and not the parent it depended on.
+
+What reviewers needed, almost every time, was the consumer: the code that reads
+the field, the parent doc defining the weights, the log proving the behavior. If
+a claim's evidence lives outside the boundary, either widen the boundary or
+accept that the claim is unreviewable — do not expect a finding about it.
+
+## Make evidence structural, not requested
+
+In this corpus every finding carries a `file:line` anchor and every empty result
+carries a rationale — 2,466/2,466 and 981/981. Not because the prompts asked
+nicely: the submit schema refuses output without them. The result is a corpus
+where reviewers are right about existence (0.3% of issues end unresolved after
+argument) and where "found nothing" is a verified statement rather than silence.
+
+This is the general rule from the capability-boundary guide applied to review:
+when output must have a property, make it unavailable without it. If your review
+route has a schema, put the anchor there. If it does not, the demand belongs in
+the request — but expect the weaker result that a request-only rule gives you.
+
+The same applies to the target: a document that cites its own facts as
+`file:line` gives the reviewer a falsifiable surface, and the corpus's best
+findings are refutations of exactly those cited facts. Prose gives nothing to
+check.
+
+## Claim only what the evidence proves, and attribute it to one root
+
+Reviewers are calibrated on whether a defect exists and miscalibrated on why.
+When a finding is narrowed, the defect itself almost always survives (97%,
+n=212). What gets cut is the causal attribution (45%) or the surface the claim
+covered (34%) — not the proposed fix (10%), and not the defect. Lenses register
+this as a first-class stance: `narrow` appears 1,320 times against 101 for
+`oppose`. They rarely disagree that something is broken; they routinely disagree
+about what broke it, and about how much of the system it touches.
+
+"Narrowed" is a misleading name for what happens. Narrowed claims get **longer**
+— 94% of them, by a median of ~118 characters — because narrowing adds
+qualification and re-attribution rather than deleting text. The final root cause
+is a near-rewrite (median text similarity 0.21 against the original). What looks
+like trimming is the reviewer being made to say what its evidence actually
+supports.
+
+That makes narrowing and rejection the same force at different granularity:
+overclaim beyond your evidence and the finding is narrowed if a proven core
+exists, dropped if it does not. The corpus language is identical in both — the
+survivors are "narrowed to the directly evidenced command-wiring gap", "to files
+proven in capsule authority_refs", "to the demonstrated side-effect path".
+
+So ask for the observable failure and the evidence that proves it, scoped to the
+surface that evidence covers. Treat the reviewer's causal story as its weakest
+claim — a hypothesis to verify, not a conclusion — and do not let a proposed fix
+become the design by default.
+
+One axis is easy to miss: in ~17% of narrowings every lens accepts the defect,
+the root, and the fix, and the only live disagreement is **how bad it is**. That
+matters more than its share suggests, because severity decides survival — a
+finding rated low never reaches the deliverable. If severity is contested, it is
+the thing to adjudicate, not a detail to average out.
+
+## Read participation before believing a verdict
+
+Seven sessions reported `Finding count: 0` — a clean bill of health — with
+`Participating lenses: 0/N`. Nothing was reviewed. And when the harness dies, two
+separate channels lie about why. Twenty-two sessions recorded
+`failure_kind: output_contract`; in the ones whose nested stderr is readable the
+cause is a provider usage-limit rejection — *"You've hit your usage limit"*,
+`exit=1`, no model output produced at all — so the label blames the model's
+output format for a pre-dispatch billing refusal, when no output ever existed to
+violate a contract. Triage by that label and you debug the prompt when you needed
+to buy credits.
+
+Two consequences for anyone consuming a review:
+
+- The tell is the participation count and execution status, never the severity
+  counts. A crashed harness renders as a perfect score.
+- Artifacts named for failure may not carry it, and the two failures compound. In
+  those same quota-killed sessions the file named `environment-warnings.yaml`
+  recorded only `non_fatal` dispatch traces with `outputTrustImpact: unknown` and
+  never once mentioned the quota; corpus-wide it holds ~9,800 warnings and has
+  never fired on a real failure. So the channel named for failures never fires,
+  the channel that fires uses the wrong name, and the truth is only in the nested
+  stderr. Read the channel the mechanism actually writes, confirmed against the
+  low-level log, not the one named for the thing you want.
+- A review deliverable names the findings it *rejected* as well as the ones it
+  kept, so a finding's presence in the document is not its survival. Deriving
+  survival from presence returns 100% by construction — it did here, until the
+  count was scoped to the material section, at which point 16% of the same
+  findings turned out to have reached the reader explicitly flagged
+  non-material. Read the verdict field, not the mention.
+
+## Trust an empty result only when it cites what it checked
+
+Empty is common and usually correct: 42% of lens invocations produce nothing,
+and those runs have *larger* inputs and sit *later* in a repo's review sequence
+than productive ones — they are re-reviews of targets already fixed. The waste
+worth naming is not the empty result; it is paying full pipeline cost to
+re-review something you already repaired.
+
+An empty result earns trust from its rationale. A reasoned null names the
+evidence it checked on both sides of the comparison. A rationale-free empty
+result is a failed run wearing a clean verdict — gate on the rationale, not on
+the emptiness.
+
+## Spend deliberation where it adjudicates, not where it agrees
+
+Two-thirds of issues (66%, n=1153) never need deliberation, and the largest
+single cause of halted sessions is the user cancelling. But they do not cancel
+early: of 27 cancelled sessions all 27 reached the raw first pass, 22 reached the
+consolidated finding ledger, and only 2 reached deliberation. Users wait for the
+deduplicated, severity-tagged ledger, act on it, and abandon the deliberation and
+synthesis that would have run next. Meanwhile the issues that *are* deliberated
+and survive are the most reliable in the corpus (94% material vs 74% for
+undeliberated).
+
+So deliberation is worth its cost when it adjudicates a contested claim, and is
+ceremony when every perspective already agrees — one of the largest deliberation
+artifacts in the corpus resolved 22 of 22 issues as "no deliberation needed".
+Front-load the actionable findings, because that is the part that gets used.
+
+## Choose perspectives that can bite
+
+Adding a perspective is not free. In this corpus the concept-surface lens
+produces the fewest findings, is silent most often, and half of what it does
+produce is discarded — because 43% of its candidates are rated low, and low
+never survives. Naming, redundancy, and abstraction concerns count only when
+they change runtime behavior or enforced semantics; ask for them on that
+condition or not at all.
+
+The inverse failure is worth watching for: when no perspective owns the real
+risk, a reviewer files a governance gap instead of a defect — *"this is a
+review-governance gap, not a design defect in the target."* That is the review
+telling you its own lens set was wrong for the target.
+
+## Evidence base
+
+Derived 2026-07-16 from ~330 onto review sessions across 15 repositories in this
+environment (1,738 classified issues; 2,466 anchored findings; 278 deliberations;
+14,370 lens stances). Every count here was reproduced independently before being
+written down, and several first attempts were wrong: survival measured by
+document presence returns 100% by construction, and hand-rolled verb-object
+counting undercounted the narrowing axes about fivefold. Where a share is given
+for how narrowing splits, read it as a floor — ~19% of cases resist
+classification — and trust the ordering (root > scope > severity > remedy) rather
+than the magnitudes.
+
+Two limits bound what this guide may claim. The corpus is ~95% a single model
+family, so nothing here is a per-model claim. And it contains no under-specified
+requests — the shortest still names its axes and its evidence bar — so these are
+the failures that survive a *good* request, not an argument that requests need
+specifying. Re-derive from a fresh corpus when the review route or the bound
+models change.

package/codex/AGENTS.md

@@ -87,6 +87,7 @@
 
 ## 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 `${CODEX_HOME:-$HOME/.codex}/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.
@@ -112,6 +113,7 @@
 
 - Codex-only standing authorization: on root/main local tasks, ordinary subagent dispatch is authorized when the `When To Spawn` gates fire. Explicit no-fan-out wins. Delegated agents may re-delegate only when their role allows. This grants no destructive, remote, credential, install, OAuth, push, live-network-expanding, or broader-sandbox authority.
 - For work spanning multiple models or CLI agents, context resets and handoffs, unattended LLM batches (including orchestrated subagent fleets), or parallel worktree branches, read and use `${CODEX_HOME:-$HOME/.codex}/guides/cli-multi-model-workflow.md` as a scoped extension of this section.
+- For composing a prompt, packet, or tool description aimed at a specific model family — including cross-family review dispatch, porting a prompt written for an older model, or choosing a reasoning-effort level for a model family — read and use `${CODEX_HOME:-$HOME/.codex}/guides/gpt-prompting.md` for gpt-family targets and `${CODEX_HOME:-$HOME/.codex}/guides/claude-prompting.md` for claude-family targets as scoped extensions of this section.
 - Allocate models by difficulty × blast radius, not phase name; when implementation ran on a cheaper tier, compensate by raising reviewer effort or adding a reviewer kind — never economize on implementation and verification at once.
 - 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.