fix: use directed edges instead of bidirectional in reduction graph (#42)

* fix: use directed edges instead of bidirectional in reduction graph

The JSON export used a single edge with `bidirectional: true` for
reversible reductions, but the source/target direction depended on
non-deterministic inventory iteration order. This broke the Typst
paper's label resolution in CI (Deploy Documentation workflow).

Replace with two separate directed edges per reversible reduction.
This makes the JSON deterministic and the paper's link resolution
trivial. Add reduction-rule entries for the 5 newly-explicit reverse
directions.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* test: add negative assertion for removed bidirectional field

Address Copilot review comment: assert that the legacy "bidirectional"
field is absent in test_to_json_string to catch accidental regressions.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: update .claude/rules to match actual codebase APIs

Full audit of all rule files against source code:

- adding-models.md: Fix Problem trait template (was missing NAME,
  variant(), Size, num_flavors(), energy_mode(), solution_size();
  had non-existent is_valid_solution(); wrong import path for
  ProblemSize). Add specialized category.
- testing.md: Fix closed-loop test pattern to use actual API
  (ReduceTo::<T>::reduce_to, solution_size().is_valid). Remove
  stale cargo-tarpaulin reference (project uses cargo-llvm-cov).
- documentation.md: Fix problem-def signature (name, body not
  name, title). Fix reduction-rule params (example is bool, no
  overhead param). Note JSON-based examples, not Rust code.
- adding-reductions.md: Fix make export-graph -> cargo run.
- CLAUDE.md: Fix problem-def signature, add directed reduction note.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: simplify .claude/rules by pointing to reference implementations

Replace verbose pseudo-code templates with references to actual files
(kcoloring.rs, VC↔IS reduction, etc.) so rules stay in sync with code.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: GiggleLiu

.claude/CLAUDE.md

@@ -97,8 +97,9 @@ Reduction graph nodes use variant IDs: `ProblemName[/GraphType][/Weighted]`
 - Test naming: `test_<source>_to_<target>_closed_loop`
 
 ### Paper (docs/paper/reductions.typ)
-- `problem-def(name, title, body)` — defines a problem with auto-generated schema, reductions list, and label `<def:ProblemName>`
-- `reduction-rule(source, target, ...)` — generates a theorem with label `<thm:Source-to-Target>` and registers in `covered-rules` state
+- `problem-def(name)[body]` — defines a problem with auto-generated schema, reductions list, and label `<def:ProblemName>`. Title comes from `display-name` dict.
+- `reduction-rule(source, target, example: bool, ...)[rule][proof]` — generates a theorem with label `<thm:Source-to-Target>` and registers in `covered-rules` state. Overhead auto-derived from JSON edge data.
+- Every directed reduction needs its own `reduction-rule` entry
 - Completeness warnings auto-check that all JSON graph nodes/edges are covered in the paper
 - `display-name` dict maps `ProblemName` to display text
 

.claude/rules/adding-models.md

@@ -5,55 +5,23 @@ paths:
 
 # Adding a Model (Problem Type)
 
-## 1. Define the Model
-Create `src/models/<category>/<name>.rs`:
-
-```rust
-use serde::{Deserialize, Serialize};
-use crate::traits::{Problem, ProblemSize};
-
-#[derive(Clone, Debug, Serialize, Deserialize)]
-pub struct MyProblem<W> {
-    // Problem data fields
-    pub size: usize,
-    pub weights: Vec<W>,
-    // ...
-}
-
-impl<W: Clone> Problem for MyProblem<W> {
-    fn num_variables(&self) -> usize { ... }
-    fn problem_size(&self) -> ProblemSize { ... }
-    fn is_valid_solution(&self, solution: &[usize]) -> bool { ... }
-}
-```
-
-## 2. Register in Module
-Add to `src/models/<category>/mod.rs`:
-```rust
-mod my_problem;
-pub use my_problem::MyProblem;
-```
-
-## 3. Categories
-Place models in appropriate category:
-- `src/models/satisfiability/` - Satisfiability, KSatisfiability, CircuitSAT
-- `src/models/graph/` - MaximumIndependentSet, MinimumVertexCover, KColoring, etc.
-- `src/models/set/` - MinimumSetCovering, MaximumSetPacking
-- `src/models/optimization/` - SpinGlass, QUBO, ILP
-
-## 4. Required Traits
-- `Serialize`, `Deserialize` - JSON I/O support
-- `Clone`, `Debug` - Standard Rust traits
-- `Problem` - Core trait with `num_variables()`, `problem_size()`, `is_valid_solution()`
-- Consider `ConstraintSatisfactionProblem` if applicable
-
-## 5. Naming
-Use explicit optimization prefixes: `Maximum` for maximization, `Minimum` for minimization (e.g., `MaximumIndependentSet`, `MinimumVertexCover`).
+**Reference implementation:** `src/models/graph/kcoloring.rs`
+
+## Steps
+
+1. **Create** `src/models/<category>/<name>.rs` — follow the reference for struct definition, `Problem` impl, and optionally `ConstraintSatisfactionProblem` impl.
+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...]`.
 
-## 6. Documentation
-Document in `docs/paper/reductions.typ` using `#problem-def("ProblemName", "Display Title")[...]`
+## Categories
 
-## Anti-patterns
-- Don't create models without JSON serialization support
-- Don't forget to implement `is_valid_solution()` correctly
-- Don't use concrete types when generic `W` is appropriate
+- `src/models/satisfiability/` — Satisfiability, KSatisfiability, CircuitSAT
+- `src/models/graph/` — MaximumIndependentSet, MinimumVertexCover, KColoring, etc.
+- `src/models/set/` — MinimumSetCovering, MaximumSetPacking
+- `src/models/optimization/` — SpinGlass, QUBO, ILP
+- `src/models/specialized/` — Factoring
+
+## Naming
+
+Use explicit optimization prefixes: `Maximum` for maximization, `Minimum` for minimization (e.g., `MaximumIndependentSet`, `MinimumVertexCover`).

.claude/rules/adding-reductions.md

@@ -3,104 +3,45 @@ paths:
   - "src/rules/**/*.rs"
 ---
 
-# Adding a Reduction Rule (A → B)
+# Adding a Reduction Rule (A -> B)
 
-## 0. Brainstorm & Generate Test Data First
+**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`)
 
-Before writing any Rust code, follow this workflow:
+## 0. Before Writing Code
 
-1. **Brainstorm the reduction** — use `superpowers:brainstorming` to discuss with the user:
-   - Research the mathematical formulation (paper, textbook, or derive it)
-   - Understand the variable mapping and constraint encoding
-   - Discuss implementation approach: penalty values, matrix construction, solution extraction
-   - Read reference implementations in the codebase (e.g., `src/rules/spinglass_qubo.rs`) to understand conventions
-   - Agree on scope (weighted vs unweighted, specific graph types, const generics)
-2. **Generate ground truth test data** — use an existing library (e.g., Python with qubogen, qubovert, or networkx) to create small instances, reduce them, brute-force solve both sides, and export as JSON to `tests/data/<target>/`. It is recommended to download the relevant package and check the existing tests to understand how to construct tests. To generate the test data, you can use the following command:
-   ```bash
-   # Example: generate QUBO test data
-   cd scripts && uv run python generate_qubo_tests.py
-   ```
-3. **Create a practical example** — design a small, explainable instance for `examples/` (e.g., "wireless tower placement" for MaximumIndependentSet, "map coloring" for KColoring). This example will also appear in the `docs/paper/reductions.typ`.
-4. **Write the implementation plan** — save to `docs/plans/` using `superpowers:writing-plans`. The plan must include implementation details from the brainstorming session (formulas, penalty terms, matrix construction, variable indexing).
+1. **Brainstorm** — use `superpowers:brainstorming` to discuss with the user:
+   - The math (variable mapping, constraint encoding, penalty terms)
+   - Which example instance to use in `examples/` (must be small, human-explainable, and agreed with the user)
+2. **Generate ground truth** — use Python scripts in `scripts/` (run with `uv`) to create test data in `tests/data/<target>/`.
+3. **Write plan** — save to `docs/plans/` using `superpowers:writing-plans`.
 
-## 1. Implementation
+## 1. Implement
 
-Create `src/rules/<source>_<target>.rs` following the pattern in `src/rules/spinglass_qubo.rs`:
+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
 
-```rust
-use crate::reduction;
+Register in `src/rules/mod.rs`.
 
-#[derive(Debug, Clone)]
-pub struct ReductionSourceToTarget {
-    target: TargetProblem<...>,
-    source_size: ProblemSize,
-    // + any metadata needed for extract_solution
-}
+## 2. Test
 
-impl ReductionResult for ReductionSourceToTarget {
-    type Source = SourceProblem<...>;
-    type Target = TargetProblem<...>;
-
-    fn target_problem(&self) -> &Self::Target { &self.target }
-    fn extract_solution(&self, target_solution: &[usize]) -> Vec<usize> { ... }
-    fn source_size(&self) -> ProblemSize { self.source_size.clone() }
-    fn target_size(&self) -> ProblemSize { self.target.problem_size() }
-}
-
-#[reduction(
-    overhead = { ReductionOverhead::new(vec![...]) }
-)]
-impl ReduceTo<TargetProblem<...>> for SourceProblem<...> {
-    type Result = ReductionSourceToTarget;
-    fn reduce_to(&self) -> Self::Result { ... }
-}
-
-#[cfg(test)]
-#[path = "../unit_tests/rules/<source>_<target>.rs"]
-mod tests;
-```
-
-The `#[reduction]` macro auto-generates the `inventory::submit!` call. Optional attributes: `source_graph`, `target_graph`, `source_weighted`, `target_weighted`.
-
-Register module in `src/rules/mod.rs`:
-```rust
-mod source_target;
-pub use source_target::ReductionSourceToTarget;
-```
-
-## 2. Tests (Required)
-
-- **Unit tests** in `src/unit_tests/rules/<source>_<target>.rs` — closed-loop + edge cases. See `rules/testing.md`.
-- **Integration tests** in `tests/suites/reductions.rs` — compare against JSON ground truth from step 0.
-- Test name: `test_<source>_to_<target>_closed_loop`
+- **Unit tests** in `src/unit_tests/rules/<source>_<target>.rs` — closed-loop + edge cases (see reference test).
+- **Integration tests** in `tests/suites/reductions.rs` — compare against JSON ground truth.
 
 ## 3. Example Program
 
-Add a round-trip demo to `examples/` showing a practical, explainable instance:
-1. Create source problem with a real-world story
-2. Reduce to target, solve, extract solution
-3. Print human-readable explanation
+Add `examples/reduction_<source>_to_<target>.rs` — create, reduce, solve, extract, verify, export JSON (see reference example).
 
-## 4. Documentation
+## 4. Document
 
-Update `docs/paper/reductions.typ` (see `rules/documentation.md` for the pattern):
-- Add `reduction-rule("Source", "Target", ...)` theorem with proof sketch
-- Add Rust code example from the example program
-- Add `display-name` entry if the problem is new
+Update `docs/paper/reductions.typ` — add `reduction-rule("Source", "Target", ...)` with proof sketch (see `rules/documentation.md`).
 
-The goal is to 1. prove the correctness of the reduction to human beings. 2. provide a minimal working example to the readers.
+## 5. Regenerate Graph
 
-Citations must be verifiable. Use `[Folklore]` or `—` for trivial reductions.
-
-## 5. Regenerate Reduction Graph
 ```bash
-make export-graph
+cargo run --example export_graph
 ```
-
-## Anti-patterns
-- Don't write Rust code before understanding the math and having test data
-- Don't create reductions without closed-loop tests
-- Don't forget `inventory::submit!` registration (reduction graph won't update)
-- Don't hardcode weights - use generic `W` parameter
-- Don't skip overhead polynomial specification
-- Don't skip the example program — every reduction needs an explainable demo

.claude/rules/documentation.md

@@ -5,50 +5,32 @@ paths:
 
 # Documentation Requirements
 
-The technical paper (`docs/paper/reductions.typ`) must include:
-
-1. **Problem Definitions** — using `problem-def` wrapper
-2. **Reduction Theorems** — using `reduction-rule` function
-3. **Reduction Examples** — minimal working example showing reduce → solve → extract
+**Reference:** search `docs/paper/reductions.typ` for `MinimumVertexCover` `MaximumIndependentSet` to see a complete problem-def + reduction-rule example.
 
 ## Adding a Problem Definition
 
 ```typst
-#problem-def("MaximumIndependentSet", "Maximum Independent Set (MIS)")[
+#problem-def("ProblemName")[
   Mathematical definition...
 ]
 ```
 
-This auto-generates:
-- A label `<def:MaximumIndependentSet>` for cross-references
-- The problem's schema (fields from Rust struct)
-- The list of available reductions
-
-Also add an entry to the `display-name` dictionary:
+Also add to the `display-name` dictionary:
 ```typst
-"MaximumIndependentSet": "MIS",
+"ProblemName": [Problem Name],
 ```
 
 ## Adding a Reduction Theorem
 
 ```typst
-#reduction-rule(
-  "MaximumIndependentSet", "QUBO",
-  example: "maximumindependentset_to_qubo",
-  overhead: (n: 0, m: 1),
+#reduction-rule("Source", "Target",
+  example: true,
+  example-caption: [caption text],
 )[
+  Rule statement...
+][
   Proof sketch...
 ]
 ```
 
-This auto-generates:
-- A theorem label `<thm:MaximumIndependentSet-to-QUBO>`
-- References to source/target problem definitions (if they exist)
-- Registration in `covered-rules` state for completeness checking
-- The example code block from `examples/reduction_<example>.rs`
-
-## Completeness Warnings
-
-The paper auto-checks completeness:
-- After Problem Definitions: warns if JSON graph nodes are missing from `display-name`
-- After Reductions section: warns if JSON graph edges are missing from `covered-rules`
+Every directed reduction in the graph needs its own `reduction-rule` entry. The paper auto-checks completeness against `reduction_graph.json`.

.claude/rules/testing.md

@@ -1,54 +1,18 @@
 # Testing Requirements
 
-## Coverage Requirement
-New code must have >95% test coverage.
+**Reference test:** `src/unit_tests/rules/minimumvertexcover_maximumindependentset.rs`
 
-```bash
-# Check coverage for specific module
-cargo tarpaulin --features ilp --skip-clean --ignore-tests -- <module_name>
+## Coverage
 
-# Generate full HTML report
-make coverage
-```
+New code must have >95% test coverage. Run `make coverage` to check.
+
+## Naming
 
-## Test Naming Conventions
 - Reduction tests: `test_<source>_to_<target>_closed_loop`
 - Model tests: `test_<model>_basic`, `test_<model>_serialization`
 - Solver tests: `test_<solver>_<problem>`
 
-## Closed-Loop Test Pattern
-Every reduction MUST have a closed-loop test:
-
-```rust
-#[test]
-fn test_source_to_target_closed_loop() {
-    // 1. Create small instance
-    let problem = SourceProblem::new(...);
-
-    // 2. Reduce
-    let reduction = problem.reduce_to::<TargetProblem>();
-    let target = reduction.target_problem();
-
-    // 3. Solve target
-    let solver = BruteForce::new();
-    let solutions = solver.find_best(target);
-
-    // 4. Extract and verify
-    for sol in solutions {
-        let extracted = reduction.extract_solution(&sol);
-        assert!(problem.is_valid_solution(&extracted));
-    }
-}
-```
-
-## Before Submitting PR
-```bash
-make test      # All tests pass
-make clippy    # No warnings
-make coverage  # >95% for new code
-```
-
-## Test File Organization
+## File Organization
 
 Unit tests live in `src/unit_tests/`, mirroring `src/` structure. Source files reference them via `#[path]`:
 
@@ -59,12 +23,10 @@ Unit tests live in `src/unit_tests/`, mirroring `src/` structure. Source files r
 mod tests;
 ```
 
-The `#[path]` is relative to the source file's directory. `use super::*` in the test file resolves to the parent module (same as inline tests).
+Integration tests are in `tests/suites/`, consolidated through `tests/main.rs`.
 
-Integration tests are consolidated into a single binary at `tests/main.rs`, with test modules in `tests/suites/`.
+## Before PR
 
-## Anti-patterns
-- Don't skip closed-loop tests for reductions
-- Don't test only happy paths - include edge cases
-- Don't ignore clippy warnings
-- Don't add inline `mod tests` blocks in `src/` — use `src/unit_tests/` with `#[path]`
+```bash
+make test clippy
+```