aw-spec-cli 0.1.8 → 0.1.10

package/assets/guardrails/domain/healthcare/domain-constitution.md

@@ -0,0 +1,119 @@
+# Domain Constitution — healthcare
+
+> The industry-specific governance base for this industry corpus. It heads the set mapped under
+> `## /aw-spec-constitution` in a project's `domain-rule-bindings.md` — this file, then the standard
+> industry rules beside it, then the project team's `domain-requirements.md` — which
+> `/appweaver constitution` ratifies into `.appweaver/memory/constitution.domain.md`.
+>
+> `domain-requirements.md` is supplied by the project owner and its mapping is optional: where
+> the file is absent the set loads without it, and the ratified half carries the standard
+> industry rules alone.
+
+This file carries **only** what is true because the industry is healthcare: project identity,
+the regulatory regime, and the domain principles that extend the technology base. Generic rules
+stay in the corpus's detail rule files — this file says which of them are supreme and
+non-negotiable, and cites them. Keep every principle to one declarative, testable line plus its
+`→` pointer; do not restate the rule file here.
+
+Principles are numbered **XVI+**, continuing the technology base which ends at XV. Each names
+the technical principle it extends. Experience principles (UX-*) belong to the lane corpus's
+`ui-constitution.md` and never appear here.
+
+## Project Identity
+
+- **Regulated role**: a system handling protected health information on behalf of covered
+  entities — clinical records, the consent that governs them, and the interoperability surfaces
+  other care systems read.
+- **Bounded contexts**: patient & identity · clinical record · consent & authorization ·
+  imaging · interoperability.
+- **Consumers**: care providers, patients exercising access rights, and partner clinical
+  systems, all through the published API and projections — never the database.
+
+## Regulatory Regime
+
+- **HIPAA** — Privacy, Security and Breach Notification Rules; the minimum-necessary standard
+  applies to every access path, not only to exports.
+- **HITECH** — breach notification and the accounting of disclosures.
+- **Interoperability** — HL7 FHIR as the published surface; HL7 v2 and DICOM at the boundaries
+  where the estate still speaks them.
+- Retention is jurisdiction-set and outranks any deletion request the platform can otherwise
+  honour; a right-to-erasure request against a retained clinical record is a documented refusal.
+
+## Domain Principles (XVI+)
+
+### XVI — PHI is Classified Before it is Stored (NON-NEGOTIABLE)
+*Extends IX (Security by Default).* Every field carrying protected health information is
+classified at design time; classification drives encryption, masking, export eligibility and log
+redaction — no field is classified after the fact, and unclassified PHI is a blocking defect.
+→ `guardrails/domain/healthcare/data-classification.domain.md`
+
+### XVII — Minimum Necessary is Enforced, Not Documented (NON-NEGOTIABLE)
+*Extends IX (Security by Default).* Access is scoped to the care relationship and the purpose of
+use; a query that can return more than the requester's role and purpose permit is a defect in
+the query, not a matter for review afterwards.
+→ `guardrails/domain/healthcare/authorization.domain.md`, `hipaa.md`
+
+### XVIII — Consent is a Precondition, Not a Filter (NON-NEGOTIABLE)
+*Extends IX (Security by Default).* Consent state is evaluated before a disclosure is assembled;
+no code path builds a response and then removes what consent forbids.
+→ `guardrails/domain/healthcare/consent.md`
+
+### XIX — Every PHI Touch is Auditable (NON-NEGOTIABLE)
+*Extends X (Observability).* Reads as well as mutations of PHI emit an audit record carrying
+actor, subject, purpose and outcome; the audit trail is append-only and survives the record it
+describes.
+→ `guardrails/domain/healthcare/auditing.domain.md`, `hipaa.md`
+
+### XX — Break-Glass is Time-Boxed and Loud
+*Extends IX (Security by Default).* Emergency access is a modelled, expiring grant that
+announces itself in the audit trail and triggers review — never an unlogged bypass and never a
+standing role.
+→ `guardrails/domain/healthcare/zero-trust.domain.md`, `authorization.domain.md`
+
+### XXI — Clinical Interoperability is FHIR-First
+*Extends XIV (Single Source of Truth).* FHIR resources are the published contract, generated
+from the domain model and versioned; HL7 v2 feeds are adapted at the boundary and never allowed
+to shape an aggregate.
+→ `guardrails/domain/healthcare/fhir.md`, `hl7.md`
+
+### XXII — Imaging Objects Stay DICOM-Governed
+*Extends XIV (Single Source of Truth).* Imaging metadata is read from and written back to DICOM
+as the authority; de-identification is an explicit, audited transformation, never a side effect
+of a projection.
+→ `guardrails/domain/healthcare/dicom.md`
+
+### XXIII — Clinical Meaning is Bound, Never Free Text (NON-NEGOTIABLE)
+*Extends III (Domain-Driven Design).* Coded clinical concepts bind to the governed value set as
+validated value objects; an unbound or unrecognised code is a rejected write, and a free-text
+field never stands in for a coded one.
+→ `guardrails/domain/healthcare/clinical-terms.md`, `terminology.md`
+
+### XXIV — Generation Refuses Where the Domain Requires a Human
+*Extends the AI operational rules.* An agent may not invent a clinical code, a consent
+semantic, a retention period or a de-identification rule; where the rule files are silent the
+generation stops and asks. Generated artifacts never contain real PHI.
+→ `guardrails/domain/healthcare/ai-rules.domain.md`
+
+## Domain Folder Additions
+
+Additions to the technology base's mandatory structure — Interop adapters per published surface,
+consent and audit control fixtures, and de-identified domain test data — are governed by
+`guardrails/domain/healthcare/folder-structure.domain.md`. Nothing here relaxes the base layout.
+
+## Governance Overrides
+
+- An amendment touching a NON-NEGOTIABLE principle above requires the Principal Engineer **and**
+  the Privacy Officer named for the project.
+- A change to a published interoperability surface, a consent semantic, a retention period or a
+  de-identification rule triggers privacy review before merge.
+- This half versions independently of `technology-constitution.md` and
+  `ui-constitution.md`; the base amendment procedure and SemVer policy apply unchanged.
+
+## Ratification Metadata
+
+> Carried into `constitution.domain.md` at ratification; the constitution command owns the
+> version bump from there.
+
+- **Version:** 1.0.0
+- **Ratified:** `<YYYY-MM-DD>`
+- **Last Amended:** `<YYYY-MM-DD>`

package/assets/guardrails/domain/healthcare/domain-driven-design.domain.md

@@ -0,0 +1,28 @@
+# Domain-Driven Design — Healthcare Domain Model
+
+> Technology base: [[domain-driven-design]]. NON-NEGOTIABLE. Commands: `/aw-spec-specify`.
+
+## Modeling
+- Use the clinical/interop ubiquitous language (see [[clinical-terms]], [[integration-terms]]).
+- FHIR-aligned, but **FHIR resources are projections, not the system of record** (see [[fhir]]).
+- Coded concepts use industry terminologies, never free text (see [[terminology]]); coded value objects follow the FHIR pattern (`Codeable`, `Coding`, `Quantity`, `Period`, `Range`, `Ratio`, `Identifier`, `HumanName`, `Address`, `ContactPoint`).
+- Domain may throw `ConsentDeniedException` beyond generic Domain exceptions (see [[consent]]).
+
+## Aggregates & invariants
+- **Patient** — MRN unique per tenant; DOB <= today; merge only via `MergePatientsCommand` preserving audit; minimum-necessary projection by role/scope.
+- **Consent** — withdrawal blocks downstream PHI disclosure for the purpose-of-use immediately; emits `ConsentChangedEvent` (see [[consent]]).
+- **Appointment** — no overlap with a booked slot for the same Practitioner/Resource; no past booking; late cancellation (< N hrs) emits `LateCancellationEvent`.
+- **Encounter** — not Closed/Discharged while any open Order/Result/ChargeItem/unsigned ClinicalNote exists; admission requires active Coverage or documented self-pay.
+- **ClinicalNote** — Signed = immutable; addendum is a new linked note; deletion forbidden (supersede via Amend).
+- **MedicationRequest** — dispense forbidden on active allergy match, lethal interaction, or pediatric/renal contraindication without a documented override (prescriber, reason, timestamp).
+- **ControlledSubstanceLedger** — every dispense/waste must balance; append-only; daily reconciliation.
+- **LabOrder/ImagingOrder** — not Cancellable once a Specimen/Image is acquired; transition to Aborted with a reason.
+- **Claim** — total billed = sum(ChargeItem.amount); resubmission needs a new ClaimVersion; none after final adjudication unless an Appeal is opened.
+- **InventoryItem** — stock <= 0 forbidden; dispensing an expired Lot rejected; near-expiry emits `ExpiryAlertEvent`.
+- **AuditRecord** — append-only; no update/delete; retention >= 6 years (see [[auditing.domain]]).
+
+## AI guidance
+See [[ai-rules.domain]] — confirm signatures, use the official FHIR SDK, never invent codes, mask PHI.
+
+## Related
+- [[domain-driven-design]] · [[fhir]] · [[terminology]] · [[consent]] · [[clinical-terms]] · [[integration-terms]] · [[auditing.domain]] · [[persistence.domain]] · [[ai-rules.domain]]

package/assets/guardrails/domain/healthcare/eventing.domain.md

@@ -0,0 +1,18 @@
+# Eventing — Healthcare Domain Addenda
+
+> Technology base: [[eventing]]. Commands: `/aw-spec-specify`, `/aw-spec-gate`.
+
+## Inbound feeds
+Each translated to internal commands via Interop adapters — never writing aggregates directly (see [[eventing]]):
+- HL7 v2 (ADT/ORM/ORU/SIU/MDM/DFT) — see [[hl7]]
+- External EHR FHIR pulls — see [[fhir]]
+- Lab / radiology result feeds; claim adjudication responses
+
+## Trace propagation
+- Trace context MUST propagate across **HL7v2 / DICOM / FHIR** outbound calls (beyond generic mediator/`HttpClient`/EF Core propagation).
+
+## Single source of truth
+- Authoritative system of record; consumers use FHIR / REST / CloudEvents / Bulk `$export` — **direct DB access FORBIDDEN** (see [[hipaa]]).
+
+## Related
+- [[eventing]] · [[hl7]] · [[fhir]] · [[dicom]] · [[hipaa]]

package/assets/guardrails/domain/healthcare/fhir.md

@@ -0,0 +1,36 @@
+# FHIR Standards
+
+> NON-NEGOTIABLE. Commands: `/aw-spec-constitution`, `/aw-spec-specify`.
+
+## Architecture
+- **R4 is the default external contract**; R5 is **additive** under `/fhir/R5/...`.
+- FHIR is the canonical interop contract; internal REST is for first-party apps. Both serve from the **same authoritative aggregates** — no duplicate write paths.
+
+## Projector rules (system of record)
+- **FHIR resources are PROJECTIONS over the aggregates — NOT the system of record.**
+- Mapping lives in `{Module}/Interop/Fhir/<Resource>Projector.cs`, hand-written + round-trip tested (`domain -> FHIR -> domain`; see [[testing]]).
+- A second FHIR write path bypassing the aggregate is FORBIDDEN; FHIR representations **MUST NOT** replace internal DTOs (see [[vertical-slices]]).
+
+## Resources & terminology
+- FHIR types come from the **official FHIR .NET SDK**, version-matched (R4/R5) to the endpoint.
+- Coded fields map from `Codeable`/`Coding` VOs to FHIR `CodeableConcept`/`Coding` (see [[terminology]]).
+
+## Profiles & CapabilityStatement
+- Honor **US Core** + project IGs; declare profiles/extensions/value-sets/search-params in `StructureDefinition` resources packaged with the service.
+- Publish `CapabilityStatement` at `/fhir/metadata` (regenerates cleanly in CI; diff reviewed); `/metadata` + `/.well-known` may be `AllowAnonymous()`.
+- Breaking changes require a **new version path** + published CapabilityStatement diff (see [[api-versioning.domain]]); FHIR validator passes for every modified resource/profile/example (CI gate).
+
+## Bundle / search / concurrency
+- List endpoints use **Bundle/searchset** semantics (`_count`, `_offset`/`_page`, `_total`).
+- Errors use `OperationOutcome` (HTTP 422 for validation).
+- `If-Match` honored via the aggregate's concurrency token → FHIR **weak** ETag at the projection boundary (see [[persistence]]).
+
+## SMART & Bulk Data
+- SMART app launch (EHR + standalone) MUST be supported — **PKCE mandatory; implicit flow forbidden**; scopes enforced on every endpoint (see [[authorization.domain]]).
+- **Bulk `$export`** supported for authorized backend extraction; de-identification required for analytics/research (see [[hipaa]]).
+
+## IHE
+- PIX/PDQ, XDS/XDS.b or MHD, ATNA, CT, BPPC followed where they apply; deviations in `guardrails/domain/healthcare/ihe-conformance.md` (see [[integration-terms]], [[auditing.domain]]).
+
+## Related
+- [[domain-driven-design.domain]] · [[terminology]] · [[hl7]] · [[dicom]] · [[consent]] · [[authorization.domain]] · [[api-versioning.domain]] · [[testing.domain]]

package/assets/guardrails/domain/healthcare/folder-structure.domain.md

@@ -0,0 +1,25 @@
+# Folder Structure — Healthcare Domain Addenda
+
+> Technology base: [[folder-structure]]. Commands: `/aw-spec-gate`. Replace `<SampleProjectName>`.
+
+## Additions to the base layout
+```
+src/<SampleProjectName>.Service/
+  Infrastructure/Security/      auth handlers, scope evaluators, PHI-access pipeline
+  Infrastructure/Auditing/      ATNA + FHIR AuditEvent emitter
+  <Module>/Domain/<ValueObject>.cs   coded VOs: Codeable, Coding, Quantity, HumanName, ...
+  <Module>/Interop/Fhir/        projectors, search-param handlers, IG profiles   (see [[fhir]])
+  <Module>/Interop/Hl7v2/       inbound parsers + outbound emitters              (see [[hl7]])
+  <Module>/Interop/Dicom/       DICOMweb adapters (Radiology only)               (see [[dicom]])
+tests/<SampleProjectName>.InteropTests/   FHIR-validator conformance             (see [[testing.domain]])
+tests/<SampleProjectName>.TestFixtures/   synthetic-PHI + terminology sentinels  (see [[testing.domain]])
+docs/interop/ihe-conformance.md · docs/interop/fhir-implementation-guide/
+docs/security/hipaa-controls.md · docs/security/gdpr-controls.md
+```
+- Paths above are **inside the project being built**, not inside the rule corpus — the `docs/` lines
+  are artefacts the project produces, and the corpus's own rule files never move there.
+- `Interop/` adapters translate to/from internal commands + projections (see [[vertical-slices.domain]]).
+- Coded value objects follow the FHIR pattern (see [[terminology]], [[coding-standards.domain]]).
+
+## Related
+- [[folder-structure]] · [[fhir]] · [[hl7]] · [[dicom]] · [[testing.domain]] · [[vertical-slices.domain]]

package/assets/guardrails/domain/healthcare/hipaa.md

@@ -0,0 +1,34 @@
+# HIPAA / PHI Protection Standards
+
+> NON-NEGOTIABLE. Commands: `/aw-spec-constitution`, `/aw-spec-specify`.
+
+## Regime
+PHI/ePHI under **HIPAA** (Privacy + Security + Breach Notification), **HITECH**, **21st Century Cures Act** anti-information-blocking, and **GDPR** where EU subjects apply, plus regional rules.
+
+## Minimum necessary
+- Every PHI read/write endpoint enforces **minimum-necessary** — return only fields the caller's role + SMART scopes authorize.
+- Field-level redaction lives in **projection extensions**, not controllers (see [[fhir]], [[authorization.domain]]).
+
+## Audit & consent
+- Every PHI read/mutation, authentication, consent change, export, and break-the-glass MUST emit an immutable audit record (see [[auditing.domain]]).
+- Consent is a first-class aggregate; the pipeline checks it before releasing PHI outside the treating-provider context (see [[consent]]).
+
+## Encryption
+- **AES-256 at rest** (TDE + CMK), **TLS 1.2+** in transit (1.3 target), encrypted backups.
+- App-level field encryption for SSN, government IDs, payment-card data, behavioral-health flags (see [[data-classification.domain]]).
+
+## De-identification
+- Exports to analytics/research/non-prod MUST pass a **Safe-Harbor OR Expert-Determination** service.
+- **Production PHI in dev/test/demo/CI is FORBIDDEN** — use synthetic-PHI fixtures (see [[testing.domain]]). De-identification without a documented method is a refusal condition (see [[ai-rules.domain]]).
+
+## Retention & rights
+- `AuditRecord` >= 6 yrs; clinical per jurisdiction (US >= 6 yrs adult, longer for minors); financial >= 7 yrs; backups under the same CMK (see [[persistence.domain]]).
+- Access, amendment, restriction, accounting-of-disclosures, erasure (GDPR Art. 17) are first-class commands with their own audit; where law forbids erasing medical records, **restriction-of-processing** is the fallback (see [[consent]]).
+
+## Breach, BAA, SSoT
+- Anomalous access (volume spikes, off-hours mass reads, repeated denials) emits **Critical** alerts.
+- Any outbound integration transmitting PHI is gated by a **BAA flag**; absence MUST refuse the integration at startup.
+- Authoritative system of record; consumers use FHIR / REST / CloudEvents / Bulk `$export` — **direct DB access FORBIDDEN** (see [[eventing]]).
+
+## Related
+- [[auditing.domain]] · [[consent]] · [[data-classification.domain]] · [[authorization.domain]] · [[zero-trust.domain]] · [[persistence.domain]] · [[testing.domain]] · [[ai-rules.domain]]

package/assets/guardrails/domain/healthcare/hl7.md

@@ -0,0 +1,15 @@
+# HL7 v2 Standards
+
+> Commands: `/aw-spec-constitution`, `/aw-spec-specify`.
+
+## Adapters (not a parallel model)
+- HL7 v2.x (**ADT, ORM, ORU, SIU, MDM, DFT**) MUST be supported via an **ingress adapter** → internal commands; an **egress adapter** converts domain events → outbound messages.
+- Adapters live in `{Module}/Interop/Hl7v2/`; translate via `IMediator` — **MUST NOT** write aggregates directly (see [[eventing]], [[domain-driven-design]]). Bypassing them from an external feed is an AI refusal condition (see [[ai-rules.domain]]).
+- Conformance tested against an **internal corpus** (see [[testing]]).
+
+## MLLP
+- The HL7v2 broker (MLLP) is an Aspire resource referenced via `.WithReference(...)`; hosts/ports discovered through Aspire, never hard-coded.
+- Ingest target: **50 messages/sec per channel**; trace context propagates across HL7v2 outbound calls (see [[auditing]]).
+
+## Related
+- [[fhir]] · [[eventing]] · [[integration-terms]] · [[domain-driven-design]] · [[testing]]

package/assets/guardrails/domain/healthcare/ihe-conformance.md

@@ -0,0 +1,31 @@
+# IHE Conformance Notes — Patients / RegisterPatient
+
+Tracks IHE-profile conformance and deliberate scope decisions for the RegisterPatient feature.
+
+## PIX / PDQ (Patient Identifier Cross-referencing / Patient Demographics Query)
+
+- **In scope (delivered):** populate-and-link. Each registered patient carries a system-assigned
+  tenant MRN plus retained external identifiers (HL7 v2 PID-3) with their assigning authorities, so
+  the patient is cross-referenceable. `ResolvePatientIdentifiersQuery` resolves a patient's full
+  identifier set from any one known identifier (`Patients/Interop/Pix/`).
+- **Deferred (follow-up feature):** standing up full **PIX Manager** / **PDQ Supplier** query-responder
+  endpoints, and outbound notification to an external/central MPI. Decision recorded per
+  `/aw-spec-clarify` Q3 and `research.md` R8.
+
+## ATNA (Audit Trail and Node Authentication)
+
+- Every PHI command/query emits a PHI-free, ATNA-shaped access record via the
+  `PhiAccessAuditBehavior` mediator behavior; entity writes are additionally captured by the
+  framework's advanced auditing. Node authentication (mTLS between nodes) is a deployment concern.
+
+## HL7 v2 ADT
+
+- Inbound ADT^A04 over MLLP with accept/receipt ACK; outbound ADT^A04 on `PatientRegisteredEvent`.
+  Conformance tested against an internal corpus (`AppWeaver.Health.TestFixtures`).
+
+## Known follow-ups
+
+- **Tenant-scoped MRN uniqueness:** the generated migration currently creates a *global* unique index
+  `UX_Patients_Mrn`. Confirm the framework tenancy discriminator column and change to a composite
+  unique index `(TenantId, Mrn)` so the "same MRN in a different tenant" edge case is permitted.
+- **FHIR CapabilityStatement / StructureDefinition** packaging and validator CI gate (HG1/HG2).

package/assets/guardrails/domain/healthcare/integration-terms.md

@@ -0,0 +1,21 @@
+# Glossary — Integration Terms
+
+> Ubiquitous language for interoperability standards + IHE profiles. Commands: `/aw-spec-specify`.
+
+| Term | Definition |
+|---|---|
+| **HL7** | **HL7 v2.x** = legacy pipe-delimited messaging (ADT/ORM/ORU/SIU/MDM/DFT) via adapters (see [[hl7]]); **HL7 FHIR** = the resource-based standard (see [[fhir]]). |
+| **FHIR** | Canonical external contract (R4 default, R5 additive); resources are projections over aggregates (see [[fhir]]). |
+| **DICOM** | Imaging standard via DICOMweb (QIDO/WADO/STOW-RS); only metadata persisted here (see [[dicom]]). |
+| **PIX / PDQ** | Patient Identifier Cross-referencing / Demographics Query (IHE) — used by Patients. |
+| **ATNA** | Audit Trail + Node Authentication (IHE); audit records exportable as FHIR `AuditEvent` (see [[auditing.domain]]). |
+| **MHD / XDS / XDS.b** | Document-sharing profiles (IHE); MHD is the FHIR-based lightweight alternative to XDS. |
+| **CT** | Consistent Time (IHE) — synchronized clocks across nodes. |
+| **BPPC** | Basic Patient Privacy Consents (IHE consent profile; see [[consent]]). |
+| **SMART on FHIR** | OAuth2/OIDC app-launch for third-party apps; PKCE mandatory (see [[authorization.domain]]). |
+| **Bulk Data / `$export`** | FHIR Bulk Data spec for population-level extraction; de-identified for analytics (see [[hipaa]]). |
+| **CloudEvents** | CNCF durable async event-stream spec over the broker (see [[eventing]]). |
+| **OpenAPI / CapabilityStatement / AsyncAPI** | Versioned machine-readable contracts for REST / FHIR / events (see [[api-versioning]]). |
+
+## Related
+- [[clinical-terms]] · [[fhir]] · [[hl7]] · [[dicom]] · [[eventing.domain]] · [[auditing.domain]] · [[authorization.domain]] · [[api-versioning.domain]]

package/assets/guardrails/domain/healthcare/persistence.domain.md

@@ -0,0 +1,20 @@
+# Persistence — Healthcare Domain Addenda
+
+> Technology base: [[persistence]]. Commands: `/aw-spec-specify`, `/aw-spec-gate`.
+
+## Soft delete & retention
+- Hard delete FORBIDDEN for any aggregate holding **clinical/financial/PHI** data — delete logically via `MarkAsDeleted(...)`. All aggregates are soft-deleted (no exemptions).
+- `AuditRecord` is **append-only** — no delete (see [[auditing.domain]]).
+- Retention: `AuditRecord` >= 6 years; clinical per jurisdiction (US >= 6 yrs adult, longer for minors); financial >= 7 years; backups under the same CMK.
+- GDPR Art. 17 erasure → **restriction-of-processing** where law forbids erasing medical records (see [[consent]], [[hipaa]]).
+
+## Encryption
+- Production PostgreSQL: **TDE with customer-managed keys (CMK)**.
+- App-level field encryption for SSN, government IDs, payment-card data, behavioral-health flags (see [[data-classification.domain]], [[hipaa]]).
+
+## Tenancy & dev data
+- Multi-hospital deployments MAY opt into tenant-per-database; default tenant-per-row.
+- SQLite dev fixtures contain **no PHI** — production PHI in dev/test/CI is FORBIDDEN (see [[hipaa]]).
+
+## Related
+- [[persistence]] · [[hipaa]] · [[auditing.domain]] · [[data-classification.domain]] · [[consent]]

package/assets/guardrails/domain/healthcare/terminology.md

@@ -0,0 +1,30 @@
+# Terminology Standards
+
+> NON-NEGOTIABLE. Commands: `/aw-spec-constitution`, `/aw-spec-specify`.
+
+## Coded value objects
+- **Coded data MUST use industry terminologies — free-text strings for coded concepts are FORBIDDEN.**
+- Every code-bearing field is a **`Codeable` value object** `{ system, code, version, display }` (mirrors FHIR `CodeableConcept`/`Coding`) — store code, code-system OID/URI, version, display.
+
+## Standard terminologies
+| Domain | Terminology |
+|---|---|
+| Diagnoses | ICD-10-CM (US) / ICD-10 (WHO); ICD-11 where required |
+| Procedures (billing / clinical / inpatient) | CPT, HCPCS Level II / SNOMED CT / ICD-10-PCS |
+| Lab observations / document types | LOINC |
+| Clinical concepts (problems, findings, body sites, allergies) | SNOMED CT |
+| Medications | RxNorm (US); NDC (dispense identity); ATC (analytics) |
+| Units of measure | UCUM |
+| Vaccines | CVX (CDC); MVX (manufacturers) |
+
+## Validation
+- Hard-coded coded literals FORBIDDEN outside the Terminology module's seed data.
+- Never invent ICD/SNOMED/LOINC/CPT/HCPCS/RxNorm/CVX codes — confirm against the module's value sets (see [[ai-rules.domain]]).
+- Free-text storage where a coded vocabulary applies is a Forbidden Pattern.
+
+## Terminology module
+- Lookup/validation/expansion **MUST** go through a dedicated **Terminology module** (internal cache or external TS via FHIR `$expand` / `$validate-code`).
+- Aggregates: `CodeSystem`, `ValueSet`, `ConceptMap` (project-managed subsets; expansions cached).
+
+## Related
+- [[fhir]] · [[domain-driven-design.domain]] · [[clinical-terms]] · [[testing.domain]] · [[ai-rules.domain]]

package/assets/guardrails/domain/healthcare/testing.domain.md

@@ -0,0 +1,15 @@
+# Testing — Healthcare Domain Addenda
+
+> Technology base: [[testing]]. Commands: `/aw-spec-gate`.
+
+## FHIR & interop tests
+- FHIR endpoints MUST validate against the official **FHIR validator** + project IGs; profile changes ship with test updates in the **same commit** (see [[fhir]]).
+- FHIR projectors MUST have a round-trip test (`domain -> FHIR -> domain`).
+- Contract tests: FHIR validator + Inferno (or equiv) for US Core/the IG; HL7 v2 conformance against an internal corpus (see [[hl7]]); CloudEvents schema validation by every consumer harness (see [[eventing.domain]]).
+
+## Test data
+- MUST use the synthetic-PHI fixture library (`<SampleProjectName>.TestFixtures`); **production PHI in dev/test/demo/CI is FORBIDDEN** (see [[hipaa]]).
+- Coded values use sentinel constants (e.g. `TerminologyFixtures.IcdSampleHypertension`) — never invented ICD/SNOMED/LOINC/CPT codes (see [[terminology]], [[ai-rules.domain]]).
+
+## Related
+- [[testing]] · [[fhir]] · [[hl7]] · [[terminology]] · [[hipaa]] · [[ai-rules.domain]]

package/assets/guardrails/domain/healthcare/ux/accessibility-standards.md

@@ -0,0 +1,36 @@
+# UX Rule — Accessibility Standards (healthcare)
+
+> Loaded under `## /aw-spec-specify` in a project's `tech-rule-bindings.md`. A methodology
+> rule: it governs how the conformance obligation is stated in the spec so that `ui-design`
+> and the UI code gate can verify it.
+
+## Why this is a spec concern at all
+
+`ui-design` and `ui-implement` author from the **spec**, never from the rule corpus. An
+accessibility obligation that lives only here reaches no UI phase and is gated by nothing. The
+lift into a `UX-n` is what makes it binding.
+
+## Rules
+
+1. **Name the target, the level, and the surface it covers.** "Meets WCAG 2.2 Level AA on
+   every user-facing surface" is checkable. "Is accessible" is not, and fails the gate as an
+   unverifiable standard.
+2. **State the assistive-technology floor in Experience Scope**, not in the standard. The
+   standard says conformance; the scope says which readers and input modes define it. The two
+   are separated so a floor change does not rewrite the standard.
+3. **Keyboard operability is stated against the User Stories.** The obligation is that every
+   task the spec lists as a `US-n` is completable keyboard-only. That binds the standard to
+   this aggregate's actual work rather than to a generic surface.
+4. **Clinical-safety accessibility is not decoration.** In this domain, colour is never the sole
+   carrier of a status that affects a clinical decision, alerts are announced to assistive
+   technology, and a dismissible warning is re-reachable. State these as `UX-n` standards.
+5. **A waiver is an id, a reason and an expiry.** An accessibility exception is recorded against
+   the `UX-n` id it relaxes, time-boxed, and expires. An unrecorded exception is a defect.
+6. **Regulatory accessibility obligations lift as themselves.** Where a jurisdiction imposes a
+   conformance regime on patient-facing software, that obligation is a `UX-n` citing the regime.
+   Where the same regime also imposes a records or retention duty, that half stays a `CN-n`.
+
+## What must NOT appear
+
+ARIA attributes, roles, landmark structure, tab order, contrast values for a specific palette,
+component libraries, or linter configuration. Those are how the standard is met.

package/assets/guardrails/domain/healthcare/ux/content-design.md

@@ -0,0 +1,32 @@
+# UX Rule — Content Design (healthcare)
+
+> Loaded under `## /aw-spec-specify` in a project's `tech-rule-bindings.md`. A methodology
+> rule: it governs the language obligations the spec carries into the UI lane.
+
+## Rules
+
+1. **The UI speaks the ubiquitous language.** User-facing terms are the terms in Key Entities.
+   Where the interface must show a term the domain does not use, the spec says which term and
+   why; an unmapped synonym invented in a component is a defect against the domain model.
+2. **Every error names what happened and what to do next.** State this once as a `UX-n`. A
+   message that reports a failure without an action is not a message, it is a dead end — see
+   `interaction-states.md`.
+3. **Regulated wording is reproduced verbatim.** Consent text, safety warnings, and any wording
+   a regulator or a labelling authority fixes are quoted exactly and never paraphrased,
+   truncated or localised without the approved translation. Lift the obligation as a `UX-n` and
+   the retention or audit duty attached to it as a `CN-n`.
+4. **Clinical values carry their units and their provenance.** A displayed measurement without
+   its unit is unsafe; a value drawn from an external feed is attributable. State the obligation
+   here, state the classification of the field itself in `DC-n`.
+5. **Identity display is a classification decision, not a wording one.** What may appear on a
+   surface — and what must not appear in logs, metrics or traces — is `DC-n`. This section
+   governs only how the permitted content reads.
+6. **Localisation is structural where it applies.** Where the product ships more than one
+   locale, state as a `UX-n` that user-visible strings come from a catalogue and that dates,
+   numbers and units format locale-aware at the boundary. Where it ships one, say so in
+   Experience Scope and omit the standard.
+
+## What must NOT appear
+
+Final copy, message strings, tone-of-voice guides, or per-screen wording. The spec states the
+obligation the wording must satisfy; the prototype and the design system settle the words.

package/assets/guardrails/domain/healthcare/ux/interaction-states.md

@@ -0,0 +1,44 @@
+# UX Rule — Interaction States (healthcare)
+
+> Loaded under `## /aw-spec-specify` in a project's `tech-rule-bindings.md`. A methodology
+> rule: it governs how the spec expresses what the user meets while the system works, never
+> how any of it is rendered.
+
+## The split this rule exists to hold
+
+Two things look alike and belong in different sections:
+
+| Statement | Home | Why |
+|---|---|---|
+| "Every asynchronous operation presents its loading, empty, partial-failure, recovery and success states" | **`UX-n`** | project-wide standard, true of every surface |
+| "IF the allergy list cannot be retrieved THEN THE SYSTEM SHALL present the last known list marked stale and offer retry" | **`FR-n`** | this aggregate's behaviour, in EARS |
+
+The standard is lifted once. The behaviour is specified per aggregate, in EARS, using the
+unwanted-behaviour patterns the spec template already defines.
+
+## Rules
+
+1. **Enumerate the states, do not draw them.** The states are loading, empty, partial,
+   failure, recovery, success and — where the domain requires it — stale and degraded. The
+   spec says which must be handled; the prototype says what they look like.
+2. **No dead end.** A `UX-n` states that no reachable state leaves the user without a next
+   action. A state the UI can reach and the spec does not describe is a spec defect routed
+   back to `specify`, never invented in a component.
+3. **Partial failure is stated, not implied.** Where a surface composes several sources, the
+   spec states whether a partial result is presentable and how it is marked. In this domain the
+   default is that partial clinical data is presentable ONLY when its incompleteness is
+   explicit; silence here is a defect, not a default.
+4. **Staleness is a clinical fact.** Where cached or last-known data may be shown, say so as an
+   `FR-n` and carry the project-wide marking obligation as a `UX-n`. Data whose currency
+   affects a clinical decision is never presented as current when it is not.
+5. **Destructive and irreversible actions state their confirmation obligation** as a `UX-n`,
+   and their specific consequence as an `FR-n` or `BR-n`.
+6. **Responsiveness is a bound, not a behaviour.** Acknowledgement and progress thresholds are
+   `UX-n` limits. Where the bound depends on a server-side budget, that budget stays a `CN-n`
+   and the two cross-reference — the service-side gates read `CN-` and never read the
+   Experience Standards.
+
+## What must NOT appear
+
+Spinners, skeletons, toasts, banners, placement, animation, timing curves, or any component
+name. Those realise the state; they are not the state.

package/assets/guardrails/domain/healthcare/ux/journey-mapping.md

@@ -0,0 +1,40 @@
+# UX Rule — Journey Mapping (healthcare)
+
+> Loaded under `## /aw-spec-specify` in a project's `tech-rule-bindings.md`. It is a
+> **methodology** rule: it governs how `specify` expresses the experience in the spec, not
+> what any screen looks like. Tier is set by the map that lists it, not by the folder it
+> sits in — this file lives in the domain corpus and is loaded as a technical input.
+
+## What this rule governs
+
+The spec states the user's **path through a task** as a `US-n` user story and the standards
+that path must hold to as `UX-n` entries. It never states the route the user takes through a
+UI. One story may become one screen or five; that is the prototype's and `design.ui.md`'s
+decision, and a spec that pre-empts it has specified the solution.
+
+## Rules
+
+1. **A journey is a `US-n`, not a new id class.** A user story is already defined as a
+   prioritized, independently testable journey. An experience journey uses that definition
+   unchanged — the actor, the goal, the acceptance criteria in Given/When/Then.
+2. **State the outcome, never the mechanism.** "A clinician can reconcile a medication list
+   for one patient in a single sitting" is a journey. "A clinician opens the reconciliation
+   tab, clicks Compare, then Accept All" is a click-path and belongs in the prototype.
+3. **Every journey names the actor from Experience Scope.** A story whose actor is not listed
+   there is either an unlisted actor or a story that does not belong to this aggregate.
+4. **Interruption is a first-class case in this domain.** Clinical work is interrupted; a
+   journey that cannot survive being abandoned mid-task and resumed is under-specified. Where
+   resumability is required, state it as an acceptance criterion on the `US-n`, and state the
+   project-wide expectation once as a `UX-n`.
+5. **Journey integrity is a `UX-n` standard.** Completability without leaving the aggregate's
+   surface, confirmation and reversibility of destructive actions, and preservation of entered
+   work across a failure are standards that hold for every journey — lift them once, do not
+   repeat them per story.
+6. **Hand-offs between actors are journeys too.** Where a task passes from one role to another
+   (order → verification → administration), the hand-off is part of the journey and its state
+   at the boundary is stated in the acceptance criteria.
+
+## What must NOT appear
+
+Screens, pages, tabs, wizards, step counts, navigation structure, button labels, modal-vs-inline
+choices, or any statement whose only realisation is one layout.

package/assets/guardrails/domain/healthcare/vertical-slices.domain.md

@@ -0,0 +1,18 @@
+# Vertical Slices — Healthcare Domain Addenda
+
+> Technology base: [[vertical-slices]]. Commands: `/aw-spec-specify`, `/aw-spec-gate`.
+
+## Interop adapters in the slice
+`{Module}/Interop/` carries the external-protocol adapters:
+```
+Fhir/    projectors, search-param handlers, IG profiles   (see [[fhir]])
+Hl7v2/   inbound parsers + outbound emitters              (see [[hl7]])
+Dicom/   DICOMweb adapters (Radiology only)               (see [[dicom]])
+```
+
+## Rules
+- FHIR resources live in a **parallel projection layer** and **MUST NOT** replace internal `Shared` DTOs (see [[fhir]]).
+- Domain DTOs (`PatientDto`, `EncounterDto`) — no setters, required `init`, base64 `RowVersionBase64`.
+
+## Related
+- [[vertical-slices]] · [[fhir]] · [[hl7]] · [[dicom]]

package/assets/guardrails/domain/healthcare/zero-trust.domain.md

@@ -0,0 +1,12 @@
+# Zero-Trust — Healthcare Domain Addenda
+
+> Technology base: [[zero-trust]]. Commands: `/aw-spec-constitution`, `/aw-spec-specify`, `/aw-spec-gate`.
+
+## Rules
+- **PHI in transit MUST be TLS-encrypted**; at-rest encryption: see [[hipaa]], [[data-classification.domain]].
+- External IdP MUST be SMART-on-FHIR-capable; tokens/scopes enforced on every FHIR endpoint and propagated through the pipeline (see [[authorization.domain]], [[fhir]]).
+- IHE **ATNA** node authentication applies to inter-node communication (see [[auditing.domain]]).
+- Trace context MUST propagate across outbound **HL7v2 / DICOM / FHIR** calls (see [[eventing.domain]]).
+
+## Related
+- [[zero-trust]] · [[authorization.domain]] · [[auditing.domain]] · [[hipaa]] · [[fhir]]

package/assets/guardrails/domain/pharma/ai-rules.domain.md

@@ -0,0 +1,32 @@
+# AI Operational Rules — Pharma Domain Addenda
+
+> Technology base: [[ai-rules]]. Commands: **ALL**.
+
+## Context & codes
+- FHIR types: use the **official FHIR .NET SDK**, version-matched (R4/R5) to the endpoint (see [[fhir]]).
+- Confirm coded values against the Terminology module's value sets; never invent NDC/UNII/RxNorm/SNOMED/ATC/UCUM codes (see [[terminology]], [[ndc]], [[atc]]).
+- Align aggregates to ISO IDMP concept boundaries, not ad-hoc shapes (see [[idmp]]).
+
+## Generation
+- `MedicinalProduct` is the Aggregate Root. Generate `NdcCode`/`ProductName`/`GenericName`/`Strength`/`DosageForm`/`RouteOfAdministration`/`AtcCode`/`MarketingStatus`/`PackageIdentifier` as **value objects**, and `ActiveIngredient`/`PackagingConfiguration`/`MarketingAuthorization` as **entities** (see [[domain-driven-design.domain]]).
+- A complete slice adds (when applicable): FHIR projector + FHIR-validator test, audit emission, version snapshot (see [[fhir]], [[auditing.domain]], [[persistence.domain]], [[testing.domain]]).
+- FHIR resources are projections — never a second FHIR write path bypassing the aggregate (see [[fhir]]).
+- Comments are reserved for regulatory/domain intent (generic rule in [[ai-rules]]).
+
+## Identifier & code safety
+- MUST NOT fabricate NDC values or Labeler Codes; MUST NOT invent ATC/UNII/RxNorm/SNOMED codes — use a sentinel constant (e.g. `TerminologyFixtures.AtcSample`) or the Terminology module (see [[testing.domain]], [[terminology]], [[ndc]], [[atc]]).
+- MUST attach a `ProvenanceRecord` on any external-import path (see [[data-provenance]]).
+
+## Security- & compliance-touching code
+- MUST NOT modify audit emitters, version-history writers, lifecycle-transition guards, or identifier-uniqueness checks without an explicit reviewer-attached prompt (see [[auditing.domain]], [[persistence.domain]], [[product-lifecycle.domain]], [[ndc]]).
+
+## Refusal conditions — extend [[ai-rules]]; refuse to:
+- Invent or hard-code NDC/ATC/UNII/RxNorm/SNOMED codes outside terminology seed data (see [[terminology]]).
+- Persist a product with an invalid NDC, invalid dosage form, invalid route, or unvalidated ATC code (see [[ndc]], [[terminology]], [[atc]]).
+- Hard-delete a `MedicinalProduct`, its history, or an `AuditRecord` (use lifecycle retirement / logical delete) (see [[persistence.domain]], [[auditing.domain]]).
+- Allow an invalid lifecycle transition or remove a transition guard (see [[product-lifecycle.domain]]).
+- Bypass Interop adapters by writing aggregates directly from an external feed (see [[hl7]], [[eventing.domain]]).
+- Suppress or weaken audit emission for create/modify/retire/identifier/classification changes (see [[auditing.domain]], [[regulatory-compliance]]).
+
+## Related
+- [[ai-rules]] · [[domain-driven-design.domain]] · [[ndc]] · [[idmp]] · [[atc]] · [[terminology]] · [[fhir]] · [[auditing.domain]] · [[persistence.domain]] · [[product-lifecycle.domain]] · [[data-provenance]] · [[testing.domain]]