@polymorphism-tech/morph-spec 3.1.0 → 4.2.0

package/CLAUDE.md

@@ -52,6 +52,802 @@ cp stacks/{stack}/CLAUDE.md seu-projeto/CLAUDE.md
 
 ---
 
+## WORKFLOW DETECTION SYSTEM (Detecção Automática de Complexidade)
+
+O framework agora detecta **AUTOMATICAMENTE** o workflow apropriado baseado na análise do pedido do usuário.
+
+### 5 Tipos de Workflow
+
+| Workflow | Complexidade | Arquivos | Linhas | Keywords Exemplo |
+|----------|--------------|----------|--------|------------------|
+| **fast-track** | Trivial | ≤3 | ≤50 | bug, fix, corrigir, css, typo |
+| **standard** | Média | 3-10 | 50-500 | paginação, filtro, refactor, export |
+| **full-morph** | Alta | >10 | >500 | sistema, autenticação, integração, cqrs |
+| **design-impl** | N/A | N/A | N/A | prototype, figma, html para, replicar |
+| **ui-refresh** | N/A | N/A | N/A | redesign, modernizar, aesthetic, bonito |
+
+### Como Funciona
+
+**1. Quando Criar Feature:**
+
+```bash
+# Detecção automática
+npx morph-spec feature create user-pagination \
+  --request "add pagination to users table"
+
+# Output:
+🔍 Analyzing request...
+✓ Detected workflow: standard (85% confidence)
+  Matched keyword: "paginação"
+  Estimated: 5 files, ~200 lines
+
+📋 Created feature: user-pagination
+    Phase: proposal
+    Workflow: standard
+```
+
+**2. Análise Manual (Opcional):**
+
+```bash
+npx morph-spec detect-workflow "implement complete authentication system"
+
+# Output:
+Detected Workflow: full-morph (92% confidence)
+
+Criteria Match:
+  ✓ Keywords: "authentication", "complete", "system"
+  ✓ Estimated: 15 files, ~800 lines
+  ✓ Infrastructure: detected
+
+Phases to Run:
+  1. CONTEXT
+  2. PROPOSAL - ⏸️ Pause for approval
+  3. SETUP
+  4. UI/UX - ⏸️ Pause for approval
+  5. DESIGN - ⏸️ Pause for approval
+  6. CLARIFY
+  7. TASKS - ⏸️ Pause for approval
+  8. IMPLEMENT
+  9. SYNC - ⏸️ Pause for approval
+
+Phases Skipped: None (all mandatory for full-morph)
+
+Alternative Workflows:
+  - standard (15%): If scope reduced to basic login only
+```
+
+### Workflow Behaviors
+
+#### fast-track (Trivial)
+- **Objetivo:** Correções rápidas, ajustes CSS, edge cases
+- **Fases:** Quick Analysis (proposal+setup+design combinados) → Implement
+- **Fases Puladas:** UIUX, CLARIFY, TASKS, SYNC
+- **Outputs:** Apenas commit message (sem .md files)
+- **Exemplo:** "fix typo in login button"
+
+#### standard (Média Complexidade)
+- **Objetivo:** Features simples, refatorações, otimizações
+- **Fases:** PROPOSAL (simplificado) → DESIGN (conciso) → TASKS (se >5 tasks) → IMPLEMENT
+- **Fases Puladas:** SETUP (contexto já carregado), UIUX (sem frontend significativo), CLARIFY (spec claro), SYNC (decisões táticas)
+- **Outputs:** proposal.md, spec.md, recap.md (minimal)
+- **Exemplo:** "add pagination to users table"
+
+#### full-morph (Alta Complexidade)
+- **Objetivo:** Sistemas completos, arquitetura, integrações
+- **Fases:** TODAS (9 fases obrigatórias)
+- **Fases Puladas:** Nenhuma
+- **Outputs:** Completo (proposal, ui-*, spec, contracts, tasks, decisions, recap)
+- **Exemplo:** "implement complete authentication system with OAuth"
+
+#### design-impl (Prototipo → Código)
+- **Objetivo:** Converter HTML, Figma, mockups para código funcional
+- **Fases:** ANÁLISE DO PROTÓTIPO → TASKS (lista de telas) → IMPLEMENT (por tela)
+- **Fases Puladas:** PROPOSAL, DESIGN técnico, CLARIFY, SYNC
+- **Outputs:** recap.md, .razor code, CSS
+- **Exemplo:** "convert HTML prototype to Blazor components"
+
+#### ui-refresh (Redesign Visual)
+- **Objetivo:** Mudanças apenas visuais, sem lógica de negócio
+- **Fases:** ANÁLISE VISUAL → DESIGN SYSTEM (simplificado) → IMPLEMENT (por página)
+- **Fases Puladas:** SETUP completo, CONTRACTS, TASKS detalhadas, INFRA, CLARIFY, SYNC
+- **Outputs:** design-refresh-checklist.md, CSS, .razor pages, recap.md
+- **Exemplo:** "redesign dashboard to look more modern"
+
+### Algoritmo de Detecção
+
+O sistema usa 4 fatores ponderados:
+
+1. **Keywords (40%):** Matching de palavras-chave (PT + EN)
+2. **Complexity (30%):** Estimativa de arquivos/linhas/componentes
+3. **Priority (20%):** Workflows específicos > genéricos
+4. **Context (10%):** Condições especiais (has prototype? existing pages?)
+
+**Penalties:**
+- -50% para workflows sem keyword match (exceto full-morph)
+
+**Boosts:**
+- +20% para workflows com 3+ keywords matched
+
+### Override Manual
+
+```bash
+# Forçar workflow específico
+npx morph-spec state set user-auth workflow full-morph
+
+# Re-detectar após mudanças no pedido
+npx morph-spec state detect-workflow user-auth \
+  "implement basic login only (no OAuth)"
+
+# Output:
+🔄 Re-analyzing request...
+✓ New workflow: standard (78% confidence)
+  Previous: full-morph
+  Reason: Scope reduced - no OAuth, no registration
+```
+
+### Configurações de Workflow
+
+Workflows são definidos em `framework/workflows/configs/*.json`:
+
+```json
+{
+  "id": "standard",
+  "criteria": {
+    "minFiles": 3,
+    "maxFiles": 10,
+    "minLines": 50,
+    "maxLines": 500
+  },
+  "keywords": ["paginação", "pagination", "filtro", "filter"],
+  "phases": {
+    "run": ["proposal", "design", "tasks", "implement"],
+    "skip": ["setup", "uiux", "clarify", "sync"]
+  },
+  "priority": 2
+}
+```
+
+### Documentação Completa
+
+Veja `framework/workflows/` para:
+- **docs/STORY-DRIVEN-DEVELOPMENT.md:** Filosofia do sistema
+- **docs/{workflow}.md:** Detalhes de cada workflow (5 arquivos)
+- **configs/{workflow}.json:** Configurações executáveis (5 arquivos)
+- **README.md:** Guia completo do sistema de workflows
+
+**REGRA CRÍTICA:** Confie na detecção automática. Override manual apenas se houver contexto que o sistema não detectou (ex: "parece grande mas já temos 80% do código pronto").
+
+---
+
+## APPROVAL GATES (Portões de Aprovação)
+
+O sistema agora rastreia aprovações explícitas para cada fase crítica em `state.json`.
+
+### Gates Obrigatórios
+
+| Gate | Quando | Bloqueio | Comando |
+|------|--------|----------|---------|
+| **design** | Após DESIGN concluído | Impede `design → clarify` | `npx morph-spec approve {feature} design` |
+| **tasks** | Após TASKS concluído | Impede `tasks → implement` | `npx morph-spec approve {feature} tasks` |
+
+### Workflow com Approval Gates
+
+```bash
+# 1. Completar fase DESIGN
+# Sistema gera: spec.md, contracts, decisions.md
+
+# 2. PAUSAR e apresentar ao usuário
+# Use AskUserQuestion: "Approve design to proceed to clarify phase?"
+
+# 3. Se aprovado pelo usuário:
+npx morph-spec approve {feature} design
+
+# 4. Avançar fase (agora permitido)
+npx morph-spec advance-phase {feature} clarify
+
+# 5. Mesmo processo para TASKS → IMPLEMENT
+```
+
+### Comandos de Approval
+
+```bash
+# Aprovar gate
+npx morph-spec approve {feature} {gate}
+
+# Rejeitar com motivo
+npx morph-spec reject {feature} {gate} "Reason here"
+
+# Ver status de todas as aprovações
+npx morph-spec approval-status {feature}
+```
+
+### Overrides (Usar com Cuidado)
+
+```bash
+# Pular verificação de aprovação (não recomendado)
+npx morph-spec advance-phase {feature} {next-phase} --skip-approval
+
+# Forçar transição inválida (emergências apenas)
+npx morph-spec advance-phase {feature} {next-phase} --force
+```
+
+**REGRA CRÍTICA:** SEMPRE apresente outputs ao usuário e obtenha aprovação explícita antes de avançar de DESIGN ou TASKS.
+
+---
+
+## AUTOMATIC CHECKPOINTS (Validação Automática)
+
+A cada 3 tasks completadas, o sistema executa validação automática.
+
+### O Que é Validado
+
+| Validator | O Que Verifica | Falha Bloqueia? |
+|-----------|----------------|-----------------|
+| **architecture** | DI patterns, Blazor lifecycle, async/await | ✅ Sim |
+| **packages** | Conflitos NuGet, versões incompatíveis | ✅ Sim |
+| **design-system** | CSS compliance, color palette, spacing | ⚠️ Warning |
+| **security** | Secrets expostos, SQL injection, XSS | ✅ Sim |
+
+### Comportamento no Checkpoint
+
+```bash
+# Task 3, 6, 9, 12... completadas
+🔍 Running CHECKPOINT 1...
+✅ Architecture: 0 violations
+✅ Packages: 0 conflicts
+⚠️  Design System: 2 warnings (non-blocking)
+✅ Security: 0 issues
+
+✅ Checkpoint 1 passed
+
+# Se checkpoint FALHAR:
+❌ Checkpoint 2 failed!
+   - Architecture: DbContext injected directly in component
+   - Security: API key hardcoded in appsettings.json
+
+❌ Task NOT marked done. Fix violations before proceeding.
+```
+
+### Configuração
+
+Edite `.morph/config/llm-interaction.json`:
+
+```json
+{
+  "checkpoints": {
+    "frequency": 3,
+    "autoValidate": true,
+    "validators": {
+      "enabled": ["architecture", "packages", "security"]
+    },
+    "onFailure": {
+      "blockProgress": true,
+      "maxRetries": 3
+    }
+  }
+}
+```
+
+**IMPORTANTE:** Se checkpoint falha 3 vezes, use `AskUserQuestion` para decidir: simplificar implementação, pular validador (arriscado), ou escalar para troubleshooting-expert.
+
+---
+
+## PHASE VALIDATION RULES (Validação Estrita)
+
+O sistema agora impede transições de fase inválidas com **state machine**.
+
+### Transições Válidas
+
+```
+proposal → setup
+setup → uiux | design
+uiux → design
+design → clarify
+clarify → tasks
+tasks → implement
+implement → sync | archived
+sync → archived
+```
+
+### 5 Gates de Validação
+
+Ao avançar fase, o sistema verifica (em ordem):
+
+1. **State Machine:** Transição é válida? (`proposal → implement` ❌)
+2. **Approval Gates:** Gate foi aprovado? (`design` ou `tasks` gates)
+3. **Output Requirements:** Arquivos obrigatórios existem? (spec.md, tasks.json)
+4. **Spec Content:** `spec.md` tem todas as seções? (Overview, Requirements, Technical Design, Data Model, API Contracts)
+5. **Tasks Content:** `tasks.json` tem estrutura válida? (IDs, descriptions, dependencies válidas, sem ciclos)
+
+### Exemplo de Bloqueio
+
+```bash
+npx morph-spec advance-phase user-auth implement
+
+❌ Invalid phase transition: design → implement
+   Valid next phases: clarify
+
+❌ Approval gate 'design' not approved
+   Run: npx morph-spec approve user-auth design
+
+❌ Spec validation failed:
+   - Missing section: ## Data Model
+   - Missing section: ## API Contracts
+
+Fix these issues before proceeding.
+```
+
+**REGRA:** Nunca pule fases. Se precisa pular (ex: feature simples sem UIUX), documente em `decisions.md` ADR e use `--force`.
+
+---
+
+## CLAUDE CODE HOOKS (Validação em Hooks)
+
+O framework integra com o sistema de hooks do Claude Code para validação automática em eventos Git e Agent Teams.
+
+### Arquitetura de Hooks
+
+**Universal (framework/hooks/):** Hooks compartilhados por todas as stacks
+- **pre-commit/**: `agents.sh`, `specs.sh`, `orchestrator.sh`
+- **commit-msg/**: `conventional-commits.sh` (Conventional Commits format)
+- **pre-push/**: `run-tests.sh` (executa test suite completo)
+- **agent-teams/**: `teammate-idle.js`, `task-completed.js`, `phase-advanced.js`
+
+**Stack-Specific (stacks/{stack}/.morph/hooks/):** Hooks específicos de cada stack
+- **pre-commit/**: `tests-csharp.sh` (blazor-azure), `tests-typescript.sh` (nextjs-supabase)
+
+### Instalação de Git Hooks
+
+```bash
+# No diretório .git/hooks do projeto
+cd .git/hooks
+
+# Pre-commit (valida agents.json, spec.md, executa testes)
+ln -sf ../../framework/hooks/pre-commit/orchestrator.sh pre-commit
+chmod +x pre-commit
+
+# Commit-msg (valida formato Conventional Commits)
+ln -sf ../../framework/hooks/commit-msg/conventional-commits.sh commit-msg
+chmod +x commit-msg
+
+# Pre-push (executa suite de testes antes de push)
+ln -sf ../../framework/hooks/pre-push/run-tests.sh pre-push
+chmod +x pre-push
+```
+
+### Configuração de Agent Teams Hooks
+
+Adicione em `.claude/settings.local.json`:
+
+```json
+{
+  "hooks": {
+    "TeammateIdle": "node framework/hooks/agent-teams/teammate-idle.js {feature}",
+    "TaskCompleted": "node framework/hooks/agent-teams/task-completed.js {feature} {taskId}",
+    "PhaseAdvanced": "node framework/hooks/agent-teams/phase-advanced.js {feature} {fromPhase} {toPhase}"
+  }
+}
+```
+
+### Validators com Hook Behavior
+
+5 validators tier-4 configurados em `agents.json` com `hook_behavior`:
+
+| Validator | Hook Triggers | Valida | Bloqueia? |
+|-----------|---------------|--------|-----------|
+| **security-expert** | TeammateIdle, TaskCompleted | SQL injection, XSS, Secrets | ✅ Sim |
+| **architecture-expert** | TeammateIdle, TaskCompleted | DbContext injection, async/await, DI order | ✅ Sim |
+| **packages-validator** | TaskCompleted | NuGet conflicts, .NET 10 compatibility | ✅ Sim |
+| **design-system-validator** | TeammateIdle | CSS palette, spacing, typography | ⚠️ Warning |
+| **blazor-concurrency-validator** | TaskCompleted | DbContext lifecycle, async void, JSInterop | ✅ Sim |
+
+### Como Funciona
+
+**Git Hooks:**
+```
+git commit → pre-commit hook → orchestrator.sh
+    ├─ Executa framework/hooks/pre-commit/*.sh (universal)
+    └─ Executa .morph/hooks/pre-commit/*.sh (stack-specific)
+    ↓
+commit-msg hook → valida formato Conventional Commits
+    ↓
+git push → pre-push hook → executa test suite
+```
+
+**Agent Teams Hooks:**
+```
+Teammate idle → TeammateIdle hook
+    ├─ Carrega agents.json
+    ├─ Filtra validators com hook_triggers: ["TeammateIdle"]
+    ├─ Executa validators via hook-executor.js
+    └─ Bloqueia se errors > 0 e blocks_on_fail: true
+```
+
+### Bypass (Não Recomendado)
+
+```bash
+# Pular hooks Git
+git commit --no-verify
+git push --no-verify
+
+# Pular validação de task
+npx morph-spec task done feature-name task-id --skip-validation
+```
+
+**IMPORTANTE:** Veja `framework/hooks/README.md` para documentação completa de hooks.
+
+---
+
+## AGENT INVOCATION PATTERNS (Spawning de Agentes)
+
+Use **Task tool** para spawnar subagentes quando apropriado.
+
+### Quando Spawnar Agentes
+
+Spawnar subagentes quando:
+
+- **5+ agentes ativos** (conforme state.activeAgents)
+- **Multi-domínio** (backend + frontend + infra)
+- **15+ arquivos** a modificar
+- **Complexidade: high ou critical**
+
+### Pattern 1: Squad Leader Spawning
+
+```typescript
+// Use Task tool
+{
+  subagent_type: "general-purpose",
+  description: "Implement backend API layer",
+  prompt: `You are the Backend Squad Leader (dotnet-senior)...
+
+Your Domain Leaders:
+- ef-modeler: Database/EF Core layer
+- api-designer: REST endpoints + DTOs
+- event-architect: Domain events + Hangfire jobs
+
+Your Mission: Implement user authentication API
+
+Feature Spec: [Include spec.md summary]
+
+Standards:
+- .morph/standards/coding.md
+- .morph/standards/architecture.md
+- .morph/standards/dotnet10-compatibility.md
+
+Your Tasks (from tasks.json):
+- T001: Create User entity + DbContext
+- T002: Implement UserService with password hashing
+- T003: Create AuthController with login/register endpoints
+
+Deliverables:
+- Entities/User.cs
+- Data/AppDbContext.cs
+- Services/UserService.cs
+- Controllers/AuthController.cs
+- DTOs (LoginRequest, RegisterRequest, AuthResponse)
+- Migrations
+
+Constraints:
+- Use IDbContextFactory (not direct DbContext injection)
+- BCrypt for password hashing
+- JWT tokens (not sessions)
+
+Report back when complete with file list + any blockers.`
+}
+```
+
+### Pattern 2: Get Team Hierarchy Helper
+
+```bash
+# Gera configurações prontas para Task tool
+npx morph-spec spawn-team {feature}
+
+# Output: JSON configs para cada squadmate
+{
+  "teammates": [
+    {
+      "agent": "dotnet-senior",
+      "role": "Backend Squad Leader",
+      "taskConfig": { ... }
+    },
+    {
+      "agent": "ef-modeler",
+      "role": "Database Layer",
+      "taskConfig": { ... }
+    }
+  ]
+}
+```
+
+### Pattern 3: Sequential Handoff
+
+```typescript
+// 1. Backend squad gera API contracts
+Task tool → dotnet-senior → generates contracts.cs
+
+// 2. AGUARDAR conclusão (não spawnar frontend ainda)
+
+// 3. Frontend squad usa contracts no contexto
+Task tool → nextjs-senior → uses contracts.cs for type generation
+```
+
+### Agent Context Template
+
+Use `.morph/templates/agent-context.md` para gerar contexto consistente:
+
+```bash
+node bin/render-template.js agent-context \
+  --feature=user-auth \
+  --agent=dotnet-senior \
+  --output=.morph/temp/agent-context.txt
+```
+
+**REGRA:** Sempre inclua spec.md summary, standards relevantes, e tasks específicas no prompt do agente.
+
+---
+
+## METADATA & QUICK ACCESS (Acesso Rápido)
+
+Para features grandes, use `metadata.json` para acesso rápido (reduz uso de tokens em 60-80%).
+
+### Quando Usar metadata.json
+
+**USE metadata.json para:**
+- Quick status (fase atual, progresso %)
+- Lista de agentes ativos
+- Resumo de decisões (ADRs com links)
+- Histórico de checkpoints
+
+**USE arquivos .md completos para:**
+- Spec técnico detalhado
+- User stories completas
+- Diagramas e arquitetura
+
+### Estrutura do metadata.json
+
+```json
+{
+  "version": "1.0.0",
+  "feature": "user-authentication",
+  "status": "active",
+  "phase": "implement",
+
+  "spec": {
+    "id": "user-auth",
+    "status": "Approved",
+    "complexity": "Medium",
+    "summary": {
+      "problem": "Users need secure login/register...",
+      "solution": "JWT-based auth with BCrypt...",
+      "tags": ["security", "authentication", "jwt"]
+    },
+    "requirements": ["REQ1: JWT tokens", "REQ2: BCrypt hashing"],
+    "dataModel": ["User entity", "RefreshToken entity"]
+  },
+
+  "decisions": {
+    "decisions": [
+      {
+        "id": "ADR-001",
+        "title": "JWT vs Sessions",
+        "summary": "Chose JWT for stateless auth...",
+        "fullPath": ".morph/features/user-auth/decisions.md#adr-001"
+      }
+    ]
+  },
+
+  "tasks": {
+    "total": 12,
+    "completed": 8,
+    "progress": "67%"
+  },
+
+  "agents": ["dotnet-senior", "ef-modeler", "api-designer"],
+
+  "checkpoints": [
+    { "num": 1, "passed": true, "timestamp": "2026-02-14T10:30:00Z" },
+    { "num": 2, "passed": true, "timestamp": "2026-02-14T11:45:00Z" }
+  ],
+
+  "quickLinks": {
+    "spec": ".morph/features/user-auth/spec.md",
+    "tasks": ".morph/features/user-auth/tasks.json",
+    "decisions": ".morph/features/user-auth/decisions.md"
+  }
+}
+```
+
+### Workflow
+
+```bash
+# 1. Antes de trabalhar na feature, leia metadata.json
+cat .morph/project/outputs/user-auth/metadata.json
+
+# 2. Metadata é auto-atualizado após cada task
+# (Configurado em llm-interaction.json: "updateFrequency": "on_task_done")
+# NOTA: Não há comando manual para gerar metadata - sempre auto-gerado
+```
+
+### Configuração
+
+```json
+{
+  "metadata": {
+    "autoGenerate": true,
+    "updateFrequency": "on_task_done"
+  }
+}
+```
+
+---
+
+## LEARNING SYSTEM (Biblioteca de Patterns)
+
+Capture e reutilize patterns bem-sucedidos em `.morph/memory/patterns-learned.md`.
+
+### Antes de Começar Nova Feature
+
+```bash
+# Buscar patterns relevantes
+npx morph-spec search-patterns "blazor state"
+npx morph-spec search-patterns "background job"
+npx morph-spec search-patterns "bicep naming"
+
+# Output:
+🔍 Found 3 pattern(s) for: "blazor state"
+
+1. Blazor DbContext Lifecycle
+   Category: Anti-Pattern to Avoid
+   Source: Framework standard
+
+   Problem: Directly injecting DbContext in Blazor components...
+
+   Correct Approach:
+   [Inject] IDbContextFactory<AppDbContext> DbFactory { get; set; }
+   ...
+```
+
+### Após Completar Feature
+
+```bash
+# Capturar pattern bem-sucedido
+npx morph-spec capture-pattern user-auth success "JWT refresh token rotation"
+
+# Capturar anti-pattern (o que evitar)
+npx morph-spec capture-pattern user-auth avoid "Storing tokens in localStorage"
+
+# Capturar otimização
+npx morph-spec capture-pattern user-auth optimization "EF Core query splitting for N+1"
+```
+
+### Categorias de Patterns
+
+| Categoria | Quando Usar |
+|-----------|-------------|
+| `success` | Abordagens comprovadas para replicar |
+| `avoid` | Anti-patterns e erros cometidos |
+| `optimization` | Melhorias de performance |
+| `security` | Best practices de segurança |
+| `convention` | Convenções do projeto (naming, estrutura) |
+| `best-practice` | Práticas gerais recomendadas |
+
+### Pattern Library Pré-Seeded
+
+O framework já vem com 11 patterns em `.morph/memory/patterns-learned.md`:
+
+- Blazor DbContext Lifecycle (anti-pattern)
+- Background Job Retry Strategy (best practice)
+- Azure Bicep Resource Naming (convention)
+- API Versioning Strategy (architecture)
+- EF Core Migration Naming (convention)
+- Blazor DI Registration Order (best practice)
+- Component Parameter Validation (best practice)
+- Async Method Naming (convention)
+- Error Handling Strategy (best practice)
+- Bicep Output Exports (convention)
+- Azure Key Vault Secrets (security)
+
+**REGRA:** Sempre busque patterns antes de começar. Capture patterns após completar. Biblioteca cresce com o tempo.
+
+---
+
+## INTERACTIVE DECISIONS (Decisões Estruturadas)
+
+Use **AskUserQuestion** com templates estruturados em `.morph/templates/decision-prompts.md`.
+
+### Quando Usar AskUserQuestion
+
+**SEMPRE use para:**
+- Escolhas arquiteturais (múltiplas abordagens válidas)
+- Clarificação de escopo (requisitos ambíguos)
+- Override de validators (checkpoint failures)
+- Pular fases (features simples sem UIUX)
+- Breaking changes (API versioning, migrations)
+
+### Pattern 1: Arquitetura Choice
+
+```markdown
+I've designed two approaches for "user-authentication":
+
+**Option A: JWT with HttpOnly Cookies**
+- Pros: XSS protection, automatic CSRF with SameSite
+- Cons: Harder CORS, mobile app compatibility
+- Cost: +2 tasks (CSRF middleware)
+
+**Option B: JWT in Authorization Header**
+- Pros: Simpler CORS, better mobile support
+- Cons: Requires manual XSS protection
+- Cost: +1 task (XSS sanitization)
+
+Recommendation: Option A (more secure for web apps)
+
+Which approach do you prefer?
+```
+
+### Pattern 2: Scope Clarification
+
+```markdown
+Analyzing "scheduled-reports" feature. Need clarification:
+
+1. **Scope:** Include email delivery or just generation?
+2. **Users:** For admins only or all authenticated users?
+3. **Priority:** Critical (deploy this week) or enhancement (iterate)?
+4. **Format:** PDF only or PDF + Excel + CSV?
+
+Please clarify so I can generate accurate spec.
+```
+
+### Pattern 3: Validator Override
+
+```markdown
+Checkpoint failed 3 times:
+
+**Error:** Architecture validator - "DbContext injected directly in ReportsPage.razor"
+
+**Attempts:**
+1. Tried refactoring to service layer - still triggered (service was scoped)
+2. Tried IDbContextFactory - validator didn't detect pattern
+3. Re-read architecture.md - our implementation is correct per standard
+
+**Options:**
+1. Skip architecture validator for this checkpoint (risky)
+2. Simplify implementation (use in-memory data, no DB)
+3. Escalate to troubleshooting-expert agent
+4. Pause for your guidance
+
+What should I do?
+```
+
+### Pattern 4: Task Ordering
+
+```markdown
+Task dependency conflict detected in "user-auth":
+
+**Circular dependency:**
+- T003 (AuthController) depends on T005 (JWT service)
+- T005 (JWT service) depends on T003 (AuthController contracts)
+
+**Proposed resolution:**
+1. Split T003 into T003a (contracts/DTOs) and T003b (controller implementation)
+2. Order: T003a → T005 → T003b
+
+Approve this task breakdown?
+```
+
+### Templates Disponíveis
+
+Veja `.morph/templates/decision-prompts.md` para templates completos:
+- Scope Clarification
+- Architecture Choice
+- Task Ordering Conflict
+- Validation Failure Recovery
+- Breaking Change Approval
+- Phase Skip Justification
+
+**REGRA:** Sempre forneça contexto, 2-3 opções específicas, trade-offs, e sua recomendação. Usuário decide.
+
+---
+
 ## ESTRUTURA DO FRAMEWORK
 
 ```
@@ -91,14 +887,97 @@ morph-spec-framework/
 
 ## TEMPLATES
 
-> SEMPRE use `bin/render-template.js` para renderizar. NUNCA preencha placeholders manualmente.
+> **Template System v2.0** - Organizado por tecnologia, reutilizável entre stacks, powered by Handlebars
+
+### Overview
+
+Templates estão em `framework/templates/` organizados por **tecnologia** (não por stack):
+- `code/dotnet/` - Templates .NET (service, repository, component, etc.)
+- `code/typescript/` - Templates TypeScript (contracts, etc.)
+- `code/sql/` - Templates SQL (Supabase migrations, RLS policies)
+- `infrastructure/azure/` - Bicep templates para Azure
+- `infrastructure/docker/` - Dockerfiles e Docker Compose
+- `integrations/` - Integrações (Asaas, Clerk, Azure Identity)
+- `ui/` - Design systems (CSS, Fluent/Mud themes)
+- `saas/` - Multi-tenant patterns
+
+**Por quê tecnologia?** Permite reutilizar templates entre stacks (ex: service.cs funciona para blazor-azure E nextjs-supabase).
+
+### CLI Commands
+
+```bash
+# Listar todos os templates
+morph-spec template list
+
+# Filtrar por categoria/tecnologia
+morph-spec template list --category code
+morph-spec template list --phase implement
+
+# Ver detalhes de um template
+morph-spec template show dotnet-backend-service --preview
+
+# Renderizar template (usando Handlebars)
+morph-spec template render dotnet-backend-service UserService.cs '{
+  "FEATURE_NAME": "user-auth",
+  "NAMESPACE": "MyApp.Services"
+}'
+
+# Customizar template (criar override stack-specific)
+morph-spec template customize dotnet-backend-service --stack blazor-azure
+```
+
+### Handlebars Helpers (v2.0)
+
+**✅ USE (novo):**
+
+| Helper | Input | Output | Uso |
+|--------|-------|--------|-----|
+| `{{pascalCase str}}` | `user-auth` | `UserAuth` | Classes |
+| `{{camelCase str}}` | `user-auth` | `userAuth` | Variables |
+| `{{snakeCase str}}` | `user-auth` | `user_auth` | SQL |
+| `{{titleCase str}}` | `user-auth` | `User Auth` | Titles |
+| `{{pluralize str}}` | `user` | `users` | Collections |
+
+**❌ DEPRECADO (v1.0):**
+
+| Placeholder | Status | Use Instead |
+|-------------|--------|-------------|
+| `{{FEATURE_NAME_PASCAL}}` | ❌ Deprecated | `{{pascalCase FEATURE_NAME}}` |
+| `{{FEATURE_NAME_CAMEL}}` | ❌ Deprecated | `{{camelCase FEATURE_NAME}}` |
+| `{{FEATURE_NAME_SNAKE}}` | ❌ Deprecated | `{{snakeCase FEATURE_NAME}}` |
+
+### Variáveis Padrão (auto-injetadas)
 
 | Placeholder | Exemplo |
 |-------------|---------|
 | `{{FEATURE_NAME}}` | `scheduled-reports` |
-| `{{FEATURE_NAME_PASCAL}}` | `ScheduledReports` |
 | `{{STACK}}` | `Blazor` ou `NextjsSupabase` |
-| `{{DATE}}`, `{{AUTHOR}}`, `{{NAMESPACE}}` | Auto from config.json |
+| `{{DATE}}` | `2026-02-17` |
+| `{{YEAR}}` | `2026` |
+| `{{TIMESTAMP}}` | `2026-02-17T19:38:00Z` |
+| `{{NAMESPACE}}` | Auto from config.json |
+| `{{AUTHOR}}` | Auto from config.json |
+
+### Stack Overrides
+
+Templates são resolvidos com fallback automático:
+1. `stacks/{stack}/.morph/templates/` (override stack-specific)
+2. `.morph/templates/` (override project-local)
+3. `framework/templates/` (fallback padrão)
+
+Para customizar um template:
+```bash
+morph-spec template customize dotnet-backend-service --stack blazor-azure
+# Edite: stacks/blazor-azure/.morph/templates/code/dotnet/backend/service.cs
+```
+
+### Documentação Completa
+
+Veja `framework/templates/README.md` para:
+- Estrutura completa de diretórios
+- Todos os helpers Handlebars disponíveis
+- Como criar novos templates
+- Migração v1 → v2
 
 ---