agent-bios 0.1.0 → 0.3.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

@@ -29,6 +29,7 @@
 - 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.
+- Do not default to a restrictive lens (security, masking, capability limits) when the system's purpose is sharing or utilization; confirm the purpose framing first, and restrict only on concrete, named risk.
 - 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
@@ -79,6 +80,7 @@
 - Treat viability as real behavior against real inputs, real authority, and the intended runtime path. Use mocks only for tests, fixtures, or explicitly requested simulations; mock-backed paths support verification but do not count as product completion.
 - Make surgical changes. Touch only what the request requires, preserve existing style, and avoid casual adjacent refactors.
 - Clean up issues introduced by the current change. Mention unrelated dead code separately.
+- Own the full lifecycle of what you create — spawned processes and handles through teardown, artifacts out of tool-managed temp locations into a durable home — and keep differently-owned state separate: never colocate deploy-managed and user-owned data in one overwrite-managed file.
 - Define success criteria before multi-step coding work, then verify against them.
 - For bugs, prefer a reproducing test before the fix when practical.
 - Every changed line should trace back to the user's request.
@@ -87,6 +89,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.
@@ -96,21 +99,27 @@
 - Report the checks run, results, and any unverified risk before calling the work done.
 - Trust a green check only when it traversed the actual changed code through the real dispatch and real calls (not a mock, dry-run, or bypass), and remember that "it ran" is not "quality met" — a fallback, floor, or mock run is not done; treat a zero-findings verdict as suspect until you confirm the harness ran rather than silently crashed, and make PASS mean concrete assertions on real output from the real path.
 - Make completion criteria falsifiable: prefer signals that fail when the mechanism is wrong (negative or contrast controls), and if no existing gate can judge a criterion, build the executable judge or do not claim the criterion met.
+- Before comparing two of anything (cost, performance, quality, frequency), fix a common basis — units, denominators, population, measurement surface — compare on equivalent output, and exclude or flag non-representative data (promotions, outages, smoke slices).
 - For non-trivial designs or high-risk changes, run independent adversarial review across distinct lenses, ideally on the design before implementation, and re-verify each finding against real code before acting on it. Apply the convergence heuristic by reviewer kind (detailed in the multi-model guide): same-kind convergence is high confidence but same-kind reviewers share blind spots — their shared "clean" is not verification; different-kind divergence is the expected signal — act on the union. Never accept an orchestrated workflow's self-reported all-green as sufficient; independently re-run the diff inspection and verification suite yourself.
-- Proportion verification to cost, risk, and information gain: before expensive or slow live runs, diagnose in code and replay the changed deterministic logic over persisted real artifacts, probe at N=1 with inputs precondition-checked, and reserve full design-review-plus-live verification for first-of-kind or authority-changing work.
-- 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.
+- Proportion verification to cost, risk, and information gain: before expensive or slow live runs, diagnose in code and replay the changed deterministic logic over persisted real artifacts, probe at N=1 with inputs precondition-checked, and reserve full design-review-plus-live verification for first-of-kind or authority-changing work; proportion assurance to the deployment context — a single-user, own-data tool does not warrant production-grade assurance; prefer delivery.
+- Trust a green / zero-findings verdict only if the check could have failed over a real, non-empty subject: assert the entity-under-test set has cardinality > 0 before any "no bad X" or "all X satisfy P" claim (an empty subject set passes vacuously and proves nothing), and for any test touching a branch you add or delete, confirm its inputs satisfy the live branch's entry guard — a copied fixture that fails the new guard silently routes into the about-to-be-deleted dead branch and stays green even after the real behavior breaks. When a check goes green unexpectedly fast or empty, dump what it actually ran over. Checker code itself must assert the expected shape and fail loud — a permissive fallback (`a || b`) inside a gate absorbs wrong assumptions and keeps passing.
 
 ## Tooling and Operational Safety
 
+- For concrete shell/CLI traps — pipe exit codes, output rendering, git range/pull semantics, config and managed-service pitfalls — read and use `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/tooling-gotchas.md` as a scoped extension of this section.
+- Ambient state — the active shell, cloud CLI project/context, command-name resolution, 'latest'-style pointers, version-bearing paths — drifts silently; where an outcome depends on it, pin it explicitly (a pinned interpreter, --project/--context flags, exact handles, resolved paths) instead of trusting the environment.
 - 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.
+- 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; snapshot the last good state before any in-place resume or overwrite of a completed run, and gate irreversible identity-tied actions (revoke, delete, grant, consent) on a live identity check — never auto-open a browser for a non-default identity (hand the operator the URL).
+- 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; assume a resource-creating call may echo the secret back in its success output — suppress or discard the response body, and treat an echoed secret as pasted (rotate).
 - Treat a coarse runtime signal — a failure label, a `ps`/process-inspection result, idle CPU with no output — as a hypothesis, and confirm the cause against the authoritative low-level evidence the mechanism emits before attributing blame or intervening: read the raw provider/skill log payload (e.g. `input_tokens:0` proves a pre-dispatch rejection that exonerates your content and your change), and confirm a config/env toggle reached a subprocess via a cheap artifact the gated branch emits rather than an unreliable `ps` env read. A multi-minute LLM or subprocess call at ~0% CPU with an output gap is the normal signature of I/O wait, not a hang — check process state and the call trace's in-flight duration before acting, so you do not abort healthy long-running work.
-- Before reasoning about what a branch contains or opening a PR, run `git fetch` and compute the range as `origin/<base>..HEAD`, never `<base>..HEAD` against the local tracking ref — on a shared repo the local base drifts behind the remote until you pull, silently inflating the diff with already-merged work; if the range is surprisingly large, suspect a stale base before suspecting the branch.
+- Before reasoning about what a branch contains or opening a PR, run `git fetch` and compute the range as `origin/<base>..HEAD`, never `<base>..HEAD` against the local tracking ref — on a shared repo the local base drifts behind the remote until you pull, silently inflating the diff with already-merged work; if the range is surprisingly large, suspect a stale base before suspecting the branch. Platform "mergeable" flags are computed against the base only — sibling PRs can each look clean yet conflict; before picking a merge order, diff their changed-file sets and simulate the sequence.
 
 ## Multi-Model Workflow
 
+- Standing spawn policy: check the spawn gates at every work-unit boundary — judgment latitude applies inside a gate, never to whether the gates are checked. Independence: verifying or reviewing your own work always spawns. Parallelism: two or more independent items spawn in parallel — SWEEP when each item applies one explicit rule and returns ambiguity as an exception, else WORKHORSE. Residual context: work whose log dwarfs the conclusion the main needs spawns with a bounded report contract. Escalation: an irreversible or authority-changing action ahead, two failed attempts, or two persisting design alternatives spawns a bounded FRONTIER judgment with a blind packet (evidence, constraints, rubric, neutral alternatives — never your draft conclusion) and a pre-noted change condition. Specifiability/de-minimis: work needing your live context, or whose verification would repeat the reasoning, or whose packet outweighs the work, stays inline.
+- Down-spawns carry a machine-checkable done-when on decision-complete work with staged output (no external irreversible actions) and briefing-plus-verifying clearly cheaper than doing. Record one line per gate decision — `SpawnGate: <gate> <tier> spawn|inline — <why>` — and for FRONTIER record the disposition afterward (what changed, or why nothing did). A launch contract's `Delegation=off` lifts the spawn obligation, not the records; explicit user no-fan-out always wins.
 - 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/agents/frontier.md

@@ -0,0 +1,9 @@
+---
+name: frontier
+description: FRONTIER tier — bounded hardest decisions, first-of-kind design, triage gates, and final verdicts. Spawn when the Escalation gate fires — an irreversible or authority-changing action ahead, two failed attempts, or two persisting design alternatives — with a blind packet (evidence, constraints, rubric, neutral alternatives; no draft conclusion) and a pre-noted change condition.
+model: claude-fable-5
+effort: max
+disallowedTools: [Edit, Write, NotebookEdit]
+---
+
+Resolve one bounded hardest decision, design question, triage gate, or verdict from the smallest sufficient evidence. Distinguish fact from inference. Do not implement, broaden scope, or seek wider authority. Report: status, decision, evidence, decisive tradeoffs and failure modes, falsifiable verification, risks_or_escalations.

package/claude/agents/sweep.md

@@ -0,0 +1,9 @@
+---
+name: sweep
+description: SWEEP tier — cheap wide scans, candidate finding, mechanical checks, and closed-form summaries. Spawn when each item applies one explicit rule; ambiguity returns as an exception, never resolved.
+model: claude-haiku-4-5
+effort: low
+disallowedTools: [Edit, Write, NotebookEdit]
+---
+
+Run one clear repeatable scan, candidate pass, mechanical check, or closed summary over exact inputs, rules, stop condition, and output shape. Read-only: do not edit, broaden scope, choose architecture, or seek authority. Parallelize independent reads. Surface ambiguity as an exception instead of inferring intent. Report: status, the non-empty items_checked, findings with proving evidence or command, risks_or_escalations.

package/claude/agents/workhorse.md

@@ -0,0 +1,8 @@
+---
+name: workhorse
+description: WORKHORSE tier — bounded implementation, fixes, tests, and per-item judgment. Spawn decision-complete work with frozen scope/interfaces and a machine-checkable done-when; two or more independent items spawn in parallel.
+model: claude-sonnet-5
+effort: high
+---
+
+Complete one bounded implementation, fix, or per-item judgment from a packet naming objective, frozen scope and inputs, allowed actions, output, done-when, and verification. Preserve out-of-scope behavior; batch independent reads; escalate missing decisions or authority instead of resolving them. Stage output for the main's acceptance — no external irreversible actions (push, install, credential, or remote mutation). Run the narrowest reliable changed-path check. Report: status, files_or_items_touched, evidence, verification or gap, risks_or_escalations.

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/cli-multi-model-workflow.md

@@ -41,13 +41,14 @@ Main-context pollution is usually costlier than spawn overhead. Apply these gate
 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.
+- **Escalation:** spawn FRONTIER first for a bounded judgment with material stakes (an irreversible or authority-changing action ahead, an architecture or public-interface commitment, or invalidation of two or more downstream units) and a named residual-risk signal (two failed attempts, two persisting alternatives, conflicting evidence, or an unverified assumption that can flip the decision). Pre-note the finding that would change what; send a blind packet — evidence, constraints, rubric, neutrally ordered alternatives, never the main's draft conclusion — and record the disposition afterward (what changed, or why nothing did; persistent no-change indicts the gate or the packet). 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.
+- Record one line per gate decision — `SpawnGate: <gate> <tier> spawn|inline — <why>` — plus the FRONTIER disposition. A launch contract's `Delegation=off` lifts the spawn obligation, not the records.
 
 ## 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.
+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. Delegated output is staged until the main accepts it — workers take no external irreversible actions — and handling (brief, verify, correct, integrate) must be clearly subordinate to the work itself. A SWEEP-bound unit applies one explicit rule per item and returns ambiguity as an exception, never resolved.
 
 - 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.
@@ -56,7 +57,8 @@ Delegate execution, not decisions. A unit is delegable only when it is decision-
 - Use a resident teammate only for dependent slices in one burst. Verify that the CLI preserves its model and context; resume-after-completion may silently change both. Retire after the burst or cache TTL, and persist durable knowledge in files.
 - After a discard or direction change, respawn once a routine round costs about as much as a fresh slice. Recover unique in-flight state to files first.
 - Redirects to busy workers may queue rather than preempt. Check artifacts before destructive redirects, phrase them conditionally, and stop an actively harmful worker by scoped PID/worktree authority.
-- Idle/progress notifications are hypotheses; verify repo artifacts before re-dispatch. Cross-reset state belongs in files, not task boards or transcripts.
+- Idle/progress notifications are hypotheses; verify repo artifacts before re-dispatch. Cross-reset state belongs in files, not task boards or transcripts. When polling concurrent async jobs, pin the exact id/handle received at dispatch — a "latest" convenience selector can silently point at a sibling job and return plausible-but-wrong results.
+- Give reviewers/subagents a read-only diff, snapshot, or isolated worktree — not the live tree the main is editing — and forbid destructive git ops (checkout --, reset --hard, stash, clean) on any tree with uncommitted work; re-verify tree integrity before trusting results produced mid-edit.
 - Review cost scales with the diff, so layered review preserves delegation savings. Lower reviewer tier before dropping a review kind.
 
 ## Driving Codex CLI Directly
@@ -104,6 +106,7 @@ Instruction/config reach is per invocation. A rule in AGENTS.md cannot bind a he
 - 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.
+- Kind labels do not guarantee distinct backends: wrappers and rate-limit fallbacks can silently route two "different-kind" verifiers to the same model/provider. Before trusting diversity on a high-stakes verdict, confirm each verifier's actual backing model from live process or usage evidence; on collapse, treat the pair as one kind and label PROPOSED.
 
 ## Unattended Batch Safety
 
@@ -117,6 +120,8 @@ Instruction/config reach is per invocation. A rule in AGENTS.md cannot bind a he
 - 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.
+- Treat tool-managed temp/cache output locations as ephemeral — they are garbage-collected on the tool's own schedule. Copy any artifact a pending or handed-off decision depends on into a project-owned durable path before relying on it later.
+- Bounded-size cross-session indexes (memory index files) truncate silently past their read limit. Compare size against the limit periodically; before compacting, migrate index-only detail into per-item files, then verify links and no orphans.
 
 ## Sessions, Branches, Worktrees
 
@@ -124,6 +129,7 @@ Instruction/config reach is per invocation. A rule in AGENTS.md cannot bind a he
 - 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.
+- Attribute a parallel session's action (commit, branch, resource) by execution evidence in that session's own transcript, never by token mentions — shared handoff/memory files inject the same tokens into every session's context.
 
 ## Handoff Contract
 
@@ -131,11 +137,12 @@ 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.
+3. CONFIRMED claims whose cited command or anchored file evidence independently re-establishes them. Anchor code citations by stable symbol names (grep-re-derivable), not bare line numbers, which drift silently under later edits.
 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.
 
+- Never record the hash of the commit that will contain the record itself — it is unstable by construction. Land substantive changes first and reference the settled hash from a follow-up commit, or use a relative phrase ("resume from the commit containing this handoff").
 - 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.
 

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

@@ -32,6 +32,8 @@ When the user asks to "설계" or design, stay in design mode. Focus on high-lev
 2. Implementation-process design: turn the design into an ordered work plan with dependencies, verification points, review gates, and redesign triggers.
 3. Implementation: make the smallest viable functional changes that satisfy the approved design and process plan.
 
+When simplifying a pipeline, moving processing downstream and dropping captured source fields are separate decisions: relocation is free simplification, but reducing captured information is riskier and needs explicit confirmation — "no current consumer" is not evidence of no future value.
+
 ## Review Loop
 
 - At each stage, run review loops as appropriate: self review, subagent review when available, and structured multi-lens review when the repository or domain supports one (concrete tool: Environment Binding below).
@@ -41,6 +43,7 @@ When the user asks to "설계" or design, stay in design mode. Focus on high-lev
 - Treat high as supported user, environment, data, or execution path failure.
 - Treat medium as meaningful weakening of trust, auditability, reproducibility, completeness, or decision quality.
 - Treat low and info as non-blocking unless requested or promoted by new evidence.
+- When a document declares sections co-authoritative for a rule (fixture blocks, conformance appendices), treat every occurrence as one replicated value: propagate edits to all declared locations in the same pass and check propagation completeness explicitly in review.
 
 ## Verification Menus
 
@@ -51,6 +54,11 @@ Per-domain menus for the global Verification Discipline loop; pick the narrowest
 - Config or data: real parsers, schema checks, fixture validation, and sample transformations.
 - Spreadsheets: static workbook checks, fixture-based output checks, cross-sheet flow checks, visual/layout checks, and real Microsoft Excel engine recalculation for formula-dependent results.
 - Docs: links, terminology, current behavior alignment, and references to isolated historical notes.
+- Release or distribution: after publishing to multiple independently writable channels (signed manifest, object storage, release host, embedded updater), digest-verify every referenced object against the staging original per channel — publish success and upload order are not evidence — and run the real installer/updater through its default path.
+- A/B or on/off measurements: before accepting a null result, verify the arms actually received different treatment in the mechanism under test — a shared default or unconditional upstream step can silently apply the treatment to both arms.
+- Model-behavior guardrails: verify by changed behavior, not recitation — a staged battery from named-trigger cases through disguised, deconfounded, category-wide, and single-variable framings; a clean pass means "no known defect", so re-run the battery when the model changes.
+- Branch/version test builds against real data: explicitly separate every state sink the app touches (files, DB, OS-level stores that ignore env overrides), confirm the launch path propagates the isolation to child processes, and back up live data before the first run — a mismatched schema that drops unknown fields on write is data loss, not a no-op.
+- Irreversible capture switches: when activation itself has unreproducible cost (a capture window that cannot be replayed), prove the downstream consumption path against existing samples before enabling — reversibility of the code path alone is not enough.
 
 ## Stop Conditions
 

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/llm-capability-boundary-patterns.md

@@ -278,6 +278,11 @@ Required rules:
 - Log tool calls, arguments, policy decisions, and results for audit.
 - Rate-limit and timeout tools that can loop, scan, spend, mutate, or call the
   network.
+- Resolve every authorization/allowlist entry against the live runtime key
+  space at boot or deploy — format validation only proves well-formedness, and
+  a mis-formatted entry can pass every deploy check while silently denying its
+  whole route class. Verify fixes with an explicit negative control plus a
+  live end-to-end call through the redeployed system.
 
 The LLM can recommend an action. The capability surface decides whether the
 action is available, permitted, confirmed, and accepted.

package/claude/guides/mock-realization-boundary.md

@@ -246,6 +246,15 @@ Examples:
 - A mock provider can prove retry handling.
 - A mock provider cannot prove the real provider integration is production-ready.
 
+Connected cloud documents (live Sheets/Docs with bound scripts, triggers,
+permissions, protections, named ranges, external references) are live
+integrated systems, not portable files: unless the user explicitly asks for a
+copy/export, edit in place through the native authority (connected-document
+MCP/API). Before writing, enumerate the beyond-cell elements so none are
+silently dropped, and report external load states (loading, timeout, quota,
+permission-denied, broken reference) distinctly instead of collapsing them
+into one success/failure.
+
 ## Design Procedure
 
 Use this procedure before adding or extending mock behavior.