brain-dev 2.3.1 → 2.4.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/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/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/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/package.json

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