brain-dev 0.2.0 → 1.0.0

package/bin/lib/commands/story.cjs

@@ -0,0 +1,972 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+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 { getAgent, resolveModel } = require('../agents.cjs');
+const {
+  RESEARCH_AREAS, CORE_QUESTIONS, buildBrownfieldQuestions,
+  readDetection, buildCodebaseContext, generateProjectMd,
+  generateRequirementsMd, extractFeatures, extractSection
+} = require('../story-helpers.cjs');
+
+async function run(args = [], opts = {}) {
+  const { values, positionals } = parseArgs({
+    args,
+    options: {
+      continue: { type: 'boolean', default: false },
+      list: { type: 'boolean', default: false },
+      complete: { type: 'boolean', default: false },
+      status: { type: 'boolean', default: false },
+      research: { type: 'boolean', default: false },
+      'no-research': { type: 'boolean', default: false },
+      answers: { type: 'string' },
+      json: { type: 'boolean', default: false }
+    },
+    strict: false,
+    allowPositionals: true
+  });
+
+  const brainDir = opts.brainDir || path.join(process.cwd(), '.brain');
+  const state = readState(brainDir);
+
+  if (!state || !state.project?.initialized) {
+    error("Project not initialized. Run '/brain:new-project' first.");
+    return { error: 'not-initialized' };
+  }
+
+  if (values.list) return handleList(brainDir, state);
+  if (values.status) return handleStatus(brainDir, state);
+  if (values.complete) return handleComplete(brainDir, state);
+  if (values.continue) return handleContinue(brainDir, state, values);
+
+  // Answers for step 1 (after questions asked)
+  if (values.answers) return handleAnswers(brainDir, state, values.answers);
+
+  // New story
+  const title = positionals.join(' ').trim();
+  if (!title) {
+    error('Usage: brain-dev story "v1.1 Feature title" [--research] [--no-research]');
+    return { error: 'no-title' };
+  }
+
+  return handleNewStory(brainDir, state, title, values);
+}
+
+// ---------------------------------------------------------------------------
+// handleNewStory
+// ---------------------------------------------------------------------------
+
+function handleNewStory(brainDir, state, title, options) {
+  // Guard: no concurrent stories
+  state.stories = state.stories || { current: null, count: 0, active: [], history: [] };
+  if (state.stories.current) {
+    error(`A story is already active: ${state.stories.current}. Complete it first or use --continue.`);
+    return { error: 'story-already-active', current: state.stories.current };
+  }
+
+  // Extract version from title (e.g. "v1.1 Add auth" -> version "v1.1", rest = "Add auth")
+  const versionMatch = title.match(/^(v\d+\.\d+)\s+(.+)$/i);
+  let version, storyTitle;
+  if (versionMatch) {
+    version = versionMatch[1].toLowerCase();
+    storyTitle = versionMatch[2].trim();
+  } else {
+    version = (state.milestone && state.milestone.current) || 'v1.0';
+    storyTitle = title;
+  }
+
+  // Generate slug
+  const slug = storyTitle
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, 40) || 'story';
+
+  const storyDirName = `${version}-${slug}`;
+  const storyDir = path.join(brainDir, 'stories', storyDirName);
+  fs.mkdirSync(storyDir, { recursive: true });
+
+  // Story metadata
+  const storyNum = (state.stories.count || 0) + 1;
+  const storyMeta = {
+    num: storyNum,
+    version,
+    title: storyTitle,
+    slug,
+    dirName: storyDirName,
+    created: new Date().toISOString(),
+    status: 'initialized',
+    research: options.research || false,
+    noResearch: options['no-research'] || false,
+    completed: null
+  };
+
+  fs.writeFileSync(path.join(storyDir, 'story.json'), JSON.stringify(storyMeta, null, 2));
+
+  // Update state
+  state.stories.current = storyDirName;
+  state.stories.count = storyNum;
+  state.stories.active = state.stories.active || [];
+  state.stories.active.push({
+    num: storyNum,
+    version,
+    title: storyTitle,
+    slug,
+    dirName: storyDirName,
+    status: 'initialized'
+  });
+  writeState(brainDir, state);
+
+  logEvent(brainDir, 0, { type: 'story-init', story: storyNum, version, title: storyTitle, slug });
+
+  // Build questions
+  const detection = readDetection(brainDir);
+  const isBrownfield = detection && detection.type === 'brownfield';
+  const questions = isBrownfield
+    ? buildBrownfieldQuestions(detection)
+    : CORE_QUESTIONS;
+
+  const humanLines = [
+    prefix(`Story #${storyNum} created: ${version} ${storyTitle}`),
+    prefix(`Directory: .brain/stories/${storyDirName}/`),
+    '',
+    prefix('Answer the following questions to define this story:'),
+    '',
+    ...questions.map((q, i) => {
+      const lines = [`  ${i + 1}. ${q.text}`];
+      if (q.options) {
+        for (const opt of q.options) {
+          lines.push(`     - ${opt.label}: ${opt.description}`);
+        }
+      }
+      return lines.join('\n');
+    }),
+    '',
+    prefix('Provide answers as JSON with --answers flag:'),
+    prefix(`  brain-dev story --answers '${JSON.stringify({ vision: '...', users: '...', features: '...', constraints: '...' })}'`)
+  ].join('\n');
+
+  const result = {
+    action: 'story-ask-questions',
+    questions,
+    story: storyMeta
+  };
+
+  output(result, humanLines);
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// handleAnswers
+// ---------------------------------------------------------------------------
+
+function handleAnswers(brainDir, state, answersJson) {
+  let answers;
+  try {
+    answers = JSON.parse(answersJson);
+  } catch (e) {
+    error(`Invalid JSON for --answers: ${e.message}`);
+    return { error: 'invalid-answers-json', message: e.message };
+  }
+
+  state.stories = state.stories || { current: null, count: 0, active: [], history: [] };
+  const currentSlug = state.stories.current;
+  if (!currentSlug) {
+    error('No active story. Start one with: brain-dev story "title"');
+    return { error: 'no-active-story' };
+  }
+
+  const storyDir = path.join(brainDir, 'stories', currentSlug);
+  if (!fs.existsSync(storyDir)) {
+    error(`Story directory not found: ${currentSlug}`);
+    return { error: 'story-dir-not-found' };
+  }
+
+  // Read detection for brownfield context
+  const detection = readDetection(brainDir);
+
+  // Generate and write PROJECT.md
+  const projectMd = generateProjectMd(answers, detection);
+  fs.writeFileSync(path.join(storyDir, 'PROJECT.md'), projectMd, 'utf8');
+
+  // Update story.json
+  const storyMetaPath = path.join(storyDir, 'story.json');
+  const storyMeta = JSON.parse(fs.readFileSync(storyMetaPath, 'utf8'));
+  storyMeta.status = 'initialized';
+  storyMeta.answersReceived = new Date().toISOString();
+  fs.writeFileSync(storyMetaPath, JSON.stringify(storyMeta, null, 2));
+
+  // Update state active entry
+  const activeIdx = (state.stories.active || []).findIndex(s => s.dirName === currentSlug);
+  if (activeIdx >= 0) state.stories.active[activeIdx].status = 'initialized';
+  writeState(brainDir, state);
+
+  logEvent(brainDir, 0, { type: 'story-answers', story: storyMeta.num, slug: storyMeta.slug });
+
+  // Determine next step
+  const skipResearch = storyMeta.noResearch === true;
+  const nextStep = skipResearch ? 'requirements' : 'research';
+
+  const humanLines = [
+    prefix(`Answers saved for story: ${storyMeta.version} ${storyMeta.title}`),
+    prefix(`PROJECT.md written to .brain/stories/${currentSlug}/PROJECT.md`),
+    '',
+    prefix(`Next step: ${nextStep}`),
+    prefix('Run: brain-dev story --continue')
+  ].join('\n');
+
+  const result = {
+    action: 'story-answers-saved',
+    nextStep
+  };
+
+  output(result, humanLines);
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// handleContinue
+// ---------------------------------------------------------------------------
+
+function handleContinue(brainDir, state, values) {
+  state.stories = state.stories || { current: null, count: 0, active: [], history: [] };
+  const currentSlug = state.stories.current;
+  if (!currentSlug) {
+    error('No active story. Start one with: brain-dev story "title"');
+    return { error: 'no-active-story' };
+  }
+
+  const storyDir = path.join(brainDir, 'stories', currentSlug);
+  if (!fs.existsSync(storyDir)) {
+    error(`Story directory not found: ${currentSlug}`);
+    return { error: 'story-dir-not-found' };
+  }
+
+  const storyMetaPath = path.join(storyDir, 'story.json');
+  const storyMeta = JSON.parse(fs.readFileSync(storyMetaPath, 'utf8'));
+
+  // File-existence based step detection
+  const hasProjectMd = fs.existsSync(path.join(storyDir, 'PROJECT.md'));
+  const hasResearchDir = fs.existsSync(path.join(storyDir, 'research'));
+  const hasSummaryMd = hasResearchDir && fs.existsSync(path.join(storyDir, 'research', 'SUMMARY.md'));
+  const hasRequirementsMd = fs.existsSync(path.join(storyDir, 'REQUIREMENTS.md'));
+  const hasRoadmapMd = fs.existsSync(path.join(storyDir, 'ROADMAP.md'));
+  const skipResearch = storyMeta.noResearch === true || values['no-research'];
+
+  if (!hasProjectMd) {
+    error("Run 'brain-dev story --answers' first to provide project context.");
+    return { error: 'no-project-md', instruction: 'Provide answers via --answers flag' };
+  }
+
+  if (!hasResearchDir && !skipResearch) {
+    return stepResearch(brainDir, storyDir, storyMeta, state);
+  }
+
+  if (hasResearchDir && !hasSummaryMd && !skipResearch) {
+    return stepSynthesize(brainDir, storyDir, storyMeta, state);
+  }
+
+  if (!hasRequirementsMd) {
+    return stepRequirements(brainDir, storyDir, storyMeta, state);
+  }
+
+  if (!hasRoadmapMd) {
+    return stepRoadmap(brainDir, storyDir, storyMeta, state);
+  }
+
+  if (storyMeta.status !== 'active') {
+    return stepActivate(brainDir, state, storyDir, storyMeta);
+  }
+
+  // Already active
+  const humanLines = [
+    prefix(`Story "${storyMeta.version} ${storyMeta.title}" is already active.`),
+    prefix("Use '/brain:discuss' to begin phase work.")
+  ].join('\n');
+
+  output({ action: 'story-already-active', story: storyMeta }, humanLines);
+  return { action: 'story-already-active', story: storyMeta };
+}
+
+// ---------------------------------------------------------------------------
+// stepResearch
+// ---------------------------------------------------------------------------
+
+function stepResearch(brainDir, storyDir, storyMeta, state) {
+  // Read PROJECT.md for context
+  const projectMd = fs.readFileSync(path.join(storyDir, 'PROJECT.md'), 'utf8');
+
+  // Create research directory
+  const researchDir = path.join(storyDir, 'research');
+  fs.mkdirSync(researchDir, { recursive: true });
+
+  // Build researcher agent prompts
+  const agents = RESEARCH_AREAS.map(area => {
+    const agentDef = getAgent('researcher');
+    const model = resolveModel('researcher', state);
+    return {
+      name: area.name,
+      file: path.join(researchDir, area.file),
+      area: area.area,
+      description: area.description,
+      model,
+      prompt: [
+        `# Research Focus: ${area.area}`,
+        '',
+        `You are a ${area.description} researcher.`,
+        '',
+        '## Project Context',
+        projectMd,
+        '',
+        `## Your Focus Area: ${area.area}`,
+        '',
+        `Research and document findings about ${area.description} for this project.`,
+        'Be specific, actionable, and concise.',
+        '',
+        `Write your findings to: ${area.file}`
+      ].join('\n')
+    };
+  });
+
+  // Check brownfield and build mapper agents if codebase not yet mapped
+  const detection = readDetection(brainDir);
+  const isBrownfield = detection && detection.type === 'brownfield';
+  const codebaseDir = path.join(brainDir, 'codebase');
+  const codebaseMapped = fs.existsSync(codebaseDir) &&
+    fs.readdirSync(codebaseDir).filter(f => f.endsWith('.md')).length > 0;
+
+  let mapperAgents = [];
+  if (isBrownfield && !codebaseMapped) {
+    const mapperDef = getAgent('mapper');
+    const mapperModel = resolveModel('mapper', state);
+    const codebaseContext = buildCodebaseContext(detection);
+
+    mapperAgents = (mapperDef.focus || ['tech', 'arch', 'quality', 'concerns']).map(focus => ({
+      name: `mapper-${focus}`,
+      file: path.join(codebaseDir, `${focus}.md`),
+      focus,
+      model: mapperModel,
+      prompt: [
+        `# Codebase Mapping: ${focus}`,
+        '',
+        codebaseContext,
+        '',
+        `Map the codebase focusing on: ${focus}`,
+        `Write output to: codebase/${focus}.md`
+      ].join('\n')
+    }));
+
+    fs.mkdirSync(codebaseDir, { recursive: true });
+  }
+
+  // Update story status
+  storyMeta.status = 'researching';
+  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 = 'researching';
+  writeState(brainDir, state);
+
+  logEvent(brainDir, 0, { type: 'story-research', story: storyMeta.num, agents: agents.length, mappers: mapperAgents.length });
+
+  const humanLines = [
+    prefix(`Story: ${storyMeta.version} ${storyMeta.title}`),
+    prefix('Step: Research'),
+    '',
+    prefix(`Spawning ${agents.length} research agents:`),
+    ...agents.map(a => prefix(`  - ${a.name}: ${a.area}`)),
+    ...(mapperAgents.length > 0 ? [
+      '',
+      prefix(`Spawning ${mapperAgents.length} mapper agents:`),
+      ...mapperAgents.map(a => prefix(`  - ${a.name}: ${a.focus}`))
+    ] : []),
+    '',
+    prefix('After research completes, run: brain-dev story --continue')
+  ].join('\n');
+
+  const result = {
+    action: 'spawn-researchers',
+    agents,
+    mapperAgents
+  };
+
+  output(result, humanLines);
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// stepSynthesize
+// ---------------------------------------------------------------------------
+
+function stepSynthesize(brainDir, storyDir, storyMeta, state) {
+  const researchDir = path.join(storyDir, 'research');
+
+  // List research files
+  const researchFiles = fs.readdirSync(researchDir)
+    .filter(f => f.endsWith('.md') && f !== 'SUMMARY.md')
+    .map(f => ({
+      name: f,
+      path: path.join(researchDir, f),
+      area: f.replace('.md', '').replace(/-/g, ' ')
+    }));
+
+  // Build synthesis prompt
+  const synthAgent = getAgent('synthesizer');
+  const model = resolveModel('synthesizer', state);
+
+  const prompt = [
+    '# Research Synthesis',
+    '',
+    'Synthesize findings from all research agents into a unified SUMMARY.md.',
+    '',
+    '## Research Files',
+    ...researchFiles.map(f => `- ${f.name} (${f.area})`),
+    '',
+    '## Instructions',
+    '1. Read all research files in the research/ directory',
+    '2. Identify common themes, conflicts, and priorities',
+    '3. Create a unified SUMMARY.md with:',
+    '   - Key recommendations (prioritized)',
+    '   - Technology decisions',
+    '   - Architecture patterns to follow',
+    '   - Risks and mitigations',
+    '   - Testing strategy summary',
+    '',
+    `Write to: ${path.join(researchDir, 'SUMMARY.md')}`
+  ].join('\n');
+
+  // Update status
+  storyMeta.status = 'synthesizing';
+  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 = 'synthesizing';
+  writeState(brainDir, state);
+
+  logEvent(brainDir, 0, { type: 'story-synthesize', story: storyMeta.num, files: researchFiles.length });
+
+  const humanLines = [
+    prefix(`Story: ${storyMeta.version} ${storyMeta.title}`),
+    prefix('Step: Synthesize Research'),
+    '',
+    prefix(`Found ${researchFiles.length} research files to synthesize:`),
+    ...researchFiles.map(f => prefix(`  - ${f.name}`)),
+    '',
+    prefix('After synthesis completes, run: brain-dev story --continue')
+  ].join('\n');
+
+  const result = {
+    action: 'spawn-synthesis',
+    prompt,
+    model,
+    researchFiles
+  };
+
+  output(result, humanLines);
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// stepRequirements
+// ---------------------------------------------------------------------------
+
+function stepRequirements(brainDir, storyDir, storyMeta, state) {
+  // Read PROJECT.md for features
+  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');
+  let summaryContent = '';
+  if (fs.existsSync(summaryPath)) {
+    summaryContent = fs.readFileSync(summaryPath, 'utf8');
+  }
+
+  // Generate REQUIREMENTS.md
+  const { requirementsMd, categories } = generateRequirementsMd(features, summaryContent);
+  fs.writeFileSync(path.join(storyDir, 'REQUIREMENTS.md'), requirementsMd, 'utf8');
+
+  // Update status
+  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'),
+    '',
+    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;
+}
+
+// ---------------------------------------------------------------------------
+// stepRoadmap
+// ---------------------------------------------------------------------------
+
+function stepRoadmap(brainDir, storyDir, storyMeta, state) {
+  // Read REQUIREMENTS.md
+  const reqPath = path.join(storyDir, 'REQUIREMENTS.md');
+  const reqContent = fs.readFileSync(reqPath, 'utf8');
+
+  // Parse categories from REQUIREMENTS.md headings
+  const categoryRegex = /## (.+)\n([\s\S]*?)(?=\n## |$)/g;
+  const phases = [];
+  let catMatch;
+  let phaseNum = 1;
+
+  while ((catMatch = categoryRegex.exec(reqContent)) !== null) {
+    const catName = catMatch[1].trim();
+    if (catName === 'Requirements' || catName.toLowerCase() === 'requirements') continue;
+
+    // Extract requirement IDs from this category
+    const catBody = catMatch[2];
+    const reqIds = [];
+    const reqLineRegex = /- \*\*(\d+\.\d+)\*\*/g;
+    let reqMatch;
+    while ((reqMatch = reqLineRegex.exec(catBody)) !== null) {
+      reqIds.push(reqMatch[1]);
+    }
+
+    // Dependencies: each phase depends on the previous one (except phase 1)
+    const dependsOn = phaseNum > 1 ? [phaseNum - 1] : [];
+
+    phases.push({
+      number: phaseNum,
+      name: catName,
+      goal: `Implement ${catName.toLowerCase()} requirements`,
+      dependsOn,
+      requirements: reqIds,
+      plans: '',
+      status: 'Pending'
+    });
+
+    phaseNum++;
+  }
+
+  // Fallback: if no phases extracted, create a single phase
+  if (phases.length === 0) {
+    phases.push({
+      number: 1,
+      name: storyMeta.title,
+      goal: `Implement ${storyMeta.title}`,
+      dependsOn: [],
+      requirements: [],
+      plans: '',
+      status: 'Pending'
+    });
+  }
+
+  // Generate ROADMAP.md
+  const roadmapLines = [
+    '# Roadmap',
+    '',
+    `Story: ${storyMeta.version} ${storyMeta.title}`,
+    '',
+    '## Phases',
+    ''
+  ];
+
+  for (const phase of phases) {
+    roadmapLines.push(`### Phase ${phase.number}: ${phase.name}`);
+    roadmapLines.push('');
+    roadmapLines.push(`- **Goal:** ${phase.goal}`);
+    roadmapLines.push(`- **Depends on:** ${phase.dependsOn.length === 0 ? 'None' : phase.dependsOn.join(', ')}`);
+    roadmapLines.push(`- **Requirements:** ${phase.requirements.length === 0 ? 'None' : phase.requirements.join(', ')}`);
+    roadmapLines.push(`- **Status:** ${phase.status}`);
+    roadmapLines.push('');
+  }
+
+  // Progress table
+  roadmapLines.push('## Progress');
+  roadmapLines.push('');
+  roadmapLines.push('| Phase | Status | Plans |');
+  roadmapLines.push('|-------|--------|-------|');
+  for (const phase of phases) {
+    roadmapLines.push(`| ${phase.number} | ${phase.status} | 0/0 |`);
+  }
+  roadmapLines.push('');
+
+  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));
+
+  const activeIdx = (state.stories.active || []).findIndex(s => s.dirName === storyMeta.dirName);
+  if (activeIdx >= 0) state.stories.active[activeIdx].status = 'roadmap';
+  writeState(brainDir, state);
+
+  logEvent(brainDir, 0, { type: 'story-roadmap', story: storyMeta.num, phases: phases.length });
+
+  const humanLines = [
+    prefix(`Story: ${storyMeta.version} ${storyMeta.title}`),
+    prefix('Step: Roadmap Generated'),
+    '',
+    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(', ')})`)),
+    '',
+    prefix('Review ROADMAP.md and confirm.'),
+    prefix('Then run: brain-dev story --continue')
+  ].join('\n');
+
+  const result = {
+    action: 'roadmap-generated',
+    phases,
+    instruction: 'Review and confirm'
+  };
+
+  output(result, humanLines);
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// stepActivate
+// ---------------------------------------------------------------------------
+
+function stepActivate(brainDir, state, storyDir, storyMeta) {
+  const rootRoadmapPath = path.join(brainDir, 'ROADMAP.md');
+  const rootRequirementsPath = path.join(brainDir, 'REQUIREMENTS.md');
+
+  // Archive existing root ROADMAP.md if present
+  if (fs.existsSync(rootRoadmapPath)) {
+    const prevPath = path.join(brainDir, 'ROADMAP.prev.md');
+    fs.copyFileSync(rootRoadmapPath, prevPath);
+  }
+
+  // Copy story REQUIREMENTS.md and ROADMAP.md to .brain/ root
+  const storyReqPath = path.join(storyDir, 'REQUIREMENTS.md');
+  const storyRoadmapPath = path.join(storyDir, 'ROADMAP.md');
+
+  if (fs.existsSync(storyReqPath)) {
+    fs.copyFileSync(storyReqPath, rootRequirementsPath);
+  }
+  if (fs.existsSync(storyRoadmapPath)) {
+    fs.copyFileSync(storyRoadmapPath, rootRoadmapPath);
+  }
+
+  // Parse ROADMAP.md to get phases
+  const { parseRoadmap } = require('../roadmap.cjs');
+  const roadmapData = parseRoadmap(brainDir);
+
+  // Update state phases
+  state.phase = state.phase || { current: 0, status: 'initialized', total: 0, phases: [] };
+  state.phase.current = 1;
+  state.phase.status = 'ready';
+  state.phase.total = roadmapData.phases.length;
+  state.phase.phases = roadmapData.phases.map(p => ({
+    number: p.number,
+    name: p.name,
+    status: p.status === 'Pending' ? 'pending' : p.status.toLowerCase(),
+    goal: p.goal
+  }));
+  state.phase.execution_started_at = null;
+  state.phase.stuck_count = 0;
+  state.phase.last_stuck_at = null;
+
+  // Update milestone
+  state.milestone = state.milestone || { current: 'v1.0', name: null, history: [] };
+  state.milestone.current = storyMeta.version;
+  state.milestone.name = storyMeta.title;
+
+  // Update story status
+  storyMeta.status = 'active';
+  fs.writeFileSync(path.join(storyDir, 'story.json'), JSON.stringify(storyMeta, null, 2));
+
+  // Update state stories
+  const activeIdx = (state.stories.active || []).findIndex(s => s.dirName === storyMeta.dirName);
+  if (activeIdx >= 0) state.stories.active[activeIdx].status = 'active';
+  writeState(brainDir, state);
+
+  logEvent(brainDir, 0, {
+    type: 'story-activated',
+    story: storyMeta.num,
+    version: storyMeta.version,
+    phases: roadmapData.phases.length
+  });
+
+  const humanLines = [
+    prefix(`Story activated: ${storyMeta.version} ${storyMeta.title}`),
+    '',
+    prefix(`Milestone set to: ${storyMeta.version}`),
+    prefix(`Phases loaded: ${roadmapData.phases.length}`),
+    prefix('ROADMAP.md and REQUIREMENTS.md copied to .brain/ root'),
+    ...(fs.existsSync(path.join(brainDir, 'ROADMAP.prev.md'))
+      ? [prefix('Previous ROADMAP.md archived as ROADMAP.prev.md')]
+      : []),
+    '',
+    prefix("Next: Use '/brain:discuss' to begin phase work.")
+  ].join('\n');
+
+  const result = {
+    action: 'story-activated',
+    story: storyMeta,
+    phases: roadmapData.phases.length,
+    nextAction: '/brain:discuss'
+  };
+
+  output(result, humanLines);
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// handleComplete
+// ---------------------------------------------------------------------------
+
+function handleComplete(brainDir, state) {
+  state.stories = state.stories || { current: null, count: 0, active: [], history: [] };
+  const currentSlug = state.stories.current;
+  if (!currentSlug) {
+    error('No active story to complete.');
+    return { error: 'no-active-story' };
+  }
+
+  const storyDir = path.join(brainDir, 'stories', currentSlug);
+  if (!fs.existsSync(storyDir)) {
+    error(`Story directory not found: ${currentSlug}`);
+    return { error: 'story-dir-not-found' };
+  }
+
+  const storyMetaPath = path.join(storyDir, 'story.json');
+  const storyMeta = JSON.parse(fs.readFileSync(storyMetaPath, 'utf8'));
+
+  // Check if all phases are complete
+  const allPhasesComplete = state.phase && Array.isArray(state.phase.phases) &&
+    state.phase.phases.length > 0 &&
+    state.phase.phases.every(p => p.status === 'complete' || p.status === 'Complete');
+
+  if (!allPhasesComplete && state.phase && state.phase.phases && state.phase.phases.length > 0) {
+    const pending = state.phase.phases.filter(p => p.status !== 'complete' && p.status !== 'Complete');
+    error(`Cannot complete story: ${pending.length} phase(s) still pending.`);
+
+    const humanLines = [
+      prefix('Incomplete phases:'),
+      ...pending.map(p => prefix(`  Phase ${p.number}: ${p.name} (${p.status})`))
+    ].join('\n');
+
+    output({ error: 'phases-incomplete', pending }, humanLines);
+    return { error: 'phases-incomplete', pending };
+  }
+
+  // Mark story complete
+  storyMeta.status = 'complete';
+  storyMeta.completed = new Date().toISOString();
+  fs.writeFileSync(storyMetaPath, JSON.stringify(storyMeta, null, 2));
+
+  // Move from active to history
+  state.stories.active = (state.stories.active || []).filter(s => s.dirName !== currentSlug);
+  state.stories.history = state.stories.history || [];
+  state.stories.history.push({
+    num: storyMeta.num,
+    version: storyMeta.version,
+    title: storyMeta.title,
+    slug: storyMeta.slug,
+    dirName: storyMeta.dirName,
+    completed: storyMeta.completed
+  });
+  state.stories.current = null;
+
+  // Bump milestone version
+  const currentVersion = storyMeta.version || 'v1.0';
+  const versionMatch = currentVersion.match(/^v(\d+)\.(\d+)$/);
+  let nextVersion = currentVersion;
+  if (versionMatch) {
+    const major = parseInt(versionMatch[1], 10);
+    const minor = parseInt(versionMatch[2], 10) + 1;
+    nextVersion = `v${major}.${minor}`;
+  }
+  state.milestone.current = nextVersion;
+  state.milestone.name = null;
+
+  // Add to milestone history
+  state.milestone.history = state.milestone.history || [];
+  state.milestone.history.push({
+    version: storyMeta.version,
+    title: storyMeta.title,
+    completed: storyMeta.completed
+  });
+
+  writeState(brainDir, state);
+
+  logEvent(brainDir, 0, {
+    type: 'story-complete',
+    story: storyMeta.num,
+    version: storyMeta.version,
+    title: storyMeta.title
+  });
+
+  const humanLines = [
+    prefix(`Story completed: ${storyMeta.version} ${storyMeta.title}`),
+    prefix(`Completed at: ${storyMeta.completed}`),
+    '',
+    prefix(`Milestone bumped to: ${nextVersion}`),
+    '',
+    prefix('Suggestions:'),
+    prefix(`  Start next story: brain-dev story "${nextVersion} Next feature"`),
+    prefix('  View history: brain-dev story --list')
+  ].join('\n');
+
+  const result = {
+    action: 'story-completed',
+    version: storyMeta.version,
+    nextVersion,
+    suggest: `/brain:story "${nextVersion} next"`
+  };
+
+  output(result, humanLines);
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// handleList
+// ---------------------------------------------------------------------------
+
+function handleList(brainDir, state) {
+  const stories = state.stories || { current: null, count: 0, active: [], history: [] };
+
+  const lines = [prefix(`Stories (${stories.count} total)`)];
+
+  if ((stories.active || []).length > 0) {
+    lines.push('');
+    lines.push(prefix('Active:'));
+    for (const s of stories.active) {
+      const current = s.dirName === stories.current ? ' (current)' : '';
+      lines.push(prefix(`  ${s.version} ${s.title} [${s.status}]${current}`));
+    }
+  }
+
+  if ((stories.history || []).length > 0) {
+    lines.push('');
+    lines.push(prefix('Completed:'));
+    for (const s of stories.history.slice(-10)) {
+      lines.push(prefix(`  ${s.version} ${s.title} (${s.completed ? s.completed.slice(0, 10) : 'unknown'})`));
+    }
+  }
+
+  if (stories.count === 0) {
+    lines.push(prefix('  No stories yet. Create one: brain-dev story "v1.1 Feature title"'));
+  }
+
+  const result = { action: 'story-list', stories };
+  output(result, lines.join('\n'));
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// handleStatus
+// ---------------------------------------------------------------------------
+
+function handleStatus(brainDir, state) {
+  const stories = state.stories || { current: null, count: 0, active: [], history: [] };
+  const currentSlug = stories.current;
+
+  if (!currentSlug) {
+    const humanLines = [
+      prefix('No active story.'),
+      prefix('Create one: brain-dev story "v1.1 Feature title"')
+    ].join('\n');
+
+    output({ action: 'story-status', active: false }, humanLines);
+    return { action: 'story-status', active: false };
+  }
+
+  const storyDir = path.join(brainDir, 'stories', currentSlug);
+  if (!fs.existsSync(storyDir)) {
+    error(`Story directory not found: ${currentSlug}`);
+    return { error: 'story-dir-not-found' };
+  }
+
+  const storyMetaPath = path.join(storyDir, 'story.json');
+  const storyMeta = JSON.parse(fs.readFileSync(storyMetaPath, 'utf8'));
+
+  // Determine step progress
+  const steps = [];
+  const hasProjectMd = fs.existsSync(path.join(storyDir, 'PROJECT.md'));
+  const hasResearchDir = fs.existsSync(path.join(storyDir, 'research'));
+  const hasSummaryMd = hasResearchDir && fs.existsSync(path.join(storyDir, 'research', 'SUMMARY.md'));
+  const hasRequirementsMd = fs.existsSync(path.join(storyDir, 'REQUIREMENTS.md'));
+  const hasRoadmapMd = fs.existsSync(path.join(storyDir, 'ROADMAP.md'));
+
+  steps.push({ name: 'Questions', done: !!storyMeta.answersReceived });
+  steps.push({ name: 'PROJECT.md', done: hasProjectMd });
+  steps.push({ name: 'Research', done: hasResearchDir, skipped: storyMeta.noResearch });
+  steps.push({ name: 'Synthesis', done: hasSummaryMd, skipped: storyMeta.noResearch });
+  steps.push({ name: 'Requirements', done: hasRequirementsMd });
+  steps.push({ name: 'Roadmap', done: hasRoadmapMd });
+  steps.push({ name: 'Activated', done: storyMeta.status === 'active' });
+
+  const completedSteps = steps.filter(s => s.done || s.skipped).length;
+  const totalSteps = steps.length;
+
+  // Phase progress (if activated)
+  let phaseProgress = null;
+  if (state.phase && Array.isArray(state.phase.phases) && state.phase.phases.length > 0) {
+    const done = state.phase.phases.filter(p => p.status === 'complete' || p.status === 'Complete').length;
+    phaseProgress = { done, total: state.phase.phases.length };
+  }
+
+  const lines = [
+    prefix(`Story: ${storyMeta.version} ${storyMeta.title}`),
+    prefix(`Status: ${storyMeta.status}`),
+    prefix(`Directory: .brain/stories/${currentSlug}/`),
+    prefix(`Progress: ${completedSteps}/${totalSteps} steps`),
+    ''
+  ];
+
+  lines.push(prefix('Steps:'));
+  for (const step of steps) {
+    const icon = step.done ? '[x]' : (step.skipped ? '[-]' : '[ ]');
+    lines.push(prefix(`  ${icon} ${step.name}${step.skipped ? ' (skipped)' : ''}`));
+  }
+
+  if (phaseProgress) {
+    lines.push('');
+    lines.push(prefix(`Phases: ${phaseProgress.done}/${phaseProgress.total} complete`));
+
+    if (state.phase.phases) {
+      for (const p of state.phase.phases) {
+        const pIcon = (p.status === 'complete' || p.status === 'Complete') ? '[x]' : '[ ]';
+        lines.push(prefix(`  ${pIcon} Phase ${p.number}: ${p.name} (${p.status})`));
+      }
+    }
+  }
+
+  const result = {
+    action: 'story-status',
+    active: true,
+    story: storyMeta,
+    steps,
+    completedSteps,
+    totalSteps,
+    phaseProgress
+  };
+
+  output(result, lines.join('\n'));
+  return result;
+}
+
+module.exports = { run };