From 9d57ce430f9f79507a0849d968f3183b77743976 Mon Sep 17 00:00:00 2001 From: Bernd Worsch Date: Mon, 16 Mar 2026 08:06:11 +0000 Subject: [PATCH] feat: Task Close Gate + HEUREKA Completion Sequence for state-hub projects MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- plugin/ralph-workplan.md | 24 ++++++++++++++++++++++++ workplan-spec.md | 39 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 63 insertions(+) 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 `HEUREKA`, +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="", event_type="milestone", + topic_id="", workstream_id="")` +4. Set workplan frontmatter `status: done` +5. Output `HEUREKA` + +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 `HEUREKA`: + +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 `HEUREKA` + +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