whetstone_DSL/docs/AGENT_HANDOFF_2026-03-18_taskitem_pool.md

Agent Handoff 2026-03-18

Summary

This handoff covers two related pieces of work:

1. The Whetstone planning pipeline for whimpwm was debugged and improved so the sprint_001_execution_spec_whetstone.md run now produces a usable queue.
2. A project-scoped taskitem pool was added so external agents can claim/release/complete generated taskitems directly from the target project without relying on an always-running orchestrator.

Key Outcomes

• Fixed the spec-to-taskitem path so prose sections are preserved and mapped into better normalized requirements.
• Fixed workspace-aware target inference so generated taskitems no longer drift into Whetstone internals when planning for another project.
• Added a project-side taskitem pool persisted under .whetstone/<project>.taskitem_pool.json.
• Added MCP tools:
  • whetstone_import_taskitem_pool
  • whetstone_list_taskitem_pool
  • whetstone_claim_taskitem
  • whetstone_release_taskitem
  • whetstone_complete_pooled_taskitem
• Added lock-based contention safety for the pool using a .lock sidecar plus atomic temp-file writes.
• Fixed MCP error shaping so failed claims now surface as proper tool errors with isError: true.

Files Changed

• editor/src/ArchitectIntakeProcessor.h
• editor/src/RequirementsParser.h
• editor/src/ScopeMilestoneDecomposer.h
• editor/src/SelfContainmentScorer.h
• editor/src/mcp/RegisterArchitectIntakeTools.h
• editor/src/mcp/RegisterValidationTools.h
• tools/mcp/run_sprint_taskitem_pipeline.sh
• editor/src/TaskitemPoolPersistence.h
• editor/src/mcp/RegisterTaskitemPoolTools.h
• editor/src/AgentPermissionPolicy.h
• editor/src/HeadlessAgentRPCHandler.h
• editor/src/headless_rpc/DispatchPart5.h
• editor/src/MCPServer.h
• editor/src/mcp/RegisterOnboardingAndAllTools.h

Verified Behavior

• whetstone_mcp rebuild succeeds.
• whimpwm queue import succeeds from:
  • logs/taskitem_runs/sprint_001_execution_spec_whetstone_20260317_214642/02_generate_taskitems.json
• Project pool persists at:
  • /home/bill/Documents/whimpwm/.whetstone/whimpwm.taskitem_pool.json
• Concurrency test succeeded:
  • two workers racing to claim the same task resulted in exactly one claim winner
  • loser returned Taskitem not ready with isError: true

Current whimpwm State

• The whimpwm pool was reset to a clean imported state before handoff.
• Current counts:
  • ready: 6
  • blocked: 1
  • total: 7
• No task is currently claimed.

Recommended Next Steps

1. Add a lightweight MCP/import bridge from planner runs into workflow items if you still want parity between the legacy workflow system and the project-scoped pool.
2. Decide whether .whetstone/*.taskitem_pool.json should remain runtime-only or become a versioned artifact for some projects.
3. Add explicit tests for:
   • import/claim/release/complete lifecycle
   • concurrent claim contention
   • error-shaping contract on failed pool mutations
4. Start real worker execution against the whimpwm queue now that the pool path is usable.