agent-bios 0.2.0 → 0.3.0

package/codex/AGENTS.md

@@ -29,6 +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.
 - 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
@@ -79,6 +80,7 @@
 - Treat viability as real behavior against real inputs, real authority, and the intended runtime path. Use mocks only for tests, fixtures, or explicitly requested simulations; mock-backed paths support verification but do not count as product completion.
 - Make surgical changes. Touch only what the request requires, preserve existing style, and avoid casual adjacent refactors.
 - Clean up issues introduced by the current change. Mention unrelated dead code separately.
+- 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.
 - Define success criteria before multi-step coding work, then verify against them.
 - For bugs, prefer a reproducing test before the fix when practical.
 - Every changed line should trace back to the user's request.
@@ -97,21 +99,26 @@
 - Report the checks run, results, and any unverified risk before calling the work done.
 - Trust a green check only when it traversed the actual changed code through the real dispatch and real calls (not a mock, dry-run, or bypass), and remember that "it ran" is not "quality met" — a fallback, floor, or mock run is not done; treat a zero-findings verdict as suspect until you confirm the harness ran rather than silently crashed, and make PASS mean concrete assertions on real output from the real path.
 - Make completion criteria falsifiable: prefer signals that fail when the mechanism is wrong (negative or contrast controls), and if no existing gate can judge a criterion, build the executable judge or do not claim the criterion met.
+- Before comparing two of anything (cost, performance, quality, frequency), fix a common basis — units, denominators, population, measurement surface — compare on equivalent output, and exclude or flag non-representative data (promotions, outages, smoke slices).
 - For non-trivial designs or high-risk changes, run independent adversarial review across distinct lenses, ideally on the design before implementation, and re-verify each finding against real code before acting on it. Apply the convergence heuristic by reviewer kind (detailed in the multi-model guide): same-kind convergence is high confidence but same-kind reviewers share blind spots — their shared "clean" is not verification; different-kind divergence is the expected signal — act on the union. Never accept an orchestrated workflow's self-reported all-green as sufficient; independently re-run the diff inspection and verification suite yourself.
-- Proportion verification to cost, risk, and information gain: before expensive or slow live runs, diagnose in code and replay the changed deterministic logic over persisted real artifacts, probe at N=1 with inputs precondition-checked, and reserve full design-review-plus-live verification for first-of-kind or authority-changing work.
-- Trust a green / zero-findings verdict only if the check could have failed over a real, non-empty subject: assert the entity-under-test set has cardinality > 0 before any "no bad X" or "all X satisfy P" claim (an empty subject set passes vacuously and proves nothing), and for any test touching a branch you add or delete, confirm its inputs satisfy the live branch's entry guard — a copied fixture that fails the new guard silently routes into the about-to-be-deleted dead branch and stays green even after the real behavior breaks. When a check goes green unexpectedly fast or empty, dump what it actually ran over.
+- Proportion verification to cost, risk, and information gain: before expensive or slow live runs, diagnose in code and replay the changed deterministic logic over persisted real artifacts, probe at N=1 with inputs precondition-checked, and reserve full design-review-plus-live verification for first-of-kind or authority-changing work; proportion assurance to the deployment context — a single-user, own-data tool does not warrant production-grade assurance; prefer delivery.
+- Trust a green / zero-findings verdict only if the check could have failed over a real, non-empty subject: assert the entity-under-test set has cardinality > 0 before any "no bad X" or "all X satisfy P" claim (an empty subject set passes vacuously and proves nothing), and for any test touching a branch you add or delete, confirm its inputs satisfy the live branch's entry guard — a copied fixture that fails the new guard silently routes into the about-to-be-deleted dead branch and stays green even after the real behavior breaks. When a check goes green unexpectedly fast or empty, dump what it actually ran over. Checker code itself must assert the expected shape and fail loud — a permissive fallback (`a || b`) inside a gate absorbs wrong assumptions and keeps passing.
 
 ## Tooling and Operational Safety
 
+- 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.
-- Never accept secrets through transcript- or history-logged channels; 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.
+- 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).
+- Never accept secrets through transcript- or history-logged channels; 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.
-- Before reasoning about what a branch contains or opening a PR, run `git fetch` and compute the range as `origin/<base>..HEAD`, never `<base>..HEAD` against the local tracking ref — on a shared repo the local base drifts behind the remote until you pull, silently inflating the diff with already-merged work; if the range is surprisingly large, suspect a stale base before suspecting the branch.
+- Before reasoning about what a branch contains or opening a PR, run `git fetch` and compute the range as `origin/<base>..HEAD`, never `<base>..HEAD` against the local tracking ref — on a shared repo the local base drifts behind the remote until you pull, silently inflating the diff with already-merged work; if the range is surprisingly large, suspect a stale base before suspecting the branch. Platform "mergeable" flags are computed against the base only — sibling PRs can each look clean yet conflict; before picking a merge order, diff their changed-file sets and simulate the sequence.
 
 ## 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.
+- 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.
 - Allocate models by difficulty × blast radius, not phase name; when implementation ran on a cheaper tier, compensate by raising reviewer effort or adding a reviewer kind — never economize on implementation and verification at once.

package/codex/config-additions.toml

@@ -0,0 +1,22 @@
+# agent-bios additions for the LIVE ~/.codex/config.toml, which is user/
+# runtime-owned and never deployed wholesale. `agent-bios install` merges
+# exactly this content additively — the [agents.*] tables inside one marked
+# block, and features.multi_agent as one tagged line — and touches nothing
+# else in that file. `agent-bios uninstall` removes only that marked content.
+# ${CODEX_HOME} expands at install time. Descriptions are projections of the
+# canonical codex/agents/*.toml templates; check-parity fails on drift.
+
+[features]
+multi_agent = true
+
+[agents.frontier]
+description = "Bounded hardest decisions, first-of-kind design, triage, and final verdicts."
+config_file = "${CODEX_HOME}/agents/frontier.toml"
+
+[agents.workhorse]
+description = "Bounded implementation, fixes, and per-item judgment for delegated Codex work."
+config_file = "${CODEX_HOME}/agents/workhorse.toml"
+
+[agents.sweep]
+description = "Cheap read-heavy scans, candidate finding, mechanical checks, and closed-form summaries."
+config_file = "${CODEX_HOME}/agents/sweep.toml"

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

@@ -41,13 +41,14 @@ Main-context pollution is usually costlier than spawn overhead. Apply these gate
 4. **Specifiability:** keep work local when it needs the main's live context or unresolved round-trips, especially deep debugging. Grind alone is not a FRONTIER reason.
 5. **De-minimis:** do work directly when its dispatch packet would be larger than the work.
 
-- Escalate by spawning FRONTIER first; switch the main only when the judgment is not delegable.
+- **Escalation:** spawn FRONTIER first for a bounded judgment with material stakes (an irreversible or authority-changing action ahead, an architecture or public-interface commitment, or invalidation of two or more downstream units) and a named residual-risk signal (two failed attempts, two persisting alternatives, conflicting evidence, or an unverified assumption that can flip the decision). Pre-note the finding that would change what; send a blind packet — evidence, constraints, rubric, neutrally ordered alternatives, never the main's draft conclusion — and record the disposition afterward (what changed, or why nothing did; persistent no-change indicts the gate or the packet). Switch the main only when the judgment is not delegable.
 - Every spawn gets a bounded report contract, artifact paths instead of pasted context, and an explicit model/effort pin. Never dump a worker transcript into the main.
 - Explicit no-fan-out overrides standing authorization.
+- Record one line per gate decision — `SpawnGate: <gate> <tier> spawn|inline — <why>` — plus the FRONTIER disposition. A launch contract's `Delegation=off` lifts the spawn obligation, not the records.
 
 ## Delegation Mechanics And Teammate Persistence
 
-Delegate execution, not decisions. A unit is delegable only when it is decision-complete, self-containedly specifiable, machine-checkable at done-when, and bounded in blast radius.
+Delegate execution, not decisions. A unit is delegable only when it is decision-complete, self-containedly specifiable, machine-checkable at done-when, and bounded in blast radius. Delegated output is staged until the main accepts it — workers take no external irreversible actions — and handling (brief, verify, correct, integrate) must be clearly subordinate to the work itself. A SWEEP-bound unit applies one explicit rule per item and returns ambiguity as an exception, never resolved.
 
 - Re-cut units containing unresolved choice, discovery-before-spec, untestable completion, or unfrozen interfaces. A worker asking which direction to take is a sizing failure; the decision returns to the main.
 - Bundle related sub-floor tasks up to the decision-complete ceiling. A scout is read-only and reports file:line evidence for named pending decisions, probing the highest kill-risk unknown first.
@@ -56,7 +57,8 @@ Delegate execution, not decisions. A unit is delegable only when it is decision-
 - Use a resident teammate only for dependent slices in one burst. Verify that the CLI preserves its model and context; resume-after-completion may silently change both. Retire after the burst or cache TTL, and persist durable knowledge in files.
 - After a discard or direction change, respawn once a routine round costs about as much as a fresh slice. Recover unique in-flight state to files first.
 - Redirects to busy workers may queue rather than preempt. Check artifacts before destructive redirects, phrase them conditionally, and stop an actively harmful worker by scoped PID/worktree authority.
-- Idle/progress notifications are hypotheses; verify repo artifacts before re-dispatch. Cross-reset state belongs in files, not task boards or transcripts.
+- Idle/progress notifications are hypotheses; verify repo artifacts before re-dispatch. Cross-reset state belongs in files, not task boards or transcripts. When polling concurrent async jobs, pin the exact id/handle received at dispatch — a "latest" convenience selector can silently point at a sibling job and return plausible-but-wrong results.
+- Give reviewers/subagents a read-only diff, snapshot, or isolated worktree — not the live tree the main is editing — and forbid destructive git ops (checkout --, reset --hard, stash, clean) on any tree with uncommitted work; re-verify tree integrity before trusting results produced mid-edit.
 - Review cost scales with the diff, so layered review preserves delegation savings. Lower reviewer tier before dropping a review kind.
 
 ## Driving Codex CLI Directly
@@ -104,6 +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.
 
 ## Unattended Batch Safety
 
@@ -117,6 +120,8 @@ Instruction/config reach is per invocation. A rule in AGENTS.md cannot bind a he
 - Resume-first from artifacts that parse, pass schema, and match their recorded source/config/HEAD fingerprint; unverifiable means invalid.
 - 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.
+- Bounded-size cross-session indexes (memory index files) truncate silently past their read limit. Compare size against the limit periodically; before compacting, migrate index-only detail into per-item files, then verify links and no orphans.
 
 ## Sessions, Branches, Worktrees
 
@@ -124,6 +129,7 @@ Instruction/config reach is per invocation. A rule in AGENTS.md cannot bind a he
 - For a new worktree, relocate natively or write a handoff and start fresh. Re-integrate branches serially and re-verify after each merge.
 - 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.
 
 ## Handoff Contract
 
@@ -131,11 +137,12 @@ Write for the next agent and re-verification, not narrative. Required content:
 
 1. One-line current state.
 2. Pinned worktree, branch, HEAD, upstream/merge-base, author tier, and active fallback/family collapse.
-3. CONFIRMED claims whose cited command or anchored file evidence independently re-establishes them.
+3. CONFIRMED claims whose cited command or anchored file evidence independently re-establishes them. Anchor code citations by stable symbol names (grep-re-derivable), not bare line numbers, which drift silently under later edits.
 4. Separate PROPOSED/OPEN items, including inherited claims not re-verified this session.
 5. Ordered next actions and the literal first command: model, orchestration authorization, and guide load for T1+.
 6. Credentials only by env-var/gitignored slot; scrub secrets from excerpts and commands.
 
+- Never record the hash of the commit that will contain the record itself — it is unstable by construction. Land substantive changes first and reference the settled hash from a follow-up commit, or use a relative phrase ("resume from the commit containing this handoff").
 - A broken evidence anchor demotes CONFIRMED to PROPOSED. If pinned state fails or no trustworthy handoff exists, rebuild from source artifacts and write a fresh handoff before acting.
 - Store handoffs in the working repo's isolated dated docs path, never this instruction-SSOT repo. Re-verify load-bearing claims on resume.
 

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

@@ -32,6 +32,8 @@ When the user asks to "설계" or design, stay in design mode. Focus on high-lev
 2. Implementation-process design: turn the design into an ordered work plan with dependencies, verification points, review gates, and redesign triggers.
 3. Implementation: make the smallest viable functional changes that satisfy the approved design and process plan.
 
+When simplifying a pipeline, moving processing downstream and dropping captured source fields are separate decisions: relocation is free simplification, but reducing captured information is riskier and needs explicit confirmation — "no current consumer" is not evidence of no future value.
+
 ## Review Loop
 
 - 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).
@@ -41,6 +43,7 @@ When the user asks to "설계" or design, stay in design mode. Focus on high-lev
 - Treat high as supported user, environment, data, or execution path failure.
 - Treat medium as meaningful weakening of trust, auditability, reproducibility, completeness, or decision quality.
 - Treat low and info as non-blocking unless requested or promoted by new evidence.
+- When a document declares sections co-authoritative for a rule (fixture blocks, conformance appendices), treat every occurrence as one replicated value: propagate edits to all declared locations in the same pass and check propagation completeness explicitly in review.
 
 ## Verification Menus
 
@@ -51,6 +54,11 @@ Per-domain menus for the global Verification Discipline loop; pick the narrowest
 - 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.
+- 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.
+- 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.
+- 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.
 
 ## Stop Conditions
 

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

@@ -278,6 +278,11 @@ Required rules:
 - Log tool calls, arguments, policy decisions, and results for audit.
 - Rate-limit and timeout tools that can loop, scan, spend, mutate, or call the
   network.
+- Resolve every authorization/allowlist entry against the live runtime key
+  space at boot or deploy — format validation only proves well-formedness, and
+  a mis-formatted entry can pass every deploy check while silently denying its
+  whole route class. Verify fixes with an explicit negative control plus a
+  live end-to-end call through the redeployed system.
 
 The LLM can recommend an action. The capability surface decides whether the
 action is available, permitted, confirmed, and accepted.

package/codex/guides/mock-realization-boundary.md

@@ -246,6 +246,15 @@ Examples:
 - A mock provider can prove retry handling.
 - A mock provider cannot prove the real provider integration is production-ready.
 
+Connected cloud documents (live Sheets/Docs with bound scripts, triggers,
+permissions, protections, named ranges, external references) are live
+integrated systems, not portable files: unless the user explicitly asks for a
+copy/export, edit in place through the native authority (connected-document
+MCP/API). Before writing, enumerate the beyond-cell elements so none are
+silently dropped, and report external load states (loading, timeout, quota,
+permission-denied, broken reference) distinctly instead of collapsing them
+into one success/failure.
+
 ## Design Procedure
 
 Use this procedure before adding or extending mock behavior.

package/codex/guides/review-request.md

@@ -196,6 +196,14 @@ Two consequences for anyone consuming a review:
   the channel that fires uses the wrong name, and the truth is only in the nested
   stderr. Read the channel the mechanism actually writes, confirmed against the
   low-level log, not the one named for the thing you want.
+- Participation tells you the lenses ran, not that they saw the whole subject.
+  Git-diff-based review tools silently omit staged-but-uncommitted changes from
+  a HEAD-range diff, and untracked files from any diff. Before dispatch, list
+  the subject with `git status --porcelain` and expose untracked files
+  (`git add -N` or a WIP commit); after the run, compare the reviewed-file list
+  against that listing — an unexplained gap demotes the verdict to incomplete.
+  (Our own dispatch wrapper does this check itself; apply this manually on
+  review routes we do not own.)
 - A review deliverable names the findings it *rejected* as well as the ones it
   kept, so a finding's presence in the document is not its survival. Deriving
   survival from presence returns 100% by construction — it did here, until the

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

@@ -0,0 +1,100 @@
+---
+guide_id: session-learning-workflow
+language: en
+status: active
+use_when:
+  - a session was launched with the Session learning preset (mission-injected)
+  - the launcher nudge says enough sessions accumulated for a mining window
+  - mining local Claude/Codex sessions for learnings absent from the corpus
+  - promoting, incubating, or retiring items in the session-learning ledger
+core_rules:
+  - the ledger and HANDOFF are the SSOT; read them before touching the pipeline
+  - placement follows PLACEMENT-FRAMEWORK.md, never ad-hoc judgment
+  - every promotion passes an explicit user-approval gate
+  - global growth per round is hard-capped (~500 tokens) by a measured gate
+  - close the window by updating mirrors, parity, deployment, and the nudge baseline
+---
+
+# Session-Learning Workflow
+
+Runbook for a learning-refinement session: mine recent main-context sessions,
+verify candidates, place them through the framework, and apply with the user.
+Everything durable lives in the agent-bios repo.
+
+## Read first (SSOT)
+
+1. `design/session-learning/HANDOFF.md` — initiative state, prior decisions,
+   open threads. 2. `design/session-learning/PLACEMENT-FRAMEWORK.md` — the
+   placement authority (typology A–G, layers, admission bars, lifecycle).
+3. `design/session-learning/ledger.json` — cumulative item states
+   (placed / incubating / absorbed / retired) with provenance.
+
+## Stage 1 — Mine (pipeline in `scripts/session-learning/`)
+
+Run in order; each stage reads the previous stage's `out/`:
+
+1. `census.py --end YYYY-MM-DD` — enumerate from both providers'
+   history.jsonl; keep only directly-handled main-context sessions by
+   transcript-side provenance (dispatched = Codex source=exec /
+   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` (Workflow) and
+   `screen-codex.js` (ultracode). 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).
+
+## Stage 2 — Review with the user
+
+- Produce a Korean review edition as a local repo file (this user cannot
+  access web artifact renders): per item, principle, why it was selected,
+  verdict, and placement recommendation, with stable IDs.
+- Decisions, in order: ① selection against the promotion bar (recurrence ≥2
+  or single-event high materiality — irreversible / verification-corrupting /
+  security); ② PROPOSED resolutions (never silently resolved); ③ G-candidate
+  adoption. Record every decision in the ledger.
+
+## Stage 3 — Classify and apply (§P8)
+
+- Walk each accepted item through the framework pipeline: type (A–G) →
+  leftward reformulation (fact→principle, knowledge→structure) → layer →
+  consumer check (hermetic dispatch and scripts read no prose) → admission
+  bar → token estimate. Ambiguity stays PROPOSED for the user.
+- Apply canonical-first, on a branch, stepwise commits: canonical guide text
+  → global edits under the measured budget gate (net growth ≤ ~500 tokens/
+  round; overflow re-routes to guides, not silent deferral) → other guides →
+  hooks (derive injected text from the canonical guide; read-only, never
+  blocking) → enforcement in owned wrappers (loud failures; keep
+  stdout/stderr channel contracts) → codex/ + ko/ mirrors.
+- Verify per layer, not just by diff: enforcement/gate fixture tests
+  (non-vacuous — known-bad must fire), hook trigger positive/negative sets,
+  `scripts/check-parity.sh` exit 0 unpiped, prompting-target gate, then
+  `agent-bios install` to activate and re-verify.
+
+## Stage 4 — G-pass (principles, not directives)
+
+- Mine user-correction turns (deterministic marker extraction over digests)
+  and initiative-arc retrospectives; add upward distillation over newly
+  placed directives (≥3 sharing one value → parent-principle candidate).
+- G evidence bar is higher: ≥3 independent consistent resolutions, or one
+  user-confirmed arc retrospective. A principle must name the tension, the
+  ordering, and what it forbids. For an under-applied gap (rule exists but
+  behavior does not follow), prose repetition is invalid — list it for the
+  behavior battery and change the surface instead.
+
+## Stage 5 — Close the window
+
+1. Ledger: statuses to placed (with implementation paths) / incubating;
+   dated corrections for anything refuted.
+2. HANDOFF: completion record, incidental finds as next-window candidates.
+3. Register the learning version: append {version = window end, commit = the
+   corpus-close commit} to `design/session-learning/versions.json` — this is
+   what the launcher's Versions & rollback screen offers — then run
+   `python3 scripts/session-learning/update-state.py --window-end <date>`
+   (nudge baseline) and `learning-state.py project` (launcher status panel).
+4. Merge the branch, push, and confirm deployed state (`agent-bios verify`).

package/codex/guides/tooling-gotchas.md

@@ -0,0 +1,155 @@
+---
+guide_id: tooling-gotchas
+language: en
+status: active
+use_when:
+  - a shell command's exit code or output will gate a pass/fail or verification decision
+  - a tool returns empty / no-match / not-found output that contradicts other evidence
+  - running git diff over ranges, or pulling into a worktree with local changes
+  - passing dynamic or untrusted strings through a shell command line
+  - operating cloud/managed-service CLIs, update APIs, or secrets-bearing config
+  - spawning subprocesses or long-lived handles
+core_rules:
+  - pin ambient state (interpreter, CLI context, command resolution) where an outcome depends on it
+  - a piped command's exit code reflects only the last stage — capture the stage under test
+  - treat surprising empty output as a tool artifact hypothesis before a world fact
+  - git two-dot diff is a snapshot comparison, not a range exclusion; protect dirty worktrees before pulling
+  - own the full lifecycle of anything you spawn
+---
+
+# Tooling Gotchas
+
+Concrete, tool-level traps behind the global principles. Claude-side hook
+injections derive their text from this file — edit here, never in the hook
+data (single source of truth).
+
+## Ambient state drifts — pin it
+
+Instances of the global rule: ambient state silently drifts; where an outcome
+depends on it, pin it explicitly instead of trusting the environment.
+
+- **Interpreter**: the default shell differs across machines (zsh/bash/dash)
+  and bash-only idioms misbehave silently elsewhere (unquoted-variable word
+  splitting, `read -r -d ''` hangs). Don't probe the shell per command — make
+  shell identity irrelevant: keep inline one-liners POSIX-portable; when a
+  bash-specific feature (arrays, `read -d`, `PIPESTATUS`) is needed, pin the
+  interpreter with a `#!/bin/bash` script file or `bash -c '…'`. The session
+  environment block already declares the shell — read it for free; probe only
+  when diagnosing a misbehavior.
+- **Command resolution**: a command name is not a fixed binary — interactive
+  shells resolve functions/aliases first, programmatic spawns resolve raw
+  PATH, and a same-named package can shadow a system tool with silent empty
+  output. Before trusting a result across execution contexts, confirm the
+  resolved target (`type -a`, absolute path).
+- **Cloud CLI context**: gcloud/aws/kubectl/terraform carry mutable ambient
+  context (active project, profile, cluster) that drifts between sessions.
+  Before the first environment-affecting command — or right after a resume —
+  verify it against intent, then pin the target explicitly on every command
+  (`--project`, `--profile`, `--context`) rather than fixing the global
+  default once.
+- **Installed is not running**: a live process keeps its old code until
+  restarted or reloaded. When confirming an update, config change, or
+  dependency bump took effect, don't stop at the on-disk artifact — confirm
+  the running process's actual version/behavior or force a restart.
+
+## Shell execution traps
+
+- **Pipe exit masking**: `$?` after a pipeline reflects only the last stage;
+  a real failure in the command under test is masked by a successful
+  `tail`/`grep`/`jq` and reads as a false green. Capture the tested stage's
+  own status: run it unpiped, store `$?` immediately, or use
+  `set -o pipefail`/`PIPESTATUS` — noting pipefail breaks legitimate
+  early-exit consumers (`cmd | head -1` → SIGPIPE 141), so it is a per-command
+  choice, not a global default. Does not apply when the final stage IS the
+  assertion (`cmd | grep -q pattern`).
+- **Reserved parameter names**: assigning to reserved shell names (`UID`,
+  `EUID`, `GID`, `PPID`) can invoke the bound system behavior instead of
+  storing a value — silently changing process credentials mid-script. Use
+  unreserved names; if such an assignment already ran alongside a
+  side-effecting command, verify the resulting system state directly instead
+  of assuming the mistake inhibited the command.
+- **Metacharacter-bearing values**: prompts, filenames, or content strings
+  that may contain `$`, backticks, quotes, or globs must not be inlined as
+  raw CLI arguments — the shell expands or mangles them before the target
+  process sees them. Pass via stdin, heredoc, or a temp file. (Our dispatch
+  scripts codex-run/codex-helm already accept stdin — use that path.)
+- **Multi-line pasted commands**: a command pasted across lines without
+  continuation markers can be re-wrapped into two invocations, silently
+  dropping trailing flags (a real incident: `--scopes` lost during an auth
+  flow → wrong-scope credential). After running one, verify the target's
+  actual state (granted scopes, applied settings); on re-run, join to one
+  line or use explicit continuations.
+
+## Tool output is a rendering, not the bytes
+
+- **grep binary heuristic**: grep silently treats heavy non-ASCII or
+  NUL-containing text files as binary and returns a false no-match without
+  error. When a no-match contradicts other evidence (git diff, an earlier
+  read), re-check with the harness Grep tool (ripgrep) or `grep -a`, or read
+  the file directly.
+- **Viewer normalization**: file-read tools can render non-printable bytes
+  (NUL) as visually indistinguishable blanks. When correctness rides on
+  byte-exact content (delimiters, encodings), verify with `hexdump`/`od` or a
+  byte-comparing script, not the rendered view.
+- **Stale caches in rapid loops**: mtime/size-keyed compile or rewrite caches
+  can re-serve a previous file's result when mutate→test cycles run within
+  timestamp resolution (mutation testing). Clear the cache or run no-cache
+  per iteration, and re-confirm the unmutated baseline still passes after a
+  cache clear.
+
+## Git operations
+
+- **Two-dot diff semantics**: `git diff A..B` is a direct snapshot
+  comparison — unlike `git log A..B` it excludes nothing, so a lagging
+  merge-base injects unrelated upstream changes into the diff. For PR/review
+  diffs use `git diff origin/base...HEAD` (merge-base form); suspect this
+  mechanism first when a diff looks too large or shows deletions in untouched
+  files.
+- **Dirty-worktree pulls**: before pulling into a worktree with
+  staged/unstaged/untracked changes, fetch first and compare incoming paths
+  against every dirty path; on overlap or a non-fast-forward, stop and clear
+  the conflict risk (stash, commit, ask). Otherwise pull `--ff-only`, confirm
+  dirty changes survived, and regenerate any local derived artifacts whose
+  inputs were updated.
+
+## Config, secrets, and managed services
+
+- **Verbatim slicing over parse-reserialize**: when provisioning part of a
+  user's structured config (TOML/YAML/INI) that may carry secrets and
+  comments, extract the section's raw text instead of parsing and
+  re-serializing — rewrites silently drop comments, formatting, or secret
+  values. Use a parser only for real structural change, and test the slicer
+  against actual shapes first.
+- **Merge-not-replace update APIs**: managed-service update calls (secret
+  rotation, mount changes) often merge new definitions into the existing set,
+  leaving stale, unreferenced definitions live. After updating, re-read the
+  resource, check definitions and active references separately, and remove
+  the orphans explicitly.
+- **Perimeter controls need the enforcement point's own logs**: an agent-side
+  fetch is not an independent external observer — its egress IP and caching
+  path are opaque, and it may share the protected network or serve a stale
+  cached response. Verify allow AND deny directions from the load balancer /
+  firewall's own logs, and check for a front-side cache/CDN separately.
+- **Smoke limits outlive the smoke test**: item caps, sample sizes, and row
+  limits left in env vars/flags/config make a later "full-scale" run silently
+  succeed on a slice. Clearing or explicitly verifying their absence is a
+  precondition of declaring a full run.
+- **Shared live config has concurrent writers**: before concluding your edit
+  to a shared state/config file was lost or corrupting, rule out concurrent
+  writers with a short live observation (mtime plus the fields you changed),
+  and scope merge/union operations to the intended fields only.
+- **Production probes expose data**: default diagnostic queries against
+  production stores to read-only server-side aggregation (counts, types,
+  presence, hashes) — never pull raw payloads into logs, prompts, or
+  transcripts — and delete scratch probe resources after the decision.
+
+## Own what you spawn
+
+Instance of the global rule: own the full lifecycle of what you create.
+
+- **Subprocess/handle lifecycle**: creating a subprocess means owning spawn
+  (set up a process group), result acquisition, and teardown — close owned
+  stdio handles, kill exactly that group (not just a wrapper PID, which
+  orphans the real child), and await exit. An unref'd child handle or open
+  stdin pipe keeps the parent's event loop alive and hangs otherwise-complete
+  commands.

package/config/agent-launch.toml

@@ -98,3 +98,20 @@ review_setup = "native-panel"
 delegation = true
 codex_execution_policy = "bypass"
 claude_permission_mode = "bypassPermissions"
+
+[presets.session-learning]
+label = "Session learning"
+description = "Dedicated learning-refinement session: mine recent sessions, verify, place, and apply per the session-learning workflow."
+main_tier = "helm"
+frontier_effort = "max"
+review_setup = "hybrid"
+delegation = true
+codex_execution_policy = "bypass"
+claude_permission_mode = "bypassPermissions"
+mission = "This is a session-learning initiative session, gated on a trigger. When the user enters the trigger command '{trigger}': read the session-learning-workflow guide in your installed guides directory, then the initiative SSOT design/session-learning/HANDOFF.md in the agent-bios repo, and run the next mining window per that guide. Until the trigger arrives, respond normally and do not start the workflow. Every promotion passes through explicit user approval; nothing is applied to the corpus without it."
+trigger = "learn!"
+
+# Nudge baseline lives in ~/.local/share/agent-bios/session-learning-state.json,
+# written by scripts/session-learning/update-state.py at window close.
+[session_learning]
+nudge_after = 250

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-bios",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "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": "scripts/install.sh"
@@ -8,9 +8,12 @@
   "files": [
     "claude/CLAUDE.md",
     "claude/guides/",
+    "claude/hooks/",
+    "claude/agents/",
     "codex/AGENTS.md",
     "codex/guides/",
     "codex/agents/",
+    "codex/config-additions.toml",
     "config/agent-launch.toml",
     "shell/agent-launch.zsh",
     "scripts/agent-launch.py",