popeye-cli 1.0.1 → 1.2.0

package/dist/workflow/execution-mode.js

@@ -1,14 +1,180 @@
 /**
  * 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 { generateCode } from '../adapters/claude.js';
-import { loadProject, updateState, updateTaskStatus, setCurrentMilestone, setCurrentTask, getNextTask, getProgress, completeProject, failProject, } from '../state/index.js';
+import { loadProject, updateState, setCurrentMilestone, completeProject, verifyProjectCompletion, comprehensiveProjectVerification, } from '../state/index.js';
 import { runTests, testsExist, getTestSummary, } 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';
 /**
  * Maximum number of retries for failed tests
  */
 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, state) {
+    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) {
+    // 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
  *
@@ -17,7 +183,7 @@ const DEFAULT_MAX_RETRIES = 3;
  * @param task - Current task
  * @returns Context string for code generation
  */
-function buildTaskContext(state, milestone, _task) {
+function buildTaskContext(state, milestone, _task, uiDesignContext) {
     const lines = [];
     lines.push(`## Project: ${state.name}`);
     lines.push(`Language: ${state.language}`);
@@ -32,6 +198,11 @@ function buildTaskContext(state, milestone, _task) {
         lines.push(state.plan.slice(0, 2000));
         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}`);
@@ -53,9 +224,10 @@ function buildTaskContext(state, milestone, _task) {
  * @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, context, projectDir) {
+export async function executeTask(task, context, projectDir, onProgress) {
     const prompt = `
 ## Task
 ${task.name}
@@ -70,7 +242,7 @@ Please implement this task completely. After implementing:
 2. Ensure code follows best practices
 3. Document any complex logic
 `.trim();
-    return generateCode(prompt, context, { cwd: projectDir });
+    return generateCode(prompt, context, { cwd: projectDir, onProgress });
 }
 /**
  * Handle a test failure by attempting to fix the code
@@ -79,9 +251,10 @@ 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, testResult, context, projectDir) {
+export async function handleTestFailure(task, testResult, context, projectDir, onProgress) {
     const prompt = `
 ## Test Failure Fix Required
 
@@ -103,7 +276,7 @@ Please:
 2. Fix the code to make all tests pass
 3. Do NOT modify the tests unless they are incorrect
 `.trim();
-    return generateCode(prompt, context, { cwd: projectDir });
+    return generateCode(prompt, context, { cwd: projectDir, onProgress });
 }
 /**
  * Execute a task with retry logic for test failures
@@ -115,11 +288,27 @@ Please:
  * @returns Task execution result
  */
 async function executeTaskWithRetry(milestone, task, state, options) {
-    const { projectDir, maxRetries = DEFAULT_MAX_RETRIES, onTestResult, } = options;
-    const context = buildTaskContext(state, milestone, task);
+    const { projectDir, maxRetries = DEFAULT_MAX_RETRIES, onTestResult, onProgress, } = options;
+    // Load UI design context if available
+    let uiDesignContext;
+    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) => 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 {
             success: false,
@@ -187,17 +376,27 @@ async function executeTaskWithRetry(milestone, task, state, options) {
     };
 }
 /**
- * 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
  */
 export async function runExecutionMode(options) {
     const { projectDir, onProgress, onTaskStart, 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 {
@@ -210,58 +409,308 @@ export async function runExecutionMode(options) {
         }
         // Update status
         state = await updateState(projectDir, { status: 'in-progress' });
-        onProgress?.('execution-start', 'Starting execution mode...');
-        // Process tasks
-        let nextTask = await getNextTask(projectDir);
-        while (nextTask) {
-            const { milestone, task } = nextTask;
-            // Set current milestone and task
+        onProgress?.('execution-start', 'Starting hierarchical execution mode...');
+        onProgress?.('execution-start', `Processing ${state.milestones.length} milestones with per-task consensus`);
+        // Import milestone workflow dynamically to avoid circular dependencies
+        const { runMilestoneWorkflow } = await import('./milestone-workflow.js');
+        // 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
             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})`);
-            if (onTaskStart) {
-                onTaskStart(milestone, task);
+            onProgress?.('milestone-start', `Starting milestone: ${milestone.name} (${milestone.tasks.length} tasks)`);
+            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,
+                });
             }
-            // Execute the task
-            const result = await executeTaskWithRetry(milestone, task, state, options);
-            if (result.success) {
-                state = await updateTaskStatus(projectDir, task.id, 'complete', {
-                    testsPassed: result.testResult?.success,
+            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}`,
+                };
+            }
+        }
+        // ============================================
+        // 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 (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',
+                });
+            }
+        }
+        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?.('verification-warning', `Final test verification failed: ${testResult.failed} test(s) failed`);
+                await logger.warn('verification', 'tests_failed', 'Final test verification failed', {
+                    passed: testResult.passed,
+                    failed: testResult.failed,
+                    total: testResult.total,
+                    failedTests: testResult.failedTests,
                 });
-                completedTasks++;
-                onProgress?.('task-complete', `Completed: ${task.name}${result.testResult ? ` (${getTestSummary(result.testResult)})` : ''}`);
             }
             else {
-                state = await updateTaskStatus(projectDir, task.id, 'failed', {
-                    testsPassed: false,
-                    error: result.error,
+                onProgress?.('verification', `All tests passed: ${testResult.passed}/${testResult.total}`);
+                await logger.success('verification', 'tests_passed', 'All tests passed', {
+                    passed: testResult.passed,
+                    total: testResult.total,
                 });
-                failedTasks++;
-                onProgress?.('task-failed', `Failed: ${task.name} - ${result.error}`);
             }
-            if (onTaskComplete) {
-                onTaskComplete(milestone, task, result.success);
+        }
+        // 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,
+        });
+        // 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);
         }
-        // Check final status
-        const progress = await getProgress(projectDir);
-        if (failedTasks > 0) {
-            state = await failProject(projectDir, `${failedTasks} tasks failed out of ${progress.totalTasks}`);
+        if (codeVerification.codeVerification.warnings.length > 0) {
+            for (const warning of codeVerification.codeVerification.warnings.slice(0, 3)) {
+                onProgress?.('verification-info', `Code Warning: ${warning}`);
+            }
+        }
+        // Summary
+        onProgress?.('verification-summary', `Verification complete: ${completedMilestones}/${state.milestones.length} milestones, ` +
+            `${completedTasks}/${allTasks.length} tasks, ` +
+            `${codeVerification.codeVerification.totalLinesOfCode} lines of code`);
+        // 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.`);
+        onProgress?.('execution-complete', `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,
@@ -272,6 +721,12 @@ export async function runExecutionMode(options) {
     catch (error) {
         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(() => ({})),
@@ -288,27 +743,61 @@ export async function runExecutionMode(options) {
  * @returns Execution mode result
  */
 export async function resumeExecutionMode(options) {
-    const state = await loadProject(options.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,
-        };
+    const { projectDir, onProgress } = options;
+    let state = await loadProject(projectDir);
+    // 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'
+                : m.tasks.some(t => t.status === 'complete' || t.status === 'in-progress')
+                    ? 'in-progress'
+                    : 'pending',
             tasks: m.tasks.map((t) => t.status === 'failed' ? { ...t, status: 'pending', 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);
 }