agent-bios 0.19.2 → 0.19.3

package/DEPENDENCIES.md

@@ -113,7 +113,7 @@ execution evidence have narrower scope:
   by the current `--version` reports. Authenticated instructions-agent execution and post-fix
   authenticated resume remain unverified.
 
-## Codex app and instruction import
+## Codex app
 
 The Codex desktop app is a separate host from the Codex CLI. Its optional bridge needs
 native skill discovery for `~/.agents/skills/agent-bios`, the explicit-invocation policy in
@@ -146,6 +146,30 @@ requires explicit selection, enables no native hooks or agents, and Off cannot r
 previously returned text. Registration is off by default and owns only its discovery
 link, preserving global instruction files and foreign entries.
 
+## Claude Desktop
+
+Claude Desktop has no launch to project into and no skill root an installer can reach,
+so it pulls through a local MCP server. `agent-bios app desktop` writes a `.mcpb` bundle
+under the private state root; the user installs it through Desktop's own dialog, and
+agent-bios writes nothing into Desktop's directories or `claude_desktop_config.json`.
+The bundle's server (`compose/app_desktop/server.py`) is standard-library Python speaking
+MCP 2025-11-25 over stdio, with no network service. Desktop resolves a bare `python3`
+through the user's login-shell `PATH` and ships no Python of its own, so the manifest names
+the absolute interpreter that generated it; that interpreter must stay installed, and the
+bundle is regenerated after it changes. The server resolves the confirmed private release
+on every call.
+
+Desktop sends no conversation identity with a tool call, so `app session --host
+claude-desktop` mints one on preview or use. Measured on Desktop 2.16120.0 (macOS,
+2026-09-30): the bundle route, protocol 2025-11-25, a 140,666-byte result delivered
+inline, and delivery with end-marker confirmation in both chat and the Code tab. The Code
+tab runs Claude Code on the user's own `~/.claude`, but its extension server still starts
+outside the session's working directory, so project scope stays excluded there too.
+Windows and `roots/list` are unverified. Local tests do not establish that a given Desktop
+version loads the bundle.
+
+## Instruction import
+
 Local instruction import also needs no model SDK or parser framework. Standard-library
 code discovers fixed instruction filenames at known global and explicit project roots,
 captures redacted evidence through `learn/redact.py`, and validates source digests,
@@ -189,9 +213,12 @@ Agent-bios does not install credentials or infer a model account from dependency
   `codex-helm.sh` and `claude-run.sh` from the selected package. Their command paths,
   binding, reach and fallback are declared in the launch contract. An unavailable or
   unauthenticated opposite-family route is reported, not credited as a completed review.
-- **MCP servers** — user-specific; only a selected capability declaring `mcp-stdio-v1`
-  is registered by the launcher. No shipped review method requires MCP. App instructions
-  context delivery does not add an MCP server.
+<!-- mcp-inventory:start -->
+<!-- facts: {"bundlers": {"compose/app_desktop/server.py": ["compose/instructions_app.py"]}, "capabilities": [], "servers": ["compose/app_desktop/server.py"]} -->
+- **MCP servers** — derived from source by `gates/check-mcp-inventory.py`.
+  Shipped servers: `compose/app_desktop/server.py` (bundled by `compose/instructions_app.py`).
+  Launch capabilities offering `mcp-stdio-v1`: none, so no shipped review method requires MCP; the launcher registers a user-specific server only through a selected capability that declares it.
+<!-- mcp-inventory:end -->
 - **spreadsheet-processing** — an optional skill referenced by the spreadsheet rule
   when those instructions are selected. If unavailable, its inline plain-tools/code and real
   spreadsheet-engine validation fallback applies.
@@ -220,6 +247,7 @@ Inspect the installed private state using this checkout's runtime:
 bash install.sh verify
 bash install.sh instructions status --json
 bash install.sh app status --json
+bash install.sh app desktop --dry-run --json
 ```
 
 Provision packages only when explicitly requested for learning validation, compatibility

package/README.md

@@ -5,7 +5,7 @@
 Build an instruction library you can inspect, edit, and reuse. Choose what each
 CLI session or Codex app task uses, while preserving your existing global instruction files.
 
-[0.19.2 release notes](docs/releases/0.19.2.md)
+[0.19.3 release notes](docs/releases/0.19.3.md)
 
 ## Purpose
 
@@ -16,6 +16,10 @@ their roles within the standards and context of their team, industry, and organi
 
 A team is the basic unit for selecting, adopting, and sharing a work environment.
 
+The goal is efficient work and continuity. Shared environments provide reusable
+defaults that workers can adapt to their repository and personal working needs;
+they are not a mechanism for enforcing uniform working methods.
+
 Workers should be able to select an environment appropriate to their role and
 team, collaborate from shared standards and decision context, and continue
 the work when a worker, model, session, or device changes. Shared context does
@@ -54,6 +58,16 @@ accepts that older command name. See [compatibility](docs/instructions-compatibi
 This is an instruction and launch layer, not a replacement for either host CLI.
 It does not train the model or guarantee that the model follows every instruction.
 
+## Windows native preview
+
+A Windows x64 installer with a bundled Python runtime is built by the Windows
+workflow. It provides `agent-bios.exe` and `agent-launch.exe` without npm or WSL.
+The same workflow also qualifies a script distribution that uses an approved or
+provisioned CPython 3.13 with signed PowerShell commands and no custom EXE.
+Each Windows script release page carries the one-line PowerShell command for
+that release, and the fixed address below serves an explicitly promoted one.
+See [Windows installation and validation limits](docs/windows.md).
+
 ## Quick start
 
 Use the terminal installer or set up through a Codex app conversation. Both offer
@@ -62,11 +76,26 @@ See [setup and prerequisites](docs/setup.md).
 
 ### In a terminal
 
-You need **macOS or Linux**, **Bash**, **Python 3.11+**, and **Node.js 18+ with npm**
-for package installation. Run:
+One line per platform. Each downloads from the project's installation page, which
+serves an explicitly promoted release rather than a moving latest.
+
+On **Windows** — from PowerShell, the Command Prompt or the Run box. The current
+release is an unsigned preview, which is what the trailing flag accepts:
+
+```text
+powershell -NoProfile -ExecutionPolicy Bypass -Command "iwr 'https://kangminlee-maker.github.io/agent-bios/install.ps1' -UseBasicParsing -OutFile (Join-Path ([IO.Path]::GetTempPath()) 'agent-bios-install.ps1') -ErrorAction Stop; & (Join-Path ([IO.Path]::GetTempPath()) 'agent-bios-install.ps1') -AcceptUnsignedPreview"
+```
+
+On **macOS or Linux**, where **Python 3.11+** and **Node.js 18+ with npm** must
+already be present:
+
+```text
+curl -fsSL https://kangminlee-maker.github.io/agent-bios/install.sh | bash
+```
+
+Then deploy the work environment:
 
 ```bash
-npm install -g agent-bios@0.19.0
 agent-bios install
 ```
 
@@ -83,6 +112,12 @@ your project:
 
 Use `codex` instead of `claude` for a Codex CLI session.
 
+The full path is deliberate: `agent-bios install` deploys the launcher to
+`~/.local/bin`, which your shell may not search. Add that directory to `PATH` to
+type `agent-launch` directly, and run `agent-bios shell restore` to make a bare
+`claude` or `codex` open the launcher (`agent-bios shell remove` undoes it).
+Installation reports both when they are not in place.
+
 1. Choose a Builder preset or **Custom**.
 2. Review the model, review setup, and permissions. **Some presets request
    permission bypass**; select settings appropriate for your project.
@@ -132,6 +167,21 @@ To add instructions to a task, explicitly ask it to use your chosen instructions
 Installation and opening Instructions Studio do not activate task context.
 [App use, off, and personal instruction import →](docs/setup.md#use-instructions-in-a-codex-app-task)
 
+### In Claude Desktop
+
+Claude Desktop opens conversations without a launcher, so agent-bios reaches it as a
+local extension you install once. After installing agent-bios on the same Mac, run:
+
+```bash
+agent-bios app desktop
+```
+
+Open the `.mcpb` file it reports with Claude Desktop and confirm the installation.
+In a conversation, ask for your agent-bios instructions: the extension returns your
+saved selection as context for that conversation only. Nothing is added until you ask,
+and a conversation already in progress receives nothing on its own.
+[Desktop use, confirmation and limits →](docs/setup.md#use-instructions-in-claude-desktop)
+
 ## Your instruction library
 
 Open **Instructions Studio** in the launcher, or run `agent-bios instructions`.

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

@@ -67,7 +67,7 @@ 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. An idle signal is liveness decoupled from the report: a subagent can go idle without ever delivering its result, so idle-without-report is not done — request the report explicitly rather than waiting. 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.
+- Idle/progress notifications are hypotheses; verify repo artifacts before re-dispatch. An idle signal is liveness decoupled from the report: a subagent can go idle without ever delivering its result, so idle-without-report is not done — request the report explicitly rather than waiting. A delivered report can also arrive cut off with no marker — mid-table or mid-finding — and asking for it again inline truncates the same way. When a report is longer than a short summary or must outlive the turn, name an output file in the brief: the worker writes the full report there and returns the path and a one-line summary. Treat a report that ends mid-item as incomplete and switch to the file rather than re-requesting inline. 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.
 - Codex `spawn_agent` decides how much of the parent crosses: `fork_turns` defaults to `all`, and takes `none` or a turn count. A `SubagentStart` hook there receives `agent_type` and may return `continue: false`, so a tier rule can be enforced rather than stated.
 - No per-spawn instructions suppression exists on either host: the subagent definition carries model and effort, not scope. Excluding the standing instructions is a process-level act — `claude --setting-sources ''`, or `CODEX_HOME` pointed at a directory holding only `auth.json` — and it removes the tier definitions with them, so a reader without those instructions and a pinned tier cannot come from one process. An emptied `CODEX_HOME` without `auth.json` fails 401; skills still load.

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

@@ -25,6 +25,11 @@ change introduced. The stages below are for work that outgrows that sentence.
 
 When the user asks to "설계" or design, stay in design mode. Focus on high-level design and implementation-process design, then present the plan, tradeoffs, review gates, and implementation trigger. Move to implementation after the user asks to implement or approves the plan.
 
+For operational user-interface flows, information layout, visual hierarchy or
+interaction design, use `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/ui-design.md`.
+Keep bounded corrections on the lightweight path; this pointer does not require
+a full UI redesign.
+
 ## When To Use
 
 - Use this workflow for architecture changes, new features, cross-module behavior changes, ontology changes, review-driven fixes, or work that affects user-visible behavior, authority, lifecycle, validation, failure handling, or roadmap commitments.
@@ -88,6 +93,18 @@ blast radius. Re-mapping a level obliges enumerating every reader of that field,
 commonly gates shipping, repair, retry, and display at once. A deferred defect is pinned as a
 strict expected failure, never a silent pass.
 
+**Choose the failure posture by what the next step reads.** Across these instructions, an
+unqualified instruction to fail loud or fail clearly means surface the problem and reject the bad
+local result; it does not by itself decide whether a whole production run stops. In development,
+tests, and gates, stop and name the problem, because a silent pass hides a defect. On a production
+runtime path, warn loudly and halt only when continuing would contaminate what the next step
+reads: an input is stale or marked not reusable (partial, failed, blocked); a contract-failing
+value is about to be recorded as valid; or an external write has an unknown outcome. Otherwise —
+an isolated item failure, a tripped breaker, an exhausted budget — warn and continue: work already
+done stays valid, work not done is recorded as not done, and the next run picks it up. This
+default assumes recoverable state kept in artifacts rather than only in the running process. The
+system's owner can redefine it. In no stage does a problem pass silently.
+
 ## 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).

package/claude/guides/llm-capability-boundary.md

@@ -110,7 +110,13 @@ Important levers:
   grounding checks, provenance checks, citation checks, static checks, E2E
   checks, and semantic quality gates.
 - Retry/fail policy: retry transient generation failures; fail clearly when the
-  available route cannot enforce the required contract.
+  available route cannot enforce the required contract. A contract-failing item
+  is rejected loudly and never recorded as a valid result; record its failed or
+  not-done status in artifact state. On a production path the whole run halts
+  only when continuing would contaminate what the next step reads — a stale or
+  not-reusable input, a contract-failing value about to be recorded as valid,
+  or an external write with an unknown outcome; otherwise it warns loudly and
+  continues, and the next run picks up the work not done.
 - Observability: prompt packet snapshot, model/provider version, schema hash,
   source snapshot, validator decision, retry reason, and artifact lineage.
 

package/claude/guides/tooling-gotchas.md

@@ -256,7 +256,26 @@ depends on it, pin it explicitly instead of trusting the environment.
   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.
+  bypass. The address an IP-based rule compares is the one selected at its
+  enforcement point, and configuration alone may not establish which: behind
+  a proxy or CDN it can be the client address the configured forwarded-header
+  trust chain hands the app, and a managed platform can route particular
+  destinations outside an otherwise configured NAT path — on GCP, Google API
+  traffic did not use the Cloud NAT address despite
+  `privateIpGoogleAccess: false`. Before writing or editing an allowlist or
+  perimeter rule, observe the address for the real workload and destination
+  at the enforcement point, with a control path that should show a different
+  one.
+- **Locating a credential must not print it**: a command meant only to find
+  where a secret lives, or to check that it is set, exposes the value if it
+  emits it into the transcript — `cat` of an env file, `printenv`,
+  `echo $TOKEN`, a keychain read with `-w`, or a grep whose match is the
+  secret line. Check existence, length, or shape without emitting any secret
+  characters (`[ -n "${X:-}" ]`, `wc -c < file`, a key-name-only listing, a
+  nonprinting format check), and let the consumer read the value directly
+  from the environment or credential store only when it needs it. Do not
+  print even a partial prefix. A value that reached the transcript is
+  exposed: rotate it.
 - **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

package/claude/guides/ui-design/visual-direction.md

@@ -0,0 +1,88 @@
+---
+language: en
+status: active
+---
+
+# Choosing a visual direction for an operational interface
+
+Use when a new visual direction or a material arrangement decision remains
+unresolved in the requested work. For an established direction or a bounded copy
+correction, use the existing system and verify the affected result proportionately.
+
+## Start from the task and supported system
+
+Identify the content people must read, compare, select, edit or act on. Preserve
+the working scope, authority and state distinctions that matter to that task.
+Inspect the project's existing components and tokens before introducing a new
+visual vocabulary. An external reference does not itself justify replacing the
+project's framework or component library.
+
+Consult a reference when it helps resolve the remaining visual decision; reuse
+sufficient existing evidence. Research more when the decision needs it or the
+user requests research. Prefer task-relevant product views or official pattern
+documentation. Distinguish live observations, release screenshots, historical
+images and explanatory artwork. Record the source and date, what it informs,
+and its applicability limits in the ordinary design note. Do not infer token
+values or usability from an image alone.
+
+## Choose only the patterns the task needs
+
+| Task | Useful arrangement | Meaning to preserve |
+| --- | --- | --- |
+| Reading and review | Give the artifact sufficient space; keep necessary evidence nearby when switching would obstruct comparison | The artifact, source, applicable conditions and review target |
+| Repeated record comparison | Align comparable values; distinguish whole-list, selected-set and individual-record actions | Units, comparison basis, exceptions and each action's scope |
+| Selection-driven editing | Keep relevant properties bound to the selected object | Selection, draft and resulting changes remain attached to the same target |
+| Input and result confirmation | Keep input, consequential effects and results close enough to follow | Entered, saved, approved and actually executed states stay distinct |
+
+These are conditional patterns, not a required navigation structure or panel
+count. Choose persistent supporting panels or transient overlays according to
+their role. Give prose a readable measure and comparisons sufficient width.
+Adapt the arrangement to the supported viewport while preserving the current
+selection, return context, reading order and keyboard focus order. Compact
+navigation when needed to keep the main task reachable on a narrow screen.
+
+## Define roles before values
+
+Explain the proposed reading order, emphasis, density and grouping briefly.
+Map foregrounds, surfaces, action states, spacing relationships and any required
+depth to the existing semantic tokens. Keep focus, selection, feedback and
+disabled states distinct even when values initially coincide. Add a pattern
+token only when it represents an independent decision. The role of a token
+must survive theme changes; check its actual foreground/background pairing.
+
+For information-dense operational work, start with typography, alignment and
+spacing to organize content; add containers, color or elevation when they
+communicate a needed relationship or interaction. Large introductory areas,
+repeated summary cards, badges and icon backgrounds need a task or brand purpose.
+Ordinary content need not look raised. Use depth when it clarifies a floating,
+movable or otherwise distinct object. Preserve useful brand and user preferences.
+
+Do not impose a reference palette, fixed pixel scale, permanently dim navigation,
+universal card ban or identical layout across tasks. When no system exists, mark
+initial values as project proposals. Define consistent text roles and spacing
+within and between groups, then check the resulting density. Resolve crowded
+content through grouping, widths and wrapping before shrinking text. Keep words
+and meaningful phrases together where the language permits, with a fallback for
+unbroken strings. Check representative Korean text when the product uses Korean.
+
+## Compare only enough to resolve the decision
+
+Use representative content, long labels, important exceptions and relevant
+states at the target sizes. Keep task, content and capability constant while
+comparing visual alternatives; use a credible baseline. Distinguish token
+changes from changes to regions, information order and grouping. Typography
+and spacing can still alter wrapping and geometry. Where narrow layouts
+converge, do not claim a difference the user cannot see.
+
+Inspect the actual rendered result when appearance is being judged. Check
+contrast, clipping, wrapping, state distinctions, action targets and focus
+visibility under the applicable accessibility requirements. Verify that
+rearrangement preserves semantic reading and keyboard order. For interactive
+changes, exercise selection, draft retention and the relevant failure/recovery
+paths; styling does not establish permission or execution.
+
+Record visual preference separately from observed task performance. Rendered
+samples support visual inspection; interaction and user-performance claims need
+their own evidence. Preserve the result and remaining uncertainty in ordinary
+team artifacts. No prescribed number of variants or new research report is
+needed for every task.

package/claude/guides/ui-design.md

@@ -0,0 +1,90 @@
+---
+guide_id: ui-design
+language: en
+status: active
+description: For designing, reviewing, or changing task flows, information layout, visual hierarchy, or interaction in operational user interfaces; keep bounded corrections proportionate.
+use_when:
+  - designing or reviewing a work application, operations tool, or interactive work surface
+  - changing information arrangement, visual hierarchy, design tokens, or interaction states
+  - preserving scope, evidence, authority, and continuity through a user interface
+---
+
+# Operational interface design and delivery
+
+Use for interfaces where people inspect evidence, compose work, make decisions
+or act on records. Match the deliverable to the user's requested stage and scope.
+A clear text correction needs that correction and a proportionate check.
+
+1. **Establish what the sources mean now.** Separate implemented behavior,
+   accepted requirements, proposed design choices and illustrative states.
+   Reconcile amendments and decisions before reusing an older screen. A newer
+   date alone does not establish authority. Keep material contradictions and
+   unknowns visible instead of silently choosing a convenient interpretation.
+
+2. **Preserve requested coverage; bound the work at the right level.** Identify
+   the operator, outcome and evidence that would complete this deliverable.
+   Distinguish people consuming work context from those authoring or managing
+   it; do not invent their visit frequency or force a common starting screen.
+   For a complete design request, cover the required operations even when their
+   backend is not built; specify their subjects, inputs, effects, dependencies
+   and recovery rather than claiming implementation. For a bounded change,
+   complete the requested path before expanding neighboring features. Include
+   adjacent repairs when that path depends on them or this change causes a
+   regression, and state why. An unavailable implementation does not erase a
+   requested design contract.
+
+3. **Organize around a meaningful next decision.** Show the working scope,
+   evidence to compare, current state, available action and resulting next step
+   together. Internal modules or protocol phases are not automatically menus
+   or buttons. Combine preparation steps behind one authorized intent when no
+   user choice is needed, while keeping distinct outcomes understandable. Use
+   the team's visual language to assign emphasis according to the task, and
+   make typography, spacing, color and boundaries express meaningful
+   relationships. Test whether actual task content is prominent at the target
+   size; decorative summaries must earn their space. When layout uncertainty
+   matters, compare arrangements at the lowest useful fidelity, explaining the
+   task tradeoff and what evidence would change the choice.
+
+   When a new visual direction or a material arrangement decision remains
+   unresolved, use
+   `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/ui-design/visual-direction.md`.
+   An established direction or a bounded correction does not require new
+   reference research or multiple designs.
+
+4. **Keep qualifications with the thing they qualify.** Preserve applicable
+   conditions, exceptions, units, source/version, time meaning and affected
+   scope through summaries, edits, comparisons and exports. Keep independent
+   dimensions separate. Missing evidence is not an empty result or a zero, and
+   an index or relationship view is not proof of its underlying body or meaning.
+   Expand technical detail when useful without hiding a consequential limit.
+
+5. **Make each action's authority and effect precise.** Name the exact target,
+   base and changed content when reviewing a change. Recheck a changed base or
+   permission instead of carrying approval onto different input. Distinguish
+   selection, saved draft, approval, execution and recipient use as applicable;
+   one positive state does not prove the next. Preserve request identity when
+   an outcome is uncertain and reconcile its actual result before retrying.
+   UI controls reflect the existing authoritative policy; they do not create it.
+   If policy is unsettled, label proposed choices and the responsible decision
+   owner rather than implying permission or omitting the required design.
+
+6. **Carry the same work across views and people.** Preserve the draft, target,
+   review/request identity and return context when moving between surfaces.
+   Equivalent outcomes need suitable representations, not identical layouts or
+   duplicated business rules. Provide keyboard and structured alternatives for
+   necessary spatial interactions. Verify evidence for the actual recipient;
+   another worker's receipt does not establish their access or delivery.
+
+7. **Verify this deliverable, then finish it.** Walk a design's concrete scenario
+   and relevant exceptions against its sources; inspect its proposed composition.
+   For working changes, exercise the changed runtime path, relevant failures,
+   keyboard and recovery. When a visual change is material, inspect the affected
+   composition with representative content and relevant states at the target
+   size, distinguishing token changes from changes to information arrangement.
+   Check that visual, reading and focus order remain coherent across layouts.
+   Report visual preference separately from observed task performance. Keep
+   simulation, observed runtime and user evidence distinct. Once the required
+   checks are complete, leave the result, material decisions, source bindings
+   and remaining work in ordinary team artifacts. Keep private facts within
+   their permitted boundary. Choose dependencies only when a requirement
+   demands a decision, using the supported environment first.

package/claude/guides/verification-discipline.md

@@ -77,6 +77,7 @@ cheapest one to write.
 - A/B or on/off measurements: before accepting a null result, verify the arms actually received different treatment in the mechanism under test — a shared default or unconditional upstream step can silently apply the treatment to both arms.
 - Multi-stage pipelines with nondeterministic stages: a final-output diff cannot attribute an effect or a regression to a stage — it conflates the change with run-to-run variance. Persist every stage's output, tabulate what each creates, may edit, and only guards, restrict the suspects to the stages that edit the content in question, and find the first stage where the intended effect disappears or the defect appears. Fix there, preferring a structural recheck over another prompt-level instruction that already failed.
 - Before/after comparisons: pin the input to an immutable copy — a snapshot or versioned artifact — and run both arms against it, because a live artifact (a growing log, a regenerated upstream stage) drifts between runs and any diff over it, a matching one included, is evidence of nothing; when the arms are metered, restore the baseline's exact upstream inputs and re-run only the changed stage. This is input identity, not the separate unit-and-denominator basis rule.
+- Cost figures from provider usage records: before pricing, map every provider's token fields onto one schema — uncached input, cache read, cache write, output. Some providers report input as a total that already includes cached tokens: treating that total as uncached input and then adding the cache-read field again counts the cached portion twice, while charging the inclusive total once at the full rate misprices that portion instead. Other providers exclude cached tokens from the input field. When a provider reports or prices cache writes separately, keep them in their own field. Confirm each provider's field meaning against its own usage documentation or a known sample, never by analogy with another provider, and derive the cache hit rate from the normalized fields.
 - Model-behavior guardrails: verify by changed behavior, not recitation — a staged battery from named-trigger cases through disguised, deconfounded, category-wide, and single-variable framings; a clean pass means "no known defect", so re-run the battery when the model changes.
 - Branch/version test builds against real data: explicitly separate every state sink the app touches (files, DB, OS-level stores that ignore env overrides), confirm the launch path propagates the isolation to child processes, and back up live data before the first run — a mismatched schema that drops unknown fields on write is data loss, not a no-op.
 - Sandbox, replay, or re-adjudication runs on production-derived config: enumerate every outbound channel the stage can reach — publish, upload, notify, external write — and disable or redirect each one before the run, proving each disarm fires as you would prove a path guard; a guard on the input or target path alone leaves egress armed. Fingerprint every external destination before the run and diff it after, so an escaped write is caught by the run rather than by a recipient.
@@ -151,6 +152,11 @@ produce a green with no evidence behind it:
 - **The suspiciously fast or empty run.** When a check goes green unexpectedly quickly, or reports
   nothing at all, dump what it actually ran over before believing it. A harness that crashed early
   and one that found nothing produce the same exit code.
+- **The verdict that ran before its checks.** If a runner computes or prints its overall verdict
+  before all checks finish, later failures cannot change it. Accumulate one failure count across
+  every check, then compute the verdict and exit status once, after the last check. Read a
+  multi-check run from that final count and an exit status verified to derive from it — never from
+  `tail` or collapsed last lines, which hide failures printed earlier.
 - **The control that failed by crashing.** A negative control is evidence only when it fails
   through the assertion it names: a traceback and a caught violation share an exit code, and an
   early crash can pre-empt every control after it. Treat each traceback in a control run as a
@@ -173,7 +179,10 @@ produce a green with no evidence behind it:
 - **The mutant that never ran.** A mutation verdict counts only if the mutant is valid: it
   compiled, sits on a path the exercised test traverses, and changes the guarded behavior, not
   healed downstream or coinciding with a default. The runner must report build failure,
-  unreachable, and equivalent distinctly from KILLED and SURVIVED, and halt on a moved anchor.
+  unreachable, equivalent, and timed out distinctly from KILLED and SURVIVED, and halt on a moved
+  anchor. A timeout is not a kill: it moves with machine load, so set the limit well above the
+  unmutated suite's runtime and accept a verdict only when repeated runs agree on which mutants
+  timed out.
   More tests red than the mutation should touch indicts it; classify a survivor (rebuild,
   discard, genuine gap) before writing a test. **Equivalent is a verdict about the probe as
   much as the mutant**: a probe that is dead or returns a constant reports every mutant as

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

@@ -18,7 +18,29 @@ GUIDE = "guides/tooling-gotchas.md"
 # Both hosts receive the same command payload and additionalContext response.
 # The guide remains available when native hooks are disabled, untrusted, or do
 # not cover a tool path. --self-test checks every anchor against both guide trees.
+_SECRET_FILE = (r"(?:\.env(?:\.\w+)?|\.netrc|\.pgpass|\.npmrc|\.pypirc|credentials(?:\.json)?"
+                r"|auth\.json|secrets?\.(?:ya?ml|json|toml))\b")
 RULES = [
+    # First because it is the one reminder whose miss is not re-work but exposure. Each
+    # branch is a command whose ordinary output IS the value: a keychain read with -w/-g,
+    # printenv or a bare env, a token-printing CLI, an echo of a credential-named variable
+    # (`\w*TOKEN\b` leaves $MAX_TOKENS alone), and a display or match over a secret-bearing
+    # file. A grep with -l/-L/-c/-q prints names, counts or nothing, so it stays quiet.
+    ("credential-print",
+     re.compile(r"(?i)\bsecurity\s+find-(?:generic|internet)-password\b[^|;&]*\s-[a-z]*[wg]\b"
+                r"|\bprintenv\b(?!\s+(?:PATH|HOME|SHELL|USER|PWD|LANG|TERM|TMPDIR)\b)"
+                r"|(?:^|[|;&]\s*)env\s*(?:$|[|;&])"
+                r"|\bgcloud\s+auth\s+(?:application-default\s+)?print-(?:access|identity)-token\b"
+                r"|\bgh\s+auth\s+token\b"
+                r"|\bkubectl\s+get\s+secrets?\b[^|;&]*-o\s*=?\s*(?:ya?ml|json|jsonpath)"
+                r"|\b(?:echo|printf)\b[^|;&]*\$\{?\w*(?:TOKEN|SECRET|PASSWORD|PASSWD|API_?KEY"
+                r"|PRIVATE_?KEY|ACCESS_?KEY|CREDENTIALS?)\b"
+                r"|\b(?:cat|head|tail|less|more|bat)\b[^|;&]*" + _SECRET_FILE +
+                r"|\b(?:grep|rg)\b(?![^|;&]*\s-[a-zA-Z]*[lLcq])[^|;&]*" + _SECRET_FILE),
+     "Checking where a credential lives or that it is set must not print it — test "
+     "existence, length, or shape without emitting secret characters; a value that "
+     f"reached the transcript is exposed, rotate it ({GUIDE}).",
+     "Locating a credential must not print it"),
     ("reserved-shell-names",
      re.compile(r"\b(UID|EUID|GID|PPID)="),
      "Assigning reserved shell names (UID/EUID/GID/PPID) can invoke the bound "
@@ -280,6 +302,7 @@ def self_test() -> int:
     # matches() never reaches the caller either — both leave the rule inert while this file
     # goes on reporting that all of them fire.
     FIXTURES = {
+        "credential-print":      "cat .env",
         "reserved-shell-names":  "UID=0 echo hi",
         "git-diff-two-dot":      "git diff main..HEAD",
         "git-pull-dirty":        "git pull origin main",
@@ -417,6 +440,24 @@ def self_test() -> int:
     if "grep-binary-heuristic" in [h for h, _ in matches("(grep -a needle payload)", limit=None)]:
         problems.append("grep-binary-heuristic: fired although the subshell-grouped "
                         "grep carries its own text-mode flag")
+    # Every branch of credential-print is a separate way the value reaches the transcript,
+    # so each gets its own firing case — a regex that loses one alternative still fires on
+    # `cat .env` and would pass the fixture above. The quiet cases are the look-alikes the
+    # rule must leave alone: existence and length checks, name-only and count-only greps,
+    # a variable named for LLM token counts, a keychain lookup without -w, and a printenv
+    # of a non-secret variable.
+    for cmd in ("printenv", "env | grep KEY", "echo $GITHUB_TOKEN", 'echo "${OPENAI_API_KEY}"',
+                "printf '%s' $DB_PASSWORD", "security find-generic-password -s svc -w",
+                "gcloud auth print-access-token", "gh auth token", "grep API_KEY .env",
+                "kubectl get secret db -o yaml", "head -3 credentials.json", "tail ~/.netrc"):
+        if "credential-print" not in [h for h, _ in matches(cmd, limit=None)]:
+            problems.append(f"credential-print: does not fire on a value-printing command ({cmd!r})")
+    for cmd in ('[ -n "${GH_TOKEN:-}" ]', "wc -c < .env", "grep -c API_KEY .env", "grep -l token .env",
+                "echo $MAX_TOKENS", "security find-generic-password -s svc", "gh auth status",
+                "gcloud auth list", "cat README.md", "env FOO=1 python3 x.py", "printenv PATH",
+                "grep -rn token src/"):
+        if "credential-print" in [h for h, _ in matches(cmd, limit=None)]:
+            problems.append(f"credential-print: fired on a command that prints no secret ({cmd!r})")
     for envcmd in ("LC_ALL=C grep needle payload", "cat payload | LC_ALL=C grep needle"):
         if "grep-binary-heuristic" not in [h for h, _ in matches(envcmd, limit=None)]:
             problems.append(f"grep-binary-heuristic: an env-assignment prefix hid the "

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

@@ -67,7 +67,7 @@ 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. An idle signal is liveness decoupled from the report: a subagent can go idle without ever delivering its result, so idle-without-report is not done — request the report explicitly rather than waiting. 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.
+- Idle/progress notifications are hypotheses; verify repo artifacts before re-dispatch. An idle signal is liveness decoupled from the report: a subagent can go idle without ever delivering its result, so idle-without-report is not done — request the report explicitly rather than waiting. A delivered report can also arrive cut off with no marker — mid-table or mid-finding — and asking for it again inline truncates the same way. When a report is longer than a short summary or must outlive the turn, name an output file in the brief: the worker writes the full report there and returns the path and a one-line summary. Treat a report that ends mid-item as incomplete and switch to the file rather than re-requesting inline. 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.
 - Codex `spawn_agent` decides how much of the parent crosses: `fork_turns` defaults to `all`, and takes `none` or a turn count. A `SubagentStart` hook there receives `agent_type` and may return `continue: false`, so a tier rule can be enforced rather than stated.
 - No per-spawn instructions suppression exists on either host: the subagent definition carries model and effort, not scope. Excluding the standing instructions is a process-level act — `claude --setting-sources ''`, or `CODEX_HOME` pointed at a directory holding only `auth.json` — and it removes the tier definitions with them, so a reader without those instructions and a pinned tier cannot come from one process. An emptied `CODEX_HOME` without `auth.json` fails 401; skills still load.

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

@@ -25,6 +25,11 @@ change introduced. The stages below are for work that outgrows that sentence.
 
 When the user asks to "설계" or design, stay in design mode. Focus on high-level design and implementation-process design, then present the plan, tradeoffs, review gates, and implementation trigger. Move to implementation after the user asks to implement or approves the plan.
 
+For operational user-interface flows, information layout, visual hierarchy or
+interaction design, use `${CODEX_HOME:-$HOME/.codex}/guides/ui-design.md`.
+Keep bounded corrections on the lightweight path; this pointer does not require
+a full UI redesign.
+
 ## When To Use
 
 - Use this workflow for architecture changes, new features, cross-module behavior changes, ontology changes, review-driven fixes, or work that affects user-visible behavior, authority, lifecycle, validation, failure handling, or roadmap commitments.
@@ -88,6 +93,18 @@ blast radius. Re-mapping a level obliges enumerating every reader of that field,
 commonly gates shipping, repair, retry, and display at once. A deferred defect is pinned as a
 strict expected failure, never a silent pass.
 
+**Choose the failure posture by what the next step reads.** Across these instructions, an
+unqualified instruction to fail loud or fail clearly means surface the problem and reject the bad
+local result; it does not by itself decide whether a whole production run stops. In development,
+tests, and gates, stop and name the problem, because a silent pass hides a defect. On a production
+runtime path, warn loudly and halt only when continuing would contaminate what the next step
+reads: an input is stale or marked not reusable (partial, failed, blocked); a contract-failing
+value is about to be recorded as valid; or an external write has an unknown outcome. Otherwise —
+an isolated item failure, a tripped breaker, an exhausted budget — warn and continue: work already
+done stays valid, work not done is recorded as not done, and the next run picks it up. This
+default assumes recoverable state kept in artifacts rather than only in the running process. The
+system's owner can redefine it. In no stage does a problem pass silently.
+
 ## 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).

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

@@ -110,7 +110,13 @@ Important levers:
   grounding checks, provenance checks, citation checks, static checks, E2E
   checks, and semantic quality gates.
 - Retry/fail policy: retry transient generation failures; fail clearly when the
-  available route cannot enforce the required contract.
+  available route cannot enforce the required contract. A contract-failing item
+  is rejected loudly and never recorded as a valid result; record its failed or
+  not-done status in artifact state. On a production path the whole run halts
+  only when continuing would contaminate what the next step reads — a stale or
+  not-reusable input, a contract-failing value about to be recorded as valid,
+  or an external write with an unknown outcome; otherwise it warns loudly and
+  continues, and the next run picks up the work not done.
 - Observability: prompt packet snapshot, model/provider version, schema hash,
   source snapshot, validator decision, retry reason, and artifact lineage.
 

package/codex/guides/tooling-gotchas.md

@@ -256,7 +256,26 @@ depends on it, pin it explicitly instead of trusting the environment.
   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.
+  bypass. The address an IP-based rule compares is the one selected at its
+  enforcement point, and configuration alone may not establish which: behind
+  a proxy or CDN it can be the client address the configured forwarded-header
+  trust chain hands the app, and a managed platform can route particular
+  destinations outside an otherwise configured NAT path — on GCP, Google API
+  traffic did not use the Cloud NAT address despite
+  `privateIpGoogleAccess: false`. Before writing or editing an allowlist or
+  perimeter rule, observe the address for the real workload and destination
+  at the enforcement point, with a control path that should show a different
+  one.
+- **Locating a credential must not print it**: a command meant only to find
+  where a secret lives, or to check that it is set, exposes the value if it
+  emits it into the transcript — `cat` of an env file, `printenv`,
+  `echo $TOKEN`, a keychain read with `-w`, or a grep whose match is the
+  secret line. Check existence, length, or shape without emitting any secret
+  characters (`[ -n "${X:-}" ]`, `wc -c < file`, a key-name-only listing, a
+  nonprinting format check), and let the consumer read the value directly
+  from the environment or credential store only when it needs it. Do not
+  print even a partial prefix. A value that reached the transcript is
+  exposed: rotate it.
 - **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