agent-bios 0.12.0 → 0.12.1

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

@@ -80,6 +80,7 @@ patching them one at a time is a queue that refills.
 
 - 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).
 - Iterate until material issues reach zero: review, identify material issues, fix them, and review again.
+- "Material issues reach zero" is counted over the declared defect criterion's stop-relevant class; choosing and declaring that criterion is owned by `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/review-defect-criteria.md`.
 - Use the severity contract for materiality — the canonical definition is the ladder below; external review tools map their levels onto it: blocker, high, and medium are material; low and info are non-material.
 - Treat blocker as primary happy-path or core-contract failure.
 - Treat high as supported user, environment, data, or execution path failure.

package/claude/guides/review-defect-criteria.md

@@ -0,0 +1,205 @@
+---
+guide_id: review-defect-criteria
+language: en
+status: active
+use_when:
+  - declaring what counts as a defect before dispatching any review
+  - choosing or writing the defect criterion for a system type × work goal
+  - a review loop plateaus, diverges, or its "material 0" stop never arrives
+  - a finding's class is contested at the boundary, or two lenses class it differently
+core_rules:
+  - choose and declare the criterion before the review starts — undeclared, every reviewer substitutes its own
+  - the severity ladder answers how bad; the criterion answers whether it is a defect, of which class, and what "zero" is counted over
+  - a criterion with an empty cell is a hunch, not a criterion — do not start the review
+  - paste the goldens into the packet verbatim; a definition alone does not classify consistently at the boundary
+  - put the class enum on the accepting channel where one exists; on prose routes, run the fold procedure
+  - a mixed packet is split — never run two observers in one trajectory
+verification_focus:
+  - every dispatched packet names its criterion and carries its goldens
+  - each round audits reported class against post-measurement class; repeated disagreement mints the next golden
+  - the stop condition is evaluated over the stop-relevant class only, never the whole finding count
+---
+
+# Review Defect Criteria
+
+A defect criterion is chosen, not assumed. This guide is a scoped extension of
+`${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/review-request.md`: before that guide's
+request composition starts, this one decides what the review is hunting. The
+evidence: one codebase, two stop criteria, opposite trajectories.
+
+| Rounds | Criterion | Trajectory |
+|---|---|---|
+| early | material = contract violation **or** unprotected contract sentence, small frozen surface | 10 → 4 → 1 → 0 |
+| late | same, scoped to client-observable behavior | 17 → 19 → 21 → 23 → 19 — **plateau** |
+| final | split classes: behavioral_defect / coverage_gap / doc_gap; stop = behavioral 0 | behavioral 10 → 5 — falling again |
+
+The plateau was the criterion, not the code: counting "a contract sentence no test
+protects" as a defect means every fix adds contract rows, each a potential defect
+next round — a self-refilling criterion cannot reach zero while its surface grows.
+Yet that same criterion is exactly right for a library, where an unprotected promise
+is a first-class defect. Neither is wrong; starting without choosing is.
+
+The **severity ladder** (in `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/coding-staged-workflow.md`)
+answers *how bad* a finding is. The **criterion** answers *whether* it is a defect at
+all, of which class, and what "zero" is counted over. The plateau happened entirely
+inside "material" — no severity adjustment could have ended it. Ordering: system type
++ goal → defect criterion → classification → defect? → severity → materiality → stop.
+
+## The criterion schema
+
+One entry carries all of these. An empty cell makes it a hunch, not a criterion — do
+not start the review on it.
+
+| Field | Meaning |
+|---|---|
+| observer | whose eyes judge — client, caller, operator, a model reading the output |
+| defect | what the observer must experience |
+| classes | the enum, exactly ONE class stop-relevant; the others are relief valves that keep the stop class honest |
+| evidence | what one finding must present |
+| non-defects | defect-lookalikes excluded by this criterion — named explicitly |
+| stop condition | what "0" means, counted over the stop class, and WHY it is reachable — how a growing surface is pinned |
+| misclassification cost | which error is expensive — the direction to tell the reviewer to lean |
+| goldens | ≥2 positive, ≥2 negative, ≥1 boundary; each with why, date, and provenance: `measured` (dated incident) or `constructed` (authored to pin a boundary) |
+
+## The catalog
+
+Four system types. A starting set, not a census.
+
+### Web service / API surface (contract compliance)
+
+- **Observer**: the HTTP client.
+- **Defect**: a client today receives a response that differs from the contract — status code, envelope, stream terminal frames, the model actually run, isolation, resource caps.
+- **Classes**: `behavioral_defect` (stop-relevant) · `coverage_gap` · `doc_gap`.
+- **Evidence**: the concrete request and observed vs promised response.
+- **Non-defects**: internal lifecycle (unless a request sequence shows two different responses), absence of a test, documentation wording.
+- **Stop**: behavioral 0 — reachable: the code surface is finite and shrinks monotonically unless a fix creates a new behavioral defect.
+- **Misclassification cost**: false negatives (a client actually breaks); but inflating coverage gaps into defects destroys the stop condition — audit category creep separately.
+- **Goldens** (all `measured`, 2026-08-13–15):
+  - **+** `GET` on a nonexistent path returned 405, not 404 — an existing-method complaint attached to a path that does not exist.
+  - **+** a streaming endpoint's terminal delta carried only `output_tokens`, so cache/input token counts never reach a streaming client — non-streaming was correct, which is why nobody saw it.
+  - **−** "no test catches a one-line flip of this default": today's behavior is correct — `coverage_gap` here, a defect only under the library criterion.
+  - **−** child-process kill grace period — out of scope until a request sequence shows a client-visible difference; pins the observer to the client.
+  - **±** rejecting a documented-as-valid boundary value (compression 100, docs say "below 100 requires jpeg/webp") — the documentation is what makes it a defect; without that sentence it is taste.
+
+### Library / SDK / contract-first system
+
+- **Observer**: the caller **and** the future maintainer.
+- **Defect**: a promise violated today, or a promise unprotected — a one-line change breaks it and nothing catches it. The API criterion's `coverage_gap` is first-class here.
+- **Classes**: `contract_defect` (stop-relevant) · `style_note` · `internal_change`.
+- **Evidence**: for a violation, as above; for an unprotected promise, the promise sentence + the one-line change that breaks it + the absence of any catching test.
+- **Non-defects**: style, internal structure.
+- **Stop**: caution — this criterion self-refills while the contract grows. Declare "0" only over a surface whose growth has stopped; on a growing surface, narrow the stop to "every promise this change added is protected."
+- **Misclassification cost**: balanced — miss an unprotected promise and the next refactor breaks it silently; over-report and the loop never ends.
+- **Goldens**:
+  - **+** a streaming-image event test matched only `.completed`, so an edit stream misnamed `image_generation.completed` still passed — mutation survival showed the promise unprotected. (`measured`, 2026-08-13–15)
+  - **+** the contract promised "storage serves a large image at least once"; the code evicted it on the next request — resolved by fixing the **contract**: the disagreement is the defect, whichever side moves. (`measured`, 2026-08-13–15)
+  - **−** renaming an internal helper no document promises — the observer holds the contract; undocumented internals carry no promise. (`measured`, 2026-08-13–15)
+  - **−** a caller breaking on undocumented iteration order — no promise existed; the rename boundary pinned from the caller's side. (`constructed`, 2026-08-19)
+  - **±** an inventory-listed test turns out vacuous — asserts nothing about its promise. "A test exists" is a claim about names until the assertion is read; hand the reviewer "check the assertion, not the name." (`measured`, 2026-08-13–15)
+
+### AI workbench / harness (agent orchestration, review loops, verification pipelines)
+
+- **Observer**: the operator, and any model consuming the harness's output.
+- **Defect**: **a false signal that looks true** — a wrong PASS, a vacuous test, a silent fallback, a packet missing the call site, a wrong denominator. Being wrong is not the defect; being wrong while *looking right* is. Second form: a run claimed without provable dispatch — no receipt.
+- **Classes**: `false_signal` (stop-relevant) · `detected_miss`. An unproven dispatch — a run or PASS claimed with no receipt — is classed `false_signal`, not given its own relief valve: a signal that cannot be shown true is counted false, or a round could declare completion while every dispatch stayed unproven.
+- **Evidence**: the input on which the instrument gave a false verdict, plus the known correct answer. The standard probe: run the instrument against an input whose answer is known to be the opposite.
+- **Non-defects**: one output's style; a false positive the harness itself **detected** — a caught error is the harness working.
+- **Stop**: every PASS emitted this run survives a known-opposite check and evidences its own dispatch. The unit is "this run's signals are trustworthy," not a standing zero.
+- **Misclassification cost**: false passes dominate. An instrument bug reporting failure dies in minutes because someone looks; one reporting success survives — a selection effect.
+- **Goldens**:
+  - **+** a shell test runner received one nonexistent path (zsh does not word-split an unquoted variable), so every run exited 1 and every mutation reported KILLED — a green instrument that never ran its subject. (`measured`, 2026-08-13–15)
+  - **+** a test-inventory grep matched only `^test('...'` and missed every parameterized name; three reviewers judged a populated file empty — nothing tied the inventory's denominator to the source's own count. (`measured`, 2026-08-13–15)
+  - **+** a negative control kept passing after a faithful revert of the fix it was written against — a guard satisfied by an absence, a false PASS about the gate itself; found only by re-running reverts. (`measured`, 2026-08)
+  - **+** a review round returned "clean" with no receipt evidencing that the declared packet was dispatched on the exact seat — `false_signal` although nothing observed was wrong: what the stop refuses is absence of proof of dispatch, not proof of falsity. (`constructed`, 2026-08-19, pinned after a classification dispute at exactly this boundary)
+  - **−** one reviewer over-classed an item as material; another lens plus measurement filtered it — the harness caught it, so it worked: `detected_miss`, not a defect. (`measured`, 2026-08-13–15)
+  - **−** five review rounds returned 8 → 9 → 10 → 5 → 12 findings, refusing to converge — and every count was true. A truthful unpleasant signal is not a false signal; the defect lived in the undeclared criterion. (`measured`, 2026-08-16–17)
+  - **±** a surviving mutation proved equivalent — the platform already normalized what the mutated guard checked. Neither a harness defect nor a test gap; but a harness that auto-reads "survived = gap" has a defect in that rule. (`measured`, 2026-08-13–15)
+
+### Decision ontology (an ontology a model decides from)
+
+- **Observer**: a model or agent deciding from the ontology alone.
+- **Defect**: a representation that produces a wrong decision or blocks a right one: overlapping concept boundaries, a missing distinction the decision needs, an instance contradicting reality, a wrong relation direction or cardinality, a name implying what the definition does not say.
+- **Classes**: `decision_defect` (stop-relevant) · `representation_note` · `out_of_scope_gap`.
+- **Evidence**: a **decision scenario** — "answered from the ontology alone, this question yields X; reality is Y" — with the question, the path taken, and the ground truth.
+- **Non-defects**: representation format, completeness as such, a question the model would get wrong without the ontology too.
+- **Stop**: zero wrong decisions over the agreed scenario set. The set is the scope — fix it first, or this criterion self-refills like the library one.
+- **Misclassification cost**: situational — feeding a hard gate makes false negatives expensive; exploratory aid makes false positives expensive. Filling this cell is mandatory at declaration.
+- **Goldens** (all `constructed`, 2026-08-19, authored to pin boundaries the source loop's decision-scenario framing left open):
+  - **+** `Customer` and `Account` both define "the paying party"; a refund-routing question resolves through both paths — overlap is a decision defect even when each definition is individually correct.
+  - **+** `Order —hasOne→ Payment` while split payments exist — cardinality is a claim, and a false claim misleads the deciding model.
+  - **−** a verbose concept description — no decision changes; form is outside this observer's sight.
+  - **−** a domain absent that no scenario in the agreed set needs — completeness is scoped by the set, not the world.
+  - **±** the distinction exists but the model cannot find it (name or link missing) — with the observer fixed as "a model seeing only the ontology," unreachable is a representation defect, not a search defect. The observer clause decides the class.
+
+## Before any review
+
+1. Write one sentence: the system type and this work's goal. ("API surface — make the responses clients receive today match the contract." / "Harness — make this run's PASS signals trustworthy.")
+2. Pick a criterion from the catalog, or fill the schema fresh. A cell you cannot fill means the review does not start.
+3. Paste the goldens into the packet verbatim. Never the definition alone.
+4. Declare the stop condition and why it is reachable — or how the scope was pinned to make it so.
+5. Put the classification on the accepting channel (next section).
+6. Audit every round: reported class vs the class confirmed after measurement. A repeated disagreement is the next golden.
+
+## Enforcing the enum, by channel
+
+Ranked by how much the channel refuses for you:
+
+1. **A route with a submit schema**: classification is a required enum field. The
+   measured precedent is anchors — 2,466 of 2,466 findings carried one, because the
+   schema refuses output without it. Where this channel exists, use it.
+2. **Prose-packet routes** (the shipped deep-review methods): the packet header
+   declares `Criterion: <name>` with the goldens pasted verbatim, and the dispatching
+   agent runs this fold procedure on what comes back:
+   1. For each returned finding row, look up its class against the declared enum.
+   2. A row carrying a class from the enum enters the findings ledger under that class.
+   3. A row with no class, or a class outside the enum, is **not admitted**: send it
+      back once for classification, or record it as refused with the reason. Never
+      admit it unclassified, and never guess its class for it.
+   4. Count the stop condition over the stop-relevant class only.
+   5. Record the audit pair (reported class, confirmed class) for procedure step 6.
+
+   Stated honestly: on a prose route this is steering, not control — the fold is
+   performed by an agent following this guide, and nothing structural refuses a
+   class-less row for it. That is the known weaker result of a request-only rule.
+3. A structural criterion slot in the review dispatch machinery is deliberately not
+   part of this guide: a criterion is per-review while dispatch config is per-launch,
+   and a slot with no schema-backed consumer would be an inert value. Until such a
+   channel exists, ranks 1–2 are the real ones.
+
+## Golden lifecycle
+
+- **Admission**: only a golden that decides a boundary the definition leaves open,
+  evidenced by a recorded classification disagreement or an audited misclassification;
+  provenance labeled `measured` or `constructed`, each with its why and date.
+- **Overturn**: only by a measured counterexample. Correct the golden in place — this
+  guide describes the present — plus a dated decision record, in whatever channel the
+  repo keeps decisions, naming the closed golden and the counterexample. Silent
+  deletion is forbidden: a wrong golden makes reviewers systematically wrong, and an
+  untracked fix hides that it ever did.
+
+## Declaring, switching, and mixed packets
+
+- Every dispatched packet names its criterion. A harness round declares `AI harness`;
+  a round whose system type has no catalog entry declares a **task-local criterion**,
+  written in the packet itself, conforming to the schema above and labeled task-local
+  — repeated use is what earns a catalog entry.
+- A mixed packet is split into one packet per criterion. Two observers in one
+  trajectory produce findings no single stop condition can count.
+- When a criterion changes mid-loop: re-classify only the findings still open; rounds
+  already recorded are dated history. Never splice pre- and post-switch counts into
+  one series — they count different things.
+
+## Evidence base
+
+Derived from a 39-round adversarial review loop (3 lenses × a frontier reviewer) on a
+peer OAuth CLI-API adapter, 2026-08-13–15: the same codebase plateaued at
+17→19→21→23→19 findings under a self-refilling criterion and resumed falling
+(behavioral 10→5) the round the classes were split and the stop counted over
+`behavioral_defect` alone. The boundary evidence is from the same loop: a packet
+instruction saying "do not inflate coverage gaps" still left two lenses classing one
+finding `doc_gap` and `behavioral_defect`, both defensibly — one golden would have
+decided it. The non-convergence golden (8→9→10→5→12, every count true) is this
+environment's own launcher-review loop, 2026-08-16–17, run under an undeclared
+"material" criterion; the two series are two populations under two criteria and are
+cited separately for exactly the reason the migration section gives. Re-derive when
+the review routes or the bound models change.

package/claude/guides/review-request.md

@@ -26,7 +26,11 @@ verification_focus:
 This guide is a scoped extension of the global Coding Guidelines. Use it when
 composing what you ask a reviewer for — the request, the evidence bar, the
 verdict shape. It does not cover when to review, how deep, or what counts as
-material (the severity ladder and review loop in `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/coding-staged-workflow.md` own that),
+material — that last question splits in two: the severity ladder and review loop in
+`${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/coding-staged-workflow.md` own *how bad*,
+while whether something is a defect at all, of which class, and what "zero" is
+counted over is the defect criterion, owned by
+`${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/review-defect-criteria.md`. Nor
 which reviewer kind to route to — the convergence heuristic in
 `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/verification-discipline.md` owns that. Phrasing a prompt for a specific model
 family is out of scope here; where that guidance ships, the rule that needs it
@@ -38,6 +42,16 @@ is a per-model claim; these are the failures that persist regardless of who
 reviews. Every rule names the evidence behind it, because a review guide that
 asserts without evidence would fail its own bar.
 
+## Declare the criterion
+
+Before composing anything else, name the defect criterion the review runs under —
+the per-system-type definition of what a defect is, its class enum, and what "zero"
+is counted over. `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/review-defect-criteria.md`
+owns choosing it; this guide assumes one is declared. Put `Criterion: <name>` at the
+top of the packet with that criterion's goldens pasted verbatim — a definition
+without goldens does not classify consistently at the boundary, and an undeclared
+criterion means every reviewer substitutes its own.
+
 ## Demand a failure path, not a gap
 
 The dominant reviewer failure is not hallucination. Across 372 rejected

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

@@ -80,6 +80,7 @@ patching them one at a time is a queue that refills.
 
 - 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).
 - Iterate until material issues reach zero: review, identify material issues, fix them, and review again.
+- "Material issues reach zero" is counted over the declared defect criterion's stop-relevant class; choosing and declaring that criterion is owned by `${CODEX_HOME:-$HOME/.codex}/guides/review-defect-criteria.md`.
 - Use the severity contract for materiality — the canonical definition is the ladder below; external review tools map their levels onto it: blocker, high, and medium are material; low and info are non-material.
 - Treat blocker as primary happy-path or core-contract failure.
 - Treat high as supported user, environment, data, or execution path failure.

package/codex/guides/review-defect-criteria.md

@@ -0,0 +1,205 @@
+---
+guide_id: review-defect-criteria
+language: en
+status: active
+use_when:
+  - declaring what counts as a defect before dispatching any review
+  - choosing or writing the defect criterion for a system type × work goal
+  - a review loop plateaus, diverges, or its "material 0" stop never arrives
+  - a finding's class is contested at the boundary, or two lenses class it differently
+core_rules:
+  - choose and declare the criterion before the review starts — undeclared, every reviewer substitutes its own
+  - the severity ladder answers how bad; the criterion answers whether it is a defect, of which class, and what "zero" is counted over
+  - a criterion with an empty cell is a hunch, not a criterion — do not start the review
+  - paste the goldens into the packet verbatim; a definition alone does not classify consistently at the boundary
+  - put the class enum on the accepting channel where one exists; on prose routes, run the fold procedure
+  - a mixed packet is split — never run two observers in one trajectory
+verification_focus:
+  - every dispatched packet names its criterion and carries its goldens
+  - each round audits reported class against post-measurement class; repeated disagreement mints the next golden
+  - the stop condition is evaluated over the stop-relevant class only, never the whole finding count
+---
+
+# Review Defect Criteria
+
+A defect criterion is chosen, not assumed. This guide is a scoped extension of
+`${CODEX_HOME:-$HOME/.codex}/guides/review-request.md`: before that guide's
+request composition starts, this one decides what the review is hunting. The
+evidence: one codebase, two stop criteria, opposite trajectories.
+
+| Rounds | Criterion | Trajectory |
+|---|---|---|
+| early | material = contract violation **or** unprotected contract sentence, small frozen surface | 10 → 4 → 1 → 0 |
+| late | same, scoped to client-observable behavior | 17 → 19 → 21 → 23 → 19 — **plateau** |
+| final | split classes: behavioral_defect / coverage_gap / doc_gap; stop = behavioral 0 | behavioral 10 → 5 — falling again |
+
+The plateau was the criterion, not the code: counting "a contract sentence no test
+protects" as a defect means every fix adds contract rows, each a potential defect
+next round — a self-refilling criterion cannot reach zero while its surface grows.
+Yet that same criterion is exactly right for a library, where an unprotected promise
+is a first-class defect. Neither is wrong; starting without choosing is.
+
+The **severity ladder** (in `${CODEX_HOME:-$HOME/.codex}/guides/coding-staged-workflow.md`)
+answers *how bad* a finding is. The **criterion** answers *whether* it is a defect at
+all, of which class, and what "zero" is counted over. The plateau happened entirely
+inside "material" — no severity adjustment could have ended it. Ordering: system type
++ goal → defect criterion → classification → defect? → severity → materiality → stop.
+
+## The criterion schema
+
+One entry carries all of these. An empty cell makes it a hunch, not a criterion — do
+not start the review on it.
+
+| Field | Meaning |
+|---|---|
+| observer | whose eyes judge — client, caller, operator, a model reading the output |
+| defect | what the observer must experience |
+| classes | the enum, exactly ONE class stop-relevant; the others are relief valves that keep the stop class honest |
+| evidence | what one finding must present |
+| non-defects | defect-lookalikes excluded by this criterion — named explicitly |
+| stop condition | what "0" means, counted over the stop class, and WHY it is reachable — how a growing surface is pinned |
+| misclassification cost | which error is expensive — the direction to tell the reviewer to lean |
+| goldens | ≥2 positive, ≥2 negative, ≥1 boundary; each with why, date, and provenance: `measured` (dated incident) or `constructed` (authored to pin a boundary) |
+
+## The catalog
+
+Four system types. A starting set, not a census.
+
+### Web service / API surface (contract compliance)
+
+- **Observer**: the HTTP client.
+- **Defect**: a client today receives a response that differs from the contract — status code, envelope, stream terminal frames, the model actually run, isolation, resource caps.
+- **Classes**: `behavioral_defect` (stop-relevant) · `coverage_gap` · `doc_gap`.
+- **Evidence**: the concrete request and observed vs promised response.
+- **Non-defects**: internal lifecycle (unless a request sequence shows two different responses), absence of a test, documentation wording.
+- **Stop**: behavioral 0 — reachable: the code surface is finite and shrinks monotonically unless a fix creates a new behavioral defect.
+- **Misclassification cost**: false negatives (a client actually breaks); but inflating coverage gaps into defects destroys the stop condition — audit category creep separately.
+- **Goldens** (all `measured`, 2026-08-13–15):
+  - **+** `GET` on a nonexistent path returned 405, not 404 — an existing-method complaint attached to a path that does not exist.
+  - **+** a streaming endpoint's terminal delta carried only `output_tokens`, so cache/input token counts never reach a streaming client — non-streaming was correct, which is why nobody saw it.
+  - **−** "no test catches a one-line flip of this default": today's behavior is correct — `coverage_gap` here, a defect only under the library criterion.
+  - **−** child-process kill grace period — out of scope until a request sequence shows a client-visible difference; pins the observer to the client.
+  - **±** rejecting a documented-as-valid boundary value (compression 100, docs say "below 100 requires jpeg/webp") — the documentation is what makes it a defect; without that sentence it is taste.
+
+### Library / SDK / contract-first system
+
+- **Observer**: the caller **and** the future maintainer.
+- **Defect**: a promise violated today, or a promise unprotected — a one-line change breaks it and nothing catches it. The API criterion's `coverage_gap` is first-class here.
+- **Classes**: `contract_defect` (stop-relevant) · `style_note` · `internal_change`.
+- **Evidence**: for a violation, as above; for an unprotected promise, the promise sentence + the one-line change that breaks it + the absence of any catching test.
+- **Non-defects**: style, internal structure.
+- **Stop**: caution — this criterion self-refills while the contract grows. Declare "0" only over a surface whose growth has stopped; on a growing surface, narrow the stop to "every promise this change added is protected."
+- **Misclassification cost**: balanced — miss an unprotected promise and the next refactor breaks it silently; over-report and the loop never ends.
+- **Goldens**:
+  - **+** a streaming-image event test matched only `.completed`, so an edit stream misnamed `image_generation.completed` still passed — mutation survival showed the promise unprotected. (`measured`, 2026-08-13–15)
+  - **+** the contract promised "storage serves a large image at least once"; the code evicted it on the next request — resolved by fixing the **contract**: the disagreement is the defect, whichever side moves. (`measured`, 2026-08-13–15)
+  - **−** renaming an internal helper no document promises — the observer holds the contract; undocumented internals carry no promise. (`measured`, 2026-08-13–15)
+  - **−** a caller breaking on undocumented iteration order — no promise existed; the rename boundary pinned from the caller's side. (`constructed`, 2026-08-19)
+  - **±** an inventory-listed test turns out vacuous — asserts nothing about its promise. "A test exists" is a claim about names until the assertion is read; hand the reviewer "check the assertion, not the name." (`measured`, 2026-08-13–15)
+
+### AI workbench / harness (agent orchestration, review loops, verification pipelines)
+
+- **Observer**: the operator, and any model consuming the harness's output.
+- **Defect**: **a false signal that looks true** — a wrong PASS, a vacuous test, a silent fallback, a packet missing the call site, a wrong denominator. Being wrong is not the defect; being wrong while *looking right* is. Second form: a run claimed without provable dispatch — no receipt.
+- **Classes**: `false_signal` (stop-relevant) · `detected_miss`. An unproven dispatch — a run or PASS claimed with no receipt — is classed `false_signal`, not given its own relief valve: a signal that cannot be shown true is counted false, or a round could declare completion while every dispatch stayed unproven.
+- **Evidence**: the input on which the instrument gave a false verdict, plus the known correct answer. The standard probe: run the instrument against an input whose answer is known to be the opposite.
+- **Non-defects**: one output's style; a false positive the harness itself **detected** — a caught error is the harness working.
+- **Stop**: every PASS emitted this run survives a known-opposite check and evidences its own dispatch. The unit is "this run's signals are trustworthy," not a standing zero.
+- **Misclassification cost**: false passes dominate. An instrument bug reporting failure dies in minutes because someone looks; one reporting success survives — a selection effect.
+- **Goldens**:
+  - **+** a shell test runner received one nonexistent path (zsh does not word-split an unquoted variable), so every run exited 1 and every mutation reported KILLED — a green instrument that never ran its subject. (`measured`, 2026-08-13–15)
+  - **+** a test-inventory grep matched only `^test('...'` and missed every parameterized name; three reviewers judged a populated file empty — nothing tied the inventory's denominator to the source's own count. (`measured`, 2026-08-13–15)
+  - **+** a negative control kept passing after a faithful revert of the fix it was written against — a guard satisfied by an absence, a false PASS about the gate itself; found only by re-running reverts. (`measured`, 2026-08)
+  - **+** a review round returned "clean" with no receipt evidencing that the declared packet was dispatched on the exact seat — `false_signal` although nothing observed was wrong: what the stop refuses is absence of proof of dispatch, not proof of falsity. (`constructed`, 2026-08-19, pinned after a classification dispute at exactly this boundary)
+  - **−** one reviewer over-classed an item as material; another lens plus measurement filtered it — the harness caught it, so it worked: `detected_miss`, not a defect. (`measured`, 2026-08-13–15)
+  - **−** five review rounds returned 8 → 9 → 10 → 5 → 12 findings, refusing to converge — and every count was true. A truthful unpleasant signal is not a false signal; the defect lived in the undeclared criterion. (`measured`, 2026-08-16–17)
+  - **±** a surviving mutation proved equivalent — the platform already normalized what the mutated guard checked. Neither a harness defect nor a test gap; but a harness that auto-reads "survived = gap" has a defect in that rule. (`measured`, 2026-08-13–15)
+
+### Decision ontology (an ontology a model decides from)
+
+- **Observer**: a model or agent deciding from the ontology alone.
+- **Defect**: a representation that produces a wrong decision or blocks a right one: overlapping concept boundaries, a missing distinction the decision needs, an instance contradicting reality, a wrong relation direction or cardinality, a name implying what the definition does not say.
+- **Classes**: `decision_defect` (stop-relevant) · `representation_note` · `out_of_scope_gap`.
+- **Evidence**: a **decision scenario** — "answered from the ontology alone, this question yields X; reality is Y" — with the question, the path taken, and the ground truth.
+- **Non-defects**: representation format, completeness as such, a question the model would get wrong without the ontology too.
+- **Stop**: zero wrong decisions over the agreed scenario set. The set is the scope — fix it first, or this criterion self-refills like the library one.
+- **Misclassification cost**: situational — feeding a hard gate makes false negatives expensive; exploratory aid makes false positives expensive. Filling this cell is mandatory at declaration.
+- **Goldens** (all `constructed`, 2026-08-19, authored to pin boundaries the source loop's decision-scenario framing left open):
+  - **+** `Customer` and `Account` both define "the paying party"; a refund-routing question resolves through both paths — overlap is a decision defect even when each definition is individually correct.
+  - **+** `Order —hasOne→ Payment` while split payments exist — cardinality is a claim, and a false claim misleads the deciding model.
+  - **−** a verbose concept description — no decision changes; form is outside this observer's sight.
+  - **−** a domain absent that no scenario in the agreed set needs — completeness is scoped by the set, not the world.
+  - **±** the distinction exists but the model cannot find it (name or link missing) — with the observer fixed as "a model seeing only the ontology," unreachable is a representation defect, not a search defect. The observer clause decides the class.
+
+## Before any review
+
+1. Write one sentence: the system type and this work's goal. ("API surface — make the responses clients receive today match the contract." / "Harness — make this run's PASS signals trustworthy.")
+2. Pick a criterion from the catalog, or fill the schema fresh. A cell you cannot fill means the review does not start.
+3. Paste the goldens into the packet verbatim. Never the definition alone.
+4. Declare the stop condition and why it is reachable — or how the scope was pinned to make it so.
+5. Put the classification on the accepting channel (next section).
+6. Audit every round: reported class vs the class confirmed after measurement. A repeated disagreement is the next golden.
+
+## Enforcing the enum, by channel
+
+Ranked by how much the channel refuses for you:
+
+1. **A route with a submit schema**: classification is a required enum field. The
+   measured precedent is anchors — 2,466 of 2,466 findings carried one, because the
+   schema refuses output without it. Where this channel exists, use it.
+2. **Prose-packet routes** (the shipped deep-review methods): the packet header
+   declares `Criterion: <name>` with the goldens pasted verbatim, and the dispatching
+   agent runs this fold procedure on what comes back:
+   1. For each returned finding row, look up its class against the declared enum.
+   2. A row carrying a class from the enum enters the findings ledger under that class.
+   3. A row with no class, or a class outside the enum, is **not admitted**: send it
+      back once for classification, or record it as refused with the reason. Never
+      admit it unclassified, and never guess its class for it.
+   4. Count the stop condition over the stop-relevant class only.
+   5. Record the audit pair (reported class, confirmed class) for procedure step 6.
+
+   Stated honestly: on a prose route this is steering, not control — the fold is
+   performed by an agent following this guide, and nothing structural refuses a
+   class-less row for it. That is the known weaker result of a request-only rule.
+3. A structural criterion slot in the review dispatch machinery is deliberately not
+   part of this guide: a criterion is per-review while dispatch config is per-launch,
+   and a slot with no schema-backed consumer would be an inert value. Until such a
+   channel exists, ranks 1–2 are the real ones.
+
+## Golden lifecycle
+
+- **Admission**: only a golden that decides a boundary the definition leaves open,
+  evidenced by a recorded classification disagreement or an audited misclassification;
+  provenance labeled `measured` or `constructed`, each with its why and date.
+- **Overturn**: only by a measured counterexample. Correct the golden in place — this
+  guide describes the present — plus a dated decision record, in whatever channel the
+  repo keeps decisions, naming the closed golden and the counterexample. Silent
+  deletion is forbidden: a wrong golden makes reviewers systematically wrong, and an
+  untracked fix hides that it ever did.
+
+## Declaring, switching, and mixed packets
+
+- Every dispatched packet names its criterion. A harness round declares `AI harness`;
+  a round whose system type has no catalog entry declares a **task-local criterion**,
+  written in the packet itself, conforming to the schema above and labeled task-local
+  — repeated use is what earns a catalog entry.
+- A mixed packet is split into one packet per criterion. Two observers in one
+  trajectory produce findings no single stop condition can count.
+- When a criterion changes mid-loop: re-classify only the findings still open; rounds
+  already recorded are dated history. Never splice pre- and post-switch counts into
+  one series — they count different things.
+
+## Evidence base
+
+Derived from a 39-round adversarial review loop (3 lenses × a frontier reviewer) on a
+peer OAuth CLI-API adapter, 2026-08-13–15: the same codebase plateaued at
+17→19→21→23→19 findings under a self-refilling criterion and resumed falling
+(behavioral 10→5) the round the classes were split and the stop counted over
+`behavioral_defect` alone. The boundary evidence is from the same loop: a packet
+instruction saying "do not inflate coverage gaps" still left two lenses classing one
+finding `doc_gap` and `behavioral_defect`, both defensibly — one golden would have
+decided it. The non-convergence golden (8→9→10→5→12, every count true) is this
+environment's own launcher-review loop, 2026-08-16–17, run under an undeclared
+"material" criterion; the two series are two populations under two criteria and are
+cited separately for exactly the reason the migration section gives. Re-derive when
+the review routes or the bound models change.

package/codex/guides/review-request.md

@@ -26,7 +26,11 @@ verification_focus:
 This guide is a scoped extension of the global Coding Guidelines. Use it when
 composing what you ask a reviewer for — the request, the evidence bar, the
 verdict shape. It does not cover when to review, how deep, or what counts as
-material (the severity ladder and review loop in `${CODEX_HOME:-$HOME/.codex}/guides/coding-staged-workflow.md` own that),
+material — that last question splits in two: the severity ladder and review loop in
+`${CODEX_HOME:-$HOME/.codex}/guides/coding-staged-workflow.md` own *how bad*,
+while whether something is a defect at all, of which class, and what "zero" is
+counted over is the defect criterion, owned by
+`${CODEX_HOME:-$HOME/.codex}/guides/review-defect-criteria.md`. Nor
 which reviewer kind to route to — the convergence heuristic in
 `${CODEX_HOME:-$HOME/.codex}/guides/verification-discipline.md` owns that. Phrasing a prompt for a specific model
 family is out of scope here; where that guidance ships, the rule that needs it
@@ -38,6 +42,16 @@ is a per-model claim; these are the failures that persist regardless of who
 reviews. Every rule names the evidence behind it, because a review guide that
 asserts without evidence would fail its own bar.
 
+## Declare the criterion
+
+Before composing anything else, name the defect criterion the review runs under —
+the per-system-type definition of what a defect is, its class enum, and what "zero"
+is counted over. `${CODEX_HOME:-$HOME/.codex}/guides/review-defect-criteria.md`
+owns choosing it; this guide assumes one is declared. Put `Criterion: <name>` at the
+top of the packet with that criterion's goldens pasted verbatim — a definition
+without goldens does not classify consistently at the boundary, and an undeclared
+criterion means every reviewer substitutes its own.
+
 ## Demand a failure path, not a gap
 
 The dominant reviewer failure is not hallucination. Across 372 rejected

package/compose/assemble.py

@@ -272,11 +272,18 @@ def replace_atomically(path, text):
     learn/migrate-learnings.py has had this discipline and states the reason; it now shares
     this one implementation rather than keeping a second. The temp file is a sibling so the
     replace stays on one filesystem, where os.replace is atomic.
+
+    An existing target's permission bits ride through the swap: the temp is born with
+    umask mode, so replacing a user-restricted file — a 0600 AGENTS.md — silently widened
+    it to world-readable. Ownership is not copied; this never runs with the privilege to
+    change it, and a same-owner rename keeps it anyway.
     """
     path.parent.mkdir(parents=True, exist_ok=True)
     tmp = path.with_name(path.name + ".tmp-agent-bios")
     try:
         tmp.write_text(text, encoding="utf-8")
+        if path.exists():
+            tmp.chmod(path.stat().st_mode & 0o777)
         os.replace(tmp, path)
     finally:
         if tmp.exists():

package/compose/domains.json

@@ -100,6 +100,7 @@
     "llm-capability-boundary-patterns.md": {"tier": "domain", "domains": ["llm-pipeline-dev"]},
     "llm-capability-boundary.md": {"tier": "domain", "domains": ["llm-pipeline-dev"]},
     "mock-realization-boundary.md": {"tier": "domain", "domains": ["builder-base"]},
+    "review-defect-criteria.md": {"tier": "domain", "domains": ["builder-base"]},
     "review-request.md": {"tier": "domain", "domains": ["builder-base"]},
     "session-distill-workflow.md": {"tier": "infra", "domains": []},
     "learning-flow.md": {"tier": "infra", "domains": []},

package/launch/agent-launch.py

@@ -3021,9 +3021,10 @@ def _sha256_file(path: str) -> str:
     return digest.hexdigest()
 
 
-def publish_atomically(target: pathlib.Path, text: str) -> None:
-    """Write `text` at `target` so a reader sees the old file or the complete new one, and
-    a failure leaves neither a partial file nor a temporary.
+def publish_atomically(target: pathlib.Path, payload: str | bytes,
+                       mode: int | None = None) -> None:
+    """Write `payload` at `target` so a reader sees the old file or the complete new one,
+    and a failure leaves neither a partial file nor a temporary.
 
     `write_text` creates the FINAL name and then fills it, so a concurrent reader — and
     the receipt fold globs exactly its directory — could observe a truncated record, and a
@@ -3036,10 +3037,17 @@ def publish_atomically(target: pathlib.Path, text: str) -> None:
     the preset save wrote its temporary and published it with no `try`, so an `os.replace`
     that failed left a complete temporary file beside the untouched preset file, for the
     next save's glob or the next reader to find (spec round 2, #6). The removal never
-    masks the error that caused it."""
+    masks the error that caused it. The registration wizard was the third copy, with
+    neither the boundary nor the cleanup (writable-scratch round, #6) — it publishes
+    BYTES it snapshotted and re-applies the file's prior mode, hence the two optionals."""
     temporary = target.with_name(f".{target.name}.{os.getpid()}.tmp")
     try:
-        temporary.write_text(text, encoding="utf-8")
+        if isinstance(payload, bytes):
+            temporary.write_bytes(payload)
+        else:
+            temporary.write_text(payload, encoding="utf-8")
+        if mode is not None:
+            temporary.chmod(mode)
         os.replace(temporary, target)
     except BaseException:
         try:
@@ -5303,32 +5311,39 @@ def _trial_registration(
     through the genuine load_config — same merge order, same validation, same
     collision refusal. Returns None on acceptance, the reader's message on refusal."""
     trial = pathlib.Path(tempfile.mkdtemp(prefix="agent-launch-register-"))
-    shutil.copy(config_path, trial / config_path.name)
-    for sibling in (USER_PRESETS_NAME, USER_LAUNCHER_NAME):
-        source = config_path.with_name(sibling)
-        if source.is_file():
-            shutil.copy(source, trial / sibling)
-    methods_source = user_methods_path(config_path)
-    existing = methods_source.read_text(encoding="utf-8") if methods_source.is_file() else USER_METHODS_HEADER
-    candidate = trial / USER_METHODS_NAME
-    try:
-        candidate.write_text(existing + block, encoding="utf-8")
-    except OSError as exc:
-        # A read-only config dir or a full disk lost every answer the
-        # user had just typed. Reported like any other refusal instead.
-        raise LaunchError(f"cannot write {candidate}: {exc}") from exc
-    candidate.chmod(0o600)
+    # One finally over EVERYTHING after the mkdtemp — the copies, the candidate
+    # write, both readers: the trial is a scratch workspace, and every exit used
+    # to leave it behind, one directory per attempt, for the life of the temp
+    # area (writable-scratch round, #7).
     try:
-        trial_config = load_config(trial / config_path.name)
-        # The REAL pipeline is both readers, not the first one. load_config accepts a
-        # method whose instructions name a slot core does not provide; load_review_methods
-        # — the reader every launch actually goes through — refuses it. Trialling only the
-        # first wrote the block, told the user it was live, and left the refusal for the
-        # next launch. A trial that does not run the reader that decides is not a trial.
-        load_review_methods(trial_config)
-    except LaunchError as exc:
-        return str(exc)
-    return None
+        shutil.copy(config_path, trial / config_path.name)
+        for sibling in (USER_PRESETS_NAME, USER_LAUNCHER_NAME):
+            source = config_path.with_name(sibling)
+            if source.is_file():
+                shutil.copy(source, trial / sibling)
+        methods_source = user_methods_path(config_path)
+        existing = methods_source.read_text(encoding="utf-8") if methods_source.is_file() else USER_METHODS_HEADER
+        candidate = trial / USER_METHODS_NAME
+        try:
+            candidate.write_text(existing + block, encoding="utf-8")
+        except OSError as exc:
+            # A read-only config dir or a full disk lost every answer the
+            # user had just typed. Reported like any other refusal instead.
+            raise LaunchError(f"cannot write {candidate}: {exc}") from exc
+        candidate.chmod(0o600)
+        try:
+            trial_config = load_config(trial / config_path.name)
+            # The REAL pipeline is both readers, not the first one. load_config accepts a
+            # method whose instructions name a slot core does not provide; load_review_methods
+            # — the reader every launch actually goes through — refuses it. Trialling only the
+            # first wrote the block, told the user it was live, and left the refusal for the
+            # next launch. A trial that does not run the reader that decides is not a trial.
+            load_review_methods(trial_config)
+        except LaunchError as exc:
+            return str(exc)
+        return None
+    finally:
+        shutil.rmtree(trial, ignore_errors=True)
 
 
 def register_reviewer_wizard(
@@ -5550,60 +5565,67 @@ def register_reviewer_wizard(
                                  back_hint=t("corpus.back.hint"))
                     return False
                 mode = (write_target.stat().st_mode & 0o777) if existed else 0o600
-                temporary = write_target.with_name(
-                    f".{write_target.name}.{os.getpid()}.tmp"
-                )
-                temporary.write_bytes(before + block.encode())
-                temporary.chmod(mode)
-                os.replace(temporary, write_target)
-                # Unreachable while the trial is the real pipeline — and
-                # load-bearing exactly when it is not: a post-write failure must
-                # restore the pre-write state (bytes, mode, or ABSENCE) and say
-                # so, never leave a corrupt registry behind a green screen.
                 try:
-                    fresh = load_config(config_path)
-                except LaunchError:
-                    fresh = None
-                if fresh is None or answers["id"] not in load_review_methods(fresh):
-                    # Restore ONLY when the file still holds exactly our write:
-                    # unconditional rollback would destroy an edit that landed in
-                    # the meantime; if the bytes moved, the human owns the merge.
-                    current = (
-                        write_target.read_bytes() if write_target.is_file() else b""
-                    )
-                    if current != before + block.encode():
-                        # Its own sentence, because this branch deliberately does NOT
-                        # roll back — someone else's edit landed and the human owns the
-                        # merge. Sharing the restore branch's message told the user the
-                        # file had been restored in the one case where it was left
-                        # exactly as the other writer wrote it.
-                        _corpus_info(
-                            ui, t("wizard.title"), [t("wizard.postwrite.raced.line")],
-                            back_hint=t("corpus.back.hint"),
-                        )
-                        return False
-                    if existed:
-                        restore = write_target.with_name(
-                            f".{write_target.name}.{os.getpid()}.restore"
+                    # The shared primitive owns the temporary's lifecycle: on any
+                    # failure it removes its own temp and re-raises. A directory at
+                    # the target, a permission flip, a full disk — each used to
+                    # escape here as a raw OSError, PAST the retained-answer loop,
+                    # with the completed temporary left beside the untouched file.
+                    # Publication failure is a refusal like any other: the reader's
+                    # loop keeps the answers, and the screen shows the OS's words.
+                    publish_atomically(write_target, before + block.encode(), mode)
+                except OSError as exc:
+                    verdict = f"cannot write {write_target}: {exc}"
+                if verdict is None:
+                    # Unreachable while the trial is the real pipeline — and
+                    # load-bearing exactly when it is not: a post-write failure must
+                    # restore the pre-write state (bytes, mode, or ABSENCE) and say
+                    # so, never leave a corrupt registry behind a green screen.
+                    try:
+                        fresh = load_config(config_path)
+                    except LaunchError:
+                        fresh = None
+                    if fresh is None or answers["id"] not in load_review_methods(fresh):
+                        # Restore ONLY when the file still holds exactly our write:
+                        # unconditional rollback would destroy an edit that landed in
+                        # the meantime; if the bytes moved, the human owns the merge.
+                        current = (
+                            write_target.read_bytes() if write_target.is_file() else b""
                         )
-                        restore.write_bytes(before)
-                        restore.chmod(mode)
-                        os.replace(restore, write_target)
-                    else:
-                        write_target.unlink(missing_ok=True)
-                    _corpus_info(ui, t("wizard.title"), [t("wizard.postwrite.line")],
-                                 back_hint=t("corpus.back.hint"))
-                    return False  # pre-write state restored above
-            config.clear()
-            config.update(fresh)
-            registry.clear()
-            registry.update(load_review_methods(config))
-            _corpus_info(
-                ui, t("wizard.title"),
-                [t("wizard.done.line").format(method_id=answers["id"])],
-                back_hint=t("corpus.back.hint"),
-            )
-            return True
+                        if current != before + block.encode():
+                            # Its own sentence, because this branch deliberately does NOT
+                            # roll back — someone else's edit landed and the human owns the
+                            # merge. Sharing the restore branch's message told the user the
+                            # file had been restored in the one case where it was left
+                            # exactly as the other writer wrote it.
+                            _corpus_info(
+                                ui, t("wizard.title"), [t("wizard.postwrite.raced.line")],
+                                back_hint=t("corpus.back.hint"),
+                            )
+                            return False
+                        if existed:
+                            restore = write_target.with_name(
+                                f".{write_target.name}.{os.getpid()}.restore"
+                            )
+                            restore.write_bytes(before)
+                            restore.chmod(mode)
+                            os.replace(restore, write_target)
+                        else:
+                            write_target.unlink(missing_ok=True)
+                        _corpus_info(ui, t("wizard.title"), [t("wizard.postwrite.line")],
+                                     back_hint=t("corpus.back.hint"))
+                        return False  # pre-write state restored above
+            if verdict is None:
+                config.clear()
+                config.update(fresh)
+                registry.clear()
+                registry.update(load_review_methods(config))
+                _corpus_info(
+                    ui, t("wizard.title"),
+                    [t("wizard.done.line").format(method_id=answers["id"])],
+                    back_hint=t("corpus.back.hint"),
+                )
+                return True
         action = choose(
             t("wizard.refused.title"),
             [
@@ -6140,21 +6162,25 @@ def preset_from_plan(
                     f"is not an effort — saving would drop it and {other} would reload at "
                     f"its host default. Fix that entry in the launch profile and save again."
                 )
+            # A non-table where the normalized home would go — `tier_overrides.<host>` or
+            # its `frontier` entry authored as a value. The serializer now carries such a
+            # value VERBATIM (spec round 7, #3), so this normalizer cannot write into it
+            # (`setdefault("frontier", {})` on a string was round 24, #8's raw TypeError)
+            # and cannot skip past it either: skipping used to be safe only because the
+            # renderer refused the block, and with that refusal gone a skip would drop
+            # the authored `frontier_effort` in silence. When the authored effort is that
+            # host's default there is nothing to write and the carry is faithful; when it
+            # is not, the home is genuinely occupied and the save refuses naming both —
+            # the one case D-20260817-105da4 keeps a named refusal for.
             block = scoped.get(other)
+            occupied = None
+            existing = None
             if block is not None and not isinstance(block, dict):
-                # Left exactly as authored; the serializer names it rather than this
-                # silently repairing a shape it is not the owner of.
-                continue
-            existing = (block or {}).get("frontier")
-            if existing is not None and not isinstance(existing, dict):
-                # Left exactly as authored, for the reason the host-block branch above says
-                # in the same words: the serializer owns unwritable shapes and names them.
-                # This normalizer wrote into the block regardless, so `setdefault("frontier",
-                # {})` handed back the STRING and `["effort"] =` left Save as a raw
-                # TypeError — past the named boundary its workhorse twin arrives through
-                # (round 24, #8). Nothing is dropped by skipping: the renderer's `_table`
-                # door refuses this very entry by name a moment later.
-                continue
+                occupied = f"tier_overrides.{other}"
+            else:
+                existing = (block or {}).get("frontier")
+                if existing is not None and not isinstance(existing, dict):
+                    occupied = f"tier_overrides.{other}.frontier"
             if isinstance(existing, dict) and existing.get("effort") not in (None, effort):
                 # The contradiction build_plan already refuses, reached from the host that
                 # does not launch it. Named here rather than resolved: picking one of two
@@ -6179,6 +6205,19 @@ def preset_from_plan(
                 .get("frontier", {}).get("effort")
             ):
                 continue
+            if occupied is not None:
+                # AFTER the default elision on purpose, unlike the contradiction above: a
+                # non-table home states no effort to contradict, so a default-valued
+                # authoring writes no line and reloads faithfully. A non-default one has
+                # exactly one home and that home is occupied by a value the save carries
+                # verbatim — writing both is impossible, and dropping either is the
+                # silence S4 forbids.
+                raise LaunchError(
+                    f"preset {name!r}: {other} authors frontier_effort={effort!r}, whose "
+                    f"saved home is tier_overrides.{other}.frontier.effort, and {occupied} "
+                    f"holds a non-table value the save carries verbatim — it cannot write "
+                    f"both. Remove one of them in the launch profile and save again."
+                )
             scoped.setdefault(other, {}).setdefault("frontier", {})["effort"] = effort
     return fields, scoped, review_block
 
@@ -6270,11 +6309,11 @@ def render_preset_block(
     tier_overrides: dict[str, Any],
     review_block: dict[str, Any] | None = None,
 ) -> str:
-    # One door for every table this writes back, hoisted here from inside the review-arm
-    # loop so the tier overrides get the same named boundary. Save failures are contracted
-    # to arrive as LaunchError at the settings hub, and the inactive-host overrides had no
-    # boundary at all: a scalar host block was silently FILTERED OUT before it arrived, and
-    # a scalar tier block reached `.items()` as a raw AttributeError (round 22, #9).
+    # One door for every place only a table can stand — an arm's `methods`, its `base`,
+    # each binding. Save failures are contracted to arrive as LaunchError at the settings
+    # hub, never a raw escape or a silent filter (round 22, #9). The tier overrides and
+    # whole review arms no longer pass through it: a non-table node there is not
+    # malformed, it is a VALUE its parent table spells (spec round 7, #2/#3).
     def _table(value, where):
         if not isinstance(value, dict):
             raise LaunchError(
@@ -6287,51 +6326,58 @@ def render_preset_block(
     lines = [f"[presets.{_toml_key(name)}]"]
     for key, value in fields.items():
         lines.append(f"{key} = {_toml_scalar(value)}")
-    for host, tiers in tier_overrides.items():
-        for tier, override in _table(tiers, f"tier_overrides.{host}").items():
-            # Through the SAME recursive emitter the review arms use. This was a flat loop
-            # over one level, so an inactive override holding a sub-table reached
-            # `_toml_scalar`, which gives a bare table no spelling — a profile the launcher
-            # accepts died at Save with `cannot serialize preset value: {'nested': 1}`,
-            # naming neither the host, the tier, nor the key (spec round 3, #6). Verbatim
-            # carry has no depth limit here for the reason it has none in an arm (round 24,
-            # #7), and the emitter puts every leaf through `_toml_key` — round 24 #10's half
-            # — and every leaf VALUE through `_arm_scalar`, so a genuinely unwritable entry
-            # is refused naming `tier_overrides.<host>.<tier>.<key>` rather than its repr.
-            _emit_arm_table(
-                lines,
-                f"presets.{_toml_key(name)}.tier_overrides"
-                f".{_toml_key(host)}.{_toml_key(tier)}",
-                _table(override, f"tier_overrides.{host}.{tier}"),
-                name, f"tier_overrides.{host}.{tier}",
-            )
+    if tier_overrides:
+        # The whole tree through the SAME recursive emitter the review arms use, from the
+        # `tier_overrides` root down. Verbatim carry has no depth limit (spec round 3, #6;
+        # round 24, #7) and no FLOOR either: a non-table node at any depth —
+        # `tier_overrides.claude = "x"`, or `…codex.workhorse = [1, 2]` — is TOML the
+        # launcher accepts, since only the active host's blocks are validated at load,
+        # and TOML spells it perfectly well as a value in its parent table; refusing it
+        # at Save made an accepted profile unsaveable, which is S4's complement (spec
+        # round 7, #3 — the per-tier loop this replaces held a table door at exactly the
+        # two depths the emitter now writes as values). The active host's blocks arrive
+        # normalized from `preset_from_plan`, so for them this emits the same
+        # `[…tier_overrides.<host>.<tier>]` tables it always did; every leaf key goes
+        # through `_toml_key` and every leaf value through `_arm_scalar`, so a genuinely
+        # unwritable entry is refused naming its full `tier_overrides.…` path.
+        _emit_arm_table(
+            lines, f"presets.{_toml_key(name)}.tier_overrides",
+            tier_overrides, name, "tier_overrides",
+        )
     if review_block is not None:
         # One sub-table per binding, and the method id is quoted: it is a user-chosen
         # name, so a bare key would break on anything a TOML bare key cannot hold.
         # Adding method N therefore appends exactly one table and touches nothing else.
         arms = review_block.get(REVIEW_ARMS_KEY)
+        # A whole arm authored as a VALUE — `hosts.codex = [1, 2]` — is TOML the launcher
+        # accepts, because only the launching arm is parsed, and TOML writes it back as a
+        # value in the parent hosts table; so that is what this does, rather than the
+        # refusal that made an accepted profile unsaveable (spec round 7, #2). Emitted
+        # before the table arms for the reason every emitter here puts scalars first; a
+        # value with no TOML form at all is refused through `_arm_scalar`, naming
+        # `review.hosts.<host>`.
+        value_arms = (
+            {host: arm for host, arm in arms.items() if not isinstance(arm, dict)}
+            if arms else {}
+        )
+        if value_arms:
+            lines.append("")
+            lines.append(f"[presets.{_toml_key(name)}.review.{REVIEW_ARMS_KEY}]")
+            for host in sorted(value_arms, key=_toml_key):
+                lines.append(
+                    f"{_toml_key(host)} = "
+                    f"{_arm_scalar(value_arms[host], name, f'review.{REVIEW_ARMS_KEY}.{host}')}"
+                )
         for prefix, block in (
             sorted((f"review.{REVIEW_ARMS_KEY}.{_toml_key(host)}", arm)
-                   for host, arm in arms.items())
+                   for host, arm in arms.items() if isinstance(arm, dict))
             if arms else [("review", review_block)]
         ):
-            # An untouched arm is written back exactly as authored, and "as authored"
-            # includes shapes this cannot serialize: a scalar where a table belongs made
-            # `"base" in block` a raw TypeError out of Save, after the launch had already
-            # happened. Save failures are contracted to arrive as LaunchError at the
-            # settings hub, so this one does too, naming the arm to look at.
-            if not isinstance(block, dict):
-                raise LaunchError(
-                    f"preset {name!r}: the review arm at {prefix!r} is "
-                    f"{type(block).__name__}, not a table — it cannot be written back. "
-                    f"Fix that entry in the launch profile and save again."
-                )
             # `.get`, because an untouched arm is written back exactly as authored and
             # a raw block need not carry both keys — only the edited arm is re-derived.
-            # The nested shapes get the same door as the arm itself: `base`, `methods` and
-            # each binding are tables or the save names the entry (round 19, #11) — the
-            # outer check above caught a scalar arm and let `.items()` on a scalar
-            # `methods` escape as AttributeError past the same boundary.
+            # The nested shapes each get a door: `base`, `methods` and each binding are
+            # tables or the save names the entry (round 19, #11), which once escaped as
+            # a raw AttributeError from `.items()` on a scalar `methods`.
             methods = _table(block.get("methods", {}), f"{prefix}.methods")
             # Everything else the arm carries. An untouched arm is promised back VERBATIM
             # and this serializer knew exactly two keys, so any other top-level field the
@@ -7799,14 +7845,17 @@ def child_agent_registrations(
     """THE Codex child-registration projection — `(tier, description, config path, config
     content)` per spawnable tier, in the order the backend receives them.
 
-    Pure: it reads the authored templates and derives, it writes nothing. One value, three
-    consumers — `run_contract` states it, `codex_agent_configs` materialises the content at
-    the path, and `project_args` writes the description and that path into argv — for the
-    same reason `review_mcp_servers` is one value: the template a tier resolves to decides
-    BOTH halves of what the backend is handed, and neither reached the contract. Repointing
-    one tier at another tier's template therefore changed the child's description and its
-    config path under a byte-identical contract, which is the one thing the contract's own
-    tail may not be false about (spec round 6, L7).
+    Pure in what it writes — nothing — but not in what it reads: the authored template
+    files and `XDG_CACHE_HOME`. One value, three consumers — `run_contract` states it,
+    `codex_agent_configs` materialises the content at the path, and `project_args` writes
+    the description and that path into argv — for the same reason `review_mcp_servers` is
+    one value: the template a tier resolves to decides BOTH halves of what the backend is
+    handed, and neither reached the contract. Repointing one tier at another tier's
+    template therefore changed the child's description and its config path under a
+    byte-identical contract, which is the one thing the contract's own tail may not be
+    false about (spec round 6, L7). And one CALL: `project_args` computes this once and
+    hands the same list to all three, because a projection that rereads its sources gives
+    each extra call a chance to answer differently (spec round 7, L7).
 
     The path is the config's IDENTITY, not an incidental location: its directory is a
     digest of the whole rendered set, so any edit to any template moves every path — and
@@ -7883,11 +7932,16 @@ def child_agent_registrations(
 
 
 def codex_agent_configs(
-    plan: dict[str, Any], materialize: bool
+    plan: dict[str, Any], materialize: bool,
+    registrations: list[tuple[str, str, pathlib.Path, str]] | None = None,
 ) -> dict[str, tuple[pathlib.Path, str]]:
     """The registration projection, written to disk. Everything decided is decided above;
-    this adds only the bytes and the failure modes writing them has."""
-    registrations = child_agent_registrations(plan)
+    this adds only the bytes and the failure modes writing them has. A caller that also
+    renders the contract passes the projection it rendered, so what is materialised is
+    the value the contract states rather than a second computation of it (spec round 7,
+    L7)."""
+    if registrations is None:
+        registrations = child_agent_registrations(plan)
     cache_root = registrations[0][2].parent
     # Every filesystem error here becomes a LaunchError, because `materialize` is exactly
     # the difference between --dry-run and a real launch: the projection skips these writes
@@ -8063,7 +8117,18 @@ def _cross_review_route(
     return " ".join(parts)
 
 
-def run_contract(plan: dict[str, Any]) -> str:
+def run_contract(
+    plan: dict[str, Any],
+    mcp_registrations: list[tuple[str, str, list[str]]] | None = None,
+    child_registrations: list[tuple[str, str, pathlib.Path, str]] | None = None,
+) -> str:
+    """The launch contract. A caller that also builds argv — `project_args` — passes the
+    MCP and child registration projections it computed, so this text and that argv are
+    generated from ONE call of each producer: the producers reread template files, the
+    environment and PATH, so calling them once per consumer let a mid-launch change put
+    one value here and another in argv under a byte-identical contract (spec round 7,
+    L7). A caller that renders only the contract omits them and the projections are
+    computed here — there is no argv beside the text to diverge from."""
     main_tier = plan["main_tier"]
     inactive = inactive_tiers(plan)
     if plan["delegation"]:
@@ -8152,7 +8217,9 @@ def run_contract(plan: dict[str, Any]) -> str:
     # Rendered from the whole triple, quoted as JSON, because reconciling this against argv
     # is the point: a command or an argument carrying a space would otherwise read as two.
     # Empty on every route that registers nothing, which includes every legacy one.
-    registrations = review_mcp_servers(plan)
+    registrations = (
+        review_mcp_servers(plan) if mcp_registrations is None else mcp_registrations
+    )
     mcp_clause = ""
     if registrations:
         rendered = "; ".join(
@@ -8181,7 +8248,11 @@ def run_contract(plan: dict[str, Any]) -> str:
     if plan["delegation"] and plan["host"] == "codex":
         rendered_children = "; ".join(
             f"{tier} = {json.dumps(description)} at {json.dumps(str(path))}"
-            for tier, description, path, _ in child_agent_registrations(plan)
+            for tier, description, path, _ in (
+                child_agent_registrations(plan)
+                if child_registrations is None
+                else child_registrations
+            )
         )
         child_clause = (
             f"Codex child agent registrations, in the order the backend receives them "
@@ -8340,9 +8411,12 @@ def review_mcp_servers(plan: dict[str, Any]) -> list[tuple[str, str, list[str]]]
 
     THE registration projection, and the only one: `run_contract` states this value and
     both argv builders write it, so the contract and the args cannot describe different
-    servers. It carries the args as well as the name and command because a triple is what
-    each backend receives — leaving them to a constant read at the argv site put a third
-    of the registration outside the value the contract is generated from.
+    servers — and `project_args` computes it ONCE, handing the same list to the contract
+    and to argv, because command resolution rereads PATH and a second call is a second
+    answer (spec round 7, L7). It carries the args as well as the name and command
+    because a triple is what each backend receives — leaving them to a constant read at
+    the argv site put a third of the registration outside the value the contract is
+    generated from.
 
     A rename here is a real change to what runs: the name below becomes the backend's
     `mcp_servers.<name>` namespace, which is how a tool call addresses the server."""
@@ -8565,7 +8639,21 @@ def project_args(plan: dict[str, Any], materialize_agents: bool = True) -> list[
         return []
     main = plan["tiers"][plan["main_tier"]]
     main_effort = tier_effort(plan, plan["main_tier"])
-    contract = run_contract(plan)
+    # Each registration projection is computed ONCE and every consumer below receives the
+    # same value. One producer was not enough: the contract render and the argv builders
+    # each CALLED it, and the producers reread template files, `XDG_CACHE_HOME` and PATH —
+    # so a change landing between the two calls put one value in the contract and another
+    # in argv, under a tail that promises what is described is what runs (spec round 7,
+    # L7). The child projection is computed exactly where both of its consumers live:
+    # codex argv with delegation on, and the contract's child clause, which renders under
+    # the same condition.
+    mcp_registrations = review_mcp_servers(plan)
+    child_registrations = (
+        child_agent_registrations(plan)
+        if plan["delegation"] and host == "codex"
+        else None
+    )
+    contract = run_contract(plan, mcp_registrations, child_registrations)
     if host == "codex":
         args = [
             "--model", main["model"],
@@ -8582,12 +8670,14 @@ def project_args(plan: dict[str, Any], materialize_agents: bool = True) -> list[
             policy_args = ["--sandbox", policy]
         args += policy_args
         if plan["delegation"]:
-            for tier, (path, description) in codex_agent_configs(plan, materialize_agents).items():
+            for tier, (path, description) in codex_agent_configs(
+                plan, materialize_agents, child_registrations
+            ).items():
                 args += [
                     "-c", f"agents.{tier}.description={json.dumps(description)}",
                     "-c", f"agents.{tier}.config_file={json.dumps(str(path))}",
                 ]
-        for name, command, server_args in review_mcp_servers(plan):
+        for name, command, server_args in mcp_registrations:
             args += [
                 "-c", f"mcp_servers.{name}.enabled=true",
                 "-c", f"mcp_servers.{name}.command={json.dumps(command)}",
@@ -8609,7 +8699,7 @@ def project_args(plan: dict[str, Any], materialize_agents: bool = True) -> list[
     else:
         policy_args = ["--permission-mode", policy]
     args += policy_args
-    servers = review_mcp_servers(plan)
+    servers = mcp_registrations
     if servers:
         mcp_config = {
             "mcpServers": {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-bios",
-  "version": "0.12.0",
-  "releaseDate": "2026-08-18",
+  "version": "0.12.1",
+  "releaseDate": "2026-08-19",
   "description": "A thin, low-level instruction layer for LLM CLI agents: one set of principles and behavior whichever model you run. Deploys into $HOME by copy via an explicit `agent-bios install`.",
   "bin": {
     "agent-bios": "install.sh"

package/provenance.json

@@ -1 +1 @@
-{"commit":"bfcc56715fb031564e370ce236739e4208b7c513","committedAt":"2026-08-18T17:23:41+09:00","dirty":false}
+{"commit":"471ff43022a60490b5e0e788f5ba6dec3a89e992","committedAt":"2026-08-19T07:44:53+09:00","dirty":false}