@agile-vibe-coding/avc 0.1.1 → 0.3.1

package/cli/sprint-planning-processor.js

@@ -0,0 +1,4162 @@
+import fs from 'fs';
+import path from 'path';
+import { LLMProvider } from './llm-provider.js';
+import { PromptLogger } from './prompt-logger.js';
+import { TokenTracker } from './token-tracker.js';
+import { EpicStoryValidator } from './epic-story-validator.js';
+import { VerificationTracker } from './verification-tracker.js';
+import { fileURLToPath } from 'url';
+import { getCeremonyHeader } from './message-constants.js';
+import { sendError, sendWarning, sendSuccess, sendInfo, sendOutput, sendIndented, sendSectionHeader, sendCeremonyHeader, sendProgress, sendSubstep } from './messaging-api.js';
+import { outputBuffer } from './output-buffer.js';
+import { loadAgent } from './agent-loader.js';
+import { CONTEXT_GENERATION_TOOLS, dispatchToolCall } from './api-reference-tool.js';
+import { computeCodingOrder } from './coding-order.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/** Local-timezone ISO string (e.g. 2026-03-04T18:05:16.554+01:00) */
+function localISO(date = new Date()) {
+  const p = n => String(n).padStart(2, '0');
+  const ms = String(date.getMilliseconds()).padStart(3, '0');
+  const tz = -date.getTimezoneOffset();
+  const sign = tz >= 0 ? '+' : '-';
+  const tzH = p(Math.floor(Math.abs(tz) / 60));
+  const tzM = p(Math.abs(tz) % 60);
+  return `${date.getFullYear()}-${p(date.getMonth()+1)}-${p(date.getDate())}T${p(date.getHours())}:${p(date.getMinutes())}:${p(date.getSeconds())}.${ms}${sign}${tzH}:${tzM}`;
+}
+
+/**
+ * SprintPlanningProcessor - Creates/expands Epics and Stories with duplicate detection
+ */
+class SprintPlanningProcessor {
+  constructor(options = {}) {
+    this.ceremonyName = 'sprint-planning';
+    this.avcPath = path.join(process.cwd(), '.avc');
+    this.projectPath = path.join(this.avcPath, 'project');
+    this.projectDocPath = path.join(this.projectPath, 'doc.md');
+    this.avcConfigPath = path.join(this.avcPath, 'avc.json');
+    this.agentsPath = path.join(__dirname, 'agents');
+
+    // Read ceremony config
+    const { provider, model, stagesConfig } = this.readCeremonyConfig();
+    this._providerName = provider;
+    this._modelName = model;
+    this.llmProvider = null;
+    this.stagesConfig = stagesConfig;
+
+    // Stage provider cache
+    this._stageProviders = {};
+
+    // LLM-generated context.md cache (keyed by epic.name / "epicName::storyName")
+    // Populated by generateContextFiles() before validation; consumed by validation loop and writeHierarchyFiles()
+    this._epicContextCache = new Map();
+    this._storyContextCache = new Map();
+
+    // Initialize prompt logger (writes per-call prompt/response JSON files)
+    this._promptLogger = new PromptLogger(process.cwd(), 'sprint-planning');
+
+    // Initialize token tracker
+    this.tokenTracker = new TokenTracker(this.avcPath);
+    this.tokenTracker.init();
+
+    // Initialize verification tracker
+    this.verificationTracker = new VerificationTracker(this.avcPath);
+
+    // Debug mode - always enabled for comprehensive logging
+    this.debugMode = true;
+
+    // Cost threshold protection
+    this._costThreshold = options?.costThreshold ?? null;
+    this._costLimitReachedCallback = options?.costLimitReachedCallback ?? null;
+    this._runningCost = 0;
+
+    // Optional user-selection gate between Stage 4 and Stage 5
+    // When provided, the processor calls this async function with the decomposed hierarchy
+    // and waits for it to resolve with { selectedEpicIds, selectedStoryIds }.
+    // When null (default), the processor runs straight through without pausing.
+    this._selectionCallback = options?.selectionCallback ?? null;
+
+    // Optional callback fired immediately after Stage 6 writes work.json files to disk.
+    // Use this to trigger Kanban board refresh before Stage 7/8 (doc gen + enrichment) complete.
+    this._hierarchyWrittenCallback = options?.hierarchyWrittenCallback ?? null;
+
+    // Optional callback fired each time a single epic or story work.json is written.
+    // Allows the Kanban board to display items one-by-one as they are created.
+    this._itemWrittenCallback = options?.itemWrittenCallback ?? null;
+
+    // Optional callback when a validator call fails with quota/rate-limit error.
+    // Async: resolves with { newProvider?, newModel? } or null (retry same model).
+    this._quotaExceededCallback = options?.quotaExceededCallback ?? null;
+  }
+
+  /**
+   * Structured debug logger - writes ONLY to file via CommandLogger
+   */
+  debug(message, data = null) {
+    if (!this.debugMode) return;
+
+    const timestamp = localISO();
+    const prefix = `[${timestamp}] [DEBUG]`;
+
+    if (data === null) {
+      console.log(`${prefix} ${message}`);
+    } else {
+      // Combine message and data in single log call with [DEBUG] prefix
+      console.log(`${prefix} ${message}\n${JSON.stringify(data, null, 2)}`);
+    }
+  }
+
+  /**
+   * Stage boundary marker
+   */
+  debugStage(stageNumber, stageName) {
+    const separator = '='.repeat(50);
+    this.debug(`\n${separator}`);
+    this.debug(`STAGE ${stageNumber}: ${stageName.toUpperCase()}`);
+    this.debug(separator);
+  }
+
+  /**
+   * Log elapsed time for a labelled operation
+   */
+  debugTiming(label, startMs) {
+    const elapsed = Date.now() - startMs;
+    this.debug(`[TIMING] ${label}: ${elapsed}ms (${(elapsed / 1000).toFixed(1)}s)`);
+  }
+
+  /**
+   * Sub-section separator for grouping related log entries within a stage
+   */
+  debugSection(title) {
+    const line = '-'.repeat(60);
+    this.debug(`\n${line}`);
+    this.debug(`-- ${title}`);
+    this.debug(line);
+  }
+
+  /**
+   * Log a full hierarchy tree for snapshot comparison across runs
+   * @param {string} label - Label for this snapshot (e.g. "PRE-RUN" or "POST-RUN")
+   * @param {Array} epics - Array of {id, name, stories:[{id, name}]} objects
+   */
+  debugHierarchySnapshot(label, epics) {
+    this.debugSection(`${label} HIERARCHY SNAPSHOT`);
+    if (!epics || epics.length === 0) {
+      this.debug(`${label}: (empty - no epics found)`);
+      return;
+    }
+    this.debug(`${label}: ${epics.length} epics`);
+    for (const epic of epics) {
+      const storyCount = epic.stories ? epic.stories.length : 0;
+      this.debug(`  [${epic.id}] ${epic.name} (${storyCount} stories)`);
+      for (const story of epic.stories || []) {
+        this.debug(`    [${story.id}] ${story.name}`);
+      }
+    }
+    // Flat totals for quick comparison
+    const totalStories = epics.reduce((sum, e) => sum + (e.stories?.length || 0), 0);
+    this.debug(`${label} TOTALS: ${epics.length} epics, ${totalStories} stories`);
+  }
+
+  /**
+   * Truncate document content for local LLMs with limited context windows.
+   * For non-local providers, returns the content unchanged.
+   *
+   * Keeps sections 1-3 in full (Overview, Target Users, Core Features),
+   * then only section headers + first paragraph for sections 4-9.
+   *
+   * @param {string} docContent - The full document content
+   * @param {number} maxChars - Maximum character length (default 6000)
+   * @returns {string} Truncated or original content
+   */
+  _truncateDocForLocalLLM(docContent, maxChars = 6000) {
+    if (this._providerName !== 'local') {
+      return docContent;
+    }
+
+    if (!docContent || docContent.length <= maxChars) {
+      this.debug('Local LLM truncation: content already within limit', {
+        contentLength: docContent?.length || 0,
+        maxChars
+      });
+      return docContent;
+    }
+
+    this.debug('Local LLM truncation: truncating document for context window', {
+      originalLength: docContent.length,
+      maxChars
+    });
+
+    const lines = docContent.split('\n');
+    const sections = [];
+    let currentSection = { header: null, lines: [] };
+
+    // Split into sections by ## headers
+    for (const line of lines) {
+      if (line.startsWith('## ')) {
+        if (currentSection.header !== null || currentSection.lines.length > 0) {
+          sections.push(currentSection);
+        }
+        currentSection = { header: line, lines: [] };
+      } else {
+        currentSection.lines.push(line);
+      }
+    }
+    // Push last section
+    if (currentSection.header !== null || currentSection.lines.length > 0) {
+      sections.push(currentSection);
+    }
+
+    // Keep first 3 sections (index 0 = preamble, 1-3 = first three ## sections) in full
+    // Summarize sections 4+
+    const resultParts = [];
+    let sectionIndex = 0;
+
+    for (const section of sections) {
+      if (section.header) {
+        sectionIndex++;
+      }
+
+      if (sectionIndex <= 3) {
+        // Keep in full
+        if (section.header) resultParts.push(section.header);
+        resultParts.push(...section.lines);
+      } else {
+        // Keep header + first paragraph only
+        if (section.header) resultParts.push(section.header);
+        let foundContent = false;
+        for (const sLine of section.lines) {
+          if (sLine.trim() === '') {
+            if (foundContent) break; // End of first paragraph
+            resultParts.push(sLine);
+          } else {
+            foundContent = true;
+            resultParts.push(sLine);
+          }
+        }
+      }
+    }
+
+    let result = resultParts.join('\n');
+
+    // Final hard truncation if still over limit
+    if (result.length > maxChars) {
+      result = result.substring(0, maxChars);
+    }
+
+    result += '\n\n[... remaining sections summarized for context window limits ...]';
+
+    this.debug('Local LLM truncation complete', {
+      originalLength: docContent.length,
+      truncatedLength: result.length
+    });
+
+    return result;
+  }
+
+  /**
+   * API call logging with timing
+   */
+  async debugApiCall(operation, fn) {
+    this.debug(`\n${'='.repeat(50)}`);
+    this.debug(`LLM API CALL: ${operation}`);
+    this.debug('='.repeat(50));
+    this.debug(`Provider: ${this._providerName}`);
+    this.debug(`Model: ${this._modelName}`);
+
+    const startTime = Date.now();
+    try {
+      const result = await fn();
+      const duration = Date.now() - startTime;
+
+      this.debug(`Response received (${duration}ms)`);
+      return result;
+    } catch (error) {
+      const duration = Date.now() - startTime;
+      this.debug(`API call failed after ${duration}ms`, {
+        error: error.message,
+        stack: error.stack
+      });
+      throw error;
+    }
+  }
+
+  readCeremonyConfig() {
+    try {
+      const config = JSON.parse(fs.readFileSync(this.avcConfigPath, 'utf8'));
+      const ceremony = config.settings?.ceremonies?.find(c => c.name === this.ceremonyName);
+
+      if (!ceremony) {
+        sendWarning(`Ceremony '${this.ceremonyName}' not found in config, using defaults`);
+        return {
+          provider: 'claude',
+          model: 'claude-sonnet-4-5-20250929',
+          stagesConfig: null
+        };
+      }
+
+      return {
+        provider: ceremony.provider || 'claude',
+        model: ceremony.defaultModel || 'claude-sonnet-4-5-20250929',
+        stagesConfig: ceremony.stages || null
+      };
+    } catch (error) {
+      sendWarning(`Could not read ceremony config: ${error.message}`);
+      return {
+        provider: 'claude',
+        model: 'claude-sonnet-4-5-20250929',
+        stagesConfig: null
+      };
+    }
+  }
+
+  /**
+   * Get provider and model for a specific stage
+   * Falls back to ceremony-level config if stage-specific config not found
+   * @param {string} stageName - Stage name ('decomposition', 'validation', 'doc-distribution')
+   * @returns {Object} { provider, model }
+   */
+  getProviderForStage(stageName) {
+    // Check if stage-specific config exists
+    if (this.stagesConfig && this.stagesConfig[stageName]) {
+      const stageConfig = this.stagesConfig[stageName];
+      return {
+        provider: stageConfig.provider || this._providerName,
+        model: stageConfig.model || this._modelName
+      };
+    }
+
+    // Fall back to ceremony-level config
+    return {
+      provider: this._providerName,
+      model: this._modelName
+    };
+  }
+
+  /**
+   * Get or create LLM provider for a specific stage
+   * @param {string} stageName - Stage name ('decomposition', 'validation', 'doc-distribution')
+   * @returns {Promise<LLMProvider>} LLM provider instance
+   */
+  async getProviderForStageInstance(stageName) {
+    let { provider, model } = this.getProviderForStage(stageName);
+
+    // Resolve to an available provider if current one has no credentials
+    const resolved = await LLMProvider.resolveAvailableProvider(provider, model);
+    if (resolved.fellBack) {
+      this.debug(`Provider fallback for ${stageName}: ${provider}→${resolved.provider} (${resolved.model})`);
+      console.warn(`[WARN] ${provider} has no API key — falling back to ${resolved.provider} for stage "${stageName}"`);
+      provider = resolved.provider;
+      model = resolved.model;
+    }
+
+    // Check if we already have a provider for this stage
+    const cacheKey = `${stageName}:${provider}:${model}`;
+
+    if (this._stageProviders[cacheKey]) {
+      this.debug(`Using cached provider for ${stageName}: ${provider} (${model})`);
+      return this._stageProviders[cacheKey];
+    }
+
+    // Create new provider
+    this.debug(`Creating new provider for ${stageName}: ${provider} (${model})`);
+    const providerInstance = await LLMProvider.create(provider, model);
+    this._registerTokenCallback(providerInstance, `${this.ceremonyName}-${stageName}`);
+    providerInstance.setPromptLogger(this._promptLogger, stageName);
+    this._stageProviders[cacheKey] = providerInstance;
+
+    return providerInstance;
+  }
+
+  /**
+   * Run an async LLM fn with a periodic elapsed-time heartbeat detail message.
+   * Keeps the UI updated while waiting for long LLM calls to complete.
+   */
+  async _withProgressHeartbeat(fn, getMsg, progressCallback, intervalMs = 5000) {
+    const startTime = Date.now();
+    let lastMsg = null;
+    const timer = setInterval(() => {
+      const elapsed = Math.round((Date.now() - startTime) / 1000);
+      const msg = getMsg(elapsed);
+      if (msg != null && msg !== lastMsg) {
+        lastMsg = msg;
+        progressCallback?.(null, null, { detail: msg })?.catch?.(() => {});
+      }
+    }, intervalMs);
+    try {
+      return await fn();
+    } finally {
+      clearInterval(timer);
+    }
+  }
+
+  /**
+   * Run async task functions with bounded concurrency.
+   * @param {Array<() => Promise>} tasks - Array of functions that return promises
+   * @param {number} concurrency - Max parallel tasks
+   * @returns {Promise<Array>} Results in original order
+   */
+  async _runWithConcurrency(tasks, concurrency) {
+    const results = [];
+    const executing = new Set();
+    for (let i = 0; i < tasks.length; i++) {
+      const p = tasks[i]().then(result => { executing.delete(p); return result; });
+      executing.add(p);
+      results.push(p);
+      if (executing.size >= concurrency) {
+        await Promise.race(executing);
+      }
+    }
+    return Promise.all(results);
+  }
+
+  /**
+   * Aggregate token usage across all provider instances:
+   * - this.llmProvider (Stage 5 validation fallback)
+   * - this._stageProviders (Stage 4 decomposition, Stage 7 doc-distribution)
+   * - this._validator._validatorProviders (Stage 5 per-validator providers)
+   */
+  _aggregateAllTokenUsage() {
+    const totals = { inputTokens: 0, outputTokens: 0, totalTokens: 0, totalCalls: 0, estimatedCost: 0 };
+    const add = (provider) => {
+      if (!provider) return;
+      const u = provider.getTokenUsage();
+      totals.inputTokens += u.inputTokens || 0;
+      totals.outputTokens += u.outputTokens || 0;
+      totals.totalTokens += u.totalTokens || (u.inputTokens || 0) + (u.outputTokens || 0);
+      totals.totalCalls += u.totalCalls || 0;
+      totals.estimatedCost += u.estimatedCost || 0;
+    };
+    add(this.llmProvider);
+    for (const p of Object.values(this._stageProviders)) add(p);
+    if (this._validator) {
+      for (const p of Object.values(this._validator._validatorProviders)) add(p);
+    }
+    return totals;
+  }
+
+  /**
+   * Register a per-call token callback on a provider instance.
+   * Each LLM API call fires addIncremental() so tokens are persisted crash-safely.
+   * @param {object} provider - LLM provider instance
+   * @param {string} [stageKey] - Stage-specific key (e.g. 'sprint-planning-decomposition').
+   *   Defaults to this.ceremonyName so the parent roll-up bucket still accumulates totals.
+   */
+  _registerTokenCallback(provider, stageKey) {
+    if (!provider) return;
+    const key = stageKey ?? this.ceremonyName;
+    provider.onCall((delta) => {
+      this.tokenTracker.addIncremental(key, delta);
+      if (delta.model) {
+        const cost = this.tokenTracker.calculateCost(delta.input, delta.output, delta.model);
+        this._runningCost += cost?.total ?? 0;
+      }
+    });
+  }
+
+  async initializeLLMProvider() {
+    try {
+      this.llmProvider = await LLMProvider.create(this._providerName, this._modelName);
+      this._registerTokenCallback(this.llmProvider);
+      this.llmProvider.setPromptLogger(this._promptLogger, 'main');
+      return this.llmProvider;
+    } catch (error) {
+      this.debug(`Could not initialize ${this._providerName} provider`);
+      this.debug(`Error: ${error.message}`);
+      return null;
+    }
+  }
+
+  async retryWithBackoff(fn, operation, maxRetries = 3, options = {}) {
+    const {
+      baseDelay = this._providerName === 'local' ? 500 : 1000,
+      multiplier = this._providerName === 'local' ? 1.5 : 2,
+      maxDelay = this._providerName === 'local' ? 5000 : 30000,
+    } = options;
+
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      try {
+        return await fn();
+      } catch (error) {
+        const isLastAttempt = attempt === maxRetries;
+        const isRetriable = error.message?.includes('rate limit') ||
+                          error.message?.includes('timeout') ||
+                          error.message?.includes('503') ||
+                          error.message?.toLowerCase().includes('connection error') ||
+                          error.message?.toLowerCase().includes('econnreset') ||
+                          error.message?.toLowerCase().includes('network error') ||
+                          error.message?.toLowerCase().includes('terminated') ||
+                          error.message?.toLowerCase().includes('econnrefused') ||
+                          error.message?.toLowerCase().includes('socket hang up');
+
+        if (isLastAttempt || !isRetriable) {
+          throw error;
+        }
+
+        const delay = Math.min(Math.pow(multiplier, attempt) * baseDelay, maxDelay);
+        this.debug(`Retry ${attempt}/${maxRetries} in ${delay/1000}s: ${operation}`);
+        this.debug(`Error: ${error.message}`);
+        await new Promise(resolve => setTimeout(resolve, delay));
+      }
+    }
+  }
+
+  // STAGE 1: Validate prerequisites
+  validatePrerequisites() {
+    this.debugStage(1, 'Validate Prerequisites');
+    this.debug('Checking prerequisites...');
+
+    if (!fs.existsSync(this.projectDocPath)) {
+      this.debug(`✗ Project doc missing: ${this.projectDocPath}`);
+      throw new Error(
+        'Project documentation not found. Please run /sponsor-call first.'
+      );
+    }
+    const docSize = fs.statSync(this.projectDocPath).size;
+    this.debug(`✓ Project doc exists: ${this.projectDocPath} (${docSize} bytes)`);
+
+    this.debug('Prerequisites validated successfully');
+  }
+
+  // STAGE 2: Read existing hierarchy
+  readExistingHierarchy() {
+    this.debugStage(2, 'Read Existing Hierarchy');
+
+    const existingEpics = new Map();  // name -> id
+    const existingStories = new Map(); // name -> id
+    const maxEpicNum = { value: 0 };
+    const maxStoryNums = new Map();  // epicId -> maxNum
+    const preRunSnapshot = [];       // Rich snapshot for cross-run comparison
+
+    if (!fs.existsSync(this.projectPath)) {
+      this.debug('Project path does not exist yet (first run)');
+      return { existingEpics, existingStories, maxEpicNum, maxStoryNums, preRunSnapshot };
+    }
+
+    this.debug(`Scanning directory: ${this.projectPath}`);
+    const dirs = fs.readdirSync(this.projectPath).sort();
+    this.debug(`Found ${dirs.length} top-level entries to scan`);
+
+    // Scan top-level directories (epics)
+    for (const dir of dirs) {
+      const epicWorkJsonPath = path.join(this.projectPath, dir, 'work.json');
+
+      if (!fs.existsSync(epicWorkJsonPath)) continue;
+
+      try {
+        const work = JSON.parse(fs.readFileSync(epicWorkJsonPath, 'utf8'));
+
+        if (work.type === 'epic') {
+          this.debug(`Found existing Epic: ${work.id} "${work.name}" [status=${work.status}, created=${work.metadata?.created || 'unknown'}]`);
+          existingEpics.set(work.name.toLowerCase(), work.id);
+
+          const epicEntry = {
+            id: work.id,
+            name: work.name,
+            domain: work.domain || '',
+            status: work.status || 'unknown',
+            created: work.metadata?.created || null,
+            ceremony: work.metadata?.ceremony || null,
+            description: (work.description || '').substring(0, 120),
+            stories: []
+          };
+
+          // Track max epic number (context-0001 → 1)
+          const match = work.id.match(/^context-(\d+)$/);
+          if (match) {
+            const num = parseInt(match[1], 10);
+            if (num > maxEpicNum.value) maxEpicNum.value = num;
+          }
+
+          // Scan for nested stories under this epic
+          const epicDir = path.join(this.projectPath, dir);
+          const epicSubdirs = fs.readdirSync(epicDir).filter(subdir => {
+            const subdirPath = path.join(epicDir, subdir);
+            return fs.statSync(subdirPath).isDirectory();
+          }).sort();
+
+          this.debug(`Scanning ${epicSubdirs.length} subdirectories under epic ${work.id}`);
+
+          for (const storyDir of epicSubdirs) {
+            const storyWorkJsonPath = path.join(epicDir, storyDir, 'work.json');
+
+            if (!fs.existsSync(storyWorkJsonPath)) continue;
+
+            try {
+              const storyWork = JSON.parse(fs.readFileSync(storyWorkJsonPath, 'utf8'));
+
+              if (storyWork.type === 'story') {
+                this.debug(`  Found existing Story: ${storyWork.id} "${storyWork.name}" [status=${storyWork.status}, created=${storyWork.metadata?.created || 'unknown'}]`);
+                existingStories.set(storyWork.name.toLowerCase(), storyWork.id);
+                epicEntry.stories.push({
+                  id: storyWork.id,
+                  name: storyWork.name,
+                  status: storyWork.status || 'unknown',
+                  created: storyWork.metadata?.created || null,
+                  userType: storyWork.userType || ''
+                });
+
+                // Track max story number per epic (context-0001-0003 → epic 0001, story 3)
+                const storyMatch = storyWork.id.match(/^context-(\d+)-(\d+)$/);
+                if (storyMatch) {
+                  const epicId = `context-${storyMatch[1]}`;
+                  const storyNum = parseInt(storyMatch[2], 10);
+
+                  if (!maxStoryNums.has(epicId)) {
+                    maxStoryNums.set(epicId, 0);
+                  }
+                  if (storyNum > maxStoryNums.get(epicId)) {
+                    maxStoryNums.set(epicId, storyNum);
+                  }
+                }
+              }
+            } catch (error) {
+              this.debug(`Could not parse ${storyWorkJsonPath}: ${error.message}`);
+            }
+          }
+
+          preRunSnapshot.push(epicEntry);
+        }
+      } catch (error) {
+        this.debug(`Could not parse ${epicWorkJsonPath}: ${error.message}`);
+        sendWarning(`Could not parse ${epicWorkJsonPath}: ${error.message}`);
+      }
+    }
+
+    // Log complete pre-run state for cross-run comparison
+    this.debugSection('PRE-RUN STATE - Full Existing Hierarchy');
+    this.debug('Pre-run counts', {
+      epics: existingEpics.size,
+      stories: existingStories.size,
+      maxEpicNum: maxEpicNum.value,
+      maxStoryNums: Object.fromEntries(maxStoryNums)
+    });
+    this.debugHierarchySnapshot('PRE-RUN', preRunSnapshot);
+    this.debug('All existing epic names (for duplicate detection)', Array.from(existingEpics.keys()));
+    this.debug('All existing story names (for duplicate detection)', Array.from(existingStories.keys()));
+
+    return { existingEpics, existingStories, maxEpicNum, maxStoryNums, preRunSnapshot };
+  }
+
+  // STAGE 3: Collect new scope (optional expansion)
+  async collectNewScope() {
+    this.debugStage(3, 'Collect New Scope');
+
+    this.debug(`Reading project doc: ${this.projectDocPath}`);
+    const docContent = fs.readFileSync(this.projectDocPath, 'utf8');
+    this.debug(`Doc content loaded (${docContent.length} chars)`);
+
+    this.debugSection('SCOPE TEXT SENT TO LLM (full doc.md)');
+    this.debug(`Full doc content (${docContent.length} chars):\n` + docContent);
+
+    return docContent;
+  }
+
+  // STAGE 4: Decompose into Epics + Stories
+  async decomposeIntoEpicsStories(scope, existingEpics, existingStories, progressCallback = null, previousIssues = null) {
+    this.debugStage(4, 'Decompose into Epics + Stories');
+
+    this.debug('Stage 1/3: Decomposing scope into Epics and Stories');
+
+    // Get stage-specific provider for decomposition
+    const provider = await this.getProviderForStageInstance('decomposition');
+    const { provider: providerName, model: modelName } = this.getProviderForStage('decomposition');
+
+    this.debug('Using provider for decomposition', { provider: providerName, model: modelName });
+    await progressCallback?.(null, `Using model: ${modelName}`, {});
+
+    // Read agent instructions
+    const agentPath = path.join(this.agentsPath, 'epic-story-decomposer.md');
+    this.debug(`Loading agent: ${agentPath}`);
+    const epicStoryDecomposerAgent = fs.readFileSync(agentPath, 'utf8');
+    this.debug(`Agent loaded (${epicStoryDecomposerAgent.length} bytes)`);
+
+    // Build prompt with duplicate detection
+    this.debug('Constructing decomposition prompt...');
+    const existingEpicNames = Array.from(existingEpics.keys());
+    const existingStoryNames = Array.from(existingStories.keys());
+
+    let prompt = `Given the following project scope:
+
+**Initial Scope (Features to Implement):**
+${scope}
+`;
+
+    if (existingEpicNames.length > 0) {
+      prompt += `\n**Existing Epics (DO NOT DUPLICATE):**
+${existingEpicNames.map(name => `- ${name}`).join('\n')}
+`;
+    }
+
+    if (existingStoryNames.length > 0) {
+      prompt += `\n**Existing Stories (DO NOT DUPLICATE):**
+${existingStoryNames.map(name => `- ${name}`).join('\n')}
+`;
+    }
+
+    prompt += `\nDecompose this project into NEW Epics (domain-based groupings) and Stories (user-facing capabilities per Epic) — create as many as needed to fully cover the scope.
+
+IMPORTANT: Only generate NEW Epics and Stories. Skip any that match the existing ones.
+
+Return your response as JSON following the exact structure specified in your instructions.`;
+
+    this.debug('Prompt includes', {
+      scopeLength: scope.length,
+      existingEpics: existingEpicNames.length,
+      existingStories: existingStoryNames.length,
+      totalPromptSize: prompt.length
+    });
+
+    const existingNote = existingEpicNames.length > 0
+      ? ` (skipping ${existingEpicNames.length} existing epics)`
+      : '';
+    await progressCallback?.(null, `Calling LLM to decompose scope${existingNote}…`, {});
+    await progressCallback?.(null, null, { detail: `Sending to ${providerName} (${modelName})…` });
+
+    // Inject quality issues from previous attempt for retry
+    if (previousIssues?.length > 0) {
+      prompt += `\n\n**CRITICAL: Your previous decomposition had these quality issues. FIX ALL of them:**\n\n${previousIssues.map((issue, i) => `${i + 1}. ${issue}`).join('\n')}\n\n**Specifically:**\n- Every epic MUST have at least 1 story (most should have 2-5)\n- All epic IDs must match format: context-XXXX (e.g., context-0001)\n- All story IDs must match format: context-XXXX-XXXX (e.g., context-0001-0001)\n- Every story must have 3-8 acceptance criteria\n`;
+    }
+
+    // Log full decomposition prompt for duplicate detection analysis
+    this.debug('\n' + '='.repeat(80));
+    this.debug('FULL DECOMPOSITION PROMPT:');
+    this.debug('='.repeat(80));
+    this.debug(prompt);
+    this.debug('='.repeat(80) + '\n');
+
+    // LLM call with full request/response logging
+    let hierarchy = await this.debugApiCall(
+      'Epic/Story Decomposition',
+      async () => {
+        this.debug('Request payload', {
+          model: modelName,
+          maxTokens: 8000,
+          agentInstructions: `${epicStoryDecomposerAgent.substring(0, 100)}...`,
+          promptPreview: `${prompt.substring(0, 200)}...`
+        });
+
+        this.debug('Sending request to LLM API...');
+
+        const result = await this._withProgressHeartbeat(
+          () => this.retryWithBackoff(
+            () => provider.generateJSON(prompt, epicStoryDecomposerAgent),
+            'Epic/Story decomposition'
+          ),
+          (elapsed) => {
+            if (elapsed < 20) return 'Reading scope and project context…';
+            if (elapsed < 40) return 'Identifying domain boundaries…';
+            if (elapsed < 60) return 'Structuring epics and stories…';
+            if (elapsed < 80) return 'Refining decomposition…';
+            if (elapsed < 100) return 'Finalizing work item hierarchy…';
+            return 'Still decomposing…';
+          },
+          progressCallback,
+          20000  // 20s interval — phase messages change each tick
+        );
+
+        // Log token usage
+        const usage = provider.getTokenUsage();
+        this.debug('Response tokens', {
+          input: usage.inputTokens,
+          output: usage.outputTokens,
+          total: usage.totalTokens
+        });
+        await progressCallback?.(null, null, { detail: `${usage.inputTokens.toLocaleString()} in · ${usage.outputTokens.toLocaleString()} out tokens` });
+
+        this.debug(`Response content (${usage.outputTokens} tokens)`, {
+          epicCount: result.epics?.length || 0,
+          totalStories: result.epics?.reduce((sum, e) => sum + (e.stories?.length || 0), 0) || 0,
+          validation: result.validation
+        });
+
+        // Log full LLM response for duplicate detection analysis
+        this.debug('\n' + '='.repeat(80));
+        this.debug('FULL LLM RESPONSE:');
+        this.debug('='.repeat(80));
+        this.debug(JSON.stringify(result, null, 2));
+        this.debug('='.repeat(80) + '\n');
+
+        return result;
+      }
+    );
+
+    // NOTE: Deduplication moved to Stage 4.1 (deduplicateEpicsLLM) in process() flow.
+    // The inline algorithmic dedup here was insufficient for semantic duplicates.
+
+    if (!hierarchy.epics || !Array.isArray(hierarchy.epics)) {
+      this.debug('✗ Invalid decomposition response: missing epics array');
+      throw new Error('Invalid decomposition response: missing epics array');
+    }
+
+    const totalStories = hierarchy.epics.reduce((sum, e) => sum + (e.stories?.length || 0), 0);
+    await progressCallback?.(null, `Decomposed into ${hierarchy.epics.length} epics, ${totalStories} stories`, {});
+    for (const epic of hierarchy.epics) {
+      await progressCallback?.(null, `  ${epic.name} (${epic.stories?.length || 0} stories)`, {});
+    }
+
+    this.debug('Parsed hierarchy', {
+      epics: hierarchy.epics.map(e => ({
+        id: e.id,
+        name: e.name,
+        storyCount: e.stories?.length || 0
+      })),
+      validation: hierarchy.validation
+    });
+
+
+    return hierarchy;
+  }
+
+  /**
+   * Check decomposition quality — returns array of issues to fix on retry.
+   * Empty array = quality is acceptable.
+   */
+  _checkDecompositionQuality(hierarchy) {
+    const issues = [];
+
+    if (!hierarchy?.epics?.length) {
+      issues.push('No epics generated — the decomposition returned an empty hierarchy.');
+      return issues;
+    }
+
+    // Check for epics with 0 stories
+    for (const epic of hierarchy.epics) {
+      if (!epic.stories || epic.stories.length === 0) {
+        issues.push(`Epic "${epic.name}" (${epic.id}) has 0 stories — every epic MUST have at least 1 story. Decompose this epic's features into user-facing stories.`);
+      }
+    }
+
+    // Check for invalid story ID formats (must be context-XXXX-XXXX)
+    for (const epic of hierarchy.epics) {
+      for (const story of epic.stories || []) {
+        if (!story.id || !/^context-\d{4}-\d{4}[a-z]?$/.test(story.id)) {
+          issues.push(`Story "${story.name}" has invalid ID "${story.id}" — must match format context-XXXX-XXXX (e.g., context-0001-0001).`);
+        }
+      }
+    }
+
+    // Check for invalid epic ID formats
+    for (const epic of hierarchy.epics) {
+      if (!epic.id || !/^context-\d{4}$/.test(epic.id)) {
+        issues.push(`Epic "${epic.name}" has invalid ID "${epic.id}" — must match format context-XXXX (e.g., context-0001).`);
+      }
+    }
+
+    // Check total story count (a calculator should have at least 5 stories)
+    const totalStories = hierarchy.epics.reduce((sum, e) => sum + (e.stories?.length || 0), 0);
+    if (totalStories < hierarchy.epics.length) {
+      issues.push(`Only ${totalStories} total stories for ${hierarchy.epics.length} epics — generate more stories to cover the full scope.`);
+    }
+
+    // Check stories have acceptance criteria
+    for (const epic of hierarchy.epics) {
+      for (const story of epic.stories || []) {
+        if (!story.acceptance || story.acceptance.length === 0) {
+          issues.push(`Story "${story.name}" has no acceptance criteria — each story must have 3-8 testable ACs.`);
+        }
+      }
+    }
+
+    return issues;
+  }
+
+  /**
+   * Merge source epic data into target epic (stories, features, dependencies).
+   * Shared by both LLM-based and algorithmic dedup paths.
+   */
+  _mergeEpicData(target, source) {
+    this.debug(`Merging duplicate epic "${source.name}" into "${target.name}"`);
+
+    // Merge stories, avoiding duplicates by name
+    const existingStoryNames = new Set((target.stories || []).map(s => s.name?.toLowerCase()));
+    for (const story of (source.stories || [])) {
+      if (!existingStoryNames.has(story.name?.toLowerCase())) {
+        target.stories = target.stories || [];
+        target.stories.push(story);
+        existingStoryNames.add(story.name?.toLowerCase());
+      }
+    }
+
+    // Merge features (deduplicate)
+    if (source.features?.length) {
+      const existingFeatures = new Set((target.features || []).map(f => f.toLowerCase()));
+      target.features = target.features || [];
+      for (const feature of source.features) {
+        if (!existingFeatures.has(feature.toLowerCase())) {
+          target.features.push(feature);
+          existingFeatures.add(feature.toLowerCase());
+        }
+      }
+    }
+
+    // Merge dependencies (deduplicate)
+    if (source.dependencies?.length) {
+      const existingDeps = new Set((target.dependencies || []).map(d => d.toLowerCase()));
+      target.dependencies = target.dependencies || [];
+      for (const dep of source.dependencies) {
+        if (!existingDeps.has(dep.toLowerCase())) {
+          target.dependencies.push(dep);
+          existingDeps.add(dep.toLowerCase());
+        }
+      }
+    }
+  }
+
+  /**
+   * Algorithmic fallback: deduplicate epics by Jaccard similarity.
+   * Used when LLM-based dedup fails or as a post-LLM cap enforcer.
+   */
+  _deduplicateEpicsAlgorithmic(hierarchy) {
+    if (!hierarchy.epics || hierarchy.epics.length <= 1) return hierarchy;
+
+    // Stop words that inflate Jaccard without carrying domain meaning
+    const STOP_WORDS = new Set(['and', 'the', 'for', 'with', 'from', 'into', 'via', 'based', 'system', 'engine', 'management', 'handling', 'service', 'services', 'module', 'platform']);
+
+    const tokenize = (text) => {
+      return new Set(
+        text.toLowerCase().replace(/[^a-z0-9\s]/g, '').split(/\s+/)
+          .filter(w => w.length > 2 && !STOP_WORDS.has(w))
+      );
+    };
+
+    const jaccardSimilarity = (setA, setB) => {
+      const intersection = [...setA].filter(w => setB.has(w)).length;
+      const union = new Set([...setA, ...setB]).size;
+      return union === 0 ? 0 : intersection / union;
+    };
+
+    // Composite similarity: name (40%) + domain (30%) + features (30%)
+    const epicSimilarity = (a, b) => {
+      const nameSim = jaccardSimilarity(tokenize(a.name || ''), tokenize(b.name || ''));
+
+      // Domain: exact match = 1.0, Jaccard on tokens otherwise
+      const domA = (a.domain || '').toLowerCase();
+      const domB = (b.domain || '').toLowerCase();
+      const domainSim = domA === domB && domA ? 1.0 : jaccardSimilarity(tokenize(domA), tokenize(domB));
+
+      // Features: extract the feature-name prefix (before parentheses), tokenize all, Jaccard
+      const extractFeatureWords = (features) => {
+        const words = new Set();
+        for (const f of (features || [])) {
+          const prefix = f.split('(')[0].trim();
+          for (const w of prefix.toLowerCase().replace(/[^a-z0-9\s]/g, ' ').split(/\s+/)) {
+            if (w.length > 2 && !STOP_WORDS.has(w)) words.add(w);
+          }
+        }
+        return words;
+      };
+      const featSim = jaccardSimilarity(extractFeatureWords(a.features), extractFeatureWords(b.features));
+
+      const combined = nameSim * 0.4 + domainSim * 0.3 + featSim * 0.3;
+      return { combined, nameSim, domainSim, featSim };
+    };
+
+    const originalCount = hierarchy.epics.length;
+
+    // Pass 1: Merge epics that are duplicates or semantically overlapping.
+    let merged = true;
+    while (merged) {
+      merged = false;
+      for (let i = 0; i < hierarchy.epics.length && !merged; i++) {
+        for (let j = i + 1; j < hierarchy.epics.length && !merged; j++) {
+          const sim = epicSimilarity(hierarchy.epics[i], hierarchy.epics[j]);
+          const shouldMerge = sim.combined > 0.5
+            || sim.nameSim >= 0.5
+            || (sim.nameSim >= 0.35 && sim.featSim >= 0.4);
+          if (shouldMerge) {
+            this.debug(`Epic similarity ${sim.combined.toFixed(2)} between "${hierarchy.epics[i].name}" and "${hierarchy.epics[j].name}" (name=${sim.nameSim.toFixed(2)}, domain=${sim.domainSim.toFixed(2)}, features=${sim.featSim.toFixed(2)})`);
+            this._mergeEpicData(hierarchy.epics[i], hierarchy.epics[j]);
+            hierarchy.epics.splice(j, 1);
+            merged = true;
+          }
+        }
+      }
+    }
+
+    if (hierarchy.epics.length < originalCount) {
+      this.debug(`Epic deduplication: ${originalCount} → ${hierarchy.epics.length} epics`);
+    } else {
+      this.debug('Epic deduplication: no duplicates found');
+    }
+
+    return hierarchy;
+  }
+
+  /**
+   * LLM-based semantic duplicate detection for epics and stories.
+   * Falls back to _deduplicateEpicsAlgorithmic on any error.
+   */
+  async deduplicateEpicsLLM(hierarchy, preRunSnapshot, progressCallback) {
+    this.debugStage(4.1, 'LLM-Based Duplicate Detection');
+
+    if (!hierarchy.epics || hierarchy.epics.length <= 1) {
+      this.debug('Skipping dedup: ≤1 epic');
+      return hierarchy;
+    }
+
+    try {
+      const provider = await this.getProviderForStageInstance('decomposition');
+      const { provider: providerName, model: modelName } = this.getProviderForStage('decomposition');
+
+      const agentInstructions = loadAgent('duplicate-detector.md');
+      this.debug('Duplicate detector agent loaded', { bytes: agentInstructions.length });
+
+      // Build compact summaries of new epics
+      const newEpicSummaries = hierarchy.epics.map((e, i) => ({
+        index: i,
+        name: e.name,
+        domain: e.domain || '',
+        description: (e.description || '').substring(0, 300),
+        features: (e.features || []).slice(0, 10),
+        storyNames: (e.stories || []).map(s => s.name)
+      }));
+
+      // Build existing epics context from preRunSnapshot
+      const existingEpicSummaries = (preRunSnapshot || []).map(e => ({
+        name: e.name,
+        domain: e.domain || '',
+        description: (e.description || '').substring(0, 300),
+        storyNames: (e.stories || []).map(s => s.name)
+      }));
+
+      const prompt = `Analyze the following newly generated epics for duplicates and overlaps.
+
+**New Epics (just generated):**
+${JSON.stringify(newEpicSummaries, null, 2)}
+
+${existingEpicSummaries.length > 0 ? `**Existing Epics (already on disk from prior runs):**
+${JSON.stringify(existingEpicSummaries, null, 2)}` : '**No existing epics on disk.**'}
+
+Detect:
+1. New epics that should be merged together (epicMergeGroups)
+2. Stories within the same epic that should be merged (storyMergeGroups)
+3. New epics that duplicate existing on-disk epics (existingOverlaps)
+
+Return JSON following the exact structure in your instructions.`;
+
+      this.debug('Duplicate detection prompt built', {
+        newEpics: newEpicSummaries.length,
+        existingEpics: existingEpicSummaries.length,
+        promptLength: prompt.length
+      });
+
+      await progressCallback?.(null, `Detecting duplicates via ${providerName} (${modelName})…`, {});
+
+      const result = await this.debugApiCall(
+        'Duplicate Detection',
+        async () => {
+          return await this._withProgressHeartbeat(
+            () => this.retryWithBackoff(
+              () => provider.generateJSON(prompt, agentInstructions),
+              'duplicate-detection'
+            ),
+            (elapsed) => `Analyzing duplicates… ${elapsed}s`,
+            progressCallback
+          );
+        }
+      );
+
+      this.debug('LLM duplicate detection result', result);
+
+      // Apply the LLM results
+      hierarchy = this._applyDuplicateResults(hierarchy, result);
+
+      const totalStories = hierarchy.epics.reduce((sum, e) => sum + (e.stories?.length || 0), 0);
+      await progressCallback?.(null, `After dedup: ${hierarchy.epics.length} epics, ${totalStories} stories`, {});
+
+      return hierarchy;
+    } catch (error) {
+      this.debug(`LLM duplicate detection failed, falling back to algorithmic: ${error.message}`, {
+        stack: error.stack
+      });
+      sendWarning(`LLM dedup failed (${error.message}), using algorithmic fallback`);
+      return this._deduplicateEpicsAlgorithmic(hierarchy);
+    }
+  }
+
+  /**
+   * Apply LLM duplicate detection results to the hierarchy.
+   * Processes: existingOverlaps → epicMergeGroups → storyMergeGroups (in that order).
+   * All indices in the LLM response refer to the ORIGINAL array positions.
+   * We maintain an oldOriginal→currentPosition mapping throughout.
+   */
+  _applyDuplicateResults(hierarchy, result) {
+    if (!result || typeof result !== 'object') {
+      this.debug('Invalid duplicate detection result, skipping');
+      return hierarchy;
+    }
+
+    const existingOverlaps = result.existingOverlaps || [];
+    const epicMergeGroups = result.epicMergeGroups || [];
+    const storyMergeGroups = result.storyMergeGroups || [];
+
+    const originalCount = hierarchy.epics.length;
+
+    // Master mapping: original index → current index (or -1 if removed)
+    // Starts as identity mapping, updated after each removal/splice.
+    const originalToCurrent = new Map();
+    for (let i = 0; i < originalCount; i++) {
+      originalToCurrent.set(i, i);
+    }
+
+    // Helper: after splicing index `splicedIdx` from the array,
+    // decrement all current-index values that are > splicedIdx.
+    const adjustAfterSplice = (splicedCurrentIdx) => {
+      for (const [origIdx, curIdx] of originalToCurrent) {
+        if (curIdx === splicedCurrentIdx) {
+          originalToCurrent.set(origIdx, -1);
+        } else if (curIdx > splicedCurrentIdx) {
+          originalToCurrent.set(origIdx, curIdx - 1);
+        }
+      }
+    };
+
+    // 1. Remove new epics that duplicate existing on-disk epics (process in reverse current-index order)
+    if (existingOverlaps.length > 0) {
+      // Collect current indices to remove (mapped from original indices)
+      const toRemove = existingOverlaps
+        .filter(o => o.recommendation === 'skip' && typeof o.newEpicIndex === 'number')
+        .map(o => ({ origIdx: o.newEpicIndex, curIdx: originalToCurrent.get(o.newEpicIndex), overlap: o }))
+        .filter(r => r.curIdx != null && r.curIdx >= 0 && r.curIdx < hierarchy.epics.length)
+        .sort((a, b) => b.curIdx - a.curIdx); // reverse for safe splicing
+
+      for (const { origIdx, curIdx, overlap } of toRemove) {
+        this.debug(`Removing epic "${hierarchy.epics[curIdx].name}" — duplicates existing "${overlap.existingEpicName}"`);
+        hierarchy.epics.splice(curIdx, 1);
+        adjustAfterSplice(curIdx);
+      }
+    }
+
+    // 2. Merge epic groups
+    if (epicMergeGroups.length > 0) {
+      for (const group of epicMergeGroups) {
+        const targetCur = originalToCurrent.get(group.targetIndex);
+        if (targetCur == null || targetCur === -1) {
+          this.debug(`Skipping epic merge group: target index ${group.targetIndex} was removed or invalid`);
+          continue;
+        }
+
+        const sourceCurIndices = (group.sourceIndices || [])
+          .map(idx => originalToCurrent.get(idx))
+          .filter(idx => idx != null && idx !== -1 && idx >= 0 && idx < hierarchy.epics.length && idx !== targetCur);
+
+        if (sourceCurIndices.length === 0) {
+          this.debug(`Skipping epic merge group: no valid source indices`);
+          continue;
+        }
+
+        if (targetCur < 0 || targetCur >= hierarchy.epics.length) {
+          this.debug(`Skipping epic merge group: remapped target ${targetCur} out of bounds`);
+          continue;
+        }
+
+        // Merge sources into target
+        for (const srcIdx of sourceCurIndices) {
+          this._mergeEpicData(hierarchy.epics[targetCur], hierarchy.epics[srcIdx]);
+        }
+
+        if (group.mergedName) {
+          hierarchy.epics[targetCur].name = group.mergedName;
+        }
+
+        this.debug(`Merged epics: ${sourceCurIndices.map(i => hierarchy.epics[i]?.name).join(', ')} → "${hierarchy.epics[targetCur].name}" (reason: ${group.reason})`);
+
+        // Remove sources in reverse order, adjusting mapping after each
+        for (const srcIdx of sourceCurIndices.sort((a, b) => b - a)) {
+          hierarchy.epics.splice(srcIdx, 1);
+          adjustAfterSplice(srcIdx);
+        }
+      }
+    }
+
+    // 3. Merge story groups within epics
+    // epicIndex from LLM refers to ORIGINAL positions — remap via originalToCurrent.
+    if (storyMergeGroups.length > 0) {
+      for (const group of storyMergeGroups) {
+        const epicIdx = originalToCurrent.get(group.epicIndex);
+        if (epicIdx == null || epicIdx === -1 || epicIdx < 0 || epicIdx >= hierarchy.epics.length) {
+          this.debug(`Skipping story merge group: epic index ${group.epicIndex} (remapped: ${epicIdx}) out of bounds or removed`);
+          continue;
+        }
+
+        const epic = hierarchy.epics[epicIdx];
+        const stories = epic.stories || [];
+        const targetIdx = group.targetStoryIndex;
+
+        if (targetIdx < 0 || targetIdx >= stories.length) {
+          this.debug(`Skipping story merge group: target story index ${targetIdx} out of bounds in epic "${epic.name}"`);
+          continue;
+        }
+
+        let sourceIndices = (group.sourceStoryIndices || [])
+          .filter(idx => idx >= 0 && idx < stories.length && idx !== targetIdx);
+
+        if (sourceIndices.length === 0) continue;
+
+        // Guard: reject merge when both stories have ≥3 acceptance criteria (both are well-scoped)
+        const targetAcCount = (stories[targetIdx].acceptance || []).length;
+        const sourceAcCounts = sourceIndices.map(idx => (stories[idx]?.acceptance || []).length);
+        if (targetAcCount >= 3 && sourceAcCounts.some(c => c >= 3)) {
+          this.debug(`Rejecting story merge in "${epic.name}": target "${stories[targetIdx].name}" has ${targetAcCount} ACs and source(s) have ${sourceAcCounts.join(',')} ACs — both are well-scoped, merging would create an oversized story`);
+          continue;
+        }
+
+        // Cap story merges: merge at most 1 source to prevent over-merging
+        if (sourceIndices.length > 1) {
+          this.debug(`Story merge group in "${epic.name}" has ${sourceIndices.length} sources — capping to 1 to prevent over-merging`);
+          sourceIndices = [sourceIndices[0]];
+        }
+
+        // Merge story acceptance criteria and dependencies
+        const target = stories[targetIdx];
+        for (const srcIdx of sourceIndices) {
+          const source = stories[srcIdx];
+
+          // Merge acceptance criteria
+          if (source.acceptance?.length) {
+            const existing = new Set((target.acceptance || []).map(a => a.toLowerCase()));
+            target.acceptance = target.acceptance || [];
+            for (const ac of source.acceptance) {
+              if (!existing.has(ac.toLowerCase())) {
+                target.acceptance.push(ac);
+                existing.add(ac.toLowerCase());
+              }
+            }
+          }
+
+          // Merge dependencies
+          if (source.dependencies?.length) {
+            const existing = new Set((target.dependencies || []).map(d => d.toLowerCase()));
+            target.dependencies = target.dependencies || [];
+            for (const dep of source.dependencies) {
+              if (!existing.has(dep.toLowerCase())) {
+                target.dependencies.push(dep);
+                existing.add(dep.toLowerCase());
+              }
+            }
+          }
+        }
+
+        this.debug(`Merged stories in epic "${epic.name}": indices ${sourceIndices.join(',')} → ${targetIdx} (reason: ${group.reason})`);
+
+        // Remap dependency references: any story depending on a merged source now depends on the target
+        const targetId = target.id;
+        for (const srcIdx of sourceIndices) {
+          const sourceId = stories[srcIdx]?.id;
+          if (sourceId && targetId) {
+            for (const e of hierarchy.epics) {
+              for (const s of e.stories || []) {
+                if (Array.isArray(s.dependencies)) {
+                  const depIdx = s.dependencies.indexOf(sourceId);
+                  if (depIdx !== -1 && s.id !== targetId) {
+                    s.dependencies[depIdx] = targetId;
+                    this.debug(`Remapped dependency: story "${s.name}" now depends on "${targetId}" (was "${sourceId}")`);
+                  }
+                }
+              }
+            }
+          }
+        }
+
+        // Remove source stories in reverse order
+        for (const srcIdx of sourceIndices.sort((a, b) => b - a)) {
+          epic.stories.splice(srcIdx, 1);
+        }
+      }
+    }
+
+    return hierarchy;
+  }
+
+  // STAGE 4.2: Review and split wide stories
+  async reviewAndSplitStories(hierarchy, progressCallback = null) {
+    this.debugStage(4.2, 'Review and Split Wide Stories');
+
+    const provider = await this.getProviderForStageInstance('decomposition');
+    const { provider: providerName, model: modelName } = this.getProviderForStage('decomposition');
+
+    const agentPath = path.join(this.agentsPath, 'story-scope-reviewer.md');
+    const reviewerAgent = fs.readFileSync(agentPath, 'utf8');
+
+    this.debug('Story scope reviewer loaded', { agentBytes: reviewerAgent.length, provider: providerName, model: modelName });
+    await progressCallback?.(null, `Reviewing story scopes for splits (${providerName} / ${modelName})…`, {});
+
+    let totalSplits = 0;
+    const contextSizeFailures = { count: 0 };
+
+    // Limit concurrency for story scope review: local models can't handle unbounded parallelism
+    const reviewConcurrency = providerName === 'local' ? 2 : hierarchy.epics.length;
+
+    // Process epics with bounded concurrency — one LLM call per epic
+    const epicTasks = hierarchy.epics.map((epic) => async () => {
+      // Early bail-out if too many context-size failures
+      if (contextSizeFailures.count >= 3) {
+        this.debug(`Skipping story review for "${epic.name}" — too many context-size failures`);
+        return { epic, stories: epic.stories, splits: [] };
+      }
+
+      const prompt = `## Epic
+name: ${epic.name}
+domain: ${epic.domain || 'unknown'}
+description: ${epic.description || ''}
+features: ${JSON.stringify(epic.features || [])}
+
+## Stories
+${JSON.stringify(epic.stories || [], null, 2)}
+
+Review the stories above and return the complete final story list for this epic, splitting any stories that are too broad according to your instructions.`;
+
+      this.debug(`Reviewing stories for epic: ${epic.name} (${(epic.stories || []).length} stories)`);
+
+      try {
+        const result = await this._withProgressHeartbeat(
+          () => this.retryWithBackoff(
+            () => provider.generateJSON(prompt, reviewerAgent),
+            `Story scope review for ${epic.name}`
+          ),
+          (elapsed) => {
+            if (elapsed < 20) return `Reviewing stories in ${epic.name}…`;
+            if (elapsed < 45) return `Checking scope boundaries for ${epic.name}…`;
+            return `Finalizing splits for ${epic.name}…`;
+          },
+          progressCallback,
+          20000
+        );
+
+        const splits = result.splits || [];
+        const stories = result.stories || epic.stories;
+
+        if (splits.length > 0) {
+          this.debug(`Splits applied in epic "${epic.name}"`, splits.map(s => ({
+            original: s.original,
+            into: s.into,
+            rationale: s.rationale
+          })));
+          for (const split of splits) {
+            await progressCallback?.(null, `  Split: ${split.original} → ${split.into.join(', ')} — ${split.rationale}`, {});
+          }
+        } else {
+          this.debug(`No splits needed for epic "${epic.name}"`);
+        }
+
+        return { epic, stories, splits };
+      } catch (err) {
+        if (err.message?.toLowerCase().includes('context size') || err.message?.includes('exceeded')) {
+          contextSizeFailures.count++;
+          this.debug(`Context-size failure #${contextSizeFailures.count} for epic "${epic.name}"`, { error: err.message });
+        }
+        this.debug(`Story scope review failed for epic "${epic.name}" — keeping original stories`, { error: err.message });
+        return { epic, stories: epic.stories, splits: [] };
+      }
+    });
+
+    // Run with bounded concurrency
+    const results = await this._runWithConcurrency(epicTasks, reviewConcurrency);
+
+    // Apply results back to hierarchy
+    for (const { epic, stories, splits } of results) {
+      epic.stories = stories;
+      totalSplits += splits.length;
+    }
+
+    const totalStories = hierarchy.epics.reduce((s, e) => s + (e.stories?.length || 0), 0);
+    this.debug(`Story scope review complete — ${totalSplits} split(s), ${totalStories} total stories`);
+    await progressCallback?.(null, `Story review complete: ${totalSplits} split(s), ${totalStories} total stories`, {});
+
+    return hierarchy;
+  }
+
+  /**
+   * Filter the decomposed hierarchy to only the epics/stories chosen by the user.
+   * @param {Object} hierarchy - Full decomposed hierarchy
+   * @param {string[]} selectedEpicIds - Epic IDs to keep
+   * @param {string[]} selectedStoryIds - Story IDs to keep
+   * @returns {Object} Filtered hierarchy
+   */
+  _filterHierarchyBySelection(hierarchy, selectedEpicIds, selectedStoryIds) {
+    const epicIdSet = new Set(selectedEpicIds);
+    const storyIdSet = new Set(selectedStoryIds);
+    const filteredEpics = hierarchy.epics
+      .filter(e => epicIdSet.has(e.id))
+      .map(e => ({
+        ...e,
+        stories: (e.stories || []).filter(s => storyIdSet.has(s.id))
+      }));
+    return { ...hierarchy, epics: filteredEpics };
+  }
+
+  /**
+   * Phase 1 of contextual selection: extract structured project characteristics from scope text.
+   * Called once per sprint-planning run when useContextualSelection is enabled.
+   * @param {string} scope - Project scope text (first 3000 chars used)
+   * @param {Function} progressCallback - Optional progress callback
+   * @returns {Promise<Object>} ProjectContext JSON (empty object on failure)
+   */
+  async extractProjectContext(scope, progressCallback) {
+    this.debug('Extracting project context for contextual agent selection');
+    try {
+      const provider = await this.getProviderForStageInstance('validation');
+      const agent = loadAgent('project-context-extractor.md');
+      // Use full doc.md for tech stack extraction — the "Initial Scope" section alone
+      // omits tech info from Overview (§1), UI/UX Design (§5), and Technical Architecture (§6).
+      let extractionText = scope || '';
+      if (fs.existsSync(this.projectDocPath)) {
+        extractionText = fs.readFileSync(this.projectDocPath, 'utf8');
+        this.debug(`Using full doc.md for context extraction (${extractionText.length} chars)`);
+      }
+      const prompt = `PROJECT SCOPE:\n\n${extractionText.substring(0, 20000)}\n\nScan the entire document above from start to finish for ALL technology mentions before filling each field. Do not stop at the first occurrence. Extract the structured project context as JSON.`;
+      const result = await provider.generateJSON(prompt, agent);
+      return result || {};
+    } catch (err) {
+      this.debug('Project context extraction failed, continuing without context', { error: err.message });
+      return {};
+    }
+  }
+
+  /**
+   * Generate canonical root context.md content from extracted project context + doc.md.
+   * Written once per run to {projectPath}/context.md — no LLM call needed.
+   * @param {Object} projectContext - JSON from project-context-extractor
+   * @param {string} docMdContent - Full root doc.md content
+   * @returns {string}
+   */
+  generateRootContextMd(projectContext, docMdContent, hierarchy = null) {
+    const ctx = projectContext || {};
+    const stack = (ctx.techStack || []).map(t => `- ${t}`).join('\n') || '- (not detected)';
+
+    // Purpose comes from the LLM-extracted field — no regex needed.
+    const purposeText = (ctx.purpose || '').trim();
+
+    // Detect auth mechanism from doc.md to enforce consistency across all contexts
+    const docLower = (docMdContent || '').toLowerCase();
+    let authMechanism = 'session-based (httpOnly cookies)';
+    // Check for "no auth" signals first
+    const noAuthPatterns = /no\s+auth|no\s+login|no\s+account|no\s+user\s+account|publicly\s+accessible|no\s+backend|no\s+server|single.file|static\s+site|client.side\s+only|no\s+authentication/i;
+    if (noAuthPatterns.test(docMdContent)) {
+      authMechanism = 'none (public, no authentication required)';
+    } else if (/jwt\s+token|bearer\s+token|authorization\s+header/i.test(docMdContent) && !/session.based|httponl/i.test(docMdContent)) {
+      authMechanism = 'JWT bearer tokens';
+    }
+
+    const lines = [
+      '# Project Context',
+      '',
+      '## Identity',
+      `- type: ${ctx.projectType || 'web-application'}`,
+      `- deployment: ${ctx.deploymentType || 'local'}`,
+      `- team: ${ctx.teamContext || 'small'}`,
+      '',
+      '## Purpose',
+      purposeText || '(see root doc.md)',
+      '',
+      '## Tech Stack',
+      stack,
+      '',
+      '## Authentication',
+      `- mechanism: ${authMechanism}`,
+      ...(authMechanism.startsWith('none')
+        ? ['- NOTE: This project has no authentication. Do NOT add auth mechanisms (sessions, JWT, login) to any epic or story.']
+        : ['- IMPORTANT: All epics and stories MUST use this auth mechanism consistently. Do NOT mix session cookies and JWT tokens.']),
+      '',
+      '## Project Characteristics',
+      `- hasCloud: ${ctx.hasCloud ?? false}`,
+      `- hasCI_CD: ${ctx.hasCI_CD ?? false}`,
+      `- hasMobileApp: ${ctx.hasMobileApp ?? false}`,
+      `- hasFrontend: ${ctx.hasFrontend ?? true}`,
+      `- hasPublicAPI: ${ctx.hasPublicAPI ?? false}`,
+    ];
+
+    // Add epic map if hierarchy is available
+    if (hierarchy?.epics?.length > 0) {
+      lines.push('', '## Epic Map');
+      for (const epic of hierarchy.epics) {
+        const storyCount = (epic.stories || []).length;
+        lines.push(`- **${epic.id}**: ${epic.name} (${storyCount} stories) — ${epic.domain || 'general'}`);
+      }
+      lines.push('', 'Use the epic IDs above when cross-referencing dependencies between epics and stories.');
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Generate a scaffolding epic by scanning all domain epic/story contexts for tech requirements.
+   * Called AFTER generateContextFiles() so all context.md files are in cache.
+   * Inserts the epic as the first item in hierarchy.epics with all others depending on it.
+   */
+  async _generateScaffoldingEpic(hierarchy, progressCallback) {
+    if (!hierarchy.epics || hierarchy.epics.length === 0) return;
+
+    // Skip if a scaffolding epic already exists (e.g., from a prior run)
+    if (hierarchy.epics.some(e => (e.domain || '').toLowerCase() === 'scaffolding')) {
+      this.debug('Scaffolding epic already exists — skipping generation');
+      return;
+    }
+
+    await progressCallback?.(null, 'Generating project scaffolding epic from tech requirements…', {});
+
+    // 1. Extract tech requirements from all cached context.md files
+    const techMentions = new Set();
+    const allContexts = [];
+
+    for (const [key, contextMd] of this._epicContextCache) {
+      allContexts.push(contextMd);
+      this._extractTechFromContext(contextMd, techMentions);
+    }
+    for (const [key, contextMd] of this._storyContextCache) {
+      allContexts.push(contextMd);
+      this._extractTechFromContext(contextMd, techMentions);
+    }
+
+    // Also extract from root context
+    if (this.rootContextMd) {
+      this._extractTechFromContext(this.rootContextMd, techMentions);
+    }
+
+    const techRequirements = [...techMentions].sort();
+    this.debug('Tech requirements extracted for scaffolding', { count: techRequirements.length, items: techRequirements });
+
+    if (techRequirements.length === 0) {
+      this.debug('No tech requirements found — skipping scaffolding generation');
+      return;
+    }
+
+    // 2. Call LLM to generate the scaffolding epic
+    const provider = await this.getProviderForStageInstance('context-generation');
+    const agentInstructions = loadAgent('scaffolding-generator.md');
+
+    const prompt = `## Project Context\n\n${this.rootContextMd || '(no root context)'}\n\n## Extracted Tech Requirements\n\nThe following technologies, packages, tools, and infrastructure were found across all ${hierarchy.epics.length} domain epics and their stories:\n\n${techRequirements.map(t => `- ${t}`).join('\n')}\n\n## Epic Count\n\n${hierarchy.epics.length} domain epics exist.`;
+
+    let scaffoldingData;
+    try {
+      scaffoldingData = await provider.generateJSON(prompt, agentInstructions);
+    } catch (err) {
+      this.debug('Scaffolding LLM call failed', { error: err.message });
+      return;
+    }
+
+    if (!scaffoldingData?.epic) {
+      this.debug('Scaffolding LLM returned no epic data');
+      return;
+    }
+
+    // 3. Build the scaffolding epic object
+    const scaffoldStories = (scaffoldingData.epic.stories || []).map((s, i) => {
+      const storyId = `context-0000-${String(i + 1).padStart(4, '0')}`;
+      const prevId = i > 0 ? `context-0000-${String(i).padStart(4, '0')}` : null;
+      // Chain dependencies: each story depends on the previous one
+      const deps = s.dependencies && s.dependencies.length > 0
+        ? s.dependencies
+        : (prevId ? [prevId] : []);
+      return {
+        id: storyId,
+        name: s.name,
+        userType: s.userType || 'developers',
+        description: s.description || '',
+        acceptance: s.acceptance || [],
+        dependencies: deps,
+      };
+    });
+
+    const scaffoldEpic = {
+      id: 'context-0000',
+      name: scaffoldingData.epic.name || 'Project Scaffolding and Environment Setup',
+      domain: 'scaffolding',
+      description: scaffoldingData.epic.description || '',
+      features: scaffoldingData.epic.features || [],
+      dependencies: [],
+      stories: scaffoldStories,
+    };
+
+    // 4. Insert as first epic
+    hierarchy.epics.unshift(scaffoldEpic);
+
+    // 5. Inject dependency: all domain epics depend on scaffolding
+    const scaffoldId = scaffoldEpic.id;
+    let injected = 0;
+    for (const epic of hierarchy.epics) {
+      if (epic.id === scaffoldId) continue;
+      if (!epic.dependencies) epic.dependencies = [];
+      if (!epic.dependencies.includes(scaffoldId)) {
+        epic.dependencies.push(scaffoldId);
+        injected++;
+      }
+    }
+
+    // 6. Generate context.md for the scaffolding epic (so validators see it)
+    try {
+      const scaffoldContext = await this.generateEpicContextMdLLM(scaffoldEpic, provider);
+      this._epicContextCache.set(scaffoldEpic.name, scaffoldContext);
+      // Also generate story contexts (4th param is the provider)
+      for (const story of scaffoldEpic.stories) {
+        const storyContext = await this.generateStoryContextMdLLM(story, scaffoldEpic, scaffoldContext, provider);
+        this._storyContextCache.set(`${scaffoldEpic.name}::${story.name}`, storyContext);
+      }
+    } catch (err) {
+      this.debug('Scaffolding context generation failed — using fallback', { error: err.message });
+    }
+
+    this.debug(`Scaffolding epic generated: "${scaffoldEpic.name}" with ${scaffoldEpic.stories.length} stories, ${injected} epics now depend on it`);
+    this.debug('Scaffolding stories', scaffoldEpic.stories.map(s => s.name));
+  }
+
+  /**
+   * Extract technology mentions from a context.md string.
+   * Looks for package names, frameworks, tools, and infrastructure.
+   */
+  _extractTechFromContext(contextText, techSet) {
+    if (!contextText) return;
+    const lower = contextText.toLowerCase();
+
+    // Common tech patterns to detect
+    const patterns = [
+      // JS/Node ecosystem
+      /\b(node\.?js|npm|yarn|pnpm)\b/gi,
+      /\b(express\.?js|express|fastify|koa|hapi)\b/gi,
+      /\b(react|vue\.?js|angular|svelte|next\.?js|nuxt)\b/gi,
+      /\b(vite|webpack|rollup|esbuild|parcel)\b/gi,
+      /\b(vitest|jest|mocha|chai|cypress|playwright)\b/gi,
+      /\b(typescript|tsconfig)\b/gi,
+      /\b(tailwind\s*css|bootstrap|material.ui)\b/gi,
+      /\b(prisma|sequelize|typeorm|knex|drizzle)\b/gi,
+      /\b(zustand|redux|mobx|react.query|tanstack)\b/gi,
+      // Databases
+      /\b(sqlite|postgresql|postgres|mysql|mongodb|redis)\b/gi,
+      // Infrastructure
+      /\b(docker|docker.compose|nginx|apache)\b/gi,
+      /\b(kubernetes|k8s|terraform|aws|gcp|azure)\b/gi,
+      // Python
+      /\b(python|pip|poetry|flask|django|fastapi|pytest)\b/gi,
+      // General
+      /\b(git|eslint|prettier|husky)\b/gi,
+      /\b(\.env|environment.variables|dotenv)\b/gi,
+      // File types that indicate tech
+      /\b(html5?|css3?|vanilla\s*javascript)\b/gi,
+    ];
+
+    for (const pattern of patterns) {
+      const matches = contextText.match(pattern);
+      if (matches) {
+        for (const m of matches) {
+          techSet.add(m.trim().toLowerCase());
+        }
+      }
+    }
+  }
+
+  /**
+   * Update the status field in a work.json file on disk.
+   */
+  _setWorkJsonStatus(workJsonPath, status) {
+    try {
+      if (!fs.existsSync(workJsonPath)) return;
+      const workJson = JSON.parse(fs.readFileSync(workJsonPath, 'utf8'));
+      workJson.status = status;
+      fs.writeFileSync(workJsonPath, JSON.stringify(workJson, null, 2), 'utf8');
+    } catch {}
+  }
+
+  /**
+   * Generate canonical context.md string for an epic from its JSON fields.
+   * No LLM call needed — derived directly from decomposition output.
+   * @param {Object} epic
+   * @returns {string}
+   */
+  generateEpicContextMd(epic) {
+    const features = (epic.features || []).map(f => `- ${f}`).join('\n') || '- (none)';
+    const deps = epic.dependencies || [];
+    const optional = deps.filter(d => /optional/i.test(d));
+    const required = deps.filter(d => !/optional/i.test(d));
+    const reqLines = required.length ? required.map(d => `- ${d}`).join('\n') : '- (none)';
+    const storyCount = (epic.stories || []).length;
+    const lines = [
+      `# Epic: ${epic.name}`,
+      '',
+      '## Identity',
+      `- id: ${epic.id || '(pending)'}`,
+      `- domain: ${epic.domain}`,
+      `- stories: ${storyCount}`,
+      '',
+      '## Summary',
+      epic.description || '(no description)',
+      '',
+      '## Features',
+      features,
+      '',
+      '## Dependencies',
+      '',
+      '### Required',
+      reqLines,
+    ];
+    if (optional.length) {
+      lines.push('', '### Optional');
+      optional.forEach(d => lines.push(`- ${d}`));
+    }
+    return lines.join('\n');
+  }
+
+  /**
+   * Generate canonical context.md string for a story from its JSON fields.
+   * No LLM call needed — derived directly from decomposition output.
+   * @param {Object} story
+   * @param {Object} epic - Parent epic for identity context
+   * @returns {string}
+   */
+  generateStoryContextMd(story, epic) {
+    const ac = (story.acceptance || []).map((a, i) => `${i + 1}. ${a}`).join('\n') || '1. (none)';
+    const deps = (story.dependencies || []).map(d => `- ${d}`).join('\n') || '- (none)';
+    return [
+      `# Story: ${story.name}`,
+      '',
+      '## Identity',
+      `- id: ${story.id || '(pending)'}`,
+      `- epic: ${epic.id || '(pending)'} (${epic.name})`,
+      `- userType: ${story.userType || 'team member'}`,
+      '',
+      '## Summary',
+      story.description || '(no description)',
+      '',
+      '## Acceptance Criteria',
+      ac,
+      '',
+      '## Dependencies',
+      deps,
+    ].join('\n');
+  }
+
+  /**
+   * Build deterministic scaffold for epic context.md — Identity, Features, Dependencies, Stories Overview.
+   * LLM only needs to write Purpose, Scope, Data Model, NFRs, Success Criteria.
+   * @param {Object} epicData - Canonical epic JSON
+   * @returns {string} Pre-built markdown sections
+   */
+  _buildEpicScaffold(epicData) {
+    const lines = [];
+    lines.push(`# Epic: ${epicData.name}`);
+    lines.push('');
+    lines.push('## Identity');
+    lines.push(`- id: ${epicData.id}`);
+    lines.push(`- domain: ${epicData.domain || 'general'}`);
+    lines.push(`- stories: ${(epicData.stories || []).length}`);
+    lines.push('');
+    lines.push('## Features');
+    for (const feature of epicData.features || []) {
+      lines.push(`- ${feature}`);
+    }
+    lines.push('');
+    lines.push('## Dependencies');
+    lines.push('');
+    lines.push('### Required');
+    const deps = epicData.dependencies || [];
+    if (deps.length === 0) {
+      lines.push('- (none)');
+    } else {
+      for (const dep of deps) {
+        lines.push(`- ${dep}`);
+      }
+    }
+    lines.push('');
+    lines.push('### Optional');
+    lines.push('- (none)');
+    lines.push('');
+    lines.push('## Stories Overview');
+    for (const story of epicData.stories || []) {
+      lines.push(`- ${story.id || 'TBD'}: ${story.name}`);
+    }
+    return lines.join('\n');
+  }
+
+  /**
+   * Build deterministic scaffold for story context.md — Identity, Acceptance Criteria, Dependencies.
+   * LLM only needs to write User Story, Summary, Scope, Technical Notes.
+   * @param {Object} storyData - Canonical story JSON
+   * @returns {string} Pre-built markdown sections
+   */
+  _buildStoryScaffold(storyData) {
+    const lines = [];
+    lines.push(`# Story: ${storyData.name}`);
+    lines.push('');
+    lines.push('## Identity');
+    lines.push(`- id: ${storyData.id || 'TBD'}`);
+    lines.push(`- epic: ${storyData.epicId || 'TBD'} (${storyData.epicName || 'TBD'})`);
+    lines.push(`- userType: ${storyData.userType || 'team member'}`);
+    lines.push('');
+    lines.push('## Acceptance Criteria');
+    const acceptance = storyData.acceptance || [];
+    for (let i = 0; i < acceptance.length; i++) {
+      lines.push(`${i + 1}. ${acceptance[i]}`);
+    }
+    lines.push('');
+    lines.push('## Dependencies');
+    const deps = storyData.dependencies || [];
+    if (deps.length === 0) {
+      lines.push('- (none)');
+    } else {
+      for (const dep of deps) {
+        lines.push(`- ${dep}`);
+      }
+    }
+    return lines.join('\n');
+  }
+
+  /**
+   * Detect domain-specific concerns from project context and work item features.
+   * Returns checklist items that the LLM MUST address in NFRs or Technical Notes.
+   * @param {string} rootContext - Root context.md text
+   * @param {Object} workItem - Epic or story-like object with features/description
+   * @returns {string[]} Domain hints
+   */
+  _detectDomainHints(rootContext, workItem) {
+    const hints = [];
+    const allText = [
+      rootContext,
+      workItem.description || '',
+      ...(workItem.features || []),
+    ].join(' ').toLowerCase();
+
+    // Scheduling / time-related → timezone handling
+    if (/schedul|cron|recurring|time.?zone|appointment|booking|remind/i.test(allText)) {
+      hints.push('Timezone handling: specify how dates/times are stored (UTC recommended) and how user-local display is handled');
+    }
+
+    // Auth / passwords → hashing strategy
+    if (/auth|password|login|sign.?up|credential|session|jwt|token/i.test(allText)) {
+      hints.push('Authentication security: specify password hashing algorithm (bcrypt/argon2), token expiry, and session invalidation strategy');
+    }
+
+    // Messaging / notifications → delivery guarantees
+    if (/messag|chat|notification|push|sms|whatsapp|email|webhook/i.test(allText)) {
+      hints.push('Message delivery: specify retry/queue strategy for failed deliveries, idempotency handling, and rate limiting');
+    }
+
+    // File uploads / media → size limits and storage
+    if (/upload|media|image|file|attachment|storage|s3|blob/i.test(allText)) {
+      hints.push('File handling: specify max file size, allowed MIME types, storage backend, and virus/malware scanning if applicable');
+    }
+
+    // Payment / billing → PCI compliance
+    if (/payment|billing|invoice|subscript|stripe|charge|refund/i.test(allText)) {
+      hints.push('Payment security: specify PCI compliance approach (tokenization recommended), refund handling, and receipt/audit trail');
+    }
+
+    // Real-time / websocket → connection management
+    if (/real.?time|websocket|socket\.io|live|stream|sse|event.?source/i.test(allText)) {
+      hints.push('Real-time connections: specify reconnection strategy, heartbeat interval, and graceful degradation when WebSocket is unavailable');
+    }
+
+    return hints;
+  }
+
+  /**
+   * Deterministic quality check for generated context.md — verifies structural completeness
+   * and source fidelity without relying on LLM self-assessment.
+   * @param {string} contextText - Generated context.md content
+   * @param {Object} sourceJson - The canonical source JSON (epic or story)
+   * @param {'epic'|'story'} type
+   * @param {Set<string>} [validIds] - Optional set of all valid epic/story IDs in the hierarchy for dependency cross-validation
+   * @returns {{ score: number, issues: string[] }}
+   */
+  _computeContextScore(contextText, sourceJson, type, validIds = null) {
+    let score = 100;
+    const issues = [];
+    const lower = contextText.toLowerCase();
+
+    // 1. Required sections present
+    const requiredSections = type === 'epic'
+      ? ['## Identity', '## Purpose', '## Scope', '### In Scope', '### Out of Scope',
+         '## Features', '## Non-Functional Requirements', '## Dependencies', '## Success Criteria', '## Stories Overview']
+      : ['## Identity', '## User Story', '## Summary', '## Scope', '### In Scope',
+         '### Out of Scope', '## Acceptance Criteria', '## Technical Notes', '## Dependencies'];
+
+    for (const section of requiredSections) {
+      if (!contextText.includes(section)) {
+        score -= 10;
+        issues.push(`Missing required section: ${section}`);
+      }
+    }
+
+    // 2. Feature / acceptance criteria coverage against source JSON
+    if (type === 'epic') {
+      const features = sourceJson.features || [];
+      let missing = 0;
+      for (const feature of features) {
+        // Extract the key term before parenthetical details
+        const featureKey = feature.split('(')[0].trim().toLowerCase().replace(/[-_]/g, ' ');
+        if (!lower.includes(featureKey) && featureKey.length > 3) {
+          missing++;
+          issues.push(`Feature possibly missing from output: "${feature.slice(0, 60)}"`);
+        }
+      }
+      score -= missing * 5;
+    } else {
+      const acceptance = sourceJson.acceptance || [];
+      if (acceptance.length > 0) {
+        // Strip markdown formatting (backticks, bold, italic) for fuzzy matching
+        const stripMd = (s) => s.toLowerCase().replace(/[`*_~]/g, '').replace(/\s+/g, ' ');
+        const lowerStripped = stripMd(contextText);
+        let matched = 0;
+        for (const ac of acceptance) {
+          const acStripped = stripMd(ac);
+          // Extract key terms (3+ char words) and check if majority appear in context
+          const keyTerms = acStripped.split(/\s+/).filter(w => w.length >= 3 && !/^(the|and|for|with|from|that|this|are|was|has|have|will|can|not|but|its|also|into)$/.test(w));
+          if (keyTerms.length === 0) { matched++; continue; }
+          const found = keyTerms.filter(term => lowerStripped.includes(term)).length;
+          if (found / keyTerms.length >= 0.5) matched++;
+        }
+        const coverage = matched / acceptance.length;
+        if (coverage < 0.7) {
+          const missCount = acceptance.length - matched;
+          score -= missCount * 5;
+          issues.push(`Only ${matched}/${acceptance.length} acceptance criteria found in output`);
+        }
+      }
+    }
+
+    // 3. Non-ASCII anomaly detection (catches Chinese/CJK character leaks from local models)
+    const cjkPattern = /[\u3000-\u9FFF\uF900-\uFAFF\uFE30-\uFE4F]/g;
+    const cjkMatches = contextText.match(cjkPattern);
+    if (cjkMatches && cjkMatches.length > 0) {
+      score -= 15;
+      issues.push(`Non-ASCII anomaly: ${cjkMatches.length} CJK character(s) detected — likely model generation artifact`);
+    }
+
+    // 4. Section minimum substance (headers with < 2 content lines)
+    const sectionBlocks = contextText.split(/^## /m).filter(s => s.trim());
+    for (const block of sectionBlocks) {
+      const lines = block.split('\n').filter(l => l.trim());
+      const sectionName = lines[0]?.trim().split('\n')[0] || 'unknown';
+      // Skip subsections (### In Scope etc.) — they're part of parent
+      if (sectionName.startsWith('#')) continue;
+      if (lines.length < 2) {
+        score -= 5;
+        issues.push(`Section too thin: "## ${sectionName}" has only ${lines.length} content line(s)`);
+      }
+    }
+
+    // 5. Dependencies match source JSON
+    const sourceDeps = sourceJson.dependencies || [];
+    for (const dep of sourceDeps) {
+      const depId = typeof dep === 'string' ? dep : dep.id || dep.name || '';
+      if (depId && !contextText.includes(depId)) {
+        score -= 5;
+        issues.push(`Dependency from source JSON not found in output: "${depId}"`);
+      }
+    }
+
+    // 6. Dependency cross-validation — verify referenced IDs exist in hierarchy
+    if (validIds && sourceDeps.length > 0) {
+      for (const dep of sourceDeps) {
+        const depId = typeof dep === 'string' ? dep : dep.id || dep.name || '';
+        if (depId && /^context-\d{4}(-\d{4})?$/.test(depId) && !validIds.has(depId)) {
+          score -= 10;
+          issues.push(`Broken dependency chain: "${depId}" does not exist in the hierarchy`);
+        }
+      }
+    }
+
+    // 7. Data model presence for data-heavy epics (soft suggestion, no score penalty)
+    if (type === 'epic') {
+      const featureText = (sourceJson.features || []).join(' ').toLowerCase();
+      const hasDataKeywords = /stor|persist|record|track|log|database|schema|model|ingestion/.test(featureText);
+      if (hasDataKeywords && !contextText.includes('## Data Model')) {
+        issues.push('Consider adding "## Data Model Sketch" section — features mention data storage');
+      }
+    }
+
+    // 8. Auth mechanism consistency — check against root context
+    if (this.rootContextMd) {
+      const rootLower = this.rootContextMd.toLowerCase();
+      const isNoAuth = rootLower.includes('none (public') || rootLower.includes('no authentication required');
+      const isSessionAuth = !isNoAuth && (rootLower.includes('session-based') || rootLower.includes('httponly'));
+      const isJwtAuth = !isNoAuth && rootLower.includes('jwt bearer');
+      if (isNoAuth) {
+        // No-auth project — penalize any auth mechanism references
+        if (/\bjwt\b|bearer\s+token|session\s+cookie|httponly|authorization\s*:\s*bearer|login|sign.?in/i.test(contextText)) {
+          score -= 10;
+          issues.push('Auth inconsistency: context references auth mechanisms but project has no authentication');
+        }
+      } else if (isSessionAuth) {
+        // Session auth project — penalize JWT references
+        if (/\bjwt\b|bearer\s+token|authorization\s*:\s*bearer/i.test(contextText)) {
+          score -= 10;
+          issues.push('Auth inconsistency: context references JWT/bearer tokens but project uses session-based auth (httpOnly cookies)');
+        }
+      } else if (isJwtAuth) {
+        // JWT project — penalize session cookie references
+        if (/session\s+cookie|httponly\s+cookie|sessionid\s+cookie/i.test(contextText)) {
+          score -= 10;
+          issues.push('Auth inconsistency: context references session cookies but project uses JWT bearer tokens');
+        }
+      }
+    }
+
+    // 9. Rate limit numeric consistency — detect contradictory values within same context
+    const rateLimitMatches = contextText.match(/(\d+)\s*(requests?|req|messages?|calls?)\s*\/?\s*(second|sec|s|minute|min|m|hour|hr|h)\b/gi) || [];
+    if (rateLimitMatches.length >= 2) {
+      // Normalize to per-minute for comparison
+      const normalize = (match) => {
+        const m = match.match(/(\d+)\s*(?:requests?|req|messages?|calls?)\s*\/?\s*(second|sec|s|minute|min|m|hour|hr|h)/i);
+        if (!m) return null;
+        const val = parseInt(m[1]);
+        const unit = m[2].toLowerCase();
+        if (unit.startsWith('s')) return val * 60; // per sec → per min
+        if (unit.startsWith('h')) return val / 60; // per hour → per min
+        return val; // per min
+      };
+      const normalized = rateLimitMatches.map(normalize).filter(v => v !== null);
+      if (normalized.length >= 2) {
+        const min = Math.min(...normalized);
+        const max = Math.max(...normalized);
+        if (max / min > 10) { // >10x discrepancy
+          score -= 5;
+          issues.push(`Rate limit inconsistency: found values ranging from ${min}/min to ${max}/min (${max/min}x difference)`);
+        }
+      }
+    }
+
+    return { score: Math.max(0, score), issues };
+  }
+
+  /**
+   * Call generateJSON with tool support if the provider has it, otherwise plain generateJSON.
+   * Only provides tools on the first write call (iter 0) — refinement iterations don't need them.
+   * @param {Object} provider - LLM provider instance
+   * @param {string} prompt - User prompt
+   * @param {string} instructions - System/agent instructions
+   * @param {boolean} [useTools=false] - Whether to attempt tool-augmented generation
+   * @returns {Promise<Object>} Parsed JSON result
+   */
+  async _generateJSONMaybeWithTools(provider, prompt, instructions, useTools = false) {
+    if (useTools && typeof provider.generateJSONWithTools === 'function') {
+      try {
+        return await provider.generateJSONWithTools(
+          prompt, instructions,
+          CONTEXT_GENERATION_TOOLS, dispatchToolCall
+        );
+      } catch (err) {
+        this.debug(`Tool-augmented generation failed, falling back to plain generateJSON: ${err.message}`);
+      }
+    }
+    return provider.generateJSON(prompt, instructions);
+  }
+
+  /**
+   * Generate a complete canonical context.md for an epic using an LLM agent.
+   * Uses deterministic pre-check (not LLM self-score) to decide whether to invoke the reviewer.
+   * Falls back to the structured formatter if the LLM call fails.
+   * @param {Object} epic
+   * @param {LLMProvider} provider
+   * @returns {Promise<string>} context.md text
+   */
+  async generateEpicContextMdLLM(epic, provider) {
+    const writerInstructions  = loadAgent('context-writer-epic.md');
+    const reviewerInstructions = loadAgent('context-reviewer-epic.md');
+    const rootSection = this.rootContextMd ? `## Project Context\n\n${this.rootContextMd}\n\n` : '';
+
+    // Canonical source for both writer and reviewer
+    const epicForContext = {
+      id: epic.id,
+      name: epic.name,
+      domain: epic.domain,
+      description: epic.description,
+      features: epic.features || [],
+      dependencies: epic.dependencies || [],
+      stories: (epic.stories || []).map(s => ({ id: s.id || 'TBD', name: s.name })),
+    };
+    const epicJson = JSON.stringify(epicForContext, null, 2);
+
+    // Template-based scaffolding — pre-generate deterministic sections so the LLM
+    // only needs to write Purpose, Scope, Data Model, NFRs, and Success Criteria.
+    const scaffold = this._buildEpicScaffold(epicForContext);
+    const scaffoldHint = `\n\n## Pre-built Scaffold (use verbatim for these sections, write the rest)\n\n\`\`\`\n${scaffold}\n\`\`\``;
+
+    // Domain-aware prompt injection — detect project features and add mandatory checklist items
+    const domainHints = this._detectDomainHints(this.rootContextMd || '', epicForContext);
+    const domainSection = domainHints.length > 0
+      ? `\n\n## Domain-Specific Requirements (MUST address in NFRs or Technical Notes)\n${domainHints.map(h => `- ${h}`).join('\n')}`
+      : '';
+
+    const baseWriterPrompt   = `${rootSection}## Epic JSON\n\n\`\`\`json\n${epicJson}\n\`\`\`${scaffoldHint}${domainSection}`;
+    const baseReviewerPrompt = `${rootSection}## Original Epic JSON\n\n\`\`\`json\n${epicJson}\n\`\`\``;
+
+    let bestContext = null;
+    let bestScore   = 0;
+    let writerPrompt = `${baseWriterPrompt}\n\nWrite the complete context.md for this epic. Use the pre-built scaffold verbatim for Identity, Features, Dependencies, and Stories Overview sections. Focus your effort on Purpose, Scope, Data Model, NFRs, and Success Criteria.`;
+
+    // Write → Review → Refine loop (max 2 review rounds = max 3 LLM calls total)
+    for (let iter = 0; iter < 3; iter++) {
+      // Step 1: Write (or refine) — use tool-augmented generation on first iteration
+      const writeResult  = await this._generateJSONMaybeWithTools(provider, writerPrompt, writerInstructions, iter === 0);
+      const contextText  = (typeof writeResult?.context === 'string' && writeResult.context.trim()) ? writeResult.context : null;
+      const writerScore  = typeof writeResult?.completenessScore === 'number' ? writeResult.completenessScore : 100;
+      const writerGaps   = Array.isArray(writeResult?.gaps) ? writeResult.gaps : [];
+
+      if (!contextText) {
+        this.debug(`[context-writer-epic] iter=${iter + 1} — no context returned, stopping (epic: ${epic.name})`);
+        break;
+      }
+
+      // Deterministic pre-check — verifies structure and source fidelity without LLM
+      const preCheck = this._computeContextScore(contextText, epicForContext, 'epic', this._hierarchyValidIds);
+      const canSkipReview = preCheck.score >= 92;
+
+      if (canSkipReview) {
+        this.debug(`[context-epic] iter=${iter + 1} writerScore=${writerScore} preCheck=${preCheck.score} — skipping review (deterministic pass) (epic: ${epic.name})`);
+        if (preCheck.score > bestScore) {
+          bestContext = contextText;
+          bestScore   = preCheck.score;
+        }
+        break;
+      }
+
+      // Pre-check found issues — run independent LLM review
+      this.debug(`[context-epic] iter=${iter + 1} writerScore=${writerScore} preCheck=${preCheck.score} preCheckIssues=${preCheck.issues.length} — triggering review (epic: ${epic.name})`);
+
+      // Step 2: Independent review — verifies accuracy against source JSON
+      const reviewPrompt  = `${baseReviewerPrompt}\n\n## Generated context.md\n\n${contextText}\n\nAudit this context.md against the source JSON.`;
+      const reviewResult  = await provider.generateJSON(reviewPrompt, reviewerInstructions);
+      const reviewScore   = typeof reviewResult?.score === 'number' ? reviewResult.score : preCheck.score;
+      const reviewIssues  = Array.isArray(reviewResult?.issues) ? reviewResult.issues : [];
+      const accurate      = reviewResult?.accurate === true;
+
+      // Combine deterministic issues with LLM reviewer issues (dedup by prefix)
+      const combinedIssues = [...preCheck.issues];
+      for (const ri of reviewIssues) {
+        if (!combinedIssues.some(ci => ci.slice(0, 40) === ri.slice(0, 40))) {
+          combinedIssues.push(ri);
+        }
+      }
+
+      // Keep the best version seen so far (use reviewer score, not self-score)
+      if (reviewScore > bestScore) {
+        bestContext = contextText;
+        bestScore   = reviewScore;
+      }
+
+      this.debug(`[context-epic] iter=${iter + 1} writerScore=${writerScore} preCheck=${preCheck.score} reviewScore=${reviewScore} accurate=${accurate} issues=${combinedIssues.length} (epic: ${epic.name})`);
+
+      // Stop if reviewer confirms accuracy and score is high enough
+      if (accurate && reviewScore >= 85) break;
+      if (iter === 2) break; // max iterations reached
+
+      // Step 3: Build refinement prompt combining deterministic + reviewer + writer issues
+      const allFeedback = [
+        ...combinedIssues,
+        ...writerGaps.filter(g => !combinedIssues.some(i => i.includes(g.slice(0, 30)))),
+      ];
+      const feedbackText = allFeedback.map((f, i) => `${i + 1}. ${f}`).join('\n');
+      writerPrompt = `${baseWriterPrompt}\n\n## Draft Context (Review Score: ${reviewScore}/100)\n\n${contextText}\n\n## Issues to Fix\n\n${feedbackText}\n\nRevise the context.md to address all issues above. Return improved JSON.`;
+    }
+
+    return bestContext || this.generateEpicContextMd(epic);
+  }
+
+  /**
+   * Generate a complete canonical context.md for a story using an LLM agent.
+   * Uses deterministic pre-check (not LLM self-score) to decide whether to invoke the reviewer.
+   * Falls back to the structured formatter if the LLM call fails.
+   * @param {Object} story
+   * @param {Object} epic - Parent epic
+   * @param {string} epicContextMd - Parent epic's generated context.md
+   * @param {LLMProvider} provider
+   * @returns {Promise<string>} context.md text
+   */
+  async generateStoryContextMdLLM(story, epic, epicContextMd, provider) {
+    const writerInstructions   = loadAgent('context-writer-story.md');
+    const reviewerInstructions = loadAgent('context-reviewer-story.md');
+    const rootSection  = this.rootContextMd ? `## Project Context\n\n${this.rootContextMd}\n\n` : '';
+    const epicSection  = epicContextMd ? `## Parent Epic Context\n\n${epicContextMd}\n\n` : '';
+
+    // Canonical source for both writer and reviewer
+    const storyForContext = {
+      id: story.id || 'TBD',
+      name: story.name,
+      userType: story.userType || 'team member',
+      description: story.description,
+      acceptance: story.acceptance || [],
+      dependencies: story.dependencies || [],
+      epicId: epic.id || 'TBD',
+      epicName: epic.name,
+    };
+    const storyJson = JSON.stringify(storyForContext, null, 2);
+
+    // Template-based scaffolding for stories
+    const scaffold = this._buildStoryScaffold(storyForContext);
+    const scaffoldHint = `\n\n## Pre-built Scaffold (use verbatim for these sections, write the rest)\n\n\`\`\`\n${scaffold}\n\`\`\``;
+
+    // Domain-aware hints for stories
+    const domainHints = this._detectDomainHints(this.rootContextMd || '', { features: story.acceptance || [], description: story.description });
+    const domainSection = domainHints.length > 0
+      ? `\n\n## Domain-Specific Requirements (MUST address in Technical Notes)\n${domainHints.map(h => `- ${h}`).join('\n')}`
+      : '';
+
+    const baseWriterPrompt   = `${rootSection}${epicSection}## Story JSON\n\n\`\`\`json\n${storyJson}\n\`\`\`${scaffoldHint}${domainSection}`;
+    const baseReviewerPrompt = `${rootSection}## Original Story JSON\n\n\`\`\`json\n${storyJson}\n\`\`\``;
+
+    let bestContext = null;
+    let bestScore   = 0;
+    let writerPrompt = `${baseWriterPrompt}\n\nWrite the complete context.md for this story. Use the pre-built scaffold verbatim for Identity, Acceptance Criteria, and Dependencies sections. Focus on User Story, Summary, Scope, and Technical Notes.`;
+
+    // Write → Review → Refine loop (max 2 review rounds = max 3 LLM calls total)
+    for (let iter = 0; iter < 3; iter++) {
+      // Step 1: Write (or refine) — use tool-augmented generation on first iteration
+      const writeResult = await this._generateJSONMaybeWithTools(provider, writerPrompt, writerInstructions, iter === 0);
+      const contextText = (typeof writeResult?.context === 'string' && writeResult.context.trim()) ? writeResult.context : null;
+      const writerScore = typeof writeResult?.completenessScore === 'number' ? writeResult.completenessScore : 100;
+      const writerGaps  = Array.isArray(writeResult?.gaps) ? writeResult.gaps : [];
+
+      if (!contextText) {
+        this.debug(`[context-writer-story] iter=${iter + 1} — no context returned, stopping (story: ${story.name})`);
+        break;
+      }
+
+      // Deterministic pre-check — verifies structure and source fidelity without LLM
+      const preCheck = this._computeContextScore(contextText, storyForContext, 'story', this._hierarchyValidIds);
+      const canSkipReview = preCheck.score >= 92;
+
+      if (canSkipReview) {
+        this.debug(`[context-story] iter=${iter + 1} writerScore=${writerScore} preCheck=${preCheck.score} — skipping review (deterministic pass) (story: ${story.name})`);
+        if (preCheck.score > bestScore) {
+          bestContext = contextText;
+          bestScore   = preCheck.score;
+        }
+        break;
+      }
+
+      // Pre-check found issues — run independent LLM review
+      this.debug(`[context-story] iter=${iter + 1} writerScore=${writerScore} preCheck=${preCheck.score} preCheckIssues=${preCheck.issues.length} — triggering review (story: ${story.name})`);
+
+      // Step 2: Independent review — verifies accuracy against source JSON
+      const reviewPrompt  = `${baseReviewerPrompt}\n\n## Generated context.md\n\n${contextText}\n\nAudit this context.md against the source JSON.`;
+      const reviewResult  = await provider.generateJSON(reviewPrompt, reviewerInstructions);
+      const reviewScore   = typeof reviewResult?.score === 'number' ? reviewResult.score : preCheck.score;
+      const reviewIssues  = Array.isArray(reviewResult?.issues) ? reviewResult.issues : [];
+      const accurate      = reviewResult?.accurate === true;
+
+      // Combine deterministic issues with LLM reviewer issues (dedup by prefix)
+      const combinedIssues = [...preCheck.issues];
+      for (const ri of reviewIssues) {
+        if (!combinedIssues.some(ci => ci.slice(0, 40) === ri.slice(0, 40))) {
+          combinedIssues.push(ri);
+        }
+      }
+
+      if (reviewScore > bestScore) {
+        bestContext = contextText;
+        bestScore   = reviewScore;
+      }
+
+      this.debug(`[context-story] iter=${iter + 1} writerScore=${writerScore} preCheck=${preCheck.score} reviewScore=${reviewScore} accurate=${accurate} issues=${combinedIssues.length} (story: ${story.name})`);
+
+      if (accurate && reviewScore >= 85 && preCheck.score >= 85) break;
+      if (iter === 2) break;
+
+      // Step 3: Refinement prompt combining deterministic + reviewer + writer issues
+      const allFeedback = [
+        ...combinedIssues,
+        ...writerGaps.filter(g => !combinedIssues.some(i => i.includes(g.slice(0, 30)))),
+      ];
+      const feedbackText = allFeedback.map((f, i) => `${i + 1}. ${f}`).join('\n');
+      writerPrompt = `${baseWriterPrompt}\n\n## Draft Context (Review Score: ${reviewScore}/100)\n\n${contextText}\n\n## Issues to Fix\n\n${feedbackText}\n\nRevise the context.md to address all issues above. Return improved JSON.`;
+    }
+
+    return bestContext || this.generateStoryContextMd(story, epic);
+  }
+
+  /**
+   * Pre-generate LLM context.md for all epics and stories before validation.
+   * Results are cached in _epicContextCache (keyed by epic.name) and
+   * _storyContextCache (keyed by "epicName::storyName").
+   * Uses 'context-generation' stage config if defined; falls back to 'doc-generation'.
+   * @param {Object} hierarchy
+   * @param {Function} progressCallback
+   */
+  async generateContextFiles(hierarchy, progressCallback = null) {
+    this.debugStage(4.8, 'Pre-generate LLM Context Files');
+    this._epicContextCache = new Map();
+    this._storyContextCache = new Map();
+
+    // Build set of all valid IDs for dependency cross-validation
+    this._hierarchyValidIds = new Set();
+    for (const epic of hierarchy.epics) {
+      if (epic.id) this._hierarchyValidIds.add(epic.id);
+      for (const story of epic.stories || []) {
+        if (story.id) this._hierarchyValidIds.add(story.id);
+      }
+    }
+    this.debug(`Dependency cross-validation: ${this._hierarchyValidIds.size} valid IDs indexed`);
+
+    // Use context-generation stage if configured; fall back to doc-generation then ceremony default
+    const stageName = this.stagesConfig?.['context-generation'] ? 'context-generation' : 'doc-generation';
+    const provider = await this.getProviderForStageInstance(stageName);
+    const { model: modelName } = this.getProviderForStage(stageName);
+    this.debug(`Context generation using model: ${modelName}`);
+
+    const epicCount = hierarchy.epics.length;
+    const storyCount = hierarchy.epics.reduce((s, e) => s + (e.stories?.length || 0), 0);
+    await progressCallback?.(null, `Generating context for ${epicCount} epics + ${storyCount} stories…`, {});
+
+    // Concurrency control — limit concurrent context-generation calls to avoid saturating the server.
+    const defaultCtxConcurrency = this._providerName === 'local' ? 2 : hierarchy.epics.length;
+    const ctxConcurrency = this.stagesConfig?.['context-generation']?.concurrency ?? defaultCtxConcurrency;
+    this.debug(`Context generation concurrency: ${ctxConcurrency} (provider: ${this._providerName})`);
+
+    // Helper: run async tasks with concurrency limit
+    const runWithConcurrency = async (items, fn, limit) => {
+      if (limit >= items.length) {
+        return Promise.all(items.map(fn));
+      }
+      const queue = [...items];
+      const running = new Set();
+      let idx = 0;
+      while (idx < queue.length || running.size > 0) {
+        while (idx < queue.length && running.size < limit) {
+          const item = queue[idx++];
+          const p = fn(item).then(() => running.delete(p));
+          running.add(p);
+        }
+        if (running.size > 0) await Promise.race(running);
+      }
+    };
+
+    // Phase 1: Generate epic contexts with concurrency control
+    const epicCtxFailures = { count: 0 };
+    await runWithConcurrency(hierarchy.epics, async (epic) => {
+      if (epicCtxFailures.count >= 3) {
+        this.debug(`Skipping LLM context for epic "${epic.name}" — too many context-size failures, using structured fallback`);
+        this._epicContextCache.set(epic.name, this.generateEpicContextMd(epic));
+      } else {
+        try {
+          this.debug(`Generating context for epic: ${epic.name}`);
+          const epicContextMd = await this.generateEpicContextMdLLM(epic, provider);
+          this._epicContextCache.set(epic.name, epicContextMd);
+          this.debug(`Epic context generated: ${epic.name} (${epicContextMd.length} bytes)`);
+        } catch (err) {
+          if (err.message?.toLowerCase().includes('context size') || err.message?.includes('exceeded')) {
+            epicCtxFailures.count++;
+            this.debug(`Context-size failure #${epicCtxFailures.count} for epic context "${epic.name}"`, { error: err.message });
+          }
+          this.debug(`Epic context generation failed — using structured fallback (${epic.name})`, { error: err.message });
+          this._epicContextCache.set(epic.name, this.generateEpicContextMd(epic));
+        }
+      }
+      // Write context.md immediately using provisional ID — visible on disk during the ceremony.
+      // Stage 6 (writeHierarchyFiles) will rename the folder if IDs change after renumbering.
+      try {
+        const provisionalEpicDir = path.join(this.projectPath, epic.id);
+        if (!fs.existsSync(provisionalEpicDir)) fs.mkdirSync(provisionalEpicDir, { recursive: true });
+        fs.writeFileSync(path.join(provisionalEpicDir, 'context.md'), this._epicContextCache.get(epic.name), 'utf8');
+        this.debug(`Epic context.md written early (provisional): ${epic.id}/context.md`);
+      } catch (err) {
+        this.debug(`Early epic context.md write failed — will retry in Stage 6`, { error: err.message });
+      }
+    }, ctxConcurrency);
+
+    // Phase 2: Generate story contexts with concurrency control.
+    // Stories within each epic run sequentially to maximise OpenAI prefix-cache hits:
+    // all stories of the same epic share an identical system-message prefix
+    // (agentInstructions + epic context.md), so calls 2-N hit the cache at a 90% discount.
+    const storyCtxFailures = { count: 0 };
+    await runWithConcurrency(hierarchy.epics, async (epic) => {
+      const epicContextMd = this._epicContextCache.get(epic.name) || this.generateEpicContextMd(epic);
+      for (const story of (epic.stories || [])) {
+        const cacheKey = `${epic.name}::${story.name}`;
+        if (storyCtxFailures.count >= 3) {
+          this.debug(`Skipping LLM context for story "${story.name}" — too many context-size failures, using structured fallback`);
+          this._storyContextCache.set(cacheKey, this.generateStoryContextMd(story, epic));
+        } else {
+          try {
+            this.debug(`Generating context for story: ${story.name}`);
+            const storyContextMd = await this.generateStoryContextMdLLM(story, epic, epicContextMd, provider);
+            this._storyContextCache.set(cacheKey, storyContextMd);
+            this.debug(`Story context generated: ${story.name} (${storyContextMd.length} bytes)`);
+          } catch (err) {
+            if (err.message?.toLowerCase().includes('context size') || err.message?.includes('exceeded')) {
+              storyCtxFailures.count++;
+              this.debug(`Context-size failure #${storyCtxFailures.count} for story context "${story.name}"`, { error: err.message });
+            }
+            this.debug(`Story context generation failed — using structured fallback (${story.name})`, { error: err.message });
+            this._storyContextCache.set(cacheKey, this.generateStoryContextMd(story, epic));
+          }
+        }
+        // Write context.md immediately using provisional IDs.
+        try {
+          const provisionalStoryDir = path.join(this.projectPath, epic.id, story.id);
+          if (!fs.existsSync(provisionalStoryDir)) fs.mkdirSync(provisionalStoryDir, { recursive: true });
+          fs.writeFileSync(path.join(provisionalStoryDir, 'context.md'), this._storyContextCache.get(cacheKey), 'utf8');
+          this.debug(`Story context.md written early (provisional): ${epic.id}/${story.id}/context.md`);
+        } catch (err) {
+          this.debug(`Early story context.md write failed — will retry in Stage 6`, { error: err.message });
+        }
+      }
+    }, ctxConcurrency);
+
+    // Post-generation dependency validation — verify all context-XXXX references exist
+    this._validateDependencyReferences(hierarchy);
+
+    this.debug(`Context generation complete: ${this._epicContextCache.size} epic contexts, ${this._storyContextCache.size} story contexts`);
+  }
+
+  /**
+   * Validate that all dependency references across the hierarchy point to existing IDs.
+   * Removes broken references and logs warnings. Runs after context generation and after splits.
+   * @param {Object} hierarchy
+   */
+  _validateDependencyReferences(hierarchy) {
+    const validIds = new Set();
+    for (const epic of hierarchy.epics) {
+      if (epic.id) validIds.add(epic.id);
+      for (const story of epic.stories || []) {
+        if (story.id) validIds.add(story.id);
+      }
+    }
+
+    let brokenCount = 0;
+    let removedCount = 0;
+
+    for (const epic of hierarchy.epics) {
+      if (Array.isArray(epic.dependencies)) {
+        epic.dependencies = epic.dependencies.filter(dep => {
+          if (/^context-\d{4}(-\d{4})?$/.test(dep) && !validIds.has(dep)) {
+            brokenCount++;
+            removedCount++;
+            this.debug(`Broken dependency removed: epic "${epic.name}" referenced non-existent "${dep}"`);
+            return false;
+          }
+          return true;
+        });
+      }
+      for (const story of epic.stories || []) {
+        if (Array.isArray(story.dependencies)) {
+          story.dependencies = story.dependencies.filter(dep => {
+            if (/^context-\d{4}(-\d{4})?$/.test(dep) && !validIds.has(dep)) {
+              brokenCount++;
+              removedCount++;
+              this.debug(`Broken dependency removed: story "${story.name}" referenced non-existent "${dep}"`);
+              return false;
+            }
+            return true;
+          });
+        }
+      }
+    }
+
+    if (brokenCount > 0) {
+      this.debug(`Dependency validation: removed ${removedCount} broken reference(s) across hierarchy`);
+      console.log(`   ⚠ Removed ${removedCount} broken dependency reference(s) (hallucinated IDs)`);
+    } else {
+      this.debug('Dependency validation: all references valid');
+    }
+  }
+
+  /**
+   * Generate narrative doc.md files for all epics and stories from their canonical context.md.
+   * Replaces the old doc-distribution stage. Uses doc-writer-epic.md and doc-writer-story.md agents.
+   *
+   * Context chain:
+   *   Epic doc.md  : root doc.md + epic context.md → narrative
+   *   Story doc.md : root doc.md + parent epic context.md + story context.md → narrative
+   *
+   * Strict: agents are instructed not to add scope beyond what is in context.md.
+   *
+   * @param {Object} hierarchy - Hierarchy with final validated epics and stories (real IDs)
+   * @param {string} rootDocContent - Content of root doc.md
+   * @param {Function} progressCallback
+   */
+  async generateDocFiles(hierarchy, rootDocContent, progressCallback = null) {
+    this.debugStage(6.5, 'Generate Narrative doc.md Files from Canonical context.md');
+
+    const epicAgentInstructions = loadAgent('doc-writer-epic.md');
+    const storyAgentInstructions = loadAgent('doc-writer-story.md');
+    // Uses 'doc-generation' stage config if defined; falls back to ceremony-level provider
+    const provider = await this.getProviderForStageInstance('doc-generation');
+
+    const doGenerate = rootDocContent && rootDocContent.length > 0;
+    if (!doGenerate) {
+      this.debug('No root doc.md content — skipping doc generation, writing minimal stubs');
+    }
+
+    await Promise.all(hierarchy.epics.map(async (epic) => {
+      const epicDir = path.join(this.projectPath, epic.id);
+      const epicContextPath = path.join(epicDir, 'context.md');
+      const epicDocPath = path.join(epicDir, 'doc.md');
+
+      // Read the epic's canonical context.md (written earlier in writeHierarchyFiles)
+      let epicContextMd = '';
+      if (fs.existsSync(epicContextPath)) {
+        epicContextMd = fs.readFileSync(epicContextPath, 'utf8');
+      } else {
+        epicContextMd = this.generateEpicContextMd(epic);
+      }
+
+      // Generate epic doc.md
+      if (doGenerate) {
+        await progressCallback?.(null, `Generating documentation → ${epic.name}`, {});
+        this.debug(`Generating doc.md for epic ${epic.id}: ${epic.name}`);
+        try {
+          const prompt = `## Project Documentation\n\n${rootDocContent}\n\n---\n\n## Epic Canonical Specification\n\n${epicContextMd}\n\nWrite the epic's doc.md. Return JSON with a \`doc\` field.`;
+          const result = await this._withProgressHeartbeat(
+            () => this.retryWithBackoff(
+              () => provider.generateJSON(prompt, epicAgentInstructions),
+              `doc generation for epic: ${epic.name}`
+            ),
+            (elapsed) => {
+              if (elapsed < 15) return `Writing ${epic.name} documentation…`;
+              if (elapsed < 40) return `Expanding ${epic.name} narrative…`;
+              return `Still writing…`;
+            },
+            progressCallback,
+            10000
+          );
+          const epicDoc = (typeof result.doc === 'string' && result.doc.trim())
+            ? result.doc
+            : `# ${epic.name}\n\n${epic.description || ''}\n`;
+          fs.writeFileSync(epicDocPath, epicDoc, 'utf8');
+          this.debug(`Epic doc.md written: ${epicDoc.length} bytes`);
+        } catch (err) {
+          this.debug(`Epic doc generation failed for ${epic.id} — writing stub`, { error: err.message });
+          fs.writeFileSync(epicDocPath, `# ${epic.name}\n\n${epic.description || ''}\n`, 'utf8');
+        }
+      } else {
+        fs.writeFileSync(epicDocPath, `# ${epic.name}\n\n${epic.description || ''}\n`, 'utf8');
+      }
+
+      // Generate story doc.md files in parallel within this epic
+      await Promise.all((epic.stories || []).map(async (story) => {
+        const storyDir = path.join(epicDir, story.id);
+        const storyContextPath = path.join(storyDir, 'context.md');
+        const storyDocPath = path.join(storyDir, 'doc.md');
+
+        let storyContextMd = '';
+        if (fs.existsSync(storyContextPath)) {
+          storyContextMd = fs.readFileSync(storyContextPath, 'utf8');
+        } else {
+          storyContextMd = this.generateStoryContextMd(story, epic);
+        }
+
+        if (doGenerate) {
+          await progressCallback?.(null, `  Generating documentation → ${story.name}`, {});
+          this.debug(`Generating doc.md for story ${story.id}: ${story.name}`);
+          try {
+            const prompt = `## Project Documentation\n\n${rootDocContent}\n\n---\n\n## Parent Epic Canonical Specification\n\n${epicContextMd}\n\n---\n\n## Story Canonical Specification\n\n${storyContextMd}\n\nWrite the story's doc.md. Return JSON with a \`doc\` field.`;
+            const result = await this._withProgressHeartbeat(
+              () => this.retryWithBackoff(
+                () => provider.generateJSON(prompt, storyAgentInstructions),
+                `doc generation for story: ${story.name}`
+              ),
+              (elapsed) => {
+                if (elapsed < 15) return `Writing ${story.name} documentation…`;
+                if (elapsed < 40) return `Expanding ${story.name} narrative…`;
+                return `Still writing…`;
+              },
+              progressCallback,
+              10000
+            );
+            const storyDoc = (typeof result.doc === 'string' && result.doc.trim())
+              ? result.doc
+              : `# ${story.name}\n\n${story.description || ''}\n`;
+            fs.writeFileSync(storyDocPath, storyDoc, 'utf8');
+            this.debug(`Story doc.md written: ${storyDoc.length} bytes`);
+          } catch (err) {
+            this.debug(`Story doc generation failed for ${story.id} — writing stub`, { error: err.message });
+            fs.writeFileSync(storyDocPath, `# ${story.name}\n\n${story.description || ''}\n`, 'utf8');
+          }
+        } else {
+          fs.writeFileSync(storyDocPath, `# ${story.name}\n\n${story.description || ''}\n`, 'utf8');
+        }
+      }));
+    }));
+
+    const epicCount = hierarchy.epics.length;
+    const storyCount = hierarchy.epics.reduce((s, e) => s + (e.stories?.length || 0), 0);
+    this.debug(`Doc generation complete: ${epicCount} epics + ${storyCount} stories`);
+  }
+
+  // STAGE 5: Multi-Agent Validation
+  async validateHierarchy(hierarchy, progressCallback = null, scope = null) {
+    this.debugStage(5, 'Multi-Agent Validation');
+
+    // Initialize default LLM provider if not already done (for fallback)
+    if (!this.llmProvider) {
+      await this.initializeLLMProvider();
+    }
+
+    // Check if smart selection is enabled
+    const useSmartSelection = this.stagesConfig?.validation?.useSmartSelection || false;
+
+    if (useSmartSelection) {
+      this.debug('Smart validator selection enabled');
+    }
+
+    // Phase 1: Extract project context if contextual selection is enabled
+    const useContextualSelection = this.stagesConfig?.validation?.useContextualSelection || false;
+    this.debug(`Contextual agent selection: useContextualSelection=${useContextualSelection}, stagesConfig.validation=${JSON.stringify(this.stagesConfig?.validation)}`);
+    let projectContext = null;
+
+    if (useContextualSelection && scope) {
+      await progressCallback?.(null, 'Analyzing project context for agent selection…', {});
+      projectContext = await this.extractProjectContext(scope, progressCallback);
+      this._projectContext = projectContext;
+      this.debug('Project context extracted', projectContext);
+    } else if (useContextualSelection) {
+      this.debug('useContextualSelection=true but no scope available — skipping context extraction');
+    }
+
+    // Generate and write root context.md (canonical project representation)
+    let rootContextMd = null;
+    try {
+      let docMdContent = '';
+      if (fs.existsSync(this.projectDocPath)) {
+        docMdContent = fs.readFileSync(this.projectDocPath, 'utf8');
+      }
+      rootContextMd = this.generateRootContextMd(projectContext || {}, docMdContent, hierarchy);
+      const rootContextPath = path.join(this.projectPath, 'context.md');
+      fs.writeFileSync(rootContextPath, rootContextMd, 'utf8');
+      this.debug(`Root context.md written (${rootContextMd.length} bytes)`);
+    } catch (err) {
+      this.debug('Failed to write root context.md — continuing without it', { error: err.message });
+    }
+
+    // Store root context on this instance so LLM context writers can access it
+    this.rootContextMd = rootContextMd;
+
+    // Pre-generate LLM context.md for all epics and stories before validation
+    // This gives validators rich, complete context rather than sparse structured stubs
+    await progressCallback?.(null, 'Generating canonical context for epics and stories…', {});
+    const _tsCtx = Date.now();
+    await this.generateContextFiles(hierarchy, progressCallback);
+    this.debugTiming('generateContextFiles', _tsCtx);
+
+    // Generate scaffolding epic AFTER all domain contexts are written — it reads them
+    // to know the exact tech requirements (packages, infra, test frameworks, etc.)
+    try {
+      const _tsScaffold = Date.now();
+      await this._generateScaffoldingEpic(hierarchy, progressCallback);
+      this.debugTiming('generateScaffoldingEpic', _tsScaffold);
+    } catch (err) {
+      this.debug(`Scaffolding epic generation failed (non-critical): ${err.message}`);
+    }
+
+    const validator = new EpicStoryValidator(
+      this.llmProvider,
+      this.verificationTracker,
+      this.stagesConfig,
+      useSmartSelection,
+      progressCallback,
+      projectContext
+    );
+    this._validator = validator;
+    if (this._quotaExceededCallback) {
+      this._validator.setQuotaExceededCallback(this._quotaExceededCallback);
+    }
+    if (rootContextMd) this._validator.setRootContextMd(rootContextMd);
+    this._validator.setPromptLogger(this._promptLogger);
+    this._validator.setTokenCallback((delta, stageHint) => {
+      const key = stageHint
+        ? `${this.ceremonyName}-${stageHint}`
+        : this.ceremonyName;
+      this.tokenTracker.addIncremental(key, delta);
+      if (delta.model) {
+        const cost = this.tokenTracker.calculateCost(delta.input, delta.output, delta.model);
+        this._runningCost += cost?.total ?? 0;
+      }
+    });
+
+    // ── Validate epics with concurrency control ──────────────────────────────
+    // Each epic (+ its stories) is validated independently. We run up to
+    // EPIC_CONCURRENCY epics in parallel to reduce wall-clock time while
+    // respecting API rate limits. Stories within each epic remain sequential
+    // because split-story splice logic requires index stability.
+    const defaultConcurrency = 2;
+    const EPIC_CONCURRENCY = this.stagesConfig?.validation?.epicConcurrency ?? defaultConcurrency;
+
+    const validateSingleEpic = async (epic) => {
+      this.debug(`\nValidating Epic: ${epic.id} "${epic.name}"`);
+      await progressCallback?.(null, `Validating Epic: ${epic.name}`, {});
+
+      // Use LLM-generated context if available; fall back to structured format
+      const epicContext = this._epicContextCache.get(epic.name) || this.generateEpicContextMd(epic);
+
+      // Validate epic with multiple domain validators
+      const _tsEpic = Date.now();
+      const epicValidation = await validator.validateEpic(epic, epicContext);
+      this.debugTiming(`  validateEpic: ${epic.id} "${epic.name}"`, _tsEpic);
+
+      // Display validation summary
+      this.displayValidationSummary('Epic', epic.name, epicValidation);
+
+      // Handle validation result
+      if (epicValidation.overallStatus === 'needs-improvement') {
+        this.debug(`Epic "${epic.name}" needs improvement - showing issues`);
+        this.displayValidationIssues(epicValidation);
+      }
+
+      // Validate each story under this epic.
+      // Use index-based loop so split stories inserted via splice() are validated in-place.
+      // Keep in sync with STORY_AC_CAP in epic-story-validator.js
+      const STORY_AC_CAP = 20;
+      const MAX_SPLIT_DEPTH = 1;
+      let si = 0;
+      while (si < (epic.stories || []).length) {
+        const story = epic.stories[si];
+        const splitDepth = story._splitDepth || 0;
+
+        this.debug(`\nValidating Story: ${story.id} "${story.name}"`);
+        await progressCallback?.(null, `  Validating story: ${story.name}`, {});
+
+        // Use LLM-generated context if available; fall back to structured format
+        const storyContext = this._storyContextCache.get(`${epic.name}::${story.name}`) || this.generateStoryContextMd(story, epic);
+
+        // Validate story with multiple domain validators
+        const _tsStory = Date.now();
+        const storyValidation = await validator.validateStory(story, storyContext, epic);
+        this.debugTiming(`    validateStory: ${story.id} "${story.name}"`, _tsStory);
+
+        // Display validation summary
+        this.displayValidationSummary('Story', story.name, storyValidation);
+
+        // Handle validation result
+        if (storyValidation.overallStatus === 'needs-improvement') {
+          this.debug(`Story "${story.name}" needs improvement - showing issues`);
+          this.displayValidationIssues(storyValidation);
+        }
+
+        // ── Split detection ────────────────────────────────────────────────────────
+        // Trigger split when:
+        // (a) AC cap reached — story too large for solver to improve further, OR
+        // (b) SA issued a SPLIT RECOMMENDATION — story has too many concerns to resolve
+        //     by adding ACs regardless of current AC count
+        const acCount = (story.acceptance || []).length;
+
+        const splitRecommended = storyValidation._splitRecommended === true
+          || storyValidation.microCheckDetails?.splitRecommendation === true;
+        const shouldSplit =
+          storyValidation.overallStatus === 'needs-improvement' &&
+          (acCount >= STORY_AC_CAP || splitRecommended) &&
+          splitDepth < MAX_SPLIT_DEPTH;
+
+        if (shouldSplit) {
+          const allIssues = [
+            ...(storyValidation.criticalIssues || []),
+            ...(storyValidation.majorIssues || []),
+          ];
+
+          const splitReason = splitRecommended
+            ? `SA split recommendation (${acCount} ACs)`
+            : `too large (${acCount} ACs)`;
+          await progressCallback?.(null, `  Splitting story: ${story.name}`, {});
+          await validator._detail(`✂ [${story.id}] ${splitReason} — attempting split…`);
+          console.log(`   ✂ Splitting story "${story.name}" — ${splitReason}`);
+
+          const splitStories = await validator._splitStory(story, epic, allIssues);
+
+          if (splitStories) {
+            // Tag split stories with depth guard and parent reference (runtime-only, prefixed _)
+            for (const s of splitStories) {
+              s._splitDepth = splitDepth + 1;
+              s._splitFrom = story.id;
+            }
+
+            // Replace the original story with the split stories in-place
+            epic.stories.splice(si, 1, ...splitStories);
+
+            // Invalidate stale context cache entry for the original story name
+            this._storyContextCache.delete(`${epic.name}::${story.name}`);
+
+            // Pre-populate structured context for split stories so they don't start with nothing.
+            // This avoids an expensive LLM context-gen call for each split story — the structured
+            // fallback is sufficient since validators will refine the story content anyway.
+            for (const splitStory of splitStories) {
+              const splitKey = `${epic.name}::${splitStory.name}`;
+              if (!this._storyContextCache.has(splitKey)) {
+                this._storyContextCache.set(splitKey, this.generateStoryContextMd(splitStory, epic));
+              }
+            }
+
+            // Post-split dependency reconciliation: any story that depended on the
+            // original (now-removed) story ID should depend on the first split story instead.
+            const originalId = story.id;
+            const replacementId = splitStories[0]?.id;
+            if (originalId && replacementId) {
+              for (const e of hierarchy.epics) {
+                for (const s of e.stories || []) {
+                  if (Array.isArray(s.dependencies)) {
+                    const depIdx = s.dependencies.indexOf(originalId);
+                    if (depIdx !== -1 && !splitStories.some(sp => sp.id === s.id)) {
+                      s.dependencies[depIdx] = replacementId;
+                      this.debug(`Post-split dep remap: story "${s.name}" now depends on "${replacementId}" (was "${originalId}")`);
+                    }
+                  }
+                }
+              }
+            }
+
+            const names = splitStories.map(s => `"${s.name}"`).join(' + ');
+            await validator._detail(`✂ [${story.id}] split into ${splitStories.length}: ${names}`);
+            console.log(`   ✂ Split into ${splitStories.length} stories: ${names}`);
+
+            // Do NOT increment si — the loop re-enters at position si
+            // which now holds the first split story
+            continue;
+          } else {
+            console.log(`   ⚠ Split failed for "${story.name}" — keeping original story`);
+          }
+        }
+
+        si++;
+      }
+    };
+
+    // Run epics with concurrency limit
+    if (EPIC_CONCURRENCY <= 1 || hierarchy.epics.length <= 1) {
+      // Sequential fallback for local LLMs or single epic
+      for (const epic of hierarchy.epics) {
+        await validateSingleEpic(epic);
+      }
+    } else {
+      // Concurrency-limited parallel execution
+      const queue = [...hierarchy.epics];
+      const running = new Set();
+      let idx = 0;
+
+      while (idx < queue.length || running.size > 0) {
+        // Launch tasks up to concurrency limit
+        while (idx < queue.length && running.size < EPIC_CONCURRENCY) {
+          const epic = queue[idx++];
+          const promise = validateSingleEpic(epic).then(() => running.delete(promise));
+          running.add(promise);
+        }
+        // Wait for at least one to complete before launching more
+        if (running.size > 0) {
+          await Promise.race(running);
+        }
+      }
+    }
+
+    // Post-validation dependency cleanup — splits may have introduced broken references
+    this._validateDependencyReferences(hierarchy);
+
+    return hierarchy;
+  }
+
+  /**
+   * Display validation summary
+   */
+  displayValidationSummary(type, name, validation) {
+    const statusPrefix = {
+      'excellent': 'SUCCESS:',
+      'acceptable': 'WARNING:',
+      'needs-improvement': 'ERROR:'
+    };
+
+    const prefix = statusPrefix[validation.overallStatus] || '';
+    sendOutput(`${prefix} ${type}: ${name}\n`);
+    sendIndented(`Overall Score: ${validation.averageScore}/100`, 1);
+    const agentCount = validation.validatorCount ?? validation.validatorResults?.length ?? 0;
+    sendIndented(`Validators: ${agentCount} agents`, 1);
+    sendIndented(`Issues: ${validation.criticalIssues?.length || 0} critical, ${validation.majorIssues?.length || 0} major, ${validation.minorIssues?.length || 0} minor`, 1);
+
+    // Show strengths if excellent or acceptable
+    if (validation.overallStatus !== 'needs-improvement' && validation.strengths?.length > 0) {
+      sendIndented(`Strengths: ${validation.strengths.slice(0, 2).join(', ')}`, 1);
+    }
+
+    sendOutput('\n');
+  }
+
+  /**
+   * Display validation issues
+   */
+  displayValidationIssues(validation) {
+    // Show critical issues
+    if (validation.criticalIssues?.length > 0) {
+      this.debug('Critical Issues', validation.criticalIssues.slice(0, 3).map(issue => ({
+        domain: issue.domain,
+        description: issue.description,
+        suggestion: issue.suggestion
+      })));
+    }
+
+    // Show major issues (micro-check format)
+    if (validation.majorIssues?.length > 0) {
+      this.debug('Major Issues', validation.majorIssues.slice(0, 3).map(issue => ({
+        description: issue.description,
+        suggestion: issue.suggestion
+      })));
+    }
+
+    // Show improvement priorities (monolithic format, if present)
+    if (validation.improvementPriorities?.length > 0) {
+      this.debug('Improvement Priorities', validation.improvementPriorities.slice(0, 3).map((priority, i) => ({
+        rank: i + 1,
+        priority: priority.priority,
+        mentionedBy: priority.mentionedBy
+      })));
+    }
+  }
+
+  /**
+   * Analyze duplicate detection decisions
+   * Logs which epics/stories should have been skipped by LLM vs which are truly new
+   */
+  analyzeDuplicates(hierarchy, existingEpics, existingStories) {
+    this.debug('\n' + '='.repeat(80));
+    this.debug('DUPLICATE DETECTION ANALYSIS');
+    this.debug('='.repeat(80));
+
+    const skippedEpics = [];
+    const createdEpics = [];
+
+    // Analyze epics
+    for (const epic of hierarchy.epics || []) {
+      const normalized = epic.name.toLowerCase();
+      const isDuplicate = existingEpics.has(normalized);
+
+      this.debug(`\nEpic: "${epic.name}"`);
+      this.debug(`  Normalized: "${normalized}"`);
+      this.debug(`  Exists in previous runs: ${isDuplicate}`);
+
+      if (isDuplicate) {
+        const existingId = existingEpics.get(normalized);
+        this.debug(`  ⚠️  Match found: ${existingId}`);
+        this.debug(`  Action: SHOULD HAVE BEEN SKIPPED BY LLM`);
+        this.debug(`  Reason: LLM generated duplicate that already exists`);
+        skippedEpics.push({ name: epic.name, existingId });
+      } else {
+        // Check for potential semantic duplicates (similar names)
+        const similarEpics = [];
+        for (const [existingName, existingId] of existingEpics.entries()) {
+          // Simple similarity: check if one name contains the other
+          if (normalized.includes(existingName) || existingName.includes(normalized)) {
+            similarEpics.push({ name: existingName, id: existingId });
+          }
+        }
+
+        if (similarEpics.length > 0) {
+          this.debug(`  ⚠️  Possible semantic duplicates found:`);
+          for (const similar of similarEpics) {
+            this.debug(`     - "${similar.name}" (${similar.id})`);
+          }
+          this.debug(`  Action: CREATE NEW (but user should review for duplicates)`);
+        } else {
+          this.debug(`  ✓  Match found: NONE`);
+          this.debug(`  Action: CREATE NEW`);
+          this.debug(`  Reason: Genuinely new epic not in existing list`);
+        }
+        createdEpics.push(epic.name);
+      }
+    }
+
+    // Analyze stories
+    const skippedStories = [];
+    const createdStories = [];
+
+    for (const epic of hierarchy.epics || []) {
+      for (const story of epic.stories || []) {
+        const normalized = story.name.toLowerCase();
+        const isDuplicate = existingStories.has(normalized);
+
+        this.debug(`\nStory: "${story.name}" (under epic "${epic.name}")`);
+        this.debug(`  Normalized: "${normalized}"`);
+        this.debug(`  Exists in previous runs: ${isDuplicate}`);
+
+        if (isDuplicate) {
+          const existingId = existingStories.get(normalized);
+          this.debug(`  ⚠️  Match found: ${existingId}`);
+          this.debug(`  Action: SHOULD HAVE BEEN SKIPPED BY LLM`);
+          skippedStories.push({ name: story.name, existingId });
+        } else {
+          this.debug(`  ✓  Match found: NONE`);
+          this.debug(`  Action: CREATE NEW`);
+          createdStories.push(story.name);
+        }
+      }
+    }
+
+    // Summary
+    this.debug('\n' + '='.repeat(80));
+    this.debug('DUPLICATE ANALYSIS SUMMARY');
+    this.debug('='.repeat(80));
+    this.debug('Epics:', {
+      shouldBeSkipped: skippedEpics.length,
+      willCreate: createdEpics.length,
+      skippedNames: skippedEpics.map(s => s.name),
+      createdNames: createdEpics
+    });
+    this.debug('Stories:', {
+      shouldBeSkipped: skippedStories.length,
+      willCreate: createdStories.length,
+      skippedNames: skippedStories.map(s => s.name),
+      createdNames: createdStories
+    });
+
+    if (skippedEpics.length > 0 || skippedStories.length > 0) {
+      this.debug('\n⚠️  WARNING: LLM generated duplicates that should have been skipped!');
+      this.debug('This indicates LLM non-determinism or insufficient duplicate detection.');
+    } else {
+      this.debug('\n✓  Result: LLM correctly identified all items as duplicates or genuinely new');
+    }
+
+    this.debug('='.repeat(80) + '\n');
+
+    return { skippedEpics, createdEpics, skippedStories, createdStories };
+  }
+
+  // STAGE 6: Renumber IDs to avoid collisions
+  renumberHierarchy(hierarchy, maxEpicNum, maxStoryNums) {
+    this.debugStage(6, 'Renumber IDs');
+    this.debug('Renumbering hierarchy to avoid ID collisions...');
+
+    // Build old→new ID mapping for dependency remapping
+    const idMap = new Map();
+
+    let nextEpicNum = maxEpicNum.value + 1;
+    this.debug(`Next epic number: ${nextEpicNum} (after existing ${maxEpicNum.value})`);
+
+    for (const epic of hierarchy.epics) {
+      const oldEpicId = epic.id;
+      const newEpicId = `context-${String(nextEpicNum).padStart(4, '0')}`;
+      idMap.set(oldEpicId, newEpicId);
+      epic.id = newEpicId;
+
+      this.debug(`ID mapping - Epic "${epic.name}": ${oldEpicId} -> ${newEpicId}`);
+
+      let nextStoryNum = (maxStoryNums.get(newEpicId) || 0) + 1;
+
+      for (const story of epic.stories || []) {
+        const oldStoryId = story.id;
+        const newStoryId = `${newEpicId}-${String(nextStoryNum).padStart(4, '0')}`;
+        idMap.set(oldStoryId, newStoryId);
+        story.id = newStoryId;
+
+        this.debug(`ID mapping - Story "${story.name}": ${oldStoryId} -> ${newStoryId}`);
+        nextStoryNum++;
+      }
+
+      nextEpicNum++;
+    }
+
+    // Remap all dependency references using the old→new ID map
+    let remappedCount = 0;
+    for (const epic of hierarchy.epics) {
+      if (Array.isArray(epic.dependencies)) {
+        epic.dependencies = epic.dependencies.map(dep => {
+          const mapped = idMap.get(dep);
+          if (mapped) { remappedCount++; return mapped; }
+          return dep;
+        });
+      }
+      for (const story of epic.stories || []) {
+        if (Array.isArray(story.dependencies)) {
+          story.dependencies = story.dependencies.map(dep => {
+            const mapped = idMap.get(dep);
+            if (mapped) { remappedCount++; return mapped; }
+            return dep;
+          });
+        }
+      }
+    }
+
+    if (remappedCount > 0) {
+      this.debug(`Remapped ${remappedCount} dependency reference(s) to new IDs`);
+    }
+
+    this.debug('Renumbered hierarchy', {
+      epics: hierarchy.epics.map(e => ({ id: e.id, name: e.name, storyCount: e.stories?.length || 0 }))
+    });
+
+    return hierarchy;
+  }
+
+  // STAGE 7: Write hierarchy files with distributed documentation
+  async writeHierarchyFiles(hierarchy, progressCallback = null) {
+    this.debugStage(7, 'Write Hierarchy Files + Distribute Documentation');
+    this.debug('Writing hierarchy files with documentation distribution');
+
+    // Phase -1: Build name→id map and normalize all dependencies to IDs
+    const nameToId = {};
+    for (const epic of hierarchy.epics) {
+      nameToId[epic.name] = epic.id;
+      nameToId[epic.name.toLowerCase()] = epic.id;
+      for (const story of epic.stories || []) {
+        nameToId[story.name] = story.id;
+        nameToId[story.name.toLowerCase()] = story.id;
+      }
+    }
+    const normalizeDeps = (deps) => (deps || []).map(d => nameToId[d] || nameToId[d?.toLowerCase?.()] || d);
+    for (const epic of hierarchy.epics) {
+      epic.dependencies = normalizeDeps(epic.dependencies);
+      for (const story of epic.stories || []) {
+        story.dependencies = normalizeDeps(story.dependencies);
+      }
+    }
+
+    // Phase 0: Rename all provisional epic folders in REVERSE order to avoid collisions
+    // (e.g., 0001→0002 must happen after 0002→0003, not before)
+    const epicsToRename = hierarchy.epics
+      .filter(e => e._provisionalId && e._provisionalId !== e.id)
+      .reverse();
+    for (const epic of epicsToRename) {
+      const provisionalDir = path.join(this.projectPath, epic._provisionalId);
+      const targetDir = path.join(this.projectPath, epic.id);
+      if (fs.existsSync(provisionalDir) && !fs.existsSync(targetDir)) {
+        fs.renameSync(provisionalDir, targetDir);
+        this.debug(`Renamed provisional epic folder: ${epic._provisionalId} → ${epic.id}`);
+      }
+    }
+
+    // Phase 1 (sync): Create all directories, write work.json and context.md files
+    for (const epic of hierarchy.epics) {
+      const epicDir = path.join(this.projectPath, epic.id);
+      if (!fs.existsSync(epicDir)) fs.mkdirSync(epicDir, { recursive: true });
+
+      // Use LLM-generated context if cached; patch the id line since IDs may have changed after renumbering
+      let epicContextMd = this._epicContextCache.get(epic.name) || this.generateEpicContextMd(epic);
+      epicContextMd = epicContextMd.replace(/^(- id: ).+$/m, `$1${epic.id}`);
+      const epicContextPath = path.join(epicDir, 'context.md');
+      fs.writeFileSync(epicContextPath, epicContextMd, 'utf8');
+      this.debug(`Writing ${epicContextPath} (${epicContextMd.length} bytes)`);
+
+      const epicWorkJson = {
+        id: epic.id,
+        name: epic.name,
+        type: 'epic',
+        domain: epic.domain,
+        description: epic.description,
+        features: epic.features,
+        status: 'planned',
+        dependencies: epic.dependencies || [],
+        children: (epic.stories || []).map(s => s.id),
+        metadata: {
+          ...(epic.metadata || {}),
+          created: localISO(),
+          ceremony: this.ceremonyName
+        }
+      };
+      const workJsonPath = path.join(epicDir, 'work.json');
+      const workJsonContent = JSON.stringify(epicWorkJson, null, 2);
+      fs.writeFileSync(workJsonPath, workJsonContent, 'utf8');
+      this.debug(`Writing ${workJsonPath} (${workJsonContent.length} bytes)`);
+      await this._itemWrittenCallback?.({ itemId: epic.id, itemType: 'epic' });
+
+      // Rename provisional story folders in reverse order to avoid collisions
+      // (e.g., 0001b→0002 must happen after 0002→0003, not before)
+      const storiesToRename = (epic.stories || [])
+        .filter(s => s._provisionalId && s._provisionalId !== s.id)
+        .reverse();
+      for (const story of storiesToRename) {
+        const provisionalStoryDir = path.join(epicDir, story._provisionalId);
+        const targetDir = path.join(epicDir, story.id);
+        if (fs.existsSync(provisionalStoryDir) && !fs.existsSync(targetDir)) {
+          fs.renameSync(provisionalStoryDir, targetDir);
+          this.debug(`Renamed provisional story folder: ${story._provisionalId} → ${story.id}`);
+        }
+      }
+
+      for (const story of epic.stories || []) {
+        const storyDir = path.join(epicDir, story.id);
+        if (!fs.existsSync(storyDir)) fs.mkdirSync(storyDir, { recursive: true });
+
+        // Use LLM-generated context if cached; patch id and epic-ref lines after renumbering
+        let storyContextMd = this._storyContextCache.get(`${epic.name}::${story.name}`) || this.generateStoryContextMd(story, epic);
+        storyContextMd = storyContextMd.replace(/^(- id: ).+$/m, `$1${story.id}`);
+        storyContextMd = storyContextMd.replace(/^(- epic: ).+$/m, `$1${epic.id} (${epic.name})`);
+        const storyContextPath = path.join(storyDir, 'context.md');
+        fs.writeFileSync(storyContextPath, storyContextMd, 'utf8');
+        this.debug(`Writing ${storyContextPath} (${storyContextMd.length} bytes)`);
+
+        const storyWorkJson = {
+          id: story.id,
+          name: story.name,
+          type: 'story',
+          userType: story.userType,
+          description: story.description,
+          acceptance: story.acceptance,
+          status: 'planned',
+          dependencies: story.dependencies || [],
+          children: [],
+          metadata: {
+            ...(story.metadata || {}),
+            created: localISO(),
+            ceremony: this.ceremonyName
+          }
+        };
+        const storyWorkJsonPath = path.join(storyDir, 'work.json');
+        const storyWorkJsonContent = JSON.stringify(storyWorkJson, null, 2);
+        fs.writeFileSync(storyWorkJsonPath, storyWorkJsonContent, 'utf8');
+        this.debug(`Writing ${storyWorkJsonPath} (${storyWorkJsonContent.length} bytes)`);
+        await this._itemWrittenCallback?.({ itemId: story.id, itemType: 'story' });
+      }
+    }
+
+    // Set dependency-ready items to 'ready' status instead of 'planned'.
+    // Items whose dependencies are all within this run (and thus all "planned") are ready
+    // if those dependencies have no external blockers. Phase 1 epics/stories with no
+    // dependencies are always ready. Others stay 'planned' until their deps are completed.
+    try {
+      const { checkDependenciesReady } = await import('./dependency-checker.js');
+
+      // Build lookup of all items in this hierarchy
+      const lookup = {};
+      for (const epic of hierarchy.epics) {
+        lookup[epic.id] = {
+          id: epic.id, name: epic.name, type: 'epic',
+          status: 'planned', dependencies: epic.dependencies || [],
+        };
+        for (const story of epic.stories || []) {
+          lookup[story.id] = {
+            id: story.id, name: story.name, type: 'story',
+            status: 'planned', dependencies: story.dependencies || [],
+          };
+        }
+      }
+
+      // Items with no dependencies (or all deps are outside this hierarchy and assumed done) → ready
+      let readyCount = 0;
+      for (const epic of hierarchy.epics) {
+        const epicDeps = (epic.dependencies || []).filter(d => lookup[d]);
+        if (epicDeps.length === 0) {
+          // Epic has no deps within this hierarchy → ready
+          this._setWorkJsonStatus(path.join(this.projectPath, epic.id, 'work.json'), 'ready');
+          lookup[epic.id].status = 'ready';
+          readyCount++;
+
+          // Its stories with no deps (or deps only on this now-ready epic) → ready
+          for (const story of epic.stories || []) {
+            const storyResult = checkDependenciesReady(story.id, lookup);
+            if (storyResult.ready) {
+              this._setWorkJsonStatus(path.join(this.projectPath, epic.id, story.id, 'work.json'), 'ready');
+              lookup[story.id].status = 'ready';
+              readyCount++;
+            }
+          }
+        }
+      }
+      this.debug(`Set ${readyCount} items to 'ready' status (dependency-free)`);
+    } catch (err) {
+      this.debug(`Failed to compute ready status (non-critical): ${err.message}`);
+    }
+
+    // Phase 2 (doc.md): Handled by generateDocFiles() called after this method.
+    // context.md files written in Phase 1 are the canonical source for doc generation.
+
+    const epicCount = hierarchy.epics.length;
+    const storyCount = hierarchy.epics.reduce((sum, epic) => sum + (epic.stories || []).length, 0);
+
+    // Log all files written this run for cross-run comparison
+    this.debugSection('FILES WRITTEN THIS RUN (Phase 1 — work.json + context.md)');
+    const filesWritten = [];
+    filesWritten.push('context.md');
+    for (const epic of hierarchy.epics) {
+      filesWritten.push(`${epic.id}/work.json`);
+      filesWritten.push(`${epic.id}/context.md`);
+      for (const story of epic.stories || []) {
+        filesWritten.push(`${epic.id}/${story.id}/work.json`);
+        filesWritten.push(`${epic.id}/${story.id}/context.md`);
+      }
+    }
+    this.debug('Files written this run (Phase 1)', filesWritten);
+    this.debug(`Total files written: ${filesWritten.length} (${epicCount} epics x 2 + ${storyCount} stories x 2)`);
+
+    // Display clean summary of created epics and stories
+    if (hierarchy.epics.length > 0) {
+      for (const epic of hierarchy.epics) {
+        sendOutput(`${epic.id}: ${epic.name}\n`);
+        for (const story of epic.stories || []) {
+          sendIndented(`${story.id}: ${story.name}`, 1);
+        }
+        sendOutput('\n');
+      }
+    }
+
+    return { epicCount, storyCount };
+  }
+
+  /**
+   * Stage 7: Enrich story doc.md files with implementation-specific detail.
+   *
+   * After doc distribution, story docs may still have vague acceptance criteria
+   * that lack concrete API contracts, error tables, DB field names, and business rules.
+   * This stage runs the story-doc-enricher agent on each story doc to fill those gaps.
+   *
+   * @param {Object} hierarchy - Hierarchy with epics and stories (post-renumbering, with real IDs)
+   * @param {Function} progressCallback - Optional progress callback
+   */
+  async enrichStoryDocs(hierarchy, progressCallback = null) {
+    this.debugStage(8, 'Enrich Story Docs with Implementation Detail');
+
+    const agentInstructions = loadAgent('story-doc-enricher.md');
+    const provider = await this.getProviderForStageInstance('enrichment');
+    const { model: modelName } = this.getProviderForStage('enrichment');
+
+    this.debug(`Using model for enrichment: ${modelName}`);
+
+    // Collect all story tasks and run all enrichments in parallel
+    const tasks = hierarchy.epics.flatMap(epic =>
+      (epic.stories || []).map(story => ({ epic, story }))
+    );
+
+    const results = await Promise.all(tasks.map(async ({ epic, story }) => {
+      const storyDir = path.join(this.projectPath, epic.id, story.id);
+      const storyDocPath = path.join(storyDir, 'doc.md');
+
+      if (!fs.existsSync(storyDocPath)) {
+        this.debug(`Skipping enrichment for ${story.id} — doc.md not found`);
+        return 'skipped';
+      }
+
+      const storyDocContent = fs.readFileSync(storyDocPath, 'utf8');
+      const acceptance = (story.acceptance || []).map((a, i) => `${i + 1}. ${a}`).join('\n') || 'none specified';
+      const prompt = `## Existing Story Doc
+
+${storyDocContent}
+
+---
+
+## Story Work Item
+
+**Name:** ${story.name}
+**User Type:** ${story.userType || 'team member'}
+**Description:** ${story.description || ''}
+**Acceptance Criteria:**
+${acceptance}
+
+---
+
+## Parent Epic Context
+
+**Epic:** ${epic.name}
+**Domain:** ${epic.domain || 'general'}
+**Description:** ${epic.description || ''}
+
+---
+
+Enrich the existing story doc to be fully implementation-ready. Fill any gaps in API contracts, error tables, data model fields, business rules, and authorization. Return JSON with \`enriched_doc\` and \`gaps_filled\` fields.`;
+
+      this.debug(`Enriching story doc: ${story.id} (${story.name})`);
+      await progressCallback?.(null, `  Enriching documentation → ${story.name}`, {});
+
+      const _tsEnrich = Date.now();
+      try {
+        const result = await this._withProgressHeartbeat(
+          () => this.retryWithBackoff(
+            () => provider.generateJSON(prompt, agentInstructions),
+            `enrichment for story: ${story.name}`
+          ),
+          (elapsed) => {
+            if (elapsed < 15) return `Enriching ${story.name}…`;
+            if (elapsed < 40) return `Adding implementation detail to ${story.name}…`;
+            return `Still enriching…`;
+          },
+          progressCallback,
+          10000
+        );
+
+        const enrichedDoc = (typeof result.enriched_doc === 'string' && result.enriched_doc.trim())
+          ? result.enriched_doc
+          : storyDocContent;
+
+        const gapsFilled = Array.isArray(result.gaps_filled) ? result.gaps_filled : [];
+
+        fs.writeFileSync(storyDocPath, enrichedDoc, 'utf8');
+
+        this.debugTiming(`    enrichStory: ${story.id} "${story.name}"`, _tsEnrich);
+        if (gapsFilled.length > 0) {
+          this.debug(`Story ${story.id} enriched: ${gapsFilled.length} gaps filled`, gapsFilled);
+        } else {
+          this.debug(`Story ${story.id}: already implementation-ready, no gaps filled`);
+        }
+        return 'enriched';
+      } catch (err) {
+        this.debugTiming(`    enrichStory FAILED: ${story.id} "${story.name}"`, _tsEnrich);
+        this.debug(`Story enrichment failed for ${story.id} — keeping original doc`, { error: err.message });
+        return 'skipped';
+      }
+    }));
+
+    const enrichedCount = results.filter(r => r === 'enriched').length;
+    const skippedCount = results.filter(r => r === 'skipped').length;
+    this.debug(`Story enrichment complete: ${enrichedCount} enriched, ${skippedCount} skipped`);
+  }
+
+  /**
+   * Distribute documentation content from a parent doc.md to a child item's doc.md.
+   *
+   * Calls the doc-distributor LLM agent which extracts content specifically about
+   * the child from the parent document, builds the child's doc.md with the extracted
+   * content plus elaboration, and returns the parent document with that content removed.
+   *
+   * @param {string} parentDocContent - Current content of the parent doc.md
+   * @param {Object} childItem - Epic or story object from decomposition result
+   * @param {'epic'|'story'} childType - Whether the child is an epic or story
+   * @param {Function} progressCallback - Optional progress callback
+   * @returns {Promise<{childDoc: string, parentDoc: string}>}
+   */
+  async distributeDocContent(parentDocContent, childItem, childType, progressCallback = null) {
+    this.debugSection(`DOC DISTRIBUTION: ${childType.toUpperCase()} "${childItem.name}"`);
+
+    const agentPath = path.join(this.agentsPath, 'doc-distributor.md');
+    this.debug(`Loading doc-distributor agent: ${agentPath}`);
+    const agentInstructions = fs.readFileSync(agentPath, 'utf8');
+
+    // Build child item description for the prompt
+    let itemDescription;
+    if (childType === 'epic') {
+      const features = (childItem.features || []).join(', ') || 'none specified';
+      const stories = (childItem.stories || []).map(s => `- ${s.name}: ${s.description || ''}`).join('\n') || 'none yet';
+      itemDescription = `Type: epic
+Name: ${childItem.name}
+Domain: ${childItem.domain || 'general'}
+Description: ${childItem.description || ''}
+Features: ${features}
+Stories that will belong to this epic:
+${stories}`;
+    } else {
+      const acceptance = (childItem.acceptance || []).map(a => `- ${a}`).join('\n') || 'none specified';
+      itemDescription = `Type: story
+Name: ${childItem.name}
+User type: ${childItem.userType || 'team member'}
+Description: ${childItem.description || ''}
+Acceptance criteria:
+${acceptance}`;
+    }
+
+    const prompt = `## Parent Document
+
+${parentDocContent}
+
+---
+
+## Child Item to Create Documentation For
+
+${itemDescription}
+
+---
+
+Extract and synthesize content from the parent document that is specifically relevant to this ${childType}, then compose the child's \`doc.md\`. Return JSON with a \`child_doc\` field.`;
+
+    this.debug(`Prompt length: ${prompt.length} chars (parent: ${parentDocContent.length}, item: ${itemDescription.length})`);
+
+    const provider = await this.getProviderForStageInstance('doc-distribution');
+
+    const result = await this._withProgressHeartbeat(
+      () => this.retryWithBackoff(
+        () => provider.generateJSON(prompt, agentInstructions),
+        `doc distribution for ${childType}: ${childItem.name}`
+      ),
+      (elapsed) => {
+        if (elapsed < 15) return `Extracting ${childType}-specific content…`;
+        if (elapsed < 40) return `Building ${childItem.name} documentation…`;
+        if (elapsed < 65) return `Refining parent document…`;
+        return `Still distributing…`;
+      },
+      progressCallback,
+      10000
+    );
+
+    const usage = provider.getTokenUsage();
+    this.debug(`Doc distribution tokens: ${usage.inputTokens} in · ${usage.outputTokens} out`);
+
+    // Validate response shape and fall back gracefully on malformed output
+    const childDoc = (typeof result.child_doc === 'string' && result.child_doc.trim())
+      ? result.child_doc
+      : `# ${childItem.name}\n\n${childItem.description || ''}\n`;
+
+    this.debug(`Distribution result: child_doc ${childDoc.length} bytes`);
+
+    return { childDoc };
+  }
+
+  // Count total hierarchy (nested structure)
+  countTotalHierarchy() {
+    let totalEpics = 0;
+    let totalStories = 0;
+
+    if (!fs.existsSync(this.projectPath)) {
+      return { totalEpics, totalStories };
+    }
+
+    const dirs = fs.readdirSync(this.projectPath);
+
+    // Scan top-level directories (epics)
+    for (const dir of dirs) {
+      const epicWorkJsonPath = path.join(this.projectPath, dir, 'work.json');
+
+      if (!fs.existsSync(epicWorkJsonPath)) continue;
+
+      try {
+        const work = JSON.parse(fs.readFileSync(epicWorkJsonPath, 'utf8'));
+
+        if (work.type === 'epic') {
+          totalEpics++;
+
+          // Count nested stories under this epic
+          const epicDir = path.join(this.projectPath, dir);
+          const epicSubdirs = fs.readdirSync(epicDir).filter(subdir => {
+            const subdirPath = path.join(epicDir, subdir);
+            return fs.statSync(subdirPath).isDirectory();
+          });
+
+          for (const storyDir of epicSubdirs) {
+            const storyWorkJsonPath = path.join(epicDir, storyDir, 'work.json');
+
+            if (!fs.existsSync(storyWorkJsonPath)) continue;
+
+            try {
+              const storyWork = JSON.parse(fs.readFileSync(storyWorkJsonPath, 'utf8'));
+              if (storyWork.type === 'story') {
+                totalStories++;
+              }
+            } catch (error) {
+              // Ignore parse errors
+            }
+          }
+        }
+      } catch (error) {
+        // Ignore parse errors
+      }
+    }
+
+    return { totalEpics, totalStories };
+  }
+
+  /**
+   * Read the full on-disk hierarchy after writing files.
+   * Returns the same shape as preRunSnapshot for direct comparison.
+   */
+  readPostRunSnapshot() {
+    if (!fs.existsSync(this.projectPath)) return [];
+
+    const snapshot = [];
+    const dirs = fs.readdirSync(this.projectPath).sort();
+
+    for (const dir of dirs) {
+      const epicWorkJsonPath = path.join(this.projectPath, dir, 'work.json');
+      if (!fs.existsSync(epicWorkJsonPath)) continue;
+
+      try {
+        const work = JSON.parse(fs.readFileSync(epicWorkJsonPath, 'utf8'));
+        if (work.type !== 'epic') continue;
+
+        const epicEntry = {
+          id: work.id,
+          name: work.name,
+          domain: work.domain || '',
+          status: work.status || 'unknown',
+          created: work.metadata?.created || null,
+          ceremony: work.metadata?.ceremony || null,
+          stories: []
+        };
+
+        const epicDir = path.join(this.projectPath, dir);
+        const epicSubdirs = fs.readdirSync(epicDir).filter(subdir =>
+          fs.statSync(path.join(epicDir, subdir)).isDirectory()
+        ).sort();
+
+        for (const storyDir of epicSubdirs) {
+          const storyWorkJsonPath = path.join(epicDir, storyDir, 'work.json');
+          if (!fs.existsSync(storyWorkJsonPath)) continue;
+          try {
+            const storyWork = JSON.parse(fs.readFileSync(storyWorkJsonPath, 'utf8'));
+            if (storyWork.type === 'story') {
+              epicEntry.stories.push({
+                id: storyWork.id,
+                name: storyWork.name,
+                status: storyWork.status || 'unknown',
+                created: storyWork.metadata?.created || null
+              });
+            }
+          } catch (e) { /* ignore */ }
+        }
+
+        snapshot.push(epicEntry);
+      } catch (e) { /* ignore */ }
+    }
+
+    return snapshot;
+  }
+
+  /**
+   * Rebuild the hierarchy object from work.json files on disk.
+   * Used by resume mode to skip stages 1-6 and jump straight to doc/enrichment stages.
+   * @returns {{ hierarchy: object, epicCount: number, storyCount: number }}
+   */
+  _rebuildHierarchyFromDisk() {
+    this.debugStage('R', 'Rebuild Hierarchy From Disk (Resume Mode)');
+
+    const epics = [];
+    if (!fs.existsSync(this.projectPath)) {
+      throw new Error('No project directory found — cannot resume');
+    }
+
+    const dirs = fs.readdirSync(this.projectPath).filter(d =>
+      d.startsWith('context-') && fs.existsSync(path.join(this.projectPath, d, 'work.json'))
+    ).sort();
+
+    let storyCount = 0;
+    for (const dir of dirs) {
+      const epicWorkPath = path.join(this.projectPath, dir, 'work.json');
+      const epicWork = JSON.parse(fs.readFileSync(epicWorkPath, 'utf8'));
+
+      const epicEntry = {
+        id: epicWork.id,
+        name: epicWork.name,
+        description: epicWork.description || '',
+        domain: epicWork.domain || '',
+        acceptanceCriteria: epicWork.acceptanceCriteria || [],
+        dependencies: epicWork.dependencies || [],
+        metadata: epicWork.metadata || {},
+        stories: [],
+      };
+
+      // Read cached context.md for this epic (used by doc generation)
+      const epicCtxPath = path.join(this.projectPath, dir, 'context.md');
+      if (fs.existsSync(epicCtxPath)) {
+        this._epicContextCache.set(epicWork.name, fs.readFileSync(epicCtxPath, 'utf8'));
+      }
+
+      // Scan story subdirectories
+      const epicDir = path.join(this.projectPath, dir);
+      const storyDirs = fs.readdirSync(epicDir).filter(sd => {
+        const sdPath = path.join(epicDir, sd);
+        return fs.statSync(sdPath).isDirectory() && fs.existsSync(path.join(sdPath, 'work.json'));
+      }).sort();
+
+      for (const sd of storyDirs) {
+        const storyWorkPath = path.join(epicDir, sd, 'work.json');
+        const storyWork = JSON.parse(fs.readFileSync(storyWorkPath, 'utf8'));
+
+        epicEntry.stories.push({
+          id: storyWork.id,
+          name: storyWork.name,
+          description: storyWork.description || '',
+          acceptanceCriteria: storyWork.acceptanceCriteria || [],
+          dependencies: storyWork.dependencies || [],
+          metadata: storyWork.metadata || {},
+        });
+
+        // Read cached story context.md
+        const storyCtxPath = path.join(epicDir, sd, 'context.md');
+        if (fs.existsSync(storyCtxPath)) {
+          this._storyContextCache.set(`${epicWork.name}::${storyWork.name}`, fs.readFileSync(storyCtxPath, 'utf8'));
+        }
+
+        storyCount++;
+      }
+
+      epics.push(epicEntry);
+    }
+
+    const hierarchy = { epics, validation: null };
+    this.debug(`Rebuilt hierarchy from disk: ${epics.length} epics, ${storyCount} stories`);
+    return { hierarchy, epicCount: epics.length, storyCount };
+  }
+
+  // Main execution method
+  async execute(progressCallback = null, { resumeFrom = null } = {}) {
+    // Cost threshold protection — wrap callback to check running cost before each progress call
+    if (this._costThreshold != null && progressCallback) {
+      const _origCallback = progressCallback;
+      progressCallback = async (...args) => {
+        if (this._costThreshold != null && this._runningCost >= this._costThreshold) {
+          if (this._costLimitReachedCallback) {
+            this._costThreshold = null; // disable re-triggering
+            await this._costLimitReachedCallback(this._runningCost);
+            // returns → ceremony continues with limit disabled
+          } else {
+            throw new Error(`COST_LIMIT_EXCEEDED:${this._runningCost.toFixed(6)}`);
+          }
+        }
+        return _origCallback(...args);
+      };
+    }
+
+    // Initialize ceremony history
+    const { CeremonyHistory } = await import('./ceremony-history.js');
+    const history = new CeremonyHistory(this.avcPath);
+    history.init();
+
+    // Start execution tracking
+    const executionId = history.startExecution('sprint-planning', 'decomposition');
+
+    // Stage checkpoint helper — updates ceremony history with current stage.
+    // Non-fatal: never throws.
+    const checkpoint = (stage) => {
+      try { history.updateExecution('sprint-planning', executionId, { stage, lastCheckpoint: localISO() }); }
+      catch {}
+    };
+
+    try {
+      // Log ceremony execution metadata
+      const runId = Date.now();
+      const runTimestamp = localISO();
+      this.debug('='.repeat(80));
+      this.debug('SPRINT PLANNING CEREMONY - EXECUTION START');
+      this.debug('='.repeat(80));
+      this.debug('Run ID (ms epoch):', runId);
+      this.debug('Timestamp:', runTimestamp);
+      this.debug('Execution ID:', executionId);
+      this.debug('Config', {
+        provider: this._providerName,
+        model: this._modelName,
+        stagesConfig: this.stagesConfig ? JSON.stringify(this.stagesConfig) : 'using defaults',
+        projectPath: this.projectPath,
+        cwd: process.cwd(),
+        nodeVersion: process.version
+      });
+
+      const header = getCeremonyHeader('sprint-planning');
+      sendCeremonyHeader(header.title);
+
+      const _t0run = Date.now();
+
+      // ── Resume fast-path ─────────────────────────────────────────────
+      // When resumeFrom is set, skip stages 1-6 and jump directly to the
+      // doc-generation / enrichment stages using hierarchy rebuilt from disk.
+      if (resumeFrom) {
+        this.debug(`RESUME MODE — resuming from checkpoint: ${resumeFrom}`);
+        await progressCallback?.(`Resuming from ${resumeFrom}…`);
+
+        const { hierarchy, epicCount, storyCount } = this._rebuildHierarchyFromDisk();
+
+        let rootDocContent = '';
+        if (fs.existsSync(this.projectDocPath)) {
+          rootDocContent = fs.readFileSync(this.projectDocPath, 'utf8');
+        }
+
+        if (resumeFrom === 'files-written') {
+          // Run stages 7, 8, 9
+          sendProgress('Generating documentation from canonical context...');
+          await progressCallback?.(`Stage 7/8: Generating documentation (${epicCount} epics, ${storyCount} stories)…`);
+          await this.generateDocFiles(hierarchy, rootDocContent, progressCallback);
+          checkpoint('docs-generated');
+
+          sendProgress('Enriching story documentation with implementation detail...');
+          await progressCallback?.(`Stage 8/8: Enriching story documentation (${storyCount} stories)…`);
+          await this.enrichStoryDocs(hierarchy, progressCallback);
+          checkpoint('enrichment-complete');
+        } else if (resumeFrom === 'docs-generated') {
+          // Run stages 8, 9
+          sendProgress('Enriching story documentation with implementation detail...');
+          await progressCallback?.(`Stage 8/8: Enriching story documentation (${storyCount} stories)…`);
+          await this.enrichStoryDocs(hierarchy, progressCallback);
+          checkpoint('enrichment-complete');
+        }
+        // 'enrichment-complete' → only summary (stage 9)
+
+        // Stage 9: Summary
+        const { totalEpics, totalStories } = this.countTotalHierarchy();
+        const returnResult = {
+          epicsCreated: epicCount,
+          storiesCreated: storyCount,
+          totalEpics,
+          totalStories,
+          tokenUsage: { input: 0, output: 0, total: 0 },
+          model: this._modelName,
+          provider: this._providerName,
+          validationIssues: [],
+          resumed: true,
+          resumedFrom: resumeFrom,
+        };
+
+        try {
+          const aggregated = this._aggregateAllTokenUsage();
+          if (aggregated.totalCalls > 0 || aggregated.inputTokens > 0) {
+            this.tokenTracker.finalizeRun(this.ceremonyName);
+            returnResult.tokenUsage = {
+              input: aggregated.inputTokens || 0,
+              output: aggregated.outputTokens || 0,
+              total: aggregated.totalTokens || 0,
+            };
+          }
+        } catch {}
+
+        try {
+          history.completeExecution('sprint-planning', executionId, 'success', {
+            stage: 'completed',
+            resumed: true,
+            resumedFrom: resumeFrom,
+            metrics: { epicsCreated: epicCount, storiesCreated: storyCount, totalEpics, totalStories }
+          });
+        } catch {}
+
+        sendOutput(`Resume complete — ${totalEpics} Epics, ${totalStories} Stories.`);
+        this.debugTiming('TOTAL resume end-to-end', _t0run);
+        return returnResult;
+      }
+      // ── End resume fast-path ─────────────────────────────────────────
+
+      // Stage 1: Validate
+      sendProgress('Validating prerequisites...');
+      await progressCallback?.('Stage 1/6: Validating prerequisites…');
+      let _ts = Date.now();
+      this.validatePrerequisites();
+      this.debugTiming('Stage 1 — validatePrerequisites', _ts);
+
+      // Stage 2: Read existing hierarchy
+      sendProgress('Analyzing existing project structure...');
+      await progressCallback?.('Stage 2/6: Analyzing existing project structure…');
+      _ts = Date.now();
+      const { existingEpics, existingStories, maxEpicNum, maxStoryNums, preRunSnapshot } = this.readExistingHierarchy();
+      this.debugTiming('Stage 2 — readExistingHierarchy', _ts);
+
+      if (existingEpics.size > 0) {
+        this.debug(`Found ${existingEpics.size} existing Epics, ${existingStories.size} existing Stories`);
+        sendInfo(`Found ${existingEpics.size} existing Epics, ${existingStories.size} existing Stories`);
+      } else {
+        this.debug('No existing Epics/Stories found (first expansion)');
+      }
+
+      // Stage 3: Collect scope
+      sendProgress('Collecting project scope...');
+      await progressCallback?.('Stage 3/6: Collecting project scope…');
+      _ts = Date.now();
+      const scope = await this.collectNewScope();
+      this.debugTiming('Stage 3 — collectNewScope', _ts);
+
+      // Clear screen before decomposition phase
+      process.stdout.write('\x1bc');
+      outputBuffer.clear();
+
+      // Stage 4: Decompose
+      sendProgress('Decomposing scope into Epics and Stories...');
+      await progressCallback?.('Stage 4/6: Decomposing scope into Epics and Stories…');
+      _ts = Date.now();
+      let hierarchy = await this.decomposeIntoEpicsStories(scope, existingEpics, existingStories, progressCallback);
+
+      // Quality gate: retry decomposition if structural issues detected
+      const maxDecompRetries = 3;
+      for (let retry = 1; retry <= maxDecompRetries; retry++) {
+        const issues = this._checkDecompositionQuality(hierarchy);
+        if (issues.length === 0) break;
+
+        if (retry === maxDecompRetries) {
+          this.debug(`Decomposition quality issues persist after ${maxDecompRetries} retries — proceeding with warnings`, { issues });
+          break;
+        }
+
+        this.debug(`Decomposition quality gate failed (attempt ${retry}/${maxDecompRetries})`, { issues });
+        await progressCallback?.(`Decomposition has ${issues.length} issue(s) — retrying (${retry}/${maxDecompRetries})…`);
+
+        // Retry with violation feedback
+        hierarchy = await this.decomposeIntoEpicsStories(scope, existingEpics, existingStories, progressCallback, issues);
+      }
+
+      this.debugTiming('Stage 4 — decomposeIntoEpicsStories', _ts);
+      checkpoint('decomposition-complete');
+
+      // Log raw LLM output before any validation/modification
+      this.debugSection('POST-DECOMPOSE: Raw LLM Output (before validation)');
+      this.debugHierarchySnapshot('POST-DECOMPOSE', hierarchy.epics.map(e => ({
+        id: e.id || '(no-id)',
+        name: e.name,
+        stories: (e.stories || []).map(s => ({ id: s.id || '(no-id)', name: s.name }))
+      })));
+      this.debug('LLM validation field', hierarchy.validation || null);
+
+      // NOTE: Scaffolding epic is generated AFTER context generation (in validateHierarchy)
+      // so it can read tech requirements from all domain epic/story contexts.
+      // Dependency injection happens inside _generateScaffoldingEpic().
+
+      // Stage 4.1: LLM-based duplicate detection
+      sendProgress('Detecting duplicate epics and stories...');
+      await progressCallback?.('Stage 4.1/8: Detecting duplicates…');
+      _ts = Date.now();
+      hierarchy = await this.deduplicateEpicsLLM(hierarchy, preRunSnapshot, progressCallback);
+      this.debugTiming('Stage 4.1 — deduplicateEpicsLLM', _ts);
+
+      // Log post-dedup snapshot
+      this.debugSection('POST-DEDUP: Hierarchy after duplicate detection');
+      this.debugHierarchySnapshot('POST-DEDUP', hierarchy.epics.map(e => ({
+        id: e.id || '(no-id)',
+        name: e.name,
+        stories: (e.stories || []).map(s => ({ id: s.id || '(no-id)', name: s.name }))
+      })));
+
+      // Stage 4.2: Review and split wide stories
+      sendProgress('Reviewing story scopes for splits...');
+      await progressCallback?.('Stage 4.2/8: Reviewing story scopes for required splits…');
+      _ts = Date.now();
+      hierarchy = await this.reviewAndSplitStories(hierarchy, progressCallback);
+      this.debugTiming('Stage 4.2 — reviewAndSplitStories', _ts);
+
+      // Log post-split snapshot
+      this.debugSection('POST-SPLIT: Hierarchy after story scope review');
+      this.debugHierarchySnapshot('POST-SPLIT', hierarchy.epics.map(e => ({
+        id: e.id || '(no-id)',
+        name: e.name,
+        stories: (e.stories || []).map(s => ({ id: s.id || '(no-id)', name: s.name }))
+      })));
+
+      // Stage 4.5: User selection gate (Kanban UI only; null = run straight through)
+      if (this._selectionCallback) {
+        await progressCallback?.('Stage 4.5/6: Waiting for epic/story selection…');
+        const selection = await this._selectionCallback(hierarchy);
+        if (selection) {
+          const { selectedEpicIds, selectedStoryIds } = selection;
+          hierarchy = this._filterHierarchyBySelection(hierarchy, selectedEpicIds, selectedStoryIds);
+          const epicCount = hierarchy.epics.length;
+          const storyCount = hierarchy.epics.reduce((s, e) => s + (e.stories?.length || 0), 0);
+          this.debug(`Selection applied: ${epicCount} epics, ${storyCount} stories selected`);
+          await progressCallback?.(null, `Confirmed: ${epicCount} epics, ${storyCount} stories selected`, {});
+        }
+      }
+
+      // Clear screen before validation phase
+      process.stdout.write('\x1bc');
+      outputBuffer.clear();
+
+      // Stage 5: Multi-Agent Validation
+      const epicCount5 = hierarchy.epics.length;
+      const storyCount5 = hierarchy.epics.reduce((s, e) => s + (e.stories?.length || 0), 0);
+      sendProgress('Validating Epics and Stories with domain experts...');
+      await progressCallback?.(`Stage 5/6: Validating with domain experts (${epicCount5} epics, ${storyCount5} stories)…`);
+      _ts = Date.now();
+      hierarchy = await this.validateHierarchy(hierarchy, progressCallback, scope);
+      checkpoint('validation-complete');
+      this.debugTiming(`Stage 5 — validateHierarchy (${epicCount5} epics, ${storyCount5} stories)`, _ts);
+
+      // Log hierarchy after validation (may have been modified)
+      this.debugSection('POST-VALIDATION: Hierarchy after domain-expert validation');
+      this.debugHierarchySnapshot('POST-VALIDATION', hierarchy.epics.map(e => ({
+        id: e.id || '(no-id)',
+        name: e.name,
+        stories: (e.stories || []).map(s => ({ id: s.id || '(no-id)', name: s.name }))
+      })));
+
+      // Snapshot provisional IDs before renumbering so writeHierarchyFiles can rename
+      // any provisional folders that were written early during context generation.
+      for (const epic of hierarchy.epics) {
+        epic._provisionalId = epic.id;
+        for (const story of epic.stories || []) {
+          story._provisionalId = story.id;
+        }
+      }
+
+      // Renumber IDs
+      hierarchy = this.renumberHierarchy(hierarchy, maxEpicNum, maxStoryNums);
+
+      // Clear screen before file writing phase
+      process.stdout.write('\x1bc');
+      outputBuffer.clear();
+
+      // Compute coding order from dependency graph and stamp phase/order onto hierarchy
+      // (before writeHierarchyFiles so work.json includes codingPhase and codingOrder)
+      try {
+        _ts = Date.now();
+        const codingOrder = computeCodingOrder(hierarchy);
+
+        // Stamp phase and order onto each epic and story in the hierarchy
+        const epicPhaseMap = new Map(); // epicId → phase number (1-based)
+        for (const phase of codingOrder.phases) {
+          for (const epicId of phase.epicIds) {
+            epicPhaseMap.set(epicId, phase.phase + 1);
+          }
+        }
+        let globalOrder = 0;
+        for (const phase of codingOrder.json.phases) {
+          for (const epicEntry of phase.epics) {
+            const epic = hierarchy.epics.find(e => e.id === epicEntry.id);
+            if (epic) {
+              globalOrder++;
+              epic.metadata = { ...(epic.metadata || {}), codingPhase: phase.phase, codingOrder: globalOrder };
+            }
+            for (const storyEntry of epicEntry.stories) {
+              const epic2 = hierarchy.epics.find(e => e.id === epicEntry.id);
+              const story = (epic2?.stories || []).find(s => s.id === storyEntry.id);
+              if (story) {
+                globalOrder++;
+                story.metadata = { ...(story.metadata || {}), codingPhase: phase.phase, codingOrder: globalOrder };
+              }
+            }
+          }
+        }
+
+        // Write coding-order files
+        const codingOrderMdPath = path.join(this.projectPath, 'coding-order.md');
+        const codingOrderJsonPath = path.join(this.projectPath, 'coding-order.json');
+        fs.writeFileSync(codingOrderMdPath, codingOrder.md, 'utf8');
+        fs.writeFileSync(codingOrderJsonPath, JSON.stringify(codingOrder.json, null, 2), 'utf8');
+        this.debug(`Coding order generated: ${codingOrder.phases.length} phases, critical path length ${codingOrder.criticalPath.length}`);
+        this.debugTiming('Stage 6 — computeCodingOrder', _ts);
+      } catch (err) {
+        this.debug(`Coding order generation failed (non-critical): ${err.message}`);
+      }
+
+      // Stage 6: Write hierarchy files (work.json + context.md — no LLM)
+      sendProgress('Writing files and canonical context...');
+      await progressCallback?.(`Stage 6/8: Writing files and canonical context (${epicCount5} epics, ${storyCount5} stories)…`);
+      _ts = Date.now();
+      const { epicCount, storyCount } = await this.writeHierarchyFiles(hierarchy, progressCallback);
+      checkpoint('files-written');
+      this.debugTiming(`Stage 6 — writeHierarchyFiles (${epicCount5} epics, ${storyCount5} stories)`, _ts);
+
+      // Notify listeners (e.g. Kanban board) that work.json files are now on disk.
+      // This fires BEFORE Stage 7/8 so the board can list new epics/stories immediately.
+      await this._hierarchyWrittenCallback?.({ epicCount, storyCount });
+
+      // Stage 7: Generate narrative doc.md from canonical context.md (replaces doc-distribution)
+      sendProgress('Generating documentation from canonical context...');
+      await progressCallback?.(`Stage 7/8: Generating documentation (${epicCount5} epics, ${storyCount5} stories)…`);
+      _ts = Date.now();
+      let rootDocContent = '';
+      if (fs.existsSync(this.projectDocPath)) {
+        rootDocContent = fs.readFileSync(this.projectDocPath, 'utf8');
+      }
+      await this.generateDocFiles(hierarchy, rootDocContent, progressCallback);
+      checkpoint('docs-generated');
+      this.debugTiming(`Stage 7 — generateDocFiles (${epicCount5} epics, ${storyCount5} stories)`, _ts);
+
+      // Stage 8: Enrich story docs with implementation detail
+      sendProgress('Enriching story documentation with implementation detail...');
+      await progressCallback?.(`Stage 8/8: Enriching story documentation (${storyCount5} stories)…`);
+      _ts = Date.now();
+      await this.enrichStoryDocs(hierarchy, progressCallback);
+      checkpoint('enrichment-complete');
+      this.debugTiming(`Stage 8 — enrichStoryDocs (${storyCount5} stories)`, _ts);
+
+      // Stage 9: Summary & Cleanup
+      this.debugStage(9, 'Summary & Cleanup');
+
+      const { totalEpics, totalStories } = this.countTotalHierarchy();
+
+      // ====================================================================
+      // Stage 9: Summary & Cleanup (non-fatal — all real work is done)
+      // Errors here must not crash the ceremony since files are already on disk.
+      // ====================================================================
+      let tokenUsageSummary = null;
+      const returnResult = {
+        epicsCreated: epicCount,
+        storiesCreated: storyCount,
+        totalEpics,
+        totalStories,
+        tokenUsage: { input: 0, output: 0, total: 0 },
+        model: this._modelName,
+        provider: this._providerName,
+        validationIssues: [],
+      };
+
+      try {
+        // Post-run snapshot
+        const postRunSnapshot = this.readPostRunSnapshot();
+        this.debugHierarchySnapshot('POST-RUN', postRunSnapshot);
+        this.debugTiming('TOTAL run() end-to-end', _t0run);
+        sendOutput(`Created ${epicCount} Epics, ${storyCount} Stories. Total: ${totalEpics} Epics, ${totalStories} Stories.`);
+
+        // Token usage
+        const aggregated = this._aggregateAllTokenUsage();
+        if (aggregated.totalCalls > 0 || aggregated.inputTokens > 0) {
+          tokenUsageSummary = aggregated;
+          this.debug('Token usage (all providers)', tokenUsageSummary);
+          this.tokenTracker.finalizeRun(this.ceremonyName);
+          returnResult.tokenUsage = {
+            input: aggregated.inputTokens || 0,
+            output: aggregated.outputTokens || 0,
+            total: aggregated.totalTokens || 0,
+          };
+        }
+
+        sendOutput('Run /seed <story-id> to decompose a Story into Tasks.');
+
+        // Comparison summary log
+        const runDuration = Date.now() - runId;
+        this.debug('\n' + '='.repeat(80));
+        this.debug('SPRINT PLANNING CEREMONY - EXECUTION END');
+        this.debug('='.repeat(80));
+        this.debug('Run ID:', runId);
+        this.debug('Duration:', `${Math.round(runDuration / 1000)} seconds`);
+
+        const duplicateAnalysis = this._lastDuplicateAnalysis || { skippedEpics: [], skippedStories: [] };
+        this.debug('Duplicate detection', {
+          epicsSkipped: duplicateAnalysis.skippedEpics.length,
+          storiesSkipped: duplicateAnalysis.skippedStories.length,
+        });
+        if (tokenUsageSummary) this.debug('Token usage this run', tokenUsageSummary);
+        this.debug('='.repeat(80) + '\n');
+      } catch (summaryErr) {
+        // Summary is non-fatal — log and continue
+        this.debug('Summary logging failed (non-fatal, all files are on disk)', { error: summaryErr.message });
+      }
+
+      // Complete ceremony history (also non-fatal)
+      try {
+        const filesGenerated = [];
+        filesGenerated.push(path.join(this.projectPath, 'context.md'));
+        for (const epic of hierarchy.epics) {
+          filesGenerated.push(path.join(this.projectPath, epic.id, 'work.json'));
+          filesGenerated.push(path.join(this.projectPath, epic.id, 'context.md'));
+          filesGenerated.push(path.join(this.projectPath, epic.id, 'doc.md'));
+          for (const story of epic.stories || []) {
+            filesGenerated.push(path.join(this.projectPath, epic.id, story.id, 'work.json'));
+            filesGenerated.push(path.join(this.projectPath, epic.id, story.id, 'context.md'));
+            filesGenerated.push(path.join(this.projectPath, epic.id, story.id, 'doc.md'));
+          }
+        }
+        history.completeExecution('sprint-planning', executionId, 'success', {
+          filesGenerated,
+          tokenUsage: tokenUsageSummary ? {
+            input: tokenUsageSummary.inputTokens,
+            output: tokenUsageSummary.outputTokens,
+            total: tokenUsageSummary.totalTokens
+          } : null,
+          model: this._modelName,
+          provider: this._providerName,
+          stage: 'completed',
+          metrics: {
+            epicsCreated: epicCount, storiesCreated: storyCount,
+            totalEpics, totalStories
+          }
+        });
+      } catch (historyErr) {
+        this.debug('Ceremony history update failed (non-fatal)', { error: historyErr.message });
+      }
+
+      return returnResult;
+    } catch (error) {
+      const isCancelled = error.message === 'CEREMONY_CANCELLED';
+
+      // Track tokens even for cancelled/error runs — tokens were spent up to this point
+      try {
+        const aggregated = this._aggregateAllTokenUsage();
+        if (aggregated.totalCalls > 0 || aggregated.inputTokens > 0) {
+          this.tokenTracker.finalizeRun(this.ceremonyName);
+          this.debug('Token tracking finalized (partial run)', aggregated);
+        }
+      } catch (trackErr) {
+        this.debug('Could not save token tracking on error', { error: trackErr.message });
+      }
+
+      if (!isCancelled) {
+        this.debug('\n========== ERROR OCCURRED ==========');
+        this.debug('Error details', {
+          message: error.message,
+          stack: error.stack,
+          name: error.name
+        });
+        this.debug('Application state at failure', {
+          ceremonyName: this.ceremonyName,
+          provider: this._providerName,
+          model: this._modelName,
+          projectPath: this.projectPath,
+          currentWorkingDir: process.cwd(),
+          nodeVersion: process.version,
+          platform: process.platform
+        });
+        sendError(`Project expansion failed: ${error.message}`);
+      }
+
+      // Mark execution as aborted on error
+      history.completeExecution('sprint-planning', executionId, 'abrupt-termination', {
+        stage: isCancelled ? 'cancelled' : 'error',
+        error: error.message
+      });
+
+      throw error;
+    }
+  }
+}
+
+export { SprintPlanningProcessor };