# SCRIMED OS Implementation Plan

Status: scrimed-os-implementation-plan-ready-no-phi
Updated: 2026-06-30

## Strategy
SCRIMED should operate as a Healthcare Intelligence Operating System that securely orchestrates frontier models, agents, clinical workflows, FHIR/EHR data, imaging systems, memory, governance, auditability, outcome tracking, and enterprise deployment.

## Boundary
SCRIMED OS implementation plan is a no-PHI, architecture-and-roadmap control. It does not authorize live PHI, autonomous diagnosis, treatment, prescribing, patient outreach, payer submission, EHR writeback, production connector use, Kubernetes mutation, remediation execution, clinical validation, certification, or customer go-live.

## GO / NO-GO
- GO for no-PHI architecture planning, synthetic workflow design, registry contracts, event contracts, and investor/buyer technical diligence.
- NO-GO for live PHI, autonomous clinical care, direct LLM database access, patient outreach, payer submission, EHR writeback, production connector use, cluster mutation, clinical validation, certification, or customer go-live.

## Architecture Principles
- Event-driven by default.
- Zero-trust agent identity.
- Human-in-the-loop clinical decisions.
- No direct LLM-to-database access.
- Governed MCP middleware between AI and systems of record.
- Every agent has identity, permissions, version, trust score, audit log, and allowed tools.
- Every model output is evaluated, logged, and traceable.
- Every clinical recommendation-like draft includes confidence, source evidence, limitations, and escalation criteria.
- All infrastructure is reproducible through IaC.
- All workflows are observable, testable, versioned, and rollback-capable.
- Prefer orchestrating best frontier models over training proprietary healthcare models unless justified.
- Use CodeMode agents for structured reasoning, calculations, SQL generation, FHIR transformations, and workflow automation.
- Preserve document structure during RAG ingestion: pages, tables, labels, values, units, citations, images, and references.

## Roadmap
- Safety and architecture contract: Freeze the operating boundary, no-PHI posture, protected-action denials, and starter contracts before implementation expands. Exit: Central policy gate is referenced by sensitive APIs.; NO-GO boundaries are visible in docs and APIs.; No direct LLM-to-database access is encoded as an invariant.; Starter registries and event names are versioned.
- Governance backbone: Build the event mesh, identity registry, audit ledger, policy registry, and core agent/model/prompt/eval registries. Exit: Every agent and model route has an identity, owner, version, policy, and audit event.; Event envelopes are deterministic and replayable.; Registry changes require approval records.
- Tool and runtime plane: Introduce Secure MCP Gateway, CodeMode Runtime, query validation middleware, and secure RAG/data ingestion. Exit: All tool calls require scoped identity and policy checks.; CodeMode runs in sandboxed, time-limited, network-restricted execution.; SQL and FHIR queries are validated before execution.; RAG ingestion preserves document structure and evidence links.
- Clinical and data workflows: Build the clinical orchestrator, FHIR validation, imaging integration, clinical QA, and safety sandbox. Exit: Clinical outputs carry evidence, confidence, limitations, and escalation criteria.; FHIR validation rejects unsafe or profile-invalid payloads.; Imaging is metadata/report-first and no-PHI until approved.; Human review remains mandatory for protected clinical workflows.
- Operations intelligence: Add configuration drift, AI cost intelligence, observability, and suggestion-only remediation loops. Exit: SLOs, traces, model costs, registry drift, and deployment drift are observable.; Autonomous remediation creates reviewed proposals, not live mutations.; Cost and provider anomaly events are routed to human owners.
- Deployment platform: Implement IaC, Kubernetes deployment contracts, canaries, approvals, rollback, and environment drift controls. Exit: Terraform or equivalent IaC can reproduce approved environments.; Kubernetes manifests are signed, scanned, policy-checked, and rollback-ready.; Deployment approval pipeline blocks unsafe releases.
- Outcome learning: Build continuous outcome learning with synthetic or approved de-identified feedback, reviewer labels, and regression gates. Exit: Outcome signals are consented, de-identified or approved, and evidence-linked.; Learning updates create evaluation tasks, not automatic clinical behavior changes.; Regression and bias checks pass before policy or prompt promotion.

## Capabilities
- SCRIMED Event Mesh: phase-1-governance-backbone; starter-build-ready; Create the append-only event backbone for agent runs, registry changes, workflow state, model routing, evaluations, approvals, and audit evidence.
- Agent Identity Registry: phase-1-governance-backbone; starter-build-ready; Give every agent persistent identity, owner, version, trust score, scopes, allowed tools, denied tools, and audit history.
- Secure MCP Gateway: phase-2-tool-runtime-plane; requires-protected-pilot; Place governed MCP middleware between agents and systems of record, with OAuth, scoped tokens, tool-level authorization, and audit.
- CodeMode Runtime for agents: phase-2-tool-runtime-plane; requires-protected-pilot; Run structured reasoning, calculations, SQL generation, FHIR transformations, validation, and workflow automation inside sandboxed CodeMode sessions.
- Clinical Workflow Orchestrator: phase-3-clinical-data-workflows; requires-protected-pilot; Coordinate deterministic clinical workflows across intake, evidence, FHIR validation, QA, review queues, and safe handoff states.
- Agent Registry: phase-1-governance-backbone; starter-build-ready; Maintain approved agent definitions, versions, scopes, owners, eval requirements, tool policies, and deployment status.
- Prompt Registry: phase-1-governance-backbone; starter-build-ready; Version prompts, system instructions, few-shot examples, safety clauses, expected outputs, owners, and eval bindings.
- Policy Registry: phase-1-governance-backbone; starter-build-ready; Centralize safety, PHI, tool, model, workflow, data-residency, cost, and deployment policies with versioned decisions.
- Model Registry: phase-1-governance-backbone; starter-build-ready; Track providers, model versions, tasks, risk tiers, cost, latency, quality, data policy, fallback, and approval state.
- Evaluation Registry: phase-1-governance-backbone; starter-build-ready; Store evaluation datasets, synthetic scenarios, reviewer labels, scorecards, regression checks, adversarial cases, and release gates.
- FHIR Validation Agent: phase-3-clinical-data-workflows; requires-protected-pilot; Validate FHIR resources, profiles, terminology, references, consent, purpose-of-use, and transformation safety before workflow use.
- Imaging Integration Layer: phase-3-clinical-data-workflows; blocked-before-production; Prepare DICOM/DICOMweb/PACS, imaging reports, metadata, AI imaging inference, and reviewer workflows without enabling live imaging authority.
- Configuration Drift Agent: phase-4-ops-intelligence; starter-build-ready; Detect drift across policies, registries, environment variables, IaC, Kubernetes manifests, deployment settings, and security headers.
- AI Cost Intelligence Agent: phase-4-ops-intelligence; starter-build-ready; Track model/tool cost, token use, latency, provider usage, budget thresholds, anomaly detection, and cost-aware routing recommendations.
- Observability Platform: phase-4-ops-intelligence; starter-build-ready; Trace requests, events, agents, model calls, tool calls, policy decisions, evaluations, workflows, costs, and safety escalations.
- Autonomous Remediation Agent: phase-4-ops-intelligence; blocked-before-production; Generate remediation proposals for drift, failed deployments, cost spikes, degraded SLOs, and eval regressions while keeping execution human-approved.
- Clinical QA Engine: phase-3-clinical-data-workflows; requires-protected-pilot; Evaluate clinical drafts for evidence quality, hallucination, missing data, bias, guideline grounding, safety boundaries, and reviewer requirements.
- Continuous Outcome Learning Engine: phase-6-outcome-learning; blocked-before-production; Learn from approved outcomes, reviewer labels, incidents, eval regressions, and workflow results without automatic clinical behavior changes.
- Infrastructure-as-Code Engine: phase-5-deployment-platform; requires-protected-pilot; Make SCRIMED environments reproducible through IaC with policy checks, secrets separation, state locking, drift detection, and rollback.
- Kubernetes Deployment Engine: phase-5-deployment-platform; blocked-before-production; Prepare Kubernetes deployment, canary, rollback, policy, runtime security, GPU scheduling, and service health contracts.
- Zero-Trust Audit Ledger: phase-1-governance-backbone; starter-build-ready; Create immutable, tamper-evident audit evidence for identity, policy, model, tool, workflow, evaluation, deployment, and review actions.
- SQL/FHIR Query Validation Middleware: phase-2-tool-runtime-plane; requires-protected-pilot; Validate generated SQL, FHIR search, and transformation requests before any database or system-of-record access.
- Deployment Approval Pipeline: phase-5-deployment-platform; starter-build-ready; Gate deployments through tests, security scans, evals, drift checks, human approvals, canaries, blast-radius controls, and rollback.
- Secure RAG/Data Ingestion Pipeline: phase-2-tool-runtime-plane; requires-protected-pilot; Ingest documents and data for retrieval while preserving structure, provenance, citations, redaction, malware checks, and policy boundaries.
- Human-in-the-loop Clinical Safety Sandbox: phase-3-clinical-data-workflows; starter-build-ready; Create a sandbox where clinical workflows, agents, prompts, models, FHIR transforms, and QA findings can be reviewed before any protected use.

## Agents To Build
- Clinical Intake Agent: Collect synthetic or approved intake context, classify missing evidence, and create reviewer-ready intake packets. First milestone: Synthetic intake packet with evidence, limitations, confidence, and escalation criteria.
- FHIR Validation Agent: Explain deterministic FHIR validation results, propose safe transformations, and route invalid resources to interoperability review. First milestone: No-PHI FHIR validation report with errors, severity, and remediation proposal.
- Imaging Integration Agent: Validate synthetic imaging metadata/report evidence and route imaging tasks to specialist review without diagnostic authority. First milestone: Synthetic imaging metadata and report validation packet.
- Clinical QA Agent: Score clinical-like drafts for evidence, hallucination, missing-data, guideline, bias, freshness, and reviewer-gate quality. First milestone: Clinical QA scorecard bound to execution-attempt evidence.
- Patient Engagement Agent: Draft general education and engagement materials for review while blocking outreach and patient-specific advice. First milestone: Reviewed, general-education draft with no outreach authority.
- Configuration Drift Agent: Compare desired and observed platform configuration, redact secrets, and create owner-routed drift findings. First milestone: Read-only drift report with deployment block recommendation.
- AI Cost Intelligence Agent: Monitor model/tool usage, detect cost anomalies, and recommend budget-safe routing changes. First milestone: Cost anomaly event and route recommendation packet.
- Autonomous Remediation Agent: Draft evidence-linked remediation plans while leaving execution blocked until human approval. First milestone: Suggestion-only remediation packet with blocked execution state.

## Starter Repository Layout
- app/lib/scrimedOSImplementationPlan.ts for typed architecture contracts.
- app/api/scrimed-os/implementation-plan/route.ts for machine-readable roadmap.
- app/scrimed-os/page.tsx for executive, engineering, and investor review.
- packages/event-mesh for future event envelope, outbox, broker adapters, and replay.
- packages/agent-runtime for identity, scopes, CodeMode, MCP gateway clients, and traces.
- packages/registries for agent, prompt, policy, model, and evaluation registry schemas.
- packages/clinical-workflows for deterministic orchestrator, FHIR validation, imaging contracts, and clinical QA.
- infra/ for IaC, Kubernetes, policy-as-code, canary, and rollback templates.

## Validation
- PASS all-requested-capabilities-mapped: All 25 requested SCRIMED OS capabilities must be represented in the roadmap.
- PASS event-driven-by-default: Every capability must emit at least one auditable event.
- PASS zero-trust-agent-identity: Agent identity, least privilege, revocation, scopes, and trust scores are first-class.
- PASS no-direct-llm-database-access: Generated SQL/FHIR queries must pass validation middleware before access.
- PASS registries-covered: Agent, prompt, policy, model, and evaluation registries are explicit.
- PASS human-in-the-loop-clinical-safety: Clinical-like outputs remain review-gated and cannot become autonomous care.
- PASS secure-rag-preserves-structure: RAG ingestion must preserve document structure and provenance.
- PASS agent-backlog-includes-patient-safety-surface: The truncated Patient agent request is safely modeled as review-gated patient engagement with no outreach authority.
- PASS production-mutation-blocked: Every capability names blocked autonomous behavior before production approval.

## Next Implementation Step
Build the Event Mesh plus Agent Identity Registry first, then bind Secure MCP Gateway and CodeMode Runtime to those identities before any clinical workflow or data connector receives tool access.