---
id: WF-PFM-ELG-017
title: Run the attention sweep
trigger: >-
  The fifteen-minute attention schedule performs expiry, retirement repair,
  ranking, escalation, reminder planning and orphan cleanup.
product_area: platform
module: eligibility
revision: 1
status: draft
design_intent: confirmed
origin: >-
  Responsibilities and attention architecture D-03 (repaired by sweeps) and D-07
  (escalation in phase 2), approved by Andrew 2026-10-18 (PLAT-M15 "Decisions");
  PLAT-M16 D2 (reminders off until an administrator enables them) and the change
  routing reminders through Notifications (2026-10-21)
implementation_evidence: inconsistent
inference: []
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
implements:
  - CAP-PFM-ELG-016
  - CAP-PFM-ELG-019
moves:
  - STATE-PFM-ELG-007
crosses:
  - SVC-PFM-ELG-attention
  - SVC-PFM-ELG-responsibilities
idempotency: >-
  Closing and cleanup repeat safely; guarded escalation stamps once, and
  reminder planning ignores duplicate reminder-occurrence keys.
concurrency: >-
  Reserved function concurrency is one. Workspace phases commit separately;
  escalation processes at most one thousand items and reminder planning at most
  five thousand.
hops:
  - 'n': 1
    actor_or_service: Attention sweep
    action: Close items whose expiry instant has passed and release their keys.
    anchor: >-
      services-platform:modules/attention/services/persistence/items.ts:expireItems
    seam: schedule
    on_failure: >-
      Log and count the failing workspace, continue other workspaces and retry
      next invocation.
    left_inconsistent: Failed expiry waits for a later successful sweep.
    observer: Failure and silence alarms expose sweep health.
    provenance: observed
    source: >-
      services-platform:modules/attention/services/sweep/sweep-tenant.ts:sweepTenant
  - 'n': 2
    actor_or_service: Attention sweep
    action: Repair recently retired kinds and update ranks that changed.
    anchor: >-
      services-platform:modules/attention/services/persistence/items.ts:refreshRanks
    seam: schedule
    on_failure: A failed phase skips the remaining phases for that workspace.
    left_inconsistent: Earlier phases remain committed while rank or retirement repair can lag.
    observer: Sweep metrics show progress.
    provenance: observed
    source: >-
      services-platform:modules/attention/services/persistence/items.ts:resolveRetiredDefinitionItems
  - 'n': 3
    actor_or_service: Attention sweep
    action: >-
      Guard the first escalation stamp, add its responsibility or role audience
      and audit in one transaction.
    anchor: >-
      services-platform:modules/attention/services/persistence/items.ts:escalateOverdueItems
    seam: schedule
    on_failure: An unresolved role target is logged and can be attempted later.
    left_inconsistent: The occurrence remains unescalated without a valid target.
    observer: Escalation counts and item explanations reveal its standing.
    provenance: observed
    source: >-
      services-platform:modules/attention/services/persistence/items.ts:escalateOverdueItems
  - 'n': 4
    actor_or_service: Attention sweep
    action: >-
      Resolve current recipients and plan due-soon, bounded overdue, escalation
      and digest rows under policy, personal state and quiet-hour rules.
    anchor: >-
      services-platform:modules/attention/services/reminders/plan-reminders.ts:planTenantReminders
    seam: schedule
    on_failure: Planning failure is logged and later scheduling retries.
    left_inconsistent: >-
      Declared policies can enable reminders without administrator action,
      contrary to the approved default.
    observer: Planned-reminder counters expose activity.
    provenance: observed
    source: 'services-platform:modules/attention/reminders.ts:effectiveReminderPolicy'
  - 'n': 5
    actor_or_service: Attention sweep
    action: >-
      Delete orphan supporting rows, clear keys lacking open occurrences and
      remove closed keys after fourteen idle months.
    anchor: >-
      services-platform:modules/attention/services/persistence/items.ts:deleteOrphans
    seam: schedule
    on_failure: Cleanup failure leaves rows for a later sweep.
    left_inconsistent: Orphans persist and generation permanence ends when a key is deleted.
    observer: Cleanup metrics expose remaining work.
    provenance: observed
    source: >-
      services-platform:modules/attention/services/persistence/reminders.ts:deleteOrphanReminders
branches:
  - >-
    The current digest and quiet-hour paths exceed the later approved
    Notifications scope.
waits: []
evidence:
  - >-
    services-platform at ad3f6a6: modules/attention/services/sweep/;
    services/persistence/items.ts, reminders.ts;
    services/reminders/plan-reminders.ts; reminders.ts;
    aws/logic/attention-sweep.lambda.ts; docs/attention.md §7;
    docs/milestones/plans/PLAT-M16-plan.md (D2).
controls: [TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-005, TC-CHG-006, TC-CHG-007, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-MON-002, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-PRV-004, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-TEN-004, TC-VEN-001, TC-VEN-002, TC-VEN-003]
---
# Run the attention sweep

## What It Does

The fifteen-minute attention schedule performs expiry, retirement repair, ranking, escalation, reminder planning and orphan cleanup.

## The Flow

```mermaid
flowchart TD
  H1["Attention sweep" ]
  H2["Attention sweep" ]
  H1 --> H2
  H3["Attention sweep" ]
  H2 --> H3
  H4["Attention sweep" ]
  H3 --> H4
  H5["Attention sweep" ]
  H4 --> H5
```

Close items whose expiry instant has passed and release their keys. Repair recently retired kinds and update ranks that changed. Guard the first escalation stamp, add its responsibility or role audience and audit in one transaction. Resolve current recipients and plan due-soon, bounded overdue, escalation and digest rows under policy, personal state and quiet-hour rules. Delete orphan supporting rows, clear keys lacking open occurrences and remove closed keys after fourteen idle months.

## When Something Fails

Log and count the failing workspace, continue other workspaces and retry next invocation. Failed expiry waits for a later successful sweep. A failed phase skips the remaining phases for that workspace. Earlier phases remain committed while rank or retirement repair can lag. An unresolved role target is logged and can be attempted later. The occurrence remains unescalated without a valid target. Planning failure is logged and later scheduling retries. Declared policies can enable reminders without administrator action, contrary to the approved default. Cleanup failure leaves rows for a later sweep. Orphans persist and generation permanence ends when a key is deleted.

## Open Design Questions

The current digest and quiet-hour paths exceed the later approved Notifications scope.