brain-dev 2.3.1 → 2.5.0

package/README.md

@@ -30,6 +30,7 @@ Brain adds structure without adding friction:
 /brain:discuss      →  Captures architectural decisions before coding
 /brain:plan         →  Creates verified execution plans with TDD
 /brain:execute      →  Builds with per-task commits and deviation handling
+/brain:review       →  Mandatory code review before verification
 /brain:verify       →  3-level verification against must-haves
 /brain:complete     →  Advances to next phase with audit trail
 ```
@@ -56,7 +57,7 @@ Brain provides four levels of work, from lightweight to comprehensive:
 
 ```
 quick        →  plan → execute → commit                    (minutes)
-new-task     →  discuss → plan → execute → verify           (hours)
+new-task     →  discuss → plan → execute → review → verify   (hours)
 story        →  research → requirements → roadmap → phases  (days/weeks)
 new-project  →  detect → map → suggest next step            (one-time setup)
 ```
@@ -94,7 +95,7 @@ For features that need more than a quick fix but less than a full story:
 /brain:new-task "add payment integration with Stripe"
 ```
 
-Brain runs the full pipeline: discuss → plan → execute → verify → complete.
+Brain runs the full pipeline: discuss → plan → execute → review → verify → complete.
 
 ```bash
 /brain:new-task --research "add rate limiting"   # With light research
@@ -150,7 +151,7 @@ No configuration needed — Brain detects your stack and injects expertise into
 ## Lifecycle
 
 ```
-init → new-project → story → discuss → plan → execute → verify → complete
+init → new-project → story → discuss → plan → execute → review → verify → complete
                        ↑                                             │
                        └──────────── next story/phase ───────────────┘
 ```
@@ -173,14 +174,14 @@ Run phases autonomously without human intervention:
 /brain:execute --auto --stop     # Stop running auto session
 ```
 
-Auto mode chains: discuss → plan → execute → verify → complete → next phase, with budget limits, stuck detection, and crash recovery built in.
+Auto mode chains: discuss → plan → execute → review → verify → complete → next phase, with budget limits, stuck detection, and crash recovery built in.
 
 ## State Machine
 
 Brain tracks progress through a deterministic state machine:
 
 ```
-pending → discussing → discussed → planning → executing → executed → verifying → verified → complete
+pending → discussing → discussed → planning → executing → executed → reviewing → reviewed → verifying → verified → complete
 ```
 
 Every command knows what comes next. `brain-dev progress` always tells you the right next step.
@@ -223,6 +224,7 @@ No supply chain risk. No transitive vulnerabilities. No `node_modules` bloat.
 | `/brain:discuss` | Capture architectural decisions |
 | `/brain:plan` | Create verified execution plans |
 | `/brain:execute` | Build according to plans with TDD |
+| `/brain:review` | Mandatory code review before verification |
 | `/brain:verify` | 3-level verification against must-haves |
 | `/brain:complete` | Mark phase done, advance to next |
 | `/brain:quick` | Quick task — skip the ceremony |

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/execute.cjs

@@ -6,7 +6,7 @@ const { readState, writeState } = require('../state.cjs');
 const { loadTemplate, interpolate, loadTemplateWithOverlay } = require('../templates.cjs');
 const { getAgent, resolveModel } = require('../agents.cjs');
 const { logEvent } = require('../logger.cjs');
-const { output, error } = require('../core.cjs');
+const { output, error, pipelineGate } = require('../core.cjs');
 const { recordInvocation, estimateTokens } = require('../cost.cjs');
 const { acquireLock, releaseLock } = require('../lock.cjs');
 const { generateExpertise, getDetectedFramework } = require('../stack-expert.cjs');
@@ -306,9 +306,9 @@ async function run(args = [], opts = {}) {
   if (!targetPlan) {
     state.phase.status = 'executed';
     writeState(brainDir, state);
-    const msg = "All plans executed. Run /brain:verify to check the work.";
-    output({ action: 'all-executed', message: msg, nextAction: '/brain:verify' }, `[brain] ${msg}`);
-    return { action: 'all-executed', message: msg, nextAction: '/brain:verify' };
+    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)}`);
+    return { action: 'all-executed', message: msg, nextAction: '/brain:review' };
   }
 
   // Read plan content
@@ -409,10 +409,8 @@ async function run(args = [], opts = {}) {
       buildDebuggerSpawnInstructions(taskSlug, errorCtx, taskCtx, attemptedFixes, state)
   };
 
-  // Build verify command with optional --auto-recover
-  const verifyCmd = autoRecover
-    ? `brain-dev verify --phase ${phaseNumber} --auto-recover`
-    : `brain-dev verify --phase ${phaseNumber}`;
+  // Build review command (review is mandatory before verify)
+  const reviewCmd = `brain-dev review --phase ${phaseNumber}`;
 
   const humanLines = [
     `[brain] Executor instructions generated for Plan ${padded} in Phase ${phaseNumber}`,
@@ -425,7 +423,8 @@ async function run(args = [], opts = {}) {
   if (autoRecover) {
     humanLines.push('[brain] Auto-recovery: enabled (verify will auto-diagnose failures)');
   }
-  humanLines.push(`[brain] Verify with: ${verifyCmd}`);
+  humanLines.push(`[brain] After execution, review with: ${reviewCmd}`);
+  humanLines.push(pipelineGate(`npx brain-dev review --phase ${phaseNumber}`));
   humanLines.push('');
   humanLines.push(fullPrompt);
   output(result, humanLines.join('\n'));

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

@@ -5,7 +5,7 @@ const path = require('node:path');
 const { parseArgs } = require('node:util');
 const { readState, writeState } = require('../state.cjs');
 const { logEvent } = require('../logger.cjs');
-const { output, error, prefix } = require('../core.cjs');
+const { output, error, prefix, pipelineGate } = require('../core.cjs');
 const { recordInvocation, estimateTokens } = require('../cost.cjs');
 
 async function run(args = [], opts = {}) {
@@ -364,7 +364,8 @@ function handleContinue(brainDir, state) {
     prefix(`Status: ${newStatus}`),
     prefix(`Next step: ${nextStep}`),
     '',
-    steps[nextStep]
+    steps[nextStep],
+    nextStep === 'review' ? pipelineGate('npx brain-dev review') : ''
   ].join('\n');
 
   output({

package/bin/lib/commands/quick.cjs

@@ -6,7 +6,7 @@ const { readState, writeState } = require('../state.cjs');
 const { loadTemplate, interpolate } = require('../templates.cjs');
 const { resolveModel } = require('../agents.cjs');
 const { logEvent } = require('../logger.cjs');
-const { output, error, success } = require('../core.cjs');
+const { output, error, success, pipelineGate } = require('../core.cjs');
 const { generateExpertise } = require('../stack-expert.cjs');
 
 /**
@@ -265,7 +265,7 @@ function handleExecute(args, brainDir, state) {
   } catch { /* ignore */ }
 
   const nextCmd = isFull
-    ? `npx brain-dev quick --verify --task ${taskNum}`
+    ? `npx brain-dev review`
     : `npx brain-dev quick --complete --task ${taskNum}`;
 
   logEvent(brainDir, 0, { type: 'quick-execute', task: taskNum });
@@ -279,9 +279,10 @@ function handleExecute(args, brainDir, state) {
     'Do NOT execute the tasks yourself.',
     '',
     `After executor completes, run: ${nextCmd}`,
+    isFull ? pipelineGate('npx brain-dev review') : '',
     '',
     prompt
-  ].join('\n');
+  ].filter(Boolean).join('\n');
 
   const result = {
     action: 'spawn-quick-executor',
@@ -313,6 +314,17 @@ function handleVerify(args, brainDir, state) {
     return { error: 'task-not-found' };
   }
 
+  // Hard gate: review must be completed before verify
+  const reviewPath = path.join(taskDir, 'REVIEW.md');
+  if (!fs.existsSync(reviewPath)) {
+    error('Review is mandatory before verify. Run: /brain:review first.');
+    output(
+      { error: 'review-required', nextAction: '/brain:review' },
+      `[brain] BLOCKED: Run /brain:review before quick --verify\n${pipelineGate('npx brain-dev review')}`
+    );
+    return { error: 'review-required' };
+  }
+
   const planPath = path.join(taskDir, 'PLAN-1.md');
   const verificationPath = path.join(taskDir, 'VERIFICATION-1.md');
 

package/bin/lib/commands/story.cjs

@@ -6,14 +6,15 @@ const { parseArgs } = require('node:util');
 const { readState, writeState } = 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(', ')})`)),

package/bin/lib/commands/verify.cjs

@@ -6,7 +6,7 @@ const { readState, writeState, atomicWriteSync } = require('../state.cjs');
 const { loadTemplate, interpolate, loadTemplateWithOverlay } = require('../templates.cjs');
 const { getAgent, resolveModel } = require('../agents.cjs');
 const { logEvent } = require('../logger.cjs');
-const { output, error, success } = require('../core.cjs');
+const { output, error, success, pipelineGate } = require('../core.cjs');
 const antiPatterns = require('../anti-patterns.cjs');
 const { buildDebuggerSpawnInstructions } = require('./execute.cjs');
 const { isPathWithinRoot } = require('../security.cjs');
@@ -203,6 +203,17 @@ async function run(args = [], opts = {}) {
     return { error: 'phase-not-found' };
   }
 
+  // Hard gate: review must be completed before verify
+  const reviewPath = path.join(phaseDir, 'REVIEW.md');
+  if (!fs.existsSync(reviewPath)) {
+    error('Review is mandatory before verify. Run: /brain:review first.');
+    output(
+      { error: 'review-required', nextAction: '/brain:review' },
+      `[brain] BLOCKED: Run /brain:review before /brain:verify\n${pipelineGate('npx brain-dev review --phase ' + phaseNumber)}`
+    );
+    return { error: 'review-required' };
+  }
+
   // Scan for PLAN-*.md files and extract must_haves from each
   const files = fs.readdirSync(phaseDir);
   const planFiles = files.filter(f => /^PLAN-\d+\.md$/.test(f)).sort();

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/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/executor.md

@@ -243,6 +243,13 @@ Include sections:
 - On failure after retry: `## EXECUTION FAILED`
 - On checkpoint (user input needed): `## CHECKPOINT REACHED`
 
+## After Execution Completes
+
+When you output EXECUTION COMPLETE:
+- The orchestrator will run /brain:review BEFORE /brain:verify
+- Review is MANDATORY — it cannot be skipped for any reason
+- Do NOT suggest running verify directly after execution
+
 ## Pipeline Enforcement Reminders
 
 **EXECUTION FAILED:** When you output this marker:

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.3.1",
+  "version": "2.5.0",
   "description": "AI-powered development workflow orchestrator",
   "author": "halilcosdu",
   "license": "MIT",