docs: migrate task and workflow specs (#2957)

2026-08-23 17:34:52 +00:00
parent 94fd9dcd44
commit 8620537f0c
460 changed files with 5554 additions and 3724 deletions
@@ -280,7 +280,11 @@ class PRWalkthroughWorkflowContractTest(unittest.TestCase):
        self.assertIn("scripts/pr-walkthrough-pr-body", self.link)
        self.assertIn("--github-response", self.link)
        self.assertIn("--input", self.link)
-        self.assertIn("needs.pr-walkthrough-publish.outputs.url", self.link)
+        self.assertIn(
+            'PUBLIC_URL="https://walkthrough.kandev.ai/pr/${PR_NUMBER}/${HEAD_SHA}.html"',
+            self.link,
+        )
+        self.assertNotIn("needs.pr-walkthrough-publish.outputs.url", self.link)
        self.assertNotIn("CLOUDFLARE_R2", self.link)
        self.assertNotIn("OPENCODE_API_KEY", self.link)
        self.assertTrue(PR_BODY_HELPER.is_file())
@@ -337,11 +337,10 @@ jobs:
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
-          PUBLIC_URL: ${{ needs.pr-walkthrough-publish.outputs.url }}
        run: |
          set -euo pipefail
          test "$(git rev-parse HEAD)" = "$BASE_SHA"
-          test -n "$PUBLIC_URL"
+          PUBLIC_URL="https://walkthrough.kandev.ai/pr/${PR_NUMBER}/${HEAD_SHA}.html"

          gh api "repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}" > pr-response.json

@@ -913,7 +913,7 @@ func (h *Handlers) handleCreateTask(ctx context.Context, msg *ws.Message) (*ws.M

 // mcpCreateTaskResult is create_task_kandev's tool-result shape: the task
 // DTO plus deduplicated/creation_complete, per
-// docs/specs/tasks/external-id-idempotency/spec.md, "MCP" — required
+// docs/specs/tasks/system-design/external-id-idempotency.md, "MCP" — required
 // booleans, not presence-only markers, mirroring the REST create response.
 type mcpCreateTaskResult struct {
 	dto.TaskDTO
@@ -93,7 +93,7 @@ func (h *Handlers) resolveMessageTargetSession(
 		// A terminal primary with nothing live is handed to dispatch rather than
 		// rejected here, so the caller still gets the documented
 		// INTERNAL_ERROR for "target session FAILED/CANCELLED"
-		// (docs/specs/tasks/parent-child-message-interrupt.md, "Errors").
+		// (docs/specs/tasks/requirements/parent-child-message-interrupt.md, "Errors").
 		// Only the message improves; the code is a contract this change has no
 		// business rewriting as a side effect.
 		return primary, true, nil
@@ -117,7 +117,7 @@ func TestHandleMessageTask_LivePrimaryKeepsPriorityOverNewerSessions(t *testing.
 //
 // The CODE stays INTERNAL_ERROR. "Target session FAILED/CANCELLED ->
 // INTERNAL_ERROR" is written down in
-// docs/specs/tasks/parent-child-message-interrupt.md, so improving the message
+// docs/specs/tasks/requirements/parent-child-message-interrupt.md, so improving the message
 // must not quietly reclassify it: a terminal primary with nothing live is
 // handed to dispatch exactly as before.
 func TestHandleMessageTask_AllSessionsTerminalNamesTheRecoveryTool(t *testing.T) {
@@ -13,7 +13,7 @@ import (

 // registerRecordStepDecisionTool registers record_step_decision_kandev, the
 // Office quorum decision-recording tool. Per the tool contract in
-// docs/specs/workflow-quorum-decision-recording/spec.md, it takes no
+// docs/specs/tasks/requirements/workflow-quorum-decision-recording-agent-surface.md, it takes no
 // task_id — task/step/role are resolved server-side from the calling
 // session, matching every other Office tool.
 func (s *Server) registerRecordStepDecisionTool() {
@@ -368,7 +368,7 @@ func (r *Repository) runTaskPriorityRecreate() error {
 	_, _ = conn.ExecContext(ctx, `ALTER TABLE tasks ADD COLUMN queued_at TIMESTAMP`)
 	_, _ = conn.ExecContext(ctx, `ALTER TABLE tasks ADD COLUMN autopilot_enabled INTEGER NOT NULL DEFAULT 0`)
 	// Same defensive add for external_id/external_id_settled_at
-	// (docs/specs/tasks/external-id-idempotency): real installs already have
+	// (docs/specs/tasks/system-design/external-id-idempotency.md): real installs already have
 	// these from task/repository/sqlite/base.go runMigrations(), but older
 	// priority-migration fixtures predate them too.
 	_, _ = conn.ExecContext(ctx, `ALTER TABLE tasks ADD COLUMN external_id TEXT COLLATE BINARY`)
@@ -476,7 +476,7 @@ func taskPriorityMigrationStatements() []string {
 		// per-task assignee moved to workflow_step_participants.
 		//
 		// uniq_tasks_external_id enforces task create-idempotency
-		// (docs/specs/tasks/external-id-idempotency). DROP TABLE tasks above
+		// (docs/specs/tasks/system-design/external-id-idempotency.md). DROP TABLE tasks above
 		// silently drops every index on the old table, this one included —
 		// unlike a plain ALTER TABLE ADD COLUMN, recreating the table means
 		// every index must be explicitly relisted here or it is gone from
@@ -236,7 +236,7 @@ type TaskDTO struct {
 	Labels                 string `json:"labels,omitempty"`
 	Identifier             string `json:"identifier,omitempty"`
 	// ExternalID is a caller-supplied identity used for task create-
-	// idempotency (docs/specs/tasks/external-id-idempotency/spec.md). Omitted
+	// idempotency (docs/specs/tasks/requirements/external-id-idempotency.md). Omitted
 	// when the task holds none.
 	ExternalID string `json:"external_id,omitempty"`
 	// IsFromOffice is the authoritative "this task is owned by office"
@@ -138,7 +138,7 @@ func (h *TaskHandlers) registerHTTP(router *gin.Engine) {
 	api := router.Group("/api/v1")
 	api.GET("/workflows/:id/tasks", h.httpListTasks)
 	api.GET("/workspaces/:id/tasks", h.httpListTasksByWorkspace)
-	// Task create-idempotency (docs/specs/tasks/external-id-idempotency):
+	// Task create-idempotency (docs/specs/tasks/requirements/external-id-idempotency.md):
 	// side-effect-free lookup, and an operator-only release. Both take
 	// external_id as a query parameter.
 	api.GET("/workspaces/:id/tasks/by-external-id", h.httpGetTaskByExternalID)
@@ -747,7 +747,7 @@ type httpCreateTaskRequest struct {
 	StartWhenUnblocked *bool  `json:"start_when_unblocked,omitempty"`
 	ProjectID          string `json:"project_id,omitempty"`
 	// ExternalID is a caller-supplied identity used for create-idempotency
-	// (docs/specs/tasks/external-id-idempotency/spec.md).
+	// (docs/specs/tasks/requirements/external-id-idempotency.md).
 	ExternalID string   `json:"external_id,omitempty"`
 	Labels     []string `json:"labels,omitempty"`
 	// Office task-handoffs phase 5 — workspace policy. Optional; same
@@ -764,7 +764,7 @@ type createTaskResponse struct {
 	AgentExecutionID string `json:"agent_execution_id,omitempty"`
 	// Deduplicated and CreationComplete are required booleans (not
 	// presence-only markers) on every create-idempotency outcome, per
-	// docs/specs/tasks/external-id-idempotency/spec.md. Deduplicated is true
+	// docs/specs/tasks/requirements/external-id-idempotency.md. Deduplicated is true
 	// for both Found outcomes. CreationComplete is false only for
 	// Found-unsettled — every other outcome (including CreatedIdentityLost)
 	// carries true, because the field means only "this task's required
@@ -1082,7 +1082,7 @@ type lookupTaskResponse struct {
 }

 // httpGetTaskByExternalID is the REST lookup route
-// (docs/specs/tasks/external-id-idempotency/spec.md, "REST — lookup"): a
+// (docs/specs/tasks/system-design/external-id-idempotency.md, "REST — lookup"): a
 // side-effect-free way to ask what holds an identity without risking a
 // create. Returns the task whether settled or not, including archived tasks.
 func (h *TaskHandlers) httpGetTaskByExternalID(c *gin.Context) {
@@ -1098,7 +1098,7 @@ func (h *TaskHandlers) httpGetTaskByExternalID(c *gin.Context) {
 }

 // httpReleaseTaskExternalID is the REST release route
-// (docs/specs/tasks/external-id-idempotency/spec.md, "REST — release"): an
+// (docs/specs/tasks/system-design/external-id-idempotency.md, "REST — release"): an
 // operator action for an identity a human has determined is abandoned. Frees
 // the identity without deleting or otherwise modifying the task. MUST NOT be
 // called automatically in response to creation_complete:false — see "The one
@@ -1375,7 +1375,7 @@ type startAgentDispatch struct {
 // step (part of step 6, "required synchronous post-create work") — it MUST
 // run, and be allowed to fail, before settlement (step 7). Only the
 // resulting agent launch is asynchronous dispatch (step 8), which must run
-// after settlement (docs/specs/tasks/external-id-idempotency/spec.md,
+// after settlement (docs/specs/tasks/system-design/external-id-idempotency.md,
 // "Settlement call site (normative, per surface)": "the helper must expose
 // preparation and dispatch separately so settlement can sit between them").
 // A prior shape settled before calling this at all, which satisfied "no
@@ -382,7 +382,7 @@ func TestHTTPCreateTask_InvalidExternalIDReturns400(t *testing.T) {
 //
 // Synchronous session prepare (create-sequence step 6) DOES run here, and
 // must: it happens before settlement (step 7) discovers the CreatedIdentityLost
-// outcome, per the settlement-ordering fix (docs/specs/tasks/external-id-idempotency/spec.md,
+// outcome, per the settlement-ordering fix (docs/specs/tasks/system-design/external-id-idempotency.md,
 // "Settlement call site (normative, per surface)"). Only the asynchronous
 // start dispatch (step 8) is guaranteed to never fire — that is the actual
 // "no side effects" guarantee the spec makes for this outcome ("no
@@ -522,7 +522,7 @@ func TestHTTPReleaseTaskExternalID_NotFound(t *testing.T) {
 // orderRecordingOrchestrator records whether the task was already settled
 // (external_id_settled_at set) at the moment synchronous session prepare
 // (orchestrator.IntentPrepare) was invoked — a direct, observable proof of
-// create-sequence ordering (docs/specs/tasks/external-id-idempotency/spec.md,
+// create-sequence ordering (docs/specs/tasks/system-design/external-id-idempotency.md,
 // "Settlement call site (normative, per surface)"): settlement (step 7) must
 // never precede synchronous session prepare (part of step 6). Only the
 // asynchronous dispatch (step 8, the actual agent-start goroutine) may run
@@ -834,7 +834,7 @@ type Task struct {
 	Identifier             string `json:"identifier,omitempty"` // e.g. "KAN-42"

 	// ExternalID is a caller-supplied identity used for create-idempotency
-	// (docs/specs/tasks/external-id-idempotency/spec.md). Empty when the task
+	// (docs/specs/tasks/requirements/external-id-idempotency.md). Empty when the task
 	// holds none. Unique per (workspace_id, external_id) when non-empty.
 	ExternalID string `json:"external_id,omitempty"`
 	// ExternalIDSettledAt is non-nil once the create that claimed ExternalID
@@ -30,7 +30,7 @@ var ErrTaskEnvironmentNotFound = errors.New("task environment not found")

 // ErrExternalIDConflict reports that a task insert lost the uniqueness race
 // on uniq_tasks_external_id — the TOCTOU backstop for the create sequence's
-// step-3 lookup (docs/specs/tasks/external-id-idempotency/spec.md). Callers
+// step-3 lookup (docs/specs/tasks/system-design/external-id-idempotency.md). Callers
 // must re-read by (workspace_id, external_id) and return the winner as a
 // Found outcome rather than surfacing this error.
 var ErrExternalIDConflict = errors.New("external_id already claimed by another task")
@@ -276,7 +276,7 @@ func (r *Repository) runMigrations() error {
 	// unarchive can restore exactly the descendants that cascade archived.
 	r.migrate.Apply("tasks.archived_by_cascade_id", `ALTER TABLE tasks ADD COLUMN archived_by_cascade_id TEXT DEFAULT ''`)

-	// Task create-idempotency (docs/specs/tasks/external-id-idempotency).
+	// Task create-idempotency (docs/specs/tasks/system-design/external-id-idempotency.md).
 	// external_id needs an explicit deterministic collation: SQLite TEXT
 	// columns already compare BINARY by default, but an unqualified Postgres
 	// column silently inherits the database's default collation, which may be
@@ -16,7 +16,7 @@ import (
 // externalIDIndexName is the partial unique index enforcing at most one task
 // per (workspace_id, external_id). Naming it explicitly here keeps
 // isExternalIDUniqueViolation attributable to this constraint specifically —
-// see docs/specs/tasks/external-id-idempotency/spec.md, "Unique-violation
+// see docs/specs/tasks/system-design/external-id-idempotency.md, "Unique-violation
 // classification across dialects".
 const externalIDIndexName = "uniq_tasks_external_id"

@@ -46,7 +46,7 @@ func TestPostgresTaskPriorityMigrationConvertsLegacyInteger(t *testing.T) {

 // TestPostgresExternalIDConcurrentInsertYieldsExactlyOneWinner is the
 // PostgreSQL twin of the SQLite concurrency coverage
-// (docs/specs/tasks/external-id-idempotency/spec.md, "Uniqueness and
+// (docs/specs/tasks/system-design/external-id-idempotency.md, "Uniqueness and
 // concurrency"): the SQLite path passing is not evidence for Postgres, since
 // the two drivers classify unique-violation errors completely differently
 // (typed pgconn.PgError vs. SQLite driver string-matching). Skips unless
@@ -12,7 +12,7 @@ import (
 )

 // ExternalIDMaxBytes is the maximum UTF-8 byte length of a normalized
-// external_id (docs/specs/tasks/external-id-idempotency/spec.md,
+// external_id (docs/specs/tasks/system-design/external-id-idempotency.md,
 // "Validation and normalization").
 const ExternalIDMaxBytes = 255

@@ -96,7 +96,7 @@ func (s *Service) GetTaskByExternalID(ctx context.Context, workspaceID, rawExter

 // ReleaseTaskExternalID is the REST release route's service-level
 // implementation: an operator action that frees an identity without
-// deleting the task holding it (docs/specs/tasks/external-id-idempotency/spec.md,
+// deleting the task holding it (docs/specs/tasks/requirements/external-id-idempotency.md,
 // "The one unsafe thing a caller can do" — this is for a human who has
 // determined the task is abandoned, not an automated retry loop). Returns
 // whether a task held the identity. Publishes task.updated on success, like
@@ -123,7 +123,7 @@ func (s *Service) ReleaseTaskExternalID(ctx context.Context, workspaceID, rawExt
 }

 // SettleExternalID performs the create sequence's step 7 (settlement) for a
-// task the caller just created (docs/specs/tasks/external-id-idempotency/spec.md,
+// task the caller just created (docs/specs/tasks/system-design/external-id-idempotency.md,
 // "Settlement"). Handlers call this after their surface's required
 // synchronous work finishes and before any asynchronous dispatch. Safe to
 // call unconditionally: a request with no external_id (externalID == "")
@@ -404,7 +404,7 @@ func (s *Service) publishTaskEventNow(ctx context.Context, eventType string, tas
 	if task.ParentID != "" {
 		data["parent_id"] = task.ParentID
 	}
-	// external_id (docs/specs/tasks/external-id-idempotency): omitted rather
+	// external_id (docs/specs/tasks/requirements/external-id-idempotency.md): omitted rather
 	// than sent as null/"" when the task holds none, matching the REST DTO's
 	// omitempty and parent_id's convention above. This map is hand-built, not
 	// derived from TaskDTO, so it needs its own explicit field.
@@ -73,7 +73,7 @@ type CreateTaskRequest struct {
 	WorkspacePath  string                 `json:"workspace_path,omitempty"` // Optional host folder for repo-less tasks

 	// ExternalID is a caller-supplied identity used for create-idempotency
-	// (docs/specs/tasks/external-id-idempotency/spec.md). Accepted on REST
+	// (docs/specs/tasks/requirements/external-id-idempotency.md). Accepted on REST
 	// and MCP; empty means no idempotency key.
 	ExternalID string `json:"external_id,omitempty"`

@@ -120,7 +120,7 @@ func isOfficeRequest(req *CreateTaskRequest) bool {

 // CreateTaskOutcome distinguishes why Service.CreateTask returned the task it
 // did, per the create-idempotency contract
-// (docs/specs/tasks/external-id-idempotency/spec.md). Only meaningful when
+// (docs/specs/tasks/requirements/external-id-idempotency.md). Only meaningful when
 // the request carried an external_id; a request without one always reports
 // CreateTaskOutcomeCreated. The fourth contract outcome, CreatedIdentityLost,
 // is not produced here — it is decided by the handler during settlement,
@@ -162,7 +162,7 @@ func foundOutcomeFor(task *models.Task) CreateTaskOutcome {
 // CreateTask creates a new task and publishes a task.created event, or —
 // when the request carries an external_id already held by a task — returns
 // that task instead, per the create-idempotency contract
-// (docs/specs/tasks/external-id-idempotency/spec.md). WorkflowID is required
+// (docs/specs/tasks/requirements/external-id-idempotency.md). WorkflowID is required
 // for non-ephemeral kanban tasks. Office tasks (project_id set, or origin is
 // agent_created/routine) auto-resolve to the workspace's office workflow.
 // Ephemeral tasks (quick chat, config chat) must NOT have a workflow.
@@ -6,7 +6,7 @@ import type { ApiClient } from "../../helpers/api-client";
 * E2E coverage for the workflow engine's guarded `move_to_step` transitions
 * (the office-default template's Review/Approval steps, each gated by a
 * `wait_for_quorum` action). Spec:
- *   docs/specs/workflow-quorum-decision-recording/spec.md
+ *   docs/specs/tasks/requirements/workflow-quorum-decision-recording.md
 *
 * Drives Work -> Review -> Approval with a reviewer and an approver
 * attached, asserting advance-on-approve, return-on-reject, and the AC-25
@@ -63,4 +63,4 @@ Backend:
 Frontend:
 - `apps/web/components/task/chat/messages/kandev/task-renderers.tsx`

-Spec: `docs/specs/tasks/multi-branch/spec.md`
+Spec: `docs/specs/tasks/requirements/multi-branch.md`
@@ -139,4 +139,4 @@ Frontend:
 - `apps/web/lib/types/http.ts` *(extend `WorkflowStep`)*
 - `apps/web/lib/state/slices/` *(transitional state for "completion pending")*

-Spec: `docs/specs/workflow/explicit-completion-signal/spec.md` *(to be written via `/spec` once this ADR is accepted)*
+Spec: `docs/specs/tasks/requirements/workflow-explicit-completion-signal.md`
@@ -4,7 +4,7 @@
 **Date:** 2026-08-08
 **Area:** backend, agentctl, protocol
 **Related ADR:** [ADR-2026-08-08-task-autopilot-contract](2026-08-08-task-autopilot-contract.md)
-**Related spec:** [Task Autopilot Mode](../specs/tasks/autopilot-mode.md)
+**Related spec:** [Task Autopilot Mode](../specs/tasks/requirements/autopilot-mode.md)

 ## Context

@@ -4,7 +4,7 @@
 **Date:** 2026-08-08
 **Area:** backend, agentctl, protocol, workflow
 **Related ADR:** [ADR-2026-08-08-autopilot-mcp-question-capabilities](2026-08-08-autopilot-mcp-question-capabilities.md)
-**Related spec:** [Task Autopilot Mode](../specs/tasks/autopilot-mode.md)
+**Related spec:** [Task Autopilot Mode](../specs/tasks/requirements/autopilot-mode.md)

 ## Context

@@ -4,7 +4,7 @@
 **Date:** 2026-08-08
 **Area:** backend, agentctl, frontend, protocol, workflow
 **Related issue:** [#2425](https://github.com/kdlbs/kandev/issues/2425)
-**Related spec:** [Task Autopilot Mode](../specs/tasks/autopilot-mode.md)
+**Related spec:** [Task Autopilot Mode](../specs/tasks/requirements/autopilot-mode.md)

 ## Context

@@ -1,5 +1,5 @@
 ---
-spec: docs/specs/tasks/agent-generated-titles.md
+spec: docs/specs/tasks/requirements/agent-generated-titles.md
 created: 2026-07-31
 updated: 2026-08-02
 status: done
@@ -5,7 +5,7 @@ status: done
 wave: 1
 depends_on: []
 plan: "plan.md"
-spec: "../../specs/tasks/agent-generated-titles.md"
+spec: "../../specs/tasks/requirements/agent-generated-titles.md"
 ---

 # Task 01: Backend preference and provisional-title lifecycle
@@ -5,7 +5,7 @@ status: done
 wave: 2
 depends_on: ["01-backend-title-lifecycle"]
 plan: "plan.md"
-spec: "../../specs/tasks/agent-generated-titles.md"
+spec: "../../specs/tasks/requirements/agent-generated-titles.md"
 ---

 # Task 02: Task MCP tool and first-turn instruction
@@ -5,7 +5,7 @@ status: done
 wave: 3
 depends_on: ["01-backend-title-lifecycle", "02-mcp-title-tool"]
 plan: "plan.md"
-spec: "../../specs/tasks/agent-generated-titles.md"
+spec: "../../specs/tasks/requirements/agent-generated-titles.md"
 ---

 # Task 03: Settings and task/subtask dialogs
@@ -5,7 +5,7 @@ status: done
 wave: 4
 depends_on: ["01-backend-title-lifecycle", "02-mcp-title-tool", "03-frontend-title-flow"]
 plan: "plan.md"
-spec: "../../specs/tasks/agent-generated-titles.md"
+spec: "../../specs/tasks/requirements/agent-generated-titles.md"
 ---

 # Task 04: End-to-end coverage and public docs
@@ -5,7 +5,7 @@ status: done
 wave: 5
 depends_on: ["02-mcp-title-tool"]
 plan: "plan.md"
-spec: "../../specs/tasks/agent-generated-titles.md"
+spec: "../../specs/tasks/requirements/agent-generated-titles.md"
 ---

 # Task 05: Single-owner title handoff
@@ -5,7 +5,7 @@ status: done
 wave: 6
 depends_on: ["05-single-owner-title-handoff"]
 plan: "plan.md"
-spec: "../../specs/tasks/agent-generated-titles.md"
+spec: "../../specs/tasks/requirements/agent-generated-titles.md"
 ---

 # Task 06: Default-on title preference
@@ -5,7 +5,7 @@ status: done
 wave: 7
 depends_on: ["05-single-owner-title-handoff", "06-default-on-title-preference"]
 plan: "plan.md"
-spec: "../../specs/tasks/agent-generated-titles.md"
+spec: "../../specs/tasks/requirements/agent-generated-titles.md"
 ---

 # Task 07: Regression coverage and public docs
@@ -1,5 +1,5 @@
 ---
-spec: docs/specs/tasks/agent-generated-titles.md
+spec: docs/specs/tasks/requirements/agent-generated-titles.md
 created: 2026-08-04
 status: complete
 ---
@@ -5,7 +5,7 @@ status: done
 wave: 1
 depends_on: []
 plan: "plan.md"
-spec: "../../specs/tasks/agent-generated-titles.md"
+spec: "../../specs/tasks/requirements/agent-generated-titles.md"
 ---

 # Task 01: Branch rename runtime
@@ -5,7 +5,7 @@ status: done
 wave: 2
 depends_on: ["01-branch-rename-runtime"]
 plan: "plan.md"
-spec: "../../specs/tasks/agent-generated-titles.md"
+spec: "../../specs/tasks/requirements/agent-generated-titles.md"
 ---

 # Task 02: Title tool integration
@@ -5,7 +5,7 @@ status: done
 wave: 3
 depends_on: ["02-title-tool-integration"]
 plan: "plan.md"
-spec: "../../specs/tasks/agent-generated-titles.md"
+spec: "../../specs/tasks/requirements/agent-generated-titles.md"
 ---

 # Task 03: Regression documentation
@@ -1,5 +1,5 @@
 ---
-spec: docs/specs/tasks/archive-confirmation.md
+spec: docs/specs/tasks/requirements/archive-confirmation.md
 created: 2026-07-15
 status: completed
 ---
@@ -5,7 +5,7 @@ status: done
 wave: 1
 depends_on: []
 plan: "plan.md"
-spec: "../../specs/tasks/archive-confirmation.md"
+spec: "../../specs/tasks/requirements/archive-confirmation.md"
 ---

 # Task 01: Backend Archive Confirmation Preference
@@ -5,7 +5,7 @@ status: done
 wave: 2
 depends_on: ["01-backend-preference"]
 plan: "plan.md"
-spec: "../../specs/tasks/archive-confirmation.md"
+spec: "../../specs/tasks/requirements/archive-confirmation.md"
 ---

 # Task 02: Frontend Archive Confirmation Behavior
@@ -5,7 +5,7 @@ status: done
 wave: 3
 depends_on: ["02-frontend-behavior"]
 plan: "plan.md"
-spec: "../../specs/tasks/archive-confirmation.md"
+spec: "../../specs/tasks/requirements/archive-confirmation.md"
 ---

 # Task 03: Archive Preference E2E and Verification
@@ -30,7 +30,7 @@ cd apps/web && pnpm run typecheck && pnpm run lint

 - `apps/web/e2e/tests/task/archive-confirmation-preference.spec.ts`
 - `apps/web/e2e/tests/task/mobile-archive-confirmation-preference.spec.ts`
- `docs/specs/tasks/archive-confirmation.md`
+- `docs/specs/tasks/requirements/archive-confirmation.md`
 - `docs/plans/archive-confirmation-preference/*.md`

 ## Inputs
@@ -1,5 +1,5 @@
 ---
-spec: docs/specs/tasks/attach-workspace-sources.md
+spec: docs/specs/tasks/system-design/attach-workspace-sources.md
 created: 2026-07-22
 status: completed
 ---
@@ -5,7 +5,7 @@ status: done
 wave: 1
 depends_on: []
 plan: "plan.md"
-spec: "../../specs/tasks/attach-workspace-sources.md"
+spec: "../../specs/tasks/system-design/attach-workspace-sources.md"
 ---

 # Task 01: Durable Source Contracts
@@ -5,7 +5,7 @@ status: done
 wave: 2
 depends_on: ["01-durable-source-contracts"]
 plan: "plan.md"
-spec: "../../specs/tasks/attach-workspace-sources.md"
+spec: "../../specs/tasks/system-design/attach-workspace-sources.md"
 ---

 # Task 02: Attachment Service
@@ -5,7 +5,7 @@ status: done
 wave: 3
 depends_on: ["02-attachment-service"]
 plan: "plan.md"
-spec: "../../specs/tasks/attach-workspace-sources.md"
+spec: "../../specs/tasks/system-design/attach-workspace-sources.md"
 ---

 # Task 03: Protocol Surfaces
@@ -5,7 +5,7 @@ status: done
 wave: 3
 depends_on: ["02-attachment-service"]
 plan: "plan.md"
-spec: "../../specs/tasks/attach-workspace-sources.md"
+spec: "../../specs/tasks/system-design/attach-workspace-sources.md"
 ---

 # Task 04: Host Materialization
@@ -5,7 +5,7 @@ status: done
 wave: 4
 depends_on: ["03-protocol-surfaces", "04-host-materialization"]
 plan: "plan.md"
-spec: "../../specs/tasks/attach-workspace-sources.md"
+spec: "../../specs/tasks/system-design/attach-workspace-sources.md"
 ---

 # Task 05: Remote Materialization
@@ -5,7 +5,7 @@ status: done
 wave: 3
 depends_on: ["02-attachment-service"]
 plan: "plan.md"
-spec: "../../specs/tasks/attach-workspace-sources.md"
+spec: "../../specs/tasks/system-design/attach-workspace-sources.md"
 ---

 # Task 06: Shared Source Picker
@@ -5,7 +5,7 @@ status: done
 wave: 4
 depends_on: ["03-protocol-surfaces", "06-shared-source-picker"]
 plan: "plan.md"
-spec: "../../specs/tasks/attach-workspace-sources.md"
+spec: "../../specs/tasks/system-design/attach-workspace-sources.md"
 ---

 # Task 07: Files Panel Surface
@@ -5,7 +5,7 @@ status: completed
 wave: 5
 depends_on: ["05-remote-materialization", "07-files-panel-surface"]
 plan: "plan.md"
-spec: "../../specs/tasks/attach-workspace-sources.md"
+spec: "../../specs/tasks/system-design/attach-workspace-sources.md"
 ---

 # Task 08: End-to-End Coverage
@@ -5,7 +5,7 @@ status: done
 wave: 5
 depends_on: ["05-remote-materialization", "07-files-panel-surface"]
 plan: "plan.md"
-spec: "../../specs/tasks/attach-workspace-sources.md"
+spec: "../../specs/tasks/system-design/attach-workspace-sources.md"
 ---

 # Task 09: Public Documentation
@@ -5,7 +5,7 @@ status: completed
 wave: 6
 depends_on: ["08-end-to-end-coverage", "09-public-documentation"]
 plan: "plan.md"
-spec: "../../specs/tasks/attach-workspace-sources.md"
+spec: "../../specs/tasks/system-design/attach-workspace-sources.md"
 ---

 # Task 10: Final Verification
@@ -6,7 +6,7 @@ wave: 7
 depends_on:
  - "06-shared-source-picker"
 plan: "plan.md"
-spec: "../../specs/tasks/attach-workspace-sources.md"
+spec: "../../specs/tasks/system-design/attach-workspace-sources.md"
 ---

 # Task 11: Tab-free repository source chooser
@@ -6,7 +6,7 @@ wave: 7
 depends_on:
  - "07-files-panel-surface"
 plan: "plan.md"
-spec: "../../specs/tasks/attach-workspace-sources.md"
+spec: "../../specs/tasks/system-design/attach-workspace-sources.md"
 ---

 # Task 12: Unified Files workspace actions
@@ -7,7 +7,7 @@ depends_on:
  - "11-shared-local-remote-selector"
  - "12-unified-files-workspace-actions"
 plan: "plan.md"
-spec: "../../specs/tasks/attach-workspace-sources.md"
+spec: "../../specs/tasks/system-design/attach-workspace-sources.md"
 ---

 # Task 13: UX delta end-to-end coverage
@@ -7,7 +7,7 @@ depends_on:
  - "11-shared-local-remote-selector"
  - "12-unified-files-workspace-actions"
 plan: "plan.md"
-spec: "../../specs/tasks/attach-workspace-sources.md"
+spec: "../../specs/tasks/system-design/attach-workspace-sources.md"
 ---

 # Task 14: UX terminology documentation
@@ -2,7 +2,7 @@
 spec: docs/specs/platform/agent-runtime-availability.md
 related_specs:
  - docs/specs/office/costs.md
-  - docs/specs/tasks/runtime-cleanup.md
+  - docs/specs/tasks/system-design/runtime-cleanup.md
  - docs/specs/ui/entity-reference-composer.md
 created: 2026-08-08
 status: completed
@@ -5,7 +5,7 @@ status: done
 wave: 1
 depends_on: []
 plan: "plan.md"
-spec: "../../specs/tasks/runtime-cleanup.md"
+spec: "../../specs/tasks/system-design/runtime-cleanup.md"
 ---

 # Task 06: Classify startup runtime cleanup
@@ -13,8 +13,8 @@ package and is separately reviewable.
 ## Related Specs

 - `docs/specs/platform/cron-office-disabled-safety.md` (Task 01, new repair spec)
- `docs/specs/tasks/title-length-limit.md` (Task 02, amended)
- `docs/specs/tasks/runtime-cleanup.md` (Task 03, amended)
+- `docs/specs/tasks/requirements/title-length-limit.md` (Task 02, amended)
+- `docs/specs/tasks/system-design/runtime-cleanup.md` (Task 03, amended)

 ## Root Causes

@@ -5,7 +5,7 @@ status: complete
 wave: 1
 depends_on: []
 plan: "plan.md"
-spec: "../../specs/tasks/title-length-limit.md"
+spec: "../../specs/tasks/requirements/title-length-limit.md"
 parallel-safe: true
 ---

@@ -71,7 +71,7 @@ None.

 ## Inputs

- Amended spec: `docs/specs/tasks/title-length-limit.md` (watcher-title bullet
+- Amended spec: `docs/specs/tasks/requirements/title-length-limit.md` (watcher-title bullet
  and scenarios).
 - Confirmed 5 "task title is too long" review-task failures in the logs
  (PRs #12096, #12057, #12054).
@@ -5,7 +5,7 @@ status: complete
 wave: 1
 depends_on: []
 plan: "plan.md"
-spec: "../../specs/tasks/runtime-cleanup.md"
+spec: "../../specs/tasks/system-design/runtime-cleanup.md"
 parallel-safe: false
 ---

@@ -82,7 +82,7 @@ consistent. Not parallel-safe.

 ## Inputs

- Amended spec: `docs/specs/tasks/runtime-cleanup.md` (confirmed-dead
+- Amended spec: `docs/specs/tasks/system-design/runtime-cleanup.md` (confirmed-dead
  not-found-as-stopped bullets, failure modes, and scenarios).
 - Existing runtime-aware liveness: `lifecycle.RowProcessLiveness` /
  `models.ProcessLiveness` and `RowMustBePreserved`
@@ -1,5 +1,5 @@
 ---
-spec: docs/specs/workflow/cancelled-turn-completion/spec.md
+spec: docs/specs/tasks/requirements/workflow-cancelled-turn-completion.md
 created: 2026-08-02
 status: implemented
 ---
@@ -5,7 +5,7 @@ status: done
 wave: 1
 depends_on: []
 plan: "plan.md"
-spec: "../../specs/workflow/cancelled-turn-completion/spec.md"
+spec: "../../specs/tasks/requirements/workflow-cancelled-turn-completion.md"
 ---

 # Task 01: Workflow step persistence contract
@@ -5,7 +5,7 @@ status: done
 wave: 2
 depends_on: ["01-step-contract-and-template"]
 plan: "plan.md"
-spec: "../../specs/workflow/cancelled-turn-completion/spec.md"
+spec: "../../specs/tasks/requirements/workflow-cancelled-turn-completion.md"
 ---

 # Task 02: Workflow configuration surfaces
@@ -5,7 +5,7 @@ status: done
 wave: 2
 depends_on: ["01-step-contract-and-template"]
 plan: "plan.md"
-spec: "../../specs/workflow/cancelled-turn-completion/spec.md"
+spec: "../../specs/tasks/requirements/workflow-cancelled-turn-completion.md"
 ---

 # Task 03: Explicit cancellation workflow routing
@@ -5,7 +5,7 @@ status: completed
 wave: 3
 depends_on: ["02-configuration-surfaces"]
 plan: "plan.md"
-spec: "../../specs/workflow/cancelled-turn-completion/spec.md"
+spec: "../../specs/tasks/requirements/workflow-cancelled-turn-completion.md"
 ---

 # Task 04: Workflow cancellation setting UI
@@ -5,7 +5,7 @@ status: completed
 wave: 3
 depends_on: ["01-step-contract-and-template", "02-configuration-surfaces"]
 plan: "plan.md"
-spec: "../../specs/workflow/cancelled-turn-completion/spec.md"
+spec: "../../specs/tasks/requirements/workflow-cancelled-turn-completion.md"
 ---

 # Task 05: Cancelled turn public documentation
@@ -5,7 +5,7 @@ status: completed
 wave: 4
 depends_on: ["03-cancellation-routing", "04-settings-ui"]
 plan: "plan.md"
-spec: "../../specs/workflow/cancelled-turn-completion/spec.md"
+spec: "../../specs/tasks/requirements/workflow-cancelled-turn-completion.md"
 ---

 # Task 06: Cancelled turn E2E coverage
@@ -1,5 +1,5 @@
 ---
-spec: docs/specs/tasks/archive-confirmation.md
+spec: docs/specs/tasks/requirements/archive-confirmation.md
 created: 2026-08-12
 status: complete
 ---
@@ -5,7 +5,7 @@ status: done
 wave: 1
 depends_on: []
 plan: "plan.md"
-spec: "../../specs/tasks/archive-confirmation.md"
+spec: "../../specs/tasks/requirements/archive-confirmation.md"
 ---

 # Task 01: Make Archive Switching Cascade-Aware
@@ -5,7 +5,7 @@ status: done
 wave: 2
 depends_on: ["01-cascade-aware-switch"]
 plan: "plan.md"
-spec: "../../specs/tasks/archive-confirmation.md"
+spec: "../../specs/tasks/requirements/archive-confirmation.md"
 ---

 # Task 02: Add Archive Navigation E2E Coverage
@@ -1,5 +1,5 @@
 ---
-spec: docs/specs/clarification-active-lifecycle/spec.md
+spec: docs/specs/tasks/requirements/clarification-active-lifecycle.md
 created: 2026-08-14
 status: completed
 ---
@@ -5,7 +5,7 @@ status: done
 wave: 1
 depends_on: []
 plan: "plan.md"
-spec: "../../specs/clarification-active-lifecycle/spec.md"
+spec: "../../specs/tasks/requirements/clarification-active-lifecycle.md"
 ---

 # Task 01: Clarification regression red
@@ -5,7 +5,7 @@ status: completed
 wave: 2
 depends_on: ["01-clarification-regression-red"]
 plan: "plan.md"
-spec: "../../specs/clarification-active-lifecycle/spec.md"
+spec: "../../specs/tasks/requirements/clarification-active-lifecycle.md"
 ---

 # Task 02: Current-turn backend authority
@@ -5,7 +5,7 @@ status: completed
 wave: 3
 depends_on: ["02-current-turn-backend-authority"]
 plan: "plan.md"
-spec: "../../specs/clarification-active-lifecycle/spec.md"
+spec: "../../specs/tasks/requirements/clarification-active-lifecycle.md"
 ---

 # Task 03: Summary pending convergence
@@ -5,7 +5,7 @@ status: completed
 wave: 4
 depends_on: ["03-summary-pending-convergence"]
 plan: "plan.md"
-spec: "../../specs/clarification-active-lifecycle/spec.md"
+spec: "../../specs/tasks/requirements/clarification-active-lifecycle.md"
 ---

 # Task 04: Pending-owner navigation
@@ -11,7 +11,7 @@ depends_on:
    "04-pending-owner-navigation",
  ]
 plan: "plan.md"
-spec: "../../specs/clarification-active-lifecycle/spec.md"
+spec: "../../specs/tasks/requirements/clarification-active-lifecycle.md"
 ---

 # Task 05: Clarification regression green
@@ -1,5 +1,5 @@
 ---
-spec: docs/specs/tasks/runtime-state-publication-order.md
+spec: docs/specs/tasks/requirements/runtime-state-publication-order.md
 created: 2026-08-02
 status: complete
 ---
@@ -5,7 +5,7 @@ status: completed
 wave: 1
 depends_on: []
 plan: "plan.md"
-spec: "../../specs/tasks/runtime-state-publication-order.md"
+spec: "../../specs/tasks/requirements/runtime-state-publication-order.md"
 ---

 # Task 01: Publish clarification task state
@@ -5,7 +5,7 @@ status: completed
 wave: 2
 depends_on: ["01-publish-clarification-task-state"]
 plan: "plan.md"
-spec: "../../specs/tasks/runtime-state-publication-order.md"
+spec: "../../specs/tasks/requirements/runtime-state-publication-order.md"
 ---

 # Task 02: Prove live sidebar regrouping
@@ -5,7 +5,7 @@ status: completed
 wave: 3
 depends_on: ["01-publish-clarification-task-state"]
 plan: "plan.md"
-spec: "../../specs/tasks/runtime-state-publication-order.md"
+spec: "../../specs/tasks/requirements/runtime-state-publication-order.md"
 ---

 # Task 03: Address ordered publication review findings
@@ -25,7 +25,7 @@ spec: "../../specs/tasks/runtime-state-publication-order.md"
 - `apps/backend/internal/mcp/handlers/handlers.go`
 - `apps/backend/internal/mcp/handlers/handlers_test.go`
 - `apps/backend/internal/task/service/service_events.go`
- `docs/specs/tasks/runtime-state-publication-order.md`
+- `docs/specs/tasks/requirements/runtime-state-publication-order.md`
 - `docs/decisions/2026-07-30-runtime-task-state-before-running-event.md`
 - `docs/plans/clarification-task-state-publication/plan.md`
 - `docs/plans/clarification-task-state-publication/task-01-publish-clarification-task-state.md`
@@ -13,7 +13,7 @@ behavior, then verify both through their existing user-facing creation flows. Th
 keeps Office onboarding separate while the frontend change preserves the current desktop and mobile
 dialog composition.

-Related requirement: `docs/specs/tasks/multi-branch/spec.md` task-creation scenarios.
+Related requirement: `docs/specs/tasks/requirements/multi-branch.md` task-creation scenarios.

 ## Backend

@@ -5,7 +5,7 @@ status: done
 wave: 1
 depends_on: []
 plan: "plan.md"
-spec: "../../specs/tasks/multi-branch/spec.md"
+spec: "../../specs/tasks/requirements/multi-branch.md"
 ---

 # Task 01: Repository tooltip containment and disclosure
@@ -38,7 +38,7 @@ None.

 ## Inputs

- `docs/specs/tasks/multi-branch/spec.md` task-creation scenarios.
+- `docs/specs/tasks/requirements/multi-branch.md` task-creation scenarios.
 - `docs/plans/creation-flow-reliability/plan.md` frontend and mobile design sections.
 - Existing `useTooltipMountGate` behavior and Radix tooltip guidance in `apps/web/AGENTS.md`.

@@ -1,5 +1,5 @@
 ---
-spec: docs/specs/tasks/mcp-task-agent-profile-default/spec.md
+spec: docs/specs/tasks/requirements/mcp-task-agent-profile-default.md
 created: 2026-08-12
 status: complete
 ---
@@ -5,7 +5,7 @@ status: done
 wave: 1
 depends_on: []
 plan: "plan.md"
-spec: "../../specs/tasks/mcp-task-agent-profile-default/spec.md"
+spec: "../../specs/tasks/requirements/mcp-task-agent-profile-default.md"
 ---

 # Task 01: Initial runtime seed
@@ -5,7 +5,7 @@ status: done
 wave: 2
 depends_on: ["01-initial-runtime-seed"]
 plan: "plan.md"
-spec: "../../specs/tasks/mcp-task-agent-profile-default/spec.md"
+spec: "../../specs/tasks/requirements/mcp-task-agent-profile-default.md"
 ---

 # Task 02: Creator-session resolution
@@ -5,7 +5,7 @@ status: done
 wave: 3
 depends_on: ["02-creator-session-resolution"]
 plan: "plan.md"
-spec: "../../specs/tasks/mcp-task-agent-profile-default/spec.md"
+spec: "../../specs/tasks/requirements/mcp-task-agent-profile-default.md"
 ---

 # Task 03: Explain creator-session default
@@ -5,7 +5,7 @@ status: done
 wave: 4
 depends_on: ["02-creator-session-resolution", "03-explain-session-default"]
 plan: "plan.md"
-spec: "../../specs/tasks/mcp-task-agent-profile-default/spec.md"
+spec: "../../specs/tasks/requirements/mcp-task-agent-profile-default.md"
 ---

 # Task 04: End-to-end inheritance
@@ -21,7 +21,7 @@ This repairs the reported case where the fork's stale `origin/main` made Kandev
 Related contracts:

 - [Workspace Git Status](../../specs/platform/workspace-git-status.md)
- [Remote Contribution Tasks](../../specs/tasks/remote-contribution-tasks.md)
+- [Remote Contribution Tasks](../../specs/tasks/system-design/remote-contribution-tasks.md)
 - [ADR: Qualify Git Comparison Targets by Repository](../../decisions/2026-08-19-repository-qualified-comparison-targets.md)
 - [ADR: Multi-branch task support](../../decisions/0013-multi-branch-tasks.md)
 - [ADR: Bind Fork Push Destinations to Tasks](../../decisions/2026-08-12-task-bound-fork-destinations.md)
@@ -5,7 +5,7 @@ status: done
 wave: 3
 depends_on: ["02-agentctl-comparison-target"]
 plan: "plan.md"
-spec: "../../specs/tasks/remote-contribution-tasks.md"
+spec: "../../specs/tasks/system-design/remote-contribution-tasks.md"
 ---

 # Task 03: PR reconciliation, lifecycle refresh, and summaries
@@ -1,5 +1,5 @@
 ---
-spec: docs/specs/tasks/link-existing-task-github-issue.md
+spec: docs/specs/tasks/requirements/link-existing-task-github-issue.md
 created: 2026-07-13
 status: completed
 ---
@@ -5,7 +5,7 @@ status: done
 wave: 1
 depends_on: []
 plan: "plan.md"
-spec: "../../specs/tasks/link-existing-task-github-issue.md"
+spec: "../../specs/tasks/requirements/link-existing-task-github-issue.md"
 ---

 # Task 01: Backend Issue-Link Reverse Lookup
@@ -5,7 +5,7 @@ status: done
 wave: 2
 depends_on: ["01-backend-reverse-lookup"]
 plan: "plan.md"
-spec: "../../specs/tasks/link-existing-task-github-issue.md"
+spec: "../../specs/tasks/requirements/link-existing-task-github-issue.md"
 ---

 # Task 02: Frontend Automatic Link And Issue Indicator
@@ -5,7 +5,7 @@ status: done
 wave: 3
 depends_on: ["02-frontend-link-and-indicator"]
 plan: "plan.md"
-spec: "../../specs/tasks/link-existing-task-github-issue.md"
+spec: "../../specs/tasks/requirements/link-existing-task-github-issue.md"
 ---

 # Task 03: Issue Indicator E2E And Verification
@@ -1,5 +1,5 @@
 ---
-spec: docs/specs/tasks/interrupted-task-indicator.md
+spec: docs/specs/tasks/requirements/interrupted-task-indicator.md
 created: 2026-08-02
 status: complete
 ---
@@ -5,7 +5,7 @@ status: done
 wave: 1
 depends_on: []
 plan: "plan.md"
-spec: "../../specs/tasks/interrupted-task-indicator.md"
+spec: "../../specs/tasks/requirements/interrupted-task-indicator.md"
 ---

 # Task 01: Backend startup interruption marker
@@ -5,7 +5,7 @@ status: done
 wave: 2
 depends_on: ["01-backend-startup-marker"]
 plan: "plan.md"
-spec: "../../specs/tasks/interrupted-task-indicator.md"
+spec: "../../specs/tasks/requirements/interrupted-task-indicator.md"
 ---

 # Task 02: Backend DTO exposure and marker clearing
@@ -5,7 +5,7 @@ status: done
 wave: 3
 depends_on: ["02-backend-dto-and-clearing"]
 plan: "plan.md"
-spec: "../../specs/tasks/interrupted-task-indicator.md"
+spec: "../../specs/tasks/requirements/interrupted-task-indicator.md"
 ---

 # Task 03: Frontend interrupted-field plumbing
@@ -5,7 +5,7 @@ status: done
 wave: 4
 depends_on: ["03-frontend-data-plumbing"]
 plan: "plan.md"
-spec: "../../specs/tasks/interrupted-task-indicator.md"
+spec: "../../specs/tasks/requirements/interrupted-task-indicator.md"
 ---

 # Task 04: Frontend interrupted icon rendering
--- a/Show More
+++ b/Show More