feat: Task Close Gate + HEUREKA Completion Sequence for state-hub projects

workplan-spec.md:
- Task Close Gate: when marking a task done in the file, also call
  update_task_status(state_hub_task_id, "done") in the State Hub
- HEUREKA Completion Sequence: before HEUREKA, for hub-integrated workplans:
  update all tasks, update_workstream_status → done, add_progress_event
  milestone, then set status: done and output HEUREKA

plugin/ralph-workplan.md:
- Added State-Hub Integration Notes section injected via stop-hook prompt
  so the worker follows Task Close Gate and HEUREKA Completion Sequence

Resolves: state-hub progress event 1e73441e (2026-03-16)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

plugin/ralph-workplan.md

@@ -74,3 +74,27 @@ Then report:
 > "🔄 Ralph loop active. The loop will feed the workplan prompt back on every
 >  iteration. It retires when all tasks are done and the workplan status is
 >  updated to 'done' in the file."
+
+## State-Hub Integration Notes
+
+These notes are injected into the stop-hook prompt so the worker follows the
+correct conventions when working on state-hub-integrated workplans.
+
+**Task Close Gate** — When marking a task `done` in the workplan file, if the
+task block has a `state_hub_task_id` field, also call `update_task_status` on
+that ID in the State Hub. Do this at the same time as editing the file, not
+in a batch at the end.
+
+**HEUREKA Completion Sequence** — Before outputting `<promise>HEUREKA</promise>`,
+if the workplan frontmatter has `state_hub_workstream_id`:
+
+1. Ensure all `state_hub_task_id` tasks are marked `done` in the hub
+   (`update_task_status` — idempotent)
+2. Call `update_workstream_status(state_hub_workstream_id, "done")`
+3. Call `add_progress_event(summary="<what was delivered>", event_type="milestone",
+   topic_id="<from CLAUDE.md>", workstream_id="<state_hub_workstream_id>")`
+4. Set workplan frontmatter `status: done`
+5. Output `<promise>HEUREKA</promise>`
+
+If the workplan has no `state_hub_workstream_id`, skip all hub calls and go
+straight to steps 4–5.

workplan-spec.md

@@ -59,6 +59,45 @@ A workplan is **done** when:
 The skill updates both as work progresses — tasks individually, then the
 workplan when all tasks are complete.
 
+## Task Close Gate (State-Hub Projects)
+
+When a workplan contains `state_hub_workstream_id` in its frontmatter and a
+task block contains `state_hub_task_id`, the worker must call
+`update_task_status(state_hub_task_id, "done")` in the State Hub at the same
+time as marking the task `done` in the file.
+
+**Why:** The file is the authoritative source of truth (ADR-001), but the hub
+is the read model used for dashboards and consistency checks. Keeping them in
+sync per-task prevents drift from accumulating and avoids the manual repair
+sessions that result from batch-syncing at the end only.
+
+Example task block with hub binding:
+
+```task
+id: MRKD-WP-0003-T01
+status: todo
+priority: high
+state_hub_task_id: 51e1b53e-a62f-496b-892d-615513c35d67
+```
+
+## HEUREKA Completion Sequence (State-Hub Projects)
+
+When all task blocks are `done` and the workplan is about to be closed, a
+state-hub-integrated workplan requires a close-out sequence **before**
+outputting `<promise>HEUREKA</promise>`:
+
+1. For each task with a `state_hub_task_id`: call `update_task_status(id, "done")`
+   (idempotent — safe to call even if the Task Close Gate already did it)
+2. Call `update_workstream_status(state_hub_workstream_id, "done")`
+3. Call `add_progress_event(summary="...", event_type="milestone",
+   topic_id=..., workstream_id=...)` summarising what was delivered
+4. Update the workplan frontmatter: `status: active → status: done`
+5. Output `<promise>HEUREKA</promise>`
+
+This sequence ensures the hub dashboard reflects completion without requiring
+a separate manual sync. The C-13 consistency check will WARN (and auto-fix)
+if step 2 is missed, but completing it proactively avoids the warning.
+
 ## Naming Convention
 
 The skill works with any filename. A common convention used in custodian-family