Files
kandev/docs/specs/tasks/system-design/workflow-explicit-completion-signal.md
T
2026-09-18 10:33:43 +01:00

3.8 KiB

status, system, requirements
status system requirements
current tasks
REQ-TASKS-WORKFLOW-EXPLICIT-COMPLETION-SIGNAL-003

Completion signal recovery system design

Purpose and boundaries

The tasks system owns completion eligibility and its recovery instructions. This design adds diagnostics to the existing completion contract. It preserves the current turn stamp, signal claim, and workflow transition rules.

Requirement mapping

Requirement Design sections
REQ-TASKS-WORKFLOW-EXPLICIT-COMPLETION-SIGNAL-003 Diagnostic response, Recovery instructions, Verification

Diagnostic response

internal/mcp/handlers/handlers.go:handleStepComplete compares the launch step from stepCompletionLaunchStep with the task's current workflow step. The mismatch continues to return VALIDATION_ERROR before the signal claim.

The error retains its existing prefix for compatibility. Its text includes both step IDs and the recovery instruction. This information belongs in the message, because internal/mcp/server/server.go:stepCompleteHandler forwards err.Error(). A details-only change would not reliably reach the agent.

Suggested message:

workflow step changed before signal was recorded. This turn started in step <launch_step_id>. The current step is <current_step_id>. No signal was recorded. Retrying in this turn cannot recover. End this turn and ask the user to resume this session for the current step. After satisfying that step, signal completion from the new turn. Do not move the task solely to bypass this error.

A missing stamp or failed turn read remains a separate internal error. The message does not promise that a concurrent future move cannot occur.

Recovery instructions

The registered tool description explains the distinction between a stale-turn error and already_signaled. A duplicate preserves the existing accepted signal. A stale-turn rejection records nothing and requires a fresh turn.

internal/sysprompt/sysprompt.go supplies concise recovery guidance in stepCompleteSection and officeStepCompleteInstruction. Gating and mode visibility stay unchanged. The long explanation resides in the returned error. This keeps prompt and tool-description size budgets intact.

The agent ends its stale turn with a clear recovery request. A user resumes the same session on the current step. Normal turn creation stamps that step. The agent evaluates current-step work before its final completion call. No tool call silently creates a turn, restamps an old turn, or moves the task.

The existing operator move remains documented as a separate manual decision. An error does not grant an agent new authority to use move_task_kandev.

Persistence and compatibility

There is no schema change, new response envelope, or new MCP argument. workflow_step_id_at_start remains an immutable historical fact. The task-at-step conditional signal claim and duplicate handling remain intact. RUNNING and WAITING_FOR_INPUT sessions both retain the mismatch guard. Idleness does not prove that work belongs to the new step.

Verification

Handler tests use the SQLite-backed existing fixtures. They reproduce Review to Work movement after turn creation, reject repeated stale calls, and accept a call after a new Work turn starts. Both session states retain the guard.

Server tests exercise error forwarding through the MCP handler. Prompt tests cover gated task and Office contexts, omission from ungated instructions, and existing size budgets. These are protocol tests, not browser layout changes.

Implementation plans