Files
kandev/docs/specs/tasks/system-design/task-completion.md
T
2026-09-10 15:01:37 +01:00

263 lines
15 KiB
Markdown

---
status: draft
system: tasks
requirements:
- REQ-TASKS-COMPLETION-001
- REQ-TASKS-COMPLETION-002
---
# Task Completion System Design
## Purpose and boundaries
The task system owns workflow completion and conversation admission. Runtime
shutdown releases execution resources; it does not establish permanent loss of
conversation access. Agent runtime restoration and workspace recovery retain
their current owners and authorization checks.
| Requirement | Design sections |
| --- | --- |
| `REQ-TASKS-COMPLETION-001` | Step contract, Migration, Entry and notification |
| `REQ-TASKS-COMPLETION-002` | Explicit resume, Follow-up ownership, Cleanup and races, User interface |
## Step contract
Use `CompleteTaskOnEnter bool` and `complete_task_on_enter` in JSON, YAML, and
SQL. The naming follows `cancel_triggers_turn_complete`. Responses and current
exports include false explicitly. PATCH uses presence-aware decoding: omission
preserves the value, false disables it, and explicit null is rejected.
Create defaults an omitted value to false and rejects null or non-booleans.
Completion requires both final-step eligibility and an enabled setting.
Persist the setting on its step across reorder operations, but ignore it while
that step is non-final. The new final step uses its own saved value; reordering
does not transfer or automatically enable completion. The editor derives
visibility from the current draft order, and the backend evaluates the committed
order. Saving or discarding the order and settings uses existing coordination.
Carry the field through both task and workflow step models, `StepDefinition`,
the embedded workflow loader, task DTO conversion, workflow controller request
types, `stepevents`, MCP schemas and handlers, and all repository projections.
`workflow_steps.complete_task_on_enter` uses the repository's integer boolean
convention with a non-null zero default. Both repositories initialize this
shared table; neither constructor may erase or bypass migration decisions.
Frontend types, workflow API, boot hydration, WebSocket merges, step drafts,
save/rollback, workflow creation, and duplication carry the same boolean.
Partial WebSocket updates that omit it retain the saved value.
Portable export advances to version 2. Each version-2 step requires a boolean
completion field. Import and sync accept versions 1 and 2. At the version-1
boundary only, omitted values are materialized using the old name-and-final
predicate; explicit false always wins. Reject null in either version.
Normalize the whole workflow before converting individual steps, because legacy
final-position detection needs all steps. Export always emits version 2.
Thus current authored definitions never depend on names at runtime.
Sync applies normalized values and includes the field in equality checks.
Version-1 sync files remain authoritative legacy input until their authors
upgrade them; local editing of synced rows stays disabled. An invalid version-2
file follows existing freeze-and-report sync behavior.
Built-in YAML declares the field explicitly for every step. Preserve each
template's old behavior: qualifying final steps are true; other steps are false.
Do not make the final PR step in Improve Kandev terminal merely because it is
last. Update stored template definitions and workspace bootstrap paths too.
## Migration
The workflow repository owns the semantic backfill, after required additive
schema changes and before serving requests or starting sync. Task repository
projection/bootstrap initialization adds the same column before its own writers
need it. It does not independently infer or backfill completion.
Use one transaction and a durable `kandev_meta` key,
`workflow_complete_task_on_enter_backfill_v1`. Inside the transaction, read the
marker, backfill legacy steps and stored template JSON, then record completion.
Use the existing portable Go normalization for trimmed case-insensitive names
and final position. A final step has no sibling with a greater position,
matching `GetNextStepByPosition`; tied maximum positions retain that definition.
Preserve row timestamps and IDs. The transaction rolls back the marker and all
backfill writes on failure. Startup fails if this required migration fails.
Replay skips the semantic backfill after the marker. It must not use
`WHERE complete_task_on_enter = 0` as a recurring migration. Fresh startup writes
explicit built-in values and records the marker before ordinary user writes.
Template backfill preserves unrelated JSON fields and respects explicit values.
Required-store conformance covers actual constructor order, fresh SQLite and
PostgreSQL, old-schema upgrade, replay after disabling, and failure/retry.
Historical release fixtures remain truthful snapshots; add assertions or a
dedicated legacy fixture rather than editing old releases to contain new columns.
## Entry and notification
Replace the name test in `IsTerminalStep` with the explicit boolean while
retaining final-position eligibility. A step completes work only when it has
no successor and its setting is true.
Keep the old name predicate private to legacy conversion/migration. Audit all
callers, including task creation, `task/service.service_workflow`,
`orchestrator.workflow_store`, queued moves, automated transitions, and
`task_launch_workflow`. Every caller must resolve the actual successor or
equivalent final-position evidence; passing nil without a lookup is not proof.
Persist step and task-state changes through existing guarded transition and
ledger operations. A checked final entry completes a nonterminal task; an
unchecked or non-final entry follows existing nonterminal/reopen behavior.
Do not convert FAILED or
CANCELLED to success. Saving the checkbox does not reevaluate resident tasks.
Do not add transition actions or replay on-enter during Resume.
Parent rollups and dependencies use committed task state. Remove name- or
step-membership fallback from `annotateTerminalChildSteps` and terminal receipt
handling. Preserve `DependencyStatusForTask`'s existing state-only resolution.
Completion events follow the
successful state write, never a speculative target lookup. Preserve existing
operation deduplication, failure/cancellation rollups, archived-child filtering,
and success-only dependency launches. Upgrade does not rewrite resident tasks
or fire old completion events; pre-existing persisted completion stays intact.
## Explicit resume
Reuse `session.recover` with `action: resume`. Admit completed recovery only
through this explicit operation or a session-pinned follow-up send. Carry a
narrow internal completed-resume permission through `LaunchSession` and
`executor.ResumeOptions`; automatic `session.ensure`, status reads, generic
open-time launch, and startup recovery never infer that permission.
Authorize the task/session pair and prompt access before side effects. Under
the existing lifecycle/cancel guards, reload the exact session and task, verify
archive and runtime ownership, and claim the current completed state/version.
Require the expected execution generation as well as state where a callback
can replace the session during recovery. Do not weaken global terminal guards.
Extend `allowsSessionStartingRecovery` only for an explicitly claimed completed
resume. Permit absent `executors_running` after cleanup; retain recoverable task
environment and profile checks. Reuse stale-execution cleanup, provider token
restoration, and native/CLI/history fallback. Persist `STARTING` and clear
`CompletedAt` through the guarded writer before credentials are issued. Retain
prior execution and turn history; do not clear ACP/provider identity.
At readiness, settle into the existing input-capable state without sending a
synthetic workflow or task-description prompt. Preserve current initial-message
backfill only for genuinely absent launch history. The next user send starts
one new conversational turn after the old one. No new session ID or queue
incarnation is allocated by Resume.
`message_target_session.go` continues to prefer live primary, then live
fallback. Completed siblings must not shadow a live session. With no live
session, a completed primary, or the newest completed session if no primary
exists, can be selected and pinned. An explicit completed `session_id` always
targets that session. Authorization and validation precede the same resume
admission, which runs before `ProcessOnTurnStart` and message persistence.
FAILED/CANCELLED dispatch continues to reject with its existing error code.
## Follow-up ownership
A message on a completed task is conversation work. Runtime running, waiting,
failed, and finished events do not reopen that task or replay workflow entry,
turn-start, turn-complete, completion-signal, or parent notification effects.
Existing explicit task moves/state APIs remain the way to reopen workflow work.
For an explicitly resumed completed session on a still-active task, persist a
session metadata marker `completion_follow_up` in the guarded resume claim.
It records conversational-only ownership independently of the mutable session
state. Such a session stays excluded from automatic profile reuse and cannot
become primary merely because it resumes. Automatic workflow triggers and
runtime task-state reconciliation skip it. An explicit workflow handoff may
clear the marker only while establishing that session's workflow ownership.
An ordinary send, page activation, or automatic reuse lookup cannot clear it.
Pinned user and MCP sends, queued dispatch, streaming completion, agent exit,
and failure publication consume the same ownership predicate. This protects a
retired profile conversation even after its state becomes `WAITING_FOR_INPUT`.
Preserve primary IDs, profile routing, step history, and current queue policy.
## Cleanup and races
For successful task completion, stop collapsing an ordinary child conversation
to `COMPLETED` in `setSessionWaitingForInputIfRequestedWithHook`. Settle it with
the existing root-task waiting behavior. Keep task status completed and retain
the fail-closed idle resource reclamation. Do not change failed/cancelled task
receipt rules through this branch.
Use current-turn clarification lookup; any active clarification retains its
existing barrier and late-answer path. Historical answered or expired bundles
remain history. A lookup error cannot justify closing the conversation.
Cleanup and resumed execution must use the same lifecycle ownership boundary.
An old receipt, stop callback, stream frame, or reclaim operation carries its
execution identity; after a newer resume claim it cannot clear queues or stop
the replacement runtime. Preserve retired-execution tombstones. Release guards
before waiting for callbacks that need those guards.
Queue admission and readiness use the existing queue-incarnation and dispatch
reservation contract. Never clear pending messages solely because the old
execution completed. Duplicate Resume joins or returns the existing attempt.
A later stop/archive/delete wins over stale recovery writes. A failed launch
uses existing recoverable error state without changing completed task state;
retain the follow-up marker for retry and preserve queued/unsent content.
## User interface
`SessionStoppedBanner` completed mode has primary Resume and secondary New
Agent. Reuse `useSessionRecoveryActions` and existing recovery error feedback.
Show busy state, disable duplicate actions, and restore the composer from the
authoritative session update. Missing profile feedback stays visible. New
Agent retains its dialog and intentional new-conversation behavior.
Keep the completed-chat open-time gate in session-resumption hooks. Extend
recovery hook tests for response success/failure, session switching while a
request is pending, and busy cleanup. Do not let a late response modify another
chat's recovery feedback or selected session.
Show the completion checkbox only in the final step's entry/general settings,
outside the conditional turn-complete controls. It remains available when the
final step has no actions. Put the description inside an adjacent info icon
using the existing HelpTip interaction: hover or focus on desktop, tap on touch.
Do not render the description permanently below the checkbox. Suggested text:
"Marks the task complete when it enters this final step. You can still continue
the conversation." Give the icon a localized accessible name. Use coordinated
dirty/save/discard state and read-only sync treatment. Localize all copy.
### Mobile composition
The existing `task-layout.tsx` phone layout and inline stopped-session banner
are the chat exemplar. Keep the transcript's single scroll owner and the
composer area's safe-area spacing. Stack Resume then New Agent on phones;
retain compact side-by-side buttons on fine-pointer desktop. Phone/coarse
pointer actions have at least 44 px active height; no unconditional desktop
`min-h-11` sizing is introduced.
The step editor's `CancelCompletionToggle` supplies the checkbox/label pattern;
the existing mobile workflow step selector supplies focused navigation. Use a
44 px tappable label and a touch-accessible info icon. Disclose wrapping helper
text through the existing touch help surface; do not require hover or add a
new standalone modal. Opening help must not toggle the checkbox.
An inline setting fits this short choice. Both viewports share draft and save
logic. Preserve keyboard focus, one settings scroll region, no horizontal page
overflow, and access to Save changes above safe-area insets.
## Verification and observability
Use barrier-based Go tests for resume/stop, reclaim/resume, stale receipt/new
execution, double Resume, and readiness/queue admission. Assert the preserved
task, primary session, provider token, history, queue order, and emitted events.
Test both database dialects at migration boundaries. Use existing structured
logs with task/session/execution identity and resume outcome; do not log tokens.
Desktop and mobile Playwright tests save/reload the final-step checkbox, complete
checked final steps, send from unchecked final steps, and Resume a persisted
completed chat. Reorder tests prove the control moves to the current final
step and a previously checked non-final step cannot complete work. Help tests
prove hover/focus/tap disclosure and that opening help does not toggle the value.
Assert a second agent response, unchanged session count and history, and no
task reopen or duplicate completion. Include a retired non-primary session and
active clarification regression. Run against freshly built production assets.
## Related decisions
- [Separate task completion from conversation availability](../../../decisions/2026-09-09-task-completion-conversation-availability.md)
- [Replayable migrations](../../../decisions/0027-replayable-schema-migrations.md)
- [Profile-switch session policy](../../../decisions/2026-08-31-workflow-profile-session-switch-policy.md)
- [Current-turn clarification ownership](../../../decisions/2026-08-14-current-turn-clarification-ownership.md)