CodingThrust
diff --git a/‎.claude/CLAUDE.md‎
Lines changed: 25 additions & 23 deletions b/‎.claude/CLAUDE.md‎
Lines changed: 25 additions & 23 deletions
diff --git a/‎.claude/rules/adding-models.md‎
Lines changed: 22 additions & 2 deletions b/‎.claude/rules/adding-models.md‎
Lines changed: 22 additions & 2 deletions
diff --git a/‎.claude/rules/adding-reductions.md‎
Lines changed: 18 additions & 7 deletions b/‎.claude/rules/adding-reductions.md‎
Lines changed: 18 additions & 7 deletions
diff --git a/‎.claude/rules/testing.md‎
Lines changed: 25 additions & 1 deletion b/‎.claude/rules/testing.md‎
Lines changed: 25 additions & 1 deletion
diff --git a/‎.gitignore‎
Lines changed: 3 additions & 0 deletions b/‎.gitignore‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎Makefile‎
Lines changed: 29 additions & 1 deletion b/‎Makefile‎
Lines changed: 29 additions & 1 deletion
diff --git a/‎benches/solver_benchmarks.rs‎
Lines changed: 10 additions & 9 deletions b/‎benches/solver_benchmarks.rs‎
Lines changed: 10 additions & 9 deletions
@@ -34,47 +34,49 @@ make test clippy  # Must pass before PR
 - `src/models/` - Problem implementations (SAT, Graph, Set, Optimization)
 - `src/rules/` - Reduction rules + inventory registration
 - `src/solvers/` - BruteForce solver, ILP solver (feature-gated)
-- `src/traits.rs` - `Problem`, `ConstraintSatisfactionProblem` traits
+- `src/traits.rs` - `Problem`, `OptimizationProblem` traits
 - `src/rules/traits.rs` - `ReduceTo<T>`, `ReductionResult` traits
 - `src/registry/` - Compile-time reduction metadata collection
 - `src/unit_tests/` - Unit test files (mirroring `src/` structure, referenced via `#[path]`)
-- `tests/main.rs` - Integration tests (modules in `tests/suites/`)
+- `tests/main.rs` - Integration tests (modules in `tests/suites/`); example tests use `include!` for direct invocation (no subprocess)
 - `tests/data/` - Ground truth JSON for integration tests
 - `scripts/` - Python test data generation scripts (managed with `uv`)
 - `docs/plans/` - Implementation plans
 
 ### Trait Hierarchy
 
 ```
-Problem (core trait - all problems must implement)
+Problem (core trait — all problems must implement)
 │
-├── const NAME: &'static str           // Problem name, e.g., "MaximumIndependentSet"
-├── type GraphType: GraphMarker        // Graph topology marker
-├── type Weight: NumericWeight         // Weight type (i32, f64, Unweighted)
-├── type Size                          // Objective value type
+├── const NAME: &'static str           // e.g., "MaximumIndependentSet"
+├── type Metric: Clone                 // SolutionSize<W> for optimization, bool for satisfaction
+├── fn dims(&self) -> Vec<usize>       // config space: [2, 2, 2] for 3 binary variables
+├── fn evaluate(&self, config) -> Metric
+├── fn variant() -> Vec<(&str, &str)>  // [("graph","SimpleGraph"), ("weight","i32")]
+└── fn num_variables(&self) -> usize   // default: dims().len()
+
+OptimizationProblem : Problem<Metric = SolutionSize<Self::Value>> (extension for optimization)
 │
-├── fn num_variables(&self) -> usize
-├── fn num_flavors(&self) -> usize     // Usually 2 for binary problems
-├── fn problem_size(&self) -> ProblemSize
-├── fn energy_mode(&self) -> EnergyMode
-├── fn solution_size(&self, config) -> SolutionSize
-└── ... (default methods: variables, flavors, is_valid_config)
-
-ConstraintSatisfactionProblem : Problem (extension for CSPs)
-│
-├── fn constraints(&self) -> Vec<LocalConstraint>
-├── fn objectives(&self) -> Vec<LocalSolutionSize>
-├── fn weights(&self) -> Vec<Self::Size>
-├── fn set_weights(&mut self, weights)
-├── fn is_weighted(&self) -> bool
-└── ... (default methods: is_satisfied, compute_objective)
+├── type Value: PartialOrd + Clone     // inner objective type (i32, f64, etc.)
+└── fn direction(&self) -> Direction   // Maximize or Minimize
+```
+
+**Satisfaction problems** (e.g., `Satisfiability`) use `Metric = bool` and do not implement `OptimizationProblem`.
+
+**Optimization problems** (e.g., `MaximumIndependentSet`) use `Metric = SolutionSize<W>` where:
+```rust
+enum SolutionSize<T> { Valid(T), Invalid }  // Invalid = infeasible config
+enum Direction { Maximize, Minimize }
 ```
 
 ### Key Patterns
 - Problems parameterized by weight type `W` and graph type `G`
 - `ReductionResult` provides `target_problem()` and `extract_solution()`
+- `Solver::find_best()` for optimization problems, `Solver::find_satisfying()` for `Metric = bool`
 - Graph types: SimpleGraph, GridGraph, UnitDiskGraph, Hypergraph
 - Weight types: `Unweighted` (marker), `i32`, `f64`
+- Weight management via inherent methods (`weights()`, `set_weights()`, `is_weighted()`), not traits
+- `NumericSize` supertrait bundles common numeric bounds (`Clone + Default + PartialOrd + Num + Zero + Bounded + AddAssign + 'static`)
 
 ### Problem Names
 Problem types use explicit optimization prefixes:
@@ -94,7 +96,7 @@ Reduction graph nodes use variant IDs: `ProblemName[/GraphType][/Weighted]`
 ### File Naming
 - Reduction files: `src/rules/<source>_<target>.rs` (e.g., `maximumindependentset_qubo.rs`)
 - Model files: `src/models/<category>/<name>.rs` (e.g., `maximum_independent_set.rs`)
-- Example files: `examples/reduction_<source>_to_<target>.rs`
+- Example files: `examples/reduction_<source>_to_<target>.rs` (must have `pub fn run()` + `fn main() { run() }`)
 - Test naming: `test_<source>_to_<target>_closed_loop`
 
 ### Paper (docs/paper/reductions.typ)
 
@@ -5,15 +5,35 @@ paths:
 
 # Adding a Model (Problem Type)
 
-**Reference implementation:** `src/models/graph/kcoloring.rs`
+**Reference implementations — read these first:**
+- **Optimization problem:** `src/models/graph/maximum_independent_set.rs` — `Problem` + `OptimizationProblem` with `Metric = SolutionSize<W>`
+- **Satisfaction problem:** `src/models/satisfiability/sat.rs` — `Problem` with `Metric = bool`
+- **Reference test:** `src/unit_tests/models/graph/maximum_independent_set.rs`
 
 ## Steps
 
-1. **Create** `src/models/<category>/<name>.rs` — follow the reference for struct definition, `Problem` impl, and optionally `ConstraintSatisfactionProblem` impl.
+1. **Create** `src/models/<category>/<name>.rs` — follow the reference for struct definition, `Problem` impl, and `OptimizationProblem` impl (if applicable).
 2. **Register** in `src/models/<category>/mod.rs`.
 3. **Add tests** in `src/unit_tests/models/<category>/<name>.rs` (linked via `#[path]`).
 4. **Document** in `docs/paper/reductions.typ`: add `display-name` entry and `#problem-def("Name")[definition...]`.
 
+## Trait Implementations
+
+Every problem must implement `Problem` (see `src/traits.rs`). Key points:
+
+- **`type Metric`** — `SolutionSize<W>` for optimization, `bool` for satisfaction
+- **`fn dims()`** — configuration space dimensions (e.g., `vec![2; n]` for n binary variables)
+- **`fn evaluate()`** — return `SolutionSize::Valid(value)` / `SolutionSize::Invalid` for optimization, or `bool` for satisfaction
+- **`fn variant()`** — graph and weight type metadata for the reduction registry
+
+Optimization problems additionally implement `OptimizationProblem` (see `src/traits.rs`):
+- **`type Value`** — the inner objective type (e.g., `i32`, `f64`, `W`)
+- **`fn direction()`** — `Direction::Maximize` or `Direction::Minimize`
+
+The supertrait `Problem<Metric = SolutionSize<Self::Value>>` ensures the solver can call `metric.is_valid()` and `metric.is_better()` directly — no per-problem customization needed.
+
+Weight management (`weights()`, `set_weights()`, `is_weighted()`) goes on inherent `impl` blocks, not traits. See the reference implementation for the pattern.
+
 ## Categories
 
 - `src/models/satisfiability/` — Satisfiability, KSatisfiability, CircuitSAT
 
@@ -5,10 +5,12 @@ paths:
 
 # Adding a Reduction Rule (A -> B)
 
-**Reference implementation:** `src/rules/minimumvertexcover_maximumindependentset.rs`
-**Reference test:** `src/unit_tests/rules/minimumvertexcover_maximumindependentset.rs`
-**Reference example:** `examples/reduction_minimumvertexcover_to_maximumindependentset.rs`
-**Reference paper entry:** `docs/paper/reductions.typ` (search for `MinimumVertexCover` `MaximumIndependentSet`)
+**Reference implementations — read these first:**
+- **Reduction rule:** `src/rules/minimumvertexcover_maximumindependentset.rs` — `ReductionResult` + `ReduceTo` + `#[reduction]` macro
+- **Unit test:** `src/unit_tests/rules/minimumvertexcover_maximumindependentset.rs` — closed-loop + edge cases
+- **Example program:** `examples/reduction_minimumvertexcover_to_maximumindependentset.rs` — create, reduce, solve, extract, verify, export
+- **Paper entry:** `docs/paper/reductions.typ` (search for `MinimumVertexCover` `MaximumIndependentSet`)
+- **Traits:** `src/rules/traits.rs` — `ReductionResult` and `ReduceTo` trait definitions
 
 ## 0. Before Writing Code
 
@@ -21,9 +23,10 @@ paths:
 ## 1. Implement
 
 Create `src/rules/<source>_<target>.rs` following the reference. Key pieces:
-- `ReductionResult` struct + impl (`target_problem`, `extract_solution`, `source_size`, `target_size`)
-- `#[reduction(...)]` macro on `ReduceTo<Target> for Source` impl (auto-generates `inventory::submit!`)
-- `#[cfg(test)] #[path = ...]` linking to unit tests
+
+- **`ReductionResult` struct + impl** — `target_problem()` + `extract_solution()` (see reference)
+- **`ReduceTo` impl with `#[reduction(...)]` macro** — auto-generates `inventory::submit!`; only `overhead` attribute needed (graph/weight types are inferred, defaulting to `SimpleGraph`/`Unweighted`)
+- **`#[cfg(test)] #[path = ...]`** linking to unit tests
 
 Register in `src/rules/mod.rs`.
 
@@ -36,6 +39,14 @@ Register in `src/rules/mod.rs`.
 
 Add `examples/reduction_<source>_to_<target>.rs` — create, reduce, solve, extract, verify, export JSON (see reference example).
 
+Examples must expose `pub fn run()` with `fn main() { run() }` so they can be tested directly via `include!` (no subprocess). Use regular comments (`//`) not inner doc comments (`//!`), and hardcode the example name instead of using `env!("CARGO_BIN_NAME")`.
+
+Register the example in `tests/suites/examples.rs` by adding:
+```rust
+example_test!(reduction_<source>_to_<target>);
+example_fn!(test_<source>_to_<target>, reduction_<source>_to_<target>);
+```
+
 ## 4. Document
 
 Update `docs/paper/reductions.typ` — add `reduction-rule("Source", "Target", ...)` with proof sketch (see `rules/documentation.md`).
 
@@ -1,6 +1,10 @@
 # Testing Requirements
 
-**Reference test:** `src/unit_tests/rules/minimumvertexcover_maximumindependentset.rs`
+**Reference implementations — read these first:**
+- **Reduction test:** `src/unit_tests/rules/minimumvertexcover_maximumindependentset.rs` — closed-loop pattern
+- **Model test:** `src/unit_tests/models/graph/maximum_independent_set.rs` — evaluation, serialization
+- **Solver test:** `src/unit_tests/solvers/brute_force.rs` — `find_best` + `find_satisfying`
+- **Trait definitions:** `src/traits.rs` (`Problem`, `OptimizationProblem`), `src/solvers/mod.rs` (`Solver`)
 
 ## Coverage
 
@@ -12,6 +16,14 @@ New code must have >95% test coverage. Run `make coverage` to check.
 - Model tests: `test_<model>_basic`, `test_<model>_serialization`
 - Solver tests: `test_<solver>_<problem>`
 
+## Key Testing Patterns
+
+Follow the reference files above for exact API usage. Summary:
+
+- `solver.find_best(&problem)` — for optimization problems (`OptimizationProblem`, `Metric = SolutionSize<W>`)
+- `solver.find_satisfying(&problem)` — for satisfaction problems (`Metric = bool`)
+- `problem.evaluate(&config)` — returns `SolutionSize::Valid(value)` / `SolutionSize::Invalid` for optimization, `bool` for satisfaction
+
 ## File Organization
 
 Unit tests live in `src/unit_tests/`, mirroring `src/` structure. Source files reference them via `#[path]`:
@@ -25,6 +37,18 @@ mod tests;
 
 Integration tests are in `tests/suites/`, consolidated through `tests/main.rs`.
 
+## Example Tests
+
+**Reference:** `tests/suites/examples.rs` — macro-based test harness
+
+Example programs (`examples/reduction_*.rs`) are tested via `include!` in `tests/suites/examples.rs` — each example is compiled directly into the test binary (no subprocess overhead). Each example must expose a `pub fn run()` entry point. See any existing example (e.g., `examples/reduction_minimumvertexcover_to_maximumindependentset.rs`) for the pattern:
+
+- `pub fn run()` with logic + `fn main() { run() }`
+- Regular comments (`//`) not inner doc comments (`//!`)
+- Hardcoded example name, not `env!("CARGO_BIN_NAME")`
+
+The test harness auto-registers each example as a separate `#[test]`, so `cargo test` runs them in parallel.
+
 ## Before PR
 
 ```bash
 
@@ -74,3 +74,6 @@ pkgref/
 
 # Generated example outputs
 docs/paper/examples/
+
+# Claude Code logs
+claude-output.log
@@ -1,6 +1,6 @@
 # Makefile for problemreductions
 
-.PHONY: help build test fmt clippy doc mdbook paper examples clean coverage rust-export compare qubo-testdata export-schemas release
+.PHONY: help build test fmt clippy doc mdbook paper examples clean coverage rust-export compare qubo-testdata export-schemas release run-plan
 
 # Default target
 help:
@@ -22,6 +22,7 @@ help:
 	@echo "  export-schemas - Export problem schemas to JSON"
 	@echo "  qubo-testdata - Regenerate QUBO test data (requires uv)"
 	@echo "  release V=x.y.z - Tag and push a new release (triggers CI publish)"
+	@echo "  run-plan   - Execute a plan with Claude autorun (latest plan in docs/plans/)"
 
 # Build the project
 build:
@@ -146,3 +147,30 @@ compare: rust-export
 		echo "Julia: $$(jq '{nodes: .num_grid_nodes, overhead: .mis_overhead, tape: .num_tape_entries}' tests/data/$${graph}_triangular_trace.json)"; \
 		echo "Rust:  $$(jq '{nodes: .stages[3].num_nodes, overhead: .total_overhead, tape: ((.crossing_tape | length) + (.simplifier_tape | length))}' tests/data/$${graph}_rust_triangular.json)"; \
 	done
+
+# Run a plan with Claude
+# Usage: make run-plan [INSTRUCTIONS="..."] [OUTPUT=output.log] [AGENT_TYPE=claude]
+# PLAN_FILE defaults to the most recently modified file in docs/plans/
+INSTRUCTIONS ?=
+OUTPUT ?= claude-output.log
+AGENT_TYPE ?= claude
+
+run-plan:
+	PLAN_FILE ?= $(shell ls -t docs/plans/*.md 2>/dev/null | head -1)
+	@NL=$$'\n'; \
+	BRANCH=$$(git branch --show-current); \
+	if [ "$(AGENT_TYPE)" = "claude" ]; then \
+		PROCESS="1. Read the plan file$${NL}2. Use /subagent-driven-development to execute tasks$${NL}3. Push: git push origin $$BRANCH$${NL}4. Post summary"; \
+	else \
+		PROCESS="1. Read the plan file$${NL}2. Execute the tasks step by step. For each task, implement and test before moving on.$${NL}3. Push: git push origin $$BRANCH$${NL}4. Post summary"; \
+	fi; \
+	PROMPT="Execute the plan in '$${PLAN_FILE}'."; \
+	if [ -n "$(INSTRUCTIONS)" ]; then \
+		PROMPT="$${PROMPT}$${NL}$${NL}## Additional Instructions$${NL}$(INSTRUCTIONS)"; \
+	fi; \
+	PROMPT="$${PROMPT}$${NL}$${NL}## Process$${NL}$${PROCESS}$${NL}$${NL}## Rules$${NL}- Tests should be strong enough to catch regressions.$${NL}- Do not modify tests to make them pass.$${NL}- Test failure must be reported."; \
+	echo "=== Prompt ===" && echo "$$PROMPT" && echo "===" ; \
+	claude --dangerously-skip-permissions \
+		--model claude-opus-4-6 \
+		--max-turns 500 \
+		-p "$$PROMPT" 2>&1 | tee "$(OUTPUT)"
@@ -1,14 +1,14 @@
 //! Benchmarks for the BruteForce solver on various problem types.
 
 use criterion::{criterion_group, criterion_main, BenchmarkId, Criterion};
-use std::hint::black_box;
 use problemreductions::models::graph::*;
-use problemreductions::topology::SimpleGraph;
 use problemreductions::models::optimization::*;
 use problemreductions::models::satisfiability::*;
 use problemreductions::models::set::*;
 use problemreductions::models::specialized::*;
 use problemreductions::prelude::*;
+use problemreductions::topology::SimpleGraph;
+use std::hint::black_box;
 
 /// Benchmark MaximumIndependentSet on graphs of varying sizes.
 fn bench_independent_set(c: &mut Criterion) {
@@ -78,19 +78,19 @@ fn bench_satisfiability(c: &mut Criterion) {
             })
             .collect();
 
-        let problem = Satisfiability::<i32>::new(*num_vars, clauses);
+        let problem = Satisfiability::new(*num_vars, clauses);
         let solver = BruteForce::new();
 
         group.bench_with_input(BenchmarkId::new("3-sat", num_vars), num_vars, |b, _| {
-            b.iter(|| solver.find_best(black_box(&problem)))
+            b.iter(|| solver.find_all_satisfying(black_box(&problem)))
         });
     }
 
     group.finish();
 }
 
 /// Benchmark SpinGlass on varying sizes.
-#[allow(clippy::manual_is_multiple_of)] // Type inference issues with is_multiple_of
+#[allow(unknown_lints, clippy::manual_is_multiple_of)] // Type inference issues with is_multiple_of
 fn bench_spin_glass(c: &mut Criterion) {
     let mut group = c.benchmark_group("SpinGlass");
 
@@ -142,7 +142,7 @@ fn bench_coloring(c: &mut Criterion) {
         let solver = BruteForce::new();
 
         group.bench_with_input(BenchmarkId::new("path_3colors", n), n, |b, _| {
-            b.iter(|| solver.find_best(black_box(&problem)))
+            b.iter(|| solver.find_all_satisfying(black_box(&problem)))
         });
     }
 
@@ -194,13 +194,14 @@ fn bench_comparison(c: &mut Criterion) {
     let solver = BruteForce::new();
 
     // MaximumIndependentSet with 8 vertices
-    let is_problem = MaximumIndependentSet::<SimpleGraph, i32>::new(8, vec![(0, 1), (2, 3), (4, 5), (6, 7)]);
+    let is_problem =
+        MaximumIndependentSet::<SimpleGraph, i32>::new(8, vec![(0, 1), (2, 3), (4, 5), (6, 7)]);
     group.bench_function("MaximumIndependentSet", |b| {
         b.iter(|| solver.find_best(black_box(&is_problem)))
     });
 
     // SAT with 8 variables
-    let sat_problem = Satisfiability::<i32>::new(
+    let sat_problem = Satisfiability::new(
         8,
         vec![
             CNFClause::new(vec![1, 2, 3]),
@@ -210,7 +211,7 @@ fn bench_comparison(c: &mut Criterion) {
         ],
     );
     group.bench_function("Satisfiability", |b| {
-        b.iter(|| solver.find_best(black_box(&sat_problem)))
+        b.iter(|| solver.find_all_satisfying(black_box(&sat_problem)))
     });
 
     // SpinGlass with 8 spins