huskies: merge 515_story_add_a_debug_mcp_tool_to_dump_the_in_memory_crdt_state_for_inspection

README.md

@@ -130,6 +130,39 @@ includes a count and a suggestion to check the server logs.
 
 Set `reconcile_on_startup = false` in `.huskies/project.toml` to disable the
 pass during the migration window if it produces noise.
+## Debugging
+
+### Inspecting the in-memory CRDT state
+
+When diagnosing state issues, use the `dump_crdt` MCP tool or the `/debug/crdt` HTTP endpoint to inspect the raw in-memory CRDT state directly. These surfaces show the ground truth that the running server holds — not a summarised pipeline view and not the persisted SQLite ops.
+
+**MCP tool** (from Claude Code or any MCP client):
+
+```
+mcp__huskies__dump_crdt
+# dump everything
+{}
+
+# restrict to a single item
+{"story_id": "42_story_my_feature"}
+```
+
+**HTTP endpoint** (browser or curl):
+
+```bash
+# dump everything
+curl http://localhost:3001/debug/crdt
+
+# restrict to a single item
+curl "http://localhost:3001/debug/crdt?story_id=42_story_my_feature"
+```
+
+Both return a JSON document with:
+
+- **`metadata`** — `in_memory_state_loaded`, `total_items`, `total_ops_in_list`, `max_seq_in_list`, `persisted_ops_count`, `pending_persist_ops_count`
+- **`items`** — one entry per CRDT list item (including tombstoned/deleted entries), each with `story_id`, `stage`, `name`, `agent`, `retry_count`, `blocked`, `depends_on`, `content_index` (hex OpId for cross-referencing with `crdt_ops`), and `is_deleted`
+
+> **This is a debug tool.** For normal pipeline introspection use `get_pipeline_status` or `GET /api/pipeline` instead.
 
 ## License