aw-spec-cli 0.1.0 → 0.1.2

package/assets/docs/architecture/clean-architecture.md

@@ -0,0 +1,71 @@
+# Clean Architecture Standards
+
+> Pure technology (domain-agnostic). NON-NEGOTIABLE. Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## 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 (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
+
+- [[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/docs/architecture/cqrs.md

@@ -0,0 +1,141 @@
+# CQRS + Mediator Standards
+
+> Pure technology (domain-agnostic) — domain additions in [[cqrs.domain]]. NON-NEGOTIABLE. Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## 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 (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
+
+- [[clean-architecture]] · [[persistence]] · [[eventing]] · [[domain-driven-design]] · [[cqrs.domain]]

package/assets/docs/architecture/eventing.md

@@ -0,0 +1,83 @@
+# Eventing Standards
+
+> Pure technology (domain-agnostic) — domain additions in [[eventing.domain]]. Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## 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 (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
+
+- [[cqrs]] · [[modular-monolith]] · [[api-versioning]] · [[eventing.domain]]

package/assets/docs/architecture/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-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+>
+> 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/
+docs/                                     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/docs/architecture/modular-monolith.md

@@ -0,0 +1,47 @@
+# Modular Monolith Standards
+
+> Pure technology (domain-agnostic). NON-NEGOTIABLE where marked. Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## 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/docs/architecture/persistence.md

@@ -0,0 +1,269 @@
+# Persistence Standards
+
+> Pure technology (domain-agnostic) — domain additions in [[persistence.domain]]. NON-NEGOTIABLE where marked. Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## 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 (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
+
+- [[clean-architecture]] · [[cqrs]] · [[domain-driven-design]] · [[api-versioning]] · [[persistence.domain]]