@eltonssouza/development-utility-kit 0.10.0

package/.claude/stacks/_template.md

@@ -0,0 +1,116 @@
+---
+stack: <lang>/<framework>           # e.g. java/spring-boot-3, python/django, go/gin
+versions_covered: "<range>"          # e.g. "3.0.x — 3.4.x", "5.0.x — 5.1.x"
+last_validated: <YYYY-MM-DD>         # date of last validation in real project
+validated_against: "<description>"   # e.g. "projeto-x v1.2 (Java 21 + SB 3.2.5)"
+status: active                       # active | deprecated | archived
+pack_owner: "@<github-handle>"       # e.g. "@elton"
+security_review: <YYYY-MM-DD>        # date of last security-focused review
+next_review_due: <YYYY-MM-DD>        # security_review + 12 months
+---
+
+# <Stack name + version>
+
+<Intro 1-3 lines: what this pack covers, when to use it vs alternative pack/version.>
+
+## 1. When to use this pack
+
+- Project declares `Primary stack: <X>` in `## Project Identity`.
+- Build manifest (`pom.xml` / `package.json` / `pyproject.toml` / `go.mod` / etc.) declares versions within `versions_covered`.
+- (Optional) Greenfield/legacy guidance — when to prefer next-major pack instead.
+
+## 2. Stack baseline (what this pack assumes)
+
+| Component | Version range | Notes |
+|---|---|---|
+| <language> | <range> | <notes — LTS, EOL dates> |
+| <framework> | <range> | <key feature for this major> |
+| <build tool> | <range> | <Maven Wrapper, npm, etc.> |
+| <test framework> | <range> | <what to avoid — e.g. never H2 as Postgres> |
+| <observability> | <stack> | <Micrometer, OpenTelemetry, etc.> |
+
+## 3. Project structure
+
+```
+<tree of canonical folder layout for this stack>
+```
+
+## 4. Code patterns
+
+### <Pattern name 1 — e.g. DTOs>
+<Real compilable snippet showing the canonical pattern + 1-line rule.>
+
+### <Pattern name 2 — e.g. Error handling>
+<Snippet + rule.>
+
+### <Pattern name 3, 4, 5...>
+
+## 5. Testing
+
+### Unit
+<Snippet + framework versions + rules.>
+
+### Integration
+<Snippet — REAL test pattern, not pseudocode.>
+
+### <Other test types if relevant — slice, contract, mutation, e2e>
+
+## 6. Build & run commands
+
+```bash
+<exact commands a dev would run — build, test, run, lint, coverage>
+```
+
+## 7. Security (per ADR-007 + ADR-027 — MANDATORY section)
+
+### 7.1 Authentication & Authorization
+<Stack-specific auth: framework class names, hashing, MFA hooks>
+
+### 7.2 CORS
+<Snippet — never `*` in prod>
+
+### 7.3 Validation & input sanitization
+<SQL injection, XSS, path traversal — stack-specific mitigation>
+
+### 7.4 Secrets management
+<Env vars, vault, never in committed files>
+
+### 7.5 Rate limiting
+<Library + config snippet for public endpoints>
+
+### 7.6 OWASP Top 10 mapping
+
+| OWASP | Mitigation in this stack |
+|---|---|
+| A01 Broken Access Control | <stack-specific> |
+| A02 Cryptographic Failures | <stack-specific> |
+| A03 Injection | <stack-specific> |
+| A04 Insecure Design | <stack-specific> |
+| A05 Security Misconfiguration | <stack-specific> |
+| A06 Vulnerable Components | <CVE scanner + Renovate/Dependabot> |
+| A07 Auth Failures | <rate limit + account lock + MFA> |
+| A08 Data Integrity | <signature verification, supply chain, SBOM> |
+| A09 Logging Failures | <structured logs + correlation ID + no PII> |
+| A10 SSRF | <allowlist for outbound, validate URLs> |
+
+### 7.7 LGPD / GDPR / compliance specifics (if applicable)
+<PII tagging, soft-delete, data subject access, encryption at rest>
+
+## 8. Anti-patterns (block in code-review)
+
+| ❌ Bad | ✅ Good | Why |
+|---|---|---|
+| <bad pattern> | <good replacement> | <reason> |
+| ... | ... | ... |
+
+## 9. Migration hints — <this version> → <next major>
+
+<Short list of breaking changes when migrating. Points to `migrator` agent.>
+
+## 10. References
+
+- ADR-007 (Senior+ gate thresholds)
+- ADR-026 (Generic agents + packs architecture)
+- ADR-027 (Pack governance)
+- <Official framework migration guide URLs>
+- <OWASP / compliance references>

package/.claude/stacks/dotnet/aspire-9.md

@@ -0,0 +1,528 @@
+---
+stack: dotnet/aspire-9
+versions_covered: "9.0.x — 9.2.x"
+last_validated: 2026-05-28
+validated_against: "reference pack — .NET 9 + Aspire 9.0 + EF Core 9 + xUnit 2.9"
+status: active
+pack_owner: "@elton"
+security_review: 2026-05-28
+next_review_due: 2027-05-28
+---
+
+# .NET 9 + Aspire 9.x
+
+Canonical knowledge pack for .NET cloud-native projects using **.NET Aspire 9.x** as the orchestration framework on top of .NET 9 + ASP.NET Core 9 + EF Core 9. Aspire is Microsoft's opinionated stack for distributed apps: it ships AppHost orchestration, service discovery, telemetry defaults, resilience defaults, and Dev Dashboard out of the box. For traditional ASP.NET Core projects without orchestration needs, this pack still applies — Aspire is additive.
+
+## 1. When to use this pack
+
+- Project declares `Primary stack: .NET 9 + Aspire 9.x + ASP.NET Core` in `## Project Identity`.
+- Solution contains a `<Solution>.AppHost` project referencing `Aspire.Hosting` and at least one ASP.NET Core service project.
+- Project follows the Aspire convention of `*.AppHost` (orchestration) + `*.ServiceDefaults` (shared telemetry/resilience) + one or more service projects.
+- Greenfield .NET on cloud-native infra (Kubernetes, Azure Container Apps, AWS ECS) — Aspire's manifest export makes deployment cleaner.
+- For Windows desktop apps, MAUI, or library-only solutions: Aspire is not applicable. This pack covers cloud-native services only.
+
+## 2. Stack baseline (what this pack assumes)
+
+| Component | Version range | Notes |
+|---|---|---|
+| .NET SDK | 9.0.x (min) / 10.0 preview (latest) | Native AOT supported for many service patterns; minimal APIs maduro |
+| Aspire workload | 9.0.x — 9.2.x | `dotnet workload install aspire`; AppHost + ServiceDefaults convention |
+| ASP.NET Core | 9.0.x | Minimal APIs are the default; `OpenAPI.NET` package replaces Swashbuckle for OpenAPI 3.1 |
+| EF Core | 9.0.x | Bulk insert/update first-class; `IExecutionStrategy` mandatory for retry-aware transactions |
+| Database providers | Npgsql 9.x (Postgres) / Microsoft.EntityFrameworkCore.SqlServer 9.x | NEVER InMemory provider for tests if prod is real DB |
+| Validation | FluentValidation 11.10+ (integrated via `SharpGrip.FluentValidation.AutoValidation`) OR DataAnnotations | FluentValidation preferred for complex rules |
+| Build | `dotnet build` + `dotnet publish` (Native AOT optional) | SLN format ok; new `slnx` (preview) acceptable |
+| Tests | xUnit 2.9+ + FluentAssertions 6.x + Moq 4.20 or NSubstitute 5.x | Testcontainers .NET 4.0+ for integration |
+| Mutation | Stryker.NET 4.4+ | Target ≥70% on `Domain` + `Application` |
+| Coverage | `coverlet.collector` + `dotnet test --collect:"XPlat Code Coverage"` | Target ≥85% lines |
+| Static analysis | Roslyn analyzers (`Microsoft.CodeAnalysis.NetAnalyzers`, `StyleCop`, `SonarAnalyzer.CSharp`) | TreatWarningsAsErrors = true in CI |
+| Security scan | `dotnet list package --vulnerable --include-transitive` + `dotnet-security-scan` | 0 CVE with CVSS ≥7.0 |
+| Observability | Aspire ServiceDefaults pre-wires OpenTelemetry SDK + Health Checks | W3C Trace Context; auto-instruments HTTP, EF Core, http.Client |
+| Service discovery | Aspire built-in (DNS-based in dev, K8s in prod) | No Consul/Eureka needed |
+| Background jobs | `Hangfire` 1.8+ OR `Quartz.NET` 3.x | Or Azure Functions / AWS Lambda for FaaS pattern |
+| Resilience | Polly 8.x (integrated via `Microsoft.Extensions.Http.Resilience`) | Standard pipelines: retry + circuit breaker + timeout |
+
+## 3. Project structure (DDD / Clean Architecture)
+
+```
+solution/
+├── solution.sln
+├── Directory.Build.props
+├── src/
+│   ├── Solution.AppHost/                  # Aspire orchestrator
+│   │   ├── Program.cs                     # builder.AddProject<...>()
+│   │   └── Solution.AppHost.csproj
+│   ├── Solution.ServiceDefaults/          # shared OTel/HealthCheck/Resilience
+│   │   ├── Extensions.cs                  # AddServiceDefaults()
+│   │   └── Solution.ServiceDefaults.csproj
+│   ├── Solution.Domain/                   # pure C#; no EF, no ASP.NET
+│   │   ├── Products/
+│   │   │   ├── Product.cs                 # entity / value object
+│   │   │   ├── IProductRepository.cs      # interface
+│   │   │   └── ProductService.cs
+│   │   └── Solution.Domain.csproj
+│   ├── Solution.Application/              # use cases (1 class each)
+│   │   ├── Products/
+│   │   │   ├── CreateProductHandler.cs
+│   │   │   ├── ListProductsHandler.cs
+│   │   │   └── Dto.cs
+│   │   └── Solution.Application.csproj
+│   ├── Solution.Infrastructure/           # EF Core, HttpClient, AWS SDK
+│   │   ├── Persistence/
+│   │   │   ├── AppDbContext.cs
+│   │   │   ├── Migrations/
+│   │   │   └── ProductRepository.cs
+│   │   └── Solution.Infrastructure.csproj
+│   └── Solution.Api/                      # minimal APIs / controllers
+│       ├── Endpoints/
+│       │   ├── Products.cs
+│       │   └── ErrorEndpoints.cs          # RFC 9457 ProblemDetails
+│       ├── Program.cs                     # bootstrap
+│       └── Solution.Api.csproj
+└── tests/
+    ├── Solution.Domain.Tests/
+    ├── Solution.Application.Tests/
+    └── Solution.Api.IntegrationTests/
+```
+
+**Rule**: `Domain` project references nothing from EF Core or ASP.NET. `Application` references only `Domain`. `Infrastructure` references EF Core. `Api` references `Application` + `Infrastructure` (for DI registration). Project references enforced by `Directory.Build.props` — compile fails on violation.
+
+## 4. Code patterns
+
+### Domain entity (no EF Core, no ASP.NET)
+
+```csharp
+// src/Solution.Domain/Products/Product.cs
+namespace Solution.Domain.Products;
+
+public sealed class Product
+{
+    public Guid Id { get; }
+    public string Name { get; private set; }
+    public decimal Price { get; private set; }
+    public int Stock { get; private set; }
+    public DateTimeOffset CreatedAt { get; }
+
+    private Product(Guid id, string name, decimal price, int stock, DateTimeOffset createdAt)
+        => (Id, Name, Price, Stock, CreatedAt) = (id, name, price, stock, createdAt);
+
+    public static Product Create(string name, decimal price, int stock)
+    {
+        if (string.IsNullOrWhiteSpace(name)) throw new ArgumentException("name required");
+        if (price <= 0) throw new ArgumentException("price must be positive");
+        if (stock < 0) throw new ArgumentException("stock cannot be negative");
+        return new Product(Guid.NewGuid(), name, price, stock, DateTimeOffset.UtcNow);
+    }
+
+    public void Reserve(int qty)
+    {
+        if (qty <= 0) throw new InvalidOperationException("qty must be positive");
+        if (qty > Stock) throw new InvalidOperationException("insufficient stock");
+        Stock -= qty;
+    }
+}
+```
+
+**Rule**: `decimal` for money (NOT `double` / `float`). Entity constructor private; static `Create` factory enforces invariants. Business rules as methods on the entity.
+
+### Repository port + EF Core adapter
+
+```csharp
+// src/Solution.Domain/Products/IProductRepository.cs
+namespace Solution.Domain.Products;
+
+public interface IProductRepository
+{
+    Task<Product?> GetAsync(Guid id, CancellationToken ct);
+    Task SaveAsync(Product product, CancellationToken ct);
+}
+```
+
+```csharp
+// src/Solution.Infrastructure/Persistence/AppDbContext.cs
+using Microsoft.EntityFrameworkCore;
+using Solution.Domain.Products;
+
+namespace Solution.Infrastructure.Persistence;
+
+public sealed class AppDbContext(DbContextOptions<AppDbContext> options) : DbContext(options)
+{
+    public DbSet<Product> Products => Set<Product>();
+
+    protected override void OnModelCreating(ModelBuilder mb)
+    {
+        var product = mb.Entity<Product>();
+        product.ToTable("products");
+        product.HasKey(p => p.Id);
+        product.Property(p => p.Name).HasMaxLength(120).IsRequired();
+        product.Property(p => p.Price).HasPrecision(12, 2);
+        product.Property(p => p.CreatedAt);
+        product.HasIndex(p => p.Name);
+    }
+}
+```
+
+```csharp
+// src/Solution.Infrastructure/Persistence/ProductRepository.cs
+using Microsoft.EntityFrameworkCore;
+using Solution.Domain.Products;
+
+namespace Solution.Infrastructure.Persistence;
+
+public sealed class ProductRepository(AppDbContext db) : IProductRepository
+{
+    public Task<Product?> GetAsync(Guid id, CancellationToken ct)
+        => db.Products.AsNoTracking().FirstOrDefaultAsync(p => p.Id == id, ct);
+
+    public async Task SaveAsync(Product product, CancellationToken ct)
+    {
+        if (await db.Products.AnyAsync(p => p.Id == product.Id, ct))
+            db.Products.Update(product);
+        else
+            db.Products.Add(product);
+        await db.SaveChangesAsync(ct);
+    }
+}
+```
+
+**Rule**: `AsNoTracking()` for read-only queries (perf). `SaveChangesAsync` always with CancellationToken. UUID primary key.
+
+### Minimal API endpoint (ASP.NET Core 9 canonical)
+
+```csharp
+// src/Solution.Api/Endpoints/Products.cs
+using Solution.Application.Products;
+
+namespace Solution.Api.Endpoints;
+
+public static class ProductEndpoints
+{
+    public record CreateProductRequest(string Name, decimal Price, int Stock);
+    public record ProductResponse(Guid Id, string Name, decimal Price, int Stock, DateTimeOffset CreatedAt);
+
+    public static void MapProductEndpoints(this IEndpointRouteBuilder app)
+    {
+        var group = app.MapGroup("/api/v1/products").WithTags("Products");
+
+        group.MapPost("/", async (
+            CreateProductRequest req,
+            CreateProductHandler handler,
+            CancellationToken ct) =>
+        {
+            var product = await handler.HandleAsync(req.Name, req.Price, req.Stock, ct);
+            return Results.Created(
+                $"/api/v1/products/{product.Id}",
+                new ProductResponse(product.Id, product.Name, product.Price, product.Stock, product.CreatedAt));
+        })
+        .WithName("CreateProduct")
+        .Produces<ProductResponse>(StatusCodes.Status201Created)
+        .ProducesValidationProblem(StatusCodes.Status422UnprocessableEntity);
+    }
+}
+```
+
+```csharp
+// src/Solution.Api/Program.cs
+using Solution.Infrastructure.Persistence;
+using Solution.Application.Products;
+using Microsoft.EntityFrameworkCore;
+
+var builder = WebApplication.CreateBuilder(args);
+
+// Aspire ServiceDefaults: telemetry, health checks, service discovery, resilience
+builder.AddServiceDefaults();
+
+// EF Core + connection string via Aspire reference
+builder.AddNpgsqlDbContext<AppDbContext>("postgresdb");
+
+builder.Services.AddScoped<IProductRepository, ProductRepository>();
+builder.Services.AddScoped<CreateProductHandler>();
+
+builder.Services.AddProblemDetails();
+builder.Services.AddOpenApi();
+
+var app = builder.Build();
+
+app.MapDefaultEndpoints();      // /health, /alive, /metrics from ServiceDefaults
+app.UseExceptionHandler();      // converts unhandled to RFC 9457
+app.MapOpenApi();
+app.MapProductEndpoints();
+
+app.Run();
+```
+
+**Rule**: minimal APIs are the default (no `Controllers/` folder unless team prefers MVC). `Results.Created/...` returns typed `IResult`. `Produces<>` for OpenAPI. ServiceDefaults pre-wires observability.
+
+### Aspire AppHost orchestration
+
+```csharp
+// src/Solution.AppHost/Program.cs
+var builder = DistributedApplication.CreateBuilder(args);
+
+var postgres = builder.AddPostgres("postgres")
+    .WithDataVolume()
+    .AddDatabase("postgresdb");
+
+var api = builder.AddProject<Projects.Solution_Api>("api")
+    .WithReference(postgres)
+    .WaitFor(postgres);
+
+builder.Build().Run();
+```
+
+**Rule**: AppHost is the single source of truth for service topology in dev. `WithReference()` injects connection strings via env vars. `WaitFor()` ensures startup order.
+
+## 5. Testing
+
+### Unit (xUnit + FluentAssertions, no EF / no ASP.NET)
+
+```csharp
+// tests/Solution.Domain.Tests/Products/ProductTests.cs
+using FluentAssertions;
+using Solution.Domain.Products;
+
+public class ProductTests
+{
+    [Fact]
+    public void Reserve_DecreasesStock()
+    {
+        var p = Product.Create("widget", 9.90m, 10);
+        p.Reserve(3);
+        p.Stock.Should().Be(7);
+    }
+
+    [Fact]
+    public void Reserve_ThrowsOnZero()
+    {
+        var p = Product.Create("widget", 9.90m, 10);
+        var act = () => p.Reserve(0);
+        act.Should().Throw<InvalidOperationException>();
+    }
+}
+```
+
+### Integration (WebApplicationFactory + Testcontainers Postgres)
+
+```csharp
+// tests/Solution.Api.IntegrationTests/ProductEndpointsTests.cs
+using FluentAssertions;
+using Microsoft.AspNetCore.Mvc.Testing;
+using Testcontainers.PostgreSql;
+
+public class ProductEndpointsTests : IAsyncLifetime
+{
+    private readonly PostgreSqlContainer _pg = new PostgreSqlBuilder()
+        .WithImage("postgres:16-alpine")
+        .Build();
+
+    private WebApplicationFactory<Program>? _factory;
+
+    public async Task InitializeAsync()
+    {
+        await _pg.StartAsync();
+        Environment.SetEnvironmentVariable("ConnectionStrings__postgresdb", _pg.GetConnectionString());
+        _factory = new WebApplicationFactory<Program>();
+    }
+
+    public async Task DisposeAsync()
+    {
+        await _pg.DisposeAsync();
+        _factory?.Dispose();
+    }
+
+    [Fact]
+    public async Task Post_CreatesProduct()
+    {
+        var client = _factory!.CreateClient();
+        var resp = await client.PostAsJsonAsync("/api/v1/products", new {
+            Name = "widget", Price = 9.90m, Stock = 100,
+        });
+        resp.StatusCode.Should().Be(HttpStatusCode.Created);
+    }
+}
+```
+
+**Rule**: NEVER `UseInMemoryDatabase()` if prod is Postgres. Testcontainers .NET 4.0+ is the standard.
+
+### Mutation (Stryker.NET)
+
+```bash
+dotnet stryker --project Solution.Domain --threshold-high 80 --threshold-low 70 --threshold-break 60
+# Target: mutation score >= 70% on Domain + Application
+```
+
+## 6. Build & run commands
+
+```bash
+# Setup (install workload once per machine)
+dotnet workload install aspire
+
+# Restore
+dotnet restore
+
+# Build (with warnings as errors)
+dotnet build -p:TreatWarningsAsErrors=true
+
+# Run via Aspire AppHost (boots all services + Dev Dashboard)
+dotnet run --project src/Solution.AppHost
+
+# Run a single service directly (skips Aspire orchestration)
+dotnet run --project src/Solution.Api
+
+# Migrations (EF Core)
+dotnet ef migrations add InitialCreate --project src/Solution.Infrastructure --startup-project src/Solution.Api
+dotnet ef database update --project src/Solution.Infrastructure --startup-project src/Solution.Api
+
+# Tests
+dotnet test                                                       # all
+dotnet test --collect:"XPlat Code Coverage"                       # with coverage
+dotnet test --filter "Category!=Integration"                      # fast loop
+
+# Mutation
+dotnet stryker
+
+# Lint (Roslyn analyzers built in; surface via build)
+dotnet format --verify-no-changes                                 # CI gate
+
+# Security scan
+dotnet list package --vulnerable --include-transitive
+dotnet list package --outdated
+
+# Native AOT publish (when applicable)
+dotnet publish src/Solution.Api -c Release -r linux-x64 -p:PublishAot=true
+
+# Aspire manifest export (for K8s/Azure deployment)
+dotnet run --project src/Solution.AppHost --publisher manifest --output-path ./aspire-manifest.json
+```
+
+## 7. Security (per ADR-007 + ADR-027 — MANDATORY section)
+
+### 7.1 Authentication & Authorization
+
+- **JWT Bearer**: `Microsoft.AspNetCore.Authentication.JwtBearer`. Configure validation parameters (issuer, audience, signing key, lifetime). RS256 preferred.
+- **Identity**: `Microsoft.AspNetCore.Identity` for user management; ASP.NET Core 9 ships `MapIdentityApi<T>()` for minimal-API friendly endpoints.
+- **OAuth2 / OIDC**: `Microsoft.AspNetCore.Authentication.OpenIdConnect` for Auth0/Entra/Keycloak.
+- **Password hashing**: ASP.NET Core Identity uses PBKDF2 by default. For new projects consider switching to Argon2 via `BCrypt.Net-Next` or `Konscious.Security.Cryptography.Argon2`.
+- **Authorization**: `[Authorize(Policy = "...")]` attributes; minimal APIs use `.RequireAuthorization("policy")`. Object-level checks inside the handler.
+
+### 7.2 CORS
+
+```csharp
+builder.Services.AddCors(opt => opt.AddPolicy("Default", p =>
+    p.WithOrigins("https://app.example.com")                  // NEVER WithAnyOrigin() in prod
+     .AllowCredentials()
+     .WithMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
+     .WithHeaders("Authorization", "Content-Type")));
+
+app.UseCors("Default");
+```
+
+### 7.3 Validation & input sanitization
+
+- **SQL injection**: EF Core parameterizes by default. NEVER `FromSqlRaw($"... {input}")` — use `FromSqlInterpolated($"... {input}")` (parameterizes) OR `FromSqlRaw` with parameters separately.
+- **DataAnnotations or FluentValidation**: required on every request DTO. `[Required]`, `[MaxLength]`, `[Range]`, etc.
+- **Path traversal**: `Path.GetFullPath` + `StartsWith` check against an allowlisted base directory.
+- **Antiforgery**: `app.UseAntiforgery()` if you serve form-based POSTs; not needed for stateless JWT APIs.
+
+### 7.4 Secrets management
+
+- **dev**: `dotnet user-secrets` (per-user, not in source).
+- **prod**: Azure Key Vault / AWS Secrets Manager / HashiCorp Vault via `Microsoft.Extensions.Configuration.<Provider>`.
+- **Aspire**: AppHost wires connection strings via `WithReference()` — secrets surface via configuration, not env vars in code.
+- Never `appsettings.json` with real secrets. `appsettings.json` committed; `appsettings.Production.json` typically NOT committed.
+
+### 7.5 Rate limiting
+
+ASP.NET Core 9 has built-in rate limiting:
+
+```csharp
+builder.Services.AddRateLimiter(opt =>
+{
+    opt.GlobalLimiter = PartitionedRateLimiter.Create<HttpContext, string>(ctx =>
+        RateLimitPartition.GetFixedWindowLimiter(
+            partitionKey: ctx.Connection.RemoteIpAddress?.ToString() ?? "anon",
+            factory: _ => new FixedWindowRateLimiterOptions {
+                PermitLimit = 100, Window = TimeSpan.FromMinutes(1) }));
+
+    opt.AddPolicy("auth", ctx => RateLimitPartition.GetFixedWindowLimiter(
+        ctx.Connection.RemoteIpAddress?.ToString() ?? "anon",
+        _ => new FixedWindowRateLimiterOptions {
+            PermitLimit = 5, Window = TimeSpan.FromMinutes(1) }));
+});
+
+app.UseRateLimiter();
+// Per-endpoint: .RequireRateLimiting("auth")
+```
+
+### 7.6 OWASP Top 10 mapping
+
+| OWASP | Mitigation in .NET 9 + ASP.NET Core |
+|---|---|
+| A01 Broken Access Control | `[Authorize]` + policy-based auth; object-level check in handler; default-deny via `[FallbackAuth]` |
+| A02 Cryptographic Failures | PBKDF2 (Identity default) or Argon2 password hashing; TLS at reverse proxy; HSTS via `app.UseHsts()`; JWT RS256 with key rotation |
+| A03 Injection | EF Core parameterization; `FromSqlInterpolated` (safe) vs `FromSqlRaw` (review); DataAnnotations/FluentValidation on every DTO |
+| A04 Insecure Design | DDD layering enforced (`Domain` no EF/ASP.NET); use case handler = single async method; ADRs document deviations |
+| A05 Security Misconfiguration | `app.UseHsts()`; `Server` header removed; CORS explicit allowlist; `ASPNETCORE_ENVIRONMENT=Production` |
+| A06 Vulnerable Components | `dotnet list package --vulnerable` in CI; Dependabot for `.csproj` bumps; `Directory.Packages.props` for central version mgmt |
+| A07 Auth Failures | Built-in rate limiter on auth endpoints; account lockout via Identity options; MFA via `Microsoft.AspNetCore.Identity.Extensions` |
+| A08 Data Integrity | `nuget.config` with verified package sources; SBOM via `dotnet-sbom-tool`; signed assemblies for internal libs |
+| A09 Logging Failures | Serilog or built-in `Microsoft.Extensions.Logging` with JSON formatter; correlation ID via `AddOpenTelemetry()`; **NEVER** log request body raw (PII) |
+| A10 SSRF | Centralized `IHttpClientFactory` with named clients + delegating handler that allowlists outbound hosts; reject private CIDRs by default |
+
+### 7.7 LGPD / GDPR / compliance specifics
+
+- **PII tagging**: attribute `[PersonalData]` (from ASP.NET Identity) on entity properties; custom Roslyn analyzer flags missing tags on string properties named Email/Document/CPF.
+- **Soft delete**: `IsDeleted` + `DeletedAt` columns; global query filter in `OnModelCreating` excludes deleted rows. NEVER hard delete user-owned data.
+- **Data subject access (Art 15)**: `GET /api/v1/me/export` returns user data as ZIP (use ASP.NET Identity's built-in personal data export).
+- **Erasure (Art 17)**: `DELETE /api/v1/me` redacts PII fields while preserving FKs.
+- **Encryption at rest**: SQL Server TDE / PostgreSQL TDE (cloud-managed) OR column-level via `Microsoft.AspNetCore.DataProtection` for sensitive fields.
+
+## 8. Anti-patterns (block in code-review)
+
+| ❌ Bad | ✅ Good | Why |
+|---|---|---|
+| `double` or `float` for money | `decimal` | IEEE 754 precision loss is real |
+| `DbContext` injected as singleton | `AddDbContext<>` (scoped — default) | `DbContext` is not thread-safe |
+| `.Result` or `.Wait()` on Tasks | `await` everywhere | Deadlocks under ASP.NET sync context; lost exceptions |
+| `FromSqlRaw($"... {input}")` (interpolated string) | `FromSqlInterpolated($"... {input}")` | The Raw + interpolated combo is SQL injection; Interpolated parameterizes |
+| Public setters on domain entity properties | Private setters + business methods | Encapsulation breaks otherwise |
+| `UseInMemoryDatabase()` for integration tests | Testcontainers Postgres / SQL Server | InMemory has DIFFERENT semantics (no FK constraints, etc.) |
+| `Controller` everywhere when minimal APIs fit | Minimal APIs for simple CRUD; controllers only when MVC features needed | Less ceremony, less code |
+| `Task<ActionResult<T>>` from minimal API | `Results.Ok(...)` / `Results.Created(...)` | Minimal APIs use `IResult`, not `ActionResult` |
+| Ignoring `CancellationToken` in async signatures | Accept + pass `CancellationToken` everywhere | Caller cancellation must propagate to DB / HTTP |
+| `JsonSerializer.Serialize(...)` without options | Configure `JsonOptions` once (camelCase, ignore nulls, etc.) | Inconsistent serialization across endpoints |
+| Catching `Exception` in handler | Let global exception handler do it; catch specific domain exceptions | Hides bugs, breaks 500 telemetry |
+| `appsettings.json` with secrets | User secrets in dev, Key Vault in prod | Secrets in repo = secrets in git history |
+| Native AOT for solutions using reflection-heavy libs | Trim warnings audited; switch lib OR keep JIT | Runtime crash discovered late |
+
+## 9. Migration hints — .NET 8 / Aspire preview → 9
+
+Breaking changes worth flagging when `migrator` agent runs .NET 8 → 9 + Aspire 1.x → 9:
+
+- **.NET 9 SDK required**; downgrading targetFramework to net8.0 still works but new APIs unavailable.
+- **Aspire workload re-install**: `dotnet workload update` after .NET 9 SDK install.
+- **`Aspire.Hosting.AppHost` package renamed/reorganized** — review AppHost `using` directives.
+- **OpenAPI**: ASP.NET 9 ships `Microsoft.AspNetCore.OpenApi` natively. Remove Swashbuckle if you only used basic Swagger UI; keep Swashbuckle if you used its extensibility heavily.
+- **EF Core 9 bulk operations**: `ExecuteUpdate` / `ExecuteDelete` work with complex predicates now. Audit places where you wrote manual batching loops.
+- **`IExceptionHandler`** interface (NET 8+) is the canonical exception hook — replaces `UseExceptionHandler(builder => ...)` patterns from earlier.
+- **Rate limiting** moved out of preview (built-in since .NET 7); remove `Microsoft.AspNetCore.RateLimiting` package if you added it manually.
+- **Native AOT** broader compat: many libs that didn't AOT in .NET 8 now do. Retry compilation if you backed off before.
+- **`PublishAot`** sets multiple sub-properties; review project file for redundant manual settings.
+
+Hand off to `migrator` with: current .NET version, Aspire version, list of AppHost dependencies, list of services using deprecated APIs.
+
+## 10. References
+
+- [.NET Aspire documentation](https://learn.microsoft.com/en-us/dotnet/aspire/)
+- [ASP.NET Core 9 docs](https://learn.microsoft.com/en-us/aspnet/core/)
+- [EF Core 9 docs](https://learn.microsoft.com/en-us/ef/core/)
+- [Minimal APIs guide](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis)
+- [Polly resilience library](https://www.thepollyproject.org/)
+- [Testcontainers .NET](https://dotnet.testcontainers.org/)
+- [Stryker.NET mutation testing](https://stryker-mutator.io/docs/stryker-net/introduction/)
+- [OWASP .NET Security Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/DotNet_Security_Cheat_Sheet.html)
+- [ASP.NET Core security overview](https://learn.microsoft.com/en-us/aspnet/core/security/)
+- ADR-007 (Senior+ gate thresholds — coverage ≥85%, mutation ≥70%)
+- ADR-026 (Generic agents + stack packs architecture)
+- ADR-027 (Pack governance — frontmatter + security mandatory + CODEOWNERS + annual review)
+- ADR-029 (Canonical pack format — this document follows it)