Build governed clinical protocol modules.

Create, validate, plan, and request review.

GitMed gives medical AI teams a reproducible workflow for deterministic protocol modules. Authors define the module in structured files, validate the clinical and technical requirements, inspect the behavior diff, and route the release for the right clinical, safety, and quality review.

$ gitmed init adult_sinusitis --template diagnostic-triage
$ gitmed validate protocols/adult_sinusitis
$ gitmed test protocols/adult_sinusitis --suite regression
$ gitmed plan \
  --from adult_sinusitis@0.1.0 \
  --to protocols/adult_sinusitis \
  --out .gitmed/plans/adult_sinusitis-0.2.0.json
$ gitmed release request protocols/adult_sinusitis \
  --version 0.2.0 \
  --plan .gitmed/plans/adult_sinusitis-0.2.0.json

protocols/adult_sinusitis/
  protocol.yaml
  facts.yaml
  rules.yaml
  sources.yaml
  contracts/
    intake.extractor.yaml
  evals/
    red_flags.yaml
    regression.yaml
    contracts/
      intake_extractor.yaml
    security/
      prompt_injection.yaml
  release.yaml

Add GitMed to the repository that owns the clinical workflow.

GitMed is designed to run in the same version-controlled repo as the protocol modules, eval suites, model contracts, and release metadata. Local commands can run without PHI; hosted validation can be enabled when teams want Auddax-managed registries, review queues, and evidence exports.

$ npm install --save-dev @auddax/gitmed
$ npx gitmed auth login --org northstar-health
$ npx gitmed workspace init \
  --protocol-dir protocols \
  --build-dir .gitmed/build

created .gitmed/config.yaml
created protocols/
created .gitmed/plans/

schema: gitmed.workspace/v0.1
organization: northstar-health
protocol_dir: protocols
build_dir: .gitmed/build
validation:
  mode: hosted
  phi_policy: deidentified_only
registry:
  environment: sandbox

Facts carry type, provenance, freshness, and admissibility.

Protocol rules do not consume raw messages, device feeds, or EHR fields directly. GitMed facts define what a workflow is allowed to know, where the value came from, how fresh it must be, and whether it can support context, triage, urgent disposition, or only clinician confirmation.

schema: gitmed.facts/v0.1
module: adult_sinusitis

facts:
  - id: symptom_duration_days
    type: integer
    source: patient_report
    required_for:
      - triage
      - disposition

  - id: double_worsening
    type: boolean
    source: patient_report
    required_for:
      - triage

  - id: periorbital_swelling
    type: boolean
    source: patient_report
    required_for:
      - red_flag_screen

  - id: wearable_resting_heart_rate
    type: number
    source: device.apple_health
    freshness: 24h
    admissibility:
      context: allowed
      triage: requires_confirmation
      urgent_disposition: excluded
    quality:
      min_samples: 3
      patient_state: resting

Model roles are bounded before they touch clinical logic.

A model contract defines the allowed inputs, output schema, blocked claims, and failure behavior for one bounded model role. The protocol can consume emitted facts only after the contract validator accepts the schema and provenance.

schema: gitmed.contract/v0.1
module: adult_sinusitis
role: intake.extractor
model_ref: customer-model:intake-v3

allowed_inputs:
  - patient_message
  - encounter_context
  - admissible_background_facts

may_emit:
  - facts
  - uncertainty
  - source_spans

blocked_outputs:
  - diagnosis
  - disposition
  - treatment_plan

output_schema: schemas/intake-facts.schema.json
violation_action: quarantine
eval_suites:
  - evals/contracts/intake_extractor.yaml
  - evals/security/prompt_injection.yaml

Cases assert clinical behavior, not just model accuracy.

Eval suites can cover regression paths, red flags, exclusions, subgroup boundaries, prompt injection, missing facts, and cross-protocol ambiguity. Each case specifies the facts supplied to the module and the expected output state, trace path, and release-gate impact.

schema: gitmed.eval/v0.1
module: adult_sinusitis
suite: red_flags

cases:
  - id: rf_orbital_swelling_001
    facts:
      symptom_duration_days: 4
      periorbital_swelling: true
      vision_change: false
      ophthalmoplegia: false
    expected:
      output: urgent_clinician_review
      trace_contains:
        - orbital_complication
      gate_on_failure: block_release

$ gitmed test protocols/adult_sinusitis \
  --suite red_flags \
  --format yaml

suite: red_flags
cases: 18
passed: 18
failed: 0
release_gate: pass

Compiled modules run with pinned versions and replayable traces.

The application layer calls a compiled kernel with admissible facts and validated model-role outputs. The runtime response includes the output state, protocol reference, evidence links, and trace ID needed for incident replay or ClearanceOS export.

import { loadKernel } from "@auddax/gitmed-runtime";

const kernel = await loadKernel(
  ".gitmed/build/adult_sinusitis/0.2.0/kernel.json"
);

const result = await kernel.evaluate({
  encounterId: "enc_7f31",
  facts: {
    symptom_duration_days: { value: 12, source: "patient_report" },
    double_worsening: { value: true, source: "patient_report" },
    periorbital_swelling: { value: false, source: "patient_report" }
  },
  modelOutputs: {
    "intake.extractor": "validated:mo_91ac"
  }
});

console.log(result.output.state);
console.log(result.trace.id);
console.log(result.protocol.ref);

Clinical modules move through a governed development lifecycle.

Each GitMed module is a versioned clinical software artifact. The workflow keeps engineering changes, clinical rationale, model boundaries, validation results, release decisions, and runtime traces tied to the same module record.

A clinical module is a folder of governed specifications.

A GitMed module is deliberately declarative. Authors describe clinical intent, facts, rules, sources, model boundaries, evaluation cases, and release requirements in structured files that can be reviewed by clinicians and compiled by engineering teams.

Structured files make clinical logic reviewable and compilable.

GitMed protocol specs use constrained YAML for deterministic clinical logic. Clinicians can review the pathway, sources, and intended use; engineers can compile the same files into runtime artifacts, test suites, SDK types, and evidence records.

schema: gitmed.protocol/v0.1
module: adult_sinusitis
version: 0.2.0
intended_use:
  statement: adult sinusitis diagnostic triage support
  user: clinician_supervised_ai_assistant
  setting: outpatient_virtual_care

scope:
  population:
    age: ">=18"
  exclusions:
    - immunocompromised
    - pregnancy
    - recent_sinus_surgery

required_facts:
  - id: symptom_duration_days
    type: integer
    source: patient_report
  - id: fever_celsius
    type: number
    source: patient_report
  - id: double_worsening
    type: boolean
    source: patient_report

red_flags:
  - id: orbital_complication
    when:
      any:
        - fact: periorbital_swelling
          equals: true
        - fact: vision_change
          equals: true
        - fact: ophthalmoplegia
          equals: true
    output: urgent_clinician_review
    source_refs:
      - idsa-2012-rhinosinusitis-red-flags

Predicate syntax is intentionally constrained so clinical reviewers can inspect the logic and the runtime can replay the same facts, protocol version, and rule path deterministically.

The plan is a clinical behavior diff.

A GitMed plan tells the team what would clinically change before a module can move forward. The output is designed for engineering review, clinical review, safety review, and ClearanceOS evidence capture.

$ gitmed plan \
  --from chest_pain@2.3.1 \
  --to protocols/chest_pain \
  --format yaml

module: chest_pain
from: 2.3.1
to: working_tree
clinical_delta:
  changed_questions: 5
  changed_dispositions: 3
  new_exclusions: 2
  new_red_flags: 1

required_evidence:
  - source_rationale
  - behavior_diff
  - red_flag_replay
  - subgroup_eval
  - clinical_signoff

release_gate:
  inside_change_boundary: false
  decision: higher_review_required
  required_signoffs:
    - cardiology
    - safety
    - release_owner

A build can fail for clinical reasons, not just syntax.

GitMed gates are machine-checkable and clinically reviewable. A module can pass schema validation and still fail release readiness because a rule lacks a source, a red flag regressed, or a subgroup boundary changed without the required evidence.

The spec compiles into runtime and evidence artifacts.

A compiled module produces the files needed to run, integrate, review, and defend a clinical workflow: deterministic kernels for Auddax runtime, SDK types for application teams, FHIR/CDS Hooks integration artifacts, CI outputs, reviewer packets, and ClearanceOS evidence records.

$ gitmed compile protocols/chest_pain \
  --version 2.4.0 \
  --target release \
  --out .gitmed/build

generated:
  kernel: .gitmed/build/chest_pain/2.4.0/kernel.json
  trace_schema: .gitmed/build/chest_pain/2.4.0/trace.schema.json
  sdk_types: .gitmed/build/chest_pain/2.4.0/sdk/typescript.d.ts
  fhir_plan_definition: .gitmed/build/chest_pain/2.4.0/fhir/PlanDefinition.json
  clearanceos_record: .gitmed/build/chest_pain/2.4.0/evidence/release-record.json

runtime:
  deterministic_kernel: ready
  trace_schema: ready
  release_registry: pending_signoff

GitMed turns protocol safety into a pull-request gate.

CI checks protocol edits, model-contract edits, eval additions, source updates, and release metadata before merge. Automated gates do not replace clinical review; they prevent incomplete changes from entering review without the required evidence.

name: gitmed-protocol-gates

on:
  pull_request:
    paths:
      - "protocols/**"
      - ".github/workflows/gitmed.yml"

jobs:
  protocol-gates:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: auddax/setup-gitmed@v1
      - name: Validate changed modules
        run: gitmed validate protocols --changed --base origin/main
      - name: Run regression suites
        run: gitmed test protocols --changed --suite regression
      - name: Build clinical plan
        run: |
          gitmed plan --base origin/main --head HEAD \
            --out .gitmed/plan.json
      - name: Enforce release gates
        run: |
          gitmed release gate .gitmed/plan.json \
            --require-sources \
            --require-signoff-plan

The language is optimized for clinical review and deterministic execution.