Hospital Readiness Framework

Delivery BoundaryCopy Anchor Link

This implements gap-closure U2. It is a configurable framework, not an approved clinical checklist. It adds manual evidence, separate review, bounded override, immutable command history, and transition gates. The case list, detail, and transition checks use the same current evidence rules. Lab PDF intake, pharmacy source records, Inventory case links, and nursing documentation remain separate units. The implementation backlog tracks those gaps.

Policy And ApprovalCopy Anchor Link

Clinical owns Hospital::ReadinessPolicyVersion, CaseReadinessItem, and ReadinessCommand. Every policy belongs to one tenant, facility, and facility procedure. It records an active member as approver, an external approval reference, approval time, version, and rules. Each rule defines its category, source, required status, review requirement, stages, freshness, and override limits. Both in_ot and completed must have rules. No universal checklist or production policy seed is supplied.

Readiness::PublishPolicy.call is an internal operator service. It requires current configuration and case-management authority and an atomic audit record. It records external clinical approval; a successful service call does not prove that approval exists. There is no policy-publishing HTTP route. Shell owns permission administration; Admin owns feature flags.

New cases bind the latest approved procedure policy. An active case keeps its original version. Readiness::BindPolicy.call can bind a later policy with a reason and audit record. It resets current evidence and retains command history. It does not silently approve old evidence. Case detail shows only requirements that match the bound policy. Removed requirements remain in history, not the current checklist. Do not rebind active care in a bulk migration. Confirm the clinical handoff before deployment.

Evidence ContractCopy Anchor Link

• record_source accepts manual clinical or consent evidence only. It increments the source revision and sets approved freshness.
• review records a decision against one current source revision. A review does not change a blocked source into ready evidence.
• override requires category management, the override key, an explicit member or role grant, a reason, and an approved override rule.
• An owner role alone cannot authorize a clinical override. Missing, unavailable, stale, or unstarted evidence cannot be overridden.
• Inventory rules cannot use clinical review or override to bypass physical stock truth.
• Replacement evidence invalidates old review and override by revision. Freshness and override leases expire at their exact boundary.
• A missing policy or required item cannot clear OT start or discharge. Optional missing evidence warns but does not block.

Commands send item version, source_revision, and a stable operation_key. The server locks the case and reloads evidence before it checks current membership, scope, modules, permissions, and versions. Source writes, policy rebinding, and clinical transitions use the same case lock. Command history, clinical event, evidence, and required activity audit commit together. Immutable database triggers protect policy and command history from update or delete.

The same key and payload return the original result. A changed payload returns IDEMPOTENCY_CONFLICT. The original result is historical evidence, not current readiness or current permissions. Each result retains the bound policy ID and full rule snapshot, even after a later rebind. PHI access logs record a new command as an amendment and an unchanged replay as a view. Refetch case detail, the case list, and OT queries after success. After an unknown response, retry the same complete command. Do not create a new key. The UI pins an open review to its evidence revision. A background change requires reopening the form.

Security And HTTPCopy Anchor Link

Both new tables have ENABLE and FORCE tenant RLS with safe missing-context handling. Composite foreign keys enforce tenant, facility, procedure, case, and item scope. The facility selector is not authority. Current active assignment or tenant owner/admin scope is required. Suspended tenants retain authorized history reads but cannot write. Category modules and category permissions apply to direct command routes as well as the UI. Clients cannot supply actor or tenant identity. Unknown command fields are rejected.

See the API reference for routes, DTOs, and errors. Source integration commands must use this case lock and revision contract. Do not make raw item updates from future Lab or stock handlers. There is no public command to claim an integrated source is ready.

Deployment And VerificationCopy Anchor Link

Apply 20261012000001_add_hospital_readiness_commands.rb and 20261012000002_add_hospital_readiness_permissions.rb. The first migration is additive. It refuses rollback if approved policy or command history exists. The rollback check locks both history tables and checks across tenants as the table owner. An explicit transaction restores FORCE RLS if it refuses. Missing tenant context cannot hide stored care history. The second adds owner-default catalog keys; other roles need Shell grants. The explicit clinical override check still applies to owners.

Clinical release gate D3 remains open. Obtain signed checklist content, freshness, override authority, emergency rules, and representative-case approval. Before release, identify existing active cases without a bound policy and agree on their care handoff. Absent approval, keep this build out of active clinical use. Do not seed test rules to bypass the gate.

Run the manual QA checklist. Use a disposable test database. Run bin/rails db:test:prepare, then bin/rails db:rls_test_role:provision before RLS tests. Schema preparation can replace schemas and remove earlier grants. Provision after preparation. The automated tests use a clearly marked test-only rule. They are not clinical acceptance. Scope review and tests do not replace whole-PR frontend/backend CI, staging QA, or release approval.

Review CorrectionsCopy Anchor Link

• Invalid readiness filters return an invalid-state message, not a claim that integration is inactive.
• Known version conflicts refetch case evidence before the user reopens the review.
• Unknown outcomes retain the original command and key. They do not use the conflict recovery path.
• Review forms reset on tenant, facility, profile, or case changes.
• Populated rollback is tested under a non-bypass table owner with no tenant context.
• Removed policy requirements do not appear as current checklist rows; their command history remains readable.
• Retry access logs do not claim a second amendment. Immutable results retain the policy and rule used for the decision.

These checks protect the read, review, retry, and deployment contracts. Keep them when source integrations are added.

Local Verification RecordCopy Anchor Link

The local U2 check passed 494 Hospital/RBAC tests with 2033 assertions and no skips. This includes real HTTP requests, enforced-role tenant isolation, audit rollback, immutable retries, and independent-connection races. The Hospital frontend passed 171 tests in 23 files, typecheck, lint, and build. The scoped backend lint passed. The additive schema matches empty rollback/reapply. Populated rollback refusal is tested separately. Desktop and mobile checks used a synthetic component harness, not authenticated end-to-end acceptance. All scoped CodeRabbit findings were fixed with regression tests. The final scoped follow-up reported no findings. Whole-PR CI, complete PR review, staging QA, clinical approval, and active-care handoff remain open.