dravoice 0.1.2 → 0.1.3

package/src/v2/benchmark.js

@@ -1,10 +1,11 @@
-import fs from "node:fs";
-import path from "node:path";
-import { learnVoicePackV2, loadVoicePackV2 } from "./profile.js";
-import { voicePromptPackV2 } from "./prompt.js";
-import { reviewVoiceDraftV2 } from "./review.js";
-import { clampScore } from "./text-utils.js";
-
+import fs from "node:fs";
+import path from "node:path";
+import { readJsonFileBounded, readUtf8FileBounded, writeUtf8FileSafely } from "./io-utils.js";
+import { learnVoicePackV2, loadVoicePackV2 } from "./profile.js";
+import { voicePromptPackV2 } from "./prompt.js";
+import { reviewVoiceDraftV2 } from "./review.js";
+import { clampScore } from "./text-utils.js";
+
 const BENCHMARK_SCHEMA_VERSION = 2;
 const GENERATED_BY = "dravoice-v2-benchmark";
 
@@ -19,517 +20,515 @@ export function prepareVoiceBenchmark({ examplesDir, topic, outDir, seed = 1, cw
   fs.mkdirSync(promptsDir, { recursive: true });
   fs.mkdirSync(draftsDir, { recursive: true });
 
-  const profile = learnVoicePackV2({ examplesDir: examplesRoot, outDir: voicePackDir });
+  const profile = learnVoicePackV2({ examplesDir: examplesRoot, outDir: voicePackDir, excludePaths: [outputRoot] });
   const sources = benchmarkSourcesFromProfile(profile);
-  const blind = blindMapping(normalizedSeed);
-  const benchmark = {
-    schemaVersion: BENCHMARK_SCHEMA_VERSION,
-    generatedBy: GENERATED_BY,
-    mode: "harness-only",
-    topic,
-    seed: normalizedSeed,
-    corpus: {
-      fileCount: sources.length,
-      sourceRoot: null,
-      files: sources.map((source) => ({
-        id: source.id,
-        path: source.path,
-        title: source.title,
-        words: source.words,
-      })),
-      voiceSource: profile.source,
-    },
-    blind,
-    blindLabels: blind,
-    paths: {
-      voicePack: "voice-pack",
-      prompts: {
-        baselineWriter: "prompts/baseline-writer.md",
-        voiceWriter: "prompts/voice-writer.md",
-        judge: "prompts/judge.md",
-      },
-      drafts: {
-        baseline: "drafts/baseline.md",
-        voiceAssisted: "drafts/voice-assisted.md",
-      },
-      judge: "judge/judgment.json",
-      scores: "scores.json",
-      report: "report.md",
-    },
-  };
-
-  writeIfMissing(path.join(draftsDir, "baseline.md"), draftPlaceholder("Baseline Draft", "Replace this file with Actor 1 output before scoring."));
-  writeIfMissing(path.join(draftsDir, "voice-assisted.md"), draftPlaceholder("Voice-Assisted Draft", "Replace this file with Actor 2 output before scoring."));
-  fs.writeFileSync(path.join(promptsDir, "baseline-writer.md"), renderBaselinePrompt({ topic, sources }), "utf8");
-  fs.writeFileSync(path.join(promptsDir, "voice-writer.md"), renderVoiceWriterPrompt({ topic, sources, voice: profile }), "utf8");
-  fs.writeFileSync(
-    path.join(promptsDir, "judge.md"),
-    renderJudgePrompt({
-      topic,
-      sources,
-      blind,
-      drafts: ["A", "B"].map((label) => ({
-        label,
-        path: blind.draftFiles[label],
-        words: 0,
-      })),
-    }),
-    "utf8",
-  );
-  fs.writeFileSync(path.join(outputRoot, "benchmark.json"), `${JSON.stringify(benchmark, null, 2)}\n`, "utf8");
-
-  return benchmark;
-}
-
-export function scoreVoiceBenchmark({ runDir, judgePath, judgeFile, judge, cwd = process.cwd() }) {
-  const root = path.resolve(resolvePath(cwd, runDir));
-  const resolvedJudgePath = judgePath ?? judgeFile ?? judge;
-  const benchmarkPath = path.join(root, "benchmark.json");
-  if (!fs.existsSync(benchmarkPath)) {
-    throw new Error(`No V2 voice benchmark found at ${runDir}. Run dravoice benchmark prepare first.`);
-  }
-
-  const benchmark = JSON.parse(fs.readFileSync(benchmarkPath, "utf8"));
-  const resolved = resolveBenchmarkPaths(root, benchmark);
-  assertBenchmarkDraftsReady(benchmark, resolved);
-  const voice = loadVoicePackV2(resolved.paths.voicePack);
-  fs.mkdirSync(path.dirname(resolved.paths.prompts.judge), { recursive: true });
-  fs.writeFileSync(
-    resolved.paths.prompts.judge,
-    renderJudgePrompt({
-      topic: benchmark.topic,
-      sources: benchmarkSources(benchmark, resolved),
-      blind: benchmark.blind,
-      drafts: benchmarkDrafts(benchmark, resolved),
-    }),
-    "utf8",
-  );
-
-  const baselineReview = reviewVoiceDraftV2({
-    file: resolved.paths.drafts.baseline,
-    voice,
-    cwd: root,
-  });
-  const voiceReview = reviewVoiceDraftV2({
-    file: resolved.paths.drafts.voiceAssisted,
-    voice,
-    cwd: root,
-  });
-  const judgeData = resolvedJudgePath ? loadJudge(resolvePath(cwd, resolvedJudgePath)) : null;
-  const scores = benchmarkScores({
-    benchmark,
-    baselineReview,
-    voiceReview,
-    judge: judgeData,
-    judgePath: resolvedJudgePath ? displayPath(resolvePath(cwd, resolvedJudgePath), root) : null,
-  });
-
-  fs.writeFileSync(resolved.paths.scores, `${JSON.stringify(scores, null, 2)}\n`, "utf8");
-  fs.writeFileSync(resolved.paths.report, renderBenchmarkReport(scores), "utf8");
-  return scores;
-}
-
-export function renderBenchmarkReport(scores) {
-  const lines = [
-    "# Dravoice V2 Voice Benchmark Report",
-    "",
-    `Topic: ${scores.topic}`,
-    `Mode: ${scores.mode}`,
-    "",
-  ];
-
-  if (scores.winner.final) {
-    lines.push(`Final winner: ${scores.winner.draft} (${scores.winner.label})`);
-    lines.push(`Margin: ${scores.winner.margin}`);
-  } else {
-    lines.push("Final winner: unavailable until judge JSON is supplied.");
-    lines.push(`Deterministic provisional leader: ${scores.deterministicWinner.draft} (${scores.deterministicWinner.label})`);
-  }
-  lines.push("Single benchmark run is directional, not proof; compare repeated runs and family diagnostics before deciding.");
-
-  for (const key of ["baseline", "voiceAssisted"]) {
-    const draft = scores.drafts[key];
-    lines.push("");
-    lines.push(`## ${draft.name}`);
-    lines.push(`Blind label: ${draft.label}`);
-    lines.push(`Voice fit: ${draft.deterministic.voiceFit}`);
-    lines.push(`Fit band: ${draft.deterministic.fitBand}`);
-    lines.push("Family scores:");
-    for (const [family, score] of Object.entries(draft.deterministic.familyScores)) {
-      lines.push(`- ${family}: ${score}`);
-    }
-    if (draft.judge) {
-      lines.push(`Judge voice score: ${draft.judge.voiceScore}`);
-      lines.push(`Hybrid score: ${draft.hybridScore}`);
-      lines.push(`Rationale: ${draft.judge.rationale}`);
-    }
-  }
-
-  return `${lines.join("\n")}\n`;
-}
-
-function benchmarkScores({ benchmark, baselineReview, voiceReview, judge, judgePath }) {
-  const baselineLabel = benchmark.blind.labels.baseline;
-  const voiceLabel = benchmark.blind.labels.voiceAssisted;
-  const baseline = draftScore({ key: "baseline", name: "Baseline", label: baselineLabel, review: baselineReview, judge });
-  const voiceAssisted = draftScore({ key: "voiceAssisted", name: "Voice-assisted", label: voiceLabel, review: voiceReview, judge });
-  const deterministicWinner = winnerFromScores({
-    baseline: baseline.deterministic.voiceFit,
-    voiceAssisted: voiceAssisted.deterministic.voiceFit,
-  }, benchmark.blind.labels);
-
-  let winner = {
-    final: false,
-    draft: null,
-    label: null,
-    margin: null,
-    reason: "No judge file provided.",
-  };
-  if (judge) {
-    winner = {
-      final: true,
-      ...winnerFromScores({
-        baseline: baseline.hybridScore,
-        voiceAssisted: voiceAssisted.hybridScore,
-      }, benchmark.blind.labels),
-      reason: "Hybrid score combines blind judge voice score, deterministic family fit, judge generic-drift score, and judge originality score.",
-    };
-  }
-
-  return {
-    schemaVersion: BENCHMARK_SCHEMA_VERSION,
-    generatedBy: GENERATED_BY,
-    mode: judge ? "final" : "provisional",
-    topic: benchmark.topic,
-    seed: benchmark.seed,
-    blind: benchmark.blind,
-    judge: {
-      provided: Boolean(judge),
-      path: judgePath,
-      declaredWinner: judge?.winner ?? null,
-    },
-    formula: {
-      judgeVoice: 0.55,
-      deterministicFamilyFit: 0.25,
-      judgeGenericDrift: 0.10,
-      judgeOriginality: 0.10,
-    },
-    drafts: {
-      baseline,
-      voiceAssisted,
-    },
-    deterministicWinner,
-    winner,
-    exitCode: 0,
-  };
-}
-
-function draftScore({ key, name, label, review, judge }) {
-  const deterministic = deterministicScore(review);
-  const judgeDraft = judge ? normalizeJudgeDraft(judge.drafts?.[label], label) : null;
-  const hybridScore = judgeDraft
-    ? roundHalfUp(
-      judgeDraft.voiceScore * 0.55 +
-      deterministic.voiceFit * 0.25 +
-      judgeDraft.genericDriftScore * 0.10 +
-      judgeDraft.originalityScore * 0.10,
-      2,
-    )
-    : null;
-
-  return {
-    key,
-    name,
-    label,
-    file: review.file,
-    deterministic,
-    judge: judgeDraft,
-    hybridScore,
-  };
-}
-
-function deterministicScore(review) {
-  const reviewFindings = review.findings.filter((finding) => finding.priority === "review").length;
-  const considerFindings = review.findings.filter((finding) => finding.priority === "consider").length;
-  return {
-    voiceFit: clampScore(100 - review.summary.fit.distance),
-    fitBand: review.summary.fit.band,
-    familyScores: review.summary.familyScores,
-    voiceDistance: review.summary.fit.distance,
-    reviewFindings,
-    considerFindings,
-  };
-}
-
-function winnerFromScores(scores, labels) {
-  if (scores.baseline === scores.voiceAssisted) {
-    return { draft: "tie", label: "tie", margin: 0 };
-  }
-  const draft = scores.voiceAssisted > scores.baseline ? "voice-assisted" : "baseline";
-  return {
-    draft,
-    label: draft === "voice-assisted" ? labels.voiceAssisted : labels.baseline,
-    margin: roundHalfUp(Math.abs(scores.voiceAssisted - scores.baseline), 2),
-  };
-}
-
-function loadJudge(judgePath) {
-  const resolved = path.resolve(judgePath);
-  if (!fs.existsSync(resolved)) {
-    throw new Error(`Judge file not found: ${judgePath}`);
-  }
-  const judge = JSON.parse(fs.readFileSync(resolved, "utf8"));
-  if (!judge.drafts || !judge.drafts.A || !judge.drafts.B) {
-    throw new Error("Judge JSON must include drafts.A and drafts.B.");
-  }
-  return judge;
-}
-
-function normalizeJudgeDraft(value, label) {
-  if (!value) {
-    throw new Error(`Judge JSON is missing scores for Draft ${label}.`);
-  }
-  return {
-    voiceScore: requiredScore(value.voiceScore, `drafts.${label}.voiceScore`),
-    genericDriftScore: requiredScore(value.genericDriftScore, `drafts.${label}.genericDriftScore`),
-    originalityScore: requiredScore(value.originalityScore, `drafts.${label}.originalityScore`),
-    rationale: String(value.rationale ?? ""),
-  };
-}
-
-function requiredScore(value, field) {
-  if (typeof value !== "number" || !Number.isFinite(value)) {
-    throw new Error(`Judge JSON field ${field} must be a number.`);
-  }
-  if (value < 0 || value > 100) {
-    throw new Error(`Judge JSON field ${field} must be between 0 and 100.`);
-  }
-  return value;
-}
-
-function renderBaselinePrompt({ topic, sources }) {
-  return [
-    "# Baseline Writer Prompt",
-    "",
-    "Write a new article on the requested topic using only the source articles as style examples.",
-    "Do not mention this benchmark. Do not explain your process.",
-    "",
-    `Topic: ${topic}`,
-    "",
-    renderSources(sources),
-  ].join("\n");
-}
-
-function renderVoiceWriterPrompt({ topic, sources, voice }) {
-  return [
-    "# Voice-Assisted Writer Prompt",
-    "",
-    "Write a new article on the requested topic. Use the learned Dravoice V2 feature-family guidance as the writing brief.",
-    "Do not mention this benchmark. Do not explain your process.",
-    "",
-    `Topic: ${topic}`,
-    "",
-    voicePromptPackV2({ voice, format: "agents" }).trim(),
-    "",
-    renderSources(sources),
-  ].join("\n");
-}
-
-function renderJudgePrompt({ topic, sources, blind, drafts }) {
-  return [
-    "# Blind V2 Voice Benchmark Judge Prompt",
-    "",
-    "You are judging which draft is closer to the source corpus across feature-family behavior: rhythm, lexical style, register, discourse, rhetorical shape, evidence habits, and structure.",
-    "The labels are blinded. Do not guess which workflow produced a draft.",
-    "Score each numeric field from 0 to 100 inclusive, where 0 means no fit and 100 means excellent fit.",
-    "Generated artifacts omit source and draft content by default. Open the local files directly when you need to judge prose.",
-    "",
-    `Topic: ${topic}`,
-    "",
-    "Return only JSON in this shape:",
-    "",
-    "```json",
-    JSON.stringify({
-      winner: "A",
-      drafts: {
-        A: {
-          voiceScore: 0,
-          genericDriftScore: 0,
-          originalityScore: 0,
-          rationale: "short reason",
-        },
-        B: {
-          voiceScore: 0,
-          genericDriftScore: 0,
-          originalityScore: 0,
-          rationale: "short reason",
-        },
-      },
-    }, null, 2),
-    "```",
-    "",
-    `Draft A file: ${blind.draftFiles.A}`,
-    `Draft B file: ${blind.draftFiles.B}`,
-    "",
-    renderDrafts(drafts),
-    "",
-    renderSources(sources),
-  ].join("\n");
-}
-
-function renderDrafts(drafts = []) {
-  const byLabel = new Map(drafts.map((draft) => [draft.label, draft]));
-  return [
-    "## Drafts",
-    "",
-    "Draft content is intentionally omitted from this generated artifact by default.",
-    "Open the local draft files when judging, then return JSON using the blind labels below.",
-    "",
-    ...["A", "B"].map((label) => {
-      const draft = byLabel.get(label);
-      return [
-        `## Draft ${label}`,
-        "",
-        `Draft file: ${draft?.path ?? "missing"}`,
-        `Draft words: ${draft?.words ?? 0}`,
-      ].join("\n");
-    }),
-  ].join("\n\n");
-}
-
-function renderSources(sources) {
-  const lines = [
-    "## Source Articles",
-    "",
-    "Source content is intentionally omitted from this generated artifact by default.",
-    "Use the learned Dravoice profile and local source files as needed; do not paste private source text into shared reports.",
-    "",
-  ];
-  for (const [index, source] of sources.entries()) {
-    lines.push(`### Source Article ${index + 1}`);
-    lines.push("");
-    lines.push(`Source id: ${source.id ?? `source-${index + 1}`}`);
-    lines.push(`Source file: ${source.path}`);
-    lines.push(`Source words: ${source.words}`);
-    lines.push("");
-  }
-  return lines.join("\n");
-}
-
-function draftPlaceholder(title, body) {
-  return [`# ${title}`, "", body, ""].join("\n");
-}
-
-function assertBenchmarkDraftsReady(benchmark, resolved) {
-  for (const [key, draftPath] of Object.entries(resolved.paths.drafts)) {
-    if (!fs.existsSync(draftPath)) {
-      throw new Error(`Replace benchmark placeholder draft before scoring: ${draftPath}`);
-    }
-    const contents = fs.readFileSync(draftPath, "utf8");
-    if (isPlaceholderDraft(contents, key)) {
-      throw new Error(`Replace benchmark placeholder draft before scoring: ${benchmark.paths.drafts[key]}`);
-    }
-  }
-}
-
-function isPlaceholderDraft(contents, key) {
-  const expectedTitle = key === "baseline" ? "# Baseline Draft" : "# Voice-Assisted Draft";
-  return contents.includes(expectedTitle) && contents.includes("Replace this file with Actor");
-}
-
-function resolveBenchmarkPaths(root, benchmark) {
-  assertObject(benchmark, "benchmark");
-  if (benchmark.schemaVersion !== BENCHMARK_SCHEMA_VERSION) {
-    throw new Error(`Benchmark JSON schemaVersion must be ${BENCHMARK_SCHEMA_VERSION}.`);
-  }
-  if (benchmark.generatedBy !== GENERATED_BY) {
-    throw new Error(`Benchmark JSON generatedBy must be ${GENERATED_BY}.`);
-  }
-  assertObject(benchmark.paths, "paths");
-  assertObject(benchmark.paths.prompts, "paths.prompts");
-  assertObject(benchmark.paths.drafts, "paths.drafts");
-  assertObject(benchmark.corpus, "corpus");
-  assertObject(benchmark.blind, "blind");
-  assertObject(benchmark.blind.labels, "blind.labels");
-  assertObject(benchmark.blind.draftFiles, "blind.draftFiles");
-  if (!Array.isArray(benchmark.corpus.files)) {
-    throw new Error("Benchmark JSON field corpus.files must be an array.");
-  }
-
-  const paths = {
-    voicePack: containedBenchmarkPath(root, root, benchmark.paths.voicePack, "paths.voicePack"),
-    prompts: {
-      baselineWriter: containedBenchmarkPath(root, root, benchmark.paths.prompts.baselineWriter, "paths.prompts.baselineWriter"),
-      voiceWriter: containedBenchmarkPath(root, root, benchmark.paths.prompts.voiceWriter, "paths.prompts.voiceWriter"),
-      judge: containedBenchmarkPath(root, root, benchmark.paths.prompts.judge, "paths.prompts.judge"),
-    },
-    drafts: {
-      baseline: containedBenchmarkPath(root, root, benchmark.paths.drafts.baseline, "paths.drafts.baseline"),
-      voiceAssisted: containedBenchmarkPath(root, root, benchmark.paths.drafts.voiceAssisted, "paths.drafts.voiceAssisted"),
-    },
-    judge: containedBenchmarkPath(root, root, benchmark.paths.judge, "paths.judge"),
-    scores: containedBenchmarkPath(root, root, benchmark.paths.scores, "paths.scores"),
-    report: containedBenchmarkPath(root, root, benchmark.paths.report, "paths.report"),
-  };
-  const files = benchmark.corpus.files.map((file, index) => {
-    assertObject(file, `corpus.files[${index}]`);
-    return file;
-  });
-  const blind = {
-    labels: benchmark.blind.labels,
-    draftFiles: {
-      A: containedBenchmarkPath(root, root, benchmark.blind.draftFiles.A, "blind.draftFiles.A"),
-      B: containedBenchmarkPath(root, root, benchmark.blind.draftFiles.B, "blind.draftFiles.B"),
-    },
-  };
-  assertBlindMappingMatchesDraftPaths(paths.drafts, blind, benchmark.blind.draftFiles);
-
-  return {
-    paths,
-    corpus: { files },
-    blind,
-  };
-}
-
-function assertBlindMappingMatchesDraftPaths(draftPaths, blind, originalDraftFiles) {
-  for (const key of ["baseline", "voiceAssisted"]) {
-    if (!["A", "B"].includes(blind.labels[key])) {
-      throw new Error(`Benchmark JSON field blind.labels.${key} must be A or B.`);
-    }
-  }
-  if (blind.labels.baseline === blind.labels.voiceAssisted) {
-    throw new Error("Benchmark JSON blind labels must be unique.");
-  }
-  for (const key of ["baseline", "voiceAssisted"]) {
-    const label = blind.labels[key];
-    if (path.resolve(blind.draftFiles[label]) !== path.resolve(draftPaths[key])) {
-      throw new Error(`Benchmark JSON field blind.draftFiles.${label} must match paths.drafts.${key}.`);
-    }
-  }
-  for (const label of ["A", "B"]) {
-    if (!(label in originalDraftFiles)) {
-      throw new Error(`Benchmark JSON field blind.draftFiles.${label} must be present.`);
-    }
-  }
-}
-
-function containedBenchmarkPath(root, base, value, field) {
-  if (typeof value !== "string" || value.trim() === "" || value.includes("\0")) {
-    throw new Error(`Benchmark JSON field ${field} must be a valid path string.`);
-  }
-  const resolved = path.resolve(base, value);
-  if (!isPathInsideOrEqual(root, resolved)) {
-    throw new Error(`Benchmark JSON field ${field} points outside the benchmark run root: ${value}`);
-  }
-  return resolved;
-}
-
-function assertObject(value, field) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw new Error(`Benchmark JSON field ${field} must be an object.`);
-  }
-}
-
+  const blind = blindMapping(normalizedSeed);
+  const benchmark = {
+    schemaVersion: BENCHMARK_SCHEMA_VERSION,
+    generatedBy: GENERATED_BY,
+    mode: "harness-only",
+    topic,
+    seed: normalizedSeed,
+    corpus: {
+      fileCount: sources.length,
+      sourceRoot: null,
+      files: sources.map((source) => ({
+        id: source.id,
+        path: source.path,
+        title: source.title,
+        words: source.words,
+      })),
+      voiceSource: profile.source,
+    },
+    blind,
+    blindLabels: blind,
+    paths: {
+      voicePack: "voice-pack",
+      prompts: {
+        baselineWriter: "prompts/baseline-writer.md",
+        voiceWriter: "prompts/voice-writer.md",
+        judge: "prompts/judge.md",
+      },
+      drafts: {
+        baseline: "drafts/baseline.md",
+        voiceAssisted: "drafts/voice-assisted.md",
+      },
+      judge: "judge/judgment.json",
+      scores: "scores.json",
+      report: "report.md",
+    },
+  };
+
+  writeIfMissing(path.join(draftsDir, "baseline.md"), draftPlaceholder("Baseline Draft", "Replace this file with Actor 1 output before scoring."));
+  writeIfMissing(path.join(draftsDir, "voice-assisted.md"), draftPlaceholder("Voice-Assisted Draft", "Replace this file with Actor 2 output before scoring."));
+  writeUtf8FileSafely(path.join(promptsDir, "baseline-writer.md"), renderBaselinePrompt({ topic, sources }));
+  writeUtf8FileSafely(path.join(promptsDir, "voice-writer.md"), renderVoiceWriterPrompt({ topic, sources, voice: profile }));
+  writeUtf8FileSafely(
+    path.join(promptsDir, "judge.md"),
+    renderJudgePrompt({
+      topic,
+      sources,
+      blind,
+      drafts: ["A", "B"].map((label) => ({
+        label,
+        path: blind.draftFiles[label],
+        words: 0,
+      })),
+    }),
+  );
+  writeUtf8FileSafely(path.join(outputRoot, "benchmark.json"), `${JSON.stringify(benchmark, null, 2)}\n`);
+
+  return benchmark;
+}
+
+export function scoreVoiceBenchmark({ runDir, judgePath, judgeFile, judge, cwd = process.cwd() }) {
+  const root = path.resolve(resolvePath(cwd, runDir));
+  const resolvedJudgePath = judgePath ?? judgeFile ?? judge;
+  const benchmarkPath = path.join(root, "benchmark.json");
+  if (!fs.existsSync(benchmarkPath)) {
+    throw new Error(`No V2 voice benchmark found at ${runDir}. Run dravoice benchmark prepare first.`);
+  }
+
+  const benchmark = readJsonFileBounded(benchmarkPath, { label: "Benchmark JSON", maxBytes: 1024 * 1024 });
+  const resolved = resolveBenchmarkPaths(root, benchmark);
+  assertBenchmarkDraftsReady(benchmark, resolved);
+  const voice = loadVoicePackV2(resolved.paths.voicePack);
+  fs.mkdirSync(path.dirname(resolved.paths.prompts.judge), { recursive: true });
+  writeUtf8FileSafely(
+    resolved.paths.prompts.judge,
+    renderJudgePrompt({
+      topic: benchmark.topic,
+      sources: benchmarkSources(benchmark, resolved),
+      blind: benchmark.blind,
+      drafts: benchmarkDrafts(benchmark, resolved),
+    }),
+  );
+
+  const baselineReview = reviewVoiceDraftV2({
+    file: resolved.paths.drafts.baseline,
+    voice,
+    cwd: root,
+  });
+  const voiceReview = reviewVoiceDraftV2({
+    file: resolved.paths.drafts.voiceAssisted,
+    voice,
+    cwd: root,
+  });
+  const judgeData = resolvedJudgePath ? loadJudge(resolvePath(cwd, resolvedJudgePath)) : null;
+  const scores = benchmarkScores({
+    benchmark,
+    baselineReview,
+    voiceReview,
+    judge: judgeData,
+    judgePath: resolvedJudgePath ? displayPath(resolvePath(cwd, resolvedJudgePath), root) : null,
+  });
+
+  writeUtf8FileSafely(resolved.paths.scores, `${JSON.stringify(scores, null, 2)}\n`);
+  writeUtf8FileSafely(resolved.paths.report, renderBenchmarkReport(scores));
+  return scores;
+}
+
+export function renderBenchmarkReport(scores) {
+  const lines = [
+    "# Dravoice V2 Voice Benchmark Report",
+    "",
+    `Topic: ${safeInline(scores.topic)}`,
+    `Mode: ${scores.mode}`,
+    "",
+  ];
+
+  if (scores.winner.final) {
+    lines.push(`Final winner: ${scores.winner.draft} (${scores.winner.label})`);
+    lines.push(`Margin: ${scores.winner.margin}`);
+  } else {
+    lines.push("Final winner: unavailable until judge JSON is supplied.");
+    lines.push(`Deterministic provisional leader: ${scores.deterministicWinner.draft} (${scores.deterministicWinner.label})`);
+  }
+  lines.push("Single benchmark run is directional, not proof; compare repeated runs and family diagnostics before deciding.");
+
+  for (const key of ["baseline", "voiceAssisted"]) {
+    const draft = scores.drafts[key];
+    lines.push("");
+    lines.push(`## ${draft.name}`);
+    lines.push(`Blind label: ${draft.label}`);
+    lines.push(`Voice fit: ${draft.deterministic.voiceFit}`);
+    lines.push(`Fit band: ${draft.deterministic.fitBand}`);
+    lines.push("Family scores:");
+    for (const [family, score] of Object.entries(draft.deterministic.familyScores)) {
+      lines.push(`- ${family}: ${score}`);
+    }
+    if (draft.judge) {
+      lines.push(`Judge voice score: ${draft.judge.voiceScore}`);
+      lines.push(`Hybrid score: ${draft.hybridScore}`);
+      lines.push(`Rationale: ${safeInline(draft.judge.rationale)}`);
+    }
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+function benchmarkScores({ benchmark, baselineReview, voiceReview, judge, judgePath }) {
+  const baselineLabel = benchmark.blind.labels.baseline;
+  const voiceLabel = benchmark.blind.labels.voiceAssisted;
+  const baseline = draftScore({ key: "baseline", name: "Baseline", label: baselineLabel, review: baselineReview, judge });
+  const voiceAssisted = draftScore({ key: "voiceAssisted", name: "Voice-assisted", label: voiceLabel, review: voiceReview, judge });
+  const deterministicWinner = winnerFromScores({
+    baseline: baseline.deterministic.voiceFit,
+    voiceAssisted: voiceAssisted.deterministic.voiceFit,
+  }, benchmark.blind.labels);
+
+  let winner = {
+    final: false,
+    draft: null,
+    label: null,
+    margin: null,
+    reason: "No judge file provided.",
+  };
+  if (judge) {
+    winner = {
+      final: true,
+      ...winnerFromScores({
+        baseline: baseline.hybridScore,
+        voiceAssisted: voiceAssisted.hybridScore,
+      }, benchmark.blind.labels),
+      reason: "Hybrid score combines blind judge voice score, deterministic family fit, judge generic-drift score, and judge originality score.",
+    };
+  }
+
+  return {
+    schemaVersion: BENCHMARK_SCHEMA_VERSION,
+    generatedBy: GENERATED_BY,
+    mode: judge ? "final" : "provisional",
+    topic: benchmark.topic,
+    seed: benchmark.seed,
+    blind: benchmark.blind,
+    judge: {
+      provided: Boolean(judge),
+      path: judgePath,
+      declaredWinner: judge?.winner ?? null,
+    },
+    formula: {
+      judgeVoice: 0.55,
+      deterministicFamilyFit: 0.25,
+      judgeGenericDrift: 0.10,
+      judgeOriginality: 0.10,
+    },
+    drafts: {
+      baseline,
+      voiceAssisted,
+    },
+    deterministicWinner,
+    winner,
+    exitCode: 0,
+  };
+}
+
+function draftScore({ key, name, label, review, judge }) {
+  const deterministic = deterministicScore(review);
+  const judgeDraft = judge ? normalizeJudgeDraft(judge.drafts?.[label], label) : null;
+  const hybridScore = judgeDraft
+    ? roundHalfUp(
+      judgeDraft.voiceScore * 0.55 +
+      deterministic.voiceFit * 0.25 +
+      judgeDraft.genericDriftScore * 0.10 +
+      judgeDraft.originalityScore * 0.10,
+      2,
+    )
+    : null;
+
+  return {
+    key,
+    name,
+    label,
+    file: review.file,
+    deterministic,
+    judge: judgeDraft,
+    hybridScore,
+  };
+}
+
+function deterministicScore(review) {
+  const reviewFindings = review.findings.filter((finding) => finding.priority === "review").length;
+  const considerFindings = review.findings.filter((finding) => finding.priority === "consider").length;
+  return {
+    voiceFit: clampScore(100 - review.summary.fit.distance),
+    fitBand: review.summary.fit.band,
+    familyScores: review.summary.familyScores,
+    voiceDistance: review.summary.fit.distance,
+    reviewFindings,
+    considerFindings,
+  };
+}
+
+function winnerFromScores(scores, labels) {
+  if (scores.baseline === scores.voiceAssisted) {
+    return { draft: "tie", label: "tie", margin: 0 };
+  }
+  const draft = scores.voiceAssisted > scores.baseline ? "voice-assisted" : "baseline";
+  return {
+    draft,
+    label: draft === "voice-assisted" ? labels.voiceAssisted : labels.baseline,
+    margin: roundHalfUp(Math.abs(scores.voiceAssisted - scores.baseline), 2),
+  };
+}
+
+function loadJudge(judgePath) {
+  const resolved = path.resolve(judgePath);
+  if (!fs.existsSync(resolved)) {
+    throw new Error(`Judge file not found: ${judgePath}`);
+  }
+  const judge = readJsonFileBounded(resolved, { label: "Judge JSON", maxBytes: 1024 * 1024 });
+  if (!judge.drafts || !judge.drafts.A || !judge.drafts.B) {
+    throw new Error("Judge JSON must include drafts.A and drafts.B.");
+  }
+  return judge;
+}
+
+function normalizeJudgeDraft(value, label) {
+  if (!value) {
+    throw new Error(`Judge JSON is missing scores for Draft ${label}.`);
+  }
+  return {
+    voiceScore: requiredScore(value.voiceScore, `drafts.${label}.voiceScore`),
+    genericDriftScore: requiredScore(value.genericDriftScore, `drafts.${label}.genericDriftScore`),
+    originalityScore: requiredScore(value.originalityScore, `drafts.${label}.originalityScore`),
+    rationale: String(value.rationale ?? ""),
+  };
+}
+
+function requiredScore(value, field) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(`Judge JSON field ${field} must be a number.`);
+  }
+  if (value < 0 || value > 100) {
+    throw new Error(`Judge JSON field ${field} must be between 0 and 100.`);
+  }
+  return value;
+}
+
+function renderBaselinePrompt({ topic, sources }) {
+  return [
+    "# Baseline Writer Prompt",
+    "",
+    "Write a new article on the requested topic using only the source articles as style examples.",
+    "Do not mention this benchmark. Do not explain your process.",
+    "",
+    `Topic: ${safeInline(topic)}`,
+    "",
+    renderSources(sources),
+  ].join("\n");
+}
+
+function renderVoiceWriterPrompt({ topic, sources, voice }) {
+  return [
+    "# Voice-Assisted Writer Prompt",
+    "",
+    "Write a new article on the requested topic. Use the learned Dravoice V2 feature-family guidance as the writing brief.",
+    "Do not mention this benchmark. Do not explain your process.",
+    "",
+    `Topic: ${safeInline(topic)}`,
+    "",
+    voicePromptPackV2({ voice, format: "agents" }).trim(),
+    "",
+    renderSources(sources),
+  ].join("\n");
+}
+
+function renderJudgePrompt({ topic, sources, blind, drafts }) {
+  return [
+    "# Blind V2 Voice Benchmark Judge Prompt",
+    "",
+    "You are judging which draft is closer to the source corpus across feature-family behavior: rhythm, lexical style, register, discourse, rhetorical shape, evidence habits, and structure.",
+    "The labels are blinded. Do not guess which workflow produced a draft.",
+    "Score each numeric field from 0 to 100 inclusive, where 0 means no fit and 100 means excellent fit.",
+    "Generated artifacts omit source and draft content by default. Open the local files directly when you need to judge prose.",
+    "",
+    `Topic: ${safeInline(topic)}`,
+    "",
+    "Return only JSON in this shape:",
+    "",
+    "```json",
+    JSON.stringify({
+      winner: "A",
+      drafts: {
+        A: {
+          voiceScore: 0,
+          genericDriftScore: 0,
+          originalityScore: 0,
+          rationale: "short reason",
+        },
+        B: {
+          voiceScore: 0,
+          genericDriftScore: 0,
+          originalityScore: 0,
+          rationale: "short reason",
+        },
+      },
+    }, null, 2),
+    "```",
+    "",
+    `Draft A file: ${blind.draftFiles.A}`,
+    `Draft B file: ${blind.draftFiles.B}`,
+    "",
+    renderDrafts(drafts),
+    "",
+    renderSources(sources),
+  ].join("\n");
+}
+
+function renderDrafts(drafts = []) {
+  const byLabel = new Map(drafts.map((draft) => [draft.label, draft]));
+  return [
+    "## Drafts",
+    "",
+    "Draft content is intentionally omitted from this generated artifact by default.",
+    "Open the local draft files when judging, then return JSON using the blind labels below.",
+    "",
+    ...["A", "B"].map((label) => {
+      const draft = byLabel.get(label);
+      return [
+        `## Draft ${label}`,
+        "",
+        `Draft file: ${safeInline(draft?.path ?? "missing")}`,
+        `Draft words: ${draft?.words ?? 0}`,
+      ].join("\n");
+    }),
+  ].join("\n\n");
+}
+
+function renderSources(sources) {
+  const lines = [
+    "## Source Articles",
+    "",
+    "Source content is intentionally omitted from this generated artifact by default.",
+    "Use the learned Dravoice profile and local source files as needed; do not paste private source text into shared reports.",
+    "",
+  ];
+  for (const [index, source] of sources.entries()) {
+    lines.push(`### Source Article ${index + 1}`);
+    lines.push("");
+    lines.push(`Source id: ${safeInline(source.id ?? `source-${index + 1}`)}`);
+    lines.push(`Source file: ${safeInline(source.path)}`);
+    lines.push(`Source words: ${source.words}`);
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+function draftPlaceholder(title, body) {
+  return [`# ${title}`, "", body, ""].join("\n");
+}
+
+function assertBenchmarkDraftsReady(benchmark, resolved) {
+  for (const [key, draftPath] of Object.entries(resolved.paths.drafts)) {
+    if (!fs.existsSync(draftPath)) {
+      throw new Error(`Replace benchmark placeholder draft before scoring: ${draftPath}`);
+    }
+    const contents = readUtf8FileBounded(draftPath, { label: "Benchmark draft", maxBytes: 2 * 1024 * 1024 });
+    if (isPlaceholderDraft(contents, key)) {
+      throw new Error(`Replace benchmark placeholder draft before scoring: ${benchmark.paths.drafts[key]}`);
+    }
+  }
+}
+
+function isPlaceholderDraft(contents, key) {
+  const expectedTitle = key === "baseline" ? "# Baseline Draft" : "# Voice-Assisted Draft";
+  return contents.includes(expectedTitle) && contents.includes("Replace this file with Actor");
+}
+
+function resolveBenchmarkPaths(root, benchmark) {
+  assertObject(benchmark, "benchmark");
+  if (benchmark.schemaVersion !== BENCHMARK_SCHEMA_VERSION) {
+    throw new Error(`Benchmark JSON schemaVersion must be ${BENCHMARK_SCHEMA_VERSION}.`);
+  }
+  if (benchmark.generatedBy !== GENERATED_BY) {
+    throw new Error(`Benchmark JSON generatedBy must be ${GENERATED_BY}.`);
+  }
+  assertObject(benchmark.paths, "paths");
+  assertObject(benchmark.paths.prompts, "paths.prompts");
+  assertObject(benchmark.paths.drafts, "paths.drafts");
+  assertObject(benchmark.corpus, "corpus");
+  assertObject(benchmark.blind, "blind");
+  assertObject(benchmark.blind.labels, "blind.labels");
+  assertObject(benchmark.blind.draftFiles, "blind.draftFiles");
+  if (!Array.isArray(benchmark.corpus.files)) {
+    throw new Error("Benchmark JSON field corpus.files must be an array.");
+  }
+
+  const paths = {
+    voicePack: containedBenchmarkPath(root, root, benchmark.paths.voicePack, "paths.voicePack"),
+    prompts: {
+      baselineWriter: containedBenchmarkPath(root, root, benchmark.paths.prompts.baselineWriter, "paths.prompts.baselineWriter"),
+      voiceWriter: containedBenchmarkPath(root, root, benchmark.paths.prompts.voiceWriter, "paths.prompts.voiceWriter"),
+      judge: containedBenchmarkPath(root, root, benchmark.paths.prompts.judge, "paths.prompts.judge"),
+    },
+    drafts: {
+      baseline: containedBenchmarkPath(root, root, benchmark.paths.drafts.baseline, "paths.drafts.baseline"),
+      voiceAssisted: containedBenchmarkPath(root, root, benchmark.paths.drafts.voiceAssisted, "paths.drafts.voiceAssisted"),
+    },
+    judge: containedBenchmarkPath(root, root, benchmark.paths.judge, "paths.judge"),
+    scores: containedBenchmarkPath(root, root, benchmark.paths.scores, "paths.scores"),
+    report: containedBenchmarkPath(root, root, benchmark.paths.report, "paths.report"),
+  };
+  const files = benchmark.corpus.files.map((file, index) => {
+    assertObject(file, `corpus.files[${index}]`);
+    return file;
+  });
+  const blind = {
+    labels: benchmark.blind.labels,
+    draftFiles: {
+      A: containedBenchmarkPath(root, root, benchmark.blind.draftFiles.A, "blind.draftFiles.A"),
+      B: containedBenchmarkPath(root, root, benchmark.blind.draftFiles.B, "blind.draftFiles.B"),
+    },
+  };
+  assertBlindMappingMatchesDraftPaths(paths.drafts, blind, benchmark.blind.draftFiles);
+
+  return {
+    paths,
+    corpus: { files },
+    blind,
+  };
+}
+
+function assertBlindMappingMatchesDraftPaths(draftPaths, blind, originalDraftFiles) {
+  for (const key of ["baseline", "voiceAssisted"]) {
+    if (!["A", "B"].includes(blind.labels[key])) {
+      throw new Error(`Benchmark JSON field blind.labels.${key} must be A or B.`);
+    }
+  }
+  if (blind.labels.baseline === blind.labels.voiceAssisted) {
+    throw new Error("Benchmark JSON blind labels must be unique.");
+  }
+  for (const key of ["baseline", "voiceAssisted"]) {
+    const label = blind.labels[key];
+    if (path.resolve(blind.draftFiles[label]) !== path.resolve(draftPaths[key])) {
+      throw new Error(`Benchmark JSON field blind.draftFiles.${label} must match paths.drafts.${key}.`);
+    }
+  }
+  for (const label of ["A", "B"]) {
+    if (!(label in originalDraftFiles)) {
+      throw new Error(`Benchmark JSON field blind.draftFiles.${label} must be present.`);
+    }
+  }
+}
+
+function containedBenchmarkPath(root, base, value, field) {
+  if (typeof value !== "string" || value.trim() === "" || value.includes("\0")) {
+    throw new Error(`Benchmark JSON field ${field} must be a valid path string.`);
+  }
+  const resolved = path.resolve(base, value);
+  if (!isPathInsideOrEqual(root, resolved)) {
+    throw new Error(`Benchmark JSON field ${field} points outside the benchmark run root: ${value}`);
+  }
+  return resolved;
+}
+
+function assertObject(value, field) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`Benchmark JSON field ${field} must be an object.`);
+  }
+}
+
 function benchmarkSourcesFromProfile(profile) {
   return profile.source.files.map((file, index) => ({
     id: file.id ?? `source-${index + 1}`,
@@ -556,7 +555,7 @@ function benchmarkDrafts(benchmark, resolved) {
       label,
       path: draftPath,
       words: fs.existsSync(resolvedDraftPath)
-        ? (fs.readFileSync(resolvedDraftPath, "utf8").match(/[a-z][a-z0-9'-]*/gi) ?? []).length
+        ? (readUtf8FileBounded(resolvedDraftPath, { label: "Benchmark draft", maxBytes: 2 * 1024 * 1024 }).match(/[a-z][a-z0-9'-]*/gi) ?? []).length
         : 0,
     };
   });
@@ -580,54 +579,61 @@ function blindMapping(seed) {
     },
   };
 }
-
-function seededRandom(seed) {
-  const next = (normalizeSeed(seed) * 1664525 + 1013904223) >>> 0;
-  return next / 4294967296;
-}
-
-function normalizeSeed(seed) {
-  const value = String(seed);
-  if (!/^\d+$/.test(value)) {
-    throw new Error(`Invalid seed: ${seed}`);
-  }
-  const parsed = BigInt(value);
-  if (parsed > 0xffffffffn) {
-    throw new Error(`Invalid seed: ${seed}`);
-  }
-  return Number(parsed);
-}
-
+
+function seededRandom(seed) {
+  const next = (normalizeSeed(seed) * 1664525 + 1013904223) >>> 0;
+  return next / 4294967296;
+}
+
+function normalizeSeed(seed) {
+  const value = String(seed);
+  if (!/^\d+$/.test(value)) {
+    throw new Error(`Invalid seed: ${seed}`);
+  }
+  const parsed = BigInt(value);
+  if (parsed > 0xffffffffn) {
+    throw new Error(`Invalid seed: ${seed}`);
+  }
+  return Number(parsed);
+}
+
 function writeIfMissing(filePath, contents) {
-  if (!fs.existsSync(filePath)) {
-    fs.writeFileSync(filePath, contents, "utf8");
-  }
-}
-
-function displayPath(filePath, cwd) {
-  const relative = path.relative(cwd, filePath);
-  if (relative && !relative.startsWith("..") && !path.isAbsolute(relative)) {
-    return toPosix(relative);
-  }
-  return toPosix(filePath);
-}
-
-function resolvePath(cwd, value) {
-  return path.isAbsolute(value) ? value : path.join(cwd, value);
-}
-
-function isPathInsideOrEqual(root, filePath) {
-  const relative = path.relative(path.resolve(root), path.resolve(filePath));
-  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
-}
-
-function roundHalfUp(value, digits = 0) {
-  const multiplier = 10 ** digits;
-  const rounded = Math.floor(value * multiplier + 0.5) / multiplier;
-  return digits === 0 ? Math.trunc(rounded) : rounded;
-}
-
-function toPosix(value) {
-  return value.split(path.sep).join("/");
-}
-
+  if (!fs.existsSync(filePath)) {
+    writeUtf8FileSafely(filePath, contents);
+  }
+}
+
+function displayPath(filePath, cwd) {
+  const relative = path.relative(cwd, filePath);
+  if (relative && !relative.startsWith("..") && !path.isAbsolute(relative)) {
+    return toPosix(relative);
+  }
+  return toPosix(filePath);
+}
+
+function resolvePath(cwd, value) {
+  return path.isAbsolute(value) ? value : path.join(cwd, value);
+}
+
+function isPathInsideOrEqual(root, filePath) {
+  const relative = path.relative(path.resolve(root), path.resolve(filePath));
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function roundHalfUp(value, digits = 0) {
+  const multiplier = 10 ** digits;
+  const rounded = Math.floor(value * multiplier + 0.5) / multiplier;
+  return digits === 0 ? Math.trunc(rounded) : rounded;
+}
+
+function toPosix(value) {
+  return value.split(path.sep).join("/");
+}
+
+function safeInline(value) {
+  return String(value ?? "")
+    .replace(/[\0-\x08\x0b\x0c\x0e-\x1f\x7f]/g, "")
+    .replace(/\s+/g, " ")
+    .replace(/`/g, "'")
+    .trim();
+}