Design for a CLI tool targeting researchers/students to explore
NP-hard problem reductions without writing Rust code. Covers
graph exploration, solve/reduce/evaluate commands, slash-based
variant notation, and JSON/text output modes.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* Add CLI tool design document for `pred`

Design for a CLI tool targeting researchers/students to explore
NP-hard problem reductions without writing Rust code. Covers
graph exploration, solve/reduce/evaluate commands, slash-based
variant notation, and JSON/text output modes.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* Add CLI tool implementation plan for `pred`

12-task plan covering workspace scaffolding, problem name resolution,
clap command hierarchy, graph exploration commands, schema command,
integration tests, and Makefile target.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat: scaffold problemreductions-cli crate with pred binary

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(cli): add problem name resolver with aliases and variant parsing

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(cli): add output module for human/JSON output modes

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(cli): add clap command hierarchy for all subcommands

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(cli): implement 'pred graph list' command

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(cli): implement 'pred graph show' command

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(cli): implement 'pred graph path' command

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(cli): implement 'pred schema' command

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* build: add Makefile target for pred CLI tool

* test(cli): add integration tests for graph and schema commands

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix(cli): resolve clippy warnings in CLI crate

- Remove unused `emit` method (only `emit_with_default_name` is used)
- Replace `map_or(true, ...)` with `is_none_or(...)` (2 places)
- Change `&PathBuf` to `&Path` in export function signature

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* new docs

* refactor(rules): replace ExecutablePath+ChainedReduction with ReductionChain

Unify ExecutablePath<S,T>, ChainedReduction<S,T>, and make_executable
into a single untyped ReductionChain and reduce_along_path(). Callers
downcast when they need typed access.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(cli): add DynProblem dispatch table for runtime problem loading

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(cli): implement 'pred evaluate' command

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(cli): implement 'pred reduce' command with full reduction bundle

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* test(cli): add integration tests for evaluate and reduce commands

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* docs: document evaluate and reduce CLI commands

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* update

* update

* feat(cli): add solve command with ILP auto-reduction and configurable backends

- Add `pred solve` command supporting ILP (default) and brute-force solvers
- Auto-reduce non-ILP problems to ILP when using ILP solver
- Support solving reduction bundles (from `pred reduce`)
- Extract solve_with_ilp helper to eliminate duplicated auto-reduction logic
- Restructure feature flags: per-backend features (highs, coin-cbc, clarabel,
  scip, lpsolve, microlp) with ilp-solver marker feature
- Update CLI help text with examples and workflow guidance
- Update mdBook CLI documentation to match current commands
- Update CLAUDE.md with documentation locations

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* polish CLI help messages and fix CI

- Define each command's help text once in cli.rs (after_help)
- Show the same help on parse errors via Cli::command().find_subcommand()
- Remove duplicated error hints from main.rs
- Comprehensive examples covering all arguments and defaults
- Cross-reference input files to their producing commands
- Replace --all-features with --features ilp-highs in CI and Makefile
  (scip/cbc/lpsolve require system libraries not available in CI)

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(cli): implement --cost minimize:<field> and show size fields

- Wire up `pred path --cost minimize:<field>` to use `Minimize(field)`
  instead of always falling back to MinimizeSteps
- Add `size_field_names()` method to ReductionGraph
- Show size fields in `pred show` output so users know which fields
  are available for `--cost minimize:<field>`

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* test(cli): add comprehensive tests for solve, create, and error cases

Increase patch coverage from 68% to address codecov/patch failure.
Adds 25 new integration tests covering solve command (brute-force,
ILP, bundles, JSON output), create for more problem types (MaxCut,
MVC, KColoring, SpinGlass, 3SAT, MaximumMatching), error cases,
help messages, and path cost functions.

Also removes unnecessary "Use with" hint from size fields display.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* chore: remove completed plan files

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* docs: update CLI page to match actual command output

- Update `pred show` example with fields, size fields, description
- Fix Quick Start: use --solver brute-force for QUBO bundle
- Add overhead formulas to `pred path` examples
- Add note about ILP solver limitations for some problems
- Document `pred reduce` stdout behavior
- Add more `pred create` examples (SpinGlass, MaxCut)

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* ci: exclude CLI crate from codecov patch coverage

The CLI crate is a thin dispatch layer with many boilerplate
type-dispatch match arms (load_problem, serialize_any_problem).
These are tested end-to-end via 50 integration tests but don't
reach 95% line coverage due to the combinatorial number of
problem type × variant arms.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

---------

Co-authored-by: Claude Opus 4.6 <[email protected]>

* docs: add design and plan for QUBO→ILP and CircuitSAT→ILP reductions

Addresses issue #83 — adds ILP reduction paths for QUBO, SpinGlass,
MaxCut, and CircuitSAT.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat: add QUBO → ILP reduction via McCormick linearization

Implement reduction from QUBO to ILP using McCormick linearization for
binary quadratic terms. Diagonal Q_ii terms become linear x_i terms,
and each non-zero off-diagonal Q_ij (i<j) introduces an auxiliary
variable y_ij with three McCormick constraints enforcing y_ij = x_i * x_j.

Closes the ILP path for QUBO, SpinGlass, and MaxCut (issue #83).

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat: add CircuitSAT → ILP reduction via gate constraint encoding

Direct 1-step path, more efficient than CircuitSAT→SpinGlass→QUBO→ILP (issue #83).

Fix XOR test: CircuitSAT `c = x XOR y` constrains c == (x XOR y)
for all variable assignments (4 solutions), not just c=true (2 solutions).

* docs: add examples and paper entries for QUBO→ILP and CircuitSAT→ILP reductions

- Remove plan files (docs/plans/2026-02-18-ilp-*)
- Add reduction examples: reduction_qubo_to_ilp.rs (4-var McCormick)
  and reduction_circuitsat_to_ilp.rs (full adder gate encoding)
- Add reduction-rule entries in paper (reductions.typ) with proofs
- Regenerate reduction_graph.json with new edges
- Register both examples in tests/suites/examples.rs

Co-Authored-By: Claude Opus 4.6 <[email protected]>

---------

Co-authored-by: Claude Opus 4.6 <[email protected]>

* docs: add CLI v2 features design (issue #81)

Design for k-neighbor exploration, colored output, and shell completions.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* docs: add CLI v2 implementation plan (issue #81)

10-task plan covering shell completions, colored output, and k-neighbor
graph exploration for the pred CLI tool.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(cli): add shell completions command (bash/zsh/fish)

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* test(cli): add integration tests for shell completions

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(cli): add owo-colors dependency and color helper functions

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(cli): add aligned columns and color to pred list

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(cli): add colors to pred show output

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(cli): add colors to pred path output

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(lib): add k_neighbors BFS method to ReductionGraph

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(cli): add --hops and --direction flags to pred show for neighbor exploration

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* test(cli): add integration tests for k-neighbor exploration

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* chore: apply rustfmt formatting

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix: address PR review comments

- Remove unused `fmt_arrow_out()` dead code (Copilot review)
- Deduplicate `find_node_index()` by delegating to existing `lookup_node()`
- Extract table formatting into reusable `format_table()` helper in output.rs
- Remove `completions` command and `clap_complete` dependency (manual setup not useful)
- Update CLI documentation with new table output and k-neighbor exploration examples

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(cli): re-add completions with auto-detection and eval setup

Shell argument is now optional — auto-detects from $SHELL env.
Setup is just one line: eval "$(pred completions)"

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(cli): add problem name completion for shell tab-completion

Custom ProblemNameParser provides all registered problem names and
aliases as completion candidates while still accepting any string
(so MIS/UnitDiskGraph variant syntax works).

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix(cli): use left arrow for "Reduces from" and green for all arrows

Makes direction immediately clear: → for outgoing, ← for incoming.
Both arrows use green for visual consistency. Removes unused
fmt_incoming() function.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix(cli): add tab completion hint to pred --help

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(cli): make --to optional when --via is given in pred reduce

The target problem is already in the path file, so --to is redundant.
Now: pred reduce problem.json --via path.json -o reduced.json
Either --to or --via must be provided; error if neither is given.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(cli): unify solve output format for direct and bundle solving

Use consistent Problem/Solver/Solution/Evaluation format for both
direct problem solving and reduction bundle solving. Bundle solver
shows "via <target>" in solver description. Add hint about -o flag
for JSON output with intermediate results.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix(cli): print solve hint after output, not before

Move the -o hint eprintln to after emit_with_default_name so the hint
appears at the last line of terminal output.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix(cli): only show solve hint when stderr is a TTY

Suppress the "Hint: use -o to save full solution details as JSON."
message when stderr is piped, so scripts and non-interactive usage
are not cluttered with the hint. Interactive terminal users still
see it.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(cli): show auto-reduction info in solve human output

When solving a non-ILP problem with the ILP solver, the human text
output now shows "Solver: ilp (via ILP)" to indicate that auto-reduction
occurred. Previously this information was only visible in JSON output.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(cli): add global -q/--quiet flag to suppress stderr info

Add a -q/--quiet global flag that suppresses all informational messages
on stderr (hints, "Wrote..." messages, summary messages). Only errors
still go to stderr in quiet mode. This enables clean scripting usage.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(cli): print JSON to stdout when create is used without -o

Previously `pred create MIS --edges 0-1,1-2` printed "Created
MaximumIndependentSet instance" but discarded the actual data. Now it
prints the problem JSON to stdout, consistent with how `reduce` works
and enabling piping to other commands.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(cli): add fuzzy matching for unknown problem names

Add "Did you mean ...?" suggestions when a problem name is not
recognized, using Levenshtein edit distance. All "Unknown problem"
error sites now also suggest running `pred list`.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(cli): add --random flag for random problem instance generation

Support random Erdos-Renyi graph generation for graph-based problems
via `pred create <PROBLEM> --random --num-vertices N [--edge-prob P] [--seed S]`.
Uses a simple LCG PRNG with no external dependencies. Supported for
MIS, MVC, MaxCut, MaxClique, MaximumMatching, MinimumDominatingSet,
SpinGlass, KColoring, and TravelingSalesman.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(cli): add inspect, stdin support, --json reduce, export-graph consistency

Remaining changes from CLI UX improvement plan:
- P4: export-graph uses global -o flag instead of positional arg
- P7: accept - for stdin in solve, evaluate, reduce
- P2: human-readable reduce output by default, --json flag for raw JSON
- F1: new inspect command for problem/bundle introspection

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat: add cli-demo Makefile target for end-to-end CLI testing

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* chore: apply rustfmt formatting

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(cli): refactor show --hops --direction into pred to / pred from commands

Split neighbor exploration out of `pred show` into dedicated subcommands:
- `pred to MIS --hops 2` for outgoing neighbors
- `pred from QUBO --hops 1` for incoming neighbors

Tree output now shows variant-level information (e.g., `MIS {graph=SimpleGraph, weight=i32}`)
instead of just problem names. The `pred show` command is simplified to only inspect
problem details (variants, fields, reductions).

Resolves H2 from the CLI UX improvements audit.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(cli): add create Factoring and solve --timeout

- P8: Support `pred create Factoring --target 15 --bits-m 4 --bits-n 4`
  with all three flags required (replaces unhelpful bail message)
- H3: Add `--timeout <seconds>` to `pred solve` using thread+channel
  pattern (default 0 = no limit, process exits on timeout)
- Add 6 CLI tests for Factoring creation and timeout behavior
- Update cli-demo, docs, and audit file

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* refactor: unify name+variant formatting and move tree-building to core

- Add fmt_node() as single source of truth for "bold name + plain variant"
- Move neighbor tree BFS from CLI into ReductionGraph::k_neighbor_tree()
- Add NeighborTree type to core library
- Remove petgraph-exposing helpers (find_node_index, neighbor_indices, etc.)
- Remove petgraph dependency from CLI crate
- Fix path header not formatting names as bold

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* chore: remove completed CLI plan files

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(cli): add global --json flag for JSON output to stdout

All commands now support --json to print JSON to stdout. Previously
only `create` (always JSON) and `reduce` (per-command --json) did.

- Add `--json` as a global CLI flag on OutputConfig
- Update emit_with_default_name to handle -o / --json / human-text
- Remove per-command --json from ReduceArgs (now global)
- Wire path and path --all through emit or --json branch
- Update docs and after_help

Co-Authored-By: Claude Opus 4.6 <[email protected]>

---------

Co-authored-by: Claude Opus 4.6 <[email protected]>

--all-features enables ilp-scip which requires SCIP solver not
available in CI. Use --features ilp-highs to match the CI workflow.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

Adds a new skill that checks completeness and correctness of model/rule
implementations. Auto-detects what changed from git diff and runs
structural checks (file existence, registrations, test presence) plus
semantic review (evaluate correctness, overhead accuracy, example quality).

Called automatically at the end of add-model/add-rule, or standalone.

Closes #87

Co-Authored-By: Claude Opus 4.6 <[email protected]>

)

* fix: add MaximalIS to CLI dispatch table

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix: add missing re-exports for MaximumClique, ILP, KSatisfiability

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* refactor: rename rule tests to closed_loop convention

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* docs: add paper entries for MaximalIS, BMF, PaintShop, BicliqueCover and SAT to CircuitSAT rule

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat: add example programs for SAT→CircuitSAT, SP→MIS, KSAT→SAT

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix: use varying set sizes in SP→MIS example

The previous example used only size-2 sets, which is degenerate
(equivalent to a matching problem). Replace with 5 sets of sizes
2 and 3 over an 8-element universe for a more general demonstration.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

---------

Co-authored-by: Claude Opus 4.6 <[email protected]>

Co-Authored-By: Claude Opus 4.6 <[email protected]>

Co-Authored-By: Claude Opus 4.6 <[email protected]>