brain-dev 1.2.6 → 2.0.0

package/bin/lib/commands/auto.cjs

@@ -242,10 +242,19 @@ function buildInstructions(runbook, brainDir) {
     lines.push('');
   }
 
-  lines.push('### Error Handling');
-  lines.push('- If any step fails, retry once. If it fails again, run: `npx brain-dev auto --stop`');
-  lines.push('- Budget check: run `npx brain-dev progress --cost` between phases');
-  lines.push('- Timeout check: run `npx brain-dev progress --stuck` if a step takes too long');
+  lines.push('### Error Recovery Decision Tree');
+  lines.push('');
+  lines.push('If a step fails, use this decision tree:');
+  lines.push('');
+  lines.push('1. **Test failure**: Re-run `npx brain-dev execute --plan <failed-plan-id>` targeting the specific plan');
+  lines.push('2. **Stuck/timeout**: Run `npx brain-dev recover --fix` to clear lock and resume');
+  lines.push('3. **Budget exceeded**: Run `npx brain-dev auto --stop` and report to user');
+  lines.push('4. **Verification gaps_found**: Re-run execute for the gap files, then re-verify');
+  lines.push('5. **Same step fails 2 times**: Stop auto mode — `npx brain-dev auto --stop`');
+  lines.push('');
+  lines.push('**Loop guard**: If the same step is attempted 3 times, stop auto mode with LOOP DETECTED status.');
+  lines.push('');
+  lines.push('Between each step, check: `npx brain-dev progress --cost` for budget status.');
   lines.push('');
   lines.push('### Completion');
   lines.push('- When all phases complete or auto stops, run: `npx brain-dev auto --stop` to release the lock');

package/bin/lib/commands/discuss.cjs

@@ -6,6 +6,7 @@ const { readState, writeState, atomicWriteSync } = require('../state.cjs');
 const { parseRoadmap } = require('../roadmap.cjs');
 const { loadTemplate, interpolate } = require('../templates.cjs');
 const { output, error, success } = require('../core.cjs');
+const { generateExpertise } = require('../stack-expert.cjs');
 
 /**
  * Find the phase directory under .brain/phases/ matching a phase number.
@@ -126,7 +127,8 @@ function handleAnalyze(args, brainDir, state) {
     phase_name: phase.name,
     phase_goal: phase.goal,
     phase_requirements: (Array.isArray(phase.requirements) ? phase.requirements.join(', ') : '') || 'None specified',
-    research_section: researchSection
+    research_section: researchSection,
+    stack_expertise: generateExpertise(brainDir, 'planner')
   });
 
   // Update status to discussing

package/bin/lib/commands/new-project.cjs

@@ -7,6 +7,41 @@ const { detectProject } = require('../detect.cjs');
 const { output, error } = require('../core.cjs');
 const { readDetection } = require('../story-helpers.cjs');
 
+/**
+ * Build detailed detection breakdown lines for human display.
+ * @param {object} detection
+ * @returns {string[]}
+ */
+function buildDetectionDetails(detection) {
+  if (!detection || detection.type === 'greenfield') return [];
+
+  const lines = [];
+  const stack = detection.stack || {};
+  const primary = stack.primary || {};
+  const frontend = stack.frontend || {};
+
+  if (primary.language || primary.framework) {
+    const parts = [primary.language, primary.framework, primary.runtime].filter(Boolean);
+    lines.push(`[brain]   Stack: ${parts.join(' + ')}`);
+  }
+  if (frontend.framework) {
+    lines.push(`[brain]   Frontend: ${frontend.framework}${frontend.bundler ? ' (' + frontend.bundler + ')' : ''}`);
+  }
+  if (detection.features && detection.features.length > 0) {
+    lines.push(`[brain]   Features: ${detection.features.slice(0, 6).join(', ')}`);
+  }
+  if (detection.signals) {
+    if (detection.signals.codeFiles) {
+      lines.push(`[brain]   Source files: ${detection.signals.codeFiles}`);
+    }
+    if (detection.signals.commitCount) {
+      lines.push(`[brain]   Git commits: ${detection.signals.commitCount}`);
+    }
+  }
+
+  return lines;
+}
+
 /**
  * Run the new-project command.
  * Simplified 2-step flow:
@@ -82,8 +117,12 @@ function stepQuestions(brainDir, rootDir) {
     ? `Brain detected your existing ${detection.summary}.`
     : 'No existing code detected — starting fresh.';
 
+  // Build detailed detection breakdown
+  const detailLines = buildDetectionDetails(detection);
+
   const humanText = [
     `[brain] ${detectionSummary}`,
+    ...detailLines,
     '',
     'IMPORTANT: Use the AskUserQuestion tool NOW to ask the user what they want to do.',
     'Do NOT print the options as text. Use AskUserQuestion with these exact parameters:',

package/bin/lib/commands/new-task.cjs

@@ -263,7 +263,13 @@ function handleContinue(brainDir, state) {
   }
 
   const taskDir = path.join(tasksDir, dirs[0]);
-  const taskMeta = JSON.parse(fs.readFileSync(path.join(taskDir, 'task.json'), 'utf8'));
+  let taskMeta;
+  try {
+    taskMeta = JSON.parse(fs.readFileSync(path.join(taskDir, 'task.json'), 'utf8'));
+  } catch {
+    error('Corrupt task.json. Delete the task directory and recreate.');
+    return { error: 'corrupt-task-meta' };
+  }
 
   // Determine current step based on what files exist
   const hasContext = fs.existsSync(path.join(taskDir, 'CONTEXT.md'));
@@ -406,7 +412,13 @@ function handlePromote(brainDir, state, taskNum) {
   }
 
   const taskDir = path.join(tasksDir, dirs[0]);
-  const taskMeta = JSON.parse(fs.readFileSync(path.join(taskDir, 'task.json'), 'utf8'));
+  let taskMeta;
+  try {
+    taskMeta = JSON.parse(fs.readFileSync(path.join(taskDir, 'task.json'), 'utf8'));
+  } catch {
+    error('Corrupt task.json. Cannot promote.');
+    return { error: 'corrupt-task-meta' };
+  }
 
   // Insert as a new phase after current phase
   try {

package/bin/lib/commands/pause.cjs

@@ -5,6 +5,95 @@ const path = require('node:path');
 const { readState, writeState, atomicWriteSync } = require('../state.cjs');
 const { output, prefix, success, error } = require('../core.cjs');
 
+/**
+ * Read CONTEXT.md from current phase directory.
+ * Extracts locked decisions and specific approaches sections.
+ * @param {object} state
+ * @returns {string|null}
+ */
+function readPhaseContext(state) {
+  const phase = state.phase || {};
+  const phaseNumber = phase.current || 0;
+  if (!phaseNumber) return null;
+
+  const padded = String(phaseNumber).padStart(2, '0');
+  const phasesDir = path.join(process.cwd(), '.brain', 'phases');
+  if (!fs.existsSync(phasesDir)) return null;
+
+  const dirs = fs.readdirSync(phasesDir).filter(d => d.startsWith(padded + '-'));
+  if (dirs.length === 0) return null;
+
+  const contextPath = path.join(phasesDir, dirs[0], 'CONTEXT.md');
+  if (!fs.existsSync(contextPath)) return null;
+
+  try {
+    const content = fs.readFileSync(contextPath, 'utf8');
+    // Extract key sections (decisions, approaches) — truncate to keep snapshot manageable
+    const lines = content.split('\n');
+    const extracted = [];
+    let inSection = false;
+    for (const line of lines) {
+      if (line.match(/^##?\s+(decision|locked|approach|specific)/i)) {
+        inSection = true;
+      } else if (line.match(/^##?\s+/) && inSection) {
+        inSection = false;
+      }
+      if (inSection) extracted.push(line);
+    }
+    return extracted.length > 0 ? extracted.join('\n').trim() : content.slice(0, 1500);
+  } catch { return null; }
+}
+
+/**
+ * Read current plan's must_haves and progress from the active phase.
+ * @param {object} state
+ * @returns {string|null}
+ */
+function readCurrentPlanState(state) {
+  const phase = state.phase || {};
+  const phaseNumber = phase.current || 0;
+  if (!phaseNumber) return null;
+
+  const padded = String(phaseNumber).padStart(2, '0');
+  const phasesDir = path.join(process.cwd(), '.brain', 'phases');
+  if (!fs.existsSync(phasesDir)) return null;
+
+  const dirs = fs.readdirSync(phasesDir).filter(d => d.startsWith(padded + '-'));
+  if (dirs.length === 0) return null;
+
+  const phaseDir = path.join(phasesDir, dirs[0]);
+  try {
+    const files = fs.readdirSync(phaseDir);
+    const planFiles = files.filter(f => f.startsWith('PLAN')).sort();
+    const summaryFiles = files.filter(f => f.toUpperCase().startsWith('SUMMARY')).sort();
+
+    const lines = [];
+    lines.push(`- Phase: ${phaseNumber} (${phase.status || 'unknown'})`);
+    lines.push(`- Plans: ${planFiles.length} total, ${summaryFiles.length} completed`);
+
+    // Extract must_haves from the latest incomplete plan
+    for (const planFile of planFiles) {
+      const planNum = planFile.match(/PLAN-(\d+)/)?.[1];
+      const hasSummary = summaryFiles.some(s => s.includes(planNum));
+      if (!hasSummary && planNum) {
+        const planContent = fs.readFileSync(path.join(phaseDir, planFile), 'utf8');
+        // Extract truths from must_haves
+        const truthMatch = planContent.match(/truths:\s*\n((?:\s+-\s+.+\n?)+)/);
+        if (truthMatch) {
+          lines.push(`- Active plan: ${planFile}`);
+          lines.push('- Must-haves:');
+          for (const truth of truthMatch[1].split('\n').filter(l => l.trim().startsWith('-'))) {
+            lines.push(`  ${truth.trim()}`);
+          }
+        }
+        break; // Only show first incomplete plan
+      }
+    }
+
+    return lines.join('\n');
+  } catch { return null; }
+}
+
 /**
  * Parse --note flag from args.
  * @param {string[]} args
@@ -72,11 +161,44 @@ function generateSnapshot(state, note) {
   }
   lines.push('');
 
-  // Decisions Made
+  // Decisions Made — inline actual CONTEXT.md content
   lines.push('## Decisions Made');
-  lines.push('- See .brain/brain.json for full state');
+  const contextContent = readPhaseContext(state);
+  if (contextContent) {
+    lines.push(contextContent);
+  } else {
+    lines.push('- No decisions recorded yet');
+  }
+  lines.push('');
+
+  // Current Plan State
+  lines.push('## Current Plan State');
+  const planState = readCurrentPlanState(state);
+  if (planState) {
+    lines.push(planState);
+  } else {
+    lines.push('- No active plan');
+  }
   lines.push('');
 
+  // Active Story/Task
+  if (state.stories?.active?.length > 0) {
+    const story = state.stories.active[0];
+    lines.push('## Active Story');
+    lines.push(`- Slug: ${story.slug || 'unknown'}`);
+    lines.push(`- Title: ${story.title || story.slug || 'unknown'}`);
+    lines.push(`- Step: ${story.step || 'unknown'}`);
+    lines.push('');
+  }
+  if (state.tasks?.active?.length > 0) {
+    const task = state.tasks.active[0];
+    lines.push('## Active Task');
+    lines.push(`- Slug: ${task.slug || 'unknown'}`);
+    lines.push(`- Title: ${task.title || task.slug || 'unknown'}`);
+    lines.push(`- Step: ${task.step || 'unknown'}`);
+    lines.push('');
+  }
+
   // Conversation Summary
   lines.push('## Conversation Summary');
   lines.push('<!-- Claude: summarize the current conversation context here when presenting to user -->');
@@ -119,8 +241,6 @@ async function run(args = [], opts = {}) {
   if (!fs.existsSync(sessionsDir)) {
     fs.mkdirSync(sessionsDir, { recursive: true });
   }
-  const sessionFileName = now.replace(/:/g, '-').replace(/\.\d+Z$/, 'Z') + '.md';
-  // Simplify to safe filename
   const safeFileName = now.slice(0, 19).replace(/:/g, '-') + '.md';
   fs.copyFileSync(snapshotPath, path.join(sessionsDir, safeFileName));
 

package/bin/lib/commands/plan.cjs

@@ -56,6 +56,100 @@ function readResearchSummary(brainDir, phaseNumber) {
   return fs.readFileSync(summaryPath, 'utf8');
 }
 
+/**
+ * Check if existing plans in a phase contradict CONTEXT.md decisions.
+ * Performs keyword matching between locked decisions/deferred items and plan task content.
+ * @param {string} brainDir
+ * @param {number} phaseNumber
+ * @returns {string|null} Warning message if violations found, null otherwise
+ */
+function checkContextCompliance(brainDir, phaseNumber) {
+  const contextContent = readContext(brainDir, phaseNumber);
+  if (!contextContent) return null;
+
+  const phaseDir = findPhaseDir(brainDir, phaseNumber);
+  if (!phaseDir) return null;
+
+  // Read existing plan files
+  let planContent = '';
+  try {
+    const files = fs.readdirSync(phaseDir).filter(f => /^PLAN-\d+\.md$/.test(f));
+    for (const f of files) {
+      planContent += fs.readFileSync(path.join(phaseDir, f), 'utf8') + '\n';
+    }
+  } catch { /* no plans yet */ }
+
+  if (!planContent) return null;
+
+  const warnings = [];
+  const planLower = planContent.toLowerCase();
+
+  // Parse locked decisions from CONTEXT.md
+  const decisionMatch = contextContent.match(/locked\s+decisions?[\s\S]*?(?=##|$)/i);
+  if (decisionMatch) {
+    const decisions = decisionMatch[0].split('\n').filter(l => l.trim().startsWith('-'));
+    for (const decision of decisions) {
+      // Extract technology choices from decisions (e.g., "use PostgreSQL", "JWT-based auth")
+      const techWords = decision.match(/\b(PostgreSQL|MySQL|MongoDB|Redis|JWT|session|REST|GraphQL|React|Vue|Angular|Express|FastAPI|Django|Laravel)\b/gi);
+      if (!techWords) continue;
+
+      for (const tech of techWords) {
+        // Check for contradicting alternatives in plans
+        const alternatives = getAlternatives(tech.toLowerCase());
+        for (const alt of alternatives) {
+          if (planLower.includes(alt.toLowerCase())) {
+            warnings.push(`Decision says "${tech}" but plan references "${alt}"`);
+          }
+        }
+      }
+    }
+  }
+
+  // Parse deferred items from CONTEXT.md
+  const deferredMatch = contextContent.match(/deferred[\s\S]*?(?=##|$)/i);
+  if (deferredMatch) {
+    const deferred = deferredMatch[0].split('\n').filter(l => l.trim().startsWith('-'));
+    for (const item of deferred) {
+      const keywords = item.replace(/^[\s-]+/, '').split(/\s+/).filter(w => w.length > 4).slice(0, 3);
+      for (const kw of keywords) {
+        if (planLower.includes(kw.toLowerCase())) {
+          warnings.push(`Deferred item mentions "${kw}" but it appears in current plans`);
+          break;
+        }
+      }
+    }
+  }
+
+  if (warnings.length === 0) return null;
+  return warnings.map(w => `> - ${w}`).join('\n');
+}
+
+/**
+ * Get common alternative technologies for contradiction detection.
+ * @param {string} tech
+ * @returns {string[]}
+ */
+function getAlternatives(tech) {
+  const map = {
+    postgresql: ['mongodb', 'mysql', 'sqlite', 'dynamodb'],
+    mysql: ['postgresql', 'mongodb', 'sqlite'],
+    mongodb: ['postgresql', 'mysql', 'sqlite'],
+    redis: ['memcached'],
+    jwt: ['session', 'cookie-based', 'oauth'],
+    session: ['jwt', 'token-based'],
+    rest: ['graphql', 'grpc', 'trpc'],
+    graphql: ['rest', 'grpc'],
+    react: ['vue', 'angular', 'svelte'],
+    vue: ['react', 'angular', 'svelte'],
+    angular: ['react', 'vue', 'svelte'],
+    express: ['fastify', 'koa', 'hapi'],
+    fastapi: ['django', 'flask'],
+    django: ['fastapi', 'flask'],
+    laravel: ['symfony', 'lumen']
+  };
+  return map[tech] || [];
+}
+
 /**
  * Generate the planner prompt for a single phase.
  * @param {object} phase - Phase data from roadmap
@@ -174,6 +268,9 @@ function handleSingle(args, brainDir, state) {
 
   const { prompt, output_dir } = generatePlannerPrompt(phase, brainDir);
 
+  // Context compliance pre-check: warn if existing plans contradict CONTEXT.md decisions
+  const complianceWarning = checkContextCompliance(brainDir, phaseNumber);
+
   // Get planner agent metadata and resolve model
   const plannerAgent = getAgent('planner');
   const model = resolveModel('planner', state);
@@ -185,8 +282,11 @@ function handleSingle(args, brainDir, state) {
     plan: 'all'
   });
 
-  // Append checker loop instruction
-  const checkerInstruction = '\n\n> After plans are generated, plan-checker will validate. Be prepared for revision requests. Max 5 checker iterations before deadlock analysis.';
+  // Append checker loop instruction + compliance warning
+  let checkerInstruction = '\n\n> After plans are generated, plan-checker will validate. Be prepared for revision requests. Max 5 checker iterations before deadlock analysis.';
+  if (complianceWarning) {
+    checkerInstruction += `\n\n> **CONTEXT COMPLIANCE WARNING:**\n${complianceWarning}`;
+  }
   const fullPrompt = prompt + checkerInstruction;
 
   // Update state: phase status = "planning"

package/bin/lib/commands/progress.cjs

@@ -24,6 +24,14 @@ function nextAction(state) {
     return '/brain:complete';
   }
 
+  // Check for active tasks/stories that take priority
+  if (state.tasks?.active?.length > 0) {
+    return '/brain:new-task --continue';
+  }
+  if (state.stories?.active?.length > 0) {
+    return '/brain:story --continue';
+  }
+
   // Route based on current phase status
   switch (phase.status) {
     case 'initialized':
@@ -33,8 +41,11 @@ function nextAction(state) {
     case 'discussing':
     case 'discussed':
       return '/brain:plan';
+    case 'ready':
+      return '/brain:discuss';
     case 'planning':
-      return '/brain:execute';
+    case 'planned':
+      return '/brain:plan';
     case 'executing':
       return '/brain:execute';
     case 'executed':
@@ -44,7 +55,12 @@ function nextAction(state) {
     case 'verified':
       return '/brain:complete';
     case 'verification-failed':
+    case 'partial':
       return '/brain:execute';
+    case 'failed':
+      return '/brain:recover';
+    case 'paused':
+      return '/brain:resume';
     case 'complete':
       return '/brain:complete';
     default:

package/bin/lib/commands/resume.cjs

@@ -76,6 +76,37 @@ function parseSections(body) {
   return sections;
 }
 
+/**
+ * Build list of context files the resumed agent should read.
+ * @param {string} brainDir
+ * @param {number|string} phaseNumber
+ * @returns {string[]} Paths relative to .brain/
+ */
+function buildContextFilesList(brainDir, phaseNumber) {
+  const files = [];
+  const stateMdPath = path.join(brainDir, 'STATE.md');
+  if (fs.existsSync(stateMdPath)) files.push('.brain/STATE.md');
+
+  if (phaseNumber) {
+    const padded = String(phaseNumber).padStart(2, '0');
+    const phasesDir = path.join(brainDir, 'phases');
+    if (fs.existsSync(phasesDir)) {
+      const dirs = fs.readdirSync(phasesDir).filter(d => d.startsWith(padded + '-'));
+      if (dirs.length > 0) {
+        const phaseDir = path.join(phasesDir, dirs[0]);
+        const phaseFiles = fs.readdirSync(phaseDir);
+        for (const f of phaseFiles) {
+          if (f === 'CONTEXT.md' || f.startsWith('PLAN') || f.toUpperCase().startsWith('SUMMARY')) {
+            files.push(`.brain/phases/${dirs[0]}/${f}`);
+          }
+        }
+      }
+    }
+  }
+
+  return files;
+}
+
 /**
  * Run the resume command.
  * @param {string[]} args - CLI arguments
@@ -179,14 +210,32 @@ async function run(args = [], opts = {}) {
     }
     briefingLines.push('');
   }
+  if (sections.decisionsMade && sections.decisionsMade !== '- No decisions recorded yet') {
+    briefingLines.push(prefix('Decisions:'));
+    for (const line of sections.decisionsMade.split('\n').filter(l => l.trim()).slice(0, 10)) {
+      briefingLines.push(`  ${line}`);
+    }
+    briefingLines.push('');
+  }
+  if (sections.currentPlanState && sections.currentPlanState !== '- No active plan') {
+    briefingLines.push(prefix('Plan State:'));
+    for (const line of sections.currentPlanState.split('\n').filter(l => l.trim())) {
+      briefingLines.push(`  ${line}`);
+    }
+    briefingLines.push('');
+  }
   if (sections.nextAction) {
     briefingLines.push(prefix(`Next: ${sections.nextAction}`));
   }
 
+  // Build contextFiles list for the resumed agent to read
+  const contextFiles = buildContextFilesList(brainDir, frontmatter.phase);
+
   const result = {
     briefing: true,
     snapshot: { frontmatter, sections },
-    source: snapshotSource
+    source: snapshotSource,
+    contextFiles
   };
 
   output(result, briefingLines.join('\n'));

package/bin/lib/commands/story.cjs

@@ -196,7 +196,13 @@ function handleAnswers(brainDir, state, answersJson) {
 
   // Update story.json
   const storyMetaPath = path.join(storyDir, 'story.json');
-  const storyMeta = JSON.parse(fs.readFileSync(storyMetaPath, 'utf8'));
+  let storyMeta;
+  try {
+    storyMeta = JSON.parse(fs.readFileSync(storyMetaPath, 'utf8'));
+  } catch {
+    error('Corrupt story.json. Cannot continue story.');
+    return { error: 'corrupt-story-meta' };
+  }
   storyMeta.status = 'initialized';
   storyMeta.answersReceived = new Date().toISOString();
   fs.writeFileSync(storyMetaPath, JSON.stringify(storyMeta, null, 2));
@@ -248,7 +254,13 @@ function handleContinue(brainDir, state, values) {
   }
 
   const storyMetaPath = path.join(storyDir, 'story.json');
-  const storyMeta = JSON.parse(fs.readFileSync(storyMetaPath, 'utf8'));
+  let storyMeta;
+  try {
+    storyMeta = JSON.parse(fs.readFileSync(storyMetaPath, 'utf8'));
+  } catch {
+    error('Corrupt story.json. Cannot continue story.');
+    return { error: 'corrupt-story-meta' };
+  }
 
   // File-existence based step detection
   const hasProjectMd = fs.existsSync(path.join(storyDir, 'PROJECT.md'));
@@ -752,7 +764,13 @@ function handleComplete(brainDir, state) {
   }
 
   const storyMetaPath = path.join(storyDir, 'story.json');
-  const storyMeta = JSON.parse(fs.readFileSync(storyMetaPath, 'utf8'));
+  let storyMeta;
+  try {
+    storyMeta = JSON.parse(fs.readFileSync(storyMetaPath, 'utf8'));
+  } catch {
+    error('Corrupt story.json. Cannot complete story.');
+    return { error: 'corrupt-story-meta' };
+  }
 
   // Check if all phases are complete
   const allPhasesComplete = state.phase && Array.isArray(state.phase.phases) &&
@@ -901,7 +919,13 @@ function handleStatus(brainDir, state) {
   }
 
   const storyMetaPath = path.join(storyDir, 'story.json');
-  const storyMeta = JSON.parse(fs.readFileSync(storyMetaPath, 'utf8'));
+  let storyMeta;
+  try {
+    storyMeta = JSON.parse(fs.readFileSync(storyMetaPath, 'utf8'));
+  } catch {
+    error('Corrupt story.json. Cannot read story status.');
+    return { error: 'corrupt-story-meta' };
+  }
 
   // Determine step progress
   const steps = [];

package/bin/lib/commands/update.cjs

@@ -125,7 +125,10 @@ async function run(args = [], opts = {}) {
   // 9. Update .gitignore
   updateGitignore(brainDir);
 
-  // 10. Report
+  // 10. Clear update notification cache (notification should disappear after update)
+  try { fs.unlinkSync(path.join(brainDir, '.update-check.json')); } catch {}
+
+  // 11. Report
   const isUpgrade = installedVersion !== packageVersion;
   const msg = isUpgrade
     ? `Updated brain-dev v${installedVersion} → v${packageVersion}. State preserved. Backup: brain.json.pre-update`

package/bin/lib/commands.cjs

@@ -293,9 +293,28 @@ function showHelp() {
     lines.push('');
   }
 
+  // Add command comparison for work-initiation commands
+  lines.push('Which command to use?');
+  lines.push(getCommandComparison());
+  lines.push('');
+
   return lines.join('\n').trimEnd();
 }
 
+/**
+ * Get a comparison table for the 3 work-initiation commands.
+ * @returns {string} Formatted comparison table
+ */
+function getCommandComparison() {
+  return [
+    '  Command      Scope          Research  Discuss  Plan  Verify  Best For',
+    '  -------      -----          --------  -------  ----  ------  --------',
+    '  story        Multi-phase    Yes       Yes      Yes   Yes     New features, milestones',
+    '  new-task     Single task    Optional  Optional Yes   Optional Significant changes',
+    '  quick        Minimal        No        No       Mini  No      Bug fixes, small tweaks'
+  ].join('\n');
+}
+
 /**
  * Show detailed help for a single unimplemented command.
  * Includes command name, description, usage, args, and status.
@@ -314,4 +333,4 @@ function showCommandHelp(name) {
   return text;
 }
 
-module.exports = { COMMANDS, getCommandHelp, showHelp, showCommandHelp };
+module.exports = { COMMANDS, getCommandHelp, showHelp, showCommandHelp, getCommandComparison };

package/bin/lib/recovery.cjs

@@ -4,7 +4,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { readLock, isLockStale, clearStaleLock } = require('./lock.cjs');
 const { readLog } = require('./logger.cjs');
-const { readState, writeState } = require('./state.cjs');
+const { readState, writeState, VALID_PHASE_STATUSES } = require('./state.cjs');
 
 /**
  * Analyze the JSONL execution log for a crashed phase.
@@ -141,8 +141,7 @@ function verifyStateConsistency(brainDir, state) {
   }
 
   // Check: status is a known value
-  const validStatuses = ['initialized', 'mapped', 'planned', 'executing', 'completed', 'paused', 'failed', 'partial'];
-  if (phase.status && !validStatuses.includes(phase.status)) {
+  if (phase.status && !VALID_PHASE_STATUSES.includes(phase.status)) {
     issues.push({
       type: 'invalid-status',
       description: `Phase status "${phase.status}" is not a recognized value`,

package/bin/lib/state.cjs

@@ -499,11 +499,23 @@ function today() {
   return new Date().toISOString().slice(0, 10);
 }
 
+/**
+ * Canonical list of valid phase statuses.
+ * Used by recovery.cjs, progress.cjs, and health.cjs for validation.
+ */
+const VALID_PHASE_STATUSES = [
+  'initialized', 'pending', 'mapped', 'ready', 'discussing', 'discussed',
+  'planning', 'planned', 'executing', 'executed',
+  'verifying', 'verified', 'verification-failed',
+  'partial', 'failed', 'paused', 'complete'
+];
+
 module.exports = {
   atomicWriteSync,
   readState,
   writeState,
   generateStateMd,
   createDefaultState,
-  migrateState
+  migrateState,
+  VALID_PHASE_STATUSES
 };

package/bin/lib/stuck.cjs

@@ -104,9 +104,74 @@ function checkTimeouts(brainDir, state) {
     };
   }
 
+  // Check for loop detection (stuck even without timeout)
+  const loop = detectStuckLoop(brainDir, state.phase?.current || 1);
+  if (loop.looping) {
+    return {
+      tier: 'idle',
+      elapsedMinutes,
+      idleMinutes,
+      message: `LOOP DETECTED: ${loop.details}. Agent is repeating the same action without progress.`
+    };
+  }
+
   return { tier: 'none', elapsedMinutes, idleMinutes, message: null };
 }
 
+/**
+ * Detect stuck loops: same plan spawned 3+ times, or same error repeated 3+ times.
+ * @param {string} brainDir
+ * @param {number} phaseNumber
+ * @returns {{ looping: boolean, loopType: 'spawn-repeat'|'error-repeat'|null, details: string|null }}
+ */
+function detectStuckLoop(brainDir, phaseNumber) {
+  const events = readLog(brainDir, phaseNumber);
+
+  // Check 1: Same plan spawned 3+ times without passing
+  const spawnsByPlan = {};
+  const passedPlans = new Set();
+
+  for (const event of events) {
+    if (event.type === 'spawn' && event.agent === 'executor' && event.plan) {
+      spawnsByPlan[event.plan] = (spawnsByPlan[event.plan] || 0) + 1;
+    }
+    if (event.type === 'spot-check' && event.passed && event.plan) {
+      passedPlans.add(event.plan);
+    }
+  }
+
+  for (const [plan, count] of Object.entries(spawnsByPlan)) {
+    if (count >= 3 && !passedPlans.has(plan)) {
+      return {
+        looping: true,
+        loopType: 'spawn-repeat',
+        details: `Plan ${plan} attempted ${count} times without passing spot-check`
+      };
+    }
+  }
+
+  // Check 2: Same error message repeated 3+ times
+  const errorMessages = {};
+  for (const event of events) {
+    if (event.type === 'error' && event.message) {
+      const key = event.message.slice(0, 100); // normalize by truncating
+      errorMessages[key] = (errorMessages[key] || 0) + 1;
+    }
+  }
+
+  for (const [msg, count] of Object.entries(errorMessages)) {
+    if (count >= 3) {
+      return {
+        looping: true,
+        loopType: 'error-repeat',
+        details: `Same error repeated ${count} times: "${msg.slice(0, 60)}..."`
+      };
+    }
+  }
+
+  return { looping: false, loopType: null, details: null };
+}
+
 /**
  * Check for execution non-convergence.
  * Detects: same plan attempted 3+ times, repeated spawns without spot-check pass.
@@ -162,6 +227,7 @@ function captureDiagnostics(brainDir, phaseNumber, stuckInfo) {
 
   const events = tailLog(brainDir, phaseNumber, null);
   const convergence = checkExecutionConvergence(brainDir, phaseNumber);
+  const loop = detectStuckLoop(brainDir, phaseNumber);
 
   const content = `---
 phase: ${phaseNumber}
@@ -183,6 +249,10 @@ timeout_tier: ${stuckInfo.tier}
 - Converging: ${convergence.converging}
 ${convergence.reason ? `- Issue: ${convergence.reason}` : ''}
 
+## Loop Detection
+- Looping: ${loop.looping}
+${loop.details ? `- Type: ${loop.loopType}\n- Details: ${loop.details}` : ''}
+
 ## Last ${events.length} Events
 ${events.map(e => `- ${e.timestamp || '?'} [${e.type || '?'}] ${JSON.stringify(e)}`).join('\n')}
 
@@ -260,6 +330,7 @@ function updateStuckBridge(brainDir, state) {
 module.exports = {
   detectProgress,
   checkTimeouts,
+  detectStuckLoop,
   checkExecutionConvergence,
   captureDiagnostics,
   buildWrapUpInstructions,

package/bin/templates/discuss.md

@@ -2,6 +2,11 @@
 
 You are facilitating a gray-area discussion for **Phase {{phase_number}}: {{phase_name}}**.
 
+## Technology Context
+{{stack_expertise}}
+
+When discussing implementation choices, consider the framework patterns above.
+
 ## Phase Context
 
 **Goal:** {{phase_goal}}

package/bin/templates/executor.md

@@ -27,16 +27,50 @@ Read the plan file above for the full task list and requirements.
    - GREEN: Write minimal code to pass
    - REFACTOR: Clean up while keeping tests green
 
-2. **Sequential execution:** Execute tasks one at a time, in order. Do not parallelize. Complete one plan before moving to the next.
+2. **NEVER commit broken code:** Run all relevant tests before every commit. If tests fail, fix them FIRST. Only commit when tests are GREEN. Do not commit TDD RED phase — only commit after GREEN or REFACTOR.
 
-3. **Commit after each task:** Use per-task atomic commit format (see Commit Format below).
+3. **Sequential execution:** Execute tasks one at a time, in order. Do not parallelize. Complete one plan before moving to the next.
 
-4. **Retry on failure:** If a task fails, retry once. If the retry also fails, output `## EXECUTION FAILED` with a structured failure block.
+4. **Commit after each task:** Use per-task atomic commit format (see Commit Format below).
+
+5. **Retry on failure:** If a task fails, retry once. If the retry also fails, output `## EXECUTION FAILED` with a structured failure block.
+
+### TDD Escape Hatch
+
+If you write a failing test (RED phase) and cannot make it pass after **3 implementation attempts**:
+
+1. Mark the test as `.skip()` or `{ skip: true }` with a TODO comment explaining why
+2. Log the skipped test in SUMMARY.md Deviations section with category `tdd-escape`
+3. Proceed to the next task — do NOT loop indefinitely
+4. The verifier will flag this as a gap, which is better than an infinite loop
+
+### Context Window Awareness
+
+Monitor your context usage. If you estimate you have used more than **60% of the context window**:
+
+1. Commit all current completed work
+2. Write a partial SUMMARY.md with `completed: "partial"` in frontmatter
+3. Output `## EXECUTION PARTIAL` with the list of completed tasks and remaining tasks
+4. Do NOT attempt to continue with exhausted context — partial progress is better than a crash
 
 ## Deviation Rules
 
 When executing, you will encounter issues not anticipated by the plan. Apply these rules:
 
+### Deviation Decision Tree
+
+When you encounter an issue not anticipated by the plan, use this decision tree:
+
+```
+Is the change confined to the CURRENT file only?
+├─ YES: Does it change any export signatures (function names, parameters, return types)?
+│       ├─ NO  → AUTO-FIX (fix immediately, log in Deviations)
+│       └─ YES → ESCALATE (other modules depend on this signature)
+└─ NO: Does it affect files OUTSIDE this plan's files_modified list?
+        ├─ NO  → AUTO-FIX (still within plan scope)
+        └─ YES → ESCALATE (cross-plan impact)
+```
+
 ### Auto-fix Scope (fix immediately, no permission needed)
 
 - **Test failures:** Fix broken assertions, update snapshots, correct test setup

package/bin/templates/planner.md

@@ -20,6 +20,32 @@ File paths, naming, and testing approach must match the detected stack.
 
 {{research_summary}}
 
+## Requirement Quality Gate
+
+Before planning, validate each requirement from `{{phase_requirements}}`. Reject and escalate requirements that are:
+
+**Vague** — cannot be turned into a testable truth:
+- BAD: "Make authentication work" → too vague, what does "work" mean?
+- BAD: "Improve performance" → no measurable target
+- BAD: "Handle errors properly" → no definition of "properly"
+- ESCALATE: Output `## PLANNING BLOCKED` with the vague requirement and ask for specifics
+
+**Circular** — restates the goal without adding implementation detail:
+- BAD: "Implement the user management feature" when the phase goal IS user management
+- FIX: Break into concrete sub-requirements (CRUD operations, validation rules, auth integration)
+
+**Contradictory** — conflicts with another requirement or a locked decision from CONTEXT.md:
+- BAD: REQ-03 says "use REST API" but REQ-07 says "use GraphQL for all endpoints"
+- ESCALATE: Output `## PLANNING BLOCKED` listing both contradicting requirements
+
+If a requirement passes the quality gate, proceed. If 2+ requirements fail, output PLANNING BLOCKED and do not generate plans.
+
+## Scope Guardrails
+
+- Each plan must modify **no more than 8 files**. If a plan needs more, split it into multiple plans.
+- Each plan should have **2-3 tasks**. If you need 5+ tasks, the plan scope is too wide — split it.
+- If the phase has 10+ requirements, create multiple plans with clear requirement ownership rather than one mega-plan.
+
 ## Output Format: Brain PLAN.md
 
 Create PLAN files at: `{{output_dir}}/PLAN-{nn}.md`
@@ -134,6 +160,42 @@ Use **goal-backward** approach to derive must_haves:
 4. **For each task:** define behavior first (TDD), then action
 5. **Verify completeness:** every must_have is covered by at least one plan's tasks
 
+### must_haves Quality Examples
+
+**BAD (vague, untestable):**
+```yaml
+truths:
+  - "Authentication works correctly"
+  - "API handles errors"
+  - "Database integration is complete"
+```
+
+**GOOD (specific, testable, verifiable):**
+```yaml
+truths:
+  - "POST /auth/login with valid email+password returns 200 with JWT token containing user_id claim"
+  - "All API endpoints return {error: string, code: number} JSON on 4xx/5xx responses"
+  - "User.findById(id) returns a User object with name, email, role fields from PostgreSQL"
+```
+
+The difference: good truths can be directly turned into test assertions. If you cannot write `assert.equal(...)` or `expect(...)` from a truth, it is too vague.
+
+## Planning Failures
+
+If you cannot create a valid plan after **2 attempts** (e.g., checker keeps rejecting, requirements are impossible, dependencies unresolvable), output:
+
+```markdown
+## PLANNING BLOCKED
+
+**Phase:** {{phase_number}} - {{phase_name}}
+**Reason:** [requirement_unclear | dependency_unresolved | scope_too_large | contradictory_requirements]
+**Details:** [specific explanation of what is blocking]
+**Missing:** [what information or decision is needed to unblock]
+**Suggestion:** [recommended next action -- e.g., "/brain:discuss to clarify requirements"]
+```
+
+Do NOT produce incomplete or low-quality plans. Blocking with clear information is better than a plan that will fail during execution.
+
 ## Enriched SUMMARY.md
 
 After each plan executes, the executor creates a SUMMARY.md with:

package/bin/templates/researcher.md

@@ -2,6 +2,9 @@
 
 You are a {{focus_area}} researcher for a new software project.
 
+## Stack Context
+{{stack_expertise}}
+
 ## Project Context
 
 **Project:** {{project_description}}

package/bin/templates/verifier.md

@@ -19,6 +19,20 @@ During verification, check:
 
 Use these results when evaluating Level 2 (Substantive) checks. Blockers MUST be reported as verification failures. Warnings should be noted but do not block.
 
+### Anti-Pattern Response Format
+
+For each blocker-level anti-pattern found, output a structured remediation block:
+
+```markdown
+**BLOCKER:** [anti-pattern name]
+- **File:** [path/to/file.cjs]
+- **Lines:** [line range, e.g., 45-52]
+- **Issue:** [specific description of what was found]
+- **Fix:** [one-sentence concrete fix suggestion]
+```
+
+Warnings are collected but do not affect the score. Blockers must be resolved before status can be "passed".
+
 ## 3-Level Verification
 
 For each artifact in must_haves, perform these automated checks:
@@ -30,10 +44,17 @@ For each artifact in must_haves, perform these automated checks:
 ### Level 2: Substantive
 - File has real implementation (not stub)
 - No TODO-only files, no empty functions, no log-only handlers
-- Minimum reasonable line count for the artifact type
 - Anti-pattern scan: count TODO/FIXME, placeholder content, empty returns
 - Cross-reference anti-pattern scan results above for blockers
 
+**Minimum line count thresholds:**
+- Functions/methods: at least **5 lines** of implementation (not counting braces/signature)
+- Classes: at least **20 lines** total
+- Modules/files: at least **30 lines** (excluding imports and empty lines)
+- Test files: at least **1 test per exported function** in the module under test
+
+If a file exports N functions, at least N-1 must have implementation beyond a single return statement. A function that only does `return null` or `return undefined` is a stub, not an implementation.
+
 ### Level 3: Wired (Enhanced Key Link Verification)
 - File is imported/used where expected
 - Check key_links: from-file imports/references to-file with specified pattern
@@ -88,13 +109,24 @@ Where:
 - **verified_count** = number of must_haves that pass all applicable levels
 - **total_count** = total number of must_haves (truths + artifacts + key_links)
 
+## Verification Priority
+
+Check must_haves in this order (most important first):
+
+1. **Truths** — behavioral invariants. If a truth fails, the feature is broken.
+2. **Artifacts** — files that must exist with correct content. If an artifact fails, the deliverable is incomplete.
+3. **Key Links** — wiring between files. If a key link fails, integration is broken.
+
+A truth failure is more severe than an artifact failure. Use this priority when determining status.
+
 ### Status Determination
 
 Based on the score:
 
 - **passed** (100%): All must_haves verified at all levels. Phase/plan deliverables are complete.
-- **gaps_found** (<100%): Some must_haves failed verification. List specific gaps with remediation steps.
-- **human_needed**: Some items require human verification (visual, interactive, UX). Automated checks passed but human gate pending.
+- **partial** (70-99%): Most must_haves verified. All truths pass but some artifacts or key_links have gaps. List specific gaps with remediation steps. This status tells the executor exactly what to fix without replanning the entire phase.
+- **gaps_found** (<70%, or any truth failure): Critical must_haves failed verification. The phase deliverables are fundamentally incomplete. List all gaps with remediation steps.
+- **human_needed**: Automated checks passed (score ≥70%) but items require human verification (visual, interactive, UX). Human gate pending.
 
 ## Output Format
 
@@ -107,7 +139,7 @@ Start the file with YAML frontmatter containing machine-parseable metadata:
 ```yaml
 ---
 phase: [phase number]
-status: passed | gaps_found | human_needed
+status: passed | partial | gaps_found | human_needed
 score: [verified]/[total]
 must_haves_verified: [count]
 must_haves_total: [count]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brain-dev",
-  "version": "1.2.6",
+  "version": "2.0.0",
   "description": "AI-powered development workflow orchestrator",
   "author": "halilcosdu",
   "license": "MIT",