refactor: adopt adaptive engineering rigor model

AGENTS.md

@@ -1,23 +1,50 @@
 # Practical Coding
 
-This repository is an Agent Skill. If you are a coding agent reading this file from a checkout, apply the skill as follows.
+This repository is an Agent Skill. If you are a coding agent reading this file from a checkout, apply the Skill from [`SKILL.md`](SKILL.md).
 
-Read [`SKILL.md`](SKILL.md) for the route-agnostic shortest-path Core, the three-branch Event Router, and the Retrieval Policy. The Core always applies. Ordinary well-specified work stays Direct with no reasoning reference and no worker.
+Practical Coding is an adaptive-rigor system, not a task classifier. The Core always applies. Start from the cheapest sufficient action and add stricter reasoning only when a present blocker requires it.
 
-The Event Router handles only unresolved blockers that change how the task must be reasoned about:
+## 1. Decision Gate
 
-| Trigger | Reasoning module |
+Before execution, determine whether a material unresolved choice blocks or materially changes the next safe action.
+
+- If no, continue to execution.
+- If yes, read [`references/decision.md`](references/decision.md) and resolve only that decision frontier.
+
+A request-, repository-, or authority-settled choice is input, not a Decision. Cheap reversible choices use the project or platform default. Resolve discoverable facts before asking the user; only genuinely user-owned scope, compatibility, cost, preference, or risk choices should remain as questions.
+
+After the choice is settled, continue with the Core. Do not assume the logical end of Decision removes `decision.md` from model context.
+
+## 2. Execution Escalation
+
+Direct is the default execution state: Core only.
+
+| Present blocker | Extra rigor |
 |---|---|
-| An observed failure, regression, or incorrect behavior still lacks an evidenced cause | [`references/debugging.md`](references/debugging.md) |
-| A material unresolved user-owned choice about architecture, whether or which external dependency/implementation to adopt, APIs, data models, or compatibility would change the next action | [`references/decision.md`](references/decision.md) |
-| An unknown contract/invariant, an unresolved material risk boundary (security/permissions, irreversible side effects, persistence/migration, concurrency/transactions, compatibility), or insufficient evidence for a risky material claim blocks safe execution | [`references/implementation.md`](references/implementation.md) |
+| Observed failure or regression still lacks an evidenced cause | [`references/debugging.md`](references/debugging.md) |
+| Safe execution is blocked by an unknown contract/invariant, unresolved material risk boundary, or unresolved sufficient evidence for a risky claim | [`references/implementation.md`](references/implementation.md) |
+
+Debugging and Implementation are escalation profiles, not sequential stages. Do not classify by task nouns, file count, code size, or apparent difficulty. A diagnosed bug can be Direct. A security, persistence, migration, concurrency, or compatibility edit can be Direct when the governing boundary, affected surface, and sufficient check are already established.
+
+If one loaded profile resolves its blocker and a materially different blocker later appears, reassess from the Core. Do not accumulate another large reasoning reference in the root merely because the task continued; isolate substantial follow-up work when the context saved exceeds handoff cost.
+
+## 3. Retrieval Policy
+
+Retrieval is independent from Decision and execution rigor. Use the cheapest sufficient available path:
+
+1. current context / known path / known symbol;
+2. bounded or ranked source discovery, falling back to ordinary filename/text/symbol search;
+3. an already-available structural index only for relationship-heavy questions where it materially reduces exploration;
+4. current-source verification for material conclusions.
+
+Read [`references/navigation.md`](references/navigation.md) only when broad retrieval itself is substantial enough to need the detailed procedure. Host-native ranked search, FFF-style retrieval, and `DeusData/codebase-memory-mcp` are optional capabilities, not project requirements. Missing capabilities fall back without installing tooling or changing project configuration solely for retrieval.
 
-Load exactly one first-match reasoning module in addition to the Core. A choice already settled by the request or repository is input, not a Decision event. A security, persistence, migration, concurrency, or compatibility noun is not itself an Implementation event when the governing boundary, affected surface, and sufficient check are already established. Do not treat file count, task nouns, search needs, or the existence of another library as routing evidence. If a different blocker appears later, reassess it without accumulating another reasoning reference in the root; use the Core when sufficient or isolate substantial follow-up work when the saved context exceeds handoff cost.
+Retrieval levels are cost bounds rather than exact semantic labels. A cheap bounded search may be acceptable where a targeted read would also suffice; an unnecessary structural exploration is not.
 
-Navigation is not a fourth Event Router branch. Code retrieval follows the cheapest sufficient available path: known source first, then bounded/ranked source discovery, then an already-available structural index only when relationship queries materially reduce exploration, followed by current-source verification for material claims. Routine targeted lookup needs no Navigation reference.
+## 4. Isolation Gate
 
-Read [`references/navigation.md`](references/navigation.md) only when broad retrieval itself is substantial enough to need the detailed procedure. Host-native ranked search, FFF-style retrieval, and `DeusData/codebase-memory-mcp` are optional capabilities, not project requirements. Use them only when already available; otherwise fall back to ordinary source search without installing tooling or changing project configuration solely for retrieval. An already-integrated structural backend may maintain or refresh its own index as part of normal use.
+The root owns user intent, authorization, repository state, integration, and the final completion claim. Keep the root to the Core plus at most one loaded reasoning reference at a time.
 
-For a substantial triggered event, prefer an isolated no-history worker only when its context savings exceed handoff cost; otherwise load the one selected reasoning reference in the root agent. Keep the root to the Core plus at most one loaded reasoning reference for the task. If broad mapping becomes expensive while another reasoning reference is already resident, prefer a read-only Navigation worker rather than loading a second large reference into the root.
+The root never reads [`references/delegation.md`](references/delegation.md). When isolation clearly saves more context than its handoff cost, dispatch one worker with `delegation.md` plus exactly one assigned reference and a compact capsule of settled choices, verified facts, scope, repository state, and success conditions.
 
-The root agent owns user intent, authorization, repository state, routing, integration, and the final completion claim. A worker reads [`references/delegation.md`](references/delegation.md) plus exactly one assigned reference and returns a compact capsule. Decision, Debugging, and Navigation workers are read-only. An Implementation worker may write only when its assignment explicitly includes implementation, must have a bounded scope, and must be the sole writer there. Treat a capsule as stale after relevant repository changes.
+Decision, Debugging, and Navigation workers are read-only. An Implementation worker may write only when explicitly assigned a bounded implementation scope and must be the sole writer there. Never use overlapping writers or worker pipelines. Treat a worker capsule as stale after relevant repository changes.

CONTRIBUTING.md

@@ -1,20 +1,48 @@
 # Contributing
 
-Contributions should preserve Practical Coding as one compact Skill with a small route-agnostic Core, three independently loadable reasoning modules, and a retrieval policy that does not become a permanent prompt tax.
+Contributions should preserve Practical Coding as one compact **adaptive-rigor Skill**: a small route-agnostic Core, one pre-execution Decision Gate, two independently loadable execution-rigor profiles, and a Retrieval Policy that does not become a permanent prompt tax.
 
-- Keep `SKILL.md` as a small shortest-path Core plus Event Router and compact Retrieval Policy. Do not add routing intensity modes unless a mature cross-agent mechanism materially improves evidence.
-- The Event Router owns only unresolved reasoning blockers: Debugging, Decision, and Implementation. Navigation is retrieval, not a fourth reasoning route.
-- Do not retune Core or module wording from a single failed benchmark cell, and do not add case-specific bans named after benchmark tasks.
-- Keep the Direct Path real: simple, well-specified work must not require a reference, broad repository scan, or worker.
+- Keep `SKILL.md` small. The Core must contain only rules that apply to essentially every coding task.
+- Treat **Decision** differently from execution rigor. Load `decision.md` only when a material unresolved choice blocks or materially changes the next safe action.
+- Treat **Direct** as the default execution state, not a route or reference.
+- Treat **Debugging** and **Implementation** as alternative escalation profiles, not a `Direct → Debugging → Implementation` pipeline.
+- Debugging is justified only while an observed failure lacks an evidenced cause. If the cause is already established and the safe fix is known, stay Direct.
+- Implementation rigor is justified only while safe execution is blocked by an unknown contract/invariant, unresolved material risk boundary, or insufficient evidence for a risky claim. Security, persistence, migration, concurrency, compatibility, or file count alone are not triggers.
+- Do not retune Core or reference wording from a single failed benchmark cell, and do not add case-specific bans or trigger nouns named after public benchmark tasks.
+- Keep simple, well-specified work genuinely cheap: no reasoning reference, broad repository scan, plan document, or worker merely because the task involves code.
 - Routine targeted source lookup must not require `references/navigation.md`. Load that reference only when broad retrieval itself is substantial enough to justify the prompt cost.
-- Preserve context isolation. The root should normally carry the Core plus at most one reasoning reference. If broad mapping becomes expensive while another reference is resident, prefer a read-only Navigation worker when saved context exceeds handoff cost.
-- Workers read `references/delegation.md` plus exactly one assigned reference and return compact evidence capsules, not transcripts.
-- Keep shared-workspace workers read-only by default. An Implementation worker may write only when its assignment explicitly includes implementation, with one bounded writer scope.
-- Prefer strengthening an existing module or retrieval primitive over adding another module. Verification remains part of Core or Implementation; do not create a mandatory Verification route.
+- Preserve context isolation. The root should normally carry the Core plus at most one large reasoning reference at a time. Logical state transitions do not remove already-read context.
+- If a later blocker needs another large reference, isolate substantial follow-up work only when saved context exceeds handoff cost. Do not create worker pipelines.
+- Workers read `references/delegation.md` plus exactly one assigned reference and return compact evidence capsules, not raw transcripts.
+- Keep shared-workspace workers read-only by default. An Implementation worker may write only when explicitly assigned one bounded writer scope.
+- Prefer strengthening an existing profile or retrieval primitive over adding another module. Verification remains part of Core or Implementation rigor; do not create a mandatory Verification stage.
 - Do not introduce mandatory plans, execution documents, Git workflows, tests, reviews, documentation, or tool-specific ceremony as universal gates.
 - Preserve reuse-before-invention, mature-implementation-first, risk-proportional verification, evidence-driven debugging, and resistance to speculative code and defensive bloat.
 - Avoid new scripts, dependencies, configuration, generated project files, or persistent services unless they solve a demonstrated project need rather than merely making retrieval possible.
 
+## Decision Gate discipline
+
+A proposed Decision trigger must answer:
+
+> Without settling this choice, can the agent already know the next safe action?
+
+If yes, it is not a blocking Decision Gate. Repository conventions, authoritative constraints, or a cheap reversible default should settle ordinary choices without an interview.
+
+When a choice genuinely remains user-owned, ask only for the minimum scope, compatibility, cost, preference, or risk information that changes the next action. A Decision module should converge and return a compact execution capsule; it should not become a design-document generator.
+
+## Execution-rigor discipline
+
+When changing `debugging.md` or `implementation.md`, test both positive and negative boundaries:
+
+- unknown-cause failure → Debugging;
+- diagnosed failure → Direct;
+- unresolved material execution boundary → Implementation;
+- already-mapped risk boundary with known affected surface and sufficient check → Direct;
+- Debugging completed with no remaining boundary blocker → Direct;
+- Debugging completed but a materially different execution boundary remains unresolved → Implementation only as a new escalation, preferably isolated if a second large reference would accumulate.
+
+The amount of code, number of files, or perceived task difficulty is not a valid substitute for these blocker conditions.
+
 ## Retrieval backends
 
 Practical Coding manages retrieval cost, not ownership of a particular search engine.
@@ -27,6 +55,31 @@ Practical Coding manages retrieval cost, not ownership of a particular search en
 
 Do not reimplement mature retrieval engines inside Practical Coding merely to avoid an optional external capability. Conversely, do not turn an optional capability into a hard dependency or automatic installation side effect.
 
+### Retrieval benchmark discipline
+
+The v1.3 benchmark uses a minimum-sufficient / maximum-reasonable interval instead of requiring one unique exact Retrieval label.
+
+A benchmark-case change must distinguish:
+
+- **insufficient retrieval** — below the minimum context needed for safe action;
+- **acceptable retrieval** — within the frozen cost interval;
+- **excessive retrieval** — above the maximum reasonable cost for the task.
+
+Do not widen an interval after seeing a failed run merely to make the cell pass. Change it only before a validation cycle or after documenting a genuine benchmark-instrument defect.
+
+## Benchmark changes
+
+The canonical v1.3 runner is `benchmarks/run_catalog.py` (runner v2.1). `run_benchmarks.py` remains the v2.0 execution core for historical interpretability; do not silently rewrite old result directories or reinterpret old Router scores under the new schema.
+
+Any behavior-changing contribution should preserve or add regression coverage for the mechanism it changes. In particular, the current transition corpus must continue to cover:
+
+- Decision → Direct;
+- Decision → Implementation;
+- Debugging → Direct;
+- Debugging → Implementation.
+
+Before publishing claims, follow [`benchmarks/NEXT_VALIDATION.md`](benchmarks/NEXT_VALIDATION.md). Public cells that influenced wording are regression evidence, not independent held-out evidence.
+
 ## Mature implementation first
 
 For any non-trivial capability with credible prior art: