agent-bios 0.14.0 → 0.16.0

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.