aw-spec-cli 0.1.0 → 0.1.2

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

@@ -0,0 +1,16 @@
+# CQRS — Pharma Domain Addenda
+
+> Technology base: [[cqrs]]. Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## Pipeline
+- Append a **product-audit behavior** to the mediator pipeline: every create/modify/retire/re-identify/reclassify command on `MedicinalProduct` MUST emit an immutable audit record (User, Timestamp, Action, Previous Value, New Value). See [[auditing.domain]], [[regulatory-compliance]].
+
+## Commands & queries
+- Registration, lifecycle transitions, ingredient/packaging edits, identifier & classification changes = **commands**; each publishes its domain event (see [[eventing.domain]], [[product-lifecycle.domain]]).
+- Product lookup, version history, FHIR projections = **queries** via `IReadRepository<MedicinalProduct>` + a `Specification` (see [[persistence.domain]]).
+
+## Error codes
+`medicinal-product.not_found` · `ndc.duplicate` · `ndc.invalid_format` · `dosage-form.invalid` · `route.invalid` · `atc.invalid_code` · `lifecycle.invalid_transition` · `concurrency.conflict`.
+
+## Related
+- [[cqrs]] · [[auditing.domain]] · [[eventing.domain]] · [[product-lifecycle.domain]] · [[persistence.domain]] · [[domain-driven-design.domain]] · [[regulatory-compliance]]

package/assets/docs/domainspecs/pharma/data-classification.domain.md

@@ -0,0 +1,24 @@
+# Data Classification — Pharma Domain Addenda
+
+> Technology base: [[data-classification]]. Commands: `/aw-spec-specify`, `/aw-spec-plan`, `/aw-spec-implement`.
+
+> No PHI — the model is commercial confidentiality, regulatory integrity, and source trust.
+
+## Categories
+| Class | Extra rules |
+|---|---|
+| **Public / Published** (NDC-directory disclosure level) | Projectable via the public FHIR surface once `MarketingStatus` is active |
+| **Commercially-Sensitive** (pre-market formulations, proprietary strengths, unpublished products) | Access-restricted; **MUST NOT** be on the public FHIR surface until marketing status permits |
+| **Regulatory-Submission** (MA dossier refs, regulator keys) | Restricted; audited access (see [[auditing.domain]]) |
+| **Externally-Sourced** (FDA NDC / RxNorm / WHO ATC / partner feeds) | Carries a `ProvenanceRecord`; still validated (see [[data-provenance]]) |
+
+## Data integrity (GxP / ALCOA+)
+- GxP records satisfy **ALCOA+** (Attributable, Legible, Contemporaneous, Original, Accurate + Complete, Consistent, Enduring, Available), enforced via immutable audit, provenance, version history (see [[auditing.domain]], [[data-provenance]], [[persistence.domain]], [[regulatory-compliance]]).
+
+## Exposure & logging
+- `Draft`/`Under Review` or non-public `MarketingStatus` products MUST NOT be published on the public FHIR/REST surface (see [[product-lifecycle.domain]], [[fhir]]).
+- Externally-sourced values are never published without passing validation (see [[ndc]], [[atc]], [[terminology]]).
+- Commercially-sensitive pre-market details MUST NOT appear in logs/metrics/traces — log the product ID only (see [[coding-standards.domain]]).
+
+## Related
+- [[data-classification]] · [[data-provenance]] · [[auditing.domain]] · [[persistence.domain]] · [[regulatory-compliance]] · [[product-lifecycle.domain]] · [[authorization.domain]] · [[coding-standards.domain]] · [[ndc]] · [[atc]] · [[fhir]]

package/assets/docs/domainspecs/pharma/data-provenance.md

@@ -0,0 +1,21 @@
+# Data Provenance Standards — Pharma
+
+> NON-NEGOTIABLE. Commands: `/aw-spec-specify`, `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## First-class concern
+- Any product attribute imported from an external source (FDA NDC directory, RxNorm, WHO ATC, an MAH submission, a partner feed) SHALL carry a **`ProvenanceRecord`** (Provenance module).
+- Provenance is captured at ingestion through the Interop adapters — never back-filled by guessing (see [[hl7]], [[fhir]], [[ai-rules.domain]]).
+
+## Record (minimum)
+```
+{ source, sourceSystem, sourceVersion, method, agent, timestamp, importedFields[], correlationId }
+```
+- **sourceVersion** = originating authority's release/version (e.g. terminology edition; see [[terminology]], [[atc]]); **method** = automated import / manual entry / API sync; **agent** = responsible principal.
+
+## Integrity
+- Complements audit (who/when/what; see [[auditing.domain]]) and version history (see [[persistence.domain]]).
+- Provenance does **not** exempt an NDC/ATC/UNII value from validation (see [[ndc]], [[atc]], [[terminology]]).
+- MAY project to the FHIR `Provenance` resource (see [[fhir]]).
+
+## Related
+- [[auditing.domain]] · [[persistence.domain]] · [[terminology]] · [[ndc]] · [[atc]] · [[fhir]] · [[regulatory-compliance]] · [[ai-rules.domain]]

package/assets/docs/domainspecs/pharma/dependency-policy.domain.md

@@ -0,0 +1,11 @@
+# Dependency Policy — Pharma Domain Addenda
+
+> Technology base: [[dependency-policy]]. Commands: `/aw-spec-plan`, `/aw-spec-implement`.
+
+## Reviews & libraries
+- Every new dependency gets a **regulatory-suitability** review beyond the generic license/supply-chain check — reject packages that phone home or ship analytics by default (leak risk for commercially-sensitive pre-market data) (see [[data-classification.domain]]).
+- FHIR: the **official FHIR .NET SDK**, version-matched to the endpoint (R4/R5; see [[fhir]]).
+- Terminology integrations (RxNorm/SNOMED/UNII/ATC/NDC) go through the Terminology module; client libraries added **only** on explicit developer request — no AI-introduced terminology/interop dependencies (see [[terminology]], [[hl7]], [[ai-rules.domain]]).
+
+## Related
+- [[dependency-policy]] · [[fhir]] · [[hl7]] · [[terminology]] · [[data-classification.domain]] · [[ai-rules.domain]]

package/assets/docs/domainspecs/pharma/domain-driven-design.domain.md

@@ -0,0 +1,36 @@
+# Domain-Driven Design — Medicinal Product Domain Model
+
+> Technology base: [[domain-driven-design]]. NON-NEGOTIABLE. Commands: `/aw-spec-specify`, `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## Modeling
+- Use the pharma/regulatory ubiquitous language (see [[pharma-terms]]), aligned to ISO IDMP concepts (see [[idmp]]).
+- FHIR- and IDMP-aligned, but **FHIR resources are projections, not the system of record** (see [[fhir]]); the aggregate is authoritative.
+- Coded concepts use industry terminologies, never free text (see [[terminology]]); coded VOs follow the FHIR pattern (`Codeable`, `Coding`, `Quantity`, `Ratio`, `Identifier`).
+
+## Aggregate Root
+- **`MedicinalProduct` is the Aggregate Root.** All product data (ingredients, packaging, marketing authorization, identifiers, classification, lifecycle state) is reached/modified **through** it; no external code mutates a contained entity directly. Invariants are enforced atomically; state changes raise domain events (see [[eventing.domain]]).
+
+## Value Objects (immutable, equality by value)
+`NdcCode` · `ProductName` · `GenericName` · `Strength` · `DosageForm` · `RouteOfAdministration` · `AtcCode` · `MarketingStatus` · `PackageIdentifier`
+- `NdcCode`/`PackageIdentifier` — segmented, format-validated, unique (see [[ndc]]).
+- `Strength` — numerator/denominator `Quantity` with UCUM units; `DosageForm`/`RouteOfAdministration`/`AtcCode` — coded against configured value sets (see [[terminology]], [[atc]]).
+
+## Entities (identity within the aggregate)
+- **`ActiveIngredient`** — Name, UNII, Strength, Strength Unit. **>= 1 required.**
+- **`PackagingConfiguration`** — Package NDC, Description, Quantity, Unit of Measure. **>= 1 required.**
+- **`MarketingAuthorization`** — authorization granted to the MAH by a regulator (see [[idmp]]).
+
+## Invariants
+- **MedicinalProduct** — NDC unique + format-valid (invalid blocks persistence); >= 1 ActiveIngredient + >= 1 PackagingConfiguration; all required attributes enforced at registration; dosage form/route must be valid coded values; lifecycle transitions must be valid (see [[product-lifecycle.domain]]); identifier/classification changes are audit-mandatory + emit events (see [[auditing.domain]], [[eventing.domain]]).
+- **PackagingConfiguration** — Package NDC unique within and across products (see [[ndc]]).
+- **ActiveIngredient** — Strength + Strength Unit required; UNII validated where supplied (see [[terminology]]).
+- **AuditRecord** — append-only; no update/delete (see [[auditing.domain]]).
+
+## Validation summary
+NDC format; required attributes; duplicate identifiers; invalid dosage forms; invalid routes; invalid lifecycle transitions (see [[ndc]], [[terminology]], [[product-lifecycle.domain]]).
+
+## AI guidance
+See [[ai-rules.domain]] — confirm signatures, use the official FHIR SDK, never invent NDC/UNII/RxNorm/SNOMED/ATC codes, keep FHIR as projections.
+
+## Related
+- [[domain-driven-design]] · [[product-lifecycle.domain]] · [[ndc]] · [[idmp]] · [[atc]] · [[terminology]] · [[fhir]] · [[eventing.domain]] · [[auditing.domain]] · [[persistence.domain]] · [[pharma-terms]] · [[ai-rules.domain]]

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

@@ -0,0 +1,99 @@
+# DOMAIN REQUIREMENTS (project-specific)
+
+> Project-specific input, **updated independently per project**. The engineering constitution
+> stays domain-agnostic and supreme; this file holds the per-project enumeration and headline
+> profiles for the **Medicinal Product Registration** domain. Detailed domain *rules* are
+> expanded in the sibling files in this folder.
+>
+> Replace `<SampleProjectName>` and the bounded-context list below for a new project.
+
+=====================================================================
+[DOMAIN: Bounded Contexts / Modules]
+=====================================================================
+- ProductRegistry — aggregate root: **MedicinalProduct**; owns ActiveIngredient,
+  PackagingConfiguration, MarketingAuthorization entities and the product value objects
+  (NdcCode, ProductName, GenericName, Strength, DosageForm, RouteOfAdministration, AtcCode,
+  MarketingStatus, PackageIdentifier). See [[domain-driven-design.domain]].
+- Substances — aggregates: Substance, ActiveMoiety; UNII-keyed ingredient identity
+  (see [[terminology]]).
+- Organizations — aggregates: Organization, MarketingAuthorizationHolder, Manufacturer,
+  Labeler. Maps to FHIR `Organization` (see [[fhir]]).
+- Classification — aggregates: AtcClassification, ProductClassification; ATC code sets and
+  SNOMED CT classification references (see [[atc]], [[terminology]]).
+- Terminology — aggregates: CodeSystem, ValueSet, ConceptMap (project-managed subsets;
+  expansions cached from external terminology services). Backs NDC/ATC/UNII/SNOMED/RxNorm
+  validation (see [[terminology]]).
+- Lifecycle — the MedicinalProduct state machine (Draft → Under Review → Approved → Active →
+  Discontinued → Withdrawn) and its transition guards (see [[product-lifecycle.domain]]).
+- Interoperability — aggregates: FhirProjection, IntegrationEndpoint; FHIR Medication /
+  MedicationKnowledge / Substance / Organization projections and HL7 readiness
+  (see [[fhir]], [[hl7]]).
+- Provenance — aggregate: ProvenanceRecord for externally sourced product data
+  (see [[data-provenance]]).
+- Auditing — aggregate: AuditRecord (append-only). Captures creation, modification,
+  retirement, identifier and classification changes (see [[auditing.domain]]).
+
+=====================================================================
+[DOMAIN: subsection pointers]
+=====================================================================
+[DOMAIN: Standards — NDC]                      -> docs/domainspecs/pharma/ndc.md
+[DOMAIN: Standards — ISO IDMP]                 -> docs/domainspecs/pharma/idmp.md
+[DOMAIN: Standards — ATC]                      -> docs/domainspecs/pharma/atc.md
+[DOMAIN: Standards — Terminology]              -> docs/domainspecs/pharma/terminology.md
+[DOMAIN: Interop — FHIR]                       -> docs/domainspecs/pharma/fhir.md
+[DOMAIN: Interop — HL7]                        -> docs/domainspecs/pharma/hl7.md
+[DOMAIN: Aggregates and Business Invariants]   -> docs/domainspecs/pharma/domain-driven-design.domain.md
+[DOMAIN: Product Lifecycle]                    -> docs/domainspecs/pharma/product-lifecycle.domain.md
+[DOMAIN: Regulatory / Compliance]              -> docs/domainspecs/pharma/regulatory-compliance.md
+[DOMAIN: Data Provenance]                      -> docs/domainspecs/pharma/data-provenance.md
+[DOMAIN: Audit Profile]                        -> docs/domainspecs/pharma/auditing.domain.md
+[DOMAIN: Persistence / Versioning Profile]     -> docs/domainspecs/pharma/persistence.domain.md
+[DOMAIN: Eventing Profile]                     -> docs/domainspecs/pharma/eventing.domain.md
+[DOMAIN: Testing Profile]                      -> docs/domainspecs/pharma/testing.domain.md
+[DOMAIN: Security Profile]                     -> docs/domainspecs/pharma/authorization.domain.md, docs/domainspecs/pharma/data-classification.domain.md, docs/domainspecs/pharma/zero-trust.domain.md
+[DOMAIN: Coding Standards Profile]             -> docs/domainspecs/pharma/coding-standards.domain.md
+[DOMAIN: CQRS / Vertical Slices Profile]       -> docs/domainspecs/pharma/cqrs.domain.md, docs/domainspecs/pharma/vertical-slices.domain.md
+[DOMAIN: Folder Structure Profile]             -> docs/domainspecs/pharma/folder-structure.domain.md
+[DOMAIN: API Versioning Profile]               -> docs/domainspecs/pharma/api-versioning.domain.md
+[DOMAIN: Dependency Policy Profile]            -> docs/domainspecs/pharma/dependency-policy.domain.md
+[DOMAIN: Integration Terms]                    -> docs/domainspecs/pharma/integration-terms.md
+[DOMAIN: AI Policy Addenda]                    -> docs/domainspecs/pharma/ai-rules.domain.md
+[DOMAIN: Ubiquitous Language]                  -> docs/domainspecs/pharma/pharma-terms.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 product registry), Redis
+  (cache for terminology expansions + read models), a message broker (Azure Service Bus,
+  AWS SQS/SNS, or RabbitMQ) for CloudEvents, an OTel collector, the configured IdP, an external
+  Terminology Service (NDC/RxNorm/SNOMED/UNII/ATC value-set expansion, optional), a FHIR
+  validator container, and an object store (S3/Blob) for imported source documents / labels.
+- Scale targets: P95 read latency < 200 ms at 200 RPS per module; FHIR search P95 < 500 ms.
+- Disaster recovery: RPO <= 15 minutes, RTO <= 4 hours; daily encrypted backups with 35-day
+  retention plus monthly archive. Product registry and audit history are retention-protected
+  (see [[persistence.domain]], [[auditing.domain]]).
+
+=====================================================================
+[DOMAIN: Governance Overrides]
+=====================================================================
+- Principal Engineers (approvers): TBD — fill at ratification.
+- Regulatory / Compliance Officer (mandatory approver for any identifier, classification, or
+  lifecycle-rule change): TBD.
+- Domain Owners (per module): TBD — assign one regulatory and one technical owner per bounded
+  context.
+- Quarterly review cadence: first business week of each quarter; an additional review after
+  every relevant regulatory or terminology-release update (e.g. WHO ATC annual update, FDA NDC
+  directory changes).
+- 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.
+
+## Related
+
+- [[domain-driven-design.domain]] · [[product-lifecycle.domain]] · [[ndc]] · [[idmp]] ·
+  [[atc]] · [[terminology]] · [[fhir]] · [[hl7]] · [[regulatory-compliance]] ·
+  [[data-provenance]] · [[auditing.domain]] · [[persistence.domain]] · [[ai-rules.domain]] ·
+  [[pharma-terms]]

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

@@ -0,0 +1,18 @@
+# Eventing — Pharma Domain Addenda
+
+> Technology base: [[eventing]]. Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## Domain events
+- `MedicinalProduct` raises domain events on every significant state change — the integration seam to downstream consumers (prescribing, dispensing, manufacturing, pharmacovigilance, clinical).
+- Events publish from the aggregate boundary, never by an external feed writing aggregates directly (see [[hl7]], [[domain-driven-design.domain]]).
+
+## Canonical events
+`MedicinalProductRegistered` (Draft) · `…SubmittedForReview`/`Approved`/`Activated`/`Discontinued`/`Withdrawn` (lifecycle, see [[product-lifecycle.domain]]) · `ProductIdentifierChanged` (NDC, see [[ndc]]) · `ProductClassificationChanged` (ATC, see [[atc]]) · `ActiveIngredientChanged`/`PackagingConfigurationChanged` · `MarketingStatusChanged`. Each = an audit-mandatory operation (see [[auditing.domain]]).
+
+## Delivery
+- Outbox pattern: events persisted transactionally with the aggregate change, published to CloudEvents. Consumers integrate via FHIR / REST / event stream — **direct DB access FORBIDDEN** (see [[fhir]]).
+- Payloads carry coded values via standard terminologies, never free text (see [[terminology]], [[ndc]], [[atc]]).
+- Each event carries a `correlationId` tying command → audit record → version snapshot (see [[auditing.domain]], [[persistence.domain]], [[regulatory-compliance]]).
+
+## Related
+- [[eventing]] · [[domain-driven-design.domain]] · [[product-lifecycle.domain]] · [[auditing.domain]] · [[persistence.domain]] · [[fhir]] · [[hl7]] · [[ndc]] · [[atc]] · [[terminology]]

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

@@ -0,0 +1,31 @@
+# FHIR Standards — Pharma
+
+> NON-NEGOTIABLE. Commands: `/aw-spec-specify`, `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## Architecture & projectors
+- **R4 default**; R5 **additive** under `/fhir/R5/...`. FHIR is the canonical interop contract; it + any internal REST serve from the **same authoritative aggregates** — no duplicate write paths.
+- **FHIR resources are PROJECTIONS, NOT the system of record** — `MedicinalProduct` is authoritative (see [[domain-driven-design.domain]]).
+- Mapping in `{Module}/Interop/Fhir/<Resource>Projector.cs`, hand-written + round-trip tested (see [[testing.domain]]). A second FHIR write path bypassing the aggregate is FORBIDDEN; FHIR representations MUST NOT replace internal DTOs.
+
+## Resource mappings
+| Domain concept | FHIR resource |
+|---|---|
+| `MedicinalProduct` (dispensable identity) | **Medication** |
+| `MedicinalProduct` (classification/packaging/regulatory) | **MedicationKnowledge** |
+| `Substance` / `ActiveIngredient` | **Substance** |
+| `MarketingAuthorizationHolder` / `Manufacturer` / `Labeler` | **Organization** |
+
+- Identifiers → FHIR `Identifier` (`NdcCode` with NDC system URI; IDMP MPID/PhPID where adopted; see [[ndc]], [[idmp]]).
+- Names → `Medication.code` + name elements; coded fields → `CodeableConcept`/`Coding` (see [[terminology]]); ATC codings carry the ATC system URI (see [[atc]]).
+- `Strength` → `Medication.ingredient.strength` (`Ratio` of `Quantity`); `DosageForm` → `Medication.form`; route + packaging → `MedicationKnowledge`.
+
+## Conformance
+- FHIR types from the **official FHIR .NET SDK**, version-matched (R4/R5) (see [[ai-rules.domain]]).
+- Declare profiles/extensions/value-sets in `StructureDefinition` resources; FHIR validator passes for every modified resource/profile/example (CI gate).
+- Publish `CapabilityStatement` at `/fhir/metadata` (diff reviewed); `/metadata` + `/.well-known` may be `AllowAnonymous()`.
+
+## Bundle / search / concurrency
+- Bundle/searchset semantics (`_count`, `_offset`/`_page`, `_total`); errors via `OperationOutcome` (HTTP 422); `If-Match` → FHIR **weak** ETag at the projection boundary (see [[persistence.domain]]).
+
+## Related
+- [[domain-driven-design.domain]] · [[terminology]] · [[ndc]] · [[idmp]] · [[atc]] · [[hl7]] · [[integration-terms]] · [[persistence.domain]] · [[testing.domain]] · [[ai-rules.domain]]

package/assets/docs/domainspecs/pharma/folder-structure.domain.md

@@ -0,0 +1,24 @@
+# Folder Structure — Pharma 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, change-authority checks
+  Infrastructure/Auditing/      immutable product-audit emitter (FHIR AuditEvent shape)
+  ProductRegistry/Domain/<ValueObject>.cs   NdcCode, AtcCode, Strength, DosageForm, ...
+  ProductRegistry/Domain/MedicinalProduct.cs   aggregate root  (see [[domain-driven-design.domain]])
+  ProductRegistry/Interop/Fhir/   Medication/MedicationKnowledge/Substance/Organization projectors  (see [[fhir]])
+  ProductRegistry/Interop/Hl7v2/  inbound parsers + outbound emitters (when needed)   (see [[hl7]])
+  Terminology/                  CodeSystem/ValueSet/ConceptMap + seed (NDC/RxNorm/SNOMED/UNII/ATC)  (see [[terminology]])
+  Provenance/                   ProvenanceRecord store for external data   (see [[data-provenance]])
+tests/<SampleProjectName>.InteropTests/   FHIR-validator conformance              (see [[testing.domain]])
+tests/<SampleProjectName>.TestFixtures/   synthetic/test NDC + terminology sentinels  (see [[testing.domain]])
+docs/interop/fhir-implementation-guide/ · docs/regulatory/compliance-controls.md
+```
+- `Interop/` adapters translate to/from internal commands + projections (see [[vertical-slices.domain]]).
+- Coded VOs follow the FHIR pattern (see [[terminology]], [[coding-standards.domain]]); version history + audit store are retention-protected (see [[persistence.domain]], [[auditing.domain]]).
+
+## Related
+- [[folder-structure]] · [[fhir]] · [[hl7]] · [[terminology]] · [[data-provenance]] · [[testing.domain]] · [[vertical-slices.domain]] · [[domain-driven-design.domain]]

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

@@ -0,0 +1,17 @@
+# HL7 Integration Readiness — Pharma
+
+> Commands: `/aw-spec-specify`, `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## Principle
+- The solution SHALL support **future integration with HL7-based systems**. The registry is the authoritative product source; HL7 surfaces are **adapters, not a parallel model**. FHIR is the primary contract (see [[fhir]]); HL7 v2 adapters are added where a downstream system (prescribing/dispensing/manufacturing/pharmacovigilance) needs them.
+
+## Adapter patterns
+- Inbound/outbound adapters live in `{Module}/Interop/Hl7v2/`; translate via `IMediator` — **MUST NOT** write aggregates directly (see [[eventing.domain]], [[domain-driven-design.domain]]). Bypassing them from an external feed is an AI refusal condition (see [[ai-rules.domain]]).
+- The egress adapter converts domain events (e.g. `MedicinalProductActivated`, `ClassificationChanged`) to outbound messages; conformance tested against an internal corpus (see [[testing.domain]]).
+- Codes in HL7 messages use standard terminologies (NDC, RxNorm, UNII, ATC) — never free text (see [[terminology]], [[ndc]], [[atc]]).
+
+## Future surfaces
+- Pharmacovigilance (ICH E2B/ICSR), manufacturing, dispensing integrations are **additive** — consume via FHIR / REST / CloudEvents; **direct DB access FORBIDDEN** (see [[eventing.domain]]).
+
+## Related
+- [[fhir]] · [[eventing.domain]] · [[terminology]] · [[ndc]] · [[atc]] · [[integration-terms]] · [[domain-driven-design.domain]] · [[testing.domain]] · [[ai-rules.domain]]

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

@@ -0,0 +1,26 @@
+# ISO IDMP — Identification of Medicinal Products
+
+> NON-NEGOTIABLE. Commands: `/aw-spec-specify`, `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## Alignment principle
+- The model SHALL align with the ISO IDMP suite (**ISO 11615/11616/11238/11239/11240**) **where applicable** — IDMP shapes the ubiquitous language + aggregate boundaries; it is **not** a wire format and does not replace the internal model (see [[domain-driven-design.domain]]).
+- Even where IDMP messages aren't yet exchanged, preserve the IDMP concept boundaries so future exchange is additive, not a rewrite.
+
+## Required concepts → model home
+| IDMP concept | Model home |
+|---|---|
+| **Medicinal Product** | `MedicinalProduct` aggregate root |
+| **Manufactured Item** | manufactured dose-form item (within the aggregate or a related entity) |
+| **Pharmaceutical Product** | administrable product = `DosageForm` + `Strength` + `RouteOfAdministration` |
+| **Substance** | `Substance` aggregate, UNII-identified (see [[terminology]]); referenced by `ActiveIngredient` |
+| **Marketing Authorization Holder** | `MarketingAuthorizationHolder` → FHIR `Organization` (see [[fhir]]) |
+| **Packaging** | `PackagingConfiguration` (Package NDC, description, quantity, UoM) (see [[ndc]]) |
+| **Strength** | `Strength` VO (numerator/denominator `Quantity`, UCUM) |
+| **Route of Administration** | `RouteOfAdministration` VO (coded) |
+
+## Identifiers & terminology
+- IDMP identifiers (**MPID**, **PhPID**) SHALL be representable as FHIR `Identifier`-shaped VOs when adopted; they coexist with NDC, not replace it (see [[ndc]]).
+- IDMP controlled vocabularies (dose form, route, units, packaging) bind to the Terminology module's code systems, never free text (see [[terminology]], [[atc]]).
+
+## Related
+- [[domain-driven-design.domain]] · [[ndc]] · [[terminology]] · [[atc]] · [[fhir]] · [[pharma-terms]]

package/assets/docs/domainspecs/pharma/integration-terms.md

@@ -0,0 +1,21 @@
+# Glossary — Integration Terms (Pharma)
+
+> Ubiquitous language for pharma interoperability standards + identifiers. Commands: `/aw-spec-specify`, `/aw-spec-clarify`, `/aw-spec-plan`. See [[pharma-terms]] (aggregates) + [[terminology]] (coding).
+
+| Term | Definition |
+|---|---|
+| **NDC** | US FDA product/package identifier (Labeler + Product + Package); the `NdcCode` VO; format-validated, unique (see [[ndc]]). |
+| **ISO IDMP** | Identification of Medicinal Products (ISO 11615/11616/11238/11239/11240); conceptual alignment; may carry MPID/PhPID (see [[idmp]]). |
+| **UNII** | FDA substance identity for ingredients/moieties; maps to FHIR `Substance.code` (see [[terminology]]). |
+| **RxNorm** | Normalized clinical-drug naming (US); optional product identifier (see [[terminology]]). |
+| **WHO ATC** | Therapeutic class codes; multiple per product, validated against configured sets (see [[atc]]). |
+| **SNOMED CT** | Terminology for dosage forms, routes, product classification (see [[terminology]]). |
+| **UCUM** | Units for strength + package quantity (see [[terminology]]). |
+| **FHIR** | Canonical external contract (R4 default, R5 additive); projects to `Medication`/`MedicationKnowledge`/`Substance`/`Organization` over aggregates (see [[fhir]]). |
+| **HL7** | **HL7 v2.x** legacy messaging via adapters where a consumer needs it; **HL7 FHIR** is the primary contract (see [[hl7]], [[fhir]]). |
+| **Provenance** | Source metadata for externally sourced data; may project to FHIR `Provenance` (see [[data-provenance]]). |
+| **CloudEvents** | CNCF durable async event-stream spec; carries product domain events (see [[eventing.domain]]). |
+| **OpenAPI / CapabilityStatement** | Versioned machine-readable contracts for REST / FHIR (see [[api-versioning.domain]]). |
+
+## Related
+- [[pharma-terms]] · [[terminology]] · [[ndc]] · [[idmp]] · [[atc]] · [[fhir]] · [[hl7]] · [[data-provenance]] · [[eventing.domain]] · [[api-versioning.domain]]

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

@@ -0,0 +1,28 @@
+# NDC — National Drug Code Standards
+
+> NON-NEGOTIABLE. Commands: `/aw-spec-specify`, `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## Value Object
+- **NDC SHALL be a Value Object** (`NdcCode`) — immutable, equality by value (see [[domain-driven-design.domain]]).
+- Product-level NDC lives on `MedicinalProduct`; package-level (`PackageIdentifier` / Package NDC) on each `PackagingConfiguration`.
+- Free-text storage of an NDC is a Forbidden Pattern.
+
+## Segments & format
+- Three segments: **Labeler Code**, **Product Code**, **Package Code** — retain each segment discretely **plus** the canonical formatted string (boundaries MUST NOT be lost to a concatenated string).
+- Common configurations (5-4-2, 5-3-2, 4-4-2 10-digit + the 11-digit normalized form) SHALL be representable as **data, not compiled constants**.
+- The Labeler Code is FDA-assigned to the **Labeler** organization; the registry does not mint Labeler Codes (see [[domain-requirements]]).
+
+## Uniqueness
+- **NDC uniqueness SHALL be enforced** — a product NDC maps to <=1 active `MedicinalProduct`; a Package NDC to <=1 `PackagingConfiguration`.
+- Duplicate detection runs at registration + any identifier change; enforced at the aggregate boundary **and** a persistence-level unique constraint (see [[persistence.domain]], [[auditing.domain]]).
+
+## Validation
+- **NDC validation rules SHALL be configurable** (segment lengths, allowed configurations, check rules = value-set data).
+- Runs on registration, identifier change, and external import (see [[data-provenance]]); an invalid NDC raises a domain error — the Domain MUST NOT persist it.
+- Never invent NDC values or Labeler Codes — validate external codes against the configured rules + FDA NDC directory via the Terminology module (see [[terminology]], [[ai-rules.domain]]).
+
+## FHIR mapping
+- `NdcCode` → FHIR `Identifier` (NDC system URI); also participates in `Medication.code` as a `CodeableConcept` coding (see [[fhir]]).
+
+## Related
+- [[domain-driven-design.domain]] · [[idmp]] · [[terminology]] · [[fhir]] · [[data-provenance]] · [[persistence.domain]] · [[auditing.domain]] · [[ai-rules.domain]]

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

@@ -0,0 +1,23 @@
+# Persistence — Pharma Domain Addenda
+
+> Technology base: [[persistence]]. NON-NEGOTIABLE. Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## Version history
+- Maintain a **version history** of product information: each approved change produces a new, immutable **`ProductVersion`** snapshot.
+- **Historical versions remain queryable** — a read model exposes prior versions by product + effective time; superseded versions are never overwritten or purged. Snapshots complement audit (who/what/when; see [[auditing.domain]]) and provenance (source; see [[data-provenance]]).
+
+## Retention-protected data
+- Hard delete FORBIDDEN for `MedicinalProduct` and all product history — delete logically via `MarkAsDeleted(...)` / lifecycle retirement.
+- **Product retirement** (Discontinued/Withdrawn) is a state change, not a delete (see [[product-lifecycle.domain]]).
+- `AuditRecord` is **append-only** — no delete (see [[auditing.domain]]).
+- Retention: registry + version history per regulatory policy (registration lifetime + statutory tail); `AuditRecord` per [[auditing.domain]]; daily encrypted backups.
+
+## Constraints & concurrency
+- Persistence-level **unique constraints** on NDC and Package NDC, beyond the aggregate check (see [[ndc]], [[domain-driven-design.domain]]).
+- Optimistic concurrency token → FHIR **weak** ETag at the projection boundary (see [[fhir]]).
+
+## Dev data
+- Fixtures use synthetic data + **synthetic/clearly-marked test NDCs** — never real identifiers that could collide with the FDA NDC directory (see [[ndc]], [[testing.domain]]).
+
+## Related
+- [[persistence]] · [[auditing.domain]] · [[data-provenance]] · [[product-lifecycle.domain]] · [[ndc]] · [[fhir]] · [[domain-driven-design.domain]] · [[testing.domain]]

package/assets/docs/domainspecs/pharma/pharma-terms.md

@@ -0,0 +1,27 @@
+# Glossary — Pharmaceutical Terms
+
+> Ubiquitous language for the medicinal product registry. Commands: `/aw-spec-specify`, `/aw-spec-clarify`, `/aw-spec-plan`. See [[domain-driven-design.domain]] (modeling), [[terminology]] (coding), [[integration-terms]] (interop).
+
+| Term | Definition |
+|---|---|
+| **MedicinalProduct** | The **Aggregate Root** — authoritative record of a registered medicine (ProductRegistry); owns ingredients, packaging, marketing authorization; aligned to IDMP *Medicinal Product* (see [[idmp]], [[domain-driven-design.domain]]). |
+| **NDC** | US FDA product identifier (Labeler + Product + Package); the `NdcCode` VO; unique, format-validated (see [[ndc]]). |
+| **PackageIdentifier** | Package-level NDC on a `PackagingConfiguration` (see [[ndc]]). |
+| **ActiveIngredient** | **Entity**: Name, UNII, Strength, Strength Unit; **>= 1** per product (see [[domain-driven-design.domain]]). |
+| **Substance / ActiveMoiety** | Chemical substance + active moiety; UNII-identified (see [[terminology]]); FHIR `Substance`. |
+| **Strength** | Active-ingredient amount per dose unit — `Strength` VO (numerator/denominator `Quantity`, UCUM) (see [[terminology]]). |
+| **DosageForm** | Physical form (tablet/capsule/solution); coded (SNOMED CT); `DosageForm` VO (see [[terminology]]). |
+| **RouteOfAdministration** | Administration path (oral/IV/topical); coded; `RouteOfAdministration` VO (see [[terminology]]). |
+| **AtcCode** | WHO ATC class code; **multiple per product**; validated against configured sets (see [[atc]]). |
+| **MarketingStatus** | Regulatory marketing state (`MarketingStatus` VO); distinct from lifecycle state (see [[product-lifecycle.domain]]). |
+| **MarketingAuthorization** | **Entity** — authorization granted by a regulator; IDMP-aligned (see [[idmp]]). |
+| **MarketingAuthorizationHolder (MAH)** | Organization holding the authorization; FHIR `Organization`. |
+| **Labeler** | Firm whose Labeler Code forms the first NDC segment (see [[ndc]]). |
+| **PackagingConfiguration** | **Entity**: Package NDC, Description, Quantity, Unit of Measure; **>= 1** per product (see [[domain-driven-design.domain]]). |
+| **ManufacturedItem / PharmaceuticalProduct** | IDMP concepts: manufactured dose-form item + administrable product (see [[idmp]]). |
+| **ProvenanceRecord** | Provenance for externally sourced data (source, method, timestamp, agent) (see [[data-provenance]]). |
+| **AuditRecord** | Append-only audit entry for create/modify/retire/identifier/classification changes (see [[auditing.domain]]). |
+| **ProductVersion** | Queryable historical snapshot of product information (see [[persistence.domain]]). |
+
+## Related
+- [[domain-driven-design.domain]] · [[idmp]] · [[ndc]] · [[atc]] · [[terminology]] · [[fhir]] · [[integration-terms]] · [[product-lifecycle.domain]] · [[data-provenance]]

package/assets/docs/domainspecs/pharma/product-lifecycle.domain.md

@@ -0,0 +1,30 @@
+# Product Lifecycle — Medicinal Product State Machine
+
+> Technology base: [[domain-driven-design]]. NON-NEGOTIABLE. Commands: `/aw-spec-specify`, `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## States
+`Draft` → `Under Review` → `Approved` → `Active` → `Discontinued` / `Withdrawn`
+- Lifecycle state is owned by the aggregate root and is distinct from the `MarketingStatus` value object, though the two MUST stay consistent (see [[domain-driven-design.domain]]).
+
+## Valid transitions (guarded; any other rejected as `lifecycle.invalid_transition`)
+| From | Allowed to |
+|---|---|
+| Draft | Under Review |
+| Under Review | Approved, Draft (returned for correction) |
+| Approved | Active |
+| Active | Discontinued, Withdrawn |
+| Discontinued | Withdrawn |
+| Withdrawn | *(terminal)* |
+
+The allowed set MAY be configurable policy, but the default above is enforced; no transition bypasses the guard.
+
+## Guards
+- Leaving **Draft** requires registration completeness (all required attributes, >= 1 ingredient, >= 1 packaging, valid NDC/dosage form/route/ATC) (see [[domain-driven-design.domain]], [[ndc]], [[terminology]], [[atc]]).
+- Approve/activate/retire are **authorized** actions — only `RegulatoryOfficer` (see [[authorization.domain]]).
+- Retirement is a **logical** state change, never a hard delete (see [[persistence.domain]], [[auditing.domain]]).
+
+## Events
+Each transition emits a domain event (`MedicinalProductSubmittedForReview`/`Approved`/`Activated`/`Discontinued`/`Withdrawn`) and is audit-mandatory (see [[eventing.domain]], [[auditing.domain]]).
+
+## Related
+- [[domain-driven-design.domain]] · [[authorization.domain]] · [[ndc]] · [[terminology]] · [[atc]] · [[eventing.domain]] · [[auditing.domain]] · [[persistence.domain]]

package/assets/docs/domainspecs/pharma/regulatory-compliance.md

@@ -0,0 +1,19 @@
+# Regulatory & Compliance Standards — Pharma
+
+> NON-NEGOTIABLE. Commands: `/aw-spec-specify`, `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+> Umbrella for the compliance requirements — mechanisms live in the linked files.
+
+## Posture
+- Built for **regulatory compliance readiness** — auditability, traceability, data integrity, provenance designed in.
+- GxP-relevant records follow **ALCOA+** (Attributable, Legible, Contemporaneous, Original, Accurate + Complete, Consistent, Enduring, Available).
+
+## Requirements
+- **Audit trail** — immutable records for product creation, modification, retirement, identifier changes, classification changes; each carries User, Timestamp, Action, Previous Value, New Value (see [[auditing.domain]]).
+- **Provenance** — capture source/method/agent/timestamp for externally sourced data (see [[data-provenance]]).
+- **Versioning** — full, queryable version history of product information (see [[persistence.domain]]).
+- **Traceability** — every change to identifiers (NDC), classification (ATC), ingredients, packaging, marketing status, lifecycle is traceable command → event → audit record → version snapshot (see [[eventing.domain]], [[auditing.domain]], [[persistence.domain]]).
+- **Authorized actions** — registration, approval, retirement are authorized operations (see [[authorization.domain]], [[product-lifecycle.domain]]).
+
+## Related
+- [[auditing.domain]] · [[data-provenance]] · [[persistence.domain]] · [[eventing.domain]] · [[product-lifecycle.domain]] · [[authorization.domain]] · [[domain-driven-design.domain]]

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

@@ -0,0 +1,32 @@
+# Terminology Standards — Pharma
+
+> 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`; see [[fhir]]).
+
+## Standard terminologies
+| Concept | Terminology | Conformance |
+|---|---|---|
+| Product / package identity | **NDC** | SHALL (see [[ndc]]) |
+| Substances / active ingredients | **UNII** | SHOULD |
+| Substance / clinical drug | **RxNorm** | SHOULD |
+| Dosage form / route / classification | **SNOMED CT** | SHOULD |
+| Therapeutic classification | **WHO ATC** | SHALL (see [[atc]]) |
+| Units (strength, package qty) | **UCUM** | SHALL |
+
+- **UNII** is the substance identity for IDMP `Substance` alignment (see [[idmp]]) and maps to FHIR `Substance.code`.
+
+## Validation
+- Hard-coded coded literals FORBIDDEN outside the Terminology module's seed data.
+- Never invent NDC/UNII/RxNorm/SNOMED/ATC/UCUM codes — confirm against value sets (see [[ai-rules.domain]]).
+- Invalid dosage forms/routes rejected at validation time; the bound value set is configuration (see [[domain-driven-design.domain]]).
+
+## 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` (subsets; expansions cached from RxNorm/SNOMED/FDA UNII-NDC/WHO ATC).
+- Code-set versions are pinned + recorded; a terminology release (e.g. WHO ATC annual update) is a tracked, audited change (see [[auditing.domain]]).
+
+## Related
+- [[ndc]] · [[atc]] · [[idmp]] · [[fhir]] · [[domain-driven-design.domain]] · [[testing.domain]] · [[ai-rules.domain]]

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

@@ -0,0 +1,19 @@
+# Testing — Pharma Domain Addenda
+
+> Technology base: [[testing]]. Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## What MUST be tested
+- **Aggregate invariants** — required attributes; >= 1 ActiveIngredient; >= 1 PackagingConfiguration; NDC uniqueness + format; invalid dosage forms/routes rejected (see [[domain-driven-design.domain]], [[ndc]], [[terminology]]).
+- **Lifecycle state machine** — every allowed transition passes; every disallowed one is rejected (see [[product-lifecycle.domain]]).
+- **NDC validation** — segment configurations, configurable rules, duplicate detection (see [[ndc]]).
+- **Terminology binding** — ATC/UNII/SNOMED/RxNorm/UCUM validated against value sets; invented codes rejected (see [[terminology]], [[atc]]).
+- **FHIR round-trip** — `domain -> FHIR -> domain` for Medication/MedicationKnowledge/Substance/Organization; FHIR validator passes (CI gate; see [[fhir]]).
+- **Audit & versioning** — every audited op writes an immutable record (User/Timestamp/Action/Previous/New); historical versions remain queryable (see [[auditing.domain]], [[persistence.domain]]).
+- **Provenance** — external imports attach a `ProvenanceRecord` (see [[data-provenance]]).
+
+## Test data & gates
+- Use **synthetic/clearly-marked test NDCs and codes** — never real identifiers that could collide with the FDA NDC directory (see [[persistence.domain]], [[ndc]]); pin the terminology code-set version under test (see [[terminology]]).
+- CI: FHIR validator passes for every modified resource/profile/example; HL7 outbound conformance checked against the internal corpus (see [[hl7]]).
+
+## Related
+- [[testing]] · [[domain-driven-design.domain]] · [[product-lifecycle.domain]] · [[ndc]] · [[terminology]] · [[atc]] · [[fhir]] · [[auditing.domain]] · [[persistence.domain]] · [[data-provenance]] · [[hl7]]

package/assets/docs/domainspecs/pharma/vertical-slices.domain.md

@@ -0,0 +1,17 @@
+# Vertical Slices — Pharma 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 pharma external-protocol adapters:
+```
+Fhir/    Medication / MedicationKnowledge / Substance / Organization projectors   (see [[fhir]])
+Hl7v2/   inbound parsers + outbound emitters (added when a consumer needs them)   (see [[hl7]])
+```
+
+## Rules
+- FHIR resources live in a **parallel projection layer** and **MUST NOT** replace internal `Shared` DTOs; projections, never the system of record (see [[fhir]], [[domain-driven-design.domain]]).
+- Domain DTOs (`MedicinalProductDto`, `ActiveIngredientDto`, `PackagingConfigurationDto`) — no setters, required `init`, base64 `RowVersionBase64` (see [[coding-standards.domain]]).
+
+## Related
+- [[vertical-slices]] · [[fhir]] · [[hl7]] · [[domain-driven-design.domain]] · [[coding-standards.domain]]

package/assets/docs/domainspecs/pharma/zero-trust.domain.md

@@ -0,0 +1,12 @@
+# Zero-Trust — Pharma Domain Addenda
+
+> Technology base: [[zero-trust]]. Commands: `/aw-spec-plan`, `/aw-spec-implement`.
+
+## Rules
+- All registry traffic MUST be TLS-encrypted; commercially-sensitive pre-market data in transit MUST be TLS-protected; at-rest: see [[data-classification.domain]], [[persistence.domain]].
+- FHIR/REST scopes (`system/Medication.read`, `system/*.write` for authorized backends) enforced on every endpoint + propagated through the pipeline. **No patient-context (SMART) launch** — product master data (see [[authorization.domain]], [[fhir]]).
+- Mutating operations **re-check change authority** at the handler edge (only `RegulatoryOfficer` approves/retires; identifier/classification changes are privileged) (see [[authorization.domain]]).
+- Trace context MUST propagate across outbound **FHIR / HL7v2** calls and the CloudEvents stream (see [[eventing.domain]], [[auditing.domain]]).
+
+## Related
+- [[zero-trust]] · [[authorization.domain]] · [[data-classification.domain]] · [[persistence.domain]] · [[auditing.domain]] · [[eventing.domain]] · [[fhir]]