Blueprint vs v6.2 — Gap Audit¶

Audit generated 2026-06-18 by automated agent comparing docs/specs/product-functional-blueprint.md against the v6.2 implementation at HEAD of branch docs/product-blueprint-v1. Reviewed + corrected 2026-06-19 (internal code-reviewer + architecture-reviewer fixes: blueprint Stage-4 section-numbering bugs and the duplicate 3.4.2 heading; audit anchor slug normalisation; C-4 coordinator-portal repo path correction; I-6 prompt file/line range correction).

Executive Summary¶

• The blueprint frames Curaway as an 8-stage, 10-intelligence-layer "Recovery Intelligence Platform" delivering a Comprehensive Mobility Restoration Program (CMRP) for GCC → India orthopaedic patients (§1.1, §2.2). v6.2 today implements a single conversational intake coordinator with SOP-contract-guided field collection — roughly Stage 1 (Discovery & Trust) + a slice of Stage 2 (Comprehensive Patient Understanding). Stages 3–8 and seven of ten intelligence layers are unimplemented.
• The blueprint's central artifact framework is absent from code. Patient Engagement Record (Stage 1), Comprehensive Patient Understanding Record (Stage 2), Shared Clinical Decision Record (Stage 3), Comprehensive Mobility Restoration Plan (Stage 4), Treatment Readiness Package (Stage 5), Treatment & Early Recovery Record (Stage 6), Mobility Restoration & Recovery Record (Stage 7), and Longitudinal Recovery Record (Stage 8) are all named first-class outputs in the blueprint but have no equivalent table, JSON contract, or service in the v6.2 implementation. Case.consolidated_state is a flat per-case JSONB, not a staged artifact chain.
• The Human Recovery Digital Twin (HRDT) — described in the blueprint as the longitudinal data backbone that every stage reads and enriches (Stage 1 §2.4.9 through Stage 8 §2.11.9) — has zero references in v6.2 prompts, services, or models. grep -ri "HRDT|Recovery Intelligence|Trust Intelligence|Explainability Intelligence" config/prompts/ returns no hits.
• Geographic and clinical scope is narrower than blueprint declares. Blueprint MVP is GCC origin → India destination, orthopaedic-only (§1.4, §1.5). Today's v6.2 prompts target US/UK/UAE/Ethiopia/Saudi/India and cover oncology, transplant, pediatric, rare-disease in the HARD BAN ("never reject based on procedure/specialty"). This is a deliberate v6.2 disagreement with blueprint scope; flagged below as Out-of-Scope/Disagreement.
• Strengths of v6.2 that the blueprint codifies as required. Voice & empathy (§1.7 Empathy/Trust), clinician-oversight ban on AI diagnosis (§2.4.11), document-trust framing, A3/A4 grave-disclosure rules, axis discipline, and anti-hallucination on tool-fire claims are all robustly implemented and exceed blueprint specificity. Care Coordinator + Orthopaedic Specialist human-in-loop is governance-correct in prompts but has no workspace UI yet.

Top 10 Action Items¶

Ranked by blueprint criticality × implementation lift. "Lift" is qualitative: S=small (prompt/yaml edit), M=medium (new service or table), L=large (new subsystem).

Critical Gaps¶

These are blueprint-stated MVP requirements that v6.2 does not yet implement at all.

C-1 — Human Recovery Digital Twin (HRDT) is unnamed and partially built¶

• What the blueprint requires. "Curaway.AI Intelligence Platform ... initiates the Human Recovery Digital Twin (HRDT) ... creating the initial longitudinal patient profile by capturing demographic, clinical, behavioral, emotional, and contextual information." (§2.4.9). HRDT is then enriched at every subsequent stage (§2.5.9 → §2.11.9) and is the named integration target of every Recovery Intelligence layer.
• What v6.2 has today. Case.consolidated_state (app/models/case.py:144, ADR-0030) is a per-case JSONB column that accumulates structured intake data. It is functionally HRDT-shaped (demographic + clinical + emotional + contextual) but is never called HRDT in code, prompts, or docs. grep -ri "HRDT" config/prompts/ app/ returns zero hits.
• Gap size. Naming + scope. The data backbone exists; the framing, longitudinal-across-cases linkage, and "behavioral / emotional" dimensions are partial.
• Suggested next step. ADR adopting HRDT as the canonical product name for consolidated_state + a follow-up issue to extend it to a patient-scoped (not case-scoped) record so multiple cases for the same patient share an HRDT.

C-2 — Eight named Stage Output Artifacts are not implemented¶

• What the blueprint requires. Every stage in §2 has a Stage Output Artifact section listing a named, structured record consumed by the next stage. The chain is: Patient Engagement Record → CPUR → SCDR → CMRP → Treatment Readiness Package → TERR → MRRR → LRR (§3.2 Business Capability Evolution).
• What v6.2 has today. Only consolidated_state (case-scoped) and the SOP must_collect field set. No table or projection corresponds to PER/CPUR/SCDR/CMRP/TRP/TERR/MRRR/LRR. The chat handoff to matching is direct from consolidated_state to matcher input, with no clinician-validated CPUR in between.
• Gap size. Foundational. The blueprint's traceability model assumes these are first-class artifacts; today they are implicit in code paths and never surfaced to clinicians.
• Suggested next step. PRD for "Stage Output Artifacts as first-class records" — start with Patient Engagement Record + CPUR (the only two within the v6.2-implemented stages). Defer SCDR onward to Stage 3 spec.

C-3 — Stage 3 (Shared Clinical Decision Making) is absent¶

• What the blueprint requires. "Curaway.AI facilitates a collaborative decision-making process where clinical evidence, Recovery Intelligence, patient goals, functional expectations, emotional readiness, cultural values, family perspectives, and financial considerations are brought together transparently." (§2.6.1). Output: Shared Clinical Decision Record. Clinician approves treatment recommendation; consent is captured.
• What v6.2 has today. The matching engine produces ranked provider options; there is no UI/workflow for clinician sign-off, no Shared Decision Record, no informed-consent capture tied to the treatment choice. The v6.2 prompt hard-bans the AI from recommending a procedure (correct per blueprint §2.6.11) — but provides no human surface to make the decision.
• Gap size. Entire stage missing.
• Suggested next step. Stage 3 spec authored as PRD docs/specs/stage-3-shared-decision.md defining the clinician workspace, treatment-option presentation, and SCDR schema.

C-4 — Care Coordinator workspace per stage¶

• What the blueprint requires. Care Coordinator is a primary actor in every stage (§2.4.5 → §2.11.5). Their MVP-required capabilities (Care Coordinator Workspace) are listed in §2.4.12, §2.5.12, §2.6.12, §2.7.12, §2.8.12, §2.9.12, §2.10.12.
• What v6.2 has today. A coordinator-portal app shell exists in the separate frontend repo (curaway-ai/curaway-frontend, not in this backend repo's tree). From the backend side there is no stage-aware inbox, no SLA timer, no escalation queue from the AI to a coordinator, no presence indicator. The prompts mention escalation but the orchestration target is undefined. The frontend repo's workspace UI maturity was not assessed in this pass and should be cross-checked before scoping.
• Gap size. Significant feature gap.
• Suggested next step. Coordinator workspace MVP spec: stage-aware case inbox, escalation queue from AI, SLA timers.

C-5 — Stage 1 trust-building telemetry / Trust Intelligence¶

• What the blueprint requires. "Trust Intelligence | Continuously evaluates patient confidence, engagement, emotional reassurance, and readiness to continue the journey | Trust & Engagement Profile" (§2.4.9 row 8).
• What v6.2 has today. The prompt enforces empathy through voice rules and emotional-context-aware tone shaping. There is no quantified Trust signal — no engagement-readiness score, no Trust profile field in consolidated_state, no telemetry to the coordinator dashboard.
• Gap size. Behavioural signal partly implemented (the LLM reads emotional state); structured Trust Profile output absent.
• Suggested next step. Add consolidated_state.trust_profile with engagement_readiness, confidence_band, escalation_recommended fields derived from the existing emotional-context classifier; surface to coordinator workspace.

C-6 — Explainability Intelligence as a layer¶

• What the blueprint requires. "Explainability Intelligence | Explains Curaway's role, AI capabilities, privacy commitments, care process, and next steps in a transparent and understandable manner" (§2.4.9 row 9).
• What v6.2 has today. FIRST-TURN PLATFORM ROLE DISCLOSURE in conversation_v6_2.yaml lines 154–188 satisfies part of this. Privacy commitments are referenced in PROCESS FACTS. But blueprint frames Explainability as a continuous layer providing rationale for every AI suggestion — there is no per-recommendation explanation field surfaced to patients beyond what the LLM naturally produces.
• Gap size. Partial; informal.
• Suggested next step. Define explainability as a structured field on matcher output (already exists for matching) and extend to every system event the patient sees.

C-7 — Governance Intelligence as a runtime layer¶

• What the blueprint requires. "Governance Intelligence | Validates consent, privacy preferences, jurisdictional requirements, and governance policies before progressing further" (§2.4.9 row 10).
• What v6.2 has today. Static governance lives in voice_rules.yaml, response_policy.py, tests/test_no_medical_advice.py, and the SOP _schema.md's clinical_safety_rules. Runtime governance enforcement (jurisdictional / consent-state gating per turn) is not centralized — it's spread across multiple Depends() decorators and the consent service.
• Gap size. Static rule enforcement is strong; runtime per-turn governance gate is implicit.
• Suggested next step. Decide whether Governance Intelligence is the SOPContract.safety_rules + voice_rules + consent_service (already 3 things), or whether to formalize as a single app/services/governance_intelligence.py facade.

C-8 — Recovery Intelligence Engine (the "Recovery Reality" model)¶

• What the blueprint requires. Recovery Intelligence is named in §2.2 design principles, §3.4.1 Platform Capability Evolution ("Recovery Intelligence Engine: Foundation=Recovery observations → MVP=Personalized recovery reasoning → Future=Predictive recovery intelligence"), and recurs as a primary output in every stage's Intelligence Layer Activation table. The blueprint expects structured Recovery Observations, Recovery States, and Recovery Intelligence objects per stage.
• What v6.2 has today. No Recovery Observation / Recovery State / Recovery Intelligence data model. The closest analog is consolidated_state.mobility_conditioning from TKR SOP layer — a field set, not a structured Recovery Intelligence record.
• Gap size. Foundational data-model gap.
• Suggested next step. ADR proposing Recovery Reality data model (Observations / States / Intelligence triple) as a layer over consolidated_state; defer Recovery Intelligence Engine reasoning (the "personalized recovery reasoning" verb) to a follow-up.

Important Gaps¶

These are blueprint requirements that have a partial implementation today but need elaboration.

I-1 — DIL (Dynamic Interaction Logic) as a named platform capability¶

• Gap size. Naming + missing evaluators.
• Suggested next step. Adopt DIL as a name for the v6.2 dispatcher loop; file follow-ups for the missing evaluators (language detection, family involvement, governance progression).

I-2 — Multilingual / Arabic-first communication¶

• Gap size. Major. Blueprint MVP requires Arabic; v6.2 is English-only.
• Suggested next step. i18n track (#423) prioritized — Arabic prompt variants + bilingual response policy.

I-3 — Family / decision-maker participation¶

• Gap size. Behavioural acknowledgement strong; data model + multi-party UX absent.
• Suggested next step. Spec: "Case participants" model with role enum (patient / caregiver / decision-maker / family-observer).

I-4 — Cultural preferences (religion, dietary, gender preferences)¶

• Gap size. Important data gap for blueprint-stated GCC focus.
• Suggested next step. Add consolidated_state.cultural_preferences schema with surgeon_gender, language, religious_observance, dietary.

I-5 — Financial Understanding (budget, insurance, affordability)¶

• Gap size. Field-level support yes, intelligence layer absent.
• Suggested next step. Spec for financial-readiness intelligence (rule-based v0: budget × provider-quote distribution).

I-6 — Records / Documents upload + extraction pipeline¶

• Gap size. Foundation laid; clinical summarization quality + structured imaging extraction need work.
• Suggested next step. Audit of document_interpreter coverage vs. blueprint CPUR-contents list.

I-7 — Cross-border logistics (visa, travel, accommodation)¶

• Gap size. Entire Stage 5 deferred.
• Suggested next step. Stage 5 spec or explicit deferred-roadmap entry.

I-8 — Audit & Traceability surface¶

• Gap size. Backend logs exist; user-facing audit surface absent.
• Suggested next step. Stage-aware audit timeline UI in coordinator workspace (links to existing audit_log records).

I-9 — Consent Management (immutable, jurisdictional, per-stage)¶

• Gap size. Backbone solid; stage-keyed consent not modeled.
• Suggested next step. Add consent_type enum to capture stage-specific consents.

I-10 — Notification / Reminder service (per-stage)¶

• Gap size. Infrastructure available; per-stage application missing.
• Suggested next step. Reuse transport-nudge chain pattern for clinical-readiness reminders in Stage 5.

I-11 — Per-procedure SOP coverage breadth¶

• Gap size. Breadth is mostly there for ortho MVP; clinical sign-off is the gate. Nephrology is out of blueprint scope (not orthopaedic) — flag for removal or move under explicit scope-extension.
• Suggested next step. Sequence Dr. Naidu reviews. Decide nephrology fate.

I-12 — Patient Engagement Record (Stage 1 output)¶

• Blueprint requires. A Patient Engagement Record consumed by Stage 2, with fields like Initial Recovery Baseline, Initial HRDT, Conversation history, Coordinator assignment (§2.4.15).
• v6.2 has. Case.consolidated_state accumulates intake. The "engagement" framing — that this is the trust-establishment artifact, not just a clinical dossier — is absent. There is no separate Initial Recovery Baseline.
• Gap size. Definitional.
• Suggested next step. Schema in app/schemas/patient_engagement_record.py projecting from consolidated_state + trust_profile + conversation_history.

Aligned (no gap)¶

Areas where v6.2 already meets or exceeds blueprint specificity. Listed briefly.

Deferred by Blueprint¶

Items the blueprint explicitly defers to "Future Evolution" or "Later Phases" — not gaps, listed here for clarity so they aren't accidentally counted as gaps in future audits.

Out-of-Scope / Disagreement¶

Areas where v6.2 has made a deliberate choice that diverges from the blueprint. These need reconciliation — pick the prompt or pick the blueprint, but don't run both forever.

D-1 — Patient origin geography¶

• Blueprint says. Patient Origin: GCC (UAE, Saudi, Qatar, Oman, Kuwait, Bahrain). India domestic and other regions are explicitly "Later Phases" (§1.4).
• v6.2 says. "Serves US, UK, UAE, Ethiopia, Saudi, India, etc." (conversation_v6_2.yaml line 100). Test personae include Ethiopia (Meskerem), UAE (Maria, Dubai). CROSS-CULTURAL CUES has US/UK + Ethiopian register hints.
• Why. v6.2 was built to serve the actual demo / live-test cohort, which is broader than the blueprint MVP.
• Reconciliation suggestion. Either tighten v6.2 to GCC origin or update blueprint §1.4 to reflect actual MVP scope.

D-2 — Clinical scope (ortho only vs broader)¶

• Blueprint says. Orthopaedic conditions only for MVP (§1.5). Oncology, cardiology, neurology, paediatric oncology explicitly out of MVP.
• v6.2 says. Hard bans against "we don't handle that" rejection for oncology, pediatric, transplants, rare conditions (conversation_v6_2.yaml line 411). Test fixtures include Maria (breast IDC, oncology) and Abdul Moeed (pediatric leukaemia). DISEASE-SPECIFIC QUESTION PRIORITY block targets pediatric leukaemia openers — non-ortho.
• Why. Per feedback_mock_sops_acceptable_in_prod.md and live-testing strategy: SD has accepted that live patient interactions span beyond ortho.
• Reconciliation suggestion. Decide whether blueprint §1.5 expands MVP scope to include oncology/pediatric, or whether v6.2 prompts should restore graceful-scope rejection with "we'll refer you" framing. Today the prompts promise a level of cross-specialty handling that the matcher cannot deliver, which is itself a HARD BAN violation source. See Action Item #9.

D-3 — AI as "AI Companion" terminology¶

• Blueprint says. "AI Companion" is the named role in Primary Actors (§2.4.5, §2.5.4, §2.6.5, §2.7.5, §2.8.5, §2.9.5, §2.10.5, §2.11.5).
• v6.2 says. "Curaway's international patient coordinator" or "AI-powered care coordinator" (conversation_v6_2.yaml lines 82, 178). Explicitly avoids "AI care coordinator" robotic phrasing (line 185).
• Why. Voice judgment — "AI Companion" reads too marketing-y when used inline in chat.
• Reconciliation suggestion. Keep v6.2 wording; clarify blueprint's "AI Companion" is the internal product taxonomy, not the user-facing label. Add a note to blueprint §2.4.5 to that effect.

D-4 — Single conversational agent vs. multi-agent architecture¶

• Blueprint says. Ten distinct "Intelligence Layers" — Dynamic Interaction, Clinical, Provider, Decision, Care Coordination, Recovery, HRDT, Trust, Explainability, Governance — each with a distinct purpose per stage.
• v6.2 says. ONE LLM call per turn, guided by SOPContract, emits both reply + StateDelta. The "layers" are encoded in the system prompt + the contract — not as separate services or model calls.
• Why. ADR-0030: latency, cost, and state-divergence concerns. Multi-agent fan-out from v4/v6 was deliberately collapsed to one call.
• Reconciliation suggestion. This is the correct engineering call. Blueprint §3.4.1 already allows "Foundation → MVP → Future" evolution per layer — frame each layer as "implemented within the v6.2 single-call architecture" so the blueprint's layer taxonomy is preserved as the product specification even though the implementation collapses them. No code change; ADR cross-reference + blueprint annotation.

D-5 — Stages flat list vs. blueprint's 8 sequential stages¶

• Blueprint says. 8 mutually-exclusive, sequential stages: Discovery → Understanding → Decision → Planning → Readiness → Treatment → Recovery → Longitudinal.
• v6.2 says. stages.yaml defines ~12 mutually-exclusive intake-stage sub-stages (discovery, procedure_identification, records_collection, match_review, etc.) — all within Stage 1+2 of the blueprint. The v6.2-flexible architecture goes further: ADR-0030 says "there is no stage in v6.2; SOPContract IS the layer."
• Why. v6.2 chose a SOP-contract-as-layer model that doesn't map cleanly onto blueprint stages.
• Reconciliation suggestion. Document the mapping in docs/specs/blueprint-stage-to-v6_2-layer-mapping.md. Blueprint Stage 1 ≈ v6.2 discovery + procedure_identification + records_collection. Blueprint Stage 2 ≈ v6.2 clinical_context layer. Etc.

D-6 — DIL as one continuous orchestration vs. v6.2's per-turn StateDelta¶

• Blueprint says. DIL "continuously evaluates" 15+ variables per turn (concerns, language, family, trust, governance, readiness). The framing suggests an orchestration engine.
• v6.2 says. Per-turn LLM call produces a StateDelta; emotional context is computed; no separate "DIL engine" exists.
• Why. Same as D-4 — collapsed by design.
• Reconciliation suggestion. None needed; treat DIL as the behavioural specification of the v6.2 dispatch loop. Adopt the DIL name in code comments.

Methodology¶

Sources read¶

• Blueprint: docs/specs/product-functional-blueprint.md (3406 lines) — sampled comprehensively: §1 Product Definition (lines 1–140), §2 CMRP overview (140–200), §2.4–§2.11 Stages 1–8 (200–3200, sampled with focus on Stage 1 §2.4, Stage 2 §2.5, Stage 3 §2.6, Stage 4 §2.7, Stage 6 §2.9 Intelligence Layer Activation, Stage 7 §2.10 outputs, Stage 8 §2.11), §3 MVP Implementation (3200–end).
• v6.2 implementation:
• config/prompts/base/conversation_v6.yaml (1031 lines, comprehensive read)
• config/prompts/base/conversation_v6_2.yaml (602 lines, full read)
• config/prompts/stages.yaml (sampled lines 1–120; 39KB file)
• config/voice_rules.yaml (size confirmed, not deeply parsed — known good)
• config/prompts/sops/_schema.md (full read)
• config/prompts/sops/tkr.yaml (sampled, identified MOCK status)
• docs/specs/conversation-v6-feature.md (sampled §0–§1.4)
• docs/adr/0030-conversation-v6-2-flexible-architecture.md (full read)
• app/services/sop_contract.py (signatures only — RequiredDataEntry, RequiredDocumentEntry, ClinicalSafetyRule, etc.)
• app/agents/triage_v6_2/dispatch.py (signatures only — StateDelta, run_triage_turn_v6_2)
• app/services/consolidated_state_writer.py (signatures only)
• tests/fixtures/v6_compliance/ (file listing only — 14 fixtures)
• Reference rules: CLAUDE.md, .claude/rules/coding-principles.md, .claude/rules/definition-of-done.md, .claude/rules/backend-agents.md, .claude/rules/prompts.md (auto-loaded by harness)

Coverage caveats¶

• §2.7 (Stage 4 — CMRP Planning), §2.8 (Stage 5 — Treatment Readiness), §2.10 (Stage 7 — Mobility Restoration), §2.11 (Stage 8 — Longitudinal Recovery) were read in headline form only. The pattern (each stage = Purpose + Objectives + Intelligence Layer Activation + Governance + Capabilities + Artifact) is consistent across stages, so coverage is representative.
• Frontend implementation was not surveyed in this pass beyond a directory check. The coordinator-portal app shell exists; per-stage workspace UI assessment is a follow-up.
• ROAS/RIOS Blueprint, Platform Blueprint, Metadata Dictionary, and Unified Governance Framework (referenced in §3.6 Engineering Navigation Guide) were not in scope; gaps against those documents may exist on top of the gaps named here.

Assessment heuristic¶

For each blueprint capability/artifact/layer, the auditor asked three questions: 1. Is the name present in code, prompts, or docs? (e.g., "HRDT", "Care Coordinator workspace", "Patient Engagement Record") 2. Is the behaviour present without the name? (e.g., consolidated_state is HRDT-shaped) 3. Is the output artifact materialized as a schema, table, or API surface that downstream stages can consume?

A gap was flagged Critical when (3) returned no, Important when (1) returned no but (2) returned yes, and Aligned when all three returned yes.

What was not graded¶

• Code quality of the v6.2 implementation
• Performance / cost (blueprint is silent on these)
• Test coverage breadth (blueprint is silent)
• Security posture beyond what blueprint names (consent + audit + governance — assessed as Aligned)

Confidence¶

• High confidence on Critical Gaps C-1, C-2, C-3, C-4, C-5 — these are structural absences confirmed by grep + directory listings.
• Medium confidence on Important Gaps I-1 through I-12 — these required cross-referencing blueprint language against partial code presence; reasonable disagreement possible on whether the v6.2 partial implementation satisfies the blueprint intent.
• Disagreements D-1 through D-6 are statements of fact about explicit divergence — not interpretive.

End of audit.