@codexstar/bug-hunter 3.0.0 → 3.0.6

package/scripts/run-bug-hunter.cjs

@@ -3,6 +3,7 @@
 const childProcess = require('child_process');
 const fs = require('fs');
 const path = require('path');
+const { validateArtifactFile, validateArtifactValue } = require('./schema-runtime.cjs');
 
 const BACKEND_PRIORITY = ['spawn_agent', 'subagent', 'teams', 'local-sequential'];
 const DEFAULT_TIMEOUT_MS = 120000;
@@ -17,7 +18,8 @@ const DEFAULT_EXPANSION_CAP = 40;
 function usage() {
   console.error('Usage:');
   console.error('  run-bug-hunter.cjs preflight [--skill-dir <path>] [--available-backends <csv>] [--backend <name>]');
-  console.error('  run-bug-hunter.cjs run --files-json <path> [--mode <name>] [--skill-dir <path>] [--state <path>] [--chunk-size <n>] [--worker-cmd <template>] [--timeout-ms <n>] [--max-retries <n>] [--backoff-ms <n>] [--available-backends <csv>] [--backend <name>] [--fail-fast <true|false>] [--use-index <true|false>] [--index-path <path>] [--delta-mode <true|false>] [--changed-files-json <path>] [--delta-hops <n>] [--expand-on-low-confidence <true|false>] [--confidence-threshold <n>] [--canary-size <n>] [--expansion-cap <n>]');
+  console.error('  run-bug-hunter.cjs run --files-json <path> [--mode <name>] [--skill-dir <path>] [--state <path>] [--chunk-size <n>] [--worker-cmd <template>] [--timeout-ms <n>] [--max-retries <n>] [--backoff-ms <n>] [--available-backends <csv>] [--backend <name>] [--fail-fast <true|false>] [--use-index <true|false>] [--index-path <path>] [--delta-mode <true|false>] [--changed-files-json <path>] [--delta-hops <n>] [--expand-on-low-confidence <true|false>] [--confidence-threshold <n>] [--canary-size <n>] [--expansion-cap <n>] [--strategy-path <path>] [--strategy-markdown-path <path>]');
+  console.error('  run-bug-hunter.cjs phase --artifact <name> --output-path <path> --worker-cmd <template> [--phase-name <name>] [--skill-dir <path>] [--journal-path <path>] [--render-cmd <template>] [--render-output-path <path>] [--timeout-ms <n>] [--render-timeout-ms <n>] [--max-retries <n>] [--backoff-ms <n>]');
   console.error('  run-bug-hunter.cjs plan --files-json <path> [--mode <name>] [--skill-dir <path>] [--chunk-size <n>] [--plan-path <path>]');
 }
 
@@ -114,10 +116,23 @@ function requiredScripts(skillDir) {
   return [
     path.join(skillDir, 'scripts', 'bug-hunter-state.cjs'),
     path.join(skillDir, 'scripts', 'payload-guard.cjs'),
+    path.join(skillDir, 'scripts', 'schema-validate.cjs'),
+    path.join(skillDir, 'scripts', 'schema-runtime.cjs'),
+    path.join(skillDir, 'scripts', 'render-report.cjs'),
     path.join(skillDir, 'scripts', 'fix-lock.cjs'),
     path.join(skillDir, 'scripts', 'doc-lookup.cjs'),
     path.join(skillDir, 'scripts', 'context7-api.cjs'),
-    path.join(skillDir, 'scripts', 'delta-mode.cjs')
+    path.join(skillDir, 'scripts', 'delta-mode.cjs'),
+    path.join(skillDir, 'scripts', 'pr-scope.cjs'),
+    path.join(skillDir, 'schemas', 'findings.schema.json'),
+    path.join(skillDir, 'schemas', 'skeptic.schema.json'),
+    path.join(skillDir, 'schemas', 'referee.schema.json'),
+    path.join(skillDir, 'schemas', 'coverage.schema.json'),
+    path.join(skillDir, 'schemas', 'fix-report.schema.json'),
+    path.join(skillDir, 'schemas', 'fix-plan.schema.json'),
+    path.join(skillDir, 'schemas', 'fix-strategy.schema.json'),
+    path.join(skillDir, 'schemas', 'recon.schema.json'),
+    path.join(skillDir, 'schemas', 'shared.schema.json')
   ];
 }
 
@@ -149,18 +164,38 @@ function runJsonScript(scriptPath, args) {
   return JSON.parse(output);
 }
 
+function runTextScript(scriptPath, args) {
+  const result = childProcess.spawnSync('node', [scriptPath, ...args], {
+    encoding: 'utf8'
+  });
+  if (result.status !== 0) {
+    const stderr = (result.stderr || '').trim();
+    const stdout = (result.stdout || '').trim();
+    throw new Error(stderr || stdout || `Script failed: ${scriptPath}`);
+  }
+  return result.stdout || '';
+}
+
 function appendJournal(logPath, event) {
   ensureDir(path.dirname(logPath));
   const line = JSON.stringify({ at: nowIso(), ...event });
   fs.appendFileSync(logPath, `${line}\n`, 'utf8');
 }
 
+function shellQuote(value) {
+  const stringValue = String(value);
+  if (stringValue.length === 0) {
+    return "''";
+  }
+  return `'${stringValue.replace(/'/g, `'\\''`)}'`;
+}
+
 function fillTemplate(template, variables) {
   return template.replace(/\{([a-zA-Z0-9_]+)\}/g, (match, key) => {
     if (!(key in variables)) {
-      return match;
+      throw new Error(`Unknown template placeholder: ${key}`);
     }
-    return String(variables[key]);
+    return shellQuote(variables[key]);
   });
 }
 
@@ -170,7 +205,8 @@ function sleep(ms) {
 
 function runCommandOnce({ command, timeoutMs }) {
   return new Promise((resolve) => {
-    const child = childProcess.spawn('/bin/zsh', ['-lc', command], {
+    const shell = process.env.SHELL || '/bin/bash';
+    const child = childProcess.spawn(shell, ['-lc', command], {
       stdio: ['ignore', 'pipe', 'pipe']
     });
     let stdout = '';
@@ -213,7 +249,9 @@ async function runWithRetry({
   backoffMs,
   journalPath,
   phase,
-  chunkId
+  chunkId,
+  beforeAttempt,
+  postAttempt
 }) {
   const attempts = maxRetries + 1;
   let lastResult = null;
@@ -227,20 +265,45 @@ async function runWithRetry({
       attempts,
       timeoutMs
     });
+    if (typeof beforeAttempt === 'function') {
+      await beforeAttempt({ attempt });
+    }
     const result = await runCommandOnce({ command, timeoutMs });
-    lastResult = result;
+    let finalResult = result;
+
+    if (finalResult.ok && typeof postAttempt === 'function') {
+      const postAttemptResult = await postAttempt({ attempt });
+      if (!postAttemptResult.ok) {
+        const validationMessage = String(postAttemptResult.errorMessage || 'post-attempt validation failed');
+        appendJournal(journalPath, {
+          event: 'attempt-post-check-failed',
+          phase,
+          chunkId,
+          attempt,
+          errorMessage: validationMessage.slice(0, 500)
+        });
+        finalResult = {
+          ...finalResult,
+          ok: false,
+          stderr: validationMessage
+        };
+      }
+    }
+
     appendJournal(journalPath, {
       event: 'attempt-end',
       phase,
       chunkId,
       attempt,
-      ok: result.ok,
-      code: result.code,
-      timeoutHit: result.timeoutHit,
-      stderr: result.stderr.slice(0, 500)
+      ok: finalResult.ok,
+      code: finalResult.code,
+      timeoutHit: finalResult.timeoutHit,
+      stderr: finalResult.stderr.slice(0, 500)
     });
-    if (result.ok) {
-      return { ok: true, result, attemptsUsed: attempt };
+
+    lastResult = finalResult;
+    if (finalResult.ok) {
+      return { ok: true, result: finalResult, attemptsUsed: attempt };
     }
     if (attempt < attempts) {
       const delayMs = backoffMs * 2 ** (attempt - 1);
@@ -378,8 +441,8 @@ function buildConsistencyReport({ bugLedger, confidenceThreshold }) {
   }
 
   const lowConfidence = bugLedger.filter((entry) => {
-    const confidence = entry.confidence;
-    return confidence === null || confidence === undefined || Number(confidence) < confidenceThreshold;
+    const confidenceScore = entry.confidenceScore;
+    return confidenceScore === null || confidenceScore === undefined || Number(confidenceScore) < confidenceThreshold;
   }).length;
 
   return {
@@ -391,30 +454,69 @@ function buildConsistencyReport({ bugLedger, confidenceThreshold }) {
   };
 }
 
-function buildFixPlan({ bugLedger, confidenceThreshold, canarySize }) {
-  const withConfidence = bugLedger.map((entry) => {
-    const confidenceRaw = entry.confidence;
-    const confidence = Number.isFinite(Number(confidenceRaw)) ? Number(confidenceRaw) : null;
+function buildConflictSets(consistency) {
+  const conflicts = toArray(consistency && consistency.conflicts);
+  const bugIds = new Set();
+  const locations = new Set();
+
+  for (const conflict of conflicts) {
+    if (conflict && conflict.type === 'bug-id-reused' && conflict.bugId) {
+      bugIds.add(String(conflict.bugId));
+    }
+    if (conflict && conflict.type === 'location-claim-conflict' && conflict.location) {
+      locations.add(String(conflict.location));
+    }
+  }
+
+  return { bugIds, locations };
+}
+
+function applyConflictClassification(entry, classification, conflictSets) {
+  const bugId = String(entry.bugId || '').trim();
+  const location = `${entry.file || ''}|${entry.lines || ''}`;
+  const hasConflict = conflictSets.bugIds.has(bugId) || conflictSets.locations.has(location);
+  if (!hasConflict) {
+    return classification;
+  }
+  return {
+    strategy: 'manual-review',
+    executionStage: 'manual-review',
+    autofixEligible: false,
+    reason: 'Consistency conflict requires manual review before any fix is attempted.'
+  };
+}
+
+function buildFixPlan({ bugLedger, confidenceThreshold, canarySize, consistency }) {
+  const conflictSets = buildConflictSets(consistency);
+  const classifiedEntries = bugLedger.map((entry) => {
+    const confidenceRaw = entry.confidenceScore;
+    const confidenceScore = Number.isFinite(Number(confidenceRaw)) ? Number(confidenceRaw) : null;
+    const classification = applyConflictClassification(
+      entry,
+      classifyStrategy({ ...entry, confidenceScore }, confidenceThreshold),
+      conflictSets
+    );
     return {
       ...entry,
-      confidence
+      confidenceScore,
+      ...classification
     };
   });
-  const eligible = withConfidence
-    .filter((entry) => entry.confidence !== null && entry.confidence >= confidenceThreshold)
+  const eligible = classifiedEntries
+    .filter((entry) => entry.autofixEligible === true)
     .sort((left, right) => {
       const severityDiff = severityRank(right.severity) - severityRank(left.severity);
       if (severityDiff !== 0) {
         return severityDiff;
       }
-      const confidenceDiff = (right.confidence || 0) - (left.confidence || 0);
+      const confidenceDiff = (right.confidenceScore || 0) - (left.confidenceScore || 0);
       if (confidenceDiff !== 0) {
         return confidenceDiff;
       }
       return String(left.key).localeCompare(String(right.key));
     });
-  const manualReview = withConfidence
-    .filter((entry) => entry.confidence === null || entry.confidence < confidenceThreshold);
+  const manualReview = classifiedEntries
+    .filter((entry) => entry.autofixEligible !== true);
   const canary = eligible.slice(0, canarySize);
   const rollout = eligible.slice(canarySize);
 
@@ -423,7 +525,7 @@ function buildFixPlan({ bugLedger, confidenceThreshold, canarySize }) {
     confidenceThreshold,
     canarySize,
     totals: {
-      findings: withConfidence.length,
+      findings: classifiedEntries.length,
       eligible: eligible.length,
       canary: canary.length,
       rollout: rollout.length,
@@ -435,6 +537,431 @@ function buildFixPlan({ bugLedger, confidenceThreshold, canarySize }) {
   };
 }
 
+function classifyStrategy(entry, confidenceThreshold) {
+  const confidenceScore = Number.isFinite(Number(entry.confidenceScore)) ? Number(entry.confidenceScore) : null;
+  const claim = String(entry.claim || '').toLowerCase();
+  const crossReferences = toArray(entry.crossReferences);
+  const architecturalSignals = ['architecture', 'migration', 'schema', 'contract', 'signature', 'protocol'];
+  const refactorSignals = ['refactor', 'transaction', 'concurrency', 'race', 'lock ordering'];
+
+  if (confidenceScore === null || confidenceScore < confidenceThreshold) {
+    return {
+      strategy: 'manual-review',
+      executionStage: 'manual-review',
+      autofixEligible: false,
+      reason: 'Confidence is below the autofix threshold.'
+    };
+  }
+
+  if (architecturalSignals.some((signal) => claim.includes(signal)) || crossReferences.length >= 3) {
+    return {
+      strategy: 'architectural-remediation',
+      executionStage: 'report-only',
+      autofixEligible: false,
+      reason: 'Claim spans broader contracts or architecture boundaries.'
+    };
+  }
+
+  if (refactorSignals.some((signal) => claim.includes(signal)) || severityRank(entry.severity) >= 2 && crossReferences.length >= 2) {
+    return {
+      strategy: 'larger-refactor',
+      executionStage: 'manual-review',
+      autofixEligible: false,
+      reason: 'Fix likely needs coordinated multi-file changes beyond a surgical patch.'
+    };
+  }
+
+  return {
+    strategy: 'safe-autofix',
+    executionStage: severityRank(entry.severity) >= 2 ? 'canary' : 'rollout',
+    autofixEligible: true,
+    reason: 'Finding is localized enough for a guarded surgical fix.'
+  };
+}
+
+function recommendedActionForStrategy(strategy) {
+  if (strategy === 'architectural-remediation') {
+    return 'Do not auto-edit. Capture a remediation design and schedule a broader change.';
+  }
+  if (strategy === 'larger-refactor') {
+    return 'Pause before patching. Review interfaces, callers, and rollback scope with a human.';
+  }
+  if (strategy === 'manual-review') {
+    return 'Keep this in the report and require human approval before any edits.';
+  }
+  return 'Proceed through the guarded fix pipeline with canary verification and rollback safety.';
+}
+
+function buildFixStrategy({ bugLedger, confidenceThreshold, consistency }) {
+  const conflictSets = buildConflictSets(consistency);
+  const normalized = bugLedger.map((entry) => {
+    const confidenceScore = Number.isFinite(Number(entry.confidenceScore)) ? Number(entry.confidenceScore) : null;
+    const classification = applyConflictClassification(
+      entry,
+      classifyStrategy({ ...entry, confidenceScore }, confidenceThreshold),
+      conflictSets
+    );
+    const filePath = String(entry.file || '').trim() || 'unknown-file';
+    const clusterDir = path.dirname(filePath);
+    const clusterSeed = `${classification.strategy}|${classification.executionStage}|${clusterDir}`;
+    return {
+      ...entry,
+      confidenceScore,
+      file: filePath,
+      clusterDir,
+      clusterSeed,
+      ...classification
+    };
+  });
+
+  const byCluster = new Map();
+  for (const entry of normalized) {
+    if (!byCluster.has(entry.clusterSeed)) {
+      byCluster.set(entry.clusterSeed, []);
+    }
+    byCluster.get(entry.clusterSeed).push(entry);
+  }
+
+  const clusters = [...byCluster.entries()].map(([clusterSeed, entries], index) => {
+    const strategy = entries[0].strategy;
+    const executionStage = entries[0].executionStage;
+    const files = [...new Set(entries.map((entry) => entry.file))].sort();
+    const bugIds = [...new Set(entries.map((entry) => String(entry.bugId || entry.key || '').trim()).filter(Boolean))];
+    const maxSeverity = entries
+      .map((entry) => entry.severity)
+      .sort((left, right) => severityRank(right) - severityRank(left))[0] || 'LOW';
+    const reasons = [...new Set(entries.map((entry) => entry.reason).filter(Boolean))];
+    const firstDir = entries[0].clusterDir || path.dirname(files[0] || 'unknown-file');
+    return {
+      clusterId: `cluster-${index + 1}`,
+      strategy,
+      executionStage,
+      autofixEligible: entries.every((entry) => entry.autofixEligible),
+      bugIds,
+      files,
+      maxSeverity,
+      summary: `${bugIds.length} bug(s) in ${firstDir || '.'} classified as ${strategy}.`,
+      recommendedAction: recommendedActionForStrategy(strategy),
+      reasons
+    };
+  }).sort((left, right) => {
+    const stageRank = {
+      canary: 0,
+      rollout: 1,
+      'manual-review': 2,
+      'report-only': 3
+    };
+    const stageDiff = stageRank[left.executionStage] - stageRank[right.executionStage];
+    if (stageDiff !== 0) {
+      return stageDiff;
+    }
+    return severityRank(right.maxSeverity) - severityRank(left.maxSeverity);
+  });
+
+  const summary = {
+    confirmed: normalized.length,
+    safeAutofix: normalized.filter((entry) => entry.strategy === 'safe-autofix').length,
+    manualReview: normalized.filter((entry) => entry.strategy === 'manual-review').length,
+    largerRefactor: normalized.filter((entry) => entry.strategy === 'larger-refactor').length,
+    architecturalRemediation: normalized.filter((entry) => entry.strategy === 'architectural-remediation').length,
+    canaryCandidates: normalized.filter((entry) => entry.executionStage === 'canary').length,
+    rolloutCandidates: normalized.filter((entry) => entry.executionStage === 'rollout').length
+  };
+
+  return {
+    version: '3.1.0',
+    generatedAt: nowIso(),
+    confidenceThreshold,
+    summary,
+    clusters
+  };
+}
+
+function toCoverageStatus(chunkStatus) {
+  if (chunkStatus === 'done') {
+    return 'done';
+  }
+  if (chunkStatus === 'in_progress') {
+    return 'in_progress';
+  }
+  if (chunkStatus === 'failed') {
+    return 'failed';
+  }
+  return 'pending';
+}
+
+function buildCoverageArtifact({ state, fixPlan }) {
+  const fileEntries = toArray(state.chunks).flatMap((chunk) => {
+    return toArray(chunk.files).map((filePath) => {
+      return {
+        path: String(filePath),
+        status: toCoverageStatus(chunk.status)
+      };
+    });
+  });
+
+  const bugs = toArray(state.bugLedger).map((entry) => {
+    return {
+      bugId: String(entry.bugId || '').trim() || String(entry.key || '').trim(),
+      severity: String(entry.severity || 'Low'),
+      file: String(entry.file || '').trim(),
+      claim: String(entry.claim || '').trim()
+    };
+  });
+
+  const fixStatusByBugId = new Map();
+  for (const entry of toArray(fixPlan && fixPlan.canary)) {
+    fixStatusByBugId.set(String(entry.bugId || '').trim(), 'CANARY');
+  }
+  for (const entry of toArray(fixPlan && fixPlan.rollout)) {
+    fixStatusByBugId.set(String(entry.bugId || '').trim(), 'ROLLOUT');
+  }
+  for (const entry of toArray(fixPlan && fixPlan.manualReview)) {
+    fixStatusByBugId.set(String(entry.bugId || '').trim(), 'MANUAL_REVIEW');
+  }
+
+  const fixes = [...fixStatusByBugId.entries()]
+    .filter(([bugId]) => Boolean(bugId))
+    .map(([bugId, status]) => {
+      return {
+        bugId,
+        status
+      };
+    });
+
+  const hasOpenChunks = toArray(state.chunks).some((chunk) => chunk.status !== 'done');
+
+  return {
+    schemaVersion: 1,
+    iteration: 1,
+    status: hasOpenChunks ? 'IN_PROGRESS' : 'COMPLETE',
+    files: fileEntries,
+    bugs,
+    fixes
+  };
+}
+
+function renderCoverageMarkdown(coverage) {
+  const lines = [
+    '# Bug Hunter Coverage',
+    '',
+    `- Status: ${coverage.status}`,
+    `- Iteration: ${coverage.iteration}`,
+    `- Files: ${coverage.files.length}`,
+    `- Bugs: ${coverage.bugs.length}`,
+    `- Fix entries: ${coverage.fixes.length}`,
+    '',
+    '## Files'
+  ];
+
+  if (coverage.files.length === 0) {
+    lines.push('- None');
+  } else {
+    for (const entry of coverage.files) {
+      lines.push(`- ${entry.status} | ${entry.path}`);
+    }
+  }
+
+  lines.push('', '## Bugs');
+  if (coverage.bugs.length === 0) {
+    lines.push('- None');
+  } else {
+    for (const bug of coverage.bugs) {
+      lines.push(`- ${bug.bugId} | ${bug.severity} | ${bug.file} | ${bug.claim}`);
+    }
+  }
+
+  lines.push('', '## Fixes');
+  if (coverage.fixes.length === 0) {
+    lines.push('- None');
+  } else {
+    for (const fix of coverage.fixes) {
+      lines.push(`- ${fix.bugId} | ${fix.status}`);
+    }
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+function validateFindingsArtifact(findingsJsonPath) {
+  if (!fs.existsSync(findingsJsonPath)) {
+    return {
+      ok: false,
+      errors: [`Missing findings artifact: ${findingsJsonPath}`]
+    };
+  }
+  return validateArtifactFile({
+    artifactName: 'findings',
+    filePath: findingsJsonPath
+  });
+}
+
+function validateNamedArtifact({ artifactName, filePath }) {
+  if (!fs.existsSync(filePath)) {
+    return {
+      ok: false,
+      errors: [`Missing ${artifactName} artifact: ${filePath}`]
+    };
+  }
+  return validateArtifactFile({
+    artifactName,
+    filePath
+  });
+}
+
+function removeFileIfExists(filePath) {
+  if (!filePath) {
+    return;
+  }
+  if (fs.existsSync(filePath)) {
+    fs.unlinkSync(filePath);
+  }
+}
+
+async function runPhase(options) {
+  const artifact = String(options.artifact || '').trim();
+  if (!artifact) {
+    throw new Error('--artifact is required for phase command');
+  }
+  if (!options['output-path']) {
+    throw new Error('--output-path is required for phase command');
+  }
+  if (!options['worker-cmd']) {
+    throw new Error('--worker-cmd is required for phase command');
+  }
+
+  const skillDir = resolveSkillDir(options);
+  const preflightResult = preflight(options);
+  if (!preflightResult.ok) {
+    throw new Error(`Missing helper scripts: ${preflightResult.missing.join(', ')}`);
+  }
+
+  const phaseName = options['phase-name'] || artifact;
+  const outputPath = path.resolve(options['output-path']);
+  const renderOutputPath = options['render-output-path']
+    ? path.resolve(options['render-output-path'])
+    : null;
+  const workerCmdTemplate = options['worker-cmd'];
+  const renderCmdTemplate = options['render-cmd'] || null;
+  const timeoutMs = toPositiveInt(options['timeout-ms'], DEFAULT_TIMEOUT_MS);
+  const renderTimeoutMs = toPositiveInt(options['render-timeout-ms'], timeoutMs);
+  const maxRetries = toPositiveInt(options['max-retries'], DEFAULT_MAX_RETRIES);
+  const backoffMs = toPositiveInt(options['backoff-ms'], DEFAULT_BACKOFF_MS);
+  const journalPath = path.resolve(
+    options['journal-path'] || path.join(path.dirname(outputPath), `${phaseName}.log`)
+  );
+  const templateVariables = {
+    artifact,
+    outputPath,
+    outputFilePath: outputPath,
+    renderOutputPath: renderOutputPath || '',
+    journalPath,
+    phaseName,
+    skillDir
+  };
+
+  ensureDir(path.dirname(outputPath));
+  if (renderOutputPath) {
+    ensureDir(path.dirname(renderOutputPath));
+  }
+  removeFileIfExists(outputPath);
+  removeFileIfExists(renderOutputPath);
+
+  appendJournal(journalPath, {
+    event: 'phase-start',
+    artifact,
+    phase: phaseName,
+    outputPath,
+    renderOutputPath
+  });
+
+  const workerCommand = fillTemplate(workerCmdTemplate, templateVariables);
+  const runResult = await runWithRetry({
+    command: workerCommand,
+    timeoutMs,
+    maxRetries,
+    backoffMs,
+    journalPath,
+    phase: phaseName,
+    chunkId: artifact,
+    beforeAttempt: async () => {
+      removeFileIfExists(outputPath);
+      removeFileIfExists(renderOutputPath);
+    },
+    postAttempt: async () => {
+      const validation = validateNamedArtifact({
+        artifactName: artifact,
+        filePath: outputPath
+      });
+      if (validation.ok) {
+        return { ok: true };
+      }
+      return {
+        ok: false,
+        errorMessage: validation.errors.join('; ')
+      };
+    }
+  });
+
+  if (!runResult.ok) {
+    const errorMessage = (runResult.result && runResult.result.stderr) || `${phaseName} failed`;
+    appendJournal(journalPath, {
+      event: 'phase-failed',
+      artifact,
+      phase: phaseName,
+      errorMessage: errorMessage.slice(0, 500)
+    });
+    throw new Error(errorMessage);
+  }
+
+  if (renderCmdTemplate) {
+    const renderCommand = fillTemplate(renderCmdTemplate, templateVariables);
+    appendJournal(journalPath, {
+      event: 'phase-render-start',
+      artifact,
+      phase: phaseName,
+      renderOutputPath
+    });
+    const renderResult = await runCommandOnce({
+      command: renderCommand,
+      timeoutMs: renderTimeoutMs
+    });
+    if (!renderResult.ok) {
+      const renderError = renderResult.stderr || renderResult.stdout || `${phaseName} render failed`;
+      appendJournal(journalPath, {
+        event: 'phase-render-failed',
+        artifact,
+        phase: phaseName,
+        errorMessage: renderError.slice(0, 500)
+      });
+      throw new Error(renderError);
+    }
+    appendJournal(journalPath, {
+      event: 'phase-render-end',
+      artifact,
+      phase: phaseName,
+      renderOutputPath
+    });
+  }
+
+  appendJournal(journalPath, {
+    event: 'phase-end',
+    artifact,
+    phase: phaseName,
+    attemptsUsed: runResult.attemptsUsed
+  });
+
+  return {
+    ok: true,
+    artifact,
+    phase: phaseName,
+    outputPath,
+    renderOutputPath,
+    journalPath,
+    attemptsUsed: runResult.attemptsUsed
+  };
+}
+
 function loadIndex(indexPath) {
   if (!indexPath || !fs.existsSync(indexPath)) {
     return null;
@@ -513,7 +1040,21 @@ async function processPendingChunks({
       backoffMs,
       journalPath,
       phase: 'chunk-worker',
-      chunkId: chunk.id
+      chunkId: chunk.id,
+      beforeAttempt: async () => {
+        removeFileIfExists(findingsJsonPath);
+        removeFileIfExists(factsJsonPath);
+      },
+      postAttempt: async () => {
+        const findingsValidation = validateFindingsArtifact(findingsJsonPath);
+        if (findingsValidation.ok) {
+          return { ok: true };
+        }
+        return {
+          ok: false,
+          errorMessage: findingsValidation.errors.join('; ')
+        };
+      }
     });
 
     if (!runResult.ok) {
@@ -531,10 +1072,8 @@ async function processPendingChunks({
     }
 
     let findings = [];
-    if (fs.existsSync(findingsJsonPath)) {
-      runJsonScript(stateScript, ['record-findings', statePath, findingsJsonPath, 'orchestrator']);
-      findings = readJson(findingsJsonPath);
-    }
+    runJsonScript(stateScript, ['record-findings', statePath, findingsJsonPath, 'orchestrator']);
+    findings = readJson(findingsJsonPath);
 
     if (fs.existsSync(factsJsonPath)) {
       runJsonScript(stateScript, ['record-fact-card', statePath, chunk.id, factsJsonPath]);
@@ -662,6 +1201,10 @@ async function runPipeline(options) {
   const chunksDir = path.resolve(path.dirname(statePath), 'chunks');
   const consistencyReportPath = path.resolve(options['consistency-report'] || path.join(path.dirname(statePath), 'consistency.json'));
   const fixPlanPath = path.resolve(options['fix-plan-path'] || path.join(path.dirname(statePath), 'fix-plan.json'));
+  const strategyPath = path.resolve(options['strategy-path'] || path.join(path.dirname(statePath), 'fix-strategy.json'));
+  const strategyMarkdownPath = path.resolve(options['strategy-markdown-path'] || path.join(path.dirname(statePath), 'fix-strategy.md'));
+  const coveragePath = path.resolve(options['coverage-path'] || path.join(path.dirname(statePath), 'coverage.json'));
+  const coverageMarkdownPath = path.resolve(options['coverage-markdown-path'] || path.join(path.dirname(statePath), 'coverage.md'));
   const factsPath = path.resolve(options['facts-path'] || path.join(path.dirname(statePath), 'bug-hunter-facts.json'));
   ensureDir(chunksDir);
 
@@ -709,7 +1252,7 @@ async function runPipeline(options) {
     const state = readJson(statePath);
     const lowConfidenceFiles = normalizeFiles(state.bugLedger
       .filter((entry) => {
-        return entry.confidence === null || entry.confidence === undefined || Number(entry.confidence) < confidenceThreshold;
+        return entry.confidenceScore === null || entry.confidenceScore === undefined || Number(entry.confidenceScore) < confidenceThreshold;
       })
       .map((entry) => entry.file));
     if (lowConfidenceFiles.length > 0 && scope.indexPath) {
@@ -773,14 +1316,96 @@ async function runPipeline(options) {
   writeJson(consistencyReportPath, consistency);
   runJsonScript(stateScript, ['set-consistency', statePath, consistencyReportPath]);
 
+  const hasOpenOrFailedChunks = (status.summary.chunkStatus.pending || 0) > 0
+    || (status.summary.chunkStatus.inProgress || 0) > 0
+    || (status.summary.chunkStatus.failed || 0) > 0;
+
+  if (hasOpenOrFailedChunks) {
+    appendJournal(journalPath, {
+      event: 'fix-planning-skipped',
+      reason: 'incomplete-or-failed-chunks',
+      chunkStatus: status.summary.chunkStatus
+    });
+
+    return {
+      ok: true,
+      backend,
+      journalPath,
+      statePath,
+      indexPath: scope.indexPath,
+      deltaMode: scope.deltaMode,
+      deltaSummary: scope.deltaResult ? {
+        selectedCount: (scope.deltaResult.selected || []).length,
+        expansionCandidatesCount: (scope.deltaResult.expansionCandidates || []).length
+      } : null,
+      consistencyReportPath,
+      strategyPath: null,
+      strategyMarkdownPath: null,
+      fixPlanPath: null,
+      coveragePath: null,
+      coverageMarkdownPath: null,
+      factsPath,
+      status: status.summary,
+      consistency: {
+        conflicts: consistency.conflicts.length,
+        lowConfidenceFindings: consistency.lowConfidenceFindings
+      },
+      fixStrategy: null,
+      fixPlan: null
+    };
+  }
+
+  const fixStrategy = buildFixStrategy({
+    bugLedger: toArray(finalState.bugLedger),
+    confidenceThreshold,
+    consistency
+  });
+  const fixStrategyValidation = validateArtifactValue({
+    artifactName: 'fix-strategy',
+    value: fixStrategy
+  });
+  if (!fixStrategyValidation.ok) {
+    throw new Error(`Generated invalid fix strategy artifact: ${fixStrategyValidation.errors.join('; ')}`);
+  }
+  writeJson(strategyPath, fixStrategy);
+  ensureDir(path.dirname(strategyMarkdownPath));
+  fs.writeFileSync(
+    strategyMarkdownPath,
+    runTextScript(path.join(skillDir, 'scripts', 'render-report.cjs'), ['fix-strategy', strategyPath]),
+    'utf8'
+  );
+
   const fixPlan = buildFixPlan({
     bugLedger: toArray(finalState.bugLedger),
     confidenceThreshold,
-    canarySize
+    canarySize,
+    consistency
   });
+  const fixPlanValidation = validateArtifactValue({
+    artifactName: 'fix-plan',
+    value: fixPlan
+  });
+  if (!fixPlanValidation.ok) {
+    throw new Error(`Generated invalid fix plan artifact: ${fixPlanValidation.errors.join('; ')}`);
+  }
   writeJson(fixPlanPath, fixPlan);
   runJsonScript(stateScript, ['set-fix-plan', statePath, fixPlanPath]);
 
+  const coverage = buildCoverageArtifact({
+    state: finalState,
+    fixPlan
+  });
+  const coverageValidation = validateArtifactValue({
+    artifactName: 'coverage',
+    value: coverage
+  });
+  if (!coverageValidation.ok) {
+    throw new Error(`Generated invalid coverage artifact: ${coverageValidation.errors.join('; ')}`);
+  }
+  writeJson(coveragePath, coverage);
+  ensureDir(path.dirname(coverageMarkdownPath));
+  fs.writeFileSync(coverageMarkdownPath, renderCoverageMarkdown(coverage), 'utf8');
+
   writeJson(factsPath, finalState.factCards || {});
 
   appendJournal(journalPath, {
@@ -802,13 +1427,18 @@ async function runPipeline(options) {
       expansionCandidatesCount: (scope.deltaResult.expansionCandidates || []).length
     } : null,
     consistencyReportPath,
+    strategyPath,
+    strategyMarkdownPath,
     fixPlanPath,
+    coveragePath,
+    coverageMarkdownPath,
     factsPath,
     status: status.summary,
     consistency: {
       conflicts: consistency.conflicts.length,
       lowConfidenceFindings: consistency.lowConfidenceFindings
     },
+    fixStrategy: fixStrategy.summary,
     fixPlan: fixPlan.totals
   };
 }
@@ -835,6 +1465,12 @@ async function main() {
     return;
   }
 
+  if (command === 'phase') {
+    const result = await runPhase(options);
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
   if (command === 'plan') {
     if (!options['files-json']) {
       throw new Error('--files-json is required for plan command');