brain-dev 2.5.1 → 2.6.0

package/bin/brain-tools.cjs

@@ -182,6 +182,10 @@ async function main() {
       await require('./lib/commands/review.cjs').run(args.slice(1));
       break;
 
+    case 'remove':
+      await require('./lib/commands/remove.cjs').run(args.slice(1));
+      break;
+
     case 'upgrade':
       await require('./lib/commands/upgrade.cjs').run(args.slice(1), {
         brainDir: path.join(process.cwd(), '.brain')

package/bin/lib/commands/remove.cjs

@@ -0,0 +1,308 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { readState, writeState } = require('../state.cjs');
+const { logEvent } = require('../logger.cjs');
+const { output, error, prefix, success } = require('../core.cjs');
+
+const VALID_TYPES = ['task', 'story', 'quick'];
+
+/**
+ * Find an entity's directory and metadata by type and number.
+ * @param {string} brainDir
+ * @param {object} state
+ * @param {string} type - 'task' | 'story' | 'quick'
+ * @param {number} num
+ * @returns {{ dir: string, meta: object } | null}
+ */
+function findEntity(brainDir, state, type, num) {
+  if (type === 'task') {
+    const tasksDir = path.join(brainDir, 'tasks');
+    if (!fs.existsSync(tasksDir)) return null;
+    const padded = String(num).padStart(2, '0');
+    const match = fs.readdirSync(tasksDir).find(d => d.startsWith(`${padded}-`));
+    if (!match) return null;
+    const dir = path.join(tasksDir, match);
+    const metaPath = path.join(dir, 'task.json');
+    let meta = { num, description: match };
+    try { meta = JSON.parse(fs.readFileSync(metaPath, 'utf8')); } catch { /* use default */ }
+    return { dir, meta };
+  }
+
+  if (type === 'story') {
+    // Find dirName from state arrays
+    const allStories = [...(state.stories?.active || []), ...(state.stories?.history || [])];
+    const storyEntry = allStories.find(s => s.num === num);
+    if (storyEntry && storyEntry.dirName) {
+      const dir = path.join(brainDir, 'stories', storyEntry.dirName);
+      let meta = { num, title: storyEntry.title || storyEntry.dirName, dirName: storyEntry.dirName };
+      const metaPath = path.join(dir, 'story.json');
+      try { meta = JSON.parse(fs.readFileSync(metaPath, 'utf8')); } catch { /* use default */ }
+      return { dir, meta };
+    }
+    // Fallback: scan story directories
+    const storiesDir = path.join(brainDir, 'stories');
+    if (!fs.existsSync(storiesDir)) return null;
+    for (const d of fs.readdirSync(storiesDir)) {
+      const metaPath = path.join(storiesDir, d, 'story.json');
+      try {
+        const meta = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+        if (meta.num === num) return { dir: path.join(storiesDir, d), meta };
+      } catch { continue; }
+    }
+    return null;
+  }
+
+  if (type === 'quick') {
+    const quickDir = path.join(brainDir, 'quick');
+    if (!fs.existsSync(quickDir)) return null;
+    const match = fs.readdirSync(quickDir).find(d => d.startsWith(`${num}-`));
+    if (!match) return null;
+    const dir = path.join(quickDir, match);
+    let meta = { num, description: match };
+    const metaPath = path.join(dir, 'task.json');
+    try { meta = JSON.parse(fs.readFileSync(metaPath, 'utf8')); } catch { /* use default */ }
+    return { dir, meta };
+  }
+
+  return null;
+}
+
+/**
+ * Run the remove command.
+ * @param {string[]} args - [type, number, --confirm, --force]
+ * @param {object} [opts]
+ */
+async function run(args = [], opts = {}) {
+  const brainDir = opts.brainDir || path.join(process.cwd(), '.brain');
+  const state = readState(brainDir);
+
+  if (!state) {
+    error("No brain state found. Run 'brain-dev init' first.");
+    return { error: 'no-state' };
+  }
+
+  // Parse args
+  const type = args[0];
+  const numStr = args[1];
+  const confirm = args.includes('--confirm');
+  const force = args.includes('--force');
+
+  if (!type) {
+    error('Usage: brain-dev remove <task|story|quick> <number> [--confirm] [--force]');
+    return { error: 'missing-type' };
+  }
+
+  if (!VALID_TYPES.includes(type)) {
+    error(`Invalid type "${type}". Must be one of: ${VALID_TYPES.join(', ')}`);
+    return { error: 'invalid-type' };
+  }
+
+  const num = parseInt(numStr, 10);
+  if (!numStr || isNaN(num) || num < 1) {
+    error(`Invalid number "${numStr}". Must be a positive integer.`);
+    return { error: 'invalid-number' };
+  }
+
+  // Find entity
+  const entity = findEntity(brainDir, state, type, num);
+  const dirExists = entity && fs.existsSync(entity.dir);
+
+  // Also check state arrays for entries without directory
+  const stateEntry = findStateEntry(state, type, num);
+
+  if (!entity && !stateEntry) {
+    error(`${type} #${num} not found.`);
+    return { error: 'not-found' };
+  }
+
+  const meta = entity?.meta || stateEntry || { num };
+  // Merge promoted_to_phase from state if disk meta is missing it (corrupt task.json)
+  if (!meta.promoted_to_phase && stateEntry?.promoted_to_phase) {
+    meta.promoted_to_phase = stateEntry.promoted_to_phase;
+  }
+  const entityDir = entity?.dir || null;
+
+  // Determine if this is the current active item
+  const isCurrent = isCurrentItem(state, type, num, meta);
+
+  // Safety checks
+  const safety = checkSafety(state, type, num, meta, force);
+
+  // Preview mode (no --confirm) — show preview even if blocked
+  if (!confirm) {
+    const description = meta.description || meta.title || meta.slug || `#${num}`;
+    const warnings = [];
+    if (isCurrent) warnings.push(`This is the current active ${type}`);
+    if (safety.blocked) warnings.push(`BLOCKED: ${safety.message}`);
+    if (safety.warnings) warnings.push(...safety.warnings);
+
+    const humanLines = [
+      prefix(`Remove ${type} #${num}: ${description}`),
+      dirExists ? prefix(`Directory: ${entityDir}`) : prefix('Directory: not found on disk'),
+      isCurrent ? prefix('WARNING: This is the current active item') : '',
+      safety.blocked ? prefix(`BLOCKED: ${safety.message}`) : '',
+      ...warnings.filter(w => !w.startsWith('BLOCKED:')).map(w => prefix(`WARNING: ${w}`)),
+      '',
+      safety.blocked ? '' : prefix(`To confirm: brain-dev remove ${type} ${num} --confirm`),
+      type === 'story' && safety.blocked && safety.code === 'story-phases-active' ? prefix('To force: brain-dev remove story ' + num + ' --confirm --force') : ''
+    ].filter(Boolean).join('\n');
+
+    const result = {
+      action: 'preview-remove',
+      type,
+      num,
+      description,
+      directory: entityDir,
+      isCurrent,
+      warnings,
+      instructions: `brain-dev remove ${type} ${num} --confirm`
+    };
+
+    output(result, humanLines);
+    return result;
+  }
+
+  // Block execution if safety check fails
+  if (safety.blocked) {
+    error(safety.message);
+    return { error: safety.code, message: safety.message };
+  }
+
+  // Execute removal
+  return executeRemove(brainDir, state, type, num, meta, entityDir, isCurrent);
+}
+
+/**
+ * Find an entity in state arrays (without reading disk).
+ */
+function findStateEntry(state, type, num) {
+  if (type === 'task') {
+    return (state.tasks?.active || []).find(t => t.num === num)
+      || (state.tasks?.history || []).find(t => t.num === num)
+      || null;
+  }
+  if (type === 'story') {
+    return (state.stories?.active || []).find(s => s.num === num)
+      || (state.stories?.history || []).find(s => s.num === num)
+      || null;
+  }
+  return null; // Quick tasks have no state arrays
+}
+
+/**
+ * Check if the item is the currently active one.
+ */
+function isCurrentItem(state, type, num, meta) {
+  if (type === 'task') return state.tasks?.current === num;
+  if (type === 'story') return state.stories?.current === (meta.dirName || null);
+  return false; // Quick tasks have no "current" concept
+}
+
+/**
+ * Run safety checks per entity type.
+ * @returns {{ blocked: boolean, code?: string, message?: string, warnings?: string[] }}
+ */
+function checkSafety(state, type, num, meta, force) {
+  const warnings = [];
+
+  if (type === 'task') {
+    if (meta.promoted_to_phase) {
+      return {
+        blocked: true,
+        code: 'promoted-task',
+        message: `Cannot remove task #${num}: promoted to Phase ${meta.promoted_to_phase}. Remove the phase first.`
+      };
+    }
+  }
+
+  if (type === 'story') {
+    const isCurrent = state.stories?.current === (meta.dirName || null);
+    if (isCurrent && Array.isArray(state.phase?.phases)) {
+      const hasActivePhases = state.phase.phases.some(p =>
+        p.status !== 'complete' && p.status !== 'completed');
+      if (hasActivePhases) {
+        if (!force) {
+          return {
+            blocked: true,
+            code: 'story-phases-active',
+            message: `Cannot remove story #${num}: it is the current story with non-complete phases. Use --force to override.`
+          };
+        }
+        warnings.push('Story has non-complete phases (forced removal)');
+      }
+    }
+  }
+
+  return { blocked: false, warnings };
+}
+
+/**
+ * Execute the actual removal.
+ */
+function executeRemove(brainDir, state, type, num, meta, entityDir, isCurrent) {
+  const description = meta.description || meta.title || meta.slug || `#${num}`;
+
+  // Delete directory if it exists
+  if (entityDir && fs.existsSync(entityDir)) {
+    fs.rmSync(entityDir, { recursive: true, force: true });
+  }
+
+  // Update state per type
+  if (type === 'task') {
+    if (state.tasks) {
+      state.tasks.active = (state.tasks.active || []).filter(t => t.num !== num);
+      state.tasks.history = (state.tasks.history || []).filter(t => t.num !== num);
+      if (state.tasks.current === num) state.tasks.current = null;
+    }
+  } else if (type === 'story') {
+    if (state.stories) {
+      const dirName = meta.dirName || null;
+      state.stories.active = (state.stories.active || []).filter(s => s.num !== num);
+      state.stories.history = (state.stories.history || []).filter(s => s.num !== num);
+      if (state.stories.current === dirName) {
+        state.stories.current = null;
+        // Reset phase state owned by the removed story
+        if (state.phase) {
+          state.phase.current = 0;
+          state.phase.status = 'initialized';
+          state.phase.total = 0;
+          state.phase.phases = [];
+          state.phase.execution_started_at = null;
+          state.phase.stuck_count = 0;
+          state.phase.last_stuck_at = null;
+        }
+      }
+    }
+  }
+  // Quick tasks: no state arrays to update (count is never decremented)
+
+  writeState(brainDir, state);
+
+  logEvent(brainDir, 0, {
+    type: `${type}-removed`,
+    num,
+    description,
+    directory: entityDir ? path.basename(entityDir) : null
+  });
+
+  const humanLines = [
+    prefix(`Removed ${type} #${num}: ${description}`),
+    entityDir ? prefix(`Directory deleted: ${path.basename(entityDir)}`) : prefix('No directory to delete'),
+    isCurrent ? prefix('Cleared as current active item') : ''
+  ].filter(Boolean).join('\n');
+
+  const result = {
+    action: 'removed',
+    type,
+    num,
+    description,
+    directory: entityDir
+  };
+
+  output(result, humanLines);
+  return result;
+}
+
+module.exports = { run };

package/bin/lib/commands/story.cjs

@@ -913,7 +913,6 @@ function stepActivate(brainDir, state, storyDir, storyMeta) {
   // Update state phases
   state.phase = state.phase || { current: 0, status: 'initialized', total: 0, phases: [] };
   state.phase.current = 1;
-  syncPhaseStatus(state, 'ready');
   state.phase.total = roadmapData.phases.length;
   state.phase.phases = roadmapData.phases.map(p => ({
     number: p.number,
@@ -921,7 +920,8 @@ function stepActivate(brainDir, state, storyDir, storyMeta) {
     status: p.status === 'Pending' ? 'pending' : p.status.toLowerCase(),
     goal: p.goal
   }));
-  state.phase.execution_started_at = null;
+  // Sync AFTER phases array is rebuilt so per-phase status is correctly updated
+  syncPhaseStatus(state, 'ready');
   state.phase.stuck_count = 0;
   state.phase.last_stuck_at = null;
 

package/bin/lib/commands.cjs

@@ -119,6 +119,15 @@ const COMMANDS = [
     needsState: true,
     args: '  --phase <n>  Phase to mark complete'
   },
+  {
+    name: 'remove',
+    description: 'Remove/cancel a task, story, or quick task',
+    usage: 'brain-dev remove <task|story|quick> <number> [--confirm] [--force]',
+    group: 'Lifecycle',
+    implemented: true,
+    needsState: true,
+    args: '  <task|story|quick>  Entity type\n  <number>            Entity number\n  --confirm           Execute removal\n  --force             Override safety checks'
+  },
   {
     name: 'map',
     description: 'Map codebase structure and patterns',

package/commands/brain/remove.md

@@ -0,0 +1,39 @@
+---
+name: brain:remove
+description: Remove/cancel a task, story, or quick task by number
+argument-hint: "<task|story|quick> <number>"
+allowed-tools:
+  - Read
+  - Bash
+  - AskUserQuestion
+---
+<objective>
+Remove a task, story, or quick task that is no longer needed. Supports preview before deletion and safety checks.
+</objective>
+
+<context>
+Usage:
+- `npx brain-dev remove task 3` — preview what will be removed
+- `npx brain-dev remove task 3 --confirm` — execute removal
+- `npx brain-dev remove story 1 --confirm --force` — force remove story with active phases
+</context>
+
+<critical-rules>
+## PIPELINE ENFORCEMENT (NON-NEGOTIABLE):
+1. Run `npx brain-dev remove $ARGUMENTS` FIRST (preview mode)
+2. READ the full output — check warnings
+3. Ask the user for confirmation using AskUserQuestion
+4. Run `npx brain-dev remove $ARGUMENTS --confirm` to execute
+5. Removal is PERMANENT — directory and all artifacts are deleted
+6. NEVER bypass the preview step
+7. If output shows ERROR (promoted task, active phases): explain to user and do NOT retry with --confirm
+</critical-rules>
+
+<process>
+1. If user didn't specify type or number, ask using AskUserQuestion
+2. Run preview: `npx brain-dev remove <type> <number>`
+3. Show the user what will be deleted and any warnings
+4. Ask for confirmation
+5. Run: `npx brain-dev remove <type> <number> --confirm`
+6. For stories with active phases: add `--force` only if user explicitly agrees
+</process>

package/package.json

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