experiment: benchmark-driven evolvable local router tree

.github/workflows/validate.yml

@@ -2,9 +2,12 @@ name: Validate skill
 
 on:
   push:
-    branches: [main]
+    branches: [main, experiment/evolvable-router-tree]
   pull_request:
 
+permissions:
+  contents: read
+
 jobs:
   validate:
     runs-on: ubuntu-latest
@@ -20,11 +23,85 @@ jobs:
         run: pip install "git+https://github.com/agentskills/agentskills.git#subdirectory=skills-ref"
       - name: Validate SKILL.md
         run: skills-ref validate ./practical-coding
-      - name: Run benchmark harness tests
+      - name: Run benchmark harness unit tests
+        working-directory: practical-coding
+        run: >-
+          python -m unittest
+          benchmarks.test_benchmarks
+          benchmarks.test_stability
+          benchmarks.test_catalog
+          benchmarks.test_ladder_analysis
+          benchmarks.test_progressive_validation
+          benchmarks.test_tree_benchmarks
+          benchmarks.test_capability_environment
+          benchmarks.test_dependency_tree_validation
+          benchmarks.test_retrieval_analysis
+          benchmarks.test_evolution_workflow
+      - name: Validate execution and retrieval topology contracts
+        working-directory: practical-coding
+        run: |
+          python benchmarks/tree_validation.py --self-test
+          python benchmarks/dependency_tree_validation.py --self-test
+          python benchmarks/retrieval_validation.py --self-test
+          python benchmarks/retrieval_analysis.py /dev/null --self-test
+      - name: Validate explicit evolution workflow contract
         working-directory: practical-coding
-        run: python -m unittest benchmarks.test_benchmarks benchmarks.test_stability benchmarks.test_catalog benchmarks.test_ladder_analysis benchmarks.test_progressive_validation
+        run: python benchmarks/evolution_workflow_validation.py --self-test --output benchmark-results/evolution-workflow-contract.json
+      - name: Check manual-only Decision layout
+        run: |
+          test ! -e practical-coding/references/decision.md
+          test -e practical-coding/references/manual/decision.md
+      - name: Check progressive Retrieval layout
+        run: |
+          test -e practical-coding/references/retrieval/SKILL.md
+          test -e practical-coding/references/retrieval/direct.md
+          test -e practical-coding/references/retrieval/discovery.md
+          test -e practical-coding/references/retrieval/evidence.md
+          test -e practical-coding/references/retrieval/structural.md
+          test -e practical-coding/benchmarks/capability_manifest.json
+      - name: Ensure removed ranked-search integration is absent from active surfaces
+        run: |
+          ! grep -R -i -E 'fff-style|pi-fff|\bFFF\b' \
+            practical-coding/SKILL.md \
+            practical-coding/AGENTS.md \
+            practical-coding/README.md \
+            practical-coding/README_zh.md \
+            practical-coding/CONTRIBUTING.md \
+            practical-coding/examples \
+            practical-coding/references \
+            practical-coding/agents \
+            practical-coding/docs/CAPABILITY_LAYER.md \
+            practical-coding/benchmarks/README.md \
+            practical-coding/benchmarks/capability_manifest.json
       - name: Check Codex default_prompt references the skill as $skill-name
         run: grep -qF '$practical-coding' practical-coding/agents/openai.yaml
+      - name: Ensure retired execution-state experiment is absent
+        run: |
+          retired_files="$({
+            find practical-coding/runtime practical-coding/tests practical-coding/benchmarks \
+              -maxdepth 1 -type f \
+              \( -name '*skill_state*' -o -name 'test_skill_state*' \) \
+              -print 2>/dev/null || true
+            find practical-coding/evolution/experiments \
+              -maxdepth 1 -type f -name 'skill-state-*' -print 2>/dev/null || true
+          })"
+          if test -n "$retired_files"; then
+            printf 'retired execution-state files remain on an active surface:\n%s\n' "$retired_files"
+            exit 1
+          fi
+          test ! -e practical-coding/docs/SKILL_STATE.md
+          test ! -e practical-coding/docs/SKILL_STATE_HOST.md
+          test ! -e practical-coding/docs/SKILL_STATE_INVARIANTS.md
+          test -e practical-coding/evolution/rejected/execution-state/README.md
+          ! grep -R -E \
+            'runtime/skill_state|SKILL_STATE_MODEL_GATE|state-history-free|Execution State Projection|"execution_state"' \
+            practical-coding/SKILL.md \
+            practical-coding/AGENTS.md \
+            practical-coding/README.md \
+            practical-coding/README_zh.md \
+            practical-coding/agents/openai.yaml \
+            practical-coding/benchmarks/README.md \
+            practical-coding/benchmarks/tree_topology.json
       - name: Ensure legacy local graph runtime is not reintroduced
         run: |
           test ! -e practical-coding/runtime/codebase_memory.py

AGENTS.md

@@ -4,30 +4,50 @@ This repository is an Agent Skill. Apply [`SKILL.md`](SKILL.md) when working fro
 
 ## Runtime model
 
-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.
+1. Apply Core at execution-tree depth 0.
+2. Core knows only its immediate automatic execution children: Debugging and Implementation.
+3. A loaded execution node owns only its own next-level router. Do not preload siblings or descendants and do not send descendant selection back to Core.
+4. Current Debugging and Implementation nodes are leaves until benchmark evidence earns a child.
+5. Retrieval is a separate progressive tree. Its depth describes the unresolved information problem, not execution complexity or tool strength.
+6. Host capabilities such as ranked search, graph retrieval, and output compaction are replaceable infrastructure outside both trees.
+7. Automatic routing must converge toward resolving the current blocker; it must not reopen deliberation.
 
-## Event Router
+## Root Router
 
-| Present unresolved event | Reference |
+| Present unresolved blocker | Immediate child |
 |---|---|
 | 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) |
+| Unknown contract/invariant, coordinated guarantee, material risk boundary, or evidence requirement 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.
+A known target and settled behavior/boundary/check stay at Core even when risk nouns are present. A read-only mapping request is Core plus Retrieval.
 
-Requirements interviewing is explicit-only through [`references/manual/clarification.md`](references/manual/clarification.md).
+## Manual modes
 
-## Retrieval
+Manual modes are outside the automatic trees:
 
-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.
+- [`references/manual/decision.md`](references/manual/decision.md) only for an explicit current request to compare options, choose a technology/architecture/dependency/API/data model, or perform decision analysis;
+- [`references/manual/clarification.md`](references/manual/clarification.md) only for an explicit current request to be interviewed, grilled, questioned, or to clarify requirements before implementation.
 
-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.
+No automatic node may route to a manual mode. Ordinary technical choices discovered during execution use the established project convention or the smallest sufficient reversible option. If a user-owned choice has no safe default, ask the minimum blocking question in the current context without opening Decision.
+
+## Navigation and Retrieval
+
+Navigation answers **which bounded repository area** should be searched. Load [`references/navigation.md`](references/navigation.md) only when that map is genuinely unresolved; it must return a compact topology and stop.
+
+Retrieval answers **which concrete evidence** resolves the current claim. Load [`references/retrieval/SKILL.md`](references/retrieval/SKILL.md), then follow only the immediate child declared by the currently loaded node. The runtime root must not reproduce the complete topology from the benchmark manifest or select a distant descendant directly.
+
+Do not route by provider name. Runtime fallback remains lossless when a ranked or graph provider is unavailable. The dependency-enabled benchmark is different: it fails closed unless every provider in [`benchmarks/capability_manifest.json`](benchmarks/capability_manifest.json) is installed and successfully pre-initialized.
+
+## Execution output
+
+Output compaction is a cross-cutting execution layer. A host adapter should make it transparent where command hooks exist; otherwise use the thinnest wrapper instruction available. It may reduce noisy shell, test, build, and Git output, but it must preserve semantics, exit status, failures, and material verification evidence. It is never a Retrieval or execution-tree node.
 
 ## Evolution
 
-`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.
+`evolution/` is maintainer knowledge and must not enter ordinary runtime context. The trees are experiment results, not fixed taxonomies.
+
+Use [`benchmarks/tree_topology.json`](benchmarks/tree_topology.json), [`benchmarks/dependency_tree_validation.py`](benchmarks/dependency_tree_validation.py), [`benchmarks/retrieval_validation.py`](benchmarks/retrieval_validation.py), [`benchmarks/tree_analysis.py`](benchmarks/tree_analysis.py), and [`benchmarks/retrieval_analysis.py`](benchmarks/retrieval_analysis.py) for active dependency-enabled topology work. Cases must not encode a gold automatic node or fixed numeric execution level. Derive minimum-sufficient nodes by capability ablation, then use repeated routing ambiguity or quality failures to propose add/split/merge/promote/collapse/remove changes.
+
+Iterations use n=1. Only a frozen candidate receives the complete n=3 baseline/no-skill comparison. Provider installation, model download, first index, dependency resolution, and first build warm-up are setup work and are never included in benchmark token, duration, or tool-call comparisons.
+
+Preserve v1.5 and rejected experiments as historical evidence rather than rewriting them for the current topology. The execution-state/history-free proposal is retired under [`evolution/rejected/execution-state/`](evolution/rejected/execution-state/); do not restore it without a new frozen hypothesis and independent evidence.

CONTRIBUTING.md

@@ -4,14 +4,37 @@ Practical Coding optimizes for the smallest quality-qualified runtime contract,
 
 ## Runtime boundaries
 
-- 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.
+- Keep `SKILL.md` compact. Core knows only the immediate automatic execution children.
+- Route only a present unresolved Debugging or Implementation blocker.
+- Decision and requirements interviewing remain explicit-only manual modes.
+- Keep the execution tree, Retrieval tree, capability providers, output transport, and maintenance workflows separate.
+- A loaded node may name only its immediate child. Do not place every depth decision in Core.
 - Do not introduce mandatory plans, reviews, tests, documents, Git workflows, workers, or lifecycle ceremony.
 
-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.
+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.
+
+## Retrieval-tree discipline
+
+The active Retrieval path is:
+
+`Retrieval Root -> R0 Direct Locate -> R1 Ranked Discovery -> R2 Evidence Expansion -> R3 Structural Trace`.
+
+- R0 handles known or narrowly identifiable targets.
+- R1 finds ranked candidates when intent is known but location is not.
+- R2 builds the smallest distributed evidence set required by unresolved claims.
+- R3 resolves relationship, flow, dependency, ownership, and impact questions.
+
+Depth represents the unresolved information problem. Tool names, brands, and installation methods do not belong in node identities or routing conditions. Every material conclusion must be verified in current source.
+
+Navigation has one narrower job: answer which bounded repository area should be searched. It must not absorb semantic search, evidence expansion, or graph tracing.
+
+## Capability providers
+
+Normal runtime use remains portable: use the strongest already-available provider appropriate to the current node, then fall back losslessly to bounded source search.
+
+Provider-enabled benchmark claims use `benchmarks/capability_manifest.json` and `benchmarks/dependency_tree_validation.py`. That profile requires `zg`, `codebase-memory-mcp`, and `rtk`; missing or failed providers abort the run. Provider probes, indexes, dependency resolution, and first-build warm-up occur before Codex starts and are never merged into compared token, duration, or tool-call fields.
+
+Do not weaken the benchmark by adding an allow-missing flag, silently falling back, estimating setup tokens, or resuming a measured cell without its matching `capability-setup.json` receipt.
 
 ## Evolution before wording
 
@@ -26,18 +49,16 @@ Do not add benchmark case nouns to runtime wording. A module must have an observ
 
 ## Benchmark discipline
 
-- Quality, safety, and build/reachability precede routing and cost.
+- Quality, safety, build/reachability, and environment parity 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.
+- Every arm in a paired task sees the same initialized providers and repository warm-up.
+- Setup is separately auditable but excluded from comparison; measured execution begins only after setup succeeds.
 - Add a test when a newly discovered mechanism or scorer invariant would otherwise regress.
 
-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.
-
-## 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.
+Public regression covers Delivery, Debug, Decision, Router, and Native Behavior. Real-repository held-out coverage validates delivered evidence, zero spontaneous manual activation, execution-node selection, progressive Retrieval disclosure, and provider use.
 
 ## Mature implementation first
 
-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.
+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 Core.