agent-bios 0.14.0 → 0.16.0

package/claude/guides/gpt-prompting.md

@@ -9,20 +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-07
+source_pins:
+  - doc: prompt-guidance-gpt-5p6
+    sha256: 46181efec9fd1160ef537b0379282a14c1ba32380f2f8149a805128253c1115a
+    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
@@ -32,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.
 
@@ -59,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.
@@ -77,23 +151,55 @@ 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.
 
+## Programmatic tool calling
+
+A bounded stage where code processes several tool results and returns a much smaller
+structured result. The qualifier is **reduction**, not parallelism: multiple, parallel,
+or dependent calls alone do not justify it.
+
+- Use it for filtering, joining, sorting, ranking, deduplication and aggregation;
+  batching across many similar records; repeated deterministic validation; and large
+  structured results reducible to a compact schema.
+- Prefer direct calls when one call suffices, when intermediate outputs are already
+  small, when each result may change the next decision, when an action needs approval,
+  when the answer must preserve citations or native artifacts, or when semantic
+  judgment sits between calls.
+- A generic "use programmatic tool calling efficiently" does nothing. State the bounded
+  stage, the eligible tools, the output schema, the retry limit, the stop condition, and
+  the handoff back to direct judgment. If both routes are needed, define one handoff and
+  say not to switch routes or repeat completed work.
+- **Test both outputs.** The program's result and the final assistant message are
+  separate; a program can return the right records while the message drops a required
+  field, citation, or caveat.
+- Compare the two routes on the same tasks, and count lower token/latency/cost as an
+  improvement only when the response still passes the existing evals.
+
 ## Working rules
 
 - One clear task per run, with an explicit output contract.
+- **Read the assembled prompt for contradictions.** This tier follows a prompt contract
+  closely, so two rules that disagree destabilize it more than a missing rule does —
+  the opposite of the intuition that more instruction is safer.
+- State each authority rule once. Repeating "ask first", "do not mutate", or "wait for
+  approval" produces approval requests for safe, expected actions.
+- Name the current layer of work — research, design, implementation, review, external
+  coordination — on long-running tasks, so the model does not move between layers
+  silently.
+- Persisted reasoning is not a free optimization. It helps while the objective and
+  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.
+- 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,
@@ -105,14 +211,28 @@ Compose in this order; omit any block that would not change the artifact.
 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 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.
+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.
+
+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.
+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.

package/claude/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/claude/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/claude/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.