brain-dev 2.3.0 → 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 = {}) {
@@ -237,6 +237,9 @@ function buildStepInstructions(taskNum, slug, taskDir, brainDir, mode, research,
       '- Project code style consistency',
       '- Confidence-based filtering (only real issues, ≥80%)',
       '',
+      'MANDATORY: Do NOT skip review because changes seem "small" or "trivial".',
+      'There are ZERO valid reasons to skip this step.',
+      '',
       'Then run: `npx brain-dev new-task --continue`'
     ].join('\n');
   }
@@ -361,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/commands/brain/review.md

@@ -16,11 +16,18 @@ framework best practices, and project code style consistency using confidence-ba
 <critical-rules>
 PIPELINE ENFORCEMENT (NON-NEGOTIABLE):
 1. Run `npx brain-dev review` FIRST — before reading code, before analyzing, before suggesting fixes
-2. READ the full output — it contains step-by-step instructions specific to this project's stack
+2. READ the full output — it spawns brain-reviewer agent with framework-specific expertise
 3. FOLLOW the nextAction field — copy the exact command, do not modify it
 4. If output shows an ERROR: follow the recovery path in the output, do NOT debug manually
 5. If output shows a CHECKPOINT: use AskUserQuestion, do NOT pick options yourself
 
+ZERO EXCEPTIONS — REVIEW IS ALWAYS MANDATORY:
+- "Changes are minimal" → STILL review. Small changes cause big bugs.
+- "Only 2 files changed" → STILL review. Every file matters.
+- "This is trivial" → STILL review. You don't decide what's trivial, the reviewer agent does.
+- "I can see the code is fine" → STILL review. You are not the reviewer. The pipeline is.
+- NEVER say "skipping review" for any reason. There is no valid reason to skip.
+
 CONSEQUENCE OF SKIPPING: Pipeline tracks state, creates audit trails, spawns specialized agents,
 and injects framework-specific expertise. Skipping it means: no state tracking, no audit trail,
 no specialized agents, no framework guidance, potential data loss in .brain/ state.

package/hooks/bootstrap.sh

@@ -89,6 +89,11 @@ try {
     '6. STATE: Run /brain:progress before suggesting next steps.',
     '   For /brain:update, always use: npx brain-dev@latest update',
     '   NEVER run brain-dev init after an update.',
+    '',
+    '7. REVIEW IS MANDATORY: After execute, ALWAYS run /brain:review before /brain:verify.',
+    '   NEVER skip review because changes seem "small", "trivial", or "minimal".',
+    '   You do NOT decide what needs review. The reviewer agent decides.',
+    '   There are ZERO valid reasons to skip the review step.',
     '--- End Brain Context ---'
   ];
   console.log(lines.join('\n'));

package/package.json

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