agent-bios 0.9.9 → 0.10.0

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.

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
 

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)

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.

package/claude/guides/documentation-hygiene.md

@@ -0,0 +1,112 @@
+---
+guide_id: documentation-hygiene
+language: en
+status: active
+use_when:
+  - writing a comment, and deciding whether it earns its place
+  - recording why something changed, an alternative that was rejected, or a migration's rationale
+  - deciding whether an active document should link to a historical note
+  - authoring a rule, guideline, or instruction others will follow
+  - choosing where change history and implementation context belong
+core_rules:
+  - prose about the past and prose about the present need different addresses, not different tenses
+  - a comment earns its place by carrying what the code cannot say about itself
+  - phrase a rule as the behavior you want, because a prohibition describes everything except what to do
+  - a continuously overwritten "current state" file claims to be now and is no particular time
+---
+
+# Documentation Hygiene
+
+A scoped extension of the global Documentation Hygiene section. The subject is placement: **prose
+about the past and prose about the present need different addresses.**
+
+The cost this manages is misreading, not tidiness. A sentence describing how something used to
+work, sitting beside code that works differently now, reads as a present fact — to a person
+skimming and to a model retrieving. Nothing marks it as history except a tense, and a tense is not
+a signal anyone checks. Moving it is cheaper than maintaining the reader's suspicion.
+
+## The two addresses
+
+**Active surfaces** — runtime code, comments, the docs someone reads to operate the thing — carry
+current behavior, current decisions, current contracts, current authority, current failure
+handling. Nothing else.
+
+**Isolated paths** — `docs/`, `design/`, `archive/`, `deprecated/` or whatever the repository uses
+— carry backward-compatibility notes, deprecated behavior, migration rationale, historical
+alternatives, change narratives, and handoff logs.
+
+The test for any sentence: *if this stopped being true, would anyone notice?* Active surfaces are
+where the answer must be yes, because something breaks. History is where the answer is no, which
+is exactly why it must not sit in the first place.
+
+## Comments carry what the code cannot
+
+A comment earns its place by saying something the code cannot say about itself:
+
+- Non-obvious current behavior — why this looks wrong and is right.
+- An invariant a reader could break without noticing they broke it.
+- A constraint that comes from outside the file: a protocol, a rate limit, an ordering another
+  system depends on.
+- A risk that still applies. Not one that used to.
+
+What does not earn its place: restating the line below it, narrating the change that introduced it
+("changed this to fix the bug"), or describing a contract that has since moved. That last one is
+not stale documentation — it is a **second, false authority**, and to whoever reads it first it is
+simply the answer.
+
+Comments describing superseded behavior are the highest-yield deletion in most files. They are
+also the hardest to find, because nothing fails when they are wrong.
+
+## History has its own address
+
+When you have something worth recording that is not current behavior — why an alternative was
+rejected, what a migration was compensating for, what a session handed off — write it in an
+isolated path rather than beside the code.
+
+Two properties make such a record useful:
+
+- **It is written once.** A record that is edited whenever things change stops describing any
+  particular moment. If it must be updated, the honest move is a new record that supersedes the
+  old one, not an overwrite.
+- **It carries its own point in time.** A timestamp in the filename cannot rot, because the age is
+  on the label. A file called "current state" makes a claim it cannot keep.
+
+That second point generalizes past records. Any continuously overwritten "the state of things"
+document claims to be now and is, in practice, no particular time — the last person to touch it
+decided how current it is, and nobody else can tell. Where the underlying facts are derivable,
+give the reader the command that re-derives them instead of a number someone typed.
+
+## Linking back
+
+Link from active material to a historical note only when the current task needs that history, or
+when the reference genuinely helps a future maintainer — usually because the present design looks
+arbitrary without it.
+
+A link is a small permanent cost: it invites the reader to leave, and it must stay resolvable. An
+active document that links to five historical notes has partly become one.
+
+## Writing rules people follow
+
+Phrase a rule as the behavior you want, not as the thing you are afraid of. A prohibition
+describes everything except what to do, and leaves the reader to invent the positive form —
+usually at the moment they have the least attention to spare.
+
+- "Pin the interpreter when a bash-specific feature is needed" beats "don't rely on the default
+  shell".
+- "State the assumption you are proceeding under" beats "don't guess".
+
+Two more properties of a rule that survives contact:
+
+- **It says when it fires.** A rule with no trigger is advice, and advice is followed when
+  convenient.
+- **It says what it costs.** A rule whose expense is hidden gets quietly dropped the first time
+  someone is in a hurry, and nobody records that it was dropped.
+
+## Where change history belongs
+
+Prefer the established homes over inventing one per change: a changelog for released behavior, a
+current-state dashboard for architecture and risk, handoff notes for what a session left unfinished.
+
+Keep their jobs distinct. A changelog that accumulates design rationale becomes unreadable as a
+changelog; a dashboard that accumulates history stops being current. When a document starts
+answering a question it was not built for, that is a signal to split it, not to add a section.

package/claude/guides/review-request.md

@@ -26,10 +26,11 @@ verification_focus:
 This guide is a scoped extension of the global Coding Guidelines. Use it when
 composing what you ask a reviewer for — the request, the evidence bar, the
 verdict shape. It does not cover when to review, how deep, or what counts as
-material (the staged-workflow guide's severity ladder and review loop own that),
-which reviewer kind to route to (the multi-model guide's convergence heuristic),
-or how to phrase a prompt for a given model family (the per-family prompting
-guides).
+material (the severity ladder and review loop in `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/coding-staged-workflow.md` own that),
+which reviewer kind to route to — the convergence heuristic in
+`${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/verification-discipline.md` owns that. Phrasing a prompt for a specific model
+family is out of scope here; where that guidance ships, the rule that needs it
+points at it.
 
 The rules below are derived from ~330 real multi-lens review sessions run in
 this environment. That corpus is one model family in practice, so nothing here
@@ -80,8 +81,9 @@ So state the floor in the request: **do not report a finding you would rate low.
 It will be discarded; spend the effort on a medium-or-above finding instead.**
 This is not a quality bar on the reviewer, it is a cost decision — the corpus
 shows the discard happens regardless, so the only question is whether you pay to
-generate it first. (What counts as each severity is the staged-workflow guide's
-ladder, not this guide's.)
+generate it first. (What counts as each severity is the ladder in
+`${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/coding-staged-workflow.md`, not
+this guide's.)
 
 ## Forbid carry-forward findings
 
@@ -128,7 +130,7 @@ nicely: the submit schema refuses output without them. The result is a corpus
 where reviewers are right about existence (0.3% of issues end unresolved after
 argument) and where "found nothing" is a verified statement rather than silence.
 
-This is the general rule from the capability-boundary guide applied to review:
+This is the general capability-boundary rule applied to review:
 when output must have a property, make it unavailable without it. If your review
 route has a schema, put the anchor there. If it does not, the demand belongs in
 the request — but expect the weaker result that a request-only rule gives you.