whetstone_DSL/sprint121_plan.md

Sprint 121 Plan: Deterministic MCP Debugging for SLM Agents

Context

The current generation + validation flow is strong, but the debugging path still expects high-skill interpretation of compile/test output. Large models can compensate; small/local SLM agents cannot. Sprint 121 makes debugging machine-directed and deterministic so low-context agents can reproduce, triage, patch, and verify with minimal ambiguity.

This sprint formalizes debugging as structured packets and explicit state transitions instead of ad-hoc stderr parsing.

---

Goals

1. Convert raw build/test failures into deterministic failure packets
2. Cluster symptom-level errors into root-cause-first groups
3. Generate patch proposals tied to failure class and local context slices
4. Provide an automated debug loop with bounded iterations and stop reasons
5. Capture replayable repro packets for training/eval and SLM readiness metrics

---

Steps

Step 1449: FailurePacket schema + normalizer (12 tests)

Create editor/src/debug/FailurePacket.h.

Define deterministic packet fields:

• packet_id
• failure_class (compile_error, test_assertion, runtime_error, tool_contract_error, schema_error, unknown)
• primary_file, primary_line, primary_symbol
• normalized_message
• repro_command
• first_failing_test
• confidence
• raw_excerpt

Add normalization rules:

• strip absolute paths to workspace-relative form
• canonicalize whitespace and duplicate diagnostics
• stable truncation (byte budget + suffix marker)

Tests (12): constructable defaults, enum parse/serialize, path canonicalization, whitespace normalization, duplicate diagnostic collapse, stable truncation, primary location extraction, first failing test extraction, confidence in range, JSON round-trip, deterministic packet_id for same input, deterministic output.

Step 1450: Root-cause clustering model (10 tests)

Create editor/src/debug/FailureClusterer.h.

Input: FailurePacket[]. Output: ordered FailureCluster[] with:

• cluster_id
• root_cause_candidate
• failure_class
• member_packet_ids[]
• blast_radius
• fix_first boolean

Heuristics:

• group by normalized symbol + file + class
• promote cluster with highest blast radius + earliest source location

Tests (10): single packet cluster, multi-packet same-cause cluster, multi-cause split, blast radius computed, fix_first only on top cluster, deterministic ordering, stable cluster ids, unknown class handled, JSON round-trip, deterministic output.

Step 1451: Fix-context assembler (tiny/small/medium) (10 tests)

Create editor/src/debug/FixContextAssembler.h.

Given a failure cluster, assemble minimal fix context:

• failing file slices
• nearest included headers
• nearest failing tests
• related schema/tool contract file snippets

Budgets:

• tiny <= 2k tokens equivalent
• small <= 6k
• medium <= 12k

Tests (10): tiny budget enforced, small budget enforced, medium budget enforced, includes primary failing span, includes nearest test span, excludes unrelated files under budget pressure, deterministic file ordering, deterministic span ordering, empty input returns empty context, deterministic output.

Step 1452: Patch proposal packet model (10 tests)

Create editor/src/debug/PatchProposal.h.

Define proposal shape:

• proposal_id
• failure_cluster_id
• patch_plan[] (ordered intents)
• candidate_diff (unified diff text)
• risk_level (low, medium, high)
• expected_tests_to_run[]
• invariants[]

Include deterministic validators:

• no edits outside allowed files
• diff format validity
• invariant list non-empty

Tests (10): constructable, ordered intents preserved, diff validation passes, out-of-scope edit rejected, risk level enum parse, expected tests populated, invariants required, JSON round-trip, deterministic proposal_id, deterministic output.

Step 1453: Failure-class-driven patch proposer (10 tests)

Create editor/src/debug/FailurePatchProposer.h.

Maps failure_class + context to template patch strategies:

• missing include/symbol -> include/namespace fix template
• schema mismatch -> key alignment template
• test assertion mismatch -> minimal behavior-preserving adjustment template
• tool contract error -> input schema/required field fix template

Emits PatchProposal with confidence and rationale.

Tests (10): include fix strategy selected, schema fix strategy selected, assertion strategy selected, tool contract strategy selected, unknown class fallback strategy, confidence populated, rationale populated, expected tests computed, deterministic strategy selection, deterministic output.

Step 1454: Repro packet archive + replay (8 tests)

Create editor/src/debug/ReproPacketStore.h.

Persist packet bundle:

• failure packet
• environment snapshot hash
• touched file hashes
• patch attempt history
• reproducible command metadata

Add replay loader to verify current failure class matches archived packet before attempting a new patch.

Tests (8): archive write succeeds, archive read succeeds, hash fields present, replay class match true on same fixture, replay mismatch flagged, history append works, JSONL export valid, deterministic output.

Step 1455: Regression guard planner (8 tests)

Create editor/src/debug/RegressionGuardPlanner.h.

Given touched files + active step id, produce deterministic guard set:

• must_pass[] (failing target + adjacent step tests)
• optional[]
• deferred[]

Include MCP registration smoke checks when MCP files are touched.

Tests (8): must_pass includes failing target, adjacent step tests selected, MCP smoke included when relevant, unrelated tests excluded, optional bucket populated when available, deferred bucket populated when budgeted, JSON round-trip, deterministic output.

Step 1456: whetstone_capture_failure_packet MCP tool (8 tests)

Input: { "command": string, "cwd": string?, "target": string? } Output: { "success": bool, "packet": FailurePacket?, "error"?: string }

Executes command in controlled mode, normalizes output into FailurePacket. No patching in this tool.

Tests (8): tool registered, missing command error, compile failure packet produced, test assertion packet produced, normalized path relative, first failing test present when applicable, bounded packet size, deterministic output.

Step 1457: whetstone_debug_until_green MCP orchestrator tool (8 tests)

Input: { "command": string, "max_iterations": int?, "context_budget": string?, "apply_patches": bool? } Output: { "status": "green"|"escalated"|"stopped", "iterations": int, "state_transitions": object[], "final_packet": FailurePacket?, "final_guard_report": object? }

State machine phases:

1. reproduce
2. capture
3. cluster
4. assemble context
5. propose patch
6. apply (optional)
7. rerun
8. guard

Tests (8): tool registered, respects max_iterations, returns green on fixable fixture, returns escalated on unfixable fixture, state transitions emitted, stop reason emitted, guard report included after apply, deterministic transitions.

Step 1458: Sprint 121 integration summary + regression (8 tests)

Create editor/src/Sprint121IntegrationSummary.h.

End-to-end fixture:

• intentionally broken test target
• run whetstone_capture_failure_packet
• run whetstone_debug_until_green with apply enabled
• verify state transitions + regression guard output + terminal status

Tests (8): headers constructable, tools registered, end-to-end deterministic fixture works, replay archive integration works, guard planner integration works, no header exceeds 600 lines, deterministic snapshots, full prior regression passes.

---

Architecture Gate

• All debugging packets are deterministic and machine-readable (no free-text-only outputs)
• Debug loop has explicit iteration cap and stop reasons; no unbounded loops
• Patch proposals must declare invariants and allowed file scope
• Replay packets contain enough metadata for offline training/eval reuse
• Tools must degrade safely: if uncertain, escalate with structured reason
• Max 600 lines per header