Task Manager – Technical Specification

1. Module Purpose & Scope (Authoritative)

Task Manager is the calendar-backed system of record for operational work across Primoro. It ensures that all planned and unplanned work — including tasks, callbacks, checklists, and work packages — is created as time-bound, visible work; explicitly owned by a role or individual; aligned to real staff availability; completed within defined time windows or SLAs; and fully auditable. Task Manager replaces private to-do lists, inbox chasing, and informal messaging with one governed work system: if work matters, it exists in the calendar.

It governs:

• Creating, assigning, progressing, and completing tasks, callbacks, checklists, and work packages
• Role-first assignment, dynamic claiming, and SLA tracking across all work items
• Template-based and recurrence-driven generation of task and work-package instances
• Kanban board, list, and queue views with audit-logged state transitions
• Checklist execution with evidence capture (notes, comments, photos, and file attachments)
• Archival and automated retention for completed work and evidence

It explicitly does not:

• Define staff availability or shift structure (owned by Rota Manager)
• Deliver or store messages and conversations (owned by Communication Hub)
• Own appointment booking logic or Reschedule Job tracking (owned by Appointment Manager)
• Store clinical notes, HR records, or payment data
• Execute autonomous actions without explicit human confirmation

2. Ownership & Responsibilities

2.1 Task Manager IS Responsible For

• End-to-end lifecycle management of tasks, callbacks, checklists, and work packages from creation through archival
• Maintaining an immutable, inspection-ready audit trail of all task and checklist events
• Exposing integration surfaces consumed by Communication Hub, Rota Manager, Appointment Manager, Aftercare Manager, Aiden, AI Meeting Notes, AI Guardian, AI Quality Monitor, AI Concierge, Lab Manager, Knowledge Training & Learning, HR & People Manager, Inventory & Compliance Manager, Referral Manager, Recall & Reconnect, Financial Insights, Product Shop, Digital Forms, Smart Dashboards, and Admin Control Plane
• Computing and owning the Overdue boolean flag; consuming surfaces MUST NOT compute it independently
• Reverting in-flight task ownership to the associated role queue when Access Manager emits an access-revocation event
• Governing execution lifecycle for tasks generated by all external event sources, regardless of which module originated the task

2.2 Task Manager IS NOT Responsible For

• Staff availability definition — owned by Rota Manager
• Messaging delivery or conversation storage — owned by Communication Hub
• Appointment booking logic and Reschedule Job ownership — owned by Appointment Manager
• Compliance task state definition (Scheduled / Due / Overdue / Escalated) — owned by Inventory & Compliance Manager; Task Manager maps these states onto its own lifecycle
• Learning pathway content and assignment logic — owned by Knowledge, Training & Learning
• HR workflow policy rules and sequence logic — owned by HR & People Manager
• Tenant health-event detection and task-creation decisions — owned by Admin Control Plane
• Task execution for aftercare workflows — task execution is governed exclusively by Task Manager; Aftercare Manager owns aftercare record management and delegates task execution here
• Clinical records, payments, or HR personnel records

3. Core Objects (Normative)

3.1 Task (Canonical Artefact)

A Task is a governed digital artefact representing a discrete unit of operational work. Every Task MUST:

• exist as a time-bound calendar event
• have a defined purpose and explicit ownership
• have a lifecycle state at all times
• retain completion evidence

Minimum required fields:

• TaskId (immutable UUID)
• Title, Description, Category
• DueDateTime OR TimeWindowStart / TimeWindowEnd
• Origin — one of: Manual, Callback, Workflow, Template-Generated, AI-Suggested
• OwnerType (User or Role), OwnerId
• Status (see §3.2)
• SLAState (On-track, At-risk, Breached)
• Priority
• Confidential (boolean)
• LinkedEntities — back-links to originating records (e.g. MeetingNoteRecord, lab case reference, HR workflow instance, compliance record, Reschedule Job reference)
• Overdue (boolean; computed and owned by Task Manager)
• CompletedTimestamp, CompletedByUserId
• ArchivedAt, RetentionPolicyId
• AuditLog (immutable)

3.2 Task State Machine (Authoritative)

States:

• Created
• Active
• In Progress
• Blocked (optional)
• Completed
• Cancelled (with mandatory reason)
• Archived (system state; post-completion, applied by retention policy)

Rules:

• All state transitions are explicit, time-stamped, and immutable in the audit log.
• A task cannot return to Created once it has reached Active or beyond.
• Completed and Cancelled tasks may not transition to any operational state; they proceed only to Archived.
• Archived is a terminal system state; it cannot be reversed.
• Cancellation MUST record a reason.
• Kanban board drag-and-drop constitutes an explicit state transition and MUST be audit-logged identically to programmatic transitions.
• Only authorised users (per Access Manager RBAC) may trigger specific transitions; see §9.
• The seven states above are canonical and exhaustive. Consuming surfaces (including the Surgery & Decon Day View tablet rendering layer) MUST NOT introduce or imply additional states. Each state maps to a defined visual treatment in consuming surfaces; any mismatch MUST be treated as an integration defect and raised against the Task Manager module owner.

3.3 Checklist / Checklist Item (Canonical Artefact)

Checklists may belong to a Task or a Work Package. Minimum required fields:

• ChecklistId (immutable UUID)
• ParentId — FK to owning Task or Work Package
• Items[] — each with an immutable ChecklistItemId, CompletionState, and optional evidence payload (notes, comments, photos, attachments)
• AuditLog (immutable)

Checklists provide execution evidence; they do not replace or alter the owning Task's lifecycle state.

3.4 Work Package (Canonical Artefact)

A Work Package is a governed collection of related Tasks (each optionally with checklists), delivered as a single operational unit (e.g. Daily Opening, Weekly Decon).

Minimum required fields:

• WorkPackageId (immutable UUID)
• Title, Description
• TimeWindowStart / TimeWindowEnd
• OwnerType (User or Role), OwnerId
• Status (mirrors Task lifecycle states)
• Tasks[] — ordered list of constituent Task references
• LinkedEntities
• AuditLog (immutable)

Requirements:

• Calendar-backed and time-bound
• One or more governed tasks per package
• Evidence captured at task or checklist-item level
• Role-first assignment and claiming (configurable per package)
• Fully auditable across creation, execution, completion, and archival

Role/team calendar association:

Each Work Package MUST carry a CalendarId field referencing the role or team calendar to which it belongs. The system maintains one calendar per configured role or team (as defined in Access Manager). This association governs:

• Which calendar track the work package appears on in the overlay view.
• The colour-coding applied to the work package in multi-calendar overlay mode.
• Default visibility rules: a user whose role matches the work package's CalendarId sees it in their default calendar; other users see it only when the relevant calendar is enabled in overlay mode or they hold a manager-level permission.

Work packages assigned to a specific individual also carry the individual's personal calendar identity as CalendarId where applicable.

Inferred from Harry Leak: 'The way I see it is you've got a calendar for each role that we have configured in the back end… it will automatically go to the people that are assigned to that calendar.'

3.5 Templates & Recurrence

Templates enable consistent operational delivery.

Task Templates define: title, description, category, default owner (user or role), due-window rules, checklist structure, and evidence requirements.

Work Package Templates define: tasks within the package, checklist structures, assignment rules, and timing rules.

Recurrence rules recreate new instances on a defined schedule (daily / weekly / monthly / custom). Each generated instance MUST:

• carry a fresh, independent audit trail
• link back to its originating template via LinkedEntities
• be generated idempotently (no silent duplicates)

4. Creation & Update Sources

4.1 Manual Creation

Authorised staff may create ad-hoc tasks and checklists. Permissions govern assignment scope, evidence requirements, and cancellation rights.

4.2 Callbacks (CORE)

Patient callbacks are a CORE capability. Callbacks are tasks with due windows, explicit ownership, and full audit logging. Callbacks and follow-up tasks may generate one another.

4.3 Event-Driven Tasks

Tasks are generated from the following sources:

• Appointments (see Appointment Manager integration below)
• Communication Hub conversations and message-to-work conversions
• Workflow completion events
• Aftercare Manager triggers
• Inventory & Compliance Manager compliance cycles
• Exception sources (e.g. Aiden quality-monitor alerts, AI Quality Monitor findings)
• AI Meeting Notes (confirmed action items and retention review tasks)
• AI Guardian (finding follow-up and actionable alert routing)
• AI Concierge (unresolved call follow-ups and recovery tasks)
• Lab Manager SLA breach escalations
• Knowledge, Training & Learning pathway assignments
• HR & People Manager policy-driven workflow steps and Critical Risk escalations
• Referral Manager SLA breach escalations and referral-state follow-up actions
• Recall & Reconnect non-clinical personal follow-up work items
• Financial Insights anomaly and risk follow-up actions
• Product Shop in-clinic fulfilment and exception-handling actions
• Digital Forms form-review and mandatory re-capture actions
• Rota Manager absence-change events (where absence triggers downstream work, e.g. rescheduling callbacks)
• Admin Control Plane / Tenant Health Monitor health events

All event-driven tasks MUST carry Origin: Workflow (or Origin: AI-Suggested for Aiden-confirmed tasks) and MUST include a LinkedEntities back-link to the originating record in the source module.

Appointment Manager — Appointment Lifecycle and Reschedule Follow-Up

Appointment Manager emits two categories of event that may result in task creation in Task Manager:

• Lifecycle transition tasks. When an appointment transitions to a state that creates a downstream task obligation (e.g. completed, no-show, or cancelled), Appointment Manager MUST emit an AppointmentTaskTriggerEvent to Task Manager. Task Manager MUST create the corresponding task with Origin: Workflow and a LinkedEntities back-link to the originating appointment record. The triggering conditions and task payload are defined in the Appointment Manager integration contract.
• Reschedule follow-up tasks. When practitioner absence impacts booked appointments, Appointment Manager creates and owns a Reschedule Job, tracking each affected patient independently. Reschedule Jobs are owned and managed by Appointment Manager, not Task Manager. Where Appointment Manager emits an event requiring operational follow-up by practice staff (e.g. a patient contact action), that follow-up work MAY be created as an event-driven task in Task Manager with Origin: Workflow and a LinkedEntities back-link to the relevant Reschedule Job reference.

Task Manager does not duplicate Appointment Manager's booking logic.

AI Meeting Notes — Confirmed Action Tasks and Retention Review Tasks

AI Meeting Notes is a recognised event-driven source for two categories of task:

• Confirmed action tasks. When a staff member confirms an ActionCandidate in AI Meeting Notes, that module MUST create a task in Task Manager. The task MUST carry Origin: Workflow, a LinkedEntities back-link to the originating MeetingNoteRecord, and title, owner, and due date supplied by the confirming user at sign-off time. No task is created autonomously; explicit human confirmation in the AI Meeting Notes sign-off flow is the sole trigger.
• Retention review tasks. The AI Meeting Notes sign-off flow MAY create a retention review task with a standardised title pattern, an assigned owner, a defined due date, and a LinkedEntities reference to the MeetingNoteRecord.

In both cases, Task Manager treats AI Meeting Notes as an external caller; no autonomous creation occurs without an explicit human confirmation action in that module. Task creation is idempotent: re-submission of the same confirmed action MUST NOT produce duplicate tasks.

AI Guardian — Finding Follow-Up Tasks

AI Guardian identifies quality and safety findings and routes actionable outputs to Task Manager. When AI Guardian determines that a finding requires staff follow-up, it MUST emit an event that results in a task being created in Task Manager. The task MUST carry Origin: Workflow and a LinkedEntities back-link to the originating finding record in AI Guardian. AI Guardian is responsible for determining when a finding warrants task creation and for defining the default owner (role or named user); Task Manager governs the task's execution lifecycle, SLA tracking, and audit trail thereafter.

AI Quality Monitor — Quality Finding Remediation Tasks

AI Quality Monitor creates structured remediation artefacts (tasks and alerts) when quality issues are detected. When a quality finding requires staff remediation action, AI Quality Monitor MUST emit an event resulting in a task being created in Task Manager. The task MUST carry Origin: Workflow and a LinkedEntities back-link to the originating quality finding record. Task Manager assigns the standard lifecycle, SLA tracking, and audit trail from the point of creation; AI Quality Monitor retains responsibility for finding detection and remediation-task initiation.

AI Concierge — Unresolved Call and Recovery Follow-Up Tasks

When an AI Concierge call cannot be resolved autonomously, the session MUST transition to a Follow-Up Created state and generate a task in Task Manager before the session closes. The task MUST carry Origin: Workflow and a LinkedEntities back-link to the originating call session record. Recovery follow-up tasks (e.g. where a patient requires a callback after a failed automated interaction) follow the same contract. Task Manager governs the follow-up task's lifecycle; AI Concierge is responsible for determining when escalation to a task is warranted.

Lab Manager — SLA Breach Escalation Tasks

When a lab case breaches its SLA, Lab Manager emits an escalation event and Task Manager MUST create an escalation task. The task payload supplied by Lab Manager MUST include at minimum:

• Origin: Workflow
• A LinkedEntities reference to the relevant lab case
• Escalation context (reason and breach timestamp)
• A default owner (role or named user as determined by Lab Manager configuration)

Task Manager assigns the standard lifecycle to the escalation task from the point of creation.

Knowledge, Training & Learning — Pathway Assignment Tasks

When Knowledge, Training & Learning assigns a learning pathway — whether triggered automatically on onboarding or role change, or manually by a manager — it MUST emit an event that results in a task being created in Task Manager. Task Manager is responsible for deadline tracking, reminders, escalation visibility, and completion recording against that task. The task MUST carry Origin: Workflow and a LinkedEntities back-link to the relevant learning pathway record. Knowledge, Training & Learning defines the learning requirement; Task Manager governs its execution lifecycle.

HR & People Manager — Policy-Driven Workflow Steps and Critical Risk Escalations

HR & People Manager executes formal policy workflows (including disciplinary and grievance processes) via Task Manager, and MUST also trigger escalation tasks when a leave classification reaches Critical Risk status. Specifically:

• Policy workflow step tasks. Each step in an HR workflow requiring staff action MUST generate a task with Origin: Workflow and a LinkedEntities back-link to the relevant HR workflow instance.
• Critical Risk escalation tasks. When HR & People Manager classifies an absence or leave event as Critical Risk, it MUST emit an event that results in a task being created in Task Manager for managerial follow-up, with Origin: Workflow and a LinkedEntities back-link to the relevant HR record.

HR & People Manager remains responsible for workflow logic, policy rules, and the determination of risk classification; Task Manager is responsible for task creation, ownership, lifecycle progression, and audit trail.

Inventory & Compliance Manager — Compliance Cycle Tasks

Compliance Tasks have a distinct five-state lifecycle within Inventory & Compliance Manager (Scheduled → Due → Completed → Overdue → Escalated). These states map onto Task Manager's governed lifecycle as follows:

Inventory & Compliance Manager state	Task Manager lifecycle effect
Scheduled	Task exists in Created or Active state
Due	Task moves to Active / In Progress
Completed	Task moves to Completed
Overdue	SLAState set to Breached; task remains in Active or In Progress
Escalated	Manual escalation visibility surfaced; ownership reassignment is manual

Task Manager MUST accept the compliance task payload from Inventory & Compliance Manager with Origin: Workflow, a LinkedEntities back-link to the compliance record, and the relevant SLA window. Both modules MUST agree the state-mapping contract during integration design.

Referral Manager — SLA Breach Escalation and Referral State Follow-Up Tasks

Referral Manager generates referral-linked tasks and escalation signals via Task Manager. Two categories of task may be created:

• SLA breach escalation tasks. When a referral breaches its SLA, Referral Manager MUST emit an escalation event resulting in a task being created in Task Manager with Origin: Workflow and a LinkedEntities back-link to the referral record.
• Referral state follow-up tasks. Referral state transitions that require staff action (e.g. triaging an inbound referral, ownership reassignment) MAY generate a follow-up task in Task Manager with Origin: Workflow and a LinkedEntities back-link to the referral record.

Referral Manager is responsible for determining when a state transition or SLA breach warrants task creation; Task Manager governs execution lifecycle, SLA tracking, and audit trail thereafter.

Recall & Reconnect — Personal Follow-Up Work Items

When Recall & Reconnect automation cannot progress safely (e.g. due to clinical complexity or patient preference), it MUST generate a non-clinical personal follow-up work item in Task Manager rather than continuing automated outreach. The task MUST carry Origin: Workflow and a LinkedEntities back-link to the originating recall or reconnect record. Task Manager governs the follow-up task's lifecycle; Recall & Reconnect is responsible for determining when escalation to a human-owned task is warranted.

Financial Insights — Anomaly and Risk Follow-Up Tasks

When Financial Insights detects a financial anomaly or risk that requires governed follow-up, it MUST emit an event resulting in a task being created in Task Manager. The task MUST carry Origin: Workflow and a LinkedEntities back-link to the originating Financial Insights record. Financial Insights is responsible for anomaly detection and the determination of when a task is warranted; Task Manager governs task execution lifecycle, SLA, and audit trail.

Product Shop — In-Clinic Fulfilment and Exception-Handling Tasks

When Product Shop determines that a staff action is required — for example, in-clinic fulfilment of an order or exception handling where automated processing cannot proceed — it MUST emit an event resulting in a task being created in Task Manager. The task MUST carry Origin: Workflow and a LinkedEntities back-link to the originating Product Shop order or exception record. Product Shop is responsible for determining when human intervention is required; Task Manager governs the task's execution lifecycle.

Digital Forms — Form Review and Re-Capture Tasks

When Digital Forms identifies that a form requires staff review (e.g. a form has expired or must be re-captured with documented justification), it MAY emit an event resulting in a task being created in Task Manager. The task MUST carry Origin: Workflow and a LinkedEntities back-link to the originating form record. Digital Forms is responsible for determining when a review or re-capture task is warranted; Task Manager governs the task's execution lifecycle.

Rota Manager — Absence-Driven Follow-Up Tasks

Rota Manager emits a canonical AbsenceChangeEvent on all absence state transitions. Where an absence change creates downstream operational work that cannot be handled automatically (e.g. rescheduling callbacks previously owned by the absent staff member), an event-driven task MAY be created in Task Manager with Origin: Workflow and a LinkedEntities back-link to the relevant absence record. The determination of when an absence event warrants task creation is governed by the consuming integration configuration; Task Manager does not replicate Rota Manager's absence or availability logic.

Admin Control Plane / Tenant Health Monitor — Health Event Tasks

The Admin Control Plane Tenant Health Monitor may auto-generate support tasks and submit them to Task Manager. Tasks originating from Admin Control Plane MUST carry Origin: Workflow and MUST be scoped to the relevant tenant. Default ownership is assigned to a support or administrator role as configured in Admin Control Plane. Task Manager treats Admin Control Plane-originated tasks identically to other event-driven tasks in terms of lifecycle, SLA, and audit trail. Admin Control Plane is responsible for determining when a health event warrants task creation; Task Manager governs execution thereafter.

4.4 Template-Driven Generation

• On-demand creation from templates
• Scheduled recurrence from templates
• Idempotent generation (no silent duplicates)
• Fully auditable creation lineage including template and recurrence linkage

4.5 AI-Assisted Suggestions (Where Enabled)

Aiden (Primoro AI Assistant) MAY suggest tasks or highlight risk. Aiden communicates task suggestions via its canonical interface models:

• AIAction — carries ActionType (e.g. CreateTask), TargetModule (task-manager), and RequiresConfirmation (always true for task creation).
• AIIntent — carries IntentType, ConfidenceScore, and SupportedActions[] listing candidate AIAction entries.

When TargetModule is task-manager, Aiden's ActionType MUST be Suggest only. Aiden MUST NOT emit ActionType values of Create, Assign, or Complete targeting Task Manager; Task Manager MUST reject any AIAction payload carrying those action types regardless of other field values. This constraint is non-negotiable and applies at both the Aiden boundary and at Task Manager's inbound validation layer.

Task Manager MUST surface the suggested action to an authorised user for explicit confirmation before any task is created. The ConfidenceScore from AIIntent MAY be displayed to the user to aid judgement but MUST NOT be used to bypass confirmation. RequiresConfirmation: true is non-negotiable; Task Manager MUST reject any AIAction payload where this flag is absent or false. Confirmed AI-suggested tasks carry Origin: AI-Suggested and retain a LinkedEntities back-link to the originating AIIntent for audit purposes.

5. Delivery Surfaces & Access (Authoritative)

5.1 Web Portal

The Web Portal provides planning and oversight capability for authorised staff:

• Workload and SLA views
• Planning and exception management
• Template and recurrence administration
• Read-only audit inspection
• Exception view for tasks requiring manual reassignment (e.g. after access revocation with no determinable role queue)

5.2 Tablet App (Surgery & Decontamination)

Context-specific execution views optimised for point-of-work completion:

• Checklist-first UX
• Explicit user attribution on shared devices
• Device-level authentication enforced via Access Manager

Work package tasks surfaced on surgery and decontamination tablets MUST expose the following fields to the tablet rendering layer:

Field	Description
DueTime	Scheduled due time within the task's time window
Status	Current lifecycle state
CompletedTimestamp	Date-time of completion (null if not yet completed)
CompletedByUserId	Attributed completing user (null if not yet completed)
Overdue	Boolean; true when current time exceeds DueTime and Status is not Completed or Cancelled

The Overdue flag MUST be computed and kept current by Task Manager; consuming surfaces such as the Surgery & Decon Day View MUST NOT compute it independently. The Surgery & Decon Day View MUST render each task state using only the canonical states defined in §3.2; no additional or derived states are introduced by the rendering layer.

5.3 Patient Mobile App

Task Manager does not surface directly in the patient mobile app. Patient-facing work (e.g. callback requests) is mediated through Communication Hub and Aftercare Manager, which may generate tasks in Task Manager as an event source.

5.4 Staff App Mode

Personal and role-based task management for staff on personal devices:

• Personal task list (user-owned tasks filtered by ownership)
• Role-based queues (tasks assigned to the user's role, scoped by location and tenant)
• Task claiming from role-based queues
• Task acknowledgement (distinct from claiming or completing — see below)
• Checklist execution with evidence capture
• Completion at point of work

Staff App Mode surfaces role-scoped views of tasks from Task Manager. The following filtering rules apply to the Staff App Mode task surface:

• Tasks are filtered by the authenticated user's assigned roles and location.
• Confidential tasks are only surfaced where the user holds an explicitly permitted role.
• Overdue tasks are flagged using the Overdue boolean computed by Task Manager; Staff App Mode MUST NOT recompute this flag.
• Queue views display tasks in Created and Active states available for claiming, alongside tasks already owned by the authenticated user in any non-terminal state.

Acknowledgement Action. Acknowledgement is a first-class interaction in Staff App Mode. A user MAY acknowledge a task to confirm awareness without yet claiming ownership or beginning execution. Acknowledgement MUST:

• be available on tasks in Created and Active states
• be recorded as an explicit, time-stamped, attributed action in the audit log
• not change the task's lifecycle state or ownership
• be visible to supervisors and role-queue managers in list and board views

Where Staff App Mode surfaces role-based queues, the acknowledge and claim actions MUST both be available as distinct controls, consistent with the Staff App Mode module's interaction contract.

5.5 Engagement Signals

Task Manager emits SLA state changes, completion events, and escalation events as signals available to staff-facing dashboards and the Web Portal workload view. All signals are derived from audited state transitions and carry timestamps and actor attribution. Smart Dashboards consumes these signals — specifically open task queue state and overdue task counts — on a near real-time basis to populate role-specific task queue widgets (TCO, Manager, Practitioner, and Nurse dashboard views). Task Manager is the authoritative source for all such signals; Smart Dashboards MUST NOT derive task queue or overdue state independently.

6. Integration Contracts

6.1 Inbound (this module consumes from)

From module	What	Contract
Rota Manager	Work Package overlay event (shift reference, role, location, linked work package template ID); AbsenceChangeEvent (where absence triggers downstream task creation)	Async event
Appointment Manager	AppointmentTaskTriggerEvent (lifecycle transition task); Reschedule Job follow-up event	Async event
Communication Hub	Conversation-triggered task event; message-to-work conversion task event	Async event
Aftercare Manager	Aftercare trigger event	Async event
AI Meeting Notes	Confirmed ActionCandidate event; retention review task event	Async event
AI Guardian	Finding follow-up task event	Async event
AI Quality Monitor	Quality finding remediation task event	Async event
AI Concierge	Unresolved call follow-up task event; recovery follow-up task event	Async event
Lab Manager	SLA breach escalation event with task payload	Async event
Knowledge, Training & Learning	Pathway assignment event	Async event
HR & People Manager	Policy workflow step event; Critical Risk escalation event	Async event
Inventory & Compliance Manager	Compliance cycle task event with lifecycle state	Async event
Referral Manager	SLA breach escalation event; referral state follow-up event	Async event
Recall & Reconnect	Personal follow-up work item event	Async event
Financial Insights	Anomaly / risk follow-up task event	Async event
Product Shop	In-clinic fulfilment / exception-handling task event	Async event
Digital Forms	Form review / re-capture task event	Async event
Admin Control Plane	Tenant health event with task payload	Async event
Aiden	AIAction / AIIntent task suggestion (ActionType: Suggest only; requires human confirmation)	Sync confirmation surface
Access Manager	Access revocation event	Async event

6.2 Outbound (this module emits to)

To module	What	Contract
Communication Hub	Task state-change notification triggers	Async event
Smart Dashboards	Open task queue state, overdue task counts, SLA state signals (near real-time)	Async event
Rota Manager	Read-only consumption of Work Package overlay; no write-back	—
Access Manager	RBAC enforcement queries	Sync
Audit & Compliance	Immutable audit event stream	Async event

6.3 PMS Boundary

Task Manager does not directly integrate with the Practice Management System (PMS). PMS-originated events that require operational follow-up reach Task Manager via intermediate modules (e.g. Appointment Manager, Communication Hub) rather than directly.

6.4 Rota Manager — Work Package Overlay Contract

Rota Manager defines ShiftType: WorkPackage as a first-class shift type. When a shift of this type is active, Rota Manager signals Task Manager via a Work Package overlay event. Task Manager MUST interpret this overlay as an instruction to surface and activate the work package(s) associated with that shift slot for the relevant role and location.

Specifically:

• Task Manager consumes the Work Package overlay event from Rota Manager, which carries at minimum the shift reference, role, location, and linked work package template identifier.
• Task Manager generates (or activates) the corresponding work package instance, consistent with its standard template-driven generation rules (idempotent, fully auditable, fresh instance per recurrence).
• Staff availability data that informs which roles are on shift remains the exclusive responsibility of Rota Manager; Task Manager does not replicate or override availability logic.
• The integration is read-only from Task Manager's perspective with respect to shift data: Task Manager receives the overlay event and acts on it; it does not write back to Rota Manager.

7. AI Boundaries (Non-Negotiable)

Module uses Aiden (Primoro AI Assistant) as an AI surface.

AI MAY:

• Suggest tasks or highlight risk to authorised staff for review (using ActionType: Suggest only when targeting Task Manager)
• Display ConfidenceScore from AIIntent to aid human judgement
• Summarise task activity for human review

AI MAY NOT:

• Create, assign, or complete tasks autonomously
• Emit ActionType values of Create, Assign, or Complete when TargetModule is task-manager
• Bypass the RequiresConfirmation: true flag on any AIAction payload
• Override governance, audit, or access checks
• Make commitments on behalf of the practice
• Replace required clinical or managerial judgement

Task Manager MUST reject any AIAction payload where RequiresConfirmation is absent or false, or where ActionType is anything other than Suggest for Aiden-originated actions targeting this module. Confirmed AI-suggested tasks carry Origin: AI-Suggested and retain a LinkedEntities back-link to the originating AIIntent.

8. Audit & Compliance

The system MUST log all of the following events, immutably and with actor attribution and timestamp:

• Task and work package creation, including creation source (Manual, Callback, Workflow, Template-Generated, AI-Suggested), template linkage, and recurrence linkage
• Ownership assignment and reassignment (including system-initiated reversion to role queue on access revocation)
• All lifecycle state transitions, including Kanban board moves
• SLA state changes (On-track → At-risk → Breached)
• Checklist creation, checklist-item completion, and evidence capture (notes, comments, photos, file attachments)
• Task acknowledgement actions (distinct from claiming or completing)
• Completion and cancellation (with cancellation reason)
• Archival and retention policy application
• Secure-deletion events
• All AI suggestions received (AIIntent / AIAction), including which were accepted and which were rejected by authorised users, and including any payloads rejected for carrying disallowed ActionType values or absent RequiresConfirmation flags
• Access revocation events and resulting ownership reversion, recording the revoked user ID, timestamp, and new owner state

Audit logs MUST be immutable, attribution-complete, and exportable for inspection. Completed tasks retain their completion attribution to the named user even after that user's access is revoked; the audit log is never modified retrospectively.

9. Access Control

Access is enforced via Access Manager using role-based permissions.

The following permission boundaries apply:

Action	Who may perform it
Create task (manual)	Authorised staff per role permissions
Create task (event-driven / template)	System (on behalf of originating module)
Read task	Owner, assigned role, supervisors, administrators (confidential tasks: restricted)
Claim role-queue task	Eligible role members
Acknowledge task	Any user with read access to the task
Update task (progress, evidence)	Owner or claiming user
Reassign / change ownership	Supervisor or administrator role
Cancel task	Authorised staff per role permissions; requires reason
Archive task	System (retention policy); administrator
Administer templates and recurrence	Administrator role via Web Portal
Inspect audit log	Administrator / compliance officer (read-only)

Additional requirements:

• Device-level authentication is enforced on shared surgery and decontamination tablets via Access Manager.
• Access revocation propagates immediately across all devices, including forced logout of active sessions. Task Manager MUST revert ownership of in-flight tasks (Created, Active, In Progress, Blocked) to the associated role queue on receipt of a revocation event. Where no role queue can be determined, the task MUST be flagged for manual reassignment by an administrator and surfaced in the Web Portal exception view.
• Confidential tasks MUST restrict visibility to explicitly permitted roles and users.
• MFA requirements for sensitive operations (e.g. cancellation of compliance-linked tasks, bulk reassignment) are governed by Access Manager configuration and are not hardcoded within Task Manager.

10. Integration Summary

• Rota Manager — inbound Work Package overlay event (async); inbound AbsenceChangeEvent for absence-triggered tasks (async); read-only from Task Manager's perspective
• Appointment Manager — inbound AppointmentTaskTriggerEvent for lifecycle transition tasks (async); inbound Reschedule Job follow-up event (async)
• Communication Hub — inbound conversation-triggered task event (async); inbound message-to-work conversion task event (async); outbound task state-change notification triggers (async)
• Aftercare Manager — inbound aftercare trigger event (async)
• Aiden — inbound AIAction / AIIntent task suggestion surface (ActionType: Suggest only; sync confirmation)
• AI Meeting Notes — inbound confirmed action and retention review task events (async)
• AI Guardian — inbound finding follow-up task events (async)
• AI Quality Monitor — inbound quality finding remediation task events (async)
• AI Concierge — inbound unresolved call and recovery follow-up task events (async)
• Lab Manager — inbound SLA breach escalation event (async)
• Knowledge, Training & Learning — inbound pathway assignment event (async)
• HR & People Manager — inbound policy workflow step event (async); inbound Critical Risk escalation event (async)
• Inventory & Compliance Manager — inbound compliance cycle task event with lifecycle state mapping (async)
• Referral Manager — inbound SLA breach escalation event (async); inbound referral state follow-up event (async)
• Recall & Reconnect — inbound personal follow-up work item event (async)
• Financial Insights — inbound anomaly / risk follow-up task event (async)
• Product Shop — inbound in-clinic fulfilment / exception-handling task event (async)
• Digital Forms — inbound form review / re-capture task event (async)
• Admin Control Plane — inbound tenant health event (async)
• Access Manager — RBAC enforcement (sync); access revocation event (async)
• Audit & Compliance — outbound immutable audit event stream (async)
• Smart Dashboards — outbound open task queue state, overdue task counts, and SLA state signals (async, near real-time)

11. Explicit Non-Goals

• Not a replacement for full enterprise project-management tools; work-package depth is operational, not programme-management-grade.
• Does not store conversations or messages — owned by Communication Hub.
• Does not determine staff availability — owned by Rota Manager.
• Does not automate work without explicit human confirmation at every step.
• Not a clinical record system; clinical notes remain outside Task Manager's scope.
• Does not own Reschedule Job tracking for appointment rescheduling — owned by Appointment Manager.

12. Versioning & Governance

This specification is owned by: the Task Manager module owner.

Changes to this spec require:

• Review by the MVP module owner
• Impact analysis across all declared related modules (see /propose)
• Version bump (patch / minor / major depending on scope of change)

All future changes must preserve the following invariants:

• Calendar-backed work
• Explicit ownership at all times
• Fully auditable state transitions
• Role-first execution
• Separation of concerns between Task Manager and originating modules

13. Build Contract (Engineering & QA)

13.1 Canonical Data Model

Task

Task (
  TaskId                UUID PRIMARY KEY,          -- immutable
  Title                 TEXT NOT NULL,
  Description           TEXT,
  Category              TEXT,
  DueDateTime           TIMESTAMPTZ,               -- mutually exclusive with TimeWindow fields
  TimeWindowStart       TIMESTAMPTZ,
  TimeWindowEnd         TIMESTAMPTZ,
  Origin                ENUM('Manual','Callback','Workflow','Template-Generated','AI-Suggested') NOT NULL,
  OwnerType             ENUM('User','Role') NOT NULL,
  OwnerId               UUID NOT NULL,
  Status                ENUM('Created','Active','In Progress','Blocked','Completed','Cancelled','Archived') NOT NULL,
  SLAState              ENUM('On-track','At-risk','Breached'),
  Priority              TEXT,
  Confidential          BOOLEAN NOT NULL DEFAULT false,
  LinkedEntities        JSONB,                     -- back-links to originating records
  Overdue               BOOLEAN NOT NULL DEFAULT false,  -- computed and owned by Task Manager
  CompletedTimestamp    TIMESTAMPTZ,
  CompletedByUserId     UUID,
  CancellationReason    TEXT,
  ArchivedAt            TIMESTAMPTZ,
  RetentionPolicyId     UUID,
  AuditLog              JSONB NOT NULL             -- immutable append-only
)

Checklist

Checklist (
  ChecklistId           UUID PRIMARY KEY,          -- immutable
  ParentTaskId          UUID,                      -- FK to Task (nullable if parented to WorkPackage)
  ParentWorkPackageId   UUID,                      -- FK to WorkPackage (nullable if parented to Task)
  AuditLog              JSONB NOT NULL
)

ChecklistItem (
  ChecklistItemId       UUID PRIMARY KEY,          -- immutable
  ChecklistId           UUID NOT NULL,             -- FK to Checklist
  Label                 TEXT NOT NULL,
  CompletionState       BOOLEAN NOT NULL DEFAULT false,
  Evidence              JSONB,                     -- notes, comments, photo/file references
  CompletedByUserId     UUID,
  CompletedTimestamp    TIMESTAMPTZ,
  AuditLog              JSONB NOT NULL
)

Work Package

WorkPackage (
  WorkPackageId         UUID PRIMARY KEY,          -- immutable
  Title                 TEXT NOT NULL,
  Description           TEXT,
  TimeWindowStart       TIMESTAMPTZ NOT NULL,
  TimeWindowEnd         TIMESTAMPTZ NOT NULL,
  OwnerType             ENUM('User','Role') NOT NULL,
  OwnerId               UUID NOT NULL,
  Status                ENUM('Created','Active','In Progress','Blocked','Completed','Cancelled','Archived') NOT NULL,
  LinkedEntities        JSONB,
  AuditLog              JSONB NOT NULL
)

WorkPackageTask (
  WorkPackageId         UUID NOT NULL,
  TaskId                UUID NOT NULL,
  Sequence              INTEGER,
  PRIMARY KEY (WorkPackageId, TaskId)
)

Templates & Recurrence

TaskTemplate (
  TaskTemplateId        UUID PRIMARY KEY,
  Title                 TEXT NOT NULL,
  Description           TEXT,
  Category              TEXT,
  DefaultOwnerType      ENUM('User','Role'),
  DefaultOwnerId        UUID,
  DueWindowRules        JSONB,
  ChecklistStructure    JSONB,
  EvidenceRequirements  JSONB,
  AuditLog              JSONB NOT NULL
)

WorkPackageTemplate (
  WorkPackageTemplateId UUID PRIMARY KEY,
  Title                 TEXT NOT NULL,
  TaskTemplates         JSONB,
  ChecklistStructures   JSONB,
  AssignmentRules       JSONB,
  TimingRules           JSONB,
  AuditLog              JSONB NOT NULL
)

RecurrenceRule (
  RecurrenceRuleId      UUID PRIMARY KEY,
  TemplateId            UUID NOT NULL,
  TemplateType          ENUM('Task','WorkPackage') NOT NULL,
  Schedule              JSONB NOT NULL,            -- daily/weekly/monthly/custom definition
  GeneratedInstances    JSONB,                     -- links to generated instance IDs
  AuditLog              JSONB NOT NULL
)

13.2 Core Behaviour Rules

1. Every task and work package MUST be calendar-backed: either DueDateTime or both TimeWindowStart and TimeWindowEnd MUST be set at creation.
2. Ownership MUST be explicit at all times; OwnerId and OwnerType MUST be non-null on every task.
3. All lifecycle state transitions — including Kanban board drag-and-drop moves — MUST be recorded in the immutable AuditLog with actor identity and timestamp.
4. Template recurrence MUST always generate a new instance per schedule tick; instances are never reused or silently duplicated (idempotent generation).
5. All evidence captured on checklist items (notes, comments, photos, files) MUST be attributable to a named user and timestamp.
6. Task Manager MUST reject any AIAction payload where RequiresConfirmation is absent or false, or where ActionType is anything other than Suggest for Aiden-originated actions targeting this module; AI is never authoritative.
7. On receipt of an access revocation event from Access Manager, Task Manager MUST revert ownership of all in-flight tasks (Created, Active, In Progress, Blocked) owned by the revoked user to the associated role queue. Where no role queue can be determined, the task MUST be flagged for manual reassignment.
8. The Overdue boolean flag MUST be computed and kept current by Task Manager; consuming surfaces MUST NOT compute it independently.
9. Acknowledgement MUST be recorded as a distinct, time-stamped, attributed audit event; it MUST NOT alter task lifecycle state or ownership.
10. All event-driven tasks from Admin Control Plane, AI Meeting Notes, AI Guardian, AI Quality Monitor, AI Concierge, Lab Manager, Knowledge Training & Learning, HR & People Manager, Inventory & Compliance Manager, Referral Manager, Recall & Reconnect, Financial Insights, Product Shop, Digital Forms, and Rota Manager (absence-triggered) MUST carry a LinkedEntities back-link to the originating record.
11. Cancellation MUST require and record a reason; the CancellationReason field MUST be non-null on any task in Cancelled state.
12. Completed and Cancelled tasks MUST NOT transition back to any operational state; they may only proceed to Archived.
13. Event-driven task creation MUST be idempotent; re-delivery of the same source event MUST NOT produce duplicate task instances.

13.3 Configuration Surfaces

• Practice-level settings (Admin Control Plane): default SLA windows, retention policy assignments, role-queue definitions, evidence requirements per category, confidential task visibility rules.
• Per-user preferences (Access Manager / Staff App Mode): personal queue display preferences, notification preferences.
• Per-template overrides (Task Manager Web Portal, administrator role): recurrence schedule, default ownership, due-window rules, checklist structure.
• Per-work-package overrides (Task Manager Web Portal, administrator role): claiming configuration, role assignment rules.

13.4 Filtering & Views

The UI MUST support the following standard filters across list, queue, and board views:

• Status (one or more lifecycle states)
• SLA state (On-track, At-risk, Breached)
• Owner / role
• Origin (Manual, Callback, Workflow, Template-Generated, AI-Suggested)
• Category
• Location
• Priority
• Confidential flag (where user has permission)
• Overdue flag
• Date range (due date / time window)

Standard views:

• List views: personal (user-owned), role/team, work-package with task drill-down
• Queue views: role-based, with claim and acknowledge actions
• Board (Kanban) view: tasks grouped by lifecycle state; personal, role-scoped, and location-scoped boards; all moves are audited state transitions; no new lifecycle states introduced by the board view

13.5 Module Extension Map

Future extensions MUST preserve the following invariants to avoid breaking this contract:

• The Origin enum may be extended with new values; existing values are frozen.
• The Status state machine may add intermediate states only between Active and Completed; terminal states (Completed, Cancelled, Archived) are frozen.
• LinkedEntities is a JSONB field; new back-link types may be added without schema migration.
• New event-driven sources integrate by emitting a payload conforming to the existing event-driven task contract (§4.3); no core schema changes are required.
• Template structures use JSONB for extensibility; new template fields may be added non-breaking.

13.6 Acceptance Criteria

The build of Task Manager is complete when:

• [ ] All canonical objects (Task, Checklist, ChecklistItem, WorkPackage, TaskTemplate, WorkPackageTemplate, RecurrenceRule) can be created, read, and updated through the API
• [ ] State machine transitions enforce all rules in §3.2 and §13.2, including terminal-state freezing and cancellation-reason requirement
• [ ] Kanban board drag-and-drop is treated as an audited state transition identical to programmatic transitions
• [ ] All integrations in §6 are wired and event payloads validated
• [ ] AI boundaries in §7 are enforced; negative tests confirm AIAction payloads without RequiresConfirmation: true are rejected, and payloads with ActionType of Create, Assign, or Complete from Aiden are rejected
• [ ] Audit log captures every event class in §8 with actor and timestamp
• [ ] Access control is enforced per §9; confidential task visibility is restricted correctly
• [ ] Access revocation from Access Manager triggers role-queue ownership reversion on all in-flight tasks (§8, §9)
• [ ] Acknowledgement action is available as a distinct control in Staff App Mode and recorded as a distinct audit event
• [ ] Overdue flag is computed by Task Manager and surfaced correctly in the tablet data contract fields (DueTime, Status, CompletedTimestamp, CompletedByUserId, Overdue)
• [ ] AI Meeting Notes task creation works for both confirmed action tasks and retention review tasks, with correct LinkedEntities back-links and idempotent behaviour on event re-delivery
• [ ] AI Guardian finding follow-up task creation contract is satisfied, including LinkedEntities back-link
• [ ] AI Quality Monitor quality finding remediation task creation contract is satisfied, including LinkedEntities back-link
• [ ] AI Concierge unresolved call and recovery follow-up task creation contract is satisfied
• [ ] Lab Manager escalation task creation contract is satisfied, including LinkedEntities back-link and default ownership
• [ ] Knowledge, Training & Learning pathway assignment task creation is functional with lifecycle tracking
• [ ] HR & People Manager workflow step and Critical Risk escalation task creation carry correct Origin: Workflow and LinkedEntities
• [ ] Inventory & Compliance Manager lifecycle state mapping is implemented per the table in §4.3
• [ ] Referral Manager SLA breach and referral state follow-up task creation contracts are satisfied
• [ ] Recall & Reconnect personal follow-up work item creation is functional with correct LinkedEntities back-link
• [ ] Financial Insights anomaly / risk follow-up task creation is functional
• [ ] Product Shop in-clinic fulfilment / exception-handling task creation is functional
• [ ] Digital Forms form review / re-capture task creation is functional
• [ ] Rota Manager AbsenceChangeEvent consumption triggers absence-driven tasks correctly where configured
• [ ] Appointment Manager AppointmentTaskTriggerEvent consumption creates lifecycle transition tasks correctly
• [ ] Admin Control Plane health event task creation is functional and tenant-scoped
• [ ] Rota Manager Work Package overlay event is consumed and activates the correct work package instance idempotently
• [ ] Template recurrence generates new instances idempotently per schedule, with LinkedEntities back-link to template
• [ ] Smart Dashboards outbound signal (open task queue, overdue counts, SLA state) is emitted correctly on state change
• [ ] Staff App Mode task surface applies correct role-scoped and location-scoped filtering rules
• [ ] All non-functional requirements in §14 are met

14. Non-Functional Requirements

• Performance: Board and list views MUST load within acceptable latency under expected concurrent user load. Overdue flag MUST be recomputed without perceptible lag at the point of due-time expiry.
• Reliability: No silent loss of task state or audit events. Idempotent recurrence generation MUST be safe to retry without creating duplicate instances. Graceful degradation is required: if an upstream event source is unavailable, Task Manager MUST queue incoming events and process them on recovery rather than silently discarding them.
• Scalability: The module MUST support multi-site, multi-tenant deployments. Role queues, board views, and tablet surfaces MUST be correctly scoped by location and tenant without cross-tenant data leakage.
• Security: All task data MUST be encrypted at rest and in transit. Secrets and key management follow platform conventions. Confidential task payloads MUST not be exposed to unauthorised roles at any layer, including event payloads emitted to other modules.
• Privacy: Task data linked to patients (e.g. callback tasks) is subject to GDPR data-subject rights. Retention policies and secure-deletion events MUST be audit-logged. Data retention periods are configurable per practice via Admin Control Plane; Task Manager enforces the configured policy but does not set default retention periods unilaterally.
• Observability: Task Manager MUST export metrics covering task creation rate, SLA breach rate, overdue task count by role and location, and event-processing latency. Structured logs MUST be emitted for all state transitions. Distributed traces MUST be propagated across cross-module event boundaries to support end-to-end latency diagnosis.
• Accessibility: All staff-facing UI surfaces (Web Portal, Staff App Mode, tablet views) MUST meet WCAG 2.1 AA accessibility standards, consistent with platform-wide requirements.

15. Open Questions

Outstanding decisions before this spec can be promoted from draft to published.

1. Confidential task event payloads — When Task Manager emits a state-change event to Communication Hub for a confidential task, what data should the payload contain? The original is silent on whether confidential task titles/descriptions are redacted in outbound events.
2. Compliance lifecycle state mapping agreement — The spec states that Inventory & Compliance Manager and Task Manager MUST agree the compliance lifecycle state mapping during integration design. This agreement has not yet been completed; the mapping table in §4.3 is a draft proposal pending sign-off from both module owners.
3. Retention periods — The spec references configurable retention policies and secure deletion but does not define default retention periods for any task category. These defaults need to be defined before the Admin Control Plane configuration surface can be built.
4. Overdue flag recomputation mechanism — The spec requires the Overdue flag to be computed and kept current by Task Manager, but does not specify whether this is event-driven (triggered at DueTime), polling-based, or a read-time computation. The implementation approach needs to be agreed before the tablet data contract acceptance criterion can be validated.
5. Board view scope for work packages — The spec states that personal, role-scoped, and location-scoped boards are supported. It is silent on whether a board view scoped to a work package (showing constituent tasks) is also required. This needs clarification before UI build.
6. Absence-driven task creation configuration — The spec notes that Rota Manager AbsenceChangeEvent MAY trigger task creation, depending on integration configuration. The specific absence state transitions that should trigger tasks (and their default payloads) have not yet been agreed between the Rota Manager and Task Manager module owners.
7. Smart Dashboards signal contract — The outbound signal contract for Smart Dashboards (open task queue state, overdue task counts, SLA state) is described at a high level. The precise payload schema, polling interval or push mechanism, and per-role filtering semantics need to be defined before the Smart Dashboards integration acceptance criterion can be validated.