@agile-vibe-coding/avc 0.2.3 → 0.3.2

package/cli/epic-story-validator.js

@@ -4,6 +4,7 @@ import path from 'path';
 import fs from 'fs';
 import { fileURLToPath } from 'url';
 import { loadAgent } from './agent-loader.js';
+import { validateWithMicroChecks } from './micro-check-validator.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -11,10 +12,8 @@ const __dirname = path.dirname(__filename);
 /**
  * Multi-Agent Epic and Story Validator
  *
- * Orchestrates validation across multiple domain-specific validator agents.
- * Each epic/story is reviewed by 2-8 specialized validators based on domain and features.
- * After each validator, a paired solver agent improves the epic/story if issues are found,
- * then the same validator re-validates — up to maxIterations times.
+ * Orchestrates validation via micro-checks: 370 small YES/NO LLM calls across
+ * 15 domain perspectives, deterministic scoring, and atomic per-check fixes.
  */
 class EpicStoryValidator {
   constructor(llmProvider, verificationTracker, stagesConfig = null, useSmartSelection = false, progressCallback = null, projectContext = null) {
@@ -28,7 +27,7 @@ class EpicStoryValidator {
     this.agentsPath = path.join(__dirname, 'agents');
     this.validationFeedback = new Map();
 
-    // Store validation stage configuration
+    // Store validation stage configuration (solver stage removed — micro-checks handle fixes).
     this.validationStageConfig = stagesConfig?.validation || null;
 
     // Cache for validator-specific providers
@@ -42,6 +41,10 @@ class EpicStoryValidator {
 
     // Per-call token callback (propagated to all created providers)
     this._tokenCallback = null;
+
+    // Root project context.md string — prepended to all validation prompts when set
+    this.rootContextMd = null;
+
   }
 
   /**
@@ -53,6 +56,136 @@ class EpicStoryValidator {
     this._tokenCallback = fn;
   }
 
+  /**
+   * Attach a PromptLogger so all providers created by this validator write payloads.
+   * @param {import('./prompt-logger.js').PromptLogger} logger
+   */
+  setPromptLogger(logger) {
+    this._promptLogger = logger;
+  }
+
+  /**
+   * Set the root project context.md string — prepended to all validation prompts.
+   * @param {string} md - Canonical root context markdown
+   */
+  setRootContextMd(md) {
+    this.rootContextMd = md;
+  }
+
+  /**
+   * Set callback invoked when a validator call fails with a quota/rate-limit error.
+   * Signature: async ({ validatorName, errMsg, provider, model }) => { newProvider?, newModel? }
+   * Returning { newProvider, newModel } switches the validation+solver stage config.
+   * Returning null/undefined retries with the same model.
+   */
+  setQuotaExceededCallback(fn) {
+    this._quotaExceededCallback = fn;
+  }
+
+  /**
+   * Update validation stage config to a new provider/model and clear provider cache.
+   * Called after user selects "Switch Provider" in the quota-limit dialog.
+   */
+  _updateValidationStageConfig(newProvider, newModel) {
+    const oldProvider = this.validationStageConfig?.provider;
+    const oldModel = this.validationStageConfig?.model;
+    if (!this.validationStageConfig) this.validationStageConfig = {};
+    this.validationStageConfig.provider = newProvider;
+    this.validationStageConfig.model = newModel;
+    // Surgical cache invalidation: only clear entries matching the old provider/model
+    // so providers that were already on the new target are preserved
+    if (oldProvider || oldModel) {
+      for (const [key, prov] of Object.entries(this._validatorProviders)) {
+        if (prov?._providerName === oldProvider || prov?._modelName === oldModel) {
+          delete this._validatorProviders[key];
+        }
+      }
+    } else {
+      // No previous config — clear everything
+      this._validatorProviders = {};
+    }
+  }
+
+  /**
+   * Returns true if the error message indicates a quota or persistent rate-limit failure.
+   */
+  _isQuotaOrRateLimit(errMsg) {
+    const m = (errMsg || '').toLowerCase();
+    return m.includes('429') || m.includes('quota') || m.includes('rate limit') ||
+      m.includes('resource exhausted') || m.includes('resource_exhausted') ||
+      m.includes('too many requests') ||
+      // Anthropic credit-balance exhausted (400 invalid_request_error)
+      m.includes('credit balance is too low') || m.includes('credit balance') ||
+      m.includes('billing') || m.includes('insufficient_quota');
+  }
+
+  /**
+   * Generate canonical context.md string for an epic from its JSON fields.
+   * This is the bounded, structured format passed to validators and solvers.
+   * @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.
+   * @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');
+  }
+
   /** Emit a Level-3 detail line to the UI (fire-and-forget safe) */
   async _detail(msg) {
     await this.progressCallback?.(null, null, { detail: msg });
@@ -139,31 +272,15 @@ class EpicStoryValidator {
     }
 
     // Create new provider
+    const role = this.extractDomain(validatorName);
     const providerInstance = await LLMProvider.create(provider, model);
     if (this._tokenCallback) providerInstance.onCall((delta) => this._tokenCallback(delta, 'validation'));
+    if (this._promptLogger) providerInstance.setPromptLogger(this._promptLogger, `validation-${role}`);
     this._validatorProviders[cacheKey] = providerInstance;
 
     return providerInstance;
   }
 
-  /**
-   * Get provider for a specific solver based on solver stage config
-   * @param {string} role - Role name (e.g., 'security')
-   * @returns {Promise<LLMProvider>} LLM provider instance
-   */
-  async getProviderForSolver(role) {
-    const solverConfig = this.validationStageConfig?.solver;
-    if (!solverConfig?.provider) return this.llmProvider;
-
-    const cacheKey = `solver:${solverConfig.provider}:${solverConfig.model}`;
-    if (this._validatorProviders[cacheKey]) return this._validatorProviders[cacheKey];
-
-    const instance = await LLMProvider.create(solverConfig.provider, solverConfig.model);
-    if (this._tokenCallback) instance.onCall((delta) => this._tokenCallback(delta, 'solver'));
-    this._validatorProviders[cacheKey] = instance;
-    return instance;
-  }
-
   /**
    * Get provider for contextual agent selection (agent-selector LLM call).
    * Uses validation stage config; falls back to this.llmProvider.
@@ -175,6 +292,7 @@ class EpicStoryValidator {
       if (this._validatorProviders[cacheKey]) return this._validatorProviders[cacheKey];
       const instance = await LLMProvider.create(this.validationStageConfig.provider, this.validationStageConfig.model);
       if (this._tokenCallback) instance.onCall((delta) => this._tokenCallback(delta, 'validation'));
+      if (this._promptLogger) instance.setPromptLogger(this._promptLogger, 'selection');
       this._validatorProviders[cacheKey] = instance;
       return instance;
     }
@@ -182,780 +300,198 @@ class EpicStoryValidator {
   }
 
   /**
-   * Validate an Epic with multiple domain validators
-   * Runs validators sequentially; after each validator, if issues exist,
-   * a paired solver improves the epic before the next validator runs.
+   * Validate an Epic via micro-checks: parallel YES/NO domain checks,
+   * cross-reference consistency checks, deterministic scoring, and atomic fixes.
    * @param {Object} epic - Epic work.json object
    * @param {string} epicContext - Epic context.md content
    * @returns {Object} Aggregated validation result
    */
   async validateEpic(epic, epicContext) {
-    // 1. Check cache for previously selected validators
-    let validators;
+    console.log(`\n🔍 Validating Epic (micro-checks): ${epic.name}`);
+    // Determine perspectives from router
+    let perspectives;
     if (epic.metadata?.selectedValidators) {
-      validators = epic.metadata.selectedValidators;
-      console.log(`   Using cached validator selection (${validators.length} validators)`);
+      perspectives = epic.metadata.selectedValidators.map(v => this.extractDomain(v));
     } else {
-      // Get applicable validators for this epic
-      const useContextualSelection = this.validationStageConfig?.useContextualSelection || false;
-      console.log(`[DEBUG] Epic validator selection: useContextualSelection=${useContextualSelection}, validationStageConfig=${JSON.stringify(this.validationStageConfig)}`);
-      if (useContextualSelection) {
-        const selectionProvider = await this.getProviderForSelection();
-        validators = await this.router.selectValidatorsWithContext(epic, 'epic', selectionProvider);
-      } else if (this.useSmartSelection) {
-        validators = await this.router.getValidatorsForEpicWithLLM(epic);
-      } else {
-        validators = this.router.getValidatorsForEpic(epic);
-      }
-
-      // Cache selection in metadata
-      if (!epic.metadata) {
-        epic.metadata = {};
-      }
+      const validators = this.router.getValidatorsForEpic(epic);
+      if (!epic.metadata) epic.metadata = {};
       epic.metadata.selectedValidators = validators;
+      perspectives = validators.map(v => this.extractDomain(v));
     }
-
-    console.log(`\n🔍 Validating Epic: ${epic.name}`);
-    console.log(`   Domain: ${epic.domain}`);
-    console.log(`   Validators (${validators.length}): ${validators.map(v => this.extractDomain(v)).join(', ')}\n`);
-
-    // Read solver iteration settings
-    const solverConfig = this.validationStageConfig?.solver || {};
-    const maxIterations = solverConfig.maxIterations ?? 3;
-    const acceptanceThreshold = solverConfig.acceptanceThreshold ?? 95;
-
-    await this._detail(`${validators.length} validator${validators.length !== 1 ? 's' : ''}: ${validators.map(v => this.extractDomain(v)).join(', ')}`);
-
-    // Working copy — accumulates improvements from solver runs
-    // Keep stories array untouched; solver only modifies epic-level fields
-    let workingEpic = { ...epic };
-
-    // ── Phase 1: run all validators in parallel on the initial snapshot ──────────
-    await this._detail(`Running ${validators.length} validators in parallel…`);
-    console.log(`   Running ${validators.length} validators in parallel…`);
-
-    const _t0Parallel = Date.now();
-    const parallelResults = await Promise.all(
-      validators.map((validatorName, vi) => {
-        const role = this.extractDomain(validatorName);
-        return this._withHeartbeat(
-          () => this.runEpicValidator(workingEpic, epicContext, validatorName),
-          (elapsed) => {
-            if (elapsed < 20) return `   [${role}] reviewing requirements…`;
-            if (elapsed < 40) return `   [${role}] analyzing concerns…`;
-            if (elapsed < 60) return `   [${role}] checking best practices…`;
-            return `   [${role}] still validating…`;
-          },
-          10000
-        ).catch(err => {
-          console.warn(`   ⚠ Validator ${validatorName} failed: ${err.message.split('\n')[0]}`);
-          return { overallScore: 0, validationStatus: 'error', issues: [], _validatorError: err.message.split('\n')[0] };
-        });
-      })
-    );
-    console.log(`[TIMING] epic parallel batch (${validators.length} validators): ${Date.now() - _t0Parallel}ms`);
-
-    // Log all parallel results
-    for (let vi = 0; vi < validators.length; vi++) {
-      const validatorName = validators[vi];
-      const role = this.extractDomain(validatorName);
-      const result = parallelResults[vi];
-      const score = result.overallScore ?? 0;
-      const allIssues = result.issues || [];
-      const critCount = allIssues.filter(i => i.severity === 'critical').length;
-      const majCount  = allIssues.filter(i => i.severity === 'major').length;
-      const acceptable = score >= acceptanceThreshold;
-      const issueStr = allIssues.length > 0 ? ` · ${allIssues.length} issue${allIssues.length !== 1 ? 's' : ''}` : '';
-      await this._detail(`[${vi + 1}/${validators.length}] ${role}: ${score}/100${issueStr} — ${acceptable ? '✓' : '⚠ below threshold'}`);
-      console.log(`   [${vi + 1}/${validators.length}] ${validatorName} score=${score}/100 status=${result.validationStatus} (critical=${critCount} major=${majCount} minor=${allIssues.length - critCount - majCount})`);
-      allIssues.forEach(issue => {
-        const cat = issue.category ? `[${issue.category}] ` : '';
-        const sug = issue.suggestion ? ` → ${issue.suggestion}` : '';
-        console.log(`     [${(issue.severity || 'unknown').toUpperCase()}] ${cat}${issue.description || '(no description)'}${sug}`);
-      });
-    }
-
-    // ── Phase 2: parallel solver rounds ──────────────────────────────────────────
-    const finalResults = [...parallelResults];
-
-    // Indices of validators still below threshold
-    let needsWork = validators.map((_, vi) => vi).filter(vi =>
-      (parallelResults[vi].overallScore ?? 0) < acceptanceThreshold
-    );
-    if (needsWork.length > 0) {
-      console.log(`   ${needsWork.length}/${validators.length} validators below threshold — running parallel solver rounds (max ${maxIterations - 1})`);
-      await this._detail(`${needsWork.length} below threshold — parallel solver rounds`);
-    }
-
-    for (let iter = 1; iter < maxIterations && needsWork.length > 0; iter++) {
-      const roundCount = needsWork.length;
-      await this._detail(`   ↻ Round ${iter}/${maxIterations - 1}: ${roundCount} solver${roundCount !== 1 ? 's' : ''} in parallel…`);
-      console.log(`   ↻ Round ${iter}/${maxIterations - 1}: ${roundCount} solver${roundCount !== 1 ? 's' : ''} running in parallel…`);
-      const _t0Round = Date.now();
-
-      // 1. Run all below-threshold solvers in parallel (all see the same workingEpic snapshot)
-      const solverResults = await Promise.all(
-        needsWork.map(vi => {
-          const validatorName = validators[vi];
-          const role = this.extractDomain(validatorName);
-          return this._withHeartbeat(
-            () => this.runEpicSolver(workingEpic, epicContext, finalResults[vi], validatorName),
-            (elapsed) => {
-              if (elapsed < 25) return `   ↻ ${role} solver — applying improvements…`;
-              if (elapsed < 50) return `   ↻ ${role} solver — refining epic quality…`;
-              return `   ↻ ${role} solver — still running…`;
-            },
-            20000
-          ).then(improved => ({ vi, improved, error: null }))
-            .catch(err => ({ vi, improved: null, error: err }));
-        })
-      );
-      console.log(`[TIMING] Phase 2 round ${iter} solvers: ${Date.now() - _t0Round}ms`);
-
-      // 2. Merge all solver results — preserve base items, add up to 3 new items per solver
-      // Base items are anchored (never dropped); each solver contributes at most 3 genuinely new features.
-      // Description taken from the solver whose validator scored lowest (most informed fix).
-      const baseFeatures = workingEpic.features || [];
-      const baseFeaturesSet = new Set(baseFeatures);
-      const newFeatureAdditions = []; // items new beyond base, insertion-ordered, deduplicated
-      const allDeps = new Set(workingEpic.dependencies || []);
-      let bestDescription = workingEpic.description;
-      let worstValidatorScore = Infinity;
-      let anyImproved = false;
-
-      for (const { vi, improved, error } of solverResults) {
-        const validatorName = validators[vi];
-        const role = this.extractDomain(validatorName);
-        if (error) {
-          console.warn(`   ⚠ Solver failed for ${validatorName}: ${error.message} — keeping current epic`);
-          await this._detail(`   ⚠ Solver failed (${role}): ${error.message.split('\n')[0].slice(0, 120)}`);
-          continue;
-        }
-        if (improved && improved.id === workingEpic.id) {
-          anyImproved = true;
-          // Collect only new items not already in base or pending additions (max 3 per solver)
-          const existingAll = new Set([...baseFeaturesSet, ...newFeatureAdditions]);
-          const solverNew = (improved.features || []).filter(f => !existingAll.has(f)).slice(0, 3);
-          newFeatureAdditions.push(...solverNew);
-          (improved.dependencies || []).forEach(d => allDeps.add(d));
-          // Description: take from the validator with the lowest score (most dissatisfied perspective)
-          const vScore = finalResults[vi]?.overallScore ?? 100;
-          if (improved.description && improved.description !== workingEpic.description && vScore < worstValidatorScore) {
-            worstValidatorScore = vScore;
-            bestDescription = improved.description;
-          }
-          console.log(`   ↻ [${role}] solver merged — ${solverNew.length} new features added`);
-          await this._detail(`   → [${role}] improvements applied`);
-        } else {
-          console.log(`   ↻ [${role}] solver returned no valid improvement (id mismatch or empty)`);
-        }
+    const workItemText = epicContext || this.generateEpicContextMd(epic);
+    const mcResult = await validateWithMicroChecks(
+      epic, workItemText, 'epic', perspectives, this.llmProvider,
+      {
+        concurrency: this.validationStageConfig?.concurrency ?? 5,
+        batchSize: this.validationStageConfig?.batchSize ?? 8,
+        maxFixAttempts: this.validationStageConfig?.maxFixAttempts ?? 3,
+        generateContextFn: (wi) => this.generateEpicContextMd(wi),
+        progressCallback: this.progressCallback,
+        projectRoot: this.projectContext?.projectRoot,
       }
-
-      if (anyImproved) {
-        // Base items always preserved first; cap only the additions portion
-        const merged = [...baseFeatures, ...newFeatureAdditions];
-        const hardCap = baseFeatures.length + 12; // allow up to 12 new features beyond original
-        const finalFeatures = merged.length > hardCap ? merged.slice(0, hardCap) : merged;
-        if (merged.length > hardCap) {
-          console.log(`   ↻ Epic features capped after merge: ${merged.length} → ${hardCap} (base=${baseFeatures.length} + new=${finalFeatures.length - baseFeatures.length})`);
-        }
-        const descBefore = (workingEpic.description || '').slice(0, 100);
-        workingEpic = {
-          ...workingEpic,
-          description:  bestDescription,
-          features:     finalFeatures,
-          dependencies: [...allDeps],
-        };
-        const descAfter = (workingEpic.description || '').slice(0, 100);
-        console.log(`   ↻ Parallel merge applied — desc changed: ${descBefore !== descAfter}, features: ${finalFeatures.length} (base=${baseFeatures.length} + new=${newFeatureAdditions.length})`);
-      }
-
-      // 3. Re-validate all in parallel
-      await this._detail(`   Re-validating ${roundCount} validator${roundCount !== 1 ? 's' : ''} in parallel (iter ${iter + 1})…`);
-      const _t0Revalidate = Date.now();
-      const revalidateResults = await Promise.all(
-        needsWork.map(vi => {
-          const validatorName = validators[vi];
-          const role = this.extractDomain(validatorName);
-          return this._withHeartbeat(
-            () => this.runEpicValidator(workingEpic, epicContext, validatorName),
-            (elapsed) => {
-              if (elapsed < 20) return `   [${role}] re-reviewing…`;
-              if (elapsed < 40) return `   [${role}] re-analyzing…`;
-              return `   [${role}] re-validating…`;
-            },
-            10000
-          ).then(result => ({ vi, result, error: null }))
-            .catch(err => ({ vi, result: null, error: err }));
-        })
-      );
-      console.log(`[TIMING] Phase 2 round ${iter} re-validates: ${Date.now() - _t0Revalidate}ms`);
-
-      // 4. Update finalResults; determine which validators need another round
-      const nextNeedsWork = [];
-      for (const { vi, result, error } of revalidateResults) {
-        const validatorName = validators[vi];
-        const role = this.extractDomain(validatorName);
-        if (error) {
-          console.warn(`   ⚠ Re-validator ${validatorName} failed: ${error.message.split('\n')[0]}`);
-          await this._detail(`   ⚠ Re-validate failed (${role}): ${error.message.split('\n')[0].slice(0, 120)}`);
-          continue; // keep finalResults[vi] as-is; give up on this validator
-        }
-        finalResults[vi] = result;
-        const newScore = result.overallScore ?? 0;
-        const acceptable = newScore >= acceptanceThreshold;
-        const issueStr2 = (result.issues || []).length > 0 ? ` · ${result.issues.length} issues` : '';
-        await this._detail(`   [${role}] iter ${iter + 1}: ${newScore}/100${issueStr2} — ${acceptable ? '✓ accepted' : `⚠ below threshold (${acceptanceThreshold})`}`);
-        console.log(`   [${vi + 1}/${validators.length}] ${validatorName} iter=${iter + 1} score=${newScore}/100 status=${result.validationStatus}`);
-        if (!acceptable) {
-          nextNeedsWork.push(vi);
-        }
-      }
-      console.log(`[TIMING] Phase 2 round ${iter} total: ${Date.now() - _t0Round}ms — ${nextNeedsWork.length} still need work`);
-      needsWork = nextNeedsWork;
-    }
-
-    const validationResults = finalResults;
-
-    // Write accumulated improvements back to the original epic object
-    // (sprint-planning-processor owns the reference; this mutates it in place)
-    epic.description  = workingEpic.description;
-    epic.features     = workingEpic.features;
-    epic.dependencies = workingEpic.dependencies;
-
-    // 3. Aggregate results
-    const aggregated = this.aggregateValidationResults(validationResults, 'epic');
-
-    // 4. Determine overall status
-    aggregated.overallStatus = this.determineOverallStatus(validationResults);
-    aggregated.readyToPublish = aggregated.overallStatus !== 'needs-improvement';
-
-    await this._detail(`Overall: ${aggregated.readyToPublish ? '✓ passed' : '⚠ needs improvement'} · avg ${aggregated.averageScore}/100`);
-    console.log(`   Epic "${epic.name}" summary: avg=${aggregated.averageScore}/100 readyToPublish=${aggregated.readyToPublish} critical=${aggregated.criticalIssues.length} major=${aggregated.majorIssues.length}`);
-    aggregated.validatorResults.forEach(vr => {
-      console.log(`     ${this.extractDomain(vr.validator)}: ${vr.score}/100 (${vr.status})`);
-    });
-
-    // 5. Store for feedback loop
-    this.storeValidationFeedback(epic.id, aggregated);
-
-    // 6. Persist result into epic metadata so sprint-planning-processor writes it to work.json
+    );
     epic.metadata = epic.metadata || {};
     epic.metadata.validationResult = {
-      averageScore: aggregated.averageScore,
-      overallStatus: aggregated.overallStatus,
-      readyToPublish: aggregated.readyToPublish,
-      criticalIssues: aggregated.criticalIssues,
-      majorIssues: aggregated.majorIssues,
-      minorIssues: aggregated.minorIssues,
-      validatorResults: aggregated.validatorResults,
-      validatedAt: new Date().toISOString(),
+      averageScore: mcResult.averageScore,
+      overallStatus: mcResult.overallStatus,
+      readyToPublish: mcResult.readyToPublish,
+      criticalIssues: mcResult.criticalIssues,
+      majorIssues: mcResult.majorIssues,
+      minorIssues: mcResult.minorIssues,
+      validatorResults: mcResult.validatorResults,
+      validatedAt: mcResult.validatedAt,
     };
-
-    return aggregated;
+    this.storeValidationFeedback(epic.id, mcResult);
+    return mcResult;
   }
 
   /**
-   * Validate a Story with multiple domain validators
-   * Runs validators sequentially; after each validator, if issues exist,
-   * a paired solver improves the story before the next validator runs.
+   * Validate a Story via micro-checks: parallel YES/NO domain checks,
+   * cross-reference consistency checks, deterministic scoring, and atomic fixes.
    * @param {Object} story - Story work.json object
    * @param {string} storyContext - Story context.md content
    * @param {Object} epic - Parent epic for routing
    * @returns {Object} Aggregated validation result
    */
   async validateStory(story, storyContext, epic) {
-    // 1. Check cache for previously selected validators
-    let validators;
+    console.log(`\n🔍 Validating Story (micro-checks): ${story.name}`);
+    let perspectives;
     if (story.metadata?.selectedValidators) {
-      validators = story.metadata.selectedValidators;
-      console.log(`   Using cached validator selection (${validators.length} validators)`);
+      perspectives = story.metadata.selectedValidators.map(v => this.extractDomain(v));
     } else {
-      // Get applicable validators for this story
-      const useContextualSelection = this.validationStageConfig?.useContextualSelection || false;
-      if (useContextualSelection) {
-        const selectionProvider = await this.getProviderForSelection();
-        validators = await this.router.selectValidatorsWithContext(story, 'story', selectionProvider, epic);
-      } else if (this.useSmartSelection) {
-        validators = await this.router.getValidatorsForStoryWithLLM(story, epic);
-      } else {
-        validators = this.router.getValidatorsForStory(story, epic);
-      }
-
-      // Cache selection in metadata
-      if (!story.metadata) {
-        story.metadata = {};
-      }
+      const validators = this.router.getValidatorsForStory(story, epic);
+      if (!story.metadata) story.metadata = {};
       story.metadata.selectedValidators = validators;
+      perspectives = validators.map(v => this.extractDomain(v));
     }
-
-    console.log(`\n🔍 Validating Story: ${story.name}`);
-    console.log(`   Epic: ${epic.name} (${epic.domain})`);
-    console.log(`   Validators (${validators.length}): ${validators.map(v => this.extractDomain(v)).join(', ')}\n`);
-
-    // Read solver iteration settings
-    const solverConfig = this.validationStageConfig?.solver || {};
-    const maxIterations = solverConfig.maxIterations ?? 3;
-    const acceptanceThreshold = solverConfig.acceptanceThreshold ?? 95;
-
-    await this._detail(`${validators.length} validator${validators.length !== 1 ? 's' : ''}: ${validators.map(v => this.extractDomain(v)).join(', ')}`);
-
-    // Working copy — accumulates improvements from solver runs
-    let workingStory = { ...story };
-
-    // ── Phase 1: run all validators in parallel on the initial snapshot ──────────
-    await this._detail(`Running ${validators.length} validators in parallel…`);
-    console.log(`   Running ${validators.length} validators in parallel…`);
-
-    const _t0Parallel = Date.now();
-    const parallelResults = await Promise.all(
-      validators.map((validatorName, vi) => {
-        const role = this.extractDomain(validatorName);
-        return this._withHeartbeat(
-          () => this.runStoryValidator(workingStory, storyContext, epic, validatorName),
-          (elapsed) => {
-            if (elapsed < 20) return `   [${role}] reviewing story…`;
-            if (elapsed < 40) return `   [${role}] checking acceptance criteria…`;
-            if (elapsed < 60) return `   [${role}] validating scope…`;
-            return `   [${role}] still validating…`;
-          },
-          10000
-        ).catch(err => {
-          console.warn(`   ⚠ Validator ${validatorName} failed: ${err.message.split('\n')[0]}`);
-          return { overallScore: 0, validationStatus: 'error', issues: [], _validatorError: err.message.split('\n')[0] };
-        });
-      })
-    );
-    console.log(`[TIMING] story parallel batch (${validators.length} validators): ${Date.now() - _t0Parallel}ms`);
-
-    // Log all parallel results
-    for (let vi = 0; vi < validators.length; vi++) {
-      const validatorName = validators[vi];
-      const role = this.extractDomain(validatorName);
-      const result = parallelResults[vi];
-      const score = result.overallScore ?? 0;
-      const allIssues = result.issues || [];
-      const critCount = allIssues.filter(i => i.severity === 'critical').length;
-      const majCount  = allIssues.filter(i => i.severity === 'major').length;
-      const acceptable = score >= acceptanceThreshold;
-      const issueStr = allIssues.length > 0 ? ` · ${allIssues.length} issue${allIssues.length !== 1 ? 's' : ''}` : '';
-      await this._detail(`[${vi + 1}/${validators.length}] ${role}: ${score}/100${issueStr} — ${acceptable ? '✓' : '⚠ below threshold'}`);
-      console.log(`   [${vi + 1}/${validators.length}] ${validatorName} score=${score}/100 status=${result.validationStatus} (critical=${critCount} major=${majCount} minor=${allIssues.length - critCount - majCount})`);
-      allIssues.forEach(issue => {
-        const cat = issue.category ? `[${issue.category}] ` : '';
-        const sug = issue.suggestion ? ` → ${issue.suggestion}` : '';
-        console.log(`     [${(issue.severity || 'unknown').toUpperCase()}] ${cat}${issue.description || '(no description)'}${sug}`);
-      });
-    }
-
-    // ── Phase 2: parallel solver rounds ──────────────────────────────────────────
-    const finalResults = [...parallelResults];
-
-    // Indices of validators still below threshold
-    let needsWork = validators.map((_, vi) => vi).filter(vi =>
-      (parallelResults[vi].overallScore ?? 0) < acceptanceThreshold
-    );
-    if (needsWork.length > 0) {
-      console.log(`   ${needsWork.length}/${validators.length} validators below threshold — running parallel solver rounds (max ${maxIterations - 1})`);
-      await this._detail(`${needsWork.length} below threshold — parallel solver rounds`);
-    }
-
-    for (let iter = 1; iter < maxIterations && needsWork.length > 0; iter++) {
-      const roundCount = needsWork.length;
-      await this._detail(`   ↻ Round ${iter}/${maxIterations - 1}: ${roundCount} solver${roundCount !== 1 ? 's' : ''} in parallel…`);
-      console.log(`   ↻ Round ${iter}/${maxIterations - 1}: ${roundCount} solver${roundCount !== 1 ? 's' : ''} running in parallel…`);
-      const _t0Round = Date.now();
-
-      // 1. Run all below-threshold solvers in parallel (all see the same workingStory snapshot)
-      const solverResults = await Promise.all(
-        needsWork.map(vi => {
-          const validatorName = validators[vi];
-          const role = this.extractDomain(validatorName);
-          return this._withHeartbeat(
-            () => this.runStorySolver(workingStory, storyContext, epic, finalResults[vi], validatorName),
-            (elapsed) => {
-              if (elapsed < 25) return `   ↻ ${role} solver — improving story…`;
-              if (elapsed < 50) return `   ↻ ${role} solver — refining acceptance criteria…`;
-              return `   ↻ ${role} solver — still running…`;
-            },
-            20000
-          ).then(improved => ({ vi, improved, error: null }))
-            .catch(err => ({ vi, improved: null, error: err }));
-        })
-      );
-      console.log(`[TIMING] Phase 2 round ${iter} solvers: ${Date.now() - _t0Round}ms`);
-
-      // 2. Merge all solver results — preserve base items, add up to 3 new items per solver
-      // Base items are anchored (never dropped); each solver contributes at most 3 genuinely new AC.
-      // Description taken from the solver whose validator scored lowest (most informed fix).
-      const baseAC = workingStory.acceptance || [];
-      const baseACSet = new Set(baseAC);
-      const newACAdditions = []; // items new beyond base, insertion-ordered, deduplicated
-      const allDeps = new Set(workingStory.dependencies || []);
-      let bestDescription = workingStory.description;
-      let worstValidatorScore = Infinity;
-      let anyImproved = false;
-
-      for (const { vi, improved, error } of solverResults) {
-        const validatorName = validators[vi];
-        const role = this.extractDomain(validatorName);
-        if (error) {
-          console.warn(`   ⚠ Solver failed for ${validatorName}: ${error.message} — keeping current story`);
-          await this._detail(`   ⚠ Solver failed (${role}): ${error.message.split('\n')[0].slice(0, 120)}`);
-          continue;
-        }
-        if (improved && improved.id === workingStory.id) {
-          anyImproved = true;
-          // Collect only new items not already in base or pending additions (max 3 per solver)
-          const existingAll = new Set([...baseACSet, ...newACAdditions]);
-          const solverNew = (improved.acceptance || []).filter(a => !existingAll.has(a)).slice(0, 3);
-          newACAdditions.push(...solverNew);
-          (improved.dependencies || []).forEach(d => allDeps.add(d));
-          // Description: take from the validator with the lowest score (most dissatisfied perspective)
-          const vScore = finalResults[vi]?.overallScore ?? 100;
-          if (improved.description && improved.description !== workingStory.description && vScore < worstValidatorScore) {
-            worstValidatorScore = vScore;
-            bestDescription = improved.description;
-          }
-          console.log(`   ↻ [${role}] solver merged — ${solverNew.length} new AC added`);
-          await this._detail(`   → [${role}] improvements applied`);
-        } else {
-          console.log(`   ↻ [${role}] solver returned no valid improvement (id mismatch or empty)`);
-        }
-      }
-
-      if (anyImproved) {
-        // Base items always preserved first; cap only the additions portion
-        const merged = [...baseAC, ...newACAdditions];
-        const hardCap = baseAC.length + 10; // allow up to 10 new AC beyond original
-        const finalAC = merged.length > hardCap ? merged.slice(0, hardCap) : merged;
-        if (merged.length > hardCap) {
-          console.log(`   ↻ Story AC capped after merge: ${merged.length} → ${hardCap} (base=${baseAC.length} + new=${finalAC.length - baseAC.length})`);
-        }
-        const descBefore = (workingStory.description || '').slice(0, 100);
-        workingStory = {
-          ...workingStory,
-          description:  bestDescription,
-          acceptance:   finalAC,
-          dependencies: [...allDeps],
-        };
-        const descAfter = (workingStory.description || '').slice(0, 100);
-        console.log(`   ↻ Parallel merge applied — desc changed: ${descBefore !== descAfter}, AC: ${finalAC.length} (base=${baseAC.length} + new=${newACAdditions.length})`);
-      }
-
-      // 3. Re-validate all in parallel
-      await this._detail(`   Re-validating ${roundCount} validator${roundCount !== 1 ? 's' : ''} in parallel (iter ${iter + 1})…`);
-      const _t0Revalidate = Date.now();
-      const revalidateResults = await Promise.all(
-        needsWork.map(vi => {
-          const validatorName = validators[vi];
-          const role = this.extractDomain(validatorName);
-          return this._withHeartbeat(
-            () => this.runStoryValidator(workingStory, storyContext, epic, validatorName),
-            (elapsed) => {
-              if (elapsed < 20) return `   [${role}] re-reviewing story…`;
-              if (elapsed < 40) return `   [${role}] re-checking acceptance criteria…`;
-              return `   [${role}] re-validating…`;
-            },
-            10000
-          ).then(result => ({ vi, result, error: null }))
-            .catch(err => ({ vi, result: null, error: err }));
-        })
-      );
-      console.log(`[TIMING] Phase 2 round ${iter} re-validates: ${Date.now() - _t0Revalidate}ms`);
-
-      // 4. Update finalResults; determine which validators need another round
-      const nextNeedsWork = [];
-      for (const { vi, result, error } of revalidateResults) {
-        const validatorName = validators[vi];
-        const role = this.extractDomain(validatorName);
-        if (error) {
-          console.warn(`   ⚠ Re-validator ${validatorName} failed: ${error.message.split('\n')[0]}`);
-          await this._detail(`   ⚠ Re-validate failed (${role}): ${error.message.split('\n')[0].slice(0, 120)}`);
-          continue; // keep finalResults[vi] as-is; give up on this validator
-        }
-        finalResults[vi] = result;
-        const newScore = result.overallScore ?? 0;
-        const acceptable = newScore >= acceptanceThreshold;
-        const issueStr2 = (result.issues || []).length > 0 ? ` · ${result.issues.length} issues` : '';
-        await this._detail(`   [${role}] iter ${iter + 1}: ${newScore}/100${issueStr2} — ${acceptable ? '✓ accepted' : `⚠ below threshold (${acceptanceThreshold})`}`);
-        console.log(`   [${vi + 1}/${validators.length}] ${validatorName} iter=${iter + 1} score=${newScore}/100 status=${result.validationStatus}`);
-        if (!acceptable) {
-          nextNeedsWork.push(vi);
-        }
+    const workItemText = storyContext || this.generateStoryContextMd(story, epic);
+    const mcResult = await validateWithMicroChecks(
+      story, workItemText, 'story', perspectives, this.llmProvider,
+      {
+        concurrency: this.validationStageConfig?.concurrency ?? 5,
+        batchSize: this.validationStageConfig?.batchSize ?? 8,
+        maxFixAttempts: this.validationStageConfig?.maxFixAttempts ?? 3,
+        generateContextFn: (wi) => this.generateStoryContextMd(wi, epic),
+        progressCallback: this.progressCallback,
+        projectRoot: this.projectContext?.projectRoot,
       }
-      console.log(`[TIMING] Phase 2 round ${iter} total: ${Date.now() - _t0Round}ms — ${nextNeedsWork.length} still need work`);
-      needsWork = nextNeedsWork;
-    }
-
-    const validationResults = finalResults;
-
-    // Write accumulated improvements back to the original story object
-    story.description  = workingStory.description;
-    story.acceptance   = workingStory.acceptance;
-    story.dependencies = workingStory.dependencies;
-
-    // 3. Aggregate results
-    const aggregated = this.aggregateValidationResults(validationResults, 'story');
-
-    // 4. Determine overall status
-    aggregated.overallStatus = this.determineOverallStatus(validationResults);
-    aggregated.readyToPublish = aggregated.overallStatus !== 'needs-improvement';
-
-    await this._detail(`Overall: ${aggregated.readyToPublish ? '✓ passed' : '⚠ needs improvement'} · avg ${aggregated.averageScore}/100`);
-    console.log(`   Story "${story.name}" summary: avg=${aggregated.averageScore}/100 readyToPublish=${aggregated.readyToPublish} critical=${aggregated.criticalIssues.length} major=${aggregated.majorIssues.length}`);
-    aggregated.validatorResults.forEach(vr => {
-      console.log(`     ${this.extractDomain(vr.validator)}: ${vr.score}/100 (${vr.status})`);
-    });
-
-    // 5. Store for feedback loop
-    this.storeValidationFeedback(story.id, aggregated);
-
-    // 6. Persist result into story metadata so sprint-planning-processor writes it to work.json
+    );
     story.metadata = story.metadata || {};
     story.metadata.validationResult = {
-      averageScore: aggregated.averageScore,
-      overallStatus: aggregated.overallStatus,
-      readyToPublish: aggregated.readyToPublish,
-      criticalIssues: aggregated.criticalIssues,
-      majorIssues: aggregated.majorIssues,
-      minorIssues: aggregated.minorIssues,
-      validatorResults: aggregated.validatorResults,
-      validatedAt: new Date().toISOString(),
+      averageScore: mcResult.averageScore,
+      overallStatus: mcResult.overallStatus,
+      readyToPublish: mcResult.readyToPublish,
+      criticalIssues: mcResult.criticalIssues,
+      majorIssues: mcResult.majorIssues,
+      minorIssues: mcResult.minorIssues,
+      validatorResults: mcResult.validatorResults,
+      validatedAt: mcResult.validatedAt,
     };
-
-    return aggregated;
+    this.storeValidationFeedback(story.id, mcResult);
+    return mcResult;
   }
 
   /**
-   * Run a single epic validator agent
+   * Build the prompt for the story-splitter agent.
+   * @param {Object} story - The oversized story to split
+   * @param {Object} epic - Parent epic for context
+   * @param {Array} allIssues - MAJOR+CRITICAL issues from all validators
+   * @returns {string}
    * @private
    */
-  async runEpicValidator(epic, epicContext, validatorName) {
-    const agentInstructions = this.loadAgentInstructions(`${validatorName}.md`);
+  _buildStorySplitterPrompt(story, epic, allIssues) {
+    const fullEpicContext = this.generateEpicContextMd(epic);
+    const epicContextMd = fullEpicContext.length > 3000
+      ? fullEpicContext.substring(0, 3000) + '\n… (truncated)'
+      : fullEpicContext;
+    const storyContext = this.generateStoryContextMd(story, epic);
+    const critMajor = allIssues.filter(i => i.severity === 'critical' || i.severity === 'major');
+    const issueText = critMajor.map((issue, i) => {
+      const cat = issue.category ? `[${issue.category}] ` : '';
+      const sug = issue.suggestion ? `\n   Required fix: ${issue.suggestion}` : '';
+      return `${i + 1}. [${(issue.severity || 'major').toUpperCase()}] ${cat}${issue.description || ''}${sug}`;
+    }).join('\n');
 
-    // Build validation prompt
-    const prompt = this.buildEpicValidationPrompt(epic, epicContext);
+    return `# Story to Split
 
-    // Get validator-specific provider based on validation type
-    const provider = await this.getProviderForValidator(validatorName);
+## Parent Epic (canonical)
 
-    // Call LLM with validator agent instructions
-    const _usageBefore = provider.getTokenUsage();
-    const _t0 = Date.now();
-    console.log(`[API-START] ${validatorName} (epic="${epic.name}", promptLen=${prompt.length})`);
-    const rawResult = await provider.generateJSON(prompt, agentInstructions);
-    const _elapsed = Date.now() - _t0;
-    const _usageAfter = provider.getTokenUsage();
-    const _deltaIn = _usageAfter.inputTokens - _usageBefore.inputTokens;
-    const _deltaOut = _usageAfter.outputTokens - _usageBefore.outputTokens;
-    console.log(`[API-DONE] ${validatorName} — ${_elapsed}ms | in=${_deltaIn} out=${_deltaOut} tokens`);
+${epicContextMd}
 
-    // Basic validation of result structure
-    if (!rawResult || typeof rawResult !== 'object') {
-      throw new Error(`Invalid validation result from ${validatorName}: expected object`);
-    }
+## Original Story (too large — ${(story.acceptance || []).length} acceptance criteria)
 
-    // Track validation session
-    if (this.verificationTracker) {
-      this.verificationTracker.recordCheck(validatorName, 'epic-validation', true);
-    }
+${storyContext}
+
+## Validator Issues That Triggered This Split
 
-    // Add metadata
-    rawResult._validatorName = validatorName;
+${issueText || 'Story exceeded the acceptance criteria size limit after multiple validation passes.'}
 
-    return rawResult;
+Split this story into 2-3 smaller independently deliverable stories.
+Return a JSON array of story objects as specified in your instructions.
+`;
   }
 
   /**
-   * Run a single story validator agent
-   * @private
+   * Call the story-splitter agent to decompose an oversized story into 2-3 smaller stories.
+   * Returns an array of 2-3 new story objects, or null if the split failed/produced invalid output.
+   * @param {Object} workingStory - The fully-validated but too-large story
+   * @param {Object} epic - Parent epic for context
+   * @param {Array} allIssues - MAJOR+CRITICAL issues from all validators
+   * @returns {Promise<Array<Object>|null>}
    */
-  async runStoryValidator(story, storyContext, epic, validatorName) {
-    const agentInstructions = this.loadAgentInstructions(`${validatorName}.md`);
+  async _splitStory(workingStory, epic, allIssues) {
+    const agentInstructions = this.loadAgentInstructions('story-splitter.md');
+    const prompt = this._buildStorySplitterPrompt(workingStory, epic, allIssues);
+    const provider = await this.getProviderForValidator('story-splitter');
 
-    // Build validation prompt
-    const prompt = this.buildStoryValidationPrompt(story, storyContext, epic);
-
-    // Get validator-specific provider based on validation type
-    const provider = await this.getProviderForValidator(validatorName);
-
-    // Call LLM with validator agent instructions
     const _usageBefore = provider.getTokenUsage();
     const _t0 = Date.now();
-    console.log(`[API-START] ${validatorName} (story="${story.name}", promptLen=${prompt.length})`);
-    const rawResult = await provider.generateJSON(prompt, agentInstructions);
-    const _elapsed = Date.now() - _t0;
-    const _usageAfter = provider.getTokenUsage();
-    const _deltaIn = _usageAfter.inputTokens - _usageBefore.inputTokens;
-    const _deltaOut = _usageAfter.outputTokens - _usageBefore.outputTokens;
-    console.log(`[API-DONE] ${validatorName} — ${_elapsed}ms | in=${_deltaIn} out=${_deltaOut} tokens`);
-
-    // Basic validation of result structure
-    if (!rawResult || typeof rawResult !== 'object') {
-      throw new Error(`Invalid validation result from ${validatorName}: expected object`);
-    }
+    console.log(`[API-START] story-splitter (story="${workingStory.name}", ACs=${(workingStory.acceptance || []).length})`);
 
-    // Track validation session
-    if (this.verificationTracker) {
-      this.verificationTracker.recordCheck(validatorName, 'story-validation', true);
+    let result;
+    try {
+      result = await this._withHeartbeat(
+        () => provider.generateJSON(prompt, agentInstructions),
+        (elapsed) => {
+          if (elapsed < 20) return `   ✂ splitting story — analyzing scope boundaries…`;
+          if (elapsed < 40) return `   ✂ splitting story — assigning acceptance criteria…`;
+          return `   ✂ splitting story — still running…`;
+        },
+        10000
+      );
+    } catch (err) {
+      console.warn(`   ⚠ story-splitter failed: ${err.message.split('\n')[0]}`);
+      return null;
     }
 
-    // Add metadata
-    rawResult._validatorName = validatorName;
-
-    return rawResult;
-  }
-
-  /**
-   * Run a solver agent to improve an epic based on validation issues
-   * @private
-   */
-  async runEpicSolver(epic, epicContext, validationResult, validatorName) {
-    const role = this.extractDomain(validatorName);
-    const agentInstructions = this.loadAgentInstructions(`solver-epic-${role}.md`);
-    const prompt = this.buildEpicSolverPrompt(epic, epicContext, validationResult, validatorName);
-    const provider = await this.getProviderForSolver(role);
-
-    const _usageBefore = provider.getTokenUsage();
-    const _t0 = Date.now();
-    console.log(`[API-START] solver-epic-${role} (epic="${epic.name}", promptLen=${prompt.length})`);
-    const improved = await provider.generateJSON(prompt, agentInstructions);
     const _elapsed = Date.now() - _t0;
     const _usageAfter = provider.getTokenUsage();
     const _deltaIn = _usageAfter.inputTokens - _usageBefore.inputTokens;
     const _deltaOut = _usageAfter.outputTokens - _usageBefore.outputTokens;
-    console.log(`[API-DONE] solver-epic-${role} — ${_elapsed}ms | in=${_deltaIn} out=${_deltaOut} tokens`);
+    console.log(`[API-DONE] story-splitter — ${_elapsed}ms | in=${_deltaIn} out=${_deltaOut} tokens`);
 
-    if (this.verificationTracker) {
-      this.verificationTracker.recordCheck(`solver-epic-${role}`, 'epic-solving', true);
+    // Validate: result must be an array of 2-3 stories
+    if (!Array.isArray(result) || result.length < 2 || result.length > 3) {
+      console.warn(`   ⚠ story-splitter returned unexpected shape (expected array of 2-3, got ${Array.isArray(result) ? result.length : typeof result}) — skipping split`);
+      return null;
     }
 
-    return improved;
-  }
-
-  /**
-   * Run a solver agent to improve a story based on validation issues
-   * @private
-   */
-  async runStorySolver(story, storyContext, epic, validationResult, validatorName) {
-    const role = this.extractDomain(validatorName);
-    const agentInstructions = this.loadAgentInstructions(`solver-story-${role}.md`);
-    const prompt = this.buildStorySolverPrompt(story, storyContext, epic, validationResult, validatorName);
-    const provider = await this.getProviderForSolver(role);
-
-    const _usageBefore = provider.getTokenUsage();
-    const _t0 = Date.now();
-    console.log(`[API-START] solver-story-${role} (story="${story.name}", promptLen=${prompt.length})`);
-    const improved = await provider.generateJSON(prompt, agentInstructions);
-    const _elapsed = Date.now() - _t0;
-    const _usageAfter = provider.getTokenUsage();
-    const _deltaIn = _usageAfter.inputTokens - _usageBefore.inputTokens;
-    const _deltaOut = _usageAfter.outputTokens - _usageBefore.outputTokens;
-    console.log(`[API-DONE] solver-story-${role} — ${_elapsed}ms | in=${_deltaIn} out=${_deltaOut} tokens`);
+    // Validate each split story has required fields; cap ACs to 8
+    for (const s of result) {
+      if (!s.id || !s.name || !Array.isArray(s.acceptance)) {
+        console.warn(`   ⚠ story-splitter returned malformed story (missing id/name/acceptance) — skipping split`);
+        return null;
+      }
+      if (s.acceptance.length > 8) {
+        s.acceptance = s.acceptance.slice(0, 8);
+      }
+    }
 
     if (this.verificationTracker) {
-      this.verificationTracker.recordCheck(`solver-story-${role}`, 'story-solving', true);
+      this.verificationTracker.recordCheck('story-splitter', 'story-splitting', true);
     }
 
-    return improved;
-  }
-
-  /**
-   * Build solver prompt for an Epic
-   * @private
-   */
-  buildEpicSolverPrompt(epic, epicContext, validationResult, validatorName) {
-    const allIssues = validationResult.issues || [];
-    const critMajor = allIssues.filter(i => i.severity === 'critical' || i.severity === 'major');
-    // When no critical/major issues exist, include minor issues so the solver has specific guidance
-    const issues = critMajor.length > 0 ? critMajor : allIssues;
-
-    const role = this.extractDomain(validatorName);
-
-    const issueText = issues.map((issue, i) =>
-      `${i + 1}. [${issue.severity.toUpperCase()}] ${issue.category}: ${issue.description}\n   Fix: ${issue.suggestion}`
-    ).join('\n');
-
-    return `# Epic to Improve
-
-**Epic ID:** ${epic.id}
-**Epic Name:** ${epic.name}
-**Domain:** ${epic.domain}
-**Current Description:** ${epic.description}
-
-**Current Features:**
-${(epic.features || []).map(f => `- ${f}`).join('\n')}
-
-**Current Dependencies:**
-${(epic.dependencies || []).length > 0 ? epic.dependencies.join(', ') : 'None'}
-
-**Epic Context:**
-\`\`\`
-${epicContext}
-\`\`\`
-
-## Issues to Fix (from ${role} review):
-
-${issueText || 'No critical/major issues — improve overall quality.'}
-
-Improve this Epic to address the issues above. Return the complete improved Epic JSON.
-
-**IMPORTANT CONSTRAINTS:**
-- Do NOT remove or consolidate existing features — only add new ones to address the issues above.
-- Each feature must be a single concise sentence (max 30 words). Do not expand them into paragraphs.
-`;
-  }
-
-  /**
-   * Build solver prompt for a Story
-   * @private
-   */
-  buildStorySolverPrompt(story, storyContext, epic, validationResult, validatorName) {
-    const allIssues = validationResult.issues || [];
-    const critMajor = allIssues.filter(i => i.severity === 'critical' || i.severity === 'major');
-    // When no critical/major issues exist, include minor issues so the solver has specific guidance
-    const issues = critMajor.length > 0 ? critMajor : allIssues;
-
-    const role = this.extractDomain(validatorName);
-
-    const issueText = issues.map((issue, i) =>
-      `${i + 1}. [${issue.severity.toUpperCase()}] ${issue.category}: ${issue.description}\n   Fix: ${issue.suggestion}`
-    ).join('\n');
-
-    return `# Story to Improve
-
-**Story ID:** ${story.id}
-**Story Name:** ${story.name}
-**User Type:** ${story.userType}
-**Current Description:** ${story.description}
-
-**Current Acceptance Criteria:**
-${(story.acceptance || []).map((ac, i) => `${i + 1}. ${ac}`).join('\n')}
-
-**Current Dependencies:**
-${(story.dependencies || []).length > 0 ? story.dependencies.join(', ') : 'None'}
-
-**Parent Epic:**
-- Name: ${epic.name}
-- Domain: ${epic.domain}
-- Features: ${(epic.features || []).join(', ')}
-
-**Story Context:**
-\`\`\`
-${storyContext}
-\`\`\`
-
-## Issues to Fix (from ${role} review):
-
-${issueText || 'No critical/major issues — improve overall quality.'}
-
-Improve this Story to address the issues above. Return the complete improved Story JSON.
-
-**IMPORTANT CONSTRAINTS:**
-- Do NOT remove or consolidate existing acceptance criteria — only add new ones to address the issues above.
-- Each AC must be a single concrete, testable sentence (max 40 words). Do not expand them into paragraphs.
-`;
+    return result;
   }
 
   /**
@@ -967,9 +503,13 @@ Improve this Story to address the issues above. Return the complete improved Sto
       type: type, // 'epic' or 'story'
       validatorCount: results.length,
       validators: results.map(r => r._validatorName),
-      averageScore: Math.round(
-        results.reduce((sum, r) => sum + (r.overallScore || 0), 0) / results.length
-      ),
+      // Exclude errored validators (API failures) from the average — a 0 from a
+      // network failure is not a real score and would corrupt the aggregate.
+      averageScore: (() => {
+        const scorable = results.filter(r => !r._validatorError);
+        if (scorable.length === 0) return 0;
+        return Math.round(scorable.reduce((sum, r) => sum + (r.overallScore || 0), 0) / scorable.length);
+      })(),
 
       // Aggregate issues by severity
       criticalIssues: [],
@@ -1041,6 +581,12 @@ Improve this Story to address the issues above. Return the complete improved Sto
   determineOverallStatus(results) {
     const statuses = results.map(r => r.validationStatus);
 
+    // If any validator errored (API failure), mark as needs-improvement so
+    // readyToPublish stays false — validation is incomplete, not "acceptable"
+    if (statuses.includes('error')) {
+      return 'needs-improvement';
+    }
+
     // If any validator says "needs-improvement", overall is "needs-improvement"
     if (statuses.includes('needs-improvement')) {
       return 'needs-improvement';
@@ -1055,68 +601,6 @@ Improve this Story to address the issues above. Return the complete improved Sto
     return 'acceptable';
   }
 
-  /**
-   * Build validation prompt for Epic
-   * @private
-   */
-  buildEpicValidationPrompt(epic, epicContext) {
-    return `# Epic to Validate
-
-**Epic ID:** ${epic.id}
-**Epic Name:** ${epic.name}
-**Domain:** ${epic.domain}
-**Description:** ${epic.description}
-
-**Features:**
-${(epic.features || []).map(f => `- ${f}`).join('\n')}
-
-**Dependencies:**
-${(epic.dependencies || []).length > 0 ? epic.dependencies.join(', ') : 'None'}
-
-**Stories:**
-${(epic.children || []).length} stories defined
-
-**Epic Context:**
-\`\`\`
-${epicContext}
-\`\`\`
-
-Validate this Epic from your domain expertise perspective and return JSON validation results following the specified format.
-`;
-  }
-
-  /**
-   * Build validation prompt for Story
-   * @private
-   */
-  buildStoryValidationPrompt(story, storyContext, epic) {
-    return `# Story to Validate
-
-**Story ID:** ${story.id}
-**Story Name:** ${story.name}
-**User Type:** ${story.userType}
-**Description:** ${story.description}
-
-**Acceptance Criteria:**
-${(story.acceptance || []).map((ac, i) => `${i + 1}. ${ac}`).join('\n')}
-
-**Dependencies:**
-${(story.dependencies || []).length > 0 ? story.dependencies.join(', ') : 'None'}
-
-**Parent Epic:**
-- Name: ${epic.name}
-- Domain: ${epic.domain}
-- Features: ${(epic.features || []).join(', ')}
-
-**Story Context:**
-\`\`\`
-${storyContext}
-\`\`\`
-
-Validate this Story from your domain expertise perspective and return JSON validation results following the specified format.
-`;
-  }
-
   /**
    * Load agent instructions from .md file
    * @private
@@ -1138,6 +622,7 @@ Validate this Story from your domain expertise perspective and return JSON valid
     // Extract domain from validator/solver name
     // e.g., "validator-epic-security" → "security"
     // e.g., "solver-epic-security" → "security"
+    if (!validatorName) return 'unknown';
     const match = validatorName.match(/(?:validator|solver)-(?:epic|story)-(.+)/);
     return match ? match[1] : 'unknown';
   }