@polymorphism-tech/morph-spec 3.1.0 → 4.2.0

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
@@ -414,18 +488,6 @@ MORPH-SPEC possui **30 agentes** organizados em 4 tiers hierárquicos com squads
 
 ---
 
-## Exemplos
-
-| Exemplo | Descrição |
-|---------|-----------|
-| [micro-saas](stacks/blazor-azure/.morph/examples/micro-saas/) | SaaS completo com Blazor + Asaas billing |
-| [api-nextjs](stacks/blazor-azure/.morph/examples/api-nextjs/) | .NET API + Next.js frontend |
-| [multi-agent](stacks/blazor-azure/.morph/examples/multi-agent/) | Sistema multi-agente com Microsoft Agent Framework |
-
-Cada exemplo inclui: `README.md`, `spec.md`, `contracts.cs`, `tasks.md`, `decisions.md`
-
----
-
 ## Estrutura do Projeto
 
 Após a instalação, seu projeto terá:
@@ -449,7 +511,6 @@ seu-projeto/
 │   │   ├── infra/
 │   │   ├── integrations/
 │   │   └── saas/
-│   ├── examples/             # Exemplos completos
 │   ├── features/             # Features em desenvolvimento
 │   └── archive/              # Features concluídas
 └── .claude/
@@ -629,7 +690,7 @@ Todo código gerado usando MORPH-SPEC é **100% seu** para usar como quiser, inc
 
 - [npm Package](https://www.npmjs.com/package/@polymorphism-tech/morph-spec)
 - [Documentação](docs/)
-- [Exemplos](stacks/blazor-azure/.morph/examples/)
+- [Wiki (Base de Conhecimento)](.wiki/) - 33 artigos sobre .NET, Azure, IA, SaaS e Claude Code
 - [Polymorphism Tech](https://polymorphism.com.br)
 
 ---

package/bin/detect-agents.js

@@ -15,7 +15,7 @@
 import { readFileSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
-import { resolveAgentsConfigPath } from '../src/lib/stack-resolver.js';
+import { resolveAgentsConfigPath } from '../src/lib/stacks/stack-resolver.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const frameworkRoot = join(__dirname, '..');

package/bin/morph-spec.js

@@ -5,33 +5,66 @@ import chalk from 'chalk';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
 import { readFileSync } from 'fs';
-import { setGlobalStack } from '../src/lib/stack-resolver.js';
-
-import { initCommand } from '../src/commands/init.js';
-import { updateCommand } from '../src/commands/update.js';
-import { doctorCommand } from '../src/commands/doctor.js';
-import { detectCommand } from '../src/commands/detect.js';
-import { detectAgentsCommand } from '../src/commands/detect-agents.js';
-import { syncCommand } from '../src/commands/sync.js';
-import { createStoryCommand } from '../src/commands/create-story.js';
-import { shardSpecCommand } from '../src/commands/shard-spec.js';
-import { sprintStatusCommand } from '../src/commands/sprint-status.js';
-import { stateCommand } from '../src/commands/state.js';
-import { taskDoneCommand, taskStartCommand, taskNextCommand } from '../src/commands/task.js';
-import { generateDesignSystemCommand } from '../src/commands/generate.js';
-import { generateContextCommand } from '../src/commands/generate-context.js';
+import { setGlobalStack } from '../src/lib/stacks/stack-resolver.js';
+
+// Project commands
+import { initCommand } from '../src/commands/project/init.js';
+import { updateCommand } from '../src/commands/project/update.js';
+import { doctorCommand } from '../src/commands/project/doctor.js';
+import { detectCommand } from '../src/commands/project/detect.js';
+import { detectAgentsCommand } from '../src/commands/project/detect-agents.js';
+import { detectWorkflowCommand } from '../src/commands/project/detect-workflow.js';
+import { syncCommand } from '../src/commands/project/sync.js';
+
+// Feature commands
+import { createStoryCommand } from '../src/commands/feature/create-story.js';
+import { shardSpecCommand } from '../src/commands/feature/shard-spec.js';
+import { sprintStatusCommand } from '../src/commands/feature/sprint-status.js';
+
+// State commands
+import { stateCommand } from '../src/commands/state/state.js';
+import { validatePhaseCommand } from '../src/commands/state/validate-phase.js';
+import { rollbackPhaseCommand } from '../src/commands/state/rollback-phase.js';
+import { advancePhaseCommand } from '../src/commands/state/advance-phase.js';
+import { approveCommand, rejectCommand, approvalStatusCommand } from '../src/commands/state/approve.js';
+
+// Task commands
+import { taskDoneCommand, taskStartCommand, taskNextCommand } from '../src/commands/tasks/task.js';
+
+// Generation commands
+import { generateDesignSystemCommand, generateMetadataCommand } from '../src/commands/generation/generate.js';
+import { generateContextCommand } from '../src/commands/generation/generate-context.js';
+
+// Validation commands
 import { validateCommand } from './validate.js';
-import { validateBlazorCommand } from '../src/commands/validate-blazor.js';
-import { lintFluentCommand } from '../src/commands/lint-fluent.js';
-import { analyzeBlazorConcurrencyCommand } from '../src/commands/analyze-blazor-concurrency.js';
-import { validateBlazorStateCommand } from '../src/commands/validate-blazor-state.js';
-import { validateCssCommand } from '../src/commands/validate-css.js';
-import { LearningSystem } from '../src/lib/learning-system.js';
-import troubleshootCommand from '../src/commands/troubleshoot.js';
-import { validatePhaseCommand } from '../src/commands/validate-phase.js';
-import { sessionSummaryCommand } from '../src/commands/session-summary.js';
-import { rollbackPhaseCommand } from '../src/commands/rollback-phase.js';
-import { advancePhaseCommand } from '../src/commands/advance-phase.js';
+import { validateBlazorCommand } from '../src/commands/validation/validate-blazor.js';
+import { lintFluentCommand } from '../src/commands/validation/lint-fluent.js';
+import { analyzeBlazorConcurrencyCommand } from '../src/commands/validation/analyze-blazor-concurrency.js';
+import { validateBlazorStateCommand } from '../src/commands/validation/validate-blazor-state.js';
+import { validateCssCommand } from '../src/commands/validation/validate-css.js';
+
+// Template commands
+import { templateListCommand } from '../src/commands/templates/template-list.js';
+import { templateShowCommand } from '../src/commands/templates/template-show.js';
+import { templateRenderCommand } from '../src/commands/templates/template-render.js';
+import { templateCustomizeCommand } from '../src/commands/templates/template-customize.js';
+import { templateValidateCommand } from '../src/commands/templates/template-validate.js';
+
+// Agent commands
+import { spawnTeamCommand } from '../src/commands/agents/spawn-team.js';
+
+// Learning commands
+import capturePatternProgram from '../src/commands/learning/capture-pattern.js';
+import searchPatternsProgram from '../src/commands/learning/search-patterns.js';
+
+// Utility commands
+import troubleshootCommand from '../src/commands/utils/troubleshoot.js';
+import { sessionSummaryCommand } from '../src/commands/utils/session-summary.js';
+import migrateStateProgram from '../src/commands/utils/migrate-state.js';
+import upgradeProgram from '../src/commands/utils/upgrade.js';
+
+// Libraries
+import { LearningSystem } from '../src/lib/learning/learning-system.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -90,6 +123,14 @@ program
   .option('-i, --ids-only', 'Output only agent IDs (one per line)')
   .action(detectAgentsCommand);
 
+program
+  .command('detect-workflow <input...>')
+  .description('Detect appropriate workflow for a feature request')
+  .option('-v, --verbose', 'Show detailed detection reasoning')
+  .option('-j, --json', 'Output as JSON')
+  .option('-p, --project-path <path>', 'Project path (default: current directory)')
+  .action(detectWorkflowCommand);
+
 program
   .command('sync')
   .description('Sync standards from feature decisions')
@@ -189,6 +230,13 @@ generateCommand
     await generateContextCommand('.', feature);
   });
 
+generateCommand
+  .command('metadata <feature>')
+  .description('Generate metadata.json summary from markdown outputs')
+  .option('--output <path>', 'Custom output path')
+  .option('--verbose', 'Show detailed extraction info')
+  .action((feature, options) => generateMetadataCommand(feature, options));
+
 // Validation commands (Sprint 4: Continuous Validation)
 program
   .command('validate [validator]')
@@ -321,6 +369,60 @@ learnCommand
     console.log(chalk.green('\n✅ Knowledge base reset\n'));
   });
 
+// Template management commands
+const templateCommand = program
+  .command('template')
+  .description('Template management (list | show | render | customize | validate)');
+
+templateCommand
+  .command('list')
+  .description('List all available templates')
+  .option('--category <category>', 'Filter by category (documentation, code, infrastructure, context, examples)')
+  .option('--phase <phase>', 'Filter by phase (proposal, design, implement, etc.)')
+  .option('--stack <stack>', 'Filter by stack (blazor-azure, nextjs-supabase)')
+  .option('--required', 'Show only required templates')
+  .action(templateListCommand);
+
+templateCommand
+  .command('show <template-id>')
+  .description('Show detailed information about a template')
+  .option('--show-path', 'Show resolved template file path')
+  .option('--preview', 'Show first 20 lines of template content')
+  .option('--stack <stack>', 'Stack for path resolution (default: blazor-azure)')
+  .option('--project-path <path>', 'Project path (default: current directory)')
+  .action(templateShowCommand);
+
+templateCommand
+  .command('render <template-id> <output-path> <variables-json>')
+  .description('Render a template with variables')
+  .option('--dry-run', 'Preview without writing file')
+  .option('--stack <stack>', 'Stack for template resolution (default: blazor-azure)')
+  .option('--project-path <path>', 'Project path (default: current directory)')
+  .option('-v, --verbose', 'Show detailed output')
+  .action(templateRenderCommand);
+
+templateCommand
+  .command('customize <template-id>')
+  .description('Copy framework template to project for customization')
+  .option('--stack <stack>', 'Target stack (default: blazor-azure)')
+  .option('--local', 'Copy to project .morph/templates/ instead of stack')
+  .option('--force', 'Overwrite existing customized template')
+  .option('--project-path <path>', 'Project path (default: current directory)')
+  .option('-v, --verbose', 'Show detailed output')
+  .action(templateCustomizeCommand);
+
+templateCommand
+  .command('validate [template-id]')
+  .description('Validate template(s) for correct Handlebars syntax')
+  .option('--category <category>', 'Validate templates in specific category')
+  .option('--technology <technology>', 'Validate templates for specific technology')
+  .option('--include-deprecated', 'Include deprecated templates')
+  .option('--show-valid', 'Show valid templates in output')
+  .option('--strict', 'Exit with error on warnings')
+  .option('--project-path <path>', 'Project path (default: current directory)')
+  .option('-v, --verbose', 'Show detailed validation information')
+  .action(templateValidateCommand);
+
 // Troubleshooting command
 program
   .command('troubleshoot <keywords...>')
@@ -365,6 +467,41 @@ program
   .option('-v, --verbose', 'Show detailed output')
   .action(rollbackPhaseCommand);
 
+// Approval workflow commands (MORPH-SPEC 3.0)
+program
+  .command('approve <feature> <gate>')
+  .description('Approve a phase gate (design, tasks, uiux, proposal)')
+  .option('--approver <name>', 'Name of approver (default: current user)')
+  .option('--notes <notes>', 'Approval notes')
+  .action((feature, gate, options) => approveCommand(feature, gate, options));
+
+program
+  .command('reject <feature> <gate> [reason]')
+  .description('Reject a phase gate with optional reason')
+  .action((feature, gate, reason, options) => rejectCommand(feature, gate, reason, options));
+
+program
+  .command('approval-status <feature>')
+  .description('Show approval status for all gates')
+  .option('--json', 'Output as JSON')
+  .action((feature, options) => approvalStatusCommand(feature, options));
+
+// Agent team spawning (MORPH-SPEC 3.0)
+program
+  .command('spawn-team <feature>')
+  .description('Generate agent team configuration for Task tool')
+  .option('--json', 'Output as JSON')
+  .option('--verbose', 'Show detailed team configuration')
+  .action((feature, options) => spawnTeamCommand(feature, options));
+
+// Pattern learning system (MORPH-SPEC 3.0) - Add as subcommands
+program.addCommand(capturePatternProgram);
+program.addCommand(searchPatternsProgram);
+
+// Migration and upgrade commands (MORPH-SPEC 3.0) - Add as subcommands
+program.addCommand(migrateStateProgram);
+program.addCommand(upgradeProgram);
+
 // Wire global --stack flag to stack-resolver before any command executes
 program.hook('preAction', () => {
   const opts = program.opts();

package/bin/task-manager.cjs

@@ -138,6 +138,9 @@ class TaskManager {
     // Save state
     await this.saveState(state);
 
+    // Auto-generate metadata.json (for quick LLM access)
+    await this.generateMetadata(featureName, feature);
+
     // Display progress
     this.displayProgress(feature);
 
@@ -230,10 +233,40 @@ class TaskManager {
    * Auto-checkpoint every 3 tasks (includes validation summary)
    */
   async autoCheckpoint(feature, tasks, featureName) {
+    const tasksCompleted = feature.tasks?.completed || tasks.length;
+    const checkpointNum = Math.floor(tasksCompleted / 3);
+
+    console.log(chalk.magenta(`\n🔍 CHECKPOINT ${checkpointNum} - Running automated validation...`));
+
+    let checkpointResult = null;
     let validationNote = '';
 
-    // Run validation and include summary in checkpoint
-    if (featureName) {
+    // Run checkpoint hooks (new enhanced validation system)
+    try {
+      const { runCheckpointHooks, shouldRunCheckpoint } = await import('../src/lib/checkpoint-hooks.js');
+
+      if (shouldRunCheckpoint(tasksCompleted, 3)) {
+        checkpointResult = await runCheckpointHooks(featureName, checkpointNum);
+
+        if (checkpointResult.passed) {
+          validationNote = ' | ✓ All validations passed';
+        } else {
+          validationNote = ` | ✗ ${checkpointResult.summary.errors} errors, ${checkpointResult.summary.warnings} warnings`;
+
+          // Check if we should block progress
+          const config = await this.loadCheckpointConfig();
+          if (config.checkpoints?.onFailure?.blockProgress && checkpointResult.summary.errors > 0) {
+            console.log(chalk.red('\n❌ Checkpoint FAILED - Fix violations before proceeding'));
+            throw new Error('Checkpoint validation failed');
+          }
+        }
+      }
+    } catch (error) {
+      if (error.message === 'Checkpoint validation failed') {
+        throw error; // Re-throw to block task completion
+      }
+      // Fallback to old validation if checkpoint-hooks not available
+      console.log(chalk.yellow('⚠️  Checkpoint hooks not available, using legacy validation'));
       try {
         const { runValidation } = await import('../src/lib/validation-runner.js');
         const result = await runValidation('.', featureName, { verbose: false });
@@ -241,23 +274,84 @@ class TaskManager {
           ? ' | Validation: PASSED'
           : ` | Validation: ${result.errors.length} errors, ${result.warnings.length} warnings`;
       } catch {
-        // Validation not available, skip
+        // No validation available
       }
     }
 
+    // Create checkpoint record
     const checkpoint = {
       id: `CHECKPOINT_AUTO_${Date.now()}`,
       timestamp: new Date().toISOString(),
       tasksCompleted: tasks.map(t => t.id),
-      note: `Auto-checkpoint: ${tasks.length} tasks completed${validationNote}`
+      note: `Auto-checkpoint: ${tasks.length} tasks completed${validationNote}`,
+      validationResults: checkpointResult?.results || null
     };
 
     feature.checkpoints = feature.checkpoints || [];
     feature.checkpoints.push(checkpoint);
 
-    console.log(chalk.magenta(`\n🎉 Auto-checkpoint reached! ${tasks.length} tasks completed`));
-    if (validationNote) {
-      console.log(chalk.gray(`   ${validationNote.trim().replace(/^ \| /, '')}`));
+    if (checkpointResult?.passed) {
+      console.log(chalk.green(`\n✅ Checkpoint ${checkpointNum} PASSED`));
+    } else if (checkpointResult) {
+      console.log(chalk.yellow(`\n⚠️  Checkpoint ${checkpointNum} completed with warnings`));
+    } else {
+      console.log(chalk.magenta(`\n🎉 Auto-checkpoint ${checkpointNum} reached!`));
+    }
+  }
+
+  /**
+   * Load checkpoint configuration from llm-interaction.json
+   */
+  async loadCheckpointConfig() {
+    try {
+      const configPath = path.join(process.cwd(), '.morph/config/llm-interaction.json');
+      const content = await fs.readFile(configPath, 'utf-8');
+      return JSON.parse(content);
+    } catch {
+      // Return defaults if config doesn't exist
+      return {
+        checkpoints: {
+          frequency: 3,
+          autoValidate: true,
+          onFailure: {
+            blockProgress: false
+          }
+        }
+      };
+    }
+  }
+
+  /**
+   * Auto-generate metadata.json after task completion
+   */
+  async generateMetadata(featureName, feature) {
+    try {
+      const config = await this.loadCheckpointConfig();
+
+      // Check if auto-generation is enabled
+      if (!config.metadata?.autoGenerate) {
+        return;
+      }
+
+      const { extractFeatureMetadata } = await import('../src/lib/metadata-extractor.js');
+      const metadata = extractFeatureMetadata(feature);
+
+      const outputPath = path.join(
+        process.cwd(),
+        `.morph/project/outputs/${featureName}/metadata.json`
+      );
+
+      // Ensure directory exists
+      const outputDir = path.dirname(outputPath);
+      await fs.mkdir(outputDir, { recursive: true });
+
+      // Write metadata
+      await fs.writeFile(outputPath, JSON.stringify(metadata, null, 2), 'utf-8');
+
+      console.log(chalk.gray(`   📊 Metadata updated: ${path.relative(process.cwd(), outputPath)}`));
+    } catch (error) {
+      // Don't block task completion if metadata generation fails
+      console.log(chalk.yellow(`   ⚠️  Metadata generation failed: ${error.message}`));
     }
   }
 

package/bin/validate.js

@@ -20,7 +20,7 @@ import chalk from 'chalk';
 import { validatePackages } from '../src/lib/validators/package-validator.js';
 import { validateArchitecture } from '../src/lib/validators/architecture-validator.js';
 import { validateContrast } from '../src/lib/validators/ui-contrast-validator.js';
-import { LearningSystem } from '../src/lib/learning-system.js';
+import { LearningSystem } from '../src/lib/learning/learning-system.js';
 
 const VALIDATORS = {
   packages: {