whetstone_DSL/FEATURE_REQUESTS.md

Feature Requests

Backlog of feature ideas to triage into future sprints (e.g., Sprint 6/7).

Security Vulnerability Awareness (Dependencies) — IMPLEMENTED (Sprint 6, Steps 190–195)

Goal: Warn when a dependency has known vulnerabilities and surface safer alternatives.

Concept:

• Maintain a vulnerability knowledge base (local cache + optional remote sources).
• When a dependency is added/updated, show immediate warnings.
• Surface findings in the Dependencies panel and Problems list.
• Optionally block auto-upgrade to vulnerable versions.

Potential Data Sources:

• OSV (Open Source Vulnerabilities) API / datasets
• NVD (CVE/NVD feeds)
• GitHub Security Advisories (GHSA)
• OWASP references (for categorization)

Candidate Data Model:

• VulnerabilityRecord
  • ecosystem (pypi/npm/crates/maven/go/vcpkg/etc)
  • package
  • affected_versions
  • severity
  • summary
  • references

UI/UX:

• Dependencies panel: inline warning badges and <20>View Advisory<72>.
• Problems panel: security diagnostics with severity.
• Agent hints: prefer safe alternatives when available.

---

Semantic Annotations for Library APIs — IMPLEMENTED (Sprint 6, Steps 193–194)

Goal: Tag library functions/types with semantic annotations (e.g., @serialize, @crypto, @io) so humans/agents can discover intent-driven APIs quickly.

Concept:

• Add annotation metadata for library symbols (by library + symbol).
• Attach annotations to ExternalModule / TypeSignature nodes.
• Use annotations to filter in Library Browser and guide agent completion.

Candidate Storage:

• annotations/library_semanno.json (or similar)
• Format: { library: { symbol: [annotations...] } }

UI/UX:

• Library Browser: filter by annotation tag.
• Completion ranking: prioritize annotated matches for task keywords.
• Agent prompts: <20>Use @serialize APIs<49> guidance.

---

Notes

• Treat these as separate features to schedule independently.
• Likely Sprint 6/7, after core library-aware flow is stable.

LLM Tooling & MCP Bridge — PLANNED (Sprint 7, Steps 202–234)

Goal: Make the agent API easy for LLMs to use and optionally expose it via MCP.

Status: Full plan written in sprint7_plan.md. 33 steps across 6 phases:

• Phase 7a: API documentation & JSON schemas (Steps 202–206)
• Phase 7b: MCP server with tools/resources/prompts (Steps 207–213)
• Phase 7c: Synthetic trace generation for training data (Steps 214–219)
• Phase 7d: Evaluation harness for LLM tool-use accuracy (Steps 220–224)
• Phase 7e: Model-specific tool definitions — Claude, Codex, open-source (Steps 225–229)
• Phase 7f: Session recording pipeline — capture, anonymize, export (Steps 230–234)

---

PHP Language Support (Full Pipeline) <20> PROPOSED

Goal: Add full PHP support (parse, AST, generate, project, and annotations) to Whetstone.

Scope:

• Tree-sitter PHP parser integration
• PHP AST mapping to SemAnno concepts
• PHP generator with annotation-aware output
• Cross-language projection to/from PHP
• Tests: parse/generate round-trip, annotation preservation, projection matrix coverage

Notes:

• Start with core PHP syntax (functions, classes, namespaces, arrays, exceptions, traits).
• WordPress-specific libraries on top of core PHP support.

---

WordPress Support (Library + Semantics) <20> PROPOSED

Goal: Enable WordPress-aware tooling on top of PHP support.

Scope:

• Library symbol stubs for WordPress core APIs
• Semantic tags for WP concepts (hooks, filters, actions)
• Agent suggestions for safe WP patterns

---

Rust Plugin Packaging (Conflict Resolver) <20> PROPOSED

Goal: Package a Rust-based topological conflict resolver as a Whetstone plugin.

Scope:

• Define plugin interface for external tools
• Packaging format and plugin discovery/loading
• Example integration with a Rust binary or shared library

Julia Language Support (Full Pipeline) <20> PROPOSED

Goal: Add full Julia support (parse, AST, generate, project, and annotations) to Whetstone.

Scope:

• Tree-sitter Julia parser integration
• Julia AST mapping to SemAnno concepts
• Julia generator with annotation-aware output
• Cross-language projection to/from Julia
• Tests: parse/generate round-trip, annotation preservation, projection matrix coverage

---

Julia ML Projection Layer <20> PROPOSED

Goal: Map common Python ML/Numerical APIs to Julia equivalents while preserving optimization intent.

Scope:

• API mapping table (NumPy/Pandas/Torch core calls ? Julia equivalents)
• Semantic tags for numerical/tensor operations
• Fallback interop for unmapped calls (PyCall/JuliaCall)
• Dual projections: clean surface Julia + preserved optimization annotations

Julia Packaging Strategy <20> PROPOSED

Goal: Define a reliable packaging path for Julia-based artifacts.

Scope:

• Document options: runtime install, PackageCompiler.jl, embedding Julia as a library
• Provide recommended defaults for CLI tools vs GUI apps
• Include guidance for minimizing startup latency and bundle size

Python/C++/JS-TS Support Enhancements <20> PROPOSED

Goal: Expand first-class support for Python, C++, and JS/TS beyond current parse/generate.

Scope:

• Improve language-specific projection fidelity and diagnostics
• Expand standard library and ecosystem stubs (pip/npm/vcpkg)
• Add language-specific refactor recipes and annotation guidance
• Strengthen test corpus and projection round-trip coverage

---

Plugin System Enhancements <20> PROPOSED

Goal: Expand plugin support for external tools and language packs.

Scope:

• Standardize plugin packaging format
• Document plugin API and lifecycle hooks
• Add plugin discovery and version compatibility checks
• Provide example plugins for language packs and external analyzers

---

Resource Lock Constraints on TaskItems — SPRINT 46 CANDIDATE

Filed by: HiveMind project agent (2026-02-21) Priority: High — blocks correct parallel scheduling Source spec: hivemind/docs/WHETSTONE_FEATURE_REQUEST_RESOURCE_LOCKS.md Components: AnnotatedTaskitem schema, whetstone_generate_taskitems, whetstone_queue_ready, whetstone_validate_taskitem

Problem: dependencyTaskIds models causal ordering (DAG edges). It does not model mutual exclusion — two tasks that cannot run concurrently because they share a resource, even though neither depends on the other's output. Without this, the scheduler must either serialize everything or rely on humans to catch conflicts. Both fail at scale.

Proposed schema addition:

interface AnnotatedTaskitem {
  // ... existing fields ...

  // NEW
  resourceLocks?: string[];  // Named resources held exclusively during execution.
                             // Tasks with overlapping locks are serialized by scheduler.
                             // Node-local by default. Prefix "global:" for swarm-wide mutex.
                             // Examples: "drone-process", "sqlite-db", "file:/path/to/f",
                             //           "global:nexus-jobs-queue"
}

Key distinction:

Field	Meaning	Relationship
dependencyTaskIds: [A]	A must finish before I start	Directed — A → B
resourceLocks: ["db"]	I need exclusive access to "db" while running	Undirected — A ↔ B

exclusionGroup as sugar: exclusionGroup: "X" expands to resourceLocks: ["group:X"]. One model, two syntaxes.

Lock scope convention (addition to original spec): All locks are node-local by default. Prefix global: for swarm-wide mutual exclusion. HiveMind's scheduler knows the dispatch target node and enforces accordingly.

Sprint 46 plan (5 steps):

1. Schema: add resourceLocks?: string[] to AnnotatedTaskitem
2. Generator: infer locks in TaskitemGeneratorV2 from spec signals ("both tests spin up a drone" → drone-process, "shared SQLite DB" → sqlite-db, "same port" → nexus-port-N)
3. MCP: surface locks in whetstone_generate_taskitems output
4. Queue: add resource_conflict_unresolved warning class to whetstone_queue_ready (warn on serialization, don't block)
5. Validation: whetstone_validate_taskitem checks lock name format, flags node-local vs global ambiguity

Precedent: GNU Make .NOTPARALLEL, Bazel tags=["exclusive"], GitHub Actions concurrency:, Kubernetes resource quotas, POSIX flock(2).

---

Deterministic MCP Debugging Workflow for SLM Agents — PROPOSED

Filed by: Whetstone execution session (2026-02-21) Priority: Critical for self-improving low-context agents Goal: Make generation + debugging robust enough that small/local models can complete tasks without expert intuition.

Why this matters

Current flow is strong for generation and validation, but debugging still relies heavily on manual compile/test interpretation. Strong agents can compensate; weaker agents cannot. The system needs deterministic failure triage and patch guidance, not just raw logs.

Feature Request A: Structured Failure Packet Tool

Tool name: whetstone_capture_failure_packet

Problem: Compile/test output is noisy and non-deterministic across environments. SLMs need compact, stable failure packets.

Requirements:

• Input: command, cwd, optional target (step707_test, etc.)
• Output packet fields:
  • failureClass (compile_error, test_assertion, schema_error, tool_contract_error, runtime_error)
  • primaryFile, primaryLine, primarySymbol
  • normalizedMessage (deduped, canonicalized)
  • reproCommand
  • firstFailingTest (if test run)
  • confidence
• Deterministic normalization rules (same stderr -> same packet).

Acceptance criteria:

• Same failing command produces byte-stable JSON packet across repeated runs.
• Packet size bounded (e.g., <= 8 KB) with deterministic truncation.

Feature Request B: Root-Cause Clustering Tool

Tool name: whetstone_cluster_failures

Problem: One broken include can yield dozens of compiler errors. Small models need one root cause, not 50 symptoms.

Requirements:

• Group errors by root cause signature (missing_symbol, type_mismatch, include_cycle, schema_shape_mismatch).
• Return ordered clusters with:
  • clusterId
  • rootCauseCandidate
  • blastRadius
  • fixFirst boolean
• Deterministic ordering by severity + source location.

Acceptance criteria:

• At least 80% reduction in symptom-level errors shown to agent for common compile breaks.

Feature Request C: Patch Proposal Tool

Tool name: whetstone_propose_patch_for_failure

Problem: Weak agents can identify a failure but cannot reliably synthesize a minimal fix.

Requirements:

• Input: failure packet + repository context slice.
• Output:
  • patchPlan (ordered edit intents)
  • candidatePatch (unified diff)
  • riskLevel
  • expectedTestsToRun
• Must include explicit invariants ("do not alter unrelated files", "preserve JSON schema keys").

Acceptance criteria:

• Patch can be applied automatically in dry-run mode.
• For known failure fixtures, first proposal passes targeted test in >=60% cases.

Feature Request D: Deterministic Debug Loop Orchestrator

Tool name: whetstone_debug_until_green

Problem: Current workflows require manual sequencing: run test, parse output, patch, rerun.

Requirements:

• Single loop with explicit phases:
  1. reproduce
  2. capture failure packet
  3. cluster root cause
  4. propose patch
  5. apply patch (optional gated)
  6. rerun targeted tests
  7. emit outcome report
• Hard iteration cap (maxIterations) and stop reasons.
• Full state machine emitted as JSON transitions.

Acceptance criteria:

• Re-running with same seed/state yields same action sequence.
• No hidden state outside packet history.

Feature Request E: Repro Packet Archive & Replay

Tool names: whetstone_save_repro_packet, whetstone_replay_repro_packet

Problem: Debugging quality is hard to improve without stable training/eval fixtures.

Requirements:

• Save packet: failing command, env snapshot, file hashes, failure packet, patch attempt history.
• Replay packet in sandbox and verify same failure class before patching.
• Export format compatible with LoRA/SLM fine-tuning datasets.

Acceptance criteria:

• Replay reproduces same failureClass and primaryFile for >=95% captured packets.

Feature Request F: Minimal Context Assembler for Fixing

Tool name: whetstone_assemble_fix_context

Problem: Small models degrade when given broad context.

Requirements:

• Input: failure packet/cluster.
• Output: minimal file slices needed to fix:
  • failing file span
  • relevant headers
  • nearest tests
  • related schema/tool contract
• Token budget modes: tiny, small, medium.

Acceptance criteria:

• Produces <=2k token context in tiny mode while preserving fix success on benchmark fixtures.

Feature Request G: Regression Guard Tool

Tool name: whetstone_regression_guard

Problem: A fix may pass one test but silently break prior working behavior.

Requirements:

• Given touched files + step ID, compute deterministic smoke set:
  • failing target
  • neighboring step tests
  • MCP tool registration checks
• Emit mustPass, optional, and deferred buckets.

Acceptance criteria:

• Any patch merged by autonomous loop includes a guard report with pass/fail matrix.

Feature Request H: Debugging Metrics for SLM Readiness

Metric packet fields:

• timeToFirstGreen
• iterationsToGreen
• tokenCostPerFix
• symptomToRootCauseCompression
• patchAcceptanceRate
• regressionEscapeRate

Requirement:

• Metrics available per run and aggregated by failure class.
• Used to decide when to switch work from large model -> SLM.

Proposed rollout

1. Phase 1: Failure packet + clustering (A, B)
2. Phase 2: Patch proposal + fix context (C, F)
3. Phase 3: Loop orchestrator + regression guard (D, G)
4. Phase 4: Replay archive + readiness metrics (E, H)

Done definition for “SLM-ready debugging”

• A small model can take a single failing test target and autonomously produce a patch that passes:
  • target test,
  • deterministic regression guard set,
  • MCP tool schema checks,
  • with full repro packet trace and no manual intervention.