popeye-cli 1.0.1 → 1.1.0

package/src/workflow/execution-mode.ts

@@ -1,20 +1,21 @@
 /**
  * Execution Mode workflow
- * Handles task execution, testing, and error recovery
+ * Handles task execution with hierarchical consensus:
+ * Milestone Plan → Consensus → (Task Plan → Consensus → Implement → Test) → Milestone Review
  */
 
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
 import type { ProjectState, Task, Milestone } from '../types/workflow.js';
+import type { ConsensusConfig } from '../types/consensus.js';
 import { generateCode, type ClaudeExecuteResult } from '../adapters/claude.js';
 import {
   loadProject,
   updateState,
-  updateTaskStatus,
   setCurrentMilestone,
-  setCurrentTask,
-  getNextTask,
-  getProgress,
   completeProject,
-  failProject,
+  verifyProjectCompletion,
+  comprehensiveProjectVerification,
 } from '../state/index.js';
 import {
   runTests,
@@ -22,6 +23,11 @@ import {
   getTestSummary,
   type TestResult,
 } from './test-runner.js';
+import { getWorkflowLogger } from './workflow-logger.js';
+import { buildWithAutoFix } from './auto-fix.js';
+import { runComprehensiveVerification, autoFixIssues } from './project-verification.js';
+import { setupUI } from './ui-setup.js';
+import { designUI, saveUISpecification, loadUISpecification } from './ui-designer.js';
 
 /**
  * Options for execution mode
@@ -29,6 +35,7 @@ import {
 export interface ExecutionModeOptions {
   projectDir: string;
   maxRetries?: number;
+  consensusConfig?: Partial<ConsensusConfig>;  // For per-task and per-milestone consensus
   onProgress?: (phase: string, message: string) => void;
   onTaskStart?: (milestone: Milestone, task: Task) => void;
   onTaskComplete?: (milestone: Milestone, task: Task, success: boolean) => void;
@@ -63,6 +70,177 @@ export interface ExecutionModeResult {
  */
 const DEFAULT_MAX_RETRIES = 3;
 
+/**
+ * Generate a comprehensive README.md for the completed project
+ * This provides users with setup and run instructions
+ *
+ * @param projectDir - Project directory
+ * @param state - Project state
+ * @returns Path to generated README or error
+ */
+async function generateProjectReadme(
+  projectDir: string,
+  state: ProjectState
+): Promise<{ success: boolean; path?: string; error?: string }> {
+  try {
+    const readmePath = path.join(projectDir, 'README.md');
+
+    // Extract features from completed milestones
+    const features = state.milestones
+      .filter(m => m.status === 'complete')
+      .map(m => ({
+        name: m.name,
+        description: m.description,
+        tasks: m.tasks.filter(t => t.status === 'complete').map(t => t.name),
+      }));
+
+    // Determine run commands based on language
+    const isTypeScript = state.language === 'typescript';
+    const installCmd = isTypeScript ? 'npm install' : 'pip install -r requirements.txt';
+    const devCmd = isTypeScript ? 'npm run dev' : 'python src/main.py';
+    const testCmd = isTypeScript ? 'npm test' : 'pytest tests/ -v';
+    const buildCmd = isTypeScript ? 'npm run build' : 'python -m py_compile src/**/*.py';
+
+    // Build README content
+    const readmeContent = `# ${state.name}
+
+${state.specification ? extractDescriptionFromSpec(state.specification) : 'A project generated by Popeye CLI.'}
+
+## Features
+
+${features.map(f => `### ${f.name}
+${f.description || ''}
+${f.tasks.length > 0 ? f.tasks.map(t => `- ${t}`).join('\n') : ''}`).join('\n\n')}
+
+## Prerequisites
+
+${isTypeScript ? `- Node.js 18.0 or higher
+- npm 8.0 or higher` : `- Python 3.9 or higher
+- pip (Python package manager)`}
+
+## Installation
+
+\`\`\`bash
+# Clone the repository (if applicable)
+cd ${state.name}
+
+# Install dependencies
+${installCmd}
+\`\`\`
+
+## Environment Setup
+
+1. Copy the example environment file:
+   \`\`\`bash
+   cp .env.example .env
+   \`\`\`
+
+2. Edit \`.env\` and fill in the required values.
+
+## Running the Application
+
+### Development Mode
+
+\`\`\`bash
+${devCmd}
+\`\`\`
+
+### Running Tests
+
+\`\`\`bash
+${testCmd}
+\`\`\`
+
+### Build for Production
+
+\`\`\`bash
+${buildCmd}
+\`\`\`
+
+${isTypeScript ? `### Start Production Server
+
+\`\`\`bash
+npm start
+\`\`\`
+` : ''}
+## Project Structure
+
+\`\`\`
+${state.name}/
+├── src/                    # Source code
+${isTypeScript ? `│   └── index.ts           # Main entry point` : `│   ├── __init__.py
+│   └── main.py            # Main entry point`}
+├── tests/                  # Test files
+├── docs/                   # Documentation
+│   ├── PLAN.md            # Development plan
+│   └── WORKFLOW_LOG.md    # Execution log
+${isTypeScript ? `├── package.json           # Dependencies and scripts
+├── tsconfig.json          # TypeScript configuration` : `├── requirements.txt       # Python dependencies
+├── pyproject.toml         # Project configuration`}
+├── .env.example           # Environment template
+├── .gitignore
+├── Dockerfile
+└── README.md
+\`\`\`
+
+## Development
+
+This project was generated using [Popeye CLI](https://github.com/your-org/popeye-cli), an autonomous code generation tool.
+
+### Development Plan
+
+See [docs/PLAN.md](docs/PLAN.md) for the complete development plan used to build this project.
+
+### Workflow Log
+
+See [docs/WORKFLOW_LOG.md](docs/WORKFLOW_LOG.md) for detailed execution logs.
+
+## License
+
+MIT
+`;
+
+    await fs.writeFile(readmePath, readmeContent, 'utf-8');
+
+    return { success: true, path: readmePath };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to generate README',
+    };
+  }
+}
+
+/**
+ * Extract a brief description from the specification
+ *
+ * @param spec - Full specification text
+ * @returns Brief description (first paragraph or summary)
+ */
+function extractDescriptionFromSpec(spec: string): string {
+  // Try to find a summary section
+  const summaryMatch = spec.match(/(?:##?\s*(?:Summary|Overview|Description)[\s\S]*?\n)([\s\S]*?)(?:\n##|\n\n##|$)/i);
+  if (summaryMatch) {
+    const summary = summaryMatch[1].trim();
+    if (summary.length > 0 && summary.length < 500) {
+      return summary;
+    }
+  }
+
+  // Fall back to first paragraph
+  const lines = spec.split('\n').filter(line => line.trim() && !line.startsWith('#'));
+  const firstParagraph = lines.slice(0, 3).join(' ').trim();
+
+  if (firstParagraph.length > 500) {
+    return firstParagraph.slice(0, 497) + '...';
+  }
+
+  return firstParagraph || 'A project generated by Popeye CLI.';
+}
+
+// Note: runCommand and runFinalBuildVerification replaced by buildWithAutoFix from auto-fix.ts
+// which provides automatic error fixing capabilities
+
 /**
  * Build the execution context for a task
  *
@@ -74,7 +252,8 @@ const DEFAULT_MAX_RETRIES = 3;
 function buildTaskContext(
   state: ProjectState,
   milestone: Milestone,
-  _task: Task
+  _task: Task,
+  uiDesignContext?: string
 ): string {
   const lines: string[] = [];
 
@@ -94,6 +273,12 @@ function buildTaskContext(
     lines.push('');
   }
 
+  // Include UI design context if available
+  if (uiDesignContext) {
+    lines.push(uiDesignContext);
+    lines.push('');
+  }
+
   lines.push('## Current Milestone');
   lines.push(`Name: ${milestone.name}`);
   lines.push(`Description: ${milestone.description}`);
@@ -118,12 +303,14 @@ function buildTaskContext(
  * @param task - The task to execute
  * @param context - Execution context
  * @param projectDir - Project directory
+ * @param onProgress - Progress callback for Claude activity
  * @returns Execution result
  */
 export async function executeTask(
   task: Task,
   context: string,
-  projectDir: string
+  projectDir: string,
+  onProgress?: (message: string) => void
 ): Promise<ClaudeExecuteResult> {
   const prompt = `
 ## Task
@@ -140,7 +327,7 @@ Please implement this task completely. After implementing:
 3. Document any complex logic
 `.trim();
 
-  return generateCode(prompt, context, { cwd: projectDir });
+  return generateCode(prompt, context, { cwd: projectDir, onProgress });
 }
 
 /**
@@ -150,13 +337,15 @@ Please implement this task completely. After implementing:
  * @param testResult - The test result
  * @param context - Execution context
  * @param projectDir - Project directory
+ * @param onProgress - Progress callback for Claude activity
  * @returns Fix attempt result
  */
 export async function handleTestFailure(
   task: Task,
   testResult: TestResult,
   context: string,
-  projectDir: string
+  projectDir: string,
+  onProgress?: (message: string) => void
 ): Promise<ClaudeExecuteResult> {
   const prompt = `
 ## Test Failure Fix Required
@@ -180,7 +369,7 @@ Please:
 3. Do NOT modify the tests unless they are incorrect
 `.trim();
 
-  return generateCode(prompt, context, { cwd: projectDir });
+  return generateCode(prompt, context, { cwd: projectDir, onProgress });
 }
 
 /**
@@ -202,13 +391,31 @@ async function executeTaskWithRetry(
     projectDir,
     maxRetries = DEFAULT_MAX_RETRIES,
     onTestResult,
+    onProgress,
   } = options;
 
-  const context = buildTaskContext(state, milestone, task);
+  // Load UI design context if available
+  let uiDesignContext: string | undefined;
+  try {
+    const uiSpec = await loadUISpecification(projectDir);
+    if (uiSpec) {
+      const { generateDesignSystemPrompt } = await import('./ui-designer.js');
+      uiDesignContext = generateDesignSystemPrompt(uiSpec);
+    }
+  } catch {
+    // UI spec not available, continue without it
+  }
+
+  const context = buildTaskContext(state, milestone, task, uiDesignContext);
   let retries = 0;
 
+  // Create a progress handler that prefixes messages with [claude]
+  const claudeProgress = onProgress
+    ? (msg: string) => onProgress('claude', msg)
+    : undefined;
+
   // Execute the task
-  const execResult = await executeTask(task, context, projectDir);
+  const execResult = await executeTask(task, context, projectDir, claudeProgress);
 
   if (!execResult.success) {
     return {
@@ -287,7 +494,8 @@ async function executeTaskWithRetry(
 }
 
 /**
- * Run execution mode for a project
+ * Run execution mode for a project using hierarchical consensus workflow
+ * Each milestone and task goes through: Plan → Consensus → Implement → Test → Review
  *
  * @param options - Execution options
  * @returns Execution mode result
@@ -302,12 +510,23 @@ export async function runExecutionMode(
     onTaskComplete,
   } = options;
 
+  // Initialize workflow logger
+  const logger = getWorkflowLogger(projectDir);
+
   let completedTasks = 0;
   let failedTasks = 0;
+  let completedMilestones = 0;
 
   try {
     let state = await loadProject(projectDir);
 
+    await logger.stageStart('execution', 'Execution Mode started', {
+      projectName: state.name,
+      phase: state.phase,
+      totalMilestones: state.milestones.length,
+      totalTasks: state.milestones.reduce((sum, m) => sum + m.tasks.length, 0),
+    });
+
     // Ensure we're in execution phase
     if (state.phase !== 'execution') {
       return {
@@ -322,95 +541,409 @@ export async function runExecutionMode(
     // Update status
     state = await updateState(projectDir, { status: 'in-progress' });
 
-    onProgress?.('execution-start', 'Starting execution mode...');
+    onProgress?.('execution-start', 'Starting hierarchical execution mode...');
+    onProgress?.('execution-start', `Processing ${state.milestones.length} milestones with per-task consensus`);
 
-    // Process tasks
-    let nextTask = await getNextTask(projectDir);
+    // Import milestone workflow dynamically to avoid circular dependencies
+    const { runMilestoneWorkflow } = await import('./milestone-workflow.js');
 
-    while (nextTask) {
-      const { milestone, task } = nextTask;
+    // Process each milestone
+    for (const milestone of state.milestones) {
+      // Skip completed milestones
+      if (milestone.status === 'complete' && milestone.completionApproved) {
+        onProgress?.('milestone-skip', `Skipping completed milestone: ${milestone.name}`);
+        completedMilestones++;
+        completedTasks += milestone.tasks.filter(t => t.status === 'complete').length;
+        continue;
+      }
 
-      // Set current milestone and task
+      // Set current milestone
       state = await setCurrentMilestone(projectDir, milestone.id);
-      state = await setCurrentTask(projectDir, task.id);
-
-      // Update task to in-progress
-      state = await updateTaskStatus(projectDir, task.id, 'in-progress');
 
       onProgress?.(
-        'task-start',
-        `Executing: ${task.name} (Milestone: ${milestone.name})`
+        'milestone-start',
+        `Starting milestone: ${milestone.name} (${milestone.tasks.length} tasks)`
       );
 
-      if (onTaskStart) {
-        onTaskStart(milestone, task);
+      await logger.stageStart('milestone', `Starting milestone: ${milestone.name}`, {
+        milestoneId: milestone.id,
+        milestoneName: milestone.name,
+        taskCount: milestone.tasks.length,
+        taskNames: milestone.tasks.map(t => t.name),
+      });
+
+      // Run the complete milestone workflow
+      const milestoneResult = await runMilestoneWorkflow(milestone, {
+        projectDir,
+        consensusConfig: options.consensusConfig,
+        onProgress,
+        onTaskStart: (task) => {
+          if (onTaskStart) {
+            onTaskStart(milestone, task);
+          }
+        },
+        onTaskComplete: (task, success) => {
+          if (success) {
+            completedTasks++;
+          } else {
+            failedTasks++;
+          }
+          if (onTaskComplete) {
+            onTaskComplete(milestone, task, success);
+          }
+        },
+      });
+
+      if (milestoneResult.success) {
+        completedMilestones++;
+        onProgress?.(
+          'milestone-complete',
+          `Milestone complete: ${milestone.name} (Score: ${milestoneResult.completionConsensus?.finalScore}%)`
+        );
+
+        await logger.stageComplete('milestone', `Milestone completed: ${milestone.name}`, {
+          milestoneId: milestone.id,
+          milestoneName: milestone.name,
+          consensusScore: milestoneResult.completionConsensus?.finalScore,
+          tasksCompleted: milestone.tasks.filter(t => t.status === 'complete').length,
+        });
+      } else {
+        onProgress?.(
+          'milestone-failed',
+          `Milestone failed: ${milestone.name} - ${milestoneResult.error}`
+        );
+
+        await logger.stageFailed('milestone', `Milestone failed: ${milestone.name}`, milestoneResult.error || 'Unknown error', {
+          milestoneId: milestone.id,
+          milestoneName: milestone.name,
+        });
+
+        // Reload state to get latest
+        state = await loadProject(projectDir);
+
+        return {
+          success: false,
+          state,
+          completedTasks,
+          failedTasks,
+          error: `Milestone "${milestone.name}" failed: ${milestoneResult.error}`,
+        };
       }
+    }
 
-      // Execute the task
-      const result = await executeTaskWithRetry(
-        milestone,
-        task,
-        state,
-        options
-      );
+    // ============================================
+    // UI SETUP PHASE
+    // ============================================
+    onProgress?.('ui-setup', 'Running UI setup and design system configuration...');
+    await logger.stageStart('ui-setup', 'Starting UI setup');
+
+    // Check if this is a frontend project
+    const frontendDir = path.join(projectDir, 'packages', 'frontend');
+    const hasFrontend = await fs.access(frontendDir).then(() => true).catch(() => false);
+
+    if (hasFrontend) {
+      try {
+        // Load or generate UI specification
+        let uiSpec = await loadUISpecification(projectDir);
+
+        if (!uiSpec && state.idea) {
+          onProgress?.('ui-setup', 'Designing UI from project idea...');
+          uiSpec = await designUI(state.idea, (msg) => onProgress?.('ui-setup', msg));
+          await saveUISpecification(projectDir, uiSpec);
+          onProgress?.('ui-setup', `UI design complete: ${uiSpec.themeName} theme selected`);
+        }
+
+        // Run UI setup to install components and configure styling
+        onProgress?.('ui-setup', 'Setting up component library and styling...');
+        const uiResult = await setupUI(
+          projectDir,
+          {
+            theme: uiSpec?.themeName || 'modern',
+            idea: state.idea,
+          },
+          (msg) => onProgress?.('ui-setup', msg)
+        );
 
-      if (result.success) {
-        state = await updateTaskStatus(projectDir, task.id, 'complete', {
-          testsPassed: result.testResult?.success,
+        if (uiResult.success) {
+          onProgress?.('ui-setup', `UI setup complete: ${uiResult.componentsInstalled.length} components installed`);
+          await logger.success('ui-setup', 'ui_setup_complete', 'UI setup completed successfully', {
+            theme: uiResult.theme,
+            components: uiResult.componentsInstalled,
+          });
+        } else {
+          onProgress?.('ui-setup', `UI setup warning: ${uiResult.error}`);
+          await logger.warn('ui-setup', 'ui_setup_warning', 'UI setup had issues', {
+            error: uiResult.error,
+          });
+        }
+      } catch (uiError) {
+        // Non-blocking - UI setup failures shouldn't stop the project
+        onProgress?.('ui-setup', `UI setup skipped: ${uiError instanceof Error ? uiError.message : 'Unknown error'}`);
+        await logger.warn('ui-setup', 'ui_setup_skipped', 'UI setup was skipped', {
+          error: uiError instanceof Error ? uiError.message : 'Unknown error',
         });
-        completedTasks++;
+      }
+    } else {
+      onProgress?.('ui-setup', 'No frontend detected, skipping UI setup');
+    }
 
+    // ============================================
+    // FINAL VERIFICATION PHASE
+    // ============================================
+    onProgress?.('verification', 'Running final verification...');
+    await logger.stageStart('verification', 'Starting final verification');
+
+    // Reload state to get latest
+    state = await loadProject(projectDir);
+
+    // Verify all milestones are complete
+    const incompleteMilestones = state.milestones.filter(m => m.status !== 'complete');
+    if (incompleteMilestones.length > 0) {
+      const incompleteNames = incompleteMilestones.map(m => m.name).join(', ');
+      onProgress?.(
+        'verification-warning',
+        `Warning: ${incompleteMilestones.length} milestone(s) not marked complete: ${incompleteNames}`
+      );
+    }
+
+    // Verify all tasks are complete
+    const allTasks = state.milestones.flatMap(m => m.tasks);
+    const incompleteTasks = allTasks.filter(t => t.status !== 'complete');
+    if (incompleteTasks.length > 0) {
+      const incompleteTaskNames = incompleteTasks.slice(0, 5).map(t => t.name).join(', ');
+      onProgress?.(
+        'verification-warning',
+        `Warning: ${incompleteTasks.length} task(s) not complete: ${incompleteTaskNames}${incompleteTasks.length > 5 ? '...' : ''}`
+      );
+    }
+
+    // Run final build verification with auto-fix
+    onProgress?.('verification', 'Running final build verification...');
+    const buildResult = await buildWithAutoFix(
+      projectDir,
+      state.language,
+      3, // max fix attempts
+      (msg) => onProgress?.('verification', `[auto-fix] ${msg}`)
+    );
+
+    if (!buildResult.success) {
+      onProgress?.(
+        'verification-error',
+        `Build verification failed${buildResult.autoFixed ? ' (after auto-fix attempts)' : ''}: Build errors remain`
+      );
+      await logger.error('verification', 'build_failed', 'Build verification failed', {
+        output: buildResult.output.slice(0, 2000),
+        autoFixed: buildResult.autoFixed,
+      });
+
+      // Block completion if build fails
+      onProgress?.(
+        'verification-error',
+        'BLOCKING: Cannot complete project with build errors. Please fix manually and resume.'
+      );
+
+      return {
+        success: false,
+        state,
+        completedTasks,
+        failedTasks,
+        error: 'Build verification failed - project not complete',
+      };
+    } else {
+      onProgress?.('verification', `Build verification passed${buildResult.autoFixed ? ' (after auto-fix)' : ''}`);
+      await logger.success('verification', 'build_passed', 'Build verification passed', {
+        autoFixed: buildResult.autoFixed,
+      });
+    }
+
+    // Run final test verification
+    const hasTests = await testsExist(projectDir, state.language);
+    if (hasTests) {
+      onProgress?.('verification', 'Running final test verification...');
+      const testResult = await runTests(projectDir, state.language);
+      if (!testResult.success) {
         onProgress?.(
-          'task-complete',
-          `Completed: ${task.name}${result.testResult ? ` (${getTestSummary(result.testResult)})` : ''}`
+          'verification-warning',
+          `Final test verification failed: ${testResult.failed} test(s) failed`
         );
-      } else {
-        state = await updateTaskStatus(projectDir, task.id, 'failed', {
-          testsPassed: false,
-          error: result.error,
+        await logger.warn('verification', 'tests_failed', 'Final test verification failed', {
+          passed: testResult.passed,
+          failed: testResult.failed,
+          total: testResult.total,
+          failedTests: testResult.failedTests,
         });
-        failedTasks++;
-
+      } else {
         onProgress?.(
-          'task-failed',
-          `Failed: ${task.name} - ${result.error}`
+          'verification',
+          `All tests passed: ${testResult.passed}/${testResult.total}`
         );
+        await logger.success('verification', 'tests_passed', 'All tests passed', {
+          passed: testResult.passed,
+          total: testResult.total,
+        });
       }
+    }
+
+    // Run comprehensive code quality verification
+    onProgress?.('verification', 'Running code quality verification...');
+    const codeVerification = await comprehensiveProjectVerification(projectDir);
+
+    // Log comprehensive verification results
+    await logger.info('verification', 'code_quality_check', 'Code quality verification results', {
+      totalSourceFiles: codeVerification.codeVerification.totalSourceFiles,
+      totalLinesOfCode: codeVerification.codeVerification.totalLinesOfCode,
+      hasMainEntryPoint: codeVerification.codeVerification.hasMainEntryPoint,
+      hasTests: codeVerification.codeVerification.hasTests,
+      hasSubstantiveCode: codeVerification.codeVerification.hasSubstantiveCode,
+      issues: codeVerification.codeVerification.issues,
+      warnings: codeVerification.codeVerification.warnings,
+    });
 
-      if (onTaskComplete) {
-        onTaskComplete(milestone, task, result.success);
+    // Display code quality results
+    onProgress?.(
+      'verification',
+      `Code: ${codeVerification.codeVerification.totalSourceFiles} files, ` +
+      `${codeVerification.codeVerification.totalLinesOfCode} lines of code`
+    );
+
+    if (codeVerification.codeVerification.issues.length > 0) {
+      for (const issue of codeVerification.codeVerification.issues) {
+        onProgress?.('verification-warning', `Code Issue: ${issue}`);
       }
+    }
 
-      // Get next task
-      nextTask = await getNextTask(projectDir);
+    if (codeVerification.codeVerification.warnings.length > 0) {
+      for (const warning of codeVerification.codeVerification.warnings.slice(0, 3)) {
+        onProgress?.('verification-info', `Code Warning: ${warning}`);
+      }
     }
 
-    // Check final status
-    const progress = await getProgress(projectDir);
+    // Summary
+    onProgress?.(
+      'verification-summary',
+      `Verification complete: ${completedMilestones}/${state.milestones.length} milestones, ` +
+      `${completedTasks}/${allTasks.length} tasks, ` +
+      `${codeVerification.codeVerification.totalLinesOfCode} lines of code`
+    );
 
-    if (failedTasks > 0) {
-      state = await failProject(
-        projectDir,
-        `${failedTasks} tasks failed out of ${progress.totalTasks}`
+    // Check if genuinely complete
+    if (!codeVerification.isGenuinelyComplete) {
+      onProgress?.(
+        'verification-warning',
+        'WARNING: Project may not be genuinely complete. Code verification found issues.'
       );
+      await logger.warn('verification', 'incomplete_code', 'Project may not be genuinely complete', {
+        taskComplete: codeVerification.taskVerification.isComplete,
+        codeQualityPassed: codeVerification.codeVerification.passed,
+        summary: codeVerification.summary,
+      });
+    }
+
+    // ============================================
+    // COMPREHENSIVE PROJECT VERIFICATION
+    // ============================================
+    onProgress?.('verification', 'Running comprehensive project verification...');
+
+    const comprehensiveReport = await runComprehensiveVerification(
+      projectDir,
+      (msg) => onProgress?.('verification', msg)
+    );
+
+    // Log verification results
+    for (const result of comprehensiveReport.results) {
+      if (!result.passed) {
+        const level = result.severity === 'error' ? 'verification-error' : 'verification-warning';
+        onProgress?.(level, `[${result.category}] ${result.message}`);
+      }
+    }
+
+    // Auto-fix fixable issues
+    if (comprehensiveReport.failedChecks > 0) {
+      const fixableCount = comprehensiveReport.results.filter(r => !r.passed && r.autoFixable).length;
+      if (fixableCount > 0) {
+        onProgress?.('verification', `Attempting to auto-fix ${fixableCount} issue(s)...`);
+        const fixed = await autoFixIssues(comprehensiveReport, (msg) => onProgress?.('verification', msg));
+        onProgress?.('verification', `Auto-fixed ${fixed} issue(s)`);
+
+        // Re-run verification after fixes
+        if (fixed > 0) {
+          onProgress?.('verification', 'Re-running verification after fixes...');
+          const reVerifyReport = await runComprehensiveVerification(projectDir);
+
+          if (reVerifyReport.failedChecks > 0) {
+            onProgress?.(
+              'verification-error',
+              `${reVerifyReport.failedChecks} critical issue(s) remain after auto-fix`
+            );
+          }
+        }
+      }
+    }
+
+    // Block completion if critical issues remain
+    if (comprehensiveReport.criticalIssues.length > 0) {
+      onProgress?.(
+        'verification-error',
+        `BLOCKING: ${comprehensiveReport.criticalIssues.length} critical issue(s) found`
+      );
+
+      for (const issue of comprehensiveReport.criticalIssues) {
+        onProgress?.('verification-error', `  - ${issue}`);
+      }
+
+      await logger.error('verification', 'critical_issues', 'Critical verification issues found', {
+        issues: comprehensiveReport.criticalIssues,
+      });
 
       return {
         success: false,
         state,
         completedTasks,
         failedTasks,
-        error: `Execution completed with ${failedTasks} failed tasks`,
+        error: `Project verification failed: ${comprehensiveReport.criticalIssues.length} critical issues`,
       };
     }
 
-    // All tasks complete
+    onProgress?.(
+      'verification',
+      `Verification complete: ${comprehensiveReport.passedChecks}/${comprehensiveReport.totalChecks} checks passed`
+    );
+
+    // ============================================
+    // GENERATE PROJECT README
+    // ============================================
+    onProgress?.('readme', 'Generating project README with setup and run instructions...');
+    const readmeResult = await generateProjectReadme(projectDir, state);
+
+    if (readmeResult.success) {
+      onProgress?.('readme', `README.md generated successfully`);
+      await logger.success('completion', 'readme_generated', 'Project README generated', {
+        path: readmeResult.path,
+      });
+    } else {
+      onProgress?.('readme-warning', `Failed to generate README: ${readmeResult.error}`);
+      await logger.warn('completion', 'readme_failed', 'Failed to generate README', {
+        error: readmeResult.error,
+      });
+    }
+
+    // All milestones complete
     state = await completeProject(projectDir);
 
     onProgress?.(
       'execution-complete',
-      `Project complete! ${completedTasks} tasks executed successfully.`
+      `Project complete! ${completedMilestones} milestones, ${completedTasks} tasks executed successfully.`
     );
 
+    await logger.stageComplete('completion', 'Project execution completed successfully', {
+      completedMilestones: completedMilestones,
+      totalMilestones: state.milestones.length,
+      completedTasks: completedTasks,
+      totalTasks: state.milestones.reduce((sum, m) => sum + m.tasks.length, 0),
+      buildPassed: buildResult.success,
+      testsPassed: hasTests ? (await runTests(projectDir, state.language)).success : true,
+    });
+
     return {
       success: true,
       state,
@@ -421,6 +954,13 @@ export async function runExecutionMode(
     const errorMessage = error instanceof Error ? error.message : 'Unknown error';
     onProgress?.('error', errorMessage);
 
+    await logger.stageFailed('execution', 'Execution Mode failed', errorMessage, {
+      errorType: error instanceof Error ? error.constructor.name : typeof error,
+      completedTasks: completedTasks,
+      failedTasks: failedTasks,
+      completedMilestones: completedMilestones,
+    });
+
     return {
       success: false,
       state: await loadProject(projectDir).catch(() => ({} as ProjectState)),
@@ -440,32 +980,91 @@ export async function runExecutionMode(
 export async function resumeExecutionMode(
   options: ExecutionModeOptions
 ): Promise<ExecutionModeResult> {
-  const state = await loadProject(options.projectDir);
+  const { projectDir, onProgress } = options;
+  let state = await loadProject(projectDir);
 
-  // Check current status
-  if (state.status === 'complete') {
-    return {
-      success: true,
-      state,
-      completedTasks: state.milestones.flatMap((m) => m.tasks).filter((t) => t.status === 'complete').length,
-      failedTasks: 0,
-    };
+  // Verify actual completion - don't trust status alone
+  const verification = await verifyProjectCompletion(projectDir);
+  const progress = verification.progress;
+
+  // Log current progress
+  onProgress?.(
+    'resume-analysis',
+    `Current progress: ${progress.progressSummary}`
+  );
+
+  // Check if actually complete
+  if (state.status === 'complete' || state.phase === 'complete') {
+    if (verification.isComplete) {
+      onProgress?.('resume-complete', 'Project is genuinely complete');
+      return {
+        success: true,
+        state,
+        completedTasks: progress.completedTasks,
+        failedTasks: 0,
+      };
+    }
+
+    // Status says complete but work is incomplete
+    onProgress?.(
+      'resume-mismatch',
+      `Status mismatch detected: status='complete' but ${progress.completedTasks}/${progress.totalTasks} tasks done`
+    );
+
+    // Reset incorrect status
+    state = await updateState(projectDir, {
+      status: 'in-progress',
+      phase: 'execution',
+      error: undefined,
+    });
+
+    onProgress?.(
+      'resume-reset',
+      `Reset project status. Will continue with ${progress.pendingTasks + progress.failedTasks} remaining tasks`
+    );
   }
 
   // Reset failed tasks to pending so they can be retried
-  if (state.status === 'failed') {
+  if (state.status === 'failed' || progress.failedTasks > 0) {
     const updatedMilestones = state.milestones.map((m) => ({
       ...m,
+      // Also reset milestone status if needed
+      status: m.tasks.every(t => t.status === 'complete')
+        ? 'complete' as const
+        : m.tasks.some(t => t.status === 'complete' || t.status === 'in-progress')
+          ? 'in-progress' as const
+          : 'pending' as const,
       tasks: m.tasks.map((t) =>
         t.status === 'failed' ? { ...t, status: 'pending' as const, error: undefined } : t
       ),
     }));
 
-    await updateState(options.projectDir, {
+    await updateState(projectDir, {
       milestones: updatedMilestones,
-      status: 'pending',
+      status: 'in-progress',
       error: undefined,
     });
+
+    if (progress.failedTasks > 0) {
+      onProgress?.(
+        'resume-retry',
+        `Reset ${progress.failedTasks} failed task(s) to pending for retry`
+      );
+    }
+  }
+
+  // Show what will be worked on
+  if (progress.nextMilestone) {
+    onProgress?.(
+      'resume-next',
+      `Next milestone: ${progress.nextMilestone.name}`
+    );
+  }
+  if (progress.nextTask) {
+    onProgress?.(
+      'resume-next',
+      `Next task: ${progress.nextTask.name} (in ${progress.nextTask.milestone})`
+    );
   }
 
   return runExecutionMode(options);