agent-bios 0.13.0 → 0.14.0

package/claude/guides/verification-discipline.md

@@ -34,11 +34,21 @@ the depth first:
   over persisted real artifacts rather than re-running the whole pipeline to observe it.
 - Probe at N=1 with the inputs precondition-checked. A single well-chosen case that reaches the
   real path outranks a hundred that stop short of it.
+- Bound the N=1 probe to reachability. One case settles whether a path works — never how often a
+  stochastic behavior holds. Before quoting a rate-shaped property (determinism, flake rate, an
+  A/B effect), confirm the mechanism honors your controls, establish the noise floor from runs on
+  hand, then sample enough to bound the rate against a no-treatment control on the real path. A
+  floor larger than the effect breaks the premise — record it before redesigning.
 - Reserve the full design-review-plus-live-verification treatment for first-of-kind work and for
   changes that move authority — who may decide, who may write, what is irreversible.
 - Proportion assurance to the deployment context. A single-user tool operating on its owner's own
   data does not warrant production-grade assurance, and treating it as if it did buys nothing
   while delaying delivery. Prefer shipping.
+- Census the population before a costed or irreversible batch. Read its current state cheaply and
+  deterministically — status distribution, version, presence of the artifacts the plan expects —
+  and compare that against the premise the batch rests on, halting to re-diagnose when the
+  distribution contradicts it. A probe validates the path; only the census validates that the
+  population is what the plan assumes. A cheap idempotent batch over a few items needs none.
 
 The failure this prevents is not under-testing. It is spending the verification budget on the
 cheap half of the risk and having nothing left for the part that could actually hurt.
@@ -62,10 +72,14 @@ cheapest one to write.
 - Config or data: real parsers, schema checks, fixture validation, and sample transformations.
 - Spreadsheets: static workbook checks, fixture-based output checks, cross-sheet flow checks, visual/layout checks, and real Microsoft Excel engine recalculation for formula-dependent results.
 - Docs: links, terminology, current behavior alignment, and references to isolated historical notes.
+- Multi-subject prose: when deliverables draw on material about different people, companies, or cases, bind every captured item to its subject and confirmation status at capture, and narrate nothing under a subject until that binding is confirmed. Cross-check subject-specific proper nouns and figures across all outputs before delivery — one subject's term under another is the signature of context bleed. Keep a figure in the same sentence as its composition, since a detached number is read at its worst.
 - Release or distribution: after publishing to multiple independently writable channels (signed manifest, object storage, release host, embedded updater), digest-verify every referenced object against the staging original per channel — publish success and upload order are not evidence — and run the real installer/updater through its default path.
 - A/B or on/off measurements: before accepting a null result, verify the arms actually received different treatment in the mechanism under test — a shared default or unconditional upstream step can silently apply the treatment to both arms.
+- Multi-stage pipelines with nondeterministic stages: a final-output diff cannot attribute an effect or a regression to a stage — it conflates the change with run-to-run variance. Persist every stage's output, tabulate what each creates, may edit, and only guards, restrict the suspects to the stages that edit the content in question, and find the first stage where the intended effect disappears or the defect appears. Fix there, preferring a structural recheck over another prompt-level instruction that already failed.
+- Before/after comparisons: pin the input to an immutable copy — a snapshot or versioned artifact — and run both arms against it, because a live artifact (a growing log, a regenerated upstream stage) drifts between runs and any diff over it, a matching one included, is evidence of nothing; when the arms are metered, restore the baseline's exact upstream inputs and re-run only the changed stage. This is input identity, not the separate unit-and-denominator basis rule.
 - Model-behavior guardrails: verify by changed behavior, not recitation — a staged battery from named-trigger cases through disguised, deconfounded, category-wide, and single-variable framings; a clean pass means "no known defect", so re-run the battery when the model changes.
 - Branch/version test builds against real data: explicitly separate every state sink the app touches (files, DB, OS-level stores that ignore env overrides), confirm the launch path propagates the isolation to child processes, and back up live data before the first run — a mismatched schema that drops unknown fields on write is data loss, not a no-op.
+- Sandbox, replay, or re-adjudication runs on production-derived config: enumerate every outbound channel the stage can reach — publish, upload, notify, external write — and disable or redirect each one before the run, proving each disarm fires as you would prove a path guard; a guard on the input or target path alone leaves egress armed. Fingerprint every external destination before the run and diff it after, so an escaped write is caught by the run rather than by a recipient.
 - Irreversible capture switches: when activation itself has unreproducible cost (a capture window that cannot be replayed), prove the downstream consumption path against existing samples before enabling — reversibility of the code path alone is not enough.
 
 ## Deriving the case space
@@ -108,6 +122,12 @@ someone typed once.
   interrupted, a restore sitting after it never runs and the plant survives into a
   commit. Plant in a copy where the shape allows it, and when it must be in place, snapshot
   first and restore from the snapshot as its own step rather than trusting the probe to finish.
+- Attribute a fault by a controlled contrast before choosing a remedy. Hold everything constant —
+  principal, path, input — vary only the candidate variable, and read a countable difference
+  (element dimensions, request count, status-code family). A missing error report is not
+  exoneration: channels can be suppressed, unobserved, or unwired from the mechanism at fault, so
+  "no violations logged" rules a cause out only when the contrast shows none either. Read the
+  contrast the evidence already holds before proposing a policy loosening.
 
 ## When a green means nothing
 
@@ -121,17 +141,65 @@ produce a green with no evidence behind it:
   confirm its inputs satisfy the live branch's entry guard. A copied fixture that fails the new
   guard routes silently into the about-to-be-deleted dead branch and stays green after the real
   behavior breaks.
+- **The fixture the producer never emits.** A test's input is evidence only when the thing that
+  produces it in production produced it. A wire fixture must be a raw response captured through
+  the same client that will parse it, never a rendered listing or a hand-written payload; a gated
+  feature's E2E must run with the gate in its production setting, on the state its real upstream
+  leaves. Replay against the live producer once, then probe every sibling built the same way.
 - **The permissive fallback in the checker.** A `a || b` inside a gate absorbs a wrong assumption
   and keeps passing. Checker code must assert the shape it expects and fail loud.
 - **The suspiciously fast or empty run.** When a check goes green unexpectedly quickly, or reports
   nothing at all, dump what it actually ran over before believing it. A harness that crashed early
   and one that found nothing produce the same exit code.
+- **The control that failed by crashing.** A negative control is evidence only when it fails
+  through the assertion it names: a traceback and a caught violation share an exit code, and an
+  early crash can pre-empt every control after it. Treat each traceback in a control run as a
+  defect until the run reports one named failure per planted violation. Run any unattended gate
+  with stdin closed, so a path reaching a prompt fails at once instead of hanging.
 - **The control that went quiet.** A negative control indexing a live list stops testing when that
   list empties, and says nothing about it. New controls build their own subject; resolving an item
   means re-reading the controls for ones that have gone silent.
-
-The discipline that covers all five: after adding a check, revert the fix it guards and watch the
-check fail. A control that survives a faithful revert was never testing the thing it names.
+- **The silent log.** Absence of activity is not evidence of non-use. Before retiring an
+  identity, key, or endpoint on a quiet log, show that the queried field is the one recording the
+  subject — delegated actions are attributed to the caller, with the target in another field, so
+  the wrong field returns clean silence — and that no live binding still references it, since a
+  reference proves use while emitting no traffic. Only a demonstrated "this use would have been
+  logged" evidences non-use.
+- **The population that shrank.** A gate scanning an explicit list of files sees only "listed but
+  empty": a subject that migrates to an unlisted surface leaves the scanned set smaller yet
+  non-empty, so the empty-subject guard never fires while coverage erodes. Retarget the gate in
+  the same change that moves the code, and pin a floor so any decrease fails loudly — proved by
+  moving one subject out. A floor is a ratchet: never lower it to pass a run.
+- **The mutant that never ran.** A mutation verdict counts only if the mutant is valid: it
+  compiled, sits on a path the exercised test traverses, and changes the guarded behavior, not
+  healed downstream or coinciding with a default. The runner must report build failure,
+  unreachable, and equivalent distinctly from KILLED and SURVIVED, and halt on a moved anchor.
+  More tests red than the mutation should touch indicts it; classify a survivor (rebuild,
+  discard, genuine gap) before writing a test.
+- **The probe that measured the original.** A copied script that derives its root or targets from
+  its own location (`$0`, `BASH_SOURCE`, a `cd` to its parent) scans the original tree, not the
+  copy, so its verdict says nothing about the mutation you planted. Pin the subject in the copy,
+  copy the whole tree, or plant in place with a snapshot-restore. The tell is a result identical
+  to the unmutated run; a script taking its subject as an argument is safe to copy.
+
+The discipline that covers every shape above: after adding a check, revert the fix it guards and
+watch the check fail. A control that survives a faithful revert was never testing the thing it
+names. Prove the plant landed: assert the altered input differs from the original and that the
+control's cases reach the mutated branch before asserting rejection. Construct corruption
+deterministically: scanning for a flip site yields no-op mutations reporting a rejection nothing
+exercised.
+
+## Before blaming code for a metric change
+
+When a live metric collapses or crosses a pre-declared threshold, localize the change in time
+before diagnosing the feature: confirm every inbound source is alive, compare only
+contemporaneous cohorts, never re-processed rows, then bracket the transition to the finest unit
+available and read the deploy log around that instant.
+
+A change landing seconds from the last-good point is the prime suspect; a step in a window with
+no deploys is an input-population shift, fixed by scoping the measured population, not the model
+or the code. Declare the threshold before looking, and confirm a failure from the fleet's vantage
+rather than your own — this does not replace fixing the comparison basis, which comes first.
 
 ## Keeping E2E honest
 

package/claude/hooks/tooling-gotchas-hook.py

@@ -53,6 +53,31 @@ RULES = [
      "Reverting a path discards ALL uncommitted edits in that file, not just the one "
      f"you planted — check `git diff <path>` first, or restore from a copy ({GUIDE}).",
      "Reverting a path is not undoing your edit"),
+    # A sweeping write treats every delta in the tree as the caller's own. Named paths
+    # (`git add src/x.py`) are exempt: naming is the attribution the rule asks for.
+    ("shared-tree-sweep",
+     # The commit flag must be its own token: a path like /x/-agent/msg.txt after -F carries
+     # "-a" too, and the first version of this rule fired on exactly that.
+     re.compile(r"\bgit\s+(add\s+(-A|--all|\.)(\s|$)|commit\s+(?:[^|;&]*\s)?(?:-[a-zA-Z]*a[a-zA-Z]*|--all)(?=\s|$)|stash\b(?!\s+(pop|apply|list|show))|clean\b|reset\s+--hard)"),
+     "A shared tree may hold another operator's work — attribute every delta you did not "
+     f"make (git status, reflog, live sessions) before sweeping it; add by name ({GUIDE}).",
+     "A shared tree holds other operators' work"),
+    ("job-logs-by-execution",
+     re.compile(r"\bgcloud\s+(?:alpha\s+|beta\s+)?(?:logging\s+read|run\s+jobs)\b"),
+     "Job-level logs retain earlier executions (even a job deleted and recreated under the "
+     f"same name) — scope the read to the execution id you launched ({GUIDE}).",
+     "Job logs outlive the execution"),
+    ("name-substring-liveness",
+     re.compile(r"\bpgrep\s+(?:-\w+\s+)*-\w*f|\bps\b[^|\n]*\|[^|\n]*\bgrep\b"),
+     "A name-substring process lookup matches the querying shell's own argv and unrelated "
+     f"same-named processes — confirm liveness by PID, handle, or output growth ({GUIDE}).",
+     "Name-substring lookup is not a liveness check"),
+    # Not a search for the word: a grep/rg over sources mentions revoke without revoking.
+    ("revoke-grant-blast-radius",
+     re.compile(r"^(?!.*\b(?:rg|grep|ag|git\s+log)\b).*\brevoke\b"),
+     "A revoke is grant-wide: everything issued under a shared client id, including the "
+     f"user's live sessions, goes with it — confirm the scope before revoking ({GUIDE}).",
+     "A revoke is grant-wide, not token-wide"),
     ("grep-binary-heuristic",
      # Applied per extracted STAGE by matches(), not to the raw line. The stage's
      # COMMAND WORD must be grep — after optional reserved words (`if ! grep -q`
@@ -265,8 +290,33 @@ def self_test() -> int:
         "metachar-inline-arg":   'codex exec "$(cat packet.md)"',
         "pipe-exit-masking":     "make build | tail -1; echo $?",
         "git-checkout-path":     "git checkout src/thing.py",
+        "shared-tree-sweep":     "git add -A && git commit -m x",
+        "job-logs-by-execution": "gcloud logging read 'resource.labels.job_name=probe' --limit 50",
+        "name-substring-liveness": "pgrep -f codex",
+        "revoke-grant-blast-radius": "gcloud auth revoke probe@example.com",
         "grep-binary-heuristic": "grep needle haystack.md",
     }
+    # Naming the path IS the attribution the sweep rule asks for, so a named add, a
+    # plain commit, and stash pop must not draw the reminder — or it fires on every commit.
+    for quiet_cmd in ("git add src/thing.py", "git commit -m 'fix'", "git stash pop", "git add -p",
+                      "git commit -F /tmp/claude-501/-Users-someone-Documents-agent-bios/scratch/msg.txt"):
+        if "shared-tree-sweep" in [h for h, _ in matches(quiet_cmd, limit=None)]:
+            problems.append(f"shared-tree-sweep: fired on a non-sweeping command ({quiet_cmd!r})")
+    for sweep_cmd in ("git add .", "git commit -am 'wip'", "git commit --all -m x", "git stash", "git reset --hard HEAD"):
+        if "shared-tree-sweep" not in [h for h, _ in matches(sweep_cmd, limit=None)]:
+            problems.append(f"shared-tree-sweep: did not fire on a sweeping command ({sweep_cmd!r})")
+    for quiet_cmd in ("gcloud run services list", "docker logs probe", "kill -0 12345",
+                      "grep -rn pgrep claude/guides/", "ls | grep foo", "rg revoke src/",
+                      "git log --grep revoke"):
+        hit = [h for h, _ in matches(quiet_cmd, limit=None)]
+        for rule in ("job-logs-by-execution", "name-substring-liveness", "revoke-grant-blast-radius"):
+            if rule in hit:
+                problems.append(f"{rule}: fired on a non-matching command ({quiet_cmd!r})")
+    for rule, cmd in (("job-logs-by-execution", "gcloud beta run jobs executions list --job probe"),
+                      ("name-substring-liveness", "ps aux | grep codex"),
+                      ("revoke-grant-blast-radius", "vault token revoke s.f3b9c2")):
+        if rule not in [h for h, _ in matches(cmd, limit=None)]:
+            problems.append(f"{rule}: did not fire on ({cmd!r})")
     # A pipeline-stage grep must reach the rule too — the fixture alone exercises only
     # command-start grep, and the reminder is most needed mid-pipeline.
     if "grep-binary-heuristic" not in [h for h, _ in matches("cat payload | grep needle", limit=None)]:

package/codex/AGENTS.md

@@ -2,7 +2,7 @@
 
 ## Global Preferences
 
-- Prefer concise Korean responses with polite speech unless the user asks otherwise.
+- Prefer concise Korean responses with polite speech unless the user asks otherwise. (private)
 - Keep file changes within the requested scope.
 
 ## Problem Solving
@@ -10,7 +10,7 @@
 - First identify the goal, scope, ambiguities, and likely completion condition.
 - Resolve ambiguity from context when safe; ask only when ambiguity blocks progress or creates risky outcomes.
 - For simple requests, choose the most direct low-risk method and proceed.
-- For non-trivial requests, compare 2-4 methods by goal fit, time, cost, risk, benefit, and "done when".
+- For non-trivial requests, compare 2-4 methods by goal fit, time, cost, risk, benefit, and "done when", and portability — take a host-, model-, or tool-specific mechanism (hook, skill, host-owned directory) only after a portable route is shown absent and its per-host cost is judged worth it.
 - Mark one default method. If the user is silent and the default is safe, proceed with it.
 - Execute the chosen method accurately and stay within scope.
 - Return to understanding if a discovery breaks the user's premise.
@@ -21,7 +21,7 @@
 
 ## Decision Framing
 
-- Ask decision questions in outcome terms, not jargon terms.
+- Ask decision questions in outcome terms, not jargon terms: before ending a turn on a decision request, check that it gives the situation in one plain sentence, what changes for the user under each option, and a default — and where a structured question channel exists, route the ask through it so its fields force that shape.
 - When the user may not know the domain, explain choices by resulting behavior, tradeoffs, time, cost, risk, reversibility, and recommended default.
 - Present 2-4 meaningful options. Ask about implementation details only when they directly affect the decision.
 - For each option, state what changes for the user or product, what it costs, what risk it carries, and when it is the right choice.
@@ -29,7 +29,7 @@
 - Ask for the user's goal or constraint when that determines the answer; otherwise choose the safest default and proceed.
 - Evaluate user suggestions for goal fit, risk, complexity, and verification before turning them into implementation plans; if a suggestion does not fit the user's goal, say so clearly and recommend a better path.
 - Distinguish implementation feasibility from recommendation.
-- Do not default to a restrictive lens (security, masking, capability limits) when the system's purpose is sharing or utilization; confirm the purpose framing first, and restrict only on concrete, named risk.
+- Do not default to a restrictive lens (security, masking, capability limits) when the system's purpose is sharing or utilization; confirm the purpose framing first, and restrict only on concrete, named risk — and size every control (gate, cap, rule, review lens, success criterion, clarifying question) to that risk: a target is a direction, not an absolute, and prefer a warning plus a recovery path over a prohibition.
 - Treat user suggestions, inherited premises, prior diagnoses, handoff and design claims, reviewer findings, and your own earlier conclusions as hypotheses, not facts; re-derive each load-bearing claim from real code or data before building on it, and record a dated correction in the source doc or memory when a finding overturns it.
 
 ## LLM And Capability Boundary
@@ -53,7 +53,7 @@
 ## Concept Economy
 
 - When adding, changing, renaming, splitting, or exposing anything lasting or shared — a feature, entity, type, field, config key, CLI flag, enum value, failure kind, artifact, or documentation term — read and use `${CODEX_HOME:-$HOME/.codex}/guides/concept-economy.md` as a scoped extension of this section.
-- Before fixing a review finding or test failure, classify the fix as reducing, preserving, or increasing the active concept surface.
+- Before fixing a review finding or test failure, name its cause — a finding is a symptom — then classify the fix as reducing, preserving, or increasing the active concept surface, and fix the cause completely now: a scope-minimal patch that leaves the cause in place is not a fix.
 
 ## Coding Guidelines
 
@@ -61,7 +61,7 @@
 - For development work, read and use `${CODEX_HOME:-$HOME/.codex}/guides/coding-staged-workflow.md` as a scoped extension of these Coding Guidelines — a change too narrow to need it is what its lightweight path decides, not a reason to skip the read.
 - For mock, fixture, fake, stub, simulated-provider, or test-realization design, read and use `${CODEX_HOME:-$HOME/.codex}/guides/mock-realization-boundary.md` as a scoped extension of these Coding Guidelines.
 - Own the full lifecycle of what you create — spawned processes and handles through teardown, artifacts out of tool-managed temp locations into a durable home — and keep differently-owned state separate: never colocate deploy-managed and user-owned data in one overwrite-managed file.
-- Land risky or behavior-changing work behind a default-off path that preserves current behavior when off (proven by diff) and is enabled by an explicit opt-in, so the change stays reversible and the on/off difference is isolated. When a request would weaken a security or authority posture — removing or loosening an authentication/authorization check or access scope, or lowering a protective value such as session/token lifetime, password/crypto strength, rate limit, lockout threshold, or audit retention — treat it as a decision, not a rote edit, even when it is a one-line change and nothing in the code labels the value as security-relevant: state the consequence and at least one safer path to the real goal, and do not apply the weakening in the same turn — proceed only after the user confirms they accept the tradeoff.
+- Land risky or behavior-changing work behind a default-off path that preserves current behavior when off (proven by diff) and is enabled by an explicit opt-in, so the change stays reversible and the on/off difference is isolated — the switch lands a fix reversibly and never substitutes for one. When a request would weaken a security or authority posture — removing or loosening an authentication/authorization check or access scope, or lowering a protective value such as session/token lifetime, password/crypto strength, rate limit, lockout threshold, or audit retention — treat it as a decision, not a rote edit, even when it is a one-line change and nothing in the code labels the value as security-relevant: state the consequence and at least one safer path to the real goal, and do not apply the weakening in the same turn — proceed only after the user confirms they accept the tradeoff.
 
 ## Verification Discipline
 
@@ -77,7 +77,7 @@
 - For concrete shell/CLI traps — pipe exit codes, output rendering, git range/pull semantics, config and managed-service pitfalls — read and use `${CODEX_HOME:-$HOME/.codex}/guides/tooling-gotchas.md` as a scoped extension of this section.
 - Ambient state — the active shell, cloud CLI project/context, command-name resolution, 'latest'-style pointers, version-bearing paths — drifts silently; where an outcome depends on it, pin it explicitly (a pinned interpreter, --project/--context flags, exact handles, resolved paths) instead of trusting the environment.
 - Before relying on any model id, tool flag, API capability, dependency version, or runtime constraint, confirm it empirically against the live or installed artifact (a minimal probe, the binary's registered options, the installed package version) rather than docs, memory, or a version string.
-- Scope destructive actions (kill, rm, force-push, reset --hard) to targets you own, identified by PID, path, or ancestry — never a broad command-line substring or blanket match — and diagnose the actual state before any irreversible git, remote, or process operation; snapshot the last good state before any in-place resume or overwrite of a completed run, and gate irreversible identity-tied actions (revoke, delete, grant, consent) on a live identity check — never auto-open a browser for a non-default identity (hand the operator the URL).
+- Scope destructive actions (kill, rm, force-push, reset --hard) to targets you own, by PID, path, or ancestry — never a broad command-line substring or blanket match — and diagnose actual state before any irreversible git, remote, or process operation; snapshot the last good state before any in-place resume or overwrite of a completed run, and gate irreversible identity-tied actions (revoke, delete, grant, consent, account-bound creation) on a live identity check — never auto-open a browser for a non-default identity (hand the operator the URL).
 - Never accept secrets through transcript- or history-logged channels.
 - When a secret must be supplied, provide a gitignored env slot, read the value only from the environment, verify its presence and format without echoing it, and advise rotating anything already pasted; assume a resource-creating call may echo the secret back in its success output — suppress or discard the response body, and treat an echoed secret as pasted (rotate).
 - Treat a coarse runtime signal — a failure label, a `ps`/process-inspection result, idle CPU with no output — as a hypothesis, and confirm the cause against the authoritative low-level evidence the mechanism emits before attributing blame or intervening: read the raw provider/skill log payload (e.g. `input_tokens:0` proves a pre-dispatch rejection that exonerates your content and your change), and confirm a config/env toggle reached a subprocess via a cheap artifact the gated branch emits rather than an unreliable `ps` env read. A multi-minute LLM or subprocess call at ~0% CPU with an output gap is the normal signature of I/O wait, not a hang — check process state and the call trace's in-flight duration before acting, so you do not abort healthy long-running work.
@@ -85,7 +85,7 @@
 ## Multi-Model Workflow
 
 - Codex-only standing authorization: on root/main local tasks, ordinary subagent dispatch is authorized when the `When To Spawn` gates fire. Explicit no-fan-out wins. Delegated agents may re-delegate only when their role allows. This grants no destructive, remote, credential, install, OAuth, push, live-network-expanding, or broader-sandbox authority.
-- Standing spawn policy: check the spawn gates at every work-unit boundary — judgment latitude applies inside a gate, never to whether the gates are checked. Independence: verifying or reviewing your own work always spawns. Parallelism: two or more independent items spawn in parallel — SWEEP when each item applies one explicit rule and returns ambiguity as an exception, else WORKHORSE. Residual context: work whose log dwarfs the conclusion the main needs spawns with a bounded report contract. Escalation: an irreversible or authority-changing action ahead, two failed attempts, or two persisting design alternatives spawns a bounded FRONTIER judgment with a blind packet (evidence, constraints, rubric, neutral alternatives — never your draft conclusion) and a pre-noted change condition. Specifiability/de-minimis: work needing your live context, or whose verification would repeat the reasoning, or whose packet outweighs the work, stays inline.
+- Standing spawn policy: check the spawn gates at every work-unit boundary — judgment latitude applies inside a gate, never to whether the gates are checked. Independence: verifying or reviewing your own work always spawns, and you raise it yourself — before presenting a load-bearing conclusion or taking an irreversible step, propose the cross-check unprompted; the user should never have to ask for it. Parallelism: two or more independent items spawn in parallel — SWEEP when each item applies one explicit rule and returns ambiguity as an exception, else WORKHORSE. Residual context: work whose log dwarfs the conclusion the main needs spawns with a bounded report contract. Escalation: an irreversible or authority-changing action ahead, two failed attempts, or two persisting design alternatives spawns a bounded FRONTIER judgment with a blind packet (evidence, constraints, rubric, neutral alternatives — never your draft conclusion) and a pre-noted change condition. Specifiability/de-minimis: work needing your live context, or whose verification would repeat the reasoning, or whose packet outweighs the work, stays inline.
 - Down-spawns carry a machine-checkable done-when on decision-complete work with staged output (no external irreversible actions) and briefing-plus-verifying clearly cheaper than doing. Record one line per gate decision — `SpawnGate: <gate> <tier> spawn|inline — <why>` — and for FRONTIER record the disposition afterward (what changed, or why nothing did). A launch contract's `Delegation=off` lifts the spawn obligation, not the records; explicit user no-fan-out always wins.
 - For work spanning multiple models or CLI agents, context resets and handoffs, unattended LLM batches (including orchestrated subagent fleets), or parallel worktree branches, read and use `${CODEX_HOME:-$HOME/.codex}/guides/cli-multi-model-workflow.md` as a scoped extension of this section.
 - For composing a prompt, packet, or tool description aimed at a specific model family — including cross-family review dispatch, porting a prompt written for an older model, or choosing a reasoning-effort level for a model family — read and use `${CODEX_HOME:-$HOME/.codex}/guides/gpt-prompting.md` for gpt-family targets and `${CODEX_HOME:-$HOME/.codex}/guides/claude-prompting.md` for claude-family targets as scoped extensions of this section.

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

@@ -106,7 +106,7 @@ Instruction/config reach is per invocation. A rule in AGENTS.md cannot bind a he
 - Run deterministic gates before LLM review. Funnel SWEEP finders → WORKHORSE judgments → FRONTIER triage/verdicts.
 - On family collapse, record the downgrade and label clean verdicts PROPOSED until diversity is restored.
 - A silent/dead lens is incomplete, never clean. Confirm liveness from usage/error/report evidence; rerun, swap provider, or report PROPOSED.
-- Kind labels do not guarantee distinct backends: wrappers and rate-limit fallbacks can silently route two "different-kind" verifiers to the same model/provider. Before trusting diversity on a high-stakes verdict, confirm each verifier's actual backing model from live process or usage evidence; on collapse, treat the pair as one kind and label PROPOSED.
+- Kind labels do not guarantee distinct backends: wrappers and rate-limit fallbacks can silently route two "different-kind" verifiers to the same model/provider. Before trusting diversity on a high-stakes verdict, confirm each verifier's actual backing model from live process or usage evidence; on collapse, treat the pair as one kind and label PROPOSED. Runners recording what ran need the same read: identity taken from the target at execution time, never a runner-side literal, and asserted equal to what was requested — fallback seats pass existence checks.
 
 ### Review Independence
 
@@ -124,6 +124,7 @@ How much independence a review actually bought, as an ordinal grade per reviewer
 - The floor still requires **at least two distinct perspectives**; one pass on the main's own seat is self-review with extra steps.
 - Multiple ready methods are **coverage, not diversity**. Distinct labels do not prove the perspectives differed.
 - **Achieved is not available.** What can be projected before a review runs is `projected`; a clean verdict without a receipt evidencing a fresh dispatch, the declared packet, a non-empty result and the exact seat is `PROPOSED`, never ACHIEVED. A model echo is not a receipt.
+- **Evidence access is its own axis.** When every reviewer saw only the blind packet, convergence — even across providers — is evidence about the packet's framing, omissions included. Before adopting a converged verdict resting on a code seat, a measured fact, or a constraint list, route one seat with live read access to falsify those facts: a lone dissent citing a real constraint outweighs a blind majority, and the missing fact returns to the packet. It sits beside the ladder, not on it.
 
 ## Dual-Provider Design Drafts
 
@@ -136,11 +137,14 @@ How much independence a review actually bought, as an ordinal grade per reviewer
 - The parent owns per-item completion and a **code-level circuit breaker**. For dispatchers you do not control, verify equivalent protection or attend the run.
 - Default breaker: halt after 3 consecutive cross-item provider limit/auth/transport failures after bounded backoff. Persist undone items and alert or swap provider.
 - Item-specific failures are poison items: cap at 2–3 attempts, then dead-letter them as complete-with-failure. Resume only unfinished/invalid items; whole-batch reruns require cheap idempotence.
+- An enumeration run is done only when its collected count is asserted against the source's own reported total for the same filter. Classify retriable failures by class — any server-side transient — rather than an enumerated code list, since an omitted code drops items silently; persist which batches failed and reconcile them before declaring completion; and treat a mismatch, or a total from a differently scoped population, as a defect rather than a footnote. A declared partial or sampled scope is outside this.
 - Persist per-item outcome, token, and cost records for recalibration.
+- Before releasing a metered batch past its first item, use that item to probe the batch machinery, not the item logic: run it end to end through the real runner to its side effect, then confirm every value the later analysis depends on — treatment knob, run identity, cost — reached the persisted record through the expected channel. On the first failures read raw run logs, not the runner's status classifier, which infers causes from missing outputs. A cheap idempotent batch needs no gate.
 
 ## Halt And Resume
 
 - Resume-first from artifacts that parse, pass schema, and match their recorded source/config/HEAD fingerprint; unverifiable means invalid.
+- A cache-hit or fingerprint predicate must cover every value that shapes the artifact's content — the upstream input's content identity, caps, templates, model ids, config — never existence, mtime, or size alone; when adding a new output-shaping value, inspect the key's pre-image in the same change and assert the key moves when the value moves. Before re-running because an upstream input changed, invalidate intermediates whose predicate omits that input's identity: a regenerate over existence-keyed caches re-derives from the old input.
 - Resubmit one invalid unit unless failures are broadly correlated, which is structural and halts the run.
 - Treat halt→continue as normal operation.
 - Treat tool-managed temp/cache output locations as ephemeral — they are garbage-collected on the tool's own schedule. Copy any artifact a pending or handed-off decision depends on into a project-owned durable path before relying on it later.
@@ -150,6 +154,7 @@ How much independence a review actually bought, as an ordinal grade per reviewer
 
 - Sessions bind to their starting directory. Use the CLI's native relocation/resume mechanism; never copy transcript files.
 - For a new worktree, relocate natively or write a handoff and start fresh. Re-integrate branches serially and re-verify after each merge.
+- A conflict-free merge with a green build is evidence about text, not placement. When the base side restructured the surrounding code — regrouped sections, split modules, new per-variant containers — locate each merged addition in the new structure and confirm its scope still matches its container's: a global setting must not sit inside a variant-specific container, and no duplicate or orphaned copy may remain. A merge onto an unchanged layout needs only the ordinary green-state check.
 - Mark superseded worktrees/handoffs dead so later resume cannot select them.
 - After resume/clear/relocation, verify pwd, branch, and HEAD against the pinned handoff before acting.
 - Attribute a parallel session's action (commit, branch, resource) by execution evidence in that session's own transcript, never by token mentions — shared handoff/memory files inject the same tokens into every session's context.

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

@@ -75,6 +75,18 @@ patching downstream: compensating code keeps accumulating around bad inputs, and
 another instance of the same defect. The first says go upstream to where the value is produced.
 The second says the instances are a class — single-source the value and fix the class, because
 patching them one at a time is a queue that refills.
+**Supplying a missing shared dependency wakes every consumer, not just the one you are fixing.** When
+a repair supplies a value many paths read and that was absent — a secret, a packaged file —
+enumerate those consumers and say what each starts doing: metered calls, external writes,
+user-visible output. Where that onset exceeds the feature under repair, hand the list to the owner
+as a decision, not a line in the fix. Consumers that are all read-only and free need no gate.
+
+**Measure a flip before you design its activation.** When a version bump, default change, or
+severity re-mapping is coming, flip it, run the full suite, classify every failure (cascade,
+pinned control, true detection, real regression), and restore — that count is the activation's
+blast radius. Re-mapping a level obliges enumerating every reader of that field, since one level
+commonly gates shipping, repair, retry, and display at once. A deferred defect is pinned as a
+strict expected failure, never a silent pass.
 
 ## Review Loop
 

package/codex/guides/learning-flow.md

@@ -103,4 +103,7 @@ payload — do not work around the validation.
 - Single-session capture only; cross-session mining is `distill!` (curator).
 - Mechanization (hook/gate/enforcement) is deferred to curation — record intent, don't build it.
 - Type-G principle manufacture is curator-only.
-- Transport (upload to the org) lands in Phase 2; Phase 1 writes locally.
+- Transport (upload to the org) is best-effort after the local write: it runs only
+  when the `~/.config/agent-bios/{ingest-url,token}` slot is set, which is the
+  only source there is. A default install sets nothing, so nothing leaves the
+  machine; an org fills the slot through its own wrapper.

package/codex/guides/llm-capability-boundary-patterns.md

@@ -314,6 +314,14 @@ Retries are safe for pure generation and validation. They are not automatically
 safe for external side effects. Use idempotency keys, locks, duplicate detection,
 or compensation plans where needed.
 
+A stage that can re-run on the same record must not read the field it writes.
+On a re-run (reclassification, backfill, retry) an input field that is also
+its output feeds the model its prior answer, and the value drifts from the
+source silently. Keep the captured original immutable, write derived values to
+their own field, and treat `original ?? current` as migration, not design.
+Audit its siblings: one harmless only because its selection rule skips
+overwritten rows is a latent instance.
+
 ## Single Source Of Truth And Schema Evolution
 
 Hybrid enforcement creates drift risk. A single constraint can appear in prompt

package/codex/guides/review-request.md

@@ -122,6 +122,12 @@ design; do not treat missing implementation as a defect." A session given exactl
 that instruction returned zero findings and proved it had looked, anchored on
 both sides of the comparison. A session not given it filed unimplemented code as
 blockers, and the user caught it manually.
+The target also has a revision. Name the commit or content hash the packet
+was dispatched on, and hold the artifact still until every reviewer on
+that revision has returned. When a fix must land while a lens is still in
+flight, map the returned findings against the pinned revision before
+counting them: a finding whose anchor text no longer exists is stale,
+closed by that mapping rather than re-fixed, and never tallied as open.
 
 ## Bundle the consumer, not just the artifact
 
@@ -226,6 +232,13 @@ Two consequences for anyone consuming a review:
   count was scoped to the material section, at which point 16% of the same
   findings turned out to have reached the reader explicitly flagged
   non-material. Read the verdict field, not the mention.
+- Count the emitted item list against every total the harness reports —
+  findings count, verdict tally, per-item decision log — before triaging.
+  Zero findings is only the extreme case: any shortfall means items were
+  dropped in aggregation, and the dropped set is not random, since a merge
+  or filter tends to lose a whole class. Recover the difference from the
+  raw per-item record and triage the union; with no raw record the
+  deliverable is incomplete, not clean.
 
 ## Trust an empty result only when it cites what it checked
 

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

@@ -49,15 +49,27 @@ Run in order; each stage reads the previous stage's `out/`:
    Claude sidechain/sdk-cli/agentId).
 2. `digest.py` — one secret-redacted digest per session with deterministic
    6-criteria signals. Screen ALL digests; triage orders, never drops.
-3. Provider-affine screening against the concatenated live baseline
-   (CLAUDE.md + guides): `screen-claude.js` (Claude sessions) and
-   `screen-codex.js` (Codex sessions), both dynamic-workflow scripts.
-   Novelty is judged against real baseline text, not memory.
-4. `consolidate.js` — dedup + independent novelty verification. Rank by
-   strength (recurrence × materiality), never by self-reported confidence.
-5. `bundle_final.py` — tiered bundle. Merge new candidates into
-   `ledger.json` by cluster identity so recurrence accumulates across
-   windows (incubated items promote when they re-occur).
+3. `batch.py` — the baseline blob (`claude/CLAUDE.md` + every guide, the
+   repo's canonical corpus) and per-provider batches; writes
+   `out/batch_index.json`, which the screeners take as their `args`.
+4. Provider-affine screening against that baseline: `screen-claude.js`
+   (Claude sessions; a Workflow script — pass the index as `args`, one
+   WORKHORSE screener per batch) and `screen-codex.py` (Codex sessions;
+   one hermetic read-only `codex exec` per batch, packet on stdin). Novelty
+   is judged against real baseline text, not memory. Then `collect.py`
+   unions the two outputs into `out/candidates-all.json` and fails when a
+   provider's screened set is smaller than its batch.
+5. `consolidate.js` (Workflow; `args` = baseline, candidates path, count,
+   and the ledger's `{id, lesson}` list) — dedup + independent novelty
+   verification, then a match pass naming which survivor recurs an
+   existing ledger entry. Rank by strength (recurrence × materiality),
+   never by self-reported confidence. Save its return value as
+   `out/consolidated.json`.
+6. `bundle_final.py` — tiered bundle. `merge-ledger.py --window-end <date>`
+   (dry-run; `--apply` writes) merges survivors into `ledger.json`: a
+   recurrence gains the window's sessions under `recurrence`, a new lesson
+   becomes a `candidate` entry — so recurrence accumulates across windows
+   and incubated items promote when they re-occur.
 
 ## Stage 2 — Review with the user