aw-spec-cli 0.1.0 → 0.1.2

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

@@ -0,0 +1,59 @@
+# 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

@@ -0,0 +1,99 @@
+# 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

@@ -0,0 +1,87 @@
+# 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

@@ -0,0 +1,40 @@
+# 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

@@ -0,0 +1,31 @@
+# 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/pharma-constitution.my-ref.md

@@ -0,0 +1,86 @@
+# Pharma Constitution — Domain Addenda
+
+> **Domain addenda to the technology constitution.** Not ratified on its own — compose it with
+> the technology base.
+
+## How to use (compose-at-ratification)
+
+The technology base (`docs/technology-constitution.md`) **auto-loads** for `/aw-spec-constitution`,
+so you pass only this domain addenda:
+
+```
+/aw-spec-constitution @docs/pharma-constitution.md
+```
+
+This file supplies **only** the pharma deltas: project identity, regulatory posture, the pharma
+domain principles (which **continue** the technology numbering at **XVI**), folder additions,
+governance overrides, and the active-domain pointer. The reusable principles I–XV live in the
+technology base and are not repeated here.
+
+Active domain folder: `docs/domainspecs/pharma/` (set via `/aw-spec-select-domain pharma`).
+
+## Project Identity (fills the technology base)
+
+- **Project name:** `<SampleProjectName>` — Medicinal Product Registry (Headless API).
+- **Mission:** maintain a centralized, authoritative registry of medicinal products in compliance with pharmaceutical industry standards, regulatory requirements, and healthcare interoperability specifications; exposed as a headless HTTP + FHIR API ready for integration with prescribing, dispensing, manufacturing, pharmacovigilance, and clinical systems.
+- **Bounded contexts (modules):** enumerated in `docs/domainspecs/pharma/domain-requirements.md` (project-specific).
+- **Architecture posture:** Modular Monolith with Clean Architecture + DDD; `MedicinalProduct` is the Aggregate Root; each module designed for clean extraction into an independent microservice. **HEADLESS.**
+
+## Regulatory Posture
+
+Built for regulatory compliance **readiness** — auditability, traceability, data integrity, and
+provenance are designed in. Data-integrity expectations follow **ALCOA+** for GxP-relevant
+product records. Identifier standards (NDC), substance identity (UNII), classification (WHO
+ATC), and ISO IDMP concept alignment are first-class. Data residency configurable per deployment.
+
+## Domain Principles
+
+> Extend the technology Core Principles; numbering **continues from XV**.
+
+### XVI — Pharmaceutical Product Identification (NON-NEGOTIABLE)
+NDC modeled as a Value Object with discrete Labeler/Product/Package segments; NDC uniqueness enforced (aggregate + persistence constraint); NDC validation rules configurable; no invented NDC/Labeler codes. The domain model aligns with ISO IDMP concepts (Medicinal Product, Manufactured Item, Pharmaceutical Product, Substance, MAH, Packaging, Strength, Route of Administration).
+→ `docs/domainspecs/pharma/ndc.md`, `idmp.md`
+
+### XVII — Pharma Terminology & Classification (NON-NEGOTIABLE)
+Coded data uses standard terminologies — UNII (substances), RxNorm (clinical drug), SNOMED CT (dose form / route / classification), UCUM (units), and WHO ATC (therapeutic classification). Every coded field is a Codeable value object; lookup/validation via the Terminology module; ATC codes validated against configured code sets (multiple ATC per product allowed); no invented or free-text codes.
+→ `docs/domainspecs/pharma/terminology.md`, `atc.md`
+
+### XVIII — Regulatory Compliance: Audit, Provenance & Versioning (NON-NEGOTIABLE)
+Immutable audit records (User, Timestamp, Action, Previous Value, New Value) for product creation, modification, retirement, identifier changes, and classification changes; `AuditRecord` is append-only. Provenance captured for externally sourced product data (source, method, agent, timestamp). Full version history of product information; historical versions remain queryable. Extends technology **X** and **XIV** with pharma compliance controls.
+→ `docs/domainspecs/pharma/regulatory-compliance.md`, `data-provenance.md`, `auditing.domain.md`, `persistence.domain.md`
+
+### XIX — Medicinal Product Lifecycle Integrity (NON-NEGOTIABLE)
+MedicinalProduct lifecycle (Draft → Under Review → Approved → Active → Discontinued/Withdrawn) is a guarded state machine; only valid transitions are permitted; registration completeness (required attributes, ≥ 1 active ingredient, ≥ 1 packaging, valid NDC/dosage-form/route/ATC) is enforced before leaving Draft; retirement is a logical state change, never a hard delete. Each transition emits a domain event and is audit-mandatory.
+→ `docs/domainspecs/pharma/product-lifecycle.domain.md`, `domain-driven-design.domain.md`, `eventing.domain.md`
+
+### XX — Healthcare Interoperability Readiness
+The model maps to FHIR Medication / MedicationKnowledge / Substance / Organization (projections, not the system of record); product identifiers map to FHIR Identifier; coded fields map to CodeableConcept/Coding; the solution supports future HL7-based integration via Interop adapters. Extends technology **XII** and **XIV** with the FHIR contract.
+→ `docs/domainspecs/pharma/fhir.md`, `hl7.md`
+
+## Folder Structure Additions
+
+- Pharma additions (Interop/Fhir + Hl7v2 adapters, InteropTests, terminology seed fixtures, provenance/version-history stores): `docs/domainspecs/pharma/folder-structure.domain.md`
+
+## Security & Governance Addenda
+
+- **Change authority** (who may register / approve / retire products, and change identifiers or classification): `docs/domainspecs/pharma/authorization.domain.md`
+- **Data classification** (public vs commercially-sensitive / pre-market / externally-sourced; GxP/ALCOA+ integrity): `docs/domainspecs/pharma/data-classification.domain.md`
+- **Zero-trust posture** (transport, scope/trace propagation, change-authority enforcement): `docs/domainspecs/pharma/zero-trust.domain.md`
+- **Coding standards** (forbidden patterns, quality gates): `docs/domainspecs/pharma/coding-standards.domain.md`
+- **API/contract versioning** (FHIR + NDC identifier stability): `docs/domainspecs/pharma/api-versioning.domain.md`
+- **Dependency policy** (FHIR SDK, terminology libraries, regulatory suitability): `docs/domainspecs/pharma/dependency-policy.domain.md`
+
+## AI Rules Addenda
+
+- Identifier/code safety (no invented NDC/UNII/RxNorm/SNOMED/ATC), projection discipline, lifecycle/audit edit limits, pharma refusal conditions: `docs/domainspecs/pharma/ai-rules.domain.md` (extends `docs/glossary/ai-rules.md`)
+
+## Governance Overrides
+
+- Mandatory approver for any identifier (NDC), classification (ATC), or lifecycle-rule change: Regulatory/Compliance Officer (in addition to a Principal Engineer and a Domain Owner). Change-authority roles are defined in `docs/domainspecs/pharma/authorization.domain.md`.
+- Additional review required after every relevant regulatory or terminology-release update (e.g. WHO ATC annual update, FDA NDC directory changes).
+- **Versioning note:** any change to NDC identity rules, the lifecycle state machine, the audit-record shape, or the canonical FHIR interoperability surface is a MAJOR bump.
+
+## Domain Requirements Pointer
+
+→ `docs/domainspecs/pharma/domain-requirements.md`
+(`[DOMAIN: Bounded Contexts / Modules]`, per-subsection pointers, `[DOMAIN: Platform Topology]`, `[DOMAIN: Governance Overrides]`).

package/assets/docs/requirement-spec.txt

@@ -0,0 +1,15 @@
+/aw-spec-specify MedicinalProduct/RegisterMedicinalProduct
+
+Allow an authorized user to register a new medicinal product in the registry.
+
+On registration the user provides: product name, generic name, NDC, dosage form, strength, route of administration, manufacturer, one or more active ingredients with details, one or more packaging configurations and one or more ATC classification codes.
+
+The system validates the submission (required attributes, duplicate NDC, valid dosage form and route of administration) and creates the product in the Draft state. A successful registration is auditable and emits a registration event.
+
+Acceptance:
+- A valid submission creates a Draft MedicinalProduct and returns its identifier.
+- A malformed or duplicate NDC is rejected with a clear validation error.
+- A product missing a required attribute, an active ingredient, or a packaging configuration is rejected.
+- The creation is recorded in the audit trail.
+
+==============================================================================================

package/assets/docs/security/auditing.md

@@ -0,0 +1,117 @@
+# 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

@@ -0,0 +1,14 @@
+# 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.

package/assets/docs/security/authorization.md

@@ -0,0 +1,87 @@
+# Authorization Standards
+
+> Pure technology (domain-agnostic) — domain roles & matrix in [[authorization.domain]]. NON-NEGOTIABLE. Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## Authorization model
+
+- Authorization is **role-based AND scope-based** — both MUST pass.
+- Per-route authorization is declared per endpoint via `Roles(...)` + scope evaluation,
+  documented in an authorization matrix.
+- Identity comes from an external IdP via `.AddAppWeaverSecurity(...)` — local identity stores
+  forbidden (see [[zero-trust]]).
+- (The concrete role set and scope syntax are domain-specific — see [[authorization.domain]].)
+
+## Policy evaluation
+
+- Endpoints inherit `SecureFastEndpoint<TRequest, TResponse>` and MUST override
+  `GetSecurityCachePolicy()` to declare `SecurityLevel` and `CachePolicy`.
+  - Mutating endpoints MUST use `CachePolicy.NoStore`.
+  - Sensitive-data read endpoints MUST use `CachePolicy.NoStore`.
+- Field-level redaction (minimum-necessary) lives in **projection extensions**, not
+  controllers (see [[data-classification]]; domain specifics in [[authorization.domain]]).
+
+## Endpoint authorization patterns
+
+- `AllowAnonymous()` is permitted **only** for infrastructure/discovery endpoints
+  (`/.well-known`, `/health`, `/alive`, service metadata) and during initial scaffolding
+  before merge to a protected branch.
+- `AllowAnonymous()` on sensitive-data or mutating endpoints in any CI-protected branch is a
+  Forbidden Pattern (CI grep gate; see [[coding-standards]]).
+
+## Canonical example (agent reference — `<SampleProjectName>` sample)
+
+Secure endpoint — declare auth scheme + roles in `Configure()`, and the security/cache policy
+in `GetSecurityCachePolicy()`:
+
+```csharp
+public override void Configure()
+{
+    Post("/projects");
+    AuthSchemes("Bearer");        // JWT from the external IdP
+    Roles("Admin");               // role-based gate (combine with scope checks for FHIR — see .domain)
+    Summary(s => s.Summary = "Create a new project");
+    Options(o => o.WithTags("02 - Project - (FastEndpoints)"));
+}
+
+protected override SecurityCachePolicy GetSecurityCachePolicy() => new()
+{
+    SecurityLevel = SecurityLevel.Internal,   // Internal | Restricted (admin/sensitive)
+    CachePolicy   = CachePolicy.NoStore       // NoStore for mutating/sensitive; PrivateCache for cacheable reads
+};
+```
+
+> Mutating endpoints use `CachePolicy.NoStore`. Admin/audit endpoints (e.g. list-including-deleted)
+> use `SecurityLevel.Restricted`. `AllowAnonymous()` is only for infrastructure/discovery routes
+> or pre-merge scaffolding (the template ships endpoints scaffolded with `AllowAnonymous()` and
+> the `AuthSchemes`/`Roles` lines commented — replace them before merging to a protected branch).
+
+Composition — external IdP only (no local identity store), role-based authorization:
+
+```csharp
+// <SampleProjectName>.Service/Program.cs
+builder.Services.AddAppWeaverSecurity(security =>
+{
+    security
+        .AddAuthentication(auth =>
+        {
+            if (authProvider == "EntraExternalID")
+                auth.UseEntraExternalID(o => { o.TenantId = cfg["EntraExternalID:TenantId"]!;
+                                               o.ClientId = cfg["EntraExternalID:ClientId"]!; }, cfg);
+            else
+                auth.UseAzureAdB2C(o => { o.Domain = cfg["AzureAdB2C:Domain"]!;
+                                          o.ClientId = cfg["AzureAdB2C:ClientId"]!;
+                                          o.SignUpSignInPolicyId = cfg["AzureAdB2C:SignUpSignInPolicyId"]!; }, cfg);
+        })
+        .AddAuthorization(authz => authz.UseRoleBased(o => o.AdminRole = "Admin"));
+        // NOTE: no .AddIdentity(...) — the IdP is the source of truth (see [[zero-trust]])
+}, options => { }, configuration: cfg);
+
+// ... pipeline order ...
+app.UseAuthentication();
+app.UseAuthorization();
+app.UseFastEndpoints();
+```
+
+## Related
+
+- [[zero-trust]] · [[auditing]] · [[data-classification]] · [[authorization.domain]]