agent-bios 0.15.0 → 0.16.0

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

@@ -23,7 +23,7 @@ Scoped extension of the global Multi-Model Workflow rules. Rules use portable ro
 
 - FRONTIER: hardest bounded design, authority-changing decisions, triage, final verdicts.
 - HELM: standing main/judgment seat; orchestration and bounded escalation.
-- WORKHORSE: implementation volume and per-item judgments. SWEEP: cheap wide reads, candidate finding, mechanical passes.
+- WORKHORSE: implementation volume and per-item judgments. SWEEP: read-only work applying one explicit rule to each item, returning ambiguity as an exception.
 - VERIFIER-A/B: different review kinds, preferably cross-family. INDEPENDENT-PR-REVIEWER: final review from a different family than the author.
 
 - Bind concrete models in Environment Binding and allocate by **difficulty × blast radius**. The main defaults to HELM; first-of-kind/authority-changing mains use FRONTIER at a session boundary; trivial work stays direct.
@@ -35,7 +35,8 @@ Scoped extension of the global Multi-Model Workflow rules. Rules use portable ro
 
 Main-context pollution is usually costlier than spawn overhead. Apply these gates in order; the first that fires decides:
 
-1. **Independence:** verification or review always spawns; isolation is the purpose.
+1. **Independence:** verification and review go outside your own reasoning, not merely outside your conversation. A child carries the standing corpus on both hosts, except Claude's built-in `Explore` and `Plan`, which omit the CLAUDE.md hierarchy. Otherwise a Claude child starts fresh, while Codex `spawn_agent` forks by default — `fork_turns` defaults to `all`, so the child also holds the parent's turn input unless the call passes `none` or a turn count. What a spawn buys is graded by the seat — see Review Independence — never by the fact that it happened.
+   Verify a spawn from the artifact: Claude writes the child to its own `agent-<id>.jsonl` beside the session transcript; Codex writes a rollout whose header carries `parent_thread_id`, `agent_nickname`, `agent_path`, `agent_role`. Codex's `--json` stream cannot see a spawn at all — its `collab_tool_call` object is identical whether or not one occurred.
 2. **Parallelism:** independent items spawn in parallel with per-item tracking.
 3. **Residual context:** spawn work whose working log is much larger than the conclusion the main needs, such as broad reads, searches, tests, or implementation bursts.
 4. **Specifiability:** keep work local when it needs the main's live context or unresolved round-trips, especially deep debugging. Grind alone is not a FRONTIER reason.
@@ -46,6 +47,14 @@ Main-context pollution is usually costlier than spawn overhead. Apply these gate
 - 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.
 
+### Cost-Driven Down-Spawn (bounded implementation work)
+
+For a unit already classified as bounded implementation work, this rule takes the place of gates 4 and 5 above; gates 1–3 and Escalation still come first, and an explicit no-fan-out instruction still wins. It is the measured text — apply it verbatim, do not paraphrase it:
+
+> This rule applies at a work-unit boundary of bounded implementation work; an explicit instruction not to fan out always wins. Spawn a WORKHORSE for the unit when it has 5 or more items and is decision-complete, has a machine-checkable done-when, and is self-contained; otherwise do it inline. An unstated count is below 5.
+
+Measured 2026-09-08 on the dependent L2 edit family with a claude-opus-5 (xhigh) parent and a claude-sonnet-5 WORKHORSE child: delegating a five-item unit saved about $0.05 per unit and a ten-item unit $0.14–0.18, net of the rule's own cost; a one-item unit cost $0.05 more delegated, and a three-item unit was unresolved at the registered sample. Untested sizes between and above the tested ones rest on the assumption that a saving present at 5 and 10 holds at 6–9 and beyond; the ordering with the gates above, the cost of reading this guide, and the rule's firing rate were not measured. Shipped by guide placement rather than into the global (decision D-20260908-2186cd).
+
 ## 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. 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.
@@ -54,11 +63,14 @@ Delegate execution, not decisions. A unit is delegable only when it is decision-
 - Bundle related sub-floor tasks up to the decision-complete ceiling. A scout is read-only and reports file:line evidence for named pending decisions, probing the highest kill-risk unknown first.
 - Prompt constants, thresholds, signatures, and judgment criteria are decisions even when stored in code. Discard decision-tainted worker output when review would cost more than a clean re-dispatch.
 - Worker cost grows with request count × transcript prefix. Batch independent reads, minimize edit rounds, and dispatch independent workers/messages together.
+- **Pin the tier before dispatch.** Unpinned, the tier is chosen once the work is in view and tracks task size rather than task difficulty. Claim a cost advantage only from evidence on this task.
 - 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. An idle signal is liveness decoupled from the report: a subagent can go idle without ever delivering its result, so idle-without-report is not done — request the report explicitly rather than waiting. Cross-reset state belongs in files, not task boards or transcripts. When polling concurrent async jobs, pin the exact id/handle received at dispatch — a "latest" convenience selector can silently point at a sibling job and return plausible-but-wrong results.
 - Give reviewers/subagents a read-only diff, snapshot, or isolated worktree — not the live tree the main is editing — and forbid destructive git ops (checkout --, reset --hard, stash, clean) on any tree with uncommitted work; re-verify tree integrity before trusting results produced mid-edit.
+- Codex `spawn_agent` decides how much of the parent crosses: `fork_turns` defaults to `all`, and takes `none` or a turn count. A `SubagentStart` hook there receives `agent_type` and may return `continue: false`, so a tier rule can be enforced rather than stated.
+- No per-spawn corpus suppression exists on either host: the subagent definition carries model and effort, not scope. Excluding the standing instructions is a process-level act — `claude --setting-sources ''`, or `CODEX_HOME` pointed at a directory holding only `auth.json` — and it removes the tier definitions with them, so a corpus-free reader and a pinned tier cannot come from one process. An emptied `CODEX_HOME` without `auth.json` fails 401; skills still load.
 - Review cost scales with the diff, so layered review preserves delegation savings. Lower reviewer tier before dropping a review kind.
 
 ## Driving Codex CLI Directly
@@ -99,6 +111,7 @@ Instruction/config reach is per invocation. A rule in AGENTS.md cannot bind a he
 - Prompt caches are per model; each mid-session switch reprocesses the loaded transcript once. Batch work by model and switch at reset boundaries.
 - Prefer a spawned FRONTIER decision. Switch the main only when context fidelity outweighs handoff cost and the judgment cannot be delegated.
 - Avoid unplanned alternation. Planned escalate/return and explicit A/B comparisons are valid when each cache miss is budgeted.
+- Forking preserves conversation content on both hosts and the prompt cache on only one: a Claude `--fork-session` at the same model reuses nearly all of it and loses it across models, while a Codex `exec fork` re-sends at any model. So "fork without changing the model" is a Claude rule; on Codex a fork is priced like a fresh dispatch.
 
 ## Cross-Verification Economy
 
@@ -120,7 +133,7 @@ How much independence a review actually bought, as an ordinal grade per reviewer
 | `perspective_floor` | otherwise — still a real review |
 
 - Only upward counts. A different-but-**lower** effort earns nothing and lands on the floor: cheaper is not another perspective.
-- **Isolation is a gate, not a rung.** A reviewer that cannot be shown to run in a fresh context is excluded entirely (`NOT_REVIEW`), never graded low — an in-context "review" is the failure this ladder exists to make visible, so it must not appear as a weak pass. Isolation is realised per mechanism: a fresh read-only subprocess, a hermetic profile, a stdio tool call in a fresh session, a headless host workflow, or a stateless API call. If none of these can deliver the required seat, the review did not happen.
+- **Isolation is a gate, not a rung.** A reviewer that cannot be shown to run in a fresh context is excluded entirely (`NOT_REVIEW`), never graded low — an in-context "review" is the failure this ladder exists to make visible, so it must not appear as a weak pass. Isolation is realised per mechanism: a fresh read-only subprocess, a hermetic profile, a stdio tool call in a fresh session, a headless host workflow, or a stateless API call. If none of these can deliver the required seat, the review did not happen. An in-process subagent clears the conversation and keeps the standing instructions, so it satisfies isolation and still grades only by its seat — spawning is not itself a rung.
 - The floor still requires **at least two distinct perspectives**; one pass on the main's own seat is self-review with extra steps.
 - Multiple ready methods are **coverage, not diversity**. Distinct labels do not prove the perspectives differed.
 - **Achieved is not available.** What can be projected before a review runs is `projected`; a clean verdict without a receipt evidencing a fresh dispatch, the declared packet, a non-empty result and the exact seat is `PROPOSED`, never ACHIEVED. A model echo is not a receipt.
@@ -222,14 +235,14 @@ Write for the next agent and re-verification, not narrative. Required content:
 
 This is the human-readable projection of concrete models/tools; `launch/agent-launch.toml` is the machine launch authority and parity checks keep them aligned. Re-probe when the binding is older than ~8 weeks or a newer observable model/tool changes the surface. `agent-bios install` overwrites deployed bindings, so edit the repo copy.
 
-Binding (2026-08-10):
+Binding (2026-09-08):
 
 | Slot | Binding | Notes |
 |---|---|---|
-| FRONTIER | Claude Fable 5 · GPT-5.6 Sol (read-only; max default, task-fit effort including Ultra) | bounded hardest decisions and verdicts |
+| FRONTIER | Claude Fable 5.1 · GPT-6 Astra (read-only; max default; launcher may explicitly select Ultra) | bounded hardest decisions and verdicts |
 | HELM | Claude Opus 5 (xhigh) · GPT-5.6 Sol (xhigh main; main Ultra requires explicit selection; bounded FRONTIER Ultra allowed) | standing main; Codex defaults bypass, explicit sandbox narrows |
-| WORKHORSE | Claude Opus 5 (medium) · GPT-5.6 Terra (high) | implementation and per-item judgment |
-| SWEEP | Claude Haiku 4.5 · GPT-5.6 Luna (low) | clear repeatable scans and mechanical work |
+| WORKHORSE | Claude Sonnet 5 (xhigh) · GPT-5.6 Terra (xhigh) | implementation and per-item judgment |
+| SWEEP | Claude Haiku 4.5 (effort omitted) · GPT-5.6 Luna (max) | read-only; one explicit rule per item; not a rebind candidate |
 | VERIFIER-A | plain `codex exec` deep pass — GPT-5.6 Sol at ultra effort, packet on stdin (`-c service_tier="fast"` as explicit fast opt-in) | strongest single reader; cross-family from a Claude main |
 | VERIFIER-B | Claude Code ultracode workflow (keyword-opened, many-agent) | code/execution kind; fan-out counterpart |
 | INDEPENDENT-PR-REVIEWER | Codex CLI | adversarial `gh pr diff` review |
@@ -241,8 +254,8 @@ Binding (2026-08-10):
 Codex direct-drive (verified 0.144.1, 2026-07-12):
 
 - `codex-helm` defaults the HELM main to `--dangerously-bypass-approvals-and-sandbox`; explicit `--sandbox` wins in any flag order. Non-Ultra defaults native multi-agent off; explicit main Ultra defaults it on.
-- HELM is instructed to dispatch tiers through internal `codex-run`, which pins model/effort/sandbox. FRONTIER uses a separate `gpt-5.6-sol`, read-only root: max by default, Ultra for divisible work, lower effort when cost/latency dominates. Nested multi-agent is enabled only for Ultra. Native `codex exec` spawn cannot pin role/effort.
-- This is an instruction-backed, live-E2E-verified default, not a security boundary: main bypass and arbitrary expert `-c` remain available by design. `frontier.toml` omits fixed effort for native surfaces that accept overrides.
+- HELM is instructed to dispatch tiers through internal `codex-run`, which pins model/effort/sandbox. FRONTIER uses a separate `gpt-6-astra`, read-only root: max by default, Ultra for divisible work, lower effort when cost/latency dominates. Nested multi-agent is enabled only for Ultra. Native `codex exec` spawn cannot pin role/effort.
+- This is an instruction-backed, live-E2E-verified default, not a security boundary: main bypass and arbitrary expert `-c` remain available by design. `frontier.toml` pins the direct native FRONTIER default to max; launcher projections overwrite it from the selected tier.
 - `codex-run` owns reach, stdin, schema, profiles, expert `-c`, channel preservation, and exit status. Keep it internal.
 - `claude-run` is its Claude-side twin and the command a composable review contract names for a panel dispatch on that host. Same shape: prompt on stdin, final message on stdout, exit status mirrored, `--model`/`--effort` pinning the seat, everything it does not recognise forwarded to `claude`. It denies the mutating tools by default, which is not the OS-level sandbox `codex-run` gets — do not read the two defaults as equivalent guarantees. Dispatch whatever command the contract names rather than the bare CLI: only the adapter can report what the dispatch actually did, and a review with no receipt stays PROPOSED.
 
@@ -250,21 +263,23 @@ Dispatch packets:
 
 | Target | Required packet / default |
 |---|---|
-| GPT-5.6 Sol FRONTIER | outcome, evidence, decision boundary, stop/verification; task-fit effort; read-only |
-| GPT-5.6 Terra WORKHORSE | outcome, frozen scope/inputs, authority, done-when, evidence/report, escalation; high |
-| GPT-5.6 Luna SWEEP | exact search space, rules, ambiguity behavior, stop, output; low; no architecture/debugging |
+| GPT-6 Astra FRONTIER | outcome, evidence, decision boundary, stop/verification; max default; read-only |
+| GPT-5.6 Terra WORKHORSE | outcome, frozen scope/inputs, authority, done-when, evidence/report, escalation; xhigh |
+| GPT-5.6 Luna SWEEP | exact search space, one rule per item, ambiguity behavior, stop, output; max; read-only; no architecture/debugging |
 | Claude Opus 5 HELM | xhigh for agentic work; high minimum for sensitive judgment; lower only when bounded/cost-led |
-| Claude Opus 5 WORKHORSE | exact scope, apply-to-all rules, tools, verification, report; high default |
-| Claude Haiku 4.5 SWEEP | closed, high-volume, latency-sensitive work with exact schema/examples |
+| Claude Sonnet 5 WORKHORSE | exact scope, apply-to-all rules, tools, verification, report; xhigh default |
+| Claude Haiku 4.5 SWEEP | one explicit rule per item, read-only; effort parameter omitted; ambiguity returned as an exception |
 
 Use only task-relevant tools; parallelize independent calls. Worker report: `status`, `files_or_items_touched`, `evidence`, `verification`, `risks_or_escalations`. Official basis: OpenAI [model](https://developers.openai.com/api/docs/guides/latest-model?model=gpt-5.6), [migration](https://developers.openai.com/api/docs/guides/upgrading-to-gpt-5p6-sol), [prompting](https://developers.openai.com/api/docs/guides/prompt-guidance-gpt-5p6), [Codex models](https://learn.chatgpt.com/docs/models); Anthropic [subagents](https://code.claude.com/docs/en/sub-agents), [model effort](https://code.claude.com/docs/en/model-config).
 
 ## Evidence Base
 
-Single owner of numeric defaults; one production environment, 2026-07. Recalibration updates this table and dependent inline thresholds.
+Single owner of numeric defaults. Dates and workload scopes belong to each observation; recalibration updates this table and dependent inline thresholds.
 
 | Evidence | Result / rule supported |
 |---|---|
+| Claude M=40 confirmation (2026-09-06), adopted by owner correction (2026-09-08) | Sonnet 5/xhigh child under Opus 5/xhigh: KEEP confirmed on five fresh paired blocks; modelled cost-to-parity saving 45.5%, lower bound 40.4%. This is scoped cost evidence, not a general quality or billing guarantee. |
+| Owner tier correction (2026-09-08), Codex discovery cells incomplete | Terra/xhigh is the measured experimental effort adopted by owner instruction, not a confirmed Codex KEEP verdict. The two HELM parent seats stay unchanged; SWEEP is not a rebind candidate and remains one-rule-per-item read-only work. |
 | 15 sessions, 3,758 requests, 10 switches | switches consumed 13.9% of uncached input; avoid unplanned switching |
 | 285-call limit incident | 208 post-limit dispatches and 34/35 lost items; breaker default 3 |
 | 99 staged reviews | 15.2% halted after most compute; resume-first |
@@ -274,3 +289,6 @@ Single owner of numeric defaults; one production environment, 2026-07. Recalibra
 | Codex native-spawn probe + HELM E2E | requested max/Ultra native children recorded xhigh/role null; separate read-only roots recorded max and Ultra successfully |
 | 1,075 sessions of 50+ requests, both hosts (2026-08-16; the earlier 62-session top-by-size sample gave ~1,800-2,000) | context grows ~2,400 tok/request (IQR 1,850-2,950), hosts within 7%, ~1,800 in 400+-request sessions; auto-compaction fires at 84-95% of window, never earlier |
 | 2 sessions decomposed by cost component (2026-08) | input 92-94% of cost, output 6-8%, cache hit 95-97%, uncached input 0.0%; an 867K→200K budget cuts cost per request ~4x |
+| 4 dispatches over 3 situations built to trigger the Independence gate, plus a positive control (2026-09-01) | 0 spawns in the 3, 1 in the control; de-minimis absorbed all three and each inline answer was correct — a spawn mandate stated as always-fire did not fire |
+| 60/150-file mechanical scan, N=5 on load-bearing cells (2026-09-02) | inline $0.627→$0.919; tier-pinned delegation $0.665→$0.921; unpinned +57-73%; an N=2 first reading of the same cells reported 19% and 36% savings that N=5 erased |
+| fork cache reuse, both hosts (2026-09-02) | Claude same-model 98.9%, cross-model 0-26%; Codex 14-18% at any model (N=1 per Codex cell) — fork guidance is host-qualified |

package/codex/guides/gpt-prompting.md

@@ -9,28 +9,30 @@ use_when:
   - porting a prompt written for an older gpt model
   - deciding a reasoning-effort level for gpt work
 core_rules:
+  - apply the shared recipe and only the section for the actual target model — GPT-5.6 and GPT-6 Astra have different prompting needs
   - 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
-derived_at: 2026-09-01
+derived_at: 2026-09-07
 source_pins:
   - doc: prompt-guidance-gpt-5p6
     sha256: 46181efec9fd1160ef537b0379282a14c1ba32380f2f8149a805128253c1115a
-    pinned_at: 2026-09-01
-  - doc: latest-model
-    sha256: 48f61f648eab971334f6076bc61478d0f2bcd7a50111064722eba267a0f98d61
-    pinned_at: 2026-09-01
+    pinned_at: 2026-09-07
+  - doc: model-guidance-gpt-6-astra
+    sha256: 2a59b26078e001a4e4e3da10693e80ad5ee1c02cbe472afa6b682308f27b8b22
+    pinned_at: 2026-09-07
 targets:
+  - gpt-6-astra
   - 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
+  - effort changes use settings the target model supports and are compared against the baseline
+  - model-specific advice is checked against its own pinned source, including autonomy, writing style, delegation, and verification
 ---
 
 # GPT Prompting Guide
@@ -40,14 +42,79 @@ 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
+Use the shared recipe below together with the section for the actual target model.
+The model being prompted decides the section, including when it is a subagent on a
+different model from the main. These sections tune prompts within the existing
+permission policy; they do not change tool permissions or approval requirements.
+
+| Target | Apply | Pinned source |
+| --- | --- | --- |
+| `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` | GPT-5.6 | `prompt-guidance-gpt-5p6` |
+| `gpt-6-astra` | GPT-6 Astra | `model-guidance-gpt-6-astra` |
+
+## GPT-5.6
+
+- **Simplify first.** State the outcome, constraints, evidence, and completion bar,
+  then leave the model room to choose its path. Start from a working prompt; remove
+  one group of repeated instructions, examples, or irrelevant tools at a time and
+  re-run the same evals. Keep a process instruction when it changes behavior.
+- **Calibrate brevity.** GPT-5.6 tends to be more concise than GPT-5.5. Re-test broad
+  brevity instructions before carrying them over; they can make answers too thin.
+  Keep them when they produce the required result. Where the API exposes
+  `text.verbosity`, use it for the default detail level and the prompt for the
+  task's length, structure, and required content. Shorten repetition before evidence,
+  decisions, caveats, or next actions.
+- **Define collaboration separately from tone.** Briefly name when to ask, assume,
+  take initiative, and explain uncertainty. Distinguish inspection or planning
+  requests from requests to implement. Name safe local actions and approval
+  boundaries once so ordinary in-scope work does not pause unnecessarily.
+- **Tune effort after the prompt.** Preserve the current effective effort as the
+  baseline, then compare it and one supported level lower on representative tasks.
+  Use `low` when latency matters and quality holds; `medium` is a balanced starting
+  point. Use `high`/`xhigh` when evals show a gain, and reserve `max` for the hardest
+  quality-first work. Verify availability against the active model and host.
+
+## GPT-6 Astra
+
+- **Initiative and follow-through.** Astra is more likely to ask a question when
+  input could materially change the result. For action requests, prompt it to infer
+  routine details from context and complete authorized work, including validation,
+  before answering. A plan or an offer to continue does not complete an action
+  request. Ask when missing information changes the outcome; continue independent
+  authorized work while waiting. If approval is required for a later step, prepare
+  the concrete, reviewable result first. Keep existing permission boundaries and
+  avoid adding approval steps based only on hypothetical risk.
+- **Instruction and skill sensitivity.** Audit the loaded skills and instruction
+  files for unclear or conflicting guidance. Make explicit user instructions take
+  precedence over skill workflow preferences within higher-priority instructions
+  and permission constraints. When a skill causes a pause, an approval request, or
+  unfinished work, identify and link the exact skill file, quote the relevant rule,
+  and explain whether it is explicit or an interpretation. Do not turn an optional
+  guideline into a new requirement.
+- **Writing style.** Astra tends toward detailed responses, lists, tables, and
+  recurring phrases. Specify the desired length and structure for the audience.
+  For plain prose, request concise paragraphs, familiar words, active verbs, and
+  the main point first. Use lists when comparison or sequence benefits; retain
+  technical detail needed to assess the result. Name unwanted stock phrases or
+  formulaic contrasts when they recur rather than assuming GPT-5.6's brevity bias.
+- **Subagent delegation.** Astra may delegate less often than a workflow needs.
+  State when independent work should be delegated, the intended amount of
+  parallelism, each subagent's scope, and when to keep work local. Use the existing
+  spawn gates, available seats, and budget; a generic instruction to be proactive
+  does not specify delegation. Require readable inter-agent messages with correct
+  spacing.
+- **Testing and verification.** Astra can over-test small coding changes. Name the
+  relevant checks and completion bar. Avoid tests that only mirror a reversible,
+  low-impact implementation. Complete required checks; broaden or repeat them only
+  when a new edit, a failure, or an unresolved concern warrants it. This calibration
+  preserves required repository gates and validation of the actual changed behavior.
+- **Reasoning effort.** Astra does not support `none`. When migrating a prompt from
+  `none` or `minimal`, begin with `low` and compare results; otherwise preserve the
+  current effective effort. Check the active model and host for supported settings
+  instead of reusing a family-wide effort ladder. Fix a missing success criterion,
+  dependency rule, or verification loop before increasing effort.
+
+## Shared prompt recipe
 
 Compose in this order; omit any block that would not change the artifact.
 
@@ -67,8 +134,7 @@ Compose in this order; omit any block that would not change the artifact.
 - 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
+- Review: 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.
@@ -85,11 +151,8 @@ Compose in this order; omit any block that would not change the artifact.
   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`.
+- Choose reasoning effort using the target model's section above and the settings
+  the active model and host actually support.
 - Prefer a self-contained packet over resuming a long history: it is cheaper to
   reason about and cheaper to cache.
 
@@ -131,18 +194,12 @@ or dependent calls alone do not justify it.
   priorities hold; once they move, stale reasoning adds tokens and anchors the model to
   a superseded approach. Compact at milestones, not every turn, and treat compacted
   items as opaque.
-- Set the default detail level through the API (`text.verbosity`) and keep the prompt
-  for task-specific length and structure; a prompt-only length rule has to be restated
-  everywhere.
 - Preserve explicit user values. Where the right value is implicit, give decision
   criteria and let the model reason from context or schema rather than installing
   universal defaults or keyword maps.
 - 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.
+  inspect the active model's cache usage and cost before adding one.
 - 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,
@@ -154,21 +211,28 @@ or dependent calls alone do not justify it.
 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.
+5. Apply the matching model section. Re-read for contradictions and rules inherited
+   from a different model; validate targeted changes with the same representative cases.
+
+## Evidence base
+
+The vendor's GPT-5.6 coding-agent sample reported roughly +10–15% eval score,
+41–66% fewer total tokens, and 33–67% lower cost with leaner system prompts
+(`prompt-guidance-gpt-5p6`, pinned 2026-09-07). These are directional results for
+that sample, not Astra measurements or promised gains on another workload.
 
 ## Sources
 
-Derived from the vendor's `prompt-guidance-gpt-5p6` and `latest-model`
-documents, at the exact bytes whose hashes are recorded in `source_pins` above.
-The pin is what makes a later vendor edit detectable rather than remembered.
+The GPT-5.6 section is derived from `prompt-guidance-gpt-5p6`; the GPT-6 Astra
+section from `model-guidance-gpt-6-astra`. The shared recipe retains task, evidence,
+tool, and validation practices from the GPT-5.6 guidance and the corpus; model
+behavior claims belong only to their matching section. `source_pins` records the
+exact bytes used for this derivation so later vendor edits can be detected.
 
-Prompting guidance is version-bound and the previous generation's advice inverted
-on this one, so when a `targets` model changes, re-derive from the current
-documents rather than editing around the old rules.
+When a `targets` model changes, re-derive its section from the matching current
+document, check the shared rules for contradictions, and re-run representative
+evals rather than extending another model's behavior claims to it.
 `launch/check-prompting-targets.sh` fails when the launch config binds a model
 this guide does not list; that check is about **naming**, and a model added to
 `targets:` satisfies it forever. Whether the guidance was actually re-derived is
 not decidable and is gated nowhere.
-`launch/check-prompting-targets.sh` fails when the launch config binds a model
-this guide does not list.

package/codex/guides/review-request.md

@@ -109,6 +109,33 @@ 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.
 
+## Stop the loop on provenance, not on count
+
+A review loop's finding count says nothing about whether to run another round. What decides
+it is where the findings came from: a finding that a previous round's **fix** created is a
+different animal from one that was always there.
+
+Classify each finding three ways, not two: **caused** by the last fix, **surfaced** by it (the
+fix made someone look there, but the defect reproduces on a path the fix never touched), or
+pre-existing. The split is a revert rule, not a taxonomy: reverting removes a caused defect and merely
+hides a surfaced one. Collapsing them is how someone reverts a design change, counts the
+findings cleared, and leaves the surfaced ones live. The test that separates them is whether
+the defect reproduces on a path the fix never touched. Then read the caused share across rounds. A rising share means the fixes are generating the work, which is the
+signature of an undecided design question being patched at its consequences. Stop reviewing
+and take the design as its own task.
+
+The mechanism is the one Concept Economy already names: a fix that adds a lasting concept —
+a field, a member, a contract, a failure mode, a new error status — is a design change no
+matter how small the diff, and the next round finds its consequences. A fix that *removes*
+a concept is the healthy shape.
+
+When you stop, split the tree rather than leaving a half-designed mechanism in place: keep
+the pure defect fixes, revert the design change, and record the gap where it will be read.
+
+Source: an external 13-round campaign on a local API adapter, where rounds 12 and 13 ran 3-of-6
+and 6-of-10 caused-by, all traceable to one two-line fix that introduced a new namespace. One
+campaign, not a measured rate — the mechanism is the transferable part, not a threshold.
+
 ## Say what the target is, and what absence means
 
 The most common thing reviewers report they lacked is the stage context: they

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

@@ -6,9 +6,10 @@ audience: author
 use_when:
   - a session was launched with the Session distill preset (mission-injected)
   - the launcher nudge says enough sessions accumulated for a mining window
-  - mining local Claude/Codex sessions for learnings absent from the corpus
+  - learning from LLM work sessions to improve the corpus and its application
   - promoting, incubating, or retiring items in the session-distill ledger
 core_rules:
+  - read Goal and desired outcomes before state files or pipeline work; use it to judge the run and its delegated work
   - the ledger is the SSOT for state; read it before touching the pipeline
   - placement follows PLACEMENT-FRAMEWORK.md, never ad-hoc judgment
   - every promotion passes an explicit user-approval gate
@@ -18,6 +19,56 @@ core_rules:
 
 # Session-Distill Workflow
 
+## Goal and desired outcomes — read first
+
+Learn from the user's directly handled LLM work sessions so that
+the user and future agents can correctly understand and explain what was learned,
+apply it in relevant situations, and improve work quality, reliability, time,
+and cost in line with the user's goals and priorities.
+
+This goal applies across LLM providers and tools, including future integrations.
+The collection sources currently supported are described under Stage 1.
+
+Useful learning includes successful approaches, mistakes and corrections,
+recurring friction, consequential exceptions, and the reasoning behind choices.
+Compare it with existing knowledge: add what is missing, clarify or correct what
+is inaccurate, improve what is not being applied, and preserve what works.
+The novelty-focused screeners provide inputs to this broader goal; use the
+retained session evidence for questions their candidate lists do not answer.
+
+A run should produce:
+
+1. **Grounded learnings.** Explain what happened, what was learned, why the
+   evidence supports it, and its limits. Keep observed facts, interpretation,
+   and unresolved uncertainty distinguishable, with traceable session evidence.
+2. **Understandable, reusable content.** State the lesson, its rationale,
+   application conditions and boundaries. For a decision principle, explain the
+   competing values and the user's priority between them. Preserve concrete
+   facts or procedures where generalization would lose useful meaning.
+3. **Assessment of both meaning and application.** Check whether the lesson is
+   correctly explained and supported, and whether relevant decisions or actions
+   apply it appropriately. Assess expected benefit and unwanted effects;
+   preserving an already-correct decision can be a good result. Use checks
+   proportionate to the evidence and consequence, and distinguish observed or
+   tested effects from proposed ones. An untested candidate may remain for
+   review; neither a fluent explanation nor one suitable action proves both.
+4. **Reviewable recommendations.** Show the relationship to existing rules, the
+   proposed disposition and canonical home, the intended consumer, the expected
+   benefit and cost, and the verification still needed. Give the user enough
+   context to adopt, revise, retain, incubate, or retire the learning.
+5. **Durable, verified application of approved changes.** Route accepted work
+   through the placement framework into the guide, principle, memory, tool fix,
+   gate, or other existing mechanism that reaches its consumer. Keep evidence
+   and decisions in the ledger; report what was applied and verified and what
+   remains open. A review-ready proposal and an applied change are distinct
+   outcomes, and promotion still requires explicit user approval.
+
+Judge success by useful, justified learning and its appropriate application.
+Candidate counts and added text measure output volume. A supported decision to
+keep existing content, or a clearly bounded unresolved finding, is also useful.
+Carry this goal and the relevant outcome criteria into delegated work, then
+assess its results against them before presenting the run as complete.
+
 **Requires an agent-bios checkout.** This runbook edits the corpus itself, so it
 names repo paths and runs repo scripts. On a packaged install those do not exist:
 say so and stop rather than following steps you cannot execute.
@@ -26,7 +77,7 @@ Runbook for a session-distill run: mine recent main-context sessions,
 verify candidates, place them through the framework, and apply with the user.
 Everything durable lives in the agent-bios repo.
 
-## Read first (SSOT)
+## Read next (SSOT)
 
 1. `design/session-distill/ledger.json` — the initiative's state. Every item
    carries its status (placed / incubating / incubating-G / absorbed /
@@ -41,6 +92,7 @@ Everything durable lives in the agent-bios repo.
 
 ## Stage 1 — Mine (pipeline in `session-distill/`)
 
+The current collectors read Claude Code and Codex session histories.
 Run in order; each stage reads the previous stage's `out/`:
 
 1. `census.py --end YYYY-MM-DD` — enumerate from both providers'

package/codex/guides/slide-writing/RUNBOOK.md

@@ -0,0 +1,137 @@
+# Paired static HTML/PDF authoring and review
+
+This companion is an opt-in execution procedure for a requested static HTML/PDF
+job. The sibling [slide-writing guide](../slide-writing.md) owns the semantic
+criteria and is the default for every slide or presentation task. All role
+requests in this path receive its same criterion text.
+
+Use this runbook only when the requested output and review can actually use its
+static `section.slide` HTML/PDF path. Preserve a requested native presentation
+format; if this renderer cannot bind that format, apply the primary guide with
+the appropriate authoring tool and disclose which runtime checks were not run.
+Do not substitute an HTML deliverable or claim that unrelated screenshots passed
+this paired runtime.
+
+Use `<runbook-root>` for the directory containing this file and its `scripts/`
+directory, and `<job>` for a new directory outside the immutable corpus bundle.
+The runtime refuses an existing job directory; revised inputs or output use a
+new job revision. In every command, `--base` names the companion directory. The
+criteria source is its sibling, `<runbook-root>/../slide-writing.md`.
+
+## Prepare
+
+Provide the source text, a JSON work specification, and any local assets. Record
+format and presentation values in that specification according to the criteria.
+The HTML runtime requires static `section.slide` elements, equal page dimensions,
+and print page breaks. An explicit positive integer `pages` in the specification
+is checked against the actual render.
+
+```bash
+python3 -B "<runbook-root>/scripts/pair.py" --base "<runbook-root>" check
+python3 -B "<runbook-root>/scripts/pair.py" --base "<runbook-root>" prepare \
+  --source "<source.md>" \
+  --spec "<work-spec.json>" \
+  --asset "<optional-local-asset>" \
+  --job "<job>"
+```
+
+Omit `--asset` when no assets are needed; repeat it for additional files. Asset
+basenames must be unique. They are copied to `input/assets/<name>`, so URLs from
+`output/deck.html` use `../input/assets/<name>`.
+
+`check` parses and validates the primary criteria source without writing to the
+guide bundle. `prepare` derives `<job>/input/slide-writing.md` and the job-only
+`<job>/input/ORACLE.json`, then freezes them with the source, specification,
+assets, and runtime version. The guide bundle has no source `ORACLE.json` and no
+build command. Give the actual writer `writer.md` and the frozen inputs it names,
+and save its result to `<job>/output/deck.html`. Keep the actual invocation
+record. Request files alone do not establish that a writer consumed them.
+
+## Render the submitted HTML
+
+Resolve the Node executable, the Playwright module file, and the browser executable
+in the current environment, then pass those paths explicitly.
+
+```bash
+python3 -B "<runbook-root>/scripts/pair.py" --base "<runbook-root>" render \
+  --job "<job>" \
+  --node "<node-executable>" \
+  --playwright "<playwright-module-file>" \
+  --browser "<chromium-browser-executable>"
+```
+
+The runtime seals the HTML and assets and invokes its renderer on that copy.
+The renderer blocks network requests and file requests outside the sealed root.
+It injects no slide styles. It creates the PDF, page images, and measurements and
+checks PDF/HTML page counts and dimensions before registration. Arbitrary supplied
+images are not a substitute for this renderer invocation.
+
+`font_px` records computed CSS size. Glyph bounds, transforms, font loading, and
+the actual image remain separate evidence. A render error leaves no completed
+render; keep its diagnostics and use a new job for a corrected attempt.
+
+## Freeze a screen reading
+
+Give a separate review context `reader.md` and its listed rendered artifacts.
+Do not supply source/specification contents or the writer's explanation during
+this first observation stage. The generated request provides the response
+contract and typed template.
+
+```bash
+python3 -B "<runbook-root>/scripts/pair.py" --base "<runbook-root>" observe \
+  --job "<job>" \
+  --request "<job>/reader-request.json" \
+  --payload "<observations-proposal.json>"
+```
+
+The accepted observation is stored in `observations.json` with its request binding.
+Only then does the runtime generate `judge.md` and `judge-request.json`, containing
+the frozen source, specification, observations, and the same common criteria.
+Packet separation does not create an operating-system read jail. Record the
+actual review context and visual inspection performed.
+
+## Compare and submit
+
+Give the judge the generated judge request and the artifacts it names. Return the
+semantic fields in that request's emitted contract; do not invent a parallel
+response schema or translate rejected values into accepted ones.
+
+```bash
+python3 -B "<runbook-root>/scripts/pair.py" --base "<runbook-root>" submit \
+  --job "<job>" \
+  --request "<job>/judge-request.json" \
+  --payload "<judgment-proposal.json>"
+```
+
+The runtime rejects missing/duplicate criteria, mismatched page coverage,
+unsupported evidence references, stale inputs, and the wrong request. It writes
+`review.json` and derives `review.md` from the accepted record. Do not edit either
+result independently. Apply the semantic criteria when interpreting those
+results; structural acceptance is not a quality verdict.
+
+## Verify or revise
+
+```bash
+python3 -B "<runbook-root>/scripts/pair.py" --base "<runbook-root>" verify --job "<job>"
+```
+
+Every consuming command also performs its own preflight checks. An edit becomes
+available to the next activated corpus snapshot and the next prepared job. An
+existing job verifies against its original immutable corpus snapshot, frozen
+criterion source, derived oracle, and runtime version. Mutating the guide or code
+path recorded by that job instead of using its original snapshot invalidates the
+binding, as do changes to its source document, specification, assets, HTML,
+requests, or registered render/results. Preserve the old job as evidence of that
+revision; prepare a new job rather than modifying its state or hashes to make it
+current.
+
+The immutable guide bundle is read-only input. Keep all job data outside it. Do
+not repair an installed snapshot in place. A local experiment with different
+criteria is a separate explicitly identified authoring copy, not an update to the
+shared guide.
+
+The protocol has no provider dispatcher or automatic publishing step. Use the
+available authorized authoring/review tools, preserve their actual invocation
+evidence, and disclose any unexecuted or uncertain checks. It verifies shared
+criteria and bindings; model interpretation and visual-detection accuracy require
+their own evidence.