agent-bios 0.9.9 → 0.11.0

package/DEPENDENCIES.md

@@ -37,10 +37,10 @@ Concrete role-slot→model bindings live only in each guide's `Environment Bindi
 
 ## Referenced / optional — not required by the core repo
 
-- **ultracode-for-codex** (0.5.0) — the `$ultracode-for-codex` Codex skill / CLI (Codex-backed, gpt). In cross-family review it is the **ultracode** route a **Claude** main dispatches (gpt review); a Codex main instead uses the **ultracode** capability, which is the `claude` backend itself run headless with the keyword `ultracode` in the prompt — that keyword is what opens the Workflow tool for the turn (`workflowKeywordTriggerEnabled`, default true, read in the installed 2.1.220 bundle). Required only when the ultracode/hybrid route is selected and the main is Claude.
-- **Cross-family review reviewers** — with `review_family=cross` (default), each main routes review to the opposite family. A Claude main dispatches gpt review via `$CODEX_HOME/bin/codex-run --profile hermetic` (and `codex-helm --mode review` for hybrid fan-out); a Codex main dispatches Claude review via the `claude` CLI (`claude -p --permission-mode plan` for native/onto, and, for the workflow-orchestration route, the same `claude` CLI headless with the keyword `ultracode` in the prompt — the keyword trigger is what the injected contract names, so this is the mechanism to follow). The reviewer command, resolved path, and opposite-family tier bindings are named in the launch contract; an absent or unauthenticated route degrades to same-family native (PROPOSED). `review_family=same` restores same-family review.
+- **Deep review** — no separate tool on either side. The Codex-seat deep reviewer (`codex-exec`) is the `codex` CLI's own non-interactive exec mode: `codex exec -s read-only -m gpt-5.6-sol -c model_reasoning_effort="ultra"`, self-contained packet on stdin (`-s read-only`, `-c model_reasoning_effort` and `-c service_tier` verified against installed codex-cli 0.146.0; `-c service_tier="fast"` is the explicit faster, shallower opt-in; `-s read-only` enforces the promised sandbox — ambient `~/.codex` config stays inherited, so the route is read-only but not hermetic). The Claude-seat deep reviewer (**ultracode**) is the `claude` backend itself run headless with the keyword `ultracode` in the prompt — that keyword is what opens the Workflow tool for the turn (`workflowKeywordTriggerEnabled`, default true, read in the installed 2.1.220 bundle). Personal or third-party reviewers register in the user-owned `review-methods.local.toml`, never in the shipped config.
+- **Cross-family review reviewers** — with `review_family=cross` (default), each main routes review to the opposite family. A Claude main dispatches gpt review via `$CODEX_HOME/bin/codex-run --profile hermetic` (and `codex-helm --mode review` for review fan-out) plus the deep `codex exec` pass above; a Codex main dispatches Claude review via the `claude` CLI (`claude -p --permission-mode plan` for native, and, for the workflow-orchestration route, the same `claude` CLI headless with the keyword `ultracode` in the prompt — the keyword trigger is what the injected contract names, so this is the mechanism to follow). The reviewer command, resolved path, and opposite-family tier bindings are named in the launch contract; an absent or unauthenticated route degrades to same-family native (PROPOSED). `review_family=same` restores same-family review.
 - **codex-plugin-cc** (1.0.6; re-evaluated 2026-07-16) — spawns `codex app-server` with inherited env and no `--ignore-user-config`/`--profile`, so every run reads the real `~/.codex` (config.toml, auth, its MCP servers); it has no per-invocation hermetic reach, which is what makes it unfit as a **review** route: the reviewer would inherit the same config and AGENTS.md as the main, undercutting the independent lens `review_family=cross` exists to provide. The model *is* selectable (`--model`/`--effort`); what is dated is the bundled `gpt-5-4-prompting` skill, so passing a current model does not resolve it. **Not adopted**; `wrappers/codex-run.sh` is preferred for controlled reach. It does not touch Claude Code's `/code-review` (no `code-review.md`; it adds namespaced `/codex:*`), so it never made that route cross-family. Capability we lack and may still want independently: its opt-in `Stop` hook review gate.
-- **MCP servers** (onto, clickhouse, node_repl, …) — environment-specific; referenced by Environment Binding (VERIFIER-A; coding-staged guide's structured multi-lens review slot), not a core dependency. For cross-family review, agent-launch mounts `onto` and instructs the main to call `onto_review` with `llmOverride={provider,model}` (from `[hosts.*].onto_review`, an onto review-role registered pair) so onto runs the opposite family; onto's own model seats are not launcher-controllable, so the family is set per call.
+- **MCP servers** (clickhouse, node_repl, …) — environment-specific; referenced by Environment Binding, not a core dependency. The launcher registers a stdio MCP server only for a user-registered capability whose offer declares the `mcp-stdio-v1` adapter; no shipped review method is MCP-backed.
 - **spreadsheet-processing** (skill) — referenced by the global spreadsheet rule; present in the author's Claude Code and Codex environments. If absent, the rule's inline fallback (plain tools/code + real Excel-engine validation) applies.
 
 ## Untracked — dependencies, but excluded by design

package/README.md

@@ -49,6 +49,7 @@ Two layers:
 | `SURFACES.md` | where knowledge and tools reach a model, and what each place admits — every entry names the code that realizes it |
 | `FINDINGS.md` | open implementation defects, live; closing one deletes its entry |
 | `design/`, `benchmarks/` | design records and the instruction-behavior benchmark |
+| `research/` | corpus research (the 12,749-file AGENTS.md/CLAUDE.md classification): reports, scripts, labeling record; bulk data stays local by `.gitignore` rule |
 | `DEPENDENCIES.md` | external tools / host CLIs / model providers + verified versions |
 
 `config.toml` and `settings.json` are machine-specific (trust lists, hook paths, secrets) and intentionally untracked.
@@ -58,12 +59,19 @@ Two layers:
 | Guide | Scope |
 | --- | --- |
 | `cli-multi-model-workflow` | multi-model CLI workflow: Default Frame, role slots/tiers, delegation mechanics, driving Codex CLI directly, cache economy, unattended-batch safety, halt/resume, handoff contract, Environment Binding |
-| `coding-staged-workflow` | staged development: design → process → implement, review loop, severity contract, verification menus, stop conditions |
+| `coding-staged-workflow` | staged development: design → process → implement, lightweight path, review loop, severity contract, stop conditions |
+| `verification-discipline` | verification depth and per-domain mix (owns the Verification Menus), case space, what a green result is worth |
+| `concept-economy` | concept-surface economy: reuse / extend / rename / split, split triggers, migration compatibility |
+| `documentation-hygiene` | where comments, history, and handoffs belong; how to phrase rules others follow |
 | `llm-capability-boundary` (+ `-patterns`, `-examples`) | LLM/tool/code authority boundary: field authority, accepted output channels, structural enforcement, worked examples |
 | `mock-realization-boundary` | mock/fixture realization vs product semantic path |
 | `svg-visualization-guide` | SVG diagram / service-blueprint spec |
 | `implementation-map` | IMPLEMENTATION_MAP.html current-state dashboard |
 
+The table names the load-bearing guides; the full inventory and its per-domain
+classification live in `compose/domains.json`, which the domains gate holds against the
+tree.
+
 ## Edit workflow
 
 1. Edit the English canonical (`claude/`), and the Korean canonical (`ko/claude/`) when the change is user-facing.
@@ -87,7 +95,7 @@ agent-bios uninstall   # remove deployed files and the zsh hook
 
 From a git clone, run `./install.sh install` directly (the same CLI). `install` respects `CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `AGENT_LAUNCH_VENV`, and `ZDOTDIR`; `--dry-run` prints actions without changing anything. Deploy to **every active environment in one sitting** — a partial deploy leaves a shared global pointing at a guide some environment lacks; globals are English only. Replaced files are backed up under `~/.local/share/agent-bios/backups/<timestamp>/`, and the installed set is recorded in a manifest that `uninstall` consumes. Those copies are **a manual escape hatch, not a restore mechanism**: nothing reads them back, so recovering from one means copying files yourself. The supported paths are the ones `agent-bios help` prints — a clone rolls corpus content back to a registered version, an npm install rolls the whole package back by version — and `uninstall` emits one archive of everything it removed. The backups exist for the case those three do not cover: the exact bytes that were on disk before a particular install. The published npm package ships only the deploy set (never `settings.json`, `config.toml`, `ko/`, or `benchmarks/`).
 
-In a TTY, zero-argument `codex` or `claude` opens the launch preflight. Every arrow-key TUI selection screen keeps the complete current setup in a fixed top panel, followed by the highlighted option's description and then the option list. Move with Up/Down, select with Enter, use Esc to return to the previous menu, and use `q` to cancel; Esc at the mode root also cancels. Each tier's model is chosen from the host's configured catalog, or via **Other** to type any model id the backend accepts; that text input preserves values that start with `q`, so Esc or Ctrl-C cancels immediately there, while submitting `q` cancels after Enter. The Textual preflight reflows to the terminal size, so there is no fixed minimum geometry. The root menu picks a mode — **Software Engineer** (repo-scoped work that defers to the project's own AGENTS.md/CLAUDE.md: **Vanilla**, the bare CLI with no launch contract, tier bindings, or applied permissions, plus **Custom**; SE-specific review defaults arrive later), **Builder** (the tier presets: Balanced, Deep review, Fast batch, Solo with delegation off, plus Custom), **Session distill** — then a preset within it. Select **Custom** (in Software Engineer or Builder) to open a persistent settings hub for the main tier, review setup, host policy, and each tier binding. Every edit returns to that hub; **Start with these settings** is the final launch confirmation, **Save these settings globally and start** additionally persists the setup as a named preset (with host-scoped tier overrides) in your user config for reuse elsewhere, and **Exit without launching** cancels the launch. The rich preflight runs from a managed virtualenv (`launch/provision-venv.sh`, at `~/.local/share/agent-launch/venv`) that the launcher re-execs into on the interactive path; when that venv is unavailable, or the call is non-interactive, or `TERM` is `dumb`/unset, the launcher falls back to numbered prompts, where `b` is the back command. Backend command names are resolved from the calling environment's `PATH`; shell functions are not re-entered. Codex child bindings are materialized as session-selected agent configs under the user cache, while Claude receives model and effort in `--agents` JSON when delegation is enabled. Review runs cross-family by default (`review_family`, default `cross`; `same` restores today's same-family projection): because the main's tiers are one model family, every dispatchable review route — native, onto, and ultracode — runs on the opposite family. The exception is `slash-review`, the host's own built-in review command (`/code-review` on Claude, with `ultra` for its deep multi-agent pass; `/review` on Codex): it needs no dependency and always resolves, but being the main's own command it cannot be dispatched cross-family, so under `cross` it runs as the same-family floor and its verdicts are labeled PROPOSED. A Claude main dispatches gpt/codex review (native via the `codex-run` reviewer wrapper resolved under `$CODEX_HOME/bin`, onto via an `llmOverride` to the configured openai seat, ultracode via the `$ultracode-for-codex` Codex skill); a Codex main dispatches Anthropic/Claude review (native via `claude -p --permission-mode plan`, onto via an `llmOverride` to the anthropic seat, ultracode via the `claude` CLI headless with the keyword `ultracode` in the prompt, which is what opens Claude Code's dynamic workflow for that turn). The concrete reviewer command, resolved absolute path, `llmOverride`, and opposite-family tier bindings are named in the injected session-start contract; cross-family reviewers are dispatched as read-only subprocesses, not CLI-native subagents, since neither CLI hosts the other family as a native subagent. When a cross-family route is unavailable at launch or unauthenticated at use time it degrades to same-family native subagent review labeled PROPOSED (family collapse) rather than blocking; a requested non-none review with no cross-family route and no same-family fallback (delegation off) stays fail-closed. Review setup means configured/requested; this launcher does not claim that review completed, and unavailable runtimes such as Ultrawork are not offered until integrated.
+In a TTY, zero-argument `codex` or `claude` opens the launch preflight. Every arrow-key TUI selection screen keeps the complete current setup in a fixed top panel, followed by the highlighted option's description and then the option list. Move with Up/Down, select with Enter, use Esc to return to the previous menu, and use `q` to cancel; Esc at the mode root also cancels. Each tier's model is chosen from the host's configured catalog, or via **Other** to type any model id the backend accepts; that text input preserves values that start with `q`, so Esc or Ctrl-C cancels immediately there, while submitting `q` cancels after Enter. The Textual preflight reflows to the terminal size, so there is no fixed minimum geometry. The root menu picks a mode — **Software Engineer** (repo-scoped work that defers to the project's own AGENTS.md/CLAUDE.md: **Vanilla**, the bare CLI with no launch contract, tier bindings, or applied permissions, plus **Custom**; SE-specific review defaults arrive later), **Builder** (the tier presets: Balanced, Deep review, Fast batch, Solo with delegation off, plus Custom), **Session distill** — then a preset within it. Select **Custom** (in Software Engineer or Builder) to open a persistent settings hub for the main tier, review setup, host policy, and each tier binding. Every edit returns to that hub; **Start with these settings** is the final launch confirmation, **Save these settings globally and start** additionally persists the setup as a named preset (with host-scoped tier overrides) in your user config for reuse elsewhere, and **Exit without launching** cancels the launch. The rich preflight runs from a managed virtualenv (`launch/provision-venv.sh`, at `~/.local/share/agent-launch/venv`) that the launcher re-execs into on the interactive path; when that venv is unavailable, or the call is non-interactive, or `TERM` is `dumb`/unset, the launcher falls back to numbered prompts, where `b` is the back command. Backend command names are resolved from the calling environment's `PATH`; shell functions are not re-entered. Codex child bindings are materialized as session-selected agent configs under the user cache, while Claude receives model and effort in `--agents` JSON when delegation is enabled. Review runs cross-family by default (`review_family`, default `cross`; `same` restores today's same-family projection): because the main's tiers are one model family, every dispatchable review route — native and the deep route — runs on the opposite family. The exception is `slash-review`, the host's own built-in review command (`/code-review` on Claude, with `ultra` for its deep multi-agent pass; `/review` on Codex): it needs no dependency and always resolves, but being the main's own command it cannot be dispatched cross-family, so under `cross` it runs as the same-family floor and its verdicts are labeled PROPOSED. A Claude main dispatches gpt/codex review (native via the `codex-run` reviewer wrapper resolved under `$CODEX_HOME/bin`, deep via plain `codex exec -m <frontier model> -c model_reasoning_effort="ultra"` with a self-contained packet on stdin — `-c service_tier="fast"` is the explicit faster, shallower opt-in); a Codex main dispatches Anthropic/Claude review (native via `claude -p --permission-mode plan`, deep via the `claude` CLI headless with the keyword `ultracode` in the prompt, which is what opens Claude Code's dynamic workflow for that turn). The concrete reviewer command, resolved absolute path, and opposite-family tier bindings are named in the injected session-start contract; cross-family reviewers are dispatched as read-only subprocesses, not CLI-native subagents, since neither CLI hosts the other family as a native subagent. When a cross-family route is unavailable at launch or unauthenticated at use time it degrades to same-family native subagent review labeled PROPOSED (family collapse) rather than blocking; a requested non-none review with no cross-family route and no same-family fallback (delegation off) stays fail-closed. Review setup means configured/requested; this launcher does not claim that review completed, and unavailable runtimes such as Ultrawork are not offered until integrated.
 
 At the shell-wrapper boundary, every argument-bearing command (`codex exec ...`, `claude -p ...`) and every non-TTY invocation skips launch-profile projection and preserves caller arguments. The Claude direct path intentionally retains its wrapper default, `--dangerously-skip-permissions`. `codex --no-tui ...` / `claude --no-tui ...` explicitly take that direct path, and `AGENT_LAUNCH_TUI=0` disables zero-argument TUI interception for a process tree.
 

package/claude/CLAUDE.md

@@ -52,57 +52,25 @@
 
 ## Concept Economy
 
-- Keep the concept graph compact by reusing existing concepts that clearly cover the behavior.
-- Treat lasting or shared names as concept candidates: features, entities, variables, types, helper modules, artifacts, config keys, CLI flags, MCP/tool fields, public response fields, artifact fields, enum values, failure kinds, retry/recovery tokens, process names, and documentation terms.
-- Before adding or changing a concept, find the nearest existing concept and choose one path explicitly: reuse, extend, rename, or split.
-- Prefer broad, stable concepts with precise properties over narrow near-duplicates.
+- When adding, changing, renaming, splitting, or exposing anything lasting or shared — a feature, entity, type, field, config key, CLI flag, enum value, failure kind, artifact, or documentation term — read and use `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/concept-economy.md` as a scoped extension of this section.
 - Before fixing a review finding or test failure, classify the fix as reducing, preserving, or increasing the active concept surface.
-- Split or promote a concept when it changes runtime behavior, ownership, lifecycle, validation, failure mode, user-visible behavior, audit/replay requirements, authority, persistence, user control, or failure handling.
-- Keep derived values as properties or projections of their source concept when tools/code can derive them from the source authority.
-- Keep internal projections and helper outputs internal unless public exposure is required for user behavior, product contract, or artifact truth.
-- Distinguish authority from visibility: public responses may expose bounded views, while the source concept or artifact remains the truth location.
-- Reuse existing enum values, failure kinds, retry/recovery tokens, and result/failure surfaces before introducing new vocabulary.
-- Use fallback paths, compatibility shims, and deprecated alias normalization when explicit migration compatibility is required.
-- Keep comments and active docs aligned with runtime behavior, failure semantics, retry policy, ownership, and authority.
-- When a split is necessary, name the parent concept, explain the reason for the split, and map aliases or variants back to the canonical concept.
-- In ontology work, check existing entities and relations first, then keep the concept graph compact.
-- In code work, follow existing naming patterns and consolidate variations introduced by the current change.
-- Let the repository's shape mirror its concept graph: keep each shared, lasting concept's canonical name traceable across the layers it appears in — path, module, type/interface, field, and public API — so the structure is navigable by name (grep-findable, path-guessable) without a translation table. This binds shared concepts only; transient locals, generic containers, and framework- or tooling-imposed layout may diverge.
 
 ## Coding Guidelines
 
 - For `.xlsx` editing, generation, reconciliation, validation, or connected spreadsheet processing, use the installed `spreadsheet-processing` skill when present — with plain tools/code as the fallback — and validate formula-dependent Excel results with the real Microsoft Excel engine.
-- For meaningful development work, read and use `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/coding-staged-workflow.md` as a scoped extension of these Coding Guidelines.
+- For development work, read and use `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/coding-staged-workflow.md` as a scoped extension of these Coding Guidelines — a change too narrow to need it is what its lightweight path decides, not a reason to skip the read.
 - For mock, fixture, fake, stub, simulated-provider, or test-realization design, read and use `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/mock-realization-boundary.md` as a scoped extension of these Coding Guidelines.
-- When the user asks to "설계" or design, read the coding-staged-workflow guide and focus on high-level design and implementation-process design; move to implementation only after the user asks to implement or approves the plan.
-- Think before coding: state key assumptions and surface ambiguity early.
-- Build the smallest viable functional path that satisfies the qualitative completion criteria. Minimum limits surface area, configuration, abstractions, optional scope, and implementation spread; it must not reduce required behavior, runtime authority, evidence quality, or verification depth.
-- Treat viability as real behavior against real inputs, real authority, and the intended runtime path. Use mocks only for tests, fixtures, or explicitly requested simulations; mock-backed paths support verification but do not count as product completion.
-- Make surgical changes. Touch only what the request requires, preserve existing style, and avoid casual adjacent refactors.
-- Clean up issues introduced by the current change. Mention unrelated dead code separately.
 - Own the full lifecycle of what you create — spawned processes and handles through teardown, artifacts out of tool-managed temp locations into a durable home — and keep differently-owned state separate: never colocate deploy-managed and user-owned data in one overwrite-managed file.
-- Define success criteria before multi-step coding work, then verify against them.
-- For bugs, prefer a reproducing test before the fix when practical.
-- Every changed line should trace back to the user's request.
-- Fix the root cause at its authority rather than the visible symptom: when downstream patches keep compensating for bad inputs, fix upstream at the source; when each fix only exposes another instance of the same defect, single-source the value and fix the whole class instead of patching instances.
 - Land risky or behavior-changing work behind a default-off path that preserves current behavior when off (proven by diff) and is enabled by an explicit opt-in, so the change stays reversible and the on/off difference is isolated. When a request would weaken a security or authority posture — removing or loosening an authentication/authorization check or access scope, or lowering a protective value such as session/token lifetime, password/crypto strength, rate limit, lockout threshold, or audit retention — treat it as a decision, not a rote edit, even when it is a one-line change and nothing in the code labels the value as security-relevant: state the consequence and at least one safer path to the real goal, and do not apply the weakening in the same turn — proceed only after the user confirms they accept the tradeoff.
 
 ## Verification Discipline
 
 - For composing a review request, packet, or reviewer role — the evidence bar, the verdict shape, and why a review returned noise, nothing, or a clean bill of health — read and use `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/review-request.md` as a scoped extension of this section.
 - After every meaningful code, ontology, config, data, spreadsheet, or documentation change, run a verification loop regardless of commit or handoff status.
-- Use static checks broadly: typecheck, lint, build, format, schema/config validation, graph validation, workbook structure checks, import boundaries, and security checks when available.
-- Add the narrowest reliable runtime or semantic test that proves the changed behavior, meaning, or contract.
-- Pick each domain's verification mix (code, ontology, config/data, spreadsheets, docs) from the Verification Menus in the coding-staged-workflow guide.
-- Let the LLM derive scenarios from the diff, user impact, concept impact, and failure modes; let tools/code execute and verify them. Where an artifact already defines the case space — a config, a schema, a route table — enumerate the cases from it rather than from judgment, and record real output as the expectation instead of typing one: a hand-listed set of cases silently stops covering as the artifact grows past it.
-- Keep E2E stable with deterministic data, resilient selectors, isolated external dependencies, and explicit waits.
+- For choosing verification depth, the per-domain mix, the case space, what makes a completion criterion falsifiable, how to keep an E2E stable, or what a green result is worth, read and use `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/verification-discipline.md` as a scoped extension of this section — its Verification Menus carry the per-domain mixes.
 - Report the checks run, results, and any unverified risk before calling the work done.
 - Trust a green check only when it traversed the actual changed code through the real dispatch and real calls (not a mock, dry-run, or bypass), and remember that "it ran" is not "quality met" — a fallback, floor, or mock run is not done; treat a zero-findings verdict as suspect until you confirm the harness ran rather than silently crashed, and make PASS mean concrete assertions on real output from the real path.
-- Make completion criteria falsifiable: prefer signals that fail when the mechanism is wrong (negative or contrast controls), and if no existing gate can judge a criterion, build the executable judge or do not claim the criterion met.
 - Before comparing two of anything (cost, performance, quality, frequency), fix a common basis — units, denominators, population, measurement surface — compare on equivalent output, and exclude or flag non-representative data (promotions, outages, smoke slices).
-- For non-trivial designs or high-risk changes, run independent adversarial review across distinct lenses, ideally on the design before implementation, and re-verify each finding against real code before acting on it. Apply the convergence heuristic by reviewer kind (detailed in the multi-model guide): same-kind convergence is high confidence but same-kind reviewers share blind spots — their shared "clean" is not verification; different-kind divergence is the expected signal — act on the union. Never accept an orchestrated workflow's self-reported all-green as sufficient; independently re-run the diff inspection and verification suite yourself.
-- Proportion verification to cost, risk, and information gain: before expensive or slow live runs, diagnose in code and replay the changed deterministic logic over persisted real artifacts, probe at N=1 with inputs precondition-checked, and reserve full design-review-plus-live verification for first-of-kind or authority-changing work; proportion assurance to the deployment context — a single-user, own-data tool does not warrant production-grade assurance; prefer delivery.
-- Trust a green / zero-findings verdict only if the check could have failed over a real, non-empty subject: assert the entity-under-test set has cardinality > 0 before any "no bad X" or "all X satisfy P" claim (an empty subject set passes vacuously and proves nothing), and for any test touching a branch you add or delete, confirm its inputs satisfy the live branch's entry guard — a copied fixture that fails the new guard silently routes into the about-to-be-deleted dead branch and stays green even after the real behavior breaks. When a check goes green unexpectedly fast or empty, dump what it actually ran over. Checker code itself must assert the expected shape and fail loud — a permissive fallback (`a || b`) inside a gate absorbs wrong assumptions and keeps passing.
 
 ## Tooling and Operational Safety
 
@@ -113,7 +81,6 @@
 - Never accept secrets through transcript- or history-logged channels.
 - When a secret must be supplied, provide a gitignored env slot, read the value only from the environment, verify its presence and format without echoing it, and advise rotating anything already pasted; assume a resource-creating call may echo the secret back in its success output — suppress or discard the response body, and treat an echoed secret as pasted (rotate).
 - Treat a coarse runtime signal — a failure label, a `ps`/process-inspection result, idle CPU with no output — as a hypothesis, and confirm the cause against the authoritative low-level evidence the mechanism emits before attributing blame or intervening: read the raw provider/skill log payload (e.g. `input_tokens:0` proves a pre-dispatch rejection that exonerates your content and your change), and confirm a config/env toggle reached a subprocess via a cheap artifact the gated branch emits rather than an unreliable `ps` env read. A multi-minute LLM or subprocess call at ~0% CPU with an output gap is the normal signature of I/O wait, not a hang — check process state and the call trace's in-flight duration before acting, so you do not abort healthy long-running work.
-- Before reasoning about what a branch contains or opening a PR, run `git fetch` and compute the range as `origin/<base>..HEAD`, never `<base>..HEAD` against the local tracking ref — on a shared repo the local base drifts behind the remote until you pull, silently inflating the diff with already-merged work; if the range is surprisingly large, suspect a stale base before suspecting the branch. Platform "mergeable" flags are computed against the base only — sibling PRs can each look clean yet conflict; before picking a merge order, diff their changed-file sets and simulate the sequence.
 
 ## Multi-Model Workflow
 
@@ -130,11 +97,7 @@
 ## Documentation Hygiene
 
 - Keep runtime code, active docs, and execution-facing docs focused on current behavior, current decisions, current contracts, current authority, and current failure handling.
-- Use comments for non-obvious current behavior, invariants, constraints, or risks that still apply.
-- Put backward-compatibility notes, deprecated behavior, migration rationale, historical alternatives, change narratives, and handoff logs in isolated documentation paths such as `docs/`, `design/`, `archive/`, or `deprecated/`.
-- Link from active docs or code to isolated notes only when the current task needs that history or the reference helps future maintainers.
-- Phrase guidelines as desired behavior and preferred patterns.
-- Prefer established docs such as `CHANGELOG.md`, `IMPLEMENTATION_MAP.html`, or handoff notes for change history and implementation context.
+- For where a comment, a compatibility note, deprecated behavior, a rejected alternative, a migration rationale, a change narrative, or a handoff log belongs — how to phrase a rule others will follow, and whether active docs should link to history — read and use `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/documentation-hygiene.md` as a scoped extension of this section.
 
 ## Visual Explanations
 

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

@@ -57,7 +57,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. 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. Cross-reset state belongs in files, not task boards or transcripts. When polling concurrent async jobs, pin the exact id/handle received at dispatch — a "latest" convenience selector can silently point at a sibling job and return plausible-but-wrong results.
 - Give reviewers/subagents a read-only diff, snapshot, or isolated worktree — not the live tree the main is editing — and forbid destructive git ops (checkout --, reset --hard, stash, clean) on any tree with uncommitted work; re-verify tree integrity before trusting results produced mid-edit.
 - Review cost scales with the diff, so layered review preserves delegation savings. Lower reviewer tier before dropping a review kind.
 
@@ -127,9 +127,9 @@ How much independence a review actually bought, as an ordinal grade per reviewer
 
 ## Dual-Provider Design Drafts
 
-- Trigger: the task is design (the staged-workflow guide's design stages) AND two or more providers are reachable at frontier tier. Reachability via an OAuth session is subscription-covered — no marginal spend, so no approval and no question: if a non-main-context OAuth frontier provider exists, proceed with the dual-provider design directly. The consent gate applies ONLY to a provider reachable solely via a metered API key: dispatching to it needs the user's explicit per-request approval of that spend (per-request, not standing — an old approval does not carry to the next design). If the only way to reach a second provider is un-approved metered API spend, stay single-provider rather than blocking the design.
+- Trigger: the task is design — high-level shape and implementation process, before any code — AND two or more providers are reachable at frontier tier. Reachability via an OAuth session is subscription-covered — no marginal spend, so no approval and no question: if a non-main-context OAuth frontier provider exists, proceed with the dual-provider design directly. The consent gate applies ONLY to a provider reachable solely via a metered API key: dispatching to it needs the user's explicit per-request approval of that spend (per-request, not standing — an old approval does not carry to the next design). If the only way to reach a second provider is un-approved metered API spend, stay single-provider rather than blocking the design.
 - Mechanics: compose ONE blind packet (evidence, constraints, rubric, neutral alternatives — the escalation-gate packet shape) and dispatch it unchanged to one frontier-tier model per provider; drafts stay independent — neither sees the other's output. Then adjudicate: compare the two dual-provider frontier design drafts against the rubric, take the winner as the skeleton, graft the loser's superior parts, and record what differed and why the synthesis chose as it did (FRONTIER disposition line).
-- Packet injection: a dispatched designer is hermetic — it reads only its packet and never loads this corpus. Inject the design principles the corpus would have supplied: concept economy (reuse/extend/rename/split, compact concept graph), the LLM/tools-code capability boundary, the staged-workflow design rules (smallest viable path, falsifiable done-when), and any domain-specific principles the design touches. A draft produced without the principles is not comparable to one produced with them.
+- Packet injection: a dispatched designer is hermetic — it reads only its packet and never loads this corpus. Inject the design principles the corpus would have supplied: concept economy (reuse/extend/rename/split, compact concept graph), the LLM/tools-code capability boundary, the staged design rules (smallest viable path, falsifiable done-when), and any domain-specific principles the design touches. A draft produced without the principles is not comparable to one produced with them.
 
 ## Unattended Batch Safety
 
@@ -173,7 +173,7 @@ Write for the next agent and re-verification, not narrative. Required content:
 
 This is the human-readable projection of concrete models/tools; `launch/agent-launch.toml` is the machine launch authority and parity checks keep them aligned. Re-probe when the binding is older than ~8 weeks or a newer observable model/tool changes the surface. `agent-bios install` overwrites deployed bindings, so edit the repo copy.
 
-Binding (2026-07-25):
+Binding (2026-08-10):
 
 | Slot | Binding | Notes |
 |---|---|---|
@@ -181,13 +181,13 @@ Binding (2026-07-25):
 | HELM | Claude Opus 5 (xhigh) · GPT-5.6 Sol (xhigh main; main Ultra requires explicit selection; bounded FRONTIER Ultra allowed) | standing main; Codex defaults bypass, explicit sandbox narrows |
 | WORKHORSE | Claude Opus 5 (medium) · GPT-5.6 Terra (high) | implementation and per-item judgment |
 | SWEEP | Claude Haiku 4.5 · GPT-5.6 Luna (low) | clear repeatable scans and mechanical work |
-| VERIFIER-A | onto-mcp review | logic/authority kind; tier units per funnel |
-| VERIFIER-B | `ultracode-for-codex` CLI v0.4.5 (Codex-backed; callable from Claude or Codex) | code/execution kind |
+| VERIFIER-A | plain `codex exec` deep pass — GPT-5.6 Sol at ultra effort, packet on stdin (`-c service_tier="fast"` as explicit fast opt-in) | strongest single reader; cross-family from a Claude main |
+| VERIFIER-B | Claude Code ultracode workflow (keyword-opened, many-agent) | code/execution kind; fan-out counterpart |
 | INDEPENDENT-PR-REVIEWER | Codex CLI | adversarial `gh pr diff` review |
 | Claude relocation | EnterWorktree, `/cd`, `--worktree`; resume is directory-scoped | verified 2.1.207 |
 | Codex relocation | `codex resume` (cwd-filtered; `--all` lifts), fork | verified 0.144.1 |
 | Claude teammate | named mailbox continuation; completed-agent message may cold-rerun on main model | keep resident; avoid completed resume |
-| Rate-limit fallback | OpenAI limited → VERIFIER-A on Anthropic; Claude limited → VERIFIER-B on Codex | record family collapse |
+| Rate-limit fallback | OpenAI limited → VERIFIER-B (Anthropic workflow); Claude limited → VERIFIER-A (Codex exec) | record family collapse |
 
 Codex direct-drive (verified 0.144.1, 2026-07-12):
 

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

@@ -7,7 +7,7 @@ use_when:
   - architecture changes, new features, cross-module or ontology changes, review-driven fixes
   - the user asks to design ("설계") before implementation
   - judging materiality of review findings and deciding when to stop or redesign
-  - choosing the per-domain verification mix (code, ontology, config/data, spreadsheets, docs)
+  - deciding where a stage's verification points and review gates belong in the work plan
 ---
 
 # Coding Guidelines: Staged Workflow
@@ -16,7 +16,12 @@ This guide is a scoped extension of the global Coding Guidelines. Use it for mea
 
 It operates inside the existing global rules for requested scope, concept economy, LLM/tools/code boundary, verification discipline, and documentation hygiene.
 
-For trivial edits, use the lightweight inspect-edit-verify path from the global Coding Guidelines.
+For trivial edits, use the lightweight inspect-edit-verify path, defined here in full:
+read the surface you are about to touch before changing it; if the request admits more
+than one reading, state the reading you act on; make the surgical edit — every changed
+line traceable to the request, adjacent code left alone; verify with the narrowest
+reliable check that would fail if the edit were wrong; clean up only what your own
+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.
 
@@ -32,8 +37,45 @@ When the user asks to "설계" or design, stay in design mode. Focus on high-lev
 2. Implementation-process design: turn the design into an ordered work plan with dependencies, verification points, review gates, and redesign triggers.
 3. Implementation: make the smallest viable functional changes that satisfy the approved design and process plan.
 
+**Minimum** limits surface area, configuration, abstractions, optional scope, and implementation spread. It must not reduce required behavior, runtime authority, evidence quality, or verification depth — a change that ships less of those is not smaller, it is less finished, and "smallest viable" becomes the excuse rather than the discipline.
+
+**Viable** means real behavior: the change runs against real inputs, real authority, and the intended runtime path. Mocks belong to tests, fixtures, and explicitly requested simulations — a mock-backed path supports verification but does not count as product completion, even when nothing labels it a mock; the full boundary lives in `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/mock-realization-boundary.md`.
+
+Define the success criteria before multi-step work starts, then verify against those criteria rather than against what you ended up building. Criteria written afterwards describe the implementation, so they cannot fail it.
+
 When simplifying a pipeline, moving processing downstream and dropping captured source fields are separate decisions: relocation is free simplification, but reducing captured information is riskier and needs explicit confirmation — "no current consumer" is not evidence of no future value.
 
+## Making the change
+
+Deciding what to build and building it are different disciplines. This one is about leaving a
+change that reads as the change that was asked for.
+
+**State the assumption before you act on it.** Most wasted implementation is not a wrong answer to
+the question; it is a right answer to a question nobody asked. Where the request admits more than
+one reading, say which one you took and keep going — surfacing it early costs a sentence, and
+surfacing it after the work costs the work.
+
+**Surgical means legible, not minimal.** Touch what the request requires, follow the file's
+existing style rather than your preferred one, and leave adjacent code alone even when it is
+worse than what you are adding. A diff carrying an unrequested refactor forces the reviewer to
+separate the two by hand, and the improvement is the part that gets dropped when they run out of
+patience.
+
+**Clean up what this change introduced, and only that.** Dead code, unused imports, and debris
+your own edit created belong in the same change. Debris you found belongs in a sentence: name it
+so it is visible, and leave it where the person who owns it can decide.
+
+**For a bug, reproduce before you fix, when that is practical.** A test written after the fix
+proves the code does what it now does. A test written before proves you understood the failure —
+and it is the only version that can tell you the fix was unnecessary, or that it addressed a
+different bug than the one reported.
+
+**Fix the cause at its authority, not the symptom where it shows.** Two signals say you are
+patching downstream: compensating code keeps accumulating around bad inputs, and each fix reveals
+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.
+
 ## 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).
@@ -45,57 +87,17 @@ When simplifying a pipeline, moving processing downstream and dropping captured
 - Treat low and info as non-blocking unless requested or promoted by new evidence.
 - When a document declares sections co-authoritative for a rule (fixture blocks, conformance appendices), treat every occurrence as one replicated value: propagate edits to all declared locations in the same pass and check propagation completeness explicitly in review.
 
-## Verification Menus
-
-Per-domain menus for the global Verification Discipline loop; pick the narrowest reliable mix that proves the changed behavior, meaning, or contract.
-
-- Code: a layered mix of unit tests, integration tests for E2E segments, targeted E2E for changed flows, and full E2E for release or high-risk changes.
-- Ontology: static graph checks, concept economy gates, changed-path integration checks, and competency-question E2E checks.
-- Config or data: real parsers, schema checks, fixture validation, and sample transformations.
-- Spreadsheets: static workbook checks, fixture-based output checks, cross-sheet flow checks, visual/layout checks, and real Microsoft Excel engine recalculation for formula-dependent results.
-- Docs: links, terminology, current behavior alignment, and references to isolated historical notes.
-- Release or distribution: after publishing to multiple independently writable channels (signed manifest, object storage, release host, embedded updater), digest-verify every referenced object against the staging original per channel — publish success and upload order are not evidence — and run the real installer/updater through its default path.
-- A/B or on/off measurements: before accepting a null result, verify the arms actually received different treatment in the mechanism under test — a shared default or unconditional upstream step can silently apply the treatment to both arms.
-- Model-behavior guardrails: verify by changed behavior, not recitation — a staged battery from named-trigger cases through disguised, deconfounded, category-wide, and single-variable framings; a clean pass means "no known defect", so re-run the battery when the model changes.
-- Branch/version test builds against real data: explicitly separate every state sink the app touches (files, DB, OS-level stores that ignore env overrides), confirm the launch path propagates the isolation to child processes, and back up live data before the first run — a mismatched schema that drops unknown fields on write is data loss, not a no-op.
-- Irreversible capture switches: when activation itself has unreproducible cost (a capture window that cannot be replayed), prove the downstream consumption path against existing samples before enabling — reversibility of the code path alone is not enough.
-
-### Deriving the case space
-
-A check has two authored halves, and they rot differently. The **verdict** — what the
-answer should be — rots by encoding a belief that was wrong from the start. The
-**space** — which cases exist — rots by staying still while the thing it covers grows.
-Recording the verdict is common practice; deriving the space is the half usually left
-hand-written, and a suite can have every expectation derived and still cover a set
-someone typed once.
-
-- Record the verdict, do not type it. Run the real path and store what came back;
-  drift then shows as a diff instead of as a belief someone has to re-justify.
-- Enumerate the space from the artifact that defines it — the config's entries, the
-  schema's fields, the router's routes, the installer's call sites. Adding one there
-  should widen coverage with no edit here.
-- Derive the exemption rule too. If some cases legitimately have no answer, decide that
-  from a property the artifact carries, never from a list of names: the list is the
-  authored space coming back through a side door, and it absorbs the regression where
-  a case that should have an answer stops having one.
-- Dedupe on the tuple that actually determines the outcome, and report how many
-  collapsed. A coverage count that hides its own truncation reads as more than it is.
-- Split by cost, not by space. When the real path needs money, credentials, or a
-  network, run a cheap stand-in on every commit and the real one on demand — both from
-  the **same enumeration**, so the two can never disagree about which cases exist.
-- Derivation moves authorship rather than removing it: the extractor and the invariants
-  are still written by hand. Give them a negative control, or the derived suite is just
-  a larger unfalsifiable one.
-- Planting a violation to prove a control fires is a write into the working tree, and
-  the restore is not atomic with it: if the probe can time out, abort, or be
-  interrupted, a restore sitting after it never runs and the plant survives into a
-  commit. Plant in a copy where the shape allows it, and when it must be in place, snapshot
-  first and restore from the snapshot as its own step rather than trusting the probe to finish.
+## Verification
+
+Verification is a subject of its own — depth, per-domain menus, deriving the case space, and what
+a green is worth. It lives in `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/verification-discipline.md`.
+Run it at each stage's verification points, and use its Verification Menus to pick the mix.
 
 ## Stop Conditions
 
 - If the issue boundary expands compared with the previous review, stop and ask the user to choose redesign/rework or continuing the current iteration.
 - Consider the boundary expanded when review reveals a broader affected purpose, failure condition, impact area, concept boundary, architecture boundary, or severity class.
+- When review rounds keep producing material findings, classify each before fixing: a regression the previous round's own fix introduced, or a fresh instance of one pre-existing root cause. Regressions say tighten the increment and continue; recurring instances with zero regressions say instance-patching is a refilling queue — trigger the redesign-versus-continue stop above.
 - Before calling the work done, report the current stage, review results, remaining material issues, verification results, and any stop reason.
 
 ## Environment Binding (edit per environment)
@@ -106,5 +108,5 @@ Binding (2026-07):
 
 | Slot | Binding | Notes |
 |---|---|---|
-| Structured multi-lens review | onto-mcp review (private MCP) | consumes/emits the severity contract defined in Review Loop |
+| Structured multi-lens review | agent-launch review methods: isolated panel + Codex deep exec (`codex exec` at ultra effort) + Claude ultracode workflow | consumes/emits the severity contract defined in Review Loop; personal tools register in the user-owned `review-methods.local.toml` |
 | Subagent review | host CLI's native review mechanism | e.g. Claude Code `/code-review` or Agent-tool reviewers |

package/claude/guides/concept-economy.md

@@ -0,0 +1,187 @@
+---
+guide_id: concept-economy
+language: en
+status: active
+use_when:
+  - naming anything lasting or shared — a feature, entity, type, field, flag, enum value, failure kind, artifact, or documentation term
+  - a review finding or test failure tempts you to add a name to make it go away
+  - deciding whether a value is its own concept or a property of an existing one
+  - deciding what a public surface exposes versus where the truth actually lives
+  - laying out a repository, or judging whether its shape still matches its concept graph
+core_rules:
+  - name the nearest existing concept before adding one, then choose reuse / extend / rename / split out loud
+  - every fix has a concept-surface sign — reducing, preserving, or increasing; say which before making it
+  - one value has one owner, and every other surface is generated from it rather than restated
+---
+
+# Concept Economy
+
+A scoped extension of the global Concept Economy section. Use it when you are about to introduce
+or change a name that will outlive the change that created it.
+
+The cost this guide manages is not disk or tokens. It is the reader's working set: every distinct
+name in a system is something a person or a model must hold, disambiguate, and keep aligned with
+its siblings. Two names for one behavior is not redundancy — it is a standing invitation to edit
+one and not the other, and that divergence is silent until something breaks in production.
+
+## What Counts As A Concept
+
+Anything **lasting or shared**. The list is deliberately long because the expensive additions are
+rarely the ones that feel like architecture:
+
+features, entities, variables, types, helper modules, artifacts, config keys, CLI flags, MCP/tool
+fields, public response fields, artifact fields, enum values, failure kinds, retry/recovery
+tokens, process names, documentation terms.
+
+What is *not* a concept: transient locals, generic containers (`items`, `result`, `tmp`), and
+layout a framework or tool imposes on you. The binding test is whether a second person has to
+learn the name to work here. A loop variable never crosses that line; a new failure kind always
+does, even when it is one string in one enum.
+
+The trap is scale-blindness. A field added to a response is one line of diff and a permanent
+addition to every consumer's mental model — including consumers you have not met.
+
+## The Four Paths
+
+Before adding or changing a concept, find the nearest existing one and choose a path **explicitly**.
+Choosing silently is how near-duplicates arrive: nobody decided to add a second name, they just
+did not look for the first.
+
+| Path | Choose it when | What you owe |
+| --- | --- | --- |
+| **Reuse** | an existing concept already covers this behavior | nothing — this is the default and needs no justification |
+| **Extend** | the existing concept covers it once you add a property | the property, and a check that existing readers tolerate its absence |
+| **Rename** | the behavior is right and the name has drifted from it | every site, in one change — a half-rename is strictly worse than either name |
+| **Split** | one of the split triggers below actually fired | the parent named, the reason stated, aliases mapped back |
+
+Prefer broad, stable concepts with precise properties over narrow near-duplicates. `Job` with a
+`kind` property beats `ImportJob` / `ExportJob` / `CleanupJob` as long as they share a lifecycle;
+the moment they stop sharing one, that is a split trigger, not a naming preference.
+
+### Finding the nearest concept
+
+The instruction to "find the nearest existing concept" fails when you search for the name you
+already have in mind — the name you invented will not be there, and its absence reads as
+permission. Search for the **behavior** instead:
+
+- Grep the vocabulary the concept would produce, not the concept: the enum values, the failure
+  strings, the field names, the log messages.
+- Read the nearest sibling's full definition, not its name. Names understate coverage; a type
+  called `Session` often already carries the lifecycle you were about to name separately.
+- Ask what would have to be true for the existing concept to be wrong here. If you cannot state
+  it as a behavioral difference, you are adding a synonym.
+- Check the terminology surface the repo already operates — a lexicon, a glossary, a domain
+  manifest — before the code. It is shorter and it is where the deliberate decisions live.
+
+If that search returns nothing, the addition is probably real. Record what you searched, because
+the next person will otherwise repeat it.
+
+## When To Split
+
+A split is warranted when the two things differ in something a caller can observe or must handle.
+These are the triggers; anything else is a preference:
+
+runtime behavior · ownership · lifecycle · validation · failure mode · user-visible behavior ·
+audit/replay requirements · authority · persistence · user control · failure handling
+
+Not triggers: a different call site, a different caller, a longer function, or a reviewer's
+discomfort. Those are reasons to add a property, a parameter, or a comment.
+
+When a split is necessary, three things ship with it or the split leaves debt:
+
+1. **Name the parent.** The concept being split from, explicitly, in the change.
+2. **State the reason.** Which trigger fired, in one sentence, where a maintainer will find it.
+3. **Map the variants back.** Aliases, deprecated spellings, and old values resolve to the
+   canonical concept — otherwise the old name lives on as a second concept nobody declared.
+
+## Derived Values Stay Derived
+
+A value that tools or code can compute from its source is a **property or projection** of that
+source, not a concept of its own. Persisting it creates a second authority that can disagree with
+the first, and it will: the source moves and the copy does not.
+
+The test is whether anything reads the stored value that could not have derived it. If the answer
+is no, the value is a cache at best and a contradiction at worst.
+
+**Authority is not visibility.** These are separate questions and conflating them produces both
+failure modes at once:
+
+| | Question | Wrong answer looks like |
+| --- | --- | --- |
+| Authority | where does the truth live, and who may change it | two writers, or a derived copy that outranks its source |
+| Visibility | what may a given surface see | an internal projection leaked into a public contract, now unchangeable |
+
+A public response may expose a bounded view — fewer fields, coarser precision, a rendered form —
+while the source concept or artifact remains the one truth location. That is a projection, and it
+is correct. What is not correct is treating the projection as the place to fix a wrong value.
+
+Keep internal projections and helper outputs internal unless public exposure is genuinely required
+by user behavior, a product contract, or artifact truth. An exposed field cannot be withdrawn on
+your schedule.
+
+## Reuse The Vocabulary Before Adding To It
+
+Enum values, failure kinds, retry/recovery tokens, and result/failure surfaces are concepts with
+unusually high blast radius: every consumer's branch coverage depends on the set being stable.
+Adding a value obliges every exhaustive reader to handle it; adding a near-synonym obliges them to
+handle it *and* to guess which one they will actually receive.
+
+Check the existing set first, and prefer an existing value whose meaning genuinely covers the case
+over a new one that describes it more precisely. Precision that fragments the set costs more than
+it buys.
+
+## Classifying A Fix
+
+Before fixing a review finding or a test failure, say which way the fix moves the active concept
+surface:
+
+- **Reducing** — the fix removes a name, merges a duplicate, or deletes a branch. Cheapest, and
+  usually available when the finding is "these two do the same thing".
+- **Preserving** — the fix changes behavior inside existing names. The normal case.
+- **Increasing** — the fix adds a name. Legitimate, but it must survive the four-paths question,
+  and a review finding is not by itself a reason to add a concept.
+
+This matters because review findings create pressure toward the increasing path: adding a flag, a
+kind, or a special case makes a finding disappear locally while widening the surface everyone else
+carries. Naming the direction before making the change is what keeps that trade deliberate.
+
+## Migration Compatibility
+
+**Use** fallback paths, compatibility shims, and deprecated alias normalization **when explicit
+migration compatibility is required** — the obligation runs both ways: required compatibility gets
+a shim, and nothing gets one as a default hedge. Each one is a second
+concept surface that must be maintained and eventually removed.
+
+When you add one, the removal condition ships with it: what has to be true for the shim to go, and
+where that is recorded. A compatibility path with no stated end becomes permanent architecture by
+attrition.
+
+## Keeping The Shape Navigable
+
+Let the repository's shape mirror its concept graph. A shared, lasting concept's canonical name
+should be traceable across every layer it appears in — path, module, type/interface, field, public
+API — so the structure is guessable from the concept name instead of from a translation table you
+have to already know.
+
+The working test: someone who knows the concept's name but not this repo should be able to guess
+the path, or find it with one grep. If finding it requires knowing that the concept is called one
+thing in the schema, another in the module, and a third in the URL, the layout has stopped being
+navigable and the names are doing damage rather than work.
+
+This binds shared concepts only. Transient locals, generic containers, and framework- or
+tooling-imposed layout may diverge, and forcing them to conform is its own kind of waste.
+
+## Domain Notes
+
+- **Ontology work.** Check existing entities and relations first — before adding, modifying,
+  removing, or relinking either; the graph is the
+  artifact whose value degrades fastest under duplication, because every added node multiplies the
+  edges a reader must consider.
+- **Code work.** Follow the naming patterns the repository already uses — the file first, then
+  its neighbors — and consolidate the variations
+  your own change introduced before calling it done. A change that leaves three spellings of one
+  idea has added two concepts regardless of intent.
+- **Comments and active docs.** Keep them aligned with current runtime behavior, failure
+  semantics, retry policy, ownership, and authority. A comment describing a superseded contract is
+  not stale documentation — it is a second, false authority, and it reads as current to anyone who
+  finds it first.