brain-dev 2.4.0 → 2.5.1

package/bin/lib/agents.cjs

@@ -2,11 +2,11 @@
 
 /**
  * Agent registry for brain orchestration.
- * Defines the 7 core agents and their metadata.
+ * Defines the 11 core agents and their metadata.
  * Constant registry with discovery and validation functions.
  */
 
-const MAX_AGENTS = 9;
+const MAX_AGENTS = 11;
 
 const AGENTS = {
   researcher: {
@@ -73,6 +73,20 @@ const AGENTS = {
     model: 'inherit',
     description: 'Maps codebase across focus areas producing structured Markdown documentation',
     focus: ['tech', 'arch', 'quality', 'concerns']
+  },
+  'requirements-generator': {
+    template: 'requirements-generator',
+    inputs: ['project_md', 'summary_content', 'stack_expertise', 'codebase_context'],
+    outputs: ['REQUIREMENTS.md'],
+    model: 'inherit',
+    description: 'Generates structured requirements with acceptance criteria from research findings and project context'
+  },
+  'roadmap-architect': {
+    template: 'roadmap-architect',
+    inputs: ['requirements_content', 'summary_content', 'project_md', 'stack_expertise'],
+    outputs: ['ROADMAP.md'],
+    model: 'inherit',
+    description: 'Creates strategically-phased roadmap with technical dependency analysis from requirements and research'
   }
 };
 

package/bin/lib/commands/complete.cjs

@@ -2,7 +2,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
-const { readState, writeState } = require('../state.cjs');
+const { readState, writeState, syncPhaseStatus } = require('../state.cjs');
 const { parseRoadmap, writeRoadmap } = require('../roadmap.cjs');
 const { gitTag } = require('../git.cjs');
 const { output, error, success } = require('../core.cjs');
@@ -163,7 +163,7 @@ function handlePhaseComplete(args, phaseIdx, brainDir, state) {
     return { error: 'not-verified', nextAction: '/brain:verify' };
   }
 
-  // Mark phase as complete in state (handle both string and object formats)
+  // Mark current phase as complete in per-phase array
   if (Array.isArray(state.phase.phases)) {
     const idx = state.phase.phases.findIndex(p =>
       typeof p === 'object' ? p.number === phaseNumber : false
@@ -179,9 +179,9 @@ function handlePhaseComplete(args, phaseIdx, brainDir, state) {
   const hasNextPhase = totalPhases > 0 && nextPhase <= totalPhases;
   if (hasNextPhase) {
     state.phase.current = nextPhase;
-    state.phase.status = 'pending';
+    syncPhaseStatus(state, 'pending');
   } else {
-    state.phase.status = 'complete';
+    syncPhaseStatus(state, 'complete');
   }
   writeState(brainDir, state);
 

package/bin/lib/commands/discuss.cjs

@@ -2,7 +2,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
-const { readState, writeState, atomicWriteSync } = require('../state.cjs');
+const { readState, writeState, atomicWriteSync, syncPhaseStatus } = require('../state.cjs');
 const { parseRoadmap } = require('../roadmap.cjs');
 const { loadTemplate, interpolate } = require('../templates.cjs');
 const { output, error, success, prefix, pipelineGate } = require('../core.cjs');
@@ -132,7 +132,7 @@ function handleAnalyze(args, brainDir, state) {
   });
 
   // Update status to discussing
-  state.phase.status = 'discussing';
+  syncPhaseStatus(state, 'discussing');
   writeState(brainDir, state);
 
   const result = {
@@ -220,7 +220,7 @@ function handleSave(args, brainDir, state) {
   atomicWriteSync(contextPath, lines.join('\n'));
 
   // Update state: set phase status to "discussed"
-  state.phase.status = 'discussed';
+  syncPhaseStatus(state, 'discussed');
   writeState(brainDir, state);
 
   const result = {

package/bin/lib/commands/execute.cjs

@@ -2,7 +2,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
-const { readState, writeState } = require('../state.cjs');
+const { readState, writeState, syncPhaseStatus } = require('../state.cjs');
 const { loadTemplate, interpolate, loadTemplateWithOverlay } = require('../templates.cjs');
 const { getAgent, resolveModel } = require('../agents.cjs');
 const { logEvent } = require('../logger.cjs');
@@ -304,7 +304,7 @@ async function run(args = [], opts = {}) {
 
   // All plans executed
   if (!targetPlan) {
-    state.phase.status = 'executed';
+    syncPhaseStatus(state, 'executed');
     writeState(brainDir, state);
     const msg = "All plans executed. Run /brain:review before verify.";
     output({ action: 'all-executed', message: msg, nextAction: '/brain:review' }, `[brain] ${msg}\n${pipelineGate('npx brain-dev review --phase ' + phaseNumber)}`);
@@ -385,7 +385,7 @@ async function run(args = [], opts = {}) {
   } catch { /* cost tracking failure is non-fatal */ }
 
   // Update state to executing
-  state.phase.status = 'executing';
+  syncPhaseStatus(state, 'executing');
   if (!state.phase.execution_started_at) {
     state.phase.execution_started_at = new Date().toISOString();
   }

package/bin/lib/commands/plan.cjs

@@ -2,7 +2,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
-const { readState, writeState } = require('../state.cjs');
+const { readState, writeState, syncPhaseStatus } = require('../state.cjs');
 const { parseRoadmap } = require('../roadmap.cjs');
 const { loadTemplate, interpolate, loadTemplateWithOverlay } = require('../templates.cjs');
 const { getAgent, resolveModel } = require('../agents.cjs');
@@ -291,7 +291,7 @@ function handleSingle(args, brainDir, state) {
   const fullPrompt = prompt + checkerInstruction;
 
   // Update state: phase status = "planning"
-  state.phase.status = 'planning';
+  syncPhaseStatus(state, 'planning');
   writeState(brainDir, state);
 
   const result = {
@@ -531,7 +531,7 @@ function handleAll(brainDir, state) {
   });
 
   // Update status to planning
-  state.phase.status = 'planning';
+  syncPhaseStatus(state, 'planning');
   writeState(brainDir, state);
 
   const result = {

package/bin/lib/commands/review.cjs

@@ -2,7 +2,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
-const { readState, writeState } = require('../state.cjs');
+const { readState, writeState, syncPhaseStatus } = require('../state.cjs');
 const { loadTemplateWithOverlay, interpolate } = require('../templates.cjs');
 const { getAgent, resolveModel } = require('../agents.cjs');
 const { logEvent } = require('../logger.cjs');
@@ -93,7 +93,7 @@ async function run(args = [], opts = {}) {
   });
 
   // Update state
-  state.phase.status = 'reviewing';
+  syncPhaseStatus(state, 'reviewing');
   writeState(brainDir, state);
 
   const result = {
@@ -145,14 +145,14 @@ function handleResult(brainDir, state, args) {
   const reviewStatus = statusMatch ? statusMatch[1] : 'passed';
 
   if (reviewStatus === 'critical') {
-    state.phase.status = 'review-failed';
+    syncPhaseStatus(state, 'review-failed');
     writeState(brainDir, state);
     error('Review found critical issues. Fix them and re-run /brain:review.');
     output({ action: 'review-failed', phase: phaseNumber, status: reviewStatus }, '');
     return { action: 'review-failed', phase: phaseNumber };
   }
 
-  state.phase.status = 'reviewed';
+  syncPhaseStatus(state, 'reviewed');
   writeState(brainDir, state);
 
   const result = {

package/bin/lib/commands/story.cjs

@@ -3,17 +3,18 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { parseArgs } = require('node:util');
-const { readState, writeState } = require('../state.cjs');
+const { readState, writeState, syncPhaseStatus } = require('../state.cjs');
 const { output, error, prefix } = require('../core.cjs');
 const { logEvent } = require('../logger.cjs');
-const { loadTemplate, interpolate } = require('../templates.cjs');
+const { loadTemplate, interpolate, loadTemplateWithOverlay } = require('../templates.cjs');
 const { getAgent, resolveModel } = require('../agents.cjs');
 const { generateExpertise } = require('../stack-expert.cjs');
 const {
   RESEARCH_AREAS, CORE_QUESTIONS, buildBrownfieldQuestions,
   readDetection, buildCodebaseContext, generateProjectMd,
-  generateRequirementsMd, extractFeatures, extractSection
+  generateRequirementsMd, validateRequirementsMd, extractFeatures, extractSection
 } = require('../story-helpers.cjs');
+const { getDetectedFramework } = require('../stack-expert.cjs');
 
 /**
  * Get research areas with optional framework-specific additions.
@@ -318,10 +319,55 @@ function handleContinue(brainDir, state, values) {
   }
 
   if (!hasRequirementsMd) {
+    if (storyMeta.status === 'requirements-generating') {
+      const humanLines = prefix('Requirements agent is generating... Run --continue after it finishes.');
+      output({ action: 'requirements-pending' }, humanLines);
+      return { action: 'requirements-pending' };
+    }
     return stepRequirements(brainDir, storyDir, storyMeta, state);
   }
 
+  // Validate requirements quality before proceeding to roadmap.
+  // Only validate agent-generated requirements (hasSummaryMd).
+  // Programmatic fallback (--no-research) skips validation because its output
+  // format intentionally lacks acceptance criteria.
+  if (hasRequirementsMd && !hasRoadmapMd && !storyMeta.requirementsValidated && hasSummaryMd) {
+    const reqContent = fs.readFileSync(path.join(storyDir, 'REQUIREMENTS.md'), 'utf8');
+    const validation = validateRequirementsMd(reqContent);
+
+    if (!validation.valid && (storyMeta.requirementsRetries || 0) < 2) {
+      fs.unlinkSync(path.join(storyDir, 'REQUIREMENTS.md'));
+      storyMeta.requirementsRetries = (storyMeta.requirementsRetries || 0) + 1;
+      storyMeta.requirementsFeedback = validation.issues;
+
+      logEvent(brainDir, 0, { type: 'requirements-retry', story: storyMeta.num, attempt: storyMeta.requirementsRetries, issues: validation.issues.length });
+
+      const humanLines = [
+        prefix(`Requirements quality check failed (attempt ${storyMeta.requirementsRetries}/2):`),
+        ...validation.issues.map(i => prefix(`  - ${i}`)),
+        '',
+        prefix('Re-spawning requirements agent with feedback...')
+      ].join('\n');
+      output({ action: 'requirements-retry', issues: validation.issues, stats: validation.stats }, humanLines);
+
+      return stepRequirements(brainDir, storyDir, storyMeta, state);
+    }
+
+    storyMeta.requirementsValidated = true;
+    fs.writeFileSync(path.join(storyDir, 'story.json'), JSON.stringify(storyMeta, null, 2));
+
+    if (!validation.valid) {
+      const humanLines = prefix(`Warning: REQUIREMENTS.md has ${validation.issues.length} quality issues after ${storyMeta.requirementsRetries} retries. Proceeding anyway.`);
+      output({ action: 'requirements-quality-warning', issues: validation.issues, stats: validation.stats }, humanLines);
+    }
+  }
+
   if (!hasRoadmapMd) {
+    if (storyMeta.status === 'roadmap-generating') {
+      const humanLines = prefix('Roadmap agent is generating... Run --continue after it finishes.');
+      output({ action: 'roadmap-pending' }, humanLines);
+      return { action: 'roadmap-pending' };
+    }
     return stepRoadmap(brainDir, storyDir, storyMeta, state);
   }
 
@@ -526,9 +572,8 @@ function stepSynthesize(brainDir, storyDir, storyMeta, state) {
 // ---------------------------------------------------------------------------
 
 function stepRequirements(brainDir, storyDir, storyMeta, state) {
-  // Read PROJECT.md for features
+  // Read PROJECT.md
   const projectMd = fs.readFileSync(path.join(storyDir, 'PROJECT.md'), 'utf8');
-  const features = extractFeatures(projectMd);
 
   // Read research summary if available
   const summaryPath = path.join(storyDir, 'research', 'SUMMARY.md');
@@ -537,36 +582,107 @@ function stepRequirements(brainDir, storyDir, storyMeta, state) {
     summaryContent = fs.readFileSync(summaryPath, 'utf8');
   }
 
-  // Generate REQUIREMENTS.md
-  const { requirementsMd, categories } = generateRequirementsMd(features, summaryContent);
-  fs.writeFileSync(path.join(storyDir, 'REQUIREMENTS.md'), requirementsMd, 'utf8');
+  // No research → use programmatic fallback
+  const skipResearch = storyMeta.noResearch === true || !summaryContent;
+  if (skipResearch) {
+    const features = extractFeatures(projectMd);
+    const { requirementsMd, categories } = generateRequirementsMd(features, summaryContent);
+    fs.writeFileSync(path.join(storyDir, 'REQUIREMENTS.md'), requirementsMd, 'utf8');
+
+    storyMeta.status = 'requirements';
+    fs.writeFileSync(path.join(storyDir, 'story.json'), JSON.stringify(storyMeta, null, 2));
+
+    const activeIdx = (state.stories.active || []).findIndex(s => s.dirName === storyMeta.dirName);
+    if (activeIdx >= 0) state.stories.active[activeIdx].status = 'requirements';
+    writeState(brainDir, state);
+
+    logEvent(brainDir, 0, { type: 'story-requirements', story: storyMeta.num, categories: categories.length });
+
+    const humanLines = [
+      prefix(`Story: ${storyMeta.version} ${storyMeta.title}`),
+      prefix('Step: Requirements Generated (programmatic fallback)'),
+      '',
+      prefix(`REQUIREMENTS.md written with ${categories.length} categories:`),
+      ...categories.map(c => prefix(`  - ${c.name} (${c.items.length} requirements)`)),
+      '',
+      prefix('Review REQUIREMENTS.md and confirm.'),
+      prefix('Then run: brain-dev story --continue')
+    ].join('\n');
+
+    const result = {
+      action: 'requirements-generated',
+      content: requirementsMd,
+      categories,
+      instruction: 'Review and confirm'
+    };
+
+    output(result, humanLines);
+    return result;
+  }
+
+  // Research exists → spawn requirements-generator agent
+  const outputPath = path.join(storyDir, 'REQUIREMENTS.md');
+  const framework = getDetectedFramework(brainDir);
+  const template = loadTemplateWithOverlay('requirements-generator', framework);
+  const stackExpertise = generateExpertise(brainDir, 'general');
+  const detection = readDetection(brainDir);
+  const codebaseContext = detection ? buildCodebaseContext(detection) : '';
+
+  // Build feedback section if retrying
+  let feedbackSection = '';
+  if (storyMeta.requirementsFeedback && storyMeta.requirementsFeedback.length > 0) {
+    feedbackSection = '\n\n## PREVIOUS ATTEMPT FEEDBACK\n\n' +
+      'Your previous output was rejected for these quality issues:\n' +
+      storyMeta.requirementsFeedback.map(i => `- ${i}`).join('\n') +
+      '\n\nFix ALL these issues in your next attempt.';
+  }
+
+  const prompt = interpolate(template, {
+    project_md: projectMd,
+    summary_content: summaryContent,
+    stack_expertise: stackExpertise || '',
+    codebase_context: codebaseContext || '_No codebase context available._',
+    output_path: outputPath
+  }) + feedbackSection;
+
+  const model = resolveModel('requirements-generator', state);
 
   // Update status
-  storyMeta.status = 'requirements';
+  storyMeta.status = 'requirements-generating';
   fs.writeFileSync(path.join(storyDir, 'story.json'), JSON.stringify(storyMeta, null, 2));
 
   const activeIdx = (state.stories.active || []).findIndex(s => s.dirName === storyMeta.dirName);
-  if (activeIdx >= 0) state.stories.active[activeIdx].status = 'requirements';
+  if (activeIdx >= 0) state.stories.active[activeIdx].status = 'requirements-generating';
   writeState(brainDir, state);
 
-  logEvent(brainDir, 0, { type: 'story-requirements', story: storyMeta.num, categories: categories.length });
+  logEvent(brainDir, 0, { type: 'story-requirements-spawn', story: storyMeta.num, retry: storyMeta.requirementsRetries || 0 });
 
   const humanLines = [
     prefix(`Story: ${storyMeta.version} ${storyMeta.title}`),
-    prefix('Step: Requirements Generated'),
+    prefix('Step: Spawning Requirements Generator Agent'),
+    storyMeta.requirementsRetries ? prefix(`Retry: ${storyMeta.requirementsRetries}/2`) : '',
     '',
-    prefix(`REQUIREMENTS.md written with ${categories.length} categories:`),
-    ...categories.map(c => prefix(`  - ${c.name} (${c.items.length} requirements)`)),
+    prefix('The agent will read your research summary and project context'),
+    prefix('to generate detailed, specific requirements with acceptance criteria.'),
     '',
-    prefix('Review REQUIREMENTS.md and confirm.'),
-    prefix('Then run: brain-dev story --continue')
-  ].join('\n');
+    prefix(`Output: ${outputPath}`),
+    prefix(`Model: ${model}`),
+    '',
+    'IMPORTANT: Use the Agent tool to spawn the requirements-generator agent.',
+    'Do NOT generate requirements yourself.',
+    '',
+    'After agent completes, run: brain-dev story --continue',
+    '',
+    prompt
+  ].filter(Boolean).join('\n');
 
   const result = {
-    action: 'requirements-generated',
-    content: requirementsMd,
-    categories,
-    instruction: 'Review and confirm'
+    action: 'spawn-requirements-agent',
+    prompt,
+    model,
+    outputPath,
+    retry: storyMeta.requirementsRetries || 0,
+    instruction: 'Spawn requirements-generator agent, then run --continue'
   };
 
   output(result, humanLines);
@@ -582,6 +698,82 @@ function stepRoadmap(brainDir, storyDir, storyMeta, state) {
   const reqPath = path.join(storyDir, 'REQUIREMENTS.md');
   const reqContent = fs.readFileSync(reqPath, 'utf8');
 
+  // Read research summary if available
+  const summaryPath = path.join(storyDir, 'research', 'SUMMARY.md');
+  let summaryContent = '';
+  if (fs.existsSync(summaryPath)) {
+    summaryContent = fs.readFileSync(summaryPath, 'utf8');
+  }
+
+  // No research → use programmatic fallback
+  const skipResearch = storyMeta.noResearch === true || !summaryContent;
+  if (skipResearch) {
+    return stepRoadmapProgrammatic(brainDir, storyDir, storyMeta, state, reqContent);
+  }
+
+  // Research exists → spawn roadmap-architect agent
+  const projectMd = fs.readFileSync(path.join(storyDir, 'PROJECT.md'), 'utf8');
+  const outputPath = path.join(storyDir, 'ROADMAP.md');
+  const framework = getDetectedFramework(brainDir);
+  const template = loadTemplateWithOverlay('roadmap-architect', framework);
+  const stackExpertise = generateExpertise(brainDir, 'general');
+
+  const prompt = interpolate(template, {
+    requirements_content: reqContent,
+    summary_content: summaryContent,
+    project_md: projectMd,
+    stack_expertise: stackExpertise || '',
+    output_path: outputPath,
+    story_version: storyMeta.version || '',
+    story_title: storyMeta.title || ''
+  });
+
+  const model = resolveModel('roadmap-architect', state);
+
+  // Update status
+  storyMeta.status = 'roadmap-generating';
+  fs.writeFileSync(path.join(storyDir, 'story.json'), JSON.stringify(storyMeta, null, 2));
+
+  const activeIdx = (state.stories.active || []).findIndex(s => s.dirName === storyMeta.dirName);
+  if (activeIdx >= 0) state.stories.active[activeIdx].status = 'roadmap-generating';
+  writeState(brainDir, state);
+
+  logEvent(brainDir, 0, { type: 'story-roadmap-spawn', story: storyMeta.num });
+
+  const humanLines = [
+    prefix(`Story: ${storyMeta.version} ${storyMeta.title}`),
+    prefix('Step: Spawning Roadmap Architect Agent'),
+    '',
+    prefix('The agent will analyze requirements and research findings'),
+    prefix('to create a strategically-phased roadmap with real dependencies.'),
+    '',
+    prefix(`Output: ${outputPath}`),
+    prefix(`Model: ${model}`),
+    '',
+    'IMPORTANT: Use the Agent tool to spawn the roadmap-architect agent.',
+    'Do NOT generate the roadmap yourself.',
+    '',
+    'After agent completes, run: brain-dev story --continue',
+    '',
+    prompt
+  ].join('\n');
+
+  const result = {
+    action: 'spawn-roadmap-agent',
+    prompt,
+    model,
+    outputPath,
+    instruction: 'Spawn roadmap-architect agent, then run --continue'
+  };
+
+  output(result, humanLines);
+  return result;
+}
+
+/**
+ * Programmatic fallback for roadmap generation (no research).
+ */
+function stepRoadmapProgrammatic(brainDir, storyDir, storyMeta, state, reqContent) {
   // Parse categories from REQUIREMENTS.md headings
   const categoryRegex = /## (.+)\n([\s\S]*?)(?=\n## |$)/g;
   const phases = [];
@@ -591,8 +783,8 @@ function stepRoadmap(brainDir, storyDir, storyMeta, state) {
   while ((catMatch = categoryRegex.exec(reqContent)) !== null) {
     const catName = catMatch[1].trim();
     if (catName === 'Requirements' || catName.toLowerCase() === 'requirements') continue;
+    if (catName === 'Traceability' || catName.toLowerCase() === 'traceability') continue;
 
-    // Extract requirement IDs from this category
     const catBody = catMatch[2];
     const reqIds = [];
     const reqLineRegex = /- \*\*(\d+\.\d+)\*\*/g;
@@ -601,7 +793,6 @@ function stepRoadmap(brainDir, storyDir, storyMeta, state) {
       reqIds.push(reqMatch[1]);
     }
 
-    // Dependencies: each phase depends on the previous one (except phase 1)
     const dependsOn = phaseNum > 1 ? [phaseNum - 1] : [];
 
     phases.push({
@@ -617,7 +808,6 @@ function stepRoadmap(brainDir, storyDir, storyMeta, state) {
     phaseNum++;
   }
 
-  // Fallback: if no phases extracted, create a single phase
   if (phases.length === 0) {
     phases.push({
       number: 1,
@@ -630,7 +820,6 @@ function stepRoadmap(brainDir, storyDir, storyMeta, state) {
     });
   }
 
-  // Generate ROADMAP.md
   const roadmapLines = [
     '# Roadmap',
     '',
@@ -650,7 +839,6 @@ function stepRoadmap(brainDir, storyDir, storyMeta, state) {
     roadmapLines.push('');
   }
 
-  // Progress table
   roadmapLines.push('## Progress');
   roadmapLines.push('');
   roadmapLines.push('| Phase | Status | Plans |');
@@ -663,7 +851,6 @@ function stepRoadmap(brainDir, storyDir, storyMeta, state) {
   const roadmapMd = roadmapLines.join('\n');
   fs.writeFileSync(path.join(storyDir, 'ROADMAP.md'), roadmapMd, 'utf8');
 
-  // Update status
   storyMeta.status = 'roadmap';
   fs.writeFileSync(path.join(storyDir, 'story.json'), JSON.stringify(storyMeta, null, 2));
 
@@ -675,7 +862,7 @@ function stepRoadmap(brainDir, storyDir, storyMeta, state) {
 
   const humanLines = [
     prefix(`Story: ${storyMeta.version} ${storyMeta.title}`),
-    prefix('Step: Roadmap Generated'),
+    prefix('Step: Roadmap Generated (programmatic fallback)'),
     '',
     prefix(`ROADMAP.md written with ${phases.length} phases:`),
     ...phases.map(p => prefix(`  Phase ${p.number}: ${p.name} (depends on: ${p.dependsOn.length === 0 ? 'none' : p.dependsOn.join(', ')})`)),
@@ -726,7 +913,7 @@ function stepActivate(brainDir, state, storyDir, storyMeta) {
   // Update state phases
   state.phase = state.phase || { current: 0, status: 'initialized', total: 0, phases: [] };
   state.phase.current = 1;
-  state.phase.status = 'ready';
+  syncPhaseStatus(state, 'ready');
   state.phase.total = roadmapData.phases.length;
   state.phase.phases = roadmapData.phases.map(p => ({
     number: p.number,

package/bin/lib/commands/verify.cjs

@@ -2,7 +2,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
-const { readState, writeState, atomicWriteSync } = require('../state.cjs');
+const { readState, writeState, atomicWriteSync, syncPhaseStatus } = require('../state.cjs');
 const { loadTemplate, interpolate, loadTemplateWithOverlay } = require('../templates.cjs');
 const { getAgent, resolveModel } = require('../agents.cjs');
 const { logEvent } = require('../logger.cjs');
@@ -320,7 +320,7 @@ async function run(args = [], opts = {}) {
   const fullPrompt = prompt + depthInstruction + summarySection;
 
   // Update state to verifying
-  state.phase.status = 'verifying';
+  syncPhaseStatus(state, 'verifying');
   writeState(brainDir, state);
 
   const result = {
@@ -421,9 +421,7 @@ function handleSaveResults(args, saveIdx, brainDir, state) {
   }
 
   // Update state
-  state.phase.status = results.passed ? 'verified' : 'verification-failed';
-  // Clear execution timer after verification completes
-  state.phase.execution_started_at = null;
+  syncPhaseStatus(state, results.passed ? 'verified' : 'verification-failed');
   writeState(brainDir, state);
 
   const msg = results.passed

package/bin/lib/config.cjs

@@ -56,7 +56,9 @@ const PROFILES = {
     models: {
       'plan-checker': 'claude-sonnet-4-20250514',
       verifier: 'claude-sonnet-4-20250514',
-      researcher: 'claude-sonnet-4-20250514'
+      researcher: 'claude-sonnet-4-20250514',
+      'requirements-generator': 'claude-sonnet-4-20250514',
+      'roadmap-architect': 'claude-sonnet-4-20250514'
     }
   },
   budget: {
@@ -67,7 +69,9 @@ const PROFILES = {
       'plan-checker': 'claude-haiku-4-20250514',
       verifier: 'claude-haiku-4-20250514',
       debugger: 'claude-haiku-4-20250514',
-      mapper: 'claude-haiku-4-20250514'
+      mapper: 'claude-haiku-4-20250514',
+      'requirements-generator': 'claude-sonnet-4-20250514',
+      'roadmap-architect': 'claude-haiku-4-20250514'
     }
   }
 };

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, VALID_PHASE_STATUSES } = require('./state.cjs');
+const { readState, writeState, VALID_PHASE_STATUSES, syncPhaseStatus } = require('./state.cjs');
 
 /**
  * Analyze the JSONL execution log for a crashed phase.
@@ -293,11 +293,11 @@ function autoResume(brainDir, logAnalysis, state) {
   if (state.phase) {
     if (state.phase.status === 'executing' && logAnalysis.inProgressTask) {
       // There was work in progress - set to planned so execution can retry
-      state.phase.status = 'planned';
+      syncPhaseStatus(state, 'planned');
       changes.push(`Reset phase status from "executing" to "planned"`);
     } else if (state.phase.status === 'executing' && !logAnalysis.inProgressTask) {
       // All tasks were completed or none in progress
-      state.phase.status = 'planned';
+      syncPhaseStatus(state, 'planned');
       changes.push(`Reset phase status to "planned" for re-verification`);
     }
 
@@ -337,8 +337,7 @@ function rollback(brainDir, staleLock, state) {
   // Reset phase status
   if (state.phase) {
     const previousStatus = state.phase.status;
-    state.phase.status = 'planned';
-    state.phase.execution_started_at = null;
+    syncPhaseStatus(state, 'planned');
     changes.push(`Reset phase status from "${previousStatus}" to "planned"`);
   }
 

package/bin/lib/state.cjs

@@ -517,6 +517,27 @@ const VALID_PHASE_STATUSES = [
   'partial', 'failed', 'paused', 'complete'
 ];
 
+/**
+ * Atomically sync phase status across both top-level and per-phase array.
+ * Also clears execution_started_at when regressing to pre-execute states.
+ * @param {object} state - brain.json state object
+ * @param {string} newStatus - New status value
+ */
+function syncPhaseStatus(state, newStatus) {
+  const preExecuteStatuses = ['pending', 'ready', 'discussing', 'discussed', 'planning', 'planned'];
+  if (preExecuteStatuses.includes(newStatus)) {
+    state.phase.execution_started_at = null;
+  }
+
+  state.phase.status = newStatus;
+  if (Array.isArray(state.phase.phases) && state.phase.current > 0) {
+    const idx = state.phase.phases.findIndex(p => p.number === state.phase.current);
+    if (idx >= 0) {
+      state.phase.phases[idx].status = newStatus;
+    }
+  }
+}
+
 module.exports = {
   atomicWriteSync,
   readState,
@@ -524,5 +545,6 @@ module.exports = {
   generateStateMd,
   createDefaultState,
   migrateState,
+  syncPhaseStatus,
   VALID_PHASE_STATUSES
 };

package/bin/lib/story-helpers.cjs

@@ -426,6 +426,74 @@ function extractSection(content, heading) {
   return match ? match[1].trim() : '';
 }
 
+/**
+ * Validate REQUIREMENTS.md quality after LLM generation.
+ * Checks for acceptance criteria, description length, banned phrases, and structure.
+ * @param {string} content - REQUIREMENTS.md content
+ * @returns {{ valid: boolean, issues: string[], stats: { requirements: number, withAcceptance: number, categories: number, acceptanceRate: number } }}
+ */
+function validateRequirementsMd(content) {
+  const issues = [];
+
+  // Parse requirements (checkbox format: - [ ] **N.M**: Description)
+  const reqRegex = /- \[[ x]\] \*\*(\S+)\*\*:?\s*(.+)/g;
+  let reqCount = 0;
+  let withAcceptance = 0;
+  let match;
+
+  while ((match = reqRegex.exec(content)) !== null) {
+    reqCount++;
+    const reqId = match[1];
+    const reqText = match[2];
+
+    // Check for acceptance criterion following this requirement
+    const reqIdx = content.indexOf(match[0]);
+    const nextLines = content.slice(reqIdx + match[0].length).split('\n').slice(0, 4);
+    const hasAcceptance = nextLines.some(l =>
+      l.trim().startsWith('- Acceptance:') || l.trim().startsWith('Acceptance:'));
+
+    if (hasAcceptance) withAcceptance++;
+    else issues.push(`${reqId}: missing acceptance criterion`);
+
+    // Check description length
+    if (reqText.split(/\s+/).length < 5) {
+      issues.push(`${reqId}: description too short (< 5 words)`);
+    }
+
+    // Check for banned vague phrases
+    const banned = [
+      'implement properly', 'handle correctly', 'make it work',
+      'ensure quality', 'integrate well', 'setup recommended'
+    ];
+    for (const phrase of banned) {
+      if (reqText.toLowerCase().includes(phrase)) {
+        issues.push(`${reqId}: contains banned vague phrase "${phrase}"`);
+      }
+    }
+  }
+
+  // Check category count (exclude special sections like Traceability, Requirements)
+  const allHeadings = content.match(/^## [A-Z].*/gm) || [];
+  const catCount = allHeadings.filter(h =>
+    !h.match(/^## (Traceability|Requirements|REQUIREMENTS)/)).length;
+  if (catCount < 2) issues.push('Too few categories (expected at least 2)');
+
+  // Check minimum requirement count
+  if (reqCount < 3) issues.push(`Only ${reqCount} requirements found (expected at least 3)`);
+
+  const valid = issues.length === 0;
+  return {
+    valid,
+    issues,
+    stats: {
+      requirements: reqCount,
+      withAcceptance,
+      categories: catCount,
+      acceptanceRate: reqCount > 0 ? Math.round(withAcceptance / reqCount * 100) : 0
+    }
+  };
+}
+
 module.exports = {
   RESEARCH_AREAS,
   CORE_QUESTIONS,
@@ -434,6 +502,7 @@ module.exports = {
   buildCodebaseContext,
   generateProjectMd,
   generateRequirementsMd,
+  validateRequirementsMd,
   extractFeatures,
   extractSection
 };

package/bin/templates/requirements-generator.md

@@ -0,0 +1,115 @@
+# Requirements Generator Agent
+
+You are a requirements engineering specialist. Your job is to analyze research findings and project context to produce specific, measurable, testable requirements.
+
+## Technology Context
+{{stack_expertise}}
+
+## Project Context
+{{project_md}}
+
+## Research Summary
+{{summary_content}}
+
+## Codebase Context
+{{codebase_context}}
+
+## Your Task
+
+Generate a structured REQUIREMENTS.md by analyzing the research summary and project context above. Every requirement must be **grounded in research findings** — no generic filler.
+
+## Output Format
+
+Write the file to: `{{output_path}}`
+
+Use this EXACT format:
+
+```markdown
+# Requirements
+
+## [Category Name]
+
+Goal: [1-sentence goal grounded in specific research findings]
+
+- [ ] **N.M**: [Specific, measurable requirement — minimum 5 words]
+  - Acceptance: [Testable criterion that can become an assert/expect statement]
+  - Source: [Which research area identified this need]
+  - Priority: P0|P1|P2
+
+## Traceability
+
+| Requirement | Category | Priority | Source |
+|-------------|----------|----------|--------|
+| N.M | Category | P0/P1/P2 | Research area |
+```
+
+### Category Rules
+- Derive categories from ACTUAL research themes and project structure
+- Do NOT use hardcoded generic names like "Infrastructure" or "Quality & Security"
+- Each category needs a Goal line grounded in specific research findings
+- Minimum 2 categories, maximum 8
+
+### Requirement Rules
+1. **Checkbox format required**: `- [ ] **N.M**: Description`
+   - N = category number (1, 2, 3...)
+   - M = requirement within category (1, 2, 3...)
+2. **Every requirement MUST have an Acceptance line** — testable criterion
+3. **Description minimum 5 words** — be specific about WHAT, not just "implement X"
+4. **Source must reference research** — which research finding drives this requirement
+5. **Priority**: P0 = must have, P1 = should have, P2 = nice to have
+
+### Banned Vague Phrases (DO NOT USE)
+- "implement properly"
+- "handle correctly"
+- "make it work"
+- "ensure quality"
+- "integrate well"
+- "setup recommended technology stack"
+- "implement testing strategy"
+- "implement security requirements"
+- "implement recommended architecture patterns"
+
+### Bad vs Good Examples
+
+**BAD:**
+```
+- [ ] **1.1**: Setup recommended technology stack
+- [ ] **2.1**: Implement security requirements
+- [ ] **3.1**: Handle errors properly
+```
+
+**GOOD:**
+```
+- [ ] **1.1**: User authentication via JWT with RS256 signing, 24h token expiration
+  - Acceptance: POST /auth/login with valid credentials returns 200 with JWT containing user_id and exp claims; expired tokens return 401
+  - Source: Security research — session management recommendations
+  - Priority: P0
+
+- [ ] **1.2**: PostgreSQL schema with users table including email uniqueness constraint and bcrypt password hashing
+  - Acceptance: Migration creates users table with UNIQUE index on email column; passwords stored as bcrypt hashes with cost factor 12
+  - Source: Stack research — database recommendations
+  - Priority: P0
+
+- [ ] **2.1**: Rate limiting on authentication endpoints at 5 requests per minute per IP
+  - Acceptance: 6th login attempt within 60 seconds returns 429 with Retry-After header
+  - Source: Security research — brute force protection
+  - Priority: P1
+```
+
+### Cross-Cutting Concerns
+Include requirements from ALL research areas, not just features:
+- Security findings → security requirements
+- Performance findings → performance requirements
+- Testing findings → testing requirements
+- Architecture findings → structural requirements
+- Pitfalls findings → defensive requirements
+
+## Output Marker
+
+When complete, output:
+```
+## REQUIREMENTS COMPLETE
+Categories: [count]
+Requirements: [total count]
+P0: [count] | P1: [count] | P2: [count]
+```

package/bin/templates/roadmap-architect.md

@@ -0,0 +1,104 @@
+# Roadmap Architect Agent
+
+You are a technical roadmap architect. Your job is to create a strategically-phased development plan with REAL technical dependencies — not a linear chain of categories.
+
+## Technology Context
+{{stack_expertise}}
+
+## Requirements
+{{requirements_content}}
+
+## Research Summary
+{{summary_content}}
+
+## Project Context
+{{project_md}}
+
+## Your Task
+
+Analyze requirements and research to create a phased ROADMAP.md with technical dependency analysis, risk assessment, and strategic sequencing.
+
+## Dependency Analysis Rules
+
+1. **Identify TECHNICAL dependencies** between requirements:
+   - Database schema must exist before CRUD endpoints
+   - Auth infrastructure before protected routes
+   - Shared models/types before their consumers
+   - Configuration/environment setup before feature code
+   - Core utilities before features that use them
+
+2. **Group by TECHNICAL AFFINITY**, not by requirement category:
+   - Requirements sharing the same domain model belong together
+   - Infrastructure requirements precede feature requirements
+   - Integration requirements follow their component requirements
+   - Testing setup can parallel with early implementation
+
+3. **Dependency graph must be a DAG**:
+   - No circular dependencies
+   - Phase N can only depend on phases < N
+   - Multiple phases CAN share dependencies (fan-in)
+   - A phase CAN enable multiple later phases (fan-out)
+   - NOT all phases need to be sequential — identify parallelizable work
+
+## Output Format
+
+Write the file to: `{{output_path}}`
+
+Use this EXACT format:
+
+```markdown
+# Roadmap
+
+Story: {{story_version}} {{story_title}}
+
+## Phases
+
+### Phase N: [Descriptive Name — NOT category name]
+
+- **Goal:** [Specific goal grounded in requirements — NOT "Implement X requirements"]
+- **Depends on:** [Comma-separated phase numbers based on TECHNICAL analysis, or None]
+- **Requirements:** [Comma-separated requirement IDs from REQUIREMENTS.md]
+- **Risk:** [Primary risk from research for this phase]
+- **Estimated complexity:** Low|Medium|High
+- **Status:** Pending
+
+## Progress
+
+| Phase | Status | Plans |
+|-------|--------|-------|
+| N | Pending | 0/0 |
+
+## Phase Rationale
+
+[2-3 sentences explaining WHY phases are ordered this way, citing specific technical dependencies discovered in research]
+```
+
+## Phase Goal Anti-Patterns (DO NOT USE)
+
+- "Implement core features requirements" — circular, says nothing
+- "Setup infrastructure" — too vague
+- "Implement X requirements" — restates the category name
+- "Build the system" — meaningless
+
+## Good Phase Goal Examples
+
+- "Establish database schema, authentication flow, and API foundation that all feature phases depend on"
+- "Build real-time notification pipeline using WebSocket connections with Redis pub/sub backing"
+- "Add rate limiting, input validation, and CSRF protection across all public endpoints"
+
+## Phase Sizing Guidelines
+
+- Each phase should have 3-8 requirements
+- If a phase has 10+ requirements, it's too large — split it
+- If a phase has 1-2 requirements, merge with a related phase
+- Aim for 3-6 phases total for most projects
+
+## Output Marker
+
+When complete, output:
+```
+## ROADMAP COMPLETE
+Phases: [count]
+Dependency depth: [max chain length]
+Parallelizable: [phases with same/no dependencies that could run concurrently]
+```

package/package.json

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