aw-spec-cli 0.1.8 → 0.1.9

package/assets/guardrails/domain/pharma/api-versioning.domain.md

@@ -0,0 +1,20 @@
+# API Versioning — Pharma Domain Addenda (FHIR)
+
+> Technology base: [[api-versioning]]. Commands: `/aw-spec-specify`, `/aw-spec-gate`.
+
+## 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/guardrails/domain/pharma/atc.md

@@ -0,0 +1,22 @@
+# ATC — WHO Anatomical Therapeutic Chemical Classification
+
+> NON-NEGOTIABLE. Commands: `/aw-spec-constitution`, `/aw-spec-specify`.
+
+## 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/guardrails/domain/pharma/auditing.domain.md

@@ -0,0 +1,90 @@
+# Auditing — Pharma Domain Addenda
+
+> Technology base: [[auditing]]. NON-NEGOTIABLE. Consumed by `/aw-spec-specify` (LIFTS the
+> auditing requirement into the spec) and `/aw-spec-gate` (VALIDATES the spec/design realise it).
+> `/aw-spec-design` and `/aw-spec-implement` never load this file — auditing reaches them through
+> the spec's **declared audit level per aggregate**, and the enablement mechanics live in the
+> technical base [[auditing]]. Keep this file technology-agnostic (levels + rules, **no code**).
+
+## Two auditing levels (framework-supported)
+
+AppWeaver auditing has exactly **two levels**; the framework's audit interceptor populates every
+audit field automatically (handlers NEVER assign audit fields):
+
+| Level | Captures | Depth |
+|---|---|---|
+| **Basic** | who/when lifecycle — created / modified / (soft-)deleted, by whom and when; one audit entry per aggregate root per save (who · action · resource type · resource id · timestamp · correlation) | entity-level (Created/Updated/Deleted) — **no** before/after values |
+| **Advanced** | everything Basic captures **plus field-level before/after** — each changed property's previous → new value | entity-level **+ property-level previous/new value** |
+
+- **Advanced is REQUIRED whenever the spec asks for "previous value / new value"** — before/after
+  values exist ONLY at the Advanced tier.
+- Child entities fold their changes into the owning aggregate root's audit entry.
+
+> Code realisation — marker interfaces (Basic = `IAuditedObject` / `IFullAuditedObject`; Advanced =
+> `+ IFieldAudited`), the one-time composition, and the audit query API — lives in the technical
+> base. See [[auditing]]; `/aw-spec-design` and `/aw-spec-implement` get the HOW from there.
+
+## Aggregate assignment rule (how specify decides the level)
+
+`/aw-spec-specify` MUST assign an audit level to every aggregate it models and LIFT it into the
+spec as an explicit, developer-editable declaration:
+
+- The **main aggregate** of the requirement (the aggregate root the story is about) → **Advanced**.
+- **Supporting aggregates** (collaborating/referenced roots) → **Basic** by default.
+- A developer MAY raise or lower a level afterwards by editing the spec declaration — the level is
+  a **spec** decision, never a design or implementation one. `/aw-spec-design` then follows the
+  declared level.
+
+Lift it as one line the gate can check, e.g. under Constraints:
+
+> **CN-0xx**: Auditing level — `<MainAggregate>` uses **Advanced** (field-level before/after)
+> auditing; `<SupportingAggregate…>` use **Basic** (lifecycle) auditing; creation is
+> audit-mandatory and append-only. — lifted from auditing.domain.
+
+Declare the **level** — do NOT enumerate the audit record's field shape in the spec (next section).
+
+## Spec-required vs framework-emitted (what the gate checks)
+
+The audit record's field shape is **framework-emitted** — the interceptor populates it; it is NOT
+spec-authored content. Fields the platform always supplies:
+
+- `resourceType`, `resourceId`, `correlationId`, `tenantId`, and the physical record layout.
+
+Split for the gate:
+
+- **Spec-required** (specify lifts it; the gate checks the spec + design carry it): the **audit
+  level per aggregate**; that creation is **audit-mandatory** and **append-only**; and the
+  business-meaningful capture — **User, Timestamp, Action, Previous Value, New Value** (the last
+  two imply Advanced).
+- **Framework-emitted** (NEVER a spec/design gap — always populated by the platform): the fields
+  listed above. The gate MUST NOT raise a LIFT-FAILURE for them; they are guaranteed by the
+  framework, not authored in the spec.
+
+## Queryable audit (framework-provided)
+
+The audit store is queryable out of the box (by resource identity, by user, by tenant, and by
+action/time with paging — see [[auditing]]). A spec "queryable creation audit record for
+compliance" success criterion is therefore satisfied by the framework's audit query API; design
+references it and does **NOT** need a bespoke audit read port/model.
+
+## Setup (pharma)
+
+- Auditing is **MANDATORY** for `MedicinalProduct` (**Advanced**) and its child entities
+  (`ActiveIngredient`, `PackagingConfiguration`, `MarketingAuthorization` — folded into the
+  product's audit entry).
+- 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]]).
+
+## Immutability & retention
+
+- Audit records (log · entity change · property change) are **append-only** — no update, no 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/guardrails/domain/pharma/authorization.domain.md

@@ -0,0 +1,25 @@
+# Authorization — Pharma Domain Addenda
+
+> Technology base: [[authorization]]. Commands: `/aw-spec-constitution`, `/aw-spec-specify`, `/aw-spec-gate`.
+
+## Roles
+`SystemAdmin`, `RegulatoryOfficer`, `ProductSteward`, `TerminologyManager`, `DataManager`, `ReadOnlyConsumer`, `ExternalSystem`. Per-route matrix: `guardrails/technology/dotnet-webapi/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/guardrails/domain/pharma/coding-standards.domain.md

@@ -0,0 +1,28 @@
+# Coding Standards — Pharma Domain Addenda
+
+> Technology base: [[coding-standards]]. Commands: `/aw-spec-gate`.
+
+## 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/guardrails/domain/pharma/cqrs.domain.md

@@ -0,0 +1,16 @@
+# CQRS — Pharma Domain Addenda
+
+> Technology base: [[cqrs]]. Commands: `/aw-spec-specify`, `/aw-spec-gate`.
+
+## 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/guardrails/domain/pharma/data-classification.domain.md

@@ -0,0 +1,24 @@
+# Data Classification — Pharma Domain Addenda
+
+> Technology base: [[data-classification]]. Commands: `/aw-spec-constitution`, `/aw-spec-specify`, `/aw-spec-gate`.
+
+> 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/guardrails/domain/pharma/data-provenance.md

@@ -0,0 +1,21 @@
+# Data Provenance Standards — Pharma
+
+> NON-NEGOTIABLE. Commands: `/aw-spec-constitution`, `/aw-spec-specify`.
+
+## 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/guardrails/domain/pharma/dependency-policy.domain.md

@@ -0,0 +1,11 @@
+# Dependency Policy — Pharma Domain Addenda
+
+> Technology base: [[dependency-policy]]. Commands: `/aw-spec-gate`.
+
+## 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/guardrails/domain/pharma/domain-constitution.md

@@ -0,0 +1,113 @@
+# Domain Constitution — pharma
+
+> 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 pharmaceutical: 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**: authoritative system of record for medicinal product data — product
+  registration, lifecycle state, and the identifiers other systems resolve against.
+- **Bounded contexts**: product registration · substance & composition · regulatory submission
+  & lifecycle · classification & coding · interoperability.
+- **Consumers**: regulatory affairs, supply-chain partners, and downstream clinical systems,
+  all through the published API and projections — never the database.
+
+## Regulatory Regime
+
+- **GxP** — the system is validated; a change to a regulated behaviour is a documented,
+  approved change, not a deployment.
+- **21 CFR Part 11 / EU Annex 11** — electronic records and electronic signatures.
+- **IDMP (ISO 11615/11616/11238/11239/11240)** — the identification of medicinal products.
+- **DSCSA / EU FMD** — traceability and serialization obligations on distribution data.
+- Retention is regulator-set, exceeds the product's commercial life, and outranks any
+  deletion request the platform can otherwise honour.
+
+## Domain Principles (XVI+)
+
+### XVI — Product Identity is Multi-Coded and Authoritative (NON-NEGOTIABLE)
+*Extends III (Domain-Driven Design).* A medicinal product carries its regulatory identifiers as
+validated value objects, never as free strings; an unrecognised or unverifiable code is a
+rejected write, not a stored one.
+→ `guardrails/domain/pharma/ndc.md`, `idmp.md`, `atc.md`
+
+### XVII — Lifecycle State is Explicit and Guarded (NON-NEGOTIABLE)
+*Extends III (Domain-Driven Design).* Registration state lives on the aggregate as a modelled
+transition with an approver and an effective date; no handler infers state, and no transition
+happens without the invariant that permits it.
+→ `guardrails/domain/pharma/product-lifecycle.domain.md`
+
+### XVIII — Data Integrity is ALCOA+ (NON-NEGOTIABLE)
+*Extends X (Observability).* Every regulated value is attributable, legible, contemporaneous,
+original and accurate: provenance travels with the data, corrections are versioned records, and
+regulated data is never destructively overwritten or hard-deleted.
+→ `guardrails/domain/pharma/data-provenance.md`, `auditing.domain.md`
+
+### XIX — Electronic Records Carry Electronic Signatures (NON-NEGOTIABLE)
+*Extends IX (Security by Default).* A regulated approval is a signed record — signer identity,
+meaning of the signature, and timestamp bound to the record — and the signature is verifiable
+for the full retention period.
+→ `guardrails/domain/pharma/regulatory-compliance.md`, `auditing.domain.md`
+
+### XX — Interoperability Surfaces are Contract-First
+*Extends XIV (Single Source of Truth).* FHIR and HL7 surfaces are published, versioned
+contracts generated from the domain model; an inbound feed is adapted at the boundary and never
+allowed to shape an aggregate.
+→ `guardrails/domain/pharma/fhir.md`, `hl7.md`
+
+### XXI — Regulated Data is Classified Before it is Stored (NON-NEGOTIABLE)
+*Extends IX (Security by Default).* Every field carrying commercially confidential or
+submission-restricted content is classified at design time; classification drives encryption,
+masking, export eligibility and log redaction — no field is classified after the fact.
+→ `guardrails/domain/pharma/data-classification.domain.md`, `authorization.domain.md`
+
+### XXII — The Ubiquitous Language is the Domain Glossary
+*Extends III (Domain-Driven Design).* Aggregates, endpoints and DTOs use the corpus's terms; a
+term the glossary does not define is a modelling gap routed back to specify, never a locally
+invented synonym.
+→ `guardrails/domain/pharma/terminology.md`, `pharma-terms.md`
+
+### XXIII — Generation Refuses Where the Domain Requires a Human
+*Extends the AI operational rules.* An agent may not invent a regulatory code, a lifecycle
+transition, a retention period or a signature semantic; where the rule files are silent the
+generation stops and asks.
+→ `guardrails/domain/pharma/ai-rules.domain.md`
+
+## Domain Folder Additions
+
+Additions to the technology base's mandatory structure — Interop adapters per published
+surface, regulatory control fixtures, and domain test data — are governed by
+`guardrails/domain/pharma/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 Regulatory Affairs approver named for the project.
+- A change to a published interoperability surface, a retention period, or a signature semantic
+  triggers regulatory 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/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`.
+
+## 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/guardrails/domain/pharma/domain-requirements.sample.md

@@ -0,0 +1,103 @@
+# DOMAIN REQUIREMENTS (project-specific)
+
+> Project-specific input, **authored by the project owner** and updated independently per
+> project. It is the last file in the set mapped under `## /aw-spec-constitution` in
+> `domain-rule-bindings.md`, and the only one there expected to differ between two projects on this
+> corpus; the standard industry rules beside it are shared. Its mapping is optional — a project
+> that has not authored it yet ratifies the standard set alone.
+>
+> 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]                      -> guardrails/domain/pharma/ndc.md
+[DOMAIN: Standards — ISO IDMP]                 -> guardrails/domain/pharma/idmp.md
+[DOMAIN: Standards — ATC]                      -> guardrails/domain/pharma/atc.md
+[DOMAIN: Standards — Terminology]              -> guardrails/domain/pharma/terminology.md
+[DOMAIN: Interop — FHIR]                       -> guardrails/domain/pharma/fhir.md
+[DOMAIN: Interop — HL7]                        -> guardrails/domain/pharma/hl7.md
+[DOMAIN: Aggregates and Business Invariants]   -> guardrails/domain/pharma/domain-driven-design.domain.md
+[DOMAIN: Product Lifecycle]                    -> guardrails/domain/pharma/product-lifecycle.domain.md
+[DOMAIN: Regulatory / Compliance]              -> guardrails/domain/pharma/regulatory-compliance.md
+[DOMAIN: Data Provenance]                      -> guardrails/domain/pharma/data-provenance.md
+[DOMAIN: Audit Profile]                        -> guardrails/domain/pharma/auditing.domain.md
+[DOMAIN: Persistence / Versioning Profile]     -> guardrails/domain/pharma/persistence.domain.md
+[DOMAIN: Eventing Profile]                     -> guardrails/domain/pharma/eventing.domain.md
+[DOMAIN: Testing Profile]                      -> guardrails/domain/pharma/testing.domain.md
+[DOMAIN: Security Profile]                     -> guardrails/domain/pharma/authorization.domain.md, guardrails/domain/pharma/data-classification.domain.md, guardrails/domain/pharma/zero-trust.domain.md
+[DOMAIN: Coding Standards Profile]             -> guardrails/domain/pharma/coding-standards.domain.md
+[DOMAIN: CQRS / Vertical Slices Profile]       -> guardrails/domain/pharma/cqrs.domain.md, guardrails/domain/pharma/vertical-slices.domain.md
+[DOMAIN: Folder Structure Profile]             -> guardrails/domain/pharma/folder-structure.domain.md
+[DOMAIN: API Versioning Profile]               -> guardrails/domain/pharma/api-versioning.domain.md
+[DOMAIN: Dependency Policy Profile]            -> guardrails/domain/pharma/dependency-policy.domain.md
+[DOMAIN: Integration Terms]                    -> guardrails/domain/pharma/integration-terms.md
+[DOMAIN: AI Policy Addenda]                    -> guardrails/domain/pharma/ai-rules.domain.md
+[DOMAIN: Ubiquitous Language]                  -> guardrails/domain/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/guardrails/domain/pharma/eventing.domain.md

@@ -0,0 +1,18 @@
+# Eventing — Pharma Domain Addenda
+
+> Technology base: [[eventing]]. Commands: `/aw-spec-specify`, `/aw-spec-gate`.
+
+## 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/guardrails/domain/pharma/fhir.md

@@ -0,0 +1,31 @@
+# FHIR Standards — Pharma
+
+> NON-NEGOTIABLE. Commands: `/aw-spec-constitution`, `/aw-spec-specify`.
+
+## 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/guardrails/domain/pharma/folder-structure.domain.md

@@ -0,0 +1,26 @@
+# Folder Structure — Pharma 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, 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
+```
+- 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 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/guardrails/domain/pharma/hl7.md

@@ -0,0 +1,17 @@
+# HL7 Integration Readiness — Pharma
+
+> Commands: `/aw-spec-constitution`, `/aw-spec-specify`.
+
+## 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]]