diff --git a/AGENTS.md b/AGENTS.md index 4917ddb..482922f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,31 +1,41 @@ # Repository Guidelines ## Project Structure & Module Organization -This repository is currently document-first. The primary deliverable is [`open_prior_auth_workbench_strategy_report.docx`](./open_prior_auth_workbench_strategy_report.docx) at the repo root. The `doctor/` directory is a local Python 3.14 virtual environment, not application source code. `.idea/` contains editor metadata and should be treated as local-only workspace state. +This repository is now a TypeScript monorepo plus documentation set for Open Prior Auth Agent Workbench. The main product code lives in `apps/` and `packages/`; the strategy report PDF at the repo root remains a reference artifact, not the only deliverable. The `doctor/` directory is a local Python virtual environment, not application source code. `.idea/` contains editor metadata and should be treated as local-only workspace state. -If code is added later, keep production modules out of `doctor/`; create a dedicated source folder such as `src/` or `app/`, and place tests in `tests/`. +Keep production modules out of `doctor/`. Application code belongs under `apps/*`; reusable package code belongs under `packages/*`; contract tests belong in `tests/`. ## Build, Test, and Development Commands -No build pipeline or automated test suite is checked in yet. Current useful local commands are: +Use Node `>=22.18.0`. Current useful local commands are: ```bash -python3.14 -m venv doctor -source doctor/bin/activate -python -m pip list +npm ci +npm run db:migrate +npm test +npm run typecheck +npm run build +npm run evals ``` -Use the first command only to recreate the local virtual environment. Activate it before running any Python-based document tooling you add. Avoid editing files under `doctor/lib/` directly; reinstall packages instead. +Local demo commands: + +```bash +npm run dev:api +npm run dev:web +``` + +Use `python3.14 -m venv doctor` only to recreate the disposable local Python environment for document tooling. Avoid editing files under `doctor/lib/` directly; reinstall packages instead. ## Coding Style & Naming Conventions Use Markdown for repository documentation and keep sections short, task-oriented, and scannable. Follow the existing filename pattern of descriptive lowercase snake_case for generated artifacts, for example `prior_auth_summary.docx`. -For future Python code, use 4-space indentation, `snake_case` for functions and modules, and `PascalCase` for classes. No formatter or linter is configured yet, so keep style conservative and consistent. +For TypeScript, follow the existing workspace style: ESM modules, explicit exported types at package boundaries, and conservative dependency direction (`apps/*` may import `packages/*`; `packages/*` must not import `apps/*`). No formatter or linter is configured yet, so keep style conservative and consistent. ## Testing Guidelines -If you introduce Python code, add `pytest` tests under `tests/` and name files `test_.py`. For document changes, verify the `.docx` opens cleanly and that headings, tables, and pagination render as expected before submitting. +Add or update Node contract tests under `tests/` when behavior changes. Run `npm test`, `npm run typecheck`, `npm run build`, and `npm run evals` before marking meaningful changes complete. For document-only changes, still run the relevant verification unless the change cannot affect code paths. ## Commit & Pull Request Guidelines -If the project is initialized as a Git repo, use short imperative commit messages such as `docs: update prior auth report` or `test: add report validation checks`. +Use short imperative commit messages such as `docs: update current status` or `test: add report validation checks`. Pull requests should include a brief summary, the files changed, and screenshots or exported previews when document layout changes materially. @@ -136,4 +146,4 @@ If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its plac 3. Use `--content docs` for documentation, `--content config` for config files, or `--content all` for everything. 4. Inspect full files only when the returned chunk does not give enough context. 5. Optionally use `semble find-related` with a promising result's `file_path` and `line` to discover related implementations. -6. Use grep only when you need exhaustive literal matches or quick confirmation of an exact string. \ No newline at end of file +6. Use grep only when you need exhaustive literal matches or quick confirmation of an exact string. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index d69b2d1..9e3393f 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -2,7 +2,7 @@ ## Our Pledge -Project participants are expected to be respectful, constructive, and clear. The goal is to make the project useful for healthcare builders without creating an intimidating or careless community space. +Project participants are expected to be respectful, constructive, and clear. The goal is to make this synthetic Doctor Agent OS / prior authorization workbench useful for healthcare builders without creating an intimidating or careless community space. ## Expected Behavior @@ -10,6 +10,7 @@ Project participants are expected to be respectful, constructive, and clear. The - Disagree about ideas without personal attacks. - Keep comments focused on the work. - Respect privacy and do not post sensitive healthcare, credential, or customer data. +- Keep standards, safety, and production-readiness claims precise; correct overclaims without personal attacks. ## Unacceptable Behavior diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bcf53a6..47d8580 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing -Thanks for helping improve Open Prior Auth Workbench. This repo is a synthetic-data-only developer sandbox, so contributions should keep the product easy to run locally and safe for external builders to inspect. +Thanks for helping improve Open Prior Auth Agent Workbench. This repo is a synthetic-data-only Doctor Agent OS reference system for provider-side prior authorization, so contributions should keep the product easy to run locally and safe for external builders to inspect. ## Local Setup @@ -32,6 +32,7 @@ The API defaults to `http://localhost:4000`. The web app defaults to `http://loc - Do not add production payer credentials, EHR URLs, secrets, or customer-specific endpoints. - Update `README.md`, `demo/README.md`, `data/README.md`, or architecture notes when behavior or fixtures change. - Add or update contract tests when API behavior changes. +- Update Doctor Evals scenarios, golden traces, or policy assertions when agent/tool behavior changes. - Keep generated build outputs out of the repo. ## Pull Request Checklist @@ -39,9 +40,10 @@ The API defaults to `http://localhost:4000`. The web app defaults to `http://loc - `npm test` passes. - `npm run typecheck` passes. - `npm run build` passes. -- Docs describe any new route, fixture, or demo step. +- `npm run evals` passes when runtime, ToolNet, agent, evidence, packet, or safety-claim behavior changes. +- Docs describe any new route, tool, fixture, eval scenario, or demo step. - Screenshots are updated when the visible demo workflow materially changes. -- The PR summary calls out whether the change affects M1, M2, M3, M4, or M5. +- The PR summary calls out affected surfaces: Prior Auth Core, ToolNet, Runtime, Agent Cockpit, standards gateway, Doctor Evals, docs, or production-path docs. ## Data Safety diff --git a/README.md b/README.md index 1be8cc9..802a1c6 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # Open Prior Auth Agent Workbench -Open Prior Auth Agent Workbench is a synthetic-data-only, provider-side prior authorization application built on the planned Doctor Agent OS substrate. The current runnable baseline remains the M1-M7 Open Prior Auth Workbench: local MRI lumbar spine and DME power wheelchair flows for requirement discovery, documentation capture, supporting information, PAS-style packet assembly, operations queueing, payer status handling, and more-info loops. +Open Prior Auth Agent Workbench is a synthetic-data-only, provider-side prior authorization application built on the Doctor Agent OS substrate. The current runnable baseline covers M1-M8 plus M9 production-path documentation: local MRI lumbar spine and DME power wheelchair flows for requirement discovery, documentation capture, supporting information, PAS-style packet assembly, operations queueing, payer status handling, more-info loops, deterministic agent runs, approval gates, standards-shaped local gateway routes, and formal deterministic evals. -Doctor Agent OS is the implementation platform direction for reusable agent runtime, ToolNet tools, MCP exposure, approvals, traces, and evaluations. It is not a broader committed business domain. The first and only committed app/domain is provider-side prior authorization. +Doctor Agent OS is the implementation platform direction for reusable agent runtime, ToolNet tools, approvals, traces, and evaluations. MCP remains the next unimplemented interoperability boundary. Doctor Agent OS is not a broader committed business domain. The first and only committed app/domain is provider-side prior authorization. ## Quickstart @@ -47,6 +47,8 @@ npm run demo:seed - M5: Agent Cockpit where prior-auth case state is primary and deterministic agent trace is visible as a trust/debug layer. - M6: SQLite-backed local persistence, transaction boundaries, DB scripts, and local standards-shaped adapter boundaries. - M7: synthetic supporting information, DocumentReference/Binary-like packet entries, fixture DTR dependencies, standards-shaped non-conformant aliases, and SQLite evidence metadata. +- M8: deterministic Doctor Evals for golden traces, ToolNet policy, ApprovalGate behavior, prompt-injection-as-data checks, and safety claim checks. +- M9: production-path documentation for FHIR data plane, security/authz/audit, EHR/payer integration, deployment/observability, and conformance testing. ## Safety And Conformance Boundaries @@ -54,7 +56,7 @@ This repository is synthetic-only, standards-shaped, non-certified, not PHI-read It does not implement production SMART App Launch, CDS Hooks CRD, FHIR `$questionnaire-package`, Da Vinci DTR, Da Vinci PAS `$submit`, X12 278, payer endpoint discovery, production payer transport, payer adjudication, production-grade durable persistence, real FHIR persistence, or real EHR integration. -The `/dtr/*` endpoints are local DTR-like product endpoints. The `/pas/*` endpoints are PAS-style local product endpoints. The M7 standards-shaped aliases return explicit non-conformance metadata and exist to mark replacement boundaries, not to claim SMART, CRD, DTR, or PAS compatibility. +The `/dtr/*` endpoints are local DTR-like product endpoints. The `/pas/*` endpoints are PAS-style local product endpoints. The standards-shaped gateway routes and aliases return explicit non-conformance metadata and exist to mark replacement boundaries, not to claim SMART, CRD, DTR, or PAS compatibility. ## Repository Map @@ -64,13 +66,14 @@ The `/dtr/*` endpoints are local DTR-like product endpoints. The `/pas/*` endpoi - `packages/prior-auth-core/`: provider-side prior-auth Use Cases and ports. - `packages/doctor-toolnet/`: agent/tool adapter over Prior Auth Core. - `packages/doctor-runtime/`: workflow-agnostic run/task/tool/approval/trace runtime with SQLite persistence. -- `packages/doctor-mcp/`, `packages/doctor-evals/`: README-only placeholders for planned MCP and eval package boundaries. +- `packages/doctor-mcp/`: README-only placeholder for the planned MCP boundary over ToolNet. +- `packages/doctor-evals/`: deterministic regression and safety harness for local synthetic agent runs. - `data/`: Synthetic FHIR bundles, golden scenarios, payer rule packs, questionnaires, evidence fixtures, and standards-shaped payload fixtures. - `docs/`: Roadmap, glossary, architecture notes, conformance matrix, and demo story docs. - `demo/`: Step-by-step demo guide and deterministic screenshot artifacts. - `examples/automations/`: Docs-only automation recipes that call existing local APIs. - `infra/compose/`: Lightweight compose notes for local API/web services. -- `tests/`: Contract tests for current M1-M7 behavior. +- `tests/`: Contract tests for current M1-M8 behavior, standards-shaped gateway routes, package boundaries, runtime approvals, cockpit responses, and eval assertions. Package direction is intentional: `apps/*` may import `packages/*`; `packages/*` must not import `apps/*`. diff --git a/SECURITY.md b/SECURITY.md index eb22daf..ec3fa1a 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,6 +1,6 @@ # Security -Open Prior Auth Workbench is an early synthetic-data-only reference project. It does not yet have a formal security response program, paid bounty, or guaranteed response timeline. +Open Prior Auth Agent Workbench is a synthetic-data-only reference project. It has local API, web, ToolNet, Runtime, Agent Cockpit, standards-shaped gateway, and Doctor Evals surfaces, but it does not have a formal security response program, paid bounty, or guaranteed response timeline. ## Reporting A Concern @@ -19,4 +19,4 @@ Do not include PHI, real patient data, payer credentials, production EHR URLs, p ## Scope -Security reports are most useful when they involve the checked-in local API, web app, fixtures, CI configuration, or documentation. Reports about production deployment hardening may still be helpful, but this repository does not currently claim production readiness. +Security reports are most useful when they involve the checked-in local API, web app, ToolNet tools, Runtime approval/trace behavior, eval harness, fixtures, CI configuration, or documentation. Reports about production deployment hardening may still be helpful, but this repository does not currently claim production readiness, PHI readiness, certified conformance, or live EHR/payer connectivity. diff --git a/demo/README.md b/demo/README.md index 597425a..2ff2981 100644 --- a/demo/README.md +++ b/demo/README.md @@ -1,16 +1,16 @@ -# Demo Guide: M1 to M8 Open Prior Auth Workbench +# Demo Guide: Open Prior Auth Agent Workbench -This guide walks through every demo piece from M1 through M8 using only synthetic prior authorization data. The current app runs the full M4 workbench for MRI lumbar spine / Acme Health and DME power wheelchair / Blue Ridge Health, M5 adds OSS-facing documentation, CI, fixture indexing, automation recipes, and deterministic screenshots for external builders, M6 makes local case state survive API restarts through SQLite, M7 adds local evidence attachments and DTR dependency fixtures, and M8 adds formal deterministic evals. Each milestone remains visible as a separate part of the flow: +This guide walks through the synthetic prior authorization demo path. The current app includes Prior Auth Core, Doctor ToolNet, Doctor Runtime with ApprovalGate, deterministic agent team, case-first Agent Cockpit, standards-shaped ToolNet tools, local standards gateway routes, and formal deterministic evals. Each milestone remains visible as a separate part of the flow: - M1: fixture-backed launch context, requirement discovery, and explicit work-item creation. - M2: local DTR-inspired questionnaire package, prefilled form workspace, validation, and review-ready handoff. - M3: PAS-style local packet builder, mock PAS submission, status timeline, and audit trail. - M4: reusable prior-auth proof, operations queue, filters, metrics, payer updates, more-info loop, structured denial, and terminal outcomes. -- M5: builder-ready docs, fixture index, CI, environment example, sample automations, and reproducible screenshots. -- M6: SQLite-backed local case state, explicit transaction boundaries, and local standards-shaped launch/CRD/DTR/PAS adapters. -- M7: synthetic evidence attachments, DocumentReference/Binary-like packet entries, fixture Library/ValueSet dependencies, and standards gateway routes with explicit non-conformance metadata. +- M5: case-first Agent Cockpit with scenario switching, agent trace, evidence board, packet preview, approvals, and status/audit panels. +- M6: standards-shaped Doctor ToolNet tools for local CRD, DTR, and PAS boundary payloads. +- M7: local standards gateway HTTP routes and aliases with explicit non-conformance metadata. - M8: deterministic doctor evals for golden traces, ToolNet policy, ApprovalGate, and safety claims. -- Doctor Runtime M3: deterministic prior-auth agent team over Runtime + ToolNet, ending at guarded submit approval. +- Supporting baseline: SQLite-backed local case state, synthetic evidence attachments, fixture DTR dependencies, OSS docs, CI, fixture indexing, automation recipes, and deterministic screenshots. No real PHI is required or expected. @@ -86,9 +86,9 @@ http://localhost:3000 The API defaults to `http://127.0.0.1:4000`. The API store is SQLite-backed at `.data/open-prior-auth.sqlite`; use `OPEN_PRIOR_AUTH_DB_PATH` to point at another local database file. M7 uploads write synthetic evidence bytes to `.data/evidence-uploads/`; use `OPEN_PRIOR_AUTH_EVIDENCE_UPLOAD_DIR` to point at another ignored local directory. Restarting `npm run dev:api` preserves work items, questionnaire sessions, packets, receipts, evidence metadata, status events, operations history, and audit events. Use `npm run db:reset` when you want a clean demo state. -## M6: Restart Survival Check +## Local SQLite Restart Survival Check -M6 proves the local durable case core: +The local durable case core proves: 1. Run `npm run db:reset`. 2. Run `npm run dev:api`. @@ -99,7 +99,7 @@ M6 proves the local durable case core: JSON remains the fixture and demo snapshot format. SQLite is the runtime source of truth for local case state. -## M7: Evidence Attachments And Standards Aliases +## Evidence Attachments And Standards Gateway Aliases After creating a work item and opening the form workspace: @@ -598,9 +598,9 @@ Expected checks: - Approved, denied, and cancelled cases are terminal. - Denied updates require structured `code`, `display`, and `detail` reason fields. -## M5: OSS Polish Artifacts +## OSS Polish Artifacts -M5 proves that an external builder can understand, run, verify, and extend the project without private context. It does not change the runtime behavior from M4. +These artifacts help external builders understand, run, verify, and extend the synthetic local project. ### M5 Docs To Review @@ -647,9 +647,10 @@ npm run build Expected results: -- `npm test`: M1 through M6 contract tests pass. -- `npm run typecheck`: API, web, and shared-type packages typecheck. -- `npm run build`: API, web, and shared-type packages build. +- `npm test`: M1 through M8 contract tests pass, including runtime, ToolNet, standards gateway, cockpit, and eval coverage. +- `npm run typecheck`: all configured workspaces typecheck. +- `npm run build`: all configured workspaces build. +- `npm run evals`: deterministic eval scenarios and assertions pass. - Queue rows derive `effectiveStatus` exactly from latest payer update plus internal work-item status. - Payer decisions include `submittedAt`, `decidedAt`, and `decisionTimeMs`. - Stale packets are rejected after QuestionnaireResponse revision changes. diff --git a/demo/m1a-prior-auth-core.md b/demo/m1a-prior-auth-core.md index d4c7edd..29e6e27 100644 --- a/demo/m1a-prior-auth-core.md +++ b/demo/m1a-prior-auth-core.md @@ -19,4 +19,4 @@ npm run build - `npm test` passes all contract tests, including core boundary and core use-case coverage. - `prior-auth-core` source has no `apps/api`, `../apps`, or `doctor-toolnet` imports. - API routes continue returning existing response shapes. -- No database table rename or ToolNet package implementation is introduced. +- M1a itself did not require database table renames; current ToolNet coverage lives in `@open-prior-auth/doctor-toolnet`. diff --git a/demo/m3-deterministic-prior-auth-agent-team.md b/demo/m3-deterministic-prior-auth-agent-team.md index 81829df..4acf758 100644 --- a/demo/m3-deterministic-prior-auth-agent-team.md +++ b/demo/m3-deterministic-prior-auth-agent-team.md @@ -1,6 +1,6 @@ # M3 Deterministic Prior-Auth Agent Team -M3 adds a scripted prior-auth agent team in `@open-prior-auth/doctor-runtime`. It uses Runtime + ToolNet only, requires no live LLM, and keeps guarded submit paused for human approval. +M3 added a scripted prior-auth agent team in `@open-prior-auth/doctor-runtime`. It uses Runtime + ToolNet only, requires no live LLM, and keeps guarded submit paused for human approval. ## What It Proves diff --git a/demo/m6-standards-shaped-toolnet-tools.md b/demo/m6-standards-shaped-toolnet-tools.md index ededc32..2a79a2c 100644 --- a/demo/m6-standards-shaped-toolnet-tools.md +++ b/demo/m6-standards-shaped-toolnet-tools.md @@ -1,6 +1,6 @@ # M6 Standards-Shaped ToolNet Tools -M6 adds standards-shaped sibling tools in Doctor ToolNet while preserving existing runtime and cockpit payloads. +M6 added standards-shaped sibling tools in Doctor ToolNet while preserving existing runtime and cockpit payloads. ## What Changed diff --git a/demo/m8-formal-doctor-evals.md b/demo/m8-formal-doctor-evals.md index 5954276..1a2c14e 100644 --- a/demo/m8-formal-doctor-evals.md +++ b/demo/m8-formal-doctor-evals.md @@ -1,6 +1,6 @@ # M8 Formal Doctor Evals -M8 adds deterministic regression and safety evals for the synthetic Doctor Agent OS prior-auth flow. +M8 added deterministic regression and safety evals for the synthetic Doctor Agent OS prior-auth flow. Run: diff --git a/docs/architecture/doctor-agent-os.md b/docs/architecture/doctor-agent-os.md index ab411c6..1c8a815 100644 --- a/docs/architecture/doctor-agent-os.md +++ b/docs/architecture/doctor-agent-os.md @@ -1,10 +1,10 @@ # Doctor Agent OS -Doctor Agent OS is the planned implementation substrate for agentic healthcare administrative workflow software. In this repository, it is scoped to the Open Prior Auth Agent Workbench and must not be described as a broader committed product domain. +Doctor Agent OS is the implementation substrate for agentic healthcare administrative workflow software. In this repository, it is scoped to the Open Prior Auth Agent Workbench and must not be described as a broader committed product domain. ## Current State -M0 is documentation and scaffold alignment only. The current runnable product remains the M1-M7 synthetic prior authorization workbench. No Doctor Agent OS runtime, ToolNet implementation, MCP server, or eval package exists yet. +The current runnable product includes the M1-M8 synthetic prior authorization workbench plus M9 production-path documentation. Prior Auth Core, Doctor ToolNet, Doctor Runtime with ApprovalGate, deterministic prior-auth agent team, Agent Cockpit, standards-shaped gateway routes, and Doctor Evals exist. Doctor MCP remains a README-only placeholder and is the main unimplemented Doctor Agent OS boundary. ## Target Responsibilities @@ -12,8 +12,8 @@ M0 is documentation and scaffold alignment only. The current runnable product re - Expose Use Cases through ToolNet tools with schemas, risk metadata, approval metadata, and call records. - Gate write/submit actions through ApprovalGate. - Persist ordered traces for debugging, replay, and audit. -- Expose selected ToolNet tools through MCP. - Run deterministic safety/regression evals. +- Expose selected ToolNet tools through MCP in a future milestone. ## Package Direction @@ -31,4 +31,4 @@ M0 is documentation and scaffold alignment only. The current runnable product re - No certified SMART, CRD, DTR, or PAS conformance claim. - No live EHR or payer integration. - No generic healthcare marketplace scope in the near term. -- No production-path docs until M9. +- No production implementation; production-path docs are guidance only. diff --git a/docs/architecture/m2_form_workspace.md b/docs/architecture/m2_form_workspace.md index 1acc8a2..95ba6d2 100644 --- a/docs/architecture/m2_form_workspace.md +++ b/docs/architecture/m2_form_workspace.md @@ -4,7 +4,7 @@ ## Boundary -M2 adds a local DTR-inspired form workspace on top of the M1 requirements sandbox. The implementation keeps the DTR vocabulary visible, but it does not claim conformance to the real FHIR `$questionnaire-package` operation. +M2 added a local DTR-inspired form workspace on top of the M1 requirements sandbox. The implementation keeps the DTR vocabulary visible, but it does not claim conformance to the real FHIR `$questionnaire-package` operation. The local package response includes: diff --git a/docs/architecture/m3_pas_style_packet_builder.md b/docs/architecture/m3_pas_style_packet_builder.md index 62f59a3..85c327a 100644 --- a/docs/architecture/m3_pas_style_packet_builder.md +++ b/docs/architecture/m3_pas_style_packet_builder.md @@ -4,7 +4,7 @@ ## Boundary -M3 adds a PAS-style local packet builder and mock transport on top of the M1 requirements sandbox and M2 form workspace. It preserves PAS vocabulary and the mental model of one request Bundle returning one response Bundle, but it does not implement Da Vinci PAS `$submit`, X12 278, payer authentication, endpoint discovery, or real payer decisions. +M3 added a PAS-style local packet builder and mock transport on top of the M1 requirements sandbox and M2 form workspace. It preserves PAS vocabulary and the mental model of one request Bundle returning one response Bundle, but it does not implement Da Vinci PAS `$submit`, X12 278, payer authentication, endpoint discovery, or real payer decisions. The local packet includes: diff --git a/docs/architecture/m4_operations_layer.md b/docs/architecture/m4_operations_layer.md index e1f768f..dbf8f30 100644 --- a/docs/architecture/m4_operations_layer.md +++ b/docs/architecture/m4_operations_layer.md @@ -4,7 +4,7 @@ ## Boundary -M4 adds a local operations layer on top of the M1-M3 CRD-inspired, DTR-inspired, and PAS-style demo flow. It is still synthetic-only and in-memory. It does not add Temporal, durable persistence, PAS inquiry, real payer endpoints, or production adjudication. +M4 added a local operations layer on top of the M1-M3 CRD-inspired, DTR-inspired, and PAS-style demo flow. At that milestone it was still synthetic-only and in-memory. It did not add Temporal, durable persistence, PAS inquiry, real payer endpoints, or production adjudication. ## Status Model diff --git a/docs/architecture/m6_durable_standards_boundary.md b/docs/architecture/m6_durable_standards_boundary.md index 4d21bad..7c6a1d4 100644 --- a/docs/architecture/m6_durable_standards_boundary.md +++ b/docs/architecture/m6_durable_standards_boundary.md @@ -65,7 +65,7 @@ npm run demo:seed ## Verification -M6 adds contract coverage for SQLite parity, restart survival, idempotent packet and receipt persistence, adapter behavior, and transaction rollback. The required verification remains: +M6 added contract coverage for SQLite parity, restart survival, idempotent packet and receipt persistence, adapter behavior, and transaction rollback. The required verification remains: ```bash npm test diff --git a/docs/architecture/m7_evidence_and_dtr_boundary.md b/docs/architecture/m7_evidence_and_dtr_boundary.md index 8d5f555..c848c90 100644 --- a/docs/architecture/m7_evidence_and_dtr_boundary.md +++ b/docs/architecture/m7_evidence_and_dtr_boundary.md @@ -4,9 +4,9 @@ ## Boundary -M7 adds local synthetic evidence attachments, FHIR-shaped DocumentReference/Binary packet entries, fixture-based DTR dependencies, and standards-shaped route aliases. It remains a local developer sandbox. It does not implement real FHIR persistence, Da Vinci conformance, production SMART App Launch, production PAS, X12 278, payer endpoint discovery, or real payer transport. +M7 added local synthetic evidence attachments, FHIR-shaped DocumentReference/Binary packet entries, fixture-based DTR dependencies, and standards-shaped route aliases. It remains a local developer sandbox. It does not implement real FHIR persistence, Da Vinci conformance, production SMART App Launch, production PAS, X12 278, payer endpoint discovery, or real payer transport. -M8 is the earliest milestone for full CQL behavior, full Bundle-like evidence package product support, real FHIR persistence, Da Vinci conformance, and production SMART/PAS behavior. +Full CQL behavior, full Bundle-like evidence package product support, real FHIR persistence, Da Vinci conformance, and production SMART/PAS behavior remain outside the local synthetic implementation and are covered only as production-path requirements. ## Evidence Model @@ -29,7 +29,7 @@ M7 models four content modes but limits product support deliberately: - Tiny inline base64 fixture content is implemented for small checked-in examples. - Local Binary-like resources are the main fixture path. - Local referenced locations are implemented for JSON/base64 uploads written to the local upload directory. -- Bundle-like evidence packages are represented by one smoke-test fixture only. Full product support is deferred to M8. +- Bundle-like evidence packages are represented by one smoke-test fixture only. Full product support remains deferred to a future production/data-plane effort. Upload validation rejects unsupported MIME types, oversized decoded payloads, malformed base64, missing filenames, and checksum mismatches. @@ -49,7 +49,7 @@ M7 includes a constrained fixture-expression evaluator for named expressions use ## Standards Aliases -M7 adds standards-shaped aliases for SMART, CRD, DTR, PAS, and evidence boundary discovery. All aliases return `conformance: false` or equivalent metadata and are labeled `local-non-conformant`. +M7 added standards-shaped aliases for SMART, CRD, DTR, PAS, and evidence boundary discovery. All aliases return `conformance: false` or equivalent metadata and are labeled `local-non-conformant`. The aliases are intended to make future replacement boundaries explicit, not to claim standards conformance. diff --git a/docs/architecture/mcp.md b/docs/architecture/mcp.md index f1332fb..d8bc22d 100644 --- a/docs/architecture/mcp.md +++ b/docs/architecture/mcp.md @@ -1,14 +1,14 @@ # MCP Boundary -The MCP Boundary is the planned external agent interoperability layer for Doctor Agent OS. It becomes real after ToolNet and Runtime exist; M0 only documents the boundary and creates a README placeholder. +The MCP Boundary is the planned external agent interoperability layer for Doctor Agent OS. ToolNet and Runtime now exist; MCP remains the next unimplemented protocol boundary and is still represented only by docs and the `packages/doctor-mcp/README.md` placeholder. ## Purpose -MCP exposes selected resources, prompts, and ToolNet tools to external agent clients without letting those clients bypass ToolNet risk metadata, approval metadata, or traceability. +Planned MCP support will expose selected resources, prompts, and ToolNet tools to external agent clients without letting those clients bypass ToolNet risk metadata, approval metadata, or traceability. ## Rules -- MCP exposes selected ToolNet tools. +- MCP should expose selected ToolNet tools. - MCP does not call Prior Auth Core directly for case-changing actions. - MCP does not call internal HTTP routes as a shortcut. - Guarded ToolNet tools remain governed by ApprovalGate. @@ -16,7 +16,7 @@ MCP exposes selected resources, prompts, and ToolNet tools to external agent cli ## Non-Goals -- No MCP implementation in M0. +- No MCP implementation yet. - No direct live payer/EHR connector. - No PHI-ready claim. - No certified standards conformance claim. diff --git a/docs/architecture/prior-auth-core.md b/docs/architecture/prior-auth-core.md index cb853d5..5b4fd58 100644 --- a/docs/architecture/prior-auth-core.md +++ b/docs/architecture/prior-auth-core.md @@ -33,7 +33,7 @@ Use Cases are the source of truth. HTTP routes and ToolNet tools are sibling ada ## M1a Boundary -M1a creates the real package manifest/config, adds simple string ID aliases, adds ports, extracts current Use Cases, and keeps current API/UI behavior unchanged. +M1a created the real package manifest/config, added simple string ID aliases, added ports, extracted current Use Cases, and kept current API/UI behavior unchanged. Implemented package exports: @@ -42,4 +42,4 @@ Implemented package exports: - `PriorAuthorizationCase`, `PriorAuthorizationRequest`, and `PayerDetermination` - Use Cases for case read, work item list, requirement evaluation, questionnaire package retrieval, questionnaire response save, evidence list, packet build, mock submit, status timeline, and audit trace -`apps/api` still owns concrete HTTP routes, SQLite/memory stores, and fixture FHIR repository adapters. The package does not import `apps/*`, does not rename DB tables, and does not add ToolNet handlers. +`apps/api` still owns concrete HTTP routes, SQLite/memory stores, and fixture FHIR repository adapters. The package does not import `apps/*` and does not rename DB tables. Doctor ToolNet owns agent-facing tool handlers over these Use Cases. diff --git a/docs/architecture/runtime.md b/docs/architecture/runtime.md index d9799f1..21536f5 100644 --- a/docs/architecture/runtime.md +++ b/docs/architecture/runtime.md @@ -14,7 +14,7 @@ Doctor Runtime is the workflow-agnostic runtime package for agent runs, tasks, a ## Persistence -M2 adds SQLite runtime tables: +M2 added SQLite runtime tables: - `agent_runs` - `agent_tasks` @@ -30,7 +30,7 @@ Guarded ToolNet write/submit tools pause the run and create approval requests. A ## M3 Deterministic Prior-Auth Agent Team -M3 adds a replayable scripted prior-auth agent team inside `packages/doctor-runtime`. The team has deterministic role classes for orchestration, requirement discovery, documentation, evidence review, packet assembly, and compliance boundary checks. +M3 added a replayable scripted prior-auth agent team inside `packages/doctor-runtime`. The team has deterministic role classes for orchestration, requirement discovery, documentation, evidence review, packet assembly, and compliance boundary checks. The MRI and DME happy paths run over Runtime + ToolNet only: @@ -44,7 +44,7 @@ The MRI and DME happy paths run over Runtime + ToolNet only: 8. Build the PAS-style packet preview. 9. Request guarded mock submit approval and stop at `waiting_for_human`. -The final submit is not auto-approved in M3/M4. This preserves ApprovalGate as the compliance boundary while still proving the deterministic team can create a packet preview without a live LLM. M4 adds DME Power Wheelchair Authorization / Blue Ridge Health through the same ordered path, with no DME-specific orchestrator. +The final submit is not auto-approved in the deterministic agent path. This preserves ApprovalGate as the compliance boundary while still proving the team can create a packet preview without a live LLM. M4 added DME Power Wheelchair Authorization / Blue Ridge Health through the same ordered path, with no DME-specific orchestrator. ## Non-Goals diff --git a/docs/architecture/strategy_report_implementation_audit.md b/docs/architecture/strategy_report_implementation_audit.md index 04a4cd3..82a5c42 100644 --- a/docs/architecture/strategy_report_implementation_audit.md +++ b/docs/architecture/strategy_report_implementation_audit.md @@ -1,22 +1,23 @@ # Strategy Report Implementation Audit -Audit date: May 22, 2026 +Audit date: May 26, 2026 -Audit status: M0 Doctor Agent OS alignment reset. +Audit status: Current north-star implementation audit. Archived prior audit: [strategy_report_implementation_audit_2026-04-29.md](archive/strategy_report_implementation_audit_2026-04-29.md) ## Executive Finding -The repository is now aligned around Doctor Agent OS as the planned implementation substrate and Open Prior Auth Agent Workbench as the first committed app/domain. This is a documentation and scaffold reset only. The current runnable baseline remains the existing M1-M7 synthetic prior authorization workbench. +The repository now implements much of the synthetic open-source Doctor Agent OS target described in `open_prior_auth_workbench_strategy_report.pdf`: Prior Auth Core, Doctor ToolNet, Doctor Runtime with ApprovalGate, deterministic prior-auth agent team, Agent Cockpit, standards-shaped gateway routes, Doctor Evals, and production-path documentation. -No functional Doctor Agent OS runtime, ToolNet implementation, MCP implementation, eval package, production standards gateway, live payer integration, live EHR integration, or PHI-ready infrastructure is implemented by M0. +The repository still does not implement Doctor MCP, live payer integration, live EHR integration, certified standards conformance, or PHI-ready infrastructure. That separation remains intentional. ## Current Baseline -Implemented baseline remains: +Implemented baseline now includes: - synthetic MRI lumbar spine / Acme Health prior authorization scenario +- synthetic DME power wheelchair / Blue Ridge Health prior authorization scenario - local requirement evaluation against a deterministic Rule Pack - Work Item operations projection - DTR-inspired local Documentation Workspace and Questionnaire Session @@ -24,33 +25,49 @@ Implemented baseline remains: - PAS-style local Submission Packet builder and mock transport - operations queue, payer status updates, additional-information flow, terminal outcomes, audit/status/operation events, and metrics - SQLite-backed local persistence -- standards-shaped local aliases with explicit non-conformance metadata +- Prior Auth Core package +- Doctor ToolNet package with runtime and standards-shaped tools +- Doctor Runtime package with ApprovalGate and ordered trace persistence +- deterministic prior-auth agent team +- Agent Cockpit +- standards-shaped local gateway routes with explicit non-conformance metadata +- Doctor Evals package with deterministic scenarios, golden trace diffs, policy assertions, and safety assertions +- production-path documentation -## M0 Alignment +## Current Alignment -M0 establishes: +Current docs and packages establish: - `README.md` as concise front door -- `docs/roadmap.md` as M0-M9 roadmap source of truth +- `docs/roadmap.md` as implemented M0-M9 roadmap and remaining-direction reference - `docs/glossary.md` as public mirror of `CONTEXT.md` - Doctor Agent OS architecture docs for core, ToolNet, runtime, MCP, conformance, and agentic demo flow -- README-only placeholders for planned packages -- pre-agentic baseline banners on old M1-M7 architecture docs +- real packages for Prior Auth Core, Doctor ToolNet, Doctor Runtime, and Doctor Evals +- README-only placeholder for planned Doctor MCP +- pre-agentic baseline banners on old M1-M7 architecture docs where those docs intentionally remain historical - package direction rule: `apps/*` may import `packages/*`; `packages/*` must not import `apps/*` ## Roadmap Landing Points -- M1a extracts `packages/prior-auth-core`. -- M1b adds `packages/doctor-toolnet`. -- M2 adds `packages/doctor-runtime` and ApprovalGate. -- M3 adds deterministic prior-auth agents. -- M4 proves reuse with DME Power Wheelchair Authorization / Blue Ridge Health. -- M5 adds Agent Cockpit. -- M6 adds standards-shaped ToolNet tools. -- M7 adds standards gateway HTTP routes and tests. -- M8 adds formal Doctor Evals. -- M9 adds production-path docs. +- M1a extracted `packages/prior-auth-core`. +- M1b added `packages/doctor-toolnet`. +- M2 added `packages/doctor-runtime` and ApprovalGate. +- M3 added deterministic prior-auth agents. +- M4 proved reuse with DME Power Wheelchair Authorization / Blue Ridge Health. +- M5 added Agent Cockpit. +- M6 added standards-shaped ToolNet tools. +- M7 added standards gateway HTTP routes and tests. +- M8 added formal Doctor Evals. +- M9 added production-path docs. +- Remaining gap: Doctor MCP implementation. ## Safety And Conformance -The project remains synthetic-only, standards-shaped, non-certified, not PHI-ready, and not connected to live EHRs or payers. No M0 doc should claim production SMART App Launch, CDS Hooks CRD, Da Vinci DTR, Da Vinci PAS, X12 278, payer endpoint discovery, production payer transport, payer adjudication, real FHIR persistence, or real EHR integration. +The project remains synthetic-only, standards-shaped, non-certified, not PHI-ready, and not connected to live EHRs or payers. No doc should claim production SMART App Launch, CDS Hooks CRD, Da Vinci DTR, Da Vinci PAS, X12 278, payer endpoint discovery, production payer transport, payer adjudication, real FHIR persistence, or real EHR integration. + +## Latest Verification + +- `npm test` passed 87/87 tests with localhost permission. +- `npm run typecheck` passed. +- `npm run build` passed. +- `npm run evals` passed 4/4 scenarios and 88/88 assertions. diff --git a/docs/architecture/toolnet.md b/docs/architecture/toolnet.md index df697cb..f0a1517 100644 --- a/docs/architecture/toolnet.md +++ b/docs/architecture/toolnet.md @@ -1,6 +1,6 @@ # Doctor ToolNet -Doctor ToolNet is the agent-facing tool adapter over Use Cases. M1b makes `packages/doctor-toolnet` a real workspace package over `prior-auth-core`. +Doctor ToolNet is the agent-facing tool adapter over Use Cases. `packages/doctor-toolnet` is a real workspace package over `prior-auth-core`. ## Purpose @@ -32,18 +32,18 @@ Executable read/draft tools call Prior Auth Core directly: - `doctor.dtr.get_questionnaire_package` - `doctor.pas.build_packet` -Declared but non-executable guarded tools: +Guarded case-changing tools: - `doctor.dtr.save_response` - `doctor.pas.submit_mock` -Guarded tools return deterministic `APPROVAL_EXECUTOR_REQUIRED` until Doctor Runtime adds ApprovalGate in M2. They are visible contracts, not executable case-changing actions. +Guarded tools return deterministic `APPROVAL_EXECUTOR_REQUIRED` when called directly through ToolNet. Doctor Runtime ApprovalGate can pause, approve/reject, and execute them with trace records. Each call returns a traceable call record with call id, tool name, category, risk level, approval flag, status, timestamps, input, and output or error. ## Non-Goals -- No approval executor in M1b. -- No MCP exposure in M1b. +- No ToolNet-owned approval executor; ApprovalGate belongs to Doctor Runtime. +- No MCP exposure yet. - No live payer submission. - No case-changing tool execution before ApprovalGate. diff --git a/docs/demo/agentic-story-flow.md b/docs/demo/agentic-story-flow.md index 23d0b55..bd8ebd9 100644 --- a/docs/demo/agentic-story-flow.md +++ b/docs/demo/agentic-story-flow.md @@ -1,10 +1,10 @@ # Agentic Story Flow -This story explains how the current M1-M7 workbench maps to the planned Doctor Agent OS flow. It is a product narrative, not an implementation claim. +This story explains how the current workbench maps to Doctor Agent OS flow. It is a product narrative and current implementation guide for the local synthetic path. ## Current Runnable Baseline -The current demo remains the synthetic MRI lumbar spine / Acme Health flow: +The current demo covers synthetic MRI lumbar spine / Acme Health and DME power wheelchair / Blue Ridge Health flows: 1. Load local patient, coverage, order, encounter, practitioner, organization, condition, and observation context. 2. Run deterministic Requirement Evaluation against a local Rule Pack. @@ -16,16 +16,19 @@ The current demo remains the synthetic MRI lumbar spine / Acme Health flow: 8. Build a PAS-style Submission Packet. 9. Submit through mock PAS transport. 10. Track queue state, payer status updates, additional-information flow, terminal outcomes, audit events, and metrics in SQLite. +11. Run deterministic prior-auth agents through Doctor Runtime and ToolNet. +12. Stop guarded submit work at ApprovalGate for human review. +13. Run Doctor Evals for golden traces, tool policy, approval behavior, and safety claims. -## Planned Agentic Flow +## Agentic Flow -Doctor Agent OS will keep the same business case primary while adding agent execution around it: +Doctor Agent OS keeps the same business case primary while adding agent execution around it: 1. Prior Auth Core reads the case and executes Use Cases. 2. ToolNet exposes safe read/draft tools over those Use Cases. 3. Doctor Runtime records ordered agent runs, tasks, tool calls, approvals, and trace events. 4. Deterministic prior-auth agents inspect the case, evaluate requirements, inspect forms/evidence, preview packets, and stop at ApprovalGate for guarded writes/submits. -5. MCP exposes selected ToolNet tools to external agent clients without bypassing approval or trace boundaries. +5. MCP will expose selected ToolNet tools to external agent clients without bypassing approval or trace boundaries. This boundary is still planned, not implemented. 6. Doctor Evals check golden traces, tool policy, approval requirements, and safety claim language. ## Design Principle diff --git a/docs/glossary.md b/docs/glossary.md index 7c56f73..0b99dd2 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -1,6 +1,6 @@ # Glossary -`CONTEXT.md` is the working modeling source of truth. This file is the public stabilized mirror for terms that appear in docs, package boundaries, and future implementation plans. +`CONTEXT.md` is the working modeling source of truth. This file is the public stabilized mirror for terms that appear in docs, package boundaries, and implementation plans. ## Domain Terms @@ -83,5 +83,5 @@ - Prior Auth Core is the source of truth for provider-side prior authorization Use Cases. - HTTP routes and ToolNet tools are sibling adapters over Use Cases. - ToolNet tools do not call internal HTTP routes. -- MCP exposes selected ToolNet tools and does not bypass ToolNet for case-changing actions. +- When MCP is implemented, it should expose selected ToolNet tools and must not bypass ToolNet for case-changing actions. - `apps/*` may import `packages/*`; `packages/*` must not import `apps/*`. diff --git a/docs/production-path/README.md b/docs/production-path/README.md index 22da982..a9f07d2 100644 --- a/docs/production-path/README.md +++ b/docs/production-path/README.md @@ -1,6 +1,6 @@ # Production Path -M9 documents what must change before this repository could move from a synthetic local workbench toward a production prior authorization system. It does not implement that system. +M9 documented what must change before this repository could move from a synthetic local workbench toward a production prior authorization system. It does not implement that system. Current official references: diff --git a/docs/production-path/conformance-test-path.md b/docs/production-path/conformance-test-path.md index e62bcc8..152ddd9 100644 --- a/docs/production-path/conformance-test-path.md +++ b/docs/production-path/conformance-test-path.md @@ -10,7 +10,7 @@ The conformance matrix is intentionally labeled as standards-shaped and non-conf Production needs a version-pinned conformance strategy for each target implementation guide and partner workflow. The test path must include official FHIR validation where applicable, IG package versions, positive and negative cases, partner sandbox tests, security tests, operational tests, and clear language distinguishing internal readiness from certification. -The likely version targets at M9 planning time are SMART App Launch v2.2.0, Da Vinci CRD v2.2.1, DTR v2.2.0, PAS v2.2.1, FHIR R4/R4B, and CMS-0057-F prior authorization API expectations. These must be rechecked before execution. +The likely version targets captured for the production path are SMART App Launch v2.2.0, Da Vinci CRD v2.2.1, DTR v2.2.0, PAS v2.2.1, FHIR R4/R4B, and CMS-0057-F prior authorization API expectations. These must be rechecked before execution. ## Adapters / Interfaces To Build @@ -23,7 +23,7 @@ The likely version targets at M9 planning time are SMART App Launch v2.2.0, Da V ## Non-Goals - Do not claim certification, official validation, or production interoperability from current tests. -- Do not add external validator tooling, partner sandbox calls, or CI changes in M9. +- Do not add external validator tooling, partner sandbox calls, or CI changes as part of the docs-only production path. - Do not treat synthetic fixture success as legal, regulatory, payer, or EHR acceptance. ## Risks / Blockers diff --git a/docs/production-path/deployment-observability.md b/docs/production-path/deployment-observability.md index 1587f4b..70b147d 100644 --- a/docs/production-path/deployment-observability.md +++ b/docs/production-path/deployment-observability.md @@ -21,7 +21,7 @@ Observability must connect business events and technical signals: case lifecycle ## Non-Goals -- Do not implement OpenTelemetry, Langfuse, Kubernetes, cloud databases, object storage, or deployment manifests in M9. +- Do not implement OpenTelemetry, Langfuse, Kubernetes, cloud databases, object storage, or deployment manifests as part of the docs-only production path. - Do not claim readiness for production deployment from local build/test success. - Do not store PHI or credentials in local demo paths such as `.data/`. diff --git a/docs/production-path/ehr-payer-integration.md b/docs/production-path/ehr-payer-integration.md index d0b5a65..ca3ad00 100644 --- a/docs/production-path/ehr-payer-integration.md +++ b/docs/production-path/ehr-payer-integration.md @@ -23,8 +23,8 @@ The provider-side domain model must stay stable across external workflows: Requi ## Non-Goals -- Do not implement SMART launch, EHR API clients, payer transport, X12 mapping, or endpoint onboarding in M9. -- Do not replace local standards aliases with production endpoints in M9. +- Do not implement SMART launch, EHR API clients, payer transport, X12 mapping, or endpoint onboarding as part of the docs-only production path. +- Do not replace local standards aliases with production endpoints as part of the docs-only production path. - Do not claim production EHR connectivity, production payer exchange, or Da Vinci certification. ## Risks / Blockers diff --git a/docs/production-path/fhir-data-plane.md b/docs/production-path/fhir-data-plane.md index 344eb07..4c5fba8 100644 --- a/docs/production-path/fhir-data-plane.md +++ b/docs/production-path/fhir-data-plane.md @@ -24,7 +24,7 @@ FHIR resource mapping must preserve the domain model: `PriorAuthorizationCase` s ## Non-Goals - Do not implement Medplum, HAPI FHIR, cloud storage, or a migration here. -- Do not replace current fixtures or local SQLite during M9. +- Do not replace current fixtures or local SQLite as part of the docs-only production path. - Do not claim US Core, Da Vinci, SMART, PAS, or payer-specific conformance based on local FHIR-shaped resources. ## Risks / Blockers diff --git a/docs/production-path/security-authz-audit.md b/docs/production-path/security-authz-audit.md index 785c49a..1c79856 100644 --- a/docs/production-path/security-authz-audit.md +++ b/docs/production-path/security-authz-audit.md @@ -23,7 +23,7 @@ Audit must be immutable enough for security review, incident response, payer dis ## Non-Goals -- Do not implement Keycloak, OpenFGA, SMART launch, backend services, or secret rotation in M9. +- Do not implement Keycloak, OpenFGA, SMART launch, backend services, or secret rotation as part of the docs-only production path. - Do not treat local actor strings or deterministic traces as production authentication. - Do not store or process PHI until security, audit, tenant, and operational controls are implemented and reviewed. diff --git a/docs/roadmap.md b/docs/roadmap.md index 2e4b74b..e7567e1 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1,13 +1,13 @@ # Doctor Agent OS Roadmap -This roadmap is the M0 source of truth for aligning the repository around Doctor Agent OS while preserving the current M1-M7 synthetic Open Prior Auth Agent Workbench baseline. +This roadmap records the implemented M0-M9 path and remaining direction for Doctor Agent OS while preserving the current synthetic Open Prior Auth Agent Workbench baseline. ## Canonical Direction - Domain: provider-side prior authorization. - Implementation substrate: Doctor Agent OS. - First app: Open Prior Auth Agent Workbench. -- Current baseline: existing M1-M7 synthetic prior-auth workbench remains runnable baseline. +- Current baseline: M1-M8 synthetic prior-auth workbench plus M9 production-path documentation. - Near-term rule: deepen prior-auth first; broader healthcare administrative workflows are future expansion only. - Production posture: synthetic-only, standards-shaped, non-certified, not PHI-ready, not connected to live EHRs or payers. @@ -25,15 +25,17 @@ This roadmap is the M0 source of truth for aligning the repository around Doctor - Use Cases are the source of truth for application actions. - HTTP routes and ToolNet tools are sibling adapters over Use Cases. - ToolNet tools must not call internal HTTP routes. -- MCP exposes selected ToolNet tools and does not bypass ToolNet for case-changing actions. +- When MCP is implemented, it should expose selected ToolNet tools and must not bypass ToolNet for case-changing actions. - `apps/*` may import `packages/*`; `packages/*` must not import `apps/*`. -- M0 has no ADRs. Revisit ADRs after M1a/M1b enforce package and import boundaries. +- No ADRs were added in M0. Revisit ADRs only when a new decision is hard to reverse, surprising, and trade-off driven. ## M0: Agentic Alignment + Repo Reset -Goal: align public docs, roadmap, glossary, audit, and package map around Doctor Agent OS as substrate while preserving current M1-M7 baseline. +Status: complete. -Scope: refresh README, create roadmap/glossary/architecture/conformance/demo docs, add README-only package placeholders, add pre-agentic banners to M1-M7 docs, archive stale audit, create current audit, and update task tracking. +Goal: align public docs, roadmap, glossary, audit, and package map around Doctor Agent OS as substrate while preserving the prior M1-M7 baseline. + +Scope: refresh README, create roadmap/glossary/architecture/conformance/demo docs, add initial package placeholders, add pre-agentic banners to M1-M7 docs, archive stale audit, create current audit, and update task tracking. Out of scope: ADRs, code extraction, ToolNet implementation, MCP implementation, runtime implementation, UI redesign, production-path docs, database migrations, and root package rename. @@ -43,6 +45,8 @@ Files/packages affected: `README.md`, `docs/`, `packages/*/README.md`, `tasks/to ## M1a: Extract Prior Auth Core +Status: complete. + Goal: create `packages/prior-auth-core` as the provider-side prior-auth Use Case and ports package. Scope: create a real package manifest/config, add simple string ID aliases, define ports, extract current prior-auth Use Cases, and keep API/UI behavior unchanged. @@ -55,6 +59,8 @@ Files/packages affected: `packages/prior-auth-core`, `apps/api`, `packages/share ## M1b: Doctor ToolNet Foundation +Status: complete. + Goal: add ToolNet as the agent/tool adapter over `prior-auth-core`, with executable read/draft tools only. Scope: create a real package, add registry/metadata/schemas/risk/approval metadata/call record shape, implement read/draft tools, and declare guarded write/submit tools as non-executable. @@ -67,6 +73,8 @@ Files/packages affected: `packages/doctor-toolnet`, `packages/prior-auth-core`, ## M2: Doctor Runtime + ApprovalGate +Status: complete. + Goal: add minimal workflow-agnostic runtime lifecycle, approval pause/resume, and durable trace state. Scope: create `packages/doctor-runtime`; add `AgentRun`, `AgentTask`, `TaskPlan`, `ToolCallRecord`, `ApprovalRequest`, `ApprovalDecision`, and `TraceEvent`; add SQLite runtime tables; pause guarded writes for approval and resume/reject after human decision. @@ -79,6 +87,8 @@ Files/packages affected: `packages/doctor-runtime`, `packages/doctor-toolnet`, ` ## M3: Deterministic Prior-Auth Agent Team +Status: complete. + Goal: implement replayable scripted prior-auth agent team over Runtime + ToolNet. Scope: add deterministic orchestrator, requirement discovery, documentation, evidence, packet assembly, and compliance boundary roles; support MRI happy path from queue to approval request; add minimal golden trace smoke test. @@ -91,6 +101,8 @@ Files/packages affected: `packages/doctor-runtime`, `packages/doctor-toolnet`, ` ## M4: Reusable Prior-Auth Domain Proof +Status: complete. + Goal: prove the same core/runtime/tool path supports a second payer/service-line scenario. Scope: add DME Power Wheelchair Authorization for Blue Ridge Health with synthetic rule pack, questionnaire, evidence fixtures, packet preview support, and same workflow path as MRI. @@ -103,6 +115,8 @@ Files/packages affected: `data`, `packages/prior-auth-core`, `packages/doctor-to ## M5: Agent Cockpit +Status: complete. + Goal: build prior-auth cockpit where business case state is primary and agent trace is visible trust/debug layer. Scope: one page supports MRI and DME scenarios with case header, current blocker/next action, agent run timeline, evidence-to-requirement board, questionnaire/packet summary, packet preview, audit/status timeline, and scenario switcher. @@ -115,6 +129,8 @@ Files/packages affected: `apps/web`, `apps/api`, shared contracts, demo docs/scr ## M6: Standards-Shaped ToolNet Tools +Status: complete. + Goal: make internal ToolNet/core actions standards-shaped before exposing protocol routes. Scope: add standards-shaped ToolNet tools for CRD discovery/invocation, DTR questionnaire package, PAS packet build, and guarded PAS mock submit; add mappers/schemas and fixture-level tests. @@ -127,6 +143,8 @@ Files/packages affected: `packages/doctor-toolnet`, `packages/prior-auth-core`, ## M7: Standards Gateway HTTP Routes + Tests +Status: complete. + Goal: expose standards-shaped HTTP adapters over ToolNet/core and validate via fixture tests. Scope: add SMART discovery, CDS services, CRD invocation, FHIR `Questionnaire/$questionnaire-package`, FHIR `Claim/$submit`, OperationOutcome-style errors, and conformance matrix fixture tests. @@ -139,6 +157,8 @@ Files/packages affected: `apps/api`, `packages/doctor-toolnet`, `data/standards` ## M8: Formal Doctor Evals +Status: complete. + Goal: add narrow deterministic regression/safety harness, not eval platform. Scope: create `packages/doctor-evals`; add scenario registry for MRI happy path, DME happy path, MRI missing evidence, and MRI prompt-injection evidence; add golden trace diffs, tool policy assertions, safety claim checks, JSON/Markdown reports, and `npm run evals`. @@ -151,6 +171,8 @@ Files/packages affected: `packages/doctor-evals`, `packages/doctor-runtime`, `pa ## M9: Production-Path Docs +Status: complete as documentation only. + Goal: document production path without implementing production system. Scope: create `docs/production-path/` with docs for FHIR data plane, security/authz/audit, EHR/payer integration, deployment/observability, and conformance test path. @@ -159,4 +181,10 @@ Out of scope: Medplum/HAPI implementation, Keycloak/OpenFGA implementation, real Exit criteria: each doc states current OSS posture, production requirement, adapter/interface to build, non-goals, risks/blockers, and sequence prerequisites. -Files/packages affected: `docs/production-path/` only when M9 begins. M0 intentionally does not create this directory. +Files/packages affected: `docs/production-path/`. + +## Remaining Direction + +- Implement Doctor MCP as the external agent interoperability boundary over selected ToolNet tools, resources, and prompts. +- Keep production work docs-only until security, data plane, payer/EHR integration, deployment, observability, and conformance prerequisites are intentionally funded and scoped. +- Keep all current runtime, standards, and eval claims synthetic-only, local-first, non-certified, and non-PHI-ready. diff --git a/docs/standards/conformance-matrix.md b/docs/standards/conformance-matrix.md index d7c0df6..aeac5c1 100644 --- a/docs/standards/conformance-matrix.md +++ b/docs/standards/conformance-matrix.md @@ -13,9 +13,9 @@ This matrix documents current standards-shaped boundaries. It does not claim cer ## Roadmap Landing Points -- M6 adds standards-shaped ToolNet tools before protocol routes. -- M7 adds standards gateway HTTP routes and fixture conformance tests. -- M9 documents the production-path requirements for real SMART, CRD, DTR, PAS, security, EHR/payer integration, deployment, observability, and conformance testing. +- M6 added standards-shaped ToolNet tools before protocol routes. +- M7 added standards gateway HTTP routes and fixture conformance tests. +- M9 documented the production-path requirements for real SMART, CRD, DTR, PAS, security, EHR/payer integration, deployment, observability, and conformance testing. ## Safety Language diff --git a/infra/compose/README.md b/infra/compose/README.md index 7e9f301..684a112 100644 --- a/infra/compose/README.md +++ b/infra/compose/README.md @@ -1,9 +1,12 @@ # Compose Notes -M1 intentionally keeps infrastructure light. The API uses a fixture-backed FHIR adapter that preserves the Medplum boundary without requiring self-hosted healthcare infrastructure during the first sprint. +The current workbench intentionally keeps infrastructure light. The API, web app, ToolNet, Runtime, standards gateway, and Doctor Evals run locally over synthetic fixtures and SQLite without self-hosted healthcare infrastructure. -When Medplum self-hosting becomes useful, add its services here and keep the API-facing contract stable: +The compose file is for local API/web convenience only. It is not a production deployment, PHI-ready environment, payer gateway, EHR integration, or conformance test harness. -- Patient, coverage, encounter, practitioner, organization, and request lookup stays behind the FHIR repository interface. -- Requirement evaluation remains deterministic. -- `POST /work-items` continues to reference stored evaluation results by `evaluationId`. +If a production-oriented FHIR data plane becomes useful later, add it behind stable package/application boundaries: + +- Patient, coverage, encounter, practitioner, organization, and request lookup stay behind the FHIR repository interface. +- Prior-auth workflow state stays behind `PriorAuthStore` and Runtime store boundaries. +- Requirement evaluation remains deterministic for checked-in synthetic scenarios. +- ToolNet and Runtime must not bypass approval, trace, or package-boundary rules. diff --git a/packages/doctor-mcp/README.md b/packages/doctor-mcp/README.md index cfb95eb..73ba3de 100644 --- a/packages/doctor-mcp/README.md +++ b/packages/doctor-mcp/README.md @@ -1,12 +1,13 @@ # Doctor MCP -README-only M0 placeholder. +README-only placeholder for the next unimplemented Doctor Agent OS protocol boundary. -This planned package will expose selected Doctor ToolNet tools through MCP. Do not add `package.json`, `tsconfig.json`, source files, or build config in M0. +This planned package will expose selected Doctor ToolNet tools, resources, and prompts through MCP. ToolNet, Runtime, ApprovalGate, Agent Cockpit, standards-shaped gateway routes, and Doctor Evals now exist; MCP remains unimplemented until a dedicated milestone adds a real package manifest, source, tests, and docs. Boundary rules: -- MCP exposes selected ToolNet tools +- MCP should expose selected ToolNet tools - MCP does not bypass ToolNet for case-changing actions - MCP does not call internal HTTP routes as a shortcut - guarded tools remain governed by ApprovalGate +- MCP docs must preserve synthetic-only, non-certified, non-PHI-ready language diff --git a/packages/doctor-toolnet/README.md b/packages/doctor-toolnet/README.md index f3389ac..a5df304 100644 --- a/packages/doctor-toolnet/README.md +++ b/packages/doctor-toolnet/README.md @@ -38,7 +38,7 @@ Guarded runtime tools: ## Standards-Shaped Sibling Tools -M6 adds standards-shaped tools that preserve explicit local non-conformance metadata: +M6 added standards-shaped tools that preserve explicit local non-conformance metadata: - `doctor.crd.discover_services` - `doctor.crd.invoke_service` @@ -73,4 +73,4 @@ Boundary rules: - does not call internal HTTP routes - does not fetch local servers - does not import `apps/*` -- keeps guarded write/submit tools non-executable until ApprovalGate exists +- keeps guarded write/submit tools non-executable outside Doctor Runtime ApprovalGate diff --git a/packages/prior-auth-core/README.md b/packages/prior-auth-core/README.md index 828ba7f..dcf5b3e 100644 --- a/packages/prior-auth-core/README.md +++ b/packages/prior-auth-core/README.md @@ -2,7 +2,7 @@ Provider-side prior authorization Use Case and ports package for Doctor Agent OS. -M1a makes this a real workspace package. HTTP routes in `apps/api` and future ToolNet tools are sibling adapters over these Use Cases. +M1a made this a real workspace package. HTTP routes in `apps/api` and Doctor ToolNet tools are sibling adapters over these Use Cases. ## Boundary @@ -11,7 +11,7 @@ M1a makes this a real workspace package. HTTP routes in `apps/api` and future To - Exposes ports for clinical context, store, clock, and ID generation. - Keeps `PriorAuthorizationCase` as domain root. - Keeps `WorkItem` as queue projection. -- Does not expose agent-callable tools. +- Does not expose agent-callable tools directly; Doctor ToolNet owns that adapter layer. ## Exports diff --git a/subagents/instructions.md b/subagents/instructions.md index 6d3db0c..4d96041 100644 --- a/subagents/instructions.md +++ b/subagents/instructions.md @@ -29,8 +29,8 @@ the repository's current prior authorization scope. must not import `apps/*`. - Treat Use Cases as the source of truth for application actions. - ToolNet tools call Use Cases directly; they do not call internal HTTP routes. -- MCP exposes selected ToolNet tools; it does not bypass ToolNet for - case-changing actions. +- When MCP is implemented, it should expose selected ToolNet tools and must not + bypass ToolNet for case-changing actions. - Keep edits minimal and verify before claiming done. ## Role Files diff --git a/subagents/prior-auth-domain-guardian.md b/subagents/prior-auth-domain-guardian.md index 96809f0..611e017 100644 --- a/subagents/prior-auth-domain-guardian.md +++ b/subagents/prior-auth-domain-guardian.md @@ -31,7 +31,7 @@ Provide only the bounded context needed for the review: ## Workflow 1. Read `CONTEXT.md` and `docs/glossary.md` terms relevant to the task. -2. Check `docs/roadmap.md` for current milestone and out-of-scope boundaries. +2. Check `tasks/audit.md` for current implementation status and `docs/roadmap.md` for intended roadmap/out-of-scope boundaries. 3. Inspect only the files needed for the assigned question. 4. Identify mismatches in domain language, architecture boundaries, safety claims, conformance claims, and package direction. @@ -52,7 +52,7 @@ Provide only the bounded context needed for the review: - Use Cases remain the application action source of truth. - HTTP routes and ToolNet tools remain sibling adapters over Use Cases. - ToolNet tools do not call internal HTTP routes. -- MCP does not bypass ToolNet for case-changing actions. +- If MCP is implemented, it does not bypass ToolNet for case-changing actions. - `apps/*` may import `packages/*`; `packages/*` must not import `apps/*`. - Safety language stays synthetic-only, non-certified, not PHI-ready, and no live EHR or payer connectivity. diff --git a/tasks/audit.md b/tasks/audit.md index 8d19b9f..3c471c0 100644 --- a/tasks/audit.md +++ b/tasks/audit.md @@ -6,9 +6,9 @@ Primary source: `open_prior_auth_workbench_strategy_report.pdf`, especially sect ## Executive Finding -The repository is ahead of several stale docs and todo entries. The current codebase implements much of the report's synthetic open-source agentic target: Prior Auth Core, Doctor ToolNet, Doctor Runtime with ApprovalGate, deterministic prior-auth agent team, Agent Cockpit, standards-shaped gateway routes, Doctor Evals, and production-path documentation. +The repository had drifted ahead of several stale docs and todo entries. The current codebase implements much of the report's synthetic open-source agentic target: Prior Auth Core, Doctor ToolNet, Doctor Runtime with ApprovalGate, deterministic prior-auth agent team, Agent Cockpit, standards-shaped gateway routes, Doctor Evals, and production-path documentation. -The project still correctly does not meet the production implementation north star. It remains synthetic-only, local-first, non-certified, not PHI-ready, and disconnected from live EHR and payer systems. The biggest current gap is not core implementation velocity; it is status/documentation drift. +The project still correctly does not meet the production implementation north star. It remains synthetic-only, local-first, non-certified, not PHI-ready, and disconnected from live EHR and payer systems. The biggest implementation gap is Doctor MCP; the biggest documentation risk was status drift. ## PDF North-Star Summary @@ -49,12 +49,9 @@ The report says to build now: MRI prior-auth vertical slice, custom runtime, too ## Documentation Drift Findings -- `AGENTS.md` still describes a document-first repo with no checked-in build pipeline/test suite, but the repo now has TypeScript workspaces, API/web apps, packages, contract tests, CI, evals, and build/typecheck scripts. -- `README.md` still says the runnable baseline is M1-M7 and calls `packages/doctor-evals` README-only/planned, while `packages/doctor-evals` is a real package and demo docs describe M1-M8. -- `docs/architecture/doctor-agent-os.md` still says no runtime, ToolNet, MCP server, or eval package exists; runtime, ToolNet, and eval package now exist. -- `docs/architecture/strategy_report_implementation_audit.md` is dated May 22 and describes M0 reset only; it is stale against current package/code state. -- `docs/roadmap.md` still frames itself as the M0 source of truth and says production-path docs are future/M9, while `docs/production-path/` now exists. +- Resolved in the documentation sync pass: `AGENTS.md`, `README.md`, `CONTRIBUTING.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md`, `docs/roadmap.md`, `docs/architecture/doctor-agent-os.md`, `docs/architecture/strategy_report_implementation_audit.md`, `docs/architecture/mcp.md`, `docs/demo/agentic-story-flow.md`, `packages/doctor-mcp/README.md`, and `infra/compose/README.md` now describe the current implementation status. - Previous `tasks/todo.md` mixed active todo, milestone history, old audits, and stale open items; it has been reset to active work only. +- Historical archive docs under `docs/architecture/archive/` intentionally remain unchanged as archived point-in-time records. ## Safety And Conformance Boundary diff --git a/tasks/todo.md b/tasks/todo.md index 2053ac9..448638e 100644 --- a/tasks/todo.md +++ b/tasks/todo.md @@ -22,9 +22,11 @@ - `tasks/todo.md` was reset from historical milestone log to current active tracker. - Historical M0-M9 implementation notes, old partial audits, stale "pause to execute M0" item, and in-progress domain grilling leftovers were removed from active todo state. - Verification passed: `npm test` 87/87, `npm run typecheck`, `npm run build`, and `npm run evals` 4/4 scenarios with 88/88 assertions. +- Documentation sync pass updated stale status language across root docs, roadmap, architecture docs, demo docs, package READMEs, production-path docs, compose notes, and subagent prompts. +- Verification after documentation sync passed: `npm test` 87/87, `npm run typecheck`, `npm run build`, and `npm run evals` 4/4 scenarios with 88/88 assertions. ## Active Follow-Ups -- [ ] Sync stale status docs called out in `tasks/audit.md`: `README.md`, `docs/roadmap.md`, `docs/architecture/doctor-agent-os.md`, `docs/architecture/strategy_report_implementation_audit.md`, and `AGENTS.md`. +- [x] Sync stale status docs called out in `tasks/audit.md`: root docs, package READMEs, roadmap, architecture docs, demo story, compose notes, and active audit notes. - [ ] Decide whether `packages/doctor-mcp` should remain a placeholder or become the next implementation milestone. - [ ] Decide whether to add dedicated UI/e2e coverage for the Agent Cockpit beyond build/typecheck and API-backed contract tests.