aw-spec-cli 0.1.0 → 0.1.2

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

@@ -0,0 +1,212 @@
+# Domain-Driven Design Standards (Tactical Patterns)
+
+> Pure technology (domain-agnostic) — generic DDD tactical patterns; the business model, canonical aggregates + invariants are in [[domain-driven-design.domain]]. NON-NEGOTIABLE. Commands: `/aw-spec-specify`, `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+> Note: this file lives under `domain/` because DDD is a domain-modeling methodology, but the
+> rules here are domain-agnostic and reusable. The business-specific model is in the companion
+> `.domain.md`.
+
+## Ubiquitous language & bounded contexts
+
+- Use a consistent ubiquitous language across each bounded context.
+- Each bounded context = one module with `Domain / Features / Persistence / Shared`
+  (see [[modular-monolith]]).
+
+## Aggregate design
+
+- Every entity exposed to the Application layer is reached through an **Aggregate Root**.
+- Aggregate roots implement `IAggregateRoot`, `EntityBase<TId>`, and the
+  audit/soft-delete/concurrency/domain-event interfaces they need:
+  `IFullAuditedObject` or `IAuditableEntityBase`, `ISoftDeletable`, `IConcurrencyTracked`,
+  `IHasDomainEvents`, `INamedEntity<TId>` when listable.
+
+### Aggregate root responsibilities
+
+- Enforce all invariants for the aggregate.
+- Own the lifecycle of its child entities.
+- Raise domain events for state transitions.
+
+### Child entity ownership
+
+- Child entities implement `IAggregateChild` and expose `GetAggregateRoot()`.
+- They are mutated **only** through methods on the aggregate root.
+
+## Transactional / consistency boundaries
+
+- **Transaction boundary equals aggregate boundary**: a single command mutates a single
+  aggregate per transaction.
+- Cross-aggregate effects flow through **domain events** or **follow-up commands**
+  (see [[eventing]], [[cqrs]]).
+
+## Strongly typed IDs
+
+- IDs are **strongly-typed Vogen value objects** (`<Aggregate>Id` as
+  `[ValueObject<Guid>] partial struct`).
+- Raw `Guid` parameters at the Application boundary **MUST be wrapped** at the handler edge.
+
+## Value objects
+
+- Value Objects are **sealed**, have **private constructors**, **validate in the constructor**,
+  throw `DomainException` on invariant violations, and expose a `From(...)` factory.
+
+## Domain events
+
+- Derive from `DomainEventBase`, are immutable, added inside aggregate methods via
+  `AddDomainEvent(...)`, published explicitly by command handlers. See [[eventing]].
+
+## Domain services, repositories, specifications
+
+- Invariants are enforced **inside the aggregate**; validators check request shape only.
+- Repository usage is limited to `IRepository<T>` / `IReadRepository<T>` + `Specification<T>`.
+- Specification pattern: query composition lives in the Domain. See [[persistence]].
+
+## Domain exception handling
+
+- Exceptions are thrown by the Domain only (`DomainException`, `InvariantViolationException`).
+  Application code returns `Result<T>` (see [[cqrs]]).
+
+## Encapsulation, immutability, audit-awareness
+
+- **Rich domain model** — no public setters on aggregates, no business logic in handlers.
+- Soft-delete and audit behavior are first-class on protected aggregates
+  (see [[persistence]], [[auditing]]).
+
+## Anti-patterns (FORBIDDEN)
+
+- **Anemic domain models** — no public setters, no "manager/service" classes mutating
+  aggregate state from outside, no primitive-typed IDs, no business logic in handlers.
+- Cross-aggregate EF navigation properties — reference by strongly-typed ID only.
+- Cross-bounded-context interaction except via Shared DTOs / `IMediator` / anti-corruption
+  adapters.
+
+## Canonical example (agent reference — `<SampleProjectName>` sample)
+
+Aggregate root with a strongly-typed Vogen ID, owned child collection, concurrency token,
+domain events, and an invariant enforced **inside** the aggregate:
+
+```csharp
+// <SampleProjectName>.Service/Projects/Domain/Project.cs
+[ValueObject<Guid>]
+public partial struct ProjectId { }
+
+public class Project :
+    EntityBase<ProjectId>, IAggregateRoot, IFullAuditedObject, IFieldAudited,
+    ISoftDeletable, IConcurrencyTracked, IHasDomainEvents, INamedEntity<ProjectId>
+{
+    private readonly List<ProjectTask> _tasks = new();
+
+    public string Name { get; set; } = default!;               // INamedEntity
+    public ProjectCode Code { get; private set; } = default!;   // value object
+    public ProjectStatus Status { get; private set; }
+    public TaskUserId? OwnerId { get; private set; }            // cross-aggregate ref by ID only
+    public IReadOnlyCollection<ProjectTask> Tasks => _tasks.AsReadOnly();
+
+    public byte[] RowVersion { get; set; } = Array.Empty<byte>();  // IConcurrencyTracked
+
+    private readonly List<DomainEventBase> _domainEvents = new();
+    [NotMapped] public IEnumerable<DomainEventBase> DomainEvents => _domainEvents.AsReadOnly();
+    public void ClearDomainEvents() => _domainEvents.Clear();
+
+    private Project() { }   // EF Core ctor
+
+    public Project(string code, string name, DateOnly startDate, TaskUserId? ownerId)
+    {
+        Id = ProjectId.From(Guid.NewGuid());
+        Code = ProjectCode.From(code);          // VO validates in its ctor
+        Name = ProjectTitle.From(name).Value;
+        Status = ProjectStatus.Planning;
+        OwnerId = ownerId;
+        AddDomainEvent(new ProjectCreatedEvent(Id.Value, Code.Value, Name));
+    }
+
+    // Invariant lives in the aggregate — never in the handler/validator.
+    public ProjectTask AddTask(string title, TaskPriority priority)
+    {
+        if (Status is ProjectStatus.Cancelled or ProjectStatus.Archived)
+            throw new DomainException("Cannot add tasks to a Cancelled or Archived project.");
+        var task = new ProjectTask(Id, title, priority);
+        _tasks.Add(task);
+        AddDomainEvent(new TaskCreatedEvent(Id.Value, task.Id.Value, task.Title.Value));
+        return task;
+    }
+
+    private void AddDomainEvent(DomainEventBase e) => _domainEvents.Add(e);
+}
+```
+
+Value object — sealed, private ctor, validates in the ctor, `From(...)` factory,
+throws `DomainException`:
+
+```csharp
+// <SampleProjectName>.Service/Projects/Domain/ProjectCode.cs
+public sealed class ProjectCode : IEquatable<ProjectCode>
+{
+    private static readonly Regex _valid = new(@"^[A-Z0-9][A-Z0-9\-]{1,14}$", RegexOptions.Compiled);
+    public string Value { get; private set; } = default!;
+
+    private ProjectCode() { }
+    private ProjectCode(string value)
+    {
+        if (string.IsNullOrWhiteSpace(value))
+            throw new DomainException("Project code cannot be empty.");
+        var trimmed = value.Trim().ToUpperInvariant();
+        if (!_valid.IsMatch(trimmed))
+            throw new DomainException("Project code must be uppercase alphanumeric with hyphens.");
+        Value = trimmed;
+    }
+
+    public static ProjectCode From(string value) => new(value);
+    public bool Equals(ProjectCode? o) => o is not null && Value == o.Value;
+    public override bool Equals(object? obj) => Equals(obj as ProjectCode);
+    public override int GetHashCode() => HashCode.Combine(Value);
+}
+```
+
+Child entity — implements `IAggregateChild`, exposes `GetAggregateRoot()`, has only `private`
+setters, and is mutated **only** through methods the parent aggregate calls:
+
+```csharp
+// <SampleProjectName>.Service/Projects/Domain/ProjectTask.cs
+[ValueObject<Guid>]
+public partial struct ProjectTaskId { }
+
+public class ProjectTask : EntityBase<ProjectTaskId>, IAggregateChild
+{
+    public ProjectId ProjectId { get; private set; }            // FK back to the root
+    public TaskTitle Title { get; private set; } = default!;    // value object
+    public ProjectTaskStatus Status { get; private set; }
+    public TaskUserId? AssigneeId { get; private set; }         // cross-aggregate ref by ID
+
+    public Project Project { get; private set; } = default!;    // EF-only nav, private setter
+    public object GetAggregateRoot() => Project;                // IAggregateChild
+
+    private ProjectTask() { }                                   // EF Core ctor
+    public ProjectTask(ProjectId projectId, string title, TaskPriority priority)
+    {
+        Id = ProjectTaskId.From(Guid.NewGuid());
+        ProjectId = projectId;
+        Title = TaskTitle.From(title);
+        Status = ProjectTaskStatus.Open;
+        Priority = priority;
+    }
+
+    // State-machine invariant lives on the child; the parent calls it (project.ChangeTaskStatus).
+    public void ChangeStatus(ProjectTaskStatus newStatus)
+    {
+        if (Status == ProjectTaskStatus.Cancelled)
+            throw new DomainException("A cancelled task cannot be re-opened.");
+        Status = newStatus;
+    }
+
+    public void AssignTo(TaskUserId assigneeId) => AssigneeId = assigneeId;
+}
+```
+
+> The aggregate root mutates children only through its own methods (e.g. `Project.AssignTask`
+> calls `task.AssignTo(...)` and raises the domain event) — callers never touch `ProjectTask`
+> directly. EF mapping for the owned collection is in [[persistence]].
+
+## Related
+
+- [[modular-monolith]] · [[clean-architecture]] · [[cqrs]] · [[persistence]] ·
+  [[eventing]] · [[domain-driven-design.domain]]

package/assets/docs/domainspecs/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/docs/domainspecs/healthcare/api-versioning.domain.md

@@ -0,0 +1,17 @@
+# API Versioning — Healthcare Domain Addenda (FHIR)
+
+> Technology base: [[api-versioning]]. Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## 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/docs/domainspecs/healthcare/auditing.domain.md

@@ -0,0 +1,29 @@
+# Auditing — Healthcare Domain Addenda (ATNA)
+
+> Technology base: [[auditing]]. NON-NEGOTIABLE. Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## Setup
+- Auditing is **MANDATORY** for every PHI-bearing aggregate.
+- Enable via `.EnableAdvancedAuditing()` + `AddAuditing(... UseEfCoreAuditing(...).UseAppWeaverDataStore())`.
+- Audit tables: shared `AppWeaver.DataStore`, schema `Auditing`, prefix `Audit_`.
+- A **PHI-access-audit** pipeline behavior runs on every mediator request (see [[cqrs.domain]]).
+
+## Record (immutable)
+Every PHI read/mutation, authentication, consent change, export, and break-the-glass MUST emit:
+```
+{ timestamp, subjectId, subjectRole, patientId, action, resourceType,
+  resourceId, outcome, sourceIp, correlationId, reason }
+```
+
+## Audit-mandatory operations
+Every PHI read/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]].
+
+## 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]]

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

@@ -0,0 +1,26 @@
+# Authorization — Healthcare Domain Addenda
+
+> Technology base: [[authorization]]. Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## Roles
+`SystemAdmin`, `ComplianceOfficer`, `Physician`, `Nurse`, `LabTechnician`, `Radiologist`, `Pharmacist`, `BillingClerk`, `FrontDesk`, `Patient`, `ExternalSystem`, `ResearchAnalyst` (de-identified scope only). Per-route matrix: `docs/security/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/docs/domainspecs/healthcare/clinical-terms.md

@@ -0,0 +1,20 @@
+# Glossary — Clinical Terms
+
+> Ubiquitous language for clinical aggregates. Commands: `/aw-spec-specify`, `/aw-spec-clarify`, `/aw-spec-plan`. 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/docs/domainspecs/healthcare/coding-standards.domain.md

@@ -0,0 +1,26 @@
+# Coding Standards — Healthcare Domain Addenda
+
+> Technology base: [[coding-standards]]. Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## Coded value objects
+- Follow the FHIR pattern: `Codeable`, `Coding`, `Quantity`, `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/docs/domainspecs/healthcare/comandrulemap.md

@@ -0,0 +1,119 @@
+# Healthcare Domain — Command → Rule-File Map
+
+Per-AW-Spec-command list of the **healthcare domain** rule files in this folder.
+Technology standards already auto-load inside each command; the files below are the
+domain-specific ones to load **in addition** for a healthcare project.
+
+- All paths are workspace-relative and live in this folder: `docs/domainspecs/healthcare/`.
+- A skill can read this file and load every path under the matching command heading.
+- This file is the **canonical source** for the healthcare domain mapping;
+  `/aw-spec-select-domain` selects this folder as active.
+
+---
+
+## /aw-spec-constitution
+- docs/domainspecs/healthcare/domain-requirements.md
+- docs/domainspecs/healthcare/ai-rules.domain.md
+
+## /aw-spec-specify
+- docs/domainspecs/healthcare/domain-requirements.md
+- docs/domainspecs/healthcare/clinical-terms.md
+- docs/domainspecs/healthcare/integration-terms.md
+- docs/domainspecs/healthcare/domain-driven-design.domain.md
+- docs/domainspecs/healthcare/fhir.md
+- docs/domainspecs/healthcare/hl7.md
+- docs/domainspecs/healthcare/dicom.md
+- docs/domainspecs/healthcare/terminology.md
+- docs/domainspecs/healthcare/hipaa.md
+- docs/domainspecs/healthcare/consent.md
+- docs/domainspecs/healthcare/data-classification.domain.md
+- docs/domainspecs/healthcare/ai-rules.domain.md
+
+## /aw-spec-clarify
+- docs/domainspecs/healthcare/domain-driven-design.domain.md
+- docs/domainspecs/healthcare/hl7.md
+- docs/domainspecs/healthcare/hipaa.md
+- docs/domainspecs/healthcare/consent.md
+- docs/domainspecs/healthcare/clinical-terms.md
+- docs/domainspecs/healthcare/integration-terms.md
+
+## /aw-spec-plan
+- docs/domainspecs/healthcare/folder-structure.domain.md
+- docs/domainspecs/healthcare/cqrs.domain.md
+- docs/domainspecs/healthcare/vertical-slices.domain.md
+- docs/domainspecs/healthcare/persistence.domain.md
+- docs/domainspecs/healthcare/testing.domain.md
+- docs/domainspecs/healthcare/eventing.domain.md
+- docs/domainspecs/healthcare/domain-driven-design.domain.md
+- docs/domainspecs/healthcare/fhir.md
+- docs/domainspecs/healthcare/hl7.md
+- docs/domainspecs/healthcare/dicom.md
+- docs/domainspecs/healthcare/terminology.md
+- docs/domainspecs/healthcare/hipaa.md
+- docs/domainspecs/healthcare/consent.md
+- docs/domainspecs/healthcare/zero-trust.domain.md
+- docs/domainspecs/healthcare/authorization.domain.md
+- docs/domainspecs/healthcare/auditing.domain.md
+- docs/domainspecs/healthcare/data-classification.domain.md
+- docs/domainspecs/healthcare/coding-standards.domain.md
+- docs/domainspecs/healthcare/dependency-policy.domain.md
+- docs/domainspecs/healthcare/api-versioning.domain.md
+- docs/domainspecs/healthcare/ai-rules.domain.md
+
+## /aw-spec-tasks
+- docs/domainspecs/healthcare/folder-structure.domain.md
+- docs/domainspecs/healthcare/vertical-slices.domain.md
+- docs/domainspecs/healthcare/cqrs.domain.md
+- docs/domainspecs/healthcare/persistence.domain.md
+- docs/domainspecs/healthcare/testing.domain.md
+- docs/domainspecs/healthcare/eventing.domain.md
+- docs/domainspecs/healthcare/domain-driven-design.domain.md
+- docs/domainspecs/healthcare/fhir.md
+- docs/domainspecs/healthcare/hl7.md
+- docs/domainspecs/healthcare/authorization.domain.md
+- docs/domainspecs/healthcare/auditing.domain.md
+- docs/domainspecs/healthcare/coding-standards.domain.md
+- docs/domainspecs/healthcare/ai-rules.domain.md
+
+## /aw-spec-analyze
+- docs/domainspecs/healthcare/hl7.md
+- docs/domainspecs/healthcare/hipaa.md
+- docs/domainspecs/healthcare/auditing.domain.md
+- docs/domainspecs/healthcare/coding-standards.domain.md
+- docs/domainspecs/healthcare/ai-rules.domain.md
+
+## /aw-spec-implement
+- docs/domainspecs/healthcare/folder-structure.domain.md
+- docs/domainspecs/healthcare/vertical-slices.domain.md
+- docs/domainspecs/healthcare/cqrs.domain.md
+- docs/domainspecs/healthcare/persistence.domain.md
+- docs/domainspecs/healthcare/testing.domain.md
+- docs/domainspecs/healthcare/eventing.domain.md
+- docs/domainspecs/healthcare/domain-driven-design.domain.md
+- docs/domainspecs/healthcare/fhir.md
+- docs/domainspecs/healthcare/hl7.md
+- docs/domainspecs/healthcare/terminology.md
+- docs/domainspecs/healthcare/hipaa.md
+- docs/domainspecs/healthcare/consent.md
+- docs/domainspecs/healthcare/authorization.domain.md
+- docs/domainspecs/healthcare/auditing.domain.md
+- docs/domainspecs/healthcare/data-classification.domain.md
+- docs/domainspecs/healthcare/zero-trust.domain.md
+- docs/domainspecs/healthcare/coding-standards.domain.md
+- docs/domainspecs/healthcare/dependency-policy.domain.md
+- docs/domainspecs/healthcare/api-versioning.domain.md
+- docs/domainspecs/healthcare/ai-rules.domain.md
+
+---
+
+## Quick reference (command → file count)
+
+| Command | Domain rule files |
+|---|---|
+| /aw-spec-constitution | 2 |
+| /aw-spec-specify | 12 |
+| /aw-spec-clarify | 6 |
+| /aw-spec-plan | 21 |
+| /aw-spec-tasks | 13 |
+| /aw-spec-analyze | 5 |
+| /aw-spec-implement | 20 |

package/assets/docs/domainspecs/healthcare/consent.md

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

@@ -0,0 +1,12 @@
+# CQRS — Healthcare Domain Addenda
+
+> Technology base: [[cqrs]]. Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## 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/docs/domainspecs/healthcare/data-classification.domain.md

@@ -0,0 +1,28 @@
+# Data Classification — Healthcare Domain Addenda
+
+> Technology base: [[data-classification]]. NON-NEGOTIABLE. Commands: `/aw-spec-specify`, `/aw-spec-plan`, `/aw-spec-implement`.
+
+## 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/docs/domainspecs/healthcare/dependency-policy.domain.md

@@ -0,0 +1,11 @@
+# Dependency Policy — Healthcare Domain Addenda
+
+> Technology base: [[dependency-policy]]. Commands: `/aw-spec-plan`, `/aw-spec-implement`.
+
+## 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/docs/domainspecs/healthcare/dicom.md

@@ -0,0 +1,15 @@
+# DICOM Standards
+
+> Commands: `/aw-spec-specify`, `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## 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]]

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

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