@polymorphism-tech/morph-spec 2.2.0 → 2.4.0

package/content/.claude/skills/checklists/code-review.md

@@ -0,0 +1,226 @@
+# Code Review Checklist
+
+> Comprehensive checklist for .NET code review: naming, architecture, clean code, duplication, and runtime patterns.
+> **Ref:** `framework/standards/coding.md` for naming conventions and style.
+> **Ref:** `framework/standards/architecture.md` for layer rules and SOLID.
+> **Ref:** `framework/standards/blazor-efcore.md` for DbContext patterns and background ops.
+
+---
+
+## Naming & Style (ref: coding.md)
+
+- [ ] `[CRITICAL]` Constants use PascalCase (`MaxRetryCount`, NOT `MAX_RETRY_COUNT`)
+- [ ] `[CRITICAL]` No Hungarian notation (`strName`, `iCount`, `btnSubmit`)
+- [ ] `[HIGH]` Private fields use `_camelCase` prefix
+- [ ] `[HIGH]` Async methods have `Async` suffix
+- [ ] `[HIGH]` Interfaces prefixed with `I`
+- [ ] `[MEDIUM]` No abbreviations in public APIs (`repository` not `repo`)
+- [ ] `[MEDIUM]` All classes `sealed` unless designed for inheritance
+- [ ] `[MEDIUM]` File-scoped namespaces used
+
+---
+
+## Architecture Review (ref: architecture.md)
+
+### Layer Integrity
+- [ ] `[CRITICAL]` Domain has zero references to Infrastructure or Web
+- [ ] `[CRITICAL]` No circular dependencies between projects
+- [ ] `[HIGH]` Application does NOT reference Web project
+- [ ] `[HIGH]` Infrastructure details don't leak into Application DTOs
+
+### Responsibility & Organization
+- [ ] `[HIGH]` No class > 300 lines (SRP violation)
+- [ ] `[HIGH]` Controllers/pages are thin (< 50 lines logic)
+- [ ] `[MEDIUM]` One class per file, file name = class name
+- [ ] `[MEDIUM]` Files in correct project/folder per architecture.md
+- [ ] `[LOW]` No "God classes" (10+ constructor dependencies)
+
+### Dependencies
+- [ ] `[HIGH]` External services accessed through interfaces
+- [ ] `[HIGH]` No hardcoded connection strings, URLs, or secrets
+- [ ] `[MEDIUM]` Configuration via Options pattern (`IOptions<T>`)
+- [ ] `[LOW]` No over-abstraction (interface with 1 impl never mocked)
+
+---
+
+## Clean Code Review
+
+### Method Quality
+- [ ] `[HIGH]` No methods > 30 lines (extract sub-methods)
+- [ ] `[HIGH]` No methods with > 4 parameters (use request object)
+- [ ] `[MEDIUM]` No nested conditionals > 3 levels (use early return)
+- [ ] `[MEDIUM]` No complex conditionals (> 3 conditions — extract to named method)
+
+### Magic Values
+- [ ] `[HIGH]` No magic strings in comparisons (use enum or constant)
+- [ ] `[HIGH]` No magic numbers (extract to PascalCase constant)
+- [ ] `[MEDIUM]` No hardcoded URLs, file paths, or config values
+
+### Dead Code
+- [ ] `[MEDIUM]` No unused private methods
+- [ ] `[MEDIUM]` No unused parameters
+- [ ] `[LOW]` No commented-out code blocks (> 3 lines)
+- [ ] `[LOW]` No empty or near-empty files
+
+---
+
+## Duplication Review
+
+- [ ] `[HIGH]` No exact/near-exact duplicate methods across classes
+- [ ] `[HIGH]` No duplicate model definitions (same properties in different classes)
+- [ ] `[MEDIUM]` No thin wrappers that only delegate without adding value
+- [ ] `[MEDIUM]` No mirrored interface methods (extract base interface)
+- [ ] `[MEDIUM]` No duplicate enums across projects (centralize in Domain)
+- [ ] `[LOW]` No passthrough service methods (controller -> service with zero logic)
+
+---
+
+## Async & Cancellation
+
+- [ ] `[CRITICAL]` CancellationToken propagated through entire call chain
+- [ ] `[CRITICAL]` No `.Result` or `.Wait()` (deadlock risk in Blazor Server)
+- [ ] `[HIGH]` No `async void` (except event handlers)
+- [ ] `[HIGH]` Timeout configured for external operations
+- [ ] `[MEDIUM]` `ConfigureAwait(false)` only in library code
+
+---
+
+## Logging
+
+- [ ] `[HIGH]` Logs at critical points (entry, exit, errors)
+- [ ] `[HIGH]` No `$""` string interpolation in log methods (use message templates)
+- [ ] `[HIGH]` No sensitive data logged (passwords, tokens, PII)
+- [ ] `[MEDIUM]` Logs include correlation IDs (OrderId, UserId)
+- [ ] `[MEDIUM]` Appropriate log level (Information, Warning, Error)
+
+---
+
+## Error Handling
+
+- [ ] `[CRITICAL]` No empty catch blocks
+- [ ] `[HIGH]` Specific exceptions (not generic `catch (Exception)` without re-throw)
+- [ ] `[HIGH]` Inner exception preserved on re-throw
+- [ ] `[HIGH]` Result pattern for expected business errors, exceptions for infrastructure
+- [ ] `[MEDIUM]` Consistent error handling pattern across all services
+
+---
+
+## DI
+
+- [ ] `[HIGH]` Constructor injection with interfaces (not concrete types)
+- [ ] `[HIGH]` Correct lifetime (Scoped for DbContext, Singleton for factories)
+- [ ] `[MEDIUM]` No service locator pattern (`IServiceProvider.GetService<T>()` in business code)
+
+---
+
+## Services
+
+### State Validation
+- [ ] `[HIGH]` Validates INVALID states (not valid ones) for future extensibility
+- [ ] `[HIGH]` Error states handled explicitly
+
+```csharp
+// Correct: validate INVALID states
+if (order.Status >= OrderStatus.Completed || order.Status == OrderStatus.Failed)
+    throw new InvalidOperationException("Cannot process completed or failed order");
+```
+
+### Transactions
+- [ ] `[HIGH]` Multiple operations wrapped in transaction
+- [ ] `[HIGH]` Rollback on error
+
+```csharp
+await using var transaction = await _context.Database.BeginTransactionAsync(ct);
+try
+{
+    await _repository.AddAsync(order, ct);
+    await _paymentService.ChargeAsync(order.Id, ct);
+    await transaction.CommitAsync(ct);
+}
+catch { await transaction.RollbackAsync(ct); throw; }
+```
+
+---
+
+## Background Operations
+
+### DbContext Safety
+- [ ] `[CRITICAL]` Uses `IDbContextFactory` (not scoped DbContext)
+- [ ] `[CRITICAL]` Repository created via Factory with `await using`
+- [ ] `[HIGH]` No `Task.Delay` as race condition workaround
+
+```csharp
+// Correct pattern
+_ = Task.Run(async () =>
+{
+    try
+    {
+        await using var repo = _repoFactory.CreateScoped();
+        var order = await repo.GetByIdAsync(orderId);
+        // ...
+    }
+    catch (Exception ex) { _logger.LogError(ex, "Failed {OrderId}", orderId); }
+});
+```
+
+### Hangfire Jobs
+- [ ] `[HIGH]` `[AutomaticRetry]` configured
+- [ ] `[HIGH]` Job is idempotent (safe to run multiple times)
+- [ ] `[MEDIUM]` CancellationToken used
+- [ ] `[MEDIUM]` No HTTP request state dependency
+
+### Resilience
+- [ ] `[MEDIUM]` Retry policy for transient operations
+- [ ] `[MEDIUM]` State persisted before long operation
+- [ ] `[MEDIUM]` Idempotency guaranteed for retries
+
+---
+
+## DTOs / Contracts
+
+### Naming
+- [ ] `[HIGH]` Descriptive property names (not "Data", "Value", "Info")
+- [ ] `[HIGH]` Correct suffix: `Request` (input), `Response` (output), `Dto` (generic), `Command`/`Query` (CQRS)
+
+### Types
+- [ ] `[MEDIUM]` `Stream` for large files, `byte[]` for small in-memory data
+- [ ] `[MEDIUM]` `DateTimeOffset` for timestamps, `DateTime` for local dates
+- [ ] `[MEDIUM]` Nullable `?` only where truly optional
+
+### Structure
+- [ ] `[MEDIUM]` Records for immutable DTOs, classes with `init` for mutable entities
+- [ ] `[MEDIUM]` Response DTOs have all properties needed by UI
+- [ ] `[MEDIUM]` Enums have explicit values with logical ordering (errors at 100+)
+
+```csharp
+public enum OrderStatus
+{
+    Created = 0, PendingPayment = 1, Processing = 2, Completed = 3,  // Normal flow
+    Failed = 100, Cancelled = 101, Refunded = 102                    // Error states
+}
+```
+
+### Service Interfaces
+- [ ] `[HIGH]` Async methods with `Async` suffix
+- [ ] `[HIGH]` CancellationToken as last parameter
+- [ ] `[MEDIUM]` `Task<Result<T>>` for expected business errors
+
+---
+
+## Quick Pre-Merge Checklist
+
+```
+[ ] Naming follows coding.md (PascalCase constants, _camelCase fields, sealed classes)
+[ ] CancellationToken propagated on all async methods
+[ ] Structured logging at critical points (message templates, not $"")
+[ ] No empty catch blocks, Result pattern for business errors
+[ ] Background ops use IDbContextFactory + await using
+[ ] No duplicate code, no magic values, no methods > 30 lines
+[ ] Architecture layers respected (Domain has zero external refs)
+[ ] DTOs have descriptive names + correct types
+```
+
+---
+
+*Consolidated from: code-review-services.md + code-review-background.md + code-review-contracts.md + architecture/clean-code/duplication analysis.*
+*MORPH-SPEC by Polymorphism Tech*

package/content/.claude/skills/checklists/morph-checklist.md

@@ -0,0 +1,117 @@
+# Skill: /morph-checklist
+
+> **Layer:** 2 | **Load:** on-keyword | **Keywords:** checklist, deploy, security, seo, performance, accessibility, lgpd, legal
+
+Types: `deploy`, `security`, `seo`, `performance`, `accessibility`, `legal-brazil`, `simulation` (see [simulation-checklist.md](simulation-checklist.md))
+
+---
+
+## Deploy
+
+### Pre-Deploy
+- [ ] `dotnet build --configuration Release` passes
+- [ ] `dotnet test` passes
+- [ ] Migrations applied (`dotnet ef database update`)
+- [ ] Env vars configured (connection strings, API keys, feature flags)
+
+### Infrastructure
+- [ ] Bicep/IaC updated (`az deployment group what-if`)
+- [ ] SSL/HTTPS configured
+- [ ] DNS pointing correctly
+- [ ] Health checks configured
+
+### Security & Monitoring
+- [ ] Secrets in Key Vault (not in code)
+- [ ] Managed Identity configured
+- [ ] CORS configured
+- [ ] Rate limiting enabled
+- [ ] Application Insights + alerts configured
+
+### Post-Deploy
+- [ ] Smoke tests executed
+- [ ] Rollback plan documented
+
+---
+
+## Security
+
+### Auth & Authorization
+- [ ] Passwords hashed (bcrypt/Argon2), MFA available
+- [ ] JWT with short expiration + refresh tokens
+- [ ] RBAC + resource-based authorization
+- [ ] Ownership verification (user sees only their data)
+
+### Input & Headers
+- [ ] Server-side validation (never trust client)
+- [ ] HTML sanitized (XSS), parametrized queries (SQLi)
+- [ ] File upload validation (type, size, content)
+- [ ] Security headers: `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `CSP: default-src 'self'`
+
+### Data
+- [ ] PII encrypted at rest, masked in logs
+- [ ] Card data never stored (use tokenization)
+- [ ] `dotnet list package --vulnerable` clean
+
+---
+
+## SEO
+
+- [ ] `<title>` + `<meta description>` (150-160 chars)
+- [ ] `<link rel="canonical">` + `robots.txt` + `sitemap.xml`
+- [ ] Open Graph tags (og:title, og:description, og:image)
+- [ ] URLs friendly, heading hierarchy (H1>H2>H3)
+- [ ] Images optimized (WebP, lazy loading, alt text)
+- [ ] Core Web Vitals: LCP < 2.5s, FID < 100ms, CLS < 0.1
+
+---
+
+## Performance
+
+### Backend
+- [ ] `.AsNoTracking()` for reads, no N+1, projections (`.Select()`)
+- [ ] Indexes on search columns
+- [ ] Response/distributed caching with invalidation
+- [ ] All I/O operations are async (no `.Result` / `.Wait()`)
+
+### Frontend (Blazor)
+- [ ] Lazy loading, virtualization for large lists
+- [ ] Debounce search inputs
+- [ ] `@key` in loops, `ShouldRender()` for perf
+
+### Infrastructure
+- [ ] CDN for static assets, gzip/brotli compression
+- [ ] Connection pooling, scale-to-zero
+
+---
+
+## Accessibility (WCAG 2.1)
+
+- [ ] Alt text on images, captions on videos
+- [ ] Contrast >= 4.5:1 (AA), color not sole indicator
+- [ ] Keyboard navigation works, focus visible
+- [ ] Skip links, `<html lang="pt-BR">`
+- [ ] Labels on all inputs, clear error messages
+- [ ] Valid HTML, ARIA used correctly
+
+---
+
+## Legal Brazil (LGPD)
+
+### Documentation
+- [ ] Privacy policy (data collected, purpose, legal basis, DPO contact)
+- [ ] Terms of use (service description, responsibilities, forum)
+
+### Consent & Rights
+- [ ] Cookie banner with granular options
+- [ ] Explicit consent for marketing, revocation option
+- [ ] Data access, correction, deletion, portability
+
+### Technical
+- [ ] Data minimization, defined retention periods
+- [ ] Anonymization/pseudonymization where possible
+- [ ] Access logs for personal data
+- [ ] Incident response plan (ANPD notification in 72h)
+
+---
+
+*MORPH-SPEC Checklist Skill*

package/content/.claude/skills/checklists/simulation-checklist.md

@@ -0,0 +1,77 @@
+# Skill: /morph-checklist simulation
+
+> **Layer:** 2 | **Load:** on-keyword | **Keywords:** simulation, mock, fake, external service, sandbox
+
+Checklist for simulating external services (AI, payment, email APIs).
+
+## Pre-Implementation
+
+### 1. Map All Dependencies
+
+- [ ] List ALL interfaces in the flow (`grep -r "I{ServiceName}" src/ --include="*.cs" -l`)
+- [ ] Identify **transitive dependencies** (e.g., `ArtGenerationService` → `IReplicateClient` + `IImageDownloader`)
+- [ ] Document dependency trace: services to mock, transitive deps, required lifetimes
+
+### 2. Verify Lifetimes
+
+| State | Lifetime | Example |
+|-------|----------|---------|
+| Stateful (Dictionary, List) | **Singleton** | `FakeReplicateClient` with prediction store |
+| Stateless | **Scoped** | `FakeEmailClient` that only logs |
+
+```csharp
+// ❌ Stateful + Scoped = loses state between requests
+services.AddScoped<IReplicateClient, FakeReplicateClient>();
+// ✅ Stateful + Singleton
+services.AddSingleton<IReplicateClient, FakeReplicateClient>();
+```
+
+### 3. Read Complete Interfaces
+
+- [ ] Check full signatures — don't miss optional parameters (`attachments`, `CancellationToken`)
+- [ ] For AI mocks: verify current prompts, model in use, response format
+- [ ] For email mocks: check for attachments/inline images, log simulated sends
+- [ ] For payment mocks: implement state transitions (PENDING → CONFIRMED → REFUNDED), simulate webhooks
+
+## Configuration Template
+
+```json
+// appsettings.Development.json
+{ "Simulation": { "Enabled": true, "ImageDelayMs": 500, "PlaceholderImageUrl": "https://picsum.photos/1024/1024" } }
+```
+
+```csharp
+if (configuration.GetValue<bool>("Simulation:Enabled"))
+    services.AddSimulationClients(configuration);  // Stateful→Singleton, Stateless→Scoped
+else
+    services.AddProductionClients(configuration);
+```
+
+## Post-Implementation
+
+- [ ] Validate DI: `dotnet build && dotnet run` + health check
+- [ ] Test full flow end-to-end (not just unit tests)
+- [ ] Verify simulation logs — confirm mocks are being called
+
+## Common Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| Mock loses state between requests | Scoped lifetime for stateful service | Change to Singleton |
+| `Unable to resolve service` at runtime | Transitive dependency not registered | Map ALL dependencies |
+| Incorrect method signature | Didn't read full interface | Check optional params |
+| Mock returns wrong data | Prompts/model changed | Read current prompts |
+| Works in test, fails at runtime | Test doesn't cover full DI | Test with `dotnet run` |
+
+## Checklist
+
+- [ ] All interfaces mapped (including transitive)
+- [ ] Lifetimes correct (stateful=Singleton, stateless=Scoped)
+- [ ] Complete interface signatures implemented
+- [ ] Simulation toggle via config
+- [ ] End-to-end flow tested in simulation mode
+- [ ] No real API calls in simulation mode
+
+---
+
+*MORPH-SPEC Simulation Checklist*