wdwd720 · wdwd720 · Apr 18, 2026 · May 14, 2026
diff --git a/docs/AUTONOMY_TRAINING.md b/docs/AUTONOMY_TRAINING.md
@@ -0,0 +1,54 @@
+# MedSim Autonomy Training
+
+MedSim autonomy support is simulation-only. It is not live robot control, not
+patient care, and not autonomous surgery.
+
+## Current Implementation
+
+- Internal `AutonomyEnv` with `reset`, `step`, `render`, and `close`.
+- Observation schema includes tool pose, needle pose, gripper state, target
+  state, placeholder deformation/contact summaries, safety state, task phase,
+  previous command, and camera quality.
+- Action schema includes tool deltas, rotation deltas, gripper command,
+  primitive command, no-op, and emergency stop.
+- Safety shield rejects unknown tools, excessive command deltas, and emergency
+  stop commands before backend execution.
+- Baseline policies:
+  - `scripted`
+  - `random`
+- Reward output includes completion reward, collision penalty, unsafe command
+  penalty, and time penalty.
+
+## Commands
+
+```bash
+python3 -m medsim.cli autonomy benchmark \
+  --backend placeholder \
+  --scenario configs/scenarios/normal.yaml \
+  --episodes 10
+```
+
+```bash
+python3 -m medsim.cli autonomy evaluate-policy \
+  --policy scripted \
+  --scenario configs/scenarios/normal.yaml
+```
+
+```bash
+python3 -m medsim.cli autonomy export-demos \
+  --runs artifacts/runs \
+  --out artifacts/datasets/demo_policy
+```
+
+## Artifacts
+
+Autonomy benchmark runs write:
+
+- `policy_rollout.json`
+- `observations.jsonl`
+- `actions.jsonl`
+- `rewards.jsonl`
+- `safety_events.jsonl`
+- `autonomy_metrics.json`
+
+All outputs are non-patient simulation artifacts.
diff --git a/docs/HOSPITAL_PILOT_READINESS.md b/docs/HOSPITAL_PILOT_READINESS.md
@@ -0,0 +1,37 @@
+# Hospital Pilot Readiness
+
+MedSim hospital pilot mode is supervised, non-patient, and evaluation-only.
+
+## Allowed Pilot Scope
+
+- Research, training, simulation, and phantom/bench evaluation.
+- No patient care.
+- No clinical decision support.
+- No live autonomous surgery.
+- Audit logging and artifact export required.
+- Risk acknowledgement required for `hospital_pilot_non_patient` mode.
+
+## Metadata
+
+Run artifacts carry pilot metadata from `SceneConfig.pilot`:
+
+- `use_mode`
+- `risk_acknowledged`
+- `operator_id`
+- `institution`
+- `reviewer`
+- `approved_protocol_id`
+- `intended_use`
+
+## Checklist
+
+- Confirm non-patient protocol.
+- Record operator and reviewer.
+- Record approved protocol ID where applicable.
+- Export validation bundle.
+- Review cybersecurity settings.
+- Review fidelity disclosure.
+
+Clinical use, patient-care decisions, or autonomous real-world actuation require
+formal validation, domain expert review, QMS controls, cybersecurity review, and
+regulatory clearance where applicable.
diff --git a/docs/PHANTOM_VALIDATION_PROTOCOL.md b/docs/PHANTOM_VALIDATION_PROTOCOL.md
@@ -0,0 +1,29 @@
+# Phantom Validation Protocol
+
+MedSim includes a scaffold for comparing simulation runs against bench/phantom
+trial data. The current fixture is synthetic and validates the pipeline only.
+
+## Bench Metadata
+
+Bench data must identify phantom material, geometry, camera/tracker system,
+calibration metadata, operator, instrument setup, trial ID, task type, recorded
+trajectory, target points, deformation proxy, contact timing if available, notes,
+and data quality flags.
+
+## Metrics
+
+The comparison pipeline reports:
+
+- trajectory RMSE
+- endpoint error
+- needle pose error
+- contact timing error when available
+- deformation proxy error
+- task success agreement
+- safety event agreement when available
+
+## Claim Boundary
+
+`phantom_validated` fidelity is blocked unless real phantom comparison artifacts
+exist and satisfy externally reviewed acceptance criteria. Synthetic fixtures do
+not permit phantom-validated claims.
diff --git a/docs/PRODUCTION_BUILD_LOG.md b/docs/PRODUCTION_BUILD_LOG.md
diff --git a/docs/ROBOT_BENCH_INTEGRATION.md b/docs/ROBOT_BENCH_INTEGRATION.md
@@ -0,0 +1,23 @@
+# Robot Bench Integration
+
+MedSim includes only a dry-run robotics abstraction. Hardware adapters are
+disabled by default and no real robot actuation code is included.
+
+## Current Scope
+
+- Preview a command.
+- Enforce command delta and rotation limits.
+- Preserve emergency-stop state as a no-actuation condition.
+- Require `NO PATIENT USE` metadata.
+- Define calibration evidence expectations for future bench/phantom adapters.
+
+## Not Implemented
+
+- Real robot drivers.
+- Network or serial hardware control.
+- Live autonomous actuation.
+- Patient-care use.
+
+Any future hardware adapter must be explicitly enabled, separately reviewed, and
+limited to supervised bench/phantom use with calibration and emergency-stop
+evidence.
diff --git a/docs/SOFA_BACKEND.md b/docs/SOFA_BACKEND.md
@@ -0,0 +1,63 @@
+# MedSim SOFA Backend
+
+MedSim includes a dependency-gated SOFA adapter path. It is intentionally honest:
+the adapter can build MedSim-owned scene plans without SOFA installed, and it
+can report dependency health, but it does not claim physics execution unless a
+real local SOFA runtime is importable and the requested runtime operation
+succeeds.
+
+## Current Status
+
+- Placeholder backend remains the runnable deterministic backend.
+- SOFA imports are lazy and optional.
+- `SofaBackend.backend_info()`, backend registry health, and preflight reports
+  work without SOFA installed.
+- `build_sofa_scene_plan(scene_config, scenario)` maps the current needle-passing
+  scene into canonical SOFA planning components: tissue, tools, needle, camera,
+  targets, scenario perturbations, and expected state fields.
+- If SOFA is installed and exposes `Sofa.Core.Node`, `SofaSceneBuilder` can build
+  a minimal root-node scene with metadata child nodes.
+- `SimulationBackend.step()` for SOFA is not implemented. Recorder-compatible
+  SOFA episodes, real contacts, FEM deformation, rendering, and deterministic
+  replay are not implemented.
+
+## Verification
+
+Run:
+
+```bash
+python3 -m medsim.cli sofa preflight \
+  --scene configs/base_scene.yaml \
+  --scenario configs/scenarios/normal.yaml
+```
+
+Optional minimal runtime build attempt:
+
+```bash
+python3 -m medsim.cli sofa preflight \
+  --scene configs/base_scene.yaml \
+  --scenario configs/scenarios/normal.yaml \
+  --attempt-runtime
+```
+
+When SOFA is missing, the expected status is `available: false` with
+`fidelity_level: sofa_unavailable_adapter_only`. That is not a failure of the
+placeholder backend.
+
+## Install Hint
+
+Install SOFA and SofaPython3 in the active Python environment, then verify:
+
+```bash
+python3 -c "import importlib; print(importlib.import_module('Sofa').__name__)"
+```
+
+SOFA packaging varies by platform, so MedSim does not pin SOFA as a required
+dependency.
+
+## Claim Boundary
+
+Do not describe the SOFA adapter as high-fidelity physics, FEM simulation,
+phantom validated, or clinically validated until real executable SOFA scenes,
+physics-derived state extraction, recorder-compatible artifacts, and validation
+evidence exist.
diff --git a/docs/qms/CHANGE_CONTROL.md b/docs/qms/CHANGE_CONTROL.md
@@ -0,0 +1,4 @@
+# Change Control
+
+Changes require scoped review, tests, build verification, build log updates, and
+claim-boundary review before release.
diff --git a/docs/qms/CLINICAL_VALIDATION_PLAN.md b/docs/qms/CLINICAL_VALIDATION_PLAN.md
@@ -0,0 +1,4 @@
+# Clinical Validation Plan
+
+No clinical validation is complete. Clinical claims require protocol approval,
+domain expert review, real-world evidence, and regulatory strategy.
diff --git a/docs/qms/CYBERSECURITY_PLAN.md b/docs/qms/CYBERSECURITY_PLAN.md
@@ -0,0 +1,4 @@
+# Cybersecurity Plan
+
+Use API key auth for pilot deployments, restrict CORS, isolate artifact paths,
+avoid secret logging, and review dependencies before external deployment.
diff --git a/docs/qms/DATA_GOVERNANCE.md b/docs/qms/DATA_GOVERNANCE.md
@@ -0,0 +1,4 @@
+# Data Governance
+
+MedSim artifacts are non-patient simulation data by default. Do not store PHI in
+prompts, metadata, bench files, or artifacts.
diff --git a/docs/qms/INTENDED_USE_AND_CLAIMS.md b/docs/qms/INTENDED_USE_AND_CLAIMS.md
@@ -0,0 +1,8 @@
+# Intended Use and Claims
+
+Allowed: production-grade infrastructure for non-patient simulation, synthetic
+data, replay/evaluation, autonomy training in simulation/phantom contexts, and
+QMS-readiness artifacts.
+
+Disallowed: FDA-cleared, clinically validated, patient-care ready, autonomous
+surgery ready, or physically validated SOFA claims without evidence.
diff --git a/docs/qms/PRODUCT_REQUIREMENTS.md b/docs/qms/PRODUCT_REQUIREMENTS.md
@@ -0,0 +1,5 @@
+# Product Requirements
+
+MedSim provides non-patient surgical robotics simulation infrastructure for
+research, synthetic data, replay/evaluation, and supervised pilot assessment.
+Clinical use requires external validation and regulatory clearance.
diff --git a/docs/qms/REGULATORY_STRATEGY_NOTES.md b/docs/qms/REGULATORY_STRATEGY_NOTES.md
@@ -0,0 +1,4 @@
+# Regulatory Strategy Notes
+
+Current positioning is non-clinical research and supervised non-patient pilot
+evaluation. Regulated use requires formal regulatory review.
diff --git a/docs/qms/RELEASE_CHECKLIST.md b/docs/qms/RELEASE_CHECKLIST.md
@@ -0,0 +1,9 @@
+# Release Checklist
+
+- Tests pass.
+- Lint passes.
+- Frontend build passes.
+- Demo pipeline runs.
+- QMS verify passes.
+- SOFA status disclosed.
+- Clinical claims absent.
diff --git a/docs/qms/REQUIREMENTS.yaml b/docs/qms/REQUIREMENTS.yaml
@@ -0,0 +1,53 @@
+requirements:
+  - id: MEDSIM-BACKEND-001
+    title: Honest backend capability reporting
+    description: Backends shall report health, fidelity, limitations, and missing dependencies.
+    rationale: Prevent unsupported physics or clinical claims.
+    risk_links: [RISK-CLAIMS-001]
+    verification_method: automated_test
+    verification_artifacts: [tests/test_backend_registry.py]
+    implementation_files: [src/medsim/sim/capabilities.py, src/medsim/sim/backend_registry.py]
+    tests: [python3 -m pytest tests/test_backend_registry.py]
+    status: implemented
+    owner: engineering
+    release_blocking: true
+  - id: MEDSIM-DATA-001
+    title: Audit-grade placeholder artifact bundle
+    description: Placeholder runs shall produce manifests, checksums, provenance, metrics, and trace streams.
+    rationale: Support reproducibility and dataset review.
+    risk_links: [RISK-DATA-001]
+    verification_method: automated_test
+    verification_artifacts: [tests/test_artifact_bundle_and_dataset.py]
+    implementation_files: [src/medsim/data/artifacts.py]
+    tests: [python3 -m pytest tests/test_artifact_bundle_and_dataset.py]
+    status: implemented
+    owner: engineering
+    release_blocking: true
+  - id: MEDSIM-SAFETY-001
+    title: Non-patient autonomy boundary
+    description: Autonomy tools shall be simulation-only and carry no-patient-use metadata.
+    rationale: Prevent misuse as live autonomous surgery.
+    risk_links: [RISK-AUTO-001]
+    verification_method: automated_test
+    verification_artifacts: [tests/test_autonomy.py]
+    implementation_files: [src/medsim/autonomy]
+    tests: [python3 -m pytest tests/test_autonomy.py]
+    status: implemented
+    owner: engineering
+    release_blocking: true
+risks:
+  - id: RISK-CLAIMS-001
+    title: Unsupported clinical or physics claims
+    severity: critical
+    mitigation: UI/API/docs/backend metadata disclose fidelity and prohibited uses.
+    status: mitigated
+  - id: RISK-DATA-001
+    title: Incomplete provenance
+    severity: major
+    mitigation: Run bundles include provenance, environment, manifests, and checksums.
+    status: mitigated
+  - id: RISK-AUTO-001
+    title: Autonomy misuse
+    severity: critical
+    mitigation: Autonomy is simulation-only; robot integration is dry-run only.
+    status: mitigated
diff --git a/docs/qms/RISK_MANAGEMENT_PLAN.md b/docs/qms/RISK_MANAGEMENT_PLAN.md
@@ -0,0 +1,4 @@
+# Risk Management Plan
+
+Track claim, data, autonomy, security, and validation risks. Critical risks must
+have mitigations before pilot use.
diff --git a/docs/qms/RISK_REGISTER.md b/docs/qms/RISK_REGISTER.md
@@ -0,0 +1,3 @@
+# Risk Register
+
+Primary machine-readable risks live in `REQUIREMENTS.yaml`.
diff --git a/docs/qms/SBOM_NOTES.md b/docs/qms/SBOM_NOTES.md
@@ -0,0 +1,4 @@
+# SBOM Notes
+
+Current dependency inventory is available through `GET /dependencies`. A formal
+SBOM should be generated before external pilot deployment.
diff --git a/docs/qms/SOFTWARE_REQUIREMENTS_SPEC.md b/docs/qms/SOFTWARE_REQUIREMENTS_SPEC.md
@@ -0,0 +1,6 @@
+# Software Requirements Specification
+
+The software shall provide deterministic placeholder execution, backend
+capability reporting, SOFA preflight, artifact bundles, replay validation,
+dataset export, autonomy benchmarks, dry-run robotics previews, phantom
+comparison, and validation bundle export.
diff --git a/docs/qms/TRACEABILITY_MATRIX.md b/docs/qms/TRACEABILITY_MATRIX.md
@@ -0,0 +1,5 @@
+# Traceability Matrix
+
+Traceability source: `docs/qms/REQUIREMENTS.yaml`.
+
+Run `python3 -m medsim.cli qms trace` to generate a current report.
diff --git a/docs/qms/VERIFICATION_PLAN.md b/docs/qms/VERIFICATION_PLAN.md
@@ -0,0 +1,4 @@
+# Verification Plan
+
+Verification uses pytest, ruff, frontend build, CLI smoke commands, replay
+validation, dataset validation, QMS verification, and demo pipeline execution.
diff --git a/docs/qms/VERIFICATION_REPORT_TEMPLATE.md b/docs/qms/VERIFICATION_REPORT_TEMPLATE.md
@@ -0,0 +1,8 @@
+# Verification Report Template
+
+- Version:
+- Commit:
+- Commands run:
+- Results:
+- Known gaps:
+- Release decision:
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Risk Register

		Primary machine-readable risks live in `REQUIREMENTS.yaml`.