Skip to content

Task (WorkflowTask)

Definition

A Task — canonically a WorkflowTask — is a human-handoff work item raised during the deliberation phase of an investigation: a review, a risk review, an attestation, a refresh, or an acknowledgment. It is the mechanism by which an agent or analyst routes work to a person (or a role/group) and tracks it to completion. A WorkflowTask is part of producing evidence and decisions — it is explicitly not a downstream "decision effect." It always references the Insight it belongs to, and review/attest tasks reference the specific Edition under review.

Note the namespace shares two objects. WorkflowTask (alias workflow_task, tasks.yaml:133, DAO cortex/cortex/userspace/workflow_task.py) is the live work item cortex's workflow.py actually manages. A simpler generic Task (alias task, tasks.yaml:99) also exists in the schema and REST, but cortex's workflow logic does not use it. This spec describes WorkflowTask.

Canonical schema: cortex/docs/spec/des-objects.yml:705. Command logic: cortex/cortex/workflow.py. Persistence: a UDS DAO over the shared Elasticsearch intelligence index under the workflow_task alias, id tsk_ + 12 hex.

Lifecycle

status: open → in_progress → {completed | rejected}, with completed / rejected terminal. Enforced by _validate_task_transition (workflow.py:82). On completion the outcome must be one of approved | rejected | attested | acknowledged | revised (workflow.py:56). (The tasks.yaml schema enum is wider and inconsistent — pending/assigned/in_progress/complete/completed/failed/open/rejected — and should converge to the DES 4-state set the code enforces.)

Journey through the code

Commands in cortex/cortex/workflow.py: create_task (:264), update_task_status (:1099), complete_task (:704), close_review (:802), request_handoff (:978), plus the per-user/edition/insight list views. Each is exposed as an MCP tool and over REST /tasks* / /workflow_task (tasks.yaml:309), and writes WorkflowTask().update(uid=tsk_…).

Every task operation also writes onto the linked Insight's event ledger and advances its head: create_task → task_created; update_task_status (open → in_progress) → task_accepted; complete_task → task_completed; request_handoff → handoff_requested; close_review → review_closed. Completing a review task syncs the Edition's review field (workflow.py:749); close_review reciprocally completes the matching open review task and auto-advances the Insight status (workflow.py:944). Routing, SLA, and escalation defaults are copied at creation from the accountability pack and the relevant TaskTemplate (workflow.py:372).

Data shape

Required (des-objects.yml:713): schema_version, task_type, status, assigned_to, insight_id, created_by. task_type ∈ review | risk_review | attest | refresh | acknowledge. assigned_to is OR-logic — user_id, roles_any[], or groups_any[]. Optional: edition_id (required for review/attest), summary (≤ 500), due_by, priority (low | normal | high | urgent), sla_hours, escalation_path, review_routing, metadata.status_history[], metadata.boundary_context (handoffs), completed_at / completed_by, completion_note, outcome. Storage: intelligence index, workflow_task alias.

Invariants

  • The Insight must exist before a task is created (workflow.py:316); review/attest tasks require an edition_id pointing at a frozen Edition (checked via content_hash presence, workflow.py:331).
  • No duplicate open task for the same edition_id + task_type (workflow.py:337).
  • State-machine-enforced transitions, and the completion outcome must be in the valid set.
  • product.insight — a Task references the Insight (insight_id) and emits events onto its ledger; open tasks block Insight closure.
  • product.edition — review/attest Tasks reference an Edition and are bidirectionally synced with its review.
  • product.profile — assigned_to role/group eligibility resolves against Profile auth.roles_any; routing and SLA defaults come from the accountability pack a Profile points at.

Open questions

  • Task vs WorkflowTask. The generic Task object appears orphaned in cortex logic — dead, or consumed by another service?
  • Schema enum drift — tasks.yaml lists far more statuses than the code's 4; it should converge to DES.
  • risk_review is valid in code/schema but not in DES core (a Beacon extra), and request_handoff maps onto task_type = acknowledge rather than a dedicated handoff type.

Realized by: component.cortex.decision-evidence, component.cortex.intelligence, component.cortex.task-and-effect