No clinical logic should reach patients unless it is reviewed, validated, traceable, versioned, and reversible.
Release principle
A clinical release should be safe to activate, safe to audit, and safe to roll back. Every release answers five questions before production. If any cannot be answered, the release should not proceed.Types of releases
Not all releases carry the same risk. A release that changes clinical interpretation must always be treated as high-risk, even if the code change looks small.Versioning model
Every release has explicit versioning. Historical reproducibility requires that a decision made months ago be reproducible with the rule version, calibration version, evidence, and adjustment active at that time. Without versioning, historical audit becomes unreliable. Versioned artifacts include the engine schema, runtime, biomarker definitions, thresholds and rules, calibrations, patterns, treatment flags, safety rules, message templates, evidence sources, AI-agent prompts or tools, consent text, and deployment configuration.Release environments
The system uses separate environments. Clinical logic should never move directly from development to production.Pre-release checklist
Before a clinical release, the team completes a structured checklist. Activation is gated, and clinical content is notACTIVE until it passes review and release gates.
Schema version recorded, runtime version recorded, clinical content diff prepared, evidence source attached, Medical Director review completed, golden tests passing, boot validators passing, runtime output trace validated, patient-facing messages approved, review-state visibility confirmed, sensitive-data/consent impact reviewed (if applicable), AI-agent behavior reviewed (if applicable), dependency/vendor impact reviewed (if applicable), security impact reviewed (if applicable), rollback plan documented, release owner assigned, and post-release monitoring plan prepared.
Release gates
Two gates run in parallel: a clinical gate and an engineering gate. The clinical gate exists because software tests alone cannot determine whether clinical behavior is appropriate.- Clinical release gate
- Engineering release gate
Confirms the medical content is ready by reviewing:
- Evidence — does every active clinical object have a cited source or approved rationale?
- Medical review — did the Medical Director approve the logic?
- Calibration safety — are applies-when conditions specific and conservative?
- Suppression behavior — are confounded results blocked or routed correctly?
- Hardening behavior — are diagnoses prevented when confirmation is required?
- Treatment boundary — are treatment flags advisory only?
- Patient language — does wording avoid diagnosis, eligibility, or prescription claims unless clinician-approved?
- Visibility — are clinician-only states blocked from final patient display?
- Escalation — are
CRITICALand review states routed correctly? - Monitoring — is there a plan to detect unsafe or unexpected behavior?
Boot-time validators before serving
Boot-time validators run before the engine serves clinical output. The rule: if the engine cannot validate itself, it should not serve patient-facing interpretation.Golden test execution
Golden test cases run before every clinical release as the regression backbone — any schema change is re-run against expected outputs. The release suite covers normal baseline,WATCH, ACTION, CRITICAL, missing data, suppression, hardening, calibration, pattern detection, treatment flags, visibility, runtime trace, and lifecycle blocking.
Patient-facing message release
Patient-facing language has its own release control, because a message change can be clinically meaningful even when no rule changes. Message release covers result explanations,WATCH/ACTION/CRITICAL explanations, missing-data prompts, calibration explanations (no broad ancestry or identity generalization), treatment pathway messages (no eligibility or authorization language), review-pending messages, and consent text. Message release must preserve the boundary that ambiguous or high-stakes results route to clinician-only review states.
AI-agent release control
AI-agent releases require special review because agents can affect patient communication and clinician workflow. The release reviews agent scope, tool access, patient-facing language, clinical grounding, review-state handling, treatment boundary, sensitive data access, model provider details, monitoring, and rollback. Agents do not prescribe, do not override the deterministic engine or clinician, and route ambiguous clinical situations to licensed clinician review.Production activation
Production activation should be explicit. Approval and activation should not be collapsed:MD_APPROVED means clinically approved; ACTIVE means released for runtime use.
ACTIVE, Medical Director approval exists, the release gate passed, validators passed, patient visibility was reviewed, the version was recorded, and monitoring is enabled.
Feature flags and staged rollout
High-risk releases should use controlled rollout where possible. For new calibrations, treatment flags, and high-risk patterns, shadow mode is especially useful — it lets the team observe how often a rule fires and whether clinicians agree before patient-facing activation.Rollback
Rollback triggers
Rollback is triggered by predefined events, so it does not require debate in the moment: golden test failure after release, boot validator failure, patient-facing overstatement, clinician-only state exposed, calibration over-applies, treatment flag appearing as authorization,CRITICAL state failing to escalate, lab mapping error, agent inventing clinical advice, security or privacy incident, clinician disagreement spike, or an evidence issue discovered.
Rollback methods
Different failures require different methods. The system preserves affected decision records even after rollback — auditability should not disappear when logic is reverted.Affected-decision review
After rollback, the team identifies affected decisions, which decision traceability makes possible. The review answers which decision IDs and patients were affected, which rules or calibrations fired, what the patient saw, whether clinicians reviewed the output, whether treatment was affected, whetherCRITICAL findings were involved, whether patients should be contacted, whether the rule should be revised or retired, and whether validation tests should be added.
Post-release monitoring
Every clinical release has a monitoring window that begins immediately after activation and continues through a defined observation period. Signals include rule firing rate, calibration firing rate, review-state volume, suppression rate,CRITICAL escalation, missing-data rate, treatment flag rate, clinician rejection rate, patient confusion reports, agent output issues, runtime errors, validator warnings, and lab normalization errors.