@polymorphism-tech/morph-spec 4.3.7 → 4.6.0

package/framework/skills/level-1-workflows/{phase-clarify.md → phase-clarify/SKILL.md}

@@ -1,3 +1,11 @@
+---
+name: phase-clarify
+description: MORPH-SPEC Phase 3 (Clarify). Reviews spec.md for ambiguities, generates 3-7 targeted clarification questions, waits for user answers, then updates spec with edge cases and clarification sections. Use after design approval to eliminate spec ambiguities before task breakdown begins.
+argument-hint: "[feature-name]"
+user-invocable: false
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
 # MORPH Clarify - FASE 3
 
 > INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
@@ -10,11 +18,39 @@ Identifique ambiguidades na especificação e faça perguntas de clarificação
 - [ ] `spec.md` aprovado pelo usuário
 - [ ] `contracts.cs` definidos
 
+## Ferramentas Recomendadas
+
+> **Ref:** `framework/skills/level-0-meta/tool-usage-guide/SKILL.md` para guia completo.
+> **Ref:** `framework/standards/integration/mcp/mcp-tools.md` para referência MCP.
+> **Example:** `references/clarifications-example.md` — filled-in clarifications.md showing expected Q&A format.
+
+| Ação | Ferramenta | Alternativa |
+|------|------------|-------------|
+| Ler spec.md completo | **Read** spec.md | — |
+| Ler contracts.cs | **Read** contracts.cs | — |
+| Ler schema-analysis.md | **Read** schema-analysis.md | — |
+| Verificar viabilidade de requisito | **Context7 MCP** `query_docs()` | **WebSearch** + **WebFetch** |
+| Verificar issues/limitações conhecidas | **GitHub MCP** `search_issues()` | **Bash** `gh issue list --search "..."` |
+| Pesquisar edge cases externos | **WebSearch** | — |
+| Verificar comportamento UI existente | **Playwright MCP** `browser_navigate()` + `browser_snapshot()` | **WebFetch** URL |
+| Atualizar spec com clarificações | **Edit** spec.md | — |
+| Criar clarifications.md | **Bash** `npx morph-spec template render docs/clarifications ...` | — |
+| Atualizar state | **Bash** `npx morph-spec state mark-output ... clarifications` | — |
+
+**MCPs desta fase:** Context7 (validar viabilidade), GitHub (issues conhecidas), Playwright (verificar UI existente).
+
+**Anti-padrões:**
+- ❌ Task agent para ler spec (use Read direto)
+- ❌ Reescrever spec do zero (use Edit para atualizar seções)
+- ❌ Pular cross-reference com schema-analysis.md (crítico para precisão)
+
+---
+
 ## Workflow
 
 ### Passo 1: Analisar Spec
 
-Leia `.morph/project/outputs/{feature}/spec.md` em detalhes e identifique:
+Leia `.morph/features/$ARGUMENTS/1-design/spec.md` em detalhes e identifique:
 
 #### 1.1. Ambiguidades
 - Requisitos vagos ou genéricos
@@ -90,6 +126,21 @@ Após receber respostas do usuário, atualize o spec com:
 
 2. **Atualizar seções relevantes** com detalhes adicionados
 
+### CHECKPOINT: Validar Respostas Completas
+
+**⏸️ PAUSE - Antes de atualizar spec:**
+
+- [ ] Todas as perguntas foram respondidas pelo usuário?
+- [ ] Nenhuma resposta é ambígua ou contraditória?
+- [ ] Respostas são consistentes com `contracts.cs` existente?
+- [ ] Respostas são consistentes com `schema-analysis.md`?
+
+**❌ Se alguma checkbox NÃO estiver marcada:**
+→ Voltar e pedir esclarecimento adicional ao usuário
+
+**✅ Se TODAS as checkboxes estiverem marcadas:**
+→ Prosseguir para atualizar spec.md
+
 ### Passo 6: Validar Edge Cases
 
 Documente no spec como lidar com cada edge case identificado:
@@ -106,12 +157,12 @@ Documente no spec como lidar com cada edge case identificado:
 ### Passo 7: Atualizar State
 
 ```bash
-npx morph-spec state set {feature-name} phase clarify
+npx morph-spec state set $ARGUMENTS phase clarify
 ```
 
 ## Outputs Gerados/Atualizados
 
-- `.morph/project/outputs/{feature}/spec.md` - Atualizado com:
+- `.morph/features/$ARGUMENTS/1-design/spec.md` - Atualizado com:
   - Seção "Clarifications" com perguntas e respostas
   - Edge cases documentados
   - Requisitos mais específicos
@@ -128,4 +179,14 @@ npx morph-spec state set {feature-name} phase clarify
 
 ---
 
-Continuar automaticamente para FASE 4 (Tasks) após clarificações resolvidas.
+## Integração com Superpowers
+
+> Disponível quando o plugin `superpowers` está instalado.
+
+| Skill | Quando Usar | Invocação |
+|-------|-------------|-----------|
+| `systematic-debugging` | Para investigar ambiguidades técnicas complexas | `Skill(superpowers:systematic-debugging)` |
+
+---
+
+Continuar automaticamente para FASE 4 (Tasks) após clarificações resolvidas.

package/framework/skills/level-1-workflows/phase-clarify/references/clarifications-example.md

@@ -0,0 +1,117 @@
+# Clarifications - Photo Processing Pipeline
+
+> Example of a well-structured clarifications.md. Filled-in reference — not a template.
+> Each Q&A is concise: question raised during design review → answer → spec update.
+
+**Feature**: photo-processing
+**Phase**: CLARIFY (Phase 3)
+**Status**: Resolved — all items incorporated into spec.md
+
+---
+
+## Questions & Answers
+
+### Q1: File size limit — 10MB for all users or tiered?
+
+**Question:** The spec says max 10MB but the proposal mentioned "higher for pro users." Should we implement tiered limits now?
+
+**Answer:** Free tier: 10MB. Pro tier: 50MB. Enforce via `[Authorize]` + claims check in the upload endpoint. YAGNI — don't build a generic tier system, just check the plan claim directly.
+
+**Spec Updates:**
+- Updated `spec.md` FR1 to specify tiered limits
+- Added `CanUploadLargeFile` policy to Security section
+- Updated `UploadPhotoCommand` to accept `userPlan` claim
+
+**Priority:** High — affects contracts
+**Resolved:** ✅ Yes
+
+---
+
+### Q2: Processed photo retention — indefinite or expiring?
+
+**Question:** Should processed photos in Blob Storage be kept forever, or do they expire?
+
+**Answer:** Auto-delete after 30 days via Blob lifecycle policy (no code needed, configured in Azure). Free tier: 7 days. Pro tier: 30 days. This is infrastructure-only — `ProcessingJob.ProcessedPhotoUrl` stays in DB but becomes a dead link after expiry.
+
+**Spec Updates:**
+- Added ADR-003 (Blob lifecycle policy over code-based cleanup)
+- Added note to `AzureBlobStorageService` about lifecycle dependency
+
+**Priority:** Low — no code change
+**Resolved:** ✅ Yes
+
+---
+
+### Q3: AI API — async webhook or polling?
+
+**Question:** spec.md assumed Hangfire polls job completion, but the AI vendor docs mention a webhook callback option.
+
+**Answer:** Use fire-and-forget HTTP call + Hangfire continuation (not webhook). The AI API's webhook requires a public URL we don't have in dev. Fire-and-forget is simpler and testable. If the vendor SLA changes, we can swap to webhook via `IPhotoProcessingJob` interface — no consumer changes needed.
+
+**Spec Updates:**
+- Clarified Processing Flow in spec.md to show fire-and-forget + await pattern
+- Added to Risks: "AI API webhook migration path if needed"
+
+**Priority:** High — affects job implementation
+**Resolved:** ✅ Yes
+
+---
+
+## Edge Cases
+
+### EC1: Upload during Hangfire downtime
+
+**Scenario:** User uploads successfully but Hangfire server is stopped — job never executes.
+
+**Expected Behavior:** Job stays in `Pending` indefinitely. On next Hangfire server start, job auto-resumes (Hangfire persistent storage).
+
+**Solution:** No code change. Add monitoring alert if job stays Pending > 10 minutes.
+
+**Acceptance Criteria:**
+- [ ] `ProcessingJob` with status `Pending` survives Hangfire restart
+- [ ] Hangfire picks up orphaned jobs on startup (built-in behavior, covered by docs)
+
+---
+
+### EC2: Concurrent uploads of same file
+
+**Scenario:** User double-clicks Upload button, sending two identical requests simultaneously.
+
+**Expected Behavior:** Two separate `ProcessingJob` records created. Both process independently. No deduplication (not required at MVP scale).
+
+**Solution:** No code change. Each request gets a fresh GUID. If deduplication becomes needed, add idempotency key header in v2.
+
+---
+
+## Business Rules Clarified
+
+### BR1: Only the uploading user can download their processed photo
+
+**Rule:** `GET /api/download/{jobId}` must check `job.UserId == currentUserId`. Return 403 if mismatch.
+
+**Rationale:** Users might guess sequential GUIDs (they can't since we use random GUIDs, but defense in depth).
+
+**Implementation:** Add `[Authorize]` + ownership check to download endpoint. Already in Security section of spec.md.
+
+---
+
+## Summary
+
+| | Count |
+|---|---|
+| Questions Answered | 3 / 3 |
+| Edge Cases Documented | 2 |
+| Business Rules Clarified | 1 |
+| Spec Updates Made | 6 |
+
+## Next Steps
+
+1. [x] All questions resolved
+2. [x] `spec.md` updated with all clarifications
+3. [x] `contracts.cs` updated (`UploadPhotoCommand` + plan claim)
+4. [x] Stakeholder approval received
+5. [ ] Advance to Phase 4 (Tasks)
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/skills/level-1-workflows/phase-codebase-analysis/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: phase-codebase-analysis
+description: MORPH-SPEC Design sub-phase that analyzes existing codebase and database schema, producing schema-analysis.md with real column names, types, relationships, and field mismatches. Use at the start of Design phase before generating contracts.cs to prevent incorrect field names or types.
+user-invocable: false
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# MORPH Codebase Analysis - Sub-fase de DESIGN
+
+> INTERNAL: Automation skill for schema analysis step within Phase 2 (Design).
+> Called by `phase-design.md` Passo 2. Not a standalone user command.
+
+Automatiza a análise de código existente para gerar `schema-analysis.md` com dados reais do banco/código.
+
+## Pré-requisitos
+
+- [ ] FASE 1 (Setup) concluída
+- [ ] Feature tem `proposal.md` aprovado
+- [ ] Contexto do projeto carregado (stack, agentes)
+
+## Ferramentas Recomendadas
+
+> **Ref:** `framework/skills/level-0-meta/tool-usage-guide/SKILL.md` para guia completo.
+> **Ref:** `framework/standards/integration/mcp/mcp-tools.md` para referência MCP.
+
+| Ação | Ferramenta | Alternativa |
+|------|------------|-------------|
+| Listar tabelas do banco | **Supabase MCP** `list_tables()` | **Grep** `.from(` no código |
+| Obter schema de tabela | **Supabase MCP** `get_table_schema()` | **Read** type definitions |
+| Obter relacionamentos FK | **Supabase MCP** `get_relationships()` | **Grep** JOIN/FK patterns |
+| Obter políticas RLS | **Supabase MCP** `query()` | **Read** policy files |
+| Encontrar queries no código | **Grep** `\.from\(` em `*.ts,*.tsx,*.js,*.cs` | — |
+| Encontrar type definitions | **Glob** `src/**/types/**/*.ts` ou `**/Entities/**/*.cs` | — |
+| Ler arquivos encontrados | **Read** cada arquivo | — |
+| Análise multi-arquivo complexa | **Task** (subagent Explore) | Read individual |
+| Gerar schema-analysis.md | **Write** usando template | **Bash** template render |
+
+**MCPs desta fase:** Supabase (schema — **PRIORITÁRIO**), Database MCPs genéricos.
+
+---
+
+## Workflow Automatizado
+
+### Passo 1: Detectar Método de Análise
+
+```
+SE MCP Supabase disponível:
+  → Usar Método A (MCP direto)
+SE MCP Database disponível:
+  → Usar Método A adaptado
+SENÃO:
+  → Usar Método B (análise estática de código)
+```
+
+### Passo 2A: Método MCP (Preferencial)
+
+**Ferramentas:** Supabase MCP
+
+```javascript
+// 1. Listar todas as tabelas
+const tables = await mcp__supabase__list_tables();
+
+// 2. Para cada tabela relevante à feature:
+for (const table of relevantTables) {
+  // 2a. Schema completo
+  const schema = await mcp__supabase__get_table_schema({ table: table.name });
+  // → column_name, data_type, is_nullable, column_default
+
+  // 2b. Relacionamentos
+  const rels = await mcp__supabase__get_relationships({ table: table.name });
+  // → foreign_table, foreign_column, constraint_type
+
+  // 2c. Indexes
+  const indexes = await mcp__supabase__query({
+    query: `SELECT indexname, indexdef FROM pg_indexes WHERE tablename = '${table.name}'`
+  });
+
+  // 2d. RLS policies (segurança)
+  const policies = await mcp__supabase__query({
+    query: `SELECT policyname, cmd, qual FROM pg_policies WHERE tablename = '${table.name}'`
+  });
+}
+```
+
+### Passo 2B: Método Análise Estática (Fallback)
+
+**Ferramentas:** Grep, Glob, Read, Task (subagent para projetos grandes)
+
+**Fase B1: Encontrar Queries**
+
+```
+Grep: "\.from\(|\.select\(|SELECT |supabase\.|context\.|dbContext\.|DbSet<"
+Type: ts,tsx,js,jsx,cs
+Output: files_with_matches
+```
+
+**Fase B2: Ler Arquivos de Query**
+
+Para cada arquivo encontrado, use **Read** para extrair:
+- Nomes de tabelas: `from('leads')`, `DbSet<Lead>`, `FROM leads`
+- Nomes de colunas: `.select('fullname, phonenumber')`, `l.FullName`
+- Tipos de dados: TypeScript interfaces, C# DTOs
+- Relacionamentos: JOIN clauses, navigation properties
+
+**Fase B3: Encontrar Type Definitions**
+
+```
+# TypeScript/JavaScript:
+Glob: "src/**/types/**/*.ts"
+Glob: "src/**/*.d.ts"
+Glob: "src/**/interfaces/*.ts"
+
+# .NET:
+Glob: "**/*Dto.cs"
+Glob: "**/Entities/**/*.cs"
+Glob: "**/Models/**/*.cs"
+```
+
+**Fase B4: Quando usar Task (subagent)**
+
+Use Task subagent **APENAS** quando:
+- Projeto tem 20+ arquivos de query
+- Múltiplos padrões de acesso a dados (Supabase + EF Core + raw SQL)
+- Análise precisa de contexto cruzado entre muitos arquivos
+
+Não use Task subagent quando:
+- Projeto tem < 10 arquivos de query (Read direto é mais rápido)
+- Padrão de acesso a dados é uniforme (só Supabase OU só EF Core)
+
+### Passo 3: Mapear Inconsistências
+
+Crie um mapa de:
+
+| Frontend/Código | Banco de Dados | Tipo | Problema |
+|----------------|----------------|------|----------|
+| user.name | users.fullname | string | ❌ MISMATCH |
+| lead.phone | leads.phonenumber | string | ❌ MISMATCH |
+| order.metadata | orders.metadata | JSONB | ⚠️ Type complex |
+
+### Passo 4: Gerar `schema-analysis.md`
+
+Use o template em `framework/templates/docs/schema-analysis.md`:
+
+```bash
+npx morph-spec template render docs/schema-analysis \
+  .morph/features/{feature-name}/1-design/schema-analysis.md \
+  '{ "FEATURE_NAME": "{feature-name}", "DATE": "..." }'
+```
+
+OU use **Write** tool para criar diretamente com os dados coletados.
+
+### Passo 5: Atualizar State
+
+```bash
+npx morph-spec state mark-output {feature-name} schema-analysis
+```
+
+---
+
+## Outputs
+
+- `.morph/features/{feature}/1-design/schema-analysis.md`
+- State atualizado com output `schemaAnalysis`
+
+## CHECKPOINT
+
+Antes de prosseguir para contracts.cs, apresente ao usuário:
+
+- [ ] Analisei {N} tabelas
+- [ ] Encontrei {N} field name mismatches
+- [ ] Encontrei {N} type mismatches
+- [ ] Mapeei {N} relacionamentos
+- [ ] `schema-analysis.md` criado
+
+**Perguntas obrigatórias:**
+1. "O schema analysis está correto?"
+2. "Posso gerar contracts.cs com base nesse schema real?"
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*