Fix #714: [Model] KClique

[GiggleLiu]

Summary

• Add the implementation plan for the KClique decision model

Fixes #714

[codecov]

Codecov Report

❌ Patch coverage is 97.43590% with 3 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (main@accbb66). Learn more about missing BASE report.
⚠️ Report is 4 commits behind head on main.

Files with missing lines	Patch %	Lines
src/models/graph/kclique.rs	95.45%	3 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #715   +/-   ##
=======================================
  Coverage        ?   97.61%           
=======================================
  Files           ?      393           
  Lines           ?    48790           
  Branches        ?        0           
=======================================
  Hits            ?    47628           
  Misses          ?     1162           
  Partials        ?        0           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[GiggleLiu]

Implementation Summary

Changes

• Added the new KClique graph satisfaction model with schema metadata, exported type wiring, default registry variant, and canonical example-db fixture.
• Added dedicated KClique unit tests covering construction, evaluation, solver behavior, serialization, and the paper/example witness.
• Added pred create KClique support in the CLI, including --graph/--k help text, validation, random-instance creation, and mirrored MCP create support.
• Added the $k$-Clique display name and problem-def("KClique") entry to the Typst paper using the canonical house-graph example.

Deviations from Plan

• Added the alias Clique in the model schema so decision-version references resolve naturally in the catalog and CLI.

Open Questions

• None.

[GiggleLiu]

Agentic Review Report

Structural Check

Structural Review: model KClique

Structural Completeness

#	Check	Status
1	Model file exists	PASS
2	inventory::submit! present	PASS
3	#[derive(...Serialize, Deserialize)] on struct	PASS
4	Problem trait impl	PASS
5	SatisfactionProblem impl	PASS
6	#[cfg(test)] + #[path = "..."] test link	PASS
7	Test file exists	PASS
8	Test file has >= 3 test functions	PASS
9	Registered in graph/mod.rs	PASS
10	Re-exported in models/mod.rs	PASS
11	declare_variants! entry exists	PASS
12	CLI resolve_alias entry	PASS
13	CLI create support	PASS
14	Canonical model example registered	PASS
15	Paper display-name entry	PASS
16	Paper problem-def block	PASS
17	Blacklisted auto-generated file check	PASS
18	Deterministic whitelist check	FAIL — files outside the model-PR whitelist were changed

Build Status

• make test: PASS
• make clippy: PASS

Semantic Review

• evaluate() correctness: OK — rejects wrong-length, non-binary, too-small, and non-clique configurations before returning true.
• dims() correctness: OK — returns one binary variable per vertex.
• Size getter consistency: OK — num_vertices() and num_edges() are present and consistent with the declared complexity metadata.
• Weight handling: OK — not applicable; KClique is an unweighted satisfaction problem.
• MCP coverage: ISSUE — new KClique creation paths were added in MCP, but the MCP test matrix was not extended.

Issue Compliance

#	Check	Status
1	Problem name matches issue	OK
2	Mathematical definition matches	OK
3	Problem type (opt/sat) matches	OK
4	Type parameters match	OK
5	Configuration space matches	OK
6	Feasibility check matches	OK
7	Objective function matches	OK
8	Complexity matches	OK

Summary

• 17/18 structural checks passed
• 8/8 issue compliance checks passed
• The provided completeness packet’s missing-item list does not match the current head: src/models/graph/kclique.rs and docs/paper/reductions.typ already contain the schema and paper entries it reported missing.
• FAIL — the PR exceeds the model-review whitelist by changing problemreductions-cli/src/cli.rs, problemreductions-cli/src/commands/create.rs, problemreductions-cli/src/mcp/tools.rs, and src/lib.rs outside the whitelist defined in scripts/pipeline_checks.py.
• ISSUE — problemreductions-cli/src/mcp/tools.rs and problemreductions-cli/src/mcp/tools.rs add new KClique MCP branches, but the create-problem coverage in problemreductions-cli/src/mcp/tests.rs was not extended, so the new MCP behavior is only compile-checked by this review’s build step.

---

Quality Check

Quality Review

Design Principles

• DRY: OK
• KISS: OK
• HC/LC: OK

HCI (if CLI/MCP changed)

• Error messages: OK
• Discoverability: ISSUE — The new MCP create_problem surface gives no way to specify total vertex count for KClique; problemreductions-cli/src/mcp/tools.rs:71 documents only edges and k, and problemreductions-cli/src/mcp/tools.rs:410 relies on problemreductions-cli/src/mcp/tools.rs:1249 to infer |V| from the largest endpoint. That makes graphs with isolated vertices undiscoverable and unrepresentable through MCP.
• Consistency: ISSUE — CLI and MCP now accept different KClique instance spaces. CLI parse_graph() preserves isolated vertices via --num-vertices at problemreductions-cli/src/commands/create.rs:3335 and problemreductions-cli/src/commands/create.rs:3376; MCP rejects the same logical instance once k exceeds the inferred endpoint count at problemreductions-cli/src/mcp/tools.rs:1264. Example: pred create KClique --graph 0-1,0-2,1-2 --num-vertices 5 --k 5 succeeds on CLI, but the MCP path would infer only 3 vertices from that edge list.
• Least surprise: ISSUE — The same edge list means different problems depending on entry point because only the CLI can preserve isolates; MCP silently shrinks the vertex set before validating k.
• Feedback: OK

Test Quality

• Naive test detection: ISSUE — Added coverage in problemreductions-cli/src/commands/create.rs:5215, problemreductions-cli/src/commands/create.rs:5252, and src/unit_tests/models/graph/kclique.rs:15 exercises direct CLI creation and model evaluation only. There is no KClique MCP create test next to the existing graph-create coverage at problemreductions-cli/src/mcp/tests.rs:216, and no isolated-vertex case covering --num-vertices, so the MCP/CLI divergence above would ship unnoticed.

Issues

Critical (Must Fix)

• OK

Important (Should Fix)

• MCP create_problem for KClique cannot represent valid instances with isolated vertices because it infers num_vertices from the edge list and then validates k against that smaller count at problemreductions-cli/src/mcp/tools.rs:410, problemreductions-cli/src/mcp/tools.rs:1249, and problemreductions-cli/src/mcp/tools.rs:1264. The CLI correctly supports the full instance space via problemreductions-cli/src/commands/create.rs:3335 and problemreductions-cli/src/commands/create.rs:3376.
• The new KClique tests do not cover the MCP creation branch or the isolated-vertex path, leaving the above regression unguarded at problemreductions-cli/src/commands/create.rs:5215 and problemreductions-cli/src/mcp/tests.rs:216.

Minor (Nice to Have)

• OK

Summary

• Important — MCP KClique creation cannot encode graphs with isolated vertices, so CLI and MCP disagree on the same problem family.
• Important — New KClique coverage misses MCP and isolated-vertex cases, leaving that behavioral mismatch untested.

---

Agentic Feature Tests

Feature-Test Report

Read-only run in /Users/jinguomini/rcode/problem-reductions/.worktrees/review-pr-715. I did not write a report file because this review was explicitly no-modify/read-only.

Date: 2026-03-21
Project type: Rust CLI + MCP server
Features tested: KClique CLI surface, KClique MCP surface
Profile: ephemeral downstream user
Use Case: discover KClique, create an instance via catalog/help/examples, and solve it through both CLI and MCP
Expected Outcome: KClique is discoverable as a new model, Clique alias works where useful, instance creation works, and the example can be solved end-to-end
Verdict: pass
Critical Issues: 0

Summary

Feature	Discoverable	Setup	Works	Expected Outcome Met	Doc Quality
KClique CLI	yes	yes	partial on default solve, yes with brute-force	yes	partial
KClique MCP	yes	yes	partial on default solve, yes with brute-force	yes	partial

Per-Feature Details

KClique CLI

• Role: downstream CLI user exploring a newly added problem type
• Use Case: find KClique, inspect it, create it from example/manual args, and solve it
• What I tried: pred list, pred show KClique, pred show Clique, pred create KClique, pred create --example KClique, pred create --example Clique, pred create KClique --graph 0-1,0-2,1-3,2-3,2-4,3-4 --k 3, and solving via pred solve
• Discoverability: good. pred list shows KClique/SimpleGraph with alias Clique; pred show KClique and pred show Clique both work; pred create KClique with no flags prints concise problem-specific help
• Setup: successful after building local pred in an isolated temp target with MCP enabled
• Functionality: creation worked through canonical name, alias, and --example; brute-force solve succeeded and returned solution [0,0,1,1,1] with evaluation true
• Expected vs Actual Outcome: expected outcome met, but only after using --solver brute-force; plain pred solve - failed with No reduction path from KClique to ILP... Try --solver brute-force
• Blocked steps: none
• Friction points: the generic default solve path does not work for this feature; users need the runtime hint to switch solvers
• Doc suggestions: add one KClique-specific end-to-end example and make the brute-force expectation more obvious

KClique MCP

• Role: downstream MCP client using the server tools directly
• Use Case: discover KClique in the tool catalog, inspect it, create via alias, and solve it
• What I tried: initialized pred mcp, confirmed tools/list, called list_problems, show_problem for KClique and Clique, create_problem for Clique, and solve with and without explicit solver
• Discoverability: good. MCP advertises the expected 10 tools; list_problems includes KClique with alias Clique
• Setup: successful
• Functionality: show_problem resolves both canonical and alias names to KClique; create_problem with problem_type: "Clique" works; brute-force solve works and returns the same satisfying solution; default solve returns an MCP tool error with the brute-force hint
• Expected vs Actual Outcome: expected outcome met with explicit brute-force solver
• Blocked steps: none
• Friction points: same default-solver trap as CLI
• Doc suggestions: add a KClique-focused MCP example and note that decision problems with no ILP path need brute-force

Issues Found

• Confirmed, low: the default solve path fails for KClique on both CLI and MCP because there is no ILP reduction path. This is recoverable and clearly hinted, so it is not a blocker.
• Confirmed, low: published docs are generic; there is no concrete KClique example in README.md, docs/src/cli.md, or docs/src/mcp.md.
• Blocked/not reproducible: none. An initial failed manual MCP probe was due incorrect client framing, not a server defect; the server worked once exercised with the transport format rmcp actually uses.

Suggestions

• Add one KClique end-to-end example to README.md and docs/src/cli.md: create plus --solver brute-force.
• Add one MCP example for KClique or Clique in docs/src/mcp.md.
• Surface the brute-force expectation earlier for zero-reduction decision problems, ideally before the user reaches a failed default solve.

---

Generated by review-pipeline