popeye-cli 1.0.0 → 1.1.0

package/src/workflow/plan-mode.ts

@@ -19,6 +19,8 @@ import {
   addMilestones,
 } from '../state/index.js';
 import { iterateUntilConsensus, type ConsensusProcessResult } from './consensus.js';
+import { getWorkflowLogger } from './workflow-logger.js';
+import { designUI, saveUISpecification } from './ui-designer.js';
 
 /**
  * Options for plan mode
@@ -26,6 +28,7 @@ import { iterateUntilConsensus, type ConsensusProcessResult } from './consensus.
 export interface PlanModeOptions {
   projectDir: string;
   consensusConfig?: Partial<ConsensusConfig>;
+  additionalContext?: string;
   onProgress?: (phase: string, message: string) => void;
 }
 
@@ -75,7 +78,7 @@ export async function createPlan(
 ): Promise<string> {
   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}`);
@@ -110,7 +113,7 @@ export async function getProjectContext(
       return 'New project - no existing codebase';
     }
 
-    const result = await analyzeCodebase(projectDir);
+    const result = await analyzeCodebase(projectDir, onProgress);
 
     if (result.success) {
       onProgress?.('Codebase analysis complete');
@@ -124,7 +127,7 @@ export async function getProjectContext(
 }
 
 /**
- * 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
@@ -135,7 +138,15 @@ export async function documentPlan(
   plan: string,
   filename: string = 'PLAN.md'
 ): Promise<string> {
-  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
 
@@ -145,11 +156,174 @@ ${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: string): boolean {
+  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: string): string {
+  // 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: string): string[] {
+  const criteria: string[] = [];
+
+  // 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: string): { isGarbage: boolean; reason?: string } {
+  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
@@ -157,54 +331,278 @@ ${plan}
 export function parsePlanMilestones(plan: string): Omit<Milestone, 'id'>[] {
   const milestones: Omit<Milestone, 'id'>[] = [];
 
-  // 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;
+  // 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: Array<{ name: string; description: string; testPlan?: string }> = [];
+
+  let taskMatch;
+  const taskPositions: Array<{ name: string; index: number; endIndex: number }> = [];
+
+  // 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
+  }
 
-    const tasks: Omit<Task, 'id' | 'status' | 'testsPassed'>[] = [];
-    let taskMatch;
+  // Extract task details
+  for (const pos of taskPositions) {
+    const content = plan.slice(pos.index, pos.endIndex);
+    const description = extractTaskDescription(content);
+    const criteria = extractAcceptanceCriteria(content);
 
-    while ((taskMatch = taskPattern.exec(content)) !== null) {
-      const taskName = taskMatch[1].trim();
-      if (taskName && !taskName.toLowerCase().startsWith('test')) {
-        tasks.push({
+    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: Array<{ name: string; index: number }> = [];
+
+  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,
+        });
+      }
+    }
+  }
+
+  // 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 as Task[],
+          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;
 
-    if (tasks.length > 0 || name.toLowerCase().includes('milestone')) {
       milestones.push({
-        name,
-        description: content.slice(0, 200).trim(),
-        tasks: tasks as Task[],
+        name: `Implementation Phase ${milestoneNum}`,
+        description: `Tasks ${i + 1} to ${Math.min(i + tasksPerMilestone, explicitTasks.length)}`,
+        tasks: milestoneTasks as Task[],
         status: 'pending',
       });
     }
-  }
+  } else {
+    // Fifth pass: Look for any headers that might be tasks (less strict matching)
+    const anyHeaderPattern = /^#{2,4}\s+(.+)$/gm;
+    const headerTasks: Array<{ name: string; description: string }> = [];
+    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 no milestones found, create a default one
-  if (milestones.length === 0) {
-    milestones.push({
-      name: 'Implementation',
-      description: 'Main implementation milestone',
-      tasks: [],
-      status: 'pending',
-    });
+    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 as Task[],
+          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: Array<{ name: string; description: string }> = [];
+
+      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 as Task[],
+            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',
+            },
+          ] as Task[],
+          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',
+            },
+          ] as Task[],
+          status: 'pending',
+        });
+      }
+    }
   }
 
   return milestones;
@@ -221,24 +619,44 @@ export async function runPlanMode(
   spec: ProjectSpec,
   options: PlanModeOptions
 ): Promise<PlanModeResult> {
-  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: ProjectState;
     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,
@@ -247,18 +665,49 @@ export async function runPlanMode(
 
       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(
+    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,
@@ -267,10 +716,16 @@ export async function runPlanMode(
 
       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,
@@ -286,29 +741,214 @@ export async function runPlanMode(
         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
-    if (consensusResult.approved) {
-      state = await storePlan(projectDir, consensusResult.finalPlan);
+    // 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,
+    });
 
-      // Parse and add milestones
-      const milestones = parsePlanMilestones(consensusResult.finalPlan);
-      state = await addMilestones(projectDir, milestones);
+    // 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}`,
+      };
+    }
 
-      // Document the plan
-      await documentPlan(projectDir, consensusResult.finalPlan);
+    // 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) {
       // 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 {
+      // Show why consensus failed
       onProgress?.(
         'failed',
-        `Consensus not reached after ${consensusResult.totalIterations} iterations (${consensusResult.finalScore}%)`
+        `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 {
@@ -320,6 +960,12 @@ export async function runPlanMode(
     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(() => ({} as ProjectState)),