conversation_v6 — Feature Spec¶

Status: Draft revision 6 (2026-05-12) — DoD compliance review complete. All 24 DoD sections covered; final 3 gaps closed in rev 6 (PostHog analytics events for view_ cards, placeholder-page mobile/a11y disclaimer, tiktoken dev-only dependency justification). Spec is final for Phase 0 kickoff conditional on the 3 blocking companion docs being authored before their respective phase starts (truth table → Phase 1, rule-location map → Phase 2a, stages-extractors matrix → Phase 2b). Supersedes: #783 (v5 alone), #834 (recovery addendum refactor). Preceded by: #835 — v4 hot-fix for P0s #642 + #743 (ships 2-3 days before v6 Phase 0). Tracking issue: #836. Land target:* Flagsmith-gated rollout via new prompt_arch=v5|v6 flag, default v5 until validation passes.

Don't merge any of this without clinical review. v6 absorbs all six v5 rule additions (2.1-2.6) into a restructured injection model. Per feedback_agent_chat_sacrosanct.md: every prompt change requires 3 baseline + 3 after conversations on each of 3 personas. v6 extends the v5 spec's 8-axis scoring to 9 axes (adds stage-transition smoothness).

0. Why v6 exists¶

Two motivations forced a decision on 2026-05-12:

1. The existing v5 work (#783) added 6 prompt rules to fix 7 logged P0/P1/P2 bugs but kept the v4 architecture (phase × layer composition, two parallel injection taxonomies, addendum-as-third-mechanism).
2. A separate brainstorm surfaced that the v4 architecture has structural drag: two overlapping concepts (phase / layer), three injection mechanisms (phase context / layer context / addendum), full base-prompt cloning per version (v1 → v4.1 → planned v5), and ~35-40% redundant tokens per turn.

Doing both as a single release (rules + architecture) avoids: - Two clinical advisor review cycles - Two validation cycles (3+3 × 3 personas, twice) - Lockstep PRs during a v5-then-v6 transition window - Rule content being written twice (once into conversation_v5.yaml, once when restructuring into stages.yaml)

The cost is delay: the 5 non-critical v5 rules wait ~3 weeks longer than they would in a v5-then-v6 split. The two P0s (#642, #743) ship sooner via the #835 hot-fix.

This spec is not a wholesale wording rewrite. Voice rules, clinical-safety bans, and emergent v4 Path-A wins from docs/specs/conversation-v5-feature.md §1 carry forward verbatim. v6 is restructure + rule additions, not "rewrite the prompt."

1. Scope¶

1.1 In scope¶

1.2 Out of scope (deferred)¶

• ICD-10 preference logic in extractor pipeline (per v5 spec arch-review A-1)
• Multilingual prompt variants (post-i18n track, #423)
• Schema field document_findings_disclosed: bool (reserved for v7)
• LiteLLM evaluation as gateway substrate (#510)
• New rich_content card types beyond view_payments, view_summary, view_consultations, stage_indicator — additions go in v7+
• Replacing Anthropic prompt caching with a different mechanism — keep as-is

1.3 Architectural wins from v4 to preserve¶

Per v5 spec §1.3, all preserved:

• Additive phase × layer composition is replaced by stages (intentional change) but the emergent behaviors it produced (one-axis-per-turn, layered context discipline) become explicit rules in stages.yaml
• Shared conversation_v4_streamer module — keep, rename to conversation_streamer (version-agnostic). Rename ripple (Phase 1 task list, COMPLETE list): update imports at app/agents/triage_agent.py:33 + app/agents/conversation_prompt.py:244, 274, 312, 447; update log-string literals at app/agents/conversation_v4_streamer.py:235, 352; rename Langfuse trace tag agent:llm_conversation.streaming → agent:conversation.streaming with Grafana/Metabase dashboard tag-union migration (old + new for 30 days, then drop old). Re-export shim (NEW rev 5 per arch review): keep app/agents/conversation_v4_streamer.py as a 5-line shim re-exporting symbols from the renamed module for two weeks post-rename. Catches any missed call site without breaking v4 traffic. Delete the shim in a follow-up PR after 14 calendar days + Langfuse confirmation that the old tag stops appearing.
• Shared conversation_v4_parser module — keep, rename to conversation_parser. Parser imports are at conversation_prompt.py:274, 312, 447 + triage_agent.py:32. Same rename-ripple + re-export-shim discipline.
• Layer extractors (5 parallel sub-nodes) — keep architecture, update prompt content
• JSON response schema with extracted_data — keep verbatim from v4/v4.1
• WS event lifecycle: batch_complete + findings_incorporated — keep; PR #805 adds message_complete — preserve.

1.4 JSON output strict-compliance preservation (NEW per SD callout 2026-05-12)¶

A run of v4 hardening PRs in early May 2026 closed real production parse failures. v6 inherits all of them — the rename in §1.3 is rename + test-suite inheritance, not "rename + reimplement." The Phase 1 implementer MUST NOT touch the parsing or prefill logic; only the module name + Langfuse tag changes.

Hardenings that MUST stay intact:

Existing reference memory (from reference_v4_parser_strict_false.md in SD's session memory): parse_v4_response MUST use json.loads(strict=False) — model emits literal newlines in JSON strings. This is one of the failure modes #800 + #803 address. Preserved.

Intake prompts (config/prompts/base/intake_v1.yaml:17, intake_v2.yaml:11) — both contain "Return ONLY valid JSON" rules and are loaded by app/agents/prompts/intake.py. v6 does NOT touch these; they remain on their own versioning track. v6 stage profiles that invoke intake extractors hand off to this unchanged code path.

JSON envelope schema (the {{"message": "markdown response", "extracted_data": {...}, ...}} block at conversation_v4.yaml:184 / conversation_v4.1.yaml:186 — verified identical between v4 and v4.1) is absorbed verbatim into conversation_v6.yaml. Added to the §4 verbatim-preservation fixture list: - tests/test_v5_rule_verbatim_preservation.py extends to assert the envelope schema (with extracted_data, detected_comorbidities, phase_complete, suggested_next, missing_critical_info fields) appears unchanged in conversation_v6.yaml.

Phase 1 CI gate (CORRECTED rev 5 per arch review — sequencing was wrong; rename happens in Phase 1, not Phase 0): every test listed in the §1.4 table above runs against the renamed v6 modules (conversation_streamer.py, conversation_parser.py) AFTER the rename PR — not just against the legacy v4 module names. Fails build if renamed modules don't carry the hardenings forward. Phase 0 (harness build) precedes the rename; the gate activates the moment the rename PR opens.

Phase 1 reviewer checklist (new mandatory check): every PR that renames conversation_v4_streamer.py → conversation_streamer.py (or parser equivalent) MUST cite the 7 PRs above and show the test inheritance in the PR description. Auto-enforced via PR template + lint script reading docs/specs/conversation-v6-feature.md §1.4 table.

2. Architecture¶

2.1 File layout¶

config/prompts/
├── base/
│   └── conversation_v6.yaml          ← ONE base file; absorbs v5 rule additions
├── stages.yaml                       ← NEW: flat mutually-exclusive stage list
├── knowledge/                        ← NEW: optional patient-state-gated addendums
│   ├── financial_options.yaml
│   ├── post_travel_logistics.yaml
│   ├── procedure_clinical_facts/
│   │   ├── knee_replacement.yaml
│   │   ├── hip_replacement.yaml
│   │   └── bariatric.yaml
│   └── insurance_handling.yaml
├── examples/                         ← UNCHANGED (loaded by examples_variant flag)
├── layer_contexts/                   ← KEPT until v5 traffic = 0 then deleted
└── phase_contexts/                   ← KEPT until v5 traffic = 0 then deleted

2.2 Stage profiles (stages.yaml)¶

Each stage: - Has a unique id, a stated goal, guidance text (300-500 tokens), a list of cards_to_use, advance_when predicates, do_not constraints. - Is mutually exclusive — at any moment, exactly one stage is active per case. - Maps deterministically from Case.layer_state + WorkflowState — app/services/stage_resolver.py (new).

Proposed stages (10):

support exists as the safety net — if stage_resolver can't determine a stage (e.g., new case, malformed state), the LLM gets support and the prompt collapses to base + patient_context only.

2.3 Knowledge addendums (knowledge/*.yaml)¶

Triggered by patient context, not stage:

Cap: max 1 addendum per turn (REVISED rev 3 — was 2; reduced to fit Anthropic 4-cache-breakpoint limit per §2.5). If >1 match, pick by priority: field; clinical-safety addendums MUST be ordered above commercial addendums in the priority map (e.g., procedure_clinical_facts priority > insurance_handling priority). See §9 risk row for the clinical-suppression mitigation.

Each addendum is 200-500 tokens. Loaded with cache-control markers like the base prompt so they participate in Anthropic prompt caching.

2.4 Patient context block (app/agents/patient_context_builder.py)¶

REVISED 2026-05-12 per code-reviewer + compliance review: - Domain placement: app/agents/, NOT app/services/. Justification: this is a prompt-assembly concern called only by LLM agents — placing it in services/ would tempt non-agent code to call it (cross-domain leakage). Per backend-services.md "no cross-domain internal imports." - Inter-domain contract: the builder accepts a typed dataclass per source domain — CaseSummary, FhirObservationSummary, DocumentManifest, WorkflowSnapshot, PatientPreferences. Each comes from its owning domain's service through a deliberately narrow read API. The builder NEVER imports repositories directly; it consumes dataclasses. - Dataclass-producing services MUST use BaseRepository (REVISED rev 3 per compliance review): the service functions that emit these dataclasses MUST go through BaseRepository._scoped_query(tenant_id) per backend-services.md "Data Access" rules. Raw SQL or unscoped queries are prohibited. CI gate: tests/test_route_access_scanner.py already enforces tenant scoping on routes; extend it to scan the dataclass-producing services for raw-query escapes. - Tenant assertion: every input dataclass MUST carry tenant_id. The builder asserts tenant_id matches across inputs and raises TenantIsolationViolation (existing exception in app/repositories/base.py) if any input has None or mismatched tenant. - PHI handling: the assembled block is request-scoped only — never logged, never sent to Langfuse trace metadata, never emitted to Telegram alerts. Per CLAUDE.md ground rule #3 + clinical.md. The Langfuse trace receives only case_id + tenant_id tags; the assembled block lives in the request body only. - GDPR Article 17: app/services/data_subject_handler.py (REVISED rev 3 — correct path, no gdpr/ subdir) already cascades on case erasure. The new chat:patient_ctx:{tenant_id}:{case_id} cache key is added to its purge list (§3.3).

Single canonical structured block built once per request from DB:

Case: CRW-1234
Procedure: Knee replacement (confirmed, ICD-10: M17.11)
Documents on file (3): HbA1c lab (2026-04-12), X-ray right knee (2026-04-08), consultation note (2026-04-10)
Documents pending (1): BMI screening — patient declined to share
Journey: 60% complete · Next milestone: Match review · Last active: 2026-05-11
Country preferences: India, Turkey
Budget tier: $$ (8-15k USD)
Language: English
Companion: Spouse (age 52, declared)
Insurance: Self-pay

Replaces ad-hoc patient context injection across conversation_prompt.py, extractor prompts, and FHIR summaries. Cached in Redis under chat:patient_ctx:{tenant_id}:{case_id} with 60s TTL (mirrors existing patient_state cache).

2.5 Composition order (v6 turn)¶

HARD CONSTRAINT — REVISED rev 3 per impl review: Anthropic supports a maximum of 4 cache_control breakpoints per request. v6 uses only 3 of the 4 available markers and leaves history uncached (history mutates every turn — a cache marker on the tail would be invalidated on the next turn anyway). Saves one cache breakpoint and matches Anthropic's "longest stable prefix" doctrine.

[CACHE SEG 1]  base/conversation_v6.yaml — system + forbidden phrases + JSON schema   ← cache_control: ephemeral (marker 1)
[CACHE SEG 2]  patient_context + stage_active.guidance (concatenated)                  ← cache_control: ephemeral (marker 2)
[CACHE SEG 3]  knowledge addendum (max 1 per turn — see §2.3)                          ← cache_control: ephemeral (marker 3)
[UNCACHED]     {conversation history — last 30 turns} + {latest user turn}             ← no cache_control marker

Why this stays within Anthropic limits: - 3 cache breakpoints used (1 marker headroom for future use) - Knowledge addendums capped at 1 per turn (consistent with §2.3, §3.9, §9). If multiple match patient state, the highest-priority one wins; clinical-safety addendums ordered above commercial ones per §2.3. - Patient context + stage are concatenated because both invalidate on the same triggers (case mutation, workflow transition), so they amortize together.

Cache hit math at steady state (mid-conversation, same patient, same stage): - Seg 1 (~2000 tok): stable for the entire case lifetime → 100% cache hit - Seg 2 (~900 tok): stable for the stage's duration → ~80% cache hit (target — see Phase 6 acceptance criterion) - Seg 3 (~400 tok): stable while patient state is unchanged → ~70% cache hit (target — see Phase 6 acceptance criterion) - History + latest turn (~2000 tok): uncached by design

Phase 6 acceptance criterion (NEW per arch review): per-segment cache hit rate measured in Langfuse and reported on the dual-shadow dashboard before Phase 7 manual validation begins. Targets are the 80%/70% numbers above; ramp blocks if Seg 2 is <60% or Seg 3 is <50% sustained over 24h.

2.6 Stage resolver truth table (NEW SECTION — addresses arch P0)¶

Stage resolution must be deterministic and total. Every reachable combination of Case.layer_state + WorkflowState maps to exactly one stage, or to the support fallback. The mapping table lives in app/services/stage_resolver.py and is also published as a human-readable matrix in docs/specs/v6-stage-resolver-truth-table.md (NEW artifact, blocking Phase 1).

Inputs to the resolver: - Case.layer_state — JSON dict with keys intent_capture, medical_status, travel_readiness, logistics, financial_readiness (each with completion: float and confidence: float) - WorkflowState — booleans: procedure_identified, documents_uploaded, match_results_shown, provider_selected, consent_given, mso_offered, mso_accepted, consultation_scheduled, consultation_completed, treatment_started, treatment_completed, recovery_offered, recovery_accepted - Case.created_at (used only for "new case" detection) - Case.recovery_milestones (presence + timing)

Tenant scoping (NEW rev 5 per compliance review): caller MUST pass a tenant-scoped Case (loaded via BaseRepository._scoped_query(tenant_id)). The resolver asserts Case.tenant_id is not None and raises TenantIsolationViolation if absent or mismatched. This mirrors §2.4 patient_context_builder's tenant discipline.

Truth table summary (full enumeration in companion doc):

Conflict resolution: rules are evaluated in the listed order; the first match wins. The support fallback catches: (a) malformed state JSON, (b) impossible combinations (e.g., consent_given=True AND procedure_identified=False), (c) stale workflow flags after a manual coordinator intervention.

Rule-order clinical justification (NEW rev 3 per arch reviewer + compliance requirement): when procedure_identified=True AND documents_uploaded=False AND intent_capture.completion < 1.0, BOTH procedure_identification and records_collection could match. The order picks procedure_identification first — the clinical rationale is that establishing why the patient needs the procedure (intent capture remaining gaps) before pushing for documents reduces premature data collection on cases that may pivot. Dr. Naidu reviews this ordering as part of the Phase 2 truth-table review gate (companion doc v6-stage-resolver-truth-table.md). If clinical preference is reversed, ordering is swapped in one place (the resolver function + the companion doc) with no impact elsewhere.

Transient-state handling (NEW rev 5 per arch review):

The predicate table assumes steady-state inputs. Three transient states are explicitly handled by predicate refinements:

1. recovery_followup just-accepted, no milestones yet: recovery_accepted=True AND recovery_milestones=[] — this is the gap between accepting the offer and the cron seeding the first milestone (can be up to 60s). REFINED predicate: recovery_accepted=True alone matches recovery_followup (drop the milestones-exist clause). When milestones are empty, the stage guidance is "acknowledge acceptance, wait for first milestone — no proactive question."

2. mso_accepted=False (patient declined): previously scheduling matched on mso_offered=True AND consultation_scheduled=False, parking declined patients in scheduling indefinitely. REFINED: scheduling requires mso_accepted=True. If mso_offered=True AND mso_accepted=False, the resolver skips ahead — next matching rule is whichever workflow step the patient is on (typically pre_travel if consultation declined but treatment proceeds; or back to match_review if patient wants to reconsider). The WorkflowState.mso_accepted input is now consumed (was previously listed but unused — arch review caught this).

3. Coordinator manual mutation produces impossible state: e.g., provider_selected=True without match_results_shown=True. The resolver still matches consent_capture (provider_selected=True AND consent_given=False). This is intentional — coordinator pre-selection is a legitimate workflow. Dr. Naidu reviews the validity of all such combinations in Phase 2.

Backward stage moves: some are intentional, some signal bugs. Documented explicitly:

Determinism guarantee: - The resolver is a pure function — no DB writes, no time-dependent reads beyond created_at. - Same input → same output, always. Enforced by tests/test_stage_resolver_determinism.py (NEW) with property-based fixtures.

Failure mode: - stage_resolver_strict=true (default): on malformed state, log + Telegram alert + fall back to support. Never raises user-visible errors. (Resolves compliance review P1.) - stage_resolver_strict=false: fall back to support silently (no alert). Reserved for dev/staging.

Telegram alert payload — strict PHI-safe schema (NEW rev 5 per compliance review):

Alert body contains ONLY non-PHI fields:

case_id: {uuid}
tenant_id: {clerk_org_id}
prompt_arch: {v5|v6}
workflow_state_booleans: {12 boolean flags from §2.6 inputs, true/false only}
layer_state_completions: {5 numeric scores 0.0-1.0, no clinical content}
resolver_outcome: {"fallback_to_support"}
timestamp: {ISO8601}

Forbidden in alert payload: procedure name, demographics, document content, milestone dates, FHIR resources, patient name, condition labels, free-text notes from Case.extra_metadata. Per CLAUDE.md ground rule #3 + clinical.md "no PHI in external channels." Enforced by tests/test_stage_resolver_alert_pii_safe.py (NEW) which constructs a malformed case with full PHI loaded and asserts the alert payload contains zero patient-identifying fields.

Dr. Naidu reviews this table during Phase 2 — clinical-safety implications of "what does the agent think it should do" are as load-bearing as the prompt rules.

2.7 Why this beats v4/v5¶

2.8 Rule-placement decision rubric (NEW 2026-05-22 per Maria-audit doc sweep)¶

stages.yaml has grown to 607 lines as we have added per-stage rules (muzzle #1084, question budget #1085, etc.). Each PR makes a defensible local choice, but the cumulative question — when does a new rule belong stage-scoped, in the base prompt, in a knowledge addendum, or in voice_rules.yaml? — was nowhere documented. This rubric captures the decision criteria so the next PR pushes against a written baseline rather than re-deriving the answer from first principles.

The 4 placement options¶

Decision criteria¶

Stage-scoped rule → when the rule only applies in 1-3 specific stages.

If you can name the small set of stages where the rule matters and the rule does NOT apply elsewhere, it belongs stage-scoped. Examples:

• #1084 muzzle (no-async-deferral-promise on procedure_identification, records_collection, match_review) — 3 stages, stage-scoped. The rule is meaningful only in stages where the patient might be left waiting; it would be noise elsewhere.
• #1085 question budget (1-question, 2-question, 3-question variants per stage) — 3 stages with distinct budgets, stage-scoped. The numeric budget is the stage-distinguishing characteristic; lifting it to base would force every stage to share a budget.

Base prompt → when the rule applies in EVERY stage (universal).

If you cannot name a stage where the rule should not fire, it belongs in base. The signature pattern: the rule encodes a platform-wide invariant rather than stage-specific behavior. Examples:

• Medical-advice ban — Curaway never diagnoses, never prescribes, never recommends. Universal across every stage of every conversation. Belongs in base (currently lives in base/system_prompt.yaml). Lifting it to a stage would create a stage where medical advice is allowed, which is nonsensical.
• Voice/tone anchors — "warm but precise," "no jargon without explanation," etc. Apply on every turn; belong in base.
• Refusal patterns for off-topic asks ("I'm here to help coordinate your care, not [X]") — universal; base.

Knowledge addendum → when the rule is procedure-specific or document-derived.

If the rule fires based on what procedure the patient is pursuing or what documents they have uploaded, it belongs in a knowledge addendum, not in stages. Stages are about where the conversation is; addendums are about what knowledge the conversation needs right now. Examples:

• Ortho-specific records list (X-ray, MRI, weight-bearing imaging) — fires when procedure family = ortho. Belongs in knowledge/procedures/ortho.yaml, NOT in stages.
• Pre-op fasting guidance — fires when the procedure requires fasting AND the patient is in pre-op stage. The trigger is procedure-specific; the addendum's triggers_when clause handles the stage gate. Belongs in knowledge/.
• Document-state-aware rules ("you've uploaded an MRI — confirm the side") — fires when the FHIR ImagingStudy state matches. Belongs in knowledge/ with a document-state trigger, not stages.

The litmus test: if removing the procedure or document state would make the rule meaningless, it is knowledge, not stage.

voice_rules.yaml → when the rule is a forbidden phrase that needs runtime validation, not just guidance.

Stage and base rules are guidance to the LLM — the model decides whether to honor them. voice_rules.yaml is runtime enforcement — response_policy.py runs regex/string checks against the assistant's output and blocks or rewrites violations. Use voice_rules when:

• The phrase is so dangerous (medical advice phrasing, deferral promises) that you cannot accept the ~5% LLM compliance miss rate
• The phrase pattern is mechanically detectable ("you should", "I'll get back to you", "diagnosed with")
• A CI test (tests/test_voice_compliance.py) must enforce it across prompt changes

Examples already in voice_rules.yaml:

• Medical-advice phrasings ("you should take", "I recommend", second-person clinical directives)
• Deferral phrases added in #1083 ("I'll check with the team", "let me get back to you")
• Diagnostic labels for auto-detected conditions

Voice rules are the belt-and-braces backup for base-prompt guidance. They do not replace prompt guidance — they enforce the most critical subset of it at runtime.

Worked decision flow¶

1. Will this rule fire on every turn of every conversation? → Base prompt. Stop.
2. Does this rule depend on the procedure or uploaded documents? → Knowledge addendum. Stop.
3. Does this rule apply only in a small named set of stages (1-3)? → Stage-scoped. Continue to 4.
4. Is the rule a forbidden phrase that needs runtime enforcement? → Also add to voice_rules.yaml. Stop.

Step 4 is additive: a phrase can be both stage-guidance AND a voice rule. The stage guides the LLM; the voice rule enforces the floor when the LLM slips.

What goes wrong if you pick the wrong placement¶

• Universal rule in stages → must be duplicated across every stage; drift risk when a new stage forgets it (this was the v4/v5 phase × layer overlap problem #491).
• Stage-specific rule in base → fires when it shouldn't; pollutes the prompt with off-topic guidance; wastes input tokens.
• Procedure-specific rule in stages → fires for the wrong procedure family; e.g., ortho records list shows up in oncology intake.
• Forbidden phrase in stages only (no voice rule) → accepts the LLM compliance miss rate for a phrase you cannot afford to miss.

3. Touchpoint sweep (full inventory)¶

Sourced from Explore agent runs on 2026-05-12. File:line citations preserved.

3.1 LLM gateway (app/services/llm_gateway.py)¶

Reuse as-is: - invoke() signature is prompt-agnostic — accepts assembled messages list. No v6-specific changes needed (llm_gateway.py:379-394). - Model selection via get_model_for_task() + model_registry.yaml — unchanged. - Response metadata stamping (model_used, provider, tier, fallback_fired) — unchanged. - Anthropic prompt caching via cached_system_message() — unchanged. - Fallback logic + Telegram alert on both-providers-fail — unchanged.

Extend: - Langfuse trace tagging (llm_gateway.py:464-482) — add three new tags: stage:{stage_name}, knowledge:{addendum_csv}, prompt_arch:{v5|v6}. Backwards-compatible (v5 traffic has empty stage + knowledge + prompt_arch=v5). - Composite prompt_version stamp (NEW per compliance review — closes #359 dependency): every assistant message + Langfuse trace stamps prompt_version as a composite string with this exact format:

v5: prompt_arch=v5; base=conversation_v4|v4.1; phase={phase_id}; layer={layer_id}; addendum=mso|none
v6: prompt_arch=v6; base=conversation_v6@{git_sha[:7]}; stage={stage_id}; knowledge=[{addendum_id_csv}|none]

3.2 Prompt loader (app/services/prompt_loader.py, app/agents/conversation_prompt.py)¶

Reuse: - _resolve_prompt_version() resolution chain (identity > tenant > env-var > Flagsmith > YAML) — keep, extend for prompt_arch (prompt_loader.py:306-327). - cached_system_message() Anthropic cache marker — keep, applied to v6 base + stage + knowledge.

Change: - Add compose_v6(case_id, tenant_id, clerk_user_id) function: resolves stage via stage_resolver, loads base + stage + 0-1 knowledge + patient_context, returns assembled prompt + metadata block. - conversation_prompt.get_system_prompt() gets a branch: if prompt_arch=v6, call compose_v6(); else fall through to existing v4/v4.1/v5 path. - _LAYER_TO_PHASE mapping (triage_agent.py:96-102) is not deleted — kept as fallback for v5 traffic until decommission Phase. - cached_system_message() signature refactor (REVISED rev 3 per impl review — current signature accepts ONE cacheable + ONE variable block at prompt_loader.py:619-654). Refactor to accept a list of (text, cache_control_flag) tuples, emitting one Anthropic cache_control marker per element with cache_control_flag=True. v5 path uses the same refactored function with a 2-element list (cacheable, variable) — semantically equivalent to current behavior, no v5 regression. v6 path uses a 4-element list (3 cached + 1 uncached tail). Refactor lands in Phase 1.

Existing call sites (will receive a prompt_arch branch): - triage_agent.py:62 (load_phase_context) - triage_agent.py:61 (load_layer_context) - conversation_prompt.py:44, :133, :156, :218, :392 - 11 test files importing load_phase_context directly — keep working in v5 mode; v6 tests use new compose_v6 entry.

3.3 Cache layer (Redis via app/services/cache_service.py)¶

REVISED 2026-05-12 per arch P1 + compliance review:

Reuse: - Existing TTLs (patient_state 60s, conv_context 120s, fhir 300s, doc_checklist 300s) — no change. - ICD-10 cache (7-day TTL, 604800s) — unrelated, unchanged.

Extend: - New cache key chat:patient_ctx:{tenant_id}:{case_id} for the patient_context block. - TTL: 60s (matches patient_state cadence — these invalidate on the same triggers).

Cache invalidation hooks (REWRITTEN rev 3 per impl review — prior draft cited fictional event-bus + services that don't exist on main):

The new key MUST invalidate whenever any field in the patient_context block can change. v6 uses the existing invalidate_case_cache() mechanism (no new event-bus infrastructure required). The mechanism is simple: invalidate_case_cache(tenant_id, case_id) purges the entire chat:*:{tenant_id}:{case_id}:* prefix in one Redis SCAN+DEL pass.

Strategy: add chat:patient_ctx as an entry in cache_service.CACHE_CONFIG (nested dict format: {"prefix": "patient_ctx", "ttl": 60} matching existing entries at cache_service.py:114-119) so invalidate_case_cache()'s loop for cfg in CACHE_CONFIG.values(): key = _chat_cache_key(cfg["prefix"], case_id, tenant_id) (real iteration shape per cache_service.py:198) covers it automatically. ANY existing or future call to invalidate_case_cache() then purges the patient_context cache as a side effect. No retrofit; no new event types; no new subscriber service.

Existing invalidate_case_cache() call sites (verified on main, 2026-05-12):

Coverage assessment: the three existing sites cover document uploads + chat messages + erasure. They do NOT cover: FHIR upsert, consent grant/revoke, profile/preferences edit, journey milestone bumps, coordinator manual case mutation. Each of these can change the patient_context block.

Phase 1 deliverable (one PR, low scope):

Add invalidate_case_cache(tenant_id, case_id) calls at the actual mutation sites that exist on main:

Verification step at Phase 1 start: a one-hour spike walks the codebase to confirm each path exists and find the precise file:line. If the path is named differently than above, the spec annotation gets corrected before the implementation PR opens.

Fallback: 60s TTL on the cache key ensures eventual consistency even if a mutation site is missed in Phase 1.

GDPR Article 17 cascade: - app/services/data_subject_handler.py (REVISED rev 3 — correct path, no gdpr/ subdir) already invokes invalidate_case_cache() on erasure. Since chat:patient_ctx: is under the same prefix, no code change required for GDPR coverage — the erasure cascade is automatic via the existing call. - Verified by tests/test_gdpr_erasure_cascade.py extension that asserts chat:patient_ctx: is purged after erasure.

Not needed: - No Redis cache for v6 prompt CONTENT — Anthropic ephemeral cache handles that.

3.4 Extractor pipeline (app/services/extractors/)¶

Per-extractor work (5 total: intent, medical, travel, logistics, financial; plus recovery_checkin which lands via PR #832):

• Each has a hardcoded system prompt referencing "layer 1/2/3/4/5" semantics (e.g., INTENT_SYSTEM_PROMPT in intent_extractor.py:13-125).
• v6 work: replace "layer N" language with stage-equivalent language (e.g., "during the records_collection stage" instead of "during layer 2 — medical_status"). Semantic-equivalent, not a content rewrite. Reviewer must verify each one preserves extraction behavior.
• Routing unchanged: each extractor runs independently per agent_name, gateway routes via model_registry.yaml. No signature changes.
• NO PATIENT CONTENT IN EXTRACTOR SYSTEM PROMPTS (NEW rule per compliance review — addresses content-leak risk): the rewrite MUST NOT embed any patient document text, FHIR JSON, patient name, or other PHI/PII into the system prompt literal. System prompts contain only static schema + few-shot examples (with synthetic patient data). Patient data flows through messages (user role), not through the system prompt. CI gate: tests/test_extractor_prompts_pii_safe.py (NEW) scans each extractor's system prompt for any pattern matching a UUID, email, phone, MRN, ICD-10 code formatted as N0/N9, or known PHI markers.

Risk: extractor prompts encode layer-specific schema expectations (e.g., medical_extractor expects to be called when discussing medical history). If stages don't 1:1 with layers, extractor routing logic in triage_agent must adapt.

Mitigation: stages.yaml stage entries declare extractors_active: [list] — orchestrator reads this to know which extractors to spawn. v6 stage definitions intentionally map 1:1 or N:1 to existing layers (no fewer extractors, only same-or-more).

3.5 Feature flags (app/services/feature_flags.py, Flagsmith)¶

Existing prompt-related flags (all keep working): - prompt_version (default v4, values {v4, v4.1, v3, v1_original}) - triage_layer_context_version (default v1, values {v1, v1.1}) - mso_patient_offer_enabled (boolean) - examples_variant (string) - llm_fallback_enabled, llm_fallback_provider

NEW flags for v6: - prompt_arch (string {v5, v6}, default v5) — top-level arch switch, identity > tenant > default - knowledge_addendums_enabled (boolean, default false) — kill-switch for knowledge layer if a specific addendum misbehaves - stage_resolver_strict (boolean, default true) — if false, falls back to support stage on unknown state; if true, falls back to support AND emits Telegram alert. Never raises user-visible errors. Per §2.6. - knowledge_addendum_allowlist (string-list per identity/tenant, default ["*"] = all enabled) — NEW per compliance review. Per-tenant override for the addendum set. Used when a tenant has regulatory requirements that differ from defaults (e.g., India vs Turkey procedure_clinical_facts wording). Resolution: is_addendum_allowed(addendum_id, tenant_id, identity) checks (a) global knowledge_addendums_enabled, (b) tenant allowlist contains addendum or "*", (c) addendum YAML's optional tenant_allowlist: field is empty OR contains the tenant. AND of all three.

Deprecated post-v6: triage_layer_context_version — kept readable but unused once v5 traffic = 0.

Resolution precedence (unchanged): identity (Clerk user_id) > tenant_id > FF_{FLAG} env override > Flagsmith > YAML default (feature_flags.py:129-182).

3.5.1 Feature flag governance (NEW rev 5 per SD callout — closes 11 gaps)¶

The 5 new v6 flags must follow Curaway's standing flag-management conventions documented in CLAUDE.md ground rule #2 + .claude/rules/definition-of-done.md "Configuration Externalization" section + the feedback_flagsmith_dual_env.md standing rule.

1. Dual-env creation policy (feedback_flagsmith_dual_env.md): every new v6 flag is created in BOTH Production AND Development Flagsmith environments atomically. Default value identical in both (prompt_arch=v5, stage_resolver_strict=true, knowledge_addendums_enabled=false, stage_indicator_visible=false, knowledge_addendum_allowlist=["*"]). Per-env overrides land later via separate ops (e.g., Dev flips prompt_arch=v6 first for staging tests; Prod stays v5 until validation passes).

2. Flagsmith V2 PATCH mechanism (reference_flagsmith_v2_env_patch.md): Curaway Flagsmith environments use V2 versioning. Flag creation + value updates use the env-scoped PATCH endpoint (e.g., PATCH /api/v2/environments/{env_api_key}/featurestates/{feature_id}/), NOT the unscoped V1 endpoint. Phase 1 flag-creation script scripts/create_v6_flags.py (NEW) uses the env-scoped path with explicit dual-env loop.

3. YAML↔Flagsmith sync CI gate (DoD checklist): all 5 new flags MUST be present in config/feature_flags.yaml with description + default value. CI gate runs scripts/sync_flagsmith.py --dry-run on every PR touching the flag list; fails build if YAML and Flagsmith state diverge. Added to .github/workflows/ci.yml slow-lane.

4. Flag dependency matrix (NEW per arch review):

knowledge_addendum_allowlist is per-tenant/identity: AND-combined with knowledge_addendums_enabled. If global flag is false, allowlist has no effect.

5. Killswitch ordering for rollback (NEW per arch review):

Atomic rollback to v5 is prompt_arch=v5 — one flip, all v6 paths disengage. The other v6 flags remain set but inert (per matrix row 1). For partial rollback (keep v6 arch but disable a specific feature), the order is: 1. knowledge_addendums_enabled=false (cheapest — removes one cache segment per turn) 2. stage_indicator_visible=false (disables FE debug card BE-side) 3. stage_resolver_strict=false (silences alerts; use only when alert volume itself is the issue) 4. Full rollback: prompt_arch=v5

6. Langfuse trace stamping for all v6 flags (CORRECTED rev 5 — prior draft only stamped prompt_arch):

Every llm_invoke under v6 stamps these Langfuse tags: - prompt_arch:{v5|v6} (§3.1) - knowledge_addendums_enabled:{true|false} - stage_resolver_strict:{true|false} - stage_indicator_visible:{true|false} (debug-mode marker) - knowledge_addendum_allowlist:{csv_of_addendum_ids|asterisk} (truncate to 100 chars)

Investigating a flag-state-related bug becomes a Langfuse filter on these tags. Implemented in llm_gateway.py extension at line 464-482.

7. Admin UI surface for new flags (extends §3.6): - /admin/flags page (existing) auto-renders all flags via the generic flag list (Flags.tsx:1-14). No code change for prompt_arch, knowledge_addendums_enabled, stage_resolver_strict, stage_indicator_visible. - knowledge_addendum_allowlist is a string-list flag — admin UI needs a multi-select widget. Reuses existing per-tenant override UI but with checkbox list of available addendum YAML files (derived from config/prompts/knowledge/*.yaml directory at server startup). - /admin/triage page (existing) gets an extension: VALID_VERSION_PAIRS dict (Triage.tsx) extended to enforce prompt_arch=v6 is paired with the stages_version flag (NEW flag for stages.yaml minor versioning, e.g., v1.0, v1.1); force_save checkbox bypasses for mismatched-pair flips during incident triage.

8. Per-user identity override prerequisite (#535 gating — EXPLICIT rev 5):

Issue #535 (bug: triage_agent doesn't pass identity to Flagsmith — per-user prompt-version overrides don't fire) MUST be resolved before v6 Phase 1 starts. Without it, per-user prompt_arch=v6 overrides during dual-shadow ramp would silently fall back to tenant default, invalidating the 10% ramp signal. Phase 0 gate: confirm #535 closed before Phase 1 PR opens.

9. mso_patient_offer_enabled migration (NEW per §10 Q6 resolution):

The MSO addendum currently lives at conversation_v4.yaml:204 mso_offer_addendum: gated by mso_patient_offer_enabled. In v6 it becomes config/prompts/knowledge/mso_second_opinion.yaml gated by the SAME flag. Migration is stateless on the flag — tenants with mso_patient_offer_enabled=true continue to see the MSO offer regardless of arch version. Phase 2b PR includes a regression test asserting flag value is honored across v5↔v6 toggle.

10. CI gate enforcement summary (NEW table — what fires when):

11. Documentation (extends Appendix B): - docs/reference/feature-flags.md — register all 5 new flags + dependency matrix - docs/runbook/prompt-rollback.md — operational guide for killswitch ordering (NEW) - scripts/create_v6_flags.py (NEW) — one-shot flag-creation script with dual-env loop + V2 PATCH

3.6 Admin app (apps/admin-app/)¶

Reuse as-is: - /admin/flags page already supports per-tenant + per-user identity overrides for arbitrary flags. New prompt_arch flag surfaces automatically (Flags.tsx:1-14). - /admin/triage page already shows prompt_version + triage_layer_context_version with VALID_VERSION_PAIRS validation (Triage.tsx:11-12). Extend: add prompt_arch selector + stage_context_version selector. Reuse force_save + audit-trail wiring.

NEW admin UI (small, in Triage page): - Selector: prompt_arch (v5 / v6) - Dropdown: when v6 active, show resolved stage_active per case (read-only debug aid; sourced from new admin endpoint /api/v1/admin/cases/{case_id}/stage) - Knowledge addendum overrides — toggle individual addendums on/off per tenant (rare, mostly for incident triage)

Endpoint authorization (NEW per arch P2 + compliance review): - /api/v1/admin/cases/{case_id}/stage MUST use Depends(require_case_access) per CLAUDE.md ground rule #3 + backend-services.md Per-Resource Authorization. Tenant filter alone is insufficient. - Allowed bypass roles: super_admin, platform_admin only. No other admin role bypasses ownership. - Returns 404 on case-not-found (NOT 403) to avoid leaking case existence.

Not needed: - No Langfuse trace viewer in admin (defer to v7+). Langfuse Cloud UI continues to serve. - No stages.yaml editor — file is checked into repo, PRs are the editing surface.

3.7 Frontend — patient app (apps/patient-app/)¶

Reuse: - RichCard.tsx dispatcher (lines 42-62) — extend the if/else tree with 4 new types: view_payments, view_summary, view_consultations, stage_indicator. Pattern matches existing 14 entries. - ConversationApp.tsx + MessageThread + MessageBubble — unchanged.

NEW rich_content types: - view_payments — payments deep-link card with case_id; opens /payments page (placeholder, route to be added) - view_summary — summary deep-link card; opens /summary - view_consultations — MSO consultation list deep-link; opens /consultations (placeholder) - stage_indicator — dev-only debug card showing current stage; server-side gated by Flagsmith flag stage_indicator_visible (default off) AND ?debug=true query param (defense in depth). BE strips the card from the assistant response payload server-side before serialization when gate fails (NEW rev 5 — FE never receives the card; "hide on FE" is not sufficient). Patient toggling URL params alone gets nothing in the response. Enforced by tests/test_stage_indicator_server_side_strip.py (NEW).

Placeholder page scope (NEW rev 6 per DoD review §10 + §12): the 3 new pages (Payments.tsx, Summary.tsx, Consultations.tsx) are minimal read-only deep-link targets — they consume existing APIs and render in <5KB gzipped each. They follow patient-app design tokens (no hardcoded colors), mobile-first 375px viewport, touch targets ≥44px on links, WCAG AA contrast on text, and dir="auto" on root containers. Full design treatment (richer layouts, prefers-reduced-motion, /impeccable audit) is deferred to v7 per §1.2 — these pages exist to satisfy the chat agent's view_* card click target, not as new product surfaces.

3.7.1 Analytics / event tracking (NEW rev 6 per DoD review §14)¶

FE PostHog events (extend existing apps/patient-app/src/lib/posthog.ts analytics helpers):

No PII in event properties — case_id is a UUID, stage_active is a config key, prompt_arch is a string literal.

BE Event model emission — for stage transitions, the existing Langfuse stage:{stage_name} trace tag (§3.1) already provides per-turn observability. Adding Event model rows for stage transitions would be redundant and would inflate the events table. Decision: rely on Langfuse for stage-transition analytics; no new EventType enum value needed. Conversion-funnel queries are answerable via Langfuse + Metabase joins on the existing case_id correlation.

NEW pages (placeholders): - /payments — minimal page reading from existing payment/charge data - /summary — minimal page reading from caseSummary API - /consultations — minimal page listing MSO sessions

These pages exist as deep-link targets for chat cards. They are not new product surfaces — the chat agent emits a view_* card and the patient clicks to see details. Each page is read-only and consumes existing APIs.

Not affected: - No FE-side prompt awareness — prompt_version and prompt_arch stay backend-only. - MessageData interface in caseApi.ts unchanged. Optional addition deferred to v7.

3.8 Cross-portal (apps/coordinator-app/, apps/mso-app/, etc.)¶

Not affected — coordinator and MSO portals don't surface conversation routing concerns today and shouldn't in v6.

Possible future: a coordinator-side "stage_active per case" column for queue prioritization. Filed as v7+ if needed.

3.9 Tests + CI gates¶

Existing v5 Phase 0 work (tests/test_prompt_compliance.py) — built in v5 spec §3 as the validation harness. v6 extends: - 8 axes from v5 stay - New 9th axis: stage-transition smoothness — given two consecutive turns, does the stage transition (if any) produce a natural conversation? Score 0-3. - New assertions: - assert len(stages_active) == 1 per turn — stage uniqueness - assert knowledge_addendums_count <= 1 — addendum cap (per §2.3, §2.5) - assert prompt_arch_active in {v5, v6} — no silent fallthrough

Existing voice-rules + no-medical-advice CI tests (tests/test_voice_compliance.py, tests/test_no_medical_advice.py) — unchanged, both v5 and v6 must pass.

NEW CI gate — token budget (REVISED 2026-05-12 per arch P1 + impl review): - Test: max(base + patient_context + active_stage + 1 knowledge addendum) ≤ 6,500 input tokens for standard stages, 7,500 for recovery_offer + recovery_followup + consent_capture (which carry ADR-0018 §K mandatory clinical text). - History is excluded from the budget — history is per-conversation, not per-stage; bloating gates should target stage definitions, not real conversations. - Tokenizer: use tiktoken (cl100k_base for Anthropic-equivalent counts) — free, deterministic, accurate to within ~3% of Anthropic's count_tokens API. Document the ~3% slack in test thresholds — gate at 6,000 / 7,000 (REVISED rev 3 per arch review — was 6,300/7,200, tightened for genuine headroom) to leave 500-token slack against real Anthropic counts. - Dependency justification (NEW rev 6 per DoD review §23): tiktoken is a Python CI-only dependency (development extra, not runtime). Wheel size ~few hundred KB; no Anthropic API call required (offline tokenization). No frontend bundle impact. Added to requirements-dev.txt (or pyproject.toml [tool.poetry.group.dev]), NOT to runtime requirements.txt. - Fails build if a stage profile or knowledge addendum bloats past these thresholds.

NEW CI gate — stage schema consistency (REVISED 2026-05-12 per impl review): - Test: every cards_to_use entry in stages.yaml maps to a rich_content.type known to the FE. - Implementation: extract RichCard.tsx switch statement into a generated JSON manifest at apps/patient-app/src/components/chat/rich_content_types.generated.json via a small Vite build hook (1 day work, lands in Phase 1). Python CI reads the manifest. No regex parsing of TSX. - Catches FE/BE drift

NEW CI gate — duplicate content (REVISED rev 5 per arch review — soft warning → hard fail above threshold): - Test: hard-fail if the same 50-token N-gram appears in 3 or more stage profiles (cross-stage duplication is the structural risk v6 was designed to eliminate per §2.7). Two-stage overlap is allowed (often legitimate); 3+ is a real bug. - Warn-only for 50-token N-grams appearing in exactly 2 stages — points to dedup opportunity without blocking the build.

NEW CI gate — voice rules dual-arch fixtures (NEW rev 5 per compliance review):

Phase 0 extends tests/test_voice_compliance.py to cover BOTH arch versions. Today's fixtures are v4-shaped; v6 fixtures cover 10 stages × 3 personas = 30 new fixture cases. Without these, the §8.5 dual-arch lockstep claim is nominal only. Same fixture expansion applies to tests/test_no_medical_advice.py. Phase 0 deliverable.

3.10 Observability extensions¶

• Langfuse tag additions: stage:{name}, knowledge:{csv}, prompt_arch:{v5|v6} (llm_gateway.py extension point).
• New Metabase queries:
• Cost per stage (group LLM usage by stage tag)
• Token usage per addendum (which addendums actually load in prod)
• Stage transition heatmap (which transitions are most common; identify weird flows)
• Telegram alert wiring:
• On stage_resolver_strict=true failure: alert with case_id + state snapshot
• On knowledge addendum load failure: alert with addendum name + tenant_id

4. v5 rule absorption mapping¶

Each v5 rule (from docs/specs/conversation-v5-feature.md §2) gets a new home in v6:

REVISED 2026-05-12 per compliance review — Rule 2.3 moved from records_collection stage back to BASE, because demographic verification is clinical-safety-critical and must fire in any stage where a demographic claim could appear (e.g., agent might fabricate age during match_review or procedure_identification, not just records_collection).

Rule 2.4 turn-cadence enforcement (NEW — compliance review P0): - Stage-presence alone is insufficient. If a case lingers in discovery for 8 turns without advancing, the records-upload re-offer must still fire on turn 2-3 of the stage regardless of advance_when triggering. - Mechanism: stages.yaml > discovery declares re_offer_on_turn: [2, 3] field. Composer reads this and injects the re-offer guidance when stage-turn-count matches. - Phase 0 test fixture: 5+ turn discovery stagnation case → assert re-offer language appears on turns 2 AND 3, then doesn't repeat.

Verbatim phrase preservation fixtures (NEW — compliance review P1):

Phase 0 must add tests/test_v5_rule_verbatim_preservation.py with assertions that the following phrase lists appear unchanged in conversation_v6.yaml: - v5 §2.1 NEVER list: "different from what your doctor told you", "this is not [diagnosis]", "the diagnosis is wrong", "I'm seeing findings that contradict…" - v5 §2.1 ALWAYS list: "I want to make sure these have been factored in", "could you check with the oncologist whether…" - v5 §2.2 SAFETY block carve-out: "Surfacing factual findings IS allowed" - v5 §2.3 identity-clarification pattern: "The report I'm reading lists the patient as X — is this for someone other than yourself?" - v5 §2.5 emotional verbatim words list: "exhausted", "scared", "desperate", "overwhelmed", "frustrated", "suffering", "worried"

If any phrase goes missing during the migration content port (§Phase 2), CI fails — content drift is caught before clinical advisor review.

All bad/good patterns from v5 spec §2 carry forward verbatim. Test seeds (case 33b8be7a, etc.) move into tests/test_prompt_compliance.py v6 fixtures.

5. Hot-fix preceding v6 (#835)¶

Lands 2-3 days before v6 Phase 0 starts.

• Scope: just the two P0s. Two new paragraphs in conversation_v4.yaml (treatment-recommendation ban + scope-rejection ban).
• Validation (REVISED rev 3 per compliance review): 2 baselines + 2 after on 3 personas (caregiver/oncology, direct/ortho, exploratory) — ratcheted up from initial 1+1 on 2 personas because two P0s warrant the full persona set even for a hot-fix. Dr. Naidu reviews the two paragraphs against case 33b8be7a transcript.
• Voice-rules + no-medical-advice CI tests must pass.
• v6 Phase 1 inherits these paragraphs into conversation_v6.yaml base — verbatim copy.
• Absorption fixture (NEW rev 5 per compliance review): tests/test_hotfix_837_absorption.py (NEW) asserts the exact two paragraphs from #837 (treatment-recommendation ban + scope-rejection ban) appear byte-identical in conversation_v6.yaml HARD BANS section. Failure means wording drifted during absorption and Rule 2.2 is weakened.

6. Phases / sequencing¶

REVISED 2026-05-12 per implementation review: tests/test_prompt_compliance.py does NOT exist (v5 Phase 0 was planned but never landed). Phase 0 must BUILD the harness from scratch, not extend it.

Total calendar: ~6-7 weeks (CORRECTED rev 5 — was 5-6; Phase 0 estimate increased by 3 days, Phase 10 by 1 day). Total active engineering: ~3.5-4 weeks.

Dr. Naidu calendar dependency (NEW rev 5 per compliance review — was understated):

v6 has 4 separate clinical-advisor sign-off gates, not 1: 1. #837 hot-fix mini-review (Phase −1, before Phase 0) 2. Phase 2a base prompt rules gate 3. Phase 2b stages.yaml content gate 4. Phase 7 validation cycle (3-persona × 9-axis sign-off)

Contingency policy: if Dr. Naidu is unavailable >2 weeks for ANY of the 4 gates, the phase pauses (no fallback reviewer for clinical-safety wording — per feedback_agent_chat_sacrosanct.md). All 4 windows MUST be locked on his calendar before Phase 0 starts. If he becomes unavailable mid-phase, all subsequent v6 PRs requiring his review are blocked until he returns or until SD designates a temporary medical advisor in writing.

7. Validation discipline¶

Per feedback_agent_chat_sacrosanct.md — every flag flip requires:

7.1 The 9 axes¶

8 axes from v5 spec §4 + the new stage-transition axis:

1. Voice compliance (no forbidden phrases)
2. Question-axis discipline (one axis per turn)
3. Emotional verbatim echo (exact word, not synonym)
4. Document trust framing (when doc findings conflict with self-report)
5. Demographic verification (no fabricated age/gender)
6. Never-diagnose / never-prescribe / never-reject
7. Records-upload offer (turn 2-3 cadence)
8. JSON schema fidelity (parses cleanly, fields present)
9. NEW: Stage transition smoothness — given two consecutive turns, is the stage change (if any) coherent? Does the assistant acknowledge before pivoting?

7.2 The 3 personas¶

• Persona A: caregiver of pediatric oncology patient (covers #743 + #560 + #547)
• Persona B: direct adult ortho patient (covers #491 + #550)
• Persona C: exploratory ("just researching", no procedure yet) (covers discovery → procedure_identification stage transition)

7.3 3 baselines + 3 after per persona¶

9 conversations total before flag flip. Conducted live by SD with Dr. Naidu observing.

7.4 Pass criteria¶

• All 9 axes scored 3/3 (perfect) on at least 8/9 conversations
• Zero hard-fail violations (forbidden phrases, medical advice, fabricated demographics) on any conversation
• Dr. Naidu signs off in writing on a per-persona basis

8. Rollback plan¶

8.1 Mechanism¶

prompt_arch Flagsmith flag selects loader at runtime. One flag flip reverts v6 traffic to v5.

8.2 What rollback preserves¶

• v5 + v4 code paths stay live until decommission Phase 10.
• v5 base prompt + phase contexts + layer contexts stay in tree.
• Tests for v5 paths stay green.

8.2.1 Mid-conversation rollback (NEW rev 5 per compliance review)¶

If the prompt_arch flag flips during an active conversation (e.g., turn 5 was on v6, turn 6 will be on v5):

• prompt_version stamp: each turn's message metadata + Langfuse trace stamp reflects the active arch at that turn's call time. Turn 5 metadata says prompt_arch=v6, turn 6 metadata says prompt_arch=v5. Audit-trail consumers must accept that a conversation can have mixed arch stamps.
• Langfuse traces: per-call, so each trace is internally consistent. A conversation-level Langfuse view will show mixed prompt_arch tags — this is expected post-rollback, not corrupted data.
• chat:patient_ctx: cache: v5 path does not read this key. Stale entries from v6 simply expire on the 60s TTL. No data corruption, no action needed.
• Conversation history: passes through unchanged (it's stored separately from prompts). The model sees the full history regardless of arch.
• WS event lifecycle (batch_complete, findings_incorporated, message_complete per #805): all events keep emitting; their consumers are arch-agnostic.

SOP for mid-conversation rollback: no special handling needed. Flagsmith updates propagate via the ~60s flag cache on the server side; the next turn after that window uses the new arch. Patient sees no error.

8.3 What rollback loses¶

• The 5 v5 rules not in the #835 hot-fix go back to v4 behavior (#560, #547, #491, #550, #546 may re-fire).
• Token savings revert.
• Mitigation: post-rollback hot-fix path — promote ONE v6 rule at a time to v5/v4 if a specific bug re-fires.

8.4 Trigger thresholds¶

Rollback if ANY of: - Voice-rules CI test failure in production traffic (auto-rollback) - 2+ clinical-safety violations in a 24h period observed by Dr. Naidu in audit - Cost-per-turn spike >2× v5 baseline for 1 hour sustained - Stage resolver alerting rate >5% of turns - JSON parse failure rate >0.5% of turns (vs v5 baseline ~0.05%)

8.5 Lockstep PR discipline (STRENGTHENED 2026-05-12 per compliance review)¶

Between Phase 2a (base migration) and Phase 9 (observation complete):

Mandatory lockstep coverage (was: only forbidden_phrases; revised to cover all clinical-safety-affecting changes):

1. Any voice-rule / hard-ban / forbidden-phrases change MUST land in BOTH conversation_v6.yaml AND conversation_v4.yaml (v5 was folded into v6, so v4 is the active legacy target) in the same PR.
2. Any new banned phrase added to v6 base MUST also be added to v4 base.
3. Any positive-pattern rule strengthened in v6 base (Rule 2.1 four-part framing, Rule 2.3 demographic clarify, Rule 2.5 emotional verbatim list) MUST be checked against v4 base for equivalent strengthening — if v4 needs it too, both go in the same PR.
4. Any change to stages.yaml > guidance that encodes a clinical-safety constraint MUST land in the corresponding v4 phase OR layer YAML if the constraint applies pre-v6 too.
5. Hot-fix paragraphs from #835 / PR #837 are lockstep targets — any future strengthening of those bullets goes to both v4 and v6 in the same PR.

Rule-location registry (NEW per arch P0):

docs/specs/v6-rule-location-map.md (NEW artifact, blocking Phase 2a) lists every clinical-safety-affecting rule and its precise location in v4, v5 (legacy), v6 base, and v6 stages. The lockstep CI gate consults this file to determine which targets each rule must update.

Format:

- rule_id: "treatment_recommendation_ban"
  closes: ["#642"]
  v4_location: "conversation_v4.yaml SAFETY block, bullet 6 (added in #837)"
  v6_base_location: "conversation_v6.yaml HARD BANS section, rule 2.2"
  v6_stages_location: null  # base only
  lockstep_required: ["v4", "v6_base"]

- rule_id: "records_upload_re_offer"
  closes: ["v5 §2.4"]
  v4_location: null  # not present in v4 (regression)
  v6_base_location: null  # stage-scoped
  v6_stages_location: ["discovery", "procedure_identification"]
  lockstep_required: ["v6_stages_only"]

CI gates (one new gate, two extended) — REVISED rev 3 per impl review (replaced LLM-graded equivalence with deterministic normalize+hash diff):

• tests/test_voice_compliance.py (existing) — runs against BOTH v4 + v6 paths during coexistence window; failure on either fails the PR.
• tests/test_lockstep_consistency.py (NEW) — reads v6-rule-location-map.md, walks every rule, asserts:
• (a) the rule text exists at the declared location in each lockstep_required: target;
• (b) no lockstep_required: target is missing if the rule has clinical-safety implications;
• (c) for rules with lockstep_required: ["v4", "v6_base"], the wording is byte-identical OR matches a deterministic "semantic-equivalence hash" computed as: lowercase → strip whitespace → drop punctuation → sort sentences → SHA-256 hash. Both targets must produce the same hash. No LLM call in CI. This is intentionally strict: when the wording deliberately diverges between v4 and v6 (e.g., v4 uses "intake coordinator" and v6 uses "stage coordinator"), the rule-location-map declares an explicit semantic_diff_allowed: true flag that suppresses the hash check for that rule with a justification comment.
• tests/test_v5_rule_verbatim_preservation.py (NEW per §4) — asserts v5 spec §2 NEVER/ALWAYS phrase lists appear verbatim in v6 base AND in the assembled (post-loader) prompt string. The post-loader check catches YAML-restructure regressions where a phrase remains in the file but under an unused key.

No external LLM calls in CI gates. All gates are deterministic + fast (~seconds, not minutes). LLM-graded scoring is reserved for the 9-axis Phase 0 harness (offline validation), not PR gates.

9. Risks & mitigations¶

10. Open questions¶

1. Should support stage exist or should it be the default for new cases? Currently spec'd as a fallback safety net. Could also be the entry stage.
2. Where does the recovery-checkin extractor live in stages? Today PR #832 ships it as a phase. In v6 it becomes stages.yaml > recovery_followup.extractors_active. Need to confirm extractor wiring stays clean.
3. Knowledge addendum priority resolution — explicit priority numbers vs deterministic ordering by patient-state importance? Spec leaves it as explicit priority: field; review may prefer alternative.
4. Per-case stage override for coordinator — should coordinator be able to force a stage from the admin UI (e.g., "this patient is actually in pre_travel, ignore the resolver")? Useful for support but adds blast radius. RESOLVED 2026-05-12 per arch P2 review: deferred to v7+. v6 does NOT support manual override — stage_resolver is the single source of truth. This keeps the resolver contract unambiguous and the blast radius bounded. Coordinators wanting to advance a stuck case must mutate WorkflowState (which then drives the resolver) rather than bypass it.
5. i18n interaction — when #423 lands, do knowledge addendums get locale variants, or do they pass through translation at runtime? Defer answer until i18n track is concrete.
6. MSO patient offer addendum — currently lives at conversation_v4.yaml:204 mso_offer_addendum:. In v6 this becomes knowledge/mso_second_opinion.yaml gated by mso_patient_offer_enabled flag. Verify the existing identity-override + tenant resolution carries forward.

Appendix A — Existing issues impact matrix¶

Appendix B — Code locations to touch¶

New companion docs (blocking artifacts)¶

• docs/specs/v6-stage-resolver-truth-table.md (NEW — blocks Phase 1; full enumerated truth table per §2.6)
• docs/specs/v6-rule-location-map.md (NEW — blocks Phase 2a; lockstep registry per §8.5)
• docs/specs/v6-stages-extractors-matrix.md (NEW — blocks Phase 2b AND Phase 5 per compliance review; stage content authoring without knowing extractor coverage risks orphaning extraction. Phase 2b cannot start until this matrix is published.)

Backend¶

• config/prompts/base/conversation_v6.yaml (NEW)
• config/prompts/stages.yaml (NEW)
• config/prompts/knowledge/*.yaml (NEW, ~4 files initially)
• app/services/prompt_loader.py — add compose_v6(), extend _resolve_prompt_version() for prompt_arch
• app/agents/patient_context_builder.py (NEW — placed in agents/, not services/, per §2.4 revision)
• app/services/stage_resolver.py (NEW)
• app/services/llm_gateway.py — extend Langfuse tag block at line 464-482
• app/services/feature_flags.py — register new flags
• app/services/cache_service.py — add chat:patient_ctx: key (mirrors existing pattern)
• app/agents/conversation_prompt.py — branch on prompt_arch in get_system_prompt() (line 113-163)
• app/agents/triage_agent.py — branch in node functions where _LAYER_TO_PHASE is consulted (line 96-102)
• app/agents/orchestrator_phases/recovery.py (file lands via PR #832 — v6 work is downstream of that merge; if #832 has not merged when v6 Phase 1 begins, this line is a no-op)
• app/services/extractors/*.py — update 5 hardcoded system prompts (semantic-equivalent rewrite)
• config/feature_flags.yaml — register prompt_arch, knowledge_addendums_enabled, stage_resolver_strict

Tests¶

• tests/test_prompt_compliance.py — extend with 9th axis, stage uniqueness, token budget, schema consistency, duplicate-content warning
• tests/test_voice_compliance.py — extend to run against both v5 + v6 paths
• tests/test_no_medical_advice.py — extend to run against both v5 + v6 paths
• tests/test_stage_resolver.py (NEW)
• tests/test_stage_resolver_determinism.py (NEW — property-based, per §2.6)
• tests/test_v5_rule_verbatim_preservation.py (NEW — per §4)
• tests/test_lockstep_consistency.py (NEW — reads v6-rule-location-map.md, per §8.5)
• tests/test_gdpr_erasure_cascade.py extension (extend existing — adds chat:patient_ctx: to cascade verification, per §3.3)
• tests/test_anthropic_cache_breakpoint_limit.py (NEW — assert composition produces ≤4 cache markers, per §2.5)
• tests/test_prompt_version_stamp_format.py (NEW — assert composite stamp format per §3.1)
• tests/test_extractor_prompts_pii_safe.py (NEW — assert no PHI/PII in extractor system prompts per §3.4)
• tests/test_addendum_priority_clinical_first.py (NEW — assert clinical-safety addendums ordered first per §9 risk row)
• tests/test_conversation_v4_streamer.py + test_conversation_v4_parser.py (EXISTING — must continue passing against renamed v6 modules per §1.4)
• tests/test_patient_context_builder.py (NEW)
• tests/test_knowledge_addendum_gating.py (NEW)
• tests/test_extractor_layer_to_stage_rename.py (NEW — regression fixture)

Frontend¶

• apps/admin-app/src/pages/Triage.tsx — add prompt_arch selector + stage debug viewer
• apps/admin-app/src/pages/Flags.tsx — auto-renders new flags, no change needed
• apps/patient-app/src/components/chat/RichCard.tsx — extend dispatcher with view_payments/view_summary/view_consultations/stage_indicator
• apps/patient-app/src/pages/Payments.tsx (NEW)
• apps/patient-app/src/pages/Summary.tsx (NEW)
• apps/patient-app/src/pages/Consultations.tsx (NEW)
• apps/patient-app/src/App.tsx — register 3 new routes

Docs¶

• docs/specs/conversation-v6-feature.md (THIS FILE)
• docs/architecture/05-llm-pipeline.md — update prompt assembly section
• docs/runbook/prompt-rollback.md (NEW) — operational guide for prompt_arch flag flip
• docs/reference/feature-flags.md — register new flags
• CLAUDE.md (root) — bump prompt architecture summary line

Appendix C — Token budget math¶

Per-turn input tokens (intake + medical_status + mso example)¶

v4/v5 today: - Base prompt (conversation_v4.yaml): ~3,000 - Phase context (intake.yaml): ~800 - Layer context (medical_status.yaml): ~1,200 - MSO offer addendum: ~600 - Tool/schema definitions (in phase contexts): ~700 - Patient context (ad-hoc injection): ~300 - History (last 20 turns): ~2,000 - Total: ~8,600

v6 proposed: - Base prompt (conversation_v6.yaml): ~2,000 (schemas moved here, but consolidated) - Stage profile (records_collection): ~500 - Knowledge addendums (mso_second_opinion + procedure_clinical_facts/knee_replacement): ~700 - Patient context (structured block): ~400 - History (last 20 turns): ~2,000 - Total: ~5,600

~35% input token reduction.

Cost math¶

At Sonnet pricing ($3/MTok input, $15/MTok output): - Today: 100 cases × 30 turns × 8,600 input tok = 25.8M tok/mo input = ~$77/mo - v6: 100 cases × 30 turns × 5,600 input tok = 16.8M tok/mo input = ~$50/mo - Savings: ~$27/mo at current scale. Scales linearly with case count.

Output tokens unchanged (v6 doesn't affect response length).

Anthropic prompt caching impact¶

Cacheable prefix (base + stage + knowledge + patient_context): - v6: ~3,600 tokens stable per case for ~5 min - v4/v5: ~5,600 tokens stable per case (more cache hits, larger prefix)

Anthropic caches at ~$0.30/MTok cached read (10× cheaper than fresh). v6 has smaller cacheable prefix → marginally less cache-hit benefit per turn, but the smaller absolute prompt more than compensates.

End of spec.