aw-spec-cli 0.1.8 → 0.1.10

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

@@ -0,0 +1,68 @@
+# Authorization Standards — canonical example
+
+> The worked `<SampleProjectName>` example for
+> `guardrails/technology/dotnet-webapi/authorization.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)
+
+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
+
+- Rule file: `guardrails/technology/dotnet-webapi/authorization.md`

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

@@ -0,0 +1,37 @@
+# Clean Architecture Standards — canonical example
+
+> The worked `<SampleProjectName>` example for
+> `guardrails/technology/dotnet-webapi/clean-architecture.md`. It is reference material for the
+> phases that generate code — mapped for `design` and `build` — 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)
+
+The dependency rule in practice — the **API** layer depends inward via `IMediator` only
+(never `IRepository`/`DbContext`); the **Application** layer depends on Domain abstractions
+(`IRepository<Project>`), never on concrete EF Core types:
+
+```csharp
+// API layer — <SampleProjectName>.Service/Projects/Features/CreateProject/CreateProjectEndpoint.cs
+public class CreateProjectEndpoint(IMediator _mediator)
+    : SecureFastEndpoint<CreateProjectRequest, ProjectDto>
+{
+    protected override Task<Result<ProjectDto>> ExecuteAsync(
+        CreateProjectRequest req, CancellationToken ct)
+        => _mediator.Send(new CreateProjectCommand(
+            req.Code, req.Name, req.Description, req.StartDate, req.EndDate, req.OwnerId), ct);
+}
+
+// Application layer — depends on Domain abstractions, not EF Core
+public class CreateProjectCommandHandler(
+    IRepository<Project> _repo, IUnitOfWork _uow, IPublisher _eventBus)
+    : ICommandHandler<CreateProjectCommand, Result<ProjectDto>> { /* ... */ }
+```
+
+## Related
+
+- Rule file: `guardrails/technology/dotnet-webapi/clean-architecture.md`

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

@@ -0,0 +1,97 @@
+# CQRS + Mediator Standards — canonical example
+
+> The worked `<SampleProjectName>` example for `guardrails/technology/dotnet-webapi/cqrs.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)
+
+Command as a `record`, write handler with transaction + event publication, and a read handler
+returning `Result.Failure(...)` for the expected not-found outcome (no exceptions):
+
+```csharp
+// Command — record implementing ICommand<Result<TDto>>
+public record CreateProjectCommand(
+    string Code, string Name, string? Description,
+    DateOnly StartDate, DateOnly? EndDate, Guid? OwnerId
+) : ICommand<Result<ProjectDto>>;
+
+// Write handler — primary-ctor DI, transaction, publish + clear events, Result<T>
+public class CreateProjectCommandHandler(
+    IRepository<Project> _repo, IUnitOfWork _uow, IPublisher _eventBus
+) : ICommandHandler<CreateProjectCommand, Result<ProjectDto>>
+{
+    public async ValueTask<Result<ProjectDto>> Handle(
+        CreateProjectCommand request, CancellationToken ct)
+        => await _uow.ExecuteInTransactionAsync(async () =>
+        {
+            var ownerId = request.OwnerId.HasValue
+                ? TaskUserId.From(request.OwnerId.Value) : (TaskUserId?)null;
+            var entity = new Project(request.Code, request.Name, request.StartDate, ownerId);
+
+            await _repo.AddAsync(entity, ct);
+            await _uow.SaveChangesAsync(ct);
+
+            foreach (var e in entity.DomainEvents) await _eventBus.Publish(e, ct);
+            entity.ClearDomainEvents();
+
+            return Result<ProjectDto>.Ok(entity.ToDto());
+        }, IsolationLevel.ReadCommitted, ct);
+}
+
+// Read handler — IReadRepository + Specification; not-found is a Result, not an exception
+public class GetProjectByIdQueryHandler(IReadRepository<Project> _repo)
+    : IQueryHandler<GetProjectByIdQuery, Result<ProjectDto>>
+{
+    public async ValueTask<Result<ProjectDto>> Handle(
+        GetProjectByIdQuery request, CancellationToken ct)
+    {
+        Guard.NotDefault(request.Id, nameof(request.Id));
+        var entity = await _repo.FirstOrDefaultAsync(
+            new ProjectWithTasksSpec(ProjectId.From(request.Id)), ct);
+
+        return entity is null
+            ? Result<ProjectDto>.Failure(new Error(
+                "project.not_found", $"Project {request.Id} not found", 404, "projects"))
+            : Result<ProjectDto>.Ok(entity.ToDto());
+    }
+}
+```
+
+Commands with no return payload use `ICommand<Result>` (e.g. delete) and return
+`Result.Success()` / `Result.Failure(...)`:
+
+```csharp
+public record DeleteProjectCommand(Guid Id, string RowVersionBase64) : ICommand<Result>;
+
+public class DeleteProjectCommandHandler(IRepository<Project> _repo, IUnitOfWork _uow, IPublisher _bus)
+    : ICommandHandler<DeleteProjectCommand, Result> { /* ... returns Result.Success() */ }
+```
+
+Composition — register the mediator with the logging + validation pipeline behaviors,
+the validators, and the in-process event bus (one-time startup wiring):
+
+```csharp
+// <SampleProjectName>.Service/Extensions/ApplicationServiceRegistration.cs
+services.AddMediator(builder =>
+{
+    builder.UseDefault()
+           .UseBehaviors()
+           .AddLoggingBehavior()
+           .AddFluentValidationBehavior();          // domain projects also add PHI-audit — see [[cqrs.domain]]
+}, options => options.Provider = "Default");
+
+services.AddAppWeaverMediatorHandlersFrom(typeof(ApplicationServiceRegistration));
+services.AddValidatorsFromAssembly(typeof(ApplicationServiceRegistration).Assembly);
+
+services.AddEventBus(b => b.UseDefaultEventBus(o =>
+    o.RegisterServicesFromAssembly(typeof(ApplicationServiceRegistration).Assembly)));
+```
+
+## Related
+
+- Rule file: `guardrails/technology/dotnet-webapi/cqrs.md`

package/assets/guardrails/technology/dotnet-webapi/examples/domain-driven-design.md

@@ -0,0 +1,141 @@
+# Domain-Driven Design Standards (Tactical Patterns) — canonical example
+
+> The worked `<SampleProjectName>` example for
+> `guardrails/technology/dotnet-webapi/domain-driven-design.md`. It is reference material for the
+> phases that generate code — mapped for `specify` — 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)
+
+Aggregate root with a strongly-typed Vogen ID, owned child collection, concurrency token,
+domain events, and an invariant enforced **inside** the aggregate:
+
+```csharp
+// <SampleProjectName>.Service/Projects/Domain/Project.cs
+[ValueObject<Guid>]
+public partial struct ProjectId { }
+
+public class Project :
+    EntityBase<ProjectId>, IAggregateRoot, IFullAuditedObject, IFieldAudited,
+    ISoftDeletable, IConcurrencyTracked, IHasDomainEvents, INamedEntity<ProjectId>
+{
+    private readonly List<ProjectTask> _tasks = new();
+
+    public string Name { get; set; } = default!;               // INamedEntity
+    public ProjectCode Code { get; private set; } = default!;   // value object
+    public ProjectStatus Status { get; private set; }
+    public TaskUserId? OwnerId { get; private set; }            // cross-aggregate ref by ID only
+    public IReadOnlyCollection<ProjectTask> Tasks => _tasks.AsReadOnly();
+
+    public byte[] RowVersion { get; set; } = Array.Empty<byte>();  // IConcurrencyTracked
+
+    private readonly List<DomainEventBase> _domainEvents = new();
+    [NotMapped] public IEnumerable<DomainEventBase> DomainEvents => _domainEvents.AsReadOnly();
+    public void ClearDomainEvents() => _domainEvents.Clear();
+
+    private Project() { }   // EF Core ctor
+
+    public Project(string code, string name, DateOnly startDate, TaskUserId? ownerId)
+    {
+        Id = ProjectId.From(Guid.NewGuid());
+        Code = ProjectCode.From(code);          // VO validates in its ctor
+        Name = ProjectTitle.From(name).Value;
+        Status = ProjectStatus.Planning;
+        OwnerId = ownerId;
+        AddDomainEvent(new ProjectCreatedEvent(Id.Value, Code.Value, Name));
+    }
+
+    // Invariant lives in the aggregate — never in the handler/validator.
+    public ProjectTask AddTask(string title, TaskPriority priority)
+    {
+        if (Status is ProjectStatus.Cancelled or ProjectStatus.Archived)
+            throw new DomainException("Cannot add tasks to a Cancelled or Archived project.");
+        var task = new ProjectTask(Id, title, priority);
+        _tasks.Add(task);
+        AddDomainEvent(new TaskCreatedEvent(Id.Value, task.Id.Value, task.Title.Value));
+        return task;
+    }
+
+    private void AddDomainEvent(DomainEventBase e) => _domainEvents.Add(e);
+}
+```
+
+Value object — sealed, private ctor, validates in the ctor, `From(...)` factory,
+throws `DomainException`:
+
+```csharp
+// <SampleProjectName>.Service/Projects/Domain/ProjectCode.cs
+public sealed class ProjectCode : IEquatable<ProjectCode>
+{
+    private static readonly Regex _valid = new(@"^[A-Z0-9][A-Z0-9\-]{1,14}$", RegexOptions.Compiled);
+    public string Value { get; private set; } = default!;
+
+    private ProjectCode() { }
+    private ProjectCode(string value)
+    {
+        if (string.IsNullOrWhiteSpace(value))
+            throw new DomainException("Project code cannot be empty.");
+        var trimmed = value.Trim().ToUpperInvariant();
+        if (!_valid.IsMatch(trimmed))
+            throw new DomainException("Project code must be uppercase alphanumeric with hyphens.");
+        Value = trimmed;
+    }
+
+    public static ProjectCode From(string value) => new(value);
+    public bool Equals(ProjectCode? o) => o is not null && Value == o.Value;
+    public override bool Equals(object? obj) => Equals(obj as ProjectCode);
+    public override int GetHashCode() => HashCode.Combine(Value);
+}
+```
+
+Child entity — implements `IAggregateChild`, exposes `GetAggregateRoot()`, has only `private`
+setters, and is mutated **only** through methods the parent aggregate calls:
+
+```csharp
+// <SampleProjectName>.Service/Projects/Domain/ProjectTask.cs
+[ValueObject<Guid>]
+public partial struct ProjectTaskId { }
+
+public class ProjectTask : EntityBase<ProjectTaskId>, IAggregateChild
+{
+    public ProjectId ProjectId { get; private set; }            // FK back to the root
+    public TaskTitle Title { get; private set; } = default!;    // value object
+    public ProjectTaskStatus Status { get; private set; }
+    public TaskUserId? AssigneeId { get; private set; }         // cross-aggregate ref by ID
+
+    public Project Project { get; private set; } = default!;    // EF-only nav, private setter
+    public object GetAggregateRoot() => Project;                // IAggregateChild
+
+    private ProjectTask() { }                                   // EF Core ctor
+    public ProjectTask(ProjectId projectId, string title, TaskPriority priority)
+    {
+        Id = ProjectTaskId.From(Guid.NewGuid());
+        ProjectId = projectId;
+        Title = TaskTitle.From(title);
+        Status = ProjectTaskStatus.Open;
+        Priority = priority;
+    }
+
+    // State-machine invariant lives on the child; the parent calls it (project.ChangeTaskStatus).
+    public void ChangeStatus(ProjectTaskStatus newStatus)
+    {
+        if (Status == ProjectTaskStatus.Cancelled)
+            throw new DomainException("A cancelled task cannot be re-opened.");
+        Status = newStatus;
+    }
+
+    public void AssignTo(TaskUserId assigneeId) => AssigneeId = assigneeId;
+}
+```
+
+> The aggregate root mutates children only through its own methods (e.g. `Project.AssignTask`
+> calls `task.AssignTo(...)` and raises the domain event) — callers never touch `ProjectTask`
+> directly. EF mapping for the owned collection is in [[persistence]].
+
+## Related
+
+- Rule file: `guardrails/technology/dotnet-webapi/domain-driven-design.md`

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

@@ -0,0 +1,46 @@
+# Eventing Standards — canonical example
+
+> The worked `<SampleProjectName>` example for `guardrails/technology/dotnet-webapi/eventing.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)
+
+Immutable domain event, raised inside the aggregate, published explicitly by the handler:
+
+```csharp
+// <SampleProjectName>.Service/Projects/Domain/Events/ProjectCreatedEvent.cs
+public class ProjectCreatedEvent(Guid projectId, string code, string name) : DomainEventBase
+{
+    public Guid ProjectId { get; } = projectId;   // get-only — immutable
+    public string Code { get; } = code;
+    public string Name { get; } = name;
+}
+```
+
+```csharp
+// Raised inside the aggregate method (never in the handler):
+AddDomainEvent(new ProjectCreatedEvent(Id.Value, Code.Value, Name));
+
+// Published by the command handler after SaveChanges, then cleared:
+foreach (var domainEvent in entity.DomainEvents)
+    await _eventBus.Publish(domainEvent, ct);   // IPublisher — in-process today, broker tomorrow
+entity.ClearDomainEvents();
+```
+
+Composition — register the event bus (handlers discovered from the assembly):
+
+```csharp
+// <SampleProjectName>.Service/Extensions/ApplicationServiceRegistration.cs
+services.AddEventBus(b => b.UseDefaultEventBus(o =>
+    o.RegisterServicesFromAssembly(typeof(ApplicationServiceRegistration).Assembly)));
+```
+
+## Related
+
+- Rule file: `guardrails/technology/dotnet-webapi/eventing.md`

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

@@ -0,0 +1,207 @@
+# Persistence Standards — canonical example
+
+> The worked `<SampleProjectName>` example for
+> `guardrails/technology/dotnet-webapi/persistence.md`. It is reference material for the phases
+> that generate code — mapped for `design` and `run` — 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)
+
+EF Core configuration (Vogen ID + value object conversions, unique business key,
+cross-aggregate FK stored as a raw `Guid` with no navigation):
+
+```csharp
+// <SampleProjectName>.Service/Projects/Persistence/ProjectConfiguration.cs
+public class ProjectConfiguration : IEntityTypeConfiguration<Project>
+{
+    public void Configure(EntityTypeBuilder<Project> builder)
+    {
+        builder.ToTable("Projects");
+        builder.HasKey(e => e.Id);
+
+        // Strongly-typed Vogen ID -> Guid, never DB-generated
+        builder.Property(e => e.Id)
+            .HasConversion(id => id.Value, v => ProjectId.From(v))
+            .ValueGeneratedNever();
+
+        // Value object -> column + unique business key
+        builder.Property(e => e.Code)
+            .HasConversion(c => c.Value, v => ProjectCode.From(v))
+            .HasColumnName("Code").HasMaxLength(20).IsRequired();
+        builder.HasIndex(e => e.Code).IsUnique();
+
+        builder.Property(e => e.Status).HasConversion<string>().HasMaxLength(30).IsRequired();
+
+        // Cross-aggregate FK as nullable Guid — NO EF navigation to TaskUser
+        builder.Property(e => e.OwnerId)
+            .HasConversion(
+                id => id.HasValue ? id.Value.Value : (Guid?)null,
+                v => v.HasValue ? TaskUserId.From(v.Value) : (TaskUserId?)null)
+            .HasColumnName("OwnerId");
+    }
+}
+```
+
+Composable specification (filter + include + paging):
+
+```csharp
+// {Module}/Domain/Specifications/ProjectSearchSpec.cs
+public sealed class ProjectSearchSpec : Specification<Project>
+{
+    public ProjectSearchSpec(string? search, ProjectStatus? status = null)
+    {
+        Query.Include(p => p.Tasks);
+        if (!string.IsNullOrWhiteSpace(search))
+        {
+            var s = search.Trim().ToLowerInvariant();
+            Query.Where(p => p.Code.Value.ToLower().Contains(s) || p.Name.ToLower().Contains(s));
+        }
+        if (status.HasValue) Query.Where(p => p.Status == status.Value);
+    }
+
+    public ProjectSearchSpec WithPaging(int pageNumber, int pageSize)
+    {
+        Query.Skip(Math.Max(0, (pageNumber - 1) * pageSize)).Take(Math.Max(1, pageSize));
+        return this;
+    }
+}
+```
+
+Read handler using the spec + typed ordering helper, returning `PagedResult<T>`:
+
+```csharp
+var spec = new ProjectSearchSpec(request.Search, request.Status)
+    .OrderByIdDesc<ProjectSearchSpec, Project, ProjectId>();   // typed helper, not ad-hoc OrderBy
+
+var total = await _repo.CountAsync(spec, ct);
+var items = await _repo.ListAsync(spec.WithPaging(request.PageNumber, request.PageSize), ct);
+
+return Result<PagedResult<ProjectDto>>.Ok(new PagedResult<ProjectDto>
+{
+    Items = items.ToDtoList(), TotalCount = total,
+    PageNumber = request.PageNumber, PageSize = request.PageSize
+});
+```
+
+Owned child-entity configuration (separate table, FK + cascade, soft-delete mirror filter,
+no EF navigation to other aggregates):
+
+```csharp
+// {Module}/Persistence/ProjectTaskConfiguration.cs
+public class ProjectTaskConfiguration : IEntityTypeConfiguration<ProjectTask>
+{
+    public void Configure(EntityTypeBuilder<ProjectTask> builder)
+    {
+        builder.ToTable("ProjectTasks");
+        builder.HasKey(e => e.Id);
+        builder.Property(e => e.Id)
+            .HasConversion(id => id.Value, v => ProjectTaskId.From(v)).ValueGeneratedNever();
+
+        builder.Property(e => e.ProjectId)                       // FK back to the root
+            .HasConversion(id => id.Value, v => ProjectId.From(v)).IsRequired();
+
+        builder.Property(e => e.Title)                           // Vogen value object
+            .HasConversion(t => t.Value, v => TaskTitle.From(v)).HasMaxLength(300).IsRequired();
+        builder.Property(e => e.Status).HasConversion<string>().HasMaxLength(30).IsRequired();
+
+        // Cross-aggregate ref stored as raw Guid — NO navigation to TaskUser
+        builder.Property(e => e.AssigneeId)
+            .HasConversion(
+                id => id.HasValue ? id.Value.Value : (Guid?)null,
+                v => v.HasValue ? TaskUserId.From(v.Value) : (TaskUserId?)null);
+
+        builder.HasOne(e => e.Project).WithMany(p => p.Tasks)    // owned collection
+            .HasForeignKey(e => e.ProjectId).OnDelete(DeleteBehavior.Cascade);
+
+        // Mirror the parent's ISoftDeletable filter onto the required dependent
+        builder.HasQueryFilter(t => !t.Project.IsDeleted);
+        builder.HasIndex(e => e.ProjectId);
+        builder.HasIndex(e => e.AssigneeId);
+    }
+}
+```
+
+DbContext — `ContextAwareDbContext`, assembly-scanned configs, provider-aware `timestamptz`,
+cross-cutting behaviors, and the client-managed concurrency token override:
+
+```csharp
+// <SampleProjectName>.Service/Infrastructure/ApplicationDbContext.cs
+public class ApplicationDbContext(
+    DbContextOptions<ApplicationDbContext> options, ICurrentTenant? tenant = null)
+    : ContextAwareDbContext<ApplicationDbContext>(options, tenant)
+{
+    protected override void OnModelCreating(ModelBuilder modelBuilder)
+    {
+        modelBuilder.ApplyConfigurationsFromAssembly(typeof(ApplicationDbContext).Assembly);
+
+        if (Database.ProviderName == "Npgsql.EntityFrameworkCore.PostgreSQL")
+            foreach (var et in modelBuilder.Model.GetEntityTypes())
+                foreach (var p in et.GetProperties()
+                    .Where(p => p.ClrType == typeof(DateTimeOffset) || p.ClrType == typeof(DateTimeOffset?)))
+                    p.SetColumnType("timestamptz");
+
+        modelBuilder.ApplyCrossCuttingBehaviors(this);   // soft-delete + tenant filters + audit
+
+        // Client-managed concurrency token (works on SQLite + PostgreSQL; not SQL Server IsRowVersion)
+        foreach (var et in modelBuilder.Model.GetEntityTypes())
+            if (typeof(IConcurrencyTracked).IsAssignableFrom(et.ClrType))
+                modelBuilder.Entity(et.ClrType).Property<byte[]>("RowVersion")
+                    .IsConcurrencyToken().ValueGeneratedNever();
+
+        base.OnModelCreating(modelBuilder);
+    }
+
+    public DbSet<Project> Projects => Set<Project>();
+    public DbSet<ProjectTask> ProjectTasks => Set<ProjectTask>();
+}
+```
+
+Soft-delete: logical delete via `MarkAsDeleted(...)` + `DeleteAsync` (never a hard delete),
+and a separate `IgnoreQueryFilters()` spec for admin/audit reads:
+
+```csharp
+// Delete handler — soft delete + concurrency guard (returns Result, no DTO)
+var entity = await _repo.GetByIdAsync(ProjectId.From(request.Id), ct);
+if (entity is null)
+    return Result.Failure(new Error("project.not_found", $"Project {request.Id} not found", 404, "projects"));
+// ... concurrency token check (see api-versioning) ...
+entity.MarkAsDeleted();                 // sets IsDeleted/DeletedOn + raises ProjectDeletedEvent
+await _repo.DeleteAsync(entity, ct);    // framework translates to UPDATE, not DELETE
+
+// Admin/audit spec that bypasses the global soft-delete filter
+public sealed class ProjectSearchIncludeDeletedSpec : Specification<Project>
+{
+    public ProjectSearchIncludeDeletedSpec(string? search, ProjectStatus? status = null)
+    {
+        Query.Include(p => p.Tasks).IgnoreQueryFilters();   // include soft-deleted rows
+        // ... same Where filters as ProjectSearchSpec ...
+    }
+}
+```
+
+Composition — repository + cross-cutting behaviors registered once at startup:
+
+```csharp
+// <SampleProjectName>.Service/Extensions/InfrastructureServiceRegistration.cs
+services.AddRepositories(builder =>
+{
+    builder
+        .UseSingleDbContextEFRepositories<ApplicationDbContext>(db => db.UseSqlite(/* or UseNpgsql */)
+            .ConfigureWarnings(w => w.Ignore(RelationalEventId.PendingModelChangesWarning)))
+        .EnableTenancy()
+        .EnableSoftDelete()
+        .EnableClientManagedConcurrency()
+        .EnableAuditing().EnableAdvancedAuditing()   // see [[auditing]]
+        .Done();
+}, options => options.Provider = "EfCore");
+
+services.TryAddScoped(typeof(IUnitOfWork), typeof(EfUnitOfWork<ApplicationDbContext>));
+```
+
+## Related
+
+- Rule file: `guardrails/technology/dotnet-webapi/persistence.md`