aspnet-domain-delivery

ASP.NET Domain Delivery

Overview

ASP.NET Domain Delivery turns an ASP.NET Core API change into a production-grade implementation plan. It treats endpoint shape, dependency lifetimes, EF Core behavior, middleware order, auth policies, validation, async cancellation, OpenTelemetry, and database migration rollback as one delivery system.

The playbook assumes modern ASP.NET Core with minimal APIs or controllers, IServiceCollection/IHostApplicationBuilder DI, EF Core, structured logging, health checks, and OpenAPI. It is not a generic web checklist; it is for deciding exactly where behavior belongs and how it is proven safe.

Expert Operating Standard

Follow <resolved-supervibe-plugin-root>/docs/references/skill-expert-operating-standard.md: read local source first, preserve evidence, follow ASP.NET conventions, keep graph execution fast with scoped verification, and cap confidence when stack-specific runtime proof, rollback, or ownership is missing.

When to Use

Use when adding or changing an ASP.NET Core route, controller action, minimal API group, service, repository, EF Core model, migration, middleware, authorization policy, validation rule, or telemetry path. Use for architecture review when a change crosses HTTP, DI, persistence, and operations.

Do not use for a pure Razor/UI change, static docs update, or mechanical formatting change with no runtime behavior.

Step 0 - Read source of truth

1. Read the requirement, existing endpoint conventions, Program.cs, service registrations, auth policy setup, middleware order, DbContext configuration, migrations, and relevant tests.
2. Search project memory and code for the nearest successful endpoint, migration, policy, validator, and telemetry pattern.
3. Identify whether the existing code favors minimal APIs, controllers, vertical slices, clean architecture, or feature folders. Follow that shape unless the requirement explicitly changes it.
4. If framework behavior matters, use official ASP.NET Core and EF Core docs through source-driven development before deciding.
5. Name the exact scoped verification command that will prove this change; do not start with broad suites during development when the repo policy forbids them.

When not to use

• Do not use when the task is generic planning, product shaping, design, or release governance and no ASP.NET implementation or review boundary exists.
• Do not use when another stack, database, security, deployment, or API owner has the primary decision; hand off to that specialist and keep the ASP.NET part scoped.
• Do not use to justify dependency swaps, broad rewrites, heavy test runs during graph execution, or mixed old-plan scope without explicit approval.

Practical Delivery Hardening

• Keep the stack-specific lifecycle, data, security, accessibility, rollback, and test requirements in this skill as the authority; these rules only decide how small the first implementation should be.
• Check framework-native, platform-native, standard-library, and existing project capabilities before custom code, new dependencies, or a new helper; reuse the local adapter, validation, migration, component, cache, queue, or test primitive when it already covers the behavior.
• Avoid speculative abstractions: delete or skip wrappers, duplicate dispatchers, unused knobs, generic factories, and indirection until source evidence shows a second real caller or a concrete behavior gap.
• Use one focused runnable check for the changed surface: a scoped command, artifact validator, or runtime proof that exercises the stack-specific behavior. Keep broad suites and release validators for final gates unless the active workflow explicitly asks for them.
• Safety, regulatory, security, and accessibility exceptions override the minimal path. When data loss, policy-sensitive behavior, auth/permission changes, cryptography, migration risk, concurrency risk, or assistive-technology behavior is affected, upgrade to the named owner, stronger review, rollback plan, and runtime proof before claiming readiness.
• Set a simplification ceiling before coding: stay with the thin reversible slice while complexity is local, risk is low, and coupling is contained. The upgrade trigger is observable scale, repeated branching, cross-boundary coupling, durability risk, or proof that the native capability cannot satisfy the behavior; downshift again when the trigger disappears.

Decision tree

Is this endpoint simple CRUD with local orchestration only?
  YES -> minimal API group is acceptable if local conventions already use it.
  NO  -> prefer controller/service or existing feature-slice pattern.

Does it mutate persistent state?
  YES -> design service-layer transaction, EF migration, idempotency, rollback, and cancellation behavior.
  NO  -> use AsNoTracking, explicit projection, caching headers only when justified.

Does the request require authorization beyond authentication?
  YES -> encode as named policy/requirement, not inline role checks in handlers.
  NO  -> still record anonymous/authenticated behavior explicitly.

Is a schema migration required?
  YES -> include forward migration, deploy order, backfill plan, rollback or compensating migration, and data risk.
  NO  -> prove no persistence contract changed.

Procedure

1. Choose the HTTP surface: minimal API route group or controller action. Keep handlers thin: bind DTOs, call an application service, map the response.

2. Define request and response DTOs. Never expose EF entities on the wire. Use explicit nullable fields, validation attributes or FluentValidation, and examples when OpenAPI is generated.

3. Place business logic in scoped services. Register dependencies with correct lifetimes: DbContext and request services scoped, stateless helpers singleton only when they consume no scoped services.

4. Model persistence with EF Core intentionally: configure keys, indexes, relationships, concurrency tokens, delete behavior, and query projections. Use AsNoTracking for reads and explicit includes/projections to avoid N+1 queries.

5. Put transaction boundaries in the application service or unit-of-work layer, not middleware or controller actions. Pass CancellationToken to every async EF, HTTP, cache, and queue call.

6. Wire middleware in operational order: exception handling, forwarded headers when applicable, routing, authentication, authorization, rate limiting/CORS, endpoints, health and metrics according to local convention.

7. Encode authorization as policies, requirements, handlers, or endpoint metadata. Avoid hard-coded role strings inside business methods.

8. Instrument the path with structured logs, Activity tags, metrics, health impact, and trace correlation. Prefer OpenTelemetry semantic conventions already present in the service.

9. Plan migrations as deployment artifacts: forward migration, compatibility with old/new app versions, backfill timing, lock risk, rollback/compensation, and data verification query.

10. Write or update targeted tests: unit tests for service rules, integration tests for endpoint/auth/validation, EF tests for migration-sensitive queries where local standards expect them.

11. Record rollback: feature flag, route disablement, policy rollback, migration revert/compensation, and telemetry signal that triggers rollback.

12. Read the source artifact, owned file paths, graph/task scope, and current project convention; record the evidence path, command, receipt, or runtime state that proves the starting point.

13. If required source, owner, dependency, runtime boundary, or approval is missing, stop and return BLOCKED with the missing field, impacted artifact, and next action instead of guessing.

14. After edits or reviewer findings, repair the smallest changed slice, rerun the same scoped command, and record command, exit code, pass/fail status, artifact path, confidence, and remaining blocker before completion.

Worked example

Requirement: add POST /api/orders/{id}/cancel.

Good delivery: route/controller accepts CancelOrderRequest, validates reason length, requires Orders.Cancel policy, calls OrderCancellationService.CancelAsync(orderId, user, reason, ct), service loads the order with required row version, rejects shipped orders with a domain error, saves inside a transaction, emits an audit event, and records order.cancelled metric. If a migration adds CancelledAt, the plan states that the nullable column deploys first, backfill is not needed, rollback leaves the nullable column unused, and a later cleanup removes it.

Verification: endpoint integration tests cover unauthenticated, unauthorized, invalid reason, not found, already shipped, success, and cancellation token propagation at service boundary.

Good and bad delivery paths

Good delivery path: deliver through controller, request DTO validation, authorization policy, scoped service, EF Core row-version check, transaction, audit/outbox, and cancellation-token propagation. Runtime-specific tests include WebApplicationFactory or minimal-host integration coverage for middleware, auth, model binding, cancellation, service rollback, EF concurrency tokens, and migration shape. Rollback disables the endpoint or flag, leaves nullable migration columns unused until cleanup, and drains outbox messages. Failure boundaries are model validation, policy denial, not found, row-version conflict, database failure, outbox failure, and client disconnect.

Bad unsafe path: mutate the aggregate directly from the controller, ignore CancellationToken, add an irreversible migration, and prove it with service-only tests. That path has no runtime-specific tests for the changed stack surface, no concrete rollback beyond hope or manual cleanup, and weak failure boundaries for model validation, policy denial, not found, row-version conflict, database failure, outbox failure, and client disconnect.

Anti-example or Common rationalizations

• "It is only one endpoint, so the handler can use DbContext directly." That makes transaction, auth, telemetry, and reuse boundaries disappear.
• "The migration is reversible because EF generated Down." Generated rollback can be wrong for data loss, indexes, default constraints, and long-running operations.
• "CancellationToken is optional." In ASP.NET Core it is the request-abort contract; ignoring it wastes capacity after clients disconnect.
• "Role checks are faster inline." Inline checks hide policy intent and bypass central audit.

Common rationalizations

• "It is just ASP.NET, so the generic implementation pattern is enough" fails because lifecycle, runtime, data, and deployment constraints differ by stack.
• "A broad suite will prove it faster" fails in graph execution; use the declared scoped command and reserve broad validators for the final release gate.
• "We can clean up the architecture while here" fails unless that cleanup is in the accepted graph scope, has rollback, and has its own verification path.

Red flags

• Singleton service depends on DbContext, IHttpContextAccessor state, or any scoped service.
• Endpoint returns tracked EF entities or accepts entity types as request bodies.
• Middleware order changes without naming security and error-handling consequences.
• Async methods call .Result, .Wait(), blocking file/network IO, or omit cancellation tokens.
• Migration combines destructive schema change and application behavior in one deploy.
• Authorization is implemented as string comparisons inside controllers.
• Telemetry has logs but no trace correlation or metric for the new critical path.

Checklist

• HTTP surface matches local minimal API/controller convention.
• DTOs, validation, errors, and OpenAPI behavior are explicit.
• DI lifetimes are checked for every new registration.
• EF Core query shape, tracking, transaction, concurrency, and migration behavior are named.
• Auth policy and middleware order are correct.
• CancellationToken flows through all async work.
• OpenTelemetry/logging/metrics are updated for the path.
• Rollback and migration compensation are written down.

Failure modes

• The ASP.NET specialist applies a generic pattern and misses framework-owned lifecycle, typing, permission, migration, cache, or deployment behavior.
• The worker mixes a new graph task with stale plan scope and creates a larger review surface than the MVP flow needs.
• The task closes with prose only: no source evidence, no scoped command or final-gate deferral, no rollback, and no next action for blockers.

Output contract

• surface: route/controller/minimal API group and request/response DTOs.
• placement: service, repository, validator, middleware, policy, and migration files to touch.
• diContract: lifetimes and dependency graph risks.
• persistencePlan: EF Core query, transaction, migration, rollback, and data checks.
• securityPlan: authentication, authorization policy, validation, and rate-limit decisions.
• operabilityPlan: logs, traces, metrics, health, dashboards, alerts, and rollback trigger.
• verificationCommands: targeted commands only, plus what behavior each proves.
• residualRisk: unresolved framework, data, scale, or deployment concern.

Guard rails

• Do not implement ASP.NET changes from a generic skill when a stack-specific owner, migration path, or runtime boundary is missing.
• Avoid broad rewrites, dependency swaps, large test suites, or speculative architecture changes during fast MVP execution.
• Reject work that skips source search, rollback naming, or scoped verification for the changed slice.
• Stop when local project conventions, version constraints, permissions, data ownership, or deployment target are unknown.

Verification

Use the narrow command declared by the owning task, such as dotnet test <project> --filter <case>, a migration script generation command, or the repository's targeted integration command. Before claiming delivery, verify endpoint behavior, validation failures, auth failures, EF migration compatibility, cancellation, and telemetry shape. Broad release gates remain final handoff only when repository policy requires them.

• If any scoped check fails or new evidence appears, repair the smallest changed slice, rerun the same scoped command, and record command, exit code, pass/fail status, blockers, and final-gate deferrals before claiming completion.

Supporting references

Resource tree hardening

• references/practice-pack.md - Load when aspnet-domain-delivery needs deeper load rules, local evidence anchors, gotchas, or the final checklist.

• scripts/self-check.mjs - Run with --check before claiming the aspnet-domain-delivery resource tree is complete; add --json when machine-readable evidence is needed.

• evals/regression.json - Use when tuning the aspnet-domain-delivery trigger boundary or checking should-trigger and should-not-trigger prompts.

• examples/workflow.md - Load when a concrete ASP.NET Domain Delivery execution example or anti-example would clarify the next action.

• templates/output-contract.md - Use when emitting aspnet-delivery-plan so status, evidence, blockers, confidence, and nextAction stay consistent.

• examples/delivery.md - worked ASP.NET implementation example, anti-example, and verification fixture.

• domain-packs/aspnet.md - ASP.NET practice pack with review matrix, rollback prompts, and MVP guard rails.

• evals/regression.json - Use when calibrating aspnet-domain-delivery trigger boundaries, happy-path/failure-path coverage, boundary rollback behavior, or resource-tree regressions.

Related

• supervibe:source-driven-development
• supervibe:test-strategy
• supervibe:error-envelope-design
• supervibe:auth-flow-design
• supervibe:verification