popeye-cli 1.0.0 → 1.1.0

package/dist/workflow/plan-mode.js

@@ -8,6 +8,8 @@ import { expandIdea as openaiExpandIdea } from '../adapters/openai.js';
 import { createPlan as claudeCreatePlan, analyzeCodebase } from '../adapters/claude.js';
 import { createProject, loadProject, setPhase, storePlan, storeSpecification, addMilestones, } from '../state/index.js';
 import { iterateUntilConsensus } from './consensus.js';
+import { getWorkflowLogger } from './workflow-logger.js';
+import { designUI, saveUISpecification } from './ui-designer.js';
 /**
  * Expand a brief idea into a detailed specification
  *
@@ -32,7 +34,7 @@ export async function expandIdea(idea, language, onProgress) {
  */
 export async function createPlan(specification, context = '', onProgress) {
     onProgress?.('Creating development plan...');
-    const result = await claudeCreatePlan(specification, context);
+    const result = await claudeCreatePlan(specification, context, onProgress);
     if (!result.success) {
         throw new Error(`Failed to create plan: ${result.error}`);
     }
@@ -56,7 +58,7 @@ export async function getProjectContext(projectDir, onProgress) {
             onProgress?.('No existing code found');
             return 'New project - no existing codebase';
         }
-        const result = await analyzeCodebase(projectDir);
+        const result = await analyzeCodebase(projectDir, onProgress);
         if (result.success) {
             onProgress?.('Codebase analysis complete');
             return result.response;
@@ -68,14 +70,22 @@ export async function getProjectContext(projectDir, onProgress) {
     }
 }
 /**
- * Save the plan to a markdown file
+ * Save the plan to a markdown file in docs folder
  *
  * @param projectDir - The project directory
  * @param plan - The plan content
  * @param filename - The filename (default: PLAN.md)
  */
 export async function documentPlan(projectDir, plan, filename = 'PLAN.md') {
-    const planPath = path.join(projectDir, filename);
+    // Create docs directory if it doesn't exist
+    const docsDir = path.join(projectDir, 'docs');
+    try {
+        await fs.mkdir(docsDir, { recursive: true });
+    }
+    catch {
+        // Directory might already exist
+    }
+    const planPath = path.join(docsDir, filename);
     const content = `# Development Plan
 
 Generated: ${new Date().toISOString()}
@@ -83,58 +93,397 @@ Generated: ${new Date().toISOString()}
 ${plan}
 `;
     await fs.writeFile(planPath, content, 'utf-8');
+    // Also save a timestamped version for history
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+    const historyFilename = `PLAN-${timestamp}.md`;
+    const historyPath = path.join(docsDir, historyFilename);
+    await fs.writeFile(historyPath, content, 'utf-8');
     return planPath;
 }
+/**
+ * Check if a task name represents an actionable implementation task
+ * Tasks should start with verbs like: Implement, Create, Build, Set up, Add, etc.
+ *
+ * @param name - The potential task name
+ * @returns True if this looks like an implementation task
+ */
+function isActionableTask(name) {
+    const nameLower = name.toLowerCase().trim();
+    // Actionable verb prefixes that indicate real implementation tasks
+    const actionableVerbs = [
+        'implement', 'create', 'build', 'develop', 'write', 'add', 'set up', 'setup',
+        'configure', 'install', 'integrate', 'design', 'define', 'establish',
+        'generate', 'construct', 'deploy', 'test', 'validate', 'fix', 'update',
+        'refactor', 'optimize', 'extend', 'enhance', 'modify', 'initialize',
+        'bootstrap', 'scaffold', 'connect', 'wire', 'hook', 'enable', 'disable',
+    ];
+    // Check if starts with an actionable verb
+    const startsWithAction = actionableVerbs.some((verb) => nameLower.startsWith(verb + ' ') || nameLower.startsWith(verb + ':'));
+    // Non-actionable patterns to exclude (plan metadata, not tasks)
+    const nonActionablePatterns = [
+        /^(background|context|overview|introduction|summary)/i,
+        /^(goal|objective|requirement|constraint|assumption|risk)/i,
+        /^(timeline|schedule|estimate|duration|deadline)/i,
+        /^(note|example|reference|appendix|glossary)/i,
+        /^(file structure|project structure|directory)/i,
+        /^(showing|displays?|contains?|includes?|describes?)/i,
+        /^(the |this |a |an )/i, // Descriptions, not actions
+        /^\d+[-.]?\s*(week|day|hour|month)/i, // Time estimates
+        /^([\w\s]+):$/, // Labels ending with colon
+    ];
+    const isNonActionable = nonActionablePatterns.some((pattern) => pattern.test(nameLower));
+    return startsWithAction && !isNonActionable;
+}
+/**
+ * Extract task description from content following a task header
+ *
+ * @param content - Content following the task header
+ * @returns Extracted description
+ */
+function extractTaskDescription(content) {
+    // Look for Description field or first paragraph
+    const descMatch = content.match(/\*\*Description\*\*:\s*(.+?)(?=\n\*\*|\n###|\n##|$)/is);
+    if (descMatch) {
+        return descMatch[1].trim().slice(0, 500);
+    }
+    // Use first non-empty line
+    const lines = content.split('\n').filter((l) => l.trim() && !l.trim().startsWith('-'));
+    if (lines.length > 0) {
+        return lines[0].trim().slice(0, 500);
+    }
+    return '';
+}
+/**
+ * Extract acceptance criteria from task content
+ *
+ * @param content - Task content
+ * @returns Array of acceptance criteria
+ */
+function extractAcceptanceCriteria(content) {
+    const criteria = [];
+    // Look for Acceptance Criteria section
+    const acMatch = content.match(/\*\*Acceptance Criteria\*\*:?\s*([\s\S]+?)(?=\n\*\*|\n###|\n##|$)/i);
+    if (acMatch) {
+        const acContent = acMatch[1];
+        const bulletMatch = acContent.match(/^[-*]\s+(.+)$/gm);
+        if (bulletMatch) {
+            for (const bullet of bulletMatch) {
+                const cleaned = bullet.replace(/^[-*]\s+/, '').trim();
+                if (cleaned.length > 5) {
+                    criteria.push(cleaned);
+                }
+            }
+        }
+    }
+    return criteria;
+}
+/**
+ * Detect if a plan is actually Claude's thinking/conversation instead of a real plan
+ * This happens when Claude outputs its reasoning instead of the plan content
+ *
+ * @param plan - The plan content
+ * @returns Object indicating if garbage and why
+ */
+export function detectGarbagePlan(plan) {
+    const planLower = plan.toLowerCase();
+    // Phrases that indicate Claude's thinking, not actual plan content
+    const garbagePhrases = [
+        'let me ',
+        'i will ',
+        'i\'ll ',
+        'now i have',
+        'i now have',
+        'let me launch',
+        'let me create',
+        'let me write',
+        'comprehensive understanding',
+        'let me analyze',
+        'based on my analysis',
+        'before i proceed',
+        'i\'ve created',
+        'i\'ve analyzed',
+        'i should',
+        'i need to',
+        'first, i',
+        'the plan is saved',
+        'saved to',
+        'saved at',
+    ];
+    for (const phrase of garbagePhrases) {
+        if (planLower.includes(phrase)) {
+            return {
+                isGarbage: true,
+                reason: `Plan contains Claude's thinking ("${phrase}") instead of actual plan content`,
+            };
+        }
+    }
+    // Check if plan has actual structure
+    const hasTaskHeaders = /^#{2,4}\s*Task\s+[\d.]+/im.test(plan);
+    const hasMilestoneHeaders = /^#{1,3}\s*Milestone\s+\d/im.test(plan);
+    const hasActionableBullets = /^[-*]\s+(implement|create|build|add|set up|configure|design|write)/im.test(plan);
+    if (!hasTaskHeaders && !hasMilestoneHeaders && !hasActionableBullets) {
+        // Check if it at least has some structure
+        const hasAnyHeaders = /^#{1,4}\s+.+$/m.test(plan);
+        const hasBulletPoints = /^[-*+]\s+.+$/m.test(plan);
+        if (!hasAnyHeaders && !hasBulletPoints) {
+            return {
+                isGarbage: true,
+                reason: 'Plan has no recognizable structure (no headers, no bullet points)',
+            };
+        }
+    }
+    return { isGarbage: false };
+}
 /**
  * Parse milestones and tasks from a plan
+ * Extracts only actionable implementation tasks, not plan metadata
  *
  * @param plan - The plan content
  * @returns Parsed milestones with tasks
  */
 export function parsePlanMilestones(plan) {
     const milestones = [];
-    // Look for milestone sections
-    const milestonePattern = /#+\s*(?:Milestone\s*\d+[:\s]*)?([^\n]+)\n([\s\S]*?)(?=#+\s*(?:Milestone|$)|$)/gi;
-    const taskPattern = /[-*]\s*(?:\[[ x]\]\s*)?(?:Task[:\s]*)?(.+)/gi;
-    let match;
-    while ((match = milestonePattern.exec(plan)) !== null) {
-        const name = match[1].trim();
-        const content = match[2];
-        // Skip non-milestone sections
-        if (name.toLowerCase().includes('background') ||
-            name.toLowerCase().includes('goal') ||
-            name.toLowerCase().includes('risk') ||
-            name.toLowerCase().includes('summary')) {
-            continue;
-        }
-        const tasks = [];
-        let taskMatch;
-        while ((taskMatch = taskPattern.exec(content)) !== null) {
-            const taskName = taskMatch[1].trim();
-            if (taskName && !taskName.toLowerCase().startsWith('test')) {
-                tasks.push({
+    // First pass: Look for explicit task markers per the spec format
+    // Format: "### Task [M].N: [Title]" or "Task N: [Title]"
+    const explicitTaskPattern = /^#{2,4}\s*Task\s+(?:[\d.]+[:\s]+)?(.+)$/gim;
+    const explicitTasks = [];
+    let taskMatch;
+    const taskPositions = [];
+    // Find all task headers
+    while ((taskMatch = explicitTaskPattern.exec(plan)) !== null) {
+        const name = taskMatch[1].trim()
+            .replace(/^\*\*(.+)\*\*$/, '$1') // Remove bold
+            .replace(/^:/, '') // Remove leading colon
+            .trim();
+        if (name.length > 3 && isActionableTask(name)) {
+            taskPositions.push({
+                name,
+                index: taskMatch.index + taskMatch[0].length,
+                endIndex: plan.length, // Will be updated
+            });
+        }
+    }
+    // Update end indices
+    for (let i = 0; i < taskPositions.length - 1; i++) {
+        taskPositions[i].endIndex = taskPositions[i + 1].index - 50; // Approximate
+    }
+    // Extract task details
+    for (const pos of taskPositions) {
+        const content = plan.slice(pos.index, pos.endIndex);
+        const description = extractTaskDescription(content);
+        const criteria = extractAcceptanceCriteria(content);
+        explicitTasks.push({
+            name: pos.name,
+            description: description || pos.name,
+            testPlan: criteria.length > 0 ? criteria.join('\n') : undefined,
+        });
+    }
+    // Second pass: Look for milestone sections containing implementation tasks
+    const milestoneSectionPattern = /^#{1,3}\s*(?:Milestone|Phase|Sprint|Stage)\s*[\d.]*[:\s]+(.+)$/gim;
+    const milestoneMatches = [];
+    let msMatch;
+    while ((msMatch = milestoneSectionPattern.exec(plan)) !== null) {
+        milestoneMatches.push({
+            name: msMatch[1].trim().replace(/^\*\*(.+)\*\*$/, '$1'),
+            index: msMatch.index,
+        });
+    }
+    // Third pass: If no explicit tasks found, look for actionable bullet points
+    if (explicitTasks.length === 0) {
+        // Look for bullet points that start with actionable verbs
+        const bulletPattern = /^[-*+]\s+(.+)$/gm;
+        let bulletMatch;
+        while ((bulletMatch = bulletPattern.exec(plan)) !== null) {
+            const taskName = bulletMatch[1].trim()
+                .replace(/^\*\*(.+)\*\*:?\s*/, '$1: ')
+                .replace(/\*\*(.+)\*\*/g, '$1')
+                .slice(0, 200);
+            if (taskName.length >= 10 && isActionableTask(taskName)) {
+                explicitTasks.push({
+                    name: taskName,
+                    description: taskName,
+                });
+            }
+        }
+    }
+    // Fourth pass: If still no tasks, look for numbered implementation items
+    if (explicitTasks.length === 0) {
+        const numberedPattern = /^\d+[.)]\s+(.+)$/gm;
+        let numMatch;
+        while ((numMatch = numberedPattern.exec(plan)) !== null) {
+            const taskName = numMatch[1].trim()
+                .replace(/^\*\*(.+)\*\*:?\s*/, '$1: ')
+                .replace(/\*\*(.+)\*\*/g, '$1')
+                .slice(0, 200);
+            if (taskName.length >= 10 && isActionableTask(taskName)) {
+                explicitTasks.push({
                     name: taskName,
                     description: taskName,
                 });
             }
         }
-        if (tasks.length > 0 || name.toLowerCase().includes('milestone')) {
+    }
+    // Build milestones from collected data
+    if (milestoneMatches.length > 0 && explicitTasks.length > 0) {
+        // Distribute tasks to milestones based on position
+        const tasksPerMilestone = Math.ceil(explicitTasks.length / milestoneMatches.length);
+        for (let i = 0; i < milestoneMatches.length; i++) {
+            const startIdx = i * tasksPerMilestone;
+            const endIdx = Math.min(startIdx + tasksPerMilestone, explicitTasks.length);
+            const milestoneTasks = explicitTasks.slice(startIdx, endIdx);
+            if (milestoneTasks.length > 0) {
+                milestones.push({
+                    name: milestoneMatches[i].name,
+                    description: `Implementation phase ${i + 1}`,
+                    tasks: milestoneTasks,
+                    status: 'pending',
+                });
+            }
+        }
+    }
+    else if (explicitTasks.length > 0) {
+        // No milestone headers found, group tasks into phases
+        const tasksPerMilestone = 5;
+        for (let i = 0; i < explicitTasks.length; i += tasksPerMilestone) {
+            const milestoneTasks = explicitTasks.slice(i, i + tasksPerMilestone);
+            const milestoneNum = Math.floor(i / tasksPerMilestone) + 1;
             milestones.push({
-                name,
-                description: content.slice(0, 200).trim(),
-                tasks: tasks,
+                name: `Implementation Phase ${milestoneNum}`,
+                description: `Tasks ${i + 1} to ${Math.min(i + tasksPerMilestone, explicitTasks.length)}`,
+                tasks: milestoneTasks,
                 status: 'pending',
             });
         }
     }
-    // If no milestones found, create a default one
-    if (milestones.length === 0) {
-        milestones.push({
-            name: 'Implementation',
-            description: 'Main implementation milestone',
-            tasks: [],
-            status: 'pending',
-        });
+    else {
+        // Fifth pass: Look for any headers that might be tasks (less strict matching)
+        const anyHeaderPattern = /^#{2,4}\s+(.+)$/gm;
+        const headerTasks = [];
+        let headerMatch;
+        while ((headerMatch = anyHeaderPattern.exec(plan)) !== null) {
+            const name = headerMatch[1].trim()
+                .replace(/^\*\*(.+)\*\*$/, '$1')
+                .replace(/^[:*-]\s*/, '');
+            // Skip obvious non-task headers
+            const skipPatterns = [
+                /^(background|context|overview|introduction|summary)/i,
+                /^(goal|objective|requirement|risk|assumption)/i,
+                /^(timeline|schedule|test plan|acceptance)/i,
+                /^(table of contents|toc|appendix|reference)/i,
+                /^(project|specification|design|architecture)$/i,
+            ];
+            const shouldSkip = skipPatterns.some(p => p.test(name));
+            if (!shouldSkip && name.length >= 5 && name.length <= 200) {
+                headerTasks.push({
+                    name: name.slice(0, 100),
+                    description: name,
+                });
+            }
+        }
+        if (headerTasks.length >= 2) {
+            // Use headers as tasks, grouped into milestones
+            const tasksPerMilestone = 5;
+            for (let i = 0; i < headerTasks.length; i += tasksPerMilestone) {
+                const milestoneTasks = headerTasks.slice(i, i + tasksPerMilestone);
+                const milestoneNum = Math.floor(i / tasksPerMilestone) + 1;
+                milestones.push({
+                    name: `Implementation Phase ${milestoneNum}`,
+                    description: `Tasks ${i + 1} to ${Math.min(i + tasksPerMilestone, headerTasks.length)}`,
+                    tasks: milestoneTasks,
+                    status: 'pending',
+                });
+            }
+        }
+        else {
+            // Sixth pass: Parse any section with implementation keywords
+            const implKeywords = [
+                'implement', 'create', 'build', 'add', 'develop', 'write',
+                'set up', 'configure', 'design', 'test', 'api', 'component',
+                'service', 'module', 'function', 'class', 'feature',
+                'database', 'model', 'controller', 'view', 'route', 'endpoint',
+            ];
+            const lines = plan.split('\n');
+            const implTasks = [];
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (trimmed.length < 10 || trimmed.length > 200)
+                    continue;
+                const hasKeyword = implKeywords.some(kw => trimmed.toLowerCase().includes(kw));
+                // Check if it looks like an item (starts with bullet, number, or header)
+                const isItem = /^[-*+#\d.]/.test(trimmed) ||
+                    /^(Task|Step|Item|Feature|Component)/i.test(trimmed);
+                if (hasKeyword && isItem) {
+                    const name = trimmed
+                        .replace(/^[-*+#]+\s*/, '')
+                        .replace(/^\d+[.)]\s*/, '')
+                        .replace(/^\*\*(.+?)\*\*:?\s*/, '$1: ')
+                        .slice(0, 100);
+                    if (name.length >= 10 && !implTasks.some(t => t.name === name)) {
+                        implTasks.push({
+                            name,
+                            description: name,
+                        });
+                    }
+                }
+            }
+            if (implTasks.length > 0) {
+                // Group implementation tasks
+                const tasksPerMilestone = 5;
+                for (let i = 0; i < implTasks.length; i += tasksPerMilestone) {
+                    const milestoneTasks = implTasks.slice(i, i + tasksPerMilestone);
+                    const milestoneNum = Math.floor(i / tasksPerMilestone) + 1;
+                    milestones.push({
+                        name: `Implementation Phase ${milestoneNum}`,
+                        description: `Tasks ${i + 1} to ${Math.min(i + tasksPerMilestone, implTasks.length)}`,
+                        tasks: milestoneTasks,
+                        status: 'pending',
+                    });
+                }
+            }
+            else {
+                // Final fallback: Create structured tasks based on common project phases
+                // This should rarely happen if the plan is well-structured
+                console.warn('[plan-parser] Warning: Could not parse tasks from plan. Using default structure.');
+                milestones.push({
+                    name: 'Core Implementation',
+                    description: 'Implement core functionality based on the plan',
+                    tasks: [
+                        {
+                            name: 'Set up project structure and dependencies',
+                            description: 'Initialize project with required structure, dependencies, and configuration',
+                        },
+                        {
+                            name: 'Implement core features',
+                            description: 'Build the main features as described in the development plan',
+                        },
+                        {
+                            name: 'Add data models and storage',
+                            description: 'Create data models, database schema, and storage layer',
+                        },
+                    ],
+                    status: 'pending',
+                });
+                milestones.push({
+                    name: 'Integration and Testing',
+                    description: 'Connect components and verify functionality',
+                    tasks: [
+                        {
+                            name: 'Integrate components',
+                            description: 'Connect all components and ensure they work together',
+                        },
+                        {
+                            name: 'Write and run tests',
+                            description: 'Create unit tests, integration tests, and verify all tests pass',
+                        },
+                        {
+                            name: 'Final verification and documentation',
+                            description: 'Run final verification, update documentation, ensure project works correctly',
+                        },
+                    ],
+                    status: 'pending',
+                });
+            }
+        }
     }
     return milestones;
 }
@@ -146,38 +495,90 @@ export function parsePlanMilestones(plan) {
  * @returns Plan mode result
  */
 export async function runPlanMode(spec, options) {
-    const { projectDir, consensusConfig, onProgress } = options;
+    const { projectDir, consensusConfig, additionalContext, onProgress } = options;
+    // Initialize workflow logger
+    const logger = getWorkflowLogger(projectDir);
     try {
         // Create or load project
         onProgress?.('plan-init', 'Initializing project...');
+        await logger.stageStart('init', 'Plan Mode initialization', {
+            projectName: spec.name,
+            language: spec.language,
+            idea: spec.idea.slice(0, 200),
+        });
         let state;
         try {
             state = await loadProject(projectDir);
             onProgress?.('plan-init', 'Loaded existing project');
+            await logger.info('init', 'project_loaded', 'Loaded existing project', {
+                projectName: state.name,
+                phase: state.phase,
+                hasPlan: !!state.plan,
+                hasSpecification: !!state.specification,
+            });
         }
         catch {
             state = await createProject(spec, projectDir);
             onProgress?.('plan-init', 'Created new project');
+            await logger.success('init', 'project_created', 'Created new project', {
+                projectName: state.name,
+                language: state.language,
+            });
         }
         // Expand idea if we don't have a specification
         if (!state.specification) {
             onProgress?.('expand-idea', 'Expanding idea into specification...');
+            await logger.stageStart('plan-generation', 'Expanding idea into specification');
             const specification = await expandIdea(spec.idea, spec.language, (msg) => onProgress?.('expand-idea', msg));
             state = await storeSpecification(projectDir, specification);
             onProgress?.('expand-idea', 'Specification complete');
+            await logger.stageComplete('plan-generation', 'Specification created', {
+                specificationLength: specification.length,
+                specificationPreview: specification.slice(0, 300),
+            });
+        }
+        // Design UI early in the process
+        onProgress?.('ui-design', 'Designing UI from project idea...');
+        try {
+            const uiSpec = await designUI(spec.idea, (msg) => onProgress?.('ui-design', msg));
+            await saveUISpecification(projectDir, uiSpec);
+            onProgress?.('ui-design', `UI design complete: ${uiSpec.themeName} theme, ${uiSpec.recommendedComponents.length} components`);
+            await logger.success('ui-design', 'ui_design_complete', 'UI design specification created', {
+                theme: uiSpec.themeName,
+                projectType: uiSpec.projectType,
+                components: uiSpec.recommendedComponents.length,
+            });
+        }
+        catch (uiError) {
+            // Non-blocking - UI design failures shouldn't stop the workflow
+            onProgress?.('ui-design', `UI design skipped: ${uiError instanceof Error ? uiError.message : 'Unknown error'}`);
+            await logger.warn('ui-design', 'ui_design_skipped', 'UI design was skipped', {
+                error: uiError instanceof Error ? uiError.message : 'Unknown error',
+            });
         }
         // Get project context
         onProgress?.('get-context', 'Gathering project context...');
-        const context = await getProjectContext(projectDir, (msg) => onProgress?.('get-context', msg));
+        let context = await getProjectContext(projectDir, (msg) => onProgress?.('get-context', msg));
+        // Append additional context if provided (e.g., when resuming with guidance)
+        if (additionalContext) {
+            onProgress?.('get-context', 'Incorporating additional guidance...');
+            context = `${context}\n\nADDITIONAL GUIDANCE FROM USER:\n${additionalContext}`;
+        }
         // Create initial plan if we don't have one
         if (!state.plan) {
             onProgress?.('create-plan', 'Creating development plan...');
+            await logger.stageStart('plan-generation', 'Creating development plan');
             const plan = await createPlan(state.specification, context, (msg) => onProgress?.('create-plan', msg));
             state = await storePlan(projectDir, plan);
             onProgress?.('create-plan', 'Initial plan created');
+            await logger.stageComplete('plan-generation', 'Development plan created', {
+                planLength: plan.length,
+                planPreview: plan.slice(0, 500),
+            });
         }
         // Run consensus loop
         onProgress?.('consensus', 'Starting consensus review...');
+        await logger.stageStart('consensus', 'Starting consensus review process');
         const consensusResult = await iterateUntilConsensus(state.plan, context, {
             projectDir,
             config: consensusConfig,
@@ -187,21 +588,157 @@ export async function runPlanMode(spec, options) {
             onRevision: (iteration, _plan) => {
                 onProgress?.('consensus', `Revising plan (iteration ${iteration})...`);
             },
+            onConcerns: (concerns, recommendations) => {
+                if (concerns.length > 0) {
+                    onProgress?.('concerns', `Concerns: ${concerns.slice(0, 2).join('; ')}`);
+                }
+                if (recommendations.length > 0) {
+                    onProgress?.('recommendations', `Suggestions: ${recommendations.slice(0, 2).join('; ')}`);
+                }
+            },
+            onArbitration: (result) => {
+                onProgress?.('arbitration', `Arbitrator decision: ${result.approved ? 'APPROVED' : 'REVISE'} (${result.score}%)`);
+                if (!result.approved && result.suggestedChanges.length > 0) {
+                    onProgress?.('arbitration', `Changes: ${result.suggestedChanges.slice(0, 2).join('; ')}`);
+                }
+            },
+            onProgress,
         });
-        // Store final plan
+        // Log consensus result
+        await logger.info('consensus', 'consensus_complete', 'Consensus process completed', {
+            approved: consensusResult.approved,
+            finalScore: consensusResult.finalScore,
+            bestScore: consensusResult.bestScore,
+            totalIterations: consensusResult.totalIterations,
+            arbitrated: consensusResult.arbitrated,
+        });
+        // Check if the plan is garbage (Claude's thinking instead of actual content)
+        const garbageCheck = detectGarbagePlan(consensusResult.bestPlan);
+        if (garbageCheck.isGarbage) {
+            onProgress?.('error', `PLAN VALIDATION FAILED: ${garbageCheck.reason}`);
+            onProgress?.('error', 'The plan contains Claude\'s thinking/conversation instead of actual plan content.');
+            onProgress?.('info', 'This typically happens when Claude describes what it will do instead of outputting the plan.');
+            onProgress?.('info', 'Saving garbage plan for debugging. Try running again or provide more specific requirements.');
+            // Still save the plan for debugging
+            await documentPlan(projectDir, consensusResult.bestPlan, 'PLAN-FAILED.md');
+            await logger.stageFailed('plan-parsing', 'Plan validation', garbageCheck.reason, {
+                planLength: consensusResult.bestPlan.length,
+                reason: garbageCheck.reason,
+            });
+            return {
+                success: false,
+                state,
+                consensusResult,
+                error: `Plan generation failed: ${garbageCheck.reason}`,
+            };
+        }
+        // Always store the best plan (even if consensus failed)
+        state = await storePlan(projectDir, consensusResult.bestPlan);
+        // Parse and add milestones from best plan
+        await logger.stageStart('plan-parsing', 'Parsing plan into milestones and tasks');
+        const milestones = parsePlanMilestones(consensusResult.bestPlan);
+        // Log parsed milestones for debugging
+        const totalTasks = milestones.reduce((sum, m) => sum + m.tasks.length, 0);
+        onProgress?.('plan-structure', `Parsed plan: ${milestones.length} milestones, ${totalTasks} tasks`);
+        // Log detailed parsing results
+        const parsedMilestones = milestones.map(m => ({
+            name: m.name,
+            taskCount: m.tasks.length,
+            taskNames: m.tasks.map(t => t.name),
+        }));
+        await logger.info('plan-parsing', 'plan_parsed', 'Parsed plan structure', {
+            milestonesCount: milestones.length,
+            totalTasks: totalTasks,
+            milestones: parsedMilestones,
+        });
+        // VALIDATION: Fail if too few milestones/tasks for a real project
+        if (milestones.length <= 1 && totalTasks <= 2) {
+            onProgress?.('error', `PLAN VALIDATION FAILED: Only ${milestones.length} milestone(s) and ${totalTasks} task(s) extracted.`);
+            onProgress?.('error', 'A valid plan should have at least 2 milestones with 3+ tasks each.');
+            onProgress?.('info', 'Expected format: "## Milestone N: Name" and "### Task N.N: Name"');
+            // Save the problematic plan for debugging
+            await documentPlan(projectDir, consensusResult.bestPlan, 'PLAN-INSUFFICIENT.md');
+            // Show what was found in the plan
+            onProgress?.('debug', 'Tasks extracted from plan:');
+            for (const m of milestones) {
+                for (const t of m.tasks) {
+                    onProgress?.('debug', `  - ${t.name}`);
+                }
+            }
+            await logger.stageFailed('plan-parsing', 'Plan validation', 'Insufficient tasks extracted', {
+                milestonesCount: milestones.length,
+                totalTasks: totalTasks,
+                expectedMinTasks: 3,
+                extractedTasks: milestones.flatMap(m => m.tasks.map(t => t.name)),
+            });
+            return {
+                success: false,
+                state,
+                consensusResult,
+                error: `Plan parsing failed: only ${totalTasks} task(s) extracted. Plan needs more structure.`,
+            };
+        }
+        // Warn if suspiciously few tasks (but don't block)
+        if (milestones.length <= 2 || totalTasks <= 5) {
+            onProgress?.('warning', `Warning: Only ${milestones.length} milestone(s) and ${totalTasks} task(s) parsed. ` +
+                `This seems low for a complete project. Consider reviewing the plan.`);
+        }
+        // Log each milestone and its tasks
+        for (const milestone of milestones) {
+            onProgress?.('plan-detail', `  Milestone: ${milestone.name} (${milestone.tasks.length} tasks)`);
+            for (const task of milestone.tasks.slice(0, 3)) {
+                onProgress?.('plan-detail', `    - ${task.name}`);
+            }
+            if (milestone.tasks.length > 3) {
+                onProgress?.('plan-detail', `    ... and ${milestone.tasks.length - 3} more tasks`);
+            }
+        }
+        state = await addMilestones(projectDir, milestones);
+        // Always document the plan (so user can see what was achieved)
+        const planFilename = consensusResult.approved ? 'PLAN.md' : 'PLAN-DRAFT.md';
+        await documentPlan(projectDir, consensusResult.bestPlan, planFilename);
         if (consensusResult.approved) {
-            state = await storePlan(projectDir, consensusResult.finalPlan);
-            // Parse and add milestones
-            const milestones = parsePlanMilestones(consensusResult.finalPlan);
-            state = await addMilestones(projectDir, milestones);
-            // Document the plan
-            await documentPlan(projectDir, consensusResult.finalPlan);
             // Transition to execution phase
             state = await setPhase(projectDir, 'execution');
-            onProgress?.('complete', `Plan approved with ${consensusResult.finalScore}% consensus`);
+            if (consensusResult.arbitrated) {
+                onProgress?.('complete', `Plan approved via arbitration with ${consensusResult.finalScore}% confidence`);
+            }
+            else {
+                onProgress?.('complete', `Plan approved with ${consensusResult.finalScore}% consensus`);
+            }
+            onProgress?.('info', `Plan saved to docs/PLAN.md`);
+            await logger.stageComplete('plan-generation', 'Plan Mode completed successfully', {
+                consensusScore: consensusResult.finalScore,
+                arbitrated: consensusResult.arbitrated,
+                milestonesCount: milestones.length,
+                totalTasks: totalTasks,
+                nextPhase: 'execution',
+            });
         }
         else {
-            onProgress?.('failed', `Consensus not reached after ${consensusResult.totalIterations} iterations (${consensusResult.finalScore}%)`);
+            // Show why consensus failed
+            onProgress?.('failed', `Consensus not reached after ${consensusResult.totalIterations} iterations (best: ${consensusResult.bestScore}% at iteration ${consensusResult.bestIteration})`);
+            // Show remaining concerns
+            if (consensusResult.finalConcerns.length > 0) {
+                onProgress?.('concerns', `Remaining concerns:`);
+                for (const concern of consensusResult.finalConcerns.slice(0, 3)) {
+                    onProgress?.('concerns', `  - ${concern}`);
+                }
+            }
+            // Show recommendations
+            if (consensusResult.finalRecommendations.length > 0) {
+                onProgress?.('recommendations', `Recommendations:`);
+                for (const rec of consensusResult.finalRecommendations.slice(0, 3)) {
+                    onProgress?.('recommendations', `  - ${rec}`);
+                }
+            }
+            onProgress?.('info', `Draft plan saved to docs/${planFilename}`);
+            await logger.warn('plan-generation', 'consensus_failed', 'Plan Mode incomplete - consensus not reached', {
+                bestScore: consensusResult.bestScore,
+                totalIterations: consensusResult.totalIterations,
+                finalConcerns: consensusResult.finalConcerns,
+                finalRecommendations: consensusResult.finalRecommendations,
+            });
         }
         return {
             success: consensusResult.approved,
@@ -212,6 +749,11 @@ export async function runPlanMode(spec, options) {
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : 'Unknown error';
         onProgress?.('error', errorMessage);
+        // Log the error
+        await logger.stageFailed('plan-generation', 'Plan Mode execution', errorMessage, {
+            errorType: error instanceof Error ? error.constructor.name : typeof error,
+            stack: error instanceof Error ? error.stack : undefined,
+        });
         return {
             success: false,
             state: await loadProject(projectDir).catch(() => ({})),