feat: restore evidence-triggered event router

.github/workflows/validate.yml

@@ -22,7 +22,7 @@ jobs:
         run: skills-ref validate ./practical-coding
       - name: Run benchmark harness tests
         working-directory: practical-coding
-        run: python -m unittest benchmarks.test_benchmarks benchmarks.test_stability benchmarks.test_catalog
+        run: python -m unittest benchmarks.test_benchmarks benchmarks.test_stability benchmarks.test_catalog benchmarks.test_ladder_analysis benchmarks.test_progressive_validation
       - name: Check Codex default_prompt references the skill as $skill-name
         run: grep -qF '$practical-coding' practical-coding/agents/openai.yaml
       - name: Ensure legacy local graph runtime is not reintroduced

AGENTS.md

@@ -1,23 +1,33 @@
 # 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. Apply [`SKILL.md`](SKILL.md) when working from this checkout.
 
-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.
+## Runtime model
 
-The Event Router handles only unresolved blockers that change how the task must be reasoned about:
+1. Apply the Core and stay Direct unless one present unresolved event matches the Router.
+2. Route only Debugging, Decision, or Implementation; load at most one reasoning reference for the current event.
+3. Complete routing before diagnostic, decision-research, or change-mapping source work. The selected reference is the next read.
+4. Keep retrieval orthogonal. Unknown paths, callers, consumers, and data flow are retrieval questions, not Implementation events.
+5. Contract to the smallest affected surface as soon as the cause, choice, contract, invariant, or evidence boundary is established.
 
-| Trigger | Reasoning module |
+## Event Router
+
+| Present unresolved event | Reference |
 |---|---|
-| 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 still lacks an evidenced cause | [`references/debugging.md`](references/debugging.md) |
+| Material user-owned implementation choice changes the next action | [`references/decision.md`](references/decision.md) |
+| Unknown contract/invariant, coordinated guarantee, material risk boundary, or evidence plan blocks safe execution | [`references/implementation.md`](references/implementation.md) |
+
+A known target and settled behavior/boundary/check stay Direct even when risk nouns are present. A read-only mapping request is Direct plus Retrieval.
+
+Requirements interviewing is explicit-only through [`references/manual/clarification.md`](references/manual/clarification.md).
 
-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
 
-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.
+Use known source, then bounded/ranked search, then an already-available structural capability when it materially reduces relationship discovery. Use exhaustive coverage or external authoritative sources only when the claim requires them. Source remains authoritative.
 
-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.
+Read [`references/navigation.md`](references/navigation.md) only for substantial retrieval. Missing graph/ranked capabilities fall back without installing or persisting tooling solely for retrieval.
 
-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.
+## Evolution
 
-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.
+`evolution/` is maintainer knowledge and must not enter ordinary runtime context. During Skill maintenance, record mechanisms and failed changes there before modifying another runtime rule. Iterations use n=1; only a frozen release candidate receives the complete n=3 matrix.

CONTRIBUTING.md

@@ -1,40 +1,43 @@
 # 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.
+Practical Coding optimizes for the smallest quality-qualified runtime contract, not the most complete-looking workflow.
 
-- 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.
-- 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.
-- 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.
+## Runtime boundaries
 
-## Retrieval backends
+- Keep `SKILL.md` compact and route-agnostic outside the Event Router.
+- Route only a present unresolved Debugging, Decision, or Implementation event.
+- Load at most one reasoning reference for the current event.
+- Keep source/context retrieval independent from reasoning selection.
+- Requirements interviewing remains explicit-only.
+- Do not introduce mandatory plans, reviews, tests, documents, Git workflows, workers, or lifecycle ceremony.
 
-Practical Coding manages retrieval cost, not ownership of a particular search engine.
+Unknown locations, callers, consumers, or relationships are retrieval questions. They become Implementation only when a requested coordinated change has an unresolved governing contract or material risk/evidence boundary.
 
-1. Prefer already-known source and narrow direct reads.
-2. Prefer an already-available bounded/ranked source-search primitive over unbounded output. Host-native ranked search and FFF-style retrieval are examples, not requirements.
-3. Prefer an already-available structural index only for relationship-heavy questions where it materially reduces repeated source exploration. `DeusData/codebase-memory-mcp` is one mature example.
-4. If a stronger capability is unavailable, fall back to ordinary source search without changing repository configuration or installing/persisting tooling solely for retrieval.
-5. Material conclusions must still be checked against current source.
+## Evolution before wording
 
-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.
+Runtime agents do not read `evolution/`. Skill maintenance must:
 
-## Mature implementation first
+1. record benchmark or real-project evidence;
+2. consolidate repeated mechanisms under `evolution/wiki/`;
+3. freeze the hypothesis and validation before changing runtime rules;
+4. preserve rejected changes under `evolution/rejected/`.
+
+Do not add benchmark case nouns to runtime wording. A module must have an observable pre-load trigger and stable quality-qualified lift over the smaller parent; otherwise tighten, merge, or remove it.
+
+## Benchmark discipline
+
+- Quality, safety, and build/reachability precede routing and cost.
+- Iteration runs use n=1. Run n=3 only for a frozen candidate believed ready to release.
+- Current-only runs may compare against prior published reports offline, but are not paired ranking evidence.
+- Keep deterministic prompts and oracles contract-consistent; do not reward behavior the prompt forbids.
+- Add a test when a newly discovered mechanism or scorer invariant would otherwise regress.
 
-For any non-trivial capability with credible prior art:
+Public regression covers Delivery, Debug, Decision, Router, and Native Behavior. Real-repository held-out coverage validates delivered evidence, zero spontaneous requirements interviewing, event selection, and retrieval scope.
 
-1. Inspect maintained mature implementations first.
-2. Prefer supported public integration surfaces — API, CLI, protocol, package, library, binary, or host-native tool — over copying internals or rebuilding the subsystem.
-3. Verify fit, maintenance state, known issues, release activity, operational constraints, and license.
-4. Add local code only for concrete gaps or confirmed upstream defects.
-5. Keep local patches narrow, attributable, and removable when upstream fixes the issue.
+## Retrieval capabilities
+
+Known source → bounded/ranked search → structural capability when useful → bounded exhaustive or authoritative external evidence only when required. FFF-style search, ordinary search, LSP/AST, and Codebase Memory are optional capabilities. Verify material claims against current source and disclose coverage gaps.
+
+## Mature implementation first
 
-A change is moving in the wrong direction if a trivial local edit must load or execute more process after the change than before it, if retrieval dumps more irrelevant context into the model, or if Practical Coding starts maintaining a weaker duplicate of a mature subsystem.
+For a non-trivial new capability, inspect maintained prior art, extract the smallest fitting mechanism, verify maintenance/license/API fit, and keep the result removable. Do not copy an entire expert workflow into the Core.