@polymorphism-tech/morph-spec 4.21.0 → 5.0.1

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

@@ -1,132 +0,0 @@
-# Feature Recap: Photo Processing Pipeline
-
-> Example of a well-structured recap.md. Filled-in reference — not a template.
-
-## Summary
-
-| Field | Value |
-|-------|-------|
-| **Feature ID** | photo-processing |
-| **Completed** | 2025-01-22 |
-| **Total Tasks** | 11 / 11 |
-| **Time Spent** | ~9h |
-| **Agents Used** | dotnet-senior, nextjs-expert, infra-architect |
-| **Stack** | blazor-azure |
-
----
-
-## Tasks Completed
-
-| ID | Title | Category | Duration |
-|----|-------|----------|----------|
-| T001 | Define C# contracts and interfaces | Contract | 25min |
-| T002 | Create ProcessingJob entity and enum | Domain | 30min |
-| T003 | EF Core migration and DbContext setup | Infrastructure | 50min |
-| T004 | Azure Blob Storage service | Infrastructure | 45min |
-| T005 | Implement PhotoProcessingService | Service | 65min |
-| T006 | Implement Hangfire background job | Job | 70min |
-| T007 | Upload and status endpoints | API | 40min |
-| T008 | Blazor upload page component | UI | 60min |
-| T009 | Blazor status polling page | UI | 65min |
-| T010 | Unit tests for PhotoProcessingService | Test | 55min |
-| T011 | Integration tests for upload + status API | Test | 70min |
-
----
-
-## What Was Delivered
-
-### Functionality
-- Photo upload via Blazor form (10MB limit, .jpg/.png only)
-- Azure Blob Storage integration with `uploads/{jobId}/original.jpg` path structure
-- Hangfire background job with 3-retry exponential backoff (5s/30s/120s)
-- Real-time status polling page (5s interval, stops on terminal state)
-- Download redirect for completed jobs
-
-### Backend (.NET)
-- Endpoints: `POST /api/upload`, `GET /api/status/{id}`, `GET /api/download/{id}`
-- Services: `PhotoProcessingService`, `PhotoProcessingJob`
-- Simulation: `FakeBlobStorageService`, `FakePhotoProcessingJob` for dev mode
-
-### Frontend (Blazor)
-- Pages: `Upload.razor`, `ProcessingStatus.razor`
-- Polling via `PeriodicTimer` — no SignalR dependency
-
----
-
-## Files Created
-
-```
-src/Domain/Entities/ProcessingJob.cs
-src/Domain/Enums/ProcessingStatus.cs
-src/Application/PhotoProcessing/Interfaces/IPhotoProcessingService.cs
-src/Application/PhotoProcessing/Commands/UploadPhotoCommand.cs
-src/Application/PhotoProcessing/Queries/GetJobStatusQuery.cs
-src/Application/PhotoProcessing/DTOs/JobStatusDto.cs
-src/Application/PhotoProcessing/PhotoProcessingService.cs
-src/Application/PhotoProcessing/PhotoProcessingJob.cs
-src/Application/PhotoProcessing/FakePhotoProcessingJob.cs
-src/Infrastructure/Storage/IBlobStorageService.cs
-src/Infrastructure/Storage/AzureBlobStorageService.cs
-src/Infrastructure/Storage/FakeBlobStorageService.cs
-src/Infrastructure/Persistence/Configurations/ProcessingJobConfiguration.cs
-src/Web/Endpoints/PhotoProcessingEndpoints.cs
-src/Web/Pages/Upload.razor + .cs
-src/Web/Pages/ProcessingStatus.razor + .cs
-tests/Unit/Application/PhotoProcessing/PhotoProcessingServiceTests.cs
-tests/Integration/Api/PhotoProcessingEndpointTests.cs
-tests/Integration/Fixtures/PhotoProcessingApiFixture.cs
-```
-
-## Files Modified
-
-```
-src/Infrastructure/Persistence/AppDbContext.cs
-src/Infrastructure/DependencyInjection.cs
-src/Application/DependencyInjection.cs
-src/Web/Program.cs
-```
-
----
-
-## Architecture Decisions
-
-| Decision | Rationale |
-|----------|-----------|
-| PeriodicTimer for polling (not SignalR) | Simpler, no hub overhead, sufficient at MVP scale |
-| FakeBlobStorageService as Singleton | Stores in-memory dict; Scoped would lose state between requests |
-| Hangfire RetryCount on entity (not Hangfire built-in) | Domain owns retry state; allows custom error messages per attempt |
-
-See full ADRs in `decisions.md`
-
----
-
-## Test Coverage
-
-| Type | Files | Notes |
-|------|-------|-------|
-| Unit | `PhotoProcessingServiceTests.cs` | Happy path, invalid type, size limit, 404, all statuses |
-| Integration | `PhotoProcessingEndpointTests.cs` | POST /upload, GET /status, GET /download (completed + pending) |
-
----
-
-## Issues Encountered
-
-| Issue | Resolution |
-|-------|-----------|
-| `FakeBlobStorageService` registered as `Scoped` — lost uploads between requests | Changed to `Singleton` per simulation-checklist.md |
-| `PeriodicTimer` not stopping on component dispose | Added `CancellationTokenSource` + dispose pattern in `ProcessingStatus.razor.cs` |
-
----
-
-## Metrics
-
-| Metric | Value |
-|--------|-------|
-| Tasks Completed | 11 / 11 |
-| Checkpoints Passed | 3 (after T003, T006, T009) |
-| Bugs Found | 2 |
-| Bugs Fixed | 2 |
-
----
-
-*MORPH-SPEC by Polymorphism Tech*

package/framework/skills/level-1-workflows/morph-phase-implement/references/vsa-implementation-guide.md

@@ -1,92 +0,0 @@
-# VSA Implementation Guide
-
-> Guia completo de implementação para Vertical Slice Architecture.
-> Referenciado pelo Passo 1.5 de `phase-implement/SKILL.md`.
-> **Ref:** `framework/standards/architecture/vertical-slice/vertical-slice.md`
-
----
-
-## Estrutura de Arquivos Obrigatória por Slice
-
-```
-Features/
-└── {Entity}Feature/
-    ├── {Entity}Errors.cs                        ← 1 arquivo por feature (compartilhado)
-    ├── Create{Entity}/
-    │   ├── Create{Entity}Handler.cs             ← Request + Response records + Handler
-    │   ├── Create{Entity}Validator.cs           ← AbstractValidator<Request>
-    │   └── Create{Entity}Endpoint.cs           ← IApiEndpoint (internal sealed)
-    ├── GetAll{Entity}s/
-    │   ├── GetAll{Entity}sHandler.cs           ← sem Validator (sem parâmetros)
-    │   └── GetAll{Entity}sEndpoint.cs
-    ├── Get{Entity}ById/
-    │   ├── Get{Entity}ByIdHandler.cs
-    │   ├── Get{Entity}ByIdValidator.cs
-    │   └── Get{Entity}ByIdEndpoint.cs
-    ├── Update{Entity}/
-    │   ├── Update{Entity}Handler.cs
-    │   ├── Update{Entity}Validator.cs
-    │   └── Update{Entity}Endpoint.cs
-    └── Delete{Entity}/
-        ├── Delete{Entity}Handler.cs
-        ├── Delete{Entity}Validator.cs
-        └── Delete{Entity}Endpoint.cs
-```
-
----
-
-## 9 Regras Obrigatórias por Slice
-
-1. `Request` e `Response` records ficam no **mesmo arquivo** que o `Handler`
-2. Tudo `sealed` — handlers, endpoints, validators, records
-3. `Guid.CreateVersion7()` para gerar IDs (não `Guid.NewGuid()`)
-4. Endpoints usam `result.Match(onSuccess, onFailure)` — nunca acesse `result.Value` sem checar `IsSuccess`
-5. Endpoints são `internal sealed` (não public)
-6. `{Entity}Errors` é static e compartilhado entre todos os slices da feature
-7. Handlers de escrita (Create/Update/Delete) injetam `IRepository<T>` + `IUnitOfWork`
-8. Handlers de leitura (GetAll/GetById) injetam apenas `IRepository<T>`
-9. GetAll não tem Validator
-
----
-
-## Registrar Entidade no DbContext
-
-```csharp
-// Database/ApplicationDbContext.cs — adicionar:
-public DbSet<{Entity}> {Entities} { get; set; } = null!;
-```
-
----
-
-## Criar Migration Após DbContext Atualizado
-
-```bash
-dotnet ef migrations add Add{Entity}
-dotnet ef database update
-```
-
----
-
-## Registrar Tag em ApiTags (se necessário)
-
-```csharp
-// Constants/ApiTags.cs — adicionar:
-public const string {Entities} = "{entities}";
-```
-
----
-
-## O que NÃO Precisa Fazer (auto-discovery via reflection)
-
-- ❌ Registrar handler manualmente no Program.cs — `AddHandlersFromAssembly()` faz isso
-- ❌ Registrar endpoint manualmente — `RegisterApiEndpointsFromAssembly()` faz isso
-- ❌ Registrar validator manualmente — `AddValidatorsFromAssembly()` faz isso
-- ❌ Criar Application Service layer — handler acessa IRepository diretamente
-
----
-
-## Verificar Build Após Cada Slice
-
-```bash
-dotnet build
-```

package/framework/skills/level-1-workflows/morph-phase-plan/SKILL.md

@@ -1,257 +0,0 @@
----
-name: morph-phase-plan
-description: MORPH-SPEC Phase 3 (Plan). Generates a detailed implementation plan with exact file paths, TDD code blocks, and execution strategy analysis. Produces plan.md in 3-plan/. Use after design phase to create an actionable implementation plan before task breakdown.
-argument-hint: "[feature-name]"
-user-invocable: false
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
-cliVersion: "4.21.0"
----
-
-# MORPH Plan — Phase 3
-
-> INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
-
-Generate a detailed implementation plan with exact paths, TDD code, and execution strategy.
-
-## Prerequisites
-
-- [ ] Phase 2 (Design) completed and approved
-- [ ] `spec.md` defined
-- [ ] `contracts.cs` or `contracts.ts` defined
-
-## Recommended Tools
-
-> **Ref:** `framework/skills/level-0-meta/morph-tool-usage-guide/SKILL.md` for complete guide.
-
-| Action | Tool | Alternative |
-|--------|------|-------------|
-| Read spec + contracts + decisions | **Read** all outputs | — |
-| Analyze existing codebase | **Glob** + **Grep** patterns | — |
-| Look up library docs | **Context7 MCP** `query_docs()` | **WebSearch** |
-| Dispatch agents for analysis | **Bash** `morph-spec dispatch-agents $ARGUMENTS plan` | — |
-| Update state | **Bash** `morph-spec state mark-output $ARGUMENTS plan` | — |
-
-**Anti-patterns:**
-- Generating plan without reading contracts (contracts are the source of truth!)
-- Generic paths ("add the file") — always use exact paths
-- Incomplete code in plan ("add validation") — always include complete code
-- Skipping existing codebase analysis (existing patterns guide the plan)
-- Ignoring `config.architecture.style` — VSA and standard architectures have different structures
-
----
-
-## Pre-flight
-
-### 0. Ensure plan phase
-
-```bash
-morph-spec state get $ARGUMENTS
-```
-
-Check the `"phase"` field:
-- `"phase": "plan"` → correct phase, proceed
-- any other value → run `morph-spec phase advance $ARGUMENTS` and re-check
-
-> **Rule:** Never write to `3-plan/` until the phase is `plan`.
-
-## MANDATORY: Session Tasks
-
-> **BEFORE reading any files**, analyze the planning workflow and create session tasks.
->
-> **Rules:** Minimum 2 tasks, typically 3-5. Mark `in_progress` before starting, `completed` after.
->
-> **Typical tasks:** feature analysis, execution strategy, plan.md generation, plan approval
-
-### 1. Read all prerequisites in PARALLEL
-
-```
-Read: .morph/features/{feature}/2-design/spec.md
-    + Read: .morph/features/{feature}/2-design/contracts.cs  (or contracts.ts)
-    + Read: .morph/features/{feature}/2-design/decisions.md
-    + Read: .morph/features/{feature}/2-design/decisions.md
-    + Read: .morph/features/{feature}/2-design/schema-analysis.md  (if exists)
-    + Read: .morph/config/config.json
-```
-
----
-
-## Workflow
-
-### Step 1: Analyze Feature for Context
-
-1. **Scan existing codebase** — Glob to find files that will be modified/created
-2. **Identify patterns** — Grep for patterns similar to what will be implemented
-3. **Check library docs** — Context7 for dependency documentation
-4. **Detect architecture:**
-
-```bash
-cat .morph/config/config.json | grep -A3 '"architecture"'
-```
-
-| `config.architecture.style` value | Path structure |
-|------------------------------------|---------------|
-| `"vertical-slice"` | VSA: `Features/{Entity}Feature/{Operation}/` |
-| any other value | Standard layer-based |
-
-### Step 2: Determine Execution Strategy
-
-Run the dispatch analysis:
-
-```bash
-morph-spec dispatch-agents $ARGUMENTS plan
-```
-
-**Factors for recommendation:**
-
-| Factor | Calculation |
-|--------|-------------|
-| `taskCount` | Number of functional requirements + technical components in spec |
-| `domainCount` | Distinct domains in activeAgents (backend, frontend, infra) |
-| `agentCount` | Total activeAgents |
-| `independence` | % of tasks without cross-domain dependencies |
-
-**Decision:**
-
-| Scenario | Recommendation |
-|----------|----------------|
-| `taskCount < 8` AND `domainCount <= 2` | **Single session** — direct sequential implementation |
-| `taskCount 8-20` AND `domainCount 2-3` | **Subagent-Driven** — one subagent per task group |
-| `taskCount > 20` OR `domainCount > 3` | **Agent Teams** — multi-domain coordination |
-
-### Step 3: Generate `plan.md`
-
-Create `.morph/features/$ARGUMENTS/3-plan/plan.md` with this structure:
-
-```markdown
-# {Feature Name} Implementation Plan
-
-> **For Claude:** Use morph-phase-implement to execute this plan.
-
-**Goal:** {One sentence describing what will be built}
-
-**Architecture:** {2-3 sentences about the approach}
-
-**Tech Stack:** {Key technologies}
-
-**Execution Strategy:** {single | subagents | agent-teams} (Recommended)
-
----
-
-## GROUP {A} — {Group Name}
-
-{Pattern and context for the group}
-
-### {A1} — {Task Name} [FR001, FR003]
-
-**Spec refs:** FR001 (description), FR003 (description)
-**Contracts:** {RelevantRequest}, {RelevantResponse}, {ErrorType}
-
-**Files:**
-- Create: `exact/path/to/file.cs`
-- Modify: `exact/path/to/existing.cs:123-145`
-- Test: `tests/exact/path/to/test.cs`
-
-**Step 1: Write the failing test**
-
-(Complete test code)
-
-**Step 2: Run test to verify it fails**
-
-Run: `{exact command}`
-Expected: FAIL with "{message}"
-
-**Step 3: Write minimal implementation**
-
-(Complete implementation code)
-
-**Step 4: Run test to verify it passes**
-
-Run: `{exact command}`
-Expected: PASS
-
-**Step 5: Commit**
-
-git add {files}
-git commit -m "{message}"
-```
-
-**Mandatory rules:**
-- **FR cross-references in EVERY task** — each task MUST reference the spec FRs it implements (e.g., `[FR001, FR003]`). Extract FR IDs from spec.md and map them to task groups. Include `Spec refs:` and `Contracts:` fields.
-- Exact paths ALWAYS (never "add the file somewhere")
-- COMPLETE code in each step (never "add validation later" or "implement here")
-- Exact test commands with expected output (pass/fail message)
-- Each task follows the TDD 5-step cycle above — this is what makes the plan actionable
-- Keep each step to a 2-5 minute action
-
-### Step 4: Update State
-
-```bash
-morph-spec state mark-output $ARGUMENTS plan
-```
-
----
-
-## Mandatory Approval Pause
-
-Use `AskUserQuestion` to capture approval before advancing. This gate prevents task breakdown from starting with an unapproved plan.
-
-```json
-{
-  "questions": [
-    {
-      "header": "Approval",
-      "question": "Implementation plan generated. Approve to start task breakdown?",
-      "multiSelect": false,
-      "options": [
-        { "label": "Approve plan", "description": "Advance to task breakdown phase" },
-        { "label": "I have feedback", "description": "Type what you want to change" }
-      ]
-    },
-    {
-      "header": "Execution",
-      "question": "Which execution strategy for implementation?",
-      "multiSelect": false,
-      "options": [
-        { "label": "{Recommendation} (Recommended)", "description": "{Justification from Step 2 analysis}" },
-        { "label": "{Alternative 1}", "description": "{Description}" },
-        { "label": "{Alternative 2}", "description": "{Description}" }
-      ]
-    }
-  ]
-}
-```
-
-> The first "Execution" option should be the context-aware recommendation from Step 2. Alternatives are the other strategies.
-
-- **"Approve plan"** →
-  ```bash
-  morph-spec approve $ARGUMENTS plan
-  morph-spec phase advance $ARGUMENTS
-  ```
-- **"I have feedback" or "Other"** → apply the feedback and repeat this PAUSE
-
----
-
-## Phase Outputs
-
-<!-- morph-outputs:plan -->
-| Output | Path |
-|--------|------|
-| `plan` | `.morph/features/{feature}/3-plan/plan.md` |
-<!-- /morph-outputs -->
-
----
-
-## Advancement Criteria
-
-- [x] `plan.md` created with all groups and tasks
-- [x] Exact paths for all files
-- [x] Complete code in each step
-- [x] Test commands with expected output
-- [x] Execution strategy defined and approved
-- [x] State updated (`mark-output plan`)
-- [x] User approved plan via `AskUserQuestion`
-
----
-
-After approval: proceed automatically to Phase 5 (Tasks).

package/framework/skills/level-1-workflows/morph-phase-tasks/.morph/logs/activity.json

@@ -1,14 +0,0 @@
-{
-  "sessionId": "",
-  "feature": "",
-  "phase": "",
-  "hooks": [
-    {
-      "name": "set-terminal-title",
-      "event": "UserPromptSubmit",
-      "result": "failed",
-      "ts": "16:38:44"
-    }
-  ],
-  "skills": []
-}