@polymorphism-tech/morph-spec 2.2.0 → 2.3.0

package/CLAUDE.md

@@ -570,17 +570,74 @@ Formato: Sempre as 3 ações acima (padrão para esta fase)
 
 ### FASE 5: IMPLEMENT
 ```
-Gatilho: Tasks aprovadas
+Gatilho: Tasks aprovadas (FASE 4 concluída)
+
 Ações:
-1. Implementar task por task
-2. Executar testes a cada task
-3. Checkpoint a cada 3 tasks
-4. Gerar recap ao final
+1. Implementar task por task seguindo tasks em state.json
+2. **SEMPRE chamar CLI após completar cada task:**
+   ```bash
+   npx morph-spec task done {feature} {task-id}
+   ```
+3. Aguardar confirmação do CLI (validação de dependencies)
+4. Framework atualiza state.json automaticamente:
+   - Marca task como completed
+   - Atualiza progress (percentage, counters)
+   - Detecta checkpoints automaticamente (a cada 3 tasks ou flag checkpoint)
+   - Mostra próxima task sugerida
+5. Executar testes quando task requer
+6. Gerar recap.md ao final de todas as tasks
+
+**Workflow de implementação:**
+
+# Claude implementa T001
+Claude: "Vou criar a entidade ScheduledReport..."
+[Gera Domain/Entities/ScheduledReport.cs]
+[Gera Infrastructure/Persistence/Config/ScheduledReportConfig.cs]
+
+# Claude chama CLI explicitamente
+Claude executa:
+npx morph-spec task done scheduled-reports T001
+
+# CLI valida e atualiza state.json
+CLI output:
+✅ Task T001 completed!
+📊 Progress: 11% (1/9)
+[█████░░░░░░░░░░░░░░░░░░░░░░░░] 11%
+⏭️  Next: T002 - Create CreateReportCommand + Handler
+
+# Claude confirma ao usuário
+Claude: "✅ T001 concluída!
+Entidade ScheduledReport criada com EF Core mapping.
+Progresso: 11% (1/9)
+Próxima: T002 - Create CreateReportCommand + Handler"
+
+# Após completar 3 tasks
+npx morph-spec task done scheduled-reports T003
+
+CLI output:
+✅ Task T003 completed!
+🎉 Auto-checkpoint reached! 3 tasks completed
+📊 Progress: 33% (3/9)
+⏭️  Next: T004 - Create ReportList component
+
+**NUNCA:**
+- ❌ Atualizar state.json manualmente
+- ❌ Atualizar tasks.json (não existe mais em schema 3.0.0)
+- ❌ Criar scripts PowerShell para atualizar tasks
+- ❌ Pular tasks com dependencies não completadas
+- ❌ Esquecer de chamar CLI após implementar task
+
+**SEMPRE:**
+- ✅ Chamar `npx morph-spec task done` após cada task
+- ✅ Verificar output do CLI (validações, próxima task)
+- ✅ Respeitar ordem de dependencies
+- ✅ Deixar framework gerenciar checkpoints automaticamente
 
 Outputs:
-- Código implementado
-- Testes criados
-- .morph/project/outputs/{feature}/recap.md
+- Código implementado (task por task)
+- Testes criados (quando task requer)
+- state.json atualizado automaticamente pelo CLI
+- .morph/project/outputs/{feature}/recap.md (ao final)
 ```
 
 ### FASE 6: SYNC (condicional)

package/bin/morph-spec.js

@@ -15,9 +15,12 @@ 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 { costCommand } from '../src/commands/cost.js';
 import { generateDesignSystemCommand } from '../src/commands/generate.js';
 import { updateResourcePricing, showPricing, validatePricing } from '../src/commands/update-pricing.js';
+import { validateCommand } from './validate.js';
+import { LearningSystem } from '../src/lib/learning-system.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -111,6 +114,26 @@ program
   .option('--json', 'Output as JSON (get command)')
   .action((action, args, options) => stateCommand(action, args, options));
 
+// Task management commands (MORPH-SPEC 3.0)
+const taskCommand = program
+  .command('task')
+  .description('Manage feature tasks (done | start | next)');
+
+taskCommand
+  .command('done <feature> <task-ids...>')
+  .description('Mark tasks as completed')
+  .action((feature, taskIds, options) => taskDoneCommand(feature, taskIds, options));
+
+taskCommand
+  .command('start <feature> <task-id>')
+  .description('Start a task (mark as in_progress)')
+  .action((feature, taskId, options) => taskStartCommand(feature, taskId, options));
+
+taskCommand
+  .command('next <feature>')
+  .description('Show next suggested task')
+  .action((feature, options) => taskNextCommand(feature, options));
+
 // Cost calculation command
 program
   .command('cost <bicep-files>')
@@ -170,4 +193,102 @@ generateCommand
   .option('--dry-run', 'Preview without writing files')
   .action(generateDesignSystemCommand);
 
+// Validation commands (Sprint 4: Continuous Validation)
+program
+  .command('validate [validator]')
+  .description('Run project validations (all | packages | architecture | contrast)')
+  .option('-v, --verbose', 'Show detailed output')
+  .option('--auto-fix, --fix', 'Auto-fix issues where possible')
+  .option('--no-fail', 'Don\'t exit with error code')
+  .option('-i, --insights', 'Show learning insights')
+  .option('--wcag-aaa', 'Use WCAG AAA standard (stricter)')
+  .action((validator, options) => {
+    const args = validator ? [validator] : ['all'];
+    if (options.verbose) args.push('--verbose');
+    if (options.autoFix) args.push('--auto-fix');
+    if (options.noFail) args.push('--no-fail');
+    if (options.insights) args.push('--insights');
+    if (options.wcagAaa) args.push('--wcag-aaa');
+    validateCommand(args);
+  });
+
+// Learning commands (Sprint 4: Learning System)
+const learnCommand = program
+  .command('learn')
+  .description('AI learning system commands');
+
+learnCommand
+  .command('analyze')
+  .description('Learn from project history (decisions.md files)')
+  .option('-v, --verbose', 'Show detailed learning progress')
+  .action(async (options) => {
+    const learner = new LearningSystem('.');
+    await learner.learnFromProject();
+
+    if (options.verbose) {
+      learner.formatInsights();
+    }
+  });
+
+learnCommand
+  .command('insights')
+  .description('Show AI insights and patterns')
+  .option('--json', 'Output as JSON')
+  .action((options) => {
+    const learner = new LearningSystem('.');
+
+    if (options.json) {
+      console.log(JSON.stringify(learner.getInsightsSummary(), null, 2));
+    } else {
+      learner.formatInsights();
+    }
+  });
+
+learnCommand
+  .command('suggest [category]')
+  .description('Get AI suggestions for a category (uiLibrary | architecture | infrastructure | authentication | stateManagement | testing)')
+  .option('--json', 'Output as JSON')
+  .action((category, options) => {
+    const learner = new LearningSystem('.');
+
+    if (category) {
+      const suggestion = learner.getSuggestion(category);
+      if (options.json) {
+        console.log(JSON.stringify(suggestion, null, 2));
+      } else {
+        console.log(chalk.cyan(`\n💡 Suggestion for ${category}:\n`));
+        if (suggestion.confidence === 'none') {
+          console.log(chalk.yellow(`   ${suggestion.reason}`));
+        } else {
+          console.log(chalk.white(`   → ${suggestion.suggestion} (${suggestion.percentage}% confidence)`));
+          console.log(chalk.gray(`     ${suggestion.reason}`));
+        }
+        console.log('');
+      }
+    } else {
+      const suggestions = learner.getAllSuggestions();
+      if (options.json) {
+        console.log(JSON.stringify(suggestions, null, 2));
+      } else {
+        learner.formatSuggestions(suggestions);
+      }
+    }
+  });
+
+learnCommand
+  .command('reset')
+  .description('Reset knowledge base (clear all learned patterns)')
+  .option('--force', 'Skip confirmation')
+  .action((options) => {
+    if (!options.force) {
+      console.log(chalk.yellow('\n⚠️  This will delete all learned patterns and preferences.'));
+      console.log(chalk.gray('   Run with --force to confirm.\n'));
+      process.exit(1);
+    }
+
+    const learner = new LearningSystem('.');
+    learner.reset();
+    console.log(chalk.green('\n✅ Knowledge base reset\n'));
+  });
+
 program.parse();

package/bin/task-manager.js

@@ -0,0 +1,368 @@
+#!/usr/bin/env node
+
+/**
+ * MORPH-SPEC Task Manager
+ *
+ * Manages task completion, dependencies, checkpoints, and progress tracking.
+ * Part of MORPH-SPEC 3.0 - Event-driven state management.
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+const chalk = require('chalk');
+
+class TaskManager {
+  constructor(statePath = '.morph/state.json') {
+    this.statePath = statePath;
+  }
+
+  /**
+   * Load state.json
+   */
+  async loadState() {
+    try {
+      const content = await fs.readFile(this.statePath, 'utf-8');
+      return JSON.parse(content);
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        throw new Error(`State file not found: ${this.statePath}. Run 'npx morph-spec state init' first.`);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Save state.json
+   */
+  async saveState(state) {
+    state.project.updatedAt = new Date().toISOString();
+    await fs.writeFile(this.statePath, JSON.stringify(state, null, 2), 'utf-8');
+  }
+
+  /**
+   * Complete one or more tasks
+   */
+  async completeTasks(featureName, taskIds) {
+    const state = await this.loadState();
+    const feature = state.features[featureName];
+
+    if (!feature) {
+      throw new Error(`Feature '${featureName}' not found in state.json`);
+    }
+
+    const results = [];
+
+    for (const taskId of taskIds) {
+      const task = feature.tasks.find(t => t.id === taskId);
+
+      if (!task) {
+        console.error(chalk.red(`❌ Task ${taskId} not found`));
+        continue;
+      }
+
+      if (task.status === 'completed') {
+        console.log(chalk.yellow(`⚠️  Task ${taskId} already completed`));
+        continue;
+      }
+
+      // Validate dependencies
+      const missingDeps = this.checkDependencies(task, feature.tasks);
+      if (missingDeps.length > 0) {
+        console.error(chalk.red(`❌ Cannot complete ${taskId}: missing dependencies: ${missingDeps.join(', ')}`));
+        continue;
+      }
+
+      // Mark as completed
+      task.status = 'completed';
+      task.completedAt = new Date().toISOString();
+      task.completedBy = 'claude';
+
+      results.push(task);
+
+      console.log(chalk.green(`✅ Task ${taskId} completed!`));
+
+      // Register checkpoint if task has one
+      if (task.checkpoint) {
+        this.registerCheckpoint(feature, task);
+      }
+    }
+
+    // Update progress
+    feature.progress = this.calculateProgress(feature.tasks);
+
+    // Auto-checkpoint every 3 tasks
+    const recentCompleted = this.getRecentCompleted(feature.tasks, 3);
+    if (recentCompleted.length === 3) {
+      const lastCheckpoint = feature.checkpoints[feature.checkpoints.length - 1];
+      const shouldAutoCheckpoint = !lastCheckpoint ||
+        !recentCompleted.every(t =>
+          lastCheckpoint.tasksCompleted.includes(t.id)
+        );
+
+      if (shouldAutoCheckpoint) {
+        this.autoCheckpoint(feature, recentCompleted);
+      }
+    }
+
+    // Save state
+    await this.saveState(state);
+
+    // Display progress
+    this.displayProgress(feature);
+
+    // Suggest next task
+    const nextTask = this.getNextTask(feature.tasks);
+    if (nextTask) {
+      console.log(chalk.cyan(`\n⏭️  Next: ${nextTask.id} - ${nextTask.title}`));
+      if (nextTask.dependencies && nextTask.dependencies.length > 0) {
+        console.log(chalk.gray(`   Dependencies: ${nextTask.dependencies.join(', ')}`));
+      }
+    } else {
+      console.log(chalk.green('\n🎉 All tasks completed!'));
+    }
+
+    return results;
+  }
+
+  /**
+   * Check if task dependencies are met
+   */
+  checkDependencies(task, allTasks) {
+    if (!task.dependencies || task.dependencies.length === 0) {
+      return [];
+    }
+
+    return task.dependencies.filter(depId => {
+      const dep = allTasks.find(t => t.id === depId);
+      return !dep || dep.status !== 'completed';
+    });
+  }
+
+  /**
+   * Calculate progress
+   */
+  calculateProgress(tasks) {
+    const total = tasks.length;
+    const completed = tasks.filter(t => t.status === 'completed').length;
+    const inProgress = tasks.filter(t => t.status === 'in_progress').length;
+    const pending = tasks.filter(t => t.status === 'pending').length;
+    const percentage = total > 0 ? Math.round((completed / total) * 100) : 0;
+
+    return {
+      total,
+      completed,
+      inProgress,
+      pending,
+      percentage
+    };
+  }
+
+  /**
+   * Register checkpoint (from task flag)
+   */
+  registerCheckpoint(feature, task) {
+    const checkpoint = {
+      id: task.checkpoint,
+      timestamp: new Date().toISOString(),
+      tasksCompleted: [task.id],
+      note: `Checkpoint: ${task.title}`
+    };
+
+    feature.checkpoints = feature.checkpoints || [];
+    feature.checkpoints.push(checkpoint);
+
+    console.log(chalk.magenta(`\n🎯 ${task.checkpoint} reached!`));
+  }
+
+  /**
+   * Auto-checkpoint every 3 tasks
+   */
+  autoCheckpoint(feature, tasks) {
+    const checkpoint = {
+      id: `CHECKPOINT_AUTO_${Date.now()}`,
+      timestamp: new Date().toISOString(),
+      tasksCompleted: tasks.map(t => t.id),
+      note: `Auto-checkpoint: ${tasks.length} tasks completed`
+    };
+
+    feature.checkpoints = feature.checkpoints || [];
+    feature.checkpoints.push(checkpoint);
+
+    console.log(chalk.magenta(`\n🎉 Auto-checkpoint reached! ${tasks.length} tasks completed`));
+  }
+
+  /**
+   * Get recently completed tasks (last N)
+   */
+  getRecentCompleted(tasks, count) {
+    const completed = tasks
+      .filter(t => t.status === 'completed' && t.completedAt)
+      .sort((a, b) => new Date(b.completedAt) - new Date(a.completedAt));
+
+    return completed.slice(0, count);
+  }
+
+  /**
+   * Get next pending task (based on dependencies)
+   */
+  getNextTask(tasks) {
+    const pending = tasks.filter(t => t.status === 'pending');
+
+    // Find first task with all dependencies completed
+    for (const task of pending) {
+      const missingDeps = this.checkDependencies(task, tasks);
+      if (missingDeps.length === 0) {
+        return task;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Display progress
+   */
+  displayProgress(feature) {
+    const { total, completed, inProgress, pending, percentage } = feature.progress;
+
+    console.log(chalk.bold(`\n📊 Progress: ${percentage}% (${completed}/${total})`));
+    console.log(chalk.gray(`   Completed: ${completed} | In Progress: ${inProgress} | Pending: ${pending}`));
+
+    // Progress bar
+    const barLength = 30;
+    const filledLength = Math.round((percentage / 100) * barLength);
+    const bar = '█'.repeat(filledLength) + '░'.repeat(barLength - filledLength);
+    console.log(chalk.cyan(`   [${bar}] ${percentage}%`));
+  }
+
+  /**
+   * Start a task (mark as in_progress)
+   */
+  async startTask(featureName, taskId) {
+    const state = await this.loadState();
+    const feature = state.features[featureName];
+
+    if (!feature) {
+      throw new Error(`Feature '${featureName}' not found`);
+    }
+
+    const task = feature.tasks.find(t => t.id === taskId);
+
+    if (!task) {
+      throw new Error(`Task ${taskId} not found`);
+    }
+
+    if (task.status === 'completed') {
+      console.log(chalk.yellow(`⚠️  Task ${taskId} already completed`));
+      return;
+    }
+
+    // Validate dependencies
+    const missingDeps = this.checkDependencies(task, feature.tasks);
+    if (missingDeps.length > 0) {
+      throw new Error(`Cannot start ${taskId}: missing dependencies: ${missingDeps.join(', ')}`);
+    }
+
+    task.status = 'in_progress';
+    task.startedAt = new Date().toISOString();
+
+    await this.saveState(state);
+
+    console.log(chalk.blue(`▶️  Task ${taskId} started: ${task.title}`));
+  }
+
+  /**
+   * Get next task suggestion
+   */
+  async getNext(featureName) {
+    const state = await this.loadState();
+    const feature = state.features[featureName];
+
+    if (!feature) {
+      throw new Error(`Feature '${featureName}' not found`);
+    }
+
+    const nextTask = this.getNextTask(feature.tasks);
+
+    if (nextTask) {
+      console.log(chalk.cyan(`\n⏭️  Next task: ${nextTask.id} - ${nextTask.title}`));
+      if (nextTask.dependencies && nextTask.dependencies.length > 0) {
+        console.log(chalk.gray(`   Dependencies: ${nextTask.dependencies.join(', ')}`));
+      }
+      if (nextTask.files && nextTask.files.length > 0) {
+        console.log(chalk.gray(`   Files:`));
+        nextTask.files.forEach(f => console.log(chalk.gray(`     - ${f}`)));
+      }
+    } else {
+      console.log(chalk.green('🎉 All tasks completed!'));
+    }
+  }
+}
+
+// CLI
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  const manager = new TaskManager();
+
+  try {
+    switch (command) {
+      case 'done':
+      case 'complete': {
+        const featureName = args[1];
+        const taskIds = args.slice(2);
+
+        if (!featureName || taskIds.length === 0) {
+          console.error(chalk.red('Usage: npx morph-spec task done <feature> <task-id> [task-id...]'));
+          process.exit(1);
+        }
+
+        await manager.completeTasks(featureName, taskIds);
+        break;
+      }
+
+      case 'start': {
+        const featureName = args[1];
+        const taskId = args[2];
+
+        if (!featureName || !taskId) {
+          console.error(chalk.red('Usage: npx morph-spec task start <feature> <task-id>'));
+          process.exit(1);
+        }
+
+        await manager.startTask(featureName, taskId);
+        break;
+      }
+
+      case 'next': {
+        const featureName = args[1];
+
+        if (!featureName) {
+          console.error(chalk.red('Usage: npx morph-spec task next <feature>'));
+          process.exit(1);
+        }
+
+        await manager.getNext(featureName);
+        break;
+      }
+
+      default:
+        console.error(chalk.red(`Unknown command: ${command}`));
+        console.log(chalk.gray('\nAvailable commands:'));
+        console.log(chalk.gray('  done <feature> <task-id...>  - Mark tasks as completed'));
+        console.log(chalk.gray('  start <feature> <task-id>    - Start a task (mark as in_progress)'));
+        console.log(chalk.gray('  next <feature>               - Show next suggested task'));
+        process.exit(1);
+    }
+  } catch (error) {
+    console.error(chalk.red(`\n❌ Error: ${error.message}`));
+    process.exit(1);
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = TaskManager;