@polymorphism-tech/morph-spec 3.1.0 → 3.2.0

package/CLAUDE.md

@@ -52,6 +52,540 @@ cp stacks/{stack}/CLAUDE.md seu-projeto/CLAUDE.md
 
 ---
 
+## 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`.
+
+---
+
+## 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")
+
+# 3. Ou gere manualmente
+npx morph-spec generate metadata user-auth
+```
+
+### 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
 
 ```

package/README.md

@@ -34,10 +34,78 @@
 
 MORPH-SPEC é um framework de desenvolvimento orientado por especificações com **30 agentes AI especializados** organizados em 4 tiers hierárquicos. Cada agente tem expertise em tecnologias específicas e segue workflows estruturados para entregar código production-ready.
 
-**Stacks suportadas:** .NET 10/Blazor, .NET 10/Next.js
-**Infraestrutura:** Azure Bicep (IaC)
+**Stacks suportadas:** .NET 10/Blazor, .NET 10/Next.js, Node.js, Monorepos
+**Infraestrutura:** Azure Bicep (IaC) + Docker
 **Ferramenta:** Claude Code
 **Validação:** Pipeline automático de enforcement com gates por fase
+**Auto-Detecção:** ✨ LLM-powered context detection (v3.1+)
+
+---
+
+## 🚀 Novidade v3.0: LLM Interaction Enhancements
+
+MORPH-SPEC v3.0 torna o framework **explícito e orientado** para Claude Code com 8 melhorias fundamentais:
+
+### 1. **Approval Gates** (Portões de Aprovação)
+- ✅ Rastreamento explícito de aprovações em `state.json`
+- 🚫 Bloqueio de transições de fase até aprovação explícita
+- 📝 Comandos: `approve`, `reject`, `approval-status`
+
+### 2. **Checkpoint Automation** (Validação Automática)
+- 🔍 Auto-validação a cada 3 tasks (T003, T006, T009...)
+- 🛡️ 4 validators: architecture, packages, security, design-system
+- 🚧 Bloqueia progresso se falhas detectadas
+
+### 3. **Stricter Phase Validation** (Validação Estrita)
+- 🎯 State machine com transições válidas
+- 📋 Validação de conteúdo (spec.md, tasks.json)
+- 5️⃣ Sistema de 5 gates de validação
+
+### 4. **Agent Team Spawning** (Spawning de Agentes)
+- 🤖 Detecção automática quando spawnar (5+ agents, 15+ files, multi-domain)
+- 🏗️ Comando `spawn-team` gera configs para Task tool
+- 📄 Templates prontos para agent context
+
+### 5. **Metadata Generation** (Geração de Metadados)
+- 📊 Auto-gera `metadata.json` após cada task
+- ⚡ Reduz uso de tokens em 60-80%
+- 🔗 Links rápidos para spec, tasks, decisões
+
+### 6. **Learning System** (Sistema de Aprendizado)
+- 📚 11 patterns pré-configurados (389 linhas)
+- 🔎 Busca: `search-patterns "{keyword}"`
+- 📝 Captura: `capture-pattern {feature} success "Description"`
+
+### 7. **MCP Template Enhancement** (Templates Dinâmicos)
+- 🌐 17 placeholders com dados do projeto
+- 📈 Injeta: files, coverage, compliance, commits
+- 🎨 Templates: `proposal-with-mcp.md`, `spec-with-mcp.md`
+
+### 8. **Interactive Decisions** (Decisões Estruturadas)
+- 💬 Templates para AskUserQuestion
+- 🎯 6 padrões documentados (scope, architecture, validation, etc.)
+- 📖 Guia completo em `.morph/templates/decision-prompts.md`
+
+**Configuração:** `.morph/config/llm-interaction.json` com 3 presets (strict, lightweight, no-guardrails)
+
+**Documentação:** [docs/llm-interaction-config.md](docs/llm-interaction-config.md)
+
+**Migration:** `npx morph-spec upgrade --preset strict`
+
+---
+
+## ✨ Novidade v3.1: Auto-Detecção Inteligente
+
+MORPH-SPEC agora **detecta automaticamente** o contexto do seu projeto usando Claude Code:
+
+- 🤖 **LLM Analysis**: Analisa package.json, .csproj, README, estrutura de pastas
+- 🎯 **90%+ Accuracy**: Few-shot learning com exemplos reais (Next.js, Blazor, Monorepo)
+- 🔒 **Privacy-First**: Processamento local, zero chamadas externas de API
+- 🛡️ **Secret Sanitization**: Redação automática de API keys, passwords, tokens
+- 🧙 **Wizard Fallback**: Wizard interativo de 7 perguntas se LLM falhar
+- ⚡ **Zero Manual Work**: Gera `.morph/project.md` e `config.json` em segundos
+
+**Saiba mais:** [docs/cli-auto-detection.md](docs/cli-auto-detection.md)
 
 ---
 
@@ -116,13 +184,19 @@ Veja também: [Troubleshooting](#troubleshooting)
 
 | Comando | Descrição |
 |---------|-----------|
-| `morph-spec init` | Inicializa MORPH no diretório atual |
+| `morph-spec init` | Inicializa MORPH e **detecta automaticamente** o contexto do projeto ✨ |
+| `morph-spec init --wizard` | Inicializa com wizard manual (sem auto-detecção LLM) |
+| `morph-spec init --skip-detection` | Inicializa sem detectar contexto (configuração manual) |
 | `morph-spec init --force` | Sobrescreve instalação existente |
-| `morph-spec update` | Atualiza projeto para versão mais recente |
+| `morph-spec update` | Atualiza projeto e **re-analisa contexto** automaticamente ✨ |
+| `morph-spec update --wizard` | Atualiza com wizard manual |
+| `morph-spec update --skip-detection` | Atualiza sem re-analisar contexto |
 | `morph-spec update --templates` | Atualiza apenas templates |
 | `morph-spec update --standards` | Atualiza apenas standards |
 | `morph-spec doctor` | Verifica saúde e versões da instalação |
 
+> ✨ **Novo em v3.1+:** Auto-detecção inteligente de stack, arquitetura e infraestrutura usando Claude Code!
+
 ### Verificar Instalação
 
 ```bash