Files
kandev/docs/specs/tasks/requirements/subtask-detachment.md
T

110 lines
6.7 KiB
Markdown

---
status: active
system: tasks
created: 2026-07-18
owners:
- kandev
---
# Subtask detachment Requirements
## Overview
This document is the migrated task-system source for the capability. The source detail below remains authoritative while the system is migrated into separate requirement and design records.
## Requirements
### REQ-TASKS-SUBTASK-DETACHMENT-001: Subtask detachment
**Intent:** Preserve the observable task or workflow behavior recorded by the legacy specification.
#### Acceptance criteria
- **AC-TASKS-SUBTASK-DETACHMENT-001.1:** When a consumer uses this capability, the system shall provide the observable behavior and exclusions documented below.
## Migrated source detail
## Why
Users can create and reorganize task trees, but they cannot promote an existing subtask to a top-level task from the task menus. Clearing only the hierarchy relationship is also unsafe for subtasks that inherit their parent's materialized workspace because future launches would lose the sharing policy.
## What
- A user can detach a subtask from its parent from the sidebar task context menu and the task card's three-dot and context menus.
- The action is shown only for tasks with a parent and requires confirmation.
- Confirmation explains that the workspace remains shared even though cleanup stewardship is separated from the former parent.
- Detachment clears the task's parent relationship without changing its workflow, workflow step, state, blockers, descendants, repositories, sessions, or agent execution.
- A detached task becomes a top-level root of its existing subtree. Its descendants remain attached to it.
- A task using `inherit_parent` workspace mode changes to `shared_group` mode when detached. Its workspace-group membership remains active, so current and future sessions continue using the same materialized workspace.
- Tasks already using `shared_group` or `new_workspace` keep that workspace mode.
- Detaching an already-root task is idempotent and succeeds without changing the task.
- Choosing `No parent` in the Office parent picker uses the same detachment behavior.
- Successful detachment is reflected in all connected board, sidebar, and task-detail views without a reload.
## Data model
Detachment updates existing persisted fields; it adds no table or column.
- `tasks.parent_id` becomes the empty string.
- `tasks.metadata.workspace.mode` changes from `inherit_parent` to `shared_group` when applicable.
- The child's active `task_workspace_group_members` row remains the durable source of shared workspace access. The owner role can move to the child.
- Workspace-group and task-environment owners and ownership generations change atomically when the former parent owns the shared materialization.
- Existing blocker rows, task-session rows, environment identity, and descendant `parent_id` values are unchanged.
The hierarchy update and workspace-mode update are persisted in the same task-row update.
## API surface
`POST /api/v1/tasks/:id/detach`
- Request body: none.
- Success: `200` with the updated task DTO. An already-root task returns its unchanged DTO.
- Missing task: `404`.
- Persistence failure: `500`; no successful response is returned.
On success, the backend publishes `task.updated`. Its payload includes `parent_id` even when cleared so clients can remove a previously cached parent relationship. When metadata changes, the payload includes the updated workspace policy.
## State transition
The operation has one transition:
`child(parent_id != "")` -> `root(parent_id = "")`
If workspace mode is `inherit_parent`, the same operation also transitions it to `shared_group`. No task, session, workflow, or executor lifecycle state changes.
## Failure modes
- If the task no longer exists, the UI keeps its current state and shows the request error.
- If persistence fails, neither the UI nor API reports success. The task remains attached according to durable state.
- Repeated submissions are safe because detaching an already-root task is a no-op.
- Detachment does not create, copy, move, clean, or delete workspace files. It can transfer the logical stewardship of those files.
## Persistence guarantees
The cleared parent relationship, normalized workspace mode, current workspace steward, and ownership generation survive backend restarts. See [Detached Workspace Continuity](detached-workspace-continuity.md) for the cleanup and concurrency contract.
## Scenarios
- **GIVEN** a subtask in the sidebar, **WHEN** the user chooses `Detach from parent` from its right-click menu and confirms, **THEN** the task appears as a top-level task without a page reload.
- **GIVEN** a subtask card on the kanban board, **WHEN** the user detaches it from the three-dot menu, **THEN** the card remains in the same workflow step and no longer belongs to its former parent.
- **GIVEN** a root task, **WHEN** either task menu opens, **THEN** `Detach from parent` is not shown.
- **GIVEN** an `inherit_parent` subtask, **WHEN** the confirmation opens, **THEN** it warns that the shared workspace remains shared.
- **GIVEN** an `inherit_parent` subtask with an active workspace-group membership, **WHEN** it is detached, **THEN** its mode becomes `shared_group`, its membership remains active, and later sessions resolve the same materialized environment.
- **GIVEN** a `new_workspace` or `shared_group` subtask, **WHEN** it is detached, **THEN** its workspace mode and workspace-group membership remain unchanged.
- **GIVEN** a subtask with descendants and blocker relationships, **WHEN** it is detached, **THEN** its descendants remain nested beneath it and all blocker relationships remain unchanged.
- **GIVEN** an Office task with a parent, **WHEN** the user chooses `No parent` in the parent picker, **THEN** the canonical detach operation applies the same workspace behavior.
- **GIVEN** a detached task update received over WebSocket, **WHEN** the client merges it into cached task state, **THEN** the prior parent relationship is cleared rather than preserved.
- **GIVEN** the mobile task switcher, **WHEN** a user opens the touch-accessible actions for a subtask, **THEN** the same detach and confirmation flow is available.
## Out of scope
- Reparenting a task to a different parent from the sidebar or kanban card menus (now covered by [subtask-reparenting-drag-drop](subtask-reparenting-drag-drop.md) for the sidebar; kanban-card reparenting remains out of scope).
- Copying or provisioning a separate workspace during detachment.
- Removing blocker relationships or changing descendant relationships.
- Stopping or restarting active sessions.
- Bulk detachment.
- Synthesizing an `on_children_completed` trigger for the former parent.
## Implementation plan
See [the implementation plan](../../../plans/subtask-detachment/plan.md).