dreampiler/kandev
1
0
Fork 0
Code Issues 43 Pull Requests Actions 6 Packages Projects Releases Wiki Activity
Files
753e5549ee730245e4124654052b8b9e364d630c
kandev/docs/specs/tasks/requirements/task-completion.md
T
Carlos Florêncio d8eefc5718 fix: restore completed task workspace access (#3577)
2026-09-12 16:26:35 +01:00

11 KiB
Raw Blame History

status, system, created, updated, owners
status system created updated owners
draft tasks 2026-09-09 2026-09-10
kandev

Task Completion Requirements

Overview

Workflow authors control when work is complete. Users can continue a completed task's conversation to ask follow-up questions. The task system owns both contracts because it owns task state, workflow entry, and session identity.

Task completion and conversation availability are independent. A completed task does not need to reopen merely because its agent answers a question.

Requirements

REQ-TASKS-COMPLETION-001: Explicit completion on step entry

Intent: Make task completion a visible, portable workflow choice.

Acceptance criteria

  • AC-TASKS-COMPLETION-001.1: Only the workflow's final step shall expose Complete task when entering this step on desktop and mobile. An adjacent info icon shall disclose the helper description on hover, keyboard focus, or touch. The description shall not appear as permanent text below the checkbox.
  • AC-TASKS-COMPLETION-001.2: When a nonterminal task enters the final step with completion enabled, the task shall become COMPLETED, regardless of the step's name. Final position alone shall not complete a task.
  • AC-TASKS-COMPLETION-001.3: Entering an unchecked step shall not complete the task. An unchecked final step shall permit further conversation. A non-final step shall not complete a task, even if its stored setting is enabled.
  • AC-TASKS-COMPLETION-001.4: Renaming or reordering a step shall not change its stored completion setting. Only the current final step's setting shall apply. Reordering shall not transfer or enable another step's setting. New custom steps shall default to unchecked.
  • AC-TASKS-COMPLETION-001.5: Upgrade shall enable the setting on existing final steps whose trimmed, case-insensitive names are Done, Complete, Completed, or Approved. Other existing steps shall remain unchecked.
  • AC-TASKS-COMPLETION-001.6: After upgrade, disabling that setting shall survive restart and schema replay. Upgrade shall preserve task and session history and shall not synthesize completion notifications.
  • AC-TASKS-COMPLETION-001.7: Create, update, reload, duplication, templates, workspace bootstrap, import/export, and workflow synchronization shall retain explicit true and false values. Omitted update fields shall preserve values.
  • AC-TASKS-COMPLETION-001.8: Legacy portable workflows shall retain their previous completion behavior when imported or synchronized. Current exports shall state each step's completion setting explicitly.
  • AC-TASKS-COMPLETION-001.9: Parent completion and successful dependency processing shall observe actual task completion. An unchecked final step shall not trigger either process through its name or position.
  • AC-TASKS-COMPLETION-001.10: Repeated delivery of one completion transition shall not repeat parent actions or dependency launches. A chat follow-up shall not create another task-completion cycle.
  • AC-TASKS-COMPLETION-001.11: Saving a step setting shall affect future entry. It shall not complete or reopen tasks already in that step. Explicit movement from a completed step to an unchecked step shall retain existing task-reopening behavior.
  • AC-TASKS-COMPLETION-001.12: Manual, bulk, queued, automated, and initial task entry shall apply the same completion setting. Existing clarification, admission, cancellation, and transition-ledger rules shall remain effective.
  • AC-TASKS-COMPLETION-001.13: The editor shall show saved and unsaved state, use coordinated Save changes and discard, and disable editing for read-only synchronized workflows. The phone control shall be reachable by touch.

REQ-TASKS-COMPLETION-002: Follow-ups in completed conversations

Intent: Preserve conversation continuity after task or session completion.

Acceptance criteria

  • AC-TASKS-COMPLETION-002.1: A COMPLETED session shall show Resume alongside New Agent in its existing chat on desktop and mobile.
  • AC-TASKS-COMPLETION-002.2: Successful Resume shall restore the composer in the selected session. A follow-up shall reach the agent with that session's existing conversation context and appear in the same transcript.
  • AC-TASKS-COMPLETION-002.3: Opening, reloading, or reconnecting to a completed chat shall not resume it or change its lifecycle state, regardless of the open-time auto-start preference.
  • AC-TASKS-COMPLETION-002.4: Resume and a follow-up shall preserve task and session identity, history, workflow position, task state, agent ownership, primary-session selection, and valid provider conversation identity.
  • AC-TASKS-COMPLETION-002.5: Root and child tasks shall both permit user follow-ups. Successful child completion without active clarification shall not permanently close its interactive conversation.
  • AC-TASKS-COMPLETION-002.6: Explicit delivery to a completed session shall resume that exact session before accepting its turn. Task-addressed agent messages shall prefer an eligible live session over a completed sibling.
  • AC-TASKS-COMPLETION-002.7: Resume shall preserve message order, queue identity, attachments, and Auto-run policy. Concurrent resume and send shall not launch duplicate runtimes or dispatch the same accepted prompt twice.
  • AC-TASKS-COMPLETION-002.8: Late callbacks or cleanup from the completed execution shall not stop, complete, or clear the resumed execution's work.
  • AC-TASKS-COMPLETION-002.9: A failed resume shall show actionable feedback without discarding history or unsent content. A missing profile or unrecoverable workspace shall not silently create a different conversation.
  • AC-TASKS-COMPLETION-002.10: Active clarification ownership, answer delivery, and question barriers shall remain unchanged. Resume shall not reactivate historical questions or discard a current question.
  • AC-TASKS-COMPLETION-002.11: FAILED and CANCELLED shall retain their existing recovery and message-delivery rules. The completed-session change shall not make ordinary sends revive those states.
  • AC-TASKS-COMPLETION-002.12: A historical session retired by a profile switch shall remain excluded from automatic workflow reuse after manual Resume. Its follow-ups shall not advance the active workflow session.
  • AC-TASKS-COMPLETION-002.13: Runtime cleanup shall retain recoverable conversation and workspace identity. Concurrent archive, delete, or explicit stop shall prevent a stale resume from resurrecting work.

REQ-TASKS-COMPLETION-003: Workspace access after conversation completion

Intent: Let users inspect and use a retained task workspace without resuming its agent conversation. The task system owns admission and recovery; workspace ownership remains governed by the canonical task environment.

Acceptance criteria

  • AC-TASKS-COMPLETION-003.1: When a completed session has a retained, accessible task workspace, opening the task shall restore file browsing, file contents, Git views, and supported workspace terminals without requiring Resume. This shall also work after its previous runtime has stopped.
  • AC-TASKS-COMPLETION-003.2: Workspace restoration shall preserve session state, completion time, transcript, task state, workflow position, primary selection, and agent ownership. It shall not start an agent, dispatch a prompt, or replay workflow actions.
  • AC-TASKS-COMPLETION-003.3: Explicit Resume shall remain available under REQ-TASKS-COMPLETION-002 after workspace restoration. Restoration shall preserve the provider identity needed to continue the same conversation, including across another backend restart.
  • AC-TASKS-COMPLETION-003.4: A FAILED or CANCELLED conversation with a retained, accessible workspace shall permit workspace-only restoration. Its existing agent recovery and message-admission rules shall remain unchanged.
  • AC-TASKS-COMPLETION-003.5: Restoration shall enforce current access and ownership permissions. An archived or deleted task, an invalid session reference, or cleanup that has claimed the environment shall prevent stale restoration from recreating resources or exposing the workspace.
  • AC-TASKS-COMPLETION-003.6: Concurrent workspace requests and explicit Resume shall not leave duplicate runtimes or stop a newer execution. A historical session sharing an environment shall not take over its live agent.
  • AC-TASKS-COMPLETION-003.7: When retained workspace inventory is missing or unsafe, passive restoration shall report its unavailability. It shall not replace a branch, discard changes, or silently create a replacement workspace.
  • AC-TASKS-COMPLETION-003.8: A workspace restoration failure shall appear within the affected workspace surface with a concise cause and expandable, bounded technical details. It shall not appear as a page-wide session-start failure, fail the conversation, or leave an indefinite preparation indicator.
  • AC-TASKS-COMPLETION-003.9: A recoverable failure shall offer workspace Retry. An in-progress attempt shall prevent duplicate retries. Failure shall not trigger an unbounded retry loop; success shall clear matching feedback. A late result shall not replace feedback for a different environment or attempt.
  • AC-TASKS-COMPLETION-003.10: Desktop and mobile shall expose the same workspace results and recovery actions. Phone controls shall have at least 44-pixel touch targets. Expanded details shall remain within the workspace surface, preserve keyboard access, and cause no horizontal page overflow.

Compatibility and exclusions

This contract replaces name-based workflow completion and the permanent completed-session lock. It does not change manual task-state APIs, failed-child rollups, successful-dependency semantics, Office scheduler ownership, archive policy, or intentional New Agent behavior. Existing manual FAILED/CANCELLED recovery is preserved; these states are not newly eligible for ordinary sends.

Automatic profile reuse remains governed by workflow profile sessions. Prompt admission during startup follows resume prompt queue. Provider restoration uses agent recovery.

Workspace restoration does not imply read-only access: existing edit and shell permissions remain authoritative. This contract does not add workspace access for tasks with no sessions, change archive/unarchive recovery, introduce a new executor, or change physical workspace ownership.

Implementation plans

Reference in New Issue View Git Blame Copy Permalink