diff --git a/plugin/ralph-workplan.md b/plugin/ralph-workplan.md
index dc44ac3..9882bf1 100644
--- a/plugin/ralph-workplan.md
+++ b/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.
diff --git a/workplan-spec.md b/workplan-spec.md
index 7093573..57998bc 100644
--- a/workplan-spec.md
+++ b/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