agent-bios 0.13.0 → 0.15.0

package/codex/guides/claude-prompting.md

@@ -15,6 +15,14 @@ core_rules:
   - make tool descriptions prescriptive about when to call, not only what the tool does
   - require progress claims to be audited against a tool result from the same session
   - name the boundary explicitly — what to do without asking, and what to stop and ask about
+derived_at: 2026-09-01
+source_pins:
+  - doc: prompting-claude-opus-5
+    sha256: 65be3e0b437cbe23cc41bb4f9b7a5031c5a71cd49ab91ec4d19c62738762b086
+    pinned_at: 2026-09-01
+  - doc: claude-prompting-best-practices
+    sha256: 476ddc2744812dced0b520c8f628aecb52df52babdaf82ee5a0b10f25f5bcbdb
+    pinned_at: 2026-09-01
 targets:
   - claude-fable-5
   - claude-opus-5
@@ -68,7 +76,12 @@ pick the path.
 - Delegation: say when *not* to delegate, and cap the spawn count. The helm
   binding reaches for subagents readily — the reverse of the binding it replaced
   — and every spawn rebuilds context, reports back, and is then re-read, so
-  unbounded delegation multiplies cost and latency. File-based memory and custom
+  unbounded delegation multiplies cost and latency. Where the harness offers
+  deterministic caps, prefer them to prose: under Claude Code and the Agent SDK
+  these are `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`,
+  `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`, and the SDK's `max_budget_usd` — a
+  limit the model cannot talk itself past. Confirm the harness version supports
+  them before relying on it. File-based memory and custom
   tools are the opposite case: they still need an explicit when-to-use trigger.
 - Autonomous runs with no human watching: say so. Otherwise it asks permission
   it does not need and blocks. Grant autonomy on minor choices (naming,
@@ -107,7 +120,9 @@ pick the path.
   treating a quiet call as a hang.
 - Do not add "summarize every N tool calls" scaffolding — this tier narrates on
   its own. If it narrates too much for a coding agent, set a silence default
-  instead: text only on a finding, a direction change, or a blocker.
+  instead: text only on a finding, a direction change, or a blocker. Describe the
+  cadence you want by example; a positive description of the style outperforms a
+  list of what not to do.
 - Length is a prompting lever, not an effort lever. This tier writes longer
   answers and longer files than its predecessors, and lowering `effort` does not
   reliably shorten visible output — only an explicit instruction does. Calibrate
@@ -121,6 +136,36 @@ pick the path.
   work they did not watch. Lead with the outcome; drop the working shorthand.
 - Do not show a remaining-context countdown. This tier can start conserving and
   suggest a fresh session instead of finishing.
+- Re-validate prompt-side vision workarounds carried from older bindings; this
+  tier is strong on charts, documents, diagrams, and UI replication, and the
+  workaround may now be the thing costing quality. Tools that let it crop and
+  visually verify beat thinking alone here.
+- Instruction following stays consistent across the full context window, so a
+  rule does not need restating near the end to survive a long session.
+
+## Running with thinking disabled
+
+Disabling thinking is accepted only at `high` effort or below, and it is usually
+the wrong lever: thinking on at `low` effort generally beats thinking off at
+comparable cost. Reach for lower effort before reaching for the switch.
+
+Two artifacts appear when it is off, and both are prompt-fixable:
+
+- A tool call written as **user-facing text** instead of a structured call. The
+  turn completes, the call never runs, and in an agentic loop the leaked text
+  stays in history and contaminates later turns. Most common on tool-heavy work.
+- Internal XML tags leaking into the visible response.
+
+One instruction mitigates both — permission to speak before a call, an out when
+no tool fits, and a general ban on internal tags:
+
+> When you use a tool, you may say a brief sentence first. If no tool can express
+> what the user asked for, say so instead of guessing. Do not include internal or
+> system XML tags in your response.
+
+Two traps. Naming the tags specifically is **less** effective than the general
+form. And if a prompt anywhere tells this tier not to think or not to reason,
+delete it: that instruction increases tag leakage rather than suppressing it.
 
 ## Prompt assembly checklist
 
@@ -134,8 +179,15 @@ pick the path.
 
 ## Sources
 
-Derived from the vendor's published guidance for the `targets` models above.
-When a `targets` model changes, re-derive this guide from current vendor
-guidance rather than editing around the old rules — prompting guidance is
-version-bound. `launch/check-prompting-targets.sh` fails when the launch config
-binds a model this guide does not list.
+Derived from the vendor's `prompting-claude-opus-5` and
+`claude-prompting-best-practices` documents, at the exact bytes whose hashes are
+recorded in `source_pins` above. The pin is what makes a later vendor edit
+detectable rather than remembered.
+
+Prompting guidance is version-bound — this generation inverted advice the last one
+gave — so when a `targets` model changes, re-derive from the current documents
+rather than editing around the old rules.
+`launch/check-prompting-targets.sh` fails when the launch config binds a model
+this guide does not list; that check is about **naming**, and a model added to
+`targets:` satisfies it forever. Whether the guidance was actually re-derived is
+not decidable and is gated nowhere.

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/gpt-prompting.md

@@ -15,6 +15,14 @@ core_rules:
   - replace blanket ALWAYS/NEVER with decision rules naming the condition each choice applies under
   - fix the prompt before raising effort — weak output usually means a missing success criterion, dependency rule, tool-routing rule, or verification loop
   - prompting habits carried from older gpt models cost tokens and can cost accuracy
+derived_at: 2026-09-01
+source_pins:
+  - doc: prompt-guidance-gpt-5p6
+    sha256: 46181efec9fd1160ef537b0379282a14c1ba32380f2f8149a805128253c1115a
+    pinned_at: 2026-09-01
+  - doc: latest-model
+    sha256: 48f61f648eab971334f6076bc61478d0f2bcd7a50111064722eba267a0f98d61
+    pinned_at: 2026-09-01
 targets:
   - gpt-5.6-sol
   - gpt-5.6-terra
@@ -85,9 +93,50 @@ Compose in this order; omit any block that would not change the artifact.
 - Prefer a self-contained packet over resuming a long history: it is cheaper to
   reason about and cheaper to cache.
 
+## Programmatic tool calling
+
+A bounded stage where code processes several tool results and returns a much smaller
+structured result. The qualifier is **reduction**, not parallelism: multiple, parallel,
+or dependent calls alone do not justify it.
+
+- Use it for filtering, joining, sorting, ranking, deduplication and aggregation;
+  batching across many similar records; repeated deterministic validation; and large
+  structured results reducible to a compact schema.
+- Prefer direct calls when one call suffices, when intermediate outputs are already
+  small, when each result may change the next decision, when an action needs approval,
+  when the answer must preserve citations or native artifacts, or when semantic
+  judgment sits between calls.
+- A generic "use programmatic tool calling efficiently" does nothing. State the bounded
+  stage, the eligible tools, the output schema, the retry limit, the stop condition, and
+  the handoff back to direct judgment. If both routes are needed, define one handoff and
+  say not to switch routes or repeat completed work.
+- **Test both outputs.** The program's result and the final assistant message are
+  separate; a program can return the right records while the message drops a required
+  field, citation, or caveat.
+- Compare the two routes on the same tasks, and count lower token/latency/cost as an
+  improvement only when the response still passes the existing evals.
+
 ## Working rules
 
 - One clear task per run, with an explicit output contract.
+- **Read the assembled prompt for contradictions.** This tier follows a prompt contract
+  closely, so two rules that disagree destabilize it more than a missing rule does —
+  the opposite of the intuition that more instruction is safer.
+- State each authority rule once. Repeating "ask first", "do not mutate", or "wait for
+  approval" produces approval requests for safe, expected actions.
+- Name the current layer of work — research, design, implementation, review, external
+  coordination — on long-running tasks, so the model does not move between layers
+  silently.
+- Persisted reasoning is not a free optimization. It helps while the objective and
+  priorities hold; once they move, stale reasoning adds tokens and anchors the model to
+  a superseded approach. Compact at milestones, not every turn, and treat compacted
+  items as opaque.
+- Set the default detail level through the API (`text.verbosity`) and keep the prompt
+  for task-specific length and structure; a prompt-only length rule has to be restated
+  everywhere.
+- Preserve explicit user values. Where the right value is implicit, give decision
+  criteria and let the model reason from context or schema rather than installing
+  universal defaults or keyword maps.
 - Keep reusable prefixes stable and avoid churn in large system prompts. Add
   explicit cache breakpoints only where they measurably improve cache behavior —
   a cache write costs 1.25× the uncached input rate, so read the cached-token
@@ -110,9 +159,16 @@ Compose in this order; omit any block that would not change the artifact.
 
 ## Sources
 
-Derived from the vendor's published prompting guidance for the `targets` models
-above. When a `targets` model changes, re-derive this guide from current vendor
-guidance rather than editing around the old rules — prompting guidance is
-version-bound, and the previous generation's advice inverted on this one.
+Derived from the vendor's `prompt-guidance-gpt-5p6` and `latest-model`
+documents, at the exact bytes whose hashes are recorded in `source_pins` above.
+The pin is what makes a later vendor edit detectable rather than remembered.
+
+Prompting guidance is version-bound and the previous generation's advice inverted
+on this one, so when a `targets` model changes, re-derive from the current
+documents rather than editing around the old rules.
+`launch/check-prompting-targets.sh` fails when the launch config binds a model
+this guide does not list; that check is about **naming**, and a model added to
+`targets:` satisfies it forever. Whether the guidance was actually re-derived is
+not decidable and is gated nowhere.
 `launch/check-prompting-targets.sh` fails when the launch config binds a model
 this guide does not list.

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
 

package/codex/guides/tooling-gotchas.md

@@ -40,28 +40,47 @@ depends on it, pin it explicitly instead of trusting the environment.
   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).
+  resolved target (`type -a`, absolute path). A missing prefix wrapper fails
+  the same silent way — GNU `timeout` is routinely absent on BSD-derived
+  systems — so confirm the wrapper too.
 - **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.
+  default once. A forge CLI (`gh`/`glab`) reads its repository from the
+  checkout's remotes too: with a fork plus an upstream it can answer for the
+  wrong repo, so pass `--repo` wherever the answer feeds a decision.
 - **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.
+- **Producer newer than consumer**: when a deployed binary validates an
+  artifact you produce (a signed config or manifest), produce and verify it
+  with the producer tooling checked out at the exact commit that binary was
+  built from — a local verify with current-tree tooling proves only that
+  newer tooling accepts it. Confirm the consumer's build commit from image
+  provenance, not the current branch; any version mismatch is a release
+  blocker. A consumer rebuilt from the same commit needs only ordinary
+  verification.
+- **A dev-labelled datastore target is a claim**: a localhost URL or
+  exported override is no evidence of a non-production target — a local port
+  can proxy into the only real instance, and a tool's config loader can
+  re-load a dotenv over your exported value. Before the first writing
+  command (migration, seeder), print what the connection reaches from inside
+  the tool's own path and assert it is the intended target; where the loader
+  is untrustworthy, extract the DDL and apply it yourself.
 
 ## 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`).
+  a real failure upstream is masked by a successful `tail`/`grep`/`jq`,
+  reading green. Capture the tested stage's own status: run it unpiped,
+  store `$?` immediately, or use `set -o pipefail`/`PIPESTATUS` — a
+  per-command choice, since pipefail breaks early-exit consumers (`cmd |
+  head -1`, `grep -q` on a long producer → SIGPIPE 141). The
+  final-stage-assertion exemption (`cmd | grep -q pattern`) holds only
+  without pipefail; under it, capture output and check its status first.
 - **Passthrough arguments in a CLI you author**: an option meant to carry
   another command's own flags cannot use a greedy-but-dash-stopping arity —
   Python's `nargs="+"` ends at the first token starting with `-`, so the
@@ -71,6 +90,13 @@ depends on it, pin it explicitly instead of trusting the environment.
   second, separate trap: argparse consumes it as its own positional marker
   before the remainder sees it, so the form every caller reaches for first is
   the one that breaks — normalize it out of `argv` before parsing.
+- **CLI flag probes that execute**: probe a CLI only with invocations that
+  cannot do real work — a help form, or the candidate flag paired with a
+  control flag that forbids execution (dry-run, an invalid required
+  argument). Never run a subcommand bare, and assume a value after a flag
+  may be read as positional input: a boolean flag does not consume it, so it
+  falls through and runs. Tell a boolean from an unregistered flag by the
+  parser's error, not by the run succeeding.
 - **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
@@ -105,6 +131,14 @@ depends on it, pin it explicitly instead of trusting the environment.
   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.
+- **Transport limits are measured on the wire payload, in the provider's
+  unit**: take the unit and value from the provider's rejection or a live
+  probe, never from docs or a variable's name, and measure the serialized
+  payload the consumer receives — after encoding and wrappers — not the
+  object you assembled. A character count against a byte limit undercounts
+  multibyte text, hiding while inputs are ASCII; an item count bounds no
+  size. Enforce at one dispatch chokepoint, deriving every budget from that
+  constant.
 
 ## Git operations
 
@@ -131,12 +165,31 @@ depends on it, pin it explicitly instead of trusting the environment.
   restore from that. The same asymmetry makes the restore step fragile: if the
   probe can time out or abort, the restore must not be the next command in the
   same invocation — put it where a failure cannot skip it.
+- **An ignore rule can swallow a durable record**: before treating a path as
+  durable — a new ledger, a cited authority — run `git check-ignore -v
+  <path>` and `git ls-files --error-unmatch <path>`. Broad runtime-state
+  patterns (`*.jsonl`, `runs/`, `out/`) absorb a new file, and a tracked
+  file pointing at an ignored path is an authority that exists in one
+  checkout only. Fix with a negation rule proven by a sibling that stays
+  ignored; genuinely ephemeral output stays ignored.
 - **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.
+- **A split series is proven commit by commit**: order them by dependency
+  and check each out into a throwaway worktree to run the build, tests, and
+  gates before pushing. Green only at the tip hides a broken bisect point
+  and a commit that cannot be reverted alone — usually a rename or shared
+  hunk in the wrong commit. If a handoff cites the branch's hashes, merge
+  with a merge commit: squash and rebase rewrite every hash.
+- **A shared tree holds other operators' work**: a commit you did not make, a file the
+  editor reports changed on disk, a staged path you never added, one more field than
+  your predicted post-state — treat an unexplained delta as someone else's work, not
+  noise. Before a sweeping write (`git add -A`/`.`, `commit -a`, `stash`, `clean`,
+  `reset --hard`), attribute it (`git status`, reflog timestamps, other live sessions)
+  and then act only on what you can prove is yours — add by name.
 
 ## Config, secrets, and managed services
 
@@ -151,6 +204,13 @@ depends on it, pin it explicitly instead of trusting the environment.
   leaving stale, unreferenced definitions live. After updating, re-read the
   resource, check definitions and active references separately, and remove
   the orphans explicitly.
+- **Derive a new revision from the live one, not from a template**: a
+  replace-semantics update drops every field the command does not restate,
+  and wrappers commonly default mounted secrets to off. Render the exact set
+  the command will send, derived from the live resource, and diff it field
+  by field; a field that disappears, or an operational value that moves
+  backward, is a blocker to explain, not a default to accept. Re-read the
+  resource afterwards, since a command rarely labels its semantics.
 - **A new revision is not live traffic**: on a runtime that pins traffic to a
   named revision (e.g. Cloud Run with a fixed split), `gcloud run deploy` (or
   the equivalent) creates the new revision but shifts no traffic to it — the
@@ -158,23 +218,101 @@ depends on it, pin it explicitly instead of trusting the environment.
   update-traffic`. Read the "deploy succeeded" message as "a revision exists",
   not "the new code is serving"; verify the live traffic split before
   concluding the deploy took effect.
-- **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.
+- **Job logs outlive the execution**: a managed job that has run more than
+  once under one name — including one deleted and recreated with the same
+  name — returns the earlier incarnations' output when its logs are read by
+  job name. Scope every read to the execution id you received at launch and
+  confirm the timestamp window covers that run. An unscoped read merges
+  prior runs into the present and yields confident false diagnoses that a
+  scoped read reverses.
+- **Dispatch status is not execution**: a CLI `--wait` returning or timing
+  out, a scheduler reporting success, a trigger accepted without error —
+  each reports what the dispatcher saw, not whether the target ran or what
+  state it reached. Before retrying or declaring done, re-derive the state
+  from the target's own record (its execution describe, the handler's logs),
+  matched to the run by id, and keep a manual probe distinguishable from the
+  scheduled one. A blind re-launch is a duplicate execution with side
+  effects.
+- **An apply cut off before confirmation is unconfirmed** — neither done nor
+  un-run: when a multi-statement side-effecting apply (migration, batch
+  write) loses its confirmation channel, enumerate which target objects
+  already exist in the store, and plan the rerun from that partial state; a
+  naive rerun half-fails on "already exists" and leaves a second partial
+  state. Where the runner surfaces only exit status, route the object list
+  out through a deliberate failure. A transactional or provably idempotent
+  apply needs only the confirmation.
+- **A traffic rollback is not a config rollback**: on a revision-pinned
+  runtime, sending traffic back to the previous revision restores behavior
+  but leaves the added env var or secret binding in the service template,
+  where the next deploy re-enables it silently. Count a rollback complete
+  only when the traffic split and the service spec are both back to the
+  prior state — re-read the spec and remove the change explicitly. Runtimes
+  that redeploy the prior spec itself (immutable-artifact, GitOps) have no
+  such gap.
+- **Perimeter controls need the enforcement point's own logs**: an
+  agent-side fetch is not an independent 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 those logs,
+  and check for a front-side cache/CDN separately. Aim the probe at an
+  in-unit sentinel the app answers without credentials: a denial the app
+  produces anyway passes with the control off, and a redirect into it is a
+  bypass.
+- **Tightening exposure is a behavior change for external clients**: switching
+  ingress mode, adding an allowlist, or requiring auth is not safe when
+  callers live outside your redeploy. Enumerate which clients reach the
+  endpoint and by which hostname, verify from a client's vantage, and
+  confirm inbound volume did not fall to zero — clients you cut off raise no
+  error on your side, so enforcement-point logs alone can sever ingestion
+  silently. Callers you redeploy in the same change need only the ordinary
+  deploy check.
 - **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.
+- **A remote handle is valid only when it was read**: a row index in a sheet
+  that auto-sorts, a downloaded copy of a hosted file — each moves between
+  your read and your write. Before writing, re-establish the target from the
+  live source: re-locate the row by its key column, not a remembered
+  position, and assert the key matches after the write; compare the remote's
+  version against the copy you edited, re-downloading and reapplying on a
+  move. Local single-writer files need none of this.
+- **Packaging and ignore rules are judged against paths and environments, not your tree**: before
+  a release, pack the real tarball, install it clean with lifecycle scripts
+  ON, and smoke it — a postinstall hook fine in the repo can delete the
+  shipped runtime where the build toolchain is absent. After moving or
+  renaming a directory, every ignore rule is void for the new paths:
+  re-check there and read the staged diff's file count, since old-path
+  patterns stop matching and excluded data enters the stage.
 - **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.
+- **Uniform failure is structural — read the persisted reason, then check the built artifact**: when
+  every item in a batch fails and the per-item error is persisted outside
+  the log (a status column, a result record), read it before blaming keys,
+  quota, or model availability. And when code reads sibling files from its
+  working directory, prove they exist inside the built image by listing or
+  hashing them there: a selective copy passes every repo-side check and
+  fails only at runtime.
 - **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.
+- **Build-context ignore patterns anchor at the root**: in a `.dockerignore`
+  or any root-anchored filter, a bare filename matches only at the context
+  root and never in a subdirectory, and an extension glob misses the
+  same-purpose credential file carrying another extension. Never conclude a
+  shipped image is secret-free from the patterns — list the built artifact's
+  own filesystem for credential-shaped files (env files, keys,
+  service-account JSON) as a named negative control, repeated whenever the
+  build context or ignore file changes.
+- **A revoke is grant-wide, not token-wide**: revoking anything issued under
+  a client id the user's live sessions share invalidates those sessions too,
+  and the failure surfaces later, elsewhere, with no re-auth prompt. A probe
+  may clean up only what it alone owns — use minimum scopes and a dedicated
+  client id, and let a probe token expire rather than revoking it. Where a
+  revoke on a shared grant is unavoidable, state the blast radius and time
+  it with the user.
 
 ## Own what you spawn
 
@@ -186,3 +324,32 @@ Instance of the global rule: own the full lifecycle of what you create.
   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.
+- **A handle issued to a human is a commitment**: once a consent URL is
+  handed over, the listener behind it must not be restarted, re-ported, or
+  replaced while the person may still act — keep it alive until the callback
+  lands, or say plainly that the link is dead. The handler captures the
+  credential write-once and ignores later hits, since a browser's favicon
+  request clears a naive one. Before asking a human to click again, drive
+  the handler with a simulated callback.
+- **A stop is confirmed at the sink, not in the process list**: a kill that
+  misses one descendant lets that stage finish and publish, and the process
+  list looks clean either way. After stopping a multi-stage run, list the
+  output sink for anything written after the stop instant and roll it back
+  as contaminated. Read the rollback path's retention — noncurrent-version
+  expiry is a recovery window, not a backup — and snapshot before a risky
+  run, choosing the restore point by timestamp.
+- **Detach what must outlive the call**: a process started inside a harness
+  tool call belongs to that call's process group: a trailing `&` is reaped
+  when the call returns, and the harness may signal the group when another
+  background task finishes. Launch anything meant to outlive one call
+  through the harness's background facility or fully detached
+  (nohup/setsid), writing progress to durable files a resume can read. A
+  zero-byte output file means it never survived. Detached still means owned
+  — PID file and stop path.
+- **Name-substring lookup is not a liveness check**: `pgrep -f <name>` and
+  `ps | grep <name>` match the argv of the shell running the query itself,
+  and match unrelated processes carrying the same name — another session, a
+  sibling dispatch, the launcher's own plan text. To decide whether a
+  dispatched job is alive, use the PID or handle captured at launch, its
+  process-group state, or growth of its own output artifact. Substring
+  lookup is for discovery only, confirmed against one of those first.