Loyalty Insights – Technical Specification

1. Module Purpose & Scope (Authoritative)

Loyalty Insights is Primoro's intelligence layer for patient loyalty, engagement, and retention. It continuously analyses behavioural, clinical-adjacent, and engagement signals to answer three prioritised questions: who is thriving, who is drifting or at risk, and where the team should act now. It sits between Primoro Core's foundational data and action-oriented modules such as Recall & Reconnect, Communication Hub, and Rewards Manager — surfacing explainable, prioritised insight and handing off cleanly to those modules for execution.

It governs:

• Dynamic loyalty status assignment and segmentation for every patient record.
• Practice-level and patient-level insight dashboards, including drill-down to cohort and individual views.
• Practitioner-linked cohort insight surfaces for authorised managerial users.
• Analytical consumption of signals from enabled optional modules (Rewards Manager, Care Plan Subscriptions, Hygiene Subscriptions) in a strictly read-only capacity.
• Structured action handoffs to Recall & Reconnect, Communication Hub, Campaigns / Outreach, and Rewards Manager.

It explicitly does not:

• Execute outreach, recalls, or reward transactions — those are owned by Recall & Reconnect, Communication Hub, Campaigns / Outreach, and Rewards Manager respectively.
• Operate as a generic reporting or marketing analytics dashboard — Performance Dashboards owns that surface.
• Write to, modify, or trigger any operation on the Rewards Manager points ledger or redemption state — Rewards Manager is the sole authoritative owner of that data.

2. Ownership & Responsibilities

2.1 Loyalty Insights IS Responsible For

• Calculating and maintaining a dynamically updated loyalty status for every patient using available signals.
• Rendering explainable insight — every status, flag, or recommendation MUST expose its contributing factors in plain language.
• Surfacing practitioner-linked cohort views (restricted to authorised managerial roles) for support and coaching purposes only.
• Emitting structured action-handoff events to Recall & Reconnect, Communication Hub, Campaigns / Outreach, and Rewards Manager.
• Audit-logging all access to practitioner-linked insight views and all AI-generated suggestions.
• Defining and enforcing the read-only integration boundary against Rewards Manager signal data.

2.2 Loyalty Insights IS NOT Responsible For

• Executing patient outreach or recall workflows — owned by Recall & Reconnect and Communication Hub.
• Running campaigns or bulk outreach — owned by Campaigns / Outreach.
• Issuing, adjusting, cancelling, or redeeming reward points — owned by Rewards Manager.
• Managing care or hygiene plan enrolment, billing, or cancellation — owned by Care Plan Subscriptions and Hygiene Subscriptions.
• Enriching loyalty profiles with care plan membership entitlement data beyond the signal inputs defined in §4.1 — Care Plan Subscriptions explicitly does not own loyalty profile enrichment or churn scoring, and the boundary between signal consumption and plan administration sits at the events listed in Category 4.
• Role and permission management — owned by Access Manager.
• Immutable event log storage — owned by Audit & Compliance.
• Performance reporting unrelated to loyalty signals — owned by Performance Dashboards.

3. Core Objects (Normative)

3.1 Patient Loyalty Profile (Canonical Artefact)

A Patient Loyalty Profile is a governed digital artefact representing the current and historical loyalty state of a single patient, derived from weighted behavioural signals.

Minimum required fields:

• ProfileID
• PatientID (FK to patient record in Primoro Core)
• LoyaltyStatus (enum: Highly Engaged | Stable | At-Risk | Disengaged)
• ContributingFactors (structured list of signals and their relative weight at last calculation)
• LastCalculatedAt
• CreatedAt
• UpdatedBy (system / rule engine)
• AuditTrail (immutable)

3.2 Patient Loyalty Profile State Machine (Authoritative)

States:

• Highly Engaged
• Stable
• At-Risk
• Disengaged

Rules:

• Status is recalculated automatically as new behavioural signals are received; no manual state promotion is required for standard transitions.
• All status changes are timestamped and recorded in the immutable AuditTrail.
• No status transition may be suppressed or overridden by a staff user; the profile reflects the computed state at all times.
• Status MUST NOT be displayed as a raw numerical score without an accompanying plain-language explanation.

AI Aiden signal-consumption boundary:

AI Aiden MAY surface loyalty signals — including current status, contributing factors, and churn risk indicators — that have been calculated and emitted by Loyalty Insights. Aiden MUST NOT independently recalculate, re-evaluate, or modify any loyalty signal, status value, or churn risk score. The authoritative calculation for all loyalty and churn signals is owned exclusively by Loyalty Insights. Aiden's role is limited to presenting, explaining, and suggesting actions based on the signals it receives from this module; it does not hold or derive its own loyalty state. This boundary aligns with Aiden's own specification, which explicitly excludes calculating churn risk predictions or loyalty signals from its responsibilities.

3.3 Action Handoff (Canonical Artefact)

An Action Handoff is a governed event record representing the explicit referral of an insight-driven action from Loyalty Insights to an executing module.

Minimum required fields:

• HandoffID
• SourceProfileID (FK to Patient Loyalty Profile)
• TargetModule (enum: Recall & Reconnect | Communication Hub | Campaigns / Outreach | Rewards Manager)
• HandoffReason (plain-language statement)
• InitiatedBy (staff user or configured automation)
• InitiatedAt
• OutcomeReceivedAt (nullable — populated when target module reports back)
• OutcomeSummary (nullable)
• AuditTrail (immutable)

Handoffs MUST be reversible prior to execution by the target module; once the target module has acted, reversal is the responsibility of that module's own cancellation flow.

4. Loyalty Signal Model (Normative)

4.1 Core Signal Categories

Loyalty Insights evaluates signals across five categories. Categories 1–3 are available with Primoro Core alone. Categories 4–5 require the relevant optional modules to be enabled.

Category 1 — Attendance & Frequency (Core)

• Completed visits and visit frequency.
• Gaps between visits.
• Did-not-attends (DNAs) and late cancellations.

Category 2 — Recall Behaviour (Core)

• Compliance versus overdue status.
• Response latency to recall communications.

Category 3 — Engagement Signals (Core)

• App usage where available.
• Message opens and confirmation responses.

Category 4 — Plan & Continuity Signals (Optional — Care Plan Subscriptions / Hygiene Subscriptions)

• Care or hygiene plan longevity.
• Cancellation risk indicators.

Care Plan Subscriptions and Hygiene Subscriptions do not own loyalty profile enrichment or churn scoring; the signals consumed here are limited to the plan longevity and cancellation risk events that those modules expose as read-only outputs. Plan membership entitlement detail, billing state, and suspension status are internal to those modules and are not ingested as loyalty signals unless explicitly surfaced in a defined event contract. Any expansion of the Category 4 signal set requires a minor version bump to this spec and a corresponding contract change with the source module.

Category 5 — Rewards & Advocacy Signals (Optional — Rewards Manager)

• Points issued: volume and frequency of reward points awarded, used to assess reward engagement depth.
• Points redeemed: redemption events and timing, used to evaluate correlation with visit or retention behaviour.
• Referral pipeline states: current and historical status of patient-initiated referrals (referred, converted, lapsed), used to assess referral effectiveness and advocate value.
• Charity donation events: instances where a patient donated reward value, used as a positive advocacy signal.
• Reward account credit activity: aggregated credit and debit movements, used to identify reward engagement trends across cohorts.

All signals are time-weighted and trend-aware.

Rewards signals framing requirement: When Category 5 signals are surfaced in any insight view or AI suggestion, they MUST be framed in terms of engagement depth, advocacy value, and retention correlation — not as financial metrics, currency equivalents, or discount indicators. Loyalty Insights MUST NOT present reward-related insight in language that positions earned points as cash, discounts, or monetary incentives. This framing requirement aligns with Rewards Manager's trust-first, behaviour-led model and its explicit prohibition on discount-driven framing.

4.2 Signal Availability Rules (Authoritative)

The module MUST:

• Operate fully with Primoro Core data alone (Categories 1–3).
• Clearly mark optional-module signals as unavailable when the relevant module is not enabled.
• Never display an optional signal surface as empty, broken, or errored when the source module is simply not licensed.

The module MUST NOT:

• Require Rewards Manager, Care Plan Subscriptions, Hygiene Subscriptions, or any other optional module to be active in order to calculate or display a loyalty status.
• Gate any core insight capability behind an optional module licence.

4.3 Recall & Reconnect Handoff and Outcome Contract

When Loyalty Insights detects disengagement patterns that warrant a recall intervention, it emits an Action Handoff event to Recall & Reconnect (per §3.3). The following contract governs the interaction:

Handoff payload (Loyalty Insights → Recall & Reconnect):

• HandoffID
• PatientID
• SourceProfileID
• TriggerSignals (the specific Category 1–3 signals that drove the handoff, with relative weights)
• LoyaltyStatusAtHandoff (the patient's status at the point the handoff was initiated)
• HandoffReason (plain-language statement)
• InitiatedBy
• InitiatedAt

Outcome event (Recall & Reconnect → Loyalty Insights):

Recall & Reconnect MUST emit an outcome event when a recall journey initiated by a Loyalty Insights handoff reaches a terminal state (completed, patient responded, patient unreachable, journey cancelled). Loyalty Insights MUST consume this event and:

• Populate OutcomeReceivedAt and OutcomeSummary on the originating Action Handoff record.
• Feed the outcome back into the signal pipeline as a Category 2 (Recall Behaviour) signal update for the relevant patient, so that status recalculation reflects the recall outcome.
• Log the outcome receipt as an audit event per §8.

Recall & Reconnect is the authoritative source of recall journey outcomes; Loyalty Insights MUST NOT infer or estimate outcomes in the absence of a received outcome event.

4.4 AI Concierge Signal Boundary

Loyalty Insights does not consume AI Concierge contact signals (e.g. contact.reached, contact.accepted, contact.declined, contact.no_answer) directly. Those signals are consumed by Campaign Manager for segmentation and telemetry annotation. If contact-outcome data is relevant to a loyalty signal in future, it MUST flow through a defined inbound contract entry in §11.1 and MUST NOT be sourced by duplicating Campaign Manager's consumption path. This restriction avoids double-counting or conflicting signal derivation between the two modules.

5. Loyalty Status & Segmentation (Authoritative)

5.1 Status Definitions

Each patient is dynamically assigned one of four loyalty statuses:

• Highly Engaged — consistent attendance, strong recall compliance, positive engagement signals.
• Stable — broadly compliant attendance and recall; no significant risk indicators.
• At-Risk — emerging gaps, declining recall compliance, or reduced engagement signals.
• Disengaged — extended inactivity, missed recalls, minimal or no engagement signals.

5.2 Status Rules

• Status MUST be explainable in plain language; the contributing factors that drove the current status MUST be visible to authorised staff.
• Status updates automatically as behaviour changes; no manual recalculation trigger is required.
• No numerical score is surfaced to staff without an accompanying human-readable explanation of what the score represents and which behaviours drove it.
• Status calculations MUST be deterministic and reproducible: given the same input signals at the same point in time, the same status MUST be returned.

6. Dashboards & Views (Required)

6.1 Practice-Level Loyalty Dashboard

The dashboard MUST show:

• Overall retention trend.
• Recall compliance trend.
• Distribution of patients by loyalty status.
• Churn risk alerts.

All metrics MUST support drill-down to cohort lists and to individual patient records.

6.2 Patient-Level Loyalty Panel

Each patient record MUST display:

• Current loyalty status.
• Recent contributing factors in plain language.
• Recommended next actions, if any.

6.3 Practitioner-Linked Cohort Insight (Authoritative — Restricted)

Loyalty Insights MAY surface practitioner-linked cohort views to authorised managerial users for support, coaching, and system improvement purposes only.

Permitted purpose:

• Identifying where additional support, capacity, or process improvement is required.
• Detecting sustained divergence in loyalty outcomes over time.
• Enabling early, constructive intervention.

Prohibited use:

• Automated performance ranking.
• Disciplinary decisions.
• Remuneration or contractual assessment.

Data model rules:

• Insight MUST operate on patient cohorts associated with a primary clinician, not on individual clinician activity in isolation.
• Views MUST show trends over time, not point-in-time snapshots.
• Views MUST always be presented alongside contributing contextual factors (e.g. appointment availability constraints, cohort composition).

Permitted signals include recall compliance of the cohort, average visit gap trends, plan participation rates, engagement responsiveness, and appointment availability constraints.

Comparative context rules:

• Where comparison is shown, it MUST compare against practice distributions or historical baselines.
• Ordinal rankings, league tables, and percentile labelling are prohibited.
• Language MUST be neutral (e.g. "requires support", "capacity constrained", "improving").

Explainability requirement:

For any practitioner-linked insight, the module MUST display why the cohort was flagged, which contributing factors were most influential, and which levers are likely to improve outcomes.

Governance:

• Views are restricted to authorised managerial roles as defined in Access Manager.
• All access to practitioner-linked insight views is audit-logged.
• Insights are advisory and non-deterministic; they MUST NOT be used as automated decision inputs.

6.4 Referral & Rewards Insight (When Rewards Manager Enabled)

When Rewards Manager is enabled, Loyalty Insights MUST:

• Analyse referral effectiveness.
• Evaluate reward impact on retention.
• Highlight stalled or high-value advocates.

These insights are analytical only. Operational tracking of referrals and rewards remains in Rewards Manager.

All referral and rewards insight surfaces MUST adhere to the framing requirement in §4.1: engagement depth and advocacy value framing only; no financial, currency, or discount framing.

7. AI Boundaries (Non-Negotiable)

Loyalty Insights embeds AI Aiden as its insight and recommendation layer.

AI Aiden MAY:

• Predict churn risk from available signal patterns.
• Identify leading indicators of loyalty status change.
• Suggest proportionate actions for staff consideration.
• Explain recommendations in plain language, including confidence level.
• Summarise cohort or individual loyalty activity for human review.

AI Aiden MUST NOT:

• Contact patients autonomously or trigger any outreach without explicit staff approval.
• Change loyalty status classification rules or segmentation criteria.
• Alter signal weighting or scoring logic without a governed configuration change.
• Make commitments on behalf of the practice.
• Bypass audit logging, access control, or governance checks.
• Replace required clinical judgement.
• Auto-decide on any policy-bound action; all execution MUST be deferred to staff or explicitly configured automation with staff oversight.
• Recalculate, re-evaluate, or modify any loyalty signal or status value — Aiden surfaces signals produced by Loyalty Insights only (see §3.2).

Every AI suggestion MUST be logged, including whether it was accepted, modified, or rejected by the staff member who reviewed it.

8. Audit & Compliance

The system MUST log the following events:

• All loyalty status changes for a patient, including the signal inputs that triggered the change, the prior status, the new status, and the timestamp.
• All staff reads of patient-level loyalty panels, with actor and timestamp.
• All reads of practitioner-linked cohort insight views, with actor, role, and timestamp.
• All action handoffs initiated, including the initiating actor, target module, and handoff reason.
• All outcome reports received back from target modules against a handoff record.
• All AI Aiden suggestions presented to staff, including the full suggestion content, the staff member who reviewed it, and the outcome (accepted / modified / rejected).
• All cross-module data consumption events from Rewards Manager signal feeds, confirming read-only access.
• All configuration changes to signal weighting, status thresholds, or dashboard settings, with actor and timestamp.

Audit logs MUST be immutable once written and MUST be exportable in a structured format for regulatory inspection.

Loyalty profiling operates under legitimate interest as the legal basis. Patient data MUST NOT be used for competitive ranking of clinicians.

9. Access Control

Access is governed by Access Manager roles. The following capability-to-role mapping defines minimum enforcement requirements; Access Manager is the authoritative source of role definitions.

MFA MUST be required for any admin-level configuration change to signal weighting, status thresholds, or access settings.

No staff user may suppress, override, or manually set a patient's loyalty status.

10. Integration Summary

• Primoro Core — inbound; foundational appointment, recall, attendance, and engagement data consumed as the baseline signal set.
• Recall & Reconnect — bidirectional; outbound action handoff events for at-risk and disengaged patients requiring recall intervention; inbound outcome events consumed to close handoff records and update Category 2 signals (see §4.3).
• Communication Hub — outbound; action handoff events for engagement-driven outreach triggers.
• Campaigns / Outreach — outbound; action handoff events for cohort-level campaign targeting.
• Rewards Manager — inbound (read-only); consumes points issued, points redeemed, referral pipeline states, charity donation events, and reward account credit activity as analytical signals.
• Care Plan Subscriptions — inbound (read-only, optional); consumes plan longevity and cancellation risk signals when module is enabled.
• Hygiene Subscriptions — inbound (read-only, optional); consumes plan longevity and cancellation risk signals when module is enabled.
• AI Assistant (Aiden) — embedded; provides churn prediction, leading indicator identification, and proportionate action suggestions subject to §7 guardrails. Aiden surfaces loyalty signals produced by this module only and does not independently calculate or modify them.
• Access Manager — RBAC enforcement for all read/write/view operations, including restriction of practitioner-linked cohort views to authorised managerial roles.
• Audit & Compliance — outbound; all audit events defined in §8 are emitted to the immutable event log.
• Performance Dashboards — outbound; aggregated loyalty trend data, patient cohort engagement metrics, recall compliance trends, and churn risk alert signals are emitted to Performance Dashboards where that module is enabled. Performance Dashboards owns the broader performance reporting surface; Loyalty Insights' contribution is limited to loyalty-signal-derived aggregates.

11. Integration Contracts

11.1 Inbound (this module consumes from)

Note: AI Concierge contact signals (contact.reached, contact.accepted, contact.declined, contact.no_answer) are consumed by Campaign Manager and are not ingested by Loyalty Insights. Any future requirement to consume these signals MUST be introduced as a new explicit inbound contract entry and MUST NOT duplicate Campaign Manager's consumption path (see §4.4).

11.2 Outbound (this module emits to)

11.3 PMS Boundary

Primoro Core acts as the intermediary for all PMS-sourced data. Loyalty Insights consumes structured data from Primoro Core and MUST NOT connect directly to any PMS data source. Any change in the shape of PMS-sourced data reaching Loyalty Insights is the responsibility of Primoro Core's integration layer to normalise before delivery.

11.4 Rewards Manager Integration Boundary (Authoritative)

Loyalty Insights consumes Rewards Manager signals in a strictly read-only capacity. The module MUST NOT:

• Write to the rewards ledger.
• Issue, adjust, or cancel reward points or redemptions.
• Modify reward eligibility or account credit state.
• Trigger any reward transaction on behalf of a patient or staff member.

This boundary MUST be enforced at the integration layer and is subject to audit logging per §8.

Handoff outcome verification and closure:

When Loyalty Insights emits an action handoff event to Rewards Manager (e.g. an advisory signal regarding a high-value advocate), Rewards Manager logs the outcome of any action it takes against that handoff. Loyalty Insights MUST consume the outcome event returned by Rewards Manager and:

• Populate OutcomeReceivedAt and OutcomeSummary on the originating Action Handoff record.
• Log the outcome receipt as an audit event per §8, confirming the handoff lifecycle is closed.

Rewards Manager is the authoritative source of reward transaction outcomes; Loyalty Insights MUST NOT infer or estimate the result of a reward-related handoff in the absence of a returned outcome event. The audit log entry for outcome receipt MUST reference both the HandoffID and the Rewards Manager transaction or event identifier where one is provided, so that the handoff contract can be independently verified by Audit & Compliance.

12. Explicit Non-Goals

• Generic performance reporting — aggregate clinical or financial performance dashboards are owned by Performance Dashboards.
• Patient outreach execution — composing and sending messages is owned by Communication Hub and Campaigns / Outreach.
• Recall workflow management — scheduling and managing recall sequences is owned by Recall & Reconnect.
• Rewards ledger management — points issuance, redemption, and eligibility are owned by Rewards Manager.
• Care and hygiene plan administration — enrolment, billing, and cancellation are owned by Care Plan Subscriptions and Hygiene Subscriptions.
• Loyalty profile enrichment from plan entitlement data — Care Plan Subscriptions and Hygiene Subscriptions do not own loyalty profile enrichment; Loyalty Insights consumes only the defined Category 4 signal events and does not reach into plan entitlement or billing state.
• Disciplinary or HR tooling — practitioner-linked cohort insight is explicitly scoped to support and coaching; any use in performance management processes is prohibited and out of scope for this module.
• Independent loyalty signal calculation by Aiden — Aiden surfaces and explains signals produced by Loyalty Insights; it does not own or derive loyalty or churn calculations.

13. Versioning & Governance

This specification is owned by the Primoro Post-MVP module owner for Loyalty Insights.

Changes to this spec require:

• Review by the Post-MVP module owner.
• Impact analysis across all declared related modules.
• Version bump (patch for clarifications, minor for behavioural additions, major for breaking contract changes).

14. Build Contract (Engineering & QA)

14.1 Canonical Data Model

(No schema defined in original — needs definition by engineering before build contract is locked.)

The following canonical tables are implied by this specification and must be formally defined:

• patient_loyalty_profiles — one record per patient; holds current status, contributing factors, and audit trail.
• loyalty_signal_inputs — time-series record of each signal ingested per patient per calculation cycle.
• action_handoffs — one record per handoff event, with outcome fields populated asynchronously.
• ai_suggestions — one record per Aiden suggestion presented, with staff disposition recorded.

14.2 Core Behaviour Rules

1. A Patient Loyalty Profile MUST exist for every patient in Primoro Core once Loyalty Insights is activated for the practice.
2. Loyalty status MUST be recalculated automatically when a new signal event is received for a patient.
3. Every status change MUST produce an immutable audit entry with prior status, new status, signal inputs, and timestamp.
4. Status MUST NOT be displayed without at least one plain-language contributing factor explanation.
5. Optional-module signals (Categories 4–5) MUST be clearly marked as unavailable when the source module is not enabled; they MUST NOT cause errors or empty-state failures.
6. All action handoffs MUST be logged before the handoff event is emitted to the target module.
7. All AI Aiden suggestions MUST be logged at the point of presentation; staff disposition MUST be captured before the suggestion is acted upon.
8. Rewards Manager signal consumption MUST be enforced as read-only at the integration layer; any write attempt MUST be rejected and logged.
9. Practitioner-linked cohort insight views MUST enforce role restriction; any access attempt by an unauthorised role MUST be rejected and logged.
10. Loyalty status MUST NOT be shown as a raw numerical score without an accompanying plain-language explanation.
11. Comparative views in practitioner-linked cohort insight MUST NOT render league tables, ordinal rankings, or percentile labels.
12. All audit logs MUST be written atomically with the event they record; a failed audit write MUST prevent the originating action from completing.
13. Recall & Reconnect outcome events received against a Loyalty Insights-initiated handoff MUST be consumed, used to close the handoff record, and fed back into the Category 2 signal pipeline for the relevant patient.
14. Rewards Manager outcome events received against a Loyalty Insights-initiated handoff MUST be consumed and used to close the handoff record; the audit log entry MUST reference both the HandoffID and any Rewards Manager event identifier provided.
15. Category 5 signal insights MUST be framed in engagement and advocacy terms; financial, currency, or discount framing is prohibited in all UI surfaces and AI suggestions.
16. Aiden MUST NOT independently recalculate or modify any loyalty signal or status value; any attempt by an Aiden integration to write loyalty state MUST be rejected and logged.

14.3 Configuration Surfaces

• Practice-level settings (Admin Control Plane): Enable/disable optional signal categories; configure churn risk alert thresholds; enable/disable practitioner-linked cohort insight surfaces.
• Per-user preferences (Access Manager): Dashboard layout preferences where supported.
• Per-module overrides (Loyalty Insights admin): Signal weighting adjustments within governed bounds.

14.4 Filtering & Views

Standard filters the UI must support:

• Filter by loyalty status (Highly Engaged / Stable / At-Risk / Disengaged).
• Filter by practitioner (managerial roles only, for cohort views).
• Filter by time period (rolling 30 / 90 / 180 / 365 days).
• Filter by signal category (Attendance, Recall, Engagement, Plan, Rewards).
• Drill-down from practice-level dashboard to cohort list to individual patient record must be supported in a single navigation flow.

14.5 Module Extension Map

• Signal Categories 4 and 5 are already designed as optional enrichment layers; adding further optional signal sources from future modules follows the same pattern without breaking the core calculation contract.
• Action handoff target modules are an extensible enum; adding a new target module requires a minor version bump to this spec and a new outbound integration contract entry in §11.2.
• Practitioner-linked cohort insight is a governed optional surface; enabling or expanding its scope requires a minor version bump and governance review.
• The Performance Dashboards outbound signal set (§11.2) is a governed surface; adding new aggregated loyalty metrics to that feed requires a minor version bump and alignment with the Performance Dashboards module owner.

14.6 Acceptance Criteria

The build of Loyalty Insights is complete when:

• [ ] Patient Loyalty Profiles are created and maintained for all patients in Primoro Core once the module is activated.
• [ ] Loyalty status is recalculated automatically on signal receipt and updates are reflected in all views.
• [ ] Practice-level dashboard renders all required metrics with drill-down to cohort and patient level.
• [ ] Patient-level loyalty panel renders status, contributing factors, and recommended actions.
• [ ] All five signal categories ingest correctly; Categories 4–5 are cleanly absent (not broken) when source modules are not enabled.
• [ ] Rewards Manager integration enforces read-only boundary (negative tests: write attempts rejected and logged).
• [ ] Recall & Reconnect outcome events are consumed, close the originating handoff record, and update Category 2 signals correctly.
• [ ] Rewards Manager handoff outcome events are consumed, close the originating handoff record, and produce an audit entry referencing both HandoffID and Rewards Manager event identifier.
• [ ] Category 5 insight surfaces use engagement and advocacy framing only; financial or discount language is absent (content review required).
• [ ] Aiden integration does not expose any write path to loyalty status or signal values (negative tests: write attempts rejected and logged).
• [ ] Performance Dashboards outbound signal feed emits cohort engagement metrics, recall compliance trends, and churn risk alert signals correctly when Performance Dashboards is enabled.
• [ ] Practitioner-linked cohort insight views are accessible only to authorised managerial roles (negative tests: unauthorised access rejected and logged).
• [ ] Comparative views contain no ordinal rankings, league tables, or percentile labels.
• [ ] All AI Aiden suggestions are logged with staff disposition captured.
• [ ] All action handoffs are logged before emission; outcome fields are populated on receipt from target modules.
• [ ] Audit log captures every event in §8; logs are immutable and exportable.
• [ ] All non-functional requirements in §15 are met.

15. Non-Functional Requirements

• Performance: Practice-level dashboard MUST load within an acceptable latency target to be defined by engineering; patient-level loyalty panel MUST render within the same page-load budget as the patient record itself. Signal recalculation MUST not block user-facing read operations.
• Reliability: The module MUST degrade gracefully if optional signal sources (Rewards Manager, Care Plan Subscriptions, Hygiene Subscriptions) are temporarily unavailable — core loyalty status based on Categories 1–3 MUST remain available. Availability target to be defined by platform SLA.
• Scalability: The signal ingestion and calculation pipeline MUST support multi-site and multi-tenant operation; a single patient's recalculation MUST NOT degrade calculation throughput for other patients or practices.
• Security: All patient-bound data MUST be encrypted at rest and in transit. Practitioner-linked cohort data MUST be subject to the same encryption controls. Secrets and integration credentials MUST be managed via the platform's approved secrets management approach.
• Privacy: Loyalty profiling operates under legitimate interest as the legal basis. The module MUST honour applicable GDPR rights (access, erasure, rectification) for patient data it holds. Data retention policy for loyalty profiles and signal history to be defined before build contract is locked.
• Observability: The module MUST export metrics covering signal ingestion rate, status recalculation latency, handoff event emission rate, handoff outcome receipt rate, and AI suggestion acceptance rate. Structured logs and distributed traces MUST be emitted for all calculation and handoff operations.

16. Open Questions

1. Data retention policy: How long are Patient Loyalty Profiles and their signal history retained? What happens to a profile when a patient is archived or deleted from Primoro Core? (implied by §8 and §15 Privacy requirements — no decision captured in original.)
2. Recalculation trigger model: Is loyalty status recalculated in real-time on every signal event, on a scheduled batch cycle, or via a hybrid approach? The original states "updates automatically as behaviour changes" but does not specify the technical trigger mechanism. (implicit in §4 and §5.)
3. AI confidence threshold: At what confidence level does Aiden surface a churn risk prediction to staff? Is there a configurable suppression threshold below which suggestions are not shown? (implied by §8.1 Guardrails but not defined.)
4. Practitioner-linked cohort insight — opt-in or opt-out: Is this surface enabled by default for all practices at activation, or must it be explicitly enabled by a practice admin? (§9.5 defines governance but not the default activation state.)
5. Handoff reversibility window: How long after initiation may a staff user reverse an action handoff before it is considered committed? (§3.3 states handoffs must be reversible prior to execution but does not define the mechanism or window.)
6. Numerical score display: The original prohibits showing numerical scores "without context" but does not define whether numerical scores are ever shown. Is there a decision to prohibit them entirely, or to permit them only with explanation? (§4 and §5.2 are ambiguous on this point.)
7. Performance Dashboards authorisation boundary: When Loyalty Insights emits aggregated loyalty data to Performance Dashboards, should patient-identifiable drill-down be available within the Performance Dashboards surface, or should the outbound feed be anonymised at the boundary? Authorisation model to be agreed between the two module owners.
8. Recall & Reconnect outcome event schema: The outcome event contract defined in §4.3 requires formal schema agreement with the Recall & Reconnect module owner before build contract is locked.