aw-spec-cli 0.1.8 → 0.1.9

package/assets/guardrails/technology/dotnet-webapi/examples/vertical-slices.md

@@ -0,0 +1,151 @@
+# Vertical Slice Standards — canonical example
+
+> The worked `<SampleProjectName>` example for
+> `guardrails/technology/dotnet-webapi/vertical-slices.md`. It is reference material for the
+> phases that generate code — mapped for `design` — and carries no rule of its own: where this
+> example and the rule file disagree, the rule file wins.
+>
+> It is deliberately absent from the `## /aw-spec-constitution` set. The constitution is a
+> thin authority document — one declarative line and a `→` pointer per principle — and has no
+> use for sample code.
+
+## Canonical example (agent reference — `<SampleProjectName>` sample)
+
+A complete slice: Endpoint (+ request class in the same file), Validator, DTO, and mapping.
+
+```csharp
+// <SampleProjectName>.Service/Projects/Features/CreateProject/CreateProjectEndpoint.cs
+public class CreateProjectEndpoint(IMediator _mediator)
+    : SecureFastEndpoint<CreateProjectRequest, ProjectDto>
+{
+    public override void Configure()
+    {
+        Post("/projects");                                  // kebab-case, plural noun
+        Summary(s => s.Summary = "Create a new project");
+        Options(o => o.WithTags("02 - Project - (FastEndpoints)"));
+    }
+
+    protected override SecurityCachePolicy GetSecurityCachePolicy() => new()
+    {
+        SecurityLevel = SecurityLevel.Internal,
+        CachePolicy = CachePolicy.NoStore                   // mutating endpoint
+    };
+
+    protected override async Task<Result<ProjectDto>> ExecuteAsync(
+        CreateProjectRequest req, CancellationToken ct)
+    {
+        var result = await _mediator.Send(new CreateProjectCommand(   // IMediator only
+            req.Code, req.Name, req.Description, req.StartDate, req.EndDate, req.OwnerId), ct);
+
+        if (result.IsSuccess && !string.IsNullOrWhiteSpace(result.Value?.RowVersionBase64))
+            HttpContext.Response.SetETagFromBase64(result.Value!.RowVersionBase64);
+        return result;
+    }
+}
+
+// Request lives in the SAME file — primitive types only
+public class CreateProjectRequest
+{
+    public string Code { get; set; } = string.Empty;
+    public string Name { get; set; } = string.Empty;
+    public string? Description { get; set; }
+    public DateOnly StartDate { get; set; }
+    public DateOnly? EndDate { get; set; }
+    public Guid? OwnerId { get; set; }
+}
+```
+
+```csharp
+// .../CreateProject/CreateProjectValidator.cs — request shape only
+public class CreateProjectValidator : AbstractValidator<CreateProjectCommand>
+{
+    public CreateProjectValidator()
+    {
+        RuleFor(x => x.Code).NotEmpty().MaximumLength(20).Matches(@"^[A-Z0-9\-]+$");
+        RuleFor(x => x.Name).NotEmpty().MaximumLength(200);
+        RuleFor(x => x.EndDate)
+            .GreaterThanOrEqualTo(x => x.StartDate).When(x => x.EndDate.HasValue);
+    }
+}
+```
+
+```csharp
+// {Module}/Shared/ProjectDto.cs — includes RowVersionBase64 (IConcurrencyTracked)
+public record ProjectDto
+{
+    public Guid Id { get; set; }
+    public string Code { get; set; } = string.Empty;
+    public string Name { get; set; } = string.Empty;
+    public string Status { get; set; } = string.Empty;
+    public Guid? OwnerId { get; set; }
+    public List<ProjectTaskDto> Tasks { get; set; } = new();
+    public string RowVersionBase64 { get; set; } = string.Empty;
+}
+
+// {Module}/Shared/ProjectMappingExtensions.cs — hand-written, zero reflection
+public static class ProjectMappingExtensions
+{
+    public static ProjectDto ToDto(this Project e) => new()
+    {
+        Id = e.Id.Value, Code = e.Code.Value, Name = e.Name,
+        Status = e.Status.ToString(), OwnerId = e.OwnerId?.Value,
+        Tasks = e.Tasks.Select(t => t.ToDto()).ToList(),
+        RowVersionBase64 = e.RowVersion is { Length: > 0 } rv
+            ? Convert.ToBase64String(rv) : string.Empty
+    };
+
+    public static List<ProjectDto> ToDtoList(this IEnumerable<Project> es)
+        => es.Select(e => e.ToDto()).ToList();
+}
+```
+
+Sub-resource endpoint for a distinct operation on a child — nested route, multiple route
+params, `EmptyResponse` when there is no body to return:
+
+```csharp
+// .../Features/AssignTask/AssignTaskEndpoint.cs
+public class AssignTaskEndpoint(IMediator _mediator)
+    : SecureFastEndpoint<AssignTaskRequest, EmptyResponse>
+{
+    public override void Configure()
+    {
+        Put("/projects/{projectId:guid}/tasks/{taskId:guid}/assignee");   // sub-resource
+        Summary(s => s.Summary = "Assign a task to a TaskUser");
+        Options(o => o.WithTags("02 - Project - (FastEndpoints)"));
+    }
+
+    protected override SecurityCachePolicy GetSecurityCachePolicy() => new()
+    { SecurityLevel = SecurityLevel.Internal, CachePolicy = CachePolicy.NoStore };
+
+    protected override async Task<Result<EmptyResponse>> ExecuteAsync(
+        AssignTaskRequest req, CancellationToken ct)
+    {
+        var projectId = Route<Guid>("projectId");
+        var taskId = Route<Guid>("taskId");
+        var result = await _mediator.Send(new AssignTaskCommand(projectId, taskId, req.AssigneeId), ct);
+        return result.IsSuccess
+            ? Result<EmptyResponse>.Ok(new EmptyResponse())
+            : Result<EmptyResponse>.Failure([.. result.Errors]);
+    }
+}
+
+public class AssignTaskRequest { public Guid AssigneeId { get; set; } }
+```
+
+Standard `PagedResult<T>` contract (required init props, computed `TotalPages`):
+
+```csharp
+// {Module}/Common/PagedResult.cs
+public sealed class PagedResult<T>
+{
+    public required IReadOnlyList<T> Items { get; init; }
+    public required int TotalCount { get; init; }
+    public required int PageNumber { get; init; }
+    public required int PageSize { get; init; }
+    public int TotalPages => (int)Math.Ceiling((double)TotalCount / PageSize);
+}
+```
+
+## Related
+
+- Rule file: `guardrails/technology/dotnet-webapi/vertical-slices.md`

package/assets/guardrails/technology/dotnet-webapi/examples/zero-trust.md

@@ -0,0 +1,48 @@
+# Zero-Trust Standards — canonical example
+
+> The worked `<SampleProjectName>` example for
+> `guardrails/technology/dotnet-webapi/zero-trust.md`. It is reference material for the phases
+> that generate code — mapped for `design` — and carries no rule of its own: where this
+> example and the rule file disagree, the rule file wins.
+>
+> It is deliberately absent from the `## /aw-spec-constitution` set. The constitution is a
+> thin authority document — one declarative line and a `→` pointer per principle — and has no
+> use for sample code.
+
+## 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
+
+- Rule file: `guardrails/technology/dotnet-webapi/zero-trust.md`

package/assets/guardrails/technology/dotnet-webapi/folder-structure.md

@@ -0,0 +1,61 @@
+# Mandatory Folder Structure
+
+> Pure technology (domain-agnostic) — domain additions (Interop adapters, conformance tests, fixtures) in [[folder-structure.domain]]. NON-NEGOTIABLE. Commands: `/aw-spec-design`, `/aw-spec-implement`, `/aw-spec-implement-delta`.
+>
+> Replace `<SampleProjectName>` with the project name (e.g. `Acme.Billing`).
+
+## Layout
+
+```
+src/
+  <SampleProjectName>.AppHost/            Aspire composition root (Program.cs)
+  <SampleProjectName>.ServiceDefaults/    OTel + Serilog + resilience + service discovery
+  <SampleProjectName>.Service/            headless API runtime  (a.k.a. <SampleProjectName>.Api)
+    Program.cs                            composition only
+    GlobalUsings.cs
+    appsettings.json / appsettings.{Env}.json
+    Common/                               PagedResult<T> + shared value objects
+    Extensions/                           ApplicationServiceRegistration (mediator/eventbus),
+                                          InfrastructureServiceRegistration (DbContext/repos),
+                                          Aspire/Host extensions, SpecificationExtensions
+    Infrastructure/
+      ApplicationDbContext.cs             ContextAwareDbContext<T>
+      *DbContextFactory.cs                design-time factories
+      Migrations/
+    Utilities/                            ETag/HTTP helpers (HttpRequest/Response ETag ext)
+    <Module>/                             one folder per bounded context
+      Domain/
+        <Aggregate>.cs
+        <ChildEntity>.cs
+        <ValueObject>.cs
+        <Aggregate>Id.cs                  [ValueObject<Guid>] partial struct
+        Enums/                            (optional) status/priority enums
+        Events/                           DomainEventBase descendants
+        Specifications/                   Specification<TAggregate>
+      Persistence/
+        <Aggregate>Configuration.cs       (+ <ChildEntity>Configuration.cs)
+      Features/<FeatureName>/             Command/Query + Handler + Endpoint + Validator
+      Shared/                             module-public DTOs + ToDto mapping extensions
+tests/
+  <SampleProjectName>.UnitTests/
+  <SampleProjectName>.IntegrationTests/   Testcontainers-driven
+  <SampleProjectName>.TestFixtures/       shared test fixtures
+helm/
+  <SampleProjectName>.Api/
+guardrails/                                     engineering standards (see [[README]] + context map)
+```
+
+## Rules
+
+- Each **module** is a top-level folder with `Domain / Features / Persistence / Shared`
+  (see [[modular-monolith]], [[vertical-slices]]).
+- Each **feature** is a self-contained vertical slice (Command/Query + Handler + Endpoint +
+  Validator co-located).
+- Cross-cutting files (`Program.cs`, `GlobalUsings.cs`, `Directory.Build.props`,
+  `Directory.Packages.props`, `global.json`) MUST stay at the level they occupy in the
+  AppWeaver template.
+- New folders outside this structure require a constitution amendment.
+
+## Related
+
+- [[modular-monolith]] · [[vertical-slices]] · [[clean-architecture]] · [[folder-structure.domain]]

package/assets/guardrails/technology/dotnet-webapi/modular-monolith.md

@@ -0,0 +1,47 @@
+# Modular Monolith Standards
+
+> Pure technology (domain-agnostic). NON-NEGOTIABLE where marked. Commands: `/aw-spec-design`.
+
+## Module boundaries
+
+- The runtime is a **single deployable service** partitioned into bounded contexts (modules).
+- Each module is a **top-level folder** containing four mandatory child folders:
+  `Domain`, `Features`, `Persistence`, `Shared` (plus `Interop` where applicable).
+- A module **owns** its aggregates, persistence configurations, DTOs, integration
+  adapters/projectors, and public events. Nothing outside the module may reach past these.
+
+## Cross-module communication
+
+- Modules **MUST NOT** reference another module's `Domain` types except through
+  **strongly-typed IDs** or the other module's **`Shared` DTOs**.
+- Modules **MUST NOT** take EF Core `DbSet` dependencies on entities they do not own.
+- **Cross-module reads** go through the other module's `Shared` DTOs or its `IMediator`
+  queries — never through its `DbContext` entities.
+- **Cross-module writes** go through commands published to `IMediator` (in-process today,
+  on the event bus tomorrow). A module **MUST NOT** acquire a write lock on another
+  module's aggregate.
+- No horizontal "Services/Managers" layers across slices.
+
+## Schema-per-module guidance
+
+- Per-module schemas in PostgreSQL (**schema-per-module**) are RECOMMENDED so a future
+  service extraction is a clean cutover.
+
+## Module isolation / testability
+
+- Every module **MUST be testable in isolation**: its unit tests and handler tests
+  **MUST NOT** require any other module to be loaded.
+
+## Future microservice extraction strategy
+
+- Today's modules are tomorrow's services. Splitting a module into its own service
+  **MUST require zero changes to the domain code of other modules**.
+- Migration to microservices is **approved by amendment** when a module's deployment
+  cadence, scaling profile, team ownership, or regulatory boundary materially diverges
+  from the rest of the monolith.
+
+## Related
+
+- [[vertical-slices]] — feature organization within a module
+- [[clean-architecture]] — dependency rule across layers
+- [[eventing]] — async cross-module/event-bus propagation

package/assets/guardrails/technology/dotnet-webapi/persistence.md

@@ -0,0 +1,82 @@
+# Persistence Standards
+
+> Pure technology (domain-agnostic) — domain additions in [[persistence.domain]]. NON-NEGOTIABLE where marked. Commands: `/aw-spec-design`, `/aw-spec-run`.
+
+## EF Core conventions
+
+- The `DbContext` is a `ContextAwareDbContext<TContext>` and is **provider-aware**.
+- EF Core mapping lives **only** in `{Module}/Persistence/<Aggregate>Configuration.cs`,
+  applied via `ApplyConfigurationsFromAssembly`.
+- `DateTimeOffset` columns **MUST** be re-mapped to `timestamptz` when the provider is Npgsql.
+- Cross-cutting behaviors are applied via `modelBuilder.ApplyCrossCuttingBehaviors(this)`:
+  soft-delete global filters, tenant filters, base concurrency-token configuration.
+
+## Repository rules
+
+- **Read handlers** inject `IReadRepository<TAggregate>`; **write handlers** inject
+  `IRepository<TAggregate>` + `IUnitOfWork`.
+- No "repository as data-access god object" — **no custom methods** beyond
+  `IRepository<T>` / `IReadRepository<T>` + `Specification<T>`.
+- Direct `DbContext.Set<T>()` LINQ inside Application Features is FORBIDDEN — use
+  `IReadRepository<T>` + a `Specification<T>` only.
+
+## Specification pattern
+
+- Every non-trivial query is encapsulated in a `Specification<TAggregate>` under
+  `{Module}/Domain/Specifications/`.
+- Specifications **MUST be composable**; paging via `WithPaging(pageNumber, pageSize)`.
+- Ordering uses shared generic helpers (`OrderByIdAsc`, `OrderByIdDesc`, `OrderByNameAsc`);
+  ad-hoc `OrderBy` in handlers is forbidden when a typed helper exists.
+- **Cross-aggregate joins via EF navigation properties are FORBIDDEN** — reference parent
+  aggregates by strongly-typed ID and project client-side.
+
+## Concurrency handling
+
+- Every mutable aggregate **MUST** implement `IConcurrencyTracked`.
+- Concurrency tokens are **client-managed**: `byte[] RowVersion`,
+  `IsConcurrencyToken().ValueGeneratedNever()`, refreshed by a `SaveChanges` interceptor.
+- SQL Server `IsRowVersion()` semantics **MUST NOT** leak into entity configurations.
+- ETag / `If-Match` at the edge: see [[api-versioning]].
+  - Server sets the ETag header on every create/read/update via `SetETagFromBase64(...)`.
+  - Update/Delete endpoints extract `If-Match` via `GetIfMatchBase64Token()` and pass it
+    to the command; mismatch returns `409 concurrency.conflict`.
+  - `DbUpdateConcurrencyException` is translated to the same `409 concurrency.conflict`.
+
+## Soft-delete rules
+
+- Soft delete is enabled via `EnableSoftDelete()`.
+- **Hard deletes are FORBIDDEN** for any aggregate flagged as retention-protected / regulated;
+  deletion is logical via `MarkAsDeleted(...)`. (See [[persistence.domain]] for which data
+  classes are retention-protected.)
+- Append-only aggregates have no delete path at all.
+
+## Tenancy patterns
+
+- Tenancy is enabled via `EnableTenancy()` and `RegisterDefaultContexts(...)`.
+- Tenant resolution **MUST be transparent** to handlers.
+- Default model: **tenant-per-row** with tenant-aware global filters; deployments MAY opt
+  into tenant-per-database via configuration.
+
+## Migrations policy
+
+- Migrations are authored against **PostgreSQL** (production provider). Development MAY run
+  on SQLite (non-sensitive development data only).
+- Multi-provider warnings (`PendingModelChangesWarning`) **MUST** be suppressed only at the
+  runtime registration site, **never** in migration code.
+- Migrations **MUST** apply cleanly to a fresh PostgreSQL instance (CI gate).
+
+## Provider profile
+
+- Production: PostgreSQL 16+ (encryption-at-rest profile in [[persistence.domain]]);
+  per-module schemas where reasonable.
+- Development: PostgreSQL via Aspire containers; SQLite only for in-memory unit-test fixtures.
+
+## Canonical example
+
+The worked `<SampleProjectName>` example for these rules lives in
+`guardrails/technology/dotnet-webapi/examples/persistence.md`, mapped for `design` and `run`.
+The constitution set maps the rules without it.
+
+## Related
+
+- [[clean-architecture]] · [[cqrs]] · [[domain-driven-design]] · [[api-versioning]] · [[persistence.domain]]

package/assets/guardrails/technology/dotnet-webapi/technology-constitution.md

@@ -0,0 +1,162 @@
+# Technology Constitution — dotnet-webapi (domain-agnostic base)
+
+> The technology-only governance base for this stack corpus. It heads the set mapped under
+> `## /aw-spec-constitution` in a project's `tech-rule-bindings.md` — this file, then the
+> standard technical rules beside it, then the project team's `technical-requirements.md` —
+> which `/appweaver constitution` ratifies into `.appweaver/memory/constitution.technical.md`.
+
+This file is domain-agnostic on purpose: the constitution command loads it *before* the domain
+is selected, and that ordering is what keeps the technical half free of domain material. The
+project's three constitutional SETS are siblings, never merged here — each is headed by
+its own base file:
+
+| Source | Ratified into | Principle series |
+|---|---|---|
+| `technology-constitution.md` (this file) | `constitution.technical.md` | I–XV |
+| `domain-constitution.md` | `constitution.domain.md` | XVI+ |
+| the lane corpus's `ui-constitution.md` | `constitution.ui.md` | UX-* |
+
+- Core Principles **I–XV** below are domain-agnostic and reused across every project that maps this corpus.
+- **PROJECT IDENTITY**, **REGULATORY REGIME**, domain principles (**XVI+**), domain folder
+  additions and governance-override values are **not** filled here — they come from
+  `domain-constitution.md`.
+- **Experience principles (UX-\*)** are not filled here — they come from the lane corpus's
+  `ui-constitution.md`.
+
+This content is the supreme engineering authority for the service lane: where any other
+engineering guidance in the repository disagrees, this document wins. It stays slim and
+authoritative — the detailed rules live in the technical rule files each principle cites.
+
+## 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 — the full rules live in the cited rule file.
+
+### 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.
+→ `guardrails/technology/dotnet-webapi/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.
+→ `guardrails/technology/dotnet-webapi/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.
+→ `guardrails/technology/dotnet-webapi/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.
+→ `guardrails/technology/dotnet-webapi/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.
+→ `guardrails/technology/dotnet-webapi/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.
+→ `guardrails/technology/dotnet-webapi/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`.
+→ `guardrails/technology/dotnet-webapi/persistence.md`, `guardrails/technology/dotnet-webapi/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.
+→ `guardrails/technology/dotnet-webapi/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).
+→ `guardrails/technology/dotnet-webapi/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.
+→ `guardrails/technology/dotnet-webapi/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.
+→ `guardrails/technology/dotnet-webapi/zero-trust.md`, `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 half.
+→ `guardrails/technology/dotnet-webapi/api-versioning.md`, `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.
+→ `guardrails/technology/dotnet-webapi/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.
+→ `guardrails/technology/dotnet-webapi/eventing.md`, `guardrails/technology/dotnet-webapi/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.
+→ `guardrails/technology/dotnet-webapi/modular-monolith.md`
+
+> **Domain principles (XVI and beyond) are supplied by `domain-constitution.md`.**
+> **Experience principles (UX-\*) are supplied by the lane corpus's `ui-constitution.md`.**
+
+## Mandatory Folder Structure
+
+Governed by the technical rule files; this file does not duplicate the tree.
+
+- Technology layout (src/tests/helm/docs, module = Domain/Features/Persistence/Shared):
+  `guardrails/technology/dotnet-webapi/folder-structure.md`
+- Domain-specific additions (Interop adapters, domain test fixtures, regulatory controls):
+  supplied by `domain-constitution.md` + the active domain corpus's `folder-structure.domain.md`
+- The frontend lane's layout lives entirely under its own root and is supplied by that lane's
+  own corpus, `guardrails/technology/nextjs/ui-constitution.md`. Nothing here applies to it.
+
+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
+
+Governed in full by the technical rule files; this file does not duplicate them.
+
+- Naming & coding conventions, the Forbidden Patterns, and the CI Quality Gates:
+  `guardrails/technology/dotnet-webapi/coding-standards.md`
+- Package governance (approved/banned packages, supply-chain, licensing):
+  `guardrails/technology/dotnet-webapi/dependency-policy.md`
+- AI operational rules (generation, context loading, refusal conditions):
+  `.appweaver/ai-rules.md` — the domain half extends this with domain-specific masking,
+  code-set and refusal rules
+
+## Governance
+
+- This constitution supersedes all other engineering documentation in the repository. Where they
+  disagree, this document wins; a rule file that contradicts a principle here is the file that
+  gets corrected.
+- Amendments are proposed via pull request that modifies this file (and the affected rule
+  files), includes a migration plan for non-compliant code, bumps the version per the policy
+  below, and is approved per the roles named in `domain-constitution.md`'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.
+  - **MINOR** — addition of a new principle, new mandatory section, or new bounded context.
+  - **PATCH** — clarifications, wording fixes, non-semantic edits.
+- This file versions independently of `domain-constitution.md` and `ui-constitution.md`.
+- 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 files MUST carry a single pointer to the ratified constitution and MUST NOT
+  duplicate or paraphrase its rules.
+- Domain-specific governance overrides (approver roles, regulatory review triggers, control
+  mappings) are supplied by `domain-constitution.md`.
+
+## Ratification Metadata
+
+> Carried into `constitution.technical.md` at ratification; the constitution command owns the
+> version bump from there.
+
+- **Version:** 1.0.0
+- **Ratified:** `<YYYY-MM-DD>`
+- **Last Amended:** `<YYYY-MM-DD>`

package/assets/guardrails/technology/dotnet-webapi/testing.md

@@ -0,0 +1,55 @@
+# Testing Standards
+
+> Pure technology (domain-agnostic) — domain additions in [[testing.domain]]. Commands: `/aw-spec-design`, `/aw-spec-implement`, `/aw-spec-implement-delta`, `/aw-spec-analyze-slice`.
+
+## Test-first engineering
+
+- Generated tests follow Test-First Engineering and **MUST fail before** the production
+  change is in place.
+- Any change to an aggregate invariant, endpoint contract, or error code **MUST** include
+  the corresponding test update **in the same commit**.
+
+## Unit test conventions
+
+- Unit tests are required for **every** aggregate behavior, value object, and specification.
+- Tests are **deterministic** — time, randomness, and IDs are injected
+  (use the framework-provided `IClock` / `IGuidGenerator`). Never `DateTime.UtcNow` /
+  `Guid.NewGuid()` in the system under test.
+- Tests **MUST NOT** reach into module internals; they exercise the public endpoint or
+  `IMediator` surface.
+
+## Handler tests
+
+Required for **every** Command/Query handler and MUST cover:
+
+- happy path
+- validation failure
+- not-found
+- (for writes) concurrency conflict
+
+## Integration testing
+
+- Required for **every** endpoint; run against **PostgreSQL via Testcontainers** or Aspire.
+- Test database engine: Testcontainers PostgreSQL for integration; in-memory fixtures for
+  unit tests.
+
+## Testcontainers usage
+
+- Integration and contract tests spin up real PostgreSQL (and other backing services)
+  via Testcontainers / Aspire — no faked persistence in integration tests.
+
+## Test data hygiene
+
+- Tests use a **shared fixture library** rather than inlining fabricated data.
+- Production data MUST NOT be used in development, test, demo, or shared CI.
+  (Domain specifics — synthetic fixtures + terminology sentinels — in [[testing.domain]].)
+
+## Coverage rules
+
+- Minimum **85% line coverage** on Application + Domain.
+- **100%** on aggregate behaviors and value objects.
+- Code coverage on changed files must meet the threshold (CI gate).
+
+## Related
+
+- [[domain-driven-design]] · [[persistence]] · [[testing.domain]]