aiwcli 0.12.1 → 0.12.2

package/dist/templates/cc-native/_cc-native/lib-ts/artifacts.ts

@@ -1,823 +1,21 @@
 /**
  * Review artifact writing and formatting.
- * See cc-native-plan-review-spec.md §4.3
- */
-
-import * as fs from "node:fs";
-import * as path from "node:path";
-
-import { ENABLE_ROBUST_PLAN_WRITES } from "./constants.js";
-import type {
-  CombinedReviewResult,
-  ReviewerResult,
-  DisplaySettings,
-  CorroborationResult,
-} from "./types.js";
-import { DEFAULT_DISPLAY } from "./types.js";
-import { atomicWrite } from "../../_shared/lib-ts/base/atomic-write.js";
-import { sanitizeFilename } from "../../_shared/lib-ts/base/constants.js";
-import { logDebug, logWarn, logError } from "../../_shared/lib-ts/base/logger.js";
-import { nowIso } from "../../_shared/lib-ts/base/utils.js";
-
-// ---------------------------------------------------------------------------
-// Markdown Formatting
-// ---------------------------------------------------------------------------
-
-/**
- * Format review results as markdown (legacy compat format).
- */
-export function formatReviewMarkdown(
-  results: ReviewerResult[],
-  overall: string,
-  title = "CC-Native Plan Review",
-  settings?: Record<string, unknown>,
-): string {
-  const display = resolveDisplay(settings);
-
-  const lines: string[] = [];
-  lines.push(`# ${title}\n`);
-  lines.push(`**Overall verdict:** \`${overall.toUpperCase()}\`\n`);
-
-  for (const r of results) {
-    const displayName = r.name === r.name.toLowerCase() ? titleCase(r.name) : r.name;
-    lines.push(`## ${displayName}\n`);
-    lines.push(`- ok: \`${r.ok}\``);
-    lines.push(`- verdict: \`${r.verdict}\``);
-
-    if (r.data && Object.keys(r.data).length > 0) {
-      const summary = String(r.data.summary ?? "").trim();
-      if (r.data.summary_source === "default") {
-        lines.push(`- summary: ⚠️ ${summary} *(reviewer did not return summary)*`);
-      } else {
-        lines.push(`- summary: ${summary}`);
-      }
-      appendReviewDetails(lines, r.data, display);
-    } else {
-      lines.push(`- note: ${r.err || "no structured output"}`);
-    }
-    lines.push("");
-  }
-
-  return lines.join("\n").trim() + "\n";
-}
-
-/**
- * Format combined review result as a single markdown document.
- */
-export function formatCombinedMarkdown(
-  result: CombinedReviewResult,
-  settings?: Record<string, unknown>,
-  corroboration?: CorroborationResult,
-): string {
-  const display = resolveDisplay(settings);
-
-  const lines: string[] = [];
-  lines.push("# CC-Native Plan Review\n");
-  lines.push(`**Overall Verdict:** \`${result.overall_verdict.toUpperCase()}\``);
-  lines.push(`**Plan Hash:** \`${result.plan_hash}\`\n`);
-
-  // Corroboration summary
-  if (corroboration) {
-    lines.push("## Corroboration Analysis\n");
-    if (corroboration.blocking.length > 0) {
-      lines.push("### Blocking Dimensions\n");
-      for (const group of corroboration.blocking) {
-        lines.push(`- **${group.dimension}**: ${group.issues.length} issues from ${group.agentCount} agents (threshold: ≥${group.threshold})`);
-      }
-      lines.push("");
-    }
-    if (corroboration.solo.length > 0) {
-      lines.push("### Solo Dimensions (informational)\n");
-      for (const s of corroboration.solo) {
-        lines.push(`- **${s.dimension}**: ${s.issues.length} issues from ${s.agentCount} agents (threshold: >${s.threshold}, not exceeded)`);
-      }
-      lines.push("");
-    }
-    if (corroboration.unclassified.length > 0) {
-      lines.push(`> ${corroboration.unclassified.length} issue(s) without dimension classification (unclassified, not blocking)\n`);
-    }
-  }
-
-  lines.push("---\n");
-
-  // Orchestration section
-  if (result.orchestration) {
-    lines.push("---\n");
-    lines.push("## Orchestration\n");
-    lines.push(`- **Complexity:** \`${result.orchestration.complexity}\``);
-    lines.push(`- **Category:** \`${result.orchestration.category}\``);
-    const agentsStr =
-      result.orchestration.selected_agents.length > 0
-        ? result.orchestration.selected_agents.join(", ")
-        : "None";
-    lines.push(`- **Agents Selected:** ${agentsStr}`);
-    lines.push(`- **Reasoning:** ${result.orchestration.reasoning}`);
-    if (result.orchestration.skip_reason) {
-      lines.push(`- **Skip Reason:** ${result.orchestration.skip_reason}`);
-    }
-    if (result.orchestration.error) {
-      lines.push(`- **Error:** ${result.orchestration.error}`);
-    }
-    lines.push("");
-  }
-
-  // Agent Reviews section
-  if (Object.keys(result.agents).length > 0) {
-    lines.push("---\n");
-    lines.push("## Agent Reviews\n");
-    for (const [name, r] of Object.entries(result.agents)) {
-      lines.push(`### ${name}\n`);
-      lines.push(`- verdict: \`${r.verdict}\``);
-      if (r.data && Object.keys(r.data).length > 0) {
-        appendSummaryLine(lines, r.data);
-        appendReviewDetails(lines, r.data, display);
-      } else if (r.err) {
-        lines.push(`- error: ${r.err}`);
-      }
-      lines.push("");
-    }
-  }
-
-  return lines.join("\n").trim() + "\n";
-}
-
-// ---------------------------------------------------------------------------
-// Inline Summaries
-// ---------------------------------------------------------------------------
-
-/**
- * Build compact inline summary of HIGH-severity findings for additionalContext.
- * When corroboration data is provided, annotates issues as [CORROBORATED] or [perspective].
- */
-export function buildInlineReviewSummary(
-  combined: CombinedReviewResult,
-  maxIssues = 5,
-  maxChars = 800,
-  corroboration?: CorroborationResult,
-): string {
-  const allReviewers = Object.values(combined.agents);
-
-  // Build set of blocking dimensions for annotation
-  const blockingDims = new Set(
-    corroboration?.blocking.map(g => g.dimension) ?? [],
-  );
-
-  const highIssues: Array<Record<string, unknown>> = [];
-  for (const r of allReviewers) {
-    if (!r.data) continue;
-    const issues = r.data.issues as Array<Record<string, unknown>> | undefined;
-    if (!issues) continue;
-    for (const issue of issues) {
-      if (issue.severity === "high") {
-        highIssues.push({ ...issue, _reviewer: r.name });
-      }
-    }
-  }
-
-  const parts: string[] = [];
-
-  // Overall verdict line
-  const issueCount = highIssues.length;
-  const countSuffix =
-    issueCount > 0
-      ? ` (${issueCount} high-severity issue${issueCount !== 1 ? "s" : ""})`
-      : "";
-  parts.push(`**Plan Review: ${combined.overall_verdict.toUpperCase()}**${countSuffix}`);
-
-  // Corroboration summary if available
-  if (corroboration) {
-    const blockCount = corroboration.blocking.length;
-    const soloCount = corroboration.solo.length;
-    if (blockCount > 0) {
-      parts.push(`**Corroboration:** ${blockCount} dimension${blockCount !== 1 ? "s" : ""} exceeded threshold (blocking), ${soloCount} solo (informational)`);
-    } else {
-      parts.push(`**Corroboration:** No dimensions exceeded threshold — all ${soloCount} solo (informational)`);
-    }
-  }
-
-  // High-severity issue bullets
-  for (const issue of highIssues.slice(0, maxIssues)) {
-    const cat = (issue.category as string) ?? "general";
-    const text = (issue.issue as string) ?? "";
-    const fix = (issue.suggested_fix as string) ?? "";
-    const reviewer = (issue._reviewer as string) ?? "unknown";
-    const dim = issue.dimension as string | undefined;
-
-    let annotation = "";
-    if (corroboration && dim) {
-      const group = corroboration.blocking.find(g => g.dimension === dim);
-      if (group) {
-        annotation = ` [CORROBORATED — ${group.issues.length} issues from ${group.agentCount} agents exceeds threshold ${group.threshold}]`;
-      } else {
-        annotation = " [perspective]";
-      }
-    }
-
-    let line = `- [${cat}] ${text}`;
-    if (fix) line += ` \u2192 ${fix}`;
-    line += ` (${reviewer})${annotation}`;
-    parts.push(line);
-  }
-
-  const remaining = highIssues.length - maxIssues;
-  if (remaining > 0) {
-    parts.push(`  ...and ${remaining} more`);
-  }
-
-  let result = parts.join("\n");
-  if (result.length > maxChars) {
-    result = result.slice(0, maxChars - 3) + "...";
-  }
-  return result;
-}
-
-/**
- * Extract top issues as compact text for permissionDecisionReason.
- */
-export function extractTopIssuesText(
-  combined: CombinedReviewResult,
-  maxCount = 3,
-  severity = "high",
-): string {
-  const allReviewers = Object.values(combined.agents);
-
-  const issues: string[] = [];
-  for (const r of allReviewers) {
-    if (!r.data) continue;
-    const issueList = r.data.issues as Array<Record<string, unknown>> | undefined;
-    if (!issueList) continue;
-    for (const issue of issueList) {
-      if (issue.severity === severity) {
-        const text = String(issue.issue ?? "").trim();
-        if (text) {
-          issues.push(`[${r.name}] ${text}`);
-          break; // first high issue per reviewer only
-        }
-      }
-    }
-    if (issues.length >= maxCount) break;
-  }
-
-  if (issues.length === 0) return "Review found critical issues";
-  return issues.join("; ");
-}
-
-/**
- * Build markdown document containing high-severity issues.
- * When corroboration data is provided, only includes corroborated (blocking) issues.
- */
-export function buildHighIssuesDocument(
-  combined: CombinedReviewResult,
-  corroboration?: CorroborationResult,
-): string {
-  // When corroboration is available, only show blocking groups
-  if (corroboration && corroboration.blocking.length > 0) {
-    const lines = ["# Corroborated High-Severity Issues\n"];
-    lines.push("> Only issues from dimensions where the total count exceeded the proportional threshold are shown.\n");
-
-    for (const group of corroboration.blocking) {
-      lines.push(`## ${group.dimension} (${group.issues.length} issues from ${group.agentCount} agents, threshold: ${group.threshold})\n`);
-      for (const { agent, issue } of group.issues) {
-        const cat = issue.category ?? "general";
-        const text = String(issue.issue ?? "").trim();
-        const fix = String(issue.suggested_fix ?? "").trim();
-        lines.push(`- **[${cat}]** ${text} *(${agent})*`);
-        if (fix) lines.push(`  - Fix: ${fix}`);
-      }
-      lines.push("");
-    }
-
-    if (corroboration.solo.length > 0) {
-      lines.push("---\n");
-      lines.push(`> ${corroboration.solo.length} dimension${corroboration.solo.length !== 1 ? "s" : ""} had issues below threshold (not blocking): ${corroboration.solo.map(s => `${s.dimension} (${s.issues.length}/${s.threshold})`).join(", ")}\n`);
-    }
-
-    return lines.join("\n");
-  }
-
-  // Fallback: no corroboration data — show all high-severity issues
-  const lines = ["# High-Severity Issues\n"];
-  const allReviewers = Object.values(combined.agents);
-
-  let foundAny = false;
-  for (const r of allReviewers) {
-    if (!r.data) continue;
-    const issues = r.data.issues as Array<Record<string, unknown>> | undefined;
-    if (!issues) continue;
-
-    const highIssues = issues.filter((i) => i.severity === "high");
-    if (highIssues.length === 0) continue;
-
-    foundAny = true;
-    lines.push(`## ${r.name} (${r.verdict})\n`);
-    for (const issue of highIssues) {
-      const cat = (issue.category as string) ?? "general";
-      const text = String(issue.issue ?? "").trim();
-      const fix = String(issue.suggested_fix ?? "").trim();
-      lines.push(`- **[${cat}]** ${text}`);
-      if (fix) lines.push(`  - Fix: ${fix}`);
-    }
-    lines.push("");
-  }
-
-  if (!foundAny) {
-    lines.push("No high-severity issues found.\n");
-  }
-
-  return lines.join("\n");
-}
-
-// ---------------------------------------------------------------------------
-// Index Generation
-// ---------------------------------------------------------------------------
-
-/**
- * Generate index.md for a review folder.
- */
-export function generateReviewIndex(
-  result: CombinedReviewResult,
-  iteration?: number,
-  _settings?: Record<string, unknown>,
-): string {
-  const now = new Date();
-
-  const lines = [
-    "---",
-    `type: review`,
-    `plan_hash: ${result.plan_hash}`,
-    `overall_verdict: ${result.overall_verdict}`,
-    `created_at: ${result.timestamp}`,
-  ];
-  if (iteration) lines.push(`iteration: ${iteration}`);
-  lines.push(
-    "---",
-    "",
-    `# Plan Review - ${formatDate(now)}`,
-    "",
-    `**Overall Verdict:** \`${result.overall_verdict.toUpperCase()}\``,
-  );
-
-  if (iteration) lines.push(`**Iteration:** ${iteration}`);
-  lines.push(`**Plan Hash:** \`${result.plan_hash}\``, "");
-
-  // Summary from orchestrator
-  if (result.orchestration) {
-    lines.push(
-      "## Analysis",
-      `- **Complexity:** \`${result.orchestration.complexity}\``,
-      `- **Category:** \`${result.orchestration.category}\``,
-      `- **Reasoning:** ${result.orchestration.reasoning}`,
-      "",
-    );
-  }
-
-  // Navigation table
-  lines.push(
-    "## Review Files",
-    "",
-    "| File | Description |",
-    "|------|-------------|",
-    "| [review.md](./review.md) | Full review details |",
-    "| [review.json](./review.json) | Structured review data |",
-    "| [plan.md](./plan.md) | Plan snapshot at review time |",
-  );
-
-  for (const name of Object.keys(result.agents)) {
-    const safeName = sanitizeFilename(name);
-    lines.push(
-      `| [${safeName}.json](./reviewer-output/${safeName}.json) | ${name} agent output |`,
-    );
-  }
-
-  lines.push(
-    "",
-    "## Verdicts Summary",
-    "",
-    "| Reviewer | Verdict |",
-    "|----------|---------|",
-  );
-
-  for (const [name, r] of Object.entries(result.agents)) {
-    lines.push(`| ${name} | \`${r.verdict}\` |`);
-  }
-  lines.push("");
-
-  return lines.join("\n");
-}
-
-// ---------------------------------------------------------------------------
-// JSON Output
-// ---------------------------------------------------------------------------
-
-/**
- * Build combined JSON output structure.
- */
-export function buildCombinedJson(
-  result: CombinedReviewResult,
-): Record<string, unknown> {
-  const output: Record<string, unknown> = {
-    metadata: {
-      timestamp: result.timestamp,
-      plan_hash: result.plan_hash,
-    },
-    overall: {
-      verdict: result.overall_verdict,
-    },
-  };
-
-  // Orchestration
-  if (result.orchestration) {
-    output.orchestration = {
-      complexity: result.orchestration.complexity,
-      category: result.orchestration.category,
-      selectedAgents: result.orchestration.selected_agents,
-      reasoning: result.orchestration.reasoning,
-      skipReason: result.orchestration.skip_reason ?? null,
-      error: result.orchestration.error ?? null,
-    };
-  }
-
-  // Agents
-  if (Object.keys(result.agents).length > 0) {
-    const agents: Record<string, unknown> = {};
-    output.agents = agents;
-    for (const [name, r] of Object.entries(result.agents)) {
-      agents[name] = {
-        verdict: r.verdict,
-        summary: r.data?.summary ?? null,
-        summarySource: r.data?.summary_source ?? null,
-        issues: r.data
-          ? ((r.data.issues as Array<Record<string, unknown>>) ?? []).filter(
-              (i) => i.severity !== "low",
-            )
-          : [],
-        missing_sections: r.data?.missing_sections ?? [],
-        questions: r.data?.questions ?? [],
-        ok: r.ok,
-        error: r.err || null,
-      };
-    }
-  }
-
-  return output;
-}
-
-// ---------------------------------------------------------------------------
-// Artifact Writing
-// ---------------------------------------------------------------------------
-
-/**
- * Write combined review artifacts to context reviews folder.
- * Uses atomic writes for critical files when ENABLE_ROBUST_PLAN_WRITES is true.
- */
-export function writeCombinedArtifacts(
-  base: string,
-  plan: string,
-  result: CombinedReviewResult,
-  payload: Record<string, unknown>,
-  settings?: Record<string, unknown>,
-  contextReviewsDir?: string,
-  reviewFolder?: string,
-  iteration?: number,
-  corroboration?: CorroborationResult,
-): string {
-  const outDir = reviewFolder ?? contextReviewsDir;
-  if (!outDir) {
-    throw new Error("Either contextReviewsDir or reviewFolder is required");
-  }
-
-  logDebug("utils", `Using review folder: ${outDir}`);
-
-  // Create directory
-  try {
-    fs.mkdirSync(outDir, { recursive: true });
-  } catch (error: unknown) {
-    logError("utils", `Cannot create directory ${outDir}: ${error}`);
-    throw error;
-  }
-
-  // JSON write
-  const jsonPath = path.join(outDir, "review.json");
-  const jsonData = buildCombinedJson(result);
-  writeFile(jsonPath, JSON.stringify(jsonData, null, 2));
-
-  // Markdown write
-  const mdPath = path.join(outDir, "review.md");
-  const mdContent = formatCombinedMarkdown(result, settings, corroboration);
-  writeFile(mdPath, mdContent);
-
-  // Individual reviewer writes (non-critical) — in reviewer-output/ subfolder
-  const reviewerOutputDir = path.join(outDir, "reviewer-output");
-  try {
-    fs.mkdirSync(reviewerOutputDir, { recursive: true });
-  } catch {
-    // Best-effort — non-critical
-  }
-  for (const [name, r] of Object.entries(result.agents)) {
-    if (r.data) {
-      writeFileNonCritical(
-        path.join(reviewerOutputDir, `${sanitizeFilename(name)}.json`),
-        JSON.stringify(r.data, null, 2),
-      );
-    }
-  }
-
-  // Generate index.md for folder-based reviews
-  if (reviewFolder) {
-    const indexContent = generateReviewIndex(result, iteration, settings);
-    writeFileNonCritical(path.join(outDir, "index.md"), indexContent);
-    return path.join(outDir, "index.md");
-  }
-
-  return mdPath;
-}
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-function resolveDisplay(
-  settings?: Record<string, unknown>,
-): DisplaySettings {
-  if (!settings) return { ...DEFAULT_DISPLAY };
-  const display = (settings.display as Partial<DisplaySettings>) ?? {};
-  return { ...DEFAULT_DISPLAY, ...display };
-}
-
-function appendSummaryLine(lines: string[], data: Record<string, unknown>): void {
-  const summary = String(data.summary ?? "").trim();
-  if (data.summary_source === "default") {
-    lines.push(`- summary: ⚠️ ${summary} *(reviewer did not return summary)*`);
-  } else {
-    lines.push(`- summary: ${summary}`);
-  }
-}
-
-function appendReviewDetails(
-  lines: string[],
-  data: Record<string, unknown>,
-  display: DisplaySettings,
-): void {
-  const issues = ((data.issues as Array<Record<string, unknown>>) ?? []).filter(
-    (i) => i.severity !== "low",
-  );
-  if (issues.length > 0) {
-    lines.push("\n**Issues:**");
-    for (const it of issues.slice(0, display.maxIssues)) {
-      const sev = (it.severity as string) ?? "medium";
-      const cat = (it.category as string) ?? "general";
-      const issue = (it.issue as string) ?? "";
-      const fix = (it.suggested_fix as string) ?? "";
-      lines.push(`- **[${sev}] ${cat}**: ${issue}`);
-      if (fix) lines.push(`  - fix: ${fix}`);
-    }
-  }
-
-  const missing = (data.missing_sections as string[]) ?? [];
-  if (missing.length > 0) {
-    lines.push("\n**Missing Sections:**");
-    for (const m of missing.slice(0, display.maxMissingSections)) {
-      lines.push(`- ${m}`);
-    }
-  }
-
-  const qs = (data.questions as string[]) ?? [];
-  if (qs.length > 0) {
-    lines.push("\n**Questions:**");
-    for (const q of qs.slice(0, display.maxQuestions)) {
-      lines.push(`- ${q}`);
-    }
-  }
-}
-
-function writeFile(filePath: string, content: string): void {
-  try {
-    if (ENABLE_ROBUST_PLAN_WRITES) {
-      const [success, error] = atomicWrite(filePath, content);
-      if (!success) throw new Error(`Atomic write failed: ${error}`);
-    } else {
-      fs.writeFileSync(filePath, content, "utf-8");
-    }
-  } catch (error: unknown) {
-    logError("utils", `Failed to write ${path.basename(filePath)}: ${error}`);
-    throw error;
-  }
-}
-
-function writeFileNonCritical(filePath: string, content: string): void {
-  try {
-    if (ENABLE_ROBUST_PLAN_WRITES) {
-      const [success, error] = atomicWrite(filePath, content);
-      if (!success) {
-        logWarn("utils", `Failed to write ${path.basename(filePath)}: ${error}`);
-      }
-    } else {
-      fs.writeFileSync(filePath, content, "utf-8");
-    }
-  } catch (error: unknown) {
-    logWarn("utils", `Failed to write ${path.basename(filePath)}: ${error}`);
-  }
-}
-
-function titleCase(s: string): string {
-  return s.charAt(0).toUpperCase() + s.slice(1);
-}
-
-function formatDate(d: Date): string {
-  const year = d.getFullYear();
-  const month = String(d.getMonth() + 1).padStart(2, "0");
-  const day = String(d.getDate()).padStart(2, "0");
-  const hours = String(d.getHours()).padStart(2, "0");
-  const minutes = String(d.getMinutes()).padStart(2, "0");
-  return `${year}-${month}-${day} ${hours}:${minutes}`;
-}
-
-// ---------------------------------------------------------------------------
-// Review Tracker
-// ---------------------------------------------------------------------------
-
-export interface ReviewTrackerEntry {
-  iteration: number;
-  timestamp: string;
-  planHash: string;
-  verdict: string;
-  decision: string;
-  score: number;
-  topIssues: string[];
-  reviewFolder: string;
-}
-
-/**
- * Build or update the review-tracker.md in the cc-native reviews directory.
- * This file provides a human-readable summary of all review iterations,
- * making it easy to see whether feedback was acted on.
- */
-export function writeReviewTracker(
-  ccNativeReviewsDir: string,
-  entry: ReviewTrackerEntry,
-): void {
-  const trackerPath = path.join(ccNativeReviewsDir, "review-tracker.md");
-
-  // Read existing tracker entries if present
-  let existingContent = "";
-  try {
-    if (fs.existsSync(trackerPath)) {
-      existingContent = fs.readFileSync(trackerPath, "utf-8");
-    }
-  } catch {
-    // Fresh start
-  }
-
-  // Parse existing entries to detect plan changes
-  const previousHashes = extractPreviousHashes(existingContent);
-  const hashChanged = previousHashes.length > 0 &&
-    previousHashes.at(-1) !== entry.planHash;
-
-  // Build the new entry section
-  const lines: string[] = [];
-  const verdictEmoji = entry.decision === "allow" ? "\u2705" : "\u274C";
-  const changeNote = previousHashes.length > 0
-    ? (hashChanged ? "\u2705 Plan was revised (hash changed)" : "\u26A0\uFE0F Plan unchanged since last review")
-    : "Initial review";
-
-  lines.push(`## Iteration ${entry.iteration} \u2014 ${entry.timestamp} \u2014 ${verdictEmoji} ${entry.verdict.toUpperCase()}`);
-  lines.push("");
-  lines.push(`- **Decision:** ${entry.decision}`);
-  lines.push(`- **Score:** ${entry.score.toFixed(2)}`);
-  lines.push(`- **Plan hash:** \`${entry.planHash}\``);
-  lines.push(`- **Status:** ${changeNote}`);
-  lines.push(`- **Full review:** [\`${path.basename(entry.reviewFolder)}/\`](${path.basename(entry.reviewFolder)}/index.md)`);
-
-  if (entry.topIssues.length > 0) {
-    lines.push("");
-    lines.push("**Top issues:**");
-    for (const issue of entry.topIssues) {
-      lines.push(`- ${issue}`);
-    }
-  }
-  lines.push("");
-
-  // Build full file
-  let output: string;
-  if (!existingContent || !existingContent.includes("# Plan Review Tracker")) {
-    // New file
-    output = [
-      "# Plan Review Tracker",
-      "",
-      "> Auto-generated by plan review hook. Shows review lifecycle across iterations.",
-      "> Check `plan.md` in each iteration folder to diff plan changes.",
-      "",
-      ...lines,
-    ].join("\n");
-  } else {
-    // Append to existing
-    output = existingContent.trimEnd() + "\n\n" + lines.join("\n");
-  }
-
-  try {
-    fs.writeFileSync(trackerPath, output, "utf-8");
-  } catch (error) {
-    logWarn("artifacts", `Failed to write review tracker: ${error}`);
-  }
-}
-
-function extractPreviousHashes(content: string): string[] {
-  const hashes: string[] = [];
-  const regex = /\*\*Plan hash:\*\* `([a-f0-9]+)`/g;
-  let match: RegExpExecArray | null;
-  while ((match = regex.exec(content)) !== null) {
-    hashes.push(match[1]!);
-  }
-  return hashes;
-}
-
-// ---------------------------------------------------------------------------
-// Corroboration Report
-// ---------------------------------------------------------------------------
-
-/**
- * Build a detailed markdown report of the corroboration analysis.
- * Shows blocking vs solo findings with threshold comparison.
- */
-export function buildCorroborationReport(
-  corroborationResult: CorroborationResult,
-): string {
-  const lines: string[] = [
-    "# Corroboration Analysis",
-    "",
-    "## Verdict: " + corroborationResult.verdict.toUpperCase(),
-    "",
-  ];
-
-  // Blocking groups table
-  if (corroborationResult.blocking.length > 0) {
-    lines.push("## Blocking Issues (Corroborated)");
-    lines.push("");
-    lines.push("| Dimension | Issues | Agents | Threshold | Status |");
-    lines.push("|-----------|--------|--------|-----------|--------|");
-
-    for (const group of corroborationResult.blocking) {
-      lines.push(
-        `| ${group.dimension} | ${group.issues.length} | ${group.agentCount} | ${group.threshold} | ⛔ EXCEEDED |`
-      );
-    }
-    lines.push("");
-
-    // Issue details
-    for (const group of corroborationResult.blocking) {
-      lines.push(`### ${group.dimension} (${group.issues.length} issues)`);
-      lines.push("");
-      for (const {agent, issue} of group.issues) {
-        lines.push(`- **[${agent}]** ${issue.description || issue.issue || "No description"}`);
-      }
-      lines.push("");
-    }
-  }
-
-  // Solo findings table
-  if (corroborationResult.solo.length > 0) {
-    lines.push("## Solo Findings (Below Threshold)");
-    lines.push("");
-    lines.push("| Dimension | Issues | Agents | Threshold | Status |");
-    lines.push("|-----------|--------|--------|-----------|--------|");
-
-    for (const group of corroborationResult.solo) {
-      lines.push(
-        `| ${group.dimension} | ${group.issues.length} | ${group.agentCount} | ${group.threshold} | ℹ️ SOLO |`
-      );
-    }
-    lines.push("");
-
-    // Issue details
-    for (const group of corroborationResult.solo) {
-      lines.push(`### ${group.dimension} (${group.issues.length} issues)`);
-      lines.push("");
-      for (const {agent, issue} of group.issues) {
-        lines.push(`- **[${agent}]** ${issue.description || issue.issue || "No description"}`);
-      }
-      lines.push("");
-    }
-  }
-
-  // Unclassified issues
-  if (corroborationResult.unclassified.length > 0) {
-    lines.push("## Unclassified Issues (No Dimension)");
-    lines.push("");
-    for (const {agent, issue} of corroborationResult.unclassified) {
-      lines.push(`- **[${agent}]** ${issue.description || issue.issue || "No description"}`);
-    }
-    lines.push("");
-  }
-
-  // Summary
-  lines.push("## Summary");
-  lines.push("");
-  lines.push(`- **Blocking groups**: ${corroborationResult.blocking.length}`);
-  lines.push(`- **Solo findings**: ${corroborationResult.solo.length}`);
-  lines.push(`- **Unclassified**: ${corroborationResult.unclassified.length}`);
-  lines.push(`- **Final verdict**: ${corroborationResult.verdict}`);
-  lines.push("");
-  lines.push("**Threshold rule**: Issues in a dimension block when count ≥ 2× distinct agents in that dimension.");
-
-  return lines.join("\n");
-}
+ * Re-exports from artifacts/ subdirectory for backward compatibility.
+ */
+
+export {
+  formatReviewMarkdown,
+  formatCombinedMarkdown,
+  buildInlineReviewSummary,
+  extractTopIssuesText,
+  buildHighIssuesDocument,
+  buildCorroborationReport,
+  generateReviewIndex,
+  buildCombinedJson,
+  writeCombinedArtifacts,
+  writeFile,
+  writeFileNonCritical,
+  writeReviewTracker,
+  extractPreviousHashes,
+} from "./artifacts/index.js";
+export type { ReviewTrackerEntry } from "./artifacts/index.js";