agent-bios 0.1.0 → 0.3.0

package/codex/guides/review-request.md

@@ -0,0 +1,274 @@
+---
+guide_id: review-request
+language: en
+status: active
+use_when:
+  - writing a review request, packet, or reviewer role for any model
+  - deciding what evidence bar and verdict shape to demand from a reviewer
+  - triaging why a review returned noise, nothing, or a clean bill of health
+  - choosing which perspectives to run and whether to pay for deliberation
+core_rules:
+  - demand a failure path, not a gap — "X is unverified" dies, "X breaks when Y" survives
+  - require every finding to anchor to file:line, and every empty result to cite what was checked
+  - say what the target is and is not — stage, boundary, and what absence means
+  - bundle the consumer the target depends on, or its most load-bearing claim is unreviewable
+  - forbid carry-forward findings — anything phrased "watch" or "document later" is not a finding
+  - read participation before believing a verdict; a crashed harness reports zero findings
+  - treat a finding's causal attribution as the reviewer's weakest claim, not its severity
+verification_focus:
+  - a zero-findings verdict is confirmed against participation, not accepted at face value
+  - findings are checked for a stated failure path before they are acted on
+  - an empty result is trusted only when it cites the evidence it checked
+---
+
+# Review Request Guide
+
+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 staged-workflow guide's severity ladder and review loop own that),
+which reviewer kind to route to (the multi-model guide's convergence heuristic),
+or how to phrase a prompt for a given model family (the per-family prompting
+guides).
+
+The rules below are derived from ~330 real multi-lens review sessions run in
+this environment. That corpus is one model family in practice, so nothing here
+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.
+
+## Demand a failure path, not a gap
+
+The dominant reviewer failure is not hallucination. Across 372 rejected
+findings, "asserted a gap without demonstrating a failure" accounts for the
+largest share (~34%), while misreading correct code accounts for **one** case
+and speculation for seven. Reviewers do not invent defects — they report
+unverified things and call them findings.
+
+The corpus separates these cleanly by how the finding is framed:
+
+| Framed as | Dropped |
+|---|---|
+| `evidence_gap` — "not covered / not verified" | 94% (n=143) |
+| `needs_evidence` | 93% (n=118) |
+| `document_only` | 92% (n=144) |
+| `root_cause` — a defect with a cause | 3% (n=878) |
+| `fix_now` | 3% (n=1026) |
+
+So say it in the request: **state the input, the branch, and the observable
+wrong behavior. "X is not verified" is not a finding; "X breaks when Y" is.**
+A reviewer that cannot show the failure should say so as a boundary note, not
+file it against the target.
+
+## Set a severity floor, because low never survives
+
+Severity is the single most decisive predictor in the corpus, and it is close to
+deterministic:
+
+| Severity | Reaches the deliverable |
+|---|---|
+| `blocker` (n=16) | 100% |
+| `high` (n=366) | 96% |
+| `medium` (n=1338) | 92% |
+| `info` (n=44) | 5% |
+| `low` (n=226) | **0%** |
+
+Not one low-severity finding out of 226 survived. The tokens that produced them
+were spent for nothing, twice — once writing, once reading.
+
+So state the floor in the request: **do not report a finding you would rate low.
+It will be discarded; spend the effort on a medium-or-above finding instead.**
+This is not a quality bar on the reviewer, it is a cost decision — the corpus
+shows the discard happens regardless, so the only question is whether you pay to
+generate it first. (What counts as each severity is the staged-workflow guide's
+ladder, not this guide's.)
+
+## Forbid carry-forward findings
+
+Every finding the corpus classified as deferrable died: `planned_later` 100%
+(n=104), `watch` 100% (n=36), `defer_watch` 97% (n=71), `out_of_scope` 92%
+(n=26). Not one survived to the deliverable.
+
+Ask only for what must change in this target now. Anything the reviewer would
+phrase as "carry forward", "watch", or "document later" costs tokens to produce,
+tokens to read, and is discarded — say that up front so it is never written.
+
+## Say what the target is, and what absence means
+
+The most common thing reviewers report they lacked is the stage context: they
+review a design and cannot see the implementation, then hedge every finding into
+a design-contract claim. Their own words, recurring across sessions: *"The packet
+reviews a design, not an implemented patch, so the exact future API is not
+visible."*
+
+Name the stage and say what absence means — "this is a pre-implementation
+design; do not treat missing implementation as a defect." A session given exactly
+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.
+
+## Bundle the consumer, not just the artifact
+
+When a target says "see X", X is part of the target. The corpus's sharpest
+example: a reviewer identified the most load-bearing connection in a design and
+then could not review it — *"§6.4 is outside the review boundary, so
+axis-consumption completeness cannot be verified within the artifact."* The
+request bundled the child and not the parent it depended on.
+
+What reviewers needed, almost every time, was the consumer: the code that reads
+the field, the parent doc defining the weights, the log proving the behavior. If
+a claim's evidence lives outside the boundary, either widen the boundary or
+accept that the claim is unreviewable — do not expect a finding about it.
+
+## Make evidence structural, not requested
+
+In this corpus every finding carries a `file:line` anchor and every empty result
+carries a rationale — 2,466/2,466 and 981/981. Not because the prompts asked
+nicely: the submit schema refuses output without them. The result is a corpus
+where reviewers are right about existence (0.3% of issues end unresolved after
+argument) and where "found nothing" is a verified statement rather than silence.
+
+This is the general rule from the capability-boundary guide applied to review:
+when output must have a property, make it unavailable without it. If your review
+route has a schema, put the anchor there. If it does not, the demand belongs in
+the request — but expect the weaker result that a request-only rule gives you.
+
+The same applies to the target: a document that cites its own facts as
+`file:line` gives the reviewer a falsifiable surface, and the corpus's best
+findings are refutations of exactly those cited facts. Prose gives nothing to
+check.
+
+## Claim only what the evidence proves, and attribute it to one root
+
+Reviewers are calibrated on whether a defect exists and miscalibrated on why.
+When a finding is narrowed, the defect itself almost always survives (97%,
+n=212). What gets cut is the causal attribution (45%) or the surface the claim
+covered (34%) — not the proposed fix (10%), and not the defect. Lenses register
+this as a first-class stance: `narrow` appears 1,320 times against 101 for
+`oppose`. They rarely disagree that something is broken; they routinely disagree
+about what broke it, and about how much of the system it touches.
+
+"Narrowed" is a misleading name for what happens. Narrowed claims get **longer**
+— 94% of them, by a median of ~118 characters — because narrowing adds
+qualification and re-attribution rather than deleting text. The final root cause
+is a near-rewrite (median text similarity 0.21 against the original). What looks
+like trimming is the reviewer being made to say what its evidence actually
+supports.
+
+That makes narrowing and rejection the same force at different granularity:
+overclaim beyond your evidence and the finding is narrowed if a proven core
+exists, dropped if it does not. The corpus language is identical in both — the
+survivors are "narrowed to the directly evidenced command-wiring gap", "to files
+proven in capsule authority_refs", "to the demonstrated side-effect path".
+
+So ask for the observable failure and the evidence that proves it, scoped to the
+surface that evidence covers. Treat the reviewer's causal story as its weakest
+claim — a hypothesis to verify, not a conclusion — and do not let a proposed fix
+become the design by default.
+
+One axis is easy to miss: in ~17% of narrowings every lens accepts the defect,
+the root, and the fix, and the only live disagreement is **how bad it is**. That
+matters more than its share suggests, because severity decides survival — a
+finding rated low never reaches the deliverable. If severity is contested, it is
+the thing to adjudicate, not a detail to average out.
+
+## Read participation before believing a verdict
+
+Seven sessions reported `Finding count: 0` — a clean bill of health — with
+`Participating lenses: 0/N`. Nothing was reviewed. And when the harness dies, two
+separate channels lie about why. Twenty-two sessions recorded
+`failure_kind: output_contract`; in the ones whose nested stderr is readable the
+cause is a provider usage-limit rejection — *"You've hit your usage limit"*,
+`exit=1`, no model output produced at all — so the label blames the model's
+output format for a pre-dispatch billing refusal, when no output ever existed to
+violate a contract. Triage by that label and you debug the prompt when you needed
+to buy credits.
+
+Two consequences for anyone consuming a review:
+
+- The tell is the participation count and execution status, never the severity
+  counts. A crashed harness renders as a perfect score.
+- Artifacts named for failure may not carry it, and the two failures compound. In
+  those same quota-killed sessions the file named `environment-warnings.yaml`
+  recorded only `non_fatal` dispatch traces with `outputTrustImpact: unknown` and
+  never once mentioned the quota; corpus-wide it holds ~9,800 warnings and has
+  never fired on a real failure. So the channel named for failures never fires,
+  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
+  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.
+
+## Trust an empty result only when it cites what it checked
+
+Empty is common and usually correct: 42% of lens invocations produce nothing,
+and those runs have *larger* inputs and sit *later* in a repo's review sequence
+than productive ones — they are re-reviews of targets already fixed. The waste
+worth naming is not the empty result; it is paying full pipeline cost to
+re-review something you already repaired.
+
+An empty result earns trust from its rationale. A reasoned null names the
+evidence it checked on both sides of the comparison. A rationale-free empty
+result is a failed run wearing a clean verdict — gate on the rationale, not on
+the emptiness.
+
+## Spend deliberation where it adjudicates, not where it agrees
+
+Two-thirds of issues (66%, n=1153) never need deliberation, and the largest
+single cause of halted sessions is the user cancelling. But they do not cancel
+early: of 27 cancelled sessions all 27 reached the raw first pass, 22 reached the
+consolidated finding ledger, and only 2 reached deliberation. Users wait for the
+deduplicated, severity-tagged ledger, act on it, and abandon the deliberation and
+synthesis that would have run next. Meanwhile the issues that *are* deliberated
+and survive are the most reliable in the corpus (94% material vs 74% for
+undeliberated).
+
+So deliberation is worth its cost when it adjudicates a contested claim, and is
+ceremony when every perspective already agrees — one of the largest deliberation
+artifacts in the corpus resolved 22 of 22 issues as "no deliberation needed".
+Front-load the actionable findings, because that is the part that gets used.
+
+## Choose perspectives that can bite
+
+Adding a perspective is not free. In this corpus the concept-surface lens
+produces the fewest findings, is silent most often, and half of what it does
+produce is discarded — because 43% of its candidates are rated low, and low
+never survives. Naming, redundancy, and abstraction concerns count only when
+they change runtime behavior or enforced semantics; ask for them on that
+condition or not at all.
+
+The inverse failure is worth watching for: when no perspective owns the real
+risk, a reviewer files a governance gap instead of a defect — *"this is a
+review-governance gap, not a design defect in the target."* That is the review
+telling you its own lens set was wrong for the target.
+
+## Evidence base
+
+Derived 2026-07-16 from ~330 onto review sessions across 15 repositories in this
+environment (1,738 classified issues; 2,466 anchored findings; 278 deliberations;
+14,370 lens stances). Every count here was reproduced independently before being
+written down, and several first attempts were wrong: survival measured by
+document presence returns 100% by construction, and hand-rolled verb-object
+counting undercounted the narrowing axes about fivefold. Where a share is given
+for how narrowing splits, read it as a floor — ~19% of cases resist
+classification — and trust the ordering (root > scope > severity > remedy) rather
+than the magnitudes.
+
+Two limits bound what this guide may claim. The corpus is ~95% a single model
+family, so nothing here is a per-model claim. And it contains no under-specified
+requests — the shortest still names its axes and its evidence bar — so these are
+the failures that survive a *good* request, not an argument that requests need
+specifying. Re-derive from a fresh corpus when the review route or the bound
+models change.

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

@@ -8,11 +8,17 @@ passthrough_args = []
 command = "claude"
 passthrough_args = ["--dangerously-skip-permissions"]
 
+# Optional dependencies. `command` gates the route: unresolvable means the route
+# is unavailable and the review setup degrades without it. `install` is the single
+# source for both the one-line hint shown when it is missing and what
+# `agent-bios install --with <name>` runs.
 [capabilities.onto]
 command = "onto"
+install = "npm i -g onto-mcp"
 
 [capabilities.ultracode]
 command = "ultracode-for-codex"
+install = "npm i -g ultracode-for-codex"
 
 [hosts.codex]
 models = ["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna"]
@@ -92,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.1.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,13 +8,17 @@
   "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",
     "scripts/check-parity.sh",
+    "scripts/check-prompting-targets.sh",
     "scripts/codex-run.sh",
     "scripts/codex-helm.sh",
     "scripts/install.sh",
@@ -48,7 +52,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/kangminlee-maker/agent-dotfiles.git"
+    "url": "git+https://github.com/kangminlee-maker/agent-bios.git"
   },
   "license": "MIT"
 }