aw-spec-cli 0.1.5 → 0.1.7

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/requirement-spec.txt

@@ -1,27 +0,0 @@
-MedicinalProduct/
-
-/aw-spec-orch constitution @docs/pharma-constitution.md
-
-/aw-spec-orch specify 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.
-
-/aw-spec-orch design 
-
-/aw-spec-orch analyze-design
-
-/aw-spec-orch implement
-
-
-
-==============================================================================================

package/assets/docs/security/auditing.md

@@ -1,160 +0,0 @@
-# Auditing & Observability Standards
-
-> Pure technology (domain-agnostic) — domain audit additions in [[auditing.domain]]. NON-NEGOTIABLE. Commands: `/aw-spec-design`.
-
-## 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]]).
-
-## Two auditing levels
-
-Auditing has exactly **two levels**, chosen **per aggregate** by the marker interfaces the root
-implements. The interceptor populates every audit field automatically (no manual
-`CreatedOn`/`ModifiedBy` assignment in handlers):
-
-| Level | Aggregate root implements | Captured | Depth |
-|-------|---------------------------|----------|-------|
-| **Basic** | `IAuditedObject` (creation+modification) or `IFullAuditedObject` (+soft-delete) | `CreatedBy/On`, `ModifiedBy/On`, `DeletedBy/On`; one `AuditLog` per root per SaveChanges | entity-level (Created/Updated/Deleted) — no before/after |
-| **Advanced** | Basic markers **+ `IFieldAudited`** | Basic + field-level before/after (`PropertyChange`: original → new) | entity + property-level previous/new |
-
-Field-level before/after values exist **only** at the Advanced tier. Children marked
-`IAggregateChild` fold into the root's `AuditLog`.
-
-## Canonical example (agent reference — `<SampleProjectName>` sample)
-
-```csharp
-// Basic — lifecycle stamps only
-public sealed class Category :
-    AggregateRootBase<CategoryId>, IAggregateRoot,
-    IAuditedObject                                    // creation + modification
-{
-    public DateTimeOffset CreatedOn { get; set; }
-    public string CreatedBy { get; set; } = default!;
-    public DateTimeOffset? ModifiedOn { get; set; }
-    public string? ModifiedBy { get; set; }
-}
-
-// Advanced — full lifecycle + field-level (before/after) tracking
-public sealed class Project :
-    AggregateRootBase<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 (one `EnableAdvancedAuditing()` registers
-the interceptor that serves **both** levels; per-aggregate level is decided by the interfaces
-above) 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>(/* ... */)
-    .EnableSoftDelete()
-    .EnableAdvancedAuditing()                        // AdvancedAuditingSaveChangesInterceptor
-    .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; });   // field-level = Advanced
-```
-
-## Querying the audit trail (framework-provided)
-
-The audit store is queryable out of the box via `IAuditEntity` — no bespoke read model required:
-
-```csharp
-// by resource identity
-var logs = await auditEntity.GetAuditLogsAsync(typeof(Project).FullName!, projectId.ToString());
-// by user / action / time, with paging
-var page = await auditEntity.GetAuditLogsAsync(new AuditLogFilter { UserId = "u1", Action = AuditAction.Updated, Take = 10 });
-// by user / tenant
-await auditEntity.GetAuditLogsByUserAsync("u1");
-await auditEntity.GetAuditLogsByTenantAsync("tenant-alpha");
-```
-
-Each `AuditLog` carries `{ UserId, UserName, Timestamp, Action, EntityType, EntityId, Metadata
-(correlationId, …) }`; its `EntityChanges` hold entity-level `ChangeType`, and — for `IFieldAudited`
-roots — nested `PropertyChanges` with `OriginalValue → NewValue`.
-
-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.

package/assets/docs/security/authorization.md

@@ -1,87 +0,0 @@
-# Authorization Standards
-
-> Pure technology (domain-agnostic) — domain roles & matrix in [[authorization.domain]]. NON-NEGOTIABLE. Commands: `/aw-spec-design`.
-
-## 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]]

package/assets/docs/security/data-classification.md

@@ -1,38 +0,0 @@
-# Data Classification Standards
-
-> Pure technology (domain-agnostic) — domain data categories in [[data-classification.domain]]. NON-NEGOTIABLE. Commands: `/aw-spec-design`.
-
-## Classification framework
-
-- Every data element is assigned a **sensitivity class**; controls (encryption, masking,
-  logging, export) are applied per class.
-- The concrete sensitivity taxonomy is project/domain-specific — see
-  [[data-classification.domain]] for the domain taxonomy.
-
-## Masking rules
-
-- Field-level redaction is applied in **projection extensions**, not controllers
-  (minimum-necessary by role/scope — see [[authorization]]).
-
-## Encryption requirements
-
-- AES-256 at rest (DB TDE + customer-managed key); TLS 1.2+ in transit (1.3 target);
-  encrypted backups.
-- **Application-level field encryption** for the most sensitive fields (the concrete field
-  list is domain-specific — see [[data-classification.domain]]).
-
-## Logging restrictions
-
-- **NEVER** log or emit in metrics/traces: authentication tokens, password material, private
-  keys, or full payment-card data.
-  (Domain-sensitive elements — PHI, SSN, government IDs — see [[data-classification.domain]].)
-
-## Export restrictions
-
-- Production data MUST NOT be copied to non-production environments without an approved
-  de-identification / anonymization step.
-- (Domain de-identification / anonymization specifics — see [[data-classification.domain]].)
-
-## Related
-
-- [[auditing]] · [[authorization]] · [[zero-trust]] · [[data-classification.domain]]

package/assets/docs/security/zero-trust.md

@@ -1,76 +0,0 @@
-# Zero-Trust Standards
-
-> Pure technology (domain-agnostic) — domain additions in [[zero-trust.domain]]. NON-NEGOTIABLE where marked. Commands: `/aw-spec-design`.
-
-## Transport security (mTLS / TLS)
-
-- HTTPS is enforced; **TLS 1.2 is the floor, TLS 1.3 the target**.
-- CORS uses **explicit allow-lists** — no wildcards.
-
-## Workload identity
-
-- Identity is composed via `.AddAppWeaverSecurity(...)` with an **external IdP**.
-- **Local identity stores are FORBIDDEN.**
-
-## Service authentication
-
-- Backing services and the IdP are declared as Aspire resources; connection strings,
-  hostnames, and ports are **discovered through Aspire — never hard-coded**.
-
-## Token propagation
-
-- Tokens / scopes are propagated through the request pipeline and honored on every endpoint
-  (see [[authorization]]).
-- Trace context propagates across `IMediator.Send`, `HttpClient`, and EF Core — bypassing the
-  framework `HttpClientFactory` is forbidden.
-
-## Internal authorization
-
-- Authorization is **role-based AND scope-based** — both enforced (see [[authorization]]).
-- Authentication tokens, password material, and private keys MUST NEVER appear in logs,
-  metrics, traces, or error messages (see [[data-classification]]).
-
-## Secrets
-
-- Secrets MUST come from **Aspire parameters** or a secrets manager (e.g. Azure Key Vault,
-  AWS Secrets Manager, HashiCorp Vault) — **NEVER from `appsettings.json`**.
-- Hard-coded connection strings, secrets, ports, or issuer URLs in source are a Forbidden
-  Pattern (see [[coding-standards]]).
-
-## Canonical example (agent reference — `<SampleProjectName>` sample)
-
-Secrets/IdP config read from configuration (Aspire parameters / secrets manager) — never
-hard-coded; explicit CORS allow-list; HTTPS enforced outside development:
-
-```csharp
-// <SampleProjectName>.Service/Program.cs
-var cfg = builder.Configuration;
-
-// IdP settings come from config — no client secrets or issuer URLs in source (see [[authorization]])
-builder.Services.AddAppWeaverSecurity(security => security
-    .AddAuthentication(auth => auth.UseAzureAdB2C(o =>
-    {
-        o.Instance = cfg["AzureAdB2C:Instance"]!;
-        o.Domain   = cfg["AzureAdB2C:Domain"]!;
-        o.ClientId = cfg["AzureAdB2C:ClientId"]!;
-    }, cfg))
-    .AddAuthorization(authz => authz.UseRoleBased(o => o.AdminRole = "Admin")),
-    options => { }, configuration: cfg);
-
-// Explicit CORS allow-list — no wildcards
-builder.Services.AddCors(o => o.AddPolicy("DevelopmentPolicy", p => p
-    .WithOrigins("http://localhost:7000", "http://localhost:3000")
-    .AllowAnyMethod().AllowAnyHeader().AllowCredentials()));
-
-var app = builder.Build();
-app.UseCors("DevelopmentPolicy");
-app.UseAuthentication();
-app.UseAuthorization();
-
-if (!app.Environment.IsEnvironment("Development"))
-    app.UseHttpsRedirection();   // enforce HTTPS outside dev
-```
-
-## Related
-
-- [[authorization]] · [[auditing]] · [[data-classification]] · [[zero-trust.domain]]

package/assets/docs/technology-constitution.md

@@ -1,172 +0,0 @@
-# Technology Constitution (domain-agnostic base)
-
-> **AppWeaver template — reusable engineering constitution.**
-> This file holds the technology-only principles. It is **not ratified on its own** — it is
-> composed with exactly **one** domain addenda file at ratification time.
-
-## How to use (compose-at-ratification)
-
-This file is **auto-loaded** by `/aw-spec-constitution` (it is in that command's auto-loaded
-engineering-standards set). You therefore pass only the **domain addenda**, which composes on
-top of this base:
-
-```
-/aw-spec-constitution @docs/healthcare-constitution.md
-/aw-spec-constitution @docs/pharma-constitution.md
-```
-
-`/aw-spec-constitution` merges the auto-loaded technology base with the supplied domain addenda
-into the single ratified `.aw-spec/memory/constitution.md` (auto-loaded by every command
-thereafter). Passing `@docs/technology-constitution.md` explicitly is harmless but redundant.
-
-- Core Principles **I–XV** below are domain-agnostic and reused verbatim across every project.
-- **PROJECT IDENTITY**, **REGULATORY REGIME**, domain principles (**XVI+**), folder additions,
-  and governance-override values are **supplied by the domain addenda file** — do not fill them
-  here.
-- Paths below use this repo's `docs/...` root. In a generated solution where the
-  engineering-standards docs live under `code/docs/...`, adjust the prefix accordingly.
-
-Treat this content as the canonical, supreme engineering authority that supersedes README,
-CLAUDE.md, AGENTS.md, and any other guidance. The detailed rules for each principle live in the
-engineering-standards docs under `docs/` (see the Context-Loading Map at the end); this
-file stays slim and authoritative.
-
-## Project Identity
-
-*Supplied by the domain addenda file.* Project name, mission, bounded contexts, regulatory
-regime, data residency, and architecture posture are provided by the composed domain addenda
-file (`docs/<domain>-constitution.md`). The technology base stays domain-agnostic.
-
-## Runtime Style
-
-A Modular Monolith built to evolve into independent services. It combines Clean Architecture,
-Domain-Driven Design, CQRS + Mediator, Vertical Slice feature organization, and
-Specification-Driven Development. Cross-cutting concerns are delegated to the AppWeaver
-framework family; business logic lives inside aggregates inside their owning module.
-
-## Core Principles (domain-agnostic)
-
-> Essence only — full rules in `docs/`, see the map below.
-
-### I — Modular Monolith with Vertical Slices (NON-NEGOTIABLE)
-Single deployable service partitioned into modules; each module = Domain/Features/Persistence/Shared; each feature is a self-contained vertical slice; no cross-module Domain coupling; no horizontal service layers.
-→ `docs/architecture/modular-monolith.md`, `vertical-slices.md`
-
-### II — Clean Architecture Dependency Rule (NON-NEGOTIABLE)
-Dependencies flow inward: API → Application → Domain ← Infrastructure. Domain is framework-agnostic; endpoints call `IMediator`, never repositories/DbContext.
-→ `docs/architecture/clean-architecture.md`
-
-### III — Domain-Driven Design with Rich Aggregates (NON-NEGOTIABLE)
-Access entities through aggregate roots; strongly-typed Vogen IDs; sealed validating value objects; immutable domain events; invariants enforced in the aggregate; transaction boundary = aggregate boundary.
-→ `docs/domain/domain-driven-design.md`
-
-### IV — CQRS via Mediator with Result Pattern (NON-NEGOTIABLE)
-All logic dispatched via AppWeaver.Mediator; commands/queries return `Result<T>`; errors are `Result.Failure` (not exceptions); writes run in a transaction and publish domain events.
-→ `docs/architecture/cqrs.md`
-
-### V — Specification-Driven Persistence (NON-NEGOTIABLE)
-Query composition lives in Domain Specifications; no ad-hoc LINQ in handlers; no cross-aggregate EF navigation joins; reference parents by strongly-typed ID.
-→ `docs/architecture/persistence.md`
-
-### VI — Immutable Contracts at the Edge
-Shared DTOs mapped with hand-written `ToDto()`; no reflection mappers; `RowVersionBase64` on concurrency-tracked DTOs; standard `PagedResult<T>`; external projections stay parallel.
-→ `docs/architecture/vertical-slices.md`
-
-### VII — Optimistic Concurrency via ETag / If-Match (NON-NEGOTIABLE)
-Mutable aggregates implement `IConcurrencyTracked`; ETag set on every create/read/update; `If-Match` required on update/delete; mismatch → 409 `concurrency.conflict`.
-→ `docs/architecture/persistence.md`, `docs/governance/api-versioning.md`
-
-### VIII — Multi-Provider, Multi-Tenant Persistence
-Provider-aware `ContextAwareDbContext`; PostgreSQL production / SQLite dev (non-sensitive); client-managed concurrency tokens; cross-cutting soft-delete/tenant/audit behaviors; hard delete forbidden for retention-protected data.
-→ `docs/architecture/persistence.md`
-
-### IX — Security by Default (NON-NEGOTIABLE)
-`SecureFastEndpoint` + declared cache policy; external IdP only (no local identity); role-based **and** scope-based auth; secrets from a manager not appsettings; TLS 1.2+; explicit CORS; sensitive data encrypted in transit and at rest (CMK).
-→ `docs/security/zero-trust.md`, `authorization.md`, `data-classification.md`
-
-### X — Observability is a First-Class Citizen (NON-NEGOTIABLE)
-AppWeaver.ServiceDefaults (OTel + Serilog + health + resilience + discovery); `ILogger` message templates only; never log secrets/regulated data; every sensitive read/mutation emits an audit record; trace context propagates everywhere.
-→ `docs/security/auditing.md`, `data-classification.md`
-
-### XI — Cloud-Native Orchestration via .NET Aspire
-AppHost is the composition root; backing services are Aspire resources referenced via `.WithReference(...)`; no hard-coded connection strings/ports; Helm stays in sync with the AppHost projection.
-→ `docs/security/zero-trust.md`, `architecture/eventing.md`
-
-### XII — REST API Standards
-Internal REST (FastEndpoints, one endpoint/file, kebab routes); standard paging; versioned breaking changes; machine-readable contracts (OpenAPI). Domain interoperability surfaces (e.g. FHIR) are added by the domain addenda.
-→ `docs/governance/api-versioning.md`, `architecture/vertical-slices.md`
-
-### XIII — Test-First Engineering
-Tests for every aggregate behavior/value object/specification/handler/endpoint; deterministic (`IClock`/`IGuidGenerator`); contract changes ship with test updates in the same commit.
-→ `docs/architecture/testing.md`
-
-### XIV — Data Integration Layer / Single Source of Truth (NON-NEGOTIABLE)
-Authoritative system of record; consumers use the REST API / published projections / CloudEvents only; no direct DB access; inbound feeds flow through Interop adapters; versioned machine-readable schemas.
-→ `docs/architecture/eventing.md`, `docs/governance/api-versioning.md`
-
-### XV — Evolutionary Path to Microservices
-Modules own their aggregates/persistence/DTOs/projectors/events; cross-module access via Shared DTOs or `IMediator`; per-module schemas recommended; extraction approved by amendment.
-→ `docs/architecture/modular-monolith.md`
-
-> **Domain principles (XVI and beyond) are supplied by the domain addenda file.**
-
-## Mandatory Folder Structure
-
-Governed by the engineering-standards docs; this file does not duplicate the tree.
-
-- Technology layout (src/tests/helm/docs, module = Domain/Features/Persistence/Shared): `docs/architecture/folder-structure.md`
-- Domain-specific additions (Interop adapters, domain test fixtures, regulatory controls): supplied by the domain addenda + `docs/domainspecs/<domain>/folder-structure.domain.md`
-
-Project names use the `<SampleProjectName>` placeholder. Cross-cutting files (`Program.cs`, `GlobalUsings.cs`, `Directory.Build.props`, `Directory.Packages.props`, `global.json`) MUST stay at the same level they occupy in the AppWeaver template.
-
-## Conventions, Forbidden Patterns, AI Rules, Quality Gates
-
-These are governed in full by the engineering-standards docs; this file does not duplicate them.
-
-- Naming & coding conventions, the Forbidden Patterns, and the CI Quality Gates: `docs/governance/coding-standards.md`
-- Package governance (approved/banned packages, supply-chain, licensing): `docs/governance/dependency-policy.md`
-- AI operational rules (generation, context loading, refusal conditions): `docs/glossary/ai-rules.md` (the domain addenda extends this with domain-specific masking / code / refusal rules)
-
-## Governance
-
-- This constitution supersedes all other engineering documentation in the repository (README.md, CLAUDE.md, AGENTS.md, wiki pages). Where they disagree, this document wins. The `docs/` engineering standards are the authorized expansion of these principles; if a doc contradicts a principle here, this file wins and the doc is corrected.
-- Amendments are proposed via pull request that modifies `.aw-spec/memory/constitution.md` (and the affected `docs/` files), includes a migration plan for non-compliant code, bumps the version per the policy below, and is approved per the roles named in the domain addenda's Governance Overrides (at minimum one Principal Engineer + the domain's mandatory approver).
-- Versioning follows SemVer applied to governance:
-  - **MAJOR** — removal or weakening of a NON-NEGOTIABLE principle, or a backward-incompatible change to the Mandatory Folder Structure or a domain's canonical interoperability surface.
-  - **MINOR** — addition of a new principle, new mandatory section, or new bounded context.
-  - **PATCH** — clarifications, wording fixes, non-semantic edits.
-- Compliance review happens on every PR. Reviewers MUST cite the principle number when requesting changes.
-- A quarterly architecture and security review MUST audit a random sample of modules against this constitution and file remediation tickets for any deviation.
-- Runtime guidance (CLAUDE.md / AGENTS.md) MUST contain a single pointer to this constitution and MUST NOT duplicate or paraphrase its rules.
-- Domain-specific governance overrides (approver roles, regulatory review triggers, control mappings) are supplied by the domain addenda file.
-
-## Context-Loading Map
-
-> Include only the relevant docs per AW-Spec command. Full index: `docs/README.md`.
-
-**Doc naming convention (technology vs. domain):**
-
-- `docs/<area>/<name>.md` = **pure technology** rule, domain-agnostic — reusable across any project. **Loaded automatically** by each AW-Spec command (see the command's SKILL.md); you do not pass them by hand.
-- `docs/domainspecs/<domain>/<name>.md` and `<name>.domain.md` = **domain-specific** rules under one folder. The `.domain.md` files extend the matching technology file; the plain `.md` files are inherently domain.
-
-**Per-command file map** (technical default that auto-loads vs. domain files to add):
-
-- Technical defaults: the *Auto-Loaded Engineering Standards* section in each `.claude/skills/aw-spec-<command>/SKILL.md` (authoritative).
-- Domain files: the active domain's `docs/domainspecs/<domain>/comandrulemap.md`.
-
-Rule of thumb: technology standards auto-load; add only the domain files listed in the active domain's `comandrulemap.md` for the slice you are building.
-
-## Domain Requirements
-
-Project-specific and maintained separately so it can be updated independently per project:
-→ `docs/domainspecs/<domain>/domain-requirements.md` (named by the domain addenda file)
-
-This holds `[DOMAIN: Bounded Contexts / Modules]`, the per-subsection pointers into `docs/`, `[DOMAIN: Platform Topology]`, and `[DOMAIN: Governance Overrides]`. The technology base above stays domain-agnostic.
-
-## Ratification Metadata
-
-> Finalized by the composed domain addenda.
-
-- **Version:** 1.0.0
-- **Ratified:** `<YYYY-MM-DD>`
-- **Last Amended:** `<YYYY-MM-DD>`