{ "schema_version": 2, "content_source": "cards.json", "master_since": "2026-07-31", "business_document": { "title": "RonanRx / Elite Care Pharmacy Business Requirements", "version": "v3.4", "audience": "Product, clinical, operations, design, and engineering collaborators implementing or reviewing RonanRx.", "authority": "Rules and Target text are binding product intent. As-built evidence and delivery status are informative and may never override a Rule or Target. Rules are founder-approved unless a rule carries an explicit Source note.", "future_cards": "A future card states direction, not authorization to implement. Work begins only through the normal approved delivery process.", "deviation_protocol": "When implementation and this registry diverge: stop, classify the difference as intent drift, implementation drift, or new evidence, then propose a correction for review. Never silently choose one side.", "one_home_rule": "Each business fact has one owning card. Other business cards link to it instead of copying it. Technical and database documents retain acknowledged implementation-detail duplication until their post-migration restructure." }, "source_baseline": { "staging": "c00248749c0287f6c87f5a553394b339fb2dedd5", "main": "d26d5e1c238bcedffef44fb4acadc1a6a3eb7788", "audited_on": "2026-07-21" }, "status_basis": "Schema-v2 status is canonical in spec/status.json; legacy status words, depends_on, connection lists, rails, views, and mobile paths are compiler-derived compatibility output.", "tracks": [ "patient", "doctor", "ai-agents", "ops" ], "card_universe": { "total": 55, "numbered": 54, "unnumbered_id": "cams-crack-commandments", "board_nodes": 47 }, "cards": [ { "key": "cam", "number": null, "section": 0, "section_title": "Agent Ground Rules", "id": "cams-crack-commandments", "title": "Cam's Crack Commandments", "track": "ai-agents", "business_anchor": "cams-crack-commandments", "technical_anchor": "cams-crack-commandments", "as_built_anchor": "cams-crack-commandments", "old_anchor": "cams-crack-commandments-agent-ground-rules-canonical-name-v2", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "The binding, priority-ordered operating rules for agents working on RonanRx, most fundamental first. They are not testable or enforceable by any code or test; agents must follow them anyway.", "target": { "summary": "Apply all twelve commandments in priority order to agent work across the product.", "gaps": [] }, "open_decisions": [], "rules": [ { "id": "RRX-AGENTS-001", "text": "**We're building, not maintaining.** We make mistakes and fix them fast: that's the job. This isn't a 20-year hospital system guarding decades of records.", "enforcement": "", "source": "" }, { "id": "RRX-AGENTS-002", "text": "**Less is more.** Simplest solution that works; don't over-engineer or balloon scope. Reuse what work. DRY rules the day.", "enforcement": "", "source": "" }, { "id": "RRX-AGENTS-003", "text": "**Default to removing, not adding.** Don't add gates, checks, or \"just to be safe\" steps to routine work.", "enforcement": "", "source": "" }, { "id": "RRX-AGENTS-004", "text": "**You're not a lawyer.** No legal or HIPAA advice, and don't block work over compliance worries: not your call.", "enforcement": "", "source": "" }, { "id": "RRX-AGENTS-005", "text": "**The operator owns the risk.** Whoever runs an action owns its outcome: you execute what they ask, don't over-protect them.", "enforcement": "", "source": "" }, { "id": "RRX-AGENTS-006", "text": "**Settled is settled.** Don't re-argue decisions already made.", "enforcement": "", "source": "" }, { "id": "RRX-AGENTS-007", "text": "**Patient data is consented and covered.** Patients sign our agreements and we hold BAAs with every platform (Anthropic, OpenAI, Gemini, Linq, GCP): using patient data in the app is normal, never a blocker.", "enforcement": "", "source": "" }, { "id": "RRX-AGENTS-008", "text": "**Touching the EHR is not dangerous.** Editing charts is normal, useful work. Don't wrap it in caution.", "enforcement": "", "source": "" }, { "id": "RRX-AGENTS-009", "text": "**Marketing and site copy are Lloyd's.** He owns the marketing and legal sites and their wording: don't flag or block on copy legality.", "enforcement": "", "source": "" }, { "id": "RRX-AGENTS-010", "text": "**Use the data we already have.** Reuse existing fields before asking for anything new. DRY.", "enforcement": "", "source": "" }, { "id": "RRX-AGENTS-011", "text": "**Don't invent database fields or tables.** Check what already exists first.", "enforcement": "", "source": "" }, { "id": "RRX-AGENTS-012", "text": "**All patient and health data goes into the EHR.** Never build a side store.", "enforcement": "", "source": "" } ], "legacy_technical_anchors": [ "section-9-ai-agent-layer" ], "node_contract": { "kind": "policy", "layer": "governance", "trigger": "Any agent or operator begins RonanRx work.", "inputs": [ "No operational input; activated only by its stated trigger." ], "outputs": [ "apply agent operating rules to Agent Router", "bound onboarding agent to Onboarding Agent" ], "owner": "AI Platform", "operator": "Product and operations leadership", "completion": "Apply all twelve commandments in priority order to agent work across the product.", "failure_retry": "Failures remain attributable and visible to the named owner; retry only the owning idempotent command and never invent success.", "system_of_record": "Version-controlled Scale business, technical, and as-built suite.", "actors": [ { "actor": "agent", "participation": "subject" }, { "actor": "operations", "participation": "operates" } ], "domains": [ "governance" ], "journey_stage": "governance", "map_presence": "default" }, "subdiagram_refs": [] }, { "key": "1.1", "number": "1.1", "section": 1, "section_title": "Patient Entry & Onboarding", "id": "iphone-link", "title": "iMessage (Linq)", "track": "patient", "business_anchor": "iphone-link", "technical_anchor": "1-1-imessage-linq", "as_built_anchor": "iphone-link", "old_anchor": "1-1-iphone-link-sms-entry-secure-signup-links-exists", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "The front door: a patient texts the advertised RonanRx number (SMS or iMessage via Linq (the linqapp.com messaging platform)) and the system carries them from first message to a secure signup link.", "target": { "summary": "Keep text messaging as the patient front door and carry each qualified patient into a secure, expiring signup flow.", "gaps": [] }, "open_decisions": [], "rules": [ { "id": "RRX-ONBOARDING-001", "text": "Signup links expire after 24 hours and may only resolve to the intended patient flow.", "enforcement": "Enforced by: test/lib/signup_magic_link_test.rb (EXPIRES_IN = 24.hours; 'consume! raises InvalidToken on an expired token' + purpose/intake isolation so a token only resolves to its intended flow) and test/models/secure_link_test.rb (short-code TTL + resolves to originating intake).", "source": "" }, { "id": "RRX-ONBOARDING-002", "text": "Inbound messages are idempotent and replay-safe.", "enforcement": "Enforced by: app/controllers/api/v1/linq_controller.rb inbound dedupe (LinqEvent.exists?(message_id:) fast-path plus an advisory-locked recheck), backed by UNIQUE index index_linq_events_on_message_id in db/structure.sql; verified by test/integration/api/v1/linq_inbound_test.rb ('duplicate message_id is ignored and does not advance the FSM').", "source": "" }, { "id": "RRX-ONBOARDING-003", "text": "The front door must preserve opt-out, consent, and emergency handling before conversational work begins.", "enforcement": "Enforced by: test/integration/api/v1/linq_inbound_test.rb (opt-out short-circuits before planning; the frozen AI-disclosure/consent burst is the first outbound turn and is not repeated for an already-disclosed phone; emergency hold takes precedence over conversational work) against the ordered guards in app/controllers/api/v1/linq_controller.rb#inbound.", "source": "" } ], "legacy_technical_anchors": [ "1-1-iphone-link-sms-entry-secure-signup-links-exists", "1-1-iphone-link-sms-entry-secure-signup-links" ], "node_contract": { "kind": "integration", "layer": "integration", "trigger": "A patient sends an inbound SMS or iMessage to the RonanRx Linq number.", "inputs": [ "deliver guarded response from Onboarding Agent" ], "outputs": [ "screen inbound turn to Medical Support Chat" ], "owner": "Patient Product", "operator": "Owning integration service and external counterparty", "completion": "Keep text messaging as the patient front door and carry each qualified patient into a secure, expiring signup flow.", "failure_retry": "Failures remain attributable and visible to the named owner; retry only the owning idempotent command and never invent success.", "system_of_record": "Rails LinqEvent and LinqConversation records; Linq is transport.", "actors": [ { "actor": "patient", "participation": "acts" } ], "domains": [ "onboarding" ], "journey_stage": "entry", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-01", "focus_nodes": [ "inbound", "safety-guards", "route-turn", "agent-reply", "delivery-authorization" ] } ] }, { "key": "1.2", "number": "1.2", "section": 1, "section_title": "Patient Entry & Onboarding", "id": "onboarding-agent", "title": "Onboarding Agent", "track": "patient", "business_anchor": "onboarding-agent", "technical_anchor": "1-2-onboarding-agent", "as_built_anchor": "onboarding-agent", "old_anchor": "1-2-onboarding-agent-exists", "flags": [ "board-node", "staging-reverified" ], "what_it_is": "The AI concierge that talks to every prospective patient over text: collects basic info, answers questions, and sends the signup link.", "target": { "summary": "Run focused onboarding conversations through Flue while Rails and Linq retain safety, consent, completion, and delivery responsibilities.", "gaps": [ "Choose and implement an explicit patient-facing failure policy if a deterministic fallback is still desired; current production deliberately logs and alerts without sending one.", "Finish the path inventory before changing SendGuard or any doctor, staff, reminder, or transactional delivery path." ] }, "open_decisions": [], "rules": [ { "id": "RRX-ONBOARDING-004", "text": "Onboarding conversation work runs in the focused Flue onboarding agent; Rails retains ingress controls, completion-link creation, and guarded delivery.", "enforcement": "Enforced in both production and staging: the deployed Rails web/worker services route authorized onboarding turns to the focused Flue service, while Rails retains authenticated ingress, dedupe, ordered safety and takeover guards, completion-link creation, SendGuard authorization, and delivery records. Verified against production main @ 2a346e1104d96f08193e921f08626aa29d1cd939 and staging @ 608c9d996eccf921f8d8c62031de84087a760d7d on 2026-07-30.", "source": "" }, { "id": "RRX-ONBOARDING-005", "text": "A model or service failure must fall back deterministically without sending duplicate or broken patient messages.", "enforcement": "Target rule, not currently enforced: Linq::AgentTurnJob logs and alerts on timeout or hard failure and sends no deterministic patient-facing fallback. Inbound and outbound dedupe still prevent duplicate messages, and invalid attachments are suppressed, but the previously documented AGENT_UNAVAILABLE floor is not present in the deployed Flue path.", "source": "" }, { "id": "RRX-ONBOARDING-006", "text": "Agent replies must preserve opt-out, emergency, human-takeover, and newer-inbound precedence.", "enforcement": "Enforced by: test/jobs/linq_reply_job_test.rb (newer-inbound supersession: an older/queued reply yields to a newer inbound) and test/jobs/linq_reply_job_takeover_test.rb (human takeover drops conversational/queued replies while governed emergency copy is still delivered); LinqReplyJob also returns on conversation.opt_out. On staging the Flue agent's reply routes through the same guard via supersede_on_newer_inbound.", "source": "" }, { "id": "RRX-ONBOARDING-007", "text": "Clinical boundaries stay within intake until Zach approves any broader Founder Mode or Doctor Bot behavior.", "enforcement": "Convention-only: honored by discipline. Founder Mode is confined to the onboarding intake spine and defers every clinical decision to the doctor (app/services/linq/founder_mode.rb), and no Doctor Bot ships on either branch, but nothing checks the 'Zach approves' gate ('Zach' appears nowhere in the repo).", "source": "" } ], "legacy_technical_anchors": [ "1-2-onboarding-agent-exists" ], "node_contract": { "kind": "ai-agent", "layer": "agent", "trigger": "A safety-screened, consented onboarding turn is routed by Rails.", "inputs": [ "start focused onboarding turn from Agent Router", "bound onboarding agent from Cam's Crack Commandments" ], "outputs": [ "deliver guarded response to iMessage (Linq)", "merge current clinical-floor JSONB to Intake 1: Basics", "merge state plus goal-or-medication handoff to Intake 1: Basics" ], "owner": "Patient Product", "operator": "Focused agent under Rails guards with human takeover", "completion": "Run focused onboarding conversations through Flue while Rails and Linq retain safety, consent, completion, and delivery responsibilities.", "failure_retry": "Failures remain attributable and visible to the named owner; retry only the owning idempotent command and never invent success.", "system_of_record": "agent.onboarding_records JSONB plus Rails conversation and delivery records.", "actors": [ { "actor": "patient", "participation": "subject" }, { "actor": "agent", "participation": "operates" } ], "domains": [ "onboarding" ], "journey_stage": "onboarding", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-01", "focus_nodes": [ "route-turn", "agent-turn", "partial-jsonb", "target-floor", "failure-alert", "secure-handoff" ] } ] }, { "key": "1.3", "number": "1.3", "section": 1, "section_title": "Patient Entry & Onboarding", "id": "signup-intake", "title": "Intake 1: Basics", "track": "patient", "business_anchor": "signup-intake", "technical_anchor": "1-3-intake-1-basics", "as_built_anchor": "signup-intake", "old_anchor": "1-3-info-1-goal-basic-bio-exists", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "The first information capture: the patient's goal and basic biography, taken conversationally.", "target": { "summary": "Make conversational Intake 1 handoff-eligible when service_state is present and either patient_goal or desired_medication is present; ask other approved basics best-effort, persist every answer/status once, and defer missing governed questions to the later intake.", "gaps": [ "Deploy the lighter service_state AND (patient_goal OR desired_medication) predicate; production still requires goal, current medications, allergies, conditions, and an addressed biometric beat.", "Project the Flue-captured service state through Rails handoff; OnboardingRecord.basics currently omits it and the job can fall back to a patient record that does not yet exist.", "Add capture_status_by_field and missing_for_later to the handoff, then add a later governed form that prefills known facts and asks only missing questions." ] }, "open_decisions": [], "rules": [ { "id": "RRX-ONBOARDING-008", "text": "Conversational Intake 1 becomes handoff-eligible when service_state is present and either patient_goal or desired_medication is present; medications, allergies, conditions, height, weight, identity offer, and other approved basics are best-effort and missing governed questions are deferred.", "enforcement": "Target rule, not deployed. Current Flue completion requires patientGoals, currentMedications, allergies, medicalConditions, and either height, weight, or a truthy biometricsAddressed value; state and desiredMeds do not gate completion. Flue captures fields.state, but Rails OnboardingRecord.basics does not project it, and no missing_for_later manifest or missing-only continuation form exists.", "source": "" }, { "id": "RRX-ONBOARDING-009", "text": "Reuse facts already supplied by the patient and never create a second account for the same verified phone identity.", "enforcement": "Enforced by: test/services/linq/signup_forward_test.rb - find_or_bootstrap takes the phone advisory lock and fails closed when a phone maps to multiple patients, and one phone-keyed intake plus its completion link are reused across conversations; captured answers are applied/reused rather than duplicated.", "source": "" }, { "id": "RRX-ONBOARDING-010", "text": "Patient-reported clinical facts retain source provenance when promoted into the EHR.", "enforcement": "Enforced by: DB CHECK constraint chk_ehr_contra_answers_source_provenance in db/structure.sql - every ehr_contraindication_answers row must carry a source (agent_chat/call_transcript/portal/doctor_entry) with the matching verification (patient_reported vs clinician_verified) and a provenance pointer (linq_event_id / pre_doctor_intake_id / source_artifact_id / recorded_by_id); model-tested in test/models/ehr/contraindication_answer_test.rb.", "source": "" } ], "legacy_technical_anchors": [ "1-3-info-1-goal-basic-bio-exists", "1-3-info-1-goal-basic-bio" ], "node_contract": { "kind": "workflow", "layer": "orchestration", "trigger": "The onboarding conversation supplies or updates a patient fact.", "inputs": [ "merge current clinical-floor JSONB from Onboarding Agent", "resume incomplete stage from Conversion Agent", "merge state plus goal-or-medication handoff from Onboarding Agent" ], "outputs": [ "open secure completion to ID Verification", "recover stalled intake to Conversion Agent" ], "owner": "Patient Product", "operator": "Named domain owner with authorized human review", "completion": "Make conversational Intake 1 handoff-eligible when service_state is present and either patient_goal or desired_medication is present; ask other approved basics best-effort, persist every answer/status once, and defer missing governed questions to the later intake.", "failure_retry": "Failures remain attributable and visible to the named owner; retry only the owning idempotent command and never invent success.", "system_of_record": "agent.onboarding_records JSONB before handoff; IntakeResponse/EHR after promotion.", "actors": [ { "actor": "patient", "participation": "acts" } ], "domains": [ "onboarding" ], "journey_stage": "onboarding", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-01", "focus_nodes": [ "field-capture", "partial-jsonb", "target-floor", "missing-manifest", "later-intake" ] }, { "subgraph_id": "sg-02", "focus_nodes": [ "identity-gate", "agreement-gate", "payment-gate", "care-choice" ] } ] }, { "key": "1.4", "number": "1.4", "section": 1, "section_title": "Patient Entry & Onboarding", "id": "sign-docs", "title": "Sign Docs / Agreement Packet", "track": "patient", "business_anchor": "sign-docs", "technical_anchor": "1-4-sign-docs-agreement-packet", "as_built_anchor": "sign-docs", "old_anchor": "1-4-sign-docs-agreement-packet-exists", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "The patient signs the legal agreement packet inside the signup wizard before paying.", "target": { "summary": "Require one complete, attributable agreement packet before payment, identity completion, or scheduling can finish.", "gaps": [] }, "open_decisions": [], "rules": [ { "id": "RRX-ONBOARDING-011", "text": "The patient signs the complete agreement packet; partial packets are not accepted.", "enforcement": "Enforced by: Portal::CompletionsController#packet_signature_complete? (app/controllers/portal/completions_controller.rb) rejects a partial packet with 422 and persists no Consent or PDF (requires e-sign agreed, a signer name, a real signature, and every one of the 7 contract documents signed); regression-tested in test/controllers/portal/completions_controller_test.rb (\"signing rejects an incomplete packet (422) without creating a consent or document\").", "source": "" }, { "id": "RRX-ONBOARDING-012", "text": "One intake produces one attributable packet, and re-signing requires a new governed packet version.", "enforcement": "Enforced by: Portal::CompletionsController#persist_packet_consent (app/controllers/portal/completions_controller.rb) is idempotent and intake-scoped -- one signed agreement_packet Consent per IntakeResponse, carrying packet_id + per-document attribution and linked back to the intake; a legitimate re-sign runs through a fresh intake. The governed packet version is pinned in config/text_authorization/agreement_packet_contract_v1.yml (packet_version); version bumps are by discipline, not a hard check.", "source": "" }, { "id": "RRX-ONBOARDING-013", "text": "Messaging and AI consent remains part of the required packet unless a later approved policy changes it.", "enforcement": "Enforced by: test/integration/ai_disclosure_copy_guard_test.rb -- fails closed if the Mobile Messaging & AI Consent (doc-07) copy is missing from config/text_authorization/agreement_packet_contract_v1.yml or the sign proto; the completeness gate requires all 7 packet documents signed, so this document cannot be dropped from the required packet.", "source": "" } ], "legacy_technical_anchors": [ "1-4-sign-docs-agreement-packet-exists" ], "node_contract": { "kind": "workflow", "layer": "orchestration", "trigger": "Secure completion reaches agreements after identity verification.", "inputs": [ "identity verified from ID Verification" ], "outputs": [ "all documents signed to Membership Pay" ], "owner": "Patient Product", "operator": "Named domain owner with authorized human review", "completion": "Require one complete, attributable agreement packet before payment, identity completion, or scheduling can finish.", "failure_retry": "Failures remain attributable and visible to the named owner; retry only the owning idempotent command and never invent success.", "system_of_record": "Sealed agreement packet and signature records.", "actors": [ { "actor": "patient", "participation": "acts" } ], "domains": [ "onboarding" ], "journey_stage": "onboarding", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-02", "focus_nodes": [ "packet-validation", "agreement-gate", "sealed-pdf", "signature-complete" ] } ] }, { "key": "1.5", "number": "1.5", "section": 1, "section_title": "Patient Entry & Onboarding", "id": "membership-subscription", "title": "Membership Pay", "track": "patient", "business_anchor": "membership-subscription", "technical_anchor": "1-5-membership-pay", "as_built_anchor": "membership-subscription", "old_anchor": "1-5-subscription-pay-platform-membership-exists", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "The patient's recurring platform membership payment, taken during signup.", "target": { "summary": "Keep the membership payment as a distinct platform charge and keep provider economics in the billing card.", "gaps": [] }, "open_decisions": [], "rules": [ { "id": "RRX-ONBOARDING-014", "text": "Membership remains a distinct RonanRx platform charge: first month free, then $39 per month, cancel anytime.", "enforcement": "Enforced externally: the $39/month membership Price and its monthly recurrence live in Stripe (STRIPE_PRICE_ID); first-month-free is applied via the \"first_month_free\" Stripe coupon (Billing::COUPON_ID) in Onboarding::ActivateSubscription (app/services/onboarding/activate_subscription.rb). The repo never hardcodes the dollar amount and no test asserts it; \"first month free, then $39/month, cancel anytime\" is display copy in app/services/onboarding/completion_state.rb.", "source": "" }, { "id": "RRX-ONBOARDING-015", "text": "Scheduling remains locked until required agreements, membership setup, and identity verification are complete.", "enforcement": "Enforced by: Portal::CompletionsController#step_accessible? (app/controllers/portal/completions_controller.rb) gates the schedule step on waiver_addressed? && payment_complete? && id_verified?, and #update_schedule re-checks schedule_bookable?; covered by test/controllers/portal/completions_controller_test.rb (\"schedule step is locked until payment is complete\", \"update_schedule is blocked until ID is verified\").", "source": "" }, { "id": "RRX-ONBOARDING-016", "text": "Stripe is the authoritative source for the active membership Price configuration.", "enforcement": "Enforced externally: Billing.price_id reads ENV STRIPE_PRICE_ID (app/lib/billing.rb) and Onboarding::ActivateSubscription passes it straight to Stripe::Subscription.create (app/services/onboarding/activate_subscription.rb); the active membership Price is defined and owned in the Stripe dashboard, not in the repo.", "source": "" } ], "legacy_technical_anchors": [ "1-5-subscription-pay-platform-membership-exists", "1-5-subscription-pay-platform-membership" ], "node_contract": { "kind": "integration", "layer": "integration", "trigger": "A complete agreement packet advances to membership payment.", "inputs": [ "all documents signed from Sign Docs / Agreement Packet", "activate membership webhook from Stripe 💳" ], "outputs": [ "membership active to Dr. Picker", "submit membership payment to Stripe 💳" ], "owner": "Patient Product", "operator": "Owning integration service and external counterparty", "completion": "Keep the membership payment as a distinct platform charge and keep provider economics in the billing card.", "failure_retry": "Failures remain attributable and visible to the named owner; retry only the owning idempotent command and never invent success.", "system_of_record": "Stripe objects reconciled to Rails billing records.", "actors": [ { "actor": "patient", "participation": "acts" } ], "domains": [ "onboarding" ], "journey_stage": "onboarding", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-02", "focus_nodes": [ "agreement-gate", "payment-gate", "care-choice" ] }, { "subgraph_id": "sg-14", "focus_nodes": [ "membership-charge", "webhook-ledger", "refund" ] } ] }, { "key": "1.6", "number": "1.6", "section": 1, "section_title": "Patient Entry & Onboarding", "id": "reengage-close-agent", "title": "Conversion Agent", "track": "patient", "business_anchor": "reengage-close-agent", "technical_anchor": "1-6-conversion-agent", "as_built_anchor": "reengage-close-agent", "old_anchor": "1-6-reengage-close-agent-partial", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "The recovery lane that brings a patient back after they stall before completing membership signup.", "target": { "summary": "Re-engage patients who stall between first contact and membership completion without duplicating messages or overriding consent and safety holds.", "gaps": [ "Cover stalled conversations, unopened secure links, unsigned packets, and unpaid memberships with a governed recovery lane." ] }, "open_decisions": [], "rules": [ { "id": "RRX-ONBOARDING-017", "text": "Recovery may target stalled conversations, unopened secure links, unsigned packets, and incomplete membership setup.", "enforcement": "Convention-only: nothing enforces this today; the reengagement/close agent and pre-payment funnel scanner are unbuilt (as-built §1.6 found no scanner for stalled intakes, unopened completion links, unsigned packets, or unpaid memberships). Only adjacent post-signup nudges (HealthHistoryNudge, WeighInNudge, PreDoctorIntakeReminders) and the manual SignupCompletionLinks::Resend exist.", "source": "" }, { "id": "RRX-ONBOARDING-018", "text": "Recovery messages respect consent, opt-out, safety holds, human takeover, and per-lane deduplication.", "enforcement": "Enforced by: app/services/linq/serialized_dispatch.rb + app/services/linq/send_guard.rb; the shared Linq send gate suppresses opt-out, human takeover, and red-flag/emergency holds, and rejects duplicate sends, for every outbound message (including all adjacent nudge/recovery paths); per-lane dedup is each nudge's own throttle (e.g. HealthHistoryNudge dedupe_key/MAX_SENDS). Verified in test/services/linq/send_guard_test.rb (opt-out and duplicate rejection).", "source": "" }, { "id": "RRX-ONBOARDING-019", "text": "Recovery stops immediately when the patient completes or deliberately exits the funnel.", "enforcement": "Partially enforced: opt-out (deliberate exit) halts all Linq outbound via app/services/linq/serialized_dispatch.rb, and each existing nudge lane stops on its own completion signal (HealthHistoryNudge skips at >=100% profile; PreDoctorIntakeReminders::Eligibility#reminder_allowed? stops at ready_for_clinician_review). No unified pre-payment recovery lane exists, so a single membership-completion stop is unbuilt (as-built §1.6).", "source": "" } ], "legacy_technical_anchors": [ "1-6-reengage-close-agent-partial", "1-6-reengage-close-agent" ], "node_contract": { "kind": "ai-agent", "layer": "agent", "trigger": "A governed onboarding stage stalls before membership completion.", "inputs": [ "recover stalled intake from Intake 1: Basics" ], "outputs": [ "resume incomplete stage to Intake 1: Basics" ], "owner": "Patient Product", "operator": "Focused agent under Rails guards with human takeover", "completion": "Re-engage patients who stall between first contact and membership completion without duplicating messages or overriding consent and safety holds.", "failure_retry": "No approved runtime exists. A future implementation must expose failures to the named owner and retry only under stable idempotency keys.", "system_of_record": "Owning domain records and agent audit events; no independent clinical side store.", "actors": [ { "actor": "patient", "participation": "subject" }, { "actor": "agent", "participation": "operates" } ], "domains": [ "onboarding" ], "journey_stage": "onboarding", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-01", "focus_nodes": [ "stalled-stage", "governed-reengage", "delivery-authorization", "secure-handoff" ] } ] }, { "key": "1.7", "number": "1.7", "section": 1, "section_title": "Patient Entry & Onboarding", "id": "id-verification", "title": "ID Verification", "track": "patient", "business_anchor": "id-verification", "technical_anchor": "1-7-id-verification", "as_built_anchor": "id-verification", "old_anchor": "1-7-id-verification-partial", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "Identity verification before scheduling, plus a provider's nonblocking attestation that the patient's ID was seen during the visit.", "target": { "summary": "Offer ID once in chat without pressure, defer gracefully when declined or unavailable, then require front-of-ID verification as the first secure-completion gate before the serial agreements, payment, and scheduling stages; retain the provider's nonblocking visit-time attestation.", "gaps": [ "Remove back-image capture only after the production evidence review required by the legacy-removal rule.", "Add explicit chat ID capture status instead of relying on the overloaded biometricsAddressed compatibility field." ] }, "open_decisions": [], "rules": [ { "id": "RRX-ONBOARDING-020", "text": "ID is offered once and remains optional in chat; refusal or unavailability is acknowledged without pressure, while the secure continuation starts with mandatory front-of-ID verification.", "enforcement": "Partially enforced: the Flue prompt asks for ID once, accepts refusal or unavailability, does not chase the patient, and defers verification to the secure link. Portal::CompletionsController starts the secure path at ID and blocks later secure stages until the front image is verified. Back-image storage remains as a legacy path when a back image is supplied.", "source": "" }, { "id": "RRX-ONBOARDING-021", "text": "Secure completion is serial: verified ID and serviceability, then the complete agreement packet, then payment, then video scheduling or governed asynchronous review.", "enforcement": "Enforced by Portal::CompletionsController step ordering and step_accessible? guards: id -> waiver -> payment -> schedule. Later stages cannot be opened or completed before the preceding gate, so signing, payment, and identity are not parallel.", "source": "" }, { "id": "RRX-ONBOARDING-022", "text": "The provider records whether the ID was seen during the visit, and an incomplete attestation warns without blocking note signing.", "enforcement": "Enforced by: Ehr::Workflows::SignEncounter#advise_telehealth (app/services/ehr/workflows/sign_encounter.rb) only logs a warning (never guard!) when the encounter's identity_verified / identity_verification_method attestation is incomplete, so note signing still proceeds; the provider records the attestation via the identity_verified checkbox and identity_verification_method field. Covered by test/services/ehr/workflows/note_signing_test.rb (\"signing tolerates blank visit timestamps ... (telehealth advisory)\" and signing succeeding with identity_verified false).", "source": "" } ], "legacy_technical_anchors": [ "1-7-id-verification-partial" ], "node_contract": { "kind": "workflow", "layer": "orchestration", "trigger": "The patient offers ID in chat or opens the first secure-completion gate.", "inputs": [ "open secure completion from Intake 1: Basics" ], "outputs": [ "identity verified to Sign Docs / Agreement Packet" ], "owner": "Patient Product", "operator": "Named domain owner with authorized human review", "completion": "Offer ID once in chat without pressure, defer gracefully when declined or unavailable, then require front-of-ID verification as the first secure-completion gate before the serial agreements, payment, and scheduling stages; retain the provider's nonblocking visit-time attestation.", "failure_retry": "Failures remain attributable and visible to the named owner; retry only the owning idempotent command and never invent success.", "system_of_record": "Identity document/verification records and encounter attestation.", "actors": [ { "actor": "patient", "participation": "acts" } ], "domains": [ "onboarding" ], "journey_stage": "onboarding", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-01", "focus_nodes": [ "chat-id-offer", "id-deferred", "secure-handoff" ] }, { "subgraph_id": "sg-02", "focus_nodes": [ "identity-gate", "serviceability", "agreement-gate", "payment-gate" ] } ] }, { "key": "2.1", "number": "2.1", "section": 2, "section_title": "Doctor Matching & Scheduling", "id": "doctor-picker", "title": "Dr. Picker", "track": "doctor", "business_anchor": "doctor-picker", "technical_anchor": "2-1-dr-picker", "as_built_anchor": "doctor-picker", "old_anchor": "2-1-dr-picker-preferences-routing-partial", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "The patient-facing doctor choice and matching experience for eligible providers.", "target": { "summary": "Match patients to eligible doctors by licensure, specialty, cost, and real availability while showing the complete eligible roster.", "gaps": [ "Add governed specialty mappings, patient-visible cost, and provider-controlled availability." ] }, "open_decisions": [], "rules": [ { "id": "RRX-SCHEDULING-001", "text": "Only providers eligible for the patient's state and program may be recommended or booked.", "enforcement": "Enforced by: test/services/onboarding/doctor_roster_test.rb; Onboarding::DoctorRoster keeps only doctors with an active, unexpired state license backed by an active credential (state-filter, inactive-credential, and expired-license cases all asserted). Note: it falls back to all active doctors when a data gap leaves none licensed (state serviceability is gated upstream), and program-level eligibility is not filtered in the roster.", "source": "" }, { "id": "RRX-SCHEDULING-002", "text": "Show the complete eligible roster while highlighting matches by specialty, cost, and availability.", "enforcement": "Partially enforced by: test/services/onboarding/doctor_roster_test.rb; the complete eligible active roster is returned and ordered by availability (round-robin on upcoming-visit count). Specialty and cost highlighting are unbuilt gaps; nothing enforces those.", "source": "" }, { "id": "RRX-SCHEDULING-003", "text": "Matching remains deterministic and auditable when candidates are otherwise equivalent.", "enforcement": "Enforced by: test/services/onboarding/doctor_roster_test.rb (\"orders by fewest upcoming booked visits (round-robin), then id\"); DoctorRoster sorts by [upcoming_count, user.id], a deterministic tie-break. Auditability is via reproducible determinism only; the match itself writes no audit log.", "source": "" } ], "legacy_technical_anchors": [ "2-1-dr-picker-preferences-routing-partial", "2-1-dr-picker-preferences-routing" ], "node_contract": { "kind": "surface", "layer": "experience", "trigger": "Identity, agreements, payment, and serviceability make the patient eligible to select care.", "inputs": [ "membership active from Membership Pay", "publish eligible provider from Provider Onboarding" ], "outputs": [ "request eligible slot to Booking" ], "owner": "Clinical Product", "operator": "Authorized patient, provider, or operations user", "completion": "Match patients to eligible doctors by licensure, specialty, cost, and real availability while showing the complete eligible roster.", "failure_retry": "Failures remain attributable and visible to the named owner; retry only the owning idempotent command and never invent success.", "system_of_record": "Provider eligibility, licenses, clinic, and availability records.", "actors": [ { "actor": "patient", "participation": "acts" }, { "actor": "doctor", "participation": "subject" } ], "domains": [ "onboarding" ], "journey_stage": "scheduling", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-03", "focus_nodes": [ "eligible-roster", "score-explain", "provider-choice", "slot-lock" ] } ] }, { "key": "2.2", "number": "2.2", "section": 2, "section_title": "Doctor Matching & Scheduling", "id": "appointment-setting", "title": "Booking", "track": "doctor", "business_anchor": "appointment-setting", "technical_anchor": "2-2-booking", "as_built_anchor": "appointment-setting", "old_anchor": "2-2-appointment-setting-partial", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "The patient books a video visit with their chosen doctor.", "target": { "summary": "Patients can book against real provider availability with tomorrow as the default earliest day and provider-controlled same-day access.", "gaps": [ "Integrate real calendar invitations and SMS across the EHR, patient app, and doctor picker." ] }, "open_decisions": [], "rules": [ { "id": "RRX-SCHEDULING-004", "text": "The default earliest appointment is tomorrow; same-day access is enabled per doctor with a doctor-configurable cutoff chosen during implementation.", "enforcement": "Not enforced (build diverges from the rule): Onboarding::ScheduleSlots uses a fixed 3-day minimum lead (MIN_LEAD_DAYS=3), not a tomorrow default, and has no per-doctor same-day cutoff; only a hardcoded, self-expiring ADHOC_WINDOWS exemption. test/services/onboarding/schedule_slots_test.rb asserts the 3-day rule. Same on origin/staging.", "source": "" }, { "id": "RRX-SCHEDULING-005", "text": "The scheduling lookahead is configurable; its default is a build-time product setting, not a standing decision.", "enforcement": "Convention-only: the lookahead is the build-time constant Onboarding::ScheduleSlots::LOOKAHEAD_DAYS (=14) in app/services/onboarding/schedule_slots.rb; edited in code, not runtime-configurable, and no test asserts configurability.", "source": "" }, { "id": "RRX-SCHEDULING-006", "text": "Provider calendars and RonanRx availability synchronize in both directions.", "enforcement": "Not enforced: calendar sync is one-way only; RonanRx to doctor via a read-only ICS feed (app/models/doctor_calendar_feed.rb, app/services/calendar/ics.rb, app/controllers/doctor/calendar_feeds_controller.rb) plus a patient \"add to Google Calendar\" template link. Availability is synthetic (ScheduleSlots) and no provider free/busy is ingested back; two-way sync is unbuilt (same on origin/staging).", "source": "" }, { "id": "RRX-SCHEDULING-007", "text": "Cancellation retains the appointment record and its audit history.", "enforcement": "Enforced by: test/services/onboarding/cancel_appointment_test.rb; Onboarding::CancelAppointment soft-cancels (status -> cancelled, row retained and never destroyed) and writes an appointment_cancelled Event with actor; the test asserts the retained cancelled row and the Event.", "source": "" }, { "id": "RRX-SCHEDULING-008", "text": "Ops rebooking is audited and preserves chart-access controls.", "enforcement": "Enforced by: test/services/ops/integration/appointment_gateway_test.rb; Ops rebook seeds the care-team chart-access row (Ehr::CareTeamMembership) to grant chart access without relaxing any clinic filter; the reschedule audit Event (completion_appointment_rescheduled) is asserted in test/services/onboarding/book_appointment_test.rb.", "source": "" } ], "legacy_technical_anchors": [ "2-2-appointment-setting-partial", "2-2-appointment-setting" ], "node_contract": { "kind": "workflow", "layer": "orchestration", "trigger": "The patient selects an eligible provider or async-review path.", "inputs": [ "request eligible slot from Dr. Picker" ], "outputs": [ "activate pre-visit intake to Intake 2: Pre-Appointment", "schedule reminders to Appointment Reminders", "create visit encounter to Appointment", "assemble visit brief to Pre-Brief" ], "owner": "Clinical Product", "operator": "Named domain owner with authorized human review", "completion": "Patients can book against real provider availability with tomorrow as the default earliest day and provider-controlled same-day access.", "failure_retry": "Failures remain attributable and visible to the named owner; retry only the owning idempotent command and never invent success.", "system_of_record": "Appointment and slot-lock records.", "actors": [ { "actor": "patient", "participation": "acts" }, { "actor": "doctor", "participation": "acts" } ], "domains": [ "onboarding" ], "journey_stage": "scheduling", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-03", "focus_nodes": [ "provider-choice", "real-availability", "slot-lock", "booking-commit", "cancel-rebook" ] } ] }, { "key": "2.3", "number": "2.3", "section": 2, "section_title": "Doctor Matching & Scheduling", "id": "pre-doctor-intake", "title": "Intake 2: Pre-Appointment", "track": "doctor", "business_anchor": "pre-doctor-intake", "technical_anchor": "2-3-intake-2-pre-appointment", "as_built_anchor": "pre-doctor-intake", "old_anchor": "2-3-info-2-triage-questions-pre-doctor-intake-partial", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "Structured pre-visit medical questions so the doctor walks in informed.", "target": { "summary": "Collect governed pre-visit answers automatically, stop completion reminders when finished, and keep incomplete intake visible without cancelling the visit.", "gaps": [ "Implement the day-before, morning-of, and T-5 cadence plus the incomplete-intake Ops queue.", "Expand beyond a single GLP-1 question set when additional specialties are approved." ] }, "open_decisions": [], "rules": [ { "id": "RRX-SCHEDULING-009", "text": "Send intake-completion reminders the day before, the morning of, and five minutes before the visit.", "enforcement": "Not enforced: the day-before / morning-of / T-5 intake-reminder cadence is unbuilt. PreDoctorIntakeReminders::Notifier only ships a throttled nudge (MAX_SENDS / THROTTLE_WINDOW) invoked by hand via Ops::Commands::PreDoctorIntakeReminder; there is no scheduler for it in config/recurring.yml (confirmed on main and origin/staging).", "source": "" }, { "id": "RRX-SCHEDULING-010", "text": "Stop completion reminders when intake is complete without suppressing the ordinary appointment reminder.", "enforcement": "Enforced by: test/services/pre_doctor_intake_reminders/notifier_test.rb (the 'ready intake is excluded and a queued reminder is dropped if readiness changes' test stops the nudge once intake status is ready_for_clinician_review; the intake-reminder lane is a separate template/switch from the ordinary Appointments reminder lane, so it does not suppress it).", "source": "" }, { "id": "RRX-SCHEDULING-011", "text": "Incomplete intake remains visible in the Pre-Brief and enters an Ops queue; it does not automatically cancel or reschedule the visit.", "enforcement": "Enforced by: test/services/pre_doctor_intake_reminders/notifier_test.rb (incomplete tuples surface in the Ops queue via Ops::Diagnostics::PreVisitIntakeCandidates and drop out once ready) and test/integration/ehr/schedule_test.rb (incomplete/absent intake stays visible on the Pre-Brief); no code cancels or reschedules on incomplete intake, so the non-cancellation clause holds by absence.", "source": "" }, { "id": "RRX-SCHEDULING-012", "text": "Message controls for this lane must not suppress unrelated patient communication.", "enforcement": "Enforced by: test/services/pre_doctor_intake_reminders/notifier_test.rb (the 'reminder delivery has an independent default-off switch' test proves the PRE_DOCTOR_INTAKE_REMINDER send mode is independent of LINQ_TEXTFLOW_AUTOREPLY_MODE, so toggling this lane does not gate other patient messaging).", "source": "" } ], "legacy_technical_anchors": [ "2-3-info-2-triage-questions-pre-doctor-intake-partial", "2-3-info-2-triage-questions-pre-doctor-intake" ], "node_contract": { "kind": "workflow", "layer": "orchestration", "trigger": "A video appointment is booked and its intake plan activates.", "inputs": [ "activate pre-visit intake from Booking" ], "outputs": [ "attach ready intake packet to Pre-Brief" ], "owner": "Clinical Product", "operator": "Named domain owner with authorized human review", "completion": "Collect governed pre-visit answers automatically, stop completion reminders when finished, and keep incomplete intake visible without cancelling the visit.", "failure_retry": "Failures remain attributable and visible to the named owner; retry only the owning idempotent command and never invent success.", "system_of_record": "PreDoctorIntake and promoted EHR facts.", "actors": [ { "actor": "patient", "participation": "acts" }, { "actor": "doctor", "participation": "subject" } ], "domains": [ "onboarding" ], "journey_stage": "pre-visit", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-03", "focus_nodes": [ "intake-activation", "known-fact-prefill", "missing-questions", "ready-packet", "ops-queue" ] } ] }, { "key": "2.4", "number": "2.4", "section": 2, "section_title": "Doctor Matching & Scheduling", "id": "meeting-reminders", "title": "Appointment Reminders", "track": "doctor", "business_anchor": "meeting-reminders", "technical_anchor": "2-4-appointment-reminders", "as_built_anchor": "meeting-reminders", "old_anchor": "2-4-meeting-reminders-partial", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "Automated appointment reminders for both patients and doctors.", "target": { "summary": "Give each provider independent beginning-of-day, T-1-hour, and T-5-minute SMS and email controls while preserving patient reminders.", "gaps": [ "Build the six provider controls and support patients who do not yet have a text thread." ] }, "open_decisions": [], "rules": [ { "id": "RRX-SCHEDULING-013", "text": "Each provider independently controls beginning-of-day, one-hour, and five-minute SMS and email notifications.", "enforcement": "Not enforced: the six per-provider begin-of-day / 1h / 5-min SMS+email controls are unbuilt. The only reminder path (Appointments::ReminderDispatcher, config/recurring.yml every 15 min) sends patient-facing T-24h and T-1h Linq texts with no provider toggles, no beginning-of-day or T-5 window, and no email channel.", "source": "" }, { "id": "RRX-SCHEDULING-014", "text": "Use the provider's maintained reminder phone and email.", "enforcement": "Not enforced: there is no provider-facing SMS/email reminder delivery and no maintained provider reminder phone/email field (none in db/structure.sql); this rule presupposes the unbuilt provider-reminder controls.", "source": "" }, { "id": "RRX-SCHEDULING-015", "text": "Calendar and reminder links open the authenticated Pre-Brief and never place PHI in the notification payload.", "enforcement": "Partially enforced: the PHI-free-payload half holds; Enforced by: test/services/calendar/ics_test.rb (calendar events carry only time, a generic 'RonanRx visit' title, and the /v visit-token link; no patient name, no drug, no Meet URL), and SMS reminders run through Linq::SendGuard's PHI/URL audit. The 'links open the authenticated Pre-Brief' half is not built: calendar and reminder links open the patient /v visit-token gate, not the Pre-Brief, and per-provider reminders are unbuilt.", "source": "" } ], "legacy_technical_anchors": [ "2-4-meeting-reminders-partial", "2-4-meeting-reminders" ], "node_contract": { "kind": "deterministic-automation", "layer": "automation", "trigger": "A live booking crosses a configured reminder offset.", "inputs": [ "schedule reminders from Booking" ], "outputs": [ "send arrival prompts to Appointment" ], "owner": "Clinical Product", "operator": "Rails worker or scheduled domain service", "completion": "Give each provider independent beginning-of-day, T-1-hour, and T-5-minute SMS and email controls while preserving patient reminders.", "failure_retry": "Failures remain attributable and visible to the named owner; retry only the owning idempotent command and never invent success.", "system_of_record": "Appointment plus idempotent delivery ledger.", "actors": [ { "actor": "patient", "participation": "receives" }, { "actor": "doctor", "participation": "subject" }, { "actor": "agent", "participation": "operates" } ], "domains": [ "onboarding", "follow-up" ], "journey_stage": "pre-visit", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-03", "focus_nodes": [ "reminder-schedule", "live-recheck", "dedupe-send", "skip-or-fail" ] } ] }, { "key": "2.5", "number": "2.5", "section": 2, "section_title": "Doctor Matching & Scheduling", "id": "pre-brief", "title": "Pre-Brief", "track": "doctor", "business_anchor": "pre-brief", "technical_anchor": "2-5-pre-brief", "as_built_anchor": "pre-brief", "old_anchor": "2-5-pre-brief-partial", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "A concise, context-aware pre-appointment briefing linked from the doctor's calendar and enabled T-5 SMS/email reminders.", "target": { "summary": "Open an authenticated, context-aware Pre-Brief from the provider's calendar and enabled reminders without placing PHI in calendar payloads.", "gaps": [ "Unify the brief around appointment purpose, intake, medications, allergies, vitals, relevant labs, history, flags, and the visit link." ] }, "open_decisions": [], "rules": [ { "id": "RRX-SCHEDULING-016", "text": "The Pre-Brief includes appointment purpose, conditions, symptoms, medications, allergies, follow-up questions, intake and flags, height, weight, BMI, relevant labs, relevant history, and the visit link.", "enforcement": "Partially enforced by: test/integration/ehr/schedule_test.rb (the 'pre-call brief renders intake background chart safety context' test asserts goal, conditions, symptoms, intake weight, medications, allergies, must-ask questions, governed-intake status + flag count, and the visit/join link). Height, BMI, and relevant labs/history are not yet surfaced on the brief (Ehr::Integration::PreCallBrief builds none of them); those parts are unverified/unbuilt.", "source": "" }, { "id": "RRX-SCHEDULING-017", "text": "The provider can reach the full chart and all labs from the brief.", "enforcement": "Enforced by: test/integration/ehr/schedule_test.rb (the 'renders and links the governed packet' test asserts the brief's 'See full chart' link resolves to ehr_chart_path(anchor: medical-history) and that following it opens the full patient chart, which contains the Results/labs section).", "source": "" }, { "id": "RRX-SCHEDULING-018", "text": "Incomplete intake is explicit and does not automatically cancel or reschedule the appointment.", "enforcement": "Enforced by: test/integration/ehr/schedule_test.rb (the 'honest empty chart states' test asserts explicit 'No intake response is available' / 'Not recorded' rendering and 'X of Y resolved' intake status on the brief); nothing in the schedule/brief flow cancels or reschedules on incomplete intake, so the non-cancellation clause holds by absence.", "source": "" }, { "id": "RRX-SCHEDULING-019", "text": "Brief content requires authentication and never appears directly in a calendar payload.", "enforcement": "Enforced by: test/integration/ehr/schedule_test.rb (patient and anonymous sessions are redirected away from the schedule/brief, and the brief URL/title carry no patient name) and test/services/calendar/ics_test.rb (the calendar payload carries no PHI; only times, a generic title, and the /v visit-token link).", "source": "" } ], "legacy_technical_anchors": [ "2-5-pre-brief-partial" ], "node_contract": { "kind": "deterministic-automation", "layer": "automation", "trigger": "An authorized provider opens the visit briefing or receives an enabled reminder.", "inputs": [ "assemble visit brief from Booking", "attach ready intake packet from Intake 2: Pre-Appointment", "add medical history from Intake 3: Medical History", "add cited prior records from Previous Charts / Records Ingestion", "add approved device signals from Device Data", "attach cited research from Medical Research Agent" ], "outputs": [ "present clinical brief to Appointment" ], "owner": "Clinical Product", "operator": "Rails worker or scheduled domain service", "completion": "Open an authenticated, context-aware Pre-Brief from the provider's calendar and enabled reminders without placing PHI in calendar payloads.", "failure_retry": "Failures remain attributable and visible to the named owner; retry only the owning idempotent command and never invent success.", "system_of_record": "EHR and appointment records; the briefing is a projection.", "actors": [ { "actor": "patient", "participation": "receives" }, { "actor": "doctor", "participation": "reviews" }, { "actor": "agent", "participation": "operates" } ], "domains": [ "onboarding", "labs" ], "journey_stage": "pre-visit", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-03", "focus_nodes": [ "intake-activation", "source-fan-in", "missing-labels", "ready-packet" ] } ] }, { "key": "2.6", "number": "2.6", "section": 2, "section_title": "Doctor Matching & Scheduling", "id": "doctor-visit", "title": "Appointment", "track": "doctor", "business_anchor": "doctor-visit", "technical_anchor": "2-6-appointment", "as_built_anchor": "doctor-visit", "old_anchor": "2-6-dr-appointment-meet-exists", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "The video visit itself.", "target": { "summary": "Run each authorized video appointment in its per-appointment Google Meet space, automatically record and transcribe it, and keep the raw Google artifacts bound to the appointment for downstream clinical documentation.", "gaps": [ "Turn native Google Meet automatic recording on and ingest every generated recording reference; automatic transcription and transcript ingest exist today.", "Verify the recording-capable Workspace policy and Meet and Drive scopes required to retrieve organizer-owned recordings before rollout." ] }, "open_decisions": [], "rules": [ { "id": "RRX-SCHEDULING-020", "text": "Automatically record and transcribe every authorized video appointment under the signed telehealth agreement and Google's participant notice, and retain the raw Google artifacts for clinical-note support.", "enforcement": "Partially enforced: per-appointment Meet spaces set autoTranscriptionGeneration to ON, transcript ingest stores the transcript and drives the note draft, and authorization remains appointment-bound. GoogleWorkspace::MeetClient hard-codes autoRecordingGeneration to OFF, and no recording reference ingest or Drive recording download exists. Recording consent rides on the signed telehealth agreement.", "source": "" }, { "id": "RRX-SCHEDULING-021", "text": "Image-assisted visual observation drafting follows the Visit Observation controls in §2.7; the provider edits and approves the final observation text through the Clinical Note workflow in §3.1.", "enforcement": "Partially supported only by the existing transcript-derived NoteDraft scaffold, doctor editing, and doctor signature gate. No Visit Observation image input, image citation, or visual-observation draft exists.", "source": "" }, { "id": "RRX-SCHEDULING-022", "text": "A doctor remains the final signer for the visit note and every prescription decision.", "enforcement": "Code-gate: Ehr::Workflows::SignEncounter raises 'Only a doctor may sign' unless actor.doctor? (app/services/ehr/workflows/sign_encounter.rb:35), and Ehr::Workflows::IssuePrescription / ConfirmPrescription raise 'Only a doctor may issue/confirm a prescription' unless actor.doctor? (app/services/ehr/workflows/issue_prescription.rb:9).", "source": "" }, { "id": "RRX-SCHEDULING-023", "text": "Visit access and recording artifacts must remain bound to the authorized appointment.", "enforcement": "Code-gate: Workflows::AuthorizeAppointmentJoin is the only path that releases a Meet URL and refuses unless the appointment is booked and inside its join window (app/services/workflows/authorize_appointment_join.rb); the Meet room is provisioned one-per-appointment (Appointments::MeetRoom / MeetSpace), and the schedule fences cross-clinic / cross-doctor visit access (verified in test/integration/ehr/schedule_test.rb).", "source": "" } ], "legacy_technical_anchors": [ "2-6-dr-appointment-meet-exists", "2-6-dr-appointment-meet" ], "node_contract": { "kind": "integration", "layer": "integration", "trigger": "An authorized patient and provider join the appointment Meet room.", "inputs": [ "create visit encounter from Booking", "present clinical brief from Pre-Brief", "send arrival prompts from Appointment Reminders" ], "outputs": [ "capture encounter frames to Visit Observation", "open encounter note to Clinical Note" ], "owner": "Clinical Product", "operator": "Owning integration service and external counterparty", "completion": "Run each authorized video appointment in its per-appointment Google Meet space, automatically record and transcribe it, and keep the raw Google artifacts bound to the appointment for downstream clinical documentation.", "failure_retry": "Failures remain attributable and visible to the named owner; retry only the owning idempotent command and never invent success.", "system_of_record": "Appointment record plus Google Meet artifact references.", "actors": [ { "actor": "patient", "participation": "acts" }, { "actor": "doctor", "participation": "acts" } ], "domains": [ "clinical-care" ], "journey_stage": "encounter", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-04", "focus_nodes": [ "room-authorization", "consent-check", "meet-artifacts", "artifact-sweep", "encounter-handoff" ] } ] }, { "key": "2.7", "number": "2.7", "section": 2, "section_title": "Doctor Matching & Scheduling", "id": "visit-observation", "title": "Visit Observation", "track": "doctor", "business_anchor": "visit-observation", "technical_anchor": "2-7-visit-observation", "as_built_anchor": "visit-observation", "old_anchor": "2-7-visit-observation-future", "flags": [ "board-node" ], "what_it_is": "The automatic creation of seven candidate screenshots from a recorded appointment, their addition to the EHR, and their use as attributable inputs to the doctor-reviewed clinical-note draft after the doctor confirms the visible subject.", "target": { "summary": "After each authorized video appointment, consume the native recording and transcription artifacts governed by §2.6, add seven technically usable candidate screenshots sampled across patient-speaking portions to the EHR, require the doctor to confirm the visible subject before an image can inform neutral visual documentation, and let the doctor delete any image before or after reviewing the note.", "gaps": [ "Consume the native recording and transcription artifacts governed by §2.6 through the existing post-call sweep and an authorized Drive recording download.", "Add deterministic patient-speaking interval selection, seven-frame extraction, technical quality checks, idempotent EHR attachment, and explicit partial-capture states.", "Add an explicit subject-unverified state, a doctor confirmation surface, and image-assisted observation drafting that accepts only doctor-confirmed source images.", "Add single-image and delete-all doctor actions that remove image bytes from the active chart and note-drafting inputs while preserving content-free audit evidence." ] }, "open_decisions": [], "rules": [ { "id": "RRX-SCHEDULING-024", "text": "Visit Observation consumes only the native Google Meet recording and transcription artifacts governed by §2.6; it requires no separate bot or Workspace-account participant and never initiates a second recording.", "enforcement": "Partially supported: per-appointment Meet spaces and automatic transcription exist, but GoogleWorkspace::MeetClient hard-codes autoRecordingGeneration to OFF and no recording-ingest workflow is user-usable.", "source": "Google Meet REST API meeting-space artifact configuration" }, { "id": "RRX-SCHEDULING-025", "text": "After the recording and transcript are available, RonanRx automatically attempts seven screenshots spread across patient-attributed speaking intervals; no doctor capture action or approval is required before technically usable candidate images enter the EHR with their visual subject marked unverified.", "enforcement": "Not enforced: no recording download, patient-speaking interval selector, frame extractor, or automatic image attachment exists.", "source": "" }, { "id": "RRX-SCHEDULING-026", "text": "The seven targets are distributed across the eligible patient-speaking timeline so that the image set represents early, middle, and late portions of the appointment rather than seven adjacent moments; selection optimizes time coverage and technical usability only and never chooses frames because the patient looks more normal, favorable, or reassuring.", "enforcement": "Not enforced: no screenshot selection workflow exists.", "source": "" }, { "id": "RRX-SCHEDULING-027", "text": "Patient speech attribution selects candidate times but does not prove that the recorded pixels show the patient. A frame enters the EHR as subject-unverified only when it decodes successfully, passes the configured resolution, black-or-frozen-frame, and duplicate checks, and comes from an interval attributed to the appointment's patient; failed targets are retried within their source interval and never replaced with a frame from another participant or appointment.", "enforcement": "Not enforced: no frame quality, speaker-source, subject-verification state, retry, duplicate, or wrong-source rejection checks exist.", "source": "" }, { "id": "RRX-SCHEDULING-028", "text": "If fewer than seven eligible candidate frames exist, RonanRx adds every technically usable frame automatically, records the actual count and reason, and continues the clinical-note workflow without inventing or duplicating images.", "enforcement": "Not enforced: no screenshot artifact or partial-capture state exists.", "source": "" }, { "id": "RRX-SCHEDULING-029", "text": "Each screenshot is added automatically to the correct patient and appointment record with capture time, appointment offset, source conference and recording, source transcript interval and participant, image checksum, extraction version, quality results, visual-subject verification state, confirming doctor and confirmation time when applicable, and creation time.", "enforcement": "Not enforced: meet_spaces and ehr_video_sessions bind conferences and transcripts to appointments, but no image artifact or image-level provenance exists.", "source": "" }, { "id": "RRX-SCHEDULING-030", "text": "The clinical-note draft may use only active screenshots whose visible subject the assigned doctor has confirmed is the patient. Presented content, layout-only frames, and any image whose subject the doctor cannot confirm are excluded from image-derived text. Eligible images may support only visible, time-bound observations such as grooming, attire, posture, facial expression, whether the eyes are visibly open, and gaze direction across sampled frames; the draft identifies the image set as sampled evidence and states material image limitations.", "enforcement": "Partially supported only by the existing editable transcript-derived note draft; no image input, doctor subject-confirmation gate, visual-observation schema, image citations, or sampled-evidence limitation text exists.", "source": "APA Telepsychiatry Toolkit" }, { "id": "RRX-SCHEDULING-031", "text": "No screenshot or model output independently classifies alertness, orientation, attention, cooperation, speech, thought process, psychomotor activity, intoxication, sobriety, credibility, deception, medication-seeking intent, diagnosis, protected characteristics, or prescribing eligibility; the doctor-only clinical and prescribing decision gates in §2.6 and §3.1 remain controlling.", "enforcement": "Not enforced: no image workflow or image-output policy test exists.", "source": "ASAM/AAAP Clinical Practice Guideline on Stimulant Use Disorder" }, { "id": "RRX-SCHEDULING-032", "text": "The doctor can delete any screenshot or all screenshots from the appointment record with one action; deletion immediately removes it from active chart display, future exports, and note-drafting inputs, offers a short undo window, then deletes the stored image bytes unless an applicable legal hold requires restricted retention, while retaining a content-free audit tombstone with image id, checksum, actor, and time. A legal hold never restores ordinary chart display. Screenshot deletion does not delete the source Meet recording.", "enforcement": "Not enforced: no screenshot storage, chart display, deletion action, undo window, object deletion, note-input invalidation, or image audit tombstone exists.", "source": "" }, { "id": "RRX-SCHEDULING-033", "text": "Deleting an image before note signing invalidates draft text derived from it and refreshes the visual-observation draft only when the doctor has not edited that text; clinician-edited text is never overwritten and instead receives a changed-source notice and optional refreshed suggestion. Deleting an image after signing never silently rewrites the signed note and instead offers the existing amendment path.", "enforcement": "Partially supported only by the existing signed-note immutability and amendment workflows; no image dependency or draft invalidation exists.", "source": "" }, { "id": "RRX-SCHEDULING-034", "text": "Duplicate sweeps, recording events, downloads, frame retries, and job retries never create duplicate EHR images or duplicate observation text, and they never recreate an image the doctor deleted.", "enforcement": "Not enforced: no recording-to-image workflow or its idempotency keys exist.", "source": "" }, { "id": "RRX-SCHEDULING-035", "text": "Each Visit Observation failure, including recording delay, unavailable media, ambiguous speaker attribution, unconfirmed visual subject, fewer than seven usable frames, image-analysis failure, or image deletion, is explicit and follows the §3.1 nonblocking optional-input policy; it never blocks appointment completion, doctor note editing, note signing, or a prescription decision.", "enforcement": "Not enforced: no screenshot workflow or failure states exist.", "source": "" } ], "node_contract": { "kind": "deterministic-automation", "layer": "automation", "trigger": "A consented appointment recording and transcript become available.", "inputs": [ "capture encounter frames from Appointment" ], "outputs": [ "attach confirmed observations to Clinical Note" ], "owner": "Clinical Product", "operator": "Rails worker or scheduled domain service", "completion": "After each authorized video appointment, consume the native recording and transcription artifacts governed by §2.6, add seven technically usable candidate screenshots sampled across patient-speaking portions to the EHR, require the doctor to confirm the visible subject before an image can inform neutral visual documentation, and let the doctor delete any image before or after reviewing the note.", "failure_retry": "No approved runtime exists. A future implementation must expose failures to the named owner and retry only under stable idempotency keys.", "system_of_record": "EHR source artifacts, candidate images, confirmations, citations, and tombstones.", "actors": [ { "actor": "doctor", "participation": "reviews" }, { "actor": "agent", "participation": "operates" } ], "domains": [ "clinical-care" ], "journey_stage": "encounter", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-05", "focus_nodes": [ "speaking-intervals", "sample-frames", "quality-dedupe", "doctor-confirm", "note-citations", "tombstone" ] } ] }, { "key": "3.1", "number": "3.1", "section": 3, "section_title": "EHR & Prescribing", "id": "charting-ehr", "title": "Clinical Note", "track": "doctor", "business_anchor": "charting-ehr", "technical_anchor": "3-1-clinical-note", "as_built_anchor": "charting-ehr", "old_anchor": "3-1-charting-ehr-partial", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "The appointment-centered clinical record for SOAP notes, problems, allergies, medications, vitals, amendments, and access history.", "target": { "summary": "Make SOAP the default appointment-note structure, accept attributable, doctor-confirmed Visit Observation (§2.7) inputs for doctor-editable visual documentation, preserve full chart audit history, and keep nonfatal observability failures from blocking care.", "gaps": [ "Align note defaults and audit-failure behavior with the nonblocking policy and complete the safe appointment terminology migration.", "Accept active, doctor-confirmed Visit Observation image citations and doctor-editable visual-observation text without weakening signed-note immutability." ] }, "open_decisions": [], "rules": [ { "id": "RRX-EHR-001", "text": "SOAP is the default structured appointment-note format, including AI-assisted drafts.", "enforcement": "Contradicted by code today: Ehr::ClinicalNote#new_notes_are_compact requires note_type == \"hpi_mdm\" for every new note (SOAP accepted only via legacy_import) and Ehr::Agents::NoteDraft defaults AI drafts to hpi_mdm; SOAP is NOT the default (intent/implementation drift, card gap). See test/models/ehr/clinical_note_test.rb (\"new soap note is invalid without legacy_import\").", "source": "" }, { "id": "RRX-EHR-002", "text": "The appointment's authorized provider remains the final signer and must re-authenticate when required.", "enforcement": "Enforced by: app/services/ehr/workflows/sign_encounter.rb and app/services/ehr/workflows/issue_prescription.rb (guard actor.id == record.provider_id and actor.reauth_fresh? before signing/issuing, raising Workflows::InvalidTransition; issuance also blocks a non-signer via \"Appointment signer must issue prescription\").", "source": "" }, { "id": "RRX-EHR-003", "text": "Every chart access and mutation is attributable and preserved in the audit history.", "enforcement": "Enforced by: app/services/ehr/access/chart_access_policy.rb (every authorized access writes an append-only Ehr::ChartAccessLog keyed to the actor, readonly once persisted, and fails closed if the audit row cannot be written) plus per-workflow Ehr::Integration::Audit.event!/gate! carrying the actor on each mutation; asserted in test/services/ehr/workflows/audit_legal_test.rb.", "source": "" }, { "id": "RRX-EHR-004", "text": "An incomplete optional section or nonfatal observability failure warns and reports; it does not block care or note signing.", "enforcement": "Enforced by: test/services/ehr/workflows/note_signing_test.rb (telehealth facts, primary-diagnosis, and unsupported AI signal are advisory and never block signing; sign_encounter.rb only Rails.logger.warn's them). Caveat: chart-access/break-glass audit still fails closed, so audit-failure nonblocking is not yet aligned (card gap).", "source": "" } ], "legacy_technical_anchors": [ "3-1-charting-ehr-partial", "3-1-charting-ehr" ], "node_contract": { "kind": "registry", "layer": "data", "trigger": "An appointment produces attributable clinical artifacts or clinician entries.", "inputs": [ "open encounter note from Appointment", "attach confirmed observations from Visit Observation", "cite prior record facts from Previous Charts / Records Ingestion", "project patient history from Intake 3: Medical History", "enforce canonical schema from EHR Schema Cleanup", "project governed observations from Device Data" ], "outputs": [ "start prescription decision to Prescription Generation", "place independent lab order to Order Labs" ], "owner": "Clinical Product", "operator": "Authorized domain steward", "completion": "Make SOAP the default appointment-note structure, accept attributable, doctor-confirmed Visit Observation (§2.7) inputs for doctor-editable visual documentation, preserve full chart audit history, and keep nonfatal observability failures from blocking care.", "failure_retry": "Failures remain attributable and visible to the named owner; retry only the owning idempotent command and never invent success.", "system_of_record": "EHR encounter, note, amendment, medication, allergy, problem, and audit records.", "actors": [ { "actor": "doctor", "participation": "reviews" } ], "domains": [ "labs" ], "journey_stage": "clinical-decision", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-04", "focus_nodes": [ "encounter-handoff", "draft-note", "doctor-edit", "signed-note", "amendment" ] }, { "subgraph_id": "sg-05", "focus_nodes": [ "doctor-confirm", "note-citations", "invalidation", "tombstone" ] } ] }, { "key": "3.2", "number": "3.2", "section": 3, "section_title": "EHR & Prescribing", "id": "prescription-generation", "title": "Prescription Generation", "track": "doctor", "business_anchor": "prescription-generation", "technical_anchor": "3-2-prescription-generation", "as_built_anchor": "prescription-generation", "old_anchor": "3-2-rx-prescription-generation-exists", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "The doctor issues a prescription from a signed appointment note (internally an `Ehr::Encounter`).", "target": { "summary": "Let a licensed clinician issue a complete prescription from a signed appointment note, using the medication catalog and approved dose boundaries.", "gaps": [ "Allow exactly ten-percent dose differences, obtain clinical approval for reference strengths, enforce the monthly standard-dose limit, and remove vestigial DEA gates." ] }, "open_decisions": [], "rules": [ { "id": "RRX-EHR-005", "text": "Prescription confirmation requires medication, strength, directions, form, route, frequency, quantity, and clinical rationale.", "enforcement": "Enforced by: app/services/ehr/workflows/confirm_prescription.rb (guard! on Prescribing::REQUIRED_RX_FIELDS = medication_name, strength, directions, form, route, frequency, quantity, clinical_rationale) and re-checked at issue in app/services/ehr/integration/prescribing.rb#validate_required_rx_fields!; asserted in test/services/ehr/workflows/prescription_confirmation_test.rb.", "source": "" }, { "id": "RRX-EHR-006", "text": "A custom compounded dose may differ from an approved reference strength by exactly ten percent or more; less than ten percent is blocked.", "enforcement": "Enforced by: app/services/ehr/integration/dose_guardrail.rb (DoseGuardrail.enforce! raises Workflows::InvalidTransition for a compounded dose within 10% of a signed FDA reference strength). Deviation: the band is inclusive (<=), so a dose exactly 10% away is currently BLOCKED, contrary to this rule's \"exactly ten percent is allowed\" (card gap); test/services/ehr/integration/dose_guardrail_test.rb pins the inclusive boundary.", "source": "" }, { "id": "RRX-EHR-007", "text": "A licensed clinician approves every prescription and may select only medication the governed catalog identifies as physically available.", "enforcement": "Partly enforced: app/services/ehr/integration/prescribing.rb#validate_preconditions! + app/services/ehr/workflows/issue_prescription.rb require an active provider credential and patient-state license, fresh reauth, and signer == provider (test/services/ehr/workflows/prescription_issue_test.rb). The \"only catalog-identified physically-available medication\" clause is NOT enforced; free-text prescribing deliberately removed the formulary/availability gate.", "source": "" }, { "id": "RRX-EHR-008", "text": "Standard-dose prescriptions are limited to four per month unless a later approved rule changes the limit.", "enforcement": "Convention-only: nothing enforces a four-per-month standard-dose limit today (no code, test, or DB constraint on main or origin/staging; card gap \"enforce the monthly standard-dose limit\").", "source": "" }, { "id": "RRX-EHR-009", "text": "Do not reintroduce DEA-based product gates removed from the current product scope.", "enforcement": "Enforced by: test/services/ehr/workflows/prescription_issue_test.rb and test/services/ehr/workflows/prescription_confirmation_test.rb (free-text Rx without a formula_version_id must confirm/sign/issue; comments pin that re-adding any formula/DEA/formulary gate to confirm/sign/issue fails these tests first). Note: a vestigial controlled-substance advisory still lives in prescription_card.rb's suggestion read-model (card gap \"remove vestigial DEA gates\").", "source": "" } ], "legacy_technical_anchors": [ "3-2-rx-prescription-generation-exists", "3-2-rx-prescription-generation" ], "node_contract": { "kind": "workflow", "layer": "orchestration", "trigger": "A clinician signs the encounter and elects to prescribe.", "inputs": [ "start prescription decision from Clinical Note", "constrain medication choices from Medication Catalog", "apply approved protocol from Protocols", "enforce supply limit from Prescription Limits (3-month max before data-driven checkup)", "authorize reissue from Follow-Up Appointment" ], "outputs": [ "create prescription charge to Prescription Pay", "queue issued prescription to Pharmacy Queue" ], "owner": "Clinical Product", "operator": "Named domain owner with authorized human review", "completion": "Let a licensed clinician issue a complete prescription from a signed appointment note, using the medication catalog and approved dose boundaries.", "failure_retry": "Failures remain attributable and visible to the named owner; retry only the owning idempotent command and never invent success.", "system_of_record": "Prescription and signed encounter records.", "actors": [ { "actor": "doctor", "participation": "approves" } ], "domains": [ "fulfillment" ], "journey_stage": "clinical-decision", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-06", "focus_nodes": [ "signed-encounter", "fingerprint", "clinical-gates", "issue-rx", "correction" ] } ] }, { "key": "3.3", "number": "3.3", "section": 3, "section_title": "EHR & Prescribing", "id": "rx-pay", "title": "Prescription Pay", "track": "doctor", "business_anchor": "rx-pay", "technical_anchor": "3-3-prescription-pay", "as_built_anchor": "rx-pay", "old_anchor": "3-3-rx-pay-subscription-offer-partial", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "The patient pays for medication through either a one-time or recurring offer.", "target": { "summary": "Use catalog-defined per-item prices and support both one-time and recurring offers without a global prescription price.", "gaps": [ "Add separate subscriber and one-time prices to the suggested-prescription catalog (bead r4li)." ] }, "open_decisions": [], "rules": [ { "id": "RRX-EHR-010", "text": "The suggested-prescription catalog is the source of each item's patient price.", "enforcement": "Not enforced today: each item's patient price comes from the flat RxPricing constant (app/lib/rx_pricing.rb, ~$195 launch price), not the suggested-prescription catalog; SuggestedPrescription and the suggested_prescriptions table carry no price column (bead r4li open).", "source": "" }, { "id": "RRX-EHR-011", "text": "Each catalog item may carry distinct one-time and subscriber prices; no global prescription price is implied.", "enforcement": "Not enforced today: there are no per-item one-time vs subscriber prices; every drug shares one flat RxPricing price (app/lib/rx_pricing.rb), i.e. effectively a global prescription price; the opposite of this rule (bead r4li open).", "source": "" }, { "id": "RRX-EHR-012", "text": "A doctor approves the prescription before any patient payment request is created.", "enforcement": "Enforced structurally: the sole PrescriptionPayment creation site is Workflows::PricePrescription (app/services/workflows/price_prescription.rb), which acts on a Prescription that exists only after a doctor signs the appointment (Prescribing.issue) or approves via Workflows::ApproveByDoctor; asserted in test/services/workflows/approve_by_doctor_pricing_test.rb.", "source": "" } ], "legacy_technical_anchors": [ "3-3-rx-pay-subscription-offer-partial", "3-3-rx-pay-subscription-offer" ], "node_contract": { "kind": "integration", "layer": "integration", "trigger": "An issued prescription has a catalog-backed patient offer.", "inputs": [ "create prescription charge from Prescription Generation", "finalize charge webhook from Stripe 💳" ], "outputs": [ "submit prescription charge to Stripe 💳" ], "owner": "Clinical Product", "operator": "Owning integration service and external counterparty", "completion": "Use catalog-defined per-item prices and support both one-time and recurring offers without a global prescription price.", "failure_retry": "Failures remain attributable and visible to the named owner; retry only the owning idempotent command and never invent success.", "system_of_record": "Stripe Checkout/subscription objects reconciled to prescription billing records.", "actors": [ { "actor": "patient", "participation": "acts" }, { "actor": "doctor", "participation": "subject" } ], "domains": [ "fulfillment" ], "journey_stage": "fulfillment", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-07", "focus_nodes": [ "create-pay-link", "hosted-checkout", "redirect", "webhook", "finalize", "reconcile" ] } ] }, { "key": "3.4", "number": "3.4", "section": 3, "section_title": "EHR & Prescribing", "id": "prescription-limits", "title": "Prescription Limits (3-month max before data-driven checkup)", "track": "doctor", "business_anchor": "prescription-limits", "technical_anchor": "3-4-prescription-limits-3-month-max-before-data-driven-checkup", "as_built_anchor": "prescription-limits", "old_anchor": "3-4-prescription-limits-3-month-max-before-data-driven-checkup-partial", "flags": [ "unverified-carried-forward" ], "what_it_is": "The maximum therapy window allowed before a data-driven Check-Up and new clinician approval.", "target": { "summary": "Limit a prescription to three months of therapy before a data-driven Check-Up and new clinician approval.", "gaps": [ "Calculate supply duration and make Check-Up evidence gate refill or reissue beyond the limit." ] }, "open_decisions": [], "rules": [ { "id": "RRX-EHR-013", "text": "A prescription covers no more than three months of therapy before a new data-driven Check-Up.", "enforcement": "Convention-only: nothing enforces a three-month therapy window before a data-driven Check-Up (no supply-duration calculation or Check-Up gate exists on main or origin/staging; card gap).", "source": "" }, { "id": "RRX-EHR-014", "text": "Refill or reissue beyond the limit requires current outcome evidence and clinician approval.", "enforcement": "Convention-only: nothing enforces this today; Workflows::ConfirmRefill (app/services/workflows/confirm_refill.rb) checks only patient ownership and therapy holds; there is no outcome-evidence or clinician-approval gate for refill/reissue beyond the limit (card gap).", "source": "" } ], "legacy_technical_anchors": [ "3-4-prescription-limits-3-month-max-before-data-driven-checkup-partial" ], "node_contract": { "kind": "policy", "layer": "governance", "trigger": "Projected therapy reaches the governed three-month boundary.", "inputs": [ "No operational input; activated only by its stated trigger." ], "outputs": [ "enforce supply limit to Prescription Generation", "require ninety-day review to Follow-Up Appointment" ], "owner": "Clinical Product", "operator": "Product and operations leadership", "completion": "Limit a prescription to three months of therapy before a data-driven Check-Up and new clinician approval.", "failure_retry": "No approved runtime exists. A future implementation must expose failures to the named owner and retry only under stable idempotency keys.", "system_of_record": "Version-controlled Scale business, technical, and as-built suite.", "actors": [ { "actor": "doctor", "participation": "acts" }, { "actor": "operations", "participation": "operates" } ], "domains": [ "fulfillment", "governance" ], "journey_stage": "follow-up", "map_presence": "default-annotation" }, "subdiagram_refs": [ { "subgraph_id": "sg-08", "focus_nodes": [ "therapy-active", "depletion-anchor", "three-month-gate", "clinician-review", "continue-change-stop" ] } ] }, { "key": "3.5", "number": "3.5", "section": 3, "section_title": "EHR & Prescribing", "id": "records-ingestion", "title": "Previous Charts / Records Ingestion", "track": "doctor", "business_anchor": "records-ingestion", "technical_anchor": "3-5-previous-charts-records-ingestion", "as_built_anchor": "records-ingestion", "old_anchor": "3-5-previous-charts-records-ingestion-partial", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "Bringing a patient's historical medical records into the system.", "target": { "summary": "Ingest historical records with source provenance, preserve conflicts and prior values, and require authorized promotion into the EHR.", "gaps": [ "Add the clinician upload path, durable conflict history, and reconciliation queue." ] }, "open_decisions": [], "rules": [ { "id": "RRX-EHR-015", "text": "Every imported fact retains original source, actor, time, and transformation provenance.", "enforcement": "Enforced by: test/services/records/promote_extracted_fields_test.rb (promotion writes source=\"imported\", recorded_by actor, and a SourceCitation with page/locator back to the uploaded document; an Event records actor+time).", "source": "" }, { "id": "RRX-EHR-016", "text": "Conflicting values preserve both histories and enter an authorized reconciliation queue.", "enforcement": "Convention-only: nothing enforces this today; imported facts are upserted (first_or_initialize, so a conflicting value overwrites the prior row), and the durable conflict history + authorized reconciliation queue remain a documented card gap.", "source": "" }, { "id": "RRX-EHR-017", "text": "Only a doctor or authorized admin promotes imported facts into the official EHR.", "enforcement": "Enforced by: app/controllers/doctor/uploaded_documents_controller.rb (require_role(:doctor, :admin) + care-team chart-write authorization on #promote); tested in test/integration/doctor_uploaded_documents_test.rb.", "source": "" } ], "legacy_technical_anchors": [ "3-5-previous-charts-records-ingestion-partial" ], "node_contract": { "kind": "workflow", "layer": "orchestration", "trigger": "An authorized user uploads or imports a prior clinical record.", "inputs": [ "No operational input; activated only by its stated trigger." ], "outputs": [ "add cited prior records to Pre-Brief", "cite prior record facts to Clinical Note" ], "owner": "Clinical Product", "operator": "Named domain owner with authorized human review", "completion": "Ingest historical records with source provenance, preserve conflicts and prior values, and require authorized promotion into the EHR.", "failure_retry": "Failures remain attributable and visible to the named owner; retry only the owning idempotent command and never invent success.", "system_of_record": "Sealed source artifacts and promoted EHR facts with provenance.", "actors": [ { "actor": "doctor", "participation": "reviews" }, { "actor": "operations", "participation": "operates" } ], "domains": [ "labs", "governance" ], "journey_stage": "pre-visit", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-09", "focus_nodes": [ "upload", "seal-source", "extract", "conflict-queue", "human-review", "promote" ] } ] }, { "key": "3.6", "number": "3.6", "section": 3, "section_title": "EHR & Prescribing", "id": "ehr-schema-cleanup", "title": "EHR Schema Cleanup", "track": "doctor", "business_anchor": "ehr-schema-cleanup", "technical_anchor": "3-6-ehr-schema-cleanup", "as_built_anchor": "ehr-schema-cleanup", "old_anchor": "3-6-ehr-schema-cleanup-review-before-removal-partial", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "A controlled review of legacy EHR/schema components before any deprecation or removal.", "target": { "summary": "Review legacy components with production counts, representative shapes, history, dependencies, migration plans, and explicit approval before removal.", "gaps": [ "Complete the production census tracked by D10 and bead vfyq." ] }, "open_decisions": [], "rules": [ { "id": "RRX-EHR-018", "text": "No legacy field, table, route, job, or service is removed solely because it has no caller in a source scan.", "enforcement": "Posture: honored by working discipline only; nothing in the repo enforces it (production removal census tracked outside code via D10 / bead vfyq).", "source": "" }, { "id": "RRX-EHR-019", "text": "Removal requires production counts, representative records, history, dependency analysis, a migration plan, rollback, and explicit approval.", "enforcement": "Posture: honored by review-and-approval discipline; no code check enforces the removal checklist (counts, representative records, history, dependency analysis, migration plan, rollback, approval).", "source": "" } ], "legacy_technical_anchors": [ "3-6-ehr-schema-cleanup-review-before-removal-partial", "3-6-ehr-schema-cleanup-review-before-removal" ], "node_contract": { "kind": "workflow", "layer": "orchestration", "trigger": "A legacy EHR component is proposed for migration or removal.", "inputs": [ "No operational input; activated only by its stated trigger." ], "outputs": [ "enforce canonical schema to Clinical Note" ], "owner": "Clinical Product", "operator": "Named domain owner with authorized human review", "completion": "Review legacy components with production counts, representative shapes, history, dependencies, migration plans, and explicit approval before removal.", "failure_retry": "No approved runtime exists. A future implementation must expose failures to the named owner and retry only under stable idempotency keys.", "system_of_record": "Owning Rails domain records described by the technical contract.", "actors": [ { "actor": "doctor", "participation": "subject" }, { "actor": "operations", "participation": "operates" } ], "domains": [ "governance" ], "journey_stage": "governance", "map_presence": "default" }, "subdiagram_refs": [] }, { "key": "4.1", "number": "4.1", "section": 4, "section_title": "Labs", "id": "order-labs", "title": "Order Labs", "track": "doctor", "business_anchor": "order-labs", "technical_anchor": "4-1-order-labs", "as_built_anchor": "order-labs", "old_anchor": "4-1-order-labs-partial", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "The clinician workflow for ordering patient laboratory work.", "target": { "summary": "Support a future Order Labs to Check-Ups flow; no lab-ordering implementation is authorized by this direction alone.", "gaps": [] }, "open_decisions": [], "rules": [ { "id": "RRX-LABS-001", "text": "Only an authorized clinician orders patient laboratory work.", "enforcement": "Convention-only: no lab-ordering flow exists today (LabOrder carries an ordering_doctor association but nothing in production creates orders; lab/orders_controller has no create). Order Labs is a future lane, so nothing enforces clinician-only ordering.", "source": "" }, { "id": "RRX-LABS-002", "text": "Order Labs is a future lane; this card does not authorize an inferred vendor, panel, or automated clinical policy.", "enforcement": "Posture: direction-only scope guard; nothing in the repo enforces it; no lab-ordering, vendor, panel, or automated clinical policy is implemented.", "source": "" }, { "id": "RRX-LABS-003", "text": "Completed results enter the human follow-up workflow before the related Check-Up is closed.", "enforcement": "Convention-only: the human lab-review follow-up workflow exists (Ehr::Workflows lab review), but nothing gates Check-Up/appointment closure on lab-review completion (the Check-Up lane is not built).", "source": "" } ], "legacy_technical_anchors": [ "4-1-order-labs-partial" ], "node_contract": { "kind": "workflow", "layer": "orchestration", "trigger": "A clinician signs an order for approved laboratory work.", "inputs": [ "place independent lab order from Clinical Note", "accept or reject requisition from Quest Lab API", "record import disposition from Function Health Lab Import" ], "outputs": [ "submit Quest requisition to Quest Lab API", "dispatch mobile collection to Mobile Phlebotomy", "authorize external import to Function Health Lab Import" ], "owner": "Clinical Product", "operator": "Named domain owner with authorized human review", "completion": "Support a future Order Labs to Check-Ups flow; no lab-ordering implementation is authorized by this direction alone.", "failure_retry": "No approved runtime exists. A future implementation must expose failures to the named owner and retry only under stable idempotency keys.", "system_of_record": "Lab order and EHR encounter records.", "actors": [ { "actor": "doctor", "participation": "approves" } ], "domains": [ "labs" ], "journey_stage": "labs", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-10", "focus_nodes": [ "clinician-order", "route-vendor", "quest-collect", "mobile-collect", "normalize", "result-review" ] } ] }, { "key": "4.2", "number": "4.2", "section": 4, "section_title": "Labs", "id": "quest-diagnostics", "title": "Quest Lab API", "track": "doctor", "business_anchor": "quest-diagnostics", "technical_anchor": "4-2-quest-lab-api", "as_built_anchor": "quest-diagnostics", "old_anchor": "4-2-quest-diagnostics-integration-partial", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "The Quest ordering, requisition, and results integration for approved lab work.", "target": { "summary": "Connect approved lab orders and results through Quest when that integration is selected.", "gaps": [ "Build ordering, requisitions, result ingestion, and review handling for unknown biomarker codes." ] }, "open_decisions": [], "rules": [ { "id": "RRX-LABS-004", "text": "Quest orders and results retain patient, order, specimen, and source identifiers end to end.", "enforcement": "Convention-only: nothing enforces this today; Quest ordering, requisitions, and result ingestion are unbuilt (card gap); only incidental Quest biomarker-code mapping exists (BiomarkerCrosswalk / questBiomarkerCode).", "source": "" }, { "id": "RRX-LABS-005", "text": "Unknown biomarker mappings enter a human review queue rather than being silently discarded or guessed.", "enforcement": "Enforced by: test/services/lab_import/function_health_importer_test.rb (unknown Quest codes are retained as needs_review rows and enqueue a BiomarkerReviewItem) and test/models/biomarker_review_item_test.rb (idempotent open review queue). Note: the queue is keyed on quest_biomarker_code but is only exercised via the Function Health importer, since Quest result ingestion itself is unbuilt.", "source": "" } ], "legacy_technical_anchors": [ "4-2-quest-diagnostics-integration-partial", "4-2-quest-diagnostics-integration" ], "node_contract": { "kind": "integration", "layer": "integration", "trigger": "An approved lab order selects Quest as the collection route.", "inputs": [ "submit Quest requisition from Order Labs" ], "outputs": [ "accept or reject requisition to Order Labs", "deliver normalized Quest results to Lab Follow-up" ], "owner": "Clinical Product", "operator": "Owning integration service and external counterparty", "completion": "Connect approved lab orders and results through Quest when that integration is selected.", "failure_retry": "No approved runtime exists. A future implementation must expose failures to the named owner and retry only under stable idempotency keys.", "system_of_record": "Lab order/result records plus Quest external identifiers.", "actors": [ { "actor": "patient", "participation": "acts" }, { "actor": "doctor", "participation": "subject" } ], "domains": [ "labs" ], "journey_stage": "labs", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-10", "focus_nodes": [ "route-vendor", "quest-collect", "normalize", "result-review" ] } ] }, { "key": "4.3", "number": "4.3", "section": 4, "section_title": "Labs", "id": "concierge-phlebotomy", "title": "Mobile Phlebotomy", "track": "doctor", "business_anchor": "concierge-phlebotomy", "technical_anchor": "4-3-mobile-phlebotomy", "as_built_anchor": "concierge-phlebotomy", "old_anchor": "4-3-concierge-phlebotomy-400-at-home-draw-future", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "An optional at-home blood draw scheduled and paid for by the patient.", "target": { "summary": "Offer an optional at-home concierge draw with transparent approximately $400 patient pricing once a vendor is approved.", "gaps": [ "Select the vendor and connect scheduling, payment, collection, and results." ] }, "open_decisions": [], "rules": [ { "id": "RRX-LABS-006", "text": "Display the full patient price before the concierge draw is scheduled.", "enforcement": "Convention-only: nothing enforces this today; concierge phlebotomy (vendor, scheduling, payment, pricing) is unbuilt; no phlebotomy code exists in the repo.", "source": "" }, { "id": "RRX-LABS-007", "text": "The selected vendor must return collection and result evidence into the ordinary lab follow-up lane.", "enforcement": "Convention-only: nothing enforces this today; no concierge phlebotomy vendor or collection/result integration exists in the repo.", "source": "" } ], "legacy_technical_anchors": [ "4-3-concierge-phlebotomy-400-at-home-draw-future", "4-3-concierge-phlebotomy-400-at-home-draw" ], "node_contract": { "kind": "integration", "layer": "integration", "trigger": "The patient accepts a quoted mobile-draw option.", "inputs": [ "dispatch mobile collection from Order Labs" ], "outputs": [ "deliver mobile collection results to Lab Follow-up" ], "owner": "Clinical Product", "operator": "Owning integration service and external counterparty", "completion": "Offer an optional at-home concierge draw with transparent approximately $400 patient pricing once a vendor is approved.", "failure_retry": "No approved runtime exists. A future implementation must expose failures to the named owner and retry only under stable idempotency keys.", "system_of_record": "Lab order, vendor booking, collection, and result references.", "actors": [ { "actor": "patient", "participation": "acts" }, { "actor": "doctor", "participation": "subject" } ], "domains": [ "labs" ], "journey_stage": "labs", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-10", "focus_nodes": [ "mobile-quote", "mobile-accept", "mobile-collect", "normalize", "result-review" ] } ] }, { "key": "4.4", "number": "4.4", "section": 4, "section_title": "Labs", "id": "function-health-lab-import", "title": "Function Health Lab Import", "track": "doctor", "business_anchor": "function-health-lab-import", "technical_anchor": "4-4-function-health-lab-import", "as_built_anchor": "function-health-lab-import", "old_anchor": "4-4-function-health-lab-import-exists-bonus-not-on-the-whiteboard", "flags": [ "unverified-carried-forward" ], "what_it_is": "The patient-authorized import of Function Health laboratory results into RonanRx.", "target": { "summary": "Import patient-authorized Function Health results with provenance and a human path for unresolved biomarker mappings.", "gaps": [ "Add an Ops resolution surface for unknown codes and keep recurring synchronization out of scope unless separately approved." ] }, "open_decisions": [], "rules": [ { "id": "RRX-LABS-008", "text": "Import only with patient authorization and retain the originating Function Health evidence.", "enforcement": "Enforced by: app/services/workflows/upsert_function_health_resource.rb (lock_and_validate_authorization! requires an active function_health_account_import consent + unconsumed/unexpired handoff token + valid lease, else raises InvalidTransition; encrypted payload_json retains the originating Function Health evidence); tested in test/services/workflows/upsert_function_health_resource_test.rb.", "source": "" }, { "id": "RRX-LABS-009", "text": "Unknown biomarker mappings require human resolution.", "enforcement": "Enforced by: test/services/lab_import/function_health_importer_test.rb (unknown or absent Quest codes are retained as needs_review rows and enqueue a BiomarkerReviewItem rather than being discarded or guessed) and test/models/biomarker_review_item_test.rb.", "source": "" }, { "id": "RRX-LABS-010", "text": "A one-time import does not imply an approved recurring synchronization product.", "enforcement": "Posture: scope/authorization direction; nothing enforces it; recurring synchronization is kept out of scope by discipline, not by any code check.", "source": "" } ], "legacy_technical_anchors": [ "4-4-function-health-lab-import-exists" ], "node_contract": { "kind": "integration", "layer": "integration", "trigger": "A patient authorizes a Function Health import.", "inputs": [ "authorize external import from Order Labs" ], "outputs": [ "record import disposition to Order Labs", "deliver cited imported results to Lab Follow-up" ], "owner": "Clinical Product", "operator": "Owning integration service and external counterparty", "completion": "Import patient-authorized Function Health results with provenance and a human path for unresolved biomarker mappings.", "failure_retry": "Failures remain attributable and visible to the named owner; retry only the owning idempotent command and never invent success.", "system_of_record": "Import lease, sealed source, mapping queue, and normalized lab results.", "actors": [ { "actor": "doctor", "participation": "subject" } ], "domains": [ "labs" ], "journey_stage": "labs", "map_presence": "view-only", "map_geometry": { "x": 900, "y": 320, "width": 152, "height": 44 } }, "subdiagram_refs": [ { "subgraph_id": "sg-11", "focus_nodes": [ "patient-consent", "one-time-token", "lease", "isolated-pull", "mapping-queue", "finalize" ] }, { "subgraph_id": "sg-10", "focus_nodes": [ "normalize", "result-review" ] } ] }, { "key": "4.5", "number": "4.5", "section": 4, "section_title": "Labs", "id": "lab-follow-up", "title": "Lab Follow-up", "track": "doctor", "business_anchor": "lab-follow-up", "technical_anchor": "4-5-lab-follow-up", "as_built_anchor": "lab-follow-up", "old_anchor": "4-5-lab-follow-up-compliance-exists", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "The human follow-up and staff-attestation workflow for every laboratory result.", "target": { "summary": "Require human follow-up on every lab result, record staff attestation, and keep the unacknowledged-results queue owned by Ops.", "gaps": [ "Build the Ops timer and queue; critical-result clinical escalation remains deferred until lab ordering is built." ] }, "open_decisions": [], "rules": [ { "id": "RRX-LABS-011", "text": "Every lab result receives human review and a recorded staff notification attestation before the case is treated as complete.", "enforcement": "Enforced by: test/services/ehr/workflows/lab_review_test.rb (review -> acknowledge -> patient-notified records channel, recorded_by, and patient_notified_at as a staff attestation) and test/integration/ehr/lab_reviews_test.rb.", "source": "" }, { "id": "RRX-LABS-012", "text": "Critical-lab escalation remains deferred until lab ordering is built; do not infer an automated escalation policy.", "enforcement": "Posture: deferral direction; nothing enforces it; no automated clinical escalation exists (critical results are grouped and manually acknowledged/overridden, not auto-escalated).", "source": "" }, { "id": "RRX-LABS-013", "text": "Ops owns the timer and queue for results awaiting staff attestation; clinical escalation policy remains deferred.", "enforcement": "Convention-only: nothing enforces this today; the Ops attestation timer and queue are a documented gap (OpenWorkQueue covers pharmacy orders, not lab attestation); patient-notified attestation is recorded but clinical escalation remains deferred by discipline.", "source": "" } ], "legacy_technical_anchors": [ "4-5-lab-follow-up-compliance-exists", "4-5-lab-follow-up-compliance" ], "node_contract": { "kind": "workflow", "layer": "orchestration", "trigger": "A normalized laboratory result enters the EHR.", "inputs": [ "deliver normalized Quest results from Quest Lab API", "deliver mobile collection results from Mobile Phlebotomy", "deliver cited imported results from Function Health Lab Import" ], "outputs": [ "publish reviewed lab event to Clinical Rounds", "raise lab exception to Ops Console" ], "owner": "Clinical Product", "operator": "Named domain owner with authorized human review", "completion": "Require human follow-up on every lab result, record staff attestation, and keep the unacknowledged-results queue owned by Ops.", "failure_retry": "Failures remain attributable and visible to the named owner; retry only the owning idempotent command and never invent success.", "system_of_record": "Lab result, acknowledgment, notification, and Ops exception records.", "actors": [ { "actor": "patient", "participation": "receives" }, { "actor": "doctor", "participation": "reviews" } ], "domains": [ "labs", "follow-up" ], "journey_stage": "labs", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-10", "focus_nodes": [ "result-review", "acknowledge", "override", "patient-notify", "follow-up" ] } ] }, { "key": "5.1", "number": "5.1", "section": 5, "section_title": "Pharmacy, Protocols & Fulfillment", "id": "protocols", "title": "Protocols", "track": "ops", "business_anchor": "protocols", "technical_anchor": "5-1-protocols", "as_built_anchor": "protocols", "old_anchor": "5-1-protocols-compounding-logic-partial", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "The governed compounding protocol engine: approved formulas, concentrations, programs, and state mappings.", "target": { "summary": "Build the full approved compounding protocol engine with clinician-selected dose and catalog-locked vial and concentration choices, then validate it in an isolated duplicate through a TestFlight admin sandbox before connecting it to live workflows.", "gaps": [] }, "open_decisions": [], "rules": [ { "id": "RRX-FULFILLMENT-001", "text": "Do not modify the live protocol engine for experimental work; duplicate it and validate the duplicate in the TestFlight admin sandbox.", "enforcement": "Convention-only: nothing enforces this today. No TestFlight admin sandbox or protocol-engine-duplication mechanism exists in the repo; the isolate-and-validate practice is honored by discipline only.", "source": "" }, { "id": "RRX-FULFILLMENT-002", "text": "Only approved formula versions may drive fulfillment behavior; clinicians may select dose, while vial and concentration choices remain locked to the governed catalog.", "enforcement": "Enforced by: test/models/formula_version_dosing_test.rb (only approved FormulaVersions serve dosing; the clinician picks an allowed dose step while concentration stays locked to the approved version) and test/services/workflows/approve_formula_version_test.rb (approval gate plus the DB partial unique index idx_formula_versions_one_approved_per_master).", "source": "" }, { "id": "RRX-FULFILLMENT-003", "text": "Free-text prescribing does not silently create or alter approved protocol records.", "enforcement": "Convention-only: nothing enforces this today. FormulaVersions are created only as drafts and promoted through Workflows::ApproveFormulaVersion (the sole governed write path; no FormulaVersion.create exists elsewhere in app/), and prescribing carries an optional formula_version_id without ever creating or mutating one; but no test asserts the invariant.", "source": "" } ], "legacy_technical_anchors": [ "5-1-protocols-compounding-logic-partial", "5-1-protocols-compounding-logic" ], "node_contract": { "kind": "registry", "layer": "data", "trigger": "An authorized protocol author creates or changes a governed version.", "inputs": [ "map catalog to protocol from Medication Catalog" ], "outputs": [ "apply approved protocol to Prescription Generation", "approve preparation protocol to Pharmacy Queue", "validate candidate protocol to TestFlight Protocol Sandbox" ], "owner": "Operations Platform", "operator": "Authorized domain steward", "completion": "Build the full approved compounding protocol engine with clinician-selected dose and catalog-locked vial and concentration choices, then validate it in an isolated duplicate through a TestFlight admin sandbox before connecting it to live workflows.", "failure_retry": "Failures remain attributable and visible to the named owner; retry only the owning idempotent command and never invent success.", "system_of_record": "Versioned protocol registry and approval history.", "actors": [ { "actor": "operations", "participation": "operates" } ], "domains": [ "fulfillment", "governance" ], "journey_stage": "fulfillment", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-12", "focus_nodes": [ "catalog-entry", "protocol-version", "approval", "mapping", "sandbox-validate" ] } ] }, { "key": "5.2", "number": "5.2", "section": 5, "section_title": "Pharmacy, Protocols & Fulfillment", "id": "internal-fulfillment-network", "title": "Pharmacy Queue", "track": "ops", "business_anchor": "internal-fulfillment-network", "technical_anchor": "5-2-pharmacy-queue", "as_built_anchor": "internal-fulfillment-network", "old_anchor": "5-2-internal-fulfillment-network-partial", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "The pharmacy operating system: automatic pharmacy routing → work queue → pharmacist review → batch/preparation → QA → pharmacist final release → fulfillment readiness. RonanRX Inc. is not itself the compounder.", "target": { "summary": "Route prescriptions through a licensed pharmacy with pharmacist review, preparation, QA, final release, and an attributable ready-for-3PL handoff.", "gaps": [ "Complete the staff work queue, restrict final release to pharmacists, reconcile order opening, and connect final release to the 3PL handoff in §5.6." ] }, "open_decisions": [], "rules": [ { "id": "RRX-FULFILLMENT-004", "text": "RonanRx routes fulfillment only to an eligible licensed pharmacy for the prescription and patient state.", "enforcement": "Enforced by: test/services/pharmacy/fulfillment_routing_test.rb (routes by patient state; TX to Elite Care, CA to Striker; and defaults to internal compounding), backed by Workflows::OpenPharmacyOrder blocking out-of-coverage patient states. The routed pharmacy's licensure is a curated per-state launch config, confirmed operationally rather than in code.", "source": "" }, { "id": "RRX-FULFILLMENT-005", "text": "Preparation, QA, pharmacist review, final release, and the release-to-3PL handoff each retain attributable evidence.", "enforcement": "Partially enforced by: test/services/workflows/hard_fail_gate_test.rb (AuditLog rows written under named gates at StartCompounding and ReleaseQa/pharmacist_release_required; QualityRelease records released_by + signature_hash). No 3PL handoff exists, so release-to-3PL evidence is not enforced.", "source": "" }, { "id": "RRX-FULFILLMENT-006", "text": "Only a pharmacist performs final release.", "enforcement": "Partially enforced by app/services/workflows/release_qa.rb: the final-release role guard permits pharmacist, lab_ops, OR admin (test/services/workflows/hard_fail_gate_test.rb confirms lab_ops is accepted), so pharmacist-only is not enforced today.", "source": "" }, { "id": "RRX-FULFILLMENT-007", "text": "Preserve existing fulfillment and refill substrate until the D10 production census supports a reviewed migration.", "enforcement": "Convention-only: nothing enforces this today. No code references a D10 production census or gates removal of legacy fulfillment/refill substrate; preservation is honored by discipline only.", "source": "" } ], "legacy_technical_anchors": [ "5-2-internal-fulfillment-network-partial", "5-2-internal-fulfillment-network" ], "node_contract": { "kind": "workflow", "layer": "orchestration", "trigger": "A complete prescription and approved protocol enter pharmacy review.", "inputs": [ "queue issued prescription from Prescription Generation", "approve preparation protocol from Protocols", "supply release evidence from Beyond-Use Date", "accept or reject release from 3PL Fulfillment Handoff" ], "outputs": [ "release fulfillment order to 3PL Fulfillment Handoff" ], "owner": "Operations Platform", "operator": "Named domain owner with authorized human review", "completion": "Route prescriptions through a licensed pharmacy with pharmacist review, preparation, QA, final release, and an attributable ready-for-3PL handoff.", "failure_retry": "Failures remain attributable and visible to the named owner; retry only the owning idempotent command and never invent success.", "system_of_record": "Pharmacy work item, preparation, QA, release, and shipment-readiness records.", "actors": [ { "actor": "operations", "participation": "operates" } ], "domains": [ "fulfillment", "governance" ], "journey_stage": "fulfillment", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-12", "focus_nodes": [ "pharmacist-review", "prepare", "lot-label-bud", "qa", "final-release" ] } ] }, { "key": "5.3", "number": "5.3", "section": 5, "section_title": "Pharmacy, Protocols & Fulfillment", "id": "beyond-use-date", "title": "Beyond-Use Date", "track": "ops", "business_anchor": "beyond-use-date", "technical_anchor": "5-3-beyond-use-date", "as_built_anchor": "beyond-use-date", "old_anchor": "5-3-beyond-use-date-bud-partial", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "The required discard-after date for a compounded medication or preparation, supplied by the pharmacy's physical process and displayed by the software.", "target": { "summary": "Store and display the beyond-use date supplied by the pharmacy's physical process; software does not derive it.", "gaps": [ "Add the display-only field and prevent release attestations from claiming a value that has not been supplied." ] }, "open_decisions": [], "rules": [ { "id": "RRX-FULFILLMENT-008", "text": "The pharmacy's physical process supplies the beyond-use date.", "enforcement": "Enforced externally: the beyond-use date originates from the pharmacy's physical compounding process. In software, Agents::CompoundingWorkflow leaves beyond_use_date nil and never derives it.", "source": "" }, { "id": "RRX-FULFILLMENT-009", "text": "Software stores and displays the supplied date but does not derive it.", "enforcement": "Convention-only: nothing enforces this today. The supplied date is stored on compounding_tasks.beyond_use_date (db/structure.sql) and shown read-only in lab/pharmacist/patient views, and no code derives it; but nothing tests the store-and-display-only behavior.", "source": "" }, { "id": "RRX-FULFILLMENT-010", "text": "A release workflow must not attest that a beyond-use date is set unless an actual value exists.", "enforcement": "Convention-only, and currently contradicted: app/services/workflows/release_qa.rb and app/services/agents/quality_gate.rb hardcode checklist \"bud_set\" => true regardless of the stored beyond_use_date, so nothing prevents a release from attesting a BUD that was never supplied.", "source": "" } ], "legacy_technical_anchors": [ "5-3-beyond-use-date-bud-partial", "5-3-beyond-use-date-bud" ], "node_contract": { "kind": "policy", "layer": "governance", "trigger": "The pharmacy supplies preparation-specific BUD evidence before release.", "inputs": [ "No operational input; activated only by its stated trigger." ], "outputs": [ "supply release evidence to Pharmacy Queue" ], "owner": "Operations Platform", "operator": "Product and operations leadership", "completion": "Store and display the beyond-use date supplied by the pharmacy's physical process; software does not derive it.", "failure_retry": "No approved runtime exists. A future implementation must expose failures to the named owner and retry only under stable idempotency keys.", "system_of_record": "Pharmacy-supplied preparation evidence stored with the released item.", "actors": [ { "actor": "operations", "participation": "operates" } ], "domains": [ "fulfillment", "governance" ], "journey_stage": "fulfillment", "map_presence": "default" }, "subdiagram_refs": [] }, { "key": "5.4", "number": "5.4", "section": 5, "section_title": "Pharmacy, Protocols & Fulfillment", "id": "delivery-bot", "title": "Delivery Bot", "track": "ops", "business_anchor": "delivery-bot", "technical_anchor": "5-4-delivery-bot", "as_built_anchor": "delivery-bot", "old_anchor": "5-4-delivery-bot-partial", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "The deterministic patient-notification workflow that consumes authoritative 3PL and carrier shipment events for compounded medications.", "target": { "summary": "Consume real 3PL and carrier events and notify the patient at approved preparation, packing, carrier-tender, delivery or pickup, and dosing-instruction milestones.", "gaps": [ "Replace synthetic tracking and unwritten temperature evidence with the §5.6 3PL handoff plus real carrier and cold-chain integrations." ] }, "open_decisions": [], "rules": [ { "id": "RRX-FULFILLMENT-011", "text": "Shipment status comes from the responsible 3PL or carrier and is never fabricated.", "enforcement": "Convention-only, and currently contradicted: shipment status is synthetic; app/services/workflows/dispatch_shipment.rb mints a \"VAL-…\" tracking_number and fabricates label_created/picked_up_by_carrier events, and confirm_delivery.rb appends a synthetic \"delivered\" event. No 3PL or carrier tracking integration exists, so nothing enforces the never-fabricated rule.", "source": "" }, { "id": "RRX-FULFILLMENT-012", "text": "Notify the patient at approved preparation, 3PL acceptance, packing, carrier-tender, delivery or pickup, and dosing-instruction milestones.", "enforcement": "Convention-only: nothing enforces this today. Shipment workflows update patient-facing order views (preparation, orders/show) but there is no milestone-notification workflow for preparation, 3PL acceptance, packing, carrier tender, delivery/pickup, or dosing-instruction milestones.", "source": "" }, { "id": "RRX-FULFILLMENT-013", "text": "Cold-chain claims require recorded temperature evidence.", "enforcement": "Convention-only, and currently contradicted: shipments.temperature_trace exists (db/structure.sql, default []) but is never written; only read in app/views/lab/shipments/show.html.erb; while cold_chain_required is set and displayed. No recorded temperature evidence backs any cold-chain claim.", "source": "" } ], "legacy_technical_anchors": [ "5-4-delivery-bot-partial" ], "node_contract": { "kind": "deterministic-automation", "layer": "automation", "trigger": "An authoritative 3PL or carrier milestone is accepted.", "inputs": [ "stream shipment events from 3PL Fulfillment Handoff" ], "outputs": [ "send delivery milestone to Patient Chat", "publish care delivery event to Clinical Rounds", "anchor depletion clock to Follow-Up Appointment" ], "owner": "Operations Platform", "operator": "Rails worker or scheduled domain service", "completion": "Consume real 3PL and carrier events and notify the patient at approved preparation, packing, carrier-tender, delivery or pickup, and dosing-instruction milestones.", "failure_retry": "No approved runtime exists. A future implementation must expose failures to the named owner and retry only under stable idempotency keys.", "system_of_record": "Authoritative shipment event ledger and message-delivery records.", "actors": [ { "actor": "patient", "participation": "receives" }, { "actor": "agent", "participation": "operates" }, { "actor": "operations", "participation": "operates" } ], "domains": [ "fulfillment", "follow-up" ], "journey_stage": "fulfillment", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-13", "focus_nodes": [ "shipment-events", "event-acceptance", "patient-milestone", "exception-queue" ] } ] }, { "key": "5.5", "number": "5.5", "section": 5, "section_title": "Pharmacy, Protocols & Fulfillment", "id": "medication-catalog", "title": "Medication Catalog", "track": "ops", "business_anchor": "medication-catalog", "technical_anchor": "5-5-medication-catalog", "as_built_anchor": "medication-catalog", "old_anchor": "5-5-drug-catalog-educator-protocols-partial", "flags": [ "unverified-carried-forward" ], "what_it_is": "The bridge from the medication catalog to educator content and then to authored, approved compounding protocols.", "target": { "summary": "Connect catalog entries to approved educator content and then to governed compounding protocols without inventing a protocol-count target.", "gaps": [ "Build the governed educator-to-protocol authoring and approval path." ] }, "open_decisions": [], "rules": [ { "id": "RRX-FULFILLMENT-014", "text": "Prescribers select from the governed medication catalog of items physically available for fulfillment.", "enforcement": "Enforced by: test/services/ehr/integration/prescription_card_test.rb; the prescription card offers only active SuggestedPrescription catalog rows (inactive rows excluded) and marks unavailable formula identities blocked. This governs what is surfaced for selection; prescribing is not otherwise hard-blocked to the catalog (medication_name remains free-text).", "source": "" }, { "id": "RRX-FULFILLMENT-015", "text": "Educator content and protocol records require explicit authorship, review, versioning, and approval.", "enforcement": "Partially enforced by: test/services/workflows/approve_formula_version_test.rb; protocol (FormulaVersion) records require draft authorship, integer versioning, and pharmacist/doctor approval, guarded by the DB unique index idx_formula_versions_one_approved_per_master. The educator-content authoring/review/approval half is not built (the governed educator-to-protocol path is an open card gap).", "source": "" }, { "id": "RRX-FULFILLMENT-016", "text": "Catalog content never silently creates or promotes a protocol.", "enforcement": "Convention-only: nothing enforces this today. The prescription card treats catalog rows as non-binding suggestions and emits no formula_version_id (app/services/ehr/integration/prescription_card.rb), and no code path promotes catalog content into a FormulaVersion; but no test asserts the invariant.", "source": "" } ], "legacy_technical_anchors": [ "5-5-drug-catalog-educator-protocols-partial", "5-5-drug-catalog-educator-protocols" ], "node_contract": { "kind": "registry", "layer": "data", "trigger": "An authorized catalog entry or price/protocol mapping changes.", "inputs": [ "No operational input; activated only by its stated trigger." ], "outputs": [ "constrain medication choices to Prescription Generation", "map catalog to protocol to Protocols" ], "owner": "Operations Platform", "operator": "Authorized domain steward", "completion": "Connect catalog entries to approved educator content and then to governed compounding protocols without inventing a protocol-count target.", "failure_retry": "Failures remain attributable and visible to the named owner; retry only the owning idempotent command and never invent success.", "system_of_record": "Medication catalog, offer, educator, and protocol mappings.", "actors": [ { "actor": "operations", "participation": "operates" } ], "domains": [ "fulfillment", "governance" ], "journey_stage": "fulfillment", "map_presence": "default-annotation" }, "subdiagram_refs": [ { "subgraph_id": "sg-12", "focus_nodes": [ "catalog-entry", "protocol-version", "mapping" ] } ] }, { "key": "5.6", "number": "5.6", "section": 5, "section_title": "Pharmacy, Protocols & Fulfillment", "id": "3pl-fulfillment-handoff", "title": "3PL Fulfillment Handoff", "track": "ops", "business_anchor": "3pl-fulfillment-handoff", "technical_anchor": "5-6-3pl-fulfillment-handoff", "as_built_anchor": "3pl-fulfillment-handoff", "old_anchor": "5-6-3pl-fulfillment-handoff-future", "flags": [ "board-node" ], "what_it_is": "The controlled connection that sends a pharmacist-released, fulfillment-ready order to the contracted third-party logistics provider's ShipStation workflow and returns acknowledgment, packing, label, carrier, and tracking state to RonanRx.", "target": { "summary": "Reliably hand pharmacist-released orders to the contracted 3PL through its ShipStation workflow, reconcile positive acknowledgment, and return real packing, label, carrier, and tracking evidence to RonanRx for Ops and Delivery Bot.", "gaps": [ "Define and implement the authenticated outbound contract, stable external IDs, positive acknowledgment, and retry and reconciliation behavior.", "Ingest authoritative 3PL, ShipStation, and carrier events, surface exceptions in Ops, and feed Delivery Bot." ] }, "open_decisions": [ { "id": "D11", "status": "open", "owner": "Operations + Engineering", "opened_on": "2026-07-30", "question": "Will RonanRx connect directly to the 3PL's ShipStation account and webhooks or use a 3PL-owned API or feed, and what authenticated event contract is available?" } ], "rules": [ { "id": "RRX-FULFILLMENT-017", "text": "RonanRx submits an order to the 3PL only after the responsible pharmacy records pharmacist final release and fulfillment readiness.", "enforcement": "Not enforced: no production path sends a released order to a 3PL or ShipStation, and Workflows::ConfirmShippingReadiness has no verified production caller.", "source": "" }, { "id": "RRX-FULFILLMENT-018", "text": "The 3PL owns packing, sealing, postage purchase, carrier-label printing, and carrier tender; RonanRx never treats submission, acknowledgment, or label creation alone as proof that the parcel shipped.", "enforcement": "External operating boundary and not implemented: no 3PL interface exists, while the current Workflows::DispatchShipment path synthesizes label and carrier events instead of receiving physical-operations evidence.", "source": "" }, { "id": "RRX-FULFILLMENT-019", "text": "Each handoff uses a stable external fulfillment ID, requires positive 3PL acknowledgment, and supports audited retries and reconciliation without duplicate fulfillment or postage.", "enforcement": "Not enforced: shipments.external_id is unused, and no handoff ledger, idempotency control, positive-acknowledgment record, or retry and reconciliation job exists.", "source": "" }, { "id": "RRX-FULFILLMENT-020", "text": "Returned packing, label, carrier, and tracking events retain their authoritative source, external event time, and RonanRx receipt time; Delivery Bot consumes those events without inventing status.", "enforcement": "Convention-only, and currently contradicted: no authenticated inbound 3PL or ShipStation event feed exists, and current dispatch and delivery workflows synthesize tracking events.", "source": "" }, { "id": "RRX-FULFILLMENT-021", "text": "Rejected, failed, stale, voided, or replaced handoffs remain visible to Ops and require an attributable resolution.", "enforcement": "Not enforced: no 3PL exception queue, reconciliation surface, or attributable handoff-resolution workflow exists.", "source": "" }, { "id": "RRX-FULFILLMENT-022", "text": "RonanRx sends only the fulfillment and shipping data the 3PL requires and excludes unrelated clinical information.", "enforcement": "Not enforced because no 3PL transport exists. The outbound payload contract and acceptance tests must verify data minimization before release.", "source": "" } ], "legacy_technical_anchors": [ "5-6-3pl-fulfillment-handoff-future" ], "node_contract": { "kind": "integration", "layer": "integration", "trigger": "The pharmacy records pharmacist final release and fulfillment readiness.", "inputs": [ "release fulfillment order from Pharmacy Queue" ], "outputs": [ "accept or reject release to Pharmacy Queue", "stream shipment events to Delivery Bot", "raise shipment exception to Ops Console" ], "owner": "Operations Platform", "operator": "Owning integration service and external counterparty", "completion": "Reliably hand pharmacist-released orders to the contracted 3PL through its ShipStation workflow, reconcile positive acknowledgment, and return real packing, label, carrier, and tracking evidence to RonanRx for Ops and Delivery Bot.", "failure_retry": "No approved runtime exists. A future implementation must expose failures to the named owner and retry only under stable idempotency keys.", "system_of_record": "Fulfillment handoff ledger keyed by stable external fulfillment ID.", "actors": [ { "actor": "operations", "participation": "operates" } ], "domains": [ "fulfillment" ], "journey_stage": "fulfillment", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-13", "focus_nodes": [ "release-submit", "positive-ack", "reject", "label-pack-seal", "carrier-tender", "shipment-events", "reconcile" ] } ] }, { "key": "6.1", "number": "6.1", "section": 6, "section_title": "Billing Architecture", "id": "billing-architecture", "title": "Stripe 💳", "track": "ops", "business_anchor": "billing-architecture", "technical_anchor": "6-1-stripe", "as_built_anchor": "billing-architecture", "old_anchor": "6-1-stripe-split-charges-two-vendor-names-partial", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "The billing model that keeps the patient's membership, prescription charge, RonanRx fee, and doctor payout explicit.", "target": { "summary": "RonanRx Inc remains merchant of record, collects the full amount, absorbs Stripe processing from its $10 fee, and pays the doctor a flat $29 through Stripe Connect.", "gaps": [ "Complete Stripe Connect and the $29 payout implementation (bead m5l2)." ] }, "open_decisions": [], "rules": [ { "id": "RRX-BILLING-001", "text": "RonanRx Inc is merchant of record and collects the full patient amount.", "enforcement": "External (Stripe account ownership): merchant-of-record is a Stripe/legal configuration, not a repo control. Today membership is collected on RonanRx's own Stripe account (app/lib/billing.rb) while the per-prescription charge routes to the Elite Care (TX) / True Nano (CA) pharmacy accounts (app/lib/rx_billing.rb), so a single 'RonanRx collects the full amount' is not yet what the code does (gap m5l2).", "source": "" }, { "id": "RRX-BILLING-002", "text": "RonanRx retains a flat $10 fee and absorbs Stripe processing from that fee.", "enforcement": "Not enforced today: the flat $10 RonanRx fee and Stripe-processing absorption are unbuilt (gap m5l2, Stripe Connect). Membership price lives in Stripe (STRIPE_PRICE_ID, app/lib/billing.rb) and the flat $195 med charge in app/lib/rx_pricing.rb; neither encodes a $10 fee split.", "source": "" }, { "id": "RRX-BILLING-003", "text": "The doctor receives a flat $29 payout through Stripe Connect.", "enforcement": "Partially external: the $29 provider-fee default is set in code and contract (app/services/provider_agreement_packet/cover_fields.rb = 2900 cents; config/text_authorization/provider_agreement_packet_contract_v1.yml, 'the Provider Fee can be settled by Stripe'), but the actual Stripe Connect payout is unbuilt (gap m5l2).", "source": "" }, { "id": "RRX-BILLING-004", "text": "Membership and prescription charges remain distinct and identify the responsible billing entity.", "enforcement": "Enforced by: test/lib/rx_billing_test.rb - asserts the per-prescription charge carries its own account key and never the global membership Stripe key, and routes the responsible billing entity by state (CA -> True Nano 'ca', else -> Elite Care 'tx'). Membership (app/lib/billing.rb) and prescription (app/lib/rx_billing.rb / PrescriptionPayment) charges are separate Stripe account families.", "source": "" } ], "legacy_technical_anchors": [ "6-1-stripe-split-charges-two-vendor-names-partial", "6-1-stripe-split-charges-two-vendor-names" ], "node_contract": { "kind": "integration", "layer": "integration", "trigger": "A membership, prescription, refund, fee, or payout money event occurs.", "inputs": [ "submit prescription charge from Prescription Pay", "submit membership payment from Membership Pay" ], "outputs": [ "finalize charge webhook to Prescription Pay", "activate membership webhook to Membership Pay" ], "owner": "Operations Platform", "operator": "Owning integration service and external counterparty", "completion": "RonanRx Inc remains merchant of record, collects the full amount, absorbs Stripe processing from its $10 fee, and pays the doctor a flat $29 through Stripe Connect.", "failure_retry": "Failures remain attributable and visible to the named owner; retry only the owning idempotent command and never invent success.", "system_of_record": "Rails billing ledger reconciled to Stripe and Connect.", "actors": [ { "actor": "operations", "participation": "operates" } ], "domains": [ "fulfillment", "governance" ], "journey_stage": "platform", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-14", "focus_nodes": [ "membership-charge", "rx-charge", "webhook-ledger", "platform-fee", "provider-payout", "refund" ] } ] }, { "key": "7.1", "number": "7.1", "section": 7, "section_title": "Async Care Loop", "id": "check-ups", "title": "Follow-Up Appointment", "track": "doctor", "business_anchor": "check-ups", "technical_anchor": "7-1-follow-up-appointment", "as_built_anchor": "check-ups", "old_anchor": "7-1-check-ups-follow-up-on-timeline-partial", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "A doctor-gated review of patient progress, adherence, outcomes, and relevant health evidence about every three months.", "target": { "summary": "Run a doctor-gated Check-Up about every three months using weight, adherence, outcomes, and relevant timeline evidence.", "gaps": [ "Connect Check-Ups to prescription limits, deliver patient prompts over SMS, and give doctors a one-action review surface." ] }, "open_decisions": [], "rules": [ { "id": "RRX-CARE-001", "text": "Check-Ups occur about every three months and remain distinct from patient Outcome Check-ins.", "enforcement": "Not enforced today: the doctor-gated ~3-month Check-Up is unbuilt - no Check-Up model, table, or quarterly cadence exists. Only the patient OutcomeCheckIn (app/models/outcome_check_in.rb; weekly/biweekly/monthly) is built, so the two are 'distinct' only because the Check-Up does not yet exist (gap).", "source": "" }, { "id": "RRX-CARE-002", "text": "The doctor reviews current weight, adherence, outcomes, and relevant timeline evidence before approving continuation.", "enforcement": "Convention-only (operational): nothing in code gates continuation on a documented review of weight, adherence, outcomes, and timeline; the doctor one-action review surface is unbuilt (gap). Spec designates this operational-review-confirmed.", "source": "" }, { "id": "RRX-CARE-003", "text": "Check-Up approval is attributable and gates therapy beyond the prescription limit.", "enforcement": "Not enforced today: no Check-Up approval exists and Prescription carries no refill/dispense-limit field (confirmed in db/structure.sql), so nothing gates 'therapy beyond the prescription limit.' Therapy holds (app/services/therapy_holds/guard.rb) gate refills, but not a Check-Up-based limit (gap).", "source": "" } ], "legacy_technical_anchors": [ "7-1-check-ups-follow-up-on-timeline-partial", "7-1-check-ups-follow-up-on-timeline" ], "node_contract": { "kind": "workflow", "layer": "orchestration", "trigger": "A follow-up is due or new evidence requires clinician review.", "inputs": [ "anchor depletion clock from Delivery Bot", "require ninety-day review from Prescription Limits (3-month max before data-driven checkup)", "request clinician refill review from Refills", "surface follow-up signal from Clinical Rounds", "add weight and adherence signals from Device Data" ], "outputs": [ "publish refill decision to Refills", "authorize reissue to Prescription Generation" ], "owner": "Clinical Product", "operator": "Named domain owner with authorized human review", "completion": "Run a doctor-gated Check-Up about every three months using weight, adherence, outcomes, and relevant timeline evidence.", "failure_retry": "No approved runtime exists. A future implementation must expose failures to the named owner and retry only under stable idempotency keys.", "system_of_record": "EHR follow-up encounter and decision record.", "actors": [ { "actor": "patient", "participation": "acts" }, { "actor": "doctor", "participation": "reviews" } ], "domains": [ "labs", "fulfillment", "follow-up" ], "journey_stage": "follow-up", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-08", "focus_nodes": [ "check-in", "evidence-packet", "three-month-gate", "clinician-review", "continue-change-stop" ] } ] }, { "key": "7.2", "number": "7.2", "section": 7, "section_title": "Async Care Loop", "id": "refills", "title": "Refills", "track": "doctor", "business_anchor": "refills", "technical_anchor": "7-2-refills", "as_built_anchor": "refills", "old_anchor": "7-2-refills-rx-partial", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "Future medication-continuity functionality intended to keep patients from running out while preserving clinician control.", "target": { "summary": "Compute refill eligibility from the prescription and expected depletion while preserving clinician approval and therapy holds.", "gaps": [ "Verify historical refill usage before redesign and connect approved refills to real fulfillment behavior." ] }, "open_decisions": [], "rules": [ { "id": "RRX-CARE-004", "text": "Refill eligibility is calculated from quantity, dose, frequency, days supply, start date, and expected depletion.", "enforcement": "Not enforced today: refill scheduling is a hardcoded 28-day cadence (app/services/agents/refill.rb sets next_refill_date = today+28; app/services/workflows/confirm_delivery.rb sets due_date = today+28). The refill_tasks table has no quantity/dose/frequency/days-supply/start-date/depletion fields, so eligibility is not computed as the rule describes (gap).", "source": "" }, { "id": "RRX-CARE-005", "text": "A clinician approves refill or reissue, and active therapy or safety holds remain authoritative.", "enforcement": "Partially enforced by code-gate: TherapyHolds::Guard.ensure_clear! (app/services/therapy_holds/guard.rb) raises Workflows::InvalidTransition to block a refill under an active therapy/safety hold, applied in Workflows::ConfirmRefill (app/services/workflows/confirm_refill.rb) and covered by test/services/agents/refill_test.rb. But there is no clinician refill/reissue APPROVAL step - refills are patient-confirmed - so that half of the rule is unenforced.", "source": "" }, { "id": "RRX-CARE-006", "text": "No patient message promises compounding or shipment until the corresponding fulfillment action exists.", "enforcement": "Convention-only: nothing ties compounding/shipment language to an existing fulfillment record. Linq outbound is restricted to approved templates by Linq::SendGuard (app/services/linq/send_guard.rb), which blocks arbitrary prose, but no check verifies a promise against a real PharmacyOrder/Shipment (e.g., the portal flash 'Pharmacy will queue your next compounding run' fires on patient confirm).", "source": "" } ], "legacy_technical_anchors": [ "7-2-refills-rx-partial", "7-2-refills-rx" ], "node_contract": { "kind": "workflow", "layer": "orchestration", "trigger": "A patient requests continuity or projected supply reaches depletion.", "inputs": [ "publish refill decision from Follow-Up Appointment" ], "outputs": [ "request clinician refill review to Follow-Up Appointment" ], "owner": "Clinical Product", "operator": "Named domain owner with authorized human review", "completion": "Compute refill eligibility from the prescription and expected depletion while preserving clinician approval and therapy holds.", "failure_retry": "No approved runtime exists. A future implementation must expose failures to the named owner and retry only under stable idempotency keys.", "system_of_record": "Refill request, clinician decision, and replacement prescription records.", "actors": [ { "actor": "patient", "participation": "acts" }, { "actor": "doctor", "participation": "acts" } ], "domains": [ "fulfillment", "follow-up" ], "journey_stage": "follow-up", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-08", "focus_nodes": [ "depletion-anchor", "refill-request", "clinician-review", "reissue", "therapy-active" ] } ] }, { "key": "7.3", "number": "7.3", "section": 7, "section_title": "Async Care Loop", "id": "doctor-newsfeed", "title": "Clinical Rounds", "track": "doctor", "business_anchor": "doctor-newsfeed", "technical_anchor": "7-3-clinical-rounds", "as_built_anchor": "doctor-newsfeed", "old_anchor": "7-3-newsfeed-timeline-doctor-facing-partial", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "The doctor-facing feed of meaningful patient progress, messages, refills, shipments, and clinical flags.", "target": { "summary": "Give doctors a patient-progress feed for Check-Ups, refills, messages, shipments, clinical flags, and meaningful health changes.", "gaps": [ "Build the Doctor Newsfeed as a distinct core surface and keep it separate from The Daily Compound." ] }, "open_decisions": [], "rules": [ { "id": "RRX-CARE-007", "text": "Use Doctor Newsfeed as the canonical name for the core provider surface.", "enforcement": "Convention-only: the Doctor Newsfeed surface is unbuilt - no 'newsfeed'/'news_feed' reference exists in app, lib, test, or origin/staging. The canonical name is honored by documentation discipline only (gap).", "source": "" }, { "id": "RRX-CARE-008", "text": "Feed events are attributable, patient-specific, and linked to their owning record or action.", "enforcement": "Not enforced today: the Doctor Newsfeed is unbuilt, so there are no feed events to attribute. The underlying Event model (app/models/event.rb) is polymorphic/attributable (eventable + actor, type allowlist) and linked to an owning record, but nothing assembles it into an attributable per-patient doctor feed (gap).", "source": "" }, { "id": "RRX-CARE-009", "text": "The Doctor Newsfeed remains distinct from The Daily Compound and from internal patient-graph history.", "enforcement": "Not enforced today: neither the Doctor Newsfeed nor 'The Daily Compound' exists in the codebase (no reference in app, lib, test, or origin/staging), so the required distinction is definitional only (gap).", "source": "" } ], "legacy_technical_anchors": [ "7-3-newsfeed-timeline-doctor-facing-partial", "7-3-newsfeed-timeline-doctor-facing" ], "node_contract": { "kind": "surface", "layer": "experience", "trigger": "An attributable patient, shipment, lab, refill, or clinical milestone arrives.", "inputs": [ "publish reviewed lab event from Lab Follow-up", "publish care delivery event from Delivery Bot" ], "outputs": [ "surface follow-up signal to Follow-Up Appointment" ], "owner": "Clinical Product", "operator": "Authorized patient, provider, or operations user", "completion": "Give doctors a patient-progress feed for Check-Ups, refills, messages, shipments, clinical flags, and meaningful health changes.", "failure_retry": "No approved runtime exists. A future implementation must expose failures to the named owner and retry only under stable idempotency keys.", "system_of_record": "Underlying EHR/event ledgers; the feed is a projection.", "actors": [ { "actor": "doctor", "participation": "receives" } ], "domains": [ "follow-up" ], "journey_stage": "follow-up", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-08", "focus_nodes": [ "shipment-evidence", "check-in", "evidence-packet", "clinician-review" ] } ] }, { "key": "7.4", "number": "7.4", "section": 7, "section_title": "Async Care Loop", "id": "doctor-patient-texting", "title": "Patient Chat", "track": "doctor", "business_anchor": "doctor-patient-texting", "technical_anchor": "7-4-patient-chat", "as_built_anchor": "doctor-patient-texting", "old_anchor": "7-4-doc-patient-texting-partial", "flags": [ "board-node", "staging-reverified" ], "what_it_is": "Doctors (and staff) texting patients directly.", "target": { "summary": "Keep doctor, staff, reminder, and transactional messaging on explicit Rails and Linq paths. Flue owns the onboarding reply brain only.", "gaps": [ "Build the missing doctor-to-patient surface without treating the onboarding Flue cutover as a replacement for this lane." ] }, "open_decisions": [], "rules": [ { "id": "RRX-CARE-010", "text": "Every outbound path has an identified owner, consent check, delivery policy, and observable failure path.", "enforcement": "Enforced by: app/services/linq/send_guard.rb (opt-out consent check, template+mode delivery policy, and observable reasons[] failure path applied on every LinqReplyJob-routed send) plus test/architecture/linq_takeover_sender_classification_test.rb, which inventories every Linq sender origin against an owner classification and fails on any unclassified or bypassing path. The dedicated doctor-to-patient lane itself is not yet built (card gap).", "source": "" }, { "id": "RRX-CARE-011", "text": "Human takeover suppresses agent replies until an explicit resume or expiry under the approved policy.", "enforcement": "Enforced by: test/services/workflows/linq_takeover_test.rb (strict 24h expiry boundary and explicit release clearing the claim) and test/services/linq/serialized_dispatch_takeover_concurrency_test.rb (an active takeover winning the chat lock blocks suppressible agent dispatch).", "source": "" }, { "id": "RRX-CARE-012", "text": "The onboarding Flue cutover does not replace doctor, staff, reminder, or transactional messaging paths.", "enforcement": "Enforced by: test/architecture/linq_takeover_sender_classification_test.rb - the transactional/staff/reminder senders (appointments notifier, health-history/weigh-in nudges, pre-doctor reminders, logins, admin messages, rx-ready-to-pay) are enumerated as an 'exempt' lane distinct from the conversational (onboarding) lane, so a cutover that removed or absorbed them fails the inventory. No 'Flue' code exists in this Rails repo (onboarding brain lives outside it).", "source": "" } ], "legacy_technical_anchors": [ "7-4-doc-patient-texting-partial", "7-4-doc-patient-texting" ], "node_contract": { "kind": "surface", "layer": "experience", "trigger": "A patient, doctor, or authorized staff member sends a care message.", "inputs": [ "send delivery milestone from Delivery Bot" ], "outputs": [ "screen care message to Medical Support Chat", "classify safe support turn to Agent Router" ], "owner": "Clinical Product", "operator": "Authorized patient, provider, or operations user", "completion": "Keep doctor, staff, reminder, and transactional messaging on explicit Rails and Linq paths. Flue owns the onboarding reply brain only.", "failure_retry": "No approved runtime exists. A future implementation must expose failures to the named owner and retry only under stable idempotency keys.", "system_of_record": "Rails/Linq conversation, consent, hold, delivery, and audit records.", "actors": [ { "actor": "patient", "participation": "receives" }, { "actor": "doctor", "participation": "acts" } ], "domains": [ "follow-up" ], "journey_stage": "support", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-01", "focus_nodes": [ "inbound", "safety-guards", "human-takeover", "delivery-authorization", "agent-reply" ] } ] }, { "key": "7.5", "number": "7.5", "section": 7, "section_title": "Async Care Loop", "id": "urgent-text-escalation", "title": "Medical Support Chat", "track": "doctor", "business_anchor": "urgent-text-escalation", "technical_anchor": "7-5-medical-support-chat", "as_built_anchor": "urgent-text-escalation", "old_anchor": "7-5-urgent-text-escalation-patient-dr-pharmacist-911-partial", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "The human escalation and audited resolution path for urgent patient messages.", "target": { "summary": "Classify urgent patient messages, place appropriate holds, notify the responsible human team, and record every action through resolution.", "gaps": [ "Connect a real paging transport and build the clinician queue for acknowledgements, adverse events, and hold release." ] }, "open_decisions": [], "rules": [ { "id": "RRX-CARE-013", "text": "Urgent messages are classified before ordinary conversational handling and may place an immediate safety hold.", "enforcement": "Enforced by: test/integration/api/v1/linq_red_flag_detector_test.rb (the red-flag detector provably runs before the typing/comprehension/voice agents and a tier-1 match latches an emergency hold + persists governed match metadata before normal planning) and test/services/linq/emergency_detection_test.rb (red-flag phrases classify to a tier-1 emergency hold reply).", "source": "" }, { "id": "RRX-CARE-014", "text": "The responsible doctor, pharmacist, or Ops responder receives an actionable notification with an acknowledgement deadline.", "enforcement": "Escalation ladder and acknowledgement-deadline scheduling are exercised by test/jobs/on_call_escalation_job_test.rb (5-min live call, 10-min ops fallback, halted once a clinician acknowledges), but actual paging delivery is external and NOT wired today: OnCall::Dispatch::ADAPTERS (app/services/on_call/dispatch.rb) is empty, ON_CALL_TRANSPORT is unset, and the boot guard fails closed - so a real responder notification is not delivered (card gap: connect a real paging transport).", "source": "" }, { "id": "RRX-CARE-015", "text": "Detection, contact attempts, acknowledgements, decisions, and hold release remain visible in the Ops audit trail.", "enforcement": "Enforced by: test/jobs/on_call_escalation_job_test.rb (detection ladder, contact/page attempts, and 'stops once acknowledged' recorded as AdverseEventEscalationEntry kinds) and test/controllers/staff/adverse_event_escalations_controller_test.rb (a same-clinic clinician acknowledgement is recorded to the encrypted escalation ledger and visible in Ops).", "source": "" }, { "id": "RRX-CARE-016", "text": "Therapy-hold release requires resolution confirmation and a fresh safety review.", "enforcement": "Enforced by: test/services/workflows/therapy_hold_workflows_test.rb, which drives app/services/workflows/release_therapy_hold.rb: release requires explicit trigger_resolved + resolution_confirmation AND a current passing glp1_fill_safety run, with missing/post-call/aged/reopened-chart evidence failing closed and confirmed pancreatitis never releasing.", "source": "" } ], "legacy_technical_anchors": [ "7-5-urgent-text-escalation-patient-dr-pharmacist-911-partial", "7-5-urgent-text-escalation-patient-dr-pharmacist-911" ], "node_contract": { "kind": "workflow", "layer": "orchestration", "trigger": "Deterministic screening identifies an urgent or emergency message.", "inputs": [ "screen inbound turn from iMessage (Linq)", "screen care message from Patient Chat", "resolve and release incident from Ops Console" ], "outputs": [ "release safe turn to Agent Router", "open urgent incident to Ops Console" ], "owner": "Clinical Product", "operator": "Named domain owner with authorized human review", "completion": "Classify urgent patient messages, place appropriate holds, notify the responsible human team, and record every action through resolution.", "failure_retry": "Failures remain attributable and visible to the named owner; retry only the owning idempotent command and never invent success.", "system_of_record": "Safety incident, hold, notification, action, and resolution records.", "actors": [ { "actor": "patient", "participation": "receives" }, { "actor": "doctor", "participation": "escalates" }, { "actor": "agent", "participation": "operates" } ], "domains": [ "follow-up" ], "journey_stage": "support", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-15", "focus_nodes": [ "deterministic-screen", "safety-hold", "governed-reply", "human-contact", "resolution", "release-hold" ] } ] }, { "key": "8.1", "number": "8.1", "section": 8, "section_title": "App Data & Health Profile", "id": "app-data-collection", "title": "Device Data", "track": "patient", "business_anchor": "app-data-collection", "technical_anchor": "8-1-device-data", "as_built_anchor": "app-data-collection", "old_anchor": "8-1-app-data-collection-withings-whoop-oura-healthkit-partial", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "Continuous patient data from approved devices and HealthKit, limited to information RonanRx can display and interpret responsibly.", "target": { "summary": "Ingest approved wearable and HealthKit data read-only after an in-app explanation and affirmative patient authorization.", "gaps": [ "Build a current backend and wire foreground and HealthKit observer synchronization; the removed 2026-07-17 snapshot implementation is historical only." ] }, "open_decisions": [], "rules": [ { "id": "RRX-DATA-001", "text": "HealthKit access is read-only and begins only after an in-app explanation and affirmative patient step before Apple's authorization dialog.", "enforcement": "Enforcement: to be confirmed in audit - HealthKit read-only access and the in-app explanation before Apple's authorization dialog are iOS-client behaviors with no code in this Rails repo (absent on main and origin/staging; the the 2026-07-17 snapshot implementation was removed and the backend is unbuilt per the card gap).", "source": "" }, { "id": "RRX-DATA-002", "text": "Ingest only data types RonanRx can display and interpret responsibly.", "enforcement": "Enforced for the only live device path (Oura) by app/services/oura/webhook_processor.rb (SUPPORTED_DATA_TYPES allowlist ignores any unsupported data_type) and app/services/oura/daily_sync.rb (only a curated set of interpretable metrics is normalized; rows carry the 'adjunctive wellness trend, not diagnostic' provenance label). The HealthKit app-data ingestion path is unbuilt (card gap).", "source": "" }, { "id": "RRX-DATA-003", "text": "Synchronize on foreground entry and through HealthKit observer delivery; do not invent hourly polling.", "enforcement": "Convention-only in this repo: the only wearable sync (Oura/Withings) uses daily recurring jobs (config/recurring.yml, 05:00/05:30 CT) plus provider webhooks (observer/push) - no hourly polling - but the HealthKit foreground-entry and observer synchronization the rule describes is iOS/app behavior that is unbuilt here (card gap); nothing in this repo enforces it.", "source": "" }, { "id": "RRX-DATA-004", "text": "Device data retains source, time, units, deduplication identity, and patient authorization state.", "enforcement": "Enforced by: test/services/workflows/ingest_wearable_daily_metrics_test.rb (one row per patient/provider/day; concurrent inserts reconciled) backed by the DB unique index idx_wearable_daily_metrics_patient_provider_date in db/structure.sql for deduplication identity. Source (provider + wearable_connection), time (measured_on), and source_ref are columns and authorization is the active wearable_connection + logged PhiAccess consent, but 'units' are not separately modeled (opaque metrics jsonb).", "source": "" } ], "legacy_technical_anchors": [ "8-1-app-data-collection-withings-whoop-oura-healthkit-partial", "8-1-app-data-collection-withings-whoop-oura-healthkit" ], "node_contract": { "kind": "integration", "layer": "integration", "trigger": "The patient grants a supported device or HealthKit authorization.", "inputs": [ "sync consented observations from RonanRX iOS" ], "outputs": [ "add approved device signals to Pre-Brief", "acknowledge sync cursor to RonanRX iOS", "project governed observations to Clinical Note", "add weight and adherence signals to Follow-Up Appointment" ], "owner": "Patient Product", "operator": "Owning integration service and external counterparty", "completion": "Ingest approved wearable and HealthKit data read-only after an in-app explanation and affirmative patient authorization.", "failure_retry": "Failures remain attributable and visible to the named owner; retry only the owning idempotent command and never invent success.", "system_of_record": "EHR/device observation records with source and authorization.", "actors": [ { "actor": "patient", "participation": "acts" } ], "domains": [ "follow-up" ], "journey_stage": "follow-up", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-16", "focus_nodes": [ "patient-consent", "oauth-healthkit", "sync-or-webhook", "allowlist", "normalize-dedupe", "consumer-projection", "revoke" ] } ] }, { "key": "8.2", "number": "8.2", "section": 8, "section_title": "App Data & Health Profile", "id": "health-history-questionnaire", "title": "Intake 3: Medical History", "track": "patient", "business_anchor": "health-history-questionnaire", "technical_anchor": "8-2-intake-3-medical-history", "as_built_anchor": "health-history-questionnaire", "old_anchor": "8-2-info-3-full-health-profile-partial", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "The deep patient health repository: full health-history questionnaire, goals, dose and side-effect logs.", "target": { "summary": "Promote patient-reported health history into the EHR with provenance, conflict history, and authorized reconciliation.", "gaps": [ "Build the governed promotion and conflict queue and make approved reminders deliver by default." ] }, "open_decisions": [], "rules": [ { "id": "RRX-DATA-005", "text": "Patient-reported health history belongs in the official EHR with a patient-reported label and full provenance.", "enforcement": "Enforced by: test/services/ehr/health_history_projector_test.rb, which drives app/services/ehr/health_history_projector.rb: completed answers project into Ehr::MedicalHistory with source 'patient_reported' and a clinical_snapshot carrying full provenance (source health-history id, questionnaire version, revision number, completed_at, projection fingerprint) plus an 'ehr_health_history_projected' audit event.", "source": "" }, { "id": "RRX-DATA-006", "text": "Conflicting values preserve both histories and enter a doctor or authorized-admin reconciliation queue.", "enforcement": "Convention-only: nothing enforces this today. Ehr::HealthHistoryReview (pending_review) is a projection-review sidecar, not a value-level conflict queue; the projector overwrites the source label and retires prior patient-reported facts rather than preserving both, and the governed promotion + doctor/authorized-admin conflict-reconciliation queue is explicitly unbuilt (card gap).", "source": "" }, { "id": "RRX-DATA-007", "text": "Do not ask the patient for a fact the governed record already contains unless confirmation is required.", "enforcement": "Enforced by: test/services/health_history/intake_prefill_test.rb - facts already supplied at signup are mapped into confirmation-only Health Story prefills carrying source_label ('From your secure signup') and source_reference, so known facts are re-surfaced for confirmation rather than asked again; deferred sentinels/blanks are suppressed.", "source": "" } ], "legacy_technical_anchors": [ "8-2-info-3-full-health-profile-partial", "8-2-info-3-full-health-profile" ], "node_contract": { "kind": "workflow", "layer": "orchestration", "trigger": "A governed later-intake plan has missing or reviewable health-history facts.", "inputs": [ "No operational input; activated only by its stated trigger." ], "outputs": [ "add medical history to Pre-Brief", "project patient history to Clinical Note" ], "owner": "Patient Product", "operator": "Named domain owner with authorized human review", "completion": "Promote patient-reported health history into the EHR with provenance, conflict history, and authorized reconciliation.", "failure_retry": "Failures remain attributable and visible to the named owner; retry only the owning idempotent command and never invent success.", "system_of_record": "HealthHistory responses and promoted EHR facts with provenance.", "actors": [ { "actor": "patient", "participation": "acts" } ], "domains": [ "onboarding", "follow-up" ], "journey_stage": "pre-visit", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-17", "focus_nodes": [ "known-fact-prefill", "missing-questions", "autosave", "ehr-projection", "conflict-resolution" ] } ] }, { "key": "9.1", "number": "9.1", "section": 9, "section_title": "AI / Agent Layer", "id": "agent-router", "title": "Agent Router", "track": "ai-agents", "business_anchor": "agent-router", "technical_anchor": "9-1-agent-router", "as_built_anchor": "agent-router", "old_anchor": "9-1-agent-router-partial", "flags": [ "board-node", "staging-reverified" ], "what_it_is": "The routing layer that sends each conversation to a focused agent while preserving safety, consent, and human-control boundaries.", "target": { "summary": "Route conversational agent work through focused Flue agents, beginning with onboarding, without weakening the Rails safety and delivery boundary.", "gaps": [] }, "open_decisions": [], "rules": [ { "id": "RRX-AGENTS-013", "text": "Safety, opt-out, and human-takeover branches run before conversational agent routing.", "enforcement": "Enforced by: test/integration/api/v1/linq_takeover_suppression_test.rb (asserts human-takeover, red-flag, and dosing safety branches run before and outrank conversational agent routing: generative agents never run and no reply is enqueued during a hold); ordering lives in app/controllers/api/v1/linq_controller.rb#inbound.", "source": "" }, { "id": "RRX-AGENTS-014", "text": "Each Flue agent owns one focused conversational responsibility.", "enforcement": "Convention-only: each Agents:: subclass declares a single artifact_kind/event_action by the BaseAgent pattern, but nothing tests that an agent owns exactly one conversational lane.", "source": "" }, { "id": "RRX-AGENTS-015", "text": "Routing expansion requires an explicit owner and boundary for the new lane.", "enforcement": "Convention-only: routing/lane expansion has no owner-or-boundary gate; the only adjacent guard is test/architecture/linq_takeover_sender_classification_test.rb, which forces new Linq send sites to be explicitly classified but does not enforce lane ownership or scope.", "source": "" } ], "legacy_technical_anchors": [ "9-1-agent-router-partial" ], "node_contract": { "kind": "deterministic-automation", "layer": "automation", "trigger": "Rails authorizes a conversational turn after ingress guards.", "inputs": [ "release safe turn from Medical Support Chat", "classify safe support turn from Patient Chat", "apply agent operating rules from Cam's Crack Commandments" ], "outputs": [ "start focused onboarding turn to Onboarding Agent", "route service support to Patient Support", "route explicit cancellation turn to Retention Agent", "route approved founder-mode turn to Founder Mode / Dr. Bot" ], "owner": "AI Platform", "operator": "Rails worker or scheduled domain service", "completion": "Route conversational agent work through focused Flue agents, beginning with onboarding, without weakening the Rails safety and delivery boundary.", "failure_retry": "Failures remain attributable and visible to the named owner; retry only the owning idempotent command and never invent success.", "system_of_record": "Rails route decision and conversation audit records.", "actors": [ { "actor": "agent", "participation": "operates" }, { "actor": "operations", "participation": "operates" } ], "domains": [ "onboarding", "governance" ], "journey_stage": "governance", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-01", "focus_nodes": [ "safety-guards", "route-turn", "agent-turn", "human-hold" ] } ] }, { "key": "9.2", "number": "9.2", "section": 9, "section_title": "AI / Agent Layer", "id": "patient-support", "title": "Patient Support", "track": "ai-agents", "business_anchor": "patient-support", "technical_anchor": "9-2-patient-support", "as_built_anchor": "patient-support", "old_anchor": "9-2-customer-service-questions-cancellation-partial", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "AI-assisted customer service, including cancellation handling.", "target": { "summary": "Provide patient support and deliberate cancellation handling without automatically cancelling a paid membership.", "gaps": [ "Add patient and staff cancellation flows, a staff reply surface, and a focused support agent with human escalation." ] }, "open_decisions": [], "rules": [ { "id": "RRX-AGENTS-016", "text": "RonanRx does not cancel a membership automatically.", "enforcement": "Convention-only: no automated membership-cancellation path exists; the sole cancel path (Onboarding::CancelSubscription) is a deliberate onboarding action for non-serviceable states during the free first month. Nothing enforces the never-automatic invariant.", "source": "" }, { "id": "RRX-AGENTS-017", "text": "Serviceability is resolved before payment activation whenever possible; later issues go to staff for deliberate handling.", "enforcement": "Convention-only: serviceability is computed by Onboarding::Serviceability and shown in the completion wizard, but since the payment-ungated hotfixes (#659/#661) it gates nothing at payment (per the Onboarding::PaymentEligibility comment); non-serviceable cases are handled deliberately by staff via Onboarding::CancelSubscription. No hard gate enforces resolution-before-payment.", "source": "" }, { "id": "RRX-AGENTS-018", "text": "Patient support can escalate to a human without losing conversation or decision history.", "enforcement": "Convention-only: Agents::PatientSupport can set escalate/human_approval_required and every run is preserved as an Artifact+Event, but no staff reply/escalation surface is wired yet (card gap), so human escalation is not enforced end-to-end.", "source": "" } ], "legacy_technical_anchors": [ "9-2-customer-service-questions-cancellation-partial", "9-2-customer-service-questions-cancellation" ], "node_contract": { "kind": "ai-agent", "layer": "agent", "trigger": "A service, billing, or cancellation-support intent is routed.", "inputs": [ "route service support from Agent Router" ], "outputs": [ "offer governed retention to Retention Agent", "escalate support exception to Ops Console" ], "owner": "AI Platform", "operator": "Focused agent under Rails guards with human takeover", "completion": "Provide patient support and deliberate cancellation handling without automatically cancelling a paid membership.", "failure_retry": "No approved runtime exists. A future implementation must expose failures to the named owner and retry only under stable idempotency keys.", "system_of_record": "Owning domain records and agent audit events; no independent clinical side store.", "actors": [ { "actor": "agent", "participation": "operates" } ], "domains": [ "follow-up" ], "journey_stage": "support", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-18", "focus_nodes": [ "intent-route", "service-support", "billing-support", "clinical-escalation", "human-resolution" ] } ] }, { "key": "9.3", "number": "9.3", "section": 9, "section_title": "AI / Agent Layer", "id": "retention-agent", "title": "Retention Agent", "track": "ai-agents", "business_anchor": "retention-agent", "technical_anchor": "9-3-retention-agent", "as_built_anchor": "retention-agent", "old_anchor": "9-3-retention-agent-future", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "The focused agent that helps a patient during an explicit cancellation flow.", "target": { "summary": "Offer governed retention help when a patient explicitly enters a cancellation flow, without obstructing cancellation.", "gaps": [ "Build the cancellation flow first, then add the focused retention lane." ] }, "open_decisions": [], "rules": [ { "id": "RRX-AGENTS-019", "text": "Retention help begins only from an explicit cancellation flow and never prevents the patient from completing cancellation.", "enforcement": "Convention-only: the retention agent is unbuilt on main and origin/staging (future card; the cancellation flow it depends on is not built). Nothing enforces this today.", "source": "" }, { "id": "RRX-AGENTS-020", "text": "The lane remains focused on retention and hands clinical, billing, or safety issues to their owning workflows.", "enforcement": "Convention-only: the retention agent is unbuilt on main and origin/staging (future card); nothing enforces its lane focus or hand-offs today.", "source": "" } ], "legacy_technical_anchors": [ "9-3-retention-agent-future" ], "node_contract": { "kind": "ai-agent", "layer": "agent", "trigger": "A patient explicitly enters the cancellation flow.", "inputs": [ "offer governed retention from Patient Support", "route explicit cancellation turn from Agent Router" ], "outputs": [ "No operational output in the approved graph." ], "owner": "AI Platform", "operator": "Focused agent under Rails guards with human takeover", "completion": "Offer governed retention help when a patient explicitly enters a cancellation flow, without obstructing cancellation.", "failure_retry": "No approved runtime exists. A future implementation must expose failures to the named owner and retry only under stable idempotency keys.", "system_of_record": "Owning domain records and agent audit events; no independent clinical side store.", "actors": [ { "actor": "agent", "participation": "operates" } ], "domains": [ "follow-up" ], "journey_stage": "support", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-18", "focus_nodes": [ "cancellation-intent", "optional-retention", "confirm-cancel", "human-resolution" ] } ] }, { "key": "9.4", "number": "9.4", "section": 9, "section_title": "AI / Agent Layer", "id": "founder-mode", "title": "Founder Mode / Dr. Bot", "track": "ai-agents", "business_anchor": "founder-mode", "technical_anchor": "9-4-founder-mode-dr-bot", "as_built_anchor": "founder-mode", "old_anchor": "9-4-dr-bot-founder-mode-partial", "flags": [ "board-node", "staging-reverified" ], "what_it_is": "An intended patient product that captures the patient's goal/treatment interest, captures provider willingness/qualification, and matches patients to appropriate providers and programs.", "target": { "summary": "Keep Founder Mode and Doctor Bot as product intent and reintroduce it on the Flue and rrx-agents architecture after its clinical boundaries are approved.", "gaps": [] }, "open_decisions": [ { "id": "D5", "status": "open", "owner": "Zach", "opened_on": "2026-07-21", "question": "Define the clinical boundaries for Founder Mode and Doctor Bot on the Flue and rrx-agents architecture. Do not implement until answered." } ], "rules": [ { "id": "RRX-AGENTS-021", "text": "Founder Mode and Doctor Bot remain approved intent but must not be implemented until Zach defines the clinical boundaries.", "enforcement": "Convention-only: enforced by governance (open decision D5, owner Zach), not code; nothing prevents implementation. Note: a distinct trigger-gated Linq::FounderMode demo-intake variant exists, but the Dr. Bot matching product this rule governs is deferred.", "source": "" }, { "id": "RRX-AGENTS-022", "text": "Any implementation belongs on the Flue and rrx-agents architecture rather than reviving the deleted Ruby path unchanged.", "enforcement": "Convention-only: an architecture directive (any implementation belongs on Flue/rrx-agents, not the deleted Ruby path); nothing enforces where a future implementation lives.", "source": "" } ], "legacy_technical_anchors": [ "9-4-dr-bot-founder-mode-future", "9-4-dr-bot-founder-mode" ], "node_contract": { "kind": "ai-agent", "layer": "agent", "trigger": "Approved provider-matching product boundaries activate this focused agent.", "inputs": [ "route approved founder-mode turn from Agent Router" ], "outputs": [ "No operational output in the approved graph." ], "owner": "AI Platform", "operator": "Focused agent under Rails guards with human takeover", "completion": "Keep Founder Mode and Doctor Bot as product intent and reintroduce it on the Flue and rrx-agents architecture after its clinical boundaries are approved.", "failure_retry": "No approved runtime exists. A future implementation must expose failures to the named owner and retry only under stable idempotency keys.", "system_of_record": "Owning domain records and agent audit events; no independent clinical side store.", "actors": [ { "actor": "agent", "participation": "operates" } ], "domains": [ "agent-platform" ], "journey_stage": "governance", "map_presence": "default" }, "subdiagram_refs": [] }, { "key": "9.5", "number": "9.5", "section": 9, "section_title": "AI / Agent Layer", "id": "medical-research-agent", "title": "Medical Research Agent", "track": "ai-agents", "business_anchor": "medical-research-agent", "technical_anchor": "9-5-medical-research-agent", "as_built_anchor": "medical-research-agent", "old_anchor": "9-5-medical-research-agent-partial", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "The focused agent that answers clinical research questions from governed evidence with traceable citations.", "target": { "summary": "Answer clinical research questions from a governed evidence corpus with traceable citations and mandatory human review.", "gaps": [ "Connect synthesis to the corpus, grade evidence, expose a review surface, and then enable ingestion." ] }, "open_decisions": [], "rules": [ { "id": "RRX-AGENTS-023", "text": "Every clinical answer is grounded in the governed evidence corpus and carries traceable citations.", "enforcement": "Convention-only: Agents::ResearchSynthesis prompts the LLM for citations and an evidence grade but is not wired to the governed evidence corpus (the research/ ingestion pipeline is separate); nothing enforces corpus grounding today (card gap: connect synthesis to the corpus).", "source": "" }, { "id": "RRX-AGENTS-024", "text": "Evidence quality and conflicts are visible to the human reviewer.", "enforcement": "Convention-only: the evidence_packet artifact carries an evidence_grade field, but no reviewer surface exposing evidence quality or conflicts is built (card gap); nothing enforces visibility.", "source": "" }, { "id": "RRX-AGENTS-025", "text": "No research-agent output becomes patient care or prescribing action without human approval.", "enforcement": "Enforced by: app/services/workflows/approve_by_doctor.rb (gate \"ai_never_makes_final_prescribing_decision\" plus a hard actor.role == \"doctor\" guard before any Prescription is created); the research agent's output is a non-actioning reference artifact.", "source": "" } ], "legacy_technical_anchors": [ "9-5-medical-research-agent-partial" ], "node_contract": { "kind": "ai-agent", "layer": "agent", "trigger": "An authorized clinician asks a governed evidence question.", "inputs": [ "No operational input; activated only by its stated trigger." ], "outputs": [ "attach cited research to Pre-Brief" ], "owner": "AI Platform", "operator": "Focused agent under Rails guards with human takeover", "completion": "Answer clinical research questions from a governed evidence corpus with traceable citations and mandatory human review.", "failure_retry": "No approved runtime exists. A future implementation must expose failures to the named owner and retry only under stable idempotency keys.", "system_of_record": "Owning domain records and agent audit events; no independent clinical side store.", "actors": [ { "actor": "doctor", "participation": "reviews" }, { "actor": "agent", "participation": "operates" } ], "domains": [ "agent-platform" ], "journey_stage": "clinical-decision", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-19", "focus_nodes": [ "resolve-sources", "governed-corpus", "citation-graph", "synthesis", "human-review" ] } ] }, { "key": "9.6", "number": "9.6", "section": 9, "section_title": "AI / Agent Layer", "id": "nutrition-fitness-agent", "title": "Health Coach", "track": "ai-agents", "business_anchor": "nutrition-fitness-agent", "technical_anchor": "9-6-health-coach", "as_built_anchor": "nutrition-fitness-agent", "old_anchor": "9-6-nutrition-bot-fitness-future", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "The focused nutrition and fitness coaching agent for approved programs.", "target": { "summary": "Provide focused nutrition and fitness coaching for approved programs within explicit clinical and escalation boundaries.", "gaps": [ "Define and build the complete focused agent." ] }, "open_decisions": [], "rules": [ { "id": "RRX-AGENTS-026", "text": "Nutrition and fitness coaching stays inside the approved program and clinical boundaries.", "enforcement": "Convention-only: no nutrition/fitness agent exists on main or origin/staging (future card); nothing enforces the program/clinical boundary today.", "source": "" }, { "id": "RRX-AGENTS-027", "text": "Clinical, safety, or medication questions hand off to the responsible care workflow.", "enforcement": "Convention-only: no nutrition/fitness agent exists on main or origin/staging (future card); nothing enforces clinical/medication hand-off today.", "source": "" } ], "legacy_technical_anchors": [ "9-6-nutrition-bot-fitness-future", "9-6-nutrition-bot-fitness" ], "node_contract": { "kind": "ai-agent", "layer": "agent", "trigger": "An enrolled patient requests approved coaching.", "inputs": [ "No operational input; activated only by its stated trigger." ], "outputs": [ "No operational output in the approved graph." ], "owner": "AI Platform", "operator": "Focused agent under Rails guards with human takeover", "completion": "Provide focused nutrition and fitness coaching for approved programs within explicit clinical and escalation boundaries.", "failure_retry": "No approved runtime exists. A future implementation must expose failures to the named owner and retry only under stable idempotency keys.", "system_of_record": "Owning domain records and agent audit events; no independent clinical side store.", "actors": [ { "actor": "agent", "participation": "operates" } ], "domains": [ "follow-up" ], "journey_stage": "follow-up", "map_presence": "default" }, "subdiagram_refs": [] }, { "key": "9.7", "number": "9.7", "section": 9, "section_title": "AI / Agent Layer", "id": "drift-layer", "title": "Greptile Watchdog", "track": "ai-agents", "business_anchor": "drift-layer", "technical_anchor": "9-7-greptile-watchdog", "as_built_anchor": "drift-layer", "old_anchor": "9-7-drift-greptile-agent-self-checking-layer-partial", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "The review layer that compares implementation with the approved suite and presents drift to humans.", "target": { "summary": "Detect drift between code and the reviewed suite, present a diff to humans, and never block a merge solely because the spec was not updated.", "gaps": [ "Build review alerts, generated diffs, ownership, and a human close-and-verify workflow." ] }, "open_decisions": [], "rules": [ { "id": "RRX-AGENTS-028", "text": "Drift produces an explainable diff, owner, and human review request.", "enforcement": "Convention-only: no drift-detection/self-checking layer exists on main or origin/staging (future card; gap: build alerts, generated diffs, ownership, close-and-verify). Nothing produces a drift diff/owner/review request today.", "source": "" }, { "id": "RRX-AGENTS-029", "text": "A missing spec edit alone does not automatically reject a merge.", "enforcement": "Convention-only: no spec-vs-code merge gate exists, so a missing spec edit cannot block a merge; the non-blocking behavior holds only because the drift layer is unbuilt, not because anything enforces it.", "source": "" }, { "id": "RRX-AGENTS-030", "text": "Closing a drift finding requires a recorded fix or an approved registry update plus verification.", "enforcement": "Convention-only: the drift layer is unbuilt (future card); nothing enforces that closing a drift finding requires a recorded fix or approved registry update plus verification.", "source": "" } ], "legacy_technical_anchors": [ "9-7-drift-greptile-agent-self-checking-layer-partial", "9-7-drift-greptile-agent-self-checking-layer" ], "node_contract": { "kind": "deterministic-automation", "layer": "automation", "trigger": "A code, spec, or deployed-runtime comparison detects a discrepancy.", "inputs": [ "No operational input; activated only by its stated trigger." ], "outputs": [ "No operational output in the approved graph." ], "owner": "AI Platform", "operator": "Rails worker or scheduled domain service", "completion": "Detect drift between code and the reviewed suite, present a diff to humans, and never block a merge solely because the spec was not updated.", "failure_retry": "No approved runtime exists. A future implementation must expose failures to the named owner and retry only under stable idempotency keys.", "system_of_record": "Owning Rails domain records described by the technical contract.", "actors": [ { "actor": "agent", "participation": "operates" }, { "actor": "operations", "participation": "operates" } ], "domains": [ "governance" ], "journey_stage": "governance", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-20", "focus_nodes": [ "compare", "finding", "owner-assign", "fix-or-approve", "verify", "close" ] } ] }, { "key": "9.8", "number": "9.8", "section": 9, "section_title": "AI / Agent Layer", "id": "agent-census", "title": "Agent Census", "track": "ai-agents", "business_anchor": "agent-census", "technical_anchor": "9-8-agent-census", "as_built_anchor": "agent-census", "old_anchor": "9-8-agent-census-all-22-agents-baseagent", "flags": [ "unverified-carried-forward" ], "what_it_is": "The maintained census of agents, their runtime type, wiring state, and responsibility.", "target": { "summary": "Maintain a cross-runtime census of focused agents, models, callers, wiring state, and ownership.", "gaps": [ "Complete the production census in D10 and distinguish Ruby agents from the Flue onboarding agent." ] }, "open_decisions": [ { "id": "D10", "status": "open", "owner": "Engineering (bead vfyq)", "opened_on": "2026-07-21", "question": "Complete the card-by-card legacy production census before enabling automated spec enforcement." } ], "rules": [ { "id": "RRX-AGENTS-031", "text": "The census covers every production-relevant Ruby and Flue agent, its model or deterministic type, callers, wiring state, and owner.", "enforcement": "Convention-only: no maintained cross-runtime agent census exists (open decision D10). Partial machine-checked inventories exist (clinical_agent_fallbacks_test lists 8 real-LLM agents; linq_takeover_sender_classification_test inventories send sites) but none records model/callers/wiring-state/owner, and nothing enforces completeness.", "source": "" }, { "id": "RRX-AGENTS-032", "text": "Historical counts are labeled by branch and date; they never stand in for the D10 production census.", "enforcement": "Convention-only: a governance rule tied to D10 (historical counts must be labeled by branch and date and never substitute for the production census); nothing in code enforces it.", "source": "" } ], "node_contract": { "kind": "registry", "layer": "data", "trigger": "An agent, model, caller, owner, or wiring state changes.", "inputs": [ "No operational input; activated only by its stated trigger." ], "outputs": [ "No operational output in the approved graph." ], "owner": "AI Platform", "operator": "Authorized domain steward", "completion": "Maintain a cross-runtime census of focused agents, models, callers, wiring state, and ownership.", "failure_retry": "Failures remain attributable and visible to the named owner; retry only the owning idempotent command and never invent success.", "system_of_record": "Versioned agent registry.", "actors": [ { "actor": "agent", "participation": "subject" }, { "actor": "operations", "participation": "operates" } ], "domains": [ "governance" ], "journey_stage": "governance", "map_presence": "view-only", "map_geometry": { "x": 384, "y": 948, "width": 152, "height": 44 } }, "subdiagram_refs": [] }, { "key": "10.1", "number": "10.1", "section": 10, "section_title": "RonanRX iOS & Scope Boundaries", "id": "ronanrx-ios", "title": "RonanRX iOS", "track": "patient", "business_anchor": "ronanrx-ios", "technical_anchor": "10-1-ronanrx-ios", "as_built_anchor": "ronanrx-ios", "old_anchor": "10-1-ronanrx-ios-app-partial", "flags": [ "unverified-carried-forward" ], "what_it_is": "The native RonanRX iOS patient app: the HealthKit data-feed leg plus (eventually) the patient's daily companion.", "target": { "summary": "Ship the native RonanRX patient experience and a current, supported backend for its approved HealthKit and care flows.", "gaps": [ "Rebuild or restore the required mobile APIs against current main and staging; do not treat the removed 2026-07-17 snapshot implementation as current substrate." ] }, "open_decisions": [], "rules": [ { "id": "RRX-PLATFORM-001", "text": "The app's product name is RonanRX and its bundle identifier is `com.ronanrx.app`.", "enforcement": "Enforced in the separate RonanRX_iOS app (Xcode bundle identifier com.ronanrx.app); not present in the ronanrx-core Rails repo.", "source": "" }, { "id": "RRX-PLATFORM-002", "text": "HealthKit follows the read-only authorization and synchronization rules in App Data Collection.", "enforcement": "Enforced in the RonanRX_iOS app (HealthKit read-only authorization); the Rails-side mobile sync API was removed (2026-07-17 snapshot) and is not present in ronanrx-core today (only Oura/Withings webhook feeds exist).", "source": "" }, { "id": "RRX-PLATFORM-003", "text": "Existing app infrastructure is reviewed against current code and intent before removal or replacement.", "enforcement": "Convention-only: nothing enforces this today.", "source": "" } ], "legacy_technical_anchors": [ "10-1-ronanrx-ios-app-partial", "10-1-ronanrx-ios-app" ], "node_contract": { "kind": "surface", "layer": "experience", "trigger": "A patient opens the native app or a supported background care sync runs.", "inputs": [ "acknowledge sync cursor from Device Data" ], "outputs": [ "sync consented observations to Device Data" ], "owner": "Patient Product", "operator": "Authorized patient, provider, or operations user", "completion": "Ship the native RonanRX patient experience and a current, supported backend for its approved HealthKit and care flows.", "failure_retry": "No approved runtime exists. A future implementation must expose failures to the named owner and retry only under stable idempotency keys.", "system_of_record": "Rails EHR/care APIs; local outbox is transient delivery state.", "actors": [ { "actor": "patient", "participation": "acts" } ], "domains": [ "patient-platform" ], "journey_stage": "platform", "map_presence": "view-only", "map_geometry": { "x": 1216, "y": 948, "width": 168, "height": 44 } }, "subdiagram_refs": [ { "subgraph_id": "sg-16", "focus_nodes": [ "patient-consent", "local-outbox", "sync-or-webhook", "normalize-dedupe", "consumer-projection", "retry-queue" ] } ] }, { "key": "10.2", "number": "10.2", "section": 10, "section_title": "RonanRX iOS & Scope Boundaries", "id": "the-daily-compound", "title": "The Daily Compound", "track": "patient", "business_anchor": "the-daily-compound", "technical_anchor": "10-2-the-daily-compound", "as_built_anchor": "the-daily-compound", "old_anchor": "10-2-ronanrx-timeline-the-daily-compound-out-of-current-approval-scope", "flags": [ "scope-boundary", "unverified-carried-forward" ], "what_it_is": "This source-of-truth pass covers `ronanrx-core` and `RonanRX_iOS`. The separate Timeline product is not being approved, status-badged, or fact-checked in this pass.", "target": { "summary": "Keep The Daily Compound outside this suite and distinct from the Doctor Newsfeed until a separate audit admits it.", "gaps": [] }, "open_decisions": [], "rules": [ { "id": "RRX-PLATFORM-004", "text": "The Daily Compound is outside this suite and is not the Doctor Newsfeed.", "enforcement": "Convention-only: The Daily Compound does not appear in ronanrx-core; nothing enforces this today.", "source": "" }, { "id": "RRX-PLATFORM-005", "text": "Do not import runtime, privacy, launch, or scheduling claims until a separate audit admits them.", "enforcement": "Convention-only: nothing enforces this today.", "source": "" } ], "legacy_technical_anchors": [ "10-2-ronanrx-timeline-the-daily-compound-out-of-current-approval-scope" ], "node_contract": { "kind": "surface", "layer": "experience", "trigger": "A separate scope review explicitly admits the Timeline product.", "inputs": [ "No operational input; activated only by its stated trigger." ], "outputs": [ "No operational output in the approved graph." ], "owner": "Patient Product", "operator": "Authorized patient, provider, or operations user", "completion": "Keep The Daily Compound outside this suite and distinct from the Doctor Newsfeed until a separate audit admits it.", "failure_retry": "No retry applies while this card remains outside the operating graph.", "system_of_record": "Owning Rails domain records described by the technical contract.", "actors": [ { "actor": "patient", "participation": "subject" } ], "domains": [ "patient-platform" ], "journey_stage": "out-of-scope", "map_presence": "scope-drawer" }, "subdiagram_refs": [] }, { "key": "10.3", "number": "10.3", "section": 10, "section_title": "RonanRX iOS & Scope Boundaries", "id": "ronanrx-brain", "title": "ronanrx-brain", "track": "ops", "business_anchor": "ronanrx-brain", "technical_anchor": "10-3-ronanrx-brain", "as_built_anchor": "ronanrx-brain", "old_anchor": "10-3-ronanrx-brain-out-of-current-approval-scope", "flags": [ "scope-boundary", "unverified-carried-forward" ], "what_it_is": "Do not include RonanRX Brain in this source-of-truth reconciliation. It is a separate company-operations system, not the patient/doctor product in `ronanrx-core` or the RonanRX iOS app.", "target": { "summary": "Keep ronanrx-brain outside the patient and doctor product scope until a separate audit admits it.", "gaps": [] }, "open_decisions": [], "rules": [ { "id": "RRX-PLATFORM-006", "text": "ronanrx-brain is outside the patient and doctor product scope.", "enforcement": "Convention-only: ronanrx-brain does not appear in ronanrx-core; nothing enforces this today.", "source": "" }, { "id": "RRX-PLATFORM-007", "text": "Do not import governance, deployment, fleet, or data claims until a separate audit admits them.", "enforcement": "Convention-only: nothing enforces this today.", "source": "" } ], "legacy_technical_anchors": [ "10-3-ronanrx-brain-out-of-current-approval-scope" ], "node_contract": { "kind": "registry", "layer": "data", "trigger": "A separate scope review explicitly admits the company-operations system.", "inputs": [ "No operational input; activated only by its stated trigger." ], "outputs": [ "No operational output in the approved graph." ], "owner": "Operations Platform", "operator": "Authorized domain steward", "completion": "Keep ronanrx-brain outside the patient and doctor product scope until a separate audit admits it.", "failure_retry": "No retry applies while this card remains outside the operating graph.", "system_of_record": "Owning Rails domain records described by the technical contract.", "actors": [ { "actor": "operations", "participation": "operates" } ], "domains": [ "operations-platform" ], "journey_stage": "out-of-scope", "map_presence": "scope-drawer" }, "subdiagram_refs": [] }, { "key": "10.4", "number": "10.4", "section": 10, "section_title": "RonanRX iOS & Scope Boundaries", "id": "elite-care-pharmacy-site", "title": "Elite Care Pharmacy Site", "track": "ops", "business_anchor": "elite-care-pharmacy-site", "technical_anchor": "10-4-elite-care-pharmacy-site", "as_built_anchor": "elite-care-pharmacy-site", "old_anchor": "10-4-elite-care-pharmacy-brand-site-out-of-current-approval-scope", "flags": [ "scope-boundary", "unverified-carried-forward" ], "what_it_is": "The separate pharmacy marketing-site repository is outside this `ronanrx-core` + `RonanRX_iOS` reconciliation pass. This does not remove Elite Care Pharmacy from the core fulfillment and billing requirements in §§3, 5, and 6.", "target": { "summary": "Keep the Elite Care Pharmacy marketing site outside this suite while retaining pharmacy fulfillment and billing requirements here.", "gaps": [] }, "open_decisions": [], "rules": [ { "id": "RRX-PLATFORM-008", "text": "The Elite Care Pharmacy marketing site is outside this suite.", "enforcement": "Convention-only: the Elite Care Pharmacy marketing site does not appear in ronanrx-core (only pharmacy fulfillment/billing references exist); nothing enforces this today.", "source": "" }, { "id": "RRX-PLATFORM-009", "text": "Its exclusion does not remove pharmacy fulfillment, billing, or licensing requirements owned by core cards.", "enforcement": "Convention-only: nothing enforces this today.", "source": "" } ], "legacy_technical_anchors": [ "10-4-elite-care-pharmacy-brand-site-out-of-current-approval-scope" ], "node_contract": { "kind": "surface", "layer": "experience", "trigger": "A separate scope review explicitly admits the marketing-site repository.", "inputs": [ "No operational input; activated only by its stated trigger." ], "outputs": [ "No operational output in the approved graph." ], "owner": "Operations Platform", "operator": "Authorized patient, provider, or operations user", "completion": "Keep the Elite Care Pharmacy marketing site outside this suite while retaining pharmacy fulfillment and billing requirements here.", "failure_retry": "No retry applies while this card remains outside the operating graph.", "system_of_record": "Owning Rails domain records described by the technical contract.", "actors": [ { "actor": "operations", "participation": "operates" } ], "domains": [ "operations-platform" ], "journey_stage": "out-of-scope", "map_presence": "scope-drawer" }, "subdiagram_refs": [] }, { "key": "10.5", "number": "10.5", "section": 10, "section_title": "RonanRX iOS & Scope Boundaries", "id": "protocol-sandbox", "title": "TestFlight Protocol Sandbox", "track": "ops", "business_anchor": "protocol-sandbox", "technical_anchor": "10-5-testflight-protocol-sandbox", "as_built_anchor": "protocol-sandbox", "old_anchor": "10-5-testflight-duplicated-protocol-sandbox-future", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "An isolated TestFlight admin sandbox for validating duplicated protocol behavior before any connection to live workflows.", "target": { "summary": "Validate duplicated protocol behavior in an isolated TestFlight admin sandbox before any live connection.", "gaps": [ "Build the isolated sandbox and its approval evidence." ] }, "open_decisions": [], "rules": [ { "id": "RRX-PLATFORM-010", "text": "The sandbox uses a duplicate of protocol behavior and never mutates the live engine.", "enforcement": "Convention-only: the TestFlight protocol sandbox is not built in ronanrx-core; nothing enforces this today.", "source": "" }, { "id": "RRX-PLATFORM-011", "text": "Connection to live workflows requires passing evidence and explicit approval.", "enforcement": "Convention-only: the sandbox-to-live promotion gate is not built; nothing enforces this today.", "source": "" } ], "legacy_technical_anchors": [ "10-5-testflight-duplicated-protocol-sandbox-future", "10-5-testflight-duplicated-protocol-sandbox" ], "node_contract": { "kind": "workflow", "layer": "orchestration", "trigger": "A protocol candidate is copied into isolated TestFlight validation.", "inputs": [ "validate candidate protocol from Protocols" ], "outputs": [ "No operational output in the approved graph." ], "owner": "Operations Platform", "operator": "Named domain owner with authorized human review", "completion": "Validate duplicated protocol behavior in an isolated TestFlight admin sandbox before any live connection.", "failure_retry": "No approved runtime exists. A future implementation must expose failures to the named owner and retry only under stable idempotency keys.", "system_of_record": "Owning Rails domain records described by the technical contract.", "actors": [ { "actor": "operations", "participation": "operates" } ], "domains": [ "fulfillment", "governance" ], "journey_stage": "governance", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-12", "focus_nodes": [ "protocol-version", "sandbox-validate", "explicit-promotion", "approval" ] } ] }, { "key": "11.1", "number": "11.1", "section": 11, "section_title": "Provider Onboarding", "id": "provider-onboarding", "title": "Provider Onboarding", "track": "doctor", "business_anchor": "provider-onboarding", "technical_anchor": "11-1-provider-onboarding", "as_built_anchor": "provider-onboarding", "old_anchor": "11-1-provider-onboarding-doctor-intake-partial", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "How a doctor (or NP/PA) gets onto the platform: invited or self-enrolled, agreement-signed, credentialed, licensed, approved, and linked to a clinic. **Provider onboarding** is the canonical term; it is not the patient's pre-doctor intake (§2.3).", "target": { "summary": "Keep provider onboarding invite-gated, agreement-complete, and inactive until human credential activation, using the approved $10 RonanRx fee and $29 doctor payout copy.", "gaps": [ "Wire Stripe Connect payout behavior without changing the approved agreement economics." ] }, "open_decisions": [], "rules": [ { "id": "RRX-PROVIDER-001", "text": "Provider onboarding is invite-gated for launch and uses the complete approved agreement packet.", "enforcement": "Enforced by: app/services/workflows/create_provider_from_invite.rb (guards a valid invite and a sealed agreement packet) and test/services/workflows/create_provider_from_invite_test.rb", "source": "" }, { "id": "RRX-PROVIDER-002", "text": "New provider credentials and licenses remain inactive until a human approves them.", "enforcement": "Partially enforced: provisioning runs only from an admin-minted, security-re-authenticated ProviderInvite (app/controllers/admin/provider_invites_controller.rb), but the resulting credentials and licenses are set status:active on provisioning (app/services/ehr/integration/providers.rb), not held inactive pending a separate human approval.", "source": "" }, { "id": "RRX-PROVIDER-003", "text": "Provider agreements use the approved $10 RonanRx fee and $29 doctor payout model.", "enforcement": "Enforced by: test/services/provider_agreement_packet/render_and_seal_test.rb (asserts $29 default provider fee, $10 flat platform fee, $39 total)", "source": "" }, { "id": "RRX-PROVIDER-004", "text": "Collect and verify the provider identity, NPI, licenses, malpractice coverage, contact details, payout identity, prescribing preferences, and program participation.", "enforcement": "Partially enforced: the required floor (name, contact email, professional designation, NPI, at least one state license) is guarded in app/services/workflows/create_provider_from_invite.rb; malpractice, payout, prescribing-preference, and program fields are captured into the encrypted prefill blob (app/services/provider_invites/create.rb) but not verified (capture-only in v1).", "source": "" }, { "id": "RRX-PROVIDER-005", "text": "Providers attest that they saw the patient's ID during the appointment under the nonblocking EHR policy.", "enforcement": "Enforced by: test/services/ehr/workflows/note_signing_test.rb (identity attestation is recorded on the encounter and the note still signs when identity is unverified; nonblocking)", "source": "" } ], "legacy_technical_anchors": [ "11-1-provider-onboarding-doctor-intake-partial", "11-1-provider-onboarding-doctor-intake" ], "node_contract": { "kind": "workflow", "layer": "orchestration", "trigger": "An invite is accepted or a permitted self-entry application begins.", "inputs": [ "No operational input; activated only by its stated trigger." ], "outputs": [ "publish eligible provider to Dr. Picker" ], "owner": "Clinical Product", "operator": "Named domain owner with authorized human review", "completion": "Keep provider onboarding invite-gated, agreement-complete, and inactive until human credential activation, using the approved $10 RonanRx fee and $29 doctor payout copy.", "failure_retry": "Failures remain attributable and visible to the named owner; retry only the owning idempotent command and never invent success.", "system_of_record": "Provider, credential, license, agreement, clinic, activation, and Connect records.", "actors": [ { "actor": "doctor", "participation": "acts" }, { "actor": "operations", "participation": "operates" } ], "domains": [ "governance" ], "journey_stage": "governance", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-21", "focus_nodes": [ "invite-or-entry", "agreement", "credentials", "inactive-review", "activation", "clinic-connect" ] } ] }, { "key": "12.1", "number": "12.1", "section": 12, "section_title": "Ops Console & Oversight", "id": "ops-console", "title": "Ops Console", "track": "ops", "business_anchor": "ops-console", "technical_anchor": "12-1-ops-console", "as_built_anchor": "ops-console", "old_anchor": "12-1-ops-console-oversight-exists", "flags": [ "board-node", "unverified-carried-forward" ], "what_it_is": "The admin-gated staff control room for audited interventions across conversations, appointments, payments, prescriptions, and charts.", "target": { "summary": "Give the Ops Console a chat surface that can handle payment actions and multiple prescriptions for one patient.", "gaps": [] }, "open_decisions": [], "rules": [ { "id": "RRX-OPS-001", "text": "Every Ops surface is admin-gated and every clinical or patient-facing intervention is attributable.", "enforcement": "Enforced by: test/controllers/ops/console_access_test.rb (admin-only access) and test/controllers/ops/audit_spine_test.rb (fail-closed per-view audit with actor attribution)", "source": "" }, { "id": "RRX-OPS-002", "text": "Human takeover suppresses conversational agent replies while preserving approved transactional communication.", "enforcement": "Enforced by: test/jobs/linq_reply_job_takeover_test.rb (an active human takeover drops conversational agent replies while emergency, appointment, and transactional traffic remain deliverable)", "source": "" }, { "id": "RRX-OPS-003", "text": "Manual messages preserve consent, safety holds, secure-link policy, delivery result, and audit history.", "enforcement": "Enforced by: app/services/linq/admin_messages/send.rb (opt-out, safety-hold, and secure-pointer/PHI guards, with dedupe and audit) and test/services/linq/admin_messages/send_test.rb", "source": "" }, { "id": "RRX-OPS-004", "text": "The Ops chat surface supports payment actions and multiple prescriptions for one patient.", "enforcement": "Enforced by: test/controllers/api/ops/v1/rx_payment_mutations_test.rb (payment-link/reconcile actions) and test/controllers/api/ops/v1/payment_diagnostics_test.rb (per-patient prescription inspection over the prescriptions array)", "source": "" } ], "legacy_technical_anchors": [ "12-1-ops-console-oversight-exists", "12-1-ops-console-oversight" ], "node_contract": { "kind": "surface", "layer": "experience", "trigger": "An authorized operator opens a queue or requests an attributable intervention.", "inputs": [ "raise lab exception from Lab Follow-up", "raise shipment exception from 3PL Fulfillment Handoff", "escalate support exception from Patient Support", "open urgent incident from Medical Support Chat" ], "outputs": [ "resolve and release incident to Medical Support Chat" ], "owner": "Operations Platform", "operator": "Authorized patient, provider, or operations user", "completion": "Give the Ops Console a chat surface that can handle payment actions and multiple prescriptions for one patient.", "failure_retry": "Failures remain attributable and visible to the named owner; retry only the owning idempotent command and never invent success.", "system_of_record": "Underlying domain records plus immutable Ops audit events.", "actors": [ { "actor": "operations", "participation": "operates" } ], "domains": [ "fulfillment", "follow-up", "governance" ], "journey_stage": "governance", "map_presence": "default" }, "subdiagram_refs": [ { "subgraph_id": "sg-22", "focus_nodes": [ "authorized-read", "human-action", "machine-preflight", "confirmation", "idempotent-execute", "audit-event", "exception-views" ] } ] } ], "edge_bundles": [ { "id": "eb-onboarding-turn", "label": "Guarded conversational turn", "kind": "paired", "auth": "Linq webhook signature on ingress; Rails-owned SendGuard authorization on egress.", "stable_ids": "Linq message ID, conversation ID, and agent turn ID remain stable across processing.", "idempotency": "Inbound message IDs are unique and replay-safe; outbound deliveries use stable dedupe keys.", "acknowledgment": "Rails records the inbound event and Linq delivery result; model output alone is never delivery acknowledgment.", "retry": "Replay only the idempotent event or delivery command; never issue a second conversational reply for one turn.", "reconciliation": "Conversation events, agent onboarding record updates, and Linq delivery receipts are compared by stable IDs.", "exception_owner": "Messaging Operations" }, { "id": "eb-membership-payment", "label": "Membership SetupIntent and subscription", "kind": "paired", "auth": "Stripe-hosted payment authentication plus signed Stripe webhooks.", "stable_ids": "Patient, intake, Stripe customer, SetupIntent, subscription, and event IDs.", "idempotency": "One membership intent per eligible onboarding stage; webhook event IDs are unique.", "acknowledgment": "Only authoritative Stripe state and a reconciled webhook complete the gate.", "retry": "Resume the same incomplete membership stage or create an attributable replacement after terminal failure.", "reconciliation": "Rails billing records reconcile against Stripe customer, subscription, invoice, and event state.", "exception_owner": "Billing Operations" }, { "id": "eb-rx-payment", "label": "Prescription Checkout and webhook", "kind": "paired", "auth": "Expiring patient pay link, Stripe-hosted Checkout, and signed webhooks.", "stable_ids": "Prescription fingerprint, offer ID, Checkout Session, payment/subscription, and event IDs.", "idempotency": "One active offer/session lineage per prescription offer; webhook event IDs finalize once.", "acknowledgment": "Browser redirect is advisory; reconciled Stripe webhook state is authoritative.", "retry": "Resume or replace a terminal session without creating a second medication charge.", "reconciliation": "Prescription billing state is compared with Stripe objects and the local money ledger.", "exception_owner": "Billing Operations" }, { "id": "eb-quest-labs", "label": "Quest order and results exchange", "kind": "governed-external", "auth": "Approved Quest integration credentials and authenticated inbound results transport.", "stable_ids": "Internal lab order, Quest requisition, specimen, result, and source event IDs.", "idempotency": "Order submissions and result events dedupe on stable external identifiers.", "acknowledgment": "Quest order acceptance is distinct from specimen collection and result finalization.", "retry": "Retry transport failures under the same order ID; human review owns rejected or conflicting state.", "reconciliation": "Open lab orders reconcile against Quest requisitions, specimen status, and final results.", "exception_owner": "Lab Operations" }, { "id": "eb-function-import", "label": "Function Health import lease", "kind": "governed-external", "auth": "Patient consent and a one-time authorization token scoped to the import.", "stable_ids": "Patient, consent, import lease, source file/pull, biomarker, and result IDs.", "idempotency": "One active lease owns an import; source hashes and biomarker keys prevent duplicate results.", "acknowledgment": "Atomic finalization records the imported source and normalized result set.", "retry": "Failed or abandoned leases are reaped before an attributable replacement attempt.", "reconciliation": "Source rows, mapping queue entries, and normalized EHR results reconcile by import ID.", "exception_owner": "Lab Operations" }, { "id": "eb-3pl-shipment", "label": "Released-order 3PL transaction", "kind": "governed-external", "auth": "Authenticated 3PL or 3PL-owned ShipStation contract; the selected mechanism must be recorded before activation.", "stable_ids": "RonanRx fulfillment ID, pharmacy release ID, 3PL order ID, ShipStation shipment ID, carrier tracking ID, and source event ID.", "idempotency": "All retries reuse the stable RonanRx fulfillment ID and every inbound event dedupes by authoritative source ID.", "acknowledgment": "A positive 3PL acceptance or attributable rejection is required; submission and label creation do not prove shipment.", "retry": "Retry only failed transport under the same fulfillment ID; rejected, voided, or replaced orders require attributable resolution.", "reconciliation": "Pharmacy release, 3PL acceptance, packing/label state, carrier tender, tracking, and exceptions reconcile continuously.", "exception_owner": "Fulfillment Operations" }, { "id": "eb-device-sync", "label": "Authorized device and iOS synchronization", "kind": "governed-external", "auth": "Affirmative patient authorization through OAuth or HealthKit with supported scopes.", "stable_ids": "Patient, authorization, device/source, observation, local outbox item, webhook, and sync cursor IDs.", "idempotency": "Source observation keys and outbox IDs dedupe repeated webhook and sync delivery.", "acknowledgment": "Server acceptance advances the local outbox; authorization revoke stops future collection.", "retry": "Retry queued transport failures with bounded backoff while the authorization remains active.", "reconciliation": "Local outbox, vendor cursor, authorization, and EHR observation state reconcile by source key.", "exception_owner": "Patient Platform Operations" } ], "edges": [ { "id": "edge-linq-to-safety-screen", "source": "iphone-link", "target": "urgent-text-escalation", "relation": "gates", "label": "screen inbound turn", "bundle_id": null, "trigger": "A verified inbound Linq message arrives.", "payload": "Message text, attachments, sender, conversation id, and event id.", "pass_condition": "No deterministic urgent-risk hold is active, or a governed human releases the hold.", "criticality": "hard", "execution": "deterministic", "synchrony": "synchronous", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-ONBOARDING-001", "RRX-CARE-013" ], "technical_contract_ref": "spec/technical.md#7-5-medical-support-chat", "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#urgent-text-escalation" ], "failure_owner": "Messaging Operations", "timeout_retry": "Fail closed into the governed urgent queue; never bypass the safety hold.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 288,536 H 1376 Q 1384,536 1384,528 V 378 Q 1384,370 1392,370 H 1400", "label_x": 1120, "label_y": 528 } }, { "id": "edge-safety-screen-to-router", "source": "urgent-text-escalation", "target": "agent-router", "relation": "routes", "label": "release safe turn", "bundle_id": null, "trigger": "The deterministic safety screen completes.", "payload": "Verified event, safety disposition, conversation state, and allowed route set.", "pass_condition": "The event is not held for urgent human handling.", "criticality": "hard", "execution": "deterministic", "synchrony": "synchronous", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-CARE-014", "RRX-AGENTS-013" ], "technical_contract_ref": "spec/technical.md#9-1-agent-router", "evidence_refs": [ "spec/as-built.md#urgent-text-escalation", "spec/as-built.md#agent-router" ], "failure_owner": "Messaging Operations", "timeout_retry": "Keep the event durable and route to Operations after bounded retry.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 1400,378 H 864 Q 856,378 856,386 V 684 Q 856,692 848,692 H 824", "label_x": 1180, "label_y": 370 } }, { "id": "edge-router-to-onboarding", "source": "agent-router", "target": "onboarding-agent", "relation": "routes", "label": "start focused onboarding turn", "bundle_id": "eb-onboarding-turn", "trigger": "Routing classifies the safe message as an onboarding turn.", "payload": "Conversation context, current onboarding JSONB, message, attachments, and safety disposition.", "pass_condition": "Onboarding is the single focused owner and no takeover is active.", "criticality": "hard", "execution": "deterministic", "synchrony": "asynchronous", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "current-verified", "business_rule_refs": [ "RRX-AGENTS-013", "RRX-ONBOARDING-004" ], "technical_contract_ref": "spec/technical.md#1-2-onboarding-agent", "evidence_refs": [ "spec/as-built.md#agent-router", "spec/as-built.md#onboarding-agent" ], "failure_owner": "Messaging Operations", "timeout_retry": "Bounded queue retry; hard failure alerts Operations and suppresses an invented reply.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 712,718 H 312", "label_x": 512, "label_y": 710 } }, { "id": "edge-onboarding-to-linq", "source": "onboarding-agent", "target": "iphone-link", "relation": "transfers", "label": "deliver guarded response", "bundle_id": "eb-onboarding-turn", "trigger": "The focused turn returns a response and the durable record update succeeds.", "payload": "Authorized response text, media references, conversation id, and source event id.", "pass_condition": "Rails outbound authorization succeeds and no safety or takeover suppression is active.", "criticality": "important", "execution": "agent", "synchrony": "asynchronous", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-ONBOARDING-005", "RRX-ONBOARDING-006" ], "technical_contract_ref": "spec/technical.md#1-1-imessage-linq", "evidence_refs": [ "spec/as-built.md#onboarding-agent", "spec/as-built.md#iphone-link" ], "failure_owner": "Messaging Operations", "timeout_retry": "Do not send on hard failure; log, alert, and retain the event for governed recovery.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 232,692 L 232,560", "label_x": 244, "label_y": 625 } }, { "id": "edge-onboarding-to-intake-one", "source": "onboarding-agent", "target": "signup-intake", "relation": "transfers", "label": "merge current clinical-floor JSONB", "bundle_id": null, "trigger": "The onboarding turn extracts or confirms a patient fact.", "payload": "Versioned field delta, provenance, declines, attachment candidates, and interaction audit.", "pass_condition": "Current production requires goal, medications, allergies, conditions, and an addressed biometric beat.", "criticality": "hard", "execution": "agent", "synchrony": "asynchronous", "delivery_state": "live", "lifecycle": "current", "evidence_state": "current-verified", "business_rule_refs": [ "RRX-ONBOARDING-007", "RRX-ONBOARDING-008" ], "technical_contract_ref": "spec/technical.md#1-3-intake-1-basics", "evidence_refs": [ "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ], "failure_owner": "Onboarding Engineering", "timeout_retry": "Retry optimistic merge against the latest version; never overwrite a newer answer.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 244,696 V 480 Q 244,472 236,472", "label_x": 252, "label_y": 584 } }, { "id": "edge-intake-one-to-id", "source": "signup-intake", "target": "id-verification", "relation": "gates", "label": "open secure completion", "bundle_id": null, "trigger": "Chat handoff eligibility is reached and a secure continuation link is opened.", "payload": "Patient and conversation ids, captured basics, source provenance, and missing-later inventory.", "pass_condition": "Current flow has a valid handoff; target requires service state and a goal or desired medication.", "criticality": "hard", "execution": "deterministic", "synchrony": "synchronous", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-ONBOARDING-008", "RRX-ONBOARDING-020" ], "technical_contract_ref": "spec/technical.md#1-7-id-verification", "evidence_refs": [ "spec/as-built.md#signup-intake", "spec/as-built.md#id-verification" ], "failure_owner": "Onboarding Operations", "timeout_retry": "The secure flow is resumable; invalid or expired access returns to governed recovery.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 296,450 L 308,450", "label_x": 302, "label_y": 442 } }, { "id": "edge-id-to-agreements", "source": "id-verification", "target": "sign-docs", "relation": "gates", "label": "identity verified", "bundle_id": null, "trigger": "Secure ID capture and verification finish.", "payload": "Verification status, identity match, serviceability result, and audit references.", "pass_condition": "Identity and current-address checks satisfy the completion policy.", "criticality": "hard", "execution": "deterministic", "synchrony": "synchronous", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "current-verified", "business_rule_refs": [ "RRX-ONBOARDING-021", "RRX-ONBOARDING-011" ], "technical_contract_ref": "spec/technical.md#1-4-sign-docs-agreement-packet", "evidence_refs": [ "spec/as-built.md#id-verification", "spec/as-built.md#sign-docs" ], "failure_owner": "Patient Operations", "timeout_retry": "Keep agreements inaccessible until verification succeeds; allow resumable correction.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 430,450 L 442,450", "label_x": 436, "label_y": 442 } }, { "id": "edge-agreements-to-membership", "source": "sign-docs", "target": "membership-subscription", "relation": "gates", "label": "all documents signed", "bundle_id": null, "trigger": "The agreement packet reaches a terminal signed state.", "payload": "Packet id, document versions, signatures, timestamps, and sealed PDF references.", "pass_condition": "Every required agreement is signed against the presented version.", "criticality": "hard", "execution": "deterministic", "synchrony": "synchronous", "delivery_state": "live", "lifecycle": "both", "evidence_state": "current-verified", "business_rule_refs": [ "RRX-ONBOARDING-012", "RRX-ONBOARDING-014" ], "technical_contract_ref": "spec/technical.md#1-5-membership-pay", "evidence_refs": [ "spec/as-built.md#sign-docs", "spec/as-built.md#membership-subscription" ], "failure_owner": "Patient Operations", "timeout_retry": "Remain on the agreement step and regenerate only under an audited version change.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 564,450 L 576,450", "label_x": 570, "label_y": 442 } }, { "id": "edge-intake-stall-to-conversion", "source": "signup-intake", "target": "reengage-close-agent", "relation": "triggers", "label": "recover stalled intake", "bundle_id": null, "trigger": "A governed stall timer expires before secure completion.", "payload": "Patient id, incomplete stage, permitted channel, and stop conditions.", "pass_condition": "Consent remains valid and no safety, opt-out, or human-takeover block exists.", "criticality": "important", "execution": "deterministic", "synchrony": "event-driven", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-ONBOARDING-017" ], "technical_contract_ref": "spec/technical.md#1-6-conversion-agent", "evidence_refs": [ "spec/as-built.md#reengage-close-agent" ], "failure_owner": "Patient Operations", "timeout_retry": "One bounded recovery cadence; stop on opt-out, response, conversion, or human takeover.", "recurring": false, "visible_by_default": false }, { "id": "edge-conversion-to-intake-one", "source": "reengage-close-agent", "target": "signup-intake", "relation": "routes", "label": "resume incomplete stage", "bundle_id": null, "trigger": "The patient accepts a governed recovery prompt.", "payload": "Signed resume link, patient id, last complete step, and channel attribution.", "pass_condition": "The link is valid and the patient is still eligible to continue.", "criticality": "important", "execution": "agent", "synchrony": "asynchronous", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-ONBOARDING-018", "RRX-ONBOARDING-019" ], "technical_contract_ref": "spec/technical.md#1-6-conversion-agent", "evidence_refs": [ "spec/as-built.md#reengage-close-agent" ], "failure_owner": "Patient Operations", "timeout_retry": "Resume remains idempotent; repeated use opens the same incomplete stage.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 400,692 V 608 Q 400,600 392,600 H 268 Q 260,600 260,592 V 476", "label_x": 320, "label_y": 600 } }, { "id": "edge-membership-to-doctor-picker", "source": "membership-subscription", "target": "doctor-picker", "relation": "gates", "label": "membership active", "bundle_id": null, "trigger": "Verified membership activation is durable.", "payload": "Patient id, membership state, service state, and care-path choice.", "pass_condition": "Membership is active and the patient is eligible for the selected care path.", "criticality": "hard", "execution": "deterministic", "synchrony": "synchronous", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-ONBOARDING-015", "RRX-SCHEDULING-001" ], "technical_contract_ref": "spec/technical.md#2-1-dr-picker", "evidence_refs": [ "spec/as-built.md#membership-subscription", "spec/as-built.md#doctor-picker" ], "failure_owner": "Patient Operations", "timeout_retry": "Keep scheduling closed and return a resumable billing exception.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 698,450 L 710,450", "label_x": 704, "label_y": 442 } }, { "id": "edge-doctor-picker-to-booking", "source": "doctor-picker", "target": "appointment-setting", "relation": "transfers", "label": "request eligible slot", "bundle_id": null, "trigger": "The patient selects an eligible provider and displayed slot.", "payload": "Patient id, provider id, clinic id, availability version, and requested time.", "pass_condition": "Provider eligibility and slot availability are rechecked at write time.", "criticality": "hard", "execution": "deterministic", "synchrony": "synchronous", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-SCHEDULING-002", "RRX-SCHEDULING-004" ], "technical_contract_ref": "spec/technical.md#2-2-booking", "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting" ], "failure_owner": "Scheduling Operations", "timeout_retry": "Release a failed lock and offer fresh availability without duplicating an appointment.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 832,450 L 844,450", "label_x": 838, "label_y": 442 } }, { "id": "edge-booking-to-previsit-intake", "source": "appointment-setting", "target": "pre-doctor-intake", "relation": "triggers", "label": "activate pre-visit intake", "bundle_id": null, "trigger": "A booking reaches confirmed state.", "payload": "Appointment id, patient id, provider id, clinic id, and appointment time.", "pass_condition": "The booking is still active and the intake plan is applicable.", "criticality": "hard", "execution": "deterministic", "synchrony": "event-driven", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-SCHEDULING-006", "RRX-SCHEDULING-009" ], "technical_contract_ref": "spec/technical.md#2-3-intake-2-pre-appointment", "evidence_refs": [ "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-doctor-intake" ], "failure_owner": "Scheduling Operations", "timeout_retry": "Retry idempotently by appointment id; cancel outstanding work if booking cancels.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 966,450 L 978,450", "label_x": 972, "label_y": 442 } }, { "id": "edge-booking-to-reminders", "source": "appointment-setting", "target": "meeting-reminders", "relation": "triggers", "label": "schedule reminders", "bundle_id": null, "trigger": "A booking is confirmed or materially rescheduled.", "payload": "Appointment id, recipient preferences, appointment time, provider, and join metadata.", "pass_condition": "The appointment remains active at send-time recheck.", "criticality": "important", "execution": "deterministic", "synchrony": "event-driven", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-SCHEDULING-013", "RRX-SCHEDULING-014" ], "technical_contract_ref": "spec/technical.md#2-4-appointment-reminders", "evidence_refs": [ "spec/as-built.md#appointment-setting", "spec/as-built.md#meeting-reminders" ], "failure_owner": "Scheduling Operations", "timeout_retry": "Recompute the reminder schedule after changes; dedupe each appointment-relative send.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 905,476 V 592 Q 905,600 897,600 H 588 Q 580,600 580,608 V 692", "label_x": 744, "label_y": 600 } }, { "id": "edge-booking-to-appointment", "source": "appointment-setting", "target": "doctor-visit", "relation": "triggers", "label": "create visit encounter", "bundle_id": null, "trigger": "The confirmed appointment enters its encounter window.", "payload": "Appointment, patient, provider, clinic, location-state, and room authorization ids.", "pass_condition": "The booking is active and the provider is authorized for the encounter.", "criticality": "hard", "execution": "deterministic", "synchrony": "event-driven", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-SCHEDULING-007", "RRX-SCHEDULING-020" ], "technical_contract_ref": "spec/technical.md#2-6-appointment", "evidence_refs": [ "spec/as-built.md#appointment-setting", "spec/as-built.md#doctor-visit" ], "failure_owner": "Clinical Operations", "timeout_retry": "Do not create duplicate encounters; route room or authorization failure to Operations.", "recurring": false, "visible_by_default": false }, { "id": "edge-booking-to-prebrief", "source": "appointment-setting", "target": "pre-brief", "relation": "triggers", "label": "assemble visit brief", "bundle_id": null, "trigger": "A booking is confirmed or relevant pre-visit data changes.", "payload": "Appointment id, patient id, provider id, and source-version cursors.", "pass_condition": "The appointment is active and every included fact retains provenance.", "criticality": "important", "execution": "deterministic", "synchrony": "event-driven", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-SCHEDULING-016" ], "technical_contract_ref": "spec/technical.md#2-5-pre-brief", "evidence_refs": [ "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ], "failure_owner": "Clinical Operations", "timeout_retry": "Rebuild idempotently from durable sources; label unavailable inputs as missing.", "recurring": false, "visible_by_default": false }, { "id": "edge-previsit-intake-to-prebrief", "source": "pre-doctor-intake", "target": "pre-brief", "relation": "transfers", "label": "attach ready intake packet", "bundle_id": null, "trigger": "Pre-appointment intake saves or reaches ready state.", "payload": "Attributed answers, source provenance, missing items, corrections, and completion state.", "pass_condition": "Only durable, attributable answers are included; missing data remains explicit.", "criticality": "hard", "execution": "deterministic", "synchrony": "event-driven", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-SCHEDULING-011", "RRX-SCHEDULING-017" ], "technical_contract_ref": "spec/technical.md#2-5-pre-brief", "evidence_refs": [ "spec/as-built.md#pre-doctor-intake", "spec/as-built.md#pre-brief" ], "failure_owner": "Clinical Operations", "timeout_retry": "Rebuild on the next durable save; never substitute an inferred answer.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 1039,424 V 264 Q 1039,256 1031,256 H 340 Q 332,256 332,248 V 204 Q 332,196 340,196 H 380 Q 388,196 388,188", "label_x": 680, "label_y": 250 } }, { "id": "edge-prebrief-to-appointment", "source": "pre-brief", "target": "doctor-visit", "relation": "informs", "label": "present clinical brief", "bundle_id": null, "trigger": "The provider opens the active encounter.", "payload": "Versioned brief, missing-data labels, source links, relevant labs, and records.", "pass_condition": "Every fact is attributable and the provider can inspect its source.", "criticality": "important", "execution": "deterministic", "synchrony": "synchronous", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-SCHEDULING-018", "RRX-SCHEDULING-020" ], "technical_contract_ref": "spec/technical.md#2-6-appointment", "evidence_refs": [ "spec/as-built.md#pre-brief", "spec/as-built.md#doctor-visit" ], "failure_owner": "Clinical Operations", "timeout_retry": "Show an explicit unavailable state; the encounter may proceed under provider judgment.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 312,162 L 340,162", "label_x": 326, "label_y": 154 } }, { "id": "edge-reminders-to-appointment", "source": "meeting-reminders", "target": "doctor-visit", "relation": "notifies", "label": "send arrival prompts", "bundle_id": null, "trigger": "An appointment-relative reminder becomes due.", "payload": "Appointment time, approved join link, recipient, locale, and message template version.", "pass_condition": "The booking is still active; reminder delivery never creates or confirms the booking.", "criticality": "advisory", "execution": "deterministic", "synchrony": "event-driven", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-SCHEDULING-014", "RRX-SCHEDULING-015" ], "technical_contract_ref": "spec/technical.md#2-4-appointment-reminders", "evidence_refs": [ "spec/as-built.md#meeting-reminders", "spec/as-built.md#doctor-visit" ], "failure_owner": "Scheduling Operations", "timeout_retry": "Dedupe by appointment and reminder offset; record delivery failure for follow-up.", "recurring": false, "visible_by_default": false }, { "id": "edge-provider-onboarding-to-picker", "source": "provider-onboarding", "target": "doctor-picker", "relation": "gates", "label": "publish eligible provider", "bundle_id": null, "trigger": "A provider is activated for a clinic, jurisdiction, and care scope.", "payload": "Provider id, clinic memberships, license coverage, capability, and activation state.", "pass_condition": "Credentials, agreements, clinic membership, and required billing setup are active.", "criticality": "hard", "execution": "human", "synchrony": "event-driven", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-PROVIDER-003", "RRX-SCHEDULING-001" ], "technical_contract_ref": "spec/technical.md#2-1-dr-picker", "evidence_refs": [ "spec/as-built.md#provider-onboarding", "spec/as-built.md#doctor-picker" ], "failure_owner": "Provider Operations", "timeout_retry": "Keep the provider inactive until review succeeds; re-evaluate after corrected evidence.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 244,308 V 400 Q 244,408 252,408 H 763 Q 771,408 771,416 V 424", "label_x": 384, "label_y": 411 } }, { "id": "edge-history-to-prebrief", "source": "health-history-questionnaire", "target": "pre-brief", "relation": "informs", "label": "add medical history", "bundle_id": null, "trigger": "A governed history answer or completion state changes.", "payload": "Attributed answers, prefill provenance, conflicts, and completion state.", "pass_condition": "Only durable answers with provenance are presented.", "criticality": "important", "execution": "deterministic", "synchrony": "event-driven", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-DATA-006", "RRX-SCHEDULING-017" ], "technical_contract_ref": "spec/technical.md#2-5-pre-brief", "evidence_refs": [ "spec/as-built.md#health-history-questionnaire", "spec/as-built.md#pre-brief" ], "failure_owner": "Clinical Operations", "timeout_retry": "Preserve the last durable version and label unresolved conflicts.", "recurring": false, "visible_by_default": false }, { "id": "edge-records-to-prebrief", "source": "records-ingestion", "target": "pre-brief", "relation": "informs", "label": "add cited prior records", "bundle_id": null, "trigger": "A reviewed record extraction is promoted or reconciled.", "payload": "Source document ids, cited facts, conflicts, review state, and provenance.", "pass_condition": "Every promoted fact cites an immutable source location.", "criticality": "important", "execution": "deterministic", "synchrony": "event-driven", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-EHR-016", "RRX-SCHEDULING-017" ], "technical_contract_ref": "spec/technical.md#2-5-pre-brief", "evidence_refs": [ "spec/as-built.md#records-ingestion", "spec/as-built.md#pre-brief" ], "failure_owner": "Clinical Operations", "timeout_retry": "Keep failed extraction quarantined; allow manual review and reprocessing.", "recurring": false, "visible_by_default": false }, { "id": "edge-device-data-to-prebrief", "source": "app-data-collection", "target": "pre-brief", "relation": "informs", "label": "add approved device signals", "bundle_id": null, "trigger": "A consented, normalized observation becomes clinically relevant.", "payload": "Observation ids, units, source, timestamps, consent scope, and quality flags.", "pass_condition": "Consent is active and the observation type is allowlisted.", "criticality": "advisory", "execution": "deterministic", "synchrony": "event-driven", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-DATA-002", "RRX-SCHEDULING-017" ], "technical_contract_ref": "spec/technical.md#2-5-pre-brief", "evidence_refs": [ "spec/as-built.md#app-data-collection", "spec/as-built.md#pre-brief" ], "failure_owner": "Platform Operations", "timeout_retry": "Skip stale or invalid observations and surface connector health separately.", "recurring": false, "visible_by_default": false }, { "id": "edge-research-to-prebrief", "source": "medical-research-agent", "target": "pre-brief", "relation": "informs", "label": "attach cited research", "bundle_id": null, "trigger": "A clinician-approved research request completes review.", "payload": "Question, governed sources, citations, synthesis, conflicts, and reviewer disposition.", "pass_condition": "Every clinical claim is cited and a human reviewer approves inclusion.", "criticality": "advisory", "execution": "agent", "synchrony": "asynchronous", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-AGENTS-024", "RRX-SCHEDULING-019" ], "technical_contract_ref": "spec/technical.md#9-5-medical-research-agent", "evidence_refs": [ "spec/as-built.md#medical-research-agent" ], "failure_owner": "Clinical Operations", "timeout_retry": "No uncited output reaches the brief; retry only against the governed corpus.", "recurring": false, "visible_by_default": false }, { "id": "edge-appointment-to-observation", "source": "doctor-visit", "target": "visit-observation", "relation": "triggers", "label": "capture encounter frames", "bundle_id": null, "trigger": "A consented video encounter enters eligible speaking intervals.", "payload": "Encounter id, consent state, authorized media stream, and timing markers.", "pass_condition": "Capture consent is active and the encounter is authorized.", "criticality": "important", "execution": "deterministic", "synchrony": "event-driven", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-SCHEDULING-024", "RRX-SCHEDULING-025" ], "technical_contract_ref": "spec/technical.md#2-7-visit-observation", "evidence_refs": [ "spec/as-built.md#visit-observation" ], "failure_owner": "Clinical Operations", "timeout_retry": "Capture quality failures do not block the visit; record why evidence is unavailable.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 412,184 V 204", "label_x": 420, "label_y": 196 } }, { "id": "edge-appointment-to-note", "source": "doctor-visit", "target": "charting-ehr", "relation": "triggers", "label": "open encounter note", "bundle_id": null, "trigger": "An authorized appointment begins or completes.", "payload": "Encounter id, patient, provider, location-state, consent, and artifact references.", "pass_condition": "The provider is authorized and the encounter identity is unique.", "criticality": "hard", "execution": "deterministic", "synchrony": "event-driven", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-SCHEDULING-022", "RRX-EHR-001" ], "technical_contract_ref": "spec/technical.md#3-1-clinical-note", "evidence_refs": [ "spec/as-built.md#doctor-visit", "spec/as-built.md#charting-ehr" ], "failure_owner": "Clinical Operations", "timeout_retry": "Resume the unique encounter draft; never create a second chart entry for the same event.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 480,162 L 508,162", "label_x": 494, "label_y": 154 } }, { "id": "edge-observation-to-note", "source": "visit-observation", "target": "charting-ehr", "relation": "transfers", "label": "attach confirmed observations", "bundle_id": null, "trigger": "The doctor confirms retained frames and drafted appearance observations.", "payload": "Doctor-confirmed images, citations, observation text, timestamps, and deletion state.", "pass_condition": "Every retained observation is doctor-confirmed and tied to an encounter artifact.", "criticality": "hard", "execution": "human", "synchrony": "asynchronous", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-SCHEDULING-030", "RRX-SCHEDULING-031" ], "technical_contract_ref": "spec/technical.md#3-1-clinical-note", "evidence_refs": [ "spec/as-built.md#visit-observation" ], "failure_owner": "Clinical Operations", "timeout_retry": "Unconfirmed frames remain excluded; deletion invalidates derived observations and citations.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 480,230 H 488 Q 496,230 496,222 V 204 Q 496,196 504,196 H 548 Q 556,196 556,188", "label_x": 518, "label_y": 198 } }, { "id": "edge-records-to-note", "source": "records-ingestion", "target": "charting-ehr", "relation": "informs", "label": "cite prior record facts", "bundle_id": null, "trigger": "A reviewed extraction is promoted for clinical use.", "payload": "Cited facts, source-document locations, conflicts, and review state.", "pass_condition": "The note preserves provenance and does not silently resolve conflicts.", "criticality": "important", "execution": "deterministic", "synchrony": "event-driven", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-EHR-016", "RRX-EHR-002" ], "technical_contract_ref": "spec/technical.md#3-1-clinical-note", "evidence_refs": [ "spec/as-built.md#records-ingestion", "spec/as-built.md#charting-ehr" ], "failure_owner": "Clinical Operations", "timeout_retry": "Leave conflicting or failed facts outside the signed note until reviewed.", "recurring": false, "visible_by_default": false }, { "id": "edge-history-to-note", "source": "health-history-questionnaire", "target": "charting-ehr", "relation": "informs", "label": "project patient history", "bundle_id": null, "trigger": "The governed history reaches a projectable state.", "payload": "Attributed answers, provenance, patient corrections, and completion state.", "pass_condition": "The clinician can distinguish patient-reported data from clinician findings.", "criticality": "important", "execution": "deterministic", "synchrony": "event-driven", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-DATA-007", "RRX-EHR-002" ], "technical_contract_ref": "spec/technical.md#3-1-clinical-note", "evidence_refs": [ "spec/as-built.md#health-history-questionnaire", "spec/as-built.md#charting-ehr" ], "failure_owner": "Clinical Operations", "timeout_retry": "Retain the last durable projection and expose missing or conflicting answers.", "recurring": false, "visible_by_default": false }, { "id": "edge-ehr-cleanup-governs-note", "source": "ehr-schema-cleanup", "target": "charting-ehr", "relation": "governs", "label": "enforce canonical schema", "bundle_id": null, "trigger": "A note field or clinical artifact is persisted.", "payload": "Canonical field contract, migration state, compatibility mapping, and validation result.", "pass_condition": "The write satisfies the active canonical schema or an explicit compatibility adapter.", "criticality": "hard", "execution": "deterministic", "synchrony": "synchronous", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-EHR-018", "RRX-EHR-019" ], "technical_contract_ref": "spec/technical.md#3-6-ehr-schema-cleanup", "evidence_refs": [ "spec/as-built.md#ehr-schema-cleanup" ], "failure_owner": "EHR Engineering", "timeout_retry": "Reject ambiguous writes and route migration exceptions for repair.", "recurring": false, "visible_by_default": false }, { "id": "edge-note-to-prescription", "source": "charting-ehr", "target": "prescription-generation", "relation": "triggers", "label": "start prescription decision", "bundle_id": null, "trigger": "A provider signs an encounter with a medication plan.", "payload": "Signed encounter id, patient, prescriber, diagnosis, medication plan, state, and citations.", "pass_condition": "The encounter is signed and the prescriber is authorized for the patient state and therapy.", "criticality": "hard", "execution": "human", "synchrony": "event-driven", "delivery_state": "live", "lifecycle": "both", "evidence_state": "current-verified", "business_rule_refs": [ "RRX-EHR-003", "RRX-EHR-005" ], "technical_contract_ref": "spec/technical.md#3-2-prescription-generation", "evidence_refs": [ "spec/as-built.md#charting-ehr", "spec/as-built.md#prescription-generation" ], "failure_owner": "Clinical Operations", "timeout_retry": "Hold issuance for provider correction; preserve the signed source encounter.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 648,162 L 676,162", "label_x": 662, "label_y": 154 } }, { "id": "edge-catalog-to-prescription", "source": "medication-catalog", "target": "prescription-generation", "relation": "governs", "label": "constrain medication choices", "bundle_id": null, "trigger": "Prescription options are rendered or validated.", "payload": "Medication identity, strengths, forms, active status, protocol mappings, and constraints.", "pass_condition": "The selected medication version is active and compatible with the approved protocol.", "criticality": "hard", "execution": "deterministic", "synchrony": "synchronous", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-FULFILLMENT-014", "RRX-EHR-006" ], "technical_contract_ref": "spec/technical.md#5-5-medication-catalog", "evidence_refs": [ "spec/as-built.md#medication-catalog", "spec/as-built.md#prescription-generation" ], "failure_owner": "Clinical Operations", "timeout_retry": "Block an inactive or unmapped selection and require clinician correction.", "recurring": false, "visible_by_default": false }, { "id": "edge-protocols-to-prescription", "source": "protocols", "target": "prescription-generation", "relation": "governs", "label": "apply approved protocol", "bundle_id": null, "trigger": "A prescription candidate is checked before issue.", "payload": "Approved protocol version, eligibility rules, dose limits, monitoring, and pharmacy mapping.", "pass_condition": "The candidate satisfies an active approved protocol or records an authorized exception.", "criticality": "hard", "execution": "deterministic", "synchrony": "synchronous", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-FULFILLMENT-001", "RRX-EHR-007" ], "technical_contract_ref": "spec/technical.md#3-2-prescription-generation", "evidence_refs": [ "spec/as-built.md#protocols", "spec/as-built.md#prescription-generation" ], "failure_owner": "Clinical Operations", "timeout_retry": "Block issuance and send the conflict back to the prescriber.", "recurring": false, "visible_by_default": false }, { "id": "edge-limits-to-prescription", "source": "prescription-limits", "target": "prescription-generation", "relation": "gates", "label": "enforce supply limit", "bundle_id": null, "trigger": "A prescription candidate is issued or reissued.", "payload": "Last supply, intended duration, refill history, check-up state, and exception authority.", "pass_condition": "Supply and continuation remain within the approved three-month boundary or a clinician records an allowed decision.", "criticality": "hard", "execution": "deterministic", "synchrony": "synchronous", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-EHR-013", "RRX-EHR-014" ], "technical_contract_ref": "spec/technical.md#3-4-prescription-limits-3-month-max-before-data-driven-checkup", "evidence_refs": [ "spec/as-built.md#prescription-limits" ], "failure_owner": "Clinical Operations", "timeout_retry": "Block automatic continuation and open a clinician review task.", "recurring": true, "visible_by_default": false }, { "id": "edge-note-to-order-labs", "source": "charting-ehr", "target": "order-labs", "relation": "triggers", "label": "place independent lab order", "bundle_id": null, "trigger": "A clinician signs a lab plan in the encounter.", "payload": "Signed order, diagnoses, test codes, patient, ordering provider, and collection preference.", "pass_condition": "The order is signed, attributable, and valid for the chosen lab path.", "criticality": "hard", "execution": "human", "synchrony": "event-driven", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-EHR-004", "RRX-LABS-001" ], "technical_contract_ref": "spec/technical.md#4-1-order-labs", "evidence_refs": [ "spec/as-built.md#charting-ehr", "spec/as-built.md#order-labs" ], "failure_owner": "Lab Operations", "timeout_retry": "Keep the order in an exception state; never infer a prescription-to-lab dependency.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 648,150 H 824 Q 832,150 832,142 V 118 Q 832,110 840,110 H 848", "label_x": 742, "label_y": 142 } }, { "id": "edge-order-to-quest", "source": "order-labs", "target": "quest-diagnostics", "relation": "transfers", "label": "submit Quest requisition", "bundle_id": "eb-quest-labs", "trigger": "A signed order selects Quest collection.", "payload": "Order, patient demographics, provider, test codes, diagnosis codes, and collection details.", "pass_condition": "Required identifiers and Quest mappings validate before submission.", "criticality": "hard", "execution": "external", "synchrony": "asynchronous", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-LABS-002", "RRX-LABS-004" ], "technical_contract_ref": "spec/technical.md#4-2-quest-lab-api", "evidence_refs": [ "spec/as-built.md#quest-diagnostics" ], "failure_owner": "Lab Operations", "timeout_retry": "Bounded retry with the same requisition key; route terminal rejection to Operations.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 920,136 V 216 Q 920,224 912,224 H 828 Q 820,224 820,232 V 260", "label_x": 868, "label_y": 216 } }, { "id": "edge-quest-to-order-ack", "source": "quest-diagnostics", "target": "order-labs", "relation": "acknowledges", "label": "accept or reject requisition", "bundle_id": "eb-quest-labs", "trigger": "Quest responds to a submitted requisition.", "payload": "Vendor requisition id, acceptance state, rejection codes, and collection instructions.", "pass_condition": "The response matches the internal order and active submission version.", "criticality": "hard", "execution": "external", "synchrony": "asynchronous", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-LABS-004", "RRX-LABS-005" ], "technical_contract_ref": "spec/technical.md#4-2-quest-lab-api", "evidence_refs": [ "spec/as-built.md#quest-diagnostics" ], "failure_owner": "Lab Operations", "timeout_retry": "Reconcile unknown acknowledgments; never create a second requisition blindly.", "recurring": false, "visible_by_default": false }, { "id": "edge-quest-to-lab-follow-up", "source": "quest-diagnostics", "target": "lab-follow-up", "relation": "transfers", "label": "deliver normalized Quest results", "bundle_id": "eb-quest-labs", "trigger": "Quest publishes a preliminary, corrected, or final result.", "payload": "Result id, analytes, units, ranges, flags, status, source timestamps, and report citation.", "pass_condition": "Patient and order match; units and source status pass normalization checks.", "criticality": "hard", "execution": "external", "synchrony": "event-driven", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-LABS-005", "RRX-LABS-011" ], "technical_contract_ref": "spec/technical.md#4-5-lab-follow-up", "evidence_refs": [ "spec/as-built.md#quest-diagnostics", "spec/as-built.md#lab-follow-up" ], "failure_owner": "Lab Operations", "timeout_retry": "Quarantine malformed or unmatched results and reconcile by vendor result id.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 884,286 H 1031 a 8,8 0 0,1 16,0 H 1076", "label_x": 980, "label_y": 278 } }, { "id": "edge-order-to-mobile-phlebotomy", "source": "order-labs", "target": "concierge-phlebotomy", "relation": "transfers", "label": "dispatch mobile collection", "bundle_id": null, "trigger": "A signed order selects at-home collection.", "payload": "Order, patient service location, collection requirements, quote constraints, and preferred window.", "pass_condition": "The location is serviceable and the patient accepts the governed quote and schedule.", "criticality": "hard", "execution": "external", "synchrony": "asynchronous", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-LABS-002", "RRX-LABS-006" ], "technical_contract_ref": "spec/technical.md#4-3-mobile-phlebotomy", "evidence_refs": [ "spec/as-built.md#concierge-phlebotomy" ], "failure_owner": "Lab Operations", "timeout_retry": "Retry dispatch with the same order id; return unavailable or rejected service to Operations.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 952,136 V 244 a 8,8 0 0,1 0,16", "label_x": 960, "label_y": 206 } }, { "id": "edge-mobile-phlebotomy-to-follow-up", "source": "concierge-phlebotomy", "target": "lab-follow-up", "relation": "transfers", "label": "deliver mobile collection results", "bundle_id": null, "trigger": "The mobile collection vendor returns a final or corrected result.", "payload": "Order and result ids, collection state, analytes, units, ranges, source report, and timestamps.", "pass_condition": "Patient and order match and the source report passes normalization checks.", "criticality": "hard", "execution": "external", "synchrony": "event-driven", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-LABS-007", "RRX-LABS-011" ], "technical_contract_ref": "spec/technical.md#4-5-lab-follow-up", "evidence_refs": [ "spec/as-built.md#concierge-phlebotomy", "spec/as-built.md#lab-follow-up" ], "failure_owner": "Lab Operations", "timeout_retry": "Quarantine unmatched or malformed results and open an actionable lab exception.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 1052,286 H 1080", "label_x": 1066, "label_y": 278 } }, { "id": "edge-order-to-function-import", "source": "order-labs", "target": "function-health-lab-import", "relation": "transfers", "label": "authorize external import", "bundle_id": "eb-function-import", "trigger": "The patient or clinician chooses an approved Function Health import path.", "payload": "Patient consent, import id, one-time token or file reference, and requested date range.", "pass_condition": "Consent is current and the import source is attributable to the patient.", "criticality": "important", "execution": "external", "synchrony": "asynchronous", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-LABS-008", "RRX-LABS-009" ], "technical_contract_ref": "spec/technical.md#4-4-function-health-lab-import", "evidence_refs": [ "spec/as-built.md#function-health-lab-import" ], "failure_owner": "Lab Operations", "timeout_retry": "Resume under an import lease; failed or expired work is visible and re-runnable.", "recurring": false, "visible_by_default": false }, { "id": "edge-function-import-to-order-ack", "source": "function-health-lab-import", "target": "order-labs", "relation": "acknowledges", "label": "record import disposition", "bundle_id": "eb-function-import", "trigger": "The importer validates the token or source file.", "payload": "Import id, accepted, rejected, or needs-review state, source checksum, and reason codes.", "pass_condition": "Disposition is durable and tied to the active import request.", "criticality": "important", "execution": "deterministic", "synchrony": "asynchronous", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-LABS-009" ], "technical_contract_ref": "spec/technical.md#4-4-function-health-lab-import", "evidence_refs": [ "spec/as-built.md#function-health-lab-import" ], "failure_owner": "Lab Operations", "timeout_retry": "Lease reaper exposes abandoned imports for safe retry.", "recurring": false, "visible_by_default": false }, { "id": "edge-function-import-to-follow-up", "source": "function-health-lab-import", "target": "lab-follow-up", "relation": "transfers", "label": "deliver cited imported results", "bundle_id": "eb-function-import", "trigger": "Mapped observations pass review or automatic promotion policy.", "payload": "Normalized observations, units, ranges, source document checksum, and citations.", "pass_condition": "Every promoted observation retains immutable source provenance.", "criticality": "hard", "execution": "deterministic", "synchrony": "event-driven", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-LABS-010", "RRX-LABS-011" ], "technical_contract_ref": "spec/technical.md#4-5-lab-follow-up", "evidence_refs": [ "spec/as-built.md#function-health-lab-import", "spec/as-built.md#lab-follow-up" ], "failure_owner": "Lab Operations", "timeout_retry": "Quarantine mapping conflicts and route them for review without losing source evidence.", "recurring": false, "visible_by_default": false }, { "id": "edge-lab-follow-up-to-rounds", "source": "lab-follow-up", "target": "doctor-newsfeed", "relation": "notifies", "label": "publish reviewed lab event", "bundle_id": null, "trigger": "A clinician reviews, acknowledges, or overrides a result disposition.", "payload": "Reviewed result summary, attribution, actions, urgency, and follow-up state.", "pass_condition": "The event reflects a human-reviewed disposition and contains no unreviewed clinical claim.", "criticality": "important", "execution": "human", "synchrony": "event-driven", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-LABS-012", "RRX-CARE-007" ], "technical_contract_ref": "spec/technical.md#7-3-clinical-rounds", "evidence_refs": [ "spec/as-built.md#lab-follow-up", "spec/as-built.md#doctor-newsfeed" ], "failure_owner": "Clinical Operations", "timeout_retry": "Keep the review task open and escalate overdue urgent results.", "recurring": false, "visible_by_default": false }, { "id": "edge-lab-follow-up-to-ops", "source": "lab-follow-up", "target": "ops-console", "relation": "notifies", "label": "raise lab exception", "bundle_id": null, "trigger": "A critical, unmatched, overdue, or failed lab event needs human action.", "payload": "Order and result ids, severity, reason, owner, due time, and source evidence.", "pass_condition": "The exception is actionable and contains no unnecessary clinical payload.", "criticality": "hard", "execution": "deterministic", "synchrony": "event-driven", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-LABS-013", "RRX-OPS-002" ], "technical_contract_ref": "spec/technical.md#12-1-ops-console", "evidence_refs": [ "spec/as-built.md#lab-follow-up", "spec/as-built.md#ops-console" ], "failure_owner": "Lab Operations", "timeout_retry": "Retry notification and retain the durable exception until acknowledged.", "recurring": false, "visible_by_default": false }, { "id": "edge-prescription-to-payment", "source": "prescription-generation", "target": "rx-pay", "relation": "triggers", "label": "create prescription charge", "bundle_id": null, "trigger": "An issued prescription requires a patient charge.", "payload": "Prescription fingerprint, patient id, amount, currency, and charge purpose.", "pass_condition": "The prescription is issued and no charge already exists for its fingerprint.", "criticality": "hard", "execution": "deterministic", "synchrony": "event-driven", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-EHR-008", "RRX-EHR-010" ], "technical_contract_ref": "spec/technical.md#3-3-prescription-pay", "evidence_refs": [ "spec/as-built.md#prescription-generation", "spec/as-built.md#rx-pay" ], "failure_owner": "Billing Operations", "timeout_retry": "Reuse the existing payment object; never create a second charge for the same fingerprint.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 780,184 V 392 Q 780,400 788,400 H 1165 Q 1173,400 1173,408 V 424", "label_x": 964, "label_y": 392 } }, { "id": "edge-rx-payment-to-stripe", "source": "rx-pay", "target": "billing-architecture", "relation": "transfers", "label": "submit prescription charge", "bundle_id": "eb-rx-payment", "trigger": "A valid prescription payment session is created or resumed.", "payload": "Patient, prescription fingerprint, amount, currency, and idempotency key.", "pass_condition": "Amount and prescription identity match the durable charge intent.", "criticality": "hard", "execution": "external", "synchrony": "asynchronous", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-EHR-011", "RRX-BILLING-002" ], "technical_contract_ref": "spec/technical.md#6-1-stripe", "evidence_refs": [ "spec/as-built.md#rx-pay", "spec/as-built.md#billing-architecture" ], "failure_owner": "Billing Operations", "timeout_retry": "Resume the existing hosted payment object with the same idempotency key.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 1173,476 V 496 Q 1173,504 1165,504 H 913 a 8,8 0 0,0 -16,0 H 660 Q 652,504 652,512", "label_x": 744, "label_y": 495 } }, { "id": "edge-stripe-to-rx-payment-ack", "source": "billing-architecture", "target": "rx-pay", "relation": "acknowledges", "label": "finalize charge webhook", "bundle_id": "eb-rx-payment", "trigger": "A verified Stripe payment event arrives.", "payload": "Stripe event id, PaymentIntent, terminal state, amount, and prescription metadata.", "pass_condition": "Signature, amount, patient, and prescription fingerprint all match.", "criticality": "hard", "execution": "external", "synchrony": "event-driven", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-EHR-012", "RRX-BILLING-003" ], "technical_contract_ref": "spec/technical.md#3-3-prescription-pay", "evidence_refs": [ "spec/as-built.md#billing-architecture", "spec/as-built.md#rx-pay" ], "failure_owner": "Billing Operations", "timeout_retry": "Stripe retries; event-id dedupe makes repeated finalization safe.", "recurring": false, "visible_by_default": false }, { "id": "edge-prescription-to-pharmacy", "source": "prescription-generation", "target": "internal-fulfillment-network", "relation": "transfers", "label": "queue issued prescription", "bundle_id": null, "trigger": "A prescription reaches issued state.", "payload": "Signed prescription, patient and prescriber ids, medication identity, dose, quantity, directions, and protocol version.", "pass_condition": "Clinical issuance gates pass; payment remains a separate branch rather than a fake sequential dependency.", "criticality": "hard", "execution": "deterministic", "synchrony": "event-driven", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-EHR-009", "RRX-FULFILLMENT-004" ], "technical_contract_ref": "spec/technical.md#5-2-pharmacy-queue", "evidence_refs": [ "spec/as-built.md#prescription-generation", "spec/as-built.md#internal-fulfillment-network" ], "failure_owner": "Pharmacy Operations", "timeout_retry": "Dedupe by prescription fingerprint and route incompatible orders to pharmacist review.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 804,184 V 376 Q 804,384 812,384 H 1299 Q 1307,384 1307,392 V 424", "label_x": 1060, "label_y": 376 } }, { "id": "edge-catalog-to-protocols", "source": "medication-catalog", "target": "protocols", "relation": "governs", "label": "map catalog to protocol", "bundle_id": null, "trigger": "A catalog entry or protocol version changes.", "payload": "Medication id, strengths, forms, active dates, and protocol mappings.", "pass_condition": "Mapping is explicit, versioned, and approved before use.", "criticality": "hard", "execution": "human", "synchrony": "event-driven", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-FULFILLMENT-015", "RRX-FULFILLMENT-002" ], "technical_contract_ref": "spec/technical.md#5-1-protocols", "evidence_refs": [ "spec/as-built.md#medication-catalog", "spec/as-built.md#protocols" ], "failure_owner": "Pharmacy Operations", "timeout_retry": "Keep unmapped or inactive catalog entries unavailable to prescribing and fulfillment.", "recurring": false, "visible_by_default": false }, { "id": "edge-protocols-to-pharmacy", "source": "protocols", "target": "internal-fulfillment-network", "relation": "gates", "label": "approve preparation protocol", "bundle_id": null, "trigger": "A pharmacy order enters pharmacist review or preparation.", "payload": "Approved protocol version, formulation, preparation instructions, QA requirements, and mapping.", "pass_condition": "The prescription maps to an active approved protocol and required pharmacist review succeeds.", "criticality": "hard", "execution": "human", "synchrony": "synchronous", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-FULFILLMENT-003", "RRX-FULFILLMENT-005" ], "technical_contract_ref": "spec/technical.md#5-2-pharmacy-queue", "evidence_refs": [ "spec/as-built.md#protocols", "spec/as-built.md#internal-fulfillment-network" ], "failure_owner": "Pharmacy Operations", "timeout_retry": "Hold the order in pharmacist exception review; never reverse the dependency.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 1382,450 L 1370,450", "label_x": 1376, "label_y": 443 } }, { "id": "edge-bud-to-pharmacy-release", "source": "beyond-use-date", "target": "internal-fulfillment-network", "relation": "gates", "label": "supply release evidence", "bundle_id": null, "trigger": "A prepared lot reaches final pharmacy release.", "payload": "Pharmacy-supplied beyond-use date, lot, preparation timestamp, source process, and pharmacist attestation.", "pass_condition": "The pharmacy supplies a valid BUD through its physical process; the app does not invent it.", "criticality": "hard", "execution": "human", "synchrony": "synchronous", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-FULFILLMENT-009", "RRX-FULFILLMENT-006" ], "technical_contract_ref": "spec/technical.md#5-3-beyond-use-date", "evidence_refs": [ "spec/as-built.md#beyond-use-date" ], "failure_owner": "Pharmacy Operations", "timeout_retry": "Hold release until corrected pharmacy evidence is supplied.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 1307,512 V 476", "label_x": 1315, "label_y": 497 } }, { "id": "edge-pharmacy-to-three-pl", "source": "internal-fulfillment-network", "target": "3pl-fulfillment-handoff", "relation": "transfers", "label": "release fulfillment order", "bundle_id": "eb-3pl-shipment", "trigger": "A pharmacist records final release and fulfillment readiness for an order.", "payload": "Release id, order, patient shipping data, package, service level, label instructions, and BUD evidence.", "pass_condition": "Pharmacist release is final and required shipping fields validate.", "criticality": "hard", "execution": "external", "synchrony": "asynchronous", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-FULFILLMENT-007", "RRX-FULFILLMENT-017" ], "technical_contract_ref": "spec/technical.md#5-6-3pl-fulfillment-handoff", "evidence_refs": [ "spec/as-built.md#3pl-fulfillment-handoff" ], "failure_owner": "Fulfillment Operations", "timeout_retry": "Retry with the same release id; timeout returns the order to the pharmacy exception queue.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 1307,476 V 488 Q 1307,496 1299,496 H 1196 Q 1188,496 1188,504 V 512", "label_x": 1240, "label_y": 488 } }, { "id": "edge-three-pl-to-pharmacy-ack", "source": "3pl-fulfillment-handoff", "target": "internal-fulfillment-network", "relation": "acknowledges", "label": "accept or reject release", "bundle_id": "eb-3pl-shipment", "trigger": "The 3PL responds to a released order.", "payload": "Release id, 3PL order id, accepted or rejected state, and reason codes.", "pass_condition": "The acknowledgment matches the active release id and payload fingerprint.", "criticality": "hard", "execution": "external", "synchrony": "asynchronous", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-FULFILLMENT-018", "RRX-FULFILLMENT-019" ], "technical_contract_ref": "spec/technical.md#5-6-3pl-fulfillment-handoff", "evidence_refs": [ "spec/as-built.md#3pl-fulfillment-handoff" ], "failure_owner": "Fulfillment Operations", "timeout_retry": "Unknown or rejected acknowledgments create a durable pharmacy and Operations exception.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 1196,520 H 1299 Q 1315,520 1315,504 V 476", "label_x": 1248, "label_y": 512 } }, { "id": "edge-three-pl-to-delivery-events", "source": "3pl-fulfillment-handoff", "target": "delivery-bot", "relation": "reconciles", "label": "stream shipment events", "bundle_id": "eb-3pl-shipment", "trigger": "The 3PL or carrier emits packing, label, tender, tracking, delivery, or exception state.", "payload": "Shipment and label ids, tracking number, carrier, event id, event type, timestamp, and exception detail.", "pass_condition": "The event authenticates, dedupes, and matches an accepted release or creates a governed unmatched exception.", "criticality": "hard", "execution": "external", "synchrony": "event-driven", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-FULFILLMENT-020", "RRX-FULFILLMENT-011" ], "technical_contract_ref": "spec/technical.md#5-4-delivery-bot", "evidence_refs": [ "spec/as-built.md#3pl-fulfillment-handoff", "spec/as-built.md#delivery-bot" ], "failure_owner": "Fulfillment Operations", "timeout_retry": "Dedupe event ids, retry processing, and reconcile shipment state on a scheduled sweep.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 1132,560 V 600 Q 1132,608 1124,608 H 956 Q 948,608 948,616 V 692", "label_x": 1032, "label_y": 600 } }, { "id": "edge-three-pl-to-ops", "source": "3pl-fulfillment-handoff", "target": "ops-console", "relation": "notifies", "label": "raise shipment exception", "bundle_id": null, "trigger": "Submission, acknowledgment, label, tender, tracking, or reconciliation enters exception state.", "payload": "Release, order, shipment, exception class, current owner, retry state, and source evidence.", "pass_condition": "The exception is durable, deduped, and actionable.", "criticality": "hard", "execution": "deterministic", "synchrony": "event-driven", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-FULFILLMENT-021", "RRX-OPS-002" ], "technical_contract_ref": "spec/technical.md#12-1-ops-console", "evidence_refs": [ "spec/as-built.md#3pl-fulfillment-handoff", "spec/as-built.md#ops-console" ], "failure_owner": "Fulfillment Operations", "timeout_retry": "Retry notification while retaining the exception until a human resolves it.", "recurring": false, "visible_by_default": false }, { "id": "edge-delivery-to-patient-chat", "source": "delivery-bot", "target": "doctor-patient-texting", "relation": "notifies", "label": "send delivery milestone", "bundle_id": null, "trigger": "A patient-visible shipment milestone becomes durable.", "payload": "Approved milestone, shipment alias, expected date, safe support action, and dedupe key.", "pass_condition": "The event is patient-visible, current, and contains no unnecessary fulfillment detail.", "criticality": "important", "execution": "deterministic", "synchrony": "event-driven", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-FULFILLMENT-012", "RRX-CARE-010" ], "technical_contract_ref": "spec/technical.md#7-4-patient-chat", "evidence_refs": [ "spec/as-built.md#delivery-bot", "spec/as-built.md#doctor-patient-texting" ], "failure_owner": "Patient Operations", "timeout_retry": "Dedupe by milestone and shipment; record delivery failure for Operations.", "recurring": false, "visible_by_default": false }, { "id": "edge-delivery-to-rounds", "source": "delivery-bot", "target": "doctor-newsfeed", "relation": "informs", "label": "publish care delivery event", "bundle_id": null, "trigger": "Tender, delivery, or material shipment exception is confirmed.", "payload": "Delivery status, timestamp, therapy context, and exception summary.", "pass_condition": "The event is attributable to the correct patient and prescription.", "criticality": "advisory", "execution": "deterministic", "synchrony": "event-driven", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-FULFILLMENT-013", "RRX-CARE-007" ], "technical_contract_ref": "spec/technical.md#7-3-clinical-rounds", "evidence_refs": [ "spec/as-built.md#delivery-bot", "spec/as-built.md#doctor-newsfeed" ], "failure_owner": "Clinical Operations", "timeout_retry": "Reconcile missing delivery state; do not manufacture a care event.", "recurring": false, "visible_by_default": false }, { "id": "edge-delivery-to-checkup", "source": "delivery-bot", "target": "check-ups", "relation": "triggers", "label": "anchor depletion clock", "bundle_id": null, "trigger": "Delivery is confirmed for a medication supply.", "payload": "Delivered-at timestamp, prescribed quantity, expected use, and prescription id.", "pass_condition": "Delivery is authoritative and the associated prescription is active.", "criticality": "important", "execution": "deterministic", "synchrony": "event-driven", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-FULFILLMENT-013", "RRX-CARE-001" ], "technical_contract_ref": "spec/technical.md#7-1-follow-up-appointment", "evidence_refs": [ "spec/as-built.md#delivery-bot", "spec/as-built.md#check-ups" ], "failure_owner": "Clinical Operations", "timeout_retry": "Reconcile delivery before scheduling; never infer delivery from label creation.", "recurring": true, "visible_by_default": true, "geometry": { "d": "M 948,696 V 648 Q 948,640 956,640 H 1068 Q 1076,640 1076,632 V 188", "label_x": 964, "label_y": 632 } }, { "id": "edge-limits-to-checkup", "source": "prescription-limits", "target": "check-ups", "relation": "gates", "label": "require ninety-day review", "bundle_id": null, "trigger": "Expected supply approaches the approved continuation boundary.", "payload": "Prescription history, delivered supply, adherence signals, labs, and last clinician decision.", "pass_condition": "A clinician completes the required data-driven continuation decision.", "criticality": "hard", "execution": "deterministic", "synchrony": "event-driven", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-EHR-014", "RRX-CARE-002" ], "technical_contract_ref": "spec/technical.md#7-1-follow-up-appointment", "evidence_refs": [ "spec/as-built.md#prescription-limits", "spec/as-built.md#check-ups" ], "failure_owner": "Clinical Operations", "timeout_retry": "Hold automated continuation and escalate overdue clinician review.", "recurring": true, "visible_by_default": true, "geometry": { "d": "M 1253,360 H 1176 Q 1168,360 1168,352 V 178 Q 1168,170 1160,170 H 1152", "label_x": 1176, "label_y": 352 } }, { "id": "edge-refill-to-checkup", "source": "refills", "target": "check-ups", "relation": "transfers", "label": "request clinician refill review", "bundle_id": null, "trigger": "A patient requests continuation or a depletion window opens.", "payload": "Patient request, adherence, side effects, labs, delivered supply, and medication history.", "pass_condition": "The request is attributable and contains enough evidence for clinician review or explicitly names what is missing.", "criticality": "hard", "execution": "human", "synchrony": "asynchronous", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-CARE-004", "RRX-CARE-002" ], "technical_contract_ref": "spec/technical.md#7-2-refills", "evidence_refs": [ "spec/as-built.md#refills", "spec/as-built.md#check-ups" ], "failure_owner": "Clinical Operations", "timeout_retry": "Keep the refill on hold and notify the responsible clinical queue.", "recurring": true, "visible_by_default": false }, { "id": "edge-checkup-to-refill-decision", "source": "check-ups", "target": "refills", "relation": "informs", "label": "publish refill decision", "bundle_id": null, "trigger": "A clinician completes continue, change, or stop review for a refill request.", "payload": "Signed decision, patient-facing disposition, next action, and source encounter id.", "pass_condition": "The decision is signed and attributable to the responsible clinician.", "criticality": "important", "execution": "human", "synchrony": "event-driven", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-CARE-003", "RRX-CARE-005" ], "technical_contract_ref": "spec/technical.md#7-2-refills", "evidence_refs": [ "spec/as-built.md#check-ups", "spec/as-built.md#refills" ], "failure_owner": "Clinical Operations", "timeout_retry": "Keep the request visibly pending until a durable decision exists.", "recurring": true, "visible_by_default": true, "geometry": { "d": "M 1152,162 L 1180,162", "label_x": 1166, "label_y": 154 } }, { "id": "edge-checkup-to-prescription", "source": "check-ups", "target": "prescription-generation", "relation": "gates", "label": "authorize reissue", "bundle_id": null, "trigger": "A clinician completes continue, change, or stop review.", "payload": "Signed continuation decision, current evidence, changed plan, and prior prescription reference.", "pass_condition": "Only a signed continue or change decision may start prescription reissue.", "criticality": "hard", "execution": "human", "synchrony": "event-driven", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-CARE-003", "RRX-CARE-006" ], "technical_contract_ref": "spec/technical.md#3-2-prescription-generation", "evidence_refs": [ "spec/as-built.md#check-ups", "spec/as-built.md#prescription-generation" ], "failure_owner": "Clinical Operations", "timeout_retry": "No direct refill-to-pharmacy shortcut; incomplete review remains on hold.", "recurring": true, "visible_by_default": true, "geometry": { "d": "M 1016,162 H 816", "label_x": 916, "label_y": 154 } }, { "id": "edge-rounds-to-checkup", "source": "doctor-newsfeed", "target": "check-ups", "relation": "informs", "label": "surface follow-up signal", "bundle_id": null, "trigger": "A reviewed care event suggests follow-up action.", "payload": "Attributed event, patient, urgency, suggested action, and source link.", "pass_condition": "A clinician can inspect the source and chooses whether to act.", "criticality": "advisory", "execution": "human", "synchrony": "event-driven", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-CARE-008", "RRX-CARE-001" ], "technical_contract_ref": "spec/technical.md#7-1-follow-up-appointment", "evidence_refs": [ "spec/as-built.md#doctor-newsfeed", "spec/as-built.md#check-ups" ], "failure_owner": "Clinical Operations", "timeout_retry": "Retain the event without auto-creating a clinical decision.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 1400,226 H 1315 a 8,8 0 0,0 -16,0 H 1108 Q 1100,226 1100,218 V 188", "label_x": 1154, "label_y": 217 } }, { "id": "edge-membership-to-stripe", "source": "membership-subscription", "target": "billing-architecture", "relation": "transfers", "label": "submit membership payment", "bundle_id": "eb-membership-payment", "trigger": "The patient enters the membership payment gate.", "payload": "Patient id, customer id, price version, SetupIntent or subscription request, and idempotency key.", "pass_condition": "The amount and price version match the active membership offer.", "criticality": "hard", "execution": "external", "synchrony": "asynchronous", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-ONBOARDING-016", "RRX-BILLING-001" ], "technical_contract_ref": "spec/technical.md#6-1-stripe", "evidence_refs": [ "spec/as-built.md#membership-subscription", "spec/as-built.md#billing-architecture" ], "failure_owner": "Billing Operations", "timeout_retry": "Resume the existing Stripe object; do not duplicate customers or subscriptions.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 637,476 V 512", "label_x": 645, "label_y": 494 } }, { "id": "edge-stripe-to-membership-ack", "source": "billing-architecture", "target": "membership-subscription", "relation": "acknowledges", "label": "activate membership webhook", "bundle_id": "eb-membership-payment", "trigger": "A verified Stripe membership event arrives.", "payload": "Stripe event id, customer, subscription or setup state, price, and terminal status.", "pass_condition": "Signature, patient mapping, price, and event ordering validate.", "criticality": "hard", "execution": "external", "synchrony": "event-driven", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-BILLING-003", "RRX-ONBOARDING-015" ], "technical_contract_ref": "spec/technical.md#1-5-membership-pay", "evidence_refs": [ "spec/as-built.md#billing-architecture", "spec/as-built.md#membership-subscription" ], "failure_owner": "Billing Operations", "timeout_retry": "Stripe retries; event-id dedupe and monotonic state prevent regression.", "recurring": false, "visible_by_default": false }, { "id": "edge-patient-chat-to-safety", "source": "doctor-patient-texting", "target": "urgent-text-escalation", "relation": "gates", "label": "screen care message", "bundle_id": null, "trigger": "A patient sends a post-onboarding care message.", "payload": "Message, attachments, patient and conversation ids, and source event id.", "pass_condition": "No deterministic urgent-risk hold is active.", "criticality": "hard", "execution": "deterministic", "synchrony": "synchronous", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-CARE-011", "RRX-CARE-013" ], "technical_contract_ref": "spec/technical.md#7-5-medical-support-chat", "evidence_refs": [ "spec/as-built.md#doctor-patient-texting", "spec/as-built.md#urgent-text-escalation" ], "failure_owner": "Messaging Operations", "timeout_retry": "Fail closed to urgent human handling.", "recurring": false, "visible_by_default": false }, { "id": "edge-patient-chat-to-router", "source": "doctor-patient-texting", "target": "agent-router", "relation": "routes", "label": "classify safe support turn", "bundle_id": null, "trigger": "A care message clears the deterministic safety guard.", "payload": "Message context, patient state, conversation state, and allowed focused routes.", "pass_condition": "No human takeover or safety hold is active.", "criticality": "hard", "execution": "deterministic", "synchrony": "asynchronous", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-CARE-011", "RRX-AGENTS-013" ], "technical_contract_ref": "spec/technical.md#9-1-agent-router", "evidence_refs": [ "spec/as-built.md#doctor-patient-texting", "spec/as-built.md#agent-router" ], "failure_owner": "Messaging Operations", "timeout_retry": "Keep the message durable and escalate after bounded retry.", "recurring": false, "visible_by_default": false }, { "id": "edge-router-to-patient-support", "source": "agent-router", "target": "patient-support", "relation": "routes", "label": "route service support", "bundle_id": null, "trigger": "The focused route is service, billing, cancellation, or general support.", "payload": "Message, patient context, safety disposition, permitted actions, and escalation policy.", "pass_condition": "The issue is non-clinical or explicitly governed for the support agent.", "criticality": "important", "execution": "deterministic", "synchrony": "asynchronous", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-AGENTS-014", "RRX-AGENTS-016" ], "technical_contract_ref": "spec/technical.md#9-2-patient-support", "evidence_refs": [ "spec/as-built.md#patient-support" ], "failure_owner": "Patient Operations", "timeout_retry": "Escalate unknown, clinical, or failed actions to a human queue.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 780,744 V 880", "label_x": 788, "label_y": 816 } }, { "id": "edge-support-to-retention", "source": "patient-support", "target": "retention-agent", "relation": "routes", "label": "offer governed retention", "bundle_id": null, "trigger": "The patient explicitly requests cancellation and is eligible for one optional save attempt.", "payload": "Cancellation intent, eligibility, approved offers, consent, and stop conditions.", "pass_condition": "No safety, clinical, legal, opt-out, or human-takeover block exists.", "criticality": "important", "execution": "agent", "synchrony": "asynchronous", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-AGENTS-018", "RRX-AGENTS-019" ], "technical_contract_ref": "spec/technical.md#9-3-retention-agent", "evidence_refs": [ "spec/as-built.md#patient-support", "spec/as-built.md#retention-agent" ], "failure_owner": "Patient Operations", "timeout_retry": "At most one governed attempt; stop immediately on decline or repeated cancellation intent.", "recurring": false, "visible_by_default": false }, { "id": "edge-support-to-ops", "source": "patient-support", "target": "ops-console", "relation": "notifies", "label": "escalate support exception", "bundle_id": null, "trigger": "The request needs a human, privileged action, or policy decision.", "payload": "Patient-safe summary, reason, requested action, current owner, and relevant audit references.", "pass_condition": "The escalation is actionable and least-privilege.", "criticality": "important", "execution": "deterministic", "synchrony": "event-driven", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-AGENTS-017", "RRX-OPS-001" ], "technical_contract_ref": "spec/technical.md#12-1-ops-console", "evidence_refs": [ "spec/as-built.md#patient-support", "spec/as-built.md#ops-console" ], "failure_owner": "Patient Operations", "timeout_retry": "Retain the durable case and retry notification without duplicate actions.", "recurring": false, "visible_by_default": false }, { "id": "edge-urgent-to-ops", "source": "urgent-text-escalation", "target": "ops-console", "relation": "notifies", "label": "open urgent incident", "bundle_id": null, "trigger": "The safety screen holds a message or a governed reply needs human action.", "payload": "Incident id, risk reason, patient contact context, source message, due time, and current hold.", "pass_condition": "The incident is durable and exposes only necessary clinical context.", "criticality": "hard", "execution": "deterministic", "synchrony": "event-driven", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-CARE-015", "RRX-OPS-002" ], "technical_contract_ref": "spec/technical.md#12-1-ops-console", "evidence_refs": [ "spec/as-built.md#urgent-text-escalation", "spec/as-built.md#ops-console" ], "failure_owner": "Clinical Operations", "timeout_retry": "Retry alert delivery and keep automated messaging held until explicit resolution.", "recurring": false, "visible_by_default": false }, { "id": "edge-ops-to-urgent-release", "source": "ops-console", "target": "urgent-text-escalation", "relation": "operates", "label": "resolve and release incident", "bundle_id": null, "trigger": "An authorized human records a governed incident disposition.", "payload": "Incident id, disposition, approved reply or action, operator, timestamp, and audit reason.", "pass_condition": "The operator has permission and the action passes confirmation and idempotency preflight.", "criticality": "hard", "execution": "human", "synchrony": "synchronous", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-OPS-003", "RRX-CARE-016" ], "technical_contract_ref": "spec/technical.md#7-5-medical-support-chat", "evidence_refs": [ "spec/as-built.md#ops-console", "spec/as-built.md#urgent-text-escalation" ], "failure_owner": "Clinical Operations", "timeout_retry": "Leave the incident held on action failure; allow a safe idempotent retry.", "recurring": false, "visible_by_default": false }, { "id": "edge-commandments-to-router", "source": "cams-crack-commandments", "target": "agent-router", "relation": "governs", "label": "apply agent operating rules", "bundle_id": null, "trigger": "The router authorizes an agent turn or action.", "payload": "Approved routing, safety, tool, escalation, evidence, and scope rules.", "pass_condition": "The proposed route and action remain within the approved operating envelope.", "criticality": "hard", "execution": "deterministic", "synchrony": "synchronous", "delivery_state": "live", "lifecycle": "both", "evidence_state": "current-verified", "business_rule_refs": [ "RRX-AGENTS-001", "RRX-AGENTS-013" ], "technical_contract_ref": "spec/technical.md#cams-crack-commandments", "evidence_refs": [ "spec/as-built.md#cams-crack-commandments", "spec/as-built.md#agent-router" ], "failure_owner": "Agent Operations", "timeout_retry": "Fail closed to a human or deterministic path; do not widen agent authority.", "recurring": false, "visible_by_default": false }, { "id": "edge-commandments-to-onboarding", "source": "cams-crack-commandments", "target": "onboarding-agent", "relation": "governs", "label": "bound onboarding agent", "bundle_id": null, "trigger": "The onboarding agent proposes text, a tool call, or a record update.", "payload": "Approved tone, safety, one-question, non-invention, ID-refusal, and escalation rules.", "pass_condition": "The turn stays inside the defined onboarding responsibility and tool permissions.", "criticality": "hard", "execution": "deterministic", "synchrony": "synchronous", "delivery_state": "live", "lifecycle": "both", "evidence_state": "current-verified", "business_rule_refs": [ "RRX-AGENTS-006", "RRX-ONBOARDING-006" ], "technical_contract_ref": "spec/technical.md#1-2-onboarding-agent", "evidence_refs": [ "spec/as-built.md#cams-crack-commandments", "spec/as-built.md#onboarding-agent" ], "failure_owner": "Agent Operations", "timeout_retry": "Suppress unsafe output and route the durable event to human review.", "recurring": false, "visible_by_default": false }, { "id": "edge-protocols-to-sandbox", "source": "protocols", "target": "protocol-sandbox", "relation": "transfers", "label": "validate candidate protocol", "bundle_id": null, "trigger": "A candidate protocol version is ready for isolated validation.", "payload": "Candidate version, fixtures, expected constraints, reviewer, and promotion criteria.", "pass_condition": "The candidate is non-production and has a complete validation plan.", "criticality": "important", "execution": "human", "synchrony": "asynchronous", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-FULFILLMENT-002", "RRX-PLATFORM-010" ], "technical_contract_ref": "spec/technical.md#10-5-testflight-protocol-sandbox", "evidence_refs": [ "spec/as-built.md#protocol-sandbox" ], "failure_owner": "Clinical Platform", "timeout_retry": "Keep failure isolated; rerun only a new immutable candidate or approved fixture set.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 1441,476 V 512", "label_x": 1449, "label_y": 495 } }, { "id": "edge-ios-to-device-data", "source": "ronanrx-ios", "target": "app-data-collection", "relation": "transfers", "label": "sync consented observations", "bundle_id": "eb-device-sync", "trigger": "The iOS outbox has new or changed consented observations.", "payload": "Connector, patient, source observation ids, values, units, timestamps, and sync cursor.", "pass_condition": "Consent is active and every observation type is allowlisted.", "criticality": "important", "execution": "external", "synchrony": "asynchronous", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-PLATFORM-002", "RRX-DATA-001" ], "technical_contract_ref": "spec/technical.md#8-1-device-data", "evidence_refs": [ "spec/as-built.md#ronanrx-ios", "spec/as-built.md#app-data-collection" ], "failure_owner": "Platform Operations", "timeout_retry": "Persist in the local outbox and retry with backoff until acknowledgment or revocation.", "recurring": true, "visible_by_default": false }, { "id": "edge-device-data-to-ios-ack", "source": "app-data-collection", "target": "ronanrx-ios", "relation": "acknowledges", "label": "acknowledge sync cursor", "bundle_id": "eb-device-sync", "trigger": "The server durably stores a sync batch.", "payload": "Connector id, highest durable cursor, accepted count, rejected ids, and reason codes.", "pass_condition": "The acknowledgment corresponds to the submitted patient and connector.", "criticality": "important", "execution": "deterministic", "synchrony": "asynchronous", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-DATA-003", "RRX-PLATFORM-003" ], "technical_contract_ref": "spec/technical.md#10-1-ronanrx-ios", "evidence_refs": [ "spec/as-built.md#ronanrx-ios", "spec/as-built.md#app-data-collection" ], "failure_owner": "Platform Operations", "timeout_retry": "The client retains unacknowledged items and safely replays them.", "recurring": true, "visible_by_default": false }, { "id": "edge-device-data-to-note", "source": "app-data-collection", "target": "charting-ehr", "relation": "reconciles", "label": "project governed observations", "bundle_id": "eb-device-sync", "trigger": "Normalized allowlisted observations become available or consent is revoked.", "payload": "Observation ids, values, units, timestamps, source, consent, quality, and revocation state.", "pass_condition": "Projection preserves provenance and removes or invalidates revoked data as policy requires.", "criticality": "important", "execution": "deterministic", "synchrony": "event-driven", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-DATA-004", "RRX-EHR-002" ], "technical_contract_ref": "spec/technical.md#3-1-clinical-note", "evidence_refs": [ "spec/as-built.md#app-data-collection", "spec/as-built.md#charting-ehr" ], "failure_owner": "Clinical Platform", "timeout_retry": "Reconcile from the durable source cursor; quarantine invalid observations.", "recurring": true, "visible_by_default": false }, { "id": "edge-device-data-to-checkup", "source": "app-data-collection", "target": "check-ups", "relation": "informs", "label": "add weight and adherence signals", "bundle_id": null, "trigger": "A consented observation becomes relevant to continuing-care review.", "payload": "Weight, adherence, activity, source, units, timestamp, consent scope, and quality flags.", "pass_condition": "The observation is allowlisted, current enough for its use, and clearly labeled as device-sourced.", "criticality": "advisory", "execution": "deterministic", "synchrony": "event-driven", "delivery_state": "partial", "lifecycle": "both", "evidence_state": "mixed", "business_rule_refs": [ "RRX-DATA-002", "RRX-CARE-002" ], "technical_contract_ref": "spec/technical.md#7-1-follow-up-appointment", "evidence_refs": [ "spec/as-built.md#app-data-collection", "spec/as-built.md#check-ups" ], "failure_owner": "Clinical Operations", "timeout_retry": "Skip stale or invalid data and show the clinician that the source is unavailable.", "recurring": true, "visible_by_default": true, "geometry": { "d": "M 1356,880 V 868 Q 1356,860 1364,860 H 1366 Q 1374,860 1374,852 V 458 a 8,8 0 0,1 0,-16 V 236 Q 1374,228 1366,228 H 1315 a 8,8 0 0,0 -16,0 H 1124 Q 1116,228 1116,220 V 188", "label_x": 1286, "label_y": 649 } }, { "id": "historical-iphone-signup", "source": "iphone-link", "target": "signup-intake", "relation": "routes", "label": "hidden direct signup jump", "bundle_id": null, "trigger": "iMessage (Linq) reaches the governed handoff condition.", "payload": "hidden direct signup jump contract payload with stable source identifiers and attributable timestamps.", "pass_condition": "The source contract is valid, authorized, attributable, and not already completed.", "criticality": "important", "execution": "deterministic", "synchrony": "asynchronous", "delivery_state": "legacy", "lifecycle": "historical", "evidence_state": "carried-forward", "business_rule_refs": [ "RRX-ONBOARDING-001" ], "technical_contract_ref": "spec/technical.md#1-1-imessage-linq", "evidence_refs": [ "spec/as-built.md#iphone-link (historical map assumption)" ], "failure_owner": "Patient Product owner", "timeout_retry": "Retry only under a stable idempotency key; expose terminal or conflicting state to the failure owner.", "recurring": false, "visible_by_default": false, "geometry": { "d": "M 232,512 L 232,476", "label_x": 240, "label_y": 494 } }, { "id": "historical-rx-labs", "source": "prescription-generation", "target": "order-labs", "relation": "triggers", "label": "prescription-causes-labs assumption", "bundle_id": null, "trigger": "Prescription Generation reaches the governed handoff condition.", "payload": "prescription-causes-labs assumption contract payload with stable source identifiers and attributable timestamps.", "pass_condition": "The source contract is valid, authorized, attributable, and not already completed.", "criticality": "important", "execution": "deterministic", "synchrony": "asynchronous", "delivery_state": "legacy", "lifecycle": "historical", "evidence_state": "carried-forward", "business_rule_refs": [ "RRX-EHR-005" ], "technical_contract_ref": "spec/technical.md#3-2-prescription-generation", "evidence_refs": [ "spec/as-built.md#prescription-generation (historical map assumption)" ], "failure_owner": "Clinical Product owner", "timeout_retry": "Retry only under a stable idempotency key; expose terminal or conflicting state to the failure owner.", "recurring": false, "visible_by_default": false, "geometry": { "d": "M 816,162 H 892 Q 900,162 900,154 V 136", "label_x": 858, "label_y": 154 } }, { "id": "historical-labs-checkup", "source": "order-labs", "target": "check-ups", "relation": "triggers", "label": "labs-direct-to-checkup assumption", "bundle_id": null, "trigger": "Order Labs reaches the governed handoff condition.", "payload": "labs-direct-to-checkup assumption contract payload with stable source identifiers and attributable timestamps.", "pass_condition": "The source contract is valid, authorized, attributable, and not already completed.", "criticality": "important", "execution": "deterministic", "synchrony": "asynchronous", "delivery_state": "legacy", "lifecycle": "historical", "evidence_state": "carried-forward", "business_rule_refs": [ "RRX-LABS-001" ], "technical_contract_ref": "spec/technical.md#4-1-order-labs", "evidence_refs": [ "spec/as-built.md#order-labs (historical map assumption)" ], "failure_owner": "Clinical Product owner", "timeout_retry": "Retry only under a stable idempotency key; expose terminal or conflicting state to the failure owner.", "recurring": false, "visible_by_default": false, "geometry": { "d": "M 984,110 H 1076 Q 1084,110 1084,118 V 136", "label_x": 1034, "label_y": 102 } }, { "id": "historical-intake-rx-pay", "source": "pre-doctor-intake", "target": "rx-pay", "relation": "triggers", "label": "intake-causes-prescription-payment assumption", "bundle_id": null, "trigger": "Intake 2: Pre-Appointment reaches the governed handoff condition.", "payload": "intake-causes-prescription-payment assumption contract payload with stable source identifiers and attributable timestamps.", "pass_condition": "The source contract is valid, authorized, attributable, and not already completed.", "criticality": "important", "execution": "deterministic", "synchrony": "asynchronous", "delivery_state": "legacy", "lifecycle": "historical", "evidence_state": "carried-forward", "business_rule_refs": [ "RRX-SCHEDULING-009" ], "technical_contract_ref": "spec/technical.md#2-3-intake-2-pre-appointment", "evidence_refs": [ "spec/as-built.md#pre-doctor-intake (historical map assumption)" ], "failure_owner": "Clinical Product owner", "timeout_retry": "Retry only under a stable idempotency key; expose terminal or conflicting state to the failure owner.", "recurring": false, "visible_by_default": false, "geometry": { "d": "M 1100,450 L 1112,450", "label_x": 1106, "label_y": 442 } }, { "id": "historical-rx-pay-pharmacy", "source": "rx-pay", "target": "internal-fulfillment-network", "relation": "gates", "label": "payment-gates-pharmacy assumption", "bundle_id": null, "trigger": "Prescription Pay reaches the governed handoff condition.", "payload": "payment-gates-pharmacy assumption contract payload with stable source identifiers and attributable timestamps.", "pass_condition": "The source contract is valid, authorized, attributable, and not already completed.", "criticality": "important", "execution": "deterministic", "synchrony": "asynchronous", "delivery_state": "legacy", "lifecycle": "historical", "evidence_state": "carried-forward", "business_rule_refs": [ "RRX-EHR-010" ], "technical_contract_ref": "spec/technical.md#3-3-prescription-pay", "evidence_refs": [ "spec/as-built.md#rx-pay (historical map assumption)" ], "failure_owner": "Clinical Product owner", "timeout_retry": "Retry only under a stable idempotency key; expose terminal or conflicting state to the failure owner.", "recurring": false, "visible_by_default": false, "geometry": { "d": "M 1234,450 L 1246,450", "label_x": 1240, "label_y": 442 } }, { "id": "historical-pharmacy-protocol", "source": "internal-fulfillment-network", "target": "protocols", "relation": "triggers", "label": "pharmacy-to-protocol reverse assumption", "bundle_id": null, "trigger": "Pharmacy Queue reaches the governed handoff condition.", "payload": "pharmacy-to-protocol reverse assumption contract payload with stable source identifiers and attributable timestamps.", "pass_condition": "The source contract is valid, authorized, attributable, and not already completed.", "criticality": "important", "execution": "deterministic", "synchrony": "asynchronous", "delivery_state": "legacy", "lifecycle": "historical", "evidence_state": "carried-forward", "business_rule_refs": [ "RRX-FULFILLMENT-004" ], "technical_contract_ref": "spec/technical.md#5-2-pharmacy-queue", "evidence_refs": [ "spec/as-built.md#internal-fulfillment-network (historical map assumption)" ], "failure_owner": "Operations Platform owner", "timeout_retry": "Retry only under a stable idempotency key; expose terminal or conflicting state to the failure owner.", "recurring": false, "visible_by_default": false, "geometry": { "d": "M 1368,450 L 1380,450", "label_x": 1374, "label_y": 442 } }, { "id": "historical-refill-pharmacy", "source": "refills", "target": "internal-fulfillment-network", "relation": "transfers", "label": "refill-bypasses-clinician reissue assumption", "bundle_id": null, "trigger": "Refills reaches the governed handoff condition.", "payload": "refill-bypasses-clinician reissue assumption contract payload with stable source identifiers and attributable timestamps.", "pass_condition": "The source contract is valid, authorized, attributable, and not already completed.", "criticality": "important", "execution": "deterministic", "synchrony": "asynchronous", "delivery_state": "legacy", "lifecycle": "historical", "evidence_state": "carried-forward", "business_rule_refs": [ "RRX-CARE-004" ], "technical_contract_ref": "spec/technical.md#7-2-refills", "evidence_refs": [ "spec/as-built.md#refills (historical map assumption)" ], "failure_owner": "Clinical Product owner", "timeout_retry": "Retry only under a stable idempotency key; expose terminal or conflicting state to the failure owner.", "recurring": false, "visible_by_default": false, "geometry": { "d": "M 1307,188 V 424", "label_x": 1315, "label_y": 360 } }, { "id": "historical-pharmacy-bud", "source": "internal-fulfillment-network", "target": "beyond-use-date", "relation": "triggers", "label": "BUD as later sequential step", "bundle_id": null, "trigger": "Pharmacy Queue reaches the governed handoff condition.", "payload": "BUD as later sequential step contract payload with stable source identifiers and attributable timestamps.", "pass_condition": "The source contract is valid, authorized, attributable, and not already completed.", "criticality": "important", "execution": "deterministic", "synchrony": "asynchronous", "delivery_state": "legacy", "lifecycle": "historical", "evidence_state": "carried-forward", "business_rule_refs": [ "RRX-FULFILLMENT-004" ], "technical_contract_ref": "spec/technical.md#5-2-pharmacy-queue", "evidence_refs": [ "spec/as-built.md#internal-fulfillment-network (historical map assumption)" ], "failure_owner": "Operations Platform owner", "timeout_retry": "Retry only under a stable idempotency key; expose terminal or conflicting state to the failure owner.", "recurring": false, "visible_by_default": false, "geometry": { "d": "M 1307,476 V 512", "label_x": 1315, "label_y": 494 } }, { "id": "historical-reminder-booking", "source": "meeting-reminders", "target": "appointment-setting", "relation": "triggers", "label": "reminder-creates-booking assumption", "bundle_id": null, "trigger": "Appointment Reminders reaches the governed handoff condition.", "payload": "reminder-creates-booking assumption contract payload with stable source identifiers and attributable timestamps.", "pass_condition": "The source contract is valid, authorized, attributable, and not already completed.", "criticality": "important", "execution": "deterministic", "synchrony": "asynchronous", "delivery_state": "legacy", "lifecycle": "historical", "evidence_state": "carried-forward", "business_rule_refs": [ "RRX-SCHEDULING-013" ], "technical_contract_ref": "spec/technical.md#2-4-appointment-reminders", "evidence_refs": [ "spec/as-built.md#meeting-reminders (historical map assumption)" ], "failure_owner": "Clinical Product owner", "timeout_retry": "Retry only under a stable idempotency key; expose terminal or conflicting state to the failure owner.", "recurring": false, "visible_by_default": false, "geometry": { "d": "M 580,692 V 608 Q 580,600 588,600 H 897 Q 905,600 905,592 V 476", "label_x": 740, "label_y": 592 } }, { "id": "edge-target-onboarding-to-intake-one", "source": "onboarding-agent", "target": "signup-intake", "relation": "transfers", "label": "merge state plus goal-or-medication handoff", "bundle_id": null, "trigger": "The target service_state AND (patient_goal OR desired_medication) predicate passes.", "payload": "Versioned partial onboarding JSONB, capture status by field, and missing_for_later manifest.", "pass_condition": "service_state is present and either patient_goal or desired_medication is present.", "criticality": "hard", "execution": "agent", "synchrony": "asynchronous", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-ONBOARDING-007", "RRX-ONBOARDING-008" ], "technical_contract_ref": "spec/technical.md#1-3-intake-1-basics", "evidence_refs": [ "spec/as-built.md#signup-intake", "spec/business.md#signup-intake" ], "failure_owner": "Onboarding Engineering", "timeout_retry": "Retry optimistic merge against the latest version; never overwrite a newer answer.", "recurring": false, "visible_by_default": false }, { "id": "edge-router-to-retention", "source": "agent-router", "target": "retention-agent", "relation": "routes", "label": "route explicit cancellation turn", "bundle_id": null, "trigger": "The focused route inventory selects retention-agent after Rails guards pass.", "payload": "Authorized focused-turn context for retention-agent.", "pass_condition": "The retention-agent agent is approved, active, and owns this intent.", "criticality": "important", "execution": "deterministic", "synchrony": "asynchronous", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-AGENTS-014", "RRX-AGENTS-016" ], "technical_contract_ref": "spec/technical.md#9-2-patient-support", "evidence_refs": [ "spec/as-built.md#retention-agent" ], "failure_owner": "Patient Operations", "timeout_retry": "Escalate unknown, clinical, or failed actions to a human queue.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 736,744 V 808 Q 736,816 728,816 H 636 Q 628,816 628,824 V 880", "label_x": 674, "label_y": 808 } }, { "id": "edge-router-to-founder", "source": "agent-router", "target": "founder-mode", "relation": "routes", "label": "route approved founder-mode turn", "bundle_id": null, "trigger": "The focused route inventory selects founder-mode after Rails guards pass.", "payload": "Authorized focused-turn context for founder-mode.", "pass_condition": "The founder-mode agent is approved, active, and owns this intent.", "criticality": "important", "execution": "deterministic", "synchrony": "asynchronous", "delivery_state": "planned", "lifecycle": "target", "evidence_state": "not-built", "business_rule_refs": [ "RRX-AGENTS-014", "RRX-AGENTS-016" ], "technical_contract_ref": "spec/technical.md#9-2-patient-support", "evidence_refs": [ "spec/as-built.md#founder-mode" ], "failure_owner": "Patient Operations", "timeout_retry": "Escalate unknown, clinical, or failed actions to a human queue.", "recurring": false, "visible_by_default": true, "geometry": { "d": "M 824,744 V 808 Q 824,816 832,816 H 940 Q 948,816 948,824 V 880", "label_x": 884, "label_y": 808 } }, { "id": "historical-note-ehr-cleanup", "source": "charting-ehr", "target": "ehr-schema-cleanup", "relation": "triggers", "label": "schema cleanup as a downstream chart step", "bundle_id": null, "trigger": "The prior hand-drawn map placed schema cleanup after the clinical note.", "payload": "No runtime payload; retained only as contradicted map evidence.", "pass_condition": "Historical only; the corrected graph renders EHR schema cleanup as governance over the note.", "criticality": "advisory", "execution": "human", "synchrony": "asynchronous", "delivery_state": "legacy", "lifecycle": "historical", "evidence_state": "carried-forward", "business_rule_refs": [ "RRX-EHR-001" ], "technical_contract_ref": "spec/technical.md#3-1-charting-ehr", "evidence_refs": [ "spec/as-built.md#charting-ehr (historical map assumption)" ], "failure_owner": "Clinical Product", "timeout_retry": "No retry; this contradicted connector is retained only for Delta evidence.", "recurring": false, "visible_by_default": false, "geometry": { "d": "M 578,188 V 244 a 8,8 0 0,1 0,16", "label_x": 586, "label_y": 220 } } ], "workflows": [ { "id": "sg-01", "title": "Messaging and onboarding spine", "forms": [ "sequence", "state-machine", "data-flow" ], "description": "Linq ingress, ordered Rails guards, focused-agent routing, progressive JSONB capture, current-versus-target handoff thresholds, secure continuation, and later missing-field intake.", "actors": [ "Patient", "Linq", "Rails", "Agent Router", "Onboarding Agent", "Conversion Agent", "Operations" ], "steps": [ { "id": "inbound", "label": "Inbound Linq event", "kind": "start", "actor": "Patient", "reality": "current", "reads": [], "writes": [ "Inbound Linq event state" ], "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "safety-guards", "label": "Dedupe, opt-out, emergency, and takeover guards", "kind": "decision", "actor": "Rails", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "Dedupe, opt-out, emergency, and takeover guards decision" ], "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "human-hold", "label": "Governed human hold", "kind": "human", "actor": "Operations", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "Governed human hold state" ], "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "route-turn", "label": "Focused turn routing", "kind": "automation", "actor": "Agent Router", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "Focused turn routing state" ], "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "agent-turn", "label": "Onboarding agent turn", "kind": "automation", "actor": "Onboarding Agent", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "Onboarding agent turn state" ], "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "field-capture", "label": "One-question progressive field capture", "kind": "state", "actor": "Onboarding Agent", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "One-question progressive field capture state" ], "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "partial-jsonb", "label": "Versioned partial onboarding JSONB", "kind": "record", "actor": "Rails", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "Versioned partial onboarding JSONB state" ], "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "current-floor", "label": "Current clinical completion floor", "kind": "decision", "actor": "Rails", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "Current clinical completion floor decision" ], "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "target-floor", "label": "State plus goal-or-medication target floor", "kind": "decision", "actor": "Rails", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "State plus goal-or-medication target floor decision" ], "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "chat-id-offer", "label": "Optional chat ID offer", "kind": "state", "actor": "Onboarding Agent", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Optional chat ID offer state" ], "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "id-deferred", "label": "Warm ID deferral without repeat pressure", "kind": "state", "actor": "Onboarding Agent", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Warm ID deferral without repeat pressure state" ], "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "missing-manifest", "label": "Explicit missing-for-later manifest", "kind": "record", "actor": "Rails", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Explicit missing-for-later manifest state" ], "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "secure-handoff", "label": "Idempotent secure handoff", "kind": "automation", "actor": "Rails", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Idempotent secure handoff state" ], "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "secure-link", "label": "Expiring secure continuation link", "kind": "record", "actor": "Rails", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "Expiring secure continuation link state" ], "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "delivery-authorization", "label": "Outbound SendGuard authorization", "kind": "decision", "actor": "Rails", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "Outbound SendGuard authorization decision" ], "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "agent-reply", "label": "Guarded Linq delivery", "kind": "external", "actor": "Linq", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "Guarded Linq delivery state" ], "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "later-intake", "label": "Known-fact prefill and missing-only intake", "kind": "end", "actor": "Patient", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Known-fact prefill and missing-only intake state" ], "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "stalled-stage", "label": "Stalled-stage detection", "kind": "decision", "actor": "Rails", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Stalled-stage detection decision" ], "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "governed-reengage", "label": "Consent-aware conversion re-engagement", "kind": "automation", "actor": "Conversion Agent", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Consent-aware conversion re-engagement state" ], "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "human-takeover", "label": "Human messaging ownership", "kind": "human", "actor": "Operations", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "Human messaging ownership state" ], "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "failure-alert", "label": "Timeout or hard-failure alert without invented reply", "kind": "end", "actor": "Operations", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "Timeout or hard-failure alert without invented reply state" ], "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] } ], "transitions": [ { "id": "sg-01-p1-t1", "from": "inbound", "to": "safety-guards", "label": "evaluate dedupe, opt-out, emergency, and takeover guards", "condition": "Dedupe, opt-out, emergency, and takeover guards has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "current", "delivery_state": "partial", "retry": "Re-evaluate only after a named input changes; Operations owns unresolved or conflicting eligibility.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "sg-01-pass", "from": "safety-guards", "to": "route-turn", "label": "pass", "condition": "All ingress guards pass.", "reality": "current", "delivery_state": "live", "retry": "Replay-safe event retry.", "human_owner": "Messaging Operations", "evidence_refs": [ "spec/as-built.md#iphone-link" ] }, { "id": "sg-01-p1-t3", "from": "route-turn", "to": "agent-turn", "label": "run onboarding agent turn", "condition": "Focused turn routing satisfies the deterministic preconditions declared for Onboarding agent turn.", "reality": "current", "delivery_state": "partial", "retry": "Retry Onboarding agent turn under the same workflow identity and dedupe key; Operations owns terminal failure.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "sg-01-p1-t4", "from": "agent-turn", "to": "field-capture", "label": "enter one-question progressive field capture", "condition": "Onboarding agent turn supplies the named facts required to enter One-question progressive field capture.", "reality": "current", "delivery_state": "partial", "retry": "Resume the same attributable workflow state; Operations owns conflicting or stalled progress.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "sg-01-p1-t5", "from": "field-capture", "to": "partial-jsonb", "label": "write versioned partial onboarding jsonb", "condition": "One-question progressive field capture has the complete attributable payload required for the durable Versioned partial onboarding JSONB write.", "reality": "current", "delivery_state": "partial", "retry": "Repeat the durable write only with its original idempotency key; Operations owns conflicting state.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "sg-01-p1-t6", "from": "partial-jsonb", "to": "current-floor", "label": "evaluate current clinical completion floor", "condition": "Current clinical completion floor has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "current", "delivery_state": "partial", "retry": "Re-evaluate only after a named input changes; Operations owns unresolved or conflicting eligibility.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "sg-01-p1-t7", "from": "current-floor", "to": "chat-id-offer", "label": "enter optional chat id offer", "condition": "Current clinical completion floor supplies the named facts required to enter Optional chat ID offer.", "reality": "current", "delivery_state": "partial", "retry": "Resume the same attributable workflow state; Operations owns conflicting or stalled progress.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "sg-01-p1-t8", "from": "chat-id-offer", "to": "secure-handoff", "label": "run idempotent secure handoff", "condition": "Optional chat ID offer satisfies the deterministic preconditions declared for Idempotent secure handoff.", "reality": "both", "delivery_state": "partial", "retry": "Retry Idempotent secure handoff under the same workflow identity and dedupe key; Operations owns terminal failure.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "sg-01-p1-t9", "from": "secure-handoff", "to": "secure-link", "label": "write expiring secure continuation link", "condition": "Idempotent secure handoff has the complete attributable payload required for the durable Expiring secure continuation link write.", "reality": "current", "delivery_state": "partial", "retry": "Repeat the durable write only with its original idempotency key; Operations owns conflicting state.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "sg-01-p1-t10", "from": "secure-link", "to": "delivery-authorization", "label": "evaluate outbound sendguard authorization", "condition": "Outbound SendGuard authorization has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "current", "delivery_state": "partial", "retry": "Re-evaluate only after a named input changes; Operations owns unresolved or conflicting eligibility.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "sg-01-p1-t11", "from": "delivery-authorization", "to": "agent-reply", "label": "submit guarded linq delivery", "condition": "Outbound SendGuard authorization supplies the authenticated external contract and stable source identifiers required by Guarded Linq delivery.", "reality": "current", "delivery_state": "partial", "retry": "Retry transport under the same stable external ID; Operations owns rejection, timeout, and reconciliation.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "sg-01-p2-t6", "from": "partial-jsonb", "to": "target-floor", "label": "evaluate state plus goal-or-medication target floor", "condition": "Target-only and not deployed: State plus goal-or-medication target floor has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Re-evaluate only after a named input changes; Operations owns unresolved or conflicting eligibility.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "sg-01-p2-t7", "from": "target-floor", "to": "chat-id-offer", "label": "enter optional chat id offer", "condition": "Target-only and not deployed: State plus goal-or-medication target floor supplies the named facts required to enter Optional chat ID offer.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Resume the same attributable workflow state; Operations owns conflicting or stalled progress.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "sg-01-p2-t8", "from": "chat-id-offer", "to": "missing-manifest", "label": "write explicit missing-for-later manifest", "condition": "Target-only and not deployed: Optional chat ID offer has the complete attributable payload required for the durable Explicit missing-for-later manifest write.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Repeat the durable write only with its original idempotency key; Operations owns conflicting state.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "sg-01-p2-t9", "from": "missing-manifest", "to": "secure-handoff", "label": "run idempotent secure handoff", "condition": "Target-only and not deployed: Explicit missing-for-later manifest satisfies the deterministic preconditions declared for Idempotent secure handoff.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Retry Idempotent secure handoff under the same workflow identity and dedupe key; Operations owns terminal failure.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "sg-01-p2-t13", "from": "agent-reply", "to": "later-intake", "label": "complete known-fact prefill and missing-only intake", "condition": "Target-only and not deployed: All named predecessor states required by Known-fact prefill and missing-only intake are satisfied or explicitly resolved.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Reopen only from the attributable unresolved predecessor; Operations owns terminal closure.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "sg-01-defer-id", "from": "chat-id-offer", "to": "id-deferred", "label": "declined or unavailable", "condition": "The patient does not provide ID in chat.", "reality": "both", "delivery_state": "partial", "retry": "Do not re-ask in chat; continue at the secure gate.", "human_owner": "Onboarding Operations", "evidence_refs": [ "spec/as-built.md#id-verification" ] }, { "id": "sg-01-p3-t2", "from": "id-deferred", "to": "secure-handoff", "label": "run idempotent secure handoff", "condition": "Warm ID deferral without repeat pressure satisfies the deterministic preconditions declared for Idempotent secure handoff.", "reality": "both", "delivery_state": "partial", "retry": "Retry Idempotent secure handoff under the same workflow identity and dedupe key; Operations owns terminal failure.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "sg-01-stall", "from": "stalled-stage", "to": "governed-reengage", "label": "eligible to re-engage", "condition": "Consent and safety state permit outreach.", "reality": "target", "delivery_state": "planned", "retry": "Dedupe by patient and stalled stage.", "human_owner": "Growth Operations", "evidence_refs": [ "spec/business.md#reengage-close-agent" ] }, { "id": "sg-01-p4-t2", "from": "governed-reengage", "to": "delivery-authorization", "label": "evaluate outbound sendguard authorization", "condition": "Target-only and not deployed: Outbound SendGuard authorization has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Re-evaluate only after a named input changes; Operations owns unresolved or conflicting eligibility.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "sg-01-p5-t1", "from": "safety-guards", "to": "human-takeover", "label": "Operations performs human messaging ownership", "condition": "Dedupe, opt-out, emergency, and takeover guards presents attributable work to Operations; no automatic approval or silent substitution is permitted.", "reality": "current", "delivery_state": "partial", "retry": "Do not auto-approve. Return the same attributable record to Operations with the unresolved reason preserved.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "sg-01-p6-t1", "from": "current-floor", "to": "field-capture", "label": "enter one-question progressive field capture", "condition": "Current clinical completion floor supplies the named facts required to enter One-question progressive field capture.", "reality": "current", "delivery_state": "partial", "retry": "Resume the same attributable workflow state; Operations owns conflicting or stalled progress.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "sg-01-p7-t1", "from": "target-floor", "to": "field-capture", "label": "enter one-question progressive field capture", "condition": "Target-only and not deployed: State plus goal-or-medication target floor supplies the named facts required to enter One-question progressive field capture.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Resume the same attributable workflow state; Operations owns conflicting or stalled progress.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "sg-01-p8-t1", "from": "secure-link", "to": "later-intake", "label": "complete known-fact prefill and missing-only intake", "condition": "Target-only and not deployed: All named predecessor states required by Known-fact prefill and missing-only intake are satisfied or explicitly resolved.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Reopen only from the attributable unresolved predecessor; Operations owns terminal closure.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "sg-01-p9-t1", "from": "secure-link", "to": "stalled-stage", "label": "evaluate stalled-stage detection", "condition": "Target-only and not deployed: Stalled-stage detection has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Re-evaluate only after a named input changes; Operations owns unresolved or conflicting eligibility.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#iphone-link", "spec/as-built.md#onboarding-agent", "spec/as-built.md#signup-intake" ] }, { "id": "sg-01-held", "from": "safety-guards", "to": "human-hold", "label": "hold", "condition": "Emergency or human takeover is active.", "reality": "current", "delivery_state": "live", "retry": "Human release only.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#iphone-link" ] }, { "id": "sg-01-fail", "from": "agent-turn", "to": "failure-alert", "label": "timeout or hard failure", "condition": "The Flue turn does not return a valid result.", "reality": "current", "delivery_state": "live", "retry": "No patient-facing fallback today; alert and inspect.", "human_owner": "AI Platform", "evidence_refs": [ "spec/as-built.md#onboarding-agent" ] } ] }, { "id": "sg-02", "title": "Secure completion gates", "forms": [ "gate-graph", "decision-tree" ], "description": "The current serial ID, serviceability, agreements, payment, and care-path gates with explicit recovery exits.", "actors": [ "Patient", "Rails", "Identity Service", "Stripe", "Scheduling", "Operations" ], "steps": [ { "id": "secure-entry", "label": "Secure link entry", "kind": "start", "actor": "Patient", "reality": "current", "reads": [], "writes": [ "Secure link entry state" ], "evidence_refs": [ "spec/as-built.md#id-verification", "spec/as-built.md#sign-docs", "spec/as-built.md#membership-subscription" ] }, { "id": "identity-gate", "label": "Front-of-ID verification gate", "kind": "decision", "actor": "Identity Service", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "Front-of-ID verification gate decision" ], "evidence_refs": [ "spec/as-built.md#id-verification", "spec/as-built.md#sign-docs", "spec/as-built.md#membership-subscription" ] }, { "id": "serviceability", "label": "Address and serviceability gate", "kind": "decision", "actor": "Rails", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "Address and serviceability gate decision" ], "evidence_refs": [ "spec/as-built.md#id-verification", "spec/as-built.md#sign-docs", "spec/as-built.md#membership-subscription" ] }, { "id": "packet-validation", "label": "Agreement packet validation", "kind": "automation", "actor": "Rails", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "Agreement packet validation state" ], "evidence_refs": [ "spec/as-built.md#id-verification", "spec/as-built.md#sign-docs", "spec/as-built.md#membership-subscription" ] }, { "id": "agreement-gate", "label": "All-or-nothing signature gate", "kind": "decision", "actor": "Patient", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "All-or-nothing signature gate decision" ], "evidence_refs": [ "spec/as-built.md#id-verification", "spec/as-built.md#sign-docs", "spec/as-built.md#membership-subscription" ] }, { "id": "sealed-pdf", "label": "Sealed agreement PDF", "kind": "record", "actor": "Rails", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "Sealed agreement PDF state" ], "evidence_refs": [ "spec/as-built.md#id-verification", "spec/as-built.md#sign-docs", "spec/as-built.md#membership-subscription" ] }, { "id": "signature-complete", "label": "Attributable signature completion", "kind": "record", "actor": "Rails", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "Attributable signature completion state" ], "evidence_refs": [ "spec/as-built.md#id-verification", "spec/as-built.md#sign-docs", "spec/as-built.md#membership-subscription" ] }, { "id": "payment-gate", "label": "Membership payment gate", "kind": "decision", "actor": "Stripe", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "Membership payment gate decision" ], "evidence_refs": [ "spec/as-built.md#id-verification", "spec/as-built.md#sign-docs", "spec/as-built.md#membership-subscription" ] }, { "id": "care-choice", "label": "Video or asynchronous review choice", "kind": "decision", "actor": "Patient", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "Video or asynchronous review choice decision" ], "evidence_refs": [ "spec/as-built.md#id-verification", "spec/as-built.md#sign-docs", "spec/as-built.md#membership-subscription" ] }, { "id": "video-booking", "label": "Provider and slot selection", "kind": "state", "actor": "Scheduling", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "Provider and slot selection state" ], "evidence_refs": [ "spec/as-built.md#id-verification", "spec/as-built.md#sign-docs", "spec/as-built.md#membership-subscription" ] }, { "id": "async-review", "label": "Governed asynchronous intake", "kind": "state", "actor": "Rails", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "Governed asynchronous intake state" ], "evidence_refs": [ "spec/as-built.md#id-verification", "spec/as-built.md#sign-docs", "spec/as-built.md#membership-subscription" ] }, { "id": "recovery-exit", "label": "Recoverable blocked-stage exit", "kind": "human", "actor": "Operations", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Recoverable blocked-stage exit state" ], "evidence_refs": [ "spec/as-built.md#id-verification", "spec/as-built.md#sign-docs", "spec/as-built.md#membership-subscription" ] }, { "id": "completion", "label": "Secure completion finished", "kind": "end", "actor": "Rails", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "Secure completion finished state" ], "evidence_refs": [ "spec/as-built.md#id-verification", "spec/as-built.md#sign-docs", "spec/as-built.md#membership-subscription" ] } ], "transitions": [ { "id": "sg-02-p1-t1", "from": "secure-entry", "to": "identity-gate", "label": "evaluate front-of-id verification gate", "condition": "Front-of-ID verification gate has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "current", "delivery_state": "partial", "retry": "Re-evaluate only after a named input changes; Operations owns unresolved or conflicting eligibility.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#id-verification", "spec/as-built.md#sign-docs", "spec/as-built.md#membership-subscription" ] }, { "id": "sg-02-p1-t2", "from": "identity-gate", "to": "serviceability", "label": "evaluate address and serviceability gate", "condition": "Address and serviceability gate has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "current", "delivery_state": "partial", "retry": "Re-evaluate only after a named input changes; Operations owns unresolved or conflicting eligibility.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#id-verification", "spec/as-built.md#sign-docs", "spec/as-built.md#membership-subscription" ] }, { "id": "sg-02-p1-t3", "from": "serviceability", "to": "packet-validation", "label": "run agreement packet validation", "condition": "Address and serviceability gate satisfies the deterministic preconditions declared for Agreement packet validation.", "reality": "current", "delivery_state": "partial", "retry": "Retry Agreement packet validation under the same workflow identity and dedupe key; Operations owns terminal failure.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#id-verification", "spec/as-built.md#sign-docs", "spec/as-built.md#membership-subscription" ] }, { "id": "sg-02-p1-t4", "from": "packet-validation", "to": "agreement-gate", "label": "evaluate all-or-nothing signature gate", "condition": "All-or-nothing signature gate has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "current", "delivery_state": "partial", "retry": "Re-evaluate only after a named input changes; Operations owns unresolved or conflicting eligibility.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#id-verification", "spec/as-built.md#sign-docs", "spec/as-built.md#membership-subscription" ] }, { "id": "sg-02-p1-t5", "from": "agreement-gate", "to": "sealed-pdf", "label": "write sealed agreement pdf", "condition": "All-or-nothing signature gate has the complete attributable payload required for the durable Sealed agreement PDF write.", "reality": "current", "delivery_state": "partial", "retry": "Repeat the durable write only with its original idempotency key; Operations owns conflicting state.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#id-verification", "spec/as-built.md#sign-docs", "spec/as-built.md#membership-subscription" ] }, { "id": "sg-02-p1-t6", "from": "sealed-pdf", "to": "signature-complete", "label": "write attributable signature completion", "condition": "Sealed agreement PDF has the complete attributable payload required for the durable Attributable signature completion write.", "reality": "current", "delivery_state": "partial", "retry": "Repeat the durable write only with its original idempotency key; Operations owns conflicting state.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#id-verification", "spec/as-built.md#sign-docs", "spec/as-built.md#membership-subscription" ] }, { "id": "sg-02-p1-t7", "from": "signature-complete", "to": "payment-gate", "label": "evaluate membership payment gate", "condition": "Membership payment gate has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "current", "delivery_state": "partial", "retry": "Re-evaluate only after a named input changes; Operations owns unresolved or conflicting eligibility.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#id-verification", "spec/as-built.md#sign-docs", "spec/as-built.md#membership-subscription" ] }, { "id": "sg-02-p1-t8", "from": "payment-gate", "to": "care-choice", "label": "evaluate video or asynchronous review choice", "condition": "Video or asynchronous review choice has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "current", "delivery_state": "partial", "retry": "Re-evaluate only after a named input changes; Operations owns unresolved or conflicting eligibility.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#id-verification", "spec/as-built.md#sign-docs", "spec/as-built.md#membership-subscription" ] }, { "id": "sg-02-video", "from": "care-choice", "to": "video-booking", "label": "video", "condition": "Patient chooses a synchronous visit.", "reality": "current", "delivery_state": "live", "retry": "Return to real availability on slot conflict.", "human_owner": "Scheduling Operations", "evidence_refs": [ "spec/as-built.md#appointment-setting" ] }, { "id": "sg-02-p1-t10", "from": "video-booking", "to": "completion", "label": "complete secure completion finished", "condition": "All named predecessor states required by Secure completion finished are satisfied or explicitly resolved.", "reality": "current", "delivery_state": "partial", "retry": "Reopen only from the attributable unresolved predecessor; Operations owns terminal closure.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#id-verification", "spec/as-built.md#sign-docs", "spec/as-built.md#membership-subscription" ] }, { "id": "sg-02-async", "from": "care-choice", "to": "async-review", "label": "async", "condition": "Patient chooses governed asynchronous review.", "reality": "current", "delivery_state": "partial", "retry": "Resume at the first missing governed question.", "human_owner": "Clinical Operations", "evidence_refs": [ "spec/as-built.md#pre-doctor-intake" ] }, { "id": "sg-02-p2-t2", "from": "async-review", "to": "completion", "label": "complete secure completion finished", "condition": "All named predecessor states required by Secure completion finished are satisfied or explicitly resolved.", "reality": "current", "delivery_state": "partial", "retry": "Reopen only from the attributable unresolved predecessor; Operations owns terminal closure.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#id-verification", "spec/as-built.md#sign-docs", "spec/as-built.md#membership-subscription" ] }, { "id": "sg-02-p3-t1", "from": "recovery-exit", "to": "identity-gate", "label": "evaluate front-of-id verification gate", "condition": "Front-of-ID verification gate has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "current", "delivery_state": "partial", "retry": "Re-evaluate only after a named input changes; Operations owns unresolved or conflicting eligibility.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#id-verification", "spec/as-built.md#sign-docs", "spec/as-built.md#membership-subscription" ] }, { "id": "sg-02-p4-t1", "from": "recovery-exit", "to": "serviceability", "label": "evaluate address and serviceability gate", "condition": "Address and serviceability gate has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "current", "delivery_state": "partial", "retry": "Re-evaluate only after a named input changes; Operations owns unresolved or conflicting eligibility.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#id-verification", "spec/as-built.md#sign-docs", "spec/as-built.md#membership-subscription" ] }, { "id": "sg-02-p5-t1", "from": "recovery-exit", "to": "packet-validation", "label": "run agreement packet validation", "condition": "Recoverable blocked-stage exit satisfies the deterministic preconditions declared for Agreement packet validation.", "reality": "current", "delivery_state": "partial", "retry": "Retry Agreement packet validation under the same workflow identity and dedupe key; Operations owns terminal failure.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#id-verification", "spec/as-built.md#sign-docs", "spec/as-built.md#membership-subscription" ] }, { "id": "sg-02-p6-t1", "from": "recovery-exit", "to": "agreement-gate", "label": "evaluate all-or-nothing signature gate", "condition": "All-or-nothing signature gate has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "current", "delivery_state": "partial", "retry": "Re-evaluate only after a named input changes; Operations owns unresolved or conflicting eligibility.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#id-verification", "spec/as-built.md#sign-docs", "spec/as-built.md#membership-subscription" ] }, { "id": "sg-02-p7-t1", "from": "recovery-exit", "to": "payment-gate", "label": "evaluate membership payment gate", "condition": "Membership payment gate has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "current", "delivery_state": "partial", "retry": "Re-evaluate only after a named input changes; Operations owns unresolved or conflicting eligibility.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#id-verification", "spec/as-built.md#sign-docs", "spec/as-built.md#membership-subscription" ] }, { "id": "sg-02-p8-t1", "from": "recovery-exit", "to": "care-choice", "label": "evaluate video or asynchronous review choice", "condition": "Video or asynchronous review choice has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "current", "delivery_state": "partial", "retry": "Re-evaluate only after a named input changes; Operations owns unresolved or conflicting eligibility.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#id-verification", "spec/as-built.md#sign-docs", "spec/as-built.md#membership-subscription" ] }, { "id": "sg-02-id-fail", "from": "identity-gate", "to": "recovery-exit", "label": "unverified", "condition": "OCR, match, or document checks fail.", "reality": "current", "delivery_state": "live", "retry": "Patient may replace the front image; repeated failure enters Ops.", "human_owner": "Onboarding Operations", "evidence_refs": [ "spec/as-built.md#id-verification" ] }, { "id": "sg-02-pay-fail", "from": "payment-gate", "to": "recovery-exit", "label": "payment incomplete", "condition": "No authoritative successful Stripe event is reconciled.", "reality": "current", "delivery_state": "live", "retry": "Resume the same payment stage; do not duplicate membership.", "human_owner": "Billing Operations", "evidence_refs": [ "spec/as-built.md#membership-subscription" ] } ] }, { "id": "sg-03", "title": "Scheduling and pre-visit", "forms": [ "swimlane", "sequence" ], "description": "Eligible roster, explainable selection, real availability, slot locking, booking, intake, reminders, Pre-Brief, and appointment readiness.", "actors": [ "Patient", "Provider", "Scheduling", "Rails", "Operations" ], "steps": [ { "id": "eligible-roster", "label": "Complete eligible provider roster", "kind": "record", "actor": "Scheduling", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Complete eligible provider roster state" ], "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "score-explain", "label": "Explainable provider scoring", "kind": "automation", "actor": "Scheduling", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Explainable provider scoring state" ], "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "provider-choice", "label": "Patient provider choice", "kind": "human", "actor": "Patient", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Patient provider choice state" ], "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "real-availability", "label": "Live provider availability", "kind": "external", "actor": "Scheduling", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Live provider availability state" ], "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "slot-lock", "label": "Concurrency-safe slot lock", "kind": "decision", "actor": "Scheduling", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Concurrency-safe slot lock decision" ], "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "booking-commit", "label": "Appointment booking commit", "kind": "record", "actor": "Rails", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Appointment booking commit state" ], "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "intake-activation", "label": "Appointment-scoped intake activation", "kind": "automation", "actor": "Rails", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Appointment-scoped intake activation state" ], "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "known-fact-prefill", "label": "Known-fact prefill with provenance", "kind": "automation", "actor": "Rails", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Known-fact prefill with provenance state" ], "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "missing-questions", "label": "Missing governed questions", "kind": "state", "actor": "Patient", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Missing governed questions state" ], "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "source-fan-in", "label": "Chart, history, labs, and device source fan-in", "kind": "record", "actor": "Rails", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Chart, history, labs, and device source fan-in state" ], "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "missing-labels", "label": "Explicit missing-data labels", "kind": "record", "actor": "Rails", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Explicit missing-data labels state" ], "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "ready-packet", "label": "Authenticated Pre-Brief packet", "kind": "record", "actor": "Rails", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Authenticated Pre-Brief packet state" ], "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "reminder-schedule", "label": "Booking-relative reminder schedule", "kind": "automation", "actor": "Rails", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Booking-relative reminder schedule state" ], "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "live-recheck", "label": "Live appointment and preference recheck", "kind": "decision", "actor": "Rails", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Live appointment and preference recheck decision" ], "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "dedupe-send", "label": "Idempotent reminder delivery", "kind": "external", "actor": "Rails", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Idempotent reminder delivery state" ], "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "skip-or-fail", "label": "Skipped or failed reminder evidence", "kind": "record", "actor": "Rails", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Skipped or failed reminder evidence state" ], "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "ops-queue", "label": "Incomplete-intake Ops queue", "kind": "human", "actor": "Operations", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Incomplete-intake Ops queue state" ], "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "cancel-rebook", "label": "Attributable cancel or rebook", "kind": "state", "actor": "Scheduling", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Attributable cancel or rebook state" ], "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "appointment-ready", "label": "Appointment ready", "kind": "end", "actor": "Provider", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Appointment ready state" ], "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] } ], "transitions": [ { "id": "sg-03-p1-t1", "from": "eligible-roster", "to": "score-explain", "label": "run explainable provider scoring", "condition": "Complete eligible provider roster satisfies the deterministic preconditions declared for Explainable provider scoring.", "reality": "both", "delivery_state": "partial", "retry": "Retry Explainable provider scoring under the same workflow identity and dedupe key; Provider owns terminal failure.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "sg-03-p1-t2", "from": "score-explain", "to": "provider-choice", "label": "Patient performs patient provider choice", "condition": "Explainable provider scoring presents attributable work to Patient; no automatic approval or silent substitution is permitted.", "reality": "both", "delivery_state": "partial", "retry": "Do not auto-approve. Return the same attributable record to Patient with the unresolved reason preserved.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "sg-03-p1-t3", "from": "provider-choice", "to": "real-availability", "label": "submit live provider availability", "condition": "Patient provider choice supplies the authenticated external contract and stable source identifiers required by Live provider availability.", "reality": "both", "delivery_state": "partial", "retry": "Retry transport under the same stable external ID; Provider owns rejection, timeout, and reconciliation.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "sg-03-p1-t4", "from": "real-availability", "to": "slot-lock", "label": "evaluate concurrency-safe slot lock", "condition": "Concurrency-safe slot lock has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "both", "delivery_state": "partial", "retry": "Re-evaluate only after a named input changes; Provider owns unresolved or conflicting eligibility.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "sg-03-p1-t5", "from": "slot-lock", "to": "booking-commit", "label": "write appointment booking commit", "condition": "Concurrency-safe slot lock has the complete attributable payload required for the durable Appointment booking commit write.", "reality": "both", "delivery_state": "partial", "retry": "Repeat the durable write only with its original idempotency key; Provider owns conflicting state.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "sg-03-p1-t6", "from": "booking-commit", "to": "appointment-ready", "label": "complete appointment ready", "condition": "All named predecessor states required by Appointment ready are satisfied or explicitly resolved.", "reality": "both", "delivery_state": "partial", "retry": "Reopen only from the attributable unresolved predecessor; Provider owns terminal closure.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "sg-03-p2-t1", "from": "booking-commit", "to": "intake-activation", "label": "run appointment-scoped intake activation", "condition": "Appointment booking commit satisfies the deterministic preconditions declared for Appointment-scoped intake activation.", "reality": "both", "delivery_state": "partial", "retry": "Retry Appointment-scoped intake activation under the same workflow identity and dedupe key; Provider owns terminal failure.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "sg-03-p2-t2", "from": "intake-activation", "to": "known-fact-prefill", "label": "run known-fact prefill with provenance", "condition": "Appointment-scoped intake activation satisfies the deterministic preconditions declared for Known-fact prefill with provenance.", "reality": "both", "delivery_state": "partial", "retry": "Retry Known-fact prefill with provenance under the same workflow identity and dedupe key; Provider owns terminal failure.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "sg-03-p2-t3", "from": "known-fact-prefill", "to": "missing-questions", "label": "enter missing governed questions", "condition": "Known-fact prefill with provenance supplies the named facts required to enter Missing governed questions.", "reality": "both", "delivery_state": "partial", "retry": "Resume the same attributable workflow state; Provider owns conflicting or stalled progress.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "sg-03-p2-t4", "from": "missing-questions", "to": "source-fan-in", "label": "write chart, history, labs, and device source fan-in", "condition": "Missing governed questions has the complete attributable payload required for the durable Chart, history, labs, and device source fan-in write.", "reality": "both", "delivery_state": "partial", "retry": "Repeat the durable write only with its original idempotency key; Provider owns conflicting state.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "sg-03-p2-t5", "from": "source-fan-in", "to": "missing-labels", "label": "write explicit missing-data labels", "condition": "Chart, history, labs, and device source fan-in has the complete attributable payload required for the durable Explicit missing-data labels write.", "reality": "both", "delivery_state": "partial", "retry": "Repeat the durable write only with its original idempotency key; Provider owns conflicting state.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "sg-03-p2-t6", "from": "missing-labels", "to": "ready-packet", "label": "write authenticated pre-brief packet", "condition": "Explicit missing-data labels has the complete attributable payload required for the durable Authenticated Pre-Brief packet write.", "reality": "both", "delivery_state": "partial", "retry": "Repeat the durable write only with its original idempotency key; Provider owns conflicting state.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "sg-03-p2-t7", "from": "ready-packet", "to": "appointment-ready", "label": "complete appointment ready", "condition": "All named predecessor states required by Appointment ready are satisfied or explicitly resolved.", "reality": "both", "delivery_state": "partial", "retry": "Reopen only from the attributable unresolved predecessor; Provider owns terminal closure.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "sg-03-p3-t1", "from": "booking-commit", "to": "reminder-schedule", "label": "run booking-relative reminder schedule", "condition": "Appointment booking commit satisfies the deterministic preconditions declared for Booking-relative reminder schedule.", "reality": "both", "delivery_state": "partial", "retry": "Retry Booking-relative reminder schedule under the same workflow identity and dedupe key; Provider owns terminal failure.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "sg-03-p3-t2", "from": "reminder-schedule", "to": "live-recheck", "label": "evaluate live appointment and preference recheck", "condition": "Live appointment and preference recheck has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "both", "delivery_state": "partial", "retry": "Re-evaluate only after a named input changes; Provider owns unresolved or conflicting eligibility.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "sg-03-p3-t3", "from": "live-recheck", "to": "dedupe-send", "label": "submit idempotent reminder delivery", "condition": "Live appointment and preference recheck supplies the authenticated external contract and stable source identifiers required by Idempotent reminder delivery.", "reality": "both", "delivery_state": "partial", "retry": "Retry transport under the same stable external ID; Provider owns rejection, timeout, and reconciliation.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "sg-03-p3-t4", "from": "dedupe-send", "to": "appointment-ready", "label": "complete appointment ready", "condition": "All named predecessor states required by Appointment ready are satisfied or explicitly resolved.", "reality": "both", "delivery_state": "partial", "retry": "Reopen only from the attributable unresolved predecessor; Provider owns terminal closure.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "sg-03-p4-t1", "from": "live-recheck", "to": "skip-or-fail", "label": "write skipped or failed reminder evidence", "condition": "Live appointment and preference recheck has the complete attributable payload required for the durable Skipped or failed reminder evidence write.", "reality": "both", "delivery_state": "partial", "retry": "Repeat the durable write only with its original idempotency key; Provider owns conflicting state.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "sg-03-p5-t1", "from": "missing-questions", "to": "ops-queue", "label": "Operations performs incomplete-intake ops queue", "condition": "Missing governed questions presents attributable work to Operations; no automatic approval or silent substitution is permitted.", "reality": "both", "delivery_state": "partial", "retry": "Do not auto-approve. Return the same attributable record to Operations with the unresolved reason preserved.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] }, { "id": "sg-03-p6-t1", "from": "booking-commit", "to": "cancel-rebook", "label": "enter attributable cancel or rebook", "condition": "Appointment booking commit supplies the named facts required to enter Attributable cancel or rebook.", "reality": "both", "delivery_state": "partial", "retry": "Resume the same attributable workflow state; Provider owns conflicting or stalled progress.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#doctor-picker", "spec/as-built.md#appointment-setting", "spec/as-built.md#pre-brief" ] } ] }, { "id": "sg-04", "title": "Meet artifacts to clinical note", "forms": [ "internal-pipeline", "sequence" ], "description": "Room authorization, consent, recording/transcript discovery, encounter creation, draft, clinician edit, signature, and immutable correction paths.", "actors": [ "Patient", "Provider", "Google Meet", "Rails", "EHR" ], "steps": [ { "id": "room-authorization", "label": "Appointment-room authorization", "kind": "decision", "actor": "Rails", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Appointment-room authorization decision" ], "evidence_refs": [ "spec/as-built.md#doctor-visit", "spec/as-built.md#charting-ehr" ] }, { "id": "consent-check", "label": "Recording consent check", "kind": "decision", "actor": "Provider", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Recording consent check decision" ], "evidence_refs": [ "spec/as-built.md#doctor-visit", "spec/as-built.md#charting-ehr" ] }, { "id": "meet-artifacts", "label": "Native recording and transcript artifacts", "kind": "external", "actor": "Google Meet", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Native recording and transcript artifacts state" ], "evidence_refs": [ "spec/as-built.md#doctor-visit", "spec/as-built.md#charting-ehr" ] }, { "id": "artifact-sweep", "label": "Idempotent artifact discovery sweep", "kind": "automation", "actor": "Rails", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Idempotent artifact discovery sweep state" ], "evidence_refs": [ "spec/as-built.md#doctor-visit", "spec/as-built.md#charting-ehr" ] }, { "id": "encounter-handoff", "label": "Appointment-bound EHR encounter", "kind": "record", "actor": "EHR", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Appointment-bound EHR encounter state" ], "evidence_refs": [ "spec/as-built.md#doctor-visit", "spec/as-built.md#charting-ehr" ] }, { "id": "draft-note", "label": "Attributable note draft", "kind": "automation", "actor": "EHR", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Attributable note draft state" ], "evidence_refs": [ "spec/as-built.md#doctor-visit", "spec/as-built.md#charting-ehr" ] }, { "id": "doctor-edit", "label": "Clinician review and edit", "kind": "human", "actor": "Provider", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Clinician review and edit state" ], "evidence_refs": [ "spec/as-built.md#doctor-visit", "spec/as-built.md#charting-ehr" ] }, { "id": "signed-note", "label": "Signed immutable clinical note", "kind": "record", "actor": "EHR", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Signed immutable clinical note state" ], "evidence_refs": [ "spec/as-built.md#doctor-visit", "spec/as-built.md#charting-ehr" ] }, { "id": "amendment", "label": "Addendum, amendment, or void", "kind": "human", "actor": "Provider", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Addendum, amendment, or void state" ], "evidence_refs": [ "spec/as-built.md#doctor-visit", "spec/as-built.md#charting-ehr" ] }, { "id": "complete", "label": "Clinical artifact pipeline complete", "kind": "end", "actor": "EHR", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Clinical artifact pipeline complete state" ], "evidence_refs": [ "spec/as-built.md#doctor-visit", "spec/as-built.md#charting-ehr" ] } ], "transitions": [ { "id": "sg-04-p1-t1", "from": "room-authorization", "to": "consent-check", "label": "evaluate recording consent check", "condition": "Recording consent check has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "both", "delivery_state": "partial", "retry": "Re-evaluate only after a named input changes; Provider owns unresolved or conflicting eligibility.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#doctor-visit", "spec/as-built.md#charting-ehr" ] }, { "id": "sg-04-consent-granted", "from": "consent-check", "to": "meet-artifacts", "label": "recording consent granted", "condition": "The authorized patient and provider granted the required recording and transcription consent for this appointment.", "reality": "both", "delivery_state": "partial", "retry": "Do not infer consent; Provider resolves an incomplete consent record before artifact capture.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#doctor-visit" ] }, { "id": "sg-04-p1-t3", "from": "meet-artifacts", "to": "artifact-sweep", "label": "run idempotent artifact discovery sweep", "condition": "Native recording and transcript artifacts satisfies the deterministic preconditions declared for Idempotent artifact discovery sweep.", "reality": "both", "delivery_state": "partial", "retry": "Retry Idempotent artifact discovery sweep under the same workflow identity and dedupe key; Provider owns terminal failure.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#doctor-visit", "spec/as-built.md#charting-ehr" ] }, { "id": "sg-04-p1-t4", "from": "artifact-sweep", "to": "encounter-handoff", "label": "write appointment-bound ehr encounter", "condition": "Idempotent artifact discovery sweep has the complete attributable payload required for the durable Appointment-bound EHR encounter write.", "reality": "both", "delivery_state": "partial", "retry": "Repeat the durable write only with its original idempotency key; Provider owns conflicting state.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#doctor-visit", "spec/as-built.md#charting-ehr" ] }, { "id": "sg-04-p1-t5", "from": "encounter-handoff", "to": "draft-note", "label": "run attributable note draft", "condition": "Appointment-bound EHR encounter satisfies the deterministic preconditions declared for Attributable note draft.", "reality": "both", "delivery_state": "partial", "retry": "Retry Attributable note draft under the same workflow identity and dedupe key; Provider owns terminal failure.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#doctor-visit", "spec/as-built.md#charting-ehr" ] }, { "id": "sg-04-p1-t6", "from": "draft-note", "to": "doctor-edit", "label": "Provider performs clinician review and edit", "condition": "Attributable note draft presents attributable work to Provider; no automatic approval or silent substitution is permitted.", "reality": "both", "delivery_state": "partial", "retry": "Do not auto-approve. Return the same attributable record to Provider with the unresolved reason preserved.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#doctor-visit", "spec/as-built.md#charting-ehr" ] }, { "id": "sg-04-p1-t7", "from": "doctor-edit", "to": "signed-note", "label": "write signed immutable clinical note", "condition": "Clinician review and edit has the complete attributable payload required for the durable Signed immutable clinical note write.", "reality": "both", "delivery_state": "partial", "retry": "Repeat the durable write only with its original idempotency key; Provider owns conflicting state.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#doctor-visit", "spec/as-built.md#charting-ehr" ] }, { "id": "sg-04-p1-t8", "from": "signed-note", "to": "complete", "label": "complete clinical artifact pipeline complete", "condition": "All named predecessor states required by Clinical artifact pipeline complete are satisfied or explicitly resolved.", "reality": "both", "delivery_state": "partial", "retry": "Reopen only from the attributable unresolved predecessor; Provider owns terminal closure.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#doctor-visit", "spec/as-built.md#charting-ehr" ] }, { "id": "sg-04-consent-declined", "from": "consent-check", "to": "encounter-handoff", "label": "continue without recording artifacts", "condition": "Recording consent was declined or no recording is available; the clinical encounter still proceeds without synthesized artifacts.", "reality": "both", "delivery_state": "partial", "retry": "No recording retry occurs without new explicit consent; Provider documents the encounter normally.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#doctor-visit" ] }, { "id": "sg-04-p3-t1", "from": "signed-note", "to": "amendment", "label": "Provider performs addendum, amendment, or void", "condition": "Signed immutable clinical note presents attributable work to Provider; no automatic approval or silent substitution is permitted.", "reality": "both", "delivery_state": "partial", "retry": "Do not auto-approve. Return the same attributable record to Provider with the unresolved reason preserved.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#doctor-visit", "spec/as-built.md#charting-ehr" ] }, { "id": "sg-04-p3-t2", "from": "amendment", "to": "complete", "label": "complete clinical artifact pipeline complete", "condition": "All named predecessor states required by Clinical artifact pipeline complete are satisfied or explicitly resolved.", "reality": "both", "delivery_state": "partial", "retry": "Reopen only from the attributable unresolved predecessor; Provider owns terminal closure.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#doctor-visit", "spec/as-built.md#charting-ehr" ] } ] }, { "id": "sg-05", "title": "Visit observation lifecycle", "forms": [ "state-machine", "internal-pipeline" ], "description": "Seven candidate frames sampled from patient-speaking intervals, technical quality controls, clinician confirmation, note citation, deletion, invalidation, and tombstones.", "actors": [ "Artifact Worker", "Provider", "EHR" ], "steps": [ { "id": "artifact-ready", "label": "Recording and transcript ready", "kind": "start", "actor": "Artifact Worker", "reality": "target", "reads": [], "writes": [ "Recording and transcript ready state" ], "evidence_refs": [ "spec/business.md#visit-observation", "spec/technical.md#2-7-visit-observation" ] }, { "id": "speaking-intervals", "label": "Patient-speaking intervals", "kind": "automation", "actor": "Artifact Worker", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Patient-speaking intervals state" ], "evidence_refs": [ "spec/business.md#visit-observation", "spec/technical.md#2-7-visit-observation" ] }, { "id": "sample-frames", "label": "Seven distributed candidate frames", "kind": "automation", "actor": "Artifact Worker", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Seven distributed candidate frames state" ], "evidence_refs": [ "spec/business.md#visit-observation", "spec/technical.md#2-7-visit-observation" ] }, { "id": "quality-dedupe", "label": "Technical quality and duplicate filter", "kind": "decision", "actor": "Artifact Worker", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Technical quality and duplicate filter decision" ], "evidence_refs": [ "spec/business.md#visit-observation", "spec/technical.md#2-7-visit-observation" ] }, { "id": "candidate-ehr", "label": "Candidate images in EHR", "kind": "record", "actor": "EHR", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Candidate images in EHR state" ], "evidence_refs": [ "spec/business.md#visit-observation", "spec/technical.md#2-7-visit-observation" ] }, { "id": "doctor-confirm", "label": "Doctor confirms visible subject", "kind": "human", "actor": "Provider", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Doctor confirms visible subject state" ], "evidence_refs": [ "spec/business.md#visit-observation", "spec/technical.md#2-7-visit-observation" ] }, { "id": "note-citations", "label": "Attributable neutral note citations", "kind": "record", "actor": "EHR", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Attributable neutral note citations state" ], "evidence_refs": [ "spec/business.md#visit-observation", "spec/technical.md#2-7-visit-observation" ] }, { "id": "doctor-delete", "label": "Doctor deletion", "kind": "human", "actor": "Provider", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Doctor deletion state" ], "evidence_refs": [ "spec/business.md#visit-observation", "spec/technical.md#2-7-visit-observation" ] }, { "id": "invalidation", "label": "Derived observation invalidation", "kind": "automation", "actor": "EHR", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Derived observation invalidation state" ], "evidence_refs": [ "spec/business.md#visit-observation", "spec/technical.md#2-7-visit-observation" ] }, { "id": "tombstone", "label": "Deletion tombstone and audit", "kind": "record", "actor": "EHR", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Deletion tombstone and audit state" ], "evidence_refs": [ "spec/business.md#visit-observation", "spec/technical.md#2-7-visit-observation" ] }, { "id": "complete", "label": "Observation lifecycle complete", "kind": "end", "actor": "EHR", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Observation lifecycle complete state" ], "evidence_refs": [ "spec/business.md#visit-observation", "spec/technical.md#2-7-visit-observation" ] } ], "transitions": [ { "id": "sg-05-p1-t1", "from": "artifact-ready", "to": "speaking-intervals", "label": "run patient-speaking intervals", "condition": "Target-only and not deployed: Recording and transcript ready satisfies the deterministic preconditions declared for Patient-speaking intervals.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Retry Patient-speaking intervals under the same workflow identity and dedupe key; Provider owns terminal failure.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#visit-observation", "spec/technical.md#2-7-visit-observation" ] }, { "id": "sg-05-p1-t2", "from": "speaking-intervals", "to": "sample-frames", "label": "run seven distributed candidate frames", "condition": "Target-only and not deployed: Patient-speaking intervals satisfies the deterministic preconditions declared for Seven distributed candidate frames.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Retry Seven distributed candidate frames under the same workflow identity and dedupe key; Provider owns terminal failure.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#visit-observation", "spec/technical.md#2-7-visit-observation" ] }, { "id": "sg-05-p1-t3", "from": "sample-frames", "to": "quality-dedupe", "label": "evaluate technical quality and duplicate filter", "condition": "Target-only and not deployed: Technical quality and duplicate filter has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Re-evaluate only after a named input changes; Provider owns unresolved or conflicting eligibility.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#visit-observation", "spec/technical.md#2-7-visit-observation" ] }, { "id": "sg-05-p1-t4", "from": "quality-dedupe", "to": "candidate-ehr", "label": "write candidate images in ehr", "condition": "Target-only and not deployed: Technical quality and duplicate filter has the complete attributable payload required for the durable Candidate images in EHR write.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Repeat the durable write only with its original idempotency key; Provider owns conflicting state.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#visit-observation", "spec/technical.md#2-7-visit-observation" ] }, { "id": "sg-05-p1-t5", "from": "candidate-ehr", "to": "doctor-confirm", "label": "Provider performs doctor confirms visible subject", "condition": "Target-only and not deployed: Candidate images in EHR presents attributable work to Provider; no automatic approval or silent substitution is permitted.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Do not auto-approve. Return the same attributable record to Provider with the unresolved reason preserved.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#visit-observation", "spec/technical.md#2-7-visit-observation" ] }, { "id": "sg-05-p1-t6", "from": "doctor-confirm", "to": "note-citations", "label": "write attributable neutral note citations", "condition": "Target-only and not deployed: Doctor confirms visible subject has the complete attributable payload required for the durable Attributable neutral note citations write.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Repeat the durable write only with its original idempotency key; Provider owns conflicting state.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#visit-observation", "spec/technical.md#2-7-visit-observation" ] }, { "id": "sg-05-p1-t7", "from": "note-citations", "to": "complete", "label": "complete observation lifecycle complete", "condition": "Target-only and not deployed: All named predecessor states required by Observation lifecycle complete are satisfied or explicitly resolved.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Reopen only from the attributable unresolved predecessor; Provider owns terminal closure.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#visit-observation", "spec/technical.md#2-7-visit-observation" ] }, { "id": "sg-05-p2-t1", "from": "candidate-ehr", "to": "doctor-delete", "label": "Provider performs doctor deletion", "condition": "Target-only and not deployed: Candidate images in EHR presents attributable work to Provider; no automatic approval or silent substitution is permitted.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Do not auto-approve. Return the same attributable record to Provider with the unresolved reason preserved.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#visit-observation", "spec/technical.md#2-7-visit-observation" ] }, { "id": "sg-05-p2-t2", "from": "doctor-delete", "to": "invalidation", "label": "run derived observation invalidation", "condition": "Target-only and not deployed: Doctor deletion satisfies the deterministic preconditions declared for Derived observation invalidation.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Retry Derived observation invalidation under the same workflow identity and dedupe key; Provider owns terminal failure.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#visit-observation", "spec/technical.md#2-7-visit-observation" ] }, { "id": "sg-05-p2-t3", "from": "invalidation", "to": "tombstone", "label": "write deletion tombstone and audit", "condition": "Target-only and not deployed: Derived observation invalidation has the complete attributable payload required for the durable Deletion tombstone and audit write.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Repeat the durable write only with its original idempotency key; Provider owns conflicting state.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#visit-observation", "spec/technical.md#2-7-visit-observation" ] }, { "id": "sg-05-p2-t4", "from": "tombstone", "to": "complete", "label": "complete observation lifecycle complete", "condition": "Target-only and not deployed: All named predecessor states required by Observation lifecycle complete are satisfied or explicitly resolved.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Reopen only from the attributable unresolved predecessor; Provider owns terminal closure.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#visit-observation", "spec/technical.md#2-7-visit-observation" ] }, { "id": "sg-05-p3-t1", "from": "doctor-confirm", "to": "doctor-delete", "label": "Provider performs doctor deletion", "condition": "Target-only and not deployed: Doctor confirms visible subject presents attributable work to Provider; no automatic approval or silent substitution is permitted.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Do not auto-approve. Return the same attributable record to Provider with the unresolved reason preserved.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#visit-observation", "spec/technical.md#2-7-visit-observation" ] }, { "id": "sg-05-p4-t1", "from": "doctor-confirm", "to": "invalidation", "label": "run derived observation invalidation", "condition": "Target-only and not deployed: Doctor confirms visible subject satisfies the deterministic preconditions declared for Derived observation invalidation.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Retry Derived observation invalidation under the same workflow identity and dedupe key; Provider owns terminal failure.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#visit-observation", "spec/technical.md#2-7-visit-observation" ] }, { "id": "sg-05-p5-t1", "from": "note-citations", "to": "doctor-delete", "label": "Provider performs doctor deletion", "condition": "Target-only and not deployed: Attributable neutral note citations presents attributable work to Provider; no automatic approval or silent substitution is permitted.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Do not auto-approve. Return the same attributable record to Provider with the unresolved reason preserved.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#visit-observation", "spec/technical.md#2-7-visit-observation" ] } ] }, { "id": "sg-06", "title": "Prescription lifecycle", "forms": [ "decision-tree", "state-machine" ], "description": "Signed encounter, stable fingerprint, clinician and catalog gates, issuance, downstream routing, correction, and void.", "actors": [ "Provider", "EHR", "Medication Catalog", "Pharmacy", "Rails" ], "steps": [ { "id": "signed-encounter", "label": "Signed encounter", "kind": "start", "actor": "EHR", "reality": "both", "reads": [], "writes": [ "Signed encounter state" ], "evidence_refs": [ "spec/as-built.md#prescription-generation", "spec/as-built.md#medication-catalog" ] }, { "id": "fingerprint", "label": "Stable prescription fingerprint", "kind": "automation", "actor": "EHR", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Stable prescription fingerprint state" ], "evidence_refs": [ "spec/as-built.md#prescription-generation", "spec/as-built.md#medication-catalog" ] }, { "id": "clinical-gates", "label": "Licensure, state, dose, and catalog gates", "kind": "decision", "actor": "Provider", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Licensure, state, dose, and catalog gates decision" ], "evidence_refs": [ "spec/as-built.md#prescription-generation", "spec/as-built.md#medication-catalog" ] }, { "id": "issue-rx", "label": "Complete issued prescription", "kind": "record", "actor": "EHR", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Complete issued prescription state" ], "evidence_refs": [ "spec/as-built.md#prescription-generation", "spec/as-built.md#medication-catalog" ] }, { "id": "payment-offer", "label": "Catalog-backed payment offer", "kind": "state", "actor": "Rails", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Catalog-backed payment offer state" ], "evidence_refs": [ "spec/as-built.md#prescription-generation", "spec/as-built.md#medication-catalog" ] }, { "id": "pharmacy-route", "label": "Licensed pharmacy routing", "kind": "automation", "actor": "Rails", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Licensed pharmacy routing state" ], "evidence_refs": [ "spec/as-built.md#prescription-generation", "spec/as-built.md#medication-catalog" ] }, { "id": "correction", "label": "Attributable correction or void", "kind": "human", "actor": "Provider", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Attributable correction or void state" ], "evidence_refs": [ "spec/as-built.md#prescription-generation", "spec/as-built.md#medication-catalog" ] }, { "id": "complete", "label": "Prescription lifecycle complete", "kind": "end", "actor": "EHR", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Prescription lifecycle complete state" ], "evidence_refs": [ "spec/as-built.md#prescription-generation", "spec/as-built.md#medication-catalog" ] } ], "transitions": [ { "id": "sg-06-p1-t1", "from": "signed-encounter", "to": "fingerprint", "label": "run stable prescription fingerprint", "condition": "Signed encounter satisfies the deterministic preconditions declared for Stable prescription fingerprint.", "reality": "both", "delivery_state": "partial", "retry": "Retry Stable prescription fingerprint under the same workflow identity and dedupe key; Provider owns terminal failure.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#prescription-generation", "spec/as-built.md#medication-catalog" ] }, { "id": "sg-06-p1-t2", "from": "fingerprint", "to": "clinical-gates", "label": "evaluate licensure, state, dose, and catalog gates", "condition": "Licensure, state, dose, and catalog gates has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "both", "delivery_state": "partial", "retry": "Re-evaluate only after a named input changes; Provider owns unresolved or conflicting eligibility.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#prescription-generation", "spec/as-built.md#medication-catalog" ] }, { "id": "sg-06-p1-t3", "from": "clinical-gates", "to": "issue-rx", "label": "write complete issued prescription", "condition": "Licensure, state, dose, and catalog gates has the complete attributable payload required for the durable Complete issued prescription write.", "reality": "both", "delivery_state": "partial", "retry": "Repeat the durable write only with its original idempotency key; Provider owns conflicting state.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#prescription-generation", "spec/as-built.md#medication-catalog" ] }, { "id": "sg-06-p1-t4", "from": "issue-rx", "to": "complete", "label": "complete prescription lifecycle complete", "condition": "All named predecessor states required by Prescription lifecycle complete are satisfied or explicitly resolved.", "reality": "both", "delivery_state": "partial", "retry": "Reopen only from the attributable unresolved predecessor; Provider owns terminal closure.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#prescription-generation", "spec/as-built.md#medication-catalog" ] }, { "id": "sg-06-p2-t1", "from": "issue-rx", "to": "payment-offer", "label": "enter catalog-backed payment offer", "condition": "Complete issued prescription supplies the named facts required to enter Catalog-backed payment offer.", "reality": "both", "delivery_state": "partial", "retry": "Resume the same attributable workflow state; Provider owns conflicting or stalled progress.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#prescription-generation", "spec/as-built.md#medication-catalog" ] }, { "id": "sg-06-p3-t1", "from": "issue-rx", "to": "pharmacy-route", "label": "run licensed pharmacy routing", "condition": "Complete issued prescription satisfies the deterministic preconditions declared for Licensed pharmacy routing.", "reality": "both", "delivery_state": "partial", "retry": "Retry Licensed pharmacy routing under the same workflow identity and dedupe key; Provider owns terminal failure.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#prescription-generation", "spec/as-built.md#medication-catalog" ] }, { "id": "sg-06-p4-t1", "from": "issue-rx", "to": "correction", "label": "Provider performs attributable correction or void", "condition": "Complete issued prescription presents attributable work to Provider; no automatic approval or silent substitution is permitted.", "reality": "both", "delivery_state": "partial", "retry": "Do not auto-approve. Return the same attributable record to Provider with the unresolved reason preserved.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#prescription-generation", "spec/as-built.md#medication-catalog" ] }, { "id": "sg-06-p4-t2", "from": "correction", "to": "complete", "label": "complete prescription lifecycle complete", "condition": "All named predecessor states required by Prescription lifecycle complete are satisfied or explicitly resolved.", "reality": "both", "delivery_state": "partial", "retry": "Reopen only from the attributable unresolved predecessor; Provider owns terminal closure.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#prescription-generation", "spec/as-built.md#medication-catalog" ] } ] }, { "id": "sg-07", "title": "Prescription payment", "forms": [ "sequence", "state-machine" ], "description": "Pay-link creation, hosted Checkout, redirect/webhook race, idempotent authoritative finalization, recovery, and reconciliation.", "actors": [ "Patient", "Rails", "Stripe", "Billing Operations" ], "steps": [ { "id": "eligible-offer", "label": "Eligible prescription offer", "kind": "start", "actor": "Rails", "reality": "both", "reads": [], "writes": [ "Eligible prescription offer state" ], "evidence_refs": [ "spec/as-built.md#rx-pay", "spec/as-built.md#billing-architecture" ] }, { "id": "create-pay-link", "label": "Expiring prescription pay link", "kind": "automation", "actor": "Rails", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Expiring prescription pay link state" ], "evidence_refs": [ "spec/as-built.md#rx-pay", "spec/as-built.md#billing-architecture" ] }, { "id": "hosted-checkout", "label": "Hosted Stripe Checkout", "kind": "external", "actor": "Stripe", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Hosted Stripe Checkout state" ], "evidence_refs": [ "spec/as-built.md#rx-pay", "spec/as-built.md#billing-architecture" ] }, { "id": "redirect", "label": "Browser success redirect", "kind": "external", "actor": "Patient", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Browser success redirect state" ], "evidence_refs": [ "spec/as-built.md#rx-pay", "spec/as-built.md#billing-architecture" ] }, { "id": "webhook", "label": "Authoritative Stripe webhook", "kind": "external", "actor": "Stripe", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Authoritative Stripe webhook state" ], "evidence_refs": [ "spec/as-built.md#rx-pay", "spec/as-built.md#billing-architecture" ] }, { "id": "finalize", "label": "Idempotent payment finalization", "kind": "record", "actor": "Rails", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Idempotent payment finalization state" ], "evidence_refs": [ "spec/as-built.md#rx-pay", "spec/as-built.md#billing-architecture" ] }, { "id": "recovery", "label": "Incomplete-payment recovery", "kind": "state", "actor": "Billing Operations", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Incomplete-payment recovery state" ], "evidence_refs": [ "spec/as-built.md#rx-pay", "spec/as-built.md#billing-architecture" ] }, { "id": "reconcile", "label": "Ledger reconciliation", "kind": "automation", "actor": "Rails", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Ledger reconciliation state" ], "evidence_refs": [ "spec/as-built.md#rx-pay", "spec/as-built.md#billing-architecture" ] }, { "id": "complete", "label": "Payment state authoritative", "kind": "end", "actor": "Rails", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Payment state authoritative state" ], "evidence_refs": [ "spec/as-built.md#rx-pay", "spec/as-built.md#billing-architecture" ] } ], "transitions": [ { "id": "sg-07-p1-t1", "from": "eligible-offer", "to": "create-pay-link", "label": "run expiring prescription pay link", "condition": "Eligible prescription offer satisfies the deterministic preconditions declared for Expiring prescription pay link.", "reality": "both", "delivery_state": "partial", "retry": "Retry Expiring prescription pay link under the same workflow identity and dedupe key; Billing Operations owns terminal failure.", "human_owner": "Billing Operations", "evidence_refs": [ "spec/as-built.md#rx-pay", "spec/as-built.md#billing-architecture" ] }, { "id": "sg-07-p1-t2", "from": "create-pay-link", "to": "hosted-checkout", "label": "submit hosted stripe checkout", "condition": "Expiring prescription pay link supplies the authenticated external contract and stable source identifiers required by Hosted Stripe Checkout.", "reality": "both", "delivery_state": "partial", "retry": "Retry transport under the same stable external ID; Billing Operations owns rejection, timeout, and reconciliation.", "human_owner": "Billing Operations", "evidence_refs": [ "spec/as-built.md#rx-pay", "spec/as-built.md#billing-architecture" ] }, { "id": "sg-07-p1-t3", "from": "hosted-checkout", "to": "webhook", "label": "submit authoritative stripe webhook", "condition": "Hosted Stripe Checkout supplies the authenticated external contract and stable source identifiers required by Authoritative Stripe webhook.", "reality": "both", "delivery_state": "partial", "retry": "Retry transport under the same stable external ID; Billing Operations owns rejection, timeout, and reconciliation.", "human_owner": "Billing Operations", "evidence_refs": [ "spec/as-built.md#rx-pay", "spec/as-built.md#billing-architecture" ] }, { "id": "sg-07-p1-t4", "from": "webhook", "to": "finalize", "label": "write idempotent payment finalization", "condition": "Authoritative Stripe webhook has the complete attributable payload required for the durable Idempotent payment finalization write.", "reality": "both", "delivery_state": "partial", "retry": "Repeat the durable write only with its original idempotency key; Billing Operations owns conflicting state.", "human_owner": "Billing Operations", "evidence_refs": [ "spec/as-built.md#rx-pay", "spec/as-built.md#billing-architecture" ] }, { "id": "sg-07-p1-t5", "from": "finalize", "to": "reconcile", "label": "run ledger reconciliation", "condition": "Idempotent payment finalization satisfies the deterministic preconditions declared for Ledger reconciliation.", "reality": "both", "delivery_state": "partial", "retry": "Retry Ledger reconciliation under the same workflow identity and dedupe key; Billing Operations owns terminal failure.", "human_owner": "Billing Operations", "evidence_refs": [ "spec/as-built.md#rx-pay", "spec/as-built.md#billing-architecture" ] }, { "id": "sg-07-p1-t6", "from": "reconcile", "to": "complete", "label": "complete payment state authoritative", "condition": "All named predecessor states required by Payment state authoritative are satisfied or explicitly resolved.", "reality": "both", "delivery_state": "partial", "retry": "Reopen only from the attributable unresolved predecessor; Billing Operations owns terminal closure.", "human_owner": "Billing Operations", "evidence_refs": [ "spec/as-built.md#rx-pay", "spec/as-built.md#billing-architecture" ] }, { "id": "sg-07-p2-t1", "from": "hosted-checkout", "to": "redirect", "label": "submit browser success redirect", "condition": "Hosted Stripe Checkout supplies the authenticated external contract and stable source identifiers required by Browser success redirect.", "reality": "both", "delivery_state": "partial", "retry": "Retry transport under the same stable external ID; Billing Operations owns rejection, timeout, and reconciliation.", "human_owner": "Billing Operations", "evidence_refs": [ "spec/as-built.md#rx-pay", "spec/as-built.md#billing-architecture" ] }, { "id": "sg-07-p2-t2", "from": "redirect", "to": "finalize", "label": "write idempotent payment finalization", "condition": "Browser success redirect has the complete attributable payload required for the durable Idempotent payment finalization write.", "reality": "both", "delivery_state": "partial", "retry": "Repeat the durable write only with its original idempotency key; Billing Operations owns conflicting state.", "human_owner": "Billing Operations", "evidence_refs": [ "spec/as-built.md#rx-pay", "spec/as-built.md#billing-architecture" ] }, { "id": "sg-07-p3-t1", "from": "hosted-checkout", "to": "recovery", "label": "enter incomplete-payment recovery", "condition": "Hosted Stripe Checkout supplies the named facts required to enter Incomplete-payment recovery.", "reality": "both", "delivery_state": "partial", "retry": "Resume the same attributable workflow state; Billing Operations owns conflicting or stalled progress.", "human_owner": "Billing Operations", "evidence_refs": [ "spec/as-built.md#rx-pay", "spec/as-built.md#billing-architecture" ] }, { "id": "sg-07-p3-t2", "from": "recovery", "to": "hosted-checkout", "label": "return to hosted stripe checkout", "condition": "Incomplete-payment recovery requires attributable retry or rework at Hosted Stripe Checkout.", "reality": "both", "delivery_state": "partial", "retry": "Retry transport under the same stable external ID; Billing Operations owns rejection, timeout, and reconciliation.", "human_owner": "Billing Operations", "evidence_refs": [ "spec/as-built.md#rx-pay", "spec/as-built.md#billing-architecture" ] }, { "id": "sg-07-p4-t1", "from": "recovery", "to": "reconcile", "label": "run ledger reconciliation", "condition": "Incomplete-payment recovery satisfies the deterministic preconditions declared for Ledger reconciliation.", "reality": "both", "delivery_state": "partial", "retry": "Retry Ledger reconciliation under the same workflow identity and dedupe key; Billing Operations owns terminal failure.", "human_owner": "Billing Operations", "evidence_refs": [ "spec/as-built.md#rx-pay", "spec/as-built.md#billing-architecture" ] } ] }, { "id": "sg-08", "title": "Ninety-day care loop", "forms": [ "lifecycle-loop", "state-machine" ], "description": "Delivery evidence, ongoing check-in, projected depletion, refill requests, the hard three-month clinician gate, reissue, and continue/change/stop decisions.", "actors": [ "Patient", "Provider", "Rails", "EHR" ], "steps": [ { "id": "therapy-active", "label": "Active therapy window", "kind": "start", "actor": "EHR", "reality": "target", "reads": [], "writes": [ "Active therapy window state" ], "evidence_refs": [ "spec/business.md#prescription-limits", "spec/business.md#check-ups", "spec/business.md#refills" ] }, { "id": "shipment-evidence", "label": "Delivery and supply evidence", "kind": "record", "actor": "Rails", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Delivery and supply evidence state" ], "evidence_refs": [ "spec/business.md#prescription-limits", "spec/business.md#check-ups", "spec/business.md#refills" ] }, { "id": "check-in", "label": "Patient progress check-in", "kind": "human", "actor": "Patient", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Patient progress check-in state" ], "evidence_refs": [ "spec/business.md#prescription-limits", "spec/business.md#check-ups", "spec/business.md#refills" ] }, { "id": "depletion-anchor", "label": "Expected depletion anchor", "kind": "automation", "actor": "Rails", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Expected depletion anchor state" ], "evidence_refs": [ "spec/business.md#prescription-limits", "spec/business.md#check-ups", "spec/business.md#refills" ] }, { "id": "refill-request", "label": "Patient refill request", "kind": "state", "actor": "Patient", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Patient refill request state" ], "evidence_refs": [ "spec/business.md#prescription-limits", "spec/business.md#check-ups", "spec/business.md#refills" ] }, { "id": "evidence-packet", "label": "Weight, adherence, outcomes, labs, and timeline packet", "kind": "record", "actor": "EHR", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Weight, adherence, outcomes, labs, and timeline packet state" ], "evidence_refs": [ "spec/business.md#prescription-limits", "spec/business.md#check-ups", "spec/business.md#refills" ] }, { "id": "three-month-gate", "label": "Three-month continuation gate", "kind": "decision", "actor": "Rails", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Three-month continuation gate decision" ], "evidence_refs": [ "spec/business.md#prescription-limits", "spec/business.md#check-ups", "spec/business.md#refills" ] }, { "id": "clinician-review", "label": "Clinician continuation review", "kind": "human", "actor": "Provider", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Clinician continuation review state" ], "evidence_refs": [ "spec/business.md#prescription-limits", "spec/business.md#check-ups", "spec/business.md#refills" ] }, { "id": "continue-change-stop", "label": "Continue, change, or stop decision", "kind": "decision", "actor": "Provider", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Continue, change, or stop decision decision" ], "evidence_refs": [ "spec/business.md#prescription-limits", "spec/business.md#check-ups", "spec/business.md#refills" ] }, { "id": "reissue", "label": "New clinician-issued prescription", "kind": "record", "actor": "EHR", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "New clinician-issued prescription state" ], "evidence_refs": [ "spec/business.md#prescription-limits", "spec/business.md#check-ups", "spec/business.md#refills" ] }, { "id": "complete", "label": "Care-loop decision recorded", "kind": "end", "actor": "EHR", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Care-loop decision recorded state" ], "evidence_refs": [ "spec/business.md#prescription-limits", "spec/business.md#check-ups", "spec/business.md#refills" ] } ], "transitions": [ { "id": "sg-08-p1-t1", "from": "therapy-active", "to": "shipment-evidence", "label": "write delivery and supply evidence", "condition": "Target-only and not deployed: Active therapy window has the complete attributable payload required for the durable Delivery and supply evidence write.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Repeat the durable write only with its original idempotency key; Provider owns conflicting state.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#prescription-limits", "spec/business.md#check-ups", "spec/business.md#refills" ] }, { "id": "sg-08-p1-t2", "from": "shipment-evidence", "to": "depletion-anchor", "label": "run expected depletion anchor", "condition": "Target-only and not deployed: Delivery and supply evidence satisfies the deterministic preconditions declared for Expected depletion anchor.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Retry Expected depletion anchor under the same workflow identity and dedupe key; Provider owns terminal failure.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#prescription-limits", "spec/business.md#check-ups", "spec/business.md#refills" ] }, { "id": "sg-08-p1-t3", "from": "depletion-anchor", "to": "evidence-packet", "label": "write weight, adherence, outcomes, labs, and timeline packet", "condition": "Target-only and not deployed: Expected depletion anchor has the complete attributable payload required for the durable Weight, adherence, outcomes, labs, and timeline packet write.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Repeat the durable write only with its original idempotency key; Provider owns conflicting state.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#prescription-limits", "spec/business.md#check-ups", "spec/business.md#refills" ] }, { "id": "sg-08-p1-t4", "from": "evidence-packet", "to": "three-month-gate", "label": "evaluate three-month continuation gate", "condition": "Target-only and not deployed: Three-month continuation gate has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Re-evaluate only after a named input changes; Provider owns unresolved or conflicting eligibility.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#prescription-limits", "spec/business.md#check-ups", "spec/business.md#refills" ] }, { "id": "sg-08-p1-t5", "from": "three-month-gate", "to": "clinician-review", "label": "Provider performs clinician continuation review", "condition": "Target-only and not deployed: Three-month continuation gate presents attributable work to Provider; no automatic approval or silent substitution is permitted.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Do not auto-approve. Return the same attributable record to Provider with the unresolved reason preserved.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#prescription-limits", "spec/business.md#check-ups", "spec/business.md#refills" ] }, { "id": "sg-08-p1-t6", "from": "clinician-review", "to": "continue-change-stop", "label": "evaluate continue, change, or stop decision", "condition": "Target-only and not deployed: Continue, change, or stop decision has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Re-evaluate only after a named input changes; Provider owns unresolved or conflicting eligibility.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#prescription-limits", "spec/business.md#check-ups", "spec/business.md#refills" ] }, { "id": "sg-08-p1-t7", "from": "continue-change-stop", "to": "reissue", "label": "write new clinician-issued prescription", "condition": "Target-only and not deployed: Continue, change, or stop decision has the complete attributable payload required for the durable New clinician-issued prescription write.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Repeat the durable write only with its original idempotency key; Provider owns conflicting state.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#prescription-limits", "spec/business.md#check-ups", "spec/business.md#refills" ] }, { "id": "sg-08-p1-t8", "from": "reissue", "to": "complete", "label": "complete care-loop decision recorded", "condition": "Target-only and not deployed: All named predecessor states required by Care-loop decision recorded are satisfied or explicitly resolved.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Reopen only from the attributable unresolved predecessor; Provider owns terminal closure.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#prescription-limits", "spec/business.md#check-ups", "spec/business.md#refills" ] }, { "id": "sg-08-p2-t1", "from": "therapy-active", "to": "check-in", "label": "Patient performs patient progress check-in", "condition": "Target-only and not deployed: Active therapy window presents attributable work to Patient; no automatic approval or silent substitution is permitted.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Do not auto-approve. Return the same attributable record to Patient with the unresolved reason preserved.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#prescription-limits", "spec/business.md#check-ups", "spec/business.md#refills" ] }, { "id": "sg-08-p2-t2", "from": "check-in", "to": "evidence-packet", "label": "write weight, adherence, outcomes, labs, and timeline packet", "condition": "Target-only and not deployed: Patient progress check-in has the complete attributable payload required for the durable Weight, adherence, outcomes, labs, and timeline packet write.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Repeat the durable write only with its original idempotency key; Provider owns conflicting state.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#prescription-limits", "spec/business.md#check-ups", "spec/business.md#refills" ] }, { "id": "sg-08-p3-t1", "from": "depletion-anchor", "to": "refill-request", "label": "enter patient refill request", "condition": "Target-only and not deployed: Expected depletion anchor supplies the named facts required to enter Patient refill request.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Resume the same attributable workflow state; Provider owns conflicting or stalled progress.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#prescription-limits", "spec/business.md#check-ups", "spec/business.md#refills" ] }, { "id": "sg-08-p3-t2", "from": "refill-request", "to": "clinician-review", "label": "Provider performs clinician continuation review", "condition": "Target-only and not deployed: Patient refill request presents attributable work to Provider; no automatic approval or silent substitution is permitted.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Do not auto-approve. Return the same attributable record to Provider with the unresolved reason preserved.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#prescription-limits", "spec/business.md#check-ups", "spec/business.md#refills" ] }, { "id": "sg-08-p4-t1", "from": "reissue", "to": "therapy-active", "label": "start active therapy window", "condition": "Target-only and not deployed: Active therapy window receives its named initiating event.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Replay only the stable initiating event; Provider owns duplicates or rejection.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#prescription-limits", "spec/business.md#check-ups", "spec/business.md#refills" ] } ] }, { "id": "sg-09", "title": "Records provenance", "forms": [ "data-flow", "internal-pipeline" ], "description": "Source upload, immutable sealing, extraction, citation, conflicts, authorized review, EHR promotion, and reconciliation.", "actors": [ "Patient", "Provider", "Extraction Worker", "EHR" ], "steps": [ { "id": "upload", "label": "Authorized source upload", "kind": "start", "actor": "Patient", "reality": "both", "reads": [], "writes": [ "Authorized source upload state" ], "evidence_refs": [ "spec/as-built.md#records-ingestion" ] }, { "id": "seal-source", "label": "Immutable source seal", "kind": "record", "actor": "EHR", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Immutable source seal state" ], "evidence_refs": [ "spec/as-built.md#records-ingestion" ] }, { "id": "extract", "label": "Structured extraction with citations", "kind": "automation", "actor": "Extraction Worker", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Structured extraction with citations state" ], "evidence_refs": [ "spec/as-built.md#records-ingestion" ] }, { "id": "conflict-queue", "label": "Conflict and prior-value queue", "kind": "decision", "actor": "EHR", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Conflict and prior-value queue decision" ], "evidence_refs": [ "spec/as-built.md#records-ingestion" ] }, { "id": "human-review", "label": "Authorized human review", "kind": "human", "actor": "Provider", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Authorized human review state" ], "evidence_refs": [ "spec/as-built.md#records-ingestion" ] }, { "id": "promote", "label": "Provenance-preserving EHR promotion", "kind": "record", "actor": "EHR", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Provenance-preserving EHR promotion state" ], "evidence_refs": [ "spec/as-built.md#records-ingestion" ] }, { "id": "reconcile", "label": "Source-to-fact reconciliation", "kind": "automation", "actor": "EHR", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Source-to-fact reconciliation state" ], "evidence_refs": [ "spec/as-built.md#records-ingestion" ] }, { "id": "complete", "label": "Record ingestion complete", "kind": "end", "actor": "EHR", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Record ingestion complete state" ], "evidence_refs": [ "spec/as-built.md#records-ingestion" ] } ], "transitions": [ { "id": "sg-09-p1-t1", "from": "upload", "to": "seal-source", "label": "write immutable source seal", "condition": "Authorized source upload has the complete attributable payload required for the durable Immutable source seal write.", "reality": "both", "delivery_state": "partial", "retry": "Repeat the durable write only with its original idempotency key; Provider owns conflicting state.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#records-ingestion" ] }, { "id": "sg-09-p1-t2", "from": "seal-source", "to": "extract", "label": "run structured extraction with citations", "condition": "Immutable source seal satisfies the deterministic preconditions declared for Structured extraction with citations.", "reality": "both", "delivery_state": "partial", "retry": "Retry Structured extraction with citations under the same workflow identity and dedupe key; Provider owns terminal failure.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#records-ingestion" ] }, { "id": "sg-09-p1-t3", "from": "extract", "to": "human-review", "label": "Provider performs authorized human review", "condition": "Structured extraction with citations presents attributable work to Provider; no automatic approval or silent substitution is permitted.", "reality": "both", "delivery_state": "partial", "retry": "Do not auto-approve. Return the same attributable record to Provider with the unresolved reason preserved.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#records-ingestion" ] }, { "id": "sg-09-p1-t4", "from": "human-review", "to": "promote", "label": "write provenance-preserving ehr promotion", "condition": "Authorized human review has the complete attributable payload required for the durable Provenance-preserving EHR promotion write.", "reality": "both", "delivery_state": "partial", "retry": "Repeat the durable write only with its original idempotency key; Provider owns conflicting state.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#records-ingestion" ] }, { "id": "sg-09-p1-t5", "from": "promote", "to": "reconcile", "label": "run source-to-fact reconciliation", "condition": "Provenance-preserving EHR promotion satisfies the deterministic preconditions declared for Source-to-fact reconciliation.", "reality": "both", "delivery_state": "partial", "retry": "Retry Source-to-fact reconciliation under the same workflow identity and dedupe key; Provider owns terminal failure.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#records-ingestion" ] }, { "id": "sg-09-p1-t6", "from": "reconcile", "to": "complete", "label": "complete record ingestion complete", "condition": "All named predecessor states required by Record ingestion complete are satisfied or explicitly resolved.", "reality": "both", "delivery_state": "partial", "retry": "Reopen only from the attributable unresolved predecessor; Provider owns terminal closure.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#records-ingestion" ] }, { "id": "sg-09-p2-t1", "from": "extract", "to": "conflict-queue", "label": "evaluate conflict and prior-value queue", "condition": "Conflict and prior-value queue has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "both", "delivery_state": "partial", "retry": "Re-evaluate only after a named input changes; Provider owns unresolved or conflicting eligibility.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#records-ingestion" ] }, { "id": "sg-09-p2-t2", "from": "conflict-queue", "to": "human-review", "label": "Provider performs authorized human review", "condition": "Conflict and prior-value queue presents attributable work to Provider; no automatic approval or silent substitution is permitted.", "reality": "both", "delivery_state": "partial", "retry": "Do not auto-approve. Return the same attributable record to Provider with the unresolved reason preserved.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#records-ingestion" ] } ] }, { "id": "sg-10", "title": "Labs lifecycle", "forms": [ "sequence", "decision-tree" ], "description": "Clinician order, Quest or mobile collection, Function Health normalization join, human result review, patient notification, and follow-up.", "actors": [ "Provider", "Patient", "Quest", "Mobile Phlebotomy", "Lab Operations", "EHR", "Rails" ], "steps": [ { "id": "clinician-order", "label": "Clinician-signed lab order", "kind": "start", "actor": "Provider", "reality": "both", "reads": [], "writes": [ "Clinician-signed lab order state" ], "evidence_refs": [ "spec/business.md#order-labs", "spec/as-built.md#lab-follow-up" ] }, { "id": "route-vendor", "label": "Approved collection-route choice", "kind": "decision", "actor": "EHR", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Approved collection-route choice decision" ], "evidence_refs": [ "spec/business.md#order-labs", "spec/as-built.md#lab-follow-up" ] }, { "id": "quest-collect", "label": "Quest requisition and collection", "kind": "external", "actor": "Quest", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Quest requisition and collection state" ], "evidence_refs": [ "spec/business.md#order-labs", "spec/as-built.md#lab-follow-up" ] }, { "id": "mobile-quote", "label": "Mobile draw quote", "kind": "external", "actor": "Mobile Phlebotomy", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Mobile draw quote state" ], "evidence_refs": [ "spec/business.md#order-labs", "spec/as-built.md#lab-follow-up" ] }, { "id": "mobile-accept", "label": "Patient accepts mobile draw", "kind": "human", "actor": "Patient", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Patient accepts mobile draw state" ], "evidence_refs": [ "spec/business.md#order-labs", "spec/as-built.md#lab-follow-up" ] }, { "id": "mobile-collect", "label": "Mobile specimen collection", "kind": "external", "actor": "Mobile Phlebotomy", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Mobile specimen collection state" ], "evidence_refs": [ "spec/business.md#order-labs", "spec/as-built.md#lab-follow-up" ] }, { "id": "normalize", "label": "Source-preserving result normalization", "kind": "automation", "actor": "EHR", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Source-preserving result normalization state" ], "evidence_refs": [ "spec/business.md#order-labs", "spec/as-built.md#lab-follow-up" ] }, { "id": "result-review", "label": "Human review of every result", "kind": "human", "actor": "Provider", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Human review of every result state" ], "evidence_refs": [ "spec/business.md#order-labs", "spec/as-built.md#lab-follow-up" ] }, { "id": "acknowledge", "label": "Staff acknowledgment", "kind": "record", "actor": "EHR", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Staff acknowledgment state" ], "evidence_refs": [ "spec/business.md#order-labs", "spec/as-built.md#lab-follow-up" ] }, { "id": "override", "label": "Attributable interpretation override", "kind": "human", "actor": "Provider", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Attributable interpretation override state" ], "evidence_refs": [ "spec/business.md#order-labs", "spec/as-built.md#lab-follow-up" ] }, { "id": "patient-notify", "label": "Governed patient notification", "kind": "external", "actor": "Rails", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Governed patient notification state" ], "evidence_refs": [ "spec/business.md#order-labs", "spec/as-built.md#lab-follow-up" ] }, { "id": "follow-up", "label": "Rounds, Ops exception, or appointment follow-up", "kind": "decision", "actor": "Lab Operations", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Rounds, Ops exception, or appointment follow-up decision" ], "evidence_refs": [ "spec/business.md#order-labs", "spec/as-built.md#lab-follow-up" ] }, { "id": "complete", "label": "Lab result closed", "kind": "end", "actor": "EHR", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Lab result closed state" ], "evidence_refs": [ "spec/business.md#order-labs", "spec/as-built.md#lab-follow-up" ] } ], "transitions": [ { "id": "sg-10-p1-t1", "from": "clinician-order", "to": "route-vendor", "label": "evaluate approved collection-route choice", "condition": "Approved collection-route choice has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "both", "delivery_state": "partial", "retry": "Re-evaluate only after a named input changes; Provider owns unresolved or conflicting eligibility.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#order-labs", "spec/as-built.md#lab-follow-up" ] }, { "id": "sg-10-p1-t2", "from": "route-vendor", "to": "quest-collect", "label": "submit quest requisition and collection", "condition": "Approved collection-route choice supplies the authenticated external contract and stable source identifiers required by Quest requisition and collection.", "reality": "both", "delivery_state": "partial", "retry": "Retry transport under the same stable external ID; Provider owns rejection, timeout, and reconciliation.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#order-labs", "spec/as-built.md#lab-follow-up" ] }, { "id": "sg-10-p1-t3", "from": "quest-collect", "to": "normalize", "label": "run source-preserving result normalization", "condition": "Quest requisition and collection satisfies the deterministic preconditions declared for Source-preserving result normalization.", "reality": "both", "delivery_state": "partial", "retry": "Retry Source-preserving result normalization under the same workflow identity and dedupe key; Provider owns terminal failure.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#order-labs", "spec/as-built.md#lab-follow-up" ] }, { "id": "sg-10-p1-t4", "from": "normalize", "to": "result-review", "label": "Provider performs human review of every result", "condition": "Source-preserving result normalization presents attributable work to Provider; no automatic approval or silent substitution is permitted.", "reality": "both", "delivery_state": "partial", "retry": "Do not auto-approve. Return the same attributable record to Provider with the unresolved reason preserved.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#order-labs", "spec/as-built.md#lab-follow-up" ] }, { "id": "sg-10-p1-t5", "from": "result-review", "to": "acknowledge", "label": "write staff acknowledgment", "condition": "Human review of every result has the complete attributable payload required for the durable Staff acknowledgment write.", "reality": "both", "delivery_state": "partial", "retry": "Repeat the durable write only with its original idempotency key; Provider owns conflicting state.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#order-labs", "spec/as-built.md#lab-follow-up" ] }, { "id": "sg-10-p1-t6", "from": "acknowledge", "to": "patient-notify", "label": "submit governed patient notification", "condition": "Staff acknowledgment supplies the authenticated external contract and stable source identifiers required by Governed patient notification.", "reality": "both", "delivery_state": "partial", "retry": "Retry transport under the same stable external ID; Provider owns rejection, timeout, and reconciliation.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#order-labs", "spec/as-built.md#lab-follow-up" ] }, { "id": "sg-10-p1-t7", "from": "patient-notify", "to": "follow-up", "label": "evaluate rounds, ops exception, or appointment follow-up", "condition": "Rounds, Ops exception, or appointment follow-up has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "both", "delivery_state": "partial", "retry": "Re-evaluate only after a named input changes; Lab Operations owns unresolved or conflicting eligibility.", "human_owner": "Lab Operations", "evidence_refs": [ "spec/business.md#order-labs", "spec/as-built.md#lab-follow-up" ] }, { "id": "sg-10-p1-t8", "from": "follow-up", "to": "complete", "label": "complete lab result closed", "condition": "All named predecessor states required by Lab result closed are satisfied or explicitly resolved.", "reality": "both", "delivery_state": "partial", "retry": "Reopen only from the attributable unresolved predecessor; Lab Operations owns terminal closure.", "human_owner": "Lab Operations", "evidence_refs": [ "spec/business.md#order-labs", "spec/as-built.md#lab-follow-up" ] }, { "id": "sg-10-p2-t1", "from": "route-vendor", "to": "mobile-quote", "label": "submit mobile draw quote", "condition": "Approved collection-route choice supplies the authenticated external contract and stable source identifiers required by Mobile draw quote.", "reality": "both", "delivery_state": "partial", "retry": "Retry transport under the same stable external ID; Provider owns rejection, timeout, and reconciliation.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#order-labs", "spec/as-built.md#lab-follow-up" ] }, { "id": "sg-10-mobile-accepted", "from": "mobile-quote", "to": "mobile-accept", "label": "patient accepts the active mobile-draw quote", "condition": "The patient affirmatively accepts the unexpired vendor quote and its disclosed patient price.", "reality": "target", "delivery_state": "planned", "retry": "Do not schedule from an expired or ambiguous acceptance; Lab Operations obtains a new quote under the same lab order.", "human_owner": "Lab Operations", "evidence_refs": [ "spec/business.md#concierge-phlebotomy" ] }, { "id": "sg-10-p2-t3", "from": "mobile-accept", "to": "mobile-collect", "label": "submit mobile specimen collection", "condition": "Patient accepts mobile draw supplies the authenticated external contract and stable source identifiers required by Mobile specimen collection.", "reality": "both", "delivery_state": "partial", "retry": "Retry transport under the same stable external ID; Provider owns rejection, timeout, and reconciliation.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#order-labs", "spec/as-built.md#lab-follow-up" ] }, { "id": "sg-10-p2-t4", "from": "mobile-collect", "to": "normalize", "label": "run source-preserving result normalization", "condition": "Mobile specimen collection satisfies the deterministic preconditions declared for Source-preserving result normalization.", "reality": "both", "delivery_state": "partial", "retry": "Retry Source-preserving result normalization under the same workflow identity and dedupe key; Provider owns terminal failure.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#order-labs", "spec/as-built.md#lab-follow-up" ] }, { "id": "sg-10-mobile-declined", "from": "mobile-quote", "to": "route-vendor", "label": "mobile quote declined or expired", "condition": "The patient declines the quote or the quote expires before affirmative acceptance.", "reality": "target", "delivery_state": "planned", "retry": "Return to collection-route selection without charging or creating a mobile booking.", "human_owner": "Lab Operations", "evidence_refs": [ "spec/business.md#concierge-phlebotomy" ] }, { "id": "sg-10-p4-t1", "from": "result-review", "to": "override", "label": "Provider performs attributable interpretation override", "condition": "Human review of every result presents attributable work to Provider; no automatic approval or silent substitution is permitted.", "reality": "both", "delivery_state": "partial", "retry": "Do not auto-approve. Return the same attributable record to Provider with the unresolved reason preserved.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#order-labs", "spec/as-built.md#lab-follow-up" ] }, { "id": "sg-10-p4-t2", "from": "override", "to": "patient-notify", "label": "submit governed patient notification", "condition": "Attributable interpretation override supplies the authenticated external contract and stable source identifiers required by Governed patient notification.", "reality": "both", "delivery_state": "partial", "retry": "Retry transport under the same stable external ID; Provider owns rejection, timeout, and reconciliation.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#order-labs", "spec/as-built.md#lab-follow-up" ] } ] }, { "id": "sg-11", "title": "Function Health import", "forms": [ "internal-pipeline", "state-machine" ], "description": "Consent, one-time token, leased isolated pull or file parse, mapping queue, finalization, failure, and abandoned-lease reaping.", "actors": [ "Patient", "Function Health", "Import Worker", "Lab Operations", "EHR" ], "steps": [ { "id": "patient-consent", "label": "Patient import consent", "kind": "start", "actor": "Patient", "reality": "current", "reads": [], "writes": [ "Patient import consent state" ], "evidence_refs": [ "spec/as-built.md#function-health-lab-import" ] }, { "id": "one-time-token", "label": "One-time authorization token", "kind": "external", "actor": "Function Health", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "One-time authorization token state" ], "evidence_refs": [ "spec/as-built.md#function-health-lab-import" ] }, { "id": "lease", "label": "Exclusive import lease", "kind": "record", "actor": "Import Worker", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "Exclusive import lease state" ], "evidence_refs": [ "spec/as-built.md#function-health-lab-import" ] }, { "id": "isolated-pull", "label": "Isolated pull or file parse", "kind": "automation", "actor": "Import Worker", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "Isolated pull or file parse state" ], "evidence_refs": [ "spec/as-built.md#function-health-lab-import" ] }, { "id": "mapping-queue", "label": "Unresolved biomarker mapping queue", "kind": "human", "actor": "Lab Operations", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "Unresolved biomarker mapping queue state" ], "evidence_refs": [ "spec/as-built.md#function-health-lab-import" ] }, { "id": "finalize", "label": "Atomic normalized-result finalization", "kind": "record", "actor": "EHR", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "Atomic normalized-result finalization state" ], "evidence_refs": [ "spec/as-built.md#function-health-lab-import" ] }, { "id": "fail", "label": "Attributable failed import", "kind": "record", "actor": "Import Worker", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "Attributable failed import state" ], "evidence_refs": [ "spec/as-built.md#function-health-lab-import" ] }, { "id": "reap", "label": "Expired lease reaping", "kind": "automation", "actor": "Import Worker", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "Expired lease reaping state" ], "evidence_refs": [ "spec/as-built.md#function-health-lab-import" ] }, { "id": "complete", "label": "Import terminal state", "kind": "end", "actor": "EHR", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "Import terminal state state" ], "evidence_refs": [ "spec/as-built.md#function-health-lab-import" ] } ], "transitions": [ { "id": "sg-11-p1-t1", "from": "patient-consent", "to": "one-time-token", "label": "submit one-time authorization token", "condition": "Patient import consent supplies the authenticated external contract and stable source identifiers required by One-time authorization token.", "reality": "current", "delivery_state": "live", "retry": "Retry transport under the same stable external ID; Lab Operations owns rejection, timeout, and reconciliation.", "human_owner": "Lab Operations", "evidence_refs": [ "spec/as-built.md#function-health-lab-import" ] }, { "id": "sg-11-p1-t2", "from": "one-time-token", "to": "lease", "label": "write exclusive import lease", "condition": "One-time authorization token has the complete attributable payload required for the durable Exclusive import lease write.", "reality": "current", "delivery_state": "live", "retry": "Repeat the durable write only with its original idempotency key; Lab Operations owns conflicting state.", "human_owner": "Lab Operations", "evidence_refs": [ "spec/as-built.md#function-health-lab-import" ] }, { "id": "sg-11-p1-t3", "from": "lease", "to": "isolated-pull", "label": "run isolated pull or file parse", "condition": "Exclusive import lease satisfies the deterministic preconditions declared for Isolated pull or file parse.", "reality": "current", "delivery_state": "live", "retry": "Retry Isolated pull or file parse under the same workflow identity and dedupe key; Lab Operations owns terminal failure.", "human_owner": "Lab Operations", "evidence_refs": [ "spec/as-built.md#function-health-lab-import" ] }, { "id": "sg-11-p1-t4", "from": "isolated-pull", "to": "finalize", "label": "write atomic normalized-result finalization", "condition": "Isolated pull or file parse has the complete attributable payload required for the durable Atomic normalized-result finalization write.", "reality": "current", "delivery_state": "live", "retry": "Repeat the durable write only with its original idempotency key; Lab Operations owns conflicting state.", "human_owner": "Lab Operations", "evidence_refs": [ "spec/as-built.md#function-health-lab-import" ] }, { "id": "sg-11-p1-t5", "from": "finalize", "to": "complete", "label": "complete import terminal state", "condition": "All named predecessor states required by Import terminal state are satisfied or explicitly resolved.", "reality": "current", "delivery_state": "live", "retry": "Reopen only from the attributable unresolved predecessor; Lab Operations owns terminal closure.", "human_owner": "Lab Operations", "evidence_refs": [ "spec/as-built.md#function-health-lab-import" ] }, { "id": "sg-11-p2-t1", "from": "isolated-pull", "to": "mapping-queue", "label": "Lab Operations performs unresolved biomarker mapping queue", "condition": "Isolated pull or file parse presents attributable work to Lab Operations; no automatic approval or silent substitution is permitted.", "reality": "current", "delivery_state": "live", "retry": "Do not auto-approve. Return the same attributable record to Lab Operations with the unresolved reason preserved.", "human_owner": "Lab Operations", "evidence_refs": [ "spec/as-built.md#function-health-lab-import" ] }, { "id": "sg-11-p2-t2", "from": "mapping-queue", "to": "finalize", "label": "write atomic normalized-result finalization", "condition": "Unresolved biomarker mapping queue has the complete attributable payload required for the durable Atomic normalized-result finalization write.", "reality": "current", "delivery_state": "live", "retry": "Repeat the durable write only with its original idempotency key; Lab Operations owns conflicting state.", "human_owner": "Lab Operations", "evidence_refs": [ "spec/as-built.md#function-health-lab-import" ] }, { "id": "sg-11-p3-t1", "from": "isolated-pull", "to": "fail", "label": "write attributable failed import", "condition": "Isolated pull or file parse has the complete attributable payload required for the durable Attributable failed import write.", "reality": "current", "delivery_state": "live", "retry": "Repeat the durable write only with its original idempotency key; Lab Operations owns conflicting state.", "human_owner": "Lab Operations", "evidence_refs": [ "spec/as-built.md#function-health-lab-import" ] }, { "id": "sg-11-p3-t2", "from": "fail", "to": "complete", "label": "complete import terminal state", "condition": "All named predecessor states required by Import terminal state are satisfied or explicitly resolved.", "reality": "current", "delivery_state": "live", "retry": "Reopen only from the attributable unresolved predecessor; Lab Operations owns terminal closure.", "human_owner": "Lab Operations", "evidence_refs": [ "spec/as-built.md#function-health-lab-import" ] }, { "id": "sg-11-p4-t1", "from": "lease", "to": "reap", "label": "run expired lease reaping", "condition": "Exclusive import lease satisfies the deterministic preconditions declared for Expired lease reaping.", "reality": "current", "delivery_state": "live", "retry": "Retry Expired lease reaping under the same workflow identity and dedupe key; Lab Operations owns terminal failure.", "human_owner": "Lab Operations", "evidence_refs": [ "spec/as-built.md#function-health-lab-import" ] }, { "id": "sg-11-p4-t2", "from": "reap", "to": "fail", "label": "write attributable failed import", "condition": "Expired lease reaping has the complete attributable payload required for the durable Attributable failed import write.", "reality": "current", "delivery_state": "live", "retry": "Repeat the durable write only with its original idempotency key; Lab Operations owns conflicting state.", "human_owner": "Lab Operations", "evidence_refs": [ "spec/as-built.md#function-health-lab-import" ] }, { "id": "sg-11-p5-t1", "from": "fail", "to": "lease", "label": "write exclusive import lease", "condition": "Attributable failed import has the complete attributable payload required for the durable Exclusive import lease write.", "reality": "current", "delivery_state": "live", "retry": "Repeat the durable write only with its original idempotency key; Lab Operations owns conflicting state.", "human_owner": "Lab Operations", "evidence_refs": [ "spec/as-built.md#function-health-lab-import" ] } ] }, { "id": "sg-12", "title": "Protocol to pharmacy", "forms": [ "lifecycle-loop", "state-machine" ], "description": "Catalog entry, versioned protocol approval and mapping, isolated sandbox validation, pharmacist review, preparation, lot/label/BUD, QA, and release.", "actors": [ "Protocol Author", "Approver", "Provider", "Pharmacist", "Pharmacy" ], "steps": [ { "id": "catalog-entry", "label": "Medication catalog entry", "kind": "start", "actor": "Protocol Author", "reality": "both", "reads": [], "writes": [ "Medication catalog entry state" ], "evidence_refs": [ "spec/as-built.md#protocols", "spec/as-built.md#internal-fulfillment-network" ] }, { "id": "protocol-version", "label": "Immutable protocol version", "kind": "record", "actor": "Protocol Author", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Immutable protocol version state" ], "evidence_refs": [ "spec/as-built.md#protocols", "spec/as-built.md#internal-fulfillment-network" ] }, { "id": "sandbox-validate", "label": "Isolated TestFlight validation", "kind": "automation", "actor": "Protocol Author", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Isolated TestFlight validation state" ], "evidence_refs": [ "spec/as-built.md#protocols", "spec/as-built.md#internal-fulfillment-network" ] }, { "id": "explicit-promotion", "label": "Explicit live-promotion gate", "kind": "decision", "actor": "Approver", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Explicit live-promotion gate decision" ], "evidence_refs": [ "spec/as-built.md#protocols", "spec/as-built.md#internal-fulfillment-network" ] }, { "id": "approval", "label": "Attributable protocol approval", "kind": "human", "actor": "Approver", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Attributable protocol approval state" ], "evidence_refs": [ "spec/as-built.md#protocols", "spec/as-built.md#internal-fulfillment-network" ] }, { "id": "mapping", "label": "Catalog, dose, state, and pharmacy mapping", "kind": "record", "actor": "Pharmacy", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Catalog, dose, state, and pharmacy mapping state" ], "evidence_refs": [ "spec/as-built.md#protocols", "spec/as-built.md#internal-fulfillment-network" ] }, { "id": "pharmacist-review", "label": "Pharmacist order review", "kind": "human", "actor": "Pharmacist", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Pharmacist order review state" ], "evidence_refs": [ "spec/as-built.md#protocols", "spec/as-built.md#internal-fulfillment-network" ] }, { "id": "prepare", "label": "Compounding preparation", "kind": "state", "actor": "Pharmacy", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Compounding preparation state" ], "evidence_refs": [ "spec/as-built.md#protocols", "spec/as-built.md#internal-fulfillment-network" ] }, { "id": "lot-label-bud", "label": "Lot, label, and supplied BUD", "kind": "record", "actor": "Pharmacy", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Lot, label, and supplied BUD state" ], "evidence_refs": [ "spec/as-built.md#protocols", "spec/as-built.md#internal-fulfillment-network" ] }, { "id": "qa", "label": "Pharmacy quality assurance", "kind": "decision", "actor": "Pharmacist", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Pharmacy quality assurance decision" ], "evidence_refs": [ "spec/as-built.md#protocols", "spec/as-built.md#internal-fulfillment-network" ] }, { "id": "final-release", "label": "Pharmacist final release", "kind": "human", "actor": "Pharmacist", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Pharmacist final release state" ], "evidence_refs": [ "spec/as-built.md#protocols", "spec/as-built.md#internal-fulfillment-network" ] }, { "id": "complete", "label": "Fulfillment ready", "kind": "end", "actor": "Pharmacy", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Fulfillment ready state" ], "evidence_refs": [ "spec/as-built.md#protocols", "spec/as-built.md#internal-fulfillment-network" ] } ], "transitions": [ { "id": "sg-12-p1-t1", "from": "catalog-entry", "to": "protocol-version", "label": "write immutable protocol version", "condition": "Medication catalog entry has the complete attributable payload required for the durable Immutable protocol version write.", "reality": "both", "delivery_state": "partial", "retry": "Repeat the durable write only with its original idempotency key; Protocol Author owns conflicting state.", "human_owner": "Protocol Author", "evidence_refs": [ "spec/as-built.md#protocols", "spec/as-built.md#internal-fulfillment-network" ] }, { "id": "sg-12-p1-t2", "from": "protocol-version", "to": "approval", "label": "Approver performs attributable protocol approval", "condition": "Immutable protocol version presents attributable work to Approver; no automatic approval or silent substitution is permitted.", "reality": "both", "delivery_state": "partial", "retry": "Do not auto-approve. Return the same attributable record to Approver with the unresolved reason preserved.", "human_owner": "Protocol Author", "evidence_refs": [ "spec/as-built.md#protocols", "spec/as-built.md#internal-fulfillment-network" ] }, { "id": "sg-12-p1-t3", "from": "approval", "to": "mapping", "label": "write catalog, dose, state, and pharmacy mapping", "condition": "Attributable protocol approval has the complete attributable payload required for the durable Catalog, dose, state, and pharmacy mapping write.", "reality": "both", "delivery_state": "partial", "retry": "Repeat the durable write only with its original idempotency key; Approver owns conflicting state.", "human_owner": "Approver", "evidence_refs": [ "spec/as-built.md#protocols", "spec/as-built.md#internal-fulfillment-network" ] }, { "id": "sg-12-p1-t4", "from": "mapping", "to": "pharmacist-review", "label": "Pharmacist performs pharmacist order review", "condition": "Catalog, dose, state, and pharmacy mapping presents attributable work to Pharmacist; no automatic approval or silent substitution is permitted.", "reality": "both", "delivery_state": "partial", "retry": "Do not auto-approve. Return the same attributable record to Pharmacist with the unresolved reason preserved.", "human_owner": "Pharmacist", "evidence_refs": [ "spec/as-built.md#protocols", "spec/as-built.md#internal-fulfillment-network" ] }, { "id": "sg-12-p1-t5", "from": "pharmacist-review", "to": "prepare", "label": "enter compounding preparation", "condition": "Pharmacist order review supplies the named facts required to enter Compounding preparation.", "reality": "both", "delivery_state": "partial", "retry": "Resume the same attributable workflow state; Pharmacist owns conflicting or stalled progress.", "human_owner": "Pharmacist", "evidence_refs": [ "spec/as-built.md#protocols", "spec/as-built.md#internal-fulfillment-network" ] }, { "id": "sg-12-p1-t6", "from": "prepare", "to": "lot-label-bud", "label": "write lot, label, and supplied bud", "condition": "Compounding preparation has the complete attributable payload required for the durable Lot, label, and supplied BUD write.", "reality": "both", "delivery_state": "partial", "retry": "Repeat the durable write only with its original idempotency key; Protocol Author owns conflicting state.", "human_owner": "Protocol Author", "evidence_refs": [ "spec/as-built.md#protocols", "spec/as-built.md#internal-fulfillment-network" ] }, { "id": "sg-12-p1-t7", "from": "lot-label-bud", "to": "qa", "label": "evaluate pharmacy quality assurance", "condition": "Pharmacy quality assurance has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "both", "delivery_state": "partial", "retry": "Re-evaluate only after a named input changes; Pharmacist owns unresolved or conflicting eligibility.", "human_owner": "Pharmacist", "evidence_refs": [ "spec/as-built.md#protocols", "spec/as-built.md#internal-fulfillment-network" ] }, { "id": "sg-12-p1-t8", "from": "qa", "to": "final-release", "label": "Pharmacist performs pharmacist final release", "condition": "Pharmacy quality assurance presents attributable work to Pharmacist; no automatic approval or silent substitution is permitted.", "reality": "both", "delivery_state": "partial", "retry": "Do not auto-approve. Return the same attributable record to Pharmacist with the unresolved reason preserved.", "human_owner": "Pharmacist", "evidence_refs": [ "spec/as-built.md#protocols", "spec/as-built.md#internal-fulfillment-network" ] }, { "id": "sg-12-p1-t9", "from": "final-release", "to": "complete", "label": "complete fulfillment ready", "condition": "All named predecessor states required by Fulfillment ready are satisfied or explicitly resolved.", "reality": "both", "delivery_state": "partial", "retry": "Reopen only from the attributable unresolved predecessor; Pharmacist owns terminal closure.", "human_owner": "Pharmacist", "evidence_refs": [ "spec/as-built.md#protocols", "spec/as-built.md#internal-fulfillment-network" ] }, { "id": "sg-12-p2-t1", "from": "protocol-version", "to": "sandbox-validate", "label": "run isolated testflight validation", "condition": "Immutable protocol version satisfies the deterministic preconditions declared for Isolated TestFlight validation.", "reality": "both", "delivery_state": "partial", "retry": "Retry Isolated TestFlight validation under the same workflow identity and dedupe key; Protocol Author owns terminal failure.", "human_owner": "Protocol Author", "evidence_refs": [ "spec/as-built.md#protocols", "spec/as-built.md#internal-fulfillment-network" ] }, { "id": "sg-12-p2-t2", "from": "sandbox-validate", "to": "explicit-promotion", "label": "evaluate explicit live-promotion gate", "condition": "Explicit live-promotion gate has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "both", "delivery_state": "partial", "retry": "Re-evaluate only after a named input changes; Protocol Author owns unresolved or conflicting eligibility.", "human_owner": "Protocol Author", "evidence_refs": [ "spec/as-built.md#protocols", "spec/as-built.md#internal-fulfillment-network" ] }, { "id": "sg-12-p2-t3", "from": "explicit-promotion", "to": "approval", "label": "Approver performs attributable protocol approval", "condition": "Explicit live-promotion gate presents attributable work to Approver; no automatic approval or silent substitution is permitted.", "reality": "both", "delivery_state": "partial", "retry": "Do not auto-approve. Return the same attributable record to Approver with the unresolved reason preserved.", "human_owner": "Approver", "evidence_refs": [ "spec/as-built.md#protocols", "spec/as-built.md#internal-fulfillment-network" ] } ] }, { "id": "sg-13", "title": "3PL shipment contract", "forms": [ "three-rail-transaction", "sequence" ], "description": "Released-order submission, positive acknowledgment or rejection, 3PL label/pack/seal/tender operations, authoritative events, exceptions, and reconciliation.", "actors": [ "Pharmacy", "RonanRx", "3PL", "ShipStation", "Carrier", "Operations", "Patient" ], "steps": [ { "id": "pharmacy-release", "label": "Pharmacist-released fulfillment order", "kind": "start", "actor": "Pharmacy", "reality": "target", "reads": [], "writes": [ "Pharmacist-released fulfillment order state" ], "evidence_refs": [ "spec/business.md#3pl-fulfillment-handoff" ] }, { "id": "release-submit", "label": "Authenticated minimized order submission", "kind": "external", "actor": "RonanRx", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Authenticated minimized order submission state" ], "evidence_refs": [ "spec/business.md#3pl-fulfillment-handoff" ] }, { "id": "positive-ack", "label": "Positive 3PL acknowledgment", "kind": "external", "actor": "3PL", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Positive 3PL acknowledgment state" ], "evidence_refs": [ "spec/business.md#3pl-fulfillment-handoff" ] }, { "id": "reject", "label": "Attributable rejection", "kind": "decision", "actor": "3PL", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Attributable rejection decision" ], "evidence_refs": [ "spec/business.md#3pl-fulfillment-handoff" ] }, { "id": "label-pack-seal", "label": "3PL label, pack, and seal", "kind": "external", "actor": "3PL", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "3PL label, pack, and seal state" ], "evidence_refs": [ "spec/business.md#3pl-fulfillment-handoff" ] }, { "id": "carrier-tender", "label": "Physical carrier tender", "kind": "external", "actor": "3PL", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Physical carrier tender state" ], "evidence_refs": [ "spec/business.md#3pl-fulfillment-handoff" ] }, { "id": "shipment-events", "label": "Authoritative tracking and exception events", "kind": "external", "actor": "Carrier", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Authoritative tracking and exception events state" ], "evidence_refs": [ "spec/business.md#3pl-fulfillment-handoff" ] }, { "id": "event-acceptance", "label": "Authenticated idempotent event acceptance", "kind": "automation", "actor": "RonanRx", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Authenticated idempotent event acceptance state" ], "evidence_refs": [ "spec/business.md#3pl-fulfillment-handoff" ] }, { "id": "patient-milestone", "label": "Patient shipment milestone", "kind": "external", "actor": "RonanRx", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Patient shipment milestone state" ], "evidence_refs": [ "spec/business.md#3pl-fulfillment-handoff" ] }, { "id": "exception-queue", "label": "Owned fulfillment exception", "kind": "human", "actor": "Operations", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Owned fulfillment exception state" ], "evidence_refs": [ "spec/business.md#3pl-fulfillment-handoff" ] }, { "id": "reconcile", "label": "Handoff and carrier reconciliation", "kind": "automation", "actor": "RonanRx", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Handoff and carrier reconciliation state" ], "evidence_refs": [ "spec/business.md#3pl-fulfillment-handoff" ] }, { "id": "complete", "label": "Shipment contract reconciled", "kind": "end", "actor": "Operations", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Shipment contract reconciled state" ], "evidence_refs": [ "spec/business.md#3pl-fulfillment-handoff" ] } ], "transitions": [ { "id": "sg-13-p1-t1", "from": "pharmacy-release", "to": "release-submit", "label": "submit authenticated minimized order submission", "condition": "Target-only and not deployed: Pharmacist-released fulfillment order supplies the authenticated external contract and stable source identifiers required by Authenticated minimized order submission.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Retry transport under the same stable external ID; Operations owns rejection, timeout, and reconciliation.", "human_owner": "Operations", "evidence_refs": [ "spec/business.md#3pl-fulfillment-handoff" ] }, { "id": "sg-13-p1-t2", "from": "release-submit", "to": "positive-ack", "label": "3PL accepts the released order", "condition": "Target-only and not deployed: the 3PL authenticates the minimized order request, binds it to the stable fulfillment ID, and accepts responsibility for physical fulfillment.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Retry transport under the same stable external ID; Operations owns rejection, timeout, and reconciliation.", "human_owner": "Operations", "evidence_refs": [ "spec/business.md#3pl-fulfillment-handoff" ] }, { "id": "sg-13-p1-t3", "from": "positive-ack", "to": "label-pack-seal", "label": "3PL prints label, packs, and seals", "condition": "Target-only and not deployed: a positive 3PL acknowledgment authorizes the 3PL to purchase postage, print the carrier label, pack the order, and seal the parcel.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Retry transport under the same stable external ID; Operations owns rejection, timeout, and reconciliation.", "human_owner": "Operations", "evidence_refs": [ "spec/business.md#3pl-fulfillment-handoff" ] }, { "id": "sg-13-p1-t4", "from": "label-pack-seal", "to": "carrier-tender", "label": "3PL tenders the sealed parcel", "condition": "Target-only and not deployed: the 3PL has completed packing, sealing, postage purchase, and carrier-label printing before tendering the parcel to the carrier.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Retry transport under the same stable external ID; Operations owns rejection, timeout, and reconciliation.", "human_owner": "Operations", "evidence_refs": [ "spec/business.md#3pl-fulfillment-handoff" ] }, { "id": "sg-13-p1-t5", "from": "carrier-tender", "to": "shipment-events", "label": "carrier and 3PL emit authoritative events", "condition": "Target-only and not deployed: carrier tender establishes the shipment identity used by the 3PL and carrier to emit attributable tracking, delivery, and exception events.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Retry transport under the same stable external ID; Operations owns rejection, timeout, and reconciliation.", "human_owner": "Operations", "evidence_refs": [ "spec/business.md#3pl-fulfillment-handoff" ] }, { "id": "sg-13-p1-t6", "from": "shipment-events", "to": "event-acceptance", "label": "run authenticated idempotent event acceptance", "condition": "Target-only and not deployed: Authoritative tracking and exception events satisfies the deterministic preconditions declared for Authenticated idempotent event acceptance.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Retry Authenticated idempotent event acceptance under the same workflow identity and dedupe key; Operations owns terminal failure.", "human_owner": "Operations", "evidence_refs": [ "spec/business.md#3pl-fulfillment-handoff" ] }, { "id": "sg-13-p1-t7", "from": "event-acceptance", "to": "patient-milestone", "label": "publish verified shipment milestone", "condition": "Target-only and not deployed: RonanRx publishes a patient-facing milestone only after authenticating, deduplicating, and matching the authoritative 3PL or carrier event.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Retry transport under the same stable external ID; Operations owns rejection, timeout, and reconciliation.", "human_owner": "Operations", "evidence_refs": [ "spec/business.md#3pl-fulfillment-handoff" ] }, { "id": "sg-13-p1-t8", "from": "patient-milestone", "to": "reconcile", "label": "run handoff and carrier reconciliation", "condition": "Target-only and not deployed: Patient shipment milestone satisfies the deterministic preconditions declared for Handoff and carrier reconciliation.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Retry Handoff and carrier reconciliation under the same workflow identity and dedupe key; Operations owns terminal failure.", "human_owner": "Operations", "evidence_refs": [ "spec/business.md#3pl-fulfillment-handoff" ] }, { "id": "sg-13-p1-t9", "from": "reconcile", "to": "complete", "label": "complete shipment contract reconciled", "condition": "Target-only and not deployed: All named predecessor states required by Shipment contract reconciled are satisfied or explicitly resolved.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Reopen only from the attributable unresolved predecessor; Operations owns terminal closure.", "human_owner": "Operations", "evidence_refs": [ "spec/business.md#3pl-fulfillment-handoff" ] }, { "id": "sg-13-p2-t1", "from": "reject", "to": "exception-queue", "label": "Operations performs owned fulfillment exception", "condition": "Target-only and not deployed: Attributable rejection presents attributable work to Operations; no automatic approval or silent substitution is permitted.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Do not auto-approve. Return the same attributable record to Operations with the unresolved reason preserved.", "human_owner": "Operations", "evidence_refs": [ "spec/business.md#3pl-fulfillment-handoff" ] }, { "id": "sg-13-p2-t2", "from": "exception-queue", "to": "reconcile", "label": "run handoff and carrier reconciliation", "condition": "Target-only and not deployed: Owned fulfillment exception satisfies the deterministic preconditions declared for Handoff and carrier reconciliation.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Retry Handoff and carrier reconciliation under the same workflow identity and dedupe key; Operations owns terminal failure.", "human_owner": "Operations", "evidence_refs": [ "spec/business.md#3pl-fulfillment-handoff" ] }, { "id": "sg-13-p3-t1", "from": "event-acceptance", "to": "exception-queue", "label": "Operations performs owned fulfillment exception", "condition": "Target-only and not deployed: Authenticated idempotent event acceptance presents attributable work to Operations; no automatic approval or silent substitution is permitted.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Do not auto-approve. Return the same attributable record to Operations with the unresolved reason preserved.", "human_owner": "Operations", "evidence_refs": [ "spec/business.md#3pl-fulfillment-handoff" ] }, { "id": "sg-13-p4-t1", "from": "reconcile", "to": "release-submit", "label": "submit authenticated minimized order submission", "condition": "Target-only and not deployed: Handoff and carrier reconciliation supplies the authenticated external contract and stable source identifiers required by Authenticated minimized order submission.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Retry transport under the same stable external ID; Operations owns rejection, timeout, and reconciliation.", "human_owner": "Operations", "evidence_refs": [ "spec/business.md#3pl-fulfillment-handoff" ] }, { "id": "sg-13-p5-t1", "from": "reconcile", "to": "shipment-events", "label": "submit authoritative tracking and exception events", "condition": "Target-only and not deployed: Handoff and carrier reconciliation supplies the authenticated external contract and stable source identifiers required by Authoritative tracking and exception events.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Retry transport under the same stable external ID; Operations owns rejection, timeout, and reconciliation.", "human_owner": "Operations", "evidence_refs": [ "spec/business.md#3pl-fulfillment-handoff" ] }, { "id": "sg-13-reject", "from": "release-submit", "to": "reject", "label": "reject", "condition": "The 3PL does not accept the released order.", "reality": "target", "delivery_state": "planned", "retry": "Correct and retry under the same stable fulfillment ID; never duplicate fulfillment.", "human_owner": "Fulfillment Operations", "evidence_refs": [ "spec/business.md#3pl-fulfillment-handoff" ] }, { "id": "sg-13-exception", "from": "shipment-events", "to": "exception-queue", "label": "exception", "condition": "A failed, stale, voided, replaced, or carrier exception event arrives.", "reality": "target", "delivery_state": "planned", "retry": "Attributable resolution and reconciliation.", "human_owner": "Fulfillment Operations", "evidence_refs": [ "spec/business.md#3pl-fulfillment-handoff" ] } ] }, { "id": "sg-14", "title": "Billing entities", "forms": [ "entity-sequence", "sequence" ], "description": "Membership and Rx charges, authoritative webhooks, RonanRx platform economics, Connect payout, refunds, and ledger reconciliation.", "actors": [ "Patient", "RonanRx", "Stripe", "Provider", "Billing Operations" ], "steps": [ { "id": "billable-event", "label": "Billable domain event", "kind": "start", "actor": "RonanRx", "reality": "both", "reads": [], "writes": [ "Billable domain event state" ], "evidence_refs": [ "spec/as-built.md#billing-architecture" ] }, { "id": "membership-charge", "label": "Membership charge", "kind": "external", "actor": "Stripe", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Membership charge state" ], "evidence_refs": [ "spec/as-built.md#billing-architecture" ] }, { "id": "rx-charge", "label": "Prescription charge", "kind": "external", "actor": "Stripe", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Prescription charge state" ], "evidence_refs": [ "spec/as-built.md#billing-architecture" ] }, { "id": "webhook-ledger", "label": "Authoritative webhook ledger", "kind": "record", "actor": "RonanRx", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Authoritative webhook ledger state" ], "evidence_refs": [ "spec/as-built.md#billing-architecture" ] }, { "id": "platform-fee", "label": "Explicit RonanRx fee", "kind": "record", "actor": "RonanRx", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Explicit RonanRx fee state" ], "evidence_refs": [ "spec/as-built.md#billing-architecture" ] }, { "id": "provider-payout", "label": "Flat provider Connect payout", "kind": "external", "actor": "Stripe", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Flat provider Connect payout state" ], "evidence_refs": [ "spec/as-built.md#billing-architecture" ] }, { "id": "refund", "label": "Attributable refund or reversal", "kind": "external", "actor": "Stripe", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Attributable refund or reversal state" ], "evidence_refs": [ "spec/as-built.md#billing-architecture" ] }, { "id": "reconcile", "label": "Money-ledger reconciliation", "kind": "automation", "actor": "Billing Operations", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Money-ledger reconciliation state" ], "evidence_refs": [ "spec/as-built.md#billing-architecture" ] }, { "id": "complete", "label": "Billing event reconciled", "kind": "end", "actor": "RonanRx", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Billing event reconciled state" ], "evidence_refs": [ "spec/as-built.md#billing-architecture" ] } ], "transitions": [ { "id": "sg-14-p1-t1", "from": "billable-event", "to": "membership-charge", "label": "submit membership charge", "condition": "Billable domain event supplies the authenticated external contract and stable source identifiers required by Membership charge.", "reality": "both", "delivery_state": "partial", "retry": "Retry transport under the same stable external ID; Provider owns rejection, timeout, and reconciliation.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#billing-architecture" ] }, { "id": "sg-14-p1-t2", "from": "membership-charge", "to": "webhook-ledger", "label": "write authoritative webhook ledger", "condition": "Membership charge has the complete attributable payload required for the durable Authoritative webhook ledger write.", "reality": "both", "delivery_state": "partial", "retry": "Repeat the durable write only with its original idempotency key; Provider owns conflicting state.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#billing-architecture" ] }, { "id": "sg-14-p1-t3", "from": "webhook-ledger", "to": "platform-fee", "label": "write explicit ronanrx fee", "condition": "Authoritative webhook ledger has the complete attributable payload required for the durable Explicit RonanRx fee write.", "reality": "both", "delivery_state": "partial", "retry": "Repeat the durable write only with its original idempotency key; Provider owns conflicting state.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#billing-architecture" ] }, { "id": "sg-14-p1-t4", "from": "platform-fee", "to": "provider-payout", "label": "submit flat provider connect payout", "condition": "Explicit RonanRx fee supplies the authenticated external contract and stable source identifiers required by Flat provider Connect payout.", "reality": "both", "delivery_state": "partial", "retry": "Retry transport under the same stable external ID; Provider owns rejection, timeout, and reconciliation.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#billing-architecture" ] }, { "id": "sg-14-p1-t5", "from": "provider-payout", "to": "reconcile", "label": "run money-ledger reconciliation", "condition": "Flat provider Connect payout satisfies the deterministic preconditions declared for Money-ledger reconciliation.", "reality": "both", "delivery_state": "partial", "retry": "Retry Money-ledger reconciliation under the same workflow identity and dedupe key; Billing Operations owns terminal failure.", "human_owner": "Billing Operations", "evidence_refs": [ "spec/as-built.md#billing-architecture" ] }, { "id": "sg-14-p1-t6", "from": "reconcile", "to": "complete", "label": "complete billing event reconciled", "condition": "All named predecessor states required by Billing event reconciled are satisfied or explicitly resolved.", "reality": "both", "delivery_state": "partial", "retry": "Reopen only from the attributable unresolved predecessor; Billing Operations owns terminal closure.", "human_owner": "Billing Operations", "evidence_refs": [ "spec/as-built.md#billing-architecture" ] }, { "id": "sg-14-p2-t1", "from": "billable-event", "to": "rx-charge", "label": "submit prescription charge", "condition": "Billable domain event supplies the authenticated external contract and stable source identifiers required by Prescription charge.", "reality": "both", "delivery_state": "partial", "retry": "Retry transport under the same stable external ID; Provider owns rejection, timeout, and reconciliation.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#billing-architecture" ] }, { "id": "sg-14-p2-t2", "from": "rx-charge", "to": "webhook-ledger", "label": "write authoritative webhook ledger", "condition": "Prescription charge has the complete attributable payload required for the durable Authoritative webhook ledger write.", "reality": "both", "delivery_state": "partial", "retry": "Repeat the durable write only with its original idempotency key; Provider owns conflicting state.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#billing-architecture" ] }, { "id": "sg-14-p3-t1", "from": "webhook-ledger", "to": "refund", "label": "submit attributable refund or reversal", "condition": "Authoritative webhook ledger supplies the authenticated external contract and stable source identifiers required by Attributable refund or reversal.", "reality": "both", "delivery_state": "partial", "retry": "Retry transport under the same stable external ID; Provider owns rejection, timeout, and reconciliation.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#billing-architecture" ] }, { "id": "sg-14-p3-t2", "from": "refund", "to": "reconcile", "label": "run money-ledger reconciliation", "condition": "Attributable refund or reversal satisfies the deterministic preconditions declared for Money-ledger reconciliation.", "reality": "both", "delivery_state": "partial", "retry": "Retry Money-ledger reconciliation under the same workflow identity and dedupe key; Billing Operations owns terminal failure.", "human_owner": "Billing Operations", "evidence_refs": [ "spec/as-built.md#billing-architecture" ] } ] }, { "id": "sg-15", "title": "Urgent support", "forms": [ "state-machine", "decision-tree" ], "description": "Deterministic safety screening, holds, governed replies, human contact, attributable resolution evidence, and hold release.", "actors": [ "Patient", "Rails", "Clinical Operations", "Provider" ], "steps": [ { "id": "inbound", "label": "Inbound patient message", "kind": "start", "actor": "Patient", "reality": "both", "reads": [], "writes": [ "Inbound patient message state" ], "evidence_refs": [ "spec/as-built.md#urgent-text-escalation" ] }, { "id": "deterministic-screen", "label": "Deterministic urgent screen", "kind": "automation", "actor": "Rails", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Deterministic urgent screen state" ], "evidence_refs": [ "spec/as-built.md#urgent-text-escalation" ] }, { "id": "safety-hold", "label": "Conversation safety hold", "kind": "record", "actor": "Rails", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Conversation safety hold state" ], "evidence_refs": [ "spec/as-built.md#urgent-text-escalation" ] }, { "id": "governed-reply", "label": "Frozen governed safety reply", "kind": "external", "actor": "Rails", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Frozen governed safety reply state" ], "evidence_refs": [ "spec/as-built.md#urgent-text-escalation" ] }, { "id": "human-contact", "label": "Responsible human contact", "kind": "human", "actor": "Clinical Operations", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Responsible human contact state" ], "evidence_refs": [ "spec/as-built.md#urgent-text-escalation" ] }, { "id": "clinical-action", "label": "Attributable clinical or service action", "kind": "human", "actor": "Provider", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Attributable clinical or service action state" ], "evidence_refs": [ "spec/as-built.md#urgent-text-escalation" ] }, { "id": "resolution", "label": "Resolution evidence", "kind": "record", "actor": "Rails", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Resolution evidence state" ], "evidence_refs": [ "spec/as-built.md#urgent-text-escalation" ] }, { "id": "release-hold", "label": "Attributable hold release", "kind": "human", "actor": "Clinical Operations", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Attributable hold release state" ], "evidence_refs": [ "spec/as-built.md#urgent-text-escalation" ] }, { "id": "complete", "label": "Safety incident closed", "kind": "end", "actor": "Rails", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Safety incident closed state" ], "evidence_refs": [ "spec/as-built.md#urgent-text-escalation" ] } ], "transitions": [ { "id": "sg-15-p1-t1", "from": "inbound", "to": "deterministic-screen", "label": "run deterministic urgent screen", "condition": "Inbound patient message satisfies the deterministic preconditions declared for Deterministic urgent screen.", "reality": "both", "delivery_state": "partial", "retry": "Retry Deterministic urgent screen under the same workflow identity and dedupe key; Clinical Operations owns terminal failure.", "human_owner": "Clinical Operations", "evidence_refs": [ "spec/as-built.md#urgent-text-escalation" ] }, { "id": "sg-15-not-urgent", "from": "deterministic-screen", "to": "complete", "label": "not urgent; return to normal routing", "condition": "The deterministic governed screen finds no urgent or emergency match and no existing safety hold requires escalation.", "reality": "both", "delivery_state": "partial", "retry": "Normal routing may reevaluate only on a new inbound event or changed governed safety state.", "human_owner": "Clinical Operations", "evidence_refs": [ "spec/as-built.md#urgent-text-escalation" ] }, { "id": "sg-15-urgent", "from": "deterministic-screen", "to": "safety-hold", "label": "urgent match; latch safety hold", "condition": "The deterministic screen matches a governed urgent tier or an existing incident requires the hold to remain latched.", "reality": "both", "delivery_state": "partial", "retry": "Never auto-release. Clinical Operations resolves classification or hold-state conflicts.", "human_owner": "Clinical Operations", "evidence_refs": [ "spec/as-built.md#urgent-text-escalation" ] }, { "id": "sg-15-p2-t2", "from": "safety-hold", "to": "governed-reply", "label": "submit frozen governed safety reply", "condition": "Conversation safety hold supplies the authenticated external contract and stable source identifiers required by Frozen governed safety reply.", "reality": "both", "delivery_state": "partial", "retry": "Retry transport under the same stable external ID; Clinical Operations owns rejection, timeout, and reconciliation.", "human_owner": "Clinical Operations", "evidence_refs": [ "spec/as-built.md#urgent-text-escalation" ] }, { "id": "sg-15-p3-t1", "from": "safety-hold", "to": "human-contact", "label": "Clinical Operations performs responsible human contact", "condition": "Conversation safety hold presents attributable work to Clinical Operations; no automatic approval or silent substitution is permitted.", "reality": "both", "delivery_state": "partial", "retry": "Do not auto-approve. Return the same attributable record to Clinical Operations with the unresolved reason preserved.", "human_owner": "Clinical Operations", "evidence_refs": [ "spec/as-built.md#urgent-text-escalation" ] }, { "id": "sg-15-p3-t2", "from": "human-contact", "to": "clinical-action", "label": "Provider performs attributable clinical or service action", "condition": "Responsible human contact presents attributable work to Provider; no automatic approval or silent substitution is permitted.", "reality": "both", "delivery_state": "partial", "retry": "Do not auto-approve. Return the same attributable record to Provider with the unresolved reason preserved.", "human_owner": "Clinical Operations", "evidence_refs": [ "spec/as-built.md#urgent-text-escalation" ] }, { "id": "sg-15-p3-t3", "from": "clinical-action", "to": "resolution", "label": "write resolution evidence", "condition": "Attributable clinical or service action has the complete attributable payload required for the durable Resolution evidence write.", "reality": "both", "delivery_state": "partial", "retry": "Repeat the durable write only with its original idempotency key; Provider owns conflicting state.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#urgent-text-escalation" ] }, { "id": "sg-15-p3-t4", "from": "resolution", "to": "release-hold", "label": "Clinical Operations performs attributable hold release", "condition": "Resolution evidence presents attributable work to Clinical Operations; no automatic approval or silent substitution is permitted.", "reality": "both", "delivery_state": "partial", "retry": "Do not auto-approve. Return the same attributable record to Clinical Operations with the unresolved reason preserved.", "human_owner": "Clinical Operations", "evidence_refs": [ "spec/as-built.md#urgent-text-escalation" ] }, { "id": "sg-15-p3-t5", "from": "release-hold", "to": "complete", "label": "complete safety incident closed", "condition": "All named predecessor states required by Safety incident closed are satisfied or explicitly resolved.", "reality": "both", "delivery_state": "partial", "retry": "Reopen only from the attributable unresolved predecessor; Clinical Operations owns terminal closure.", "human_owner": "Clinical Operations", "evidence_refs": [ "spec/as-built.md#urgent-text-escalation" ] }, { "id": "sg-15-p4-t1", "from": "human-contact", "to": "resolution", "label": "write resolution evidence", "condition": "Responsible human contact has the complete attributable payload required for the durable Resolution evidence write.", "reality": "both", "delivery_state": "partial", "retry": "Repeat the durable write only with its original idempotency key; Clinical Operations owns conflicting state.", "human_owner": "Clinical Operations", "evidence_refs": [ "spec/as-built.md#urgent-text-escalation" ] }, { "id": "sg-15-p5-t1", "from": "resolution", "to": "human-contact", "label": "Clinical Operations performs responsible human contact", "condition": "Resolution evidence presents attributable work to Clinical Operations; no automatic approval or silent substitution is permitted.", "reality": "both", "delivery_state": "partial", "retry": "Do not auto-approve. Return the same attributable record to Clinical Operations with the unresolved reason preserved.", "human_owner": "Clinical Operations", "evidence_refs": [ "spec/as-built.md#urgent-text-escalation" ] } ] }, { "id": "sg-16", "title": "Device and iOS sync", "forms": [ "data-flow", "internal-pipeline" ], "description": "Consent, OAuth or HealthKit authorization, local outbox and webhook/sync delivery, allowlist, normalization, dedupe, governed consumers, retries, and revoke.", "actors": [ "Patient", "RonanRx iOS", "Device Vendor", "Rails", "EHR" ], "steps": [ { "id": "patient-consent", "label": "Affirmative patient authorization", "kind": "start", "actor": "Patient", "reality": "both", "reads": [], "writes": [ "Affirmative patient authorization state" ], "evidence_refs": [ "spec/as-built.md#app-data-collection", "spec/as-built.md#ronanrx-ios" ] }, { "id": "oauth-healthkit", "label": "OAuth or HealthKit grant", "kind": "external", "actor": "RonanRx iOS", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "OAuth or HealthKit grant state" ], "evidence_refs": [ "spec/as-built.md#app-data-collection", "spec/as-built.md#ronanrx-ios" ] }, { "id": "local-outbox", "label": "Durable local outbox", "kind": "record", "actor": "RonanRx iOS", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Durable local outbox state" ], "evidence_refs": [ "spec/as-built.md#app-data-collection", "spec/as-built.md#ronanrx-ios" ] }, { "id": "sync-or-webhook", "label": "Sync or vendor webhook", "kind": "external", "actor": "Device Vendor", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Sync or vendor webhook state" ], "evidence_refs": [ "spec/as-built.md#app-data-collection", "spec/as-built.md#ronanrx-ios" ] }, { "id": "allowlist", "label": "Approved data-type allowlist", "kind": "decision", "actor": "Rails", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Approved data-type allowlist decision" ], "evidence_refs": [ "spec/as-built.md#app-data-collection", "spec/as-built.md#ronanrx-ios" ] }, { "id": "normalize-dedupe", "label": "Source-aware normalize and dedupe", "kind": "automation", "actor": "Rails", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Source-aware normalize and dedupe state" ], "evidence_refs": [ "spec/as-built.md#app-data-collection", "spec/as-built.md#ronanrx-ios" ] }, { "id": "consumer-projection", "label": "EHR and care-flow projection", "kind": "record", "actor": "EHR", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "EHR and care-flow projection state" ], "evidence_refs": [ "spec/as-built.md#app-data-collection", "spec/as-built.md#ronanrx-ios" ] }, { "id": "retry-queue", "label": "Idempotent delivery retry", "kind": "automation", "actor": "Rails", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Idempotent delivery retry state" ], "evidence_refs": [ "spec/as-built.md#app-data-collection", "spec/as-built.md#ronanrx-ios" ] }, { "id": "revoke", "label": "Authorization revoke and future-sync stop", "kind": "human", "actor": "Patient", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Authorization revoke and future-sync stop state" ], "evidence_refs": [ "spec/as-built.md#app-data-collection", "spec/as-built.md#ronanrx-ios" ] }, { "id": "complete", "label": "Device sync terminal state", "kind": "end", "actor": "Rails", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Device sync terminal state state" ], "evidence_refs": [ "spec/as-built.md#app-data-collection", "spec/as-built.md#ronanrx-ios" ] } ], "transitions": [ { "id": "sg-16-p1-t1", "from": "patient-consent", "to": "oauth-healthkit", "label": "submit oauth or healthkit grant", "condition": "Affirmative patient authorization supplies the authenticated external contract and stable source identifiers required by OAuth or HealthKit grant.", "reality": "both", "delivery_state": "partial", "retry": "Retry transport under the same stable external ID; RonanRx iOS owns rejection, timeout, and reconciliation.", "human_owner": "RonanRx iOS", "evidence_refs": [ "spec/as-built.md#app-data-collection", "spec/as-built.md#ronanrx-ios" ] }, { "id": "sg-16-p1-t2", "from": "oauth-healthkit", "to": "local-outbox", "label": "write durable local outbox", "condition": "OAuth or HealthKit grant has the complete attributable payload required for the durable Durable local outbox write.", "reality": "both", "delivery_state": "partial", "retry": "Repeat the durable write only with its original idempotency key; RonanRx iOS owns conflicting state.", "human_owner": "RonanRx iOS", "evidence_refs": [ "spec/as-built.md#app-data-collection", "spec/as-built.md#ronanrx-ios" ] }, { "id": "sg-16-p1-t3", "from": "local-outbox", "to": "sync-or-webhook", "label": "submit sync or vendor webhook", "condition": "Durable local outbox supplies the authenticated external contract and stable source identifiers required by Sync or vendor webhook.", "reality": "both", "delivery_state": "partial", "retry": "Retry transport under the same stable external ID; Device Vendor owns rejection, timeout, and reconciliation.", "human_owner": "Device Vendor", "evidence_refs": [ "spec/as-built.md#app-data-collection", "spec/as-built.md#ronanrx-ios" ] }, { "id": "sg-16-p1-t4", "from": "sync-or-webhook", "to": "allowlist", "label": "evaluate approved data-type allowlist", "condition": "Approved data-type allowlist has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "both", "delivery_state": "partial", "retry": "Re-evaluate only after a named input changes; Rails owns unresolved or conflicting eligibility.", "human_owner": "Rails", "evidence_refs": [ "spec/as-built.md#app-data-collection", "spec/as-built.md#ronanrx-ios" ] }, { "id": "sg-16-p1-t5", "from": "allowlist", "to": "normalize-dedupe", "label": "run source-aware normalize and dedupe", "condition": "Approved data-type allowlist satisfies the deterministic preconditions declared for Source-aware normalize and dedupe.", "reality": "both", "delivery_state": "partial", "retry": "Retry Source-aware normalize and dedupe under the same workflow identity and dedupe key; Rails owns terminal failure.", "human_owner": "Rails", "evidence_refs": [ "spec/as-built.md#app-data-collection", "spec/as-built.md#ronanrx-ios" ] }, { "id": "sg-16-p1-t6", "from": "normalize-dedupe", "to": "consumer-projection", "label": "write ehr and care-flow projection", "condition": "Source-aware normalize and dedupe has the complete attributable payload required for the durable EHR and care-flow projection write.", "reality": "both", "delivery_state": "partial", "retry": "Repeat the durable write only with its original idempotency key; EHR owns conflicting state.", "human_owner": "EHR", "evidence_refs": [ "spec/as-built.md#app-data-collection", "spec/as-built.md#ronanrx-ios" ] }, { "id": "sg-16-p1-t7", "from": "consumer-projection", "to": "complete", "label": "complete device sync terminal state", "condition": "All named predecessor states required by Device sync terminal state are satisfied or explicitly resolved.", "reality": "both", "delivery_state": "partial", "retry": "Reopen only from the attributable unresolved predecessor; Rails owns terminal closure.", "human_owner": "Rails", "evidence_refs": [ "spec/as-built.md#app-data-collection", "spec/as-built.md#ronanrx-ios" ] }, { "id": "sg-16-p2-t1", "from": "oauth-healthkit", "to": "sync-or-webhook", "label": "submit sync or vendor webhook", "condition": "OAuth or HealthKit grant supplies the authenticated external contract and stable source identifiers required by Sync or vendor webhook.", "reality": "both", "delivery_state": "partial", "retry": "Retry transport under the same stable external ID; Device Vendor owns rejection, timeout, and reconciliation.", "human_owner": "Device Vendor", "evidence_refs": [ "spec/as-built.md#app-data-collection", "spec/as-built.md#ronanrx-ios" ] }, { "id": "sg-16-p3-t1", "from": "sync-or-webhook", "to": "retry-queue", "label": "run idempotent delivery retry", "condition": "Sync or vendor webhook satisfies the deterministic preconditions declared for Idempotent delivery retry.", "reality": "both", "delivery_state": "partial", "retry": "Retry Idempotent delivery retry under the same workflow identity and dedupe key; Rails owns terminal failure.", "human_owner": "Rails", "evidence_refs": [ "spec/as-built.md#app-data-collection", "spec/as-built.md#ronanrx-ios" ] }, { "id": "sg-16-p4-t1", "from": "patient-consent", "to": "revoke", "label": "Patient performs authorization revoke and future-sync stop", "condition": "Affirmative patient authorization presents attributable work to Patient; no automatic approval or silent substitution is permitted.", "reality": "both", "delivery_state": "partial", "retry": "Do not auto-approve. Return the same attributable record to Patient with the unresolved reason preserved.", "human_owner": "Patient", "evidence_refs": [ "spec/as-built.md#app-data-collection", "spec/as-built.md#ronanrx-ios" ] }, { "id": "sg-16-p4-t2", "from": "revoke", "to": "complete", "label": "complete device sync terminal state", "condition": "All named predecessor states required by Device sync terminal state are satisfied or explicitly resolved.", "reality": "both", "delivery_state": "partial", "retry": "Reopen only from the attributable unresolved predecessor; Rails owns terminal closure.", "human_owner": "Rails", "evidence_refs": [ "spec/as-built.md#app-data-collection", "spec/as-built.md#ronanrx-ios" ] } ] }, { "id": "sg-17", "title": "Health-history projection", "forms": [ "data-flow", "state-machine" ], "description": "Known-fact prefill, one-question missing intake, autosave, completion, provenance-preserving EHR projection, review, and conflict resolution.", "actors": [ "Patient", "Rails", "Provider", "EHR" ], "steps": [ { "id": "plan-activation", "label": "Governed question-plan activation", "kind": "start", "actor": "Rails", "reality": "both", "reads": [], "writes": [ "Governed question-plan activation state" ], "evidence_refs": [ "spec/as-built.md#health-history-questionnaire" ] }, { "id": "known-fact-prefill", "label": "Known-fact prefill", "kind": "automation", "actor": "Rails", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Known-fact prefill state" ], "evidence_refs": [ "spec/as-built.md#health-history-questionnaire" ] }, { "id": "missing-questions", "label": "Required unanswered question", "kind": "decision", "actor": "Rails", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Required unanswered question decision" ], "evidence_refs": [ "spec/as-built.md#health-history-questionnaire" ] }, { "id": "patient-answer", "label": "Patient answer or explicit status", "kind": "human", "actor": "Patient", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Patient answer or explicit status state" ], "evidence_refs": [ "spec/as-built.md#health-history-questionnaire" ] }, { "id": "autosave", "label": "Per-answer autosave", "kind": "record", "actor": "Rails", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Per-answer autosave state" ], "evidence_refs": [ "spec/as-built.md#health-history-questionnaire" ] }, { "id": "completion", "label": "Question-plan completion", "kind": "decision", "actor": "Rails", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Question-plan completion decision" ], "evidence_refs": [ "spec/as-built.md#health-history-questionnaire" ] }, { "id": "ehr-projection", "label": "Provenance-preserving EHR projection", "kind": "record", "actor": "EHR", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Provenance-preserving EHR projection state" ], "evidence_refs": [ "spec/as-built.md#health-history-questionnaire" ] }, { "id": "provider-review", "label": "Provider review", "kind": "human", "actor": "Provider", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Provider review state" ], "evidence_refs": [ "spec/as-built.md#health-history-questionnaire" ] }, { "id": "conflict-resolution", "label": "Attributable conflict resolution", "kind": "record", "actor": "EHR", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Attributable conflict resolution state" ], "evidence_refs": [ "spec/as-built.md#health-history-questionnaire" ] }, { "id": "complete", "label": "Health history reconciled", "kind": "end", "actor": "EHR", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Health history reconciled state" ], "evidence_refs": [ "spec/as-built.md#health-history-questionnaire" ] } ], "transitions": [ { "id": "sg-17-p1-t1", "from": "plan-activation", "to": "known-fact-prefill", "label": "run known-fact prefill", "condition": "Governed question-plan activation satisfies the deterministic preconditions declared for Known-fact prefill.", "reality": "both", "delivery_state": "partial", "retry": "Retry Known-fact prefill under the same workflow identity and dedupe key; Provider owns terminal failure.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#health-history-questionnaire" ] }, { "id": "sg-17-p1-t2", "from": "known-fact-prefill", "to": "missing-questions", "label": "evaluate required unanswered question", "condition": "Required unanswered question has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "both", "delivery_state": "partial", "retry": "Re-evaluate only after a named input changes; Provider owns unresolved or conflicting eligibility.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#health-history-questionnaire" ] }, { "id": "sg-17-p1-t3", "from": "missing-questions", "to": "patient-answer", "label": "Patient performs patient answer or explicit status", "condition": "Required unanswered question presents attributable work to Patient; no automatic approval or silent substitution is permitted.", "reality": "both", "delivery_state": "partial", "retry": "Do not auto-approve. Return the same attributable record to Patient with the unresolved reason preserved.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#health-history-questionnaire" ] }, { "id": "sg-17-p1-t4", "from": "patient-answer", "to": "autosave", "label": "write per-answer autosave", "condition": "Patient answer or explicit status has the complete attributable payload required for the durable Per-answer autosave write.", "reality": "both", "delivery_state": "partial", "retry": "Repeat the durable write only with its original idempotency key; Provider owns conflicting state.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#health-history-questionnaire" ] }, { "id": "sg-17-p1-t5", "from": "autosave", "to": "completion", "label": "evaluate question-plan completion", "condition": "Question-plan completion has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "both", "delivery_state": "partial", "retry": "Re-evaluate only after a named input changes; Provider owns unresolved or conflicting eligibility.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#health-history-questionnaire" ] }, { "id": "sg-17-p2-t1", "from": "completion", "to": "missing-questions", "label": "evaluate required unanswered question", "condition": "Required unanswered question has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "both", "delivery_state": "partial", "retry": "Re-evaluate only after a named input changes; Provider owns unresolved or conflicting eligibility.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#health-history-questionnaire" ] }, { "id": "sg-17-p3-t1", "from": "completion", "to": "ehr-projection", "label": "write provenance-preserving ehr projection", "condition": "Question-plan completion has the complete attributable payload required for the durable Provenance-preserving EHR projection write.", "reality": "both", "delivery_state": "partial", "retry": "Repeat the durable write only with its original idempotency key; Provider owns conflicting state.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#health-history-questionnaire" ] }, { "id": "sg-17-p3-t2", "from": "ehr-projection", "to": "provider-review", "label": "Provider performs provider review", "condition": "Provenance-preserving EHR projection presents attributable work to Provider; no automatic approval or silent substitution is permitted.", "reality": "both", "delivery_state": "partial", "retry": "Do not auto-approve. Return the same attributable record to Provider with the unresolved reason preserved.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#health-history-questionnaire" ] }, { "id": "sg-17-p3-t3", "from": "provider-review", "to": "complete", "label": "complete health history reconciled", "condition": "All named predecessor states required by Health history reconciled are satisfied or explicitly resolved.", "reality": "both", "delivery_state": "partial", "retry": "Reopen only from the attributable unresolved predecessor; Provider owns terminal closure.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#health-history-questionnaire" ] }, { "id": "sg-17-p4-t1", "from": "provider-review", "to": "conflict-resolution", "label": "write attributable conflict resolution", "condition": "Provider review has the complete attributable payload required for the durable Attributable conflict resolution write.", "reality": "both", "delivery_state": "partial", "retry": "Repeat the durable write only with its original idempotency key; Provider owns conflicting state.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#health-history-questionnaire" ] }, { "id": "sg-17-p4-t2", "from": "conflict-resolution", "to": "ehr-projection", "label": "write provenance-preserving ehr projection", "condition": "Attributable conflict resolution has the complete attributable payload required for the durable Provenance-preserving EHR projection write.", "reality": "both", "delivery_state": "partial", "retry": "Repeat the durable write only with its original idempotency key; Provider owns conflicting state.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#health-history-questionnaire" ] } ] }, { "id": "sg-18", "title": "Support and cancellation", "forms": [ "decision-tree", "state-machine" ], "description": "Safety-first intent routing across clinical, billing, service, and cancellation paths, optional retention, confirmation, and human escalation.", "actors": [ "Patient", "Agent Router", "Patient Support", "Retention Agent", "Operations" ], "steps": [ { "id": "support-intake", "label": "Support request", "kind": "start", "actor": "Patient", "reality": "target", "reads": [], "writes": [ "Support request state" ], "evidence_refs": [ "spec/business.md#patient-support", "spec/business.md#retention-agent" ] }, { "id": "intent-route", "label": "Safety-first intent route", "kind": "decision", "actor": "Agent Router", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Safety-first intent route decision" ], "evidence_refs": [ "spec/business.md#patient-support", "spec/business.md#retention-agent" ] }, { "id": "service-support", "label": "Service support path", "kind": "automation", "actor": "Patient Support", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Service support path state" ], "evidence_refs": [ "spec/business.md#patient-support", "spec/business.md#retention-agent" ] }, { "id": "billing-support", "label": "Billing support path", "kind": "automation", "actor": "Patient Support", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Billing support path state" ], "evidence_refs": [ "spec/business.md#patient-support", "spec/business.md#retention-agent" ] }, { "id": "clinical-escalation", "label": "Clinical human escalation", "kind": "human", "actor": "Operations", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Clinical human escalation state" ], "evidence_refs": [ "spec/business.md#patient-support", "spec/business.md#retention-agent" ] }, { "id": "cancellation-intent", "label": "Explicit cancellation intent", "kind": "decision", "actor": "Patient", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Explicit cancellation intent decision" ], "evidence_refs": [ "spec/business.md#patient-support", "spec/business.md#retention-agent" ] }, { "id": "optional-retention", "label": "Optional non-obstructive retention", "kind": "automation", "actor": "Retention Agent", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Optional non-obstructive retention state" ], "evidence_refs": [ "spec/business.md#patient-support", "spec/business.md#retention-agent" ] }, { "id": "confirm-cancel", "label": "Patient confirms cancellation", "kind": "human", "actor": "Patient", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Patient confirms cancellation state" ], "evidence_refs": [ "spec/business.md#patient-support", "spec/business.md#retention-agent" ] }, { "id": "human-resolution", "label": "Attributable human resolution", "kind": "human", "actor": "Operations", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Attributable human resolution state" ], "evidence_refs": [ "spec/business.md#patient-support", "spec/business.md#retention-agent" ] }, { "id": "complete", "label": "Support case closed", "kind": "end", "actor": "Operations", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Support case closed state" ], "evidence_refs": [ "spec/business.md#patient-support", "spec/business.md#retention-agent" ] } ], "transitions": [ { "id": "sg-18-p1-t1", "from": "support-intake", "to": "intent-route", "label": "evaluate safety-first intent route", "condition": "Target-only and not deployed: Safety-first intent route has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Re-evaluate only after a named input changes; Operations owns unresolved or conflicting eligibility.", "human_owner": "Operations", "evidence_refs": [ "spec/business.md#patient-support", "spec/business.md#retention-agent" ] }, { "id": "sg-18-service-intent", "from": "intent-route", "to": "service-support", "label": "service-support intent", "condition": "The request is nonclinical service help and is not a billing dispute, safety issue, or explicit cancellation.", "reality": "target", "delivery_state": "planned", "retry": "Preserve the classified request and escalate ambiguity to Operations rather than guessing.", "human_owner": "Operations", "evidence_refs": [ "spec/business.md#patient-support" ] }, { "id": "sg-18-p1-t3", "from": "service-support", "to": "human-resolution", "label": "Operations performs attributable human resolution", "condition": "Target-only and not deployed: Service support path presents attributable work to Operations; no automatic approval or silent substitution is permitted.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Do not auto-approve. Return the same attributable record to Operations with the unresolved reason preserved.", "human_owner": "Operations", "evidence_refs": [ "spec/business.md#patient-support", "spec/business.md#retention-agent" ] }, { "id": "sg-18-p1-t4", "from": "human-resolution", "to": "complete", "label": "complete support case closed", "condition": "Target-only and not deployed: All named predecessor states required by Support case closed are satisfied or explicitly resolved.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Reopen only from the attributable unresolved predecessor; Operations owns terminal closure.", "human_owner": "Operations", "evidence_refs": [ "spec/business.md#patient-support", "spec/business.md#retention-agent" ] }, { "id": "sg-18-billing-intent", "from": "intent-route", "to": "billing-support", "label": "billing-support intent", "condition": "The request concerns a charge, payment, refund, or membership billing state and contains no urgent clinical signal.", "reality": "target", "delivery_state": "planned", "retry": "Reconcile authoritative billing state before replying; Billing Operations owns conflicts.", "human_owner": "Operations", "evidence_refs": [ "spec/business.md#patient-support" ] }, { "id": "sg-18-p2-t2", "from": "billing-support", "to": "human-resolution", "label": "Operations performs attributable human resolution", "condition": "Target-only and not deployed: Billing support path presents attributable work to Operations; no automatic approval or silent substitution is permitted.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Do not auto-approve. Return the same attributable record to Operations with the unresolved reason preserved.", "human_owner": "Operations", "evidence_refs": [ "spec/business.md#patient-support", "spec/business.md#retention-agent" ] }, { "id": "sg-18-clinical-intent", "from": "intent-route", "to": "clinical-escalation", "label": "clinical or safety intent", "condition": "The request contains clinical judgment, an urgent signal, or another issue that requires a responsible human.", "reality": "target", "delivery_state": "planned", "retry": "Do not answer clinically through the support agent; Operations maintains the escalation until a human owns it.", "human_owner": "Operations", "evidence_refs": [ "spec/business.md#patient-support" ] }, { "id": "sg-18-p3-t2", "from": "clinical-escalation", "to": "human-resolution", "label": "Operations performs attributable human resolution", "condition": "Target-only and not deployed: Clinical human escalation presents attributable work to Operations; no automatic approval or silent substitution is permitted.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Do not auto-approve. Return the same attributable record to Operations with the unresolved reason preserved.", "human_owner": "Operations", "evidence_refs": [ "spec/business.md#patient-support", "spec/business.md#retention-agent" ] }, { "id": "sg-18-cancellation-intent", "from": "intent-route", "to": "cancellation-intent", "label": "explicit cancellation intent", "condition": "The patient explicitly asks to cancel; dissatisfaction or a support complaint alone does not silently enter cancellation.", "reality": "target", "delivery_state": "planned", "retry": "Preserve the patient's words and current membership state; Operations resolves ambiguity without blocking cancellation.", "human_owner": "Operations", "evidence_refs": [ "spec/business.md#retention-agent" ] }, { "id": "sg-18-p4-t2", "from": "cancellation-intent", "to": "confirm-cancel", "label": "Patient performs patient confirms cancellation", "condition": "Target-only and not deployed: Explicit cancellation intent presents attributable work to Patient; no automatic approval or silent substitution is permitted.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Do not auto-approve. Return the same attributable record to Patient with the unresolved reason preserved.", "human_owner": "Operations", "evidence_refs": [ "spec/business.md#patient-support", "spec/business.md#retention-agent" ] }, { "id": "sg-18-p4-t3", "from": "confirm-cancel", "to": "human-resolution", "label": "Operations performs attributable human resolution", "condition": "Target-only and not deployed: Patient confirms cancellation presents attributable work to Operations; no automatic approval or silent substitution is permitted.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Do not auto-approve. Return the same attributable record to Operations with the unresolved reason preserved.", "human_owner": "Operations", "evidence_refs": [ "spec/business.md#patient-support", "spec/business.md#retention-agent" ] }, { "id": "sg-18-p5-t1", "from": "cancellation-intent", "to": "optional-retention", "label": "run optional non-obstructive retention", "condition": "Target-only and not deployed: Explicit cancellation intent satisfies the deterministic preconditions declared for Optional non-obstructive retention.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Retry Optional non-obstructive retention under the same workflow identity and dedupe key; Operations owns terminal failure.", "human_owner": "Operations", "evidence_refs": [ "spec/business.md#patient-support", "spec/business.md#retention-agent" ] }, { "id": "sg-18-p5-t2", "from": "optional-retention", "to": "confirm-cancel", "label": "Patient performs patient confirms cancellation", "condition": "Target-only and not deployed: Optional non-obstructive retention presents attributable work to Patient; no automatic approval or silent substitution is permitted.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Do not auto-approve. Return the same attributable record to Patient with the unresolved reason preserved.", "human_owner": "Operations", "evidence_refs": [ "spec/business.md#patient-support", "spec/business.md#retention-agent" ] }, { "id": "sg-18-p6-t1", "from": "optional-retention", "to": "human-resolution", "label": "Operations performs attributable human resolution", "condition": "Target-only and not deployed: Optional non-obstructive retention presents attributable work to Operations; no automatic approval or silent substitution is permitted.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Do not auto-approve. Return the same attributable record to Operations with the unresolved reason preserved.", "human_owner": "Operations", "evidence_refs": [ "spec/business.md#patient-support", "spec/business.md#retention-agent" ] } ] }, { "id": "sg-19", "title": "Research evidence", "forms": [ "internal-pipeline", "data-flow" ], "description": "Resolver-backed documents, governed corpus, citation graph, synthesis, conflict handling, and mandatory human review.", "actors": [ "Provider", "Research Agent", "Evidence Corpus", "Clinical Reviewer" ], "steps": [ { "id": "question", "label": "Authorized clinical question", "kind": "start", "actor": "Provider", "reality": "target", "reads": [], "writes": [ "Authorized clinical question state" ], "evidence_refs": [ "spec/business.md#medical-research-agent" ] }, { "id": "resolve-sources", "label": "Resolver-backed source retrieval", "kind": "automation", "actor": "Research Agent", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Resolver-backed source retrieval state" ], "evidence_refs": [ "spec/business.md#medical-research-agent" ] }, { "id": "governed-corpus", "label": "Governed evidence corpus", "kind": "record", "actor": "Evidence Corpus", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Governed evidence corpus state" ], "evidence_refs": [ "spec/business.md#medical-research-agent" ] }, { "id": "citation-graph", "label": "Claim-to-source citation graph", "kind": "record", "actor": "Research Agent", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Claim-to-source citation graph state" ], "evidence_refs": [ "spec/business.md#medical-research-agent" ] }, { "id": "conflict-check", "label": "Conflicting-evidence check", "kind": "decision", "actor": "Research Agent", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Conflicting-evidence check decision" ], "evidence_refs": [ "spec/business.md#medical-research-agent" ] }, { "id": "synthesis", "label": "Bounded cited synthesis", "kind": "automation", "actor": "Research Agent", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Bounded cited synthesis state" ], "evidence_refs": [ "spec/business.md#medical-research-agent" ] }, { "id": "human-review", "label": "Mandatory clinical human review", "kind": "human", "actor": "Clinical Reviewer", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Mandatory clinical human review state" ], "evidence_refs": [ "spec/business.md#medical-research-agent" ] }, { "id": "complete", "label": "Reviewed answer released", "kind": "end", "actor": "Provider", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Reviewed answer released state" ], "evidence_refs": [ "spec/business.md#medical-research-agent" ] } ], "transitions": [ { "id": "sg-19-p1-t1", "from": "question", "to": "resolve-sources", "label": "run resolver-backed source retrieval", "condition": "Target-only and not deployed: Authorized clinical question satisfies the deterministic preconditions declared for Resolver-backed source retrieval.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Retry Resolver-backed source retrieval under the same workflow identity and dedupe key; Provider owns terminal failure.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#medical-research-agent" ] }, { "id": "sg-19-p1-t2", "from": "resolve-sources", "to": "governed-corpus", "label": "write governed evidence corpus", "condition": "Target-only and not deployed: Resolver-backed source retrieval has the complete attributable payload required for the durable Governed evidence corpus write.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Repeat the durable write only with its original idempotency key; Provider owns conflicting state.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#medical-research-agent" ] }, { "id": "sg-19-p1-t3", "from": "governed-corpus", "to": "citation-graph", "label": "write claim-to-source citation graph", "condition": "Target-only and not deployed: Governed evidence corpus has the complete attributable payload required for the durable Claim-to-source citation graph write.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Repeat the durable write only with its original idempotency key; Provider owns conflicting state.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#medical-research-agent" ] }, { "id": "sg-19-p1-t4", "from": "citation-graph", "to": "synthesis", "label": "run bounded cited synthesis", "condition": "Target-only and not deployed: Claim-to-source citation graph satisfies the deterministic preconditions declared for Bounded cited synthesis.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Retry Bounded cited synthesis under the same workflow identity and dedupe key; Provider owns terminal failure.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#medical-research-agent" ] }, { "id": "sg-19-p1-t5", "from": "synthesis", "to": "human-review", "label": "Clinical Reviewer performs mandatory clinical human review", "condition": "Target-only and not deployed: Bounded cited synthesis presents attributable work to Clinical Reviewer; no automatic approval or silent substitution is permitted.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Do not auto-approve. Return the same attributable record to Clinical Reviewer with the unresolved reason preserved.", "human_owner": "Clinical Reviewer", "evidence_refs": [ "spec/business.md#medical-research-agent" ] }, { "id": "sg-19-p1-t6", "from": "human-review", "to": "complete", "label": "complete reviewed answer released", "condition": "Target-only and not deployed: All named predecessor states required by Reviewed answer released are satisfied or explicitly resolved.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Reopen only from the attributable unresolved predecessor; Clinical Reviewer owns terminal closure.", "human_owner": "Clinical Reviewer", "evidence_refs": [ "spec/business.md#medical-research-agent" ] }, { "id": "sg-19-p2-t1", "from": "citation-graph", "to": "conflict-check", "label": "evaluate conflicting-evidence check", "condition": "Target-only and not deployed: Conflicting-evidence check has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Re-evaluate only after a named input changes; Provider owns unresolved or conflicting eligibility.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#medical-research-agent" ] }, { "id": "sg-19-p2-t2", "from": "conflict-check", "to": "synthesis", "label": "run bounded cited synthesis", "condition": "Target-only and not deployed: Conflicting-evidence check satisfies the deterministic preconditions declared for Bounded cited synthesis.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Retry Bounded cited synthesis under the same workflow identity and dedupe key; Provider owns terminal failure.", "human_owner": "Provider", "evidence_refs": [ "spec/business.md#medical-research-agent" ] } ] }, { "id": "sg-20", "title": "Drift review loop", "forms": [ "control-loop", "state-machine" ], "description": "Code, specification, and deployed-runtime comparison, explainable findings, ownership, fix or approval, verification, and closure.", "actors": [ "Drift Watchdog", "Engineer", "Product Owner", "Operations" ], "steps": [ { "id": "compare", "label": "Code, spec, and runtime comparison", "kind": "start", "actor": "Drift Watchdog", "reality": "target", "reads": [], "writes": [ "Code, spec, and runtime comparison state" ], "evidence_refs": [ "spec/business.md#drift-layer" ] }, { "id": "finding", "label": "Explainable drift finding", "kind": "record", "actor": "Drift Watchdog", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Explainable drift finding state" ], "evidence_refs": [ "spec/business.md#drift-layer" ] }, { "id": "owner-assign", "label": "Named accountable owner", "kind": "human", "actor": "Operations", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Named accountable owner state" ], "evidence_refs": [ "spec/business.md#drift-layer" ] }, { "id": "fix-or-approve", "label": "Fix implementation or explicit approval", "kind": "decision", "actor": "Product Owner", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Fix implementation or explicit approval decision" ], "evidence_refs": [ "spec/business.md#drift-layer" ] }, { "id": "verify", "label": "Independent verification", "kind": "automation", "actor": "Drift Watchdog", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Independent verification state" ], "evidence_refs": [ "spec/business.md#drift-layer" ] }, { "id": "close", "label": "Attributable closure", "kind": "record", "actor": "Operations", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Attributable closure state" ], "evidence_refs": [ "spec/business.md#drift-layer" ] }, { "id": "repeat", "label": "Next governed comparison", "kind": "end", "actor": "Drift Watchdog", "reality": "target", "reads": [ "Governed prior workflow state" ], "writes": [ "Next governed comparison state" ], "evidence_refs": [ "spec/business.md#drift-layer" ] } ], "transitions": [ { "id": "sg-20-p1-t1", "from": "compare", "to": "close", "label": "write attributable closure", "condition": "Target-only and not deployed: Code, spec, and runtime comparison has the complete attributable payload required for the durable Attributable closure write.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Repeat the durable write only with its original idempotency key; Operations owns conflicting state.", "human_owner": "Operations", "evidence_refs": [ "spec/business.md#drift-layer" ] }, { "id": "sg-20-p1-t2", "from": "close", "to": "repeat", "label": "complete next governed comparison", "condition": "Target-only and not deployed: All named predecessor states required by Next governed comparison are satisfied or explicitly resolved.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Reopen only from the attributable unresolved predecessor; Operations owns terminal closure.", "human_owner": "Operations", "evidence_refs": [ "spec/business.md#drift-layer" ] }, { "id": "sg-20-p1-t3", "from": "repeat", "to": "compare", "label": "return to code, spec, and runtime comparison", "condition": "Target-only and not deployed: Code, spec, and runtime comparison receives its named initiating event.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Replay only the stable initiating event; Engineer owns duplicates or rejection.", "human_owner": "Engineer", "evidence_refs": [ "spec/business.md#drift-layer" ] }, { "id": "sg-20-p2-t1", "from": "compare", "to": "finding", "label": "write explainable drift finding", "condition": "Target-only and not deployed: Code, spec, and runtime comparison has the complete attributable payload required for the durable Explainable drift finding write.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Repeat the durable write only with its original idempotency key; Engineer owns conflicting state.", "human_owner": "Engineer", "evidence_refs": [ "spec/business.md#drift-layer" ] }, { "id": "sg-20-p2-t2", "from": "finding", "to": "owner-assign", "label": "Operations performs named accountable owner", "condition": "Target-only and not deployed: Explainable drift finding presents attributable work to Operations; no automatic approval or silent substitution is permitted.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Do not auto-approve. Return the same attributable record to Operations with the unresolved reason preserved.", "human_owner": "Operations", "evidence_refs": [ "spec/business.md#drift-layer" ] }, { "id": "sg-20-p2-t3", "from": "owner-assign", "to": "fix-or-approve", "label": "evaluate fix implementation or explicit approval", "condition": "Target-only and not deployed: Fix implementation or explicit approval has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Re-evaluate only after a named input changes; Operations owns unresolved or conflicting eligibility.", "human_owner": "Operations", "evidence_refs": [ "spec/business.md#drift-layer" ] }, { "id": "sg-20-p2-t4", "from": "fix-or-approve", "to": "verify", "label": "run independent verification", "condition": "Target-only and not deployed: Fix implementation or explicit approval satisfies the deterministic preconditions declared for Independent verification.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Retry Independent verification under the same workflow identity and dedupe key; Product Owner owns terminal failure.", "human_owner": "Product Owner", "evidence_refs": [ "spec/business.md#drift-layer" ] }, { "id": "sg-20-p2-t5", "from": "verify", "to": "close", "label": "write attributable closure", "condition": "Target-only and not deployed: Independent verification has the complete attributable payload required for the durable Attributable closure write.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Repeat the durable write only with its original idempotency key; Operations owns conflicting state.", "human_owner": "Operations", "evidence_refs": [ "spec/business.md#drift-layer" ] }, { "id": "sg-20-p3-t1", "from": "fix-or-approve", "to": "close", "label": "write attributable closure", "condition": "Target-only and not deployed: Fix implementation or explicit approval has the complete attributable payload required for the durable Attributable closure write.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Repeat the durable write only with its original idempotency key; Product Owner owns conflicting state.", "human_owner": "Product Owner", "evidence_refs": [ "spec/business.md#drift-layer" ] }, { "id": "sg-20-p4-t1", "from": "verify", "to": "finding", "label": "write explainable drift finding", "condition": "Target-only and not deployed: Independent verification has the complete attributable payload required for the durable Explainable drift finding write.", "reality": "target", "delivery_state": "planned", "retry": "No runtime retry exists until this target transition is deployed. Repeat the durable write only with its original idempotency key; Engineer owns conflicting state.", "human_owner": "Engineer", "evidence_refs": [ "spec/business.md#drift-layer" ] } ] }, { "id": "sg-21", "title": "Provider onboarding", "forms": [ "state-machine", "decision-tree" ], "description": "Invite or permitted self-entry, agreement, credentials, inactive human review, activation, clinic linkage, and Stripe Connect.", "actors": [ "Provider", "Provider Operations", "Credentialing", "Stripe" ], "steps": [ { "id": "invite-or-entry", "label": "Invite or permitted self-entry", "kind": "start", "actor": "Provider", "reality": "both", "reads": [], "writes": [ "Invite or permitted self-entry state" ], "evidence_refs": [ "spec/as-built.md#provider-onboarding" ] }, { "id": "agreement", "label": "Complete provider agreement", "kind": "human", "actor": "Provider", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Complete provider agreement state" ], "evidence_refs": [ "spec/as-built.md#provider-onboarding" ] }, { "id": "credentials", "label": "Credential and license evidence", "kind": "record", "actor": "Credentialing", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Credential and license evidence state" ], "evidence_refs": [ "spec/as-built.md#provider-onboarding" ] }, { "id": "inactive-review", "label": "Inactive human credential review", "kind": "human", "actor": "Provider Operations", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Inactive human credential review state" ], "evidence_refs": [ "spec/as-built.md#provider-onboarding" ] }, { "id": "activation", "label": "Attributable provider activation", "kind": "decision", "actor": "Provider Operations", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Attributable provider activation decision" ], "evidence_refs": [ "spec/as-built.md#provider-onboarding" ] }, { "id": "clinic-connect", "label": "Clinic relationship", "kind": "record", "actor": "Provider Operations", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Clinic relationship state" ], "evidence_refs": [ "spec/as-built.md#provider-onboarding" ] }, { "id": "stripe-connect", "label": "Stripe Connect account", "kind": "external", "actor": "Stripe", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Stripe Connect account state" ], "evidence_refs": [ "spec/as-built.md#provider-onboarding" ] }, { "id": "eligible-roster", "label": "Eligible scheduling roster", "kind": "end", "actor": "Provider Operations", "reality": "both", "reads": [ "Governed prior workflow state" ], "writes": [ "Eligible scheduling roster state" ], "evidence_refs": [ "spec/as-built.md#provider-onboarding" ] } ], "transitions": [ { "id": "sg-21-p1-t1", "from": "invite-or-entry", "to": "agreement", "label": "Provider performs complete provider agreement", "condition": "Invite or permitted self-entry presents attributable work to Provider; no automatic approval or silent substitution is permitted.", "reality": "both", "delivery_state": "partial", "retry": "Do not auto-approve. Return the same attributable record to Provider with the unresolved reason preserved.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#provider-onboarding" ] }, { "id": "sg-21-p1-t2", "from": "agreement", "to": "credentials", "label": "write credential and license evidence", "condition": "Complete provider agreement has the complete attributable payload required for the durable Credential and license evidence write.", "reality": "both", "delivery_state": "partial", "retry": "Repeat the durable write only with its original idempotency key; Provider owns conflicting state.", "human_owner": "Provider", "evidence_refs": [ "spec/as-built.md#provider-onboarding" ] }, { "id": "sg-21-p1-t3", "from": "credentials", "to": "inactive-review", "label": "Provider Operations performs inactive human credential review", "condition": "Credential and license evidence presents attributable work to Provider Operations; no automatic approval or silent substitution is permitted.", "reality": "both", "delivery_state": "partial", "retry": "Do not auto-approve. Return the same attributable record to Provider Operations with the unresolved reason preserved.", "human_owner": "Credentialing", "evidence_refs": [ "spec/as-built.md#provider-onboarding" ] }, { "id": "sg-21-p1-t4", "from": "inactive-review", "to": "activation", "label": "evaluate attributable provider activation", "condition": "Attributable provider activation has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "both", "delivery_state": "partial", "retry": "Re-evaluate only after a named input changes; Provider Operations owns unresolved or conflicting eligibility.", "human_owner": "Provider Operations", "evidence_refs": [ "spec/as-built.md#provider-onboarding" ] }, { "id": "sg-21-p1-t5", "from": "activation", "to": "clinic-connect", "label": "write clinic relationship", "condition": "Attributable provider activation has the complete attributable payload required for the durable Clinic relationship write.", "reality": "both", "delivery_state": "partial", "retry": "Repeat the durable write only with its original idempotency key; Provider Operations owns conflicting state.", "human_owner": "Provider Operations", "evidence_refs": [ "spec/as-built.md#provider-onboarding" ] }, { "id": "sg-21-p1-t6", "from": "clinic-connect", "to": "stripe-connect", "label": "submit stripe connect account", "condition": "Clinic relationship supplies the authenticated external contract and stable source identifiers required by Stripe Connect account.", "reality": "both", "delivery_state": "partial", "retry": "Retry transport under the same stable external ID; Provider Operations owns rejection, timeout, and reconciliation.", "human_owner": "Provider Operations", "evidence_refs": [ "spec/as-built.md#provider-onboarding" ] }, { "id": "sg-21-p1-t7", "from": "stripe-connect", "to": "eligible-roster", "label": "complete eligible scheduling roster", "condition": "All named predecessor states required by Eligible scheduling roster are satisfied or explicitly resolved.", "reality": "both", "delivery_state": "partial", "retry": "Reopen only from the attributable unresolved predecessor; Provider Operations owns terminal closure.", "human_owner": "Provider Operations", "evidence_refs": [ "spec/as-built.md#provider-onboarding" ] }, { "id": "sg-21-p2-t1", "from": "inactive-review", "to": "credentials", "label": "write credential and license evidence", "condition": "Inactive human credential review has the complete attributable payload required for the durable Credential and license evidence write.", "reality": "both", "delivery_state": "partial", "retry": "Repeat the durable write only with its original idempotency key; Provider Operations owns conflicting state.", "human_owner": "Provider Operations", "evidence_refs": [ "spec/as-built.md#provider-onboarding" ] }, { "id": "sg-21-p3-t1", "from": "activation", "to": "inactive-review", "label": "Provider Operations performs inactive human credential review", "condition": "Attributable provider activation presents attributable work to Provider Operations; no automatic approval or silent substitution is permitted.", "reality": "both", "delivery_state": "partial", "retry": "Do not auto-approve. Return the same attributable record to Provider Operations with the unresolved reason preserved.", "human_owner": "Provider Operations", "evidence_refs": [ "spec/as-built.md#provider-onboarding" ] }, { "id": "sg-21-connect-retry", "from": "stripe-connect", "to": "stripe-connect", "label": "retry the same Connect onboarding", "condition": "The existing Stripe Connect account remains incomplete or a retryable transport failure occurred; no replacement account is created.", "reality": "both", "delivery_state": "partial", "retry": "Retry with the same Connect account and idempotency key, then send terminal or conflicting state to Provider Operations.", "human_owner": "Provider Operations", "evidence_refs": [ "spec/as-built.md#provider-onboarding" ] } ] }, { "id": "sg-22", "title": "Operations control plane", "forms": [ "sequence", "control-loop" ], "description": "Authorized human reads and actions separated from machine preflight, confirmation, idempotent execution, immutable audit, and focused exception views.", "actors": [ "Operations", "Ops Console", "Domain Service", "Audit Ledger" ], "steps": [ { "id": "authorized-read", "label": "Admin-authorized domain read", "kind": "start", "actor": "Ops Console", "reality": "current", "reads": [], "writes": [ "Admin-authorized domain read state" ], "evidence_refs": [ "spec/as-built.md#ops-console" ] }, { "id": "exception-views", "label": "Messaging, labs, safety, billing, and 3PL exception view", "kind": "record", "actor": "Ops Console", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "Messaging, labs, safety, billing, and 3PL exception view state" ], "evidence_refs": [ "spec/as-built.md#ops-console" ] }, { "id": "human-action", "label": "Attributable human action request", "kind": "human", "actor": "Operations", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "Attributable human action request state" ], "evidence_refs": [ "spec/as-built.md#ops-console" ] }, { "id": "machine-preflight", "label": "Domain preflight and guard check", "kind": "automation", "actor": "Domain Service", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "Domain preflight and guard check state" ], "evidence_refs": [ "spec/as-built.md#ops-console" ] }, { "id": "confirmation", "label": "Explicit confirmation for consequential action", "kind": "decision", "actor": "Operations", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "Explicit confirmation for consequential action decision" ], "evidence_refs": [ "spec/as-built.md#ops-console" ] }, { "id": "idempotent-execute", "label": "Idempotent domain command", "kind": "automation", "actor": "Domain Service", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "Idempotent domain command state" ], "evidence_refs": [ "spec/as-built.md#ops-console" ] }, { "id": "audit-event", "label": "Immutable actor/outcome audit event", "kind": "record", "actor": "Audit Ledger", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "Immutable actor/outcome audit event state" ], "evidence_refs": [ "spec/as-built.md#ops-console" ] }, { "id": "reconcile", "label": "Result reconciliation and queue refresh", "kind": "automation", "actor": "Ops Console", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "Result reconciliation and queue refresh state" ], "evidence_refs": [ "spec/as-built.md#ops-console" ] }, { "id": "complete", "label": "Operation closed", "kind": "end", "actor": "Operations", "reality": "current", "reads": [ "Governed prior workflow state" ], "writes": [ "Operation closed state" ], "evidence_refs": [ "spec/as-built.md#ops-console" ] } ], "transitions": [ { "id": "sg-22-p1-t1", "from": "authorized-read", "to": "exception-views", "label": "write messaging, labs, safety, billing, and 3pl exception view", "condition": "Admin-authorized domain read has the complete attributable payload required for the durable Messaging, labs, safety, billing, and 3PL exception view write.", "reality": "current", "delivery_state": "live", "retry": "Repeat the durable write only with its original idempotency key; Operations owns conflicting state.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#ops-console" ] }, { "id": "sg-22-p1-t2", "from": "exception-views", "to": "complete", "label": "complete operation closed", "condition": "All named predecessor states required by Operation closed are satisfied or explicitly resolved.", "reality": "current", "delivery_state": "live", "retry": "Reopen only from the attributable unresolved predecessor; Operations owns terminal closure.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#ops-console" ] }, { "id": "sg-22-p2-t1", "from": "exception-views", "to": "human-action", "label": "Operations performs attributable human action request", "condition": "Messaging, labs, safety, billing, and 3PL exception view presents attributable work to Operations; no automatic approval or silent substitution is permitted.", "reality": "current", "delivery_state": "live", "retry": "Do not auto-approve. Return the same attributable record to Operations with the unresolved reason preserved.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#ops-console" ] }, { "id": "sg-22-p2-t2", "from": "human-action", "to": "machine-preflight", "label": "run domain preflight and guard check", "condition": "Attributable human action request satisfies the deterministic preconditions declared for Domain preflight and guard check.", "reality": "current", "delivery_state": "live", "retry": "Retry Domain preflight and guard check under the same workflow identity and dedupe key; Operations owns terminal failure.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#ops-console" ] }, { "id": "sg-22-p2-t3", "from": "machine-preflight", "to": "confirmation", "label": "evaluate explicit confirmation for consequential action", "condition": "Explicit confirmation for consequential action has received its named governed inputs and may evaluate the eligible branch without inventing missing facts.", "reality": "current", "delivery_state": "live", "retry": "Re-evaluate only after a named input changes; Operations owns unresolved or conflicting eligibility.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#ops-console" ] }, { "id": "sg-22-p2-t4", "from": "confirmation", "to": "idempotent-execute", "label": "run idempotent domain command", "condition": "Explicit confirmation for consequential action satisfies the deterministic preconditions declared for Idempotent domain command.", "reality": "current", "delivery_state": "live", "retry": "Retry Idempotent domain command under the same workflow identity and dedupe key; Operations owns terminal failure.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#ops-console" ] }, { "id": "sg-22-p2-t5", "from": "idempotent-execute", "to": "audit-event", "label": "write immutable actor/outcome audit event", "condition": "Idempotent domain command has the complete attributable payload required for the durable Immutable actor/outcome audit event write.", "reality": "current", "delivery_state": "live", "retry": "Repeat the durable write only with its original idempotency key; Operations owns conflicting state.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#ops-console" ] }, { "id": "sg-22-p2-t6", "from": "audit-event", "to": "reconcile", "label": "run result reconciliation and queue refresh", "condition": "Immutable actor/outcome audit event satisfies the deterministic preconditions declared for Result reconciliation and queue refresh.", "reality": "current", "delivery_state": "live", "retry": "Retry Result reconciliation and queue refresh under the same workflow identity and dedupe key; Operations owns terminal failure.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#ops-console" ] }, { "id": "sg-22-p2-t7", "from": "reconcile", "to": "complete", "label": "complete operation closed", "condition": "All named predecessor states required by Operation closed are satisfied or explicitly resolved.", "reality": "current", "delivery_state": "live", "retry": "Reopen only from the attributable unresolved predecessor; Operations owns terminal closure.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#ops-console" ] }, { "id": "sg-22-preflight-failed", "from": "machine-preflight", "to": "audit-event", "label": "preflight rejected; record no-op", "condition": "Authorization, current-state, payload, or domain guards fail before any consequential side effect executes.", "reality": "current", "delivery_state": "live", "retry": "Record the rejection, correct the named failed precondition, and submit a new attributable command.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#ops-console" ] }, { "id": "sg-22-confirmation-declined", "from": "confirmation", "to": "audit-event", "label": "operator declines confirmation", "condition": "The authorized operator declines or abandons the explicit consequential-action confirmation.", "reality": "current", "delivery_state": "live", "retry": "Record a no-op audit result; a later attempt requires a new confirmation against current state.", "human_owner": "Operations", "evidence_refs": [ "spec/as-built.md#ops-console" ] } ] } ], "views": [ { "id": "whole-machine", "label": "Whole machine", "description": "The unchanged canonical Machina layout with every default node and connector.", "predicate_any": [ { "all": true } ], "force_include": [], "force_exclude": [], "support_depth": 0, "context_opacity": 1, "background_opacity": 1, "default_label_density": "all", "mobile_presentation": "map" }, { "id": "patient-journey", "label": "Patient journey", "description": "Actions the patient takes and milestones the patient receives, with one-hop operating context.", "predicate_any": [ { "actors_any": [ { "actor": "patient", "participations": [ "acts", "receives" ] } ] } ], "force_include": [], "force_exclude": [], "support_depth": 1, "context_opacity": 0.45, "background_opacity": 0.1, "default_label_density": "focus", "mobile_presentation": "path" }, { "id": "doctor-work", "label": "Doctor work", "description": "Provider actions, reviews, decisions, received work, and escalations.", "predicate_any": [ { "actors_any": [ { "actor": "doctor", "participations": [ "acts", "approves", "reviews", "receives", "escalates" ] } ] } ], "force_include": [], "force_exclude": [], "support_depth": 1, "context_opacity": 0.45, "background_opacity": 0.1, "default_label_density": "focus", "mobile_presentation": "path" }, { "id": "agent-behavior", "label": "Agent behavior", "description": "Focused AI agents and deterministic automations that actively operate a governed behavior.", "predicate_any": [ { "actors_any": [ { "actor": "agent", "participations": [ "operates" ] } ] } ], "force_include": [], "force_exclude": [], "support_depth": 1, "context_opacity": 0.45, "background_opacity": 0.1, "default_label_density": "focus", "mobile_presentation": "map" }, { "id": "onboarding-conversion", "label": "Onboarding and conversion", "description": "Patient entry through secure completion and appointment readiness.", "predicate_any": [ { "domains_any": [ "onboarding" ] } ], "force_include": [], "force_exclude": [ { "id": "provider-onboarding", "reason": "Provider onboarding is a separate governed workforce lifecycle, never the patient signup sequence." } ], "support_depth": 1, "context_opacity": 0.45, "background_opacity": 0.1, "default_label_density": "focus", "mobile_presentation": "path" }, { "id": "labs", "label": "Labs", "description": "Ordering, collection, import, normalization, review, notification, and follow-up.", "predicate_any": [ { "domains_any": [ "labs" ] } ], "force_include": [], "force_exclude": [], "support_depth": 1, "context_opacity": 0.45, "background_opacity": 0.1, "default_label_density": "focus", "mobile_presentation": "path" }, { "id": "fulfillment", "label": "Fulfillment", "description": "Prescription, payment, protocol, pharmacy, 3PL, delivery, billing, and continuing-care contracts.", "predicate_any": [ { "domains_any": [ "fulfillment" ] } ], "force_include": [], "force_exclude": [], "support_depth": 1, "context_opacity": 0.45, "background_opacity": 0.1, "default_label_density": "focus", "mobile_presentation": "path" }, { "id": "follow-up-support", "label": "Follow-up and support", "description": "Post-visit evidence, patient support, clinical communication, escalation, and continuing care.", "predicate_any": [ { "domains_any": [ "follow-up" ] } ], "force_include": [], "force_exclude": [], "support_depth": 1, "context_opacity": 0.45, "background_opacity": 0.1, "default_label_density": "focus", "mobile_presentation": "path" }, { "id": "operations-governance", "label": "Operations and governance", "description": "Policies, registries, control-plane actions, review loops, and operational exception ownership.", "predicate_any": [ { "domains_any": [ "governance" ] } ], "force_include": [], "force_exclude": [], "support_depth": 1, "context_opacity": 0.45, "background_opacity": 0.1, "default_label_density": "focus", "mobile_presentation": "map" } ] }