whetstone_DSL/docs/TOOL_CONTRACT_V1_IMPLEMENTATION_CHECKLIST.md

Whetstone: Tool Contract v1 Implementation Checklist

Date: 2026-02-26 Target: L2 compliance (as a standalone tool and Hivemind-integrated tool) Contract source: /home/bill/Documents/drive_projects/drive-download-20260217T155135Z-1-001/TOOL_CONTRACT_V1.md

Scope

Whetstone should present itself as a modular tool with stable contract surfaces, independent of Hivemind internals.

L0 (Manifest + Health)

• Define tool.manifest for Whetstone tool server/MCP layer
• Include required fields:
  • tool_id = whetstone_editor
  • tool_name = Whetstone Editor Tool
  • contract_version = 1.0.0
  • tool_version
  • modes = ["standalone", "orchestrated"]
  • capabilities from supported MCP operations
• Source schemas from whetstone_tool_schemas.json
• Add/standardize health endpoint in MCP/runtime layer
• Add contract L0 tests under editor/tests

L1 (Execute + Typed Errors)

• Add tool.execute envelope adapter around existing MCP calls
• Ensure execution returns standard contract response envelope
• Normalize MCP/tool errors into typed contract errors:
  • INVALID_INPUT, POLICY_BLOCKED, DEPENDENCY_UNAVAILABLE, TIMEOUT, INTERNAL_ERROR
• Add idempotency support where operations are retryable
• Add L1 tests validating envelope shape and error mapping

L2 (Validate + Policy + Observability)

• Implement tool.validate preflight for selected high-impact capabilities first
• Return: is_valid, violations, required_approvals, estimated_cost, estimated_risk
• Emit policy metadata per call:
  • risk_level, impact_scope, requires_human_review, blocked_reasons
• Add trace propagation and structured logging in MCP execution path
• Add metrics for capability success/failure and latency distribution
• Add L2 tests for validate/policy/trace behavior

Decoupling Rules (Critical)

• No Hivemind-specific assumptions in core Whetstone execution paths
• Hivemind integration via contract adapter only
• Keep standalone CLI/local execution path fully functional without Hivemind

Candidate Integration Files

Use these as first implementation touchpoints:

• tools/mcp/README.md
• tools/mcp/whetstone_tool_schemas.json
• editor/src
• editor/tests

Rollout Order

1. Publish manifest from existing tool schema inventory
2. Add health + envelope adapter (L0/L1)
3. Add validation + policy metadata for top capabilities (L2)
4. Verify Hivemind consumes Whetstone exclusively through contract endpoints

Exit Criteria

• L0/L1/L2 tests passing
• Whetstone runs standalone with full core capability set
• Hivemind integration works via contract only (no direct internals)
• Contract versioned and documented for replacement interoperability