# clinical-ai-validation-harness

> A validation harness for clinical AI on OpenMRS and OpenELIS — specs, plans, and visual canvases, mirrored here as full static HTML for LLM agents.


---

# Why local-first clinical AI

The home page makes a set of claims in plain language: that much of the world's care
happens offline, that cloud-trained AI fits those patients poorly, that patient data
should stay on site, that small models can't be trusted to check themselves, and that
this is now a solvable problem. This page is the evidence behind each of those claims,
with sources. Where the underlying research is recent or qualified, that is noted —
nothing here is stronger than what the sources actually support.

> Sources, exact figures, and confidence notes are collected in the project's
> research file: [Background & evidence (research)](#/spec/specs/artifacts/planning/global-health-ai-background-research-2026-06-14).

## Where most primary care actually happens

The setting, not the algorithm, is what makes this hard.

- **Power.** Close to **1 billion people** in low- and lower-middle-income countries are served by health facilities with unreliable electricity or none at all; in sub-Saharan Africa only about **40%** of facilities have reliable electricity ([WHO, 2023](https://www.who.int/news-room/fact-sheets/detail/electricity-in-health-care-facilities)).
- **Connectivity.** **78%** of people in low-income countries are offline, and in rural areas only about **1 in 6** use the internet ([ITU, Facts and Figures 2024](https://www.itu.int/itu-d/reports/statistics/2024/11/10/ff24-internet-use-in-urban-and-rural-areas/)). An always-online, cloud-only design cannot reach them.
- **People.** WHO projects a shortfall of roughly **11 million health workers by 2030**, concentrated in low- and lower-middle-income countries ([WHO health workforce](https://www.who.int/health-topics/health-workforce)). (The exact figure has moved across WHO documents; treat it as an order of magnitude.)
- **The consensus fix.** A 2026 scoping review of clinical-AI deployment in these settings found fragile infrastructure, hardware limits, and fragmented records to be the dominant barriers, and recommended **offline-capable AI with local data caching** ([Al-Ganad et al., *Frontiers in Digital Health*, 2026](https://www.frontiersin.org/journals/digital-health/articles/10.3389/fdgth.2026.1743634/full)).

## Why high-income-trained AI underperforms here

- WHO's own guidance warns that AI "systems trained primarily on data collected from individuals in **high-income countries may not perform well** for individuals in low- and middle-income settings" ([WHO, *Ethics and governance of AI for health*, 2021](https://www.who.int/news/item/28-06-2021-who-issues-first-global-report-on-ai-in-health-and-six-guiding-principles-for-its-design-and-use)).
- That is borne out in practice: a 2025 review reports LLMs make **up to three times more errors** on information about low-income countries, and accuracy can fall sharply in lower-resourced languages — while over **87%** of healthcare-LLM research is led by high-income-country institutions ([Chen et al., *Lancet Regional Health – Western Pacific*, 2025](https://pmc.ncbi.nlm.nih.gov/articles/PMC12556221/)). (Some underlying figures are single-source within that review.)

The AI is least reliable exactly where it is needed most — which is the case for contextualizing it to each deployment rather than shipping one global model.

## Why patient data should stay local

- WHO cautions that data disclosed to a model provider "can usually not be retrieved as future iterations of the model may be trained on this data" ([WHO, *Guidance on large multi-modal models*, 2024](https://www.who.int/news/item/18-01-2024-who-releases-ai-ethics-and-governance-guidance-for-large-multi-modal-models)).
- A review of **464** healthcare-LLM studies found six distinct privacy risks from external/cloud models, that **38%** reported no patient-data protection at all, and recommended that "**priority should be given to deploying the LLM locally**" ([Zhong et al., *JMIR*, 2025](https://www.jmir.org/2025/1/e76571)).
- The governance literature points the same way: the Health Data Governance Principles call for keeping data "close to their point of generation," and at WHO's 2026 digital-health debate, low- and middle-income countries argued health data should be "a national asset under local control" ([Health Data Governance Principles](https://healthdatagovernance.org/principles/); [Health Policy Watch, 2026](https://healthpolicy-watch.news/who-debates-global-ai-rules/)).

"Patient data never leaves the deployment" is the architecture that answers this body of guidance directly.

## Why small, right-sized open models — with a strong judge

- **Small can run offline.** A 3.8-billion-parameter open model runs fully offline on a phone at roughly the quality of a previous-generation cloud model ([Microsoft Research, Phi-3 technical report, 2024](https://arxiv.org/abs/2404.14219)).
- **Open is closing the gap.** On 1,933 real radiology cases, the leading closed model scored 79.6% and the best open model 73.2% — the authors concluded "open-source LLMs are quickly closing the gap to proprietary LLMs" ([Kim et al., *npj Digital Medicine*, 2025](https://pmc.ncbi.nlm.nih.gov/articles/PMC11814077/)). Open medical models such as MedGemma are explicitly built to run locally or offline ([Sellergren et al., 2025](https://arxiv.org/abs/2507.05201); its top score uses extra test-time computation).
- **Right-size the model to the job.** Matching model size to task difficulty — small models for routine work, escalating only when needed — captures most of the quality at a fraction of the cost (survey: [Moslem & Kelleher, 2026](https://arxiv.org/abs/2603.04445); direction is robust, exact savings are setup-dependent).
- **But a small model can't check itself.** In a 2026 study, AI self-verification wrongly accepted incorrect medical answers **more than 60%** of the time, and smaller models were no better — the authors warn it "cannot serve as a universal safety layer" ([Jin et al., 2026](https://arxiv.org/abs/2605.10850), a recent preprint). That is why grading is escalated to a stronger model rather than left to the local team.

This is exactly the project's design: a team of small, right-sized open models doing the work, every answer grounded in the record, and a stronger judge checking the result.

## Why guideline-concordant and testable

WHO's **SMART Guidelines** exist to turn paper recommendations into a standards-based, computable form so digital systems deliver guideline-concordant care faithfully and faster — organized as a ladder of knowledge layers from **L1 narrative** through machine-readable and executable forms ([WHO SMART Guidelines](https://www.who.int/teams/digital-health-and-innovation/smart-guidelines); [WHO, 2021](https://www.who.int/news/item/18-02-2021-from-paper-to-digital-pathway-who-launches-first-smart-guidelines)). The first such guidelines covered antenatal care, family planning, STIs, and HIV — HIV being **one** concrete example of a computable WHO guideline, not the limit of what a validation harness covers.

The point of contact for this project is the standard itself: software that delivers clinical guidance should be **standards-based, verifiable, and testable** — exactly the property the harness checks for, for any clinical-AI surface, by tracing every answer to evidence rather than trusting it. WHO's AI guidance reinforces the bar, warning that large models carry "documented risks of producing false, inaccurate, biased, or incomplete statements" and can encourage "automation bias" where errors go unnoticed ([WHO, 2024](https://www.who.int/news/item/18-01-2024-who-releases-ai-ethics-and-governance-guidance-for-large-multi-modal-models)).

## The through-line

| The reality | The project's answer |
|---|---|
| Care runs offline, on modest hardware | A local team of small models; offline-capable, no cloud dependency |
| High-income-trained AI underperforms for these patients | A knowledge base contextualized to each deployment's own concepts and drugs |
| Sending data to clouds is a privacy and sovereignty risk | Patient data never leaves the deployment |
| Models hallucinate; small models can't self-verify | Every answer traced to a record; a stronger model grades, not the small one |
| Clinical software should be guideline-concordant and testable | A validation harness: real systems, real data, reviewable evidence at every step |

The argument in one line: **the way clinical AI is usually built is wrong for where most primary care actually happens — and there is now a credible, evidence-graded way to do it right: local, contextualized, and traceable.**


---

# clinical-ai-validation-harness

A validation harness for early clinical AI tools — helping teams test AI-powered clinical systems against realistic health data and real integration paths, with traceable, reviewable evidence at every step.

The harness currently focuses on OpenMRS-based clinical AI (chart search, query retrieval, clinical chat) and OpenELIS lab-system AI (Catalyst). Validation means real systems, real data, and decisions that can be traced back to specific clinical records — not just passing unit tests.

## Why this matters

Much of the world's primary care runs in settings with intermittent connectivity, modest hardware, few IT staff, and strong reasons to keep patient data local. Clinical AI for these settings has to run **offline and on less-powerful hardware**, keep **patient data on-site** (privacy and local data ownership), and **fit local clinical reality** — guidelines, and the data most AI is trained on, come from better-resourced settings, leaving the conditions, formularies, and populations of low-resource clinics underrepresented in clinical research and guidelines. That shapes every choice here: local small-model profiles, including both fast single-model and deliberate team configurations, a knowledge base contextualized to each deployment's own concepts and drugs, and validation against real local systems with every claim traceable to a specific record. The intent mirrors WHO's [SMART Guidelines](https://www.who.int/teams/digital-health-and-innovation/smart-guidelines) — let local programs benefit from global evidence while adapting it to their own context — applied to the question "can we trust this AI here?"

## Who this is for

- **Clinical and program stakeholders** — understand how AI answers are evaluated, what evidence backs a validation claim, and where the governance guardrails are.
- **Technical collaborators** — run the harness locally or on a VM, inspect transforms and run artifacts, and contribute code or mapping reviews.
- **AI validation and research readers** — explore the evidence model, evaluation methodology, and metadata schema across retrieval, answer quality, citation, abstention, and safety dimensions.
- **OpenMRS / OpenELIS community members** — see how demo data is modernized for the latest Reference Application, how harness tools relate to existing modules, and what parts could be reused.

## What this harness validates

The harness coordinates validation across four clinical AI projects:

| Project | What it does | Role here |
|---------|-------------|-----------|
| `chartsearchai` | OpenMRS clinical-chat module with bundled and med-agent-hub provider paths | Product integration target: shared lifecycle UX, persistence, evidence display, cancellation, and security |
| `querystore` | Read-optimized OpenMRS clinical-record projection and optional med-agent-hub source | Context-source validation: materialized records, indexing integrity, date/freshness semantics, and retrieval experiments |
| `openmrs_chatbot` | Python clinical chatbot with patient/doctor interfaces and agent workflow scaffolding | Future expansion: multi-turn grounding and role-aware answer evaluation |
| `Catalyst` (OpenELIS) | Supervised reporting workbench: OpenELIS → HAPI FHIR → FHIR Data Pipes → governed query/table → versioned Dataset/Widget/Dashboard drafts → Superset bundle | Query/notebook MVP accepted; Superset-backed Dashboard Builder selected next; data, repair, evaluation, narrative, and production paths remain independently gated |

## Current priority: the validation spine and active lanes

The OpenMRS demo-data remap (Roadmap M1 / feature 002) is **complete** — the public 2.7 demo corpus is transformed and imported as the canonical 5,284-patient 2.8 demo schema the harness validates against. (See the [Feature 002 spec](https://github.com/pmanko/clinical-ai-validation-harness/blob/main/specs/002-openmrs-demo-data-2-8-remap/spec.md) and [quickstart](https://github.com/pmanko/clinical-ai-validation-harness/blob/main/specs/002-openmrs-demo-data-2-8-remap/quickstart.md) for that work.)

Current work is the **dual-provider foundational-parity roadmap**: preserve bundled ChartSearchAI
inference as the fresh-install default while allowing a configured med-agent-hub provider through
the same OpenMRS conversation, evidence, persistence, and cancellation contract. QueryStore remains
an OpenMRS projection with an optional hub adapter, not a hub dependency. The current integration
branches carry that contract and are the source of truth for harness proof; upstream PR merge state
does not gate local integration. See the checked-in [roadmap](specs/artifacts/planning/openmrs-dual-provider-parity-roadmap.md),
[status](specs/artifacts/planning/openmrs-dual-provider-parity-roadmap-status.md), and
[upstream inventory](specs/artifacts/planning/openmrs-dual-provider-upstream-inventory.md).

## How the docs fit together

| What you need | Where to go |
|---------------|-------------|
| Visual project overview and navigation | [Public docs site](https://pmanko.github.io/clinical-ai-validation-harness/) |
| Roadmap — what is planned, why, and in what order | [Feature roadmap canvas](https://pmanko.github.io/clinical-ai-validation-harness/#/canvas/specs/roadmap) |
| Development operating plan — lanes, gates, launch sequence | `specs/artifacts/lanes/` (in-repo) |
| Validation evidence model and evaluation methodology | [Validation research canvas](https://pmanko.github.io/clinical-ai-validation-harness/#/canvas/specs/artifacts/canvases/validation-research) |
| Current priority operator walkthrough | [Feature 002 quickstart](https://github.com/pmanko/clinical-ai-validation-harness/blob/main/specs/002-openmrs-demo-data-2-8-remap/quickstart.md) |
| Harness foundation and control-plane detail | [Feature 001 spec](https://github.com/pmanko/clinical-ai-validation-harness/blob/main/specs/001-harness-control-plane-foundation/spec.md) |
| Catalyst product pathways and selected milestone | [Catalyst product roadmap status](specs/artifacts/planning/catalyst-product-roadmap-status.md) |
| All planning artifacts, canvases, and research docs | [specs/artifacts/](https://github.com/pmanko/clinical-ai-validation-harness/tree/main/specs/artifacts) |
| Superseded pre-hub cloud guide | [docs/cloud-deploy.md](https://github.com/pmanko/clinical-ai-validation-harness/blob/main/docs/cloud-deploy.md) |

The public docs site auto-deploys from `main` and publishes the public-facing surface — this README and the visual canvases. The detailed feature specs, plans, briefs, and per-lane dossiers are dev-internal: they live in the repo (under `specs/`), not on the published site. Browse the site locally with `cd site && npm install && npm run dev` (opens at `http://127.0.0.1:4321/clinical-ai-validation-harness/`).

## Milestone names and IDs

Human-facing docs use plain names. IDs appear in parentheses on first use and inside technical specs.

| Plain name | Roadmap ID | Feature folder | Status |
|-----------|-----------|----------------|--------|
| Harness foundation | M0 | `001` | Complete |
| OpenMRS demo-data remap | M1 | `002` | Complete |
| Validation spine | M2 | `006` | In progress (validation-harness MVP; runner/report/feedback shipped — see lane L3) |
| Real adapter entrypoints | M3 | `004` | In progress |
| med-agent-hub service | F005 | `005` | Shipped as the configured profile-driven provider; Catalyst uses its shared profile schema and named-role executor |
| LLM config overrides | F007 | `007` | Superseded by explicit provider/profile configuration |
| med-agent-hub MCP tools | F010 | `017` | Superseded; dead MCP/A2A runtime removed |
| ChartSearchAI model gateway | F008 | `008` | Bundled and configured-Hub providers preserved behind the [dual-provider roadmap](specs/artifacts/planning/openmrs-dual-provider-parity-roadmap.md) |
| Clinical knowledge base | F009 | `009` | [Brief + research](https://github.com/pmanko/clinical-ai-validation-harness/blob/main/specs/artifacts/planning/clinical-kb-brief.md) |
| Retrieval evaluation | M4 | `010` | Planned |
| Catalyst supervised reporting | M10 | `008` | Query/workbench foundation accepted; Dashboard Builder M3 accepted 2026-08-06; M4 release hardening in progress |
| Answer, citation, and abstention | M5 | `012` | Planned |
| Safety and red-team | M6 | `013` | Planned |
| Clinician governance review | M7 | `014` | Planned |
| Querystore parity testbed | M8 | `015` | Planned |
| Cross-project expansion | M9 | `016` | Planned |

> **Note on feature 002 internal phases:** Work inside the OpenMRS demo-data remap (M1 / `002`) uses implementation sub-labels `M2-A` through `M2-Z` in detailed feature docs. These are internal planning labels for that feature's phases — not related to roadmap milestone M2 (Validation spine).

> **Note on F-prefixed IDs and non-monotonic slugs:** F005, F007, F008, F009, F010 are features inserted into the roadmap after the M0–M10 sequence was authored. The validation spine (M2) shipped as slug `006` (validation-harness MVP) — the earlier `003` slug was never created. `007` is LLM config overrides (F007); `017` is the med-agent-hub MCP tools (F010). The Roadmap IDs (M0–M10, F005–F010) carry the semantic ordering anchor; folder slugs are filesystem identifiers and may be non-monotonic. See [`specs/roadmap.canvas.tsx`](https://pmanko.github.io/clinical-ai-validation-harness/#/canvas/specs/roadmap) for the dependency DAG.

> **Note on M10 and repository ownership:** The harness is the umbrella repository. Catalyst and Med-Agent Hub are pinned as sibling submodules under `targets/`; Catalyst contains no nested Git submodules. The umbrella runner builds the pinned Hub sibling directly. Standalone Catalyst may clone the same unmodified Hub commit as a disposable fallback, alongside its disposable OpenELIS and FHIR Data Pipes checkouts.

## Principles

How validation claims are made and how evidence is handled:

- **Use real paths.** Run real OpenMRS, real `chartsearchai`, and real adapters. Stubs and simulations are labeled as scaffolding and cannot count as production-path evidence.
- **Separate clinical data from operating metadata.** Record-level clinical evidence lives in the database or SQL artifacts. Run manifests, event traces, and evaluation records are metadata kept separate.
- **Keep LLM output advisory.** Machine-generated mapping proposals are starting points only. Accepted mappings must be reviewed and stored in deterministic, versioned artifacts before use.
- **Require record-level evidence.** Validation claims trace to specific records — not just counts or aggregate metrics.
- **Cover diverse scenarios.** Evaluation sets include edge cases, absent-data cases, and adversarial inputs — not only the happy path used to tune a prompt or mapping.
- **Document material changes.** Significant changes to models, prompts, retrieval, mappings, or pipelines require a change record (PCCP — see Key Terms). This keeps decisions reviewable and reproducible.

The canonical governance reference is `.specify/memory/constitution.md`.

## Repository layout

```
docs/          User-facing guides and operator runbooks
specs/         Feature specs, plans, research docs, and canvases; specs/artifacts/ for cross-cutting materials
compose/       Docker Compose files for the OpenMRS/MariaDB stack and optional services
datasets/      Source pointers, mapping artifacts, deterministic transforms, and fixtures
harness/       Python orchestration package and CLI (harness-cli)
adapters/      Adapter contracts for invoking real project validation paths
evals/         pytest suites for import, indexing, retrieval, and metadata checks
artifacts/     Per-run outputs: manifests, events, reports (gitignored)
site/          Static-site build of the README and canvases (public surface); auto-deployed to GitHub Pages
targets/       Pinned submodule checkouts of the four target projects
```

## Quickstart

**Requirements:** Python 3.11+, `uv`, Docker / Docker Compose, Git.

## Catalyst query workbench and dashboard direction

Initialize the two sibling targets without `--recursive`:

```bash
git submodule update --init targets/catalyst targets/med-agent-hub
```

The local sandbox brings up OpenELIS, HAPI FHIR, FHIR Data Pipes, the analytics
database, Catalyst Gateway, the pinned sibling Hub, and the sidecar UI; an
explicit seed command loads the synthetic multi-analyte cohort. Hub owns the
shared Catalyst query profile, prompts, role models, and model knobs. Gateway
owns catalog/context assembly, SQL lint and policy, writer/reviewer
orchestration, execution, and query-version lineage.

The prior final-pin manual workbench was accepted on 2026-08-04 after a 12/12 real-model
matrix, independent PostgreSQL/gold comparisons, bounded failure/recovery, and
actual keyboard-only plus 200%-browser-zoom checks. The deterministic
Playwright notebook path preserves the corresponding focus and reflow boundary.
The Hub-owned profile migration and exact-pin live gate have passed; Dashboard
Builder implementation is now in M4 release hardening.

The selected next product milestone is the Superset-backed Dashboard Builder:
promote governed executions through immutable Dataset, Widget, and multi-widget
Dashboard drafts, then publish a deterministic native ZIP to a shared local
outbox for import by pinned Superset 6.1.0. Catalyst owns the iterative desired
configuration in this one-way MVP; Superset renders it. The prototype's Ask
shell integrates the accepted query notebook without removing its profile/model evidence, single
SQL editor, manual versions, Validate/Run, diagnostics/results, contextual
follow-up, history, refresh, or New session behavior; only the dataset-preview
presentation moves into the builder's Dataset tile/review panel. Multi-source/lossless
onboarding, targeted SQL repair, session-export/comparative experiments,
evidence-linked narratives, and production security are parallel pathways, not
sequential prerequisites. Superset REST API publication, embedded viewing,
cross-system reconciliation, model-generated visualization specifications,
sharing, scheduling, automatic refresh, and production access control remain
outside this milestone.

The original table-only bundle/import implementation was a Superset import
spike, not a smaller Dashboard MVP. The accepted M3 implementation integrates
the real-profile query notebook with the binding 4c Dataset → Widget →
Dashboard experience and native Superset import. M3 closed with focused D1d
evidence and explicit user review on 2026-08-06; exhaustive recovery/evidence
hardening is active M4 work. Actual 200% browser zoom is deferred polish rather
than an MVP gate; desktop and 320/390/640-CSS-pixel reflow coverage remains.
The D1b runtime/lifecycle checkpoint (T139/T140/T160–T162) now passes with
the pinned Superset identity, DB-enforced read-only access, non-destructive
volume restart, retained imported state, secret-free evidence, and synchronized
tests. The deterministic seven-chart, five-family clean-import fixture at T141
also passes; importer/state failure and recovery matrices T142/T163 are next.

The P5 Catalyst report is published at
[reports.openclinai.org/catalyst-t094-release](https://reports.openclinai.org/catalyst-t094-release/):
13/13 scenario repetitions and 411/411 deterministic assertions passed, with
three advisory judge passes retained alongside record-level evidence. PR #43
merged green at `136067a`; optional future evaluation expansion is parallel and
is not a Dashboard MVP implementation dependency.

Start the local OpenAI-compatible router on port `1234`; it must advertise the
exact `google/gemma-4-e4b` writer and `qwen2.5-14b-instruct-mlx` reviewer model
IDs. The only supported manual path is then:

```bash
make catalyst-mvp-external
```

That first-time path starts the isolated stack and explicitly loads the demo
OpenELIS → FHIR → analytics pipeline. Day-to-day restarts retain the stack's
named Docker volumes and do not reload that data:

```bash
make catalyst-mvp-restart
```

Use `make catalyst-mvp-seed` only to deliberately reload the fixture and
`make catalyst-mvp-reset` only to discard the isolated data state.

When a Catalyst dashboard bundle is published, inspect or import it into the
same isolated Superset instance with `make catalyst-superset-status` and
`make catalyst-superset-import`. The latter records the exact Catalyst commit
in its durable local receipt; it does not reload OpenELIS or FHIR data.

The external model URL defaults to `http://host.docker.internal:1234`; override
`MVP_EXTERNAL_ROUTER_URL` only when the real router is elsewhere. Startup fails
if the router cannot advertise both configured profile models. Open
`http://localhost:13000` after the health gate succeeds. Every `make
catalyst-mvp-*` target runs the isolated stack
(`compose/catalyst-mvp-isolated.override.yml`), which publishes the UI on
`13000` and the gateway on `18000` so they cannot collide with another stack on
this host. `3000` is Catalyst's own default, which you get only when running
its compose directly from `targets/catalyst`. `CATALYST_UI_PORT` overrides
either. The profile picker shows only available Hub-owned query profiles and
their exact writer/reviewer models; see
[Catalyst manual LLM testing](docs/catalyst-manual-llm-testing.md). This is
demo-data engineering evidence, not a clinical-quality claim.

After the real-model health gate passes, run the versioned validation suite
against that live Gateway. Hub discovery records the exact model and prompt
configuration used by each role.

```bash
uv run python scripts/run-catalyst-validation.py \
  --suite datasets/validation/catalyst/catalyst-mvp-v1.json \
  --gateway-url http://127.0.0.1:18000
```

Run evidence is written under `artifacts/catalyst-validation/<run-id>/`.

The iterative-query notebook uses the same top-level CLI and reporting archive
as ChartSearchAI. By default it independently checks both the selected query
execution and the hand-authored gold query against read-only PostgreSQL:

```bash
uv run harness-cli catalyst run \
  --suite datasets/validation/catalyst/catalyst-notebook-t094-v1.json

uv run harness-cli catalyst report \
  artifacts/catalyst-notebook-validation/<run-id>
```

After three judge passes are finalized, stage or publish the report and its
relative evidence links with the family-aware publisher:

```bash
scripts/publish-report.sh catalyst \
  artifacts/catalyst-notebook-validation/<run-id> \
  catalyst-t094-release "Catalyst T094 validation"
```

Use `PUBLISH_DRY_RUN=1 REPORTS_ROOT=<temporary-directory>` to render, index,
and verify a publication without cloud or VM access. The legacy
`scripts/validate-publish.sh <run-id> ...` command remains a ChartSearchAI
compatibility wrapper.

```bash
# 1. Install uv (Python environment manager) if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Set up the Python environment and install all dev dependencies
make setup

# 3. Bring up the OpenMRS Reference Application stack through its stable launcher
make up

# 4. Run a schema diff between the legacy 2.7 source and the clean 2.8 baseline
uv run harness-cli schema-diff --output-dir artifacts/schema-diff

# 5. Run the smoke test suite
make smoke
```

If `make` is unavailable:

```bash
uv python install 3.11
uv sync --extra dev
uv run pytest evals/dataset_import evals/metadata
```

Python 3.11+ is required. The project tracks `.python-version = 3.11` and `requires-python = ">=3.11"` in `pyproject.toml`.

For the full OpenMRS demo-data remap workflow, see [specs/002-openmrs-demo-data-2-8-remap/quickstart.md](https://github.com/pmanko/clinical-ai-validation-harness/blob/main/specs/002-openmrs-demo-data-2-8-remap/quickstart.md).

## ChartSearch operations

The approved product shape is **two providers behind one ChartSearchAI experience**. A standard
OpenMRS installation defaults to bundled ChartSearchAI inference. Deployments that configure
med-agent-hub may expose it as an additional provider; changing provider begins a new conversation.
The hub remains a supported direct service and owns its own profile/stage, temporal, review,
grounding, and In-Depth behavior. It is not a required dependency for bundled operation.

The existing hub-relay integration and local commands remain useful for development while the
dual-provider rebuild is in progress, but they do not define the final provider configuration.
Use the roadmap's product-proof gates before treating either path as the released canonical UI.

```bash
# Development helper for the hub path. It does not replace bundled inference or
# declare the hub the default provider in a fresh OpenMRS installation.
make chartsearchai-local

# Useful focused operations:
./scripts/chartsearchai-local.sh --check  # validate prerequisites without starting services
make local-stack-up                  # fast resume: no builds; waits for the existing stack
make local-stack-down                # stop Compose + its managed router; keep named volumes
make openmrs-source-pair-build        # build/stage current Querystore, then ChartSearchAI
make openmrs-source-pair-test         # install pinned Querystore, then test/build pinned ChartSearchAI
./scripts/test-querystore.sh mysql-integration  # real MySQL completeness/read-path contract
./scripts/test-chartsearchai-esm.sh   # frontend tests, typecheck, lint, and production build
./scripts/verify-dual-provider-parity-gates.sh --phase full  # source suites plus exact-head evidence
make llama-router-models             # inspect raw models behind the hub
make chartsearch-build               # same ordered pair build; ChartSearchAI depends on current Querystore API
make med-agent-hub-up                # (re)start the hub on its own
make chartsearch-configure           # write the fixed hub endpoint; profile discovery supplies the default
make chartsearch-doctor              # verify router, hub profile metadata, and module status

# Retrieval backend — querystore's CQRS read store tier
make chartsearch-backend BACKEND=elasticsearch   # or lucene | mysql
```

`make chartsearchai-local` remains the canonical first-run and source-change workflow: it
builds or verifies artifacts, configures the product path, and exercises the real integration.
The `local-stack-*` targets are intentionally narrower daily helpers. They require a configured
`.env.chartsearch` and already-built images/artifacts, start Docker Desktop when supported, and
fail rather than silently rebuilding or reporting an unready stack as healthy. Teardown preserves
the Compose named volumes and only stops a llama-router recorded as managed by this checkout.

**Provider and profile selection.** The final ESM shows no picker with bundled-only configuration.
With hub configured, it shows a provider choice first and the provider's supported profile/mode choices
second. Unready configured providers remain visibly disabled; the UI never invents raw model choices or
silently falls back to another provider.

**Cloud.** The older GCE/LM Link workflow predates the current dual-provider boundary and is not the canonical
proof path. Use the local workflow above while the cloud scripts are reconciled with the same provider contract.

## Key terms

| Term | Meaning |
|------|---------|
| **Harness** | This repository — it orchestrates validation across the four target projects without living inside any of them. |
| **Target** | One of the four clinical AI projects validated here: `chartsearchai`, `querystore`, `openmrs_chatbot`, or Catalyst. |
| **Canvas** | An interactive visual summary page (`.canvas.tsx`) authored in Cursor and published on the docs site. |
| **CIEL** | Columbia International eHealth Laboratory dictionary — the open clinical concept terminology standard used by OpenMRS. |
| **OCL** | Open Concept Lab — the terminology service that hosts CIEL and other clinical dictionaries. |
| **FHIR** | Fast Healthcare Interoperability Resources — used here as the grammar for terminology mapping artifacts (ConceptMap format). |
| **Ref App** | OpenMRS Reference Application, the standard OpenMRS distribution. "O3 Ref App" refers to the current 3.x version on Core 2.8. |
| **SQLMesh** | The deterministic data transformation framework used to materialize the OpenMRS 2.7 → 2.8 migration. |
| **run_manifest.json** | Machine-readable provenance record emitted for every harness run: inputs, versions, component SHAs, and evidence status. |
| **events.jsonl** | Append-only event trace for a run: queries, retrievals, model calls, evaluations, and reviewer actions. |
| **PCCP** | Predetermined Change Control Plan — a structured change record (adapted from FDA AI guidance) used here for material changes to models, prompts, retrieval, mappings, or pipelines. Keeps decisions auditable. |

## Spec Kit and contributor automation

This repository uses [GitHub Spec Kit](https://github.com/github/spec-kit) (`v0.8.9`) for AI-assisted feature specification and planning. Agent and contributor guidance lives in `AGENTS.md`. Cursor skills are in `.cursor/skills/`; Claude skills are in `.claude/skills/`.

Useful skills for contributors:

- `/speckit-specify` — create or update a feature spec
- `/speckit-plan` — generate an implementation plan
- `/speckit-tasks` — generate task lists from a plan
- `/speckit-implement` — execute tasks from `tasks.md`
- `/speckit-analyze` — cross-artifact consistency check

## Notes on source data and sibling repositories

The OpenMRS 2.7 demo corpus (`large-demo-data-2-7-0.sql`) is not stored in this repository. It is expected as a sibling checkout alongside this repo:

```
../openmrs-module-chartsearchai/data/large-demo-data-2-7-0.sql
```

Use an environment variable to override the location:

```bash
export HARNESS_TARGET_CHARTSEARCHAI=/path/to/openmrs-module-chartsearchai
```

The QueryStore source used by builds and validation is the pinned submodule at
`targets/querystore`. Initialize submodules before running the OpenMRS build targets; do not
substitute an unrelated sibling checkout for the tested pin.

For OpenELIS feasibility analysis (feature 002, sub-phase M2-H), the OpenELIS Global 2 repository is read from a sibling checkout (`../OpenELIS-Global-2`) or via `OPENELIS_ROOT=/path/to/OpenELIS-Global-2`.


---

# Validation roadmap

Interactive canvas — full HTML at /clinical-ai-validation-harness/canvas/specs/roadmap.html

---

# Validation research

Interactive canvas — full HTML at /clinical-ai-validation-harness/canvas/specs/artifacts/canvases/validation-research.html

---

# Demo-data profile & cohorts

Interactive canvas — full HTML at /clinical-ai-validation-harness/canvas/specs/artifacts/canvases/demo-data-profile.html

---

# Clinical-AI research guidance

Interactive canvas — full HTML at /clinical-ai-validation-harness/canvas/specs/artifacts/canvases/clinical-ai-research-guidance.html

---

# Scout comparative analysis

Interactive canvas — full HTML at /clinical-ai-validation-harness/canvas/specs/artifacts/canvases/scout-comparative-analysis.html

---

# Catalyst demos

Interactive canvas — full HTML at /clinical-ai-validation-harness/canvas/specs/artifacts/canvases/catalyst-demos.html

---

# Concept mapping & transformation

Interactive canvas — full HTML at /clinical-ai-validation-harness/canvas/specs/artifacts/canvases/concept-mapping-discovery.html

---

# SQLMesh transformation flow

Interactive canvas — full HTML at /clinical-ai-validation-harness/canvas/specs/artifacts/canvases/sqlmesh-transformation-flow.html

---

# chartsearchai & querystore

Interactive canvas — full HTML at /clinical-ai-validation-harness/canvas/specs/artifacts/canvases/chartsearchai-and-querystore.html

---

# Answer / In-Depth parity

Interactive canvas — full HTML at /clinical-ai-validation-harness/canvas/specs/artifacts/canvases/answer-indepth-parity.html

---

# Answer flow — what to simplify

Interactive canvas — full HTML at /clinical-ai-validation-harness/canvas/specs/artifacts/canvases/answer-flow.html

---

# Cross-project comparison

Interactive canvas — full HTML at /clinical-ai-validation-harness/canvas/specs/artifacts/canvases/cross-project-comparison.html

---

# Upstream contribution & compatibility

Interactive canvas — full HTML at /clinical-ai-validation-harness/canvas/specs/artifacts/canvases/upstream-contribution-and-compatibility.html

---

# Validator audit framework

Interactive canvas — full HTML at /clinical-ai-validation-harness/canvas/specs/artifacts/canvases/validator-audit-framework.html

---

# Background & evidence — clinical AI for low-resource health settings

Cited grounding for the project's "why," from authoritative sources (WHO,
peer-reviewed literature, and respected global / digital-health bodies). Each claim is
recorded with its source and a confidence note. Where a figure is qualified, or a
primary source (e.g. some WHO PDFs and paywalled journals) was reached only through an
official summary or abstract rather than the full text, that is stated inline — nothing
should be cited more strongly than the confidence noted here.

---

## 1. WHO SMART Guidelines — computable, guideline-concordant care

- **SMART = Standards-based, Machine-readable, Adaptive, Requirements-based, Testable** — WHO's approach to getting its recommendations into countries' digital systems faithfully and fast. (WHO, "From paper to digital pathway," 18 Feb 2021 — who.int/news; confirmed across 3 sources incl. JMIR 2025. *high*)
- They are "a comprehensive set of reusable digital health components … that transform the guideline adaptation and implementation process to **preserve fidelity and accelerate uptake**." (WHO Digital Health & Innovation — who.int/teams/digital-health-and-innovation/smart-guidelines. *high*)
- Organized into **five knowledge layers (L1–L5)** — "a systematic, transparent and testable structure": **L1 Narrative** (human-readable recommendations) → **L2 Operational** (software-neutral requirements, delivered as Digital Adaptation Kits) → **L3 Machine-readable** (structured specs with coding/terminology/interoperability standards) → **L4 Executable** (software running static algorithms) → **L5 Dynamic** (algorithms optimized with analytics). (WHO smart.who.int DAK pages; L1–L4 *high*, L5 one-line definition *medium* — WHO confirms the name "Dynamic" but L5 content is largely "not yet available".)
- Motivation (peer-reviewed): converting narrative guidelines to digital systems has been "laborious, prone to error, and lacks accompanying technical documentation appropriate for digital use." (Muliokela et al., JMIR Medical Informatics, 7 Feb 2025 — medinform.jmir.org/2025/1/e58858. *high*) Foundational paper: Mehl et al., "WHO SMART guidelines…," Lancet Digital Health, 2021 (PMID 33610488 — thesis confirmed, full text paywalled).
- **Project tie-in:** the harness asks for the same property SMART Guidelines demand of software — answers that are **standards-based, verifiable, and traceable**, not opaque.

**Caveat:** No verified WHO figure for a guideline publication→implementation lag (the popular "17 years" number is *not* sourced to WHO). Speak qualitatively ("delays in uptake").

## 2. WHO ethics & governance of AI / LMMs in health

- WHO's first global guidance, **"Ethics and governance of artificial intelligence for health"** (28 Jun 2021, ISBN 9789240029200), sets six principles: human autonomy; well-being/safety/public interest; transparency & explainability; responsibility & accountability; inclusiveness & equity; responsive & sustainable AI. (who.int/news 28-06-2021. *high*)
- **Equity warning (quotable):** AI "systems trained primarily on data collected from individuals in **high-income countries may not perform well for individuals in low- and middle-income settings**." (WHO, 28 Jun 2021. *high*)
- Second, dedicated guidance, **"…Guidance on large multi-modal models (LMMs)"** (18 Jan 2024, ISBN 9789240084759), 40+ recommendations. (who.int/news 18-01-2024. *high*)
- **Hallucination/harm (quotable):** LMMs carry "documented risks of producing **false, inaccurate, biased, or incomplete statements, which could harm people** using such information in making health decisions." (WHO, 18 Jan 2024. *high*)
- **Automation bias (quotable):** LMMs "can also encourage 'automation bias' … whereby errors are overlooked that would otherwise have been identified." (WHO, 18 Jan 2024. *high*)
- Data risk: data disclosed to LMM developers "can usually not be retrieved as future iterations of the model may be trained on this data." (WHO, 18 Jan 2024. *high*)
- Safeguards WHO recommends: inclusive design with clinicians/patients from the start; mandatory independent post-release auditing & impact assessment; assigning a regulator to approve health LMMs; models designed "to perform well-defined tasks with the necessary accuracy and reliability." (WHO, 18 Jan 2024. *high*)

**Caveat:** the "LMICs used only as a data source" framing is consistent with WHO's equity principle but was not surfaced verbatim from a WHO source; the strong, citable equity line is the 2021 one above.

## 3. Why low-resource settings need a different design

- **Electricity (quotable):** "Close to **1 billion people** in low- and lower-middle-income countries are … served by health-care facilities **without reliable electricity or with no electricity** at all." In sub-Saharan Africa only **40%** of facilities have reliable electricity, **15%** none. (WHO fact sheet, 31 Aug 2023 — who.int/news-room/fact-sheets/detail/electricity-in-health-care-facilities. *high*)
- **Connectivity (quotable):** **78%** of people in low-income countries are offline (vs 7% in high-income); in rural low-income areas only **1 in 6 (16%)** use the internet. (ITU Facts and Figures 2024. *high*)
- **Workforce:** WHO projects a shortfall of **~11 million health workers by 2030**, mostly in low/lower-middle-income countries. (WHO health-workforce page. *high* for current figure; the number has moved 10–18M across WHO docs/years — treat as version-dependent.)
- **Research/data concentration:** >87% of healthcare-LLM research is led by high-income-country institutions; Africa ≈0.31% despite ~20% of world population. (Chen et al., Lancet Regional Health – Western Pacific, Oct 2025 — PMC12556221. *high*)
- **Performance gap (quotable):** "LLMs make up to **three times more errors** when retrieving information related to low-income countries"; accuracy can fall "from around 80% in English to just 50% in Thai." (Chen et al., 2025. *high* for citation; underlying primary numbers *medium*.)
- **Cloud economics:** a 70B model needs ~8 A100 GPUs (~US$300k/yr cloud); serving one per 100k people "could consume up to 15% of national healthcare expenditure"; even a $20/mo fee "exceeds the financial means of nearly half the global population." (Chen et al., 2025. *high* as reported.)
- **Independent confirmation + recommendation:** 2026 scoping review (44 studies) — fragile infrastructure a barrier in 77.3%, hardware limits 50%, literacy/staffing gaps 61.4%, fragmented/paper records 81.8%; recommends "**offline-capable AI models with local data caching**." (Al-Ganad et al., Frontiers in Digital Health, 2026. *high*)
- **Project tie-in:** offline-capable, on-device, locally-contextualized AI isn't a nice-to-have here — it's the only design that reaches these facilities at all.

## 4. Data privacy, sovereignty & local ownership

- **Sovereignty (quotable):** at WHO's May 2026 digital-health/AI debate, LMICs warned AI "risks accelerating data extraction"; Cameroon (African Region) feared corporations would "harvest data from the Global South to train AI models"; Barbados argued health data should be "**a national asset under local control**." (Health Policy Watch, 2 May 2026. *high*)
- **Governance principle (quotable):** the Health Data Governance Principles (Transform Health; 200+ contributors, 130+ orgs, 2022) call for "**federated storage, processing and use of data, which allow data to remain close to their point of generation**" — the governance case for on-premise processing. (healthdatagovernance.org/principles. *high*; verify verbatim against the official PDF before quoting word-for-word.)
- **Cloud-LLM privacy risk (quotable):** a review of **464** healthcare-LLM studies found six privacy risks from external/cloud LLMs and that **38.4%** reported *no* PHI-protection measures; its top recommendation: "**Priority should be given to deploying the LLM locally.**" (Zhong et al., JMIR, 21 Nov 2025 — jmir.org/2025/1/e76571. *high*)
- "Data colonialism" = "the extractive and exploitative practices of a high-income-country institution removing data from an LMIC context." (decolonizing-global-health scoping review, PMC12560380, 2025. *high* concept; verify exact phrasing in body.)
- Regulation: AU **Malabo Convention** (binding regional data-protection treaty) in force June 2023; 10 of 12 surveyed African jurisdictions have data-protection laws, most adding cross-border-transfer conditions for health data (Staunton et al., 2024). GDPR treats health data as "special category" (Art. 9), restricting cross-border transfer (Chapter V). (*high* for the legal facts; cite primary law text on any public page.)
- **Project tie-in:** "PHI never leaves the deployment" is the architecture answer to this body of governance.

**Caveat:** Malabo exact in-force day varies by source (June 2023 agreed). Cite GDPR/AU primary texts, not vendor blogs, on a public page.

## 5. Open-weight models & right-sizing per task

- **Small can run offline (quotable):** a **3.8B** open model (Phi-3-mini) runs fully offline on an iPhone in ~1.8 GB at >12 tok/s, at roughly GPT-3.5 quality. (Microsoft Research, Phi-3 Technical Report, Apr 2024 — arxiv.org/abs/2404.14219. *high*)
- **Open is closing the gap (quotable):** on 1,933 real radiology cases, closed GPT-4o scored **79.6%** and open Llama-3-70B **73.2%**; authors: "open-source LLMs are quickly closing the gap to proprietary LLMs." (Kim et al., npj Digital Medicine, 12 Feb 2025 — PMC11814077. *high*)
- **Medical open models:** MedGemma (open, Gemma-3-based, 4B/27B) scores 64.4% (4B) / 87.7% (27B w/ test-time scaling) on MedQA vs 50.7%/74.9% base; authors recommend it when a use case needs "ability to run locally or offline." (Sellergren et al., Google, Jul 2025 — arxiv.org/abs/2507.05201. *high*; the 87.7% includes test-time scaling.)
- **Right-sizing / routing:** matching model size to task difficulty (small for easy, escalate to large only for hard) yields large savings (e.g. a router hitting 97% of GPT-4 quality at ~24% cost). (Moslem & Kelleher survey, ADAPT/TCD, Apr 2026 — arxiv.org/abs/2603.04445. Direction *high*; exact percentages *medium*, setup-dependent.)
- **Capable size range on modest hardware:** Llama 3.2 1B, Qwen2.5 1.5B, Gemma 2 2B/9B, Phi-3-mini 3.8B/Phi-4 14B, Mistral 7B — 1–9B built for on-device. (model cards; anchored by Phi-3. *high*.)
- **Safety limit — small models can't self-verify (quotable):** AI self-verification wrongly accepted incorrect medical answers **>60%** of the time, and smaller models were no better — "cannot serve as a universal safety layer." (Jin et al., "Verification Mirage," UBC/Vector, May 2026 — arxiv.org/abs/2605.10850. *medium*, recent preprint, consistent w/ peer-reviewed LLM-as-judge literature.) Corroborated: small local 4–8B models unreliable as autonomous medical graders → escalate grading to a strong (cloud) judge.
- **Project tie-in:** this is exactly the project's design — a **team of small, right-sized open models** for the work, with **a strong judge for grading** (not trusting small models to grade themselves), all runnable locally.

**Caveat:** Findings on small-model self-verification (#6/#7 in the source sweep) are 2026 preprints; cite as "reported by the authors." MedGemma 27B headline number includes test-time scaling.

---

## How the external evidence maps to the project (the through-line)

| The reality (cited above) | The project's answer (in-repo) |
|---|---|
| Care runs offline, on modest hardware (§3) | Local "AI team" of small models + local llama-router; offline-capable |
| HIC-trained AI underperforms for LMIC patients (§2, §3) | KB *contextualized* to each deployment's own concepts/drugs/populations |
| Sending PHI to clouds is a privacy/sovereignty risk (§4) | PHI never leaves the deployment; on-premise by design |
| LMMs hallucinate; small models can't self-verify (§2, §5) | Every claim traced to a specific record; strong judge grades, not the small model |
| Software should be guideline-concordant & testable (§1) | Validation harness: real systems, real data, reviewable evidence at every step |

This is the page's argument in one line: **the way clinical AI is usually built is wrong
for where most primary care actually happens — and there's now a credible, evidence-graded
way to do it right: local, contextualized, and traceable.**


---

# Guardrails + control-flow methodology: deep-research findings (decision input)

> Deep-research workflow (run `wf_942b8fdc-5e8`, 107 agents, 25 sources fetched, 120 claims → 25 verified via 3-vote adversarial check → 21 confirmed / 4 refuted → 6 synthesized findings). Primary sources: Anthropic + OpenAI prompt guides, NVIDIA NeMo Guardrails docs, Meta LlamaFirewall, Swiss-Cheese-for-AI-safety, small-model reliability papers, clinical-LLM safety. Scoped to OUR stack (med-agent-hub clinical chart-QA, 4-8B local models, strict JSON envelope, 006 harness).

## Bottom line

**Your "start soft → measure → harden" instinct is SOUND and matches established practice — with two non-negotiable qualifiers the evidence forces:**

1. **Defense-in-depth means NOT everything starts soft.** The recognized framing is the Swiss Cheese model: every layer has holes, so no single guardrail — least of all a system prompt — is trusted alone. Real systems (NeMo Guardrails, Meta LlamaFirewall) deliberately *stack and mix* enforcement types, and layering empirically beats any single mechanism. So a set of clinical-safety goals must be **HARD by real-clinical-use** (the research says "from day one"; *our* build order scopes that to production use — for the demo POC these are the first measurement-driven output guards, not preconditions; see the Goal-by-goal map scoping note and the Reconciliation section).

2. **"Measure" must measure CORRECTNESS + GROUNDEDNESS, not just that the JSON is well-formed.** Small models can be "reliably wrong" (consistent, schema-conformant, still incorrect), and single-pass scores collapse on paraphrases. Schema-validity ≠ the guardrail holds.

## Findings (all high-confidence)

1. **Defense-in-depth (Swiss Cheese) is the established framing** — directly justifies stacking soft (prompt) + hard (code) rather than trusting one. "If any single guardrail fails, the associated risks may bypass it" (arXiv 2408.02205); UC Berkeley agentic-defense taxonomy is built on defense-in-depth (arXiv 2603.11088); "model-based detectors are bypassed by adaptive attacks… rule-based detectors require extensive human effort" — neither alone is reliable.

2. **Real systems layer AND mix enforcement types; layering wins.** NeMo Guardrails = 5 staged rail types (input / retrieval / dialog / execution / output) as a code-enforced out-of-model intermediary. Meta LlamaFirewall mixes deterministic detectors + one LLM auditor → cut AgentDojo injection attack-success **17.6% → 1.75% (>90%)** at ~5pp utility cost; neither component sufficed alone (arXiv 2505.03574). → Keep deterministic envelope/citation checks as the hard floor; layer the soft prompt for the rest. No single tool need do everything.

3. **Evidence-based SOFT-layer methodology** (Anthropic + OpenAI, for the orchestrator system prompt):
   - **Clear, explicit, scoped instructions** — models don't infer "above and beyond" or scope from vague prompts.
   - **3-5 diverse XML-tagged few-shot examples** — the most reliable lever for output format/structure (use for the envelope as a *soft* contract atop the hard schema; include an abstention example).
   - **Quote-first grounding** — extract verbatim source quotes into tagged sections *before* answering. Anthropic's own worked example is literally a clinical physician's-assistant chart task ("Find quotes from the patient records… place in `<quotes>` tags. Then…").
   - **Single non-contradictory instruction hierarchy + explicit escape hatch** — contradictory instructions actively degrade reasoning ("if KB search returns nothing relevant, abstain and say so").
   - Prompt structure for the strong-guidance default: role → numbered non-contradictory default path (search KB → consult expert → synthesize → envelope) → tool-use guidance → envelope contract w/ 3-5 worked examples → quote-first grounding → one explicit abstention escape hatch.

4. **The SOFT layer breaks down on 4-8B local models** — the empirical core for hardening safety goals:
   - Prompt *style alone* swings small-model clinical-QA accuracy double digits (roleplay cost Phi-3 Mini **21.5pp** on MedQA; arXiv 2603.00917).
   - Small models can be **"reliably wrong"** — high consistency, schema-conformant, still incorrect (Gemma 2: consistent-yet-wrong on 38.5% of MedQA items). "A dangerous failure mode in clinical AI."
   - Single-pass instruction-following collapses **up to 61.8%** across semantically-equivalent paraphrases on small models (Qwen3-0.6B 58.0%→22.2% vs GPT-5 only −18.3%; arXiv 2512.14754). Reliability is a *second-order* property beyond accuracy.
   - **Small models are poor LLM verifiers** (high false-positive rates) — so a local 4-8B groundedness verifier is unreliable; prefer deterministic citation resolution (code) or escalate the verifier to the cloud model.

5. **Two HARD levers — choose by WHAT must be guaranteed:**
   - **Harden the OUTPUT** (constrained/structured decoding — json_schema response_format / grammar makes violating tokens unproducible) when the guarantee is about *shape/format*. We already do this for the envelope. **Guarantees well-formed, NOT correct or grounded.**
   - **Harden the CONTROL FLOW** (deterministic code / state machine that calls the tool, gates retrieval, forces abstention) when the guarantee is about a *procedure or safety gate a prompt could skip*.

6. **Goal-by-goal map** (the deliverable):

> **Scoping (synced with user 2026-05-29):** the research says clinical-safety goals should be "HARD from day one." We scope "day one" to **day one of real clinical use, not day one of the demo POC** (this is a demo — openclinai.org — not production patient care). For the POC we **start on the existing ReAct loop + the one hard guard we already have (the JSON envelope)** and add the safety guards as the *first, cheap, measurement-driven* hardenings — not as preconditions to starting. The "Production floor" column is the research's must-be-hard target for real clinical use; the "Demo POC start" column is where we actually begin. Crucially, the safety guards are thin **output validators wrapping the loop's result** — they are NOT the deterministic orchestration complexity we're deferring.

| Goal | Demo POC start | Production floor | Mechanism |
|---|---|---|---|
| JSON envelope shape | **HARD (have it)** | HARD | constrained decoding (json_schema) — already in place |
| Citation groundedness (no fabricated indices) | SOFT (prompt) → first guard to add | **HARD** | thin output check: each integer citation index resolves to a real chart record + quote-first prompting |
| Abstention on insufficient evidence | SOFT (prompt) → early guard | **HARD** | retrieval-gating output guard: empty/irrelevant KB hit → force abstention |
| Scope / PHI limits | SOFT (prompt) | **HARD** | code-enforced output/log guard |
| Path adherence (KB→expert→synthesize) | SOFT — and the path is a **hypothesis**, not a fixed default | SOFT (only harden if measured) | light, provisional prompt steering on the ReAct loop |
| Completeness / thoroughness | SOFT | SOFT | prompt |
| Tone | SOFT | SOFT | prompt |
| Citation *selection* quality | SOFT | SOFT | prompt + harness groundedness scoring |

**Promotion criterion:** promote a goal from soft → a hard guard (or, for *path*, → deterministic control flow) when the 006 harness shows the loop failing it on **correctness / groundedness / abstention-outcome** across paraphrase or adversarial probes — not on a single pass, and not on schema-validity. The safety guards (citation resolution, abstention) are the cheapest and first to add when the harness shows the model fabricating citations or failing to abstain; path-hardening (deterministic orchestration) is a last resort, only if guidance can't hold a behavior that matters.

## Framework recommendation

**Hand-roll deterministic validators now.** We already hand-roll the envelope guardrail; NeMo is a heavyweight out-of-model intermediary; LLM-based verifier guardrails degrade sharply on small models. Keep the architecture expandable. (Caveat: Guardrails AI / OpenAI Agents SDK tripwires were NOT covered by surviving evidence — this is grounded inference, not a head-to-head. Revisit if/when validators multiply.)

## Caveats (honest)

- **TERMINOLOGY TRAP (most important):** the academic "hard vs soft guardrails" (hard = rigid for legal/ethical/safety; soft = context-*adjustable*/flexible) is a DIFFERENT axis from our "soft = prompt-level/always-violable" vs "hard = code/constrained-decoding/non-negotiable." The claim that the academic taxonomy maps onto ours was **refuted 0-3**. What the literature licenses is the *defense-in-depth/layering* principle and *mixing enforcement types* — the prompt-vs-code labeling is our own operational framing. Treat SOFT/HARD here as our definitions.
- **Vendor prompt docs target FRONTIER models** (Claude Opus 4.x, GPT-5). They establish the right *method* for the soft layer but do NOT establish prompts steer reliably enough on 4-8B to skip hard enforcement — the small-model findings cut the other way. OpenAI's `reasoning_effort` knob has no gemma/medgemma analog on LM Studio.
- **4-8B band is extrapolated** — reliability-collapse measurements bracket it (≤3B and ≥70B); direction (smaller → more brittle) well-supported, exact in-band magnitude inferred.
- **Framework coverage incomplete** (NeMo + LlamaFirewall have primary sources; Guardrails AI / OpenAI Agents SDK do not).
- **Security ≠ clinical metrics:** the AgentDojo injection numbers motivate *layering as a principle*; they're not predictions of clinical-QA groundedness performance.
- **Refuted (do NOT cite):** academic hard/soft = our axis (0-3); GPT-5 persistence-instruction reliability (0-3); Meditron-7B 99% UNKNOWN near-complete instruction-failure (0-3); input rule-vs-model = our axis (1-2).

## Open questions

1. Can a groundedness/abstention *verifier* run acceptably on the local 4-8B stack at all (high FPR), or must citation-groundedness be pure-code citation-resolution / escalate to the cloud model? Decides whether 006's deferred automated `citations_resolve` can be pure code.
2. Concrete NUMERIC promotion threshold on THIS harness's metrics (Scout accuracy/completeness, failed-to-abstain rate, unsupported-citation rate) to trigger soft→hard. Must be set empirically against the default comparison set.
3. Are Guardrails AI / OpenAI Agents SDK tripwires worth adopting over hand-rolled validators for our local + OpenAI-compat + small-model + observability needs?
4. Within 4-8B (gemma-4-e4b vs medgemma-1.5-4b), does the accuracy-vs-reliability decoupling hold — i.e. select the default engine by measured *reliability on the guided path*, not benchmark accuracy?

## Reconciliation with the settled orchestrator design (synced with user 2026-05-29)

This **refines** the settled design (start on the existing ReAct loop, typed tool interface) — it does not reverse it, and it does **not** introduce deterministic complexity up front.

- **Start lean on what exists.** The orchestrator is the ReAct loop med-agent-hub already has; we begin with it + the one hard guard we already have (the JSON envelope) + light, provisional prompt steering. We do not pre-build deterministic control flow or pre-prescribe a fixed path — the path is a hypothesis the harness tests against the real (wide) question range, and the agent set will grow (admin, clinical-research, …), which favors a flexible router over a pipeline.
- **Two enforcement *kinds*, don't conflate them.** (1) *Orchestration control flow* (a deterministic pipeline/state machine) — **deferred**, a last-resort promotion only if guidance can't hold a behavior that matters. (2) *Output guards* (citation-index resolution, retrieval-gated abstention, scope/PHI) — thin validators that wrap the loop's **output**, a few lines each, NOT orchestration complexity. The research wants these "hard from day one"; we scope "day one" to **real clinical use**, and for the demo POC they're the *first, cheapest, measurement-driven* hardenings rather than preconditions.
- **The harness is the decider.** 006 already measures correctness/groundedness/abstention — exactly the "measure" step. Everything is promotion-by-measurement: add a safety output-guard the moment the harness shows fabricated citations or failed abstention; harden the path (deterministic flow) only as a last resort.

## Key sources

- Swiss-Cheese AI safety: https://arxiv.org/html/2408.02205v3 · Agentic defense taxonomy: https://arxiv.org/html/2603.11088v1
- NeMo Guardrails: https://docs.nvidia.com/nemo/guardrails/latest/user-guides/guardrails-process.html · LlamaFirewall: https://arxiv.org/pdf/2505.03574
- Anthropic prompting: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices · OpenAI GPT-5 guide: https://developers.openai.com/cookbook/examples/gpt-5/gpt-5_prompting_guide
- Small-model clinical reliability (LMIC): https://arxiv.org/abs/2603.00917 · Reliability vs accuracy: https://arxiv.org/html/2512.14754v1