aw-spec-cli 0.1.7 → 0.1.9

package/assets/guardrails/README.md

@@ -0,0 +1,222 @@
+# Guardrails — Index & Rule-Loading Map
+
+Rules live in **shared corpora**, keyed on the one thing that makes them differ: a technical rule
+varies by **stack**, a domain rule varies by **industry**. A **project** owns neither corpus. It
+owns two maps that say which files it loads, plus the handful of files its own team authors.
+
+```
+guardrails/
+├── technology/<stack>/       technical rules — vary by stack, never by industry
+│   ├── dotnet-webapi/            the reference corpus (+ examples/)
+│   ├── nextjs/                   the frontend lane's corpus
+│   └── java-spring/              unauthored — the extension point, worked
+├── domain/<industry>/        domain rules — vary by industry, never by stack
+│   ├── healthcare/
+│   └── pharma/
+└── projects/<project>/       what a project SELECTS
+    └── dotnet-default-project/
+        ├── tech-rule-bindings.md      → technology/dotnet-webapi/ + technology/nextjs/
+        ├── domain-rule-bindings.md    → domain/healthcare/
+        ├── service/technical-requirements.md    PROJECT-SUPPLIED
+        ├── frontend/ui-requirements.md          PROJECT-SUPPLIED
+        └── domain/domain-requirements.md        PROJECT-SUPPLIED
+```
+
+`/appweaver select-domain` selects a **project** folder and stores it in `.appweaver/domain.json`;
+`resolve-tech` and `resolve-domain` read that project's two maps. **To change what a command loads,
+edit the map — never a workflow.** The folder names `technology/` and `domain/` are the only
+vocabulary here: a project's maps may point anywhere, in any combination.
+
+**A directory under `projects/` is a project only if it carries a rule map.** Both shells'
+`list-domains` enforces that, exactly as `foundations/` requires a `*.pack.txt`. Either map
+qualifies, because `onboard` writes the domain map several steps before the technical one.
+
+**A brownfield project owns its rules outright.** `dotnet-default-project` above holds only three
+files because it maps the rest from the shared corpora. A project `onboard` reverse-engineers —
+`projects/brf-<name>/` — holds everything: the domain set in `domain/`, the technical set in
+`service/`, the lane set in `frontend/`, and its own charter at `domain/domain-constitution.md`,
+named the way an industry corpus names its charter. Both maps still sit at the project root, and
+nothing a project owns is written outside its own folder — which is what lets two onboarded
+projects share one workspace.
+
+## Why the corpora are shared
+
+Until 2026-08-18 every rule lived inside a per-industry pack, so the technical corpus was stored
+once per industry. The two shipped packs were measured against each other before the split:
+**31 technical files, ~2455 lines, and after normalising the industry word and line wrapping, all
+31 were the same file.** `technology-constitution.md`'s 40 differing lines were 100% name
+substitution; the Next.js `ui-constitution.md` differed by two. The corpus never varied by
+industry — the storage layout only claimed it did, and the cost was paid on every edit and would
+have been paid again by every new industry.
+
+The split makes the corpus **O(stack + industry)** instead of O(stack × industry). Adding Java
+touches one folder. Adding an industry touches one folder. Neither touches the other, and neither
+touches a workflow.
+
+Nothing about *loading* changed. `resolve-tech` and `resolve-domain` collect the `- ` bullets under
+`## /<command>` and return them verbatim; they never inspected where a path pointed. Only the map's
+own location moved.
+
+## The three tiers
+
+| Set | Mapped under | In | Ratified into |
+|---|---|---|---|
+| technical | `## /aw-spec-constitution` | `tech-rule-bindings.md` | `constitution.technical.md` |
+| frontend | `## /aw-spec-ui-constitution` | `tech-rule-bindings.md` | `constitution.ui.md` |
+| domain | `## /aw-spec-constitution` | `domain-rule-bindings.md` | `constitution.domain.md` |
+
+Every set has the same shape: **the tier's constitution, then the standard rules the corpus shares,
+then the one file the project team authors** — `service/technical-requirements.md`,
+`frontend/ui-requirements.md`, `domain/domain-requirements.md`. Those three are the only mapped
+files expected to differ between two projects on the same corpora, and their mapping is optional: a
+project that has not authored one ratifies the standard set alone.
+
+The constitution is the authority layer; these files are the detail layer it cites.
+
+**Rules and samples are mapped separately.** A rule file states the rule; `technology/<stack>/examples/`
+holds its worked `<SampleProjectName>` sample. The code-generating phases map both. The three
+constitution headings map the rules alone — a ratified half is one declarative line and a `→`
+pointer per principle, so sample code is weight without a reader.
+
+**A file's tier is set by the map that lists it, not by the folder it lives in.**
+`domain/healthcare/ihe-conformance.md` is the live proof: it sits in the domain corpus because IHE
+is a healthcare standard, and it is on the **technical** tier because `tech-rule-bindings.md`
+is what lists it. Infer the tier from the folder and the fold breaks.
+
+## Adding to the tree
+
+- **A stack** — create `technology/<stack-id>/`, author the rules domain-free, map them from a
+  project. See [technology/java-spring/README.md](technology/java-spring/README.md), which is that
+  procedure written out. Use the stack id from `.appweaver/stack-profiles/`, so a lane in
+  `stacks.json` and a rule folder are the same word.
+- **An industry** — create `domain/<industry>/`, author the overlays, point a project's
+  `domain-rule-bindings.md` at it. The technical map needs no edit.
+- **A project** — copy `projects/dotnet-default-project/`, repoint the bullets, replace the three
+  project-supplied files. Nothing outside that folder changes.
+
+## Files — technical (`technology/dotnet-webapi/`)
+
+**Architecture**
+- [clean-architecture.md](technology/dotnet-webapi/clean-architecture.md) — dependency rule, layers, infra boundaries
+- [modular-monolith.md](technology/dotnet-webapi/modular-monolith.md) — module boundaries, cross-module rules, extraction
+- [vertical-slices.md](technology/dotnet-webapi/vertical-slices.md) — feature & folder structure
+- [folder-structure.md](technology/dotnet-webapi/folder-structure.md) — mandatory `src/tests/helm/docs` tree
+- [cqrs.md](technology/dotnet-webapi/cqrs.md) — mediator, Result pattern, transactions
+- [persistence.md](technology/dotnet-webapi/persistence.md) — EF Core, specs, concurrency, tenancy
+- [eventing.md](technology/dotnet-webapi/eventing.md) — CloudEvents, versioning, broker
+- [testing.md](technology/dotnet-webapi/testing.md) — unit/integration/Testcontainers/coverage
+
+**Security**
+- [zero-trust.md](technology/dotnet-webapi/zero-trust.md) — TLS, identity, secrets
+- [authorization.md](technology/dotnet-webapi/authorization.md) — role+scope model, cache policy
+- [authorization-matrix.md](technology/dotnet-webapi/authorization-matrix.md) — role/scope matrix
+- [auditing.md](technology/dotnet-webapi/auditing.md) — observability, structured logging, immutable audit
+- [data-classification.md](technology/dotnet-webapi/data-classification.md) — classification framework, encryption
+
+**Governance**
+- [coding-standards.md](technology/dotnet-webapi/coding-standards.md) — naming, forbidden patterns, CI gates
+- [dependency-policy.md](technology/dotnet-webapi/dependency-policy.md) — package governance, banned packages
+- [api-versioning.md](technology/dotnet-webapi/api-versioning.md) — REST versioning, ETag, OpenAPI/AsyncAPI
+
+**Modelling and packaging**
+- [domain-driven-design.md](technology/dotnet-webapi/domain-driven-design.md) — generic DDD tactical patterns; the one file `specify` may load from this tier
+- [PACKAGING.md](technology/dotnet-webapi/PACKAGING.md) — foundation pack/unpack conventions
+
+**Constitution**
+- [technology-constitution.md](technology/dotnet-webapi/technology-constitution.md) — the ratified technology base, principles I–XV
+
+Each rule file's worked sample sits at [examples/](technology/dotnet-webapi/examples/) under the
+same name.
+
+## Files — frontend (`technology/nextjs/`)
+
+- [ui-constitution.md](technology/nextjs/ui-constitution.md) — the Next.js frontend base, UX-\* principles
+
+Mapping `## /aw-spec-ui-*` in a project's `tech-rule-bindings.md` is what declares that the project
+*has* a frontend lane. With no such heading, `constitution` skips the UI half and creates no file.
+
+## Files — healthcare domain (`domain/healthcare/`)
+
+**Constitution**
+- [domain-constitution.md](domain/healthcare/domain-constitution.md) — the ratified industry base, principles XVI+
+
+**Architecture overlays** — each extends the `technology/<stack>/` file of the same name
+- [folder-structure.domain.md](domain/healthcare/folder-structure.domain.md) — Interop, conformance tests, PHI fixtures
+- [cqrs.domain.md](domain/healthcare/cqrs.domain.md) — PHI-audit behavior
+- [vertical-slices.domain.md](domain/healthcare/vertical-slices.domain.md) — FHIR-HL7-DICOM Interop slice
+- [persistence.domain.md](domain/healthcare/persistence.domain.md) — PHI retention & encryption-at-rest
+- [testing.domain.md](domain/healthcare/testing.domain.md) — FHIR validation & synthetic PHI
+- [eventing.domain.md](domain/healthcare/eventing.domain.md) — healthcare feeds & protocol tracing
+
+**Domain (clinical)**
+- [domain-driven-design.domain.md](domain/healthcare/domain-driven-design.domain.md) — canonical aggregates & invariants
+- [fhir.md](domain/healthcare/fhir.md) — projectors, CapabilityStatement, profiles, Bundle/search, SMART, Bulk Data
+- [terminology.md](domain/healthcare/terminology.md) — ICD/LOINC/SNOMED/RxNorm, coded value objects, terminology service
+- [hl7.md](domain/healthcare/hl7.md) — HL7 v2 ingestion/egress, adapters, MLLP
+- [dicom.md](domain/healthcare/dicom.md) — DICOMweb, PACS/VNA boundary, metadata-only persistence
+- [consent.md](domain/healthcare/consent.md) — consent enforcement, break-the-glass, FHIR Consent
+- [hipaa.md](domain/healthcare/hipaa.md) — PHI handling, audit, retention, minimum-necessary, breach handling
+- [ihe-conformance.md](domain/healthcare/ihe-conformance.md) — interoperability conformance profiles; on the **technical** tier
+
+**Security overlays**
+- [zero-trust.domain.md](domain/healthcare/zero-trust.domain.md) — PHI transport, SMART tokens, ATNA node auth
+- [authorization.domain.md](domain/healthcare/authorization.domain.md) — clinical roles, SMART scopes, consent, break-the-glass
+- [auditing.domain.md](domain/healthcare/auditing.domain.md) — ATNA, FHIR AuditEvent, PHI audit
+- [data-classification.domain.md](domain/healthcare/data-classification.domain.md) — PHI/PII/PCI taxonomy, de-identification
+
+**Governance overlays**
+- [coding-standards.domain.md](domain/healthcare/coding-standards.domain.md) — FHIR & PHI patterns and gates
+- [dependency-policy.domain.md](domain/healthcare/dependency-policy.domain.md) — HIPAA suitability, healthcare libs
+- [api-versioning.domain.md](domain/healthcare/api-versioning.domain.md) — FHIR versioning, CapabilityStatement
+
+**Experience (`ux/`)** — mapped under `## /aw-spec-specify` on the **technical** tier, like
+`ihe-conformance.md`: they govern how `specify` states the experience, and the spec's Experience
+Scope + Experience Standards (`UX-`) are what `prototype`, `ui-design` and `ui-implement` author
+and verify against. Each carries a "What must NOT appear" section — that is what keeps screens,
+pages and components out of the spec.
+- [ux/journey-mapping.md](domain/healthcare/ux/journey-mapping.md) — a journey is a `US-n`; outcome not click-path; interruption and hand-off
+- [ux/interaction-states.md](domain/healthcare/ux/interaction-states.md) — which states must be handled; the `UX-` standard vs the EARS `FR-` behaviour
+- [ux/accessibility-standards.md](domain/healthcare/ux/accessibility-standards.md) — conformance target, AT floor, keyboard-completable `US-n`, waiver discipline
+- [ux/content-design.md](domain/healthcare/ux/content-design.md) — ubiquitous language, actionable errors, verbatim regulated wording, units and provenance
+
+**Glossary**
+- [clinical-terms.md](domain/healthcare/clinical-terms.md) — MRN, Encounter, Observation, Coverage, etc.
+- [integration-terms.md](domain/healthcare/integration-terms.md) — HL7, FHIR, DICOM, PIX/PDQ, ATNA, MHD, XDS
+- [ai-rules.domain.md](domain/healthcare/ai-rules.domain.md) — PHI masking, codes, FHIR, security-edit limits
+
+## Files — pharma domain (`domain/pharma/`)
+
+The same shape with its own files — NDC/IDMP/ATC identity, product lifecycle, data provenance,
+regulatory compliance. **No shipped project maps it**, so it is the second corpus a reader can
+compare against, and the one to repoint a `domain-rule-bindings.md` at to see the swap work.
+[domain-requirements.sample.md](domain/pharma/domain-requirements.sample.md) is the
+Medicinal-Product-Registration enumeration a pharma project would copy into its own
+`domain/domain-requirements.md`; it is a sample, not a rule, and no map lists it.
+
+## Naming convention
+
+- **`technology/<stack>/<name>.md`** — technical rules: architecture, security, governance,
+  conventions, code generation. Domain-free, and on the **technical** tier because
+  `tech-rule-bindings.md` is what lists them.
+- **`domain/<industry>/<name>.domain.md`** — a domain overlay extending the `technology/` file of
+  the same name.
+- **`domain/<industry>/<name>.md`** — inherently domain (FHIR, HIPAA, NDC, terminology…).
+
+## What is not here
+
+The universal AI operating rules are the kit's own, at `.appweaver/ai-rules.md`, and belong to no
+project — a project that could switch them off is a project the kit can make no promise about.
+The pre-pack seed the brownfield flows once read is deleted: `inventory`, `onboard` and `adopt` run
+against a repository that has no project yet, and each carries the vocabulary it needs in its own
+prompt rather than reading one project's house style as the shape to look for.
+
+Everything this tree once held that governance does not load left it on 2026-08-18, for
+`foundations/<stack>/`:
+
+- **Scaffold corpora** — `foundations/dotnet/ModularMonolith/` and `foundations/dotnet/VerticalSlice/`:
+  a `<Name>.pack.txt` payload and the scripts that pack and unpack it, read by
+  `/appweaver foundation`.
+- **Framework component runbooks** — `foundations/dotnet/components/`: the integration contracts
+  `/appweaver add-component` follows when wiring an opt-in component into a scaffolded project.
+
+Both describe code to write, which is the opposite of a rule constraining what may be written.

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

@@ -0,0 +1,34 @@
+# AI Operational Rules — Healthcare 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 ICD/SNOMED/LOINC/CPT codes (see [[terminology]]).
+
+## Generation
+- A complete slice adds a FHIR projector + FHIR-validator test when applicable (see [[fhir]], [[testing.domain]]).
+- Generated FHIR resources MUST honor declared IG profiles and pass the FHIR validator (see [[fhir]]).
+- Comments are reserved for clinical intent (generic rule in [[ai-rules]]).
+
+## PHI masking
+- MUST NOT log, echo, or commit any field of `Patient`/`Encounter`/`Observation`/`MedicationRequest`/`ClinicalNote`/`DiagnosticReport`/`Claim`/`Coverage` other than the strongly-typed ID.
+- Apply field-level redaction in every generated example payload (see [[data-classification.domain]], [[hipaa]]).
+
+## Tests
+- MUST use the synthetic-PHI fixture library (`<SampleProjectName>.TestFixtures`); never inline fabricated PHI.
+- Never invent ICD/SNOMED/LOINC/CPT/HCPCS/RxNorm/CVX codes — use a sentinel constant (see [[testing.domain]], [[terminology]]).
+
+## Security-touching code
+- MUST NOT modify authorization handlers, scope evaluators, consent checks, audit emitters, or encryption code without an explicit security-reviewer-attached prompt (see [[authorization.domain]], [[auditing.domain]], [[consent]]).
+- FHIR profile changes: regenerate the IG artifacts + CapabilityStatement in the **same commit** (see [[fhir]], [[api-versioning.domain]]).
+
+## Refusal conditions — extend [[ai-rules]]; refuse to:
+- Embed any PHI test fixture in code/config.
+- Disable a consent check globally.
+- Bypass Interop adapters by writing aggregates directly from an external feed (see [[hl7]], [[eventing.domain]]).
+- Generate de-identification logic without a documented method (Safe Harbor / Expert Determination) (see [[hipaa]]).
+- Return PHI in error messages, logs, or trace attributes (see [[data-classification.domain]]).
+
+## Related
+- [[ai-rules]] · [[fhir]] · [[terminology]] · [[hipaa]] · [[consent]] · [[data-classification.domain]] · [[auditing.domain]] · [[authorization.domain]] · [[testing.domain]]

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

@@ -0,0 +1,17 @@
+# API Versioning — Healthcare Domain Addenda (FHIR)
+
+> Technology base: [[api-versioning]]. Commands: `/aw-spec-specify`, `/aw-spec-gate`.
+
+## FHIR versioning
+- R4 default; R5 is **additive** under a versioned path (`/fhir/R5/...`).
+- Breaking FHIR changes require a **new version path** + a published CapabilityStatement diff (see [[fhir]]).
+- FHIR list endpoints use Bundle/searchset semantics (`_count`, `_offset`/`_page`, `_total`).
+
+## 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/AsyncAPI); regenerates cleanly in CI; diff reviewed for breaking changes (see [[fhir]], [[coding-standards.domain]]).
+
+## Related
+- [[api-versioning]] · [[fhir]] · [[persistence.domain]] · [[coding-standards.domain]]

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

@@ -0,0 +1,97 @@
+# Auditing — Healthcare Domain Addenda (ATNA)
+
+> 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** for entity state-change auditing; 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.
+- Beyond state-change auditing, healthcare additionally requires **PHI access (read) auditing** —
+  a separate mandatory concern (see below), not one of the two write-levels.
+
+> 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:
+
+- Every **PHI-bearing main aggregate** of the requirement → **Advanced** (regulated PHI change
+  history requires field-level before/after).
+- **Supporting aggregates** (collaborating/referenced roots, no PHI) → **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 — `<PHIAggregate>` uses **Advanced** (field-level before/after)
+> auditing; `<SupportingAggregate…>` use **Basic** (lifecycle) auditing; all PHI access and change
+> 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).
+
+## PHI access auditing (ATNA — mandatory)
+
+Distinct from state-change auditing: every PHI **read/access**, authentication, consent change,
+export, and break-the-glass MUST emit an audit event (a PHI-access-audit pipeline behavior runs on
+every mediator request). Audit-mandatory triggers:
+
+- Every PHI **read** and **write**; every authentication; every consent change; every export
+  (`$export`, bulk / report download); every **break-the-glass**; every privileged admin action;
+  every IdP / role change. See [[authorization.domain]].
+
+## 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:
+
+- `timestamp`, acting `subjectId` (user), `action`, `resourceType`, `resourceId`, `sourceIp`,
+  `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 PHI access/change is **audit-mandatory** and **append-only**; and the
+  ATNA business capture — **patientId** (whose PHI), **subjectRole**, **outcome** (grant/deny),
+  **reason** (break-the-glass justification), and **Previous Value / New Value** (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/subject, by tenant, and
+by action/time with paging — see [[auditing]]). A spec "queryable audit trail for compliance /
+ATNA review" 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.
+
+## Retention & format
+
+- **Append-only**; retained **>= 6 years**; exportable as FHIR `AuditEvent` (see
+  [[domain-driven-design.domain]], [[persistence.domain]]).
+
+## Telemetry & breach
+
+- **PHI, full SSN, payment-card numbers, government IDs MUST NEVER** appear in logs, metric labels,
+  exception messages, or traces (see [[data-classification.domain]]).
+- Anomalous PHI access (volume spikes, off-hours mass reads, repeated denials) emits **Critical**
+  alerts (see [[hipaa]]).
+
+## Related
+- [[auditing]] · [[hipaa]] · [[data-classification.domain]] · [[authorization.domain]] · [[consent]] · [[fhir]] · [[cqrs.domain]] · [[persistence.domain]] · [[domain-driven-design.domain]]

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

@@ -0,0 +1,26 @@
+# Authorization — Healthcare Domain Addenda
+
+> Technology base: [[authorization]]. Commands: `/aw-spec-constitution`, `/aw-spec-specify`, `/aw-spec-gate`.
+
+## Roles
+`SystemAdmin`, `ComplianceOfficer`, `Physician`, `Nurse`, `LabTechnician`, `Radiologist`, `Pharmacist`, `BillingClerk`, `FrontDesk`, `Patient`, `ExternalSystem`, `ResearchAnalyst` (de-identified scope only). Per-route matrix: `guardrails/technology/dotnet-webapi/authorization-matrix.md`.
+
+## SMART-on-FHIR scopes
+- Scopes (`patient/*.read`, `user/Observation.read`, `system/*.write`, `launch/patient`) MUST be enforced on **every FHIR endpoint**.
+- App launch (EHR + standalone): **PKCE mandatory; implicit flow FORBIDDEN** (see [[fhir]]).
+
+## PHI minimum-necessary
+- The PHI-access pipeline returns only fields the caller's role + scopes authorize; field-level redaction lives in projection extensions (see [[hipaa]], [[data-classification.domain]]).
+
+## Consent & break-the-glass
+- Pipeline checks **consent state** before releasing PHI outside the treating-provider context (see [[consent]]).
+- Break-the-glass = explicit emergency-access command: documented reason + high-priority audit + real-time alert (see [[consent]], [[auditing.domain]]).
+
+## Audit-mandatory
+Every PHI read/write, authentication, consent change, export, break-the-glass, privileged admin action, IdP/role change (see [[auditing.domain]]).
+
+## Anonymous allowlist
+- Adds `/metadata` (FHIR CapabilityStatement) to the generic allowlist (see [[fhir]]).
+
+## Related
+- [[authorization]] · [[hipaa]] · [[consent]] · [[auditing.domain]] · [[data-classification.domain]] · [[fhir]]

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

@@ -0,0 +1,20 @@
+# Glossary — Clinical Terms
+
+> Ubiquitous language for clinical aggregates. Commands: `/aw-spec-constitution`, `/aw-spec-specify`. See [[domain-driven-design.domain]] (modeling) + [[terminology]] (coding).
+
+| Term | Definition |
+|---|---|
+| **MRN** | Patient identifier, **unique per tenant** on `Patient` (Patients); cross-referenced via PIX/PDQ (see [[integration-terms]]). |
+| **Encounter** | Clinical interaction (inpatient/outpatient/emergency); owns Admission/Transfer/Discharge; not Closeable with open Orders/Results/ChargeItems/unsigned ClinicalNotes (Encounters). |
+| **Observation** | A discrete measurement/finding — vitals/social history (EMR) or lab result (Lab); coded LOINC/SNOMED (see [[terminology]]). |
+| **Coverage** | Patient insurance record (Insurance); required (or documented self-pay) before admission. |
+| **PractitionerRole** | A Practitioner's role within an Organization/Location (Identity) — drives role-based auth (see [[authorization.domain]]). |
+| **CarePlan** | A planned set of clinical activities (EMR). |
+| **DiagnosticReport** | A finalized result set with interpretation — radiology (Radiology) or lab (Lab). |
+| **ClinicalNote** | Documentation entry; once **Signed** immutable; corrections are addenda; deletion forbidden (supersede via Amend). |
+| **ProblemList / AllergyIntolerance / MedicationStatement / Immunization / Procedure / ServiceRequest** | EMR aggregates; coded SNOMED/ICD/RxNorm/CVX as applicable. |
+| **MedicationRequest / MedicationDispense / MedicationAdministration** | Pharmacy aggregates; dispense blocked on allergy/interaction/contraindication without documented override. |
+| **Consent** | First-class aggregate governing PHI disclosure; withdrawal blocks disclosure immediately (see [[consent]]). |
+
+## Related
+- [[integration-terms]] · [[domain-driven-design.domain]] · [[terminology]] · [[fhir]]

package/assets/guardrails/domain/healthcare/coding-standards.domain.md

@@ -0,0 +1,26 @@
+# Coding Standards — Healthcare Domain Addenda
+
+> Technology base: [[coding-standards]]. Commands: `/aw-spec-gate`.
+
+## Coded value objects
+- Follow the FHIR pattern: `Codeable`, `Coding`, `Quantity`, `Period`, `Range`, `Ratio`, `Identifier`, `HumanName`, `Address`, `ContactPoint` (see [[terminology]]).
+- The Domain may additionally throw `ConsentDeniedException` (see [[consent]]).
+
+## Forbidden patterns — extend [[coding-standards]]
+- **H1.** Hard delete of any clinical/financial/audit/PHI-bearing aggregate (see [[persistence.domain]]).
+- **H2.** Hard-coded IdP issuer / FHIR server / HL7 endpoint URLs, or PHI test fixtures, in source.
+- **H3.** Logging/emitting any PHI element, full SSN/government ID (see [[data-classification.domain]]).
+- **H4.** Storing patient data (names, MRNs, DOBs, diagnoses, meds, labs, imaging) as free text when a coded vocabulary applies (see [[terminology]]).
+- **H5.** A second FHIR write path bypassing the canonical aggregate (see [[fhir]]).
+- **H6.** Storing/transmitting PHI to any non-production environment (see [[hipaa]]).
+- **H7.** FHIR errors not using `OperationOutcome` with HTTP 422 (see [[fhir]]).
+
+## Quality gates — extend [[coding-standards]]
+- **HG1.** FHIR CapabilityStatement regenerates cleanly; diff reviewed (see [[fhir]]).
+- **HG2.** FHIR validator passes for every modified resource/profile/example.
+- **HG3.** Grep: no PHI string literals in tests outside sanctioned fixtures; no MediatR/AutoMapper.
+- **HG4.** PHI-logging analyzer passes — no Patient/Encounter/Observation/MedicationRequest field logged except the ID (see [[data-classification.domain]]).
+- **HG5.** Security-reviewer sign-off for any PHI-access change.
+
+## Related
+- [[coding-standards]] · [[terminology]] · [[fhir]] · [[hipaa]] · [[consent]] · [[data-classification.domain]] · [[persistence.domain]]

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

@@ -0,0 +1,19 @@
+# Consent Standards
+
+> NON-NEGOTIABLE. Commands: `/aw-spec-constitution`, `/aw-spec-specify`.
+
+## First-class aggregate
+- Consent is a **first-class aggregate** (Patients module). A **withdrawn consent MUST block downstream PHI disclosure** for the purpose-of-use **immediately**; state changes emit `ConsentChangedEvent` (see [[eventing]]).
+- The access-control pipeline **MUST check consent before releasing PHI** outside the treating-provider context. Denial surfaces as `ConsentDeniedException` from the Domain (see [[domain-driven-design.domain]], [[authorization.domain]]).
+
+## Break-the-glass
+- Explicit **emergency-access command**: documented reason + high-priority audit + real-time alert; audit-mandatory (see [[auditing.domain]]).
+
+## Restriction-of-processing
+- GDPR restriction (Art. 18) + erasure (Art. 17) are first-class audited commands. Where law forbids erasing medical records, **restriction-of-processing is the fallback** (see [[hipaa]], [[persistence.domain]]).
+
+## FHIR mapping
+- **BPPC** + **FHIR Consent** profiles honored; Consent projects to the FHIR `Consent` resource (see [[fhir]]).
+
+## Related
+- [[hipaa]] · [[authorization.domain]] · [[auditing.domain]] · [[fhir]] · [[domain-driven-design.domain]]

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

@@ -0,0 +1,12 @@
+# CQRS — Healthcare Domain Addenda
+
+> Technology base: [[cqrs]]. Commands: `/aw-spec-specify`, `/aw-spec-gate`.
+
+## Pipeline
+- Append a **PHI-access-audit behavior** to the mediator pipeline (beyond generic logging + FluentValidation): emit an audit record for every command/query touching PHI (see [[auditing.domain]]).
+
+## Error codes
+Dot-namespaced slugs (see [[cqrs]]). Examples: `patient.not_found` · `claim.duplicate_submission` · `consent.denied` · `concurrency.conflict`.
+
+## Related
+- [[cqrs]] · [[auditing.domain]] · [[hipaa]] · [[domain-driven-design.domain]]

package/assets/guardrails/domain/healthcare/data-classification.domain.md

@@ -0,0 +1,28 @@
+# Data Classification — Healthcare Domain Addenda
+
+> Technology base: [[data-classification]]. NON-NEGOTIABLE. Commands: `/aw-spec-constitution`, `/aw-spec-specify`, `/aw-spec-gate`.
+
+## Categories
+| Class | Extra rules |
+|---|---|
+| **PHI** (clinical, demographic, identifiers) | Minimum-necessary; audited; encrypted |
+| **PII** (non-clinical identifiers) | Encrypted; minimum-necessary |
+| **PCI** (payment) | **Out of scope** — route to a PCI-DSS processor |
+| **Behavioral Health** (42 CFR Part 2) | Extra-sensitive; field-level encryption |
+| **Genetic** (GINA) | Extra-sensitive |
+| **Pediatric** (minors) | Extended retention; heightened protection |
+
+## Field-level encryption (required)
+SSN, government IDs, payment-card data, behavioral-health flags (see [[hipaa]], [[persistence.domain]]).
+
+## Logging
+- **NEVER** log/emit any PHI element, full SSN, government ID, or full payment-card data.
+- PHI-logging analyzer (CI gate): no Patient/Encounter/Observation/MedicationRequest field logged except the ID (see [[coding-standards.domain]]).
+
+## Export
+- Analytics/research/non-prod exports MUST pass **Safe-Harbor or Expert-Determination** de-identification.
+- **Production PHI in non-production is FORBIDDEN** (see [[hipaa]], [[testing.domain]]).
+- Bulk `$export` gated by authorization + de-identification (see [[fhir]]).
+
+## Related
+- [[data-classification]] · [[hipaa]] · [[auditing.domain]] · [[authorization.domain]] · [[persistence.domain]] · [[coding-standards.domain]]

package/assets/guardrails/domain/healthcare/dependency-policy.domain.md

@@ -0,0 +1,11 @@
+# Dependency Policy — Healthcare Domain Addenda
+
+> Technology base: [[dependency-policy]]. Commands: `/aw-spec-gate`.
+
+## Reviews & libraries
+- Every new dependency gets a **HIPAA-suitability** review beyond the generic license/supply-chain check — e.g. reject a logging package that ships analytics by default (PHI-exfiltration risk) (see [[hipaa]], [[data-classification.domain]]).
+- FHIR: the **official FHIR .NET SDK**, version-matched to the endpoint (R4/R5; see [[fhir]]).
+- HL7 v2 / DICOM libraries are added **only** on explicit developer request — no AI-introduced healthcare-protocol dependencies (see [[hl7]], [[dicom]], [[ai-rules.domain]]).
+
+## Related
+- [[dependency-policy]] · [[fhir]] · [[hl7]] · [[dicom]] · [[hipaa]] · [[ai-rules.domain]]

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

@@ -0,0 +1,15 @@
+# DICOM Standards
+
+> Commands: `/aw-spec-constitution`, `/aw-spec-specify`.
+
+## DICOMweb façade
+- Supported via a **DICOMweb façade** — **QIDO-RS** (query), **WADO-RS** (retrieve), **STOW-RS** (store) — fronting a separately deployed PACS/VNA. Adapters live in `{Module}/Interop/Dicom/` (Radiology only).
+- The PACS/VNA endpoint is an Aspire resource referenced via `.WithReference(...)`; hosts/ports discovered through Aspire, never hard-coded.
+
+## Metadata only
+- **Only DICOM METADATA is persisted here** — pixel data lives in the PACS/VNA, referenced by study/series/instance UIDs.
+- Radiology aggregates: `ImagingOrder`, `ImagingStudy` (metadata), `DiagnosticReport`; results surface via FHIR projections (`ImagingStudy`, `DiagnosticReport`; see [[fhir]]).
+- Trace context propagates across DICOM outbound calls (see [[auditing]]).
+
+## Related
+- [[fhir]] · [[integration-terms]] · [[domain-driven-design]]