feat: add State Hub bulk status skill

skills/state-hub/references/tool-signatures.md

@@ -0,0 +1,97 @@
+# State Hub Tool Signatures
+
+Load this reference when a session needs exact REST fallback paths or batched
+write payloads.
+
+## Orientation
+
+```text
+MCP: get_domain_summary(domain_slug)
+REST: GET /state/summary then filter by topic/domain when MCP is unavailable
+```
+
+Use `get_domain_summary("custodian")` inside State Hub work. It returns the
+domain topic, active workstreams, blocking decisions, recent progress, repos,
+and compact capability hints.
+
+## Agent Messages
+
+```text
+MCP: get_messages(to_agent?, from_agent?, unread_only?, limit?)
+REST: GET /messages/?to_agent=<repo>&unread_only=true
+
+MCP: send_message(from_agent, to_agent, subject, body, thread_id?)
+REST: POST /messages/
+
+MCP: mark_message_read(message_id)
+REST: PATCH /messages/{message_id}/read
+```
+
+Use repo slugs as agent names. Use `broadcast` only for genuinely shared
+coordination.
+
+## Workstreams and Tasks
+
+```text
+MCP: create_workstream(topic_id, title, slug?, description?, owner?, due_date?, repo_id?, planning_priority?, planning_order?)
+REST: POST /workstreams/
+
+MCP: create_task(workstream_id, title, priority="medium", description?, assignee?, due_date?)
+REST: POST /tasks/
+
+MCP: update_task_status(task_id, status, blocking_reason?, tokens_in?, tokens_out?, workplan_tokens_in?, workplan_tokens_out?, note?, model?, agent?, session_id?)
+REST: PATCH /tasks/{task_id}
+```
+
+Canonical task statuses are `wait`, `todo`, `progress`, `done`, and `cancel`.
+Legacy aliases are accepted during migration, but do not emit new workplan files
+with old vocabulary.
+
+## Bulk Task Status Sync
+
+```text
+MCP: bulk_update_task_statuses(updates, author?, session_id?)
+REST: POST /tasks/bulk-status-sync
+```
+
+Payload:
+
+```json
+{
+  "updates": [
+    {"task_id": "uuid-1", "status": "progress"},
+    {"task_id": "uuid-2", "status": "done"},
+    {"task_id": "uuid-3", "status": "wait", "blocking_reason": "needs approval"}
+  ],
+  "author": "codex",
+  "session_id": "optional-session-id"
+}
+```
+
+Response:
+
+```json
+{
+  "updated": [
+    {"id": "uuid-1", "status": "progress", "...": "..."}
+  ],
+  "progress_event_ids": ["event-uuid-1"]
+}
+```
+
+The endpoint rejects duplicate task ids with `400` and missing task ids with
+`404` before changing any task. Each successful item emits one
+`task_status_changed` progress event with `detail.bulk_status_sync = true`.
+
+## Progress and Decisions
+
+```text
+MCP: add_progress_event(summary, event_type="note", topic_id?, workstream_id?, task_id?, detail?)
+REST: POST /progress/
+
+MCP: record_decision(title, decision_type="pending", topic_id?, workstream_id?, description?, rationale?, decided_by?, deadline?)
+REST: POST /decisions/
+```
+
+Prefer one progress event per checkpoint. A useful close event says what changed,
+which tests ran, whether consistency sync passed, and what remains.