aw-spec-cli 0.1.7 → 0.1.9

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

@@ -0,0 +1,39 @@
+# 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
+
+The worked `<SampleProjectName>` example for these rules lives in
+`guardrails/technology/dotnet-webapi/examples/authorization.md`, mapped for `design`. The
+constitution set maps the rules without it.
+
+## Related
+
+- [[zero-trust]] · [[auditing]] · [[data-classification]] · [[authorization.domain]]

package/assets/guardrails/technology/dotnet-webapi/clean-architecture.md

@@ -0,0 +1,54 @@
+# Clean Architecture Standards
+
+> Pure technology (domain-agnostic). NON-NEGOTIABLE. Commands: `/aw-spec-design`, `/aw-spec-build`.
+
+## Dependency direction
+
+Dependencies flow **inward only**:
+
+```
+API  ->  Application (Features)  ->  Domain  <-  Infrastructure
+```
+
+The Domain is the innermost ring; everything depends on it and it depends on nothing.
+
+## Layer responsibilities
+
+- **API** — HTTP surface (FastEndpoints). Translates transport to/from mediator
+  messages. MUST NOT contain business logic.
+- **Application (Features)** — Command/Query handlers, validators, orchestration.
+  Dispatched via `IMediator`. MUST NOT depend on API frameworks or concrete EF Core types.
+- **Domain** — aggregates, entities, value objects, domain events, specifications.
+  Framework-agnostic.
+- **Infrastructure** — EF Core, external service clients, persistence configuration.
+  Depends inward on Domain abstractions.
+
+## Allowed dependencies / annotations in Domain
+
+The Domain layer is framework-agnostic. The **only** allowed annotations are:
+
+- `[NotMapped]`
+- `[ValueObject<T>]` (Vogen)
+- `System.ComponentModel.DataAnnotations.Schema`
+
+## Infrastructure boundaries
+
+- EF Core mapping lives **only** in `{Module}/Persistence/<Aggregate>Configuration.cs` and is
+  applied via `ApplyConfigurationsFromAssembly`.
+- **Endpoints MUST NOT** call repositories, `DbContext`, or `IUnitOfWork` directly; they
+  **MUST** call `IMediator.Send(...)`.
+- **Application Features MUST NOT** depend on API frameworks or concrete EF Core types.
+- Direct `DbContext` access from Endpoints or Application Features (outside the
+  repository / specification surface) is FORBIDDEN.
+
+## Canonical example
+
+The worked `<SampleProjectName>` example for these rules lives in
+`guardrails/technology/dotnet-webapi/examples/clean-architecture.md`, mapped for `design` and
+`build`. The constitution set maps the rules without it.
+
+## Related
+
+- [[cqrs]] — how the Application layer dispatches work
+- [[persistence]] — repository + specification surface, EF Core conventions
+- [[vertical-slices]] — physical organization of the layers per feature

package/assets/guardrails/technology/dotnet-webapi/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-implement`, `/aw-spec-implement-delta`, `/aw-spec-build`, `/aw-spec-analyze-slice`.
+
+## 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/guardrails/technology/dotnet-webapi/cqrs.md

@@ -0,0 +1,63 @@
+# CQRS + Mediator Standards
+
+> Pure technology (domain-agnostic) — domain additions in [[cqrs.domain]]. NON-NEGOTIABLE. Commands: `/aw-spec-design`.
+
+## Command / query patterns
+
+- All application logic is dispatched through **`AppWeaver.Mediator`** (NOT MediatR).
+- **Commands:** `record XxxCommand(...) : ICommand<Result<TDto>>` or `ICommand<Result>`.
+- **Queries:** `record XxxQuery(...) : IQuery<Result<TDto>>`.
+- Handlers use **primary-constructor DI** and return `ValueTask<Result<T>>`.
+
+## Mediator conventions
+
+- Endpoints call `IMediator.Send(...)` — never repositories/`DbContext`/`IUnitOfWork` directly.
+- Raw `Guid` parameters at the Application boundary **MUST be wrapped** into strongly-typed
+  IDs at the handler edge.
+
+## Pipeline behaviors
+
+Enabled at startup, in order:
+
+1. Logging behavior
+2. FluentValidation behavior
+
+> Additional cross-cutting behaviors (e.g. domain access-audit behaviors) may be appended —
+> see [[cqrs.domain]] for the domain audit-pipeline behavior.
+
+## Result pattern
+
+- Errors are returned as `Result<T>.Failure(new Error(code, message, status, resource))`.
+- **Exceptions MUST NOT** be used for expected business outcomes (validation, not-found,
+  conflict, concurrency). `DomainException` is reserved for invariant violations and is
+  caught by the centralized exception handler.
+- **Error code** MUST be a stable dot-namespaced slug — e.g. `resource.not_found`,
+  `concurrency.conflict`, `resource.duplicate`.
+- **resource** MUST be the kebab-case resource name.
+
+## Handler responsibilities
+
+- **Read handlers** inject `IReadRepository<TAggregate>`.
+- **Write handlers** inject `IRepository<TAggregate>` + `IUnitOfWork` (+ `IPublisher`
+  when domain events are produced).
+- Validators check **request shape only**; invariants are enforced inside the aggregate.
+- No business logic in handlers (anemic-domain anti-pattern — see [[domain-driven-design]]).
+
+## Transaction handling
+
+- Write handlers **MUST** wrap mutating work in
+  `IUnitOfWork.ExecuteInTransactionAsync(..., IsolationLevel.ReadCommitted, ct)` and call
+  `SaveChangesAsync` **inside** the lambda.
+- They **MUST** publish domain events and call `ClearDomainEvents()` before returning.
+- **One command mutates one aggregate per transaction** — cross-aggregate effects flow
+  through domain events or follow-up commands (see [[eventing]]).
+
+## Canonical example
+
+The worked `<SampleProjectName>` example for these rules lives in
+`guardrails/technology/dotnet-webapi/examples/cqrs.md`, mapped for `design`. The constitution
+set maps the rules without it.
+
+## Related
+
+- [[clean-architecture]] · [[persistence]] · [[eventing]] · [[domain-driven-design]] · [[cqrs.domain]]

package/assets/guardrails/technology/dotnet-webapi/data-classification.md

@@ -0,0 +1,38 @@
+# 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/guardrails/technology/dotnet-webapi/dependency-policy.md

@@ -0,0 +1,40 @@
+# Dependency Policy
+
+> Pure technology (domain-agnostic) — domain package rules in [[dependency-policy.domain]]. Commands: `/aw-spec-implement`, `/aw-spec-implement-delta`.
+
+## 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/guardrails/technology/dotnet-webapi/domain-driven-design.md

@@ -0,0 +1,91 @@
+# Domain-Driven Design Standards (Tactical Patterns)
+
+> Pure technology (domain-agnostic) — generic DDD tactical patterns; the business model, canonical aggregates + invariants are in [[domain-driven-design.domain]]. NON-NEGOTIABLE. Commands: `/aw-spec-specify`.
+
+> Note: DDD is a domain-modelling methodology, but the rules here are domain-agnostic and
+> reusable, so the file sits in the technology corpus and is mapped on the technical tier. The
+> business-specific model is in the companion `.domain.md`, in the active domain corpus.
+
+## Ubiquitous language & bounded contexts
+
+- Use a consistent ubiquitous language across each bounded context.
+- Each bounded context = one module with `Domain / Features / Persistence / Shared`
+  (see [[modular-monolith]]).
+
+## Aggregate design
+
+- Every entity exposed to the Application layer is reached through an **Aggregate Root**.
+- Aggregate roots implement `IAggregateRoot`, `EntityBase<TId>`, and the
+  audit/soft-delete/concurrency/domain-event interfaces they need:
+  `IFullAuditedObject` or `IAuditableEntityBase`, `ISoftDeletable`, `IConcurrencyTracked`,
+  `IHasDomainEvents`, `INamedEntity<TId>` when listable.
+
+### Aggregate root responsibilities
+
+- Enforce all invariants for the aggregate.
+- Own the lifecycle of its child entities.
+- Raise domain events for state transitions.
+
+### Child entity ownership
+
+- Child entities implement `IAggregateChild` and expose `GetAggregateRoot()`.
+- They are mutated **only** through methods on the aggregate root.
+
+## Transactional / consistency boundaries
+
+- **Transaction boundary equals aggregate boundary**: a single command mutates a single
+  aggregate per transaction.
+- Cross-aggregate effects flow through **domain events** or **follow-up commands**
+  (see [[eventing]], [[cqrs]]).
+
+## Strongly typed IDs
+
+- IDs are **strongly-typed Vogen value objects** (`<Aggregate>Id` as
+  `[ValueObject<Guid>] partial struct`).
+- Raw `Guid` parameters at the Application boundary **MUST be wrapped** at the handler edge.
+
+## Value objects
+
+- Value Objects are **sealed**, have **private constructors**, **validate in the constructor**,
+  throw `DomainException` on invariant violations, and expose a `From(...)` factory.
+
+## Domain events
+
+- Derive from `DomainEventBase`, are immutable, added inside aggregate methods via
+  `AddDomainEvent(...)`, published explicitly by command handlers. See [[eventing]].
+
+## Domain services, repositories, specifications
+
+- Invariants are enforced **inside the aggregate**; validators check request shape only.
+- Repository usage is limited to `IRepository<T>` / `IReadRepository<T>` + `Specification<T>`.
+- Specification pattern: query composition lives in the Domain. See [[persistence]].
+
+## Domain exception handling
+
+- Exceptions are thrown by the Domain only (`DomainException`, `InvariantViolationException`).
+  Application code returns `Result<T>` (see [[cqrs]]).
+
+## Encapsulation, immutability, audit-awareness
+
+- **Rich domain model** — no public setters on aggregates, no business logic in handlers.
+- Soft-delete and audit behavior are first-class on protected aggregates
+  (see [[persistence]], [[auditing]]).
+
+## Anti-patterns (FORBIDDEN)
+
+- **Anemic domain models** — no public setters, no "manager/service" classes mutating
+  aggregate state from outside, no primitive-typed IDs, no business logic in handlers.
+- Cross-aggregate EF navigation properties — reference by strongly-typed ID only.
+- Cross-bounded-context interaction except via Shared DTOs / `IMediator` / anti-corruption
+  adapters.
+
+## Canonical example
+
+The worked `<SampleProjectName>` example for these rules lives in
+`guardrails/technology/dotnet-webapi/examples/domain-driven-design.md`, mapped for `specify`.
+The constitution set maps the rules without it.
+
+## Related
+
+- [[modular-monolith]] · [[clean-architecture]] · [[cqrs]] · [[persistence]] ·
+  [[eventing]] · [[domain-driven-design.domain]]

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

@@ -0,0 +1,57 @@
+# Eventing Standards
+
+> Pure technology (domain-agnostic) — domain additions in [[eventing.domain]]. Commands: `/aw-spec-design`.
+
+## Domain events
+
+- Domain Events derive from `DomainEventBase`, are **immutable**, and are added **inside**
+  aggregate methods via `AddDomainEvent(...)`.
+- They are published **explicitly** by command handlers: `foreach` over `entity.DomainEvents`,
+  then `ClearDomainEvents()` before returning. See [[cqrs]].
+- Cross-aggregate effects flow through domain events or follow-up commands — never a
+  multi-aggregate transaction.
+
+## CloudEvents conventions
+
+- Asynchronous propagation of domain events to downstream consumers uses a **durable event
+  stream**: **CloudEvents** over the configured broker (e.g. Azure Service Bus, AWS SQS/SNS,
+  or RabbitMQ).
+- Each module owns its **public events**; downstream consumers subscribe to them rather than
+  reading the OLTP database.
+
+## Event immutability
+
+- Published events are immutable facts. Consumers build their own read models; they
+  **MUST NOT** query the source OLTP database directly.
+- Analytics / reporting is built from emitted events — **never** by querying the OLTP DB
+  directly.
+
+## Event versioning
+
+- The service publishes a versioned, machine-readable **AsyncAPI** document for event
+  contracts.
+- Breaking changes to a domain-event contract are **MAJOR** version bumps and require the
+  AsyncAPI document to regenerate cleanly (CI gate). See [[api-versioning]].
+
+## Broker integration patterns
+
+- The message broker is declared as an Aspire resource and referenced via `.WithReference(...)`;
+  connection details are discovered through Aspire, never hard-coded.
+- Trace context **MUST** propagate across `IMediator.Send`, `HttpClient`, and EF Core; bypassing
+  the framework's `HttpClientFactory` is forbidden.
+  (Outbound domain-protocol propagation is covered in [[eventing.domain]].)
+
+## Inbound integration rule (generic)
+
+- Inbound integrations flow through **Interop adapters** that translate to internal commands;
+  they **MUST NOT** write directly to aggregates. (Domain feed types in [[eventing.domain]].)
+
+## Canonical example
+
+The worked `<SampleProjectName>` example for these rules lives in
+`guardrails/technology/dotnet-webapi/examples/eventing.md`, mapped for `design`. The
+constitution set maps the rules without it.
+
+## Related
+
+- [[cqrs]] · [[modular-monolith]] · [[api-versioning]] · [[eventing.domain]]

package/assets/guardrails/technology/dotnet-webapi/examples/api-versioning.md

@@ -0,0 +1,75 @@
+# API Versioning Policy — canonical example
+
+> The worked `<SampleProjectName>` example for
+> `guardrails/technology/dotnet-webapi/api-versioning.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)
+
+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
+
+- Rule file: `guardrails/technology/dotnet-webapi/api-versioning.md`

package/assets/guardrails/technology/dotnet-webapi/examples/auditing.md

@@ -0,0 +1,84 @@
+# Auditing & Observability Standards — canonical example
+
+> The worked `<SampleProjectName>` example for `guardrails/technology/dotnet-webapi/auditing.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)
+
+```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
+```
+
+## Related
+
+- Rule file: `guardrails/technology/dotnet-webapi/auditing.md`