---
id: WF-CRM-ACT-003
title: Write a task and keep its overdue item in step
trigger: 'A console or API caller creates, changes, routes, closes, reopens or deletes task work.'
product_area: crm
module: activities-tasks
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
inference: []
source_sha:
  services-crm: a8d1364f1dd44b723bb5f9acba12f983e9ec8d69
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
implements:
  - CAP-CRM-ACT-010
  - CAP-CRM-ACT-011
  - CAP-CRM-ACT-012
  - CAP-CRM-ACT-015
moves:
  - STATE-CRM-ACT-002
  - STATE-CRM-ACT-003
  - STATE-CRM-ACT-004
crosses:
  - SVC-CRM-ACT-tasks
idempotency: >-
  Console creation retains its chosen identifier and reads it after a recoverable
  ambiguous response or existing-record conflict. Public edits and closing actions compare
  the read version, and repeats may be stale or already closed. The assignment API can
  omit a version and then applies its serialized request to current work.
concurrency: >-
  Persistence serializes changes on the task. Lifecycle guards and applicable version
  checks use the locked row. Enabled attention changes share the task transaction;
  reconciliation has a separate race described by its own workflow.
hops:
  - 'n': 1
    actor_or_service: Task list and detail drawer
    action: >-
      Patch changed drawer values, including the assignee, with the read version; invoke
      closing and reopening separately and create with the retained sheet identifier.
    anchor: 'react-console:components/tasks/use-task.ts:useTaskMutations'
    seam: sync
    on_failure: >-
      Keep field failures visible. Closing actions revalidate shared query keys even on
      refusal; a failed edit or claim does not guarantee a refreshed drawer.
    left_inconsistent: The local display may remain older than a task changed elsewhere.
    observer: The user receives mutation feedback.
    provenance: observed
    source: >-
      react-console:components/tasks/use-task.ts:useTaskMutations;
      react-console:app/(console)/console/[tenantId]/tasks/page.tsx:changeTask
  - 'n': 2
    actor_or_service: Tasks API
    action: >-
      Authorize the task operation and map its patch or replacement body to the
      persistence input.
    anchor: 'services-crm:modules/tasks/aws/api/tasks.routes.ts:tasksRoutes'
    seam: sync
    on_failure: 'Return validation, authorization or absence errors before the write proceeds.'
    left_inconsistent: The rejected request leaves records unchanged.
    observer: The requesting caller receives the error.
    provenance: test
    source: >-
      services-crm:modules/tasks/tests/e2e/tasks.e2e.spec.js#answers 403 to a caller who
      may only read tasks claiming one
  - 'n': 3
    actor_or_service: Task persistence transaction
    action: >-
      Validate work and reference values, lock existing work, apply lifecycle and lock
      restrictions, and write routing and closing stamp pairs while preserving workflow
      origin.
    anchor: 'services-crm:modules/tasks/services/persistence/tasks.ts:updateTask'
    seam: sync
    on_failure: 'Roll back and return the coded lifecycle, lock or validation refusal.'
    left_inconsistent: No partial task persistence survives the transaction.
    observer: The caller receives the coded response.
    provenance: test
    source: >-
      services-crm:modules/tasks/tests/unit/services/tasks/lifecycle.spec.js#gives every
      refusal of the table a code
  - 'n': 4
    actor_or_service: Task attention synchronization
    action: >-
      Compare overdue qualification before and after persistence; publish qualifying work
      with its audience or resolve work that ceased qualifying.
    anchor: >-
      services-crm:modules/tasks/services/persistence/task-attention-items.ts:syncTaskOverdueAttention
    seam: sync
    on_failure: >-
      With publication enabled, an attention error rolls back the task change; disabled
      publication emits no attention write.
    left_inconsistent: >-
      The task and its own attention changes commit together, although older or
      concurrently swept items can still exist.
    observer: Platform attention and the task caller expose the result.
    provenance: test
    source: >-
      services-crm:modules/tasks/tests/integration/services/persistence/task-attention-items.integration.spec.js#leaves
      no item behind a task write that rolled back
branches:
  - >-
    Replacement preserves omitted work day, candidate role and workflow origin while
    clearing other omitted optional values; this planning discrepancy remains recorded.
  - Task deletion exists through the API but has no console command.
  - >-
    A newly created task whose due day has ended qualifies immediately for enabled
    attention publication.
waits: []
evidence:
  - >-
    services-crm at a8d1364f: modules/tasks/aws/api/tasks.routes.ts; task-api-mapper.ts;
    services/persistence/tasks.ts (createTaskWithOutcome, updateTask, assignTask,
    closeTask, deleteTask); services/tasks/lifecycle.ts; services/tasks/task-refusals.ts;
    services/persistence/task-attention-items.ts; lib/attention.ts.
  - >-
    react-console at baf6dae3: lib/api/tasks.ts; components/tasks/use-task.ts;
    components/tasks/task-detail-sheet.tsx; components/tasks/create-task-sheet.tsx.
controls: [TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-006, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-IAM-001, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-MON-002, TC-PI-001, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-TEN-001, TC-TEN-002, TC-TEN-003]
---

# Write a task and keep its overdue item in step

## What It Does

Task writes combine work persistence with conditional overdue publication. The drawer uses ordinary patches for field and assignee changes, with separate commands for completion, cancellation and reopening. The structured hops describe API-only deletion as well.

## The Flow

```mermaid
flowchart TD
  A[Submit task field or lifecycle request] --> B[Authorize and validate]
  B --> C[Apply locked lifecycle and version checks]
  C --> D[Persist work and attribution]
  D --> E{Attention enabled?}
  E -->|Yes| F[Publish or resolve inside transaction]
  E -->|No| G[Commit task transaction]
  F --> G
  G --> H[Return result and refresh successful views]
```

The numbered hops specify the request, persistence and integration boundaries in order. Each hop identifies its evidence anchor, synchronization seam and observable failure outcome. Branches distinguish optional and delegated paths.

## When Something Fails

Validation and lifecycle failures return without a committed task change. When publication is enabled, its failure also refuses the write. Shared-list revalidation after a closing action does not guarantee that manually held drawer details have been reread.

## Open Design Questions

Product needs to settle replacement completeness, task history and the availability cost of making attention publication part of the task transaction.