@polymorphism-tech/morph-spec 4.21.0 → 5.0.1

package/framework/skills/level-1-workflows/morph-phase-tasks/references/tasks-example.md

@@ -1,404 +0,0 @@
-# Tasks - Photo Processing Pipeline
-
-> Example of a well-structured tasks.md. This is a filled-in reference — not a template.
-> All tasks are atomic (15–60 min), independently commitable, and directly traceable to spec.md.
-
-| Task ID | Type | Title | Status |
-|---------|------|-------|--------|
-| T001 | Contract | Define C# contracts and interfaces | Done |
-| T002 | Domain | Create ProcessingJob entity and enum | Done |
-| T003 | Infra | EF Core migration and DbContext setup | Done |
-| T004 | Infra | Azure Blob Storage service | Done |
-| T005 | Service | Implement PhotoProcessingService | In Progress |
-| T006 | Job | Implement Hangfire background job | Pending |
-| T007 | API | Upload and status endpoints (Minimal API) | Pending |
-| T008 | UI | Blazor upload page component | Pending |
-| T009 | UI | Blazor status polling page | Pending |
-| T010 | Test | Unit tests for PhotoProcessingService | Pending |
-| T011 | Test | Integration tests for upload + status API | Pending |
-
-**Status Values:** `Pending | In Progress | Blocked | Done`
-
----
-
-## Phase 1: Contracts & Data Model
-
-### T001: Define C# contracts and interfaces
-- **Type:** Contract
-- **Priority:** 1
-- **Estimate:** 30min
-- **Assigned:** dotnet-senior
-- **Dependencies:** None
-
-**Description:**
-Define all service interfaces, command/result records, and DTOs needed for the feature. These become the API contract other tasks depend on — implement data model and services against these interfaces.
-
-**Deliverables:**
-- [ ] Create: `src/Application/PhotoProcessing/Interfaces/IPhotoProcessingService.cs`
-- [ ] Create: `src/Application/PhotoProcessing/Commands/UploadPhotoCommand.cs`
-- [ ] Create: `src/Application/PhotoProcessing/Queries/GetJobStatusQuery.cs`
-- [ ] Create: `src/Application/PhotoProcessing/DTOs/JobStatusDto.cs`
-
----
-
-### T002: Create ProcessingJob entity and enum
-- **Type:** Domain
-- **Priority:** 1
-- **Estimate:** 30min
-- **Assigned:** dotnet-senior
-- **Dependencies:** T001
-
-**Description:**
-Create the `ProcessingJob` domain entity and `ProcessingStatus` enum per the data model in spec.md. Entity must use private setters and expose domain methods for state transitions (`MarkProcessing()`, `MarkCompleted()`, `MarkFailed()`).
-
-**Deliverables:**
-- [ ] Create: `src/Domain/Entities/ProcessingJob.cs`
-- [ ] Create: `src/Domain/Enums/ProcessingStatus.cs`
-
----
-
-### T003: EF Core migration and DbContext setup
-- **Type:** Infrastructure
-- **Priority:** 1
-- **Estimate:** 45min
-- **Assigned:** dotnet-senior
-- **Dependencies:** T002
-
-**Description:**
-Add `ProcessingJob` to `AppDbContext`, configure via Fluent API (column lengths, indexes, defaults), and create initial migration. Verify migration applies cleanly to a local SQL Server instance.
-
-**Deliverables:**
-- [ ] Update: `src/Infrastructure/Persistence/AppDbContext.cs`
-- [ ] Create: `src/Infrastructure/Persistence/Configurations/ProcessingJobConfiguration.cs`
-- [ ] Run: `dotnet ef migrations add AddProcessingJob`
-- [ ] Verify: migration applies without errors
-
----
-
-## Phase 2: Infrastructure Services
-
-### T004: Azure Blob Storage service
-- **Type:** Infrastructure
-- **Priority:** 1
-- **Estimate:** 45min
-- **Assigned:** infra-architect
-- **Dependencies:** None
-
-**Description:**
-Implement `IBlobStorageService` with upload and generate-URL operations using `Azure.Storage.Blobs` SDK. Register as scoped in DI. Add connection string to `appsettings.json` (placeholder) and Key Vault reference for production.
-
-**Deliverables:**
-- [ ] Create: `src/Infrastructure/Storage/IBlobStorageService.cs`
-- [ ] Create: `src/Infrastructure/Storage/AzureBlobStorageService.cs`
-- [ ] Create: `src/Infrastructure/Storage/FakeBlobStorageService.cs` (for simulation mode)
-- [ ] Update: `src/Infrastructure/DependencyInjection.cs`
-
----
-
-### T005: Implement PhotoProcessingService
-- **Type:** Service
-- **Priority:** 2
-- **Estimate:** 1h
-- **Assigned:** dotnet-senior
-- **Dependencies:** T001, T002, T003, T004
-
-**Description:**
-Implement `IPhotoProcessingService` with `UploadAsync` (validate → blob upload → create job → enqueue Hangfire job) and `GetStatusAsync`. Use result pattern for validation errors; throw `NotFoundException` for missing jobs.
-
-**Deliverables:**
-- [ ] Create: `src/Application/PhotoProcessing/PhotoProcessingService.cs`
-- [ ] Update: `src/Application/DependencyInjection.cs`
-
----
-
-### T006: Implement Hangfire background job
-- **Type:** Job
-- **Priority:** 2
-- **Estimate:** 1h
-- **Assigned:** dotnet-senior
-- **Dependencies:** T002, T004
-
-**Description:**
-Implement `IPhotoProcessingJob` that: sets status = Processing → downloads original from Blob → calls AI API → uploads processed photo → sets status = Completed. On exception: increment RetryCount, set Failed if >= 3. Add `[AutomaticRetry(Attempts = 3)]` attribute.
-
-**Deliverables:**
-- [ ] Create: `src/Application/PhotoProcessing/PhotoProcessingJob.cs`
-- [ ] Create: `src/Application/PhotoProcessing/FakePhotoProcessingJob.cs` (simulation mode)
-
----
-
-## Phase 3: API Endpoints
-
-### T007: Upload and status endpoints (Minimal API)
-- **Type:** API
-- **Priority:** 2
-- **Estimate:** 45min
-- **Assigned:** dotnet-senior
-- **Dependencies:** T005
-
-**Description:**
-Create two endpoints per spec.md:
-- `POST /api/upload` — multipart/form-data, returns `{ jobId }`, maps to `UploadPhotoCommand`
-- `GET /api/status/{jobId}` — returns `JobStatusDto`
-- `GET /api/download/{jobId}` — redirects to Blob URL if Completed, else 404
-
-**Deliverables:**
-- [ ] Create: `src/Web/Endpoints/PhotoProcessingEndpoints.cs`
-- [ ] Update: `src/Web/Program.cs` to register endpoint group
-
----
-
-## Phase 4: UI Components
-
-### T008: Blazor upload page component
-- **Type:** UI
-- **Priority:** 2
-- **Estimate:** 1h
-- **Assigned:** nextjs-expert
-- **Dependencies:** T007
-
-**Description:**
-Frontend page at `/upload`. File input with client-side validation (type + size before submit). Loading state during upload. Redirect to `/processing/{jobId}` on success. Error message display per spec wireframe.
-
-**Deliverables:**
-- [ ] Create: `src/Web/Pages/Upload.razor`
-- [ ] Create: `src/Web/Pages/Upload.razor.cs`
-
----
-
-### T009: Blazor status polling page
-- **Type:** UI
-- **Priority:** 3
-- **Estimate:** 1h
-- **Assigned:** nextjs-expert
-- **Dependencies:** T007
-
-**Description:**
-Frontend page at `/processing/{jobId}`. Polls `GET /api/status/{jobId}` every 5 seconds using `PeriodicTimer`. Shows status label + progress indicator. "Download" button when Completed. "Retry" suggestion when Failed. Stops polling on terminal state.
-
-**Deliverables:**
-- [ ] Create: `src/Web/Pages/ProcessingStatus.razor`
-- [ ] Create: `src/Web/Pages/ProcessingStatus.razor.cs`
-
----
-
-## Phase 5: Tests
-
-### T010: Unit tests for PhotoProcessingService
-- **Type:** Test
-- **Priority:** 2
-- **Estimate:** 1h
-- **Assigned:** dotnet-senior
-- **Dependencies:** T005
-
-**Description:**
-Unit tests covering: happy path upload, invalid file type rejection, file too large rejection, status retrieval for each status value, not-found case. Use Moq for `IBlobStorageService` and `IProcessingJobRepository`. FluentAssertions for assertions.
-
-**Deliverables:**
-- [ ] Create: `tests/Unit/Application/PhotoProcessing/PhotoProcessingServiceTests.cs`
-
----
-
-### T011: Integration tests for upload + status API
-- **Type:** Test
-- **Priority:** 3
-- **Estimate:** 1h
-- **Assigned:** dotnet-senior
-- **Dependencies:** T007, T010
-
-**Description:**
-Integration tests using `WebApplicationFactory` + in-memory SQLite (or TestContainers for SQL Server). Tests: POST /api/upload returns 200 with jobId, GET /api/status/{jobId} returns correct status, GET /api/download/{completedJobId} returns redirect.
-
-**Deliverables:**
-- [ ] Create: `tests/Integration/Api/PhotoProcessingEndpointTests.cs`
-- [ ] Create: `tests/Integration/Fixtures/PhotoProcessingApiFixture.cs`
-
----
-
-## Summary
-
-| Phase | Tasks | Estimate |
-|-------|-------|----------|
-| Contracts & Data Model | T001–T003 | 1h45m |
-| Infrastructure Services | T004–T006 | 2h45m |
-| API Endpoints | T007 | 45m |
-| UI Components | T008–T009 | 2h |
-| Tests | T010–T011 | 2h |
-| **Total** | **11 tasks** | **~9h15m** |
-
----
-
----
-
-# Tasks - Book CRUD (VSA Example)
-
-> Example of tasks.md for a Vertical Slice Architecture (VSA) feature.
-> Key rule: 1 task = 1 complete slice (Handler + Validator + Endpoint together).
-> GetAll slices have no Validator — stated explicitly in the task.
-
-| Task ID | Category | Title | Status |
-|---------|----------|-------|--------|
-| T001 | entity | Criar Entity Book + registrar DbSet no ApplicationDbContext | Pending |
-| T002 | errors | Criar BookErrors (NotFound + outros factory methods) | Pending |
-| T003 | tags | Adicionar ApiTags.Books em Constants/ApiTags.cs | Pending |
-| T004 | migration | Criar migration AddBook + aplicar ao banco | Pending |
-| T005 | slice | Implementar slice CreateBook (Handler + Validator + Endpoint) | Pending |
-| T006 | slice | Implementar slice GetAllBooks (Handler + Endpoint, sem Validator) | Pending |
-| T007 | slice | Implementar slice GetBookById (Handler + Validator + Endpoint) | Pending |
-| T008 | slice | Implementar slice UpdateBook (Handler + Validator + Endpoint) | Pending |
-| T009 | slice | Implementar slice DeleteBook (Handler + Validator + Endpoint) | Pending |
-
-**Status Values:** `Pending | In Progress | Blocked | Done`
-
----
-
-## Phase 1: Foundation
-
-### T001: Criar Entity Book + registrar DbSet no ApplicationDbContext
-- **Category:** entity
-- **Estimate:** 20min
-- **Dependencies:** None
-
-**Description:**
-Criar a entity `Book` com todos os campos definidos no spec.md. Registrar `DbSet<Book>` no `ApplicationDbContext`. Usar `Guid.CreateVersion7()` para o campo Id — não `Guid.NewGuid()`. Propriedades obrigatórias como `sealed` ou com setters `private init`.
-
-**Deliverables:**
-- [ ] Create: `Entities/Book.cs`
-- [ ] Update: `Database/ApplicationDbContext.cs` (add `public DbSet<Book> Books { get; set; } = null!;`)
-
----
-
-### T002: Criar BookErrors (NotFound + outros factory methods)
-- **Category:** errors
-- **Estimate:** 10min
-- **Dependencies:** T001
-
-**Description:**
-Criar a classe `BookErrors` static com factory methods para cada tipo de erro da feature. Cada method retorna um `Error` com code e description. Esses erros são compartilhados por todos os slices da BookFeature.
-
-**Deliverables:**
-- [ ] Create: `Features/BookFeature/BookErrors.cs`
-
----
-
-### T003: Adicionar ApiTags.Books em Constants/ApiTags.cs
-- **Category:** tags
-- **Estimate:** 5min
-- **Dependencies:** None
-
-**Description:**
-Adicionar a constante `Books` em `ApiTags` para uso em todos os endpoints da feature. Se a constante já existir, pular esta task.
-
-**Deliverables:**
-- [ ] Update: `Constants/ApiTags.cs` (add `public const string Books = "books";`)
-
----
-
-### T004: Criar migration AddBook + aplicar ao banco
-- **Category:** migration
-- **Estimate:** 10min
-- **Dependencies:** T001
-
-**Description:**
-Gerar a migration EF Core para a entity `Book` e aplicar ao banco local. Verificar que a migration foi gerada corretamente antes de aplicar.
-
-**Deliverables:**
-- [ ] Run: `dotnet ef migrations add AddBook`
-- [ ] Run: `dotnet ef database update`
-- [ ] Verify: migration applies without errors
-
----
-
-## Phase 2: Slices
-
-### T005: Implementar slice CreateBook (Handler + Validator + Endpoint)
-- **Category:** slice
-- **Estimate:** 45min
-- **Dependencies:** T001, T002, T003, T004
-
-**Description:**
-Implementar o slice completo de criação. O arquivo Handler deve conter os records `CreateBookRequest` e `CreateBookResponse` no mesmo arquivo. O Validator deve herdar de `AbstractValidator<CreateBookRequest>`. O Endpoint deve ser `internal sealed` e usar `result.Match()` — nunca `result.Value` sem checar `IsSuccess`.
-
-Handler injeta: `IRepository<Book>` + `IUnitOfWork`.
-
-**Deliverables:**
-- [ ] Create: `Features/BookFeature/CreateBook/CreateBookHandler.cs`
-- [ ] Create: `Features/BookFeature/CreateBook/CreateBookValidator.cs`
-- [ ] Create: `Features/BookFeature/CreateBook/CreateBookEndpoint.cs`
-
----
-
-### T006: Implementar slice GetAllBooks (Handler + Endpoint, sem Validator)
-- **Category:** slice
-- **Estimate:** 25min
-- **Dependencies:** T001, T004
-
-**Description:**
-Implementar o slice de listagem. GetAll NÃO tem Validator (sem parâmetros de entrada para validar). Handler injeta apenas `IRepository<Book>` — não precisa de `IUnitOfWork` (read-only).
-
-**Deliverables:**
-- [ ] Create: `Features/BookFeature/GetAllBooks/GetAllBooksHandler.cs`
-- [ ] Create: `Features/BookFeature/GetAllBooks/GetAllBooksEndpoint.cs`
-
----
-
-### T007: Implementar slice GetBookById (Handler + Validator + Endpoint)
-- **Category:** slice
-- **Estimate:** 30min
-- **Dependencies:** T001, T002, T004
-
-**Description:**
-Implementar o slice de busca por ID. Validator verifica que o Guid não é empty. Handler retorna `BookErrors.NotFound()` se o livro não existir. Handler injeta apenas `IRepository<Book>`.
-
-**Deliverables:**
-- [ ] Create: `Features/BookFeature/GetBookById/GetBookByIdHandler.cs`
-- [ ] Create: `Features/BookFeature/GetBookById/GetBookByIdValidator.cs`
-- [ ] Create: `Features/BookFeature/GetBookById/GetBookByIdEndpoint.cs`
-
----
-
-### T008: Implementar slice UpdateBook (Handler + Validator + Endpoint)
-- **Category:** slice
-- **Estimate:** 45min
-- **Dependencies:** T001, T002, T003, T004
-
-**Description:**
-Implementar o slice de atualização. Handler retorna `BookErrors.NotFound()` se o livro não existir antes de atualizar. Handler injeta: `IRepository<Book>` + `IUnitOfWork`.
-
-**Deliverables:**
-- [ ] Create: `Features/BookFeature/UpdateBook/UpdateBookHandler.cs`
-- [ ] Create: `Features/BookFeature/UpdateBook/UpdateBookValidator.cs`
-- [ ] Create: `Features/BookFeature/UpdateBook/UpdateBookEndpoint.cs`
-
----
-
-### T009: Implementar slice DeleteBook (Handler + Validator + Endpoint)
-- **Category:** slice
-- **Estimate:** 30min
-- **Dependencies:** T001, T002, T003, T004
-
-**Description:**
-Implementar o slice de deleção. Handler verifica existência antes de deletar, retorna `BookErrors.NotFound()` se não existir. Handler injeta: `IRepository<Book>` + `IUnitOfWork`.
-
-**Deliverables:**
-- [ ] Create: `Features/BookFeature/DeleteBook/DeleteBookHandler.cs`
-- [ ] Create: `Features/BookFeature/DeleteBook/DeleteBookValidator.cs`
-- [ ] Create: `Features/BookFeature/DeleteBook/DeleteBookEndpoint.cs`
-
----
-
-## Summary
-
-| Phase | Tasks | Estimate |
-|-------|-------|----------|
-| Foundation (entity + errors + tags + migration) | T001–T004 | 45min |
-| Slices (Create + GetAll + GetById + Update + Delete) | T005–T009 | 2h55m |
-| **Total** | **9 tasks** | **~3h40m** |
-
-> **VSA Note:** No manual DI registration needed — `AddHandlersFromAssembly()`,
-> `RegisterApiEndpointsFromAssembly()`, and `AddValidatorsFromAssembly()` discover
-> all handlers, endpoints and validators automatically via assembly scanning (Scrutor).
-
----
-
-*MORPH-SPEC by Polymorphism Tech*

package/framework/skills/level-1-workflows/morph-phase-tasks/scripts/validate-tasks.mjs

@@ -1,112 +0,0 @@
-#!/usr/bin/env node
-/**
- * validate-tasks.mjs
- *
- * Validates a MORPH-SPEC tasks.md file for structure and completeness.
- * Executed locally by Claude via Bash — output returned to Claude.
- *
- * Usage:
- *   node validate-tasks.mjs <tasks-file>
- *   node validate-tasks.mjs .morph/features/my-feature/4-tasks/tasks.md
- *
- * Checks:
- *   - Summary table exists with T### IDs and valid statuses
- *   - Each task header has T### format
- *   - Each task has Type, Priority, Estimate, Dependencies fields
- *   - Each task has at least one deliverable checkbox
- *   - Task IDs are sequential (no gaps)
- *   - Reports counts by status
- */
-
-import { readFileSync, existsSync } from 'fs';
-
-const taskFile = process.argv[2];
-
-if (!taskFile) {
-  console.error(JSON.stringify({ error: 'Usage: validate-tasks.mjs <tasks-file>' }));
-  process.exit(1);
-}
-
-if (!existsSync(taskFile)) {
-  console.error(JSON.stringify({ error: `File not found: ${taskFile}` }));
-  process.exit(1);
-}
-
-const content = readFileSync(taskFile, 'utf-8');
-const lines = content.split('\n');
-
-const errors = [];
-const warnings = [];
-
-// 1. Parse summary table (| T001 | Type | Title | Status |)
-const tableRows = lines.filter(l => /^\|\s*T\d{3}/.test(l));
-const VALID_STATUSES = new Set(['Pending', 'In Progress', 'Blocked', 'Done']);
-const summaryTasks = [];
-
-for (const row of tableRows) {
-  const parts = row.split('|').map(s => s.trim()).filter(Boolean);
-  if (parts.length < 4) continue;
-  const [id, , , status] = parts;
-  summaryTasks.push({ id, status });
-  if (!VALID_STATUSES.has(status)) {
-    errors.push(`Task ${id}: invalid status '${status}' — must be one of: ${[...VALID_STATUSES].join(', ')}`);
-  }
-}
-
-if (summaryTasks.length === 0) {
-  errors.push('No summary table found — expected rows matching | T### | Type | Title | Status |');
-}
-
-// 2. Parse task headers (### T001: Title  or  ### T001 — Title  or  ### T001 - Title)
-const taskHeaders = lines
-  .map((l, i) => ({ line: i + 1, match: l.match(/^###\s+(T\d{3})\s*[—–:\-]\s+(.+)/) }))
-  .filter(r => r.match);
-
-// Check sequential IDs
-const ids = taskHeaders.map(r => parseInt(r.match[1].slice(1)));
-for (let i = 0; i < ids.length; i++) {
-  if (ids[i] !== i + 1) {
-    warnings.push(`Task ID gap or duplicate near T${String(ids[i]).padStart(3, '0')} (expected T${String(i + 1).padStart(3, '0')})`);
-    break;
-  }
-}
-
-// 3. Check each task section has required fields
-for (const { line, match } of taskHeaders) {
-  const taskId = match[1];
-  // Collect lines in this task section (until next ### or end)
-  const start = line; // 1-indexed
-  let end = lines.length;
-  for (let i = start; i < lines.length; i++) {
-    if (i > start - 1 && /^#{1,3}\s/.test(lines[i])) { end = i; break; }
-  }
-  const section = lines.slice(start, end).join('\n');
-
-  if (!/\*\*Type:\*\*/.test(section))       errors.push(`${taskId}: missing **Type:** field`);
-  if (!/\*\*Priority:\*\*/.test(section))   errors.push(`${taskId}: missing **Priority:** field`);
-  if (!/\*\*Estimate:\*\*/.test(section))   errors.push(`${taskId}: missing **Estimate:** field`);
-  if (!/\*\*Dependencies:\*\*/.test(section)) warnings.push(`${taskId}: missing **Dependencies:** field`);
-  if (!/- \[ \]/.test(section))             warnings.push(`${taskId}: no deliverable checkboxes found`);
-}
-
-// 4. Status counts
-const statusCounts = {};
-for (const { status } of summaryTasks) {
-  statusCounts[status] = (statusCounts[status] ?? 0) + 1;
-}
-
-const result = {
-  file: taskFile,
-  valid: errors.length === 0,
-  tasks: {
-    total: summaryTasks.length,
-    byStatus: statusCounts,
-    completed: statusCounts['Done'] ?? 0,
-    remaining: (summaryTasks.length) - (statusCounts['Done'] ?? 0),
-  },
-  errors,
-  warnings,
-};
-
-console.log(JSON.stringify(result, null, 2));
-process.exit(errors.length > 0 ? 1 : 0);