@drunkcoding/dknet-implementation-skills 0.1.0

package/skills/dknet-crud/SKILL.md

@@ -0,0 +1,483 @@
+---
+name: dknet-crud
+description: Create commands (Create/Update/business transitions/Delete) at the AppServices layer for a DKNet.Minimal feature — request contracts, FluentValidation validators, and SlimMessageBus handlers, in both the hand-written and generator-driven (CrudCreate/CrudUpdate/CrudAction) shapes. Use after the domain entity and EF Core mapper exist. Queries and paged lists are the `dknet-queries-specs` skill; response DTOs and Mapster are `dknet-dto-mapping`. Invoke as `/dknet-crud <Feature> <Entity> [mode=manual|auto] [version=V1]` to scaffold it for a feature.
+metadata:
+  kind: workflow
+  arguments: "<Feature> <Entity> [mode=manual|auto] [version=V1]"
+allowed-tools: Read, Grep, Glob, Edit, Write, Bash, Agent
+---
+
+Usage: `/dknet-crud <Feature> <Entity> [mode=manual|auto] [version=V1]`
+
+# AppServices actions
+
+Commands only: Create, Update, a business-rule transition, Delete, and the generator's
+`[CrudCreate]`/`[CrudUpdate]`/`[CrudAction]` equivalents. For query specs and paged lists, load
+`dknet-queries-specs`. For DTO shape and Mapster wiring, load `dknet-dto-mapping`. For whether a
+rule belongs on the entity or in a handler, load `dknet-ddd-principles` first.
+
+## GlobalUsings already in Minimal.AppServices
+
+`Minimal.AppServices/GlobalUsings.cs` gives every file in the project these without an explicit
+`using`: `DKNet.AspCore.Extensions.ModelBinding` (`[FromClaim]`), `DKNet.SlimBus.Extensions`
+(`Fluents.*`, `NotFoundError`), `System.ComponentModel.DataAnnotations`, `System.Security.Claims`
+(`ClaimTypes`), `System.Text.Json.Serialization`, `FluentResults`, `Minimal.Domains.Services`,
+`Microsoft.Extensions.DependencyInjection`, `FluentValidation`, `Mapster`, `MapsterMapper`,
+`Minimal.AppServices.Extensions`, `DKNet.SlimBus.Extensions.LazyMapper`, `Minimal.AppServices.Share`
+(`PreconditionCodes`, `IPrincipalProvider`). An action file typically adds only the entity's and its
+own spec's namespace.
+
+## Request and handler contracts
+
+| Shape | Request | Handler | Return |
+|---|---|---|---|
+| Command returning a DTO | `Fluents.Requests.IWitResponse<TDto>` | `Fluents.Requests.IHandler<TReq, TDto>` | `Task<IResult<TDto>>` |
+| Command with no response | `Fluents.Requests.INoResponse` | `Fluents.Requests.IHandler<TReq>` | `Task<IResultBase>` |
+
+The handler method is `OnHandle(TRequest, CancellationToken)`, never `Handle`. Both are discovered
+by assembly scan onto the in-memory bus — no per-message registration. Handlers never call
+`SaveChanges`: the SlimBus EF Core interceptor auto-saves once, after the handler returns. A request
+record is `public sealed record`; its validator and handler are `internal sealed class` — enforced
+by `Minimal.App.Tests/Architecture/AppServiceTests.cs`.
+
+File layout: one file per verb, request + validator + handler co-located —
+`<Feature>/V1/Actions/<Verb>.cs` (`ManualSample/V1/Actions/Create.cs`, `Update.cs`, `Cancel.cs`,
+`Delete.cs`).
+
+## Acting user
+
+`mode=manual`: a `[FromClaim(ClaimTypes.Name)] public string? ByUser { get; set; }` property.
+`AddContextualRequestPopulation` (wired once in `Program.cs`) overwrites it from the caller's claim
+before validation and before the handler runs — a value the caller put in the body is always
+discarded, never trusted. The handler still guards it:
+
+```csharp
+if (string.IsNullOrEmpty(request.ByUser))
+{
+    return Result.Fail<PurchaseOrderDto>("The caller is not authenticated.");
+}
+```
+
+The demo authentication provider (`FeatureManagement:EnableDemoAuthentication`) supplies this claim
+locally and in tests, so the guard is reachable but rarely hit — an authenticated caller with a
+missing name claim still has to fail it explicitly, there is no fallback to a system account.
+
+`mode=auto`: a generated request never carries `[FromClaim]` — the generator forwards only
+`System.ComponentModel.DataAnnotations` attributes, and `[FromClaim]` lives in
+`DKNet.AspCore.Extensions.ModelBinding`. Instead `DataOwnerHook` stamps `OwnedBy` and the audit hook
+stamps `CreatedBy`/`UpdatedBy`, both from `IPrincipalProvider`, wired once in
+`ServiceConfigs.AddAllAppServices` (`.AddDataOwnerProvider<CoreDbContext, PrincipalProvider>()` /
+`.AddCurrentUserProvider<CoreDbContext, PrincipalProvider>()`) and applying to every entity on
+`CoreDbContext`, not just the one you're adding.
+
+**The `[CrudAction]` acting-user pitfall.** A method parameter literally named `byUser` is still
+just a constructor/method parameter to the generator — it becomes a caller-settable, body-bound
+property:
+
+```csharp
+[CrudAction("approval")]
+public void Approve(string byUser) => SetUpdatedBy(byUser);
+```
+
+generates `public required string ByUser { get; init; }` on `ApproveProductRequest`, bound from the
+JSON body (`{ "byUser": "alice" }`). Nothing stamps it from the caller's identity — whatever the
+client sends is what `SetUpdatedBy` receives. Don't name a `[CrudCreate]`/`[CrudUpdate]`/
+`[CrudAction]` parameter after an acting-user concept; if a method needs the real caller, stamp it
+from `DataOwnerHook`/the audit hook instead, or hand-write the action.
+
+## FluentValidation
+
+A validator is `internal sealed class XValidator : AbstractValidator<TRequest>`, co-located with
+its request. There is no per-route opt-in call: `Minimal.Api/Configs/FluentValidationConfig.cs`
+registers every validator in the assembly —
+
+```csharp
+builder.Services.AddValidatorsFromAssembly(typeof(AppSetup).Assembly, includeInternalTypes: true);
+```
+
+— and `UseEndpointConfigs` attaches `AddFluentValidationAutoValidation()` to **every** endpoint
+group (`Program.cs`), so it runs on generated routes exactly as it runs on hand-mapped ones. A
+request failing validation never reaches the handler; it short-circuits to `400` (or `409`, see
+below) with no handler code involved. Two hard constraints: the validator class must live in
+`Minimal.AppServices` (one in `Minimal.Api` is never registered), and it must be `internal sealed`.
+
+**Ordinary input rules** stay inline (`RuleFor(a => a.Amount).GreaterThan(0)`). Keep `Id` out of an
+update validator — an unknown/empty id is a `404` from the handler's spec lookup, not a `400` from
+validation (`UpdatePurchaseOrderCommandValidator`'s comment says this explicitly).
+
+**Precondition validators** read stored data through `IRepositorySpec` and refuse with a code:
+
+```csharp
+internal sealed class CreateProductRequestValidator : AbstractValidator<CreateProductRequest>
+{
+    public CreateProductRequestValidator(IRepositorySpec repository)
+    {
+        RuleFor(r => r.Name)
+            .MustAsync(async (name, ct) => !await repository.AnyAsync(new SpecProductByName(name), ct))
+            .WithErrorCode(PreconditionCodes.ProductNameTaken)
+            .WithMessage(r => $"The product name '{r.Name}' is already taken.");
+    }
+}
+```
+
+Any code prefixed `PreconditionCodes.Prefix` (`"precondition."`) makes
+`FluentValidationConfig`'s `AddErrorResponses` answer `409` instead of `400`, with that code echoed
+in the response body's `code` extension. This is a check, not a guarantee — the database's unique
+index is what actually enforces it under a race.
+
+**Keep 404 out of validators.** `DeleteProductRequestValidator` deliberately *passes* an unknown id:
+
+```csharp
+RuleFor(r => r.Id)
+    .MustAsync(async (id, ct) =>
+    {
+        var product = await repository.FirstOrDefaultAsync(new SpecGetProduct(id), ct);
+        return product is null || product.IsDiscontinued;
+    })
+    .WithErrorCode(PreconditionCodes.ProductDeleteWhileForSale)
+    .WithMessage("The product is still for sale and cannot be deleted.");
+```
+
+If it refused a missing id too, the route's own `404` would be hidden behind a `409`.
+
+**Validators on generated requests are the supported way to add a business rule to a generated
+route.** `CreateProductRequestValidator` and `DeleteProductRequestValidator` both target generated
+request types (`Minimal.AppServices.Crud.CreateProductRequest` / `DeleteProductRequest`) — no
+literal `Map*` call is needed for FluentValidation to reach them, only the `using
+Minimal.AppServices.Crud;` and a constructor parameter naming the request type. This is the fix for
+the one thing `[DataAnnotations]` cannot do on a generated route: `[Range]`/`[Required]`/etc.
+forwarded onto a generated request property is **not evaluated**, because .NET's validation source
+generator only recognizes literal `Map*(string, Delegate)` calls in the compiling project's own
+source — true for `PurchaseOrderV1Endpoint`'s hand-mapped routes, false for anything routed through
+`DKNet.AspCore.Extensions`'s generic `Map*<TRequest,TDto>` wrapper, which is every generated CRUD
+route. `POST /v1/products` with `price: -1` returns `201`, not `400`, despite
+`CreateProductRequest.Price` carrying `[Range(0.01, double.MaxValue)]`. Don't assume a
+DataAnnotations attribute on a generated request is enforced; write a validator for any rule you
+actually need.
+
+## Handler patterns
+
+**Create** (`ManualSample/V1/Actions/Create.cs`) — construct the aggregate through its own
+constructor, add it, return a lazily-mapped result so the response carries the DB-generated `Id`:
+
+```csharp
+var order = new PurchaseOrder(request.CustomerName, request.Amount, request.ByUser);
+await repository.AddAsync(order, cancellationToken);
+return mapper.ResultOf<PurchaseOrderDto>(order);
+```
+
+**Update / business transition** (`Update.cs`) — fetch via spec, `404` if missing, mutate through
+a domain method, map eagerly since nothing on the DTO needs a value only `SaveChanges` produces:
+
+```csharp
+var order = await repository.FirstOrDefaultAsync(new SpecGetPurchaseOrder(request.Id), cancellationToken);
+if (order is null)
+    return Result.Fail<PurchaseOrderDto>(new NotFoundError($"The purchase order {request.Id} was not found."));
+order.ChangeAmount(request.Amount, request.ByUser);
+return Result.Ok(mapper.Map<PurchaseOrderDto>(order));
+```
+
+**Rejected transition** (`Cancel.cs`) — a domain-specific `409`, distinct from the generic
+`NotFoundError` `404`:
+
+```csharp
+if (order.Status == PurchaseOrderStatus.Cancelled)
+    return Result.Fail<PurchaseOrderDto>(
+        new Error($"The purchase order {request.Id} is already cancelled.")
+            .WithMetadata("Code", PreconditionCodes.PurchaseOrderAlreadyCancelled));
+```
+
+`.WithMetadata("Code", ...)` is the handler-side equivalent of `.WithErrorCode(...)` in a
+validator — same `PreconditionCodes.Prefix` check drives the same `409`.
+
+**Delete** (`Delete.cs`, `INoResponse`) — fetch, `404` if missing, `repository.Delete(order)`,
+`Result.Ok()`. No DTO, no mapper.
+
+**Multi-aggregate command** (`AutomatedSample/V1/Actions/Discontinue.cs`) — one handler, two writes,
+one `SaveChanges`:
+
+```csharp
+public sealed record DiscontinueProductCommand : Fluents.Requests.IWitResponse<ProductDto>
+{
+    public Guid Id { get; init; }              // not `required` — bound via `req with { Id = id }`
+    [Required, StringLength(150)] public string ReplacementName { get; init; } = null!;
+    [Range(0.01, double.MaxValue)] public decimal ReplacementPrice { get; init; }
+}
+```
+
+```csharp
+product.Discontinue();
+var replacement = new Product(request.ReplacementName, request.ReplacementPrice);
+await repository.AddAsync(replacement, cancellationToken);
+return mapper.ResultOf<ProductDto>(product);
+```
+
+Named `...Command`, not `...Request`: `Product.Discontinue()` keeps its own `[CrudAction]`
+declaration (so the generator still has a route to drop by name), which reserves the generated
+`DiscontinueProductRequest`/`DiscontinueProductHandler` names — a second, hand-written type by
+either name would collide. `Id` is deliberately not `required`: the request body from a client never
+carries `id` (it comes from the route), and `required` would make System.Text.Json reject that body
+outright; the endpoint supplies it with `req with { Id = id }`. This kind of command cannot be
+generated at all — an operation writing more than one aggregate in one transaction is outside what
+`[CrudUpdate]`/`[CrudAction]` can express — so it stays fully hand-written even though the entity is
+otherwise generator-driven.
+
+## Generated requests and handlers (`mode=auto`)
+
+Naming, mechanical from the entity's own signatures: `Create<Entity>Request` (from `[CrudCreate]`),
+`Change<Member><Entity>Request` (from a `[CrudUpdate]` method named `Change<Member>`),
+`<Method><Entity>Request` (from `[CrudAction]`), `Delete<Entity>Request` (always). Handlers mirror
+the name with `Handler` instead of `Request` — `CreateProductHandler`, `ChangePriceProductHandler`,
+`ApproveProductHandler`, `DiscontinueProductHandler`, `AssignSupplierReferenceProductHandler` — all
+in namespace `Minimal.AppServices.Crud`, emitted under
+`obj/Generated/DKNet.SlimBus.Generators/.../<Entity>CrudRequests.g.cs` and `...Handlers.g.cs`. They
+are compiler output, not files in the repo — inspect them after a build, not by searching source.
+
+A generated update handler, verbatim (`ProductCrudHandlers.g.cs`):
+
+```csharp
+internal sealed class ChangePriceProductHandler(IRepositorySpec repository, IMapper mapper)
+    : Fluents.Requests.IHandler<ChangePriceProductRequest, ProductDto>
+{
+    public async Task<IResult<ProductDto>> OnHandle(ChangePriceProductRequest request, CancellationToken cancellationToken)
+    {
+        var entity = await repository.FirstOrDefaultAsync(new ProductByIdCrudSpec(request.Id), cancellationToken);
+        if (entity is null)
+            return Result.Fail<ProductDto>(new NotFoundError($"Product '{request.Id}' was not found."));
+        entity.ChangePrice(request.Price);
+        return mapper.ResultOf<ProductDto>(entity);
+    }
+}
+```
+
+Fetch by a private, generated `ProductByIdCrudSpec`, `404` if missing, call the one domain method,
+`ResultOf`. This is exactly the shape of a hand-written Update handler above, generated for you.
+
+**Replacing a generated handler.** The generated file's own doc comment says how: "Write a class
+implementing the same IHandler to replace it." Add your own `internal sealed class` implementing
+`Fluents.Requests.IHandler<ChangePriceProductRequest, ProductDto>` in `Minimal.AppServices` — DI
+registration is by interface via assembly scan, so yours and the generated one cannot coexist; keep
+only yours (there is no attribute to suppress generation of the handler alone — drop the whole
+route with `CrudMapOptions.Exclude` if you also need to change the request shape).
+
+**Adding a rule without leaving the generated route**: write a validator, as above.
+
+**The generated request records are `partial`.** You may declare a member in your own partial
+`record CreateProductRequest { ... }`, but the generated handler never reads it — it only
+constructs the entity from the parameters the generator saw on `[CrudCreate]`. A partial addition is
+for a validator or a Mapster customization to read, not a way to pass extra data into the entity
+constructor.
+
+## Error → HTTP mapping
+
+| Outcome | Status | Body |
+|---|---|---|
+| `Result.Ok(dto)` | `200`, or `201` on a create route with `isCreated: true` | the DTO |
+| `Result.Fail(new NotFoundError(...))` | `404` | `errors: [{ message }]` |
+| `Result.Fail(...)`/validator error with a `precondition.`-prefixed code | `409` | `errors: [...]`, `code` = that code |
+| Any other `Result.Fail(...)` or FluentValidation failure | `400` | `errors: [{ message, code?, field? }]` |
+| Unhandled `OwnershipRequiredException` | `403` | `errors: [{ message }]` |
+| Any other unhandled exception | `500` | generic message outside `Development`, `traceId` always present |
+
+Every body shares `title: "Error"`, `status`, `type` (the status's name, e.g. `"Conflict"`), and
+`traceId` (the current `Activity` id, falling back to `TraceIdentifier`). One registration answers
+all three failure kinds — `Minimal.Api/Configs/FluentValidationConfig.cs`'s single
+`AddErrorResponses(...)` call — there is no second place to configure this.
+
+## Architecture rules enforced by tests
+
+`Minimal.App.Tests/Architecture/AppServiceTests.cs` and `RecordArchitectureTests.cs` pin, exactly:
+
+- Every class implementing `IRequestHandler<>`/`IRequestHandler<,>`/`IConsumer<>` must be
+  non-public and `sealed` (`AllHandlerClassesShouldBeInternalAndSealed`).
+- Every non-abstract class inheriting `AbstractValidator<>` must be non-public and `sealed`
+  (`AllValidatorClassesShouldBeInternalAndSealed` — two hand-authored customer/order sample
+  validators are exempted by name; a new feature's validators are not).
+- Any interface named `*Repo`/`*Repository` must inherit `IRepository<TEntity>`
+  (`AllRepoInterfaces_ShouldInheritFromIRepository`).
+- A `[GenerateDto]` type must expose no property whose type (or generic argument) inherits
+  `DomainEntity` (`DtosWithGenerateDtoAttribute_ShouldNotHaveProperties_ThatAreDomainEntities`) —
+  the DTO boundary must not leak an entity.
+- No record type in `Minimal.Domains` or `Minimal.AppServices` may declare a public property with a
+  **private** setter (`RecordTypes_ShouldNotContain_PrivateSetters_OnPublicProperties`) — AutoMapper
+  (Mapster's `MapToConstructor`/property assignment) cannot fill it.
+
+## Step-by-step
+
+**mode=manual** (mirror `ManualSample/PurchaseOrder`):
+
+1. Add `<Feature>/V1/Actions/Create.cs`: request implementing `IWitResponse<TDto>` with
+   `[FromClaim(ClaimTypes.Name)] ByUser`, a co-located validator, a handler constructing the
+   aggregate and returning `mapper.ResultOf<TDto>(entity)`.
+2. Add `Update.cs` / a named business-transition file: request with `Id` (route-bound) and the
+   mutable fields, a validator that skips `Id`, a handler that fetches via spec, 404s, calls a
+   domain method, returns `Result.Ok(mapper.Map<TDto>(entity))`.
+3. Add `Delete.cs`: `INoResponse` request, handler fetches, 404s, `repository.Delete(entity)`,
+   `Result.Ok()`.
+4. Wire each into `<Feature>V1Endpoint.cs` with a literal `Map*` call (`dknet-endpoint`) so
+   DataAnnotations validation, if any, is actually enforced.
+
+**mode=auto** (mirror `AutomatedSample/Product`):
+
+1. Confirm the entity already carries `[CrudCreate]` on its constructor and `[CrudUpdate]`/
+   `[CrudAction]` on its mutation methods (`dknet-entity`, `dknet-crud`).
+2. Build once; read the generated request/handler/endpoint files to know the exact contract.
+3. Add any business rule as a validator against the generated request type — never a hand-mapped
+   route just to enforce a `[Range]`/`[Required]` attribute.
+4. For an operation that must write more than one aggregate, or must reject a repeat call as a
+   domain failure rather than a `200`, write a `...Command` (not `...Request`) and drop the
+   generated route for that member with `CrudMapOptions.Exclude("MethodName")` in the endpoint.
+
+## Validation checklist
+
+- Request is `public sealed record`; validator and handler are `internal sealed class`.
+- `[FromClaim(ClaimTypes.Name)]` only on a hand-written request — never named onto a
+  `[CrudCreate]`/`[CrudUpdate]`/`[CrudAction]` parameter.
+- Handler guards `IsNullOrEmpty(request.ByUser)` (manual mode) before doing anything else.
+- No `SaveChanges` call anywhere in the handler.
+- A precondition rule uses `.WithErrorCode(PreconditionCodes.X)` (validator) or
+  `.WithMetadata("Code", PreconditionCodes.X)` (handler `Error`), not a bare `Result.Fail(string)`.
+- A validator that must let an unknown id through to the route's own `404` does so explicitly.
+- `mapper.ResultOf<TDto>(entity)` after a write whose DTO needs a DB-generated value;
+  `mapper.Map<TDto>(entity)` otherwise.
+- A rule for a generated request lives in a validator, not a DataAnnotations attribute you're
+  hoping gets enforced.
+
+## Common mistakes
+
+- **What you might expect**: adding `[Range(0.01, double.MaxValue)]` to a `[CrudUpdate]` parameter
+  enforces it, since the generated request clearly carries the attribute.
+  **What actually happens**: `PUT` with a negative value still returns `200`.
+  **Why**: the generated route is mapped through a generic library wrapper the .NET validation
+  source generator cannot see into; only a validator runs on that route.
+
+- **What you might expect**: a `[CrudAction]` method parameter called `byUser` is populated the
+  same way `[FromClaim]` populates a hand-written request.
+  **What actually happens**: the generated request exposes `ByUser` as an ordinary
+  caller-supplied, required body field.
+  **Why**: the generator forwards only `DataAnnotations` attributes; `[FromClaim]` is a different
+  namespace it never looks at.
+
+- **What you might expect**: a validator refusing an unknown id in a delete/update route is the
+  safer default.
+  **What actually happens**: the route now answers `409` for a target that doesn't exist, instead
+  of the expected `404`.
+  **Why**: FluentValidation runs before the handler; a `MustAsync` that fails closed on "not found"
+  hides the handler's own 404 behind a validation-layer 409.
+
+- **What you might expect**: replacing a generated handler means adding an attribute to suppress
+  generation.
+  **What actually happens**: there is no such attribute — both classes would be registered, and DI
+  resolution becomes ambiguous.
+  **Why**: the generator has no per-handler opt-out; write your own class implementing the same
+  `IHandler<TRequest, TDto>` and remove nothing from the entity, or drop the whole route with
+  `CrudMapOptions.Exclude` if the request shape itself must change.
+
+---
+
+# Workflow: `/dknet-crud`
+
+The procedure an agent follows when invoked with arguments. The reference sections above are the rules it applies.
+
+You are scaffolding the **AppServices** layer for an aggregate that already has Domain + Infra wiring. Run `/dknet-entity` first if the entity does not exist yet.
+
+The `mode` argument selects the path. It must match the mode `/dknet-entity` ran in — `auto` requires
+the entity to already carry `[CrudCreate]`/`[CrudUpdate]`/`[RaisesEvent]`, and there is nothing to
+generate without them. If `mode=` was not supplied, detect it: grep the entity for `[CrudCreate]`;
+present it means `auto`, absent means `manual`. Say which you detected.
+
+Pick one per aggregate, don't mix them for the same entity:
+
+- **Hand-written** (below) — every request/validator/handler/spec/DTO is a file you write. Needed whenever the aggregate has a business rule beyond DataAnnotations, a filtered query, idempotent writes, or a DTO that must hide fields.
+- **Declarative CRUD generation** (further down) — `[CrudCreate]`/`[CrudUpdate]`/`[GenerateDto]` on the entity itself; `DKNet.SlimBus.Generators` produces the request/handler/route types for you. Only for genuinely plain CRUD — read the validation-gap caveat before choosing it.
+
+The `dknet-feature-lifecycle` skill §1 is the authoritative comparison between the two; use it to decide.
+
+### Inputs
+
+`$ARGUMENTS` — feature slice folder (e.g. `ManualSample`), entity (`PurchaseOrder`), optional
+`mode=manual|auto`, optional API version (defaults to `V1`).
+
+The `dknet-feature-lifecycle` skill §1 is the decision procedure if the mode is still open.
+
+### Path 1: Hand-written CRUD (`mode=manual`)
+
+#### Required reading
+
+1. The reference sections above
+2. `ApiEndpoints/Minimal.AppServices/ManualSample/V1/` (exemplar: `Actions/{Create,Update,Cancel,Delete}.cs`, `Specs/SpecGetPurchaseOrder.cs`, `Queries/{GetPurchaseOrderById,ListPurchaseOrders}.cs`, `Events/`, `PurchaseOrderDto.cs`)
+
+#### Steps
+
+1. Use the `dknet-implementer` subagent to execute Step 5 of the implementer protocol:
+   - Hand-written response DTO record — no `[GenerateDto]` — exposing exactly the fields the API should return (see `PurchaseOrderDto`).
+   - `Create<Entity>Request` (`Fluents.Requests.IWitResponse<TDto>`, `[FromClaim(ClaimTypes.Name)] ByUser` for the acting user — never trust a payload value) + `AbstractValidator` + `internal sealed` handler that constructs the aggregate (which raises its own event via `AddEvent(...)` in its constructor) and calls `IRepositorySpec.AddAsync`, returning `mapper.ResultOf<TDto>(entity)` (lazy mapping).
+   - `Update<Entity>Request` + handler that fetches via `SpecGet<Entity>` (404 via `NotFoundError` on miss) and calls the entity's mutation method.
+   - `Delete<Entity>Request` (`Fluents.Requests.INoResponse`) + handler, same fetch-then-404 shape.
+   - Any business-action request (e.g. `Cancel`) that rejects an invalid state transition with a `Result.Fail(...)` — mirror `CancelPurchaseOrderRequest`/`CancelPurchaseOrderCommandHandler` rejecting an already-cancelled order.
+   - `SpecGet<Entity>` query specification — remember an unfiltered predicate builder needs at least one `.And()`/`.Or()` call to avoid compiling to `WHERE FALSE` (see `SpecGetPurchaseOrder`'s explicit `predicator.And(_ => true)` fallback).
+   - Domain event record + in-memory event handler (only if the plan calls for one beyond what the constructor already raises).
+2. Build: `dotnet build -c Release`. Fix any analyzer/warning errors before continuing.
+3. Report the mode used, files created, and the next command (`/dknet-endpoint <Feature> <Entity> mode=manual`).
+
+#### Constraints
+
+- Handlers, validators, specs, event handlers MUST be `internal sealed`.
+- Use `IRepositorySpec` — never introduce a custom repo interface.
+- Auto-fields the client must not set: `[FromClaim(...)]` on the request property, always overwritten by the endpoint from the authenticated caller.
+- Create handler returns `mapper.ResultOf<TDto>(entity)` (lazy mapping).
+- Do not modify endpoint files in this command.
+
+### Path 2: Declarative CRUD generation (`mode=auto`)
+
+For a genuinely plain CRUD entity, declare the CRUD surface on the entity instead of writing it. Exemplar: `Product` (`ApiEndpoints/Minimal.Domains/Features/AutomatedSample/Entities/Product.cs`, `ApiEndpoints/Minimal.AppServices/AutomatedSample/V1/ProductDto.cs`).
+
+Most of the entity-side attributes are `/dknet-entity mode=auto`'s job. This command's own output at
+the AppServices layer is small on purpose: **one `[GenerateDto]` line, plus any hand-written event
+consumer.** If you find yourself writing a request, validator, or handler here, the mode is wrong.
+
+#### What you write
+
+- `[RaisesEvent(EventOperations.Created, Include=[nameof(Id), ...])]` and/or `[RaisesEvent(EventOperations.Updated, nameof(Prop))]` at the class level — replaces a hand-written event record + `AddEvent(...)` call. The composed event-record name is `<Entity><NarrowingProps><Operation>Event` — e.g. `[RaisesEvent(EventOperations.Updated, nameof(Price))]` on `Product` composes `ProductPriceUpdatedEvent`, **not** `ProductUpdatedEvent`. Verify the exact composed name against the compiled assembly before wiring a consumer — there is no hand-written source file for it.
+- `[CrudCreate]` on the entity's constructor — its parameter list becomes the generated create request's payload (DataAnnotations attributes on the parameters, e.g. `[Required][StringLength(150)]`, forward onto the generated request property).
+- `[CrudUpdate]` on a mutation method — same forwarding for its parameter(s).
+- `[CrudAction("segment")]` on a domain-action method — publishes a route at the by-id path plus a
+  segment, returning `200` + the entity DTO. The default verb is POST and the default segment is
+  derived from the method name; `[CrudAction(Verb = CrudActionVerb.Put)]` overrides the verb.
+  `Product.Approve` (segment override) and `Product.AssignSupplierReference` (both overridden) are
+  the shipped exemplars. A generated action's handler on its own is a no-op `200` when the entity is
+  already in that state — but the request is body-bound and passes the group-level
+  `AddFluentValidationAutoValidation()` filter, so a **pre-condition belongs in a FluentValidation
+  validator** on the generated request, which can read stored data and refuse (the product sample
+  answers `409` that way on create and delete). A pre-condition is therefore never a reason to leave
+  the generated map — hand-write the route only when the operation writes **more than one
+  aggregate in one transaction**, which the generator cannot express. Then drop that one route by
+  name (`o.Exclude("<MethodName>")` on `MapProductCrud`) and hand-write it below the generated call.
+  `Product.Discontinue` is the shipped case: it also creates the product's named replacement in the
+  same transaction. The rest of the entity's routes stay generated; there is no need to fall back to
+  Path 1 for the whole feature.
+- `[GenerateDto(typeof(Entity))] public sealed partial record <Entity>Dto;` — one line, generates every audited property by default (`Exclude`/`Include` to narrow).
+
+#### What gets generated
+
+`DKNet.SlimBus.Generators` produces (namespace `Minimal.AppServices.Crud`, not committed — inspect via `dotnet build` then `obj/Generated/DKNet.SlimBus.Generators/`):
+
+- `Create<Entity>Request` / `Change<Member><Entity>Request` (named after the `[CrudUpdate]` method, e.g. `ChangePriceProductRequest`) + matching `internal sealed` handlers (`Create<Entity>Handler` / `Change<Member><Entity>Handler`) — no hand-written request/validator/handler exists for these.
+- `<Entity>CrudEndpointExtensions.Map<Entity>Crud()` — GetById/GetList/Delete map straight to `DKNet.AspCore.Extensions`'s generic `MapGetById<TEntity,TKey,TDto>`/`MapGetList`/`MapDeleteById`; Create/Update use the generated handlers above.
+
+#### Constraints and the validation-gap caveat
+
+- Do NOT hand-write a request or handler for a `[CrudCreate]`/`[CrudUpdate]` member while its route is still generated — that defeats the point of the generator. A **validator** is the exception and the supported shape: a FluentValidation validator for the generated request runs on the generated route through the group filter. Exclude a route by name (`CrudMapOptions.Exclude(string)`) and hand-write it below the `Map<Entity>Crud(...)` call only when the operation writes more than one aggregate in one transaction. Generated and hand-written routes coexisting in one endpoint is the shipped shape, not a smell — see `ProductV1Endpoint`.
+- **Validation gap, confirmed live**: a `[Range]`/`[Required]` on a `[CrudCreate]`/`[CrudUpdate]` parameter *is* forwarded onto the generated request property, but it is **never enforced** under this template's endpoint-registration convention — the .NET 10 validation source generator only recognizes literal `Map*(string, Delegate)` calls, and the generated route goes through `DKNet.AspCore.Extensions`'s generic `MapPost<TRequest,TDto>` wrapper instead. `POST /v1/products` with a negative price returns `201`, not `400`. Do not present a DataAnnotations attribute on a generated request as enforced without checking the endpoint's mapping style.
+- Acting-user attribution cannot use `[FromClaim]` on a generated request (the generator forwards only `System.ComponentModel.DataAnnotations` attributes) — it goes through `DKNet.EfCore.DataAuthorization`'s `DataOwnerHook` instead, wired once in `Minimal.Api/Configs/ServiceConfigs.cs`, not per-entity.
+- No idempotency key support on the generated create route — see `/dknet-endpoint`'s "Alternative: generated CRUD route" section if the feature needs it.
+
+#### Steps
+
+1. Add the attributes to the entity and the one-line `[GenerateDto]` DTO (Domain + AppServices layers together — there's no separate scaffolding step).
+2. Build: `dotnet build -c Release`, then inspect `obj/Generated/DKNet.SlimBus.Generators/` to confirm the expected types were produced.
+3. Report the mode used, the generated type names, and the next command
+   (`/dknet-endpoint <Feature> <Entity> mode=auto`, which for this path is just `group.Map<Entity>Crud()`).
+
+An empty `obj/Generated/DKNet.SlimBus.Generators/` after a green build means the attributes did not
+take — STOP and fix the entity rather than hand-writing the missing pieces.

package/skills/dknet-ddd-principles/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: dknet-ddd-principles
+description: DDD tactical judgment for this codebase — aggregate boundaries, entity vs. value object, invariant enforcement, when to use a domain event, avoiding anemic domain models. Use before dknet-entity and dknet-crud whenever the aggregate shape or business-rule placement isn't obvious.
+---
+
+# Skill: DDD Tactical Principles
+
+This codebase already gives you the class shapes (`AggregateRoot`, `DomainEntity`, `AddEvent`) — see `dknet-entity`. This skill covers the judgment calls those shapes don't make for you: what belongs in one aggregate, what's an entity vs. a value object, where an invariant lives, and when a domain event is the right tool.
+
+This template is a single microservice / single bounded context — these are tactical patterns, not strategic (bounded-context) design.
+
+---
+
+## When to Use
+
+- Deciding what a new aggregate root should own vs. what belongs to a separate aggregate.
+- Deciding whether a new type needs its own identity (entity) or is just a bag of values (owned/value object).
+- Deciding whether a business rule belongs on the entity, in a domain service, or in the command handler.
+- Deciding whether a mutation needs to publish a domain event or just needs a plain method call.
+
+## Aggregate Boundaries
+
+An aggregate is a transactional consistency boundary: everything inside it is saved together and its invariants are enforced together. The rule of thumb —
+
+- If two pieces of data must always be consistent with each other *at the moment they're saved* (e.g. a `PurchaseOrder`'s `Amount` and its `Status` — cancelling and re-pricing an order in the same save must not leave those two fields disagreeing), they belong in the same aggregate. That's why `PurchaseOrder` owns both `Amount` and `Status` directly rather than splitting them into two persisted types.
+- If two pieces of data can be consistent *eventually*, a moment apart, they belong in separate aggregates, coordinated through a domain event — not a direct object reference.
+- Aggregates reference each other by ID (`Guid`), never by object reference. `PurchaseOrder` (`ApiEndpoints/Minimal.Domains/Features/ManualSample/Entities/PurchaseOrder.cs`) does not hold a `Customer` object — it holds a plain `CustomerName` string, no navigation property back to another aggregate.
+
+Keep aggregates small. A large aggregate means more contention (every mutation locks the whole thing) and usually signals a boundary was drawn around "things that seem related" rather than "things that must be consistent together."
+
+## Entity vs. Value Object
+
+- **Entity** (in this codebase: `AggregateRoot` for the root, `DomainEntity` for non-root entities): has identity and a lifecycle. Two entities with identical property values are still different entities if their `Id` differs. `PurchaseOrder` is an entity — two orders with the same customer name and amount are still two different orders.
+- **Value object** (owned type, plain class with no `Id`): defined entirely by its values. Two value objects with identical properties are interchangeable. If a type never needs to be looked up or referenced independently of its parent entity, it's a value object — model it as a plain owned type (see `dknet-entity` "Step 3: Create Owned Value Objects"), not as another `DomainEntity`.
+
+Ask: "Do I ever need to fetch or reference this thing on its own, independent of its parent?" Yes → entity. No → value object.
+
+## Invariant Enforcement
+
+An invariant is a rule that must always hold true for an entity (e.g. "amount is never negative," "a cancelled order stays cancelled"). In this codebase, invariants are enforced by construction and by the entity's own mutation methods — never by a public setter:
+
+- Properties are `{ get; private set; }`. Nothing outside the entity can put it into an invalid state directly.
+- The constructor establishes the invariant for a new entity. Named mutation methods (`ChangeAmount`, `Cancel` — see `PurchaseOrder` in `dknet-entity`) re-establish it for every mutation, and are the *only* path to changing mutable state.
+- A rule that depends on the entity's **own current state** belongs on the entity, or right next to the fetch in the handler when it must read the stored row first. `PurchaseOrder.Cancel(string userId)` is the clearest example: `CancelPurchaseOrderCommandHandler` (`ApiEndpoints/Minimal.AppServices/ManualSample/V1/Actions/Cancel.cs`) checks `order.Status == PurchaseOrderStatus.Cancelled` and fails the request *before* calling `Cancel`; the transition itself still lives on the entity. Note the weakness this leaves — the guard is one call away from being bypassed by a second caller who skips it, so treat handler-side guards as a boundary check, not as the invariant's home.
+- If a rule needs data external to the entity (e.g. "customer name must be unique across all orders"), that's not an entity invariant — it's a cross-entity business rule, and it belongs in the command handler as a duplicate-check `Specification` query (see `dknet-crud`), because the entity has no way to see other entities.
+
+## When to Use a Domain Event
+
+This codebase has two equally valid ways to raise the same kind of event — pick the one that matches how much control you need over the raise:
+
+- **Hand-raised** (`PurchaseOrder`): the constructor calls `AddEvent(new PurchaseOrderCreatedEvent(Id, CustomerName, Amount))` directly, in application code you can step through in a debugger. You write the payload by hand. Use this when the event's payload, timing, or "did this actually happen" condition needs logic more specific than "a tracked property changed."
+- **Declared** (`Product`): the class carries `[RaisesEvent(EventOperations.Created, Include = [nameof(Id), nameof(Name), nameof(Price)])]` and `[RaisesEvent(EventOperations.Updated, nameof(Price))]` — no line of application code calls `AddEvent` anywhere in `AutomatedSample/`. DKNet's EF Core save hook reads these declarations and raises the composed event records (`ProductCreatedEvent`, `ProductPriceUpdatedEvent`) after a successful `SaveChanges`, driven by the change tracker. Use this when the event is a straightforward "this property changed" notification and you're already using `[CrudCreate]`/`[CrudUpdate]` for the entity.
+  The trade-offs: you cannot single-step from "constructor ran" to "event raised" the way you can with `AddEvent`, and the payload's name and shape follow a fixed composition rule (`<Entity><NarrowingProps><Operation>Event`) rather than one you choose — verify the composed name against the compiled assembly before wiring a consumer to it.
+
+Both styles are delivered identically afterward: `ApiEndpoints/Minimal.Infra/Services/EventPublisher.cs` forwards to `IMessageBus` regardless of which raised the event.
+
+Reach for either one when **something outside this aggregate might care that this happened** — another aggregate needs to react, or an external system needs to be notified. `Product`'s declared `Created` event is consumed both in-process and over Azure Service Bus (`ProductCreatedNotificationHandler`), exactly as a hand-raised one would be.
+
+Do NOT reach for an event when the effect is entirely local to this one request:
+- Setting a computed field during the same handler → just do it in the handler or the entity method, no event needed.
+- A validation failure → return `Result.Fail(...)`, don't publish an event.
+
+If you can't name a concrete future subscriber (even a logging handler counts, but "just in case" doesn't), it's not an event yet — add it when a real consumer appears.
+
+## Avoiding Anemic Domain Models
+
+An anemic model is an entity that's just a property bag, with all the actual business logic living in command handlers. Symptoms to watch for:
+
+- A handler reads several properties off an entity, computes something, then writes several properties back — that computation belongs in a named method on the entity (e.g. `entity.ChangeAmount(amount, userId)` or `entity.Cancel(userId)`), not in the handler.
+- The handler is the only place an invariant is checked — meaning the entity could be constructed or mutated elsewhere into an invalid state.
+
+The handler's job is orchestration: fetch the entity (via `IRepositorySpec` + a `Specification`), call one or more methods on it, persist, map to a DTO. The entity's job is protecting its own consistency and encoding what a valid state transition looks like.
+
+## Decision Checklist
+
+- [ ] Can I name a concrete reason this needs to be consistent with the parent in the same transaction? If no, it's a separate aggregate.
+- [ ] Does this type ever get looked up independently of its parent? If no, it's a value object, not an entity.
+- [ ] Does this rule only need data already on the entity? If yes, enforce it in the entity's constructor/`Update` method, not the handler.
+- [ ] Can I name a real, current subscriber for this event? If no, skip the event for now.
+- [ ] Is the handler computing business logic, or just orchestrating fetch → mutate → persist → map? If it's computing, move the logic onto the entity.
+
+---
+
+## Next Steps
+
+→ `dknet-entity` — apply these decisions to actual entity code
+→ `dknet-crud` — apply the handler-orchestration boundary to CQRS actions