aw-spec-cli 0.1.4 → 0.1.6

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

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

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

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

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

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

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

@@ -1,32 +0,0 @@
-# Terminology Standards — Pharma
-
-> NON-NEGOTIABLE. Commands: `/aw-spec-specify`, `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
-
-## Coded value objects
-- **Coded data MUST use industry terminologies — free-text strings for coded concepts are FORBIDDEN.**
-- Every code-bearing field is a **`Codeable` value object** `{ system, code, version, display }` (mirrors FHIR `CodeableConcept`/`Coding`; see [[fhir]]).
-
-## Standard terminologies
-| Concept | Terminology | Conformance |
-|---|---|---|
-| Product / package identity | **NDC** | SHALL (see [[ndc]]) |
-| Substances / active ingredients | **UNII** | SHOULD |
-| Substance / clinical drug | **RxNorm** | SHOULD |
-| Dosage form / route / classification | **SNOMED CT** | SHOULD |
-| Therapeutic classification | **WHO ATC** | SHALL (see [[atc]]) |
-| Units (strength, package qty) | **UCUM** | SHALL |
-
-- **UNII** is the substance identity for IDMP `Substance` alignment (see [[idmp]]) and maps to FHIR `Substance.code`.
-
-## Validation
-- Hard-coded coded literals FORBIDDEN outside the Terminology module's seed data.
-- Never invent NDC/UNII/RxNorm/SNOMED/ATC/UCUM codes — confirm against value sets (see [[ai-rules.domain]]).
-- Invalid dosage forms/routes rejected at validation time; the bound value set is configuration (see [[domain-driven-design.domain]]).
-
-## Terminology module
-- Lookup/validation/expansion **MUST** go through a dedicated **Terminology module** (internal cache or external TS via FHIR `$expand` / `$validate-code`).
-- Aggregates: `CodeSystem`, `ValueSet`, `ConceptMap` (subsets; expansions cached from RxNorm/SNOMED/FDA UNII-NDC/WHO ATC).
-- Code-set versions are pinned + recorded; a terminology release (e.g. WHO ATC annual update) is a tracked, audited change (see [[auditing.domain]]).
-
-## Related
-- [[ndc]] · [[atc]] · [[idmp]] · [[fhir]] · [[domain-driven-design.domain]] · [[testing.domain]] · [[ai-rules.domain]]

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

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

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

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

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

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

package/assets/docs/glossary/ai-rules.md

@@ -1,59 +0,0 @@
-# AI Operational Rules
-
-> Pure technology (domain-agnostic) — domain AI rules in [[ai-rules.domain]]. Applies to all AI agents (Claude Code, Augment, Copilot, etc.). Commands: **ALL**.
-
-AI agents MUST treat the constitution as **ground truth**, overriding pre-trained habits and
-any contradictory documentation found inside the repo.
-
-## Context loading rules / retrieval expectations
-
-- Before generating or editing code, **inspect the relevant vertical slice**
-  (`<Module>/Features/<Feature>/`) and the aggregate it mutates (see [[vertical-slices]]).
-- **Confirm symbol signatures via repository search** rather than inferring from generic
-  framework knowledge — `IRepository<T>` here is AppWeaver's, not a generic one
-  (see [[cqrs]], [[persistence]]).
-
-## AI generation rules
-
-- New features are generated as **complete vertical slices**: Command/Query + Handler +
-  Endpoint + Validator + (when applicable) Specification + DTO + mapping extension + Unit test
-  + Integration test.
-- Do **NOT** introduce new top-level dependencies (see [[dependency-policy]]).
-- Do **NOT** create speculative abstractions (single-implementation interfaces, generic
-  wrappers around existing framework types) — YAGNI.
-- Generated tests follow Test-First Engineering and **MUST fail before** the production change
-  is in place (see [[testing]]).
-
-## Output formatting conventions
-
-- Do **NOT** write inline rationale comments explaining why a pattern was chosen — the
-  constitution is the rationale (see [[coding-standards]]).
-
-## Migration generation policy
-
-- AI MAY scaffold EF Core migrations but **MUST NOT run them** against shared environments.
-  Production migrations require DBA sign-off and an SRE-executed rollout (see [[persistence]]).
-
-## Operating envelope
-
-- Edits limited to the scope explicitly requested. Drive-by refactors of unrelated files are
-  forbidden.
-- File creation constrained to the Mandatory Folder Structure; new folders require an amendment.
-- All AI-authored commits are self-contained: source change + tests + affected
-  DTOs/mappings + migration (when schema changes).
-
-## Refusal conditions (generic) — refuse and ask for clarification when a request would:
-
-- Violate a NON-NEGOTIABLE principle.
-- Introduce a Forbidden Pattern (see [[coding-standards]]).
-- Require a cross-aggregate transaction (see [[cqrs]], [[domain-driven-design]]).
-- Embed a secret, connection string, or production hostname in code or config.
-- Disable a soft-delete filter, tenancy filter, audit interceptor, scope check, or auth policy
-  globally.
-
-> Domain-specific generation rules, data masking, terminology codes, and refusal conditions are in [[ai-rules.domain]].
-
-## Related
-
-- [[coding-standards]] · [[dependency-policy]] · [[testing]] · [[persistence]] ·
-  [[vertical-slices]] · [[ai-rules.domain]]

package/assets/docs/governance/api-versioning.md

@@ -1,99 +0,0 @@
-# API Versioning Policy
-
-> Pure technology (domain-agnostic) — domain (e.g. FHIR) versioning in [[api-versioning.domain]]. Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
-
-## REST versioning
-
-- Internal REST (FastEndpoints) serves first-party apps and operational tooling.
-- List endpoints accept `pageNumber` (1-based) + `pageSize` and return `PagedResult<TDto>`
-  (see [[vertical-slices]]).
-- Breaking changes to internal REST require a **versioned route prefix** (`v2/...`).
-- Endpoints MUST NOT swallow exceptions; the central exception handler owns the contract.
-
-## ETag / concurrency at the edge
-
-- The server sets the ETag header on every create/read/update via `SetETagFromBase64(...)`.
-- Update/Delete extract `If-Match` via `GetIfMatchBase64Token()`; mismatch -> `409
-  concurrency.conflict`. ETag tokens are strong; `W/` weak prefixes stripped on read.
-  See [[persistence]].
-
-## Machine-readable schemas
-
-- The service publishes versioned, machine-readable schemas:
-  - **OpenAPI** for REST,
-  - **AsyncAPI** for events (see [[eventing]]).
-- All schemas regenerate cleanly in CI; diffs are reviewed for breaking changes
-  (see [[coding-standards]]).
-- (FHIR CapabilityStatement — see [[api-versioning.domain]].)
-
-## Deprecation lifecycle & sunset policy
-
-- **Breaking changes are MAJOR version bumps** (per the constitution's governance SemVer).
-- A superseded REST version remains available through a documented deprecation window before
-  sunset; the deprecation and sunset are announced via the published schema diffs and the
-  governance amendment process.
-
-## Canonical example (agent reference — `<SampleProjectName>` sample)
-
-ETag round-trip: the endpoint reads `If-Match` on update and sets the `ETag` on success;
-the handler compares the token and translates an EF conflict to `409 concurrency.conflict`:
-
-```csharp
-// Endpoint (PUT /projects/{id:guid})
-var id = Route<Guid>("id");
-var token = HttpContext.Request.GetIfMatchBase64Token();      // extract If-Match
-
-var result = await _mediator.Send(new UpdateProjectCommand(
-    id, req.Name, req.Description, req.StartDate, req.EndDate, req.OwnerId, token), ct);
-
-if (result.IsSuccess && !string.IsNullOrWhiteSpace(result.Value?.RowVersionBase64))
-    HttpContext.Response.SetETagFromBase64(result.Value!.RowVersionBase64);   // set ETag
-return result;
-```
-
-```csharp
-// Handler — compare the supplied token, and catch EF's concurrency exception
-var current = entity.RowVersion is { Length: > 0 } rv ? Convert.ToBase64String(rv) : string.Empty;
-if (string.IsNullOrWhiteSpace(request.RowVersionBase64) ||
-    !string.Equals(current, request.RowVersionBase64, StringComparison.Ordinal))
-    return Result<ProjectDto>.Failure(new Error(
-        "concurrency.conflict", "Resource was modified by another process. Reload and retry.",
-        409, "projects"));
-
-entity.Update(request.Name, request.Description, request.StartDate, request.EndDate, ownerId);
-await _repo.UpdateAsync(entity, ct);
-
-try { await _uow.SaveChangesAsync(ct); }
-catch (DbUpdateConcurrencyException)
-{
-    return Result<ProjectDto>.Failure(new Error(
-        "concurrency.conflict", "Resource was modified by another process. Reload and retry.",
-        409, "projects"));
-}
-```
-
-ETag token helpers — strong tokens; strip `W/` weak prefix and quotes on read:
-
-```csharp
-// <SampleProjectName>.Service/Utilities/HttpRequestETagExtensions.cs
-public static string GetIfMatchBase64Token(this HttpRequest request, string? fallback = null)
-{
-    var token = request.Headers.IfMatch.FirstOrDefault();
-    return !string.IsNullOrWhiteSpace(token) ? SanitizeETagToken(token) : (fallback ?? string.Empty);
-}
-
-public static string SanitizeETagToken(string? raw)
-{
-    if (string.IsNullOrWhiteSpace(raw)) return string.Empty;
-    var token = raw.Trim();
-    if (token.StartsWith("W/")) token = token[2..].Trim();   // strip weak prefix
-    return token.Trim('"');                                  // strip quotes
-}
-
-// On success the endpoint sets the strong ETag from the DTO's RowVersionBase64:
-HttpContext.Response.SetETagFromBase64(result.Value!.RowVersionBase64);
-```
-
-## Related
-
-- [[vertical-slices]] · [[persistence]] · [[eventing]] · [[coding-standards]] · [[api-versioning.domain]]

package/assets/docs/governance/coding-standards.md

@@ -1,87 +0,0 @@
-# Coding Standards
-
-> Pure technology (domain-agnostic) — domain forbidden patterns & CI gates in [[coding-standards.domain]]. Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
-
-## Naming conventions
-
-- Solution and projects: `<SampleProjectName>.<Role>` (e.g. `<SampleProjectName>.Api`,
-  `<SampleProjectName>.AppHost`, `<SampleProjectName>.ServiceDefaults`).
-- Namespaces mirror the folder path exactly; **file-scoped namespaces only**.
-- Aggregates: `class <Aggregate> : EntityBase<<Aggregate>Id>, IAggregateRoot,
-  IFullAuditedObject, ISoftDeletable, IConcurrencyTracked, IHasDomainEvents,
-  INamedEntity<<Aggregate>Id>`.
-- Commands/Queries: `record <Verb><Aggregate>Command(...) : ICommand<Result<TDto>>`.
-- DTOs: `record <Aggregate>Dto { public required Guid Id { get; init; } ... }` — no setters;
-  required init for non-nullable members.
-
-## Nullable & language rules
-
-- C# language version: latest LTS; **nullable reference types ENABLED**; implicit usings
-  ENABLED; **`TreatWarningsAsErrors` for Release**.
-
-## Async conventions
-
-- Every I/O-bound method ends with `Async` and accepts a `CancellationToken` as the **last
-  parameter**.
-- `async void` is forbidden outside event handlers.
-- Blocking calls (`.Result`, `.Wait()`, `Task.Run` to fake async) in request-handling paths
-  are FORBIDDEN.
-
-## Error / exception conventions
-
-- Exceptions are thrown by the **Domain only** (`DomainException`,
-  `InvariantViolationException`). Application code returns `Result<T>` (see [[cqrs]]).
-- Never catch-all `catch (Exception)` that swallows or rewraps without rethrow, except in the
-  central exception handler.
-- Never return HTTP 200 with an error body — use correct status codes (4xx client, 5xx server,
-  409 concurrency).
-
-## Documentation expectations
-
-- XML doc comments on public types and aggregate methods.
-- Inline comments only where intent is non-obvious. Commented-out code MUST be removed before
-  merge.
-- Do not write inline rationale comments explaining pattern choices — the constitution is the
-  rationale (see [[ai-rules]]).
-
-## Forbidden patterns (generic; rejected at review, build-warning where statically detectable)
-
-1. MediatR — use `AppWeaver.Mediator` (see [[dependency-policy]]).
-2. AutoMapper / Mapster reflection mapping — hand-written `ToDto()` only.
-3. Anemic domain models (see [[domain-driven-design]]).
-4. Repository as data-access god object (see [[persistence]]).
-5. Cross-aggregate EF navigation properties — strongly-typed ID only.
-6. Hard-coded connection strings, secrets, ports, or issuer URLs in source (see [[zero-trust]]).
-7. Static service locator — use constructor DI.
-8. Direct `DbContext` access from Endpoints or Features outside repo/spec surface.
-9. Blocking calls in request paths.
-10. Catch-all that swallows/rewraps without rethrow (outside central handler).
-11. `AllowAnonymous()` on sensitive-data/mutating endpoints in a CI-protected branch.
-12. Logging/emitting secrets, tokens, keys, or payment-card data (see [[data-classification]]).
-13. Multiple aggregate mutations in one transaction (see [[cqrs]], [[eventing]]).
-14. `DateTime.UtcNow` / `Guid.NewGuid()` in aggregates/handlers/SUT — use `IClock` /
-    `IGuidGenerator` (see [[testing]]).
-15. HTTP 200 with an error body.
-16. Analytics/reporting by querying the OLTP DB directly — emit events (see [[eventing]]).
-
-> Domain-specific forbidden patterns are in [[coding-standards.domain]].
-
-## Quality gates (CI) — generic, must pass before merge
-
-1. `dotnet build` succeeds with `TreatWarningsAsErrors=true` for Release.
-2. `dotnet test` passes for UnitTests + IntegrationTests.
-3. Code coverage on changed files meets the Testing Profile threshold (see [[testing]]).
-4. EF Core migrations apply cleanly to a fresh PostgreSQL instance (see [[persistence]]).
-5. OpenAPI document generation succeeds; diff reviewed for breaking changes.
-6. AsyncAPI regenerates cleanly for any domain-event contract change (see [[eventing]]).
-7. Static analysis (Roslyn analyzers, nullable warnings, banned-API analyzer) — zero errors.
-8. Grep checks: no `AllowAnonymous()` on production endpoints, no hard-coded secrets, no
-   MediatR/AutoMapper references.
-9. Constitution compliance review checked off in the PR template.
-
-> Domain-specific CI gates are in [[coding-standards.domain]].
-
-## Related
-
-- [[dependency-policy]] · [[api-versioning]] · [[domain-driven-design]] · [[cqrs]] ·
-  [[persistence]] · [[testing]] · [[ai-rules]] · [[coding-standards.domain]]

package/assets/docs/governance/dependency-policy.md

@@ -1,40 +0,0 @@
-# Dependency Policy
-
-> Pure technology (domain-agnostic) — domain package rules in [[dependency-policy.domain]]. Commands: `/aw-spec-plan`, `/aw-spec-implement`.
-
-## Package governance
-
-- **All package versions are governed by `Directory.Packages.props`** (Central Package
-  Management). `PackageReference` entries in `.csproj` MUST NOT specify a `Version`.
-- New dependencies are added via `dotnet add package`.
-
-## Approved / preferred packages
-
-- Mediator: **`AppWeaver.Mediator`**.
-- Mapping: **hand-written `ToDto()` extension methods** (no reflection mapper).
-- Observability: **`AppWeaver.ServiceDefaults`** (OpenTelemetry + Serilog + resilience +
-  discovery) — see [[auditing]].
-- Validation: FluentValidation (via the mediator pipeline behavior; see [[cqrs]]).
-
-## Banned packages
-
-- **MediatR** — MUST NOT appear in any `Directory.Packages.props` entry (CI grep gate).
-- **AutoMapper / Mapster** (reflection mapping) — forbidden (see [[coding-standards]]).
-- Any logging package that ships analytics/telemetry exfiltration by default — rejected.
-
-## Supply-chain rules
-
-- New dependencies are reviewed for **license and supply-chain risk** before adoption.
-- AI agents **MUST NOT** introduce new top-level dependencies; new framework capabilities are
-  requested explicitly by the developer (see [[ai-rules]]).
-- Do not create speculative abstractions (single-implementation interfaces, generic wrappers
-  around existing framework types) — YAGNI is enforced.
-
-## Licensing expectations
-
-- Dependencies must carry a license compatible with the intended commercial deployment;
-  copyleft licenses that would force source disclosure of the service are rejected.
-
-## Related
-
-- [[coding-standards]] · [[cqrs]] · [[auditing]] · [[ai-rules]] · [[dependency-policy.domain]]

package/assets/docs/interop/ihe-conformance.md

@@ -1,31 +0,0 @@
-# IHE Conformance Notes — Patients / RegisterPatient
-
-Tracks IHE-profile conformance and deliberate scope decisions for the RegisterPatient feature.
-
-## PIX / PDQ (Patient Identifier Cross-referencing / Patient Demographics Query)
-
-- **In scope (delivered):** populate-and-link. Each registered patient carries a system-assigned
-  tenant MRN plus retained external identifiers (HL7 v2 PID-3) with their assigning authorities, so
-  the patient is cross-referenceable. `ResolvePatientIdentifiersQuery` resolves a patient's full
-  identifier set from any one known identifier (`Patients/Interop/Pix/`).
-- **Deferred (follow-up feature):** standing up full **PIX Manager** / **PDQ Supplier** query-responder
-  endpoints, and outbound notification to an external/central MPI. Decision recorded per
-  `/aw-spec-clarify` Q3 and `research.md` R8.
-
-## ATNA (Audit Trail and Node Authentication)
-
-- Every PHI command/query emits a PHI-free, ATNA-shaped access record via the
-  `PhiAccessAuditBehavior` mediator behavior; entity writes are additionally captured by the
-  framework's advanced auditing. Node authentication (mTLS between nodes) is a deployment concern.
-
-## HL7 v2 ADT
-
-- Inbound ADT^A04 over MLLP with accept/receipt ACK; outbound ADT^A04 on `PatientRegisteredEvent`.
-  Conformance tested against an internal corpus (`AppWeaver.Health.TestFixtures`).
-
-## Known follow-ups
-
-- **Tenant-scoped MRN uniqueness:** the generated migration currently creates a *global* unique index
-  `UX_Patients_Mrn`. Confirm the framework tenancy discriminator column and change to a composite
-  unique index `(TenantId, Mrn)` so the "same MRN in a different tenant" edge case is permitted.
-- **FHIR CapabilityStatement / StructureDefinition** packaging and validator CI gate (HG1/HG2).

package/assets/docs/security/auditing.md

@@ -1,117 +0,0 @@
-# Auditing & Observability Standards
-
-> Pure technology (domain-agnostic) — domain audit additions in [[auditing.domain]]. NON-NEGOTIABLE. Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
-
-## Observability baseline
-
-- All services consume `AppWeaver.ServiceDefaults` (`builder.AddServiceDefaults()`):
-  OpenTelemetry (ASP.NET Core, HttpClient, EF Core, runtime), Serilog structured logging with
-  enrichment (environment/machine/thread/correlation IDs), health checks at `/health` and
-  `/alive`, standard HTTP resilience handlers, and Aspire service discovery.
-
-## Structured logging
-
-- All logging goes through `ILogger<T>` with **message templates** (no string interpolation in
-  log calls).
-- `Console.WriteLine`, `Debug.WriteLine`, and `System.Diagnostics.Trace` are **forbidden** in
-  production code.
-- Log levels: Information (state transitions), Warning (recoverable anomalies), Error
-  (handled failures), Critical (invariant breaches). Debug/Trace MUST be safe to enable in
-  production.
-
-## Metrics & tracing
-
-- Custom metrics follow OTel semantic conventions, registered via a single `Meter` per module.
-- Trace context MUST propagate across `IMediator.Send`, `HttpClient`, and EF Core; bypassing
-  the framework's `HttpClientFactory` is forbidden.
-
-## Secrets never in telemetry
-
-- Authentication tokens, password material, private keys, and full payment-card numbers MUST
-  NEVER appear in logs, metrics labels, exception messages, or trace attributes.
-  (Domain-sensitive data — PHI, SSN, government IDs — see [[data-classification.domain]] and
-  [[auditing.domain]].)
-
-## Immutable audit strategy (generic)
-
-- Audit records are **append-only**: no update, no delete (no hard-delete path).
-- An audit-access pipeline behavior runs on every mediator request (see [[cqrs]]).
-- Audit records are retained per the applicable retention policy (see [[persistence]];
-  regulatory retention in [[auditing.domain]]).
-
-## Canonical example (agent reference — `<SampleProjectName>` sample)
-
-Aggregates opt into auditing by implementing the audit interfaces; the framework populates the
-fields automatically (no manual `CreatedOn`/`ModifiedBy` assignment in handlers):
-
-```csharp
-public class Project :
-    EntityBase<ProjectId>, IAggregateRoot,
-    IFullAuditedObject,   // ICreationAudited + IModificationAudited + IDeletionAudited
-    IFieldAudited,        // opt-in to field-level (before/after) auditing
-    ISoftDeletable, IConcurrencyTracked, IHasDomainEvents
-{
-    public DateTimeOffset CreatedOn { get; set; }
-    public string CreatedBy { get; set; } = default!;
-    public DateTimeOffset? ModifiedOn { get; set; }
-    public string? ModifiedBy { get; set; }
-    public bool IsDeleted { get; set; }
-    public DateTimeOffset? DeletedOn { get; set; }
-    public string? DeletedBy { get; set; }
-    // ...
-}
-```
-
-The DbContext applies audit (plus soft-delete/tenant) behaviors centrally:
-
-```csharp
-// OnModelCreating — see [[persistence]] for the full DbContext
-modelBuilder.ApplyCrossCuttingBehaviors(this);   // wires audit interceptors + filters
-```
-
-Composition — enable auditing on the repository stack and route audit records to a
-separate, append-only store (schema `Auditing`, prefix `Audit_`):
-
-```csharp
-// <SampleProjectName>.Service/Extensions/InfrastructureServiceRegistration.cs
-services.AddRepositories(builder => builder
-    .UseSingleDbContextEFRepositories<ApplicationDbContext>(/* ... */)
-    .EnableAuditing()
-    .EnableAdvancedAuditing()
-    .Done(), o => o.Provider = "EfCore");
-
-services.AddDataStore(b => b.UseEfCoreDataStore(/* ... */), o =>
-{
-    o.Strategy = DataStoreStrategy.Shared;   // infra tables (audit, tenancy) in one store
-    o.TablePrefix = "AppWeaver_";
-    o.AutoMigrate = true;
-});
-
-services.AddAuditing(b => b
-    .UseEfCoreAuditing(o =>
-    {
-        o.TablePrefix = "Audit_";
-        o.SchemaName = "Auditing";
-        o.ExcludeShadowProperties = true;
-    })
-    .UseAppWeaverDataStore(),
-    o => { o.IsEnabled = true; o.EnableFieldLevelAuditing = true; });
-```
-
-Observability baseline — `ServiceDefaults` (OTel + Serilog + health) wired once in `Program.cs`:
-
-```csharp
-// <SampleProjectName>.Service/Program.cs
-builder.AddServiceDefaults();                 // OTel, resilience, service discovery, health
-Log.Logger = new LoggerConfiguration()
-    .ReadFrom.Configuration(builder.Configuration)
-    .Enrich.FromLogContext()
-    .CreateLogger();
-builder.Host.UseSerilog();
-// ...
-app.MapDefaultEndpoints();                     // /health, /alive
-```
-
-## Related
-
-- [[data-classification]] · [[cqrs]] · [[persistence]] · [[auditing.domain]]

package/assets/docs/security/authorization-matrix.md

@@ -1,14 +0,0 @@
-# Authorization Matrix
-
-Per-route role + SMART-scope authorization (authorization.domain). PHI endpoints are
-`SecurityLevel.Restricted`, `CachePolicy.NoStore`, and emit ATNA audit records.
-
-| Route | Method | Roles | SMART scope | Security level | Notes |
-|---|---|---|---|---|---|
-| `/patients` | POST | `FrontDesk`, `SystemAdmin`, `ExternalSystem` | `system/Patient.write` or `user/Patient.write` | Restricted | Register patient (PHI write). 400/409/422 per spec. |
-| `/fhir/R4/Patient/{id}` | GET | `Physician`, `Nurse`, `SystemAdmin`, `ExternalSystem` | `patient/Patient.read`, `user/Patient.read`, or `patient/Patient.read.full` for un-redacted demographics | Restricted | Minimum-necessary redaction in the projection extension. |
-| `/fhir/metadata` | GET | — (anonymous) | — | Public | CapabilityStatement (infra/discovery allowlist). |
-| HL7 v2 MLLP ingress (ADT^A04) | MLLP | `ExternalSystem` (node-authenticated) | n/a | Restricted | Receipt ACK; async registration via canonical command. |
-
-> The `patient/Patient.read.full` scope gates full demographics (telecom/address/secondary identifiers);
-> without it the FHIR read returns identity essentials only.