aw-spec-cli 0.1.0 → 0.1.2

package/assets/docs/domainspecs/healthcare/domain-requirements.md

@@ -0,0 +1,55 @@
+# DOMAIN REQUIREMENTS (project-specific)
+
+> Project-specific input, **updated independently per project**. The engineering constitution
+> (the technology base composed with `healthcare-constitution.md`) references this file; the
+> constitution stays domain-agnostic and supreme. Detailed domain *rules* are expanded in
+> `docs/` — this file holds the
+> per-project enumeration and headline profiles.
+>
+> Replace `<SampleProjectName>` and the bounded-context list below for a new project.
+
+=====================================================================
+[DOMAIN: Bounded Contexts / Modules]
+=====================================================================
+- Patients — aggregates: Patient (master patient index), Consent, RelatedPerson; cross-references via PIX/PDQ.
+- Appointments — aggregates: Appointment, Slot, Schedule, Waitlist.
+- Encounters — aggregates: Encounter (inpatient, outpatient, emergency), Admission, Transfer, Discharge.
+- EMR — aggregates: ClinicalNote, ProblemList, AllergyIntolerance, MedicationStatement, Observation (vitals, social history), Immunization, CarePlan, ServiceRequest, Procedure.
+- Radiology — aggregates: ImagingOrder, ImagingStudy (DICOM metadata), DiagnosticReport (radiology); pixel data lives in PACS/VNA.
+- Lab — aggregates: LabOrder, Specimen, Observation (lab result), DiagnosticReport (lab).
+- Pharmacy — aggregates: MedicationRequest, MedicationDispense, MedicationAdministration, Formulary, ControlledSubstanceLedger.
+- Billing — aggregates: ChargeItem, Invoice, Claim, ClaimResponse, PaymentReconciliation, Account, AdjustmentEntry.
+- Insurance — aggregates: Coverage, Payer, Plan, EligibilityRequest, EligibilityResponse, PriorAuth.
+- Inventory — aggregates: InventoryItem, Lot, StockMovement, Reservation, ExpiryAlert.
+- Interoperability — aggregates: IntegrationEndpoint, MessageEnvelope (HL7v2), FhirSubscription, BulkExportJob.
+- PatientPortal — aggregates: PortalAccount (identity-bound), MessageThread, AppointmentRequest, RecordAccessRequest.
+- Identity — aggregates: Practitioner, PractitionerRole, Organization, Location, HealthcareService.
+- Auditing — aggregates: AuditRecord (append-only, ATNA + FHIR AuditEvent shape).
+- Terminology — aggregates: CodeSystem, ValueSet, ConceptMap (project-managed subsets; expansions cached from external TS).
+
+=====================================================================
+[DOMAIN: subsection pointers]
+=====================================================================
+[DOMAIN: Aggregates and Business Invariants]  -> docs/domainspecs/healthcare/domain-driven-design.domain.md
+[DOMAIN: Persistence Profile]                 -> docs/domainspecs/healthcare/persistence.domain.md
+[DOMAIN: Security Profile]                     -> docs/domainspecs/healthcare/authorization.domain.md, docs/domainspecs/healthcare/data-classification.domain.md
+[DOMAIN: Testing Profile]                      -> docs/domainspecs/healthcare/testing.domain.md
+[DOMAIN: AI Policy Addenda]                    -> docs/domainspecs/healthcare/ai-rules.domain.md
+[DOMAIN: Platform Topology]                    -> below
+
+=====================================================================
+[DOMAIN: Platform Topology]
+=====================================================================
+- Target runtime: Kubernetes (AKS, EKS, or on-prem). Single-region by default; multi-region active/passive for DR.
+- External dependencies (Aspire resources): PostgreSQL (primary), Redis (cache + portal session), a message broker (Azure Service Bus, AWS SQS/SNS, or RabbitMQ) for CloudEvents, an OTel collector, the configured IdP, an external Terminology Service (optional), a FHIR validator container, a PACS/VNA endpoint (DICOMweb), an HL7v2 broker (MLLP), an SMTP/SMS gateway, an object store (S3/Blob) for binaries.
+- Scale targets: P95 read latency < 200 ms at 200 RPS per module; FHIR search P95 < 500 ms; HL7v2 ingest sustains 50 messages/sec per channel.
+- Disaster recovery: RPO <= 15 minutes, RTO <= 4 hours; daily encrypted backups with 35-day retention plus monthly archive >= 7 years.
+
+=====================================================================
+[DOMAIN: Governance Overrides]
+=====================================================================
+- Principal Engineers (approvers): TBD — fill at ratification.
+- Security/Compliance Officer (mandatory approver for any PHI/security change): TBD.
+- Domain Owners (per module): TBD — assign one clinical and one technical owner per bounded context.
+- Quarterly review cadence: first business week of each quarter; security review additionally after every significant regulatory update.
+- Exception process: a time-boxed waiver via a Waiver Request issue, approved by a Principal Engineer + the Compliance Officer, with a mandatory expiry <= 90 days and a remediation plan recorded in the issue.

package/assets/docs/domainspecs/healthcare/eventing.domain.md

@@ -0,0 +1,18 @@
+# Eventing — Healthcare Domain Addenda
+
+> Technology base: [[eventing]]. Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## 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/docs/domainspecs/healthcare/fhir.md

@@ -0,0 +1,36 @@
+# FHIR Standards
+
+> NON-NEGOTIABLE. Commands: `/aw-spec-specify`, `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## 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 `docs/interop/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/docs/domainspecs/healthcare/folder-structure.domain.md

@@ -0,0 +1,23 @@
+# Folder Structure — Healthcare Domain Addenda
+
+> Technology base: [[folder-structure]]. Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`. 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
+```
+- `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/docs/domainspecs/healthcare/hipaa.md

@@ -0,0 +1,34 @@
+# HIPAA / PHI Protection Standards
+
+> NON-NEGOTIABLE. Commands: `/aw-spec-specify`, `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## 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/docs/domainspecs/healthcare/hl7.md

@@ -0,0 +1,15 @@
+# HL7 v2 Standards
+
+> Commands: `/aw-spec-specify`, `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## 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/docs/domainspecs/healthcare/integration-terms.md

@@ -0,0 +1,21 @@
+# Glossary — Integration Terms
+
+> Ubiquitous language for interoperability standards + IHE profiles. Commands: `/aw-spec-specify`, `/aw-spec-clarify`, `/aw-spec-plan`.
+
+| 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/docs/domainspecs/healthcare/persistence.domain.md

@@ -0,0 +1,20 @@
+# Persistence — Healthcare Domain Addenda
+
+> Technology base: [[persistence]]. Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## 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/docs/domainspecs/healthcare/terminology.md

@@ -0,0 +1,30 @@
+# Terminology Standards
+
+> NON-NEGOTIABLE. Commands: `/aw-spec-specify`, `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## 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/docs/domainspecs/healthcare/testing.domain.md

@@ -0,0 +1,15 @@
+# Testing — Healthcare Domain Addenda
+
+> Technology base: [[testing]]. Commands: `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## 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/docs/domainspecs/healthcare/vertical-slices.domain.md

@@ -0,0 +1,18 @@
+# Vertical Slices — Healthcare Domain Addenda
+
+> Technology base: [[vertical-slices]]. Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## 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/docs/domainspecs/healthcare/zero-trust.domain.md

@@ -0,0 +1,12 @@
+# Zero-Trust — Healthcare Domain Addenda
+
+> Technology base: [[zero-trust]]. Commands: `/aw-spec-plan`, `/aw-spec-implement`.
+
+## 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/docs/domainspecs/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]]

package/assets/docs/domainspecs/pharma/api-versioning.domain.md

@@ -0,0 +1,20 @@
+# API Versioning — Pharma Domain Addenda (FHIR)
+
+> Technology base: [[api-versioning]]. Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## FHIR versioning
+- R4 default; R5 **additive** under a versioned path (`/fhir/R5/...`).
+- Breaking changes to the Medication / MedicationKnowledge / Substance / Organization surface require a **new version path** + a published CapabilityStatement diff (see [[fhir]]).
+- FHIR list endpoints use Bundle/searchset semantics (`_count`, `_offset`/`_page`, `_total`).
+
+## NDC identifier stability
+- `NdcCode` is a **stable identifier** — never silently rewritten. A correction is an explicit, audited identifier-change emitting `ProductIdentifierChanged`, preserved in version history (see [[ndc]], [[auditing.domain]], [[persistence.domain]], [[eventing.domain]]). ATC reclassification is likewise a versioned, audited event (see [[atc]]).
+
+## Concurrency at the edge
+- FHIR resources honor `If-Match` via the aggregate's concurrency token → FHIR **weak** ETag at the projection boundary (see [[persistence.domain]]).
+
+## CapabilityStatement
+- Published for FHIR (beyond generic OpenAPI); regenerates cleanly in CI; diff reviewed for breaking changes (see [[fhir]], [[coding-standards.domain]]).
+
+## Related
+- [[api-versioning]] · [[fhir]] · [[ndc]] · [[atc]] · [[persistence.domain]] · [[eventing.domain]] · [[auditing.domain]] · [[coding-standards.domain]]

package/assets/docs/domainspecs/pharma/atc.md

@@ -0,0 +1,22 @@
+# ATC — WHO Anatomical Therapeutic Chemical Classification
+
+> NON-NEGOTIABLE. Commands: `/aw-spec-specify`, `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## Value Object
+- ATC is the **`AtcCode` value object** — immutable, equality by value (see [[domain-driven-design.domain]]); carries code, ATC system URI, **ATC edition/version** (WHO updates annually), display.
+- Free-text storage of a therapeutic class is a Forbidden Pattern.
+
+## Multiplicity
+- **Multiple ATC codes MAY attach to one `MedicinalProduct`** (a collection of `AtcCode` VOs).
+- The 7-character hierarchy (anatomical → therapeutic → pharmacological → chemical subgroup → substance) SHALL be representable; level is derivable from code length.
+
+## Validation
+- **ATC codes SHALL be validated against configured code sets** — the bound edition is value-set data via the Terminology module (see [[terminology]]).
+- An ATC code absent from the configured set is rejected; the Domain MUST NOT persist an unvalidated ATC code; never invent ATC codes (see [[ai-rules.domain]]).
+- Changing a product's ATC is a **classification change** — audit-mandatory (see [[auditing.domain]]).
+
+## FHIR mapping
+- ATC → FHIR `Medication.code` / `MedicationKnowledge` classification codings (`CodeableConcept`, ATC system URI) (see [[fhir]]).
+
+## Related
+- [[terminology]] · [[domain-driven-design.domain]] · [[fhir]] · [[auditing.domain]] · [[ai-rules.domain]]

package/assets/docs/domainspecs/pharma/auditing.domain.md

@@ -0,0 +1,26 @@
+# Auditing — Pharma Domain Addenda
+
+> Technology base: [[auditing]]. NON-NEGOTIABLE. Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## Setup
+- Auditing is **MANDATORY** for `MedicinalProduct` and its entities (ActiveIngredient, PackagingConfiguration, MarketingAuthorization).
+- Enable via `.EnableAdvancedAuditing()` + `AddAuditing(... UseEfCoreAuditing(...).UseAppWeaverDataStore())`.
+- Audit tables: shared `AppWeaver.DataStore`, schema `Auditing`, prefix `Audit_`.
+- An audit pipeline behavior runs on every mediator request (see [[cqrs.domain]], [[eventing.domain]]).
+
+## Audit-mandatory operations
+Product **creation**, **modification**, **retirement** (Discontinued/Withdrawn), **identifier changes** (NDC/Package NDC), **classification changes** (ATC) — plus every lifecycle transition and authorized admin action (see [[product-lifecycle.domain]], [[ndc]], [[atc]]).
+
+## Record (immutable)
+```
+{ user, timestamp, action, resourceType, resourceId, previousValue, newValue, correlationId }
+```
+**User, Timestamp, Action, Previous Value, New Value** are spec-required and MUST always be populated.
+
+## Immutability & retention
+- `AuditRecord` is **append-only** — no update/delete (see [[domain-driven-design.domain]], [[persistence.domain]]).
+- Retained per regulatory policy, queryable for the full window; exportable, MAY project to FHIR `AuditEvent` / `Provenance` (see [[fhir]], [[data-provenance]]).
+- Audit + domain events + version snapshots give end-to-end traceability (see [[regulatory-compliance]], [[eventing.domain]]).
+
+## Related
+- [[auditing]] · [[regulatory-compliance]] · [[data-provenance]] · [[persistence.domain]] · [[product-lifecycle.domain]] · [[ndc]] · [[atc]] · [[cqrs.domain]] · [[eventing.domain]] · [[fhir]] · [[domain-driven-design.domain]]

package/assets/docs/domainspecs/pharma/authorization.domain.md

@@ -0,0 +1,25 @@
+# Authorization — Pharma Domain Addenda
+
+> Technology base: [[authorization]]. Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## Roles
+`SystemAdmin`, `RegulatoryOfficer`, `ProductSteward`, `TerminologyManager`, `DataManager`, `ReadOnlyConsumer`, `ExternalSystem`. Per-route matrix: `docs/security/authorization-matrix.md`.
+
+## Change authority
+- **Only `RegulatoryOfficer`** performs guarded lifecycle transitions — approve / activate / discontinue / withdraw (see [[product-lifecycle.domain]]).
+- `ProductSteward` creates/edits a `Draft` and submits for review; MUST NOT approve/activate/retire.
+- **NDC and ATC changes require `RegulatoryOfficer`** authority (or `ProductSteward` + documented `RegulatoryOfficer` sign-off) (see [[ndc]], [[atc]], [[auditing.domain]]).
+- `TerminologyManager` owns `CodeSystem`/`ValueSet`/`ConceptMap` + version changes (see [[terminology]]).
+- `DataManager` runs external imports; each attaches a `ProvenanceRecord` (see [[data-provenance]]).
+
+## Scope enforcement
+- FHIR endpoints scope-enforced (`system/Medication.read`, `system/Substance.read`, `system/*.write` for authorized backends). **No patient-context (SMART) scope** — product master data, not patient data (see [[fhir]], [[zero-trust.domain]]).
+
+## Audit-mandatory
+Every product create/modify/retire, identifier change, classification change, lifecycle transition, terminology change, external import, privileged admin/role change (see [[auditing.domain]]).
+
+## Anonymous allowlist
+- `/fhir/metadata` (CapabilityStatement) and `/health`; no write or product-data endpoint is anonymous (see [[fhir]]).
+
+## Related
+- [[authorization]] · [[product-lifecycle.domain]] · [[ndc]] · [[atc]] · [[terminology]] · [[data-provenance]] · [[auditing.domain]] · [[data-classification.domain]] · [[fhir]] · [[zero-trust.domain]]

package/assets/docs/domainspecs/pharma/coding-standards.domain.md

@@ -0,0 +1,28 @@
+# Coding Standards — Pharma Domain Addenda
+
+> Technology base: [[coding-standards]]. Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## Coded value objects
+- Follow the FHIR pattern: `Codeable`, `Coding`, `Quantity`, `Ratio`, `Identifier` (see [[terminology]], [[fhir]]).
+- Spec-mandated names: `NdcCode`, `ProductName`, `GenericName`, `Strength`, `DosageForm`, `RouteOfAdministration`, `AtcCode`, `MarketingStatus`, `PackageIdentifier` (see [[domain-driven-design.domain]]).
+- Domain may throw `InvalidNdcException`, `InvalidLifecycleTransitionException`, `UnvalidatedCodeException` (see [[ndc]], [[product-lifecycle.domain]], [[terminology]]).
+
+## Forbidden patterns — extend [[coding-standards]]
+- **P1.** Hard delete of a `MedicinalProduct`, version history, or `AuditRecord` — use lifecycle retirement / logical delete (see [[persistence.domain]], [[product-lifecycle.domain]]).
+- **P2.** Hard-coded NDC/Labeler/ATC/UNII/RxNorm/SNOMED literals outside the Terminology seed (see [[terminology]], [[ndc]], [[atc]]).
+- **P3.** Storing NDC, dosage form, route, ATC, or strength as **free text** when a value object/code applies (see [[terminology]]).
+- **P4.** A second FHIR write path bypassing the aggregate (see [[fhir]]).
+- **P5.** Persisting a product with an invalid NDC, dosage form, route, or unvalidated ATC code (see [[ndc]], [[atc]], [[terminology]]).
+- **P6.** Mutating a contained entity (`ActiveIngredient`/`PackagingConfiguration`/`MarketingAuthorization`) outside the aggregate root (see [[domain-driven-design.domain]]).
+- **P7.** Allowing an invalid lifecycle transition or removing a transition guard (see [[product-lifecycle.domain]]).
+- **P8.** Exposing `Draft`/pre-market product data on the public surface (see [[data-classification.domain]]).
+
+## Quality gates — extend [[coding-standards]]
+- **PG1.** FHIR CapabilityStatement regenerates cleanly; FHIR validator passes for every modified Medication/MedicationKnowledge/Substance/Organization resource (see [[fhir]]).
+- **PG2.** No invented NDC/ATC/UNII/RxNorm/SNOMED codes — codes resolve against value sets (grep + tests; see [[terminology]]).
+- **PG3.** NDC uniqueness + format + duplicate-detection tests pass (see [[ndc]]).
+- **PG4.** Lifecycle state-machine tests pass — every allowed + every rejected transition (see [[product-lifecycle.domain]], [[testing.domain]]).
+- **PG5.** Audit-emission tests cover create/modify/retire/identifier/classification with required fields (see [[auditing.domain]]).
+
+## Related
+- [[coding-standards]] · [[terminology]] · [[ndc]] · [[atc]] · [[fhir]] · [[domain-driven-design.domain]] · [[product-lifecycle.domain]] · [[persistence.domain]] · [[data-classification.domain]] · [[auditing.domain]] · [[testing.domain]]

package/assets/docs/domainspecs/pharma/comandrulemap.md

@@ -0,0 +1,136 @@
+# Pharma Domain — Command → Rule-File Map
+
+Per-AW-Spec-command list of the **pharma domain** rule files in this folder.
+Technology standards already auto-load inside each command; the files below are the
+domain-specific ones to load **in addition** for a medicinal-product-registration project.
+
+- All paths are workspace-relative and live in this folder: `docs/domainspecs/pharma/`.
+- A skill can read this file and load every path under the matching command heading.
+- This file is the **canonical source** for the pharma domain mapping; `/aw-spec-select-domain`
+  selects this folder as active.
+
+---
+
+## /aw-spec-constitution
+- docs/domainspecs/pharma/domain-requirements.md
+- docs/domainspecs/pharma/regulatory-compliance.md
+- docs/domainspecs/pharma/ai-rules.domain.md
+
+## /aw-spec-specify
+- docs/domainspecs/pharma/domain-requirements.md
+- docs/domainspecs/pharma/pharma-terms.md
+- docs/domainspecs/pharma/integration-terms.md
+- docs/domainspecs/pharma/domain-driven-design.domain.md
+- docs/domainspecs/pharma/product-lifecycle.domain.md
+- docs/domainspecs/pharma/ndc.md
+- docs/domainspecs/pharma/idmp.md
+- docs/domainspecs/pharma/terminology.md
+- docs/domainspecs/pharma/atc.md
+- docs/domainspecs/pharma/fhir.md
+- docs/domainspecs/pharma/hl7.md
+- docs/domainspecs/pharma/regulatory-compliance.md
+- docs/domainspecs/pharma/data-provenance.md
+- docs/domainspecs/pharma/data-classification.domain.md
+- docs/domainspecs/pharma/ai-rules.domain.md
+
+## /aw-spec-clarify
+- docs/domainspecs/pharma/domain-driven-design.domain.md
+- docs/domainspecs/pharma/product-lifecycle.domain.md
+- docs/domainspecs/pharma/ndc.md
+- docs/domainspecs/pharma/terminology.md
+- docs/domainspecs/pharma/atc.md
+- docs/domainspecs/pharma/regulatory-compliance.md
+- docs/domainspecs/pharma/pharma-terms.md
+- docs/domainspecs/pharma/integration-terms.md
+
+## /aw-spec-plan
+- docs/domainspecs/pharma/folder-structure.domain.md
+- docs/domainspecs/pharma/cqrs.domain.md
+- docs/domainspecs/pharma/vertical-slices.domain.md
+- docs/domainspecs/pharma/persistence.domain.md
+- docs/domainspecs/pharma/testing.domain.md
+- docs/domainspecs/pharma/eventing.domain.md
+- docs/domainspecs/pharma/domain-driven-design.domain.md
+- docs/domainspecs/pharma/product-lifecycle.domain.md
+- docs/domainspecs/pharma/ndc.md
+- docs/domainspecs/pharma/idmp.md
+- docs/domainspecs/pharma/fhir.md
+- docs/domainspecs/pharma/hl7.md
+- docs/domainspecs/pharma/terminology.md
+- docs/domainspecs/pharma/atc.md
+- docs/domainspecs/pharma/regulatory-compliance.md
+- docs/domainspecs/pharma/data-provenance.md
+- docs/domainspecs/pharma/zero-trust.domain.md
+- docs/domainspecs/pharma/authorization.domain.md
+- docs/domainspecs/pharma/auditing.domain.md
+- docs/domainspecs/pharma/data-classification.domain.md
+- docs/domainspecs/pharma/coding-standards.domain.md
+- docs/domainspecs/pharma/dependency-policy.domain.md
+- docs/domainspecs/pharma/api-versioning.domain.md
+- docs/domainspecs/pharma/ai-rules.domain.md
+
+## /aw-spec-tasks
+- docs/domainspecs/pharma/folder-structure.domain.md
+- docs/domainspecs/pharma/vertical-slices.domain.md
+- docs/domainspecs/pharma/cqrs.domain.md
+- docs/domainspecs/pharma/persistence.domain.md
+- docs/domainspecs/pharma/testing.domain.md
+- docs/domainspecs/pharma/eventing.domain.md
+- docs/domainspecs/pharma/domain-driven-design.domain.md
+- docs/domainspecs/pharma/product-lifecycle.domain.md
+- docs/domainspecs/pharma/ndc.md
+- docs/domainspecs/pharma/fhir.md
+- docs/domainspecs/pharma/hl7.md
+- docs/domainspecs/pharma/authorization.domain.md
+- docs/domainspecs/pharma/auditing.domain.md
+- docs/domainspecs/pharma/coding-standards.domain.md
+- docs/domainspecs/pharma/ai-rules.domain.md
+
+## /aw-spec-analyze
+- docs/domainspecs/pharma/ndc.md
+- docs/domainspecs/pharma/terminology.md
+- docs/domainspecs/pharma/product-lifecycle.domain.md
+- docs/domainspecs/pharma/regulatory-compliance.md
+- docs/domainspecs/pharma/auditing.domain.md
+- docs/domainspecs/pharma/coding-standards.domain.md
+- docs/domainspecs/pharma/ai-rules.domain.md
+
+## /aw-spec-implement
+- docs/domainspecs/pharma/folder-structure.domain.md
+- docs/domainspecs/pharma/vertical-slices.domain.md
+- docs/domainspecs/pharma/cqrs.domain.md
+- docs/domainspecs/pharma/persistence.domain.md
+- docs/domainspecs/pharma/testing.domain.md
+- docs/domainspecs/pharma/eventing.domain.md
+- docs/domainspecs/pharma/domain-driven-design.domain.md
+- docs/domainspecs/pharma/product-lifecycle.domain.md
+- docs/domainspecs/pharma/ndc.md
+- docs/domainspecs/pharma/idmp.md
+- docs/domainspecs/pharma/fhir.md
+- docs/domainspecs/pharma/hl7.md
+- docs/domainspecs/pharma/terminology.md
+- docs/domainspecs/pharma/atc.md
+- docs/domainspecs/pharma/regulatory-compliance.md
+- docs/domainspecs/pharma/data-provenance.md
+- docs/domainspecs/pharma/authorization.domain.md
+- docs/domainspecs/pharma/auditing.domain.md
+- docs/domainspecs/pharma/data-classification.domain.md
+- docs/domainspecs/pharma/zero-trust.domain.md
+- docs/domainspecs/pharma/coding-standards.domain.md
+- docs/domainspecs/pharma/dependency-policy.domain.md
+- docs/domainspecs/pharma/api-versioning.domain.md
+- docs/domainspecs/pharma/ai-rules.domain.md
+
+---
+
+## Quick reference (command → file count)
+
+| Command | Domain rule files |
+|---|---|
+| /aw-spec-constitution | 3 |
+| /aw-spec-specify | 15 |
+| /aw-spec-clarify | 8 |
+| /aw-spec-plan | 24 |
+| /aw-spec-tasks | 15 |
+| /aw-spec-analyze | 7 |
+| /aw-spec-implement | 24 |