Treatment Pipeline Manager – Technical Specification

1. Module Purpose & Scope (Authoritative)

Treatment Pipeline Manager is Primoro's governed operational engine and single system of record for dental sales and treatment conversion. It controls how enquiries enter the organisation, manages intent qualification and triage, enforces booking eligibility, and drives timely follow-up through SLAs and next-actions. It prevents leakage, duplication, and unsafe automation across all intake channels.

It governs:

• Leads — new patient or new treatment enquiries not yet fully qualified for booking
• Opportunities — qualified treatment intent associated with a known patient
• Pipeline Stacks and Stage Templates — the governed operational views and progression rules that route records through the conversion journey
• BookingEligibility — the authoritative field that controls whether booking is permitted; enforced across all channels

It explicitly does not:

• Send messages, hold conversations, or render conversation UX (Communication Hub, AI Concierge, Aiden)
• Perform voice interactions or web chat UX (AI Concierge)
• Manage appointment diaries or slot selection (Appointment Manager)
• Execute marketing campaigns (Campaign Manager)
• Act as a patient portal
• Execute tasks or reminders (Task Manager)
• Exercise clinical judgement or diagnosis

2. Ownership & Responsibilities

2.1 Treatment Pipeline Manager IS Responsible For

• Creating and maintaining Lead and Opportunity records as governed digital artefacts
• Controlling pipeline stages, stacks, and progression rules
• Holding TriageStatus and BookingEligibility as authoritative fields that no other module may override
• Declaring required next actions and SLA expectations per Stack
• Emitting auditable operational and segmentation events to downstream modules
• Acting as the sole source of truth for whether booking is permitted on any given record
• Exposing a governed intake endpoint for AI Concierge to create or link Leads

2.2 Treatment Pipeline Manager IS NOT Responsible For

• Conversation rendering or message delivery — owned by Communication Hub, AI Concierge, and Aiden
• Voice call or web chat UX — owned by AI Concierge
• Task execution or reminder delivery — owned by Task Manager
• Diary availability or appointment slot selection — owned by Appointment Manager
• Marketing campaign execution — owned by Campaign Manager
• Clinical judgement or diagnosis — out of scope for the platform
• Autonomous AI decisions — AI surfaces remain strictly advisory

3. Core Objects (Normative)

3.1 Lead (Canonical Artefact)

A Lead is a governed digital artefact representing a new enquiry that has not yet been fully qualified for booking.

Characteristics:

• May originate from website conversation (Aiden), voice call (AI Concierge), form, or campaign
• Exists independently of a confirmed Patient record
• Is owned by Treatment Pipeline Manager until converted or exited

Minimum required fields:

• LeadID
• SourceChannel — enum: Website, Voice, Form, Campaign, Other
• Stack
• PipelineStage
• TriageStatus
• BookingEligibility — boolean; always false at intake
• ConversationThreadID — indexed reference to Communication Hub thread
• OwnerRole / OwnerUser
• CreatedAt
• AuditTrail (immutable)

Rules:

• A Lead MUST always have exactly one current stage.
• A Lead MUST NOT be booked unless BookingEligibility is explicitly set to true by Treatment Pipeline Manager.
• A Lead MUST reference exactly one ConversationThreadID owned by Communication Hub. Treatment Pipeline Manager MUST store this as a reference and read-only summary only; it MUST NOT replicate or own the full conversation record, which is held exclusively by Communication Hub.

3.2 Opportunity (Canonical Artefact)

An Opportunity is a governed digital artefact representing qualified treatment intent for an existing or newly registered patient.

Characteristics:

• References exactly one Patient record
• Represents a specific treatment intent
• Is the canonical object for conversion and value tracking

Minimum required fields:

• OpportunityID
• PatientID
• Stack
• PipelineStage
• BookingEligibility — boolean
• EstimatedValue — read-only
• ConversationThreadID — indexed reference to Communication Hub thread
• OwnerRole / OwnerUser
• CreatedAt
• AuditTrail (immutable)

Rules:

• A Patient may have multiple Opportunities over time, but only one active Opportunity per treatment intent.
• Opportunities MUST NOT be auto-created by AI channels (Aiden or AI Concierge).
• An Opportunity MUST reference exactly one ConversationThreadID; when a Lead is converted to an Opportunity, the existing ConversationThreadID MUST be carried forward so the unified timeline is unbroken. As with Leads, Treatment Pipeline Manager MUST store this as a reference and read-only summary only; it MUST NOT replicate or own the full conversation record, which is held exclusively by Communication Hub.

3.3 Lead and Opportunity State Machine (Authoritative)

States (applicable to both object types unless noted):

• New Enquiry
• Awaiting Triage
• Qualified – Not Ready
• Booking Permitted
• Booked
• Converted
• Lost / Closed

Rules:

• Stages enforce ordering and guardrails; no record may skip a required stage.
• All stage transitions are auditable and time-stamped in the AuditTrail.
• AI surfaces (Aiden, AI Concierge) MAY recommend stage transitions but MUST NOT execute them.
• A record that has reached Booking Permitted, Booked, Converted, or Lost / Closed MUST NOT be returned to New Enquiry or Awaiting Triage.
• BookingEligibility MUST be set to true by Treatment Pipeline Manager before any record may advance to Booking Permitted.
• Emergency Stack records MUST follow the same state machine but are additionally constrained by the 72-hour maximum lifetime defined in §4.3.

3.3.1 Smart Treatment Proposal Integration

An Opportunity MAY be linked to one or more Smart Treatment Proposals via a LinkedOpportunityID held on the Proposal record.

Proposal state machine. Smart Treatment Proposals operates the following authoritative state machine for each Proposal record:

Treatment Pipeline Manager integrates at the Accepted transition only. Intermediate transitions (Draft → Presented, Presented → Explained & Acknowledged) do not trigger pipeline state changes and MUST be ignored by Treatment Pipeline Manager.

Finance application rule. A patient submitting or being assessed for a finance application MUST NOT cause the Proposal to advance to Accepted. Finance application activity is handled within Smart Treatment Proposals and does not constitute acceptance for the purposes of this integration. Treatment Pipeline Manager MUST NOT treat any finance-related event as a proxy for ProposalAccepted.

Event handling. When a linked Proposal transitions to Accepted, Smart Treatment Proposals MUST emit a ProposalAccepted event carrying the LinkedOpportunityID. Treatment Pipeline Manager MUST handle this event as follows:

• If the Opportunity's current PipelineStage is earlier than Booking Permitted, the pipeline MUST evaluate whether the acceptance satisfies outstanding triage artefacts for the Stack and, if so, set BookingEligibility = true and advance the stage to Booking Permitted.
• If BookingEligibility is already true, the event MUST advance the stage to Converted.
• The stage transition triggered by a ProposalAccepted event MUST be recorded in the AuditTrail with Trigger = ProposalAccepted and the originating ProposalID.

No other module may infer or simulate this transition. Treatment Pipeline Manager is the sole authority for acting on the accepted-proposal signal.

4. Pipeline, Stacks & Stage Templates

4.1 Stacks (Authoritative)

A Stack is a governed operational view over the pipeline, optimised for a specific treatment intent. Each Stack defines:

• Whether it accepts Leads, Opportunities, or both
• Required triage artefacts that must be satisfied before BookingEligibility may be set to true
• SLA thresholds for next-action cadence
• Eligibility rules specific to the treatment type

Example Stacks (non-exhaustive):

• Emergency – New Patient
• New Patient – Free Consultation
• Invisalign – New Patient
• Existing Patient – Treatment Acceptance

Stack definitions are configurable by practice administrators via the Admin Control Plane; the list above is illustrative, not exhaustive.

4.2 Stage Templates

Pipeline stages are derived from Stack-level Stage Templates. The canonical stage sequence is defined in §3.3. Rules:

• Stage transitions enforce ordering and guardrails as declared in the Stage Template for the assigned Stack.
• Stage transitions are auditable.
• AI surfaces MAY recommend transitions; only authorised staff roles may execute them.

4.3 Emergency Stack Contract

Emergency Stacks:

• Have a maximum record lifetime of 72 hours.
• Enforce aggressive SLA thresholds.
• Exclude all marketing and nurture activity; no segmentation events associated with nurture eligibility may be emitted for Emergency Stack records.

5. Source of Truth – Qualification & Booking (Normative)

Booking is permitted only when one of the following is true:

• Lead.BookingEligibility = true
• Opportunity.BookingEligibility = true

BookingEligibility:

• Is owned and set exclusively by Treatment Pipeline Manager.
• Is derived from completed triage and staff review; it MUST NOT be inferred from conversation content, AI output, or any upstream signal.
• MUST be enforced by Appointment Manager and all channels before any booking action is taken.

No upstream system — including AI Concierge or Aiden — may bypass, override, or infer eligibility. Appointment Manager MUST query Treatment Pipeline Manager for the current BookingEligibility value and MUST NOT cache or assume it.

6. Delivery Surfaces & Access (Authoritative)

6.1 Web Portal

Treatment Pipeline Manager surfaces in the staff web portal as a pipeline view, presenting Leads and Opportunities grouped by Stack and stage, with filtering by SLA status, owner, and booking eligibility. Staff may advance stages, update triage artefacts, and set BookingEligibility from this surface.

6.2 Tablet App

On the in-practice tablet, Treatment Pipeline Manager surfaces as a triage and booking readiness dashboard, allowing front-desk staff to review incoming Leads, confirm triage completeness, and hand off to Appointment Manager when eligibility is confirmed.

6.3 Patient Mobile App

Treatment Pipeline Manager has no direct patient-facing surface. Patients interact via Aiden (website) or AI Concierge (voice); all pipeline records are created and managed by staff or governed AI intake channels on the patient's behalf.

6.4 Engagement Signals

Treatment Pipeline Manager emits the following signals for staff visibility and analytics:

• Stage transition events (consumed by Task Manager for follow-up generation and by Audit & Compliance for the immutable log)
• Segmentation events (consumed by Campaign Manager — see §8.1 for the full contract)
• BookingEligibility change events (consumed by Appointment Manager and Communication Hub)

7. AI Boundaries (Non-Negotiable)

Module does embed AI surfaces indirectly: Aiden and AI Concierge are governed AI channels that interact with Treatment Pipeline Manager via declared integration contracts. The following boundaries apply to all AI surfaces operating against this module.

AI MAY:

• Ask triage questions defined by the Stack and summarise responses into the Lead or Opportunity record
• Recommend pipeline stage transitions for staff review and approval
• Inform a caller or website visitor that booking is permitted, once BookingEligibility = true has been confirmed by querying Treatment Pipeline Manager
• Provide high-level guidance to existing patients (Aiden, website channel only)
• Summarise Lead or Opportunity activity for staff review

AI MAY NOT:

• Create Opportunities directly; only Leads may be created via AI intake
• Set BookingEligibility to any value
• Execute stage transitions
• Complete triage on behalf of a staff member
• Generate or simulate segmentation events
• Bypass governance, audit, or access checks
• Make commitments on behalf of the practice
• Replace required clinical judgement
• Create a second Lead for a ConversationThreadID that already has an active Lead within the same call session

8. Audit & Compliance

8.1 Audit Events

The system MUST log, with actor identity and UTC timestamp, the following events:

• All Lead and Opportunity creation events, including SourceChannel and assigned Stack
• All stage transitions, including trigger mechanism (staff action, ProposalAccepted event, system rule)
• All BookingEligibility changes, including the staff actor who authorised the change
• All booking attempts against a Lead or Opportunity, whether permitted or rejected
• All ProposalAccepted events received from Smart Treatment Proposals and the resulting pipeline action
• All segmentation events emitted to Campaign Manager (see §8.2)
• All AI involvement markers — which AI channel supplied data, what was suggested, and whether it was accepted or rejected by a staff member
• All intake endpoint calls from AI Concierge, including request payload summary and response
• All cross-module events emitted or consumed

8.2 Segmentation Event Contract (Authoritative)

Treatment Pipeline Manager is the authoritative emitter of all segmentation events consumed by Campaign Manager. Campaign Manager MUST NOT subscribe to any pipeline signal not listed here. The full structure, timing, and payload of each event are defined in this section; Campaign Manager MUST rely solely on this contract and MUST NOT infer pipeline state from any other source.

Rules:

• Treatment Pipeline Manager MUST emit each event atomically at the point of the triggering state transition; deferred or batched emission is not permitted.
• Each event MUST include a monotonic EventTimestampUTC and a unique EventID to support idempotent consumption.
• Campaign Manager MUST treat these events as read-only signals; it MUST NOT write back to the pipeline in response.
• No AI channel may generate or simulate a segmentation event.
• Emergency Stack records are excluded from nurture-related segmentation events (LeadNurtureEligible, LeadBecameCold) per §4.3.

8.3 Compliance Requirements

Audit logs MUST be immutable and exportable for inspection. Audit logs MUST be forwarded to the Audit & Compliance module in real time; Treatment Pipeline Manager MUST NOT be the system of record for audit logs — it is the emitter only.

All patient-bound data held in Lead and Opportunity records is subject to GDPR data subject rights. Treatment Pipeline Manager MUST honour deletion and export requests coordinated through the platform's data governance process; the specific retention periods are an open question — see §15.

9. Access Control

Role assignments are governed by Access Manager. Treatment Pipeline Manager enforces the following permissions:

Role names above use the canonical names from Access Manager; any deviation requires an Access Manager spec change, not a Treatment Pipeline Manager change.

MFA is required for any action that sets BookingEligibility = true or closes a record, if the platform's MFA policy is enabled at the practice level.

10. Integration Contracts

10.1 Inbound (Treatment Pipeline Manager consumes from)

10.2 Outbound (Treatment Pipeline Manager emits to)

10.3 AI Concierge Intake Endpoint Contract (Authoritative)

Treatment Pipeline Manager owns and exposes a governed intake endpoint that AI Concierge MUST call to create or link a Lead. This endpoint is the single, authoritative mechanism by which AI Concierge creates or links Lead records; no alternative pathway exists and no duplication is permitted.

Deduplication guarantee. Treatment Pipeline Manager MUST enforce that exactly one active Lead exists per ConversationThreadID within a given call session. If AI Concierge calls the endpoint with a ConversationThreadID for which an active Lead already exists in the same session, Treatment Pipeline Manager MUST return the existing Lead record and MUST NOT create a new one. AI Concierge MUST use the returned LeadID for all subsequent references to that enquiry within the same call.

Request — minimum required fields supplied by AI Concierge:

Response — fields Treatment Pipeline Manager MUST return:

Treatment Pipeline Manager MUST reject any attempt to create a second Lead for the same ConversationThreadID within the same call session and instead return the existing Lead record.

10.4 Unified Conversation Thread Contract

Each Lead and each Opportunity MUST reference exactly one ConversationThreadID owned by Communication Hub. That thread is created at first contact (enquiry intake) and persists as a single, continuous timeline across all channels — WhatsApp, SMS, email, web forms, proposal delivery, and follow-ups — through to conversion or closure.

Treatment Pipeline Manager:

• MUST store the ConversationThreadID as an indexed property on every Lead and Opportunity record.
• MUST store only a reference and read-only summary against this field; it MUST NOT replicate or hold the full conversation record, which is owned exclusively by Communication Hub.
• MUST supply the ConversationThreadID in all operational and segmentation events it emits, so that downstream modules can correlate communications without querying the pipeline directly.
• MUST NOT create or manage conversation threads; Communication Hub is the sole authority for thread lifecycle.

Where a Lead is converted into an Opportunity, the existing ConversationThreadID MUST be carried forward to the resulting Opportunity record so that the unified timeline is unbroken.

10.5 PMS Boundary

(No content captured in original — needs definition.)

11. Integration Summary

• Communication Hub — inbound ConversationThreadID reference at creation; outbound stage-change and notification events; thread lifecycle authority; Treatment Pipeline Manager holds references and read-only summaries only
• AI Concierge — inbound governed Lead intake via sync endpoint; voice triage summaries; deduplication enforced per ConversationThreadID within each call session
• Aiden — inbound Lead creation from website conversational intake
• Appointment Manager — outbound BookingEligibility events; Appointment Manager enforces eligibility before booking
• Campaign Manager — outbound segmentation events (read-only, full contract in §8.2); Campaign Manager MUST NOT write back to pipeline
• Task Manager — outbound next-action and SLA breach triggers for staff follow-up
• Smart Treatment Proposals — inbound ProposalAccepted events (Proposal state machine: Draft → Presented → Explained & Acknowledged → Accepted / Declined / Expired); Treatment Pipeline Manager acts on Accepted transitions only to advance Opportunity stage
• Audit & Compliance — outbound immutable audit event stream
• Access Manager — RBAC enforcement for all create / read / update / approve / close actions

12. Explicit Non-Goals

• Marketing campaign execution — owned by Campaign Manager; Treatment Pipeline Manager supplies segmentation signals only.
• Patient self-service portal — out of scope; Aiden provides guided website intake only.
• Autonomous clinical decisions — no AI surface may make or record a clinical decision via this module.
• Voice call handling infrastructure — owned by AI Concierge; Treatment Pipeline Manager receives the output of calls, not the calls themselves.
• Task reminder delivery — owned by Task Manager; Treatment Pipeline Manager declares next-action requirements and emits events; it does not execute reminders.
• Appointment slot management — owned by Appointment Manager; Treatment Pipeline Manager declares booking eligibility only.
• Conversation thread ownership — owned by Communication Hub; Treatment Pipeline Manager holds references and read-only summaries only.

13. Versioning & Governance

This specification is owned by: (role — needs definition).

Changes to this spec require:

• Review by the Post-MVP module owner
• Impact analysis across all declared related modules (see /propose)
• Version bump (patch / minor / major) according to the change classification

14. Build Contract (Engineering & QA)

14.1 Canonical Data Model

(Detailed schema not captured in original — needs definition by engineering. The following fields are normative minimums derived from §3.)

leads

leads (
  lead_id                UUID PRIMARY KEY,
  source_channel         ENUM('Website','Voice','Form','Campaign','Other') NOT NULL,
  stack                  VARCHAR NOT NULL,
  pipeline_stage         VARCHAR NOT NULL,
  triage_status          VARCHAR,
  booking_eligibility    BOOLEAN NOT NULL DEFAULT false,
  conversation_thread_id VARCHAR NOT NULL,
  owner_role             VARCHAR,
  owner_user_id          UUID,
  created_at             TIMESTAMPTZ NOT NULL,
  audit_trail            JSONB NOT NULL   -- immutable append-only log
)

opportunities

opportunities (
  opportunity_id         UUID PRIMARY KEY,
  patient_id             UUID NOT NULL,
  stack                  VARCHAR NOT NULL,
  pipeline_stage         VARCHAR NOT NULL,
  booking_eligibility    BOOLEAN NOT NULL DEFAULT false,
  estimated_value        NUMERIC,          -- read-only; set by treatment valuation logic
  conversation_thread_id VARCHAR NOT NULL,
  owner_role             VARCHAR,
  owner_user_id          UUID,
  created_at             TIMESTAMPTZ NOT NULL,
  audit_trail            JSONB NOT NULL   -- immutable append-only log
)

These are normative minimum schemas. Engineering may add columns but MUST NOT remove or rename any column listed here without a major version bump to this spec.

14.2 Core Behaviour Rules

Numbered testable behavioural rules:

1. A Lead MUST be created with booking_eligibility = false; the intake endpoint MUST reject any request that supplies booking_eligibility = true.
2. A Lead or Opportunity MUST NOT advance to Booking Permitted stage unless booking_eligibility = true has been explicitly set by an authorised staff action.
3. BookingEligibility MUST only be settable by Treatment Pipeline Manager via an authorised staff action; no AI channel, no Campaign Manager, no Appointment Manager write may alter it.
4. The intake endpoint MUST return the existing Lead record — not create a new one — when a request arrives with a ConversationThreadID that already has an active Lead within the same call session.
5. A ProposalAccepted event received from Smart Treatment Proposals MUST trigger the stage and eligibility logic defined in §3.3.1 within the same transaction; it MUST NOT be processed asynchronously in a way that leaves the Opportunity in an intermediate inconsistent state.
6. All stage transitions MUST be recorded in the AuditTrail with actor identity, UTC timestamp, and trigger mechanism before the transition is committed.
7. Emergency Stack records MUST be flagged for escalation or closure within 72 hours of creation; the system MUST emit a Task Manager trigger when the 72-hour threshold is approached.
8. Each segmentation event listed in §8.2 MUST be emitted atomically at the point of the triggering state transition; it MUST carry a unique EventID and monotonic EventTimestampUTC.
9. A ConversationThreadID MUST be stored as an indexed field on every Lead and Opportunity; queries filtering by ConversationThreadID MUST use this index.
10. AI Concierge's service account MUST NOT be permitted to create Opportunities via any endpoint; attempts MUST be rejected with an explicit error.
11. A finance application submission or assessment event from Smart Treatment Proposals MUST NOT be treated as a ProposalAccepted signal; Treatment Pipeline Manager MUST only advance Opportunity state in response to an explicit ProposalAccepted event with Trigger = ProposalAccepted.
12. Treatment Pipeline Manager MUST NOT store a replica of any Communication Hub conversation record; the conversation_thread_id column is a reference only, and any summary stored alongside it MUST be read-only and derived from a governed query to Communication Hub.

14.3 Configuration Surfaces

14.4 Filtering & Views

The staff UI MUST support the following standard filters and saved views:

• Filter by Stack
• Filter by PipelineStage
• Filter by BookingEligibility (true / false)
• Filter by owner (role or individual user)
• Filter by SourceChannel
• Filter by SLA status (on track / at risk / breached)
• Saved views: "Booking Ready" (all records with BookingEligibility = true not yet at Booked stage), "Emergency" (all open Emergency Stack records), "My Pipeline" (records owned by the current user)

14.5 Module Extension Map

• Additional Stacks may be added via Admin Control Plane without schema changes.
• Additional segmentation events may be added to §8.2 as a minor version bump; Campaign Manager must opt in to new event types explicitly.
• The intake endpoint contract (§10.3) may be extended with additional optional request fields as a minor version bump; required field additions are a major version bump.
• Smart Treatment Proposals integration (§3.3.1) is the first example of a third-party canonical event driving pipeline state; the same pattern may be extended to other proposal or consent modules without breaking this contract, provided they follow the ProposalAccepted event shape and the six-state Proposal state machine described in §3.3.1.

14.6 Acceptance Criteria

The build of Treatment Pipeline Manager is complete when:

• [ ] All canonical objects (Lead, Opportunity) can be created, read, and updated through the API with the minimum required fields enforced
• [ ] State machine transitions enforce all rules in §3.3 (including Emergency Stack 72-hour constraint)
• [ ] BookingEligibility cannot be set by any AI channel, Campaign Manager, or Appointment Manager — negative tests pass
• [ ] The intake endpoint correctly deduplicates Leads by ConversationThreadID within the same call session
• [ ] The ProposalAccepted event handler correctly advances Opportunity stage and eligibility per §3.3.1 — both branches tested; finance application events are confirmed not to trigger advancement (negative test)
• [ ] All segmentation events in §8.2 are emitted atomically with EventID and EventTimestampUTC
• [ ] All integrations in §10 are wired and tested end-to-end
• [ ] AI boundaries in §7 are enforced — negative tests pass for all prohibited actions
• [ ] Audit log captures every event in §8.1 with actor, timestamp, and trigger
• [ ] Access control is enforced per §9 — role-based negative tests pass
• [ ] All non-functional requirements in §15 are met
• [ ] conversation_thread_id is confirmed to store a reference only; no conversation record replication is present — verified by data model review

15. Non-Functional Requirements

The following NFRs scaffold the production-readiness bar for this module. Specific targets are to be confirmed with engineering during the build phase.

• Performance: The intake endpoint (§10.3) MUST respond within 2 seconds under normal load. Pipeline stage transition writes MUST complete within 1 second. Read queries for BookingEligibility by Appointment Manager MUST be served from an indexed path.
• Reliability: Treatment Pipeline Manager MUST be available whenever AI Concierge or Aiden is accepting inbound enquiries. Segmentation event emission MUST be retried with exponential backoff on downstream failure; the pipeline record state MUST NOT be rolled back if an event emission fails after the state transition has committed.
• Scalability: The module MUST support multi-site, multi-practice tenancy. Stack and Stage Template configurations MUST be isolated per practice. ConversationThreadID indexing MUST remain performant as Lead and Opportunity volume scales.
• Security: All patient-bound data MUST be encrypted at rest and in transit. The AI Concierge service account MUST be a scoped service credential with no broader write permissions than the intake endpoint requires. Secrets (service credentials) MUST be managed via the platform's secrets management facility, not hardcoded.
• Privacy: Lead and Opportunity records containing patient-identifiable data are subject to GDPR. The module MUST support data subject export and deletion requests coordinated through the platform's data governance process. Retention periods are an open question — see §16.
• Observability: The module MUST export metrics for pipeline throughput (Leads and Opportunities created per period), stage transition latency, BookingEligibility conversion rate per Stack, segmentation event emission success/failure rate, and intake endpoint error rate. Structured logs MUST include LeadID / OpportunityID, Stack, and SourceChannel as indexed fields for tracing.
• Accessibility: Staff-facing UI surfaces MUST meet WCAG 2.1 AA.

16. Open Questions

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

1. Retention periods: What are the data retention periods for Lead and Opportunity records containing patient-identifiable data? This determines GDPR deletion scheduling and archive policy. (Implicit in §11 audit/compliance content — no decision captured.)
2. PMS boundary: What does the Practice Management System own versus Treatment Pipeline Manager, and what is the integration contract at that boundary? (Acknowledged as a boundary in the original but left undefined — §10.5.)
3. Spec ownership role: Which named role owns this specification and has authority to approve version bumps? (Left as a placeholder in §13.)
4. Stack-level inactivity thresholds: What are the default inactivity thresholds (in hours/days) that trigger the LeadBecameCold segmentation event for each Stack? Are these configurable at practice level or set centrally? (Referenced in §8.2 as "Stack-defined inactivity threshold" but no values or configuration authority specified.)
5. EstimatedValue derivation: How is EstimatedValue on an Opportunity calculated or set, and which module is authoritative for that value? The original marks it read-only but does not define its source. (Implicit in §3.2.)
6. Aiden intake endpoint contract: The spec defines the AI Concierge intake endpoint in detail (§10.3) but does not define an equivalent governed intake contract for Aiden (website). Should Aiden use the same endpoint with a different SourceChannel value, or is a separate contract required? (Implicit gap between §6 and §10.3.)