@agile-vibe-coding/avc 0.2.3 → 0.3.2

package/cli/sprint-planning-processor.js

@@ -1,6 +1,7 @@
 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';
@@ -9,6 +10,8 @@ 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);
@@ -46,6 +49,14 @@ class SprintPlanningProcessor {
     // 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();
@@ -66,6 +77,18 @@ class SprintPlanningProcessor {
     // 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;
   }
 
   /**
@@ -137,6 +160,102 @@ class SprintPlanningProcessor {
     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
    */
@@ -222,7 +341,16 @@ class SprintPlanningProcessor {
    * @returns {Promise<LLMProvider>} LLM provider instance
    */
   async getProviderForStageInstance(stageName) {
-    const { provider, model } = this.getProviderForStage(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}`;
@@ -236,6 +364,7 @@ class SprintPlanningProcessor {
     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;
@@ -263,6 +392,26 @@ class SprintPlanningProcessor {
     }
   }
 
+  /**
+   * 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)
@@ -311,6 +460,7 @@ class SprintPlanningProcessor {
     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`);
@@ -319,7 +469,13 @@ class SprintPlanningProcessor {
     }
   }
 
-  async retryWithBackoff(fn, operation, maxRetries = 3) {
+  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();
@@ -327,13 +483,19 @@ class SprintPlanningProcessor {
         const isLastAttempt = attempt === maxRetries;
         const isRetriable = error.message?.includes('rate limit') ||
                           error.message?.includes('timeout') ||
-                          error.message?.includes('503');
+                          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.pow(2, attempt) * 1000;
+        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));
@@ -486,96 +648,14 @@ class SprintPlanningProcessor {
     const docContent = fs.readFileSync(this.projectDocPath, 'utf8');
     this.debug(`Doc content loaded (${docContent.length} chars)`);
 
-    // Log full doc.md content for cross-run comparison
-    this.debugSection('PROJECT DOC.MD CONTENT (full text used as scope source)');
-    this.debug('doc.md full content:\n' + docContent);
-
-    // Try to extract scope from known section headers
-    const scopeFromSection = this.tryExtractScopeFromSections(docContent);
-
-    if (scopeFromSection) {
-      this.debug(`✓ Scope extracted from section (${scopeFromSection.length} chars)`);
-      this.debugSection('SCOPE TEXT SENT TO LLM (extracted from doc section)');
-      this.debug('Full scope text:\n' + scopeFromSection);
-      return scopeFromSection;
-    }
-
-    // Fallback: Use entire doc.md
-    this.debug('⚠️  No standard scope section found');
-    this.debug('Using entire doc.md content as scope source');
-
-    sendWarning('No standard scope section found in doc.md');
-    sendIndented('Using entire documentation for feature extraction.', 1);
-    sendIndented('For better results and lower token usage, consider adding one of:', 1);
-    sendIndented('- "## Initial Scope"', 1);
-    sendIndented('- "## Scope"', 1);
-    sendIndented('- "## Features"', 1);
+    this.debugSection('SCOPE TEXT SENT TO LLM (full doc.md)');
+    this.debug(`Full doc content (${docContent.length} chars):\n` + docContent);
 
-    this.debugSection('SCOPE TEXT SENT TO LLM (full doc.md - no scope section found)');
-    this.debug(`Using full doc content (${docContent.length} chars) as scope`);
     return docContent;
   }
 
-  /**
-   * Try to extract scope from known section headers
-   * Returns null if no section found
-   */
-  tryExtractScopeFromSections(docContent) {
-    // Section headers to try (in priority order)
-    const sectionHeaders = [
-      'Initial Scope',           // Official AVC convention
-      'Scope',                   // Common variation
-      'Project Scope',           // Formal variation
-      'Features',                // Common alternative
-      'Core Features',           // Detailed variation
-      'Requirements',            // Specification style
-      'Functional Requirements', // Formal specification
-      'User Stories',            // Agile style
-      'Feature List',            // Simple list style
-      'Objectives',              // Goal-oriented style
-      'Goals',                   // Simple goal style
-      'Deliverables',            // Project management style
-      'Product Features',        // Product-focused
-      'System Requirements'      // Technical specification
-    ];
-
-    this.debug(`Attempting to extract scope from known sections...`);
-    this.debug(`Trying ${sectionHeaders.length} section name variations`);
-
-    // Try each section header
-    for (const header of sectionHeaders) {
-      // Build regex (case-insensitive). Allow optional numeric prefix so
-      // "## 3. Initial Scope" matches when searching for "Initial Scope".
-      const regex = new RegExp(
-        `##\\s+(?:\\d+\\.\\s+)?${this.escapeRegex(header)}\\s+([\\s\\S]+?)(?=\\n#{1,2}[^#]|$)`,
-        'i'
-      );
-
-      const match = docContent.match(regex);
-
-      if (match && match[1].trim().length > 0) {
-        const scope = match[1].trim();
-        this.debug(`✓ Found scope in section: "## ${header}"`);
-        this.debug(`Extracted ${scope.length} chars`);
-        return scope;
-      }
-
-      this.debug(`✗ Section "## ${header}" not found or empty`);
-    }
-
-    this.debug('✗ No known scope section found');
-    return null;
-  }
-
-  /**
-   * Escape special regex characters in section names
-   */
-  escapeRegex(str) {
-    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  }
-
   // STAGE 4: Decompose into Epics + Stories
-  async decomposeIntoEpicsStories(scope, existingEpics, existingStories, progressCallback = null) {
+  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');
@@ -616,7 +696,7 @@ ${existingStoryNames.map(name => `- ${name}`).join('\n')}
 `;
     }
 
-    prompt += `\nDecompose this project into NEW Epics (3-7 domain-based groupings) and Stories (2-8 user-facing capabilities per Epic).
+    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.
 
@@ -635,6 +715,11 @@ Return your response as JSON following the exact structure specified in your ins
     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:');
@@ -643,7 +728,7 @@ Return your response as JSON following the exact structure specified in your ins
     this.debug('='.repeat(80) + '\n');
 
     // LLM call with full request/response logging
-    const hierarchy = await this.debugApiCall(
+    let hierarchy = await this.debugApiCall(
       'Epic/Story Decomposition',
       async () => {
         this.debug('Request payload', {
@@ -698,6 +783,9 @@ Return your response as JSON following the exact structure specified in your ins
       }
     );
 
+    // 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');
@@ -722,44 +810,1769 @@ Return your response as JSON following the exact structure specified in your ins
     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))
+  /**
+   * 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');
+        }
       }));
-    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');
-      const prompt = `PROJECT SCOPE:\n\n${scope.substring(0, 3000)}\n\nExtract 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 {};
-    }
+    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
@@ -792,6 +2605,41 @@ Return your response as JSON following the exact structure specified in your ins
       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,
@@ -801,6 +2649,11 @@ Return your response as JSON following the exact structure specified in your ins
       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}`
@@ -812,13 +2665,20 @@ Return your response as JSON following the exact structure specified in your ins
       }
     });
 
-    // Validate each epic
-    for (const epic of hierarchy.epics) {
+    // ── 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}`, {});
 
-      // Build epic context string for validation
-      const epicContext = `# Epic: ${epic.name}\n\n**Description:** ${epic.description}\n\n**Domain:** ${epic.domain}\n\n**Features:**\n${(epic.features || []).map(f => `- ${f}`).join('\n')}\n`;
+      // 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();
@@ -834,13 +2694,21 @@ Return your response as JSON following the exact structure specified in your ins
         this.displayValidationIssues(epicValidation);
       }
 
-      // Validate each story under this epic
-      for (const story of epic.stories || []) {
+      // 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}`, {});
 
-        // Build story context string for validation
-        const storyContext = `# Story: ${story.name}\n\n**User Type:** ${story.userType}\n\n**Description:** ${story.description}\n\n**Acceptance Criteria:**\n${(story.acceptance || []).map((ac, i) => `${i + 1}. ${ac}`).join('\n')}\n\n**Parent Epic:** ${epic.name} (${epic.domain})\n`;
+        // 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();
@@ -855,9 +2723,122 @@ Return your response as JSON following the exact structure specified in your ins
           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;
   }
 
@@ -874,11 +2855,12 @@ Return your response as JSON following the exact structure specified in your ins
     const prefix = statusPrefix[validation.overallStatus] || '';
     sendOutput(`${prefix} ${type}: ${name}\n`);
     sendIndented(`Overall Score: ${validation.averageScore}/100`, 1);
-    sendIndented(`Validators: ${validation.validatorCount} agents`, 1);
-    sendIndented(`Issues: ${validation.criticalIssues.length} critical, ${validation.majorIssues.length} major, ${validation.minorIssues.length} minor`, 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) {
+    if (validation.overallStatus !== 'needs-improvement' && validation.strengths?.length > 0) {
       sendIndented(`Strengths: ${validation.strengths.slice(0, 2).join(', ')}`, 1);
     }
 
@@ -890,7 +2872,7 @@ Return your response as JSON following the exact structure specified in your ins
    */
   displayValidationIssues(validation) {
     // Show critical issues
-    if (validation.criticalIssues.length > 0) {
+    if (validation.criticalIssues?.length > 0) {
       this.debug('Critical Issues', validation.criticalIssues.slice(0, 3).map(issue => ({
         domain: issue.domain,
         description: issue.description,
@@ -898,8 +2880,16 @@ Return your response as JSON following the exact structure specified in your ins
       })));
     }
 
-    // Show improvement priorities
-    if (validation.improvementPriorities.length > 0) {
+    // 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,
@@ -1020,12 +3010,16 @@ Return your response as JSON following the exact structure specified in your ins
     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}`);
@@ -1035,6 +3029,7 @@ Return your response as JSON following the exact structure specified in your ins
       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}`);
@@ -1044,6 +3039,31 @@ Return your response as JSON following the exact structure specified in your ins
       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 }))
     });
@@ -1056,22 +3076,50 @@ Return your response as JSON following the exact structure specified in your ins
     this.debugStage(7, 'Write Hierarchy Files + Distribute Documentation');
     this.debug('Writing hierarchy files with documentation distribution');
 
-    // Read the root project doc.md (used as source for all epic distributions)
-    let projectDocContent = '';
-    if (fs.existsSync(this.projectDocPath)) {
-      projectDocContent = fs.readFileSync(this.projectDocPath, 'utf8');
-      this.debug(`Read project doc.md (${projectDocContent.length} bytes) for distribution`);
-    } else {
-      this.debug('project/doc.md not found — skipping 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);
+      }
     }
 
-    const doDistribute = projectDocContent.length > 0;
+    // 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 and write all work.json files
+    // 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,
@@ -1092,11 +3140,34 @@ Return your response as JSON following the exact structure specified in your ins
       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,
@@ -1117,69 +3188,77 @@ Return your response as JSON following the exact structure specified in your ins
         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' });
       }
     }
 
-    // Phase 2 (parallel): Distribute docs — all epics concurrently, stories within each epic concurrently
-    await Promise.all(
-      hierarchy.epics.map(async (epic) => {
-        const epicDir = path.join(this.projectPath, epic.id);
+    // 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');
 
-        // Distribute epic doc from project doc
-        let epicDocContent;
-        if (doDistribute) {
-          await progressCallback?.(null, `Distributing documentation → ${epic.name}`, {});
-          this.debug(`Distributing docs: project/doc.md → ${epic.id}/doc.md`);
-          const result = await this.distributeDocContent(projectDocContent, epic, 'epic', progressCallback);
-          epicDocContent = result.childDoc;
-          this.debug(`Epic doc ${epic.id}: ${epicDocContent.length} bytes`);
-        } else {
-          await progressCallback?.(null, `Writing Epic: ${epic.name}`, {});
-          epicDocContent = `# ${epic.name}\n\n${epic.description || ''}\n`;
+      // 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 || [],
+          };
         }
+      }
 
-        // Distribute all story docs from epic doc — in parallel within this epic
-        const storyDocs = await Promise.all(
-          (epic.stories || []).map(async (story) => {
-            if (!doDistribute) {
-              return `# ${story.name}\n\n${story.description || ''}\n`;
+      // 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++;
             }
-            await progressCallback?.(null, `  Distributing documentation → ${story.name}`, {});
-            this.debug(`Distributing docs: ${epic.id}/doc.md → ${story.id}/doc.md`);
-            const result = await this.distributeDocContent(epicDocContent, story, 'story', progressCallback);
-            this.debug(`Story doc ${story.id}: ${result.childDoc.length} bytes`);
-            return result.childDoc;
-          })
-        );
-
-        // Write all doc.md files for this epic
-        const epicDocPath = path.join(epicDir, 'doc.md');
-        fs.writeFileSync(epicDocPath, epicDocContent, 'utf8');
-        this.debug(`Writing ${epicDocPath} (${epicDocContent.length} bytes)`);
+          }
+        }
+      }
+      this.debug(`Set ${readyCount} items to 'ready' status (dependency-free)`);
+    } catch (err) {
+      this.debug(`Failed to compute ready status (non-critical): ${err.message}`);
+    }
 
-        (epic.stories || []).forEach((story, si) => {
-          const storyDocPath = path.join(epicDir, story.id, 'doc.md');
-          fs.writeFileSync(storyDocPath, storyDocs[si], 'utf8');
-          this.debug(`Writing ${storyDocPath} (${storyDocs[si].length} bytes)`);
-        });
-      })
-    );
+    // 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');
+    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}/doc.md`);
+      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}/doc.md`);
+        filesWritten.push(`${epic.id}/${story.id}/context.md`);
       }
     }
-    this.debug('Files written this run', filesWritten);
+    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
@@ -1500,8 +3579,84 @@ Extract and synthesize content from the parent document that is specifically rel
     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) {
+  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;
@@ -1527,6 +3682,13 @@ Extract and synthesize content from the parent document that is specifically rel
     // 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();
@@ -1547,10 +3709,86 @@ Extract and synthesize content from the parent document that is specifically rel
       });
 
       const header = getCeremonyHeader('sprint-planning');
-      sendCeremonyHeader(header.title, header.url);
+      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…');
@@ -1588,7 +3826,27 @@ Extract and synthesize content from the parent document that is specifically rel
       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)');
@@ -1599,6 +3857,40 @@ Extract and synthesize content from the parent document that is specifically rel
       })));
       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…');
@@ -1624,6 +3916,7 @@ Extract and synthesize content from the parent document that is specifically rel
       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)
@@ -1634,8 +3927,14 @@ Extract and synthesize content from the parent document that is specifically rel
         stories: (e.stories || []).map(s => ({ id: s.id || '(no-id)', name: s.name }))
       })));
 
-      // Analyze duplicate detection (before renumbering)
-      const duplicateAnalysis = this.analyzeDuplicates(hierarchy, existingEpics, existingStories);
+      // 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);
@@ -1644,126 +3943,176 @@ Extract and synthesize content from the parent document that is specifically rel
       process.stdout.write('\x1bc');
       outputBuffer.clear();
 
-      // Stage 6: Write hierarchy files
-      sendProgress('Writing files and distributing documentation...');
-      await progressCallback?.(`Stage 6/7: Writing files and distributing documentation (${epicCount5} epics, ${storyCount5} stories)…`);
+      // 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);
 
-      // Stage 7: Enrich story docs with implementation detail
+      // 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 7/7: Enriching story documentation (${storyCount5} stories)…`);
+      await progressCallback?.(`Stage 8/8: Enriching story documentation (${storyCount5} stories)…`);
       _ts = Date.now();
       await this.enrichStoryDocs(hierarchy, progressCallback);
-      this.debugTiming(`Stage 7 — enrichStoryDocs (${storyCount5} stories)`, _ts);
+      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();
 
-      // Capture and log post-run hierarchy snapshot for comparison
-      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.`);
-
-      // Track token usage — aggregate across all provider instances
-      const aggregated = this._aggregateAllTokenUsage();
+      // ====================================================================
+      // 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;
-      if (aggregated.totalCalls > 0 || aggregated.inputTokens > 0) {
-        tokenUsageSummary = aggregated;
-        this.debug('Token usage (all providers)', tokenUsageSummary);
-
-        this.tokenTracker.finalizeRun(this.ceremonyName);
-        this.debug('Token tracking finalized in .avc/token-history.json');
-      }
-
-      sendOutput('Run /seed <story-id> to decompose a Story into Tasks.');
-
-      // Log ceremony execution end with full comparison summary
-      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('Started:', runTimestamp);
-      this.debug('Ended:', localISO());
-      this.debug('Duration:', `${Math.round(runDuration / 1000)} seconds`);
-
-      this.debugSection('RUN COMPARISON SUMMARY (compare this block across runs)');
-      this.debug('PRE-RUN state', {
-        epics: existingEpics.size,
-        stories: existingStories.size,
-        epicNames: Array.from(existingEpics.keys())
-      });
-      this.debug('THIS RUN added', {
-        epics: epicCount,
-        stories: storyCount,
-        epicNames: hierarchy.epics.map(e => e.name),
-        storyNames: hierarchy.epics.flatMap(e => (e.stories || []).map(s => s.name))
-      });
-      this.debug('POST-RUN state', {
-        epics: totalEpics,
-        stories: totalStories
-      });
-      this.debug('Duplicate detection results', {
-        epicsSkippedAsDuplicates: duplicateAnalysis.skippedEpics.length,
-        storiesSkippedAsDuplicates: duplicateAnalysis.skippedStories.length,
-        skippedEpicNames: duplicateAnalysis.skippedEpics.map(s => s.name),
-        skippedStoryNames: duplicateAnalysis.skippedStories.map(s => s.name)
-      });
-      if (tokenUsageSummary) {
-        this.debug('Token usage this run', tokenUsageSummary);
-      }
-      this.debug('='.repeat(80) + '\n');
-
-      // Build return result for kanban integration
       const returnResult = {
         epicsCreated: epicCount,
         storiesCreated: storyCount,
         totalEpics,
         totalStories,
-        tokenUsage: {
-          input: tokenUsageSummary?.inputTokens || 0,
-          output: tokenUsageSummary?.outputTokens || 0,
-          total: tokenUsageSummary?.totalTokens || 0,
-        },
+        tokenUsage: { input: 0, output: 0, total: 0 },
         model: this._modelName,
         provider: this._providerName,
         validationIssues: [],
       };
 
-      // Complete ceremony history tracking
-      const filesGenerated = [];
-      for (const epic of hierarchy.epics) {
-        filesGenerated.push(path.join(this.projectPath, epic.id, 'work.json'));
-        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, 'doc.md'));
+      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 });
       }
 
-      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: totalEpics,
-          totalStories: totalStories
+      // 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) {