executable-stories-formatters 0.8.0 → 0.9.0

package/dist/cli.js

@@ -414,7 +414,7 @@ var raw_run_schema_default = {
     },
     RawAttachment: {
       type: "object",
-      description: "A test attachment (screenshot, log, artifact). In the MVP schema, only path-based attachments are supported (no inline base64).",
+      description: "A test attachment (screenshot, log, artifact). Either path-based or inline (body); the ACL decides embed-vs-link.",
       properties: {
         name: {
           type: "string",
@@ -427,9 +427,40 @@ var raw_run_schema_default = {
         path: {
           type: "string",
           description: "File path (relative to projectRoot or absolute)."
+        },
+        body: {
+          type: "string",
+          description: "Inline content (e.g., base64-encoded image or UTF-8 text)."
+        },
+        encoding: {
+          type: "string",
+          enum: ["BASE64", "IDENTITY"],
+          description: "Content encoding for an inline body."
+        },
+        charset: {
+          type: "string",
+          description: "Character set for IDENTITY text bodies (default utf-8)."
+        },
+        fileName: {
+          type: "string",
+          description: "Actual artifact filename (distinct from the logical name)."
+        },
+        byteLength: {
+          type: "integer",
+          minimum: 0,
+          description: "Size in bytes, used for embed-vs-link decisions."
+        },
+        stepIndex: {
+          type: "integer",
+          minimum: 0,
+          description: "Step index this attachment belongs to (undefined = test-case level)."
+        },
+        stepId: {
+          type: "string",
+          description: "Stable step ID this attachment belongs to (preferred over stepIndex)."
         }
       },
-      required: ["name", "mediaType", "path"],
+      required: ["name", "mediaType"],
       additionalProperties: false
     },
     RawStepEvent: {
@@ -475,6 +506,22 @@ var raw_run_schema_default = {
         buildNumber: {
           type: "string",
           description: "CI build number or run ID."
+        },
+        provider: {
+          type: "string",
+          description: "Typed provider key (e.g., 'github', 'gitlab', 'circleci')."
+        },
+        branch: {
+          type: "string",
+          description: "Git branch name."
+        },
+        commitSha: {
+          type: "string",
+          description: "Git commit SHA."
+        },
+        prNumber: {
+          type: "string",
+          description: "Pull/merge request number."
         }
       },
       required: ["name"],
@@ -845,7 +892,8 @@ function canonicalizeTestCase(raw, options, projectRoot) {
     projectName: raw.projectName,
     retry: raw.retry ?? 0,
     retries: raw.retries ?? 0,
-    tags
+    tags,
+    ...raw.evidence ? { evidence: raw.evidence } : {}
   };
 }
 function normalizeTags(story) {
@@ -14461,7 +14509,7 @@ function renderDocEntry(entry, deps) {
 // src/formatters/html/renderers/steps.ts
 var CONTINUATION_KEYWORDS = ["And", "But", "*"];
 function renderStep(step, stepResult, index, deps) {
-  const statusIcon2 = stepResult ? deps.getStatusIcon(stepResult.status) : "\u25CB";
+  const statusIcon4 = stepResult ? deps.getStatusIcon(stepResult.status) : "\u25CB";
   const statusClass = stepResult ? `status-${stepResult.status}` : "";
   const duration = stepResult && stepResult.durationMs > 0 ? `${stepResult.durationMs}ms` : "";
   const keywordTrimmed = step.keyword.trim();
@@ -14470,7 +14518,7 @@ function renderStep(step, stepResult, index, deps) {
   const stepDocs = deps.renderDocs(step.docs, "step-docs");
   const textHtml = deps.highlightStepParams ? deps.highlightStepParams(step.text) : deps.escapeHtml(step.text);
   return `<div class="${stepClass}" data-keyword="${deps.escapeHtml(keywordTrimmed)}" data-text="${deps.escapeHtml(step.text)}">
-  <span class="step-status ${statusClass}">${statusIcon2}</span>
+  <span class="step-status ${statusClass}">${statusIcon4}</span>
   <span class="step-keyword">${deps.escapeHtml(step.keyword)}</span>
   <span class="step-text">${textHtml}</span>
   <span class="step-duration">${duration}</span>
@@ -14515,16 +14563,16 @@ function highlightStepParams(text2, deps) {
 var MIN_METRIC_SAMPLES = 5;
 
 // src/formatters/html/renderers/scenario.ts
-function renderTicket(ticket, template, escapeHtml3) {
+function renderTicket(ticket, template, escapeHtml4) {
   const url = ticket.url ?? (template ? template.replace("{ticket}", ticket.id) : void 0);
   if (url) {
-    return `<a class="tag ticket-tag" href="${escapeHtml3(url)}" target="_blank" rel="noopener noreferrer">${escapeHtml3(ticket.id)}</a>`;
+    return `<a class="tag ticket-tag" href="${escapeHtml4(url)}" target="_blank" rel="noopener noreferrer">${escapeHtml4(ticket.id)}</a>`;
   }
-  return `<span class="tag ticket-tag">${escapeHtml3(ticket.id)}</span>`;
+  return `<span class="tag ticket-tag">${escapeHtml4(ticket.id)}</span>`;
 }
 function renderScenario(args, deps) {
   const { tc } = args;
-  const statusIcon2 = deps.getStatusIcon(tc.status);
+  const statusIcon4 = deps.getStatusIcon(tc.status);
   const statusClass = `status-${tc.status}`;
   const duration = tc.durationMs > 0 ? `${(tc.durationMs / 1e3).toFixed(2)}s` : "";
   const tags = tc.tags.map((t) => `<span class="tag">${deps.escapeHtml(t)}</span>`).join("");
@@ -14594,7 +14642,7 @@ function renderScenario(args, deps) {
   <div class="scenario-header" role="button" tabindex="0" aria-expanded="${ariaExpanded}">
     <div class="scenario-info">
       <div class="scenario-title">
-        <span class="status-icon ${statusClass}">${statusIcon2}</span>
+        <span class="status-icon ${statusClass}">${statusIcon4}</span>
         <span class="scenario-name">${deps.escapeHtml(tc.story.scenario)}</span>
       </div>
       <div class="scenario-meta">${tags}${tickets}${outcomeBadge}${sourceLink}${traceBadge}${metricBadges}</div>
@@ -14720,7 +14768,7 @@ function flattenTree(roots) {
   }
   return result;
 }
-function buildTooltip(span, escapeHtml3) {
+function buildTooltip(span, escapeHtml4) {
   const parts = [];
   parts.push(`${span.name} (${formatDuration(span.durationMs)})`);
   if (span.statusMessage) {
@@ -14738,7 +14786,7 @@ function buildTooltip(span, escapeHtml3) {
   if (text2.length > TOOLTIP_MAX_LENGTH) {
     text2 = text2.slice(0, TOOLTIP_MAX_LENGTH - 3) + "...";
   }
-  return escapeHtml3(text2);
+  return escapeHtml4(text2);
 }
 function renderTraceView(args, deps) {
   if (!args.spans || args.spans.length === 0) return "";
@@ -14961,11 +15009,11 @@ function renderToc(args, deps) {
     const featureName = suitePaths.length > 0 && suitePaths[0].length > 0 ? suitePaths[0][0] : file.split("/").pop()?.replace(/\.[^.]+$/, "") ?? file;
     const featureSlug = `feature-${slugify(file)}`;
     const scenarios = testCases.map((tc) => {
-      const statusIcon2 = deps.getStatusIcon(tc.status);
+      const statusIcon4 = deps.getStatusIcon(tc.status);
       const statusClass = `status-${tc.status}`;
       const failedClass = tc.status === "failed" ? " toc-failed" : "";
       return `<a class="toc-scenario${failedClass}" href="#scenario-${tc.id}">
-          <span class="toc-status ${statusClass}">${statusIcon2}</span>
+          <span class="toc-status ${statusClass}">${statusIcon4}</span>
           ${deps.escapeHtml(tc.story.scenario)}
         </a>`;
     }).join("\n");
@@ -19482,6 +19530,697 @@ function listScenarios(args, _deps) {
   return lines.join("\n");
 }
 
+// src/review/conventions.ts
+var CHANGE_TAG_PREFIX = "change:";
+var AUDIENCE_TAG_PREFIX = "audience:";
+var VALID_CHANGE_TYPES = /* @__PURE__ */ new Set([
+  "feature",
+  "bugfix",
+  "refactor",
+  "perf",
+  "deps"
+]);
+var STAKEHOLDER_FILE = /(?:\.e2e\.)|(?:^|\/)e2e\/|(?:\.spec\.)/i;
+var CODE_EXTENSIONS = /* @__PURE__ */ new Set([
+  "ts",
+  "tsx",
+  "js",
+  "jsx",
+  "mjs",
+  "cjs",
+  "py",
+  "go",
+  "rs",
+  "kt",
+  "kts",
+  "java",
+  "cs",
+  "rb"
+]);
+var TEST_INFIX = /\.(?:story\.)?(?:int\.|e2e\.|unit\.)?(?:test|spec|cy)\.[a-z]+$/i;
+function deriveAudience(sourceFile, tags) {
+  const override = tags.map((t) => t.toLowerCase()).find((t) => t.startsWith(AUDIENCE_TAG_PREFIX));
+  if (override) {
+    const value = override.slice(AUDIENCE_TAG_PREFIX.length);
+    if (value === "stakeholder" || value === "engineer") return value;
+  }
+  return STAKEHOLDER_FILE.test(sourceFile) ? "stakeholder" : "engineer";
+}
+function deriveChangeType(tags) {
+  for (const tag of tags) {
+    const lower = tag.toLowerCase();
+    if (lower.startsWith(CHANGE_TAG_PREFIX)) {
+      const value = lower.slice(CHANGE_TAG_PREFIX.length);
+      if (VALID_CHANGE_TYPES.has(value)) return value;
+    }
+  }
+  return "unknown";
+}
+function extensionOf(path10) {
+  const base = path10.split("/").pop() ?? path10;
+  const dot = base.lastIndexOf(".");
+  return dot === -1 ? "" : base.slice(dot + 1).toLowerCase();
+}
+function isTestFile(path10) {
+  return TEST_INFIX.test(path10);
+}
+function isReviewableSource(path10) {
+  if (isTestFile(path10)) return false;
+  if (path10.endsWith(".d.ts")) return false;
+  return CODE_EXTENSIONS.has(extensionOf(path10));
+}
+function testBaseKey(testFile) {
+  return testFile.replace(TEST_INFIX, "");
+}
+function sourceBaseKey(sourceFile) {
+  const dot = sourceFile.lastIndexOf(".");
+  const slash = sourceFile.lastIndexOf("/");
+  return dot > slash ? sourceFile.slice(0, dot) : sourceFile;
+}
+
+// src/review/build-review.ts
+var STRENGTH_RANK = {
+  none: 0,
+  weak: 1,
+  moderate: 2,
+  strong: 3
+};
+var INTENT_SECTION_TITLE = /\b(why|intent|approach|rationale|reasoning)\b/i;
+function findDoc(docs, predicate) {
+  if (!docs) return void 0;
+  for (const doc of docs) {
+    if (predicate(doc)) return doc;
+    const nested = findDoc(doc.children, predicate);
+    if (nested) return nested;
+  }
+  return void 0;
+}
+function anyDoc(docs, predicate) {
+  return findDoc(docs, predicate) !== void 0;
+}
+function extractIntent(testCase) {
+  const docs = testCase.story.docs;
+  const section = findDoc(
+    docs,
+    (d) => d.kind === "section" && INTENT_SECTION_TITLE.test(d.title)
+  );
+  if (section && section.kind === "section") return section.markdown;
+  const note = findDoc(docs, (d) => d.kind === "note");
+  if (note && note.kind === "note") return note.text;
+  return void 0;
+}
+function hasScreenshot(testCase) {
+  if (testCase.attachments.some((a) => a.mediaType.startsWith("image/"))) {
+    return true;
+  }
+  if (anyDoc(testCase.story.docs, (d) => d.kind === "screenshot")) return true;
+  return testCase.story.steps.some(
+    (step) => anyDoc(step.docs, (d) => d.kind === "screenshot")
+  );
+}
+function hasOtelTrace(testCase) {
+  return (testCase.story.otelSpans?.length ?? 0) > 0;
+}
+function gradeEvidence(testCase, audience) {
+  if (testCase.status !== "passed") {
+    return {
+      strength: "none",
+      reasons: [`test is ${testCase.status} \u2014 the proof does not hold`]
+    };
+  }
+  const ev = testCase.evidence;
+  const screenshot = hasScreenshot(testCase);
+  const otel = hasOtelTrace(testCase);
+  const isIntegration = /\.int\.test\./i.test(testCase.sourceFile);
+  const mutation = ev?.mutationScorePct;
+  const changedCov = ev?.changedLineCoveragePct;
+  const strong2 = [];
+  if (ev?.failingFirstVerified) {
+    strong2.push("failing-first verified (red on base ref, green on head)");
+  }
+  if (typeof mutation === "number" && mutation >= 80) {
+    strong2.push(`mutation score ${mutation}% (\u226580%)`);
+  }
+  if (screenshot && otel) {
+    strong2.push("backed by screenshot + OTEL trace");
+  } else if (audience === "stakeholder" && (screenshot || otel)) {
+    strong2.push(`stakeholder proof: ${screenshot ? "screenshot" : "OTEL trace"}`);
+  }
+  if (strong2.length > 0) return { strength: "strong", reasons: strong2 };
+  const moderate = [];
+  if (screenshot) moderate.push("screenshot attached");
+  if (otel) moderate.push("OTEL trace attached");
+  if (typeof mutation === "number" && mutation >= 50) {
+    moderate.push(`mutation score ${mutation}%`);
+  }
+  if (typeof changedCov === "number" && changedCov >= 80) {
+    moderate.push(`changed-line coverage ${changedCov}%`);
+  }
+  if (isIntegration) moderate.push("integration-level test");
+  if (moderate.length > 0) return { strength: "moderate", reasons: moderate };
+  return {
+    strength: "weak",
+    reasons: [
+      "passing test only \u2014 no corroborating evidence (add e2e proof, mutation score, or failing-first)"
+    ]
+  };
+}
+function toClaim(testCase, changedSourcePaths) {
+  const audience = deriveAudience(testCase.sourceFile, testCase.tags);
+  const changeType = deriveChangeType(testCase.tags);
+  const { strength, reasons } = gradeEvidence(testCase, audience);
+  const key = testBaseKey(testCase.sourceFile);
+  const coversFiles = changedSourcePaths.filter(
+    (path10) => sourceBaseKey(path10) === key
+  );
+  return {
+    id: testCase.id,
+    scenario: testCase.story.scenario,
+    sourceFile: testCase.sourceFile,
+    sourceLine: testCase.sourceLine,
+    status: testCase.status,
+    audience,
+    changeType,
+    strength,
+    strengthReasons: reasons,
+    intent: extractIntent(testCase),
+    coversFiles,
+    testCase
+  };
+}
+function bandFor(claims) {
+  if (claims.length === 0) return "uncovered";
+  const maxRank = Math.max(...claims.map((c) => STRENGTH_RANK[c.strength]));
+  return maxRank >= STRENGTH_RANK.moderate ? "covered" : "weak";
+}
+var AUDIENCE_ORDER = {
+  stakeholder: 0,
+  engineer: 1
+};
+function buildReview(run, context = { changedFiles: [] }) {
+  const changedSource = context.changedFiles.filter(
+    (f) => isReviewableSource(f.path)
+  );
+  const changedSourcePaths = changedSource.map((f) => f.path);
+  const claims = run.testCases.map((tc) => toClaim(tc, changedSourcePaths));
+  const changedFiles = changedSource.map((file) => {
+    const covering = claims.filter((c) => c.coversFiles.includes(file.path));
+    return {
+      path: file.path,
+      changeKind: file.changeKind,
+      band: bandFor(covering),
+      claims: covering.map((c) => ({
+        id: c.id,
+        scenario: c.scenario,
+        strength: c.strength
+      }))
+    };
+  });
+  const sortedClaims = [...claims].sort((a, b) => {
+    if (AUDIENCE_ORDER[a.audience] !== AUDIENCE_ORDER[b.audience]) {
+      return AUDIENCE_ORDER[a.audience] - AUDIENCE_ORDER[b.audience];
+    }
+    if (STRENGTH_RANK[a.strength] !== STRENGTH_RANK[b.strength]) {
+      return STRENGTH_RANK[a.strength] - STRENGTH_RANK[b.strength];
+    }
+    if (a.sourceFile !== b.sourceFile) {
+      return a.sourceFile.localeCompare(b.sourceFile);
+    }
+    return a.scenario.localeCompare(b.scenario);
+  });
+  const bandRank = { uncovered: 0, weak: 1, covered: 2 };
+  const sortedFiles = [...changedFiles].sort((a, b) => {
+    if (bandRank[a.band] !== bandRank[b.band]) {
+      return bandRank[a.band] - bandRank[b.band];
+    }
+    return a.path.localeCompare(b.path);
+  });
+  const summary = buildSummary2(sortedClaims, sortedFiles);
+  return {
+    run,
+    context,
+    summary,
+    claims: sortedClaims,
+    changedFiles: sortedFiles
+  };
+}
+function buildSummary2(claims, changedFiles) {
+  const byAudience = {
+    stakeholder: 0,
+    engineer: 0
+  };
+  const byStrength = {
+    none: 0,
+    weak: 0,
+    moderate: 0,
+    strong: 0
+  };
+  for (const claim of claims) {
+    byAudience[claim.audience] += 1;
+    byStrength[claim.strength] += 1;
+  }
+  return {
+    totalClaims: claims.length,
+    byAudience,
+    byStrength,
+    changedSourceFiles: changedFiles.length,
+    uncovered: changedFiles.filter((f) => f.band === "uncovered").length,
+    weaklyCovered: changedFiles.filter((f) => f.band === "weak").length,
+    covered: changedFiles.filter((f) => f.band === "covered").length
+  };
+}
+
+// src/formatters/review-markdown.ts
+var STRENGTH_BADGE = {
+  strong: "\u{1F7E2} strong",
+  moderate: "\u{1F7E1} moderate",
+  weak: "\u{1F7E0} weak",
+  none: "\u{1F534} none"
+};
+function statusIcon2(status) {
+  switch (status) {
+    case "passed":
+      return "\u2705";
+    case "failed":
+      return "\u274C";
+    case "skipped":
+      return "\u2298";
+    default:
+      return "\u2022";
+  }
+}
+function escapeCell2(value) {
+  return value.replace(/\|/g, "\\|").replace(/\n/g, " ");
+}
+function intentSummary(intent) {
+  const firstLine = intent.split("\n").find((l) => l.trim().length > 0) ?? "";
+  const trimmed = firstLine.trim();
+  return trimmed.length > 200 ? `${trimmed.slice(0, 197)}\u2026` : trimmed;
+}
+function renderTicket2(ticket) {
+  return ticket.url ? `[${ticket.id}](${ticket.url})` : `\`${ticket.id}\``;
+}
+function renderUncoveredBand(lines, files) {
+  const uncovered = files.filter((f) => f.band === "uncovered");
+  if (uncovered.length === 0) return;
+  lines.push(`## \u{1F534} Changed code with no evidence (${uncovered.length})`);
+  lines.push("");
+  lines.push("Start here \u2014 these changed source files have no claim or test behind them.");
+  lines.push("");
+  for (const file of uncovered) {
+    lines.push(`- \`${file.path}\` _(${file.changeKind})_`);
+  }
+  lines.push("");
+}
+function renderWeakBand(lines, files) {
+  const weak = files.filter((f) => f.band === "weak");
+  if (weak.length === 0) return;
+  lines.push(`## \u{1F7E1} Changed code with weak evidence (${weak.length})`);
+  lines.push("");
+  for (const file of weak) {
+    const covered = file.claims.map((c) => `${escapeCell2(c.scenario)} (${c.strength})`).join(", ");
+    lines.push(`- \`${file.path}\` _(${file.changeKind})_ \u2014 only: ${covered}`);
+  }
+  lines.push("");
+}
+function renderClaim(lines, claim) {
+  lines.push(`### ${statusIcon2(claim.status)} ${claim.scenario}`);
+  lines.push("");
+  lines.push(`- File: \`${claim.sourceFile}:${claim.sourceLine}\``);
+  if (claim.changeType !== "unknown") {
+    lines.push(`- Change: \`${claim.changeType}\``);
+  }
+  const tickets = claim.testCase.story.tickets ?? [];
+  if (tickets.length > 0) {
+    lines.push(`- Tickets: ${tickets.map(renderTicket2).join(", ")}`);
+  }
+  lines.push(
+    `- Evidence: ${STRENGTH_BADGE[claim.strength]} \u2014 ${claim.strengthReasons.join("; ")}`
+  );
+  if (claim.coversFiles.length > 0) {
+    lines.push(
+      `- Covers: ${claim.coversFiles.map((f) => `\`${f}\``).join(", ")}`
+    );
+  }
+  if (claim.intent) {
+    lines.push(`- Why: ${escapeCell2(intentSummary(claim.intent))}`);
+  }
+  lines.push("");
+}
+function renderAudienceSection(lines, title, claims) {
+  if (claims.length === 0) return;
+  lines.push(`## ${title} (${claims.length})`);
+  lines.push("");
+  for (const claim of claims) {
+    renderClaim(lines, claim);
+  }
+}
+var ReviewMarkdownFormatter = class {
+  title;
+  constructor(options = {}) {
+    this.title = options.title ?? "Evidence Review";
+  }
+  format(review) {
+    const lines = [];
+    const { summary, context } = review;
+    lines.push(`# ${this.title}`);
+    lines.push("");
+    if (context.baseRef || context.headRef) {
+      lines.push(
+        `Comparing \`${context.baseRef ?? "base"}\` \u2192 \`${context.headRef ?? "head"}\`.`
+      );
+      lines.push("");
+    }
+    lines.push("## Review priority");
+    lines.push("");
+    if (summary.changedSourceFiles === 0) {
+      lines.push(
+        "No changed source files supplied \u2014 showing claims and evidence only."
+      );
+    } else if (summary.uncovered > 0) {
+      lines.push(
+        `Review the ${summary.uncovered} unaccounted-for file(s) first: changed code with no evidence behind it.`
+      );
+    } else if (summary.weaklyCovered > 0) {
+      lines.push(
+        `No unaccounted-for changes. Review ${summary.weaklyCovered} weakly-covered file(s) next.`
+      );
+    } else {
+      lines.push("Every changed source file is backed by at least moderate evidence.");
+    }
+    lines.push("");
+    if (summary.changedSourceFiles > 0) {
+      lines.push("| \u{1F534} Uncovered | \u{1F7E1} Weak | \u{1F7E2} Covered | Changed files |");
+      lines.push("| ---: | ---: | ---: | ---: |");
+      lines.push(
+        `| ${summary.uncovered} | ${summary.weaklyCovered} | ${summary.covered} | ${summary.changedSourceFiles} |`
+      );
+      lines.push("");
+    }
+    lines.push("| Claims | Stakeholder | Engineer | Strong | Moderate | Weak | None |");
+    lines.push("| ---: | ---: | ---: | ---: | ---: | ---: | ---: |");
+    lines.push(
+      `| ${summary.totalClaims} | ${summary.byAudience.stakeholder} | ${summary.byAudience.engineer} | ${summary.byStrength.strong} | ${summary.byStrength.moderate} | ${summary.byStrength.weak} | ${summary.byStrength.none} |`
+    );
+    lines.push("");
+    renderUncoveredBand(lines, review.changedFiles);
+    renderWeakBand(lines, review.changedFiles);
+    renderAudienceSection(
+      lines,
+      "Stakeholder behaviour",
+      review.claims.filter((c) => c.audience === "stakeholder")
+    );
+    renderAudienceSection(
+      lines,
+      "Engineer changes",
+      review.claims.filter((c) => c.audience === "engineer")
+    );
+    return lines.join("\n").trimEnd();
+  }
+};
+
+// src/formatters/review-html.ts
+function escapeHtml3(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+var STRENGTH_LABEL = {
+  strong: "Strong",
+  moderate: "Moderate",
+  weak: "Weak",
+  none: "None"
+};
+function statusIcon3(status) {
+  switch (status) {
+    case "passed":
+      return "\u2705";
+    case "failed":
+      return "\u274C";
+    case "skipped":
+      return "\u2298";
+    default:
+      return "\u2022";
+  }
+}
+function formatStep3(step) {
+  return `<li><strong>${escapeHtml3(step.keyword)}</strong> ${escapeHtml3(step.text)}</li>`;
+}
+function inlineDoc(doc) {
+  switch (doc.kind) {
+    case "note":
+      return escapeHtml3(doc.text);
+    case "section":
+      return `<strong>${escapeHtml3(doc.title)}</strong>: ${escapeHtml3(doc.markdown)}`;
+    case "kv":
+      return `${escapeHtml3(doc.label)}: ${escapeHtml3(String(doc.value))}`;
+    case "code":
+      return `${escapeHtml3(doc.label)}: <code>${escapeHtml3(doc.content)}</code>`;
+    case "link":
+      return `${escapeHtml3(doc.label)}: ${escapeHtml3(doc.url)}`;
+    default:
+      return escapeHtml3(doc.kind);
+  }
+}
+function renderEvidenceArtifacts(testCase) {
+  const parts = [];
+  for (const att of testCase.attachments) {
+    if (att.mediaType.startsWith("image/") && att.contentEncoding === "BASE64") {
+      parts.push(
+        `<img class="shot" alt="${escapeHtml3(att.name)}" src="data:${escapeHtml3(att.mediaType)};base64,${att.body}" />`
+      );
+    }
+  }
+  if ((testCase.story.otelSpans?.length ?? 0) > 0) {
+    parts.push(
+      `<p class="trace-note">\u{1F4E1} ${testCase.story.otelSpans.length} OTEL span(s) captured</p>`
+    );
+  }
+  return parts.length > 0 ? `<div class="artifacts">${parts.join("")}</div>` : "";
+}
+function renderTicketPills(claim) {
+  const tickets = claim.testCase.story.tickets ?? [];
+  if (tickets.length === 0) return "";
+  return `<div class="ticket-row">${tickets.map((ticket) => {
+    const label = escapeHtml3(ticket.id);
+    if (ticket.url) {
+      return `<a class="ticket-pill" href="${escapeHtml3(ticket.url)}" target="_blank" rel="noopener noreferrer">${label}</a>`;
+    }
+    return `<span class="ticket-pill">${label}</span>`;
+  }).join("")}</div>`;
+}
+function renderClaimCard(claim) {
+  const ticketSearch = (claim.testCase.story.tickets ?? []).map((ticket) => ticket.id).join(" ");
+  const search = escapeHtml3(
+    `${claim.scenario} ${claim.sourceFile} ${claim.changeType} ${claim.audience} ${claim.strength} ${ticketSearch}`
+  ).toLowerCase();
+  const steps = claim.testCase.story.steps.length > 0 ? `<ul class="step-list">${claim.testCase.story.steps.map(formatStep3).join("")}</ul>` : "";
+  const reasons = `<ul class="reasons">${claim.strengthReasons.map((r) => `<li>${escapeHtml3(r)}</li>`).join("")}</ul>`;
+  const intent = claim.intent !== void 0 ? `<div class="intent"><span class="intent-label">Why</span> ${escapeHtml3(claim.intent)}</div>` : "";
+  const covers = claim.coversFiles.length > 0 ? `<p class="covers">Covers ${claim.coversFiles.map((f) => `<code>${escapeHtml3(f)}</code>`).join(", ")}</p>` : "";
+  const docs = (claim.testCase.story.docs ?? []).filter(
+    (d) => d.kind === "section" || d.kind === "note"
+  );
+  const extraDocs = docs.length > 0 && claim.intent === void 0 ? `<div class="intent">${docs.map(inlineDoc).join("<br>")}</div>` : "";
+  return `
+    <article class="claim-card" data-audience="${claim.audience}" data-strength="${claim.strength}" data-search="${search}">
+      <header class="claim-header">
+        <div>
+          <span class="strength-badge strength-${claim.strength}">${STRENGTH_LABEL[claim.strength]}</span>
+          ${claim.changeType !== "unknown" ? `<span class="change-pill">${escapeHtml3(claim.changeType)}</span>` : ""}
+          <h3>${statusIcon3(claim.status)} ${escapeHtml3(claim.scenario)}</h3>
+          <p class="source">${escapeHtml3(`${claim.sourceFile}:${claim.sourceLine}`)}</p>
+          ${renderTicketPills(claim)}
+        </div>
+      </header>
+      ${intent}${extraDocs}
+      <div class="evidence-block">
+        <span class="evidence-label">Evidence</span>
+        ${reasons}
+      </div>
+      ${covers}
+      ${renderEvidenceArtifacts(claim.testCase)}
+      ${steps}
+    </article>`;
+}
+function renderChangedFileRow(file) {
+  const claims = file.claims.length > 0 ? file.claims.map((c) => `${escapeHtml3(c.scenario)} <em>(${c.strength})</em>`).join(", ") : "\u2014";
+  return `<tr data-band="${file.band}">
+    <td><span class="band-dot band-${file.band}"></span></td>
+    <td><code>${escapeHtml3(file.path)}</code></td>
+    <td>${escapeHtml3(file.changeKind)}</td>
+    <td>${claims}</td>
+  </tr>`;
+}
+function renderAudienceSection2(title, claims) {
+  if (claims.length === 0) return "";
+  return `<section class="audience-section">
+    <h2>${escapeHtml3(title)} <span class="count">${claims.length}</span></h2>
+    <div class="claim-list">${claims.map(renderClaimCard).join("\n")}</div>
+  </section>`;
+}
+var REVIEW_CSS = `
+  * { box-sizing: border-box; }
+  body { margin: 0; font-family: var(--font-sans, system-ui, sans-serif); background: var(--background); color: var(--foreground); }
+  main { max-width: 1100px; margin: 0 auto; padding: 32px 20px 80px; }
+  h1, h2, h3, p { margin: 0; }
+  .review-header { display: flex; justify-content: space-between; align-items: center; margin-bottom: 8px; }
+  .subtle { color: var(--muted-foreground); margin-top: 6px; }
+  .theme-toggle { background: var(--secondary); border: 1px solid var(--border); border-radius: 8px; padding: 8px 12px; cursor: pointer; font-size: 1.1rem; color: var(--foreground); }
+  .card, .claim-card, .summary-card, .panel { background: var(--card); border: 1px solid var(--border); border-radius: var(--radius, 16px); }
+  .hero-card { padding: 24px; margin-bottom: 20px; }
+  .summary-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(120px, 1fr)); gap: 12px; margin-bottom: 20px; }
+  .summary-card { padding: 14px 16px; }
+  .summary-card strong { display: block; font-size: 1.8rem; }
+  .priority-banner { padding: 18px 20px; margin-bottom: 20px; background: linear-gradient(135deg, color-mix(in srgb, var(--destructive) 10%, transparent), var(--card)); }
+  .panel { padding: 18px; margin-bottom: 24px; }
+  table { width: 100%; border-collapse: collapse; }
+  th, td { text-align: left; padding: 8px 10px; border-bottom: 1px solid var(--border); vertical-align: top; }
+  th { color: var(--muted-foreground); font-weight: 600; }
+  .band-dot { display: inline-block; width: 12px; height: 12px; border-radius: 50%; }
+  .band-uncovered { background: var(--destructive); }
+  .band-weak { background: var(--warning, #b58900); }
+  .band-covered { background: var(--success, #2e7d32); }
+  .toolbar { position: sticky; top: 12px; z-index: 2; display: flex; flex-wrap: wrap; gap: 10px; padding: 14px; margin-bottom: 20px; }
+  .toolbar input { flex: 1 1 240px; border: 1px solid var(--border); border-radius: 999px; padding: 10px 14px; font: inherit; background: var(--background); color: var(--foreground); }
+  .toolbar button { border: 1px solid var(--border); background: var(--secondary); border-radius: 999px; padding: 10px 14px; font: inherit; cursor: pointer; color: var(--foreground); }
+  .toolbar button.active { background: var(--foreground); color: var(--background); }
+  .audience-section { margin-bottom: 28px; }
+  .audience-section h2 { margin-bottom: 12px; }
+  .count { color: var(--muted-foreground); font-weight: 400; }
+  .claim-list { display: grid; gap: 14px; }
+  .claim-card { padding: 18px; }
+  .claim-header h3 { margin-top: 8px; }
+  .source { color: var(--muted-foreground); font-family: var(--font-mono, ui-monospace, monospace); font-size: 0.85rem; margin-top: 4px; }
+  .ticket-row { display: flex; flex-wrap: wrap; gap: 6px; margin-top: 8px; }
+  .ticket-pill { display: inline-flex; align-items: center; border: 1px solid var(--border); border-radius: 999px; padding: 3px 9px; color: var(--muted-foreground); background: var(--background); font-size: 0.78rem; text-decoration: none; }
+  .ticket-pill:hover { color: var(--foreground); border-color: var(--muted-foreground); }
+  .strength-badge, .change-pill { display: inline-flex; align-items: center; padding: 3px 10px; border-radius: 999px; font-size: 0.8rem; margin-right: 6px; }
+  .change-pill { background: var(--secondary); }
+  .strength-strong { background: color-mix(in srgb, var(--success, #2e7d32) 18%, transparent); color: var(--success, #2e7d32); }
+  .strength-moderate { background: color-mix(in srgb, var(--warning, #b58900) 20%, transparent); color: var(--warning, #b58900); }
+  .strength-weak { background: color-mix(in srgb, #d2691e 20%, transparent); color: #b5530a; }
+  .strength-none { background: color-mix(in srgb, var(--destructive) 16%, transparent); color: var(--destructive); }
+  .intent { margin: 12px 0; padding: 10px 12px; border-left: 3px solid var(--border); background: color-mix(in srgb, var(--card) 60%, var(--background)); border-radius: 6px; }
+  .intent-label { font-weight: 700; margin-right: 6px; }
+  .evidence-block { margin-top: 10px; }
+  .evidence-label { font-weight: 600; color: var(--muted-foreground); }
+  .reasons { margin: 6px 0 0; padding-left: 18px; }
+  .covers { color: var(--muted-foreground); margin-top: 8px; font-size: 0.9rem; }
+  .artifacts { margin-top: 12px; display: flex; flex-wrap: wrap; gap: 10px; align-items: flex-start; }
+  .shot { max-width: 280px; max-height: 200px; border: 1px solid var(--border); border-radius: 8px; }
+  .trace-note { color: var(--muted-foreground); }
+  .step-list { margin: 12px 0 0; padding-left: 18px; color: var(--muted-foreground); }
+`;
+var JS_THEME_TOGGLE2 = `
+function getSystemTheme() { return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'; }
+function getEffectiveTheme() { var s = localStorage.getItem('review-theme'); return (s === 'dark' || s === 'light') ? s : getSystemTheme(); }
+function toggleTheme() { var n = getEffectiveTheme() === 'dark' ? 'light' : 'dark'; localStorage.setItem('review-theme', n); applyTheme(n); }
+function applyTheme(t) {
+  document.documentElement.setAttribute('data-theme', t);
+  var b = document.querySelector('.theme-toggle');
+  if (b) { b.textContent = t === 'dark' ? '\\u2600\\ufe0f' : '\\ud83c\\udf19'; }
+}
+`;
+var ReviewHtmlFormatter = class {
+  title;
+  theme;
+  darkMode;
+  constructor(options = {}) {
+    this.title = options.title ?? "Evidence Review";
+    this.theme = resolveTheme(options.theme ?? "default");
+    this.darkMode = options.darkMode ?? true;
+  }
+  format(review) {
+    const { summary, context } = review;
+    const priority = summary.changedSourceFiles === 0 ? "No changed source files supplied \u2014 showing claims and evidence only." : summary.uncovered > 0 ? `${summary.uncovered} changed file(s) have no evidence. Review them first.` : summary.weaklyCovered > 0 ? `No unaccounted-for changes. ${summary.weaklyCovered} file(s) are weakly covered.` : "Every changed source file is backed by at least moderate evidence.";
+    const changedFilesPanel = summary.changedSourceFiles > 0 ? `<section class="panel">
+            <h2>Changed files</h2>
+            <table>
+              <thead><tr><th></th><th>File</th><th>Change</th><th>Evidence</th></tr></thead>
+              <tbody>${review.changedFiles.map(renderChangedFileRow).join("")}</tbody>
+            </table>
+          </section>` : "";
+    const themeToggleHtml = this.darkMode ? `<button type="button" class="theme-toggle" onclick="toggleTheme()" aria-label="Toggle theme"></button>` : "";
+    const themeInitJs = this.darkMode ? `${JS_THEME_TOGGLE2}
+applyTheme(getEffectiveTheme());` : "";
+    const themeAttr = this.darkMode ? ' data-theme="light"' : "";
+    const refsLine = context.baseRef || context.headRef ? `<p class="subtle">Comparing ${escapeHtml3(context.baseRef ?? "base")} \u2192 ${escapeHtml3(context.headRef ?? "head")}</p>` : "";
+    return `<!doctype html>
+<html lang="en"${themeAttr}>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${escapeHtml3(this.title)}</title>
+    <style>
+      ${this.theme.css}
+      ${REVIEW_CSS}
+    </style>
+  </head>
+  <body>
+    <main>
+      <div class="hero-card card">
+        <div class="review-header">
+          <h1>${escapeHtml3(this.title)}</h1>
+          ${themeToggleHtml}
+        </div>
+        ${refsLine}
+      </div>
+      <section class="summary-grid">
+        <div class="summary-card"><strong>${summary.uncovered}</strong><span>\u{1F534} Uncovered</span></div>
+        <div class="summary-card"><strong>${summary.weaklyCovered}</strong><span>\u{1F7E1} Weak</span></div>
+        <div class="summary-card"><strong>${summary.covered}</strong><span>\u{1F7E2} Covered</span></div>
+        <div class="summary-card"><strong>${summary.totalClaims}</strong><span>Claims</span></div>
+        <div class="summary-card"><strong>${summary.byStrength.strong}</strong><span>Strong</span></div>
+        <div class="summary-card"><strong>${summary.byStrength.weak + summary.byStrength.none}</strong><span>Weak/None</span></div>
+      </section>
+      <section class="card priority-banner">
+        <h2>Review priority</h2>
+        <p class="subtle">${escapeHtml3(priority)}</p>
+      </section>
+      ${changedFilesPanel}
+      <section class="toolbar">
+        <input type="search" placeholder="Filter claims by scenario, file, change-type" aria-label="Filter claims" />
+        <button type="button" class="active" data-filter="all">All</button>
+        <button type="button" data-filter="stakeholder">Stakeholder</button>
+        <button type="button" data-filter="engineer">Engineer</button>
+        <button type="button" data-filter="weak">Weak/None</button>
+      </section>
+      ${renderAudienceSection2("Stakeholder behaviour", review.claims.filter((c) => c.audience === "stakeholder"))}
+      ${renderAudienceSection2("Engineer changes", review.claims.filter((c) => c.audience === "engineer"))}
+    </main>
+    <script>
+      ${themeInitJs}
+      const input = document.querySelector('input[type="search"]');
+      const buttons = Array.from(document.querySelectorAll('[data-filter]'));
+      const cards = Array.from(document.querySelectorAll('.claim-card'));
+      let activeFilter = 'all';
+      function applyFilters() {
+        const query = (input.value || '').trim().toLowerCase();
+        cards.forEach((card) => {
+          const audience = card.getAttribute('data-audience');
+          const strength = card.getAttribute('data-strength');
+          const haystack = card.getAttribute('data-search') || '';
+          let matchesFilter = activeFilter === 'all'
+            || audience === activeFilter
+            || (activeFilter === 'weak' && (strength === 'weak' || strength === 'none'));
+          const matchesSearch = !query || haystack.includes(query);
+          card.style.display = matchesFilter && matchesSearch ? '' : 'none';
+        });
+      }
+      input.addEventListener('input', applyFilters);
+      buttons.forEach((button) => {
+        button.addEventListener('click', () => {
+          activeFilter = button.getAttribute('data-filter');
+          buttons.forEach((b) => b.classList.toggle('active', b === button));
+          applyFilters();
+        });
+      });
+      applyFilters();
+    </script>
+  </body>
+</html>`;
+  }
+};
+
 // src/index.ts
 var FORMAT_EXTENSIONS = {
   astro: ".md",
@@ -19977,6 +20716,7 @@ var EXIT_CANONICAL_VALIDATION = 2;
 var EXIT_GENERATION = 3;
 var EXIT_USAGE = 4;
 var EXIT_COMPARE_GATE = 5;
+var EXIT_REVIEW_GATE = 5;
 var HELP_TEXT = `
 executable-stories \u2014 Generate reports from test results JSON.
 
@@ -19984,6 +20724,7 @@ USAGE
   executable-stories format <file> [options]
   executable-stories format --stdin [options]
   executable-stories compare <baseline-file> <current-file> [options]
+  executable-stories review <file> --changed-files <path> [options]
   executable-stories list <file> [options]
   executable-stories validate <file>
   executable-stories validate --stdin
@@ -19994,6 +20735,7 @@ USAGE
 SUBCOMMANDS
   format             Read raw test results and generate reports
   compare            Compare two runs and generate a diff report
+  review             Generate an Evidence Review of AI-authored changes (correlate a run to the diff)
   list               List scenarios from a test run (text table or JSON)
   validate           Validate a JSON file against the schema (no output generated)
   init-astro         Scaffold an Astro docs site for story output (Starlight with themed CSS)
@@ -20044,6 +20786,11 @@ OPTIONS
   --fail-on-regression          Exit non-zero when any regression is detected in compare
   --fail-on-added-failures      Exit non-zero when newly added scenarios are failing
   --max-regressions <n>         Exit non-zero when regressions exceed threshold
+  --changed-files <path>        (review) Changed files: JSON (ChangedFile[] or {changedFiles,baseRef,headRef}) or "git diff --name-status" text
+  --base-ref <ref>              (review) Base ref label shown in the report (informational)
+  --head-ref <ref>              (review) Head ref label shown in the report (informational)
+  --fail-on <band>              (review) Gate: "uncovered" or "weak" \u2014 exit non-zero when changed code lacks evidence (default: off)
+  --min-evidence <strength>     (review) Gate: "weak"|"moderate"|"strong" \u2014 exit non-zero when any claim is below this strength (default: off)
   --emit-canonical <path>       Write canonical JSON to given path
   --help                        Show this help message
 
@@ -20116,9 +20863,9 @@ async function parseCliArgs(argv) {
     process.exit(EXIT_SUCCESS);
   }
   const subcommand = args[0];
-  if (subcommand !== "format" && subcommand !== "compare" && subcommand !== "list" && subcommand !== "validate" && subcommand !== "init-astro" && subcommand !== "publish-confluence" && subcommand !== "publish-jira") {
+  if (subcommand !== "format" && subcommand !== "compare" && subcommand !== "review" && subcommand !== "list" && subcommand !== "validate" && subcommand !== "init-astro" && subcommand !== "publish-confluence" && subcommand !== "publish-jira") {
     console.error(
-      `Unknown subcommand: "${subcommand}". Use "format", "compare", "list", "validate", "init-astro", "publish-confluence", or "publish-jira".`
+      `Unknown subcommand: "${subcommand}". Use "format", "compare", "review", "list", "validate", "init-astro", "publish-confluence", or "publish-jira".`
     );
     process.exit(EXIT_USAGE);
   }
@@ -20212,6 +20959,11 @@ async function parseCliArgs(argv) {
       "fail-on-regression": { type: "boolean", default: false },
       "fail-on-added-failures": { type: "boolean", default: false },
       "max-regressions": { type: "string" },
+      "changed-files": { type: "string" },
+      "base-ref": { type: "string" },
+      "head-ref": { type: "string" },
+      "fail-on": { type: "string" },
+      "min-evidence": { type: "string" },
       "config": { type: "string" },
       help: { type: "boolean", default: false }
     },
@@ -20337,6 +21089,17 @@ async function parseCliArgs(argv) {
     console.error(`Error: --asset-mode must be "none" or "copy", got "${assetModeRaw}".`);
     process.exit(EXIT_USAGE);
   }
+  const failOnRaw = values["fail-on"];
+  if (failOnRaw !== void 0 && failOnRaw !== "uncovered" && failOnRaw !== "weak") {
+    console.error(`Error: --fail-on must be "uncovered" or "weak", got "${failOnRaw}".`);
+    process.exit(EXIT_USAGE);
+  }
+  const minEvidenceRaw = values["min-evidence"];
+  const validMinEvidence = /* @__PURE__ */ new Set(["weak", "moderate", "strong"]);
+  if (minEvidenceRaw !== void 0 && !validMinEvidence.has(minEvidenceRaw)) {
+    console.error(`Error: --min-evidence must be "weak", "moderate", or "strong", got "${minEvidenceRaw}".`);
+    process.exit(EXIT_USAGE);
+  }
   const cliArgs = {
     subcommand,
     inputFile,
@@ -20388,6 +21151,11 @@ async function parseCliArgs(argv) {
     failOnRegression: values["fail-on-regression"],
     failOnAddedFailures: values["fail-on-added-failures"],
     maxRegressions,
+    changedFilesPath: values["changed-files"],
+    baseRef: values["base-ref"],
+    headRef: values["head-ref"],
+    failOn: failOnRaw,
+    minEvidence: minEvidenceRaw,
     config: values["config"]
   };
   return { args: cliArgs, pluginConfig, customRequested };
@@ -20601,6 +21369,30 @@ async function main() {
       process.exit(EXIT_GENERATION);
     }
   }
+  if (args.subcommand === "review") {
+    const text3 = await readInput(args);
+    const run = applySelection(normalizeRunFromText(text3, args).run, args);
+    const context = loadReviewContext(args);
+    const review = buildReview(run, context);
+    try {
+      const files = writeReviewReport(review, args);
+      for (const f of files) {
+        console.log(f);
+      }
+      const gateFailures = evaluateReviewGate(review, args);
+      if (gateFailures.length > 0) {
+        for (const failure of gateFailures) {
+          console.error(`Review gate failed: ${failure}`);
+        }
+        process.exit(EXIT_REVIEW_GATE);
+      }
+      process.exit(EXIT_SUCCESS);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(`Review failed: ${msg}`);
+      process.exit(EXIT_GENERATION);
+    }
+  }
   if (args.subcommand === "list") {
     const text3 = await readInput(args);
     const run = applySelection(normalizeRunFromText(text3, args).run, args);
@@ -20959,6 +21751,102 @@ async function generateCompareReports(baseline, current, baselineFile, args) {
     prSummary: args.prSummary || args.prSummaryFile ? createPrCommentSummary(result.diff) : void 0
   };
 }
+var STRENGTH_RANK2 = {
+  none: 0,
+  weak: 1,
+  moderate: 2,
+  strong: 3
+};
+function mapStatus(status) {
+  const letter = status.charAt(0).toUpperCase();
+  if (letter === "A") return "added";
+  if (letter === "D") return "deleted";
+  if (letter === "R") return "renamed";
+  if (letter === "C") return "added";
+  return "modified";
+}
+function parseNameStatus(text2) {
+  const files = [];
+  for (const raw of text2.split("\n")) {
+    const line = raw.trim();
+    if (!line) continue;
+    const cols = line.includes("	") ? line.split("	") : line.split(/\s+/);
+    const status = cols[0];
+    if (!status) continue;
+    const filePath = /^[RC]/i.test(status) && cols.length >= 3 ? cols[cols.length - 1] : cols[1];
+    if (!filePath) continue;
+    files.push({ path: filePath, changeKind: mapStatus(status) });
+  }
+  return files;
+}
+var VALID_CHANGE_KINDS = /* @__PURE__ */ new Set(["added", "modified", "deleted", "renamed"]);
+function coerceChangedFile(value) {
+  if (typeof value !== "object" || value === null) return void 0;
+  const obj = value;
+  if (typeof obj.path !== "string") return void 0;
+  const kind = typeof obj.changeKind === "string" && VALID_CHANGE_KINDS.has(obj.changeKind) ? obj.changeKind : "modified";
+  const changedLines = Array.isArray(obj.changedLines) ? obj.changedLines.filter((n) => typeof n === "number") : void 0;
+  return changedLines ? { path: obj.path, changeKind: kind, changedLines } : { path: obj.path, changeKind: kind };
+}
+function loadReviewContext(args) {
+  let changedFiles = [];
+  let baseRef = args.baseRef;
+  let headRef = args.headRef;
+  if (args.changedFilesPath) {
+    const text2 = readFileInput(args.changedFilesPath);
+    const parsed = tryParseJson(text2);
+    if (Array.isArray(parsed)) {
+      changedFiles = parsed.map(coerceChangedFile).filter((f) => f !== void 0);
+    } else if (parsed && typeof parsed === "object") {
+      const obj = parsed;
+      if (Array.isArray(obj.changedFiles)) {
+        changedFiles = obj.changedFiles.map(coerceChangedFile).filter((f) => f !== void 0);
+      }
+      if (typeof obj.baseRef === "string") baseRef = baseRef ?? obj.baseRef;
+      if (typeof obj.headRef === "string") headRef = headRef ?? obj.headRef;
+    } else {
+      changedFiles = parseNameStatus(text2);
+    }
+  }
+  return { changedFiles, baseRef, headRef };
+}
+function writeReviewReport(review, args) {
+  const title = args.htmlTitle && args.htmlTitle !== "Test Results" ? args.htmlTitle : void 0;
+  const titleOpt = title ? { title } : {};
+  const markdown = new ReviewMarkdownFormatter(titleOpt).format(review);
+  const html = new ReviewHtmlFormatter({ ...titleOpt, theme: args.htmlTheme }).format(review);
+  const outputDir = args.outputDir ?? "reports";
+  const baseName = args.outputName ?? "evidence-review";
+  const suffix = args.outputNameTimestamp ? `-${Math.floor(review.run.startedAtMs / 1e3)}` : "";
+  fs8.mkdirSync(outputDir, { recursive: true });
+  const mdPath = path9.join(outputDir, `${baseName}${suffix}.md`);
+  const htmlPath = path9.join(outputDir, `${baseName}${suffix}.html`);
+  fs8.writeFileSync(mdPath, markdown, "utf8");
+  fs8.writeFileSync(htmlPath, html, "utf8");
+  return [mdPath, htmlPath];
+}
+function evaluateReviewGate(review, args) {
+  const failures = [];
+  const { summary } = review;
+  if (args.failOn === "uncovered" && summary.uncovered > 0) {
+    failures.push(`${summary.uncovered} changed source file(s) have no evidence`);
+  }
+  if (args.failOn === "weak" && summary.uncovered + summary.weaklyCovered > 0) {
+    failures.push(
+      `${summary.uncovered + summary.weaklyCovered} changed source file(s) lack moderate+ evidence`
+    );
+  }
+  if (args.minEvidence) {
+    const threshold = STRENGTH_RANK2[args.minEvidence];
+    const below = review.claims.filter((c) => STRENGTH_RANK2[c.strength] < threshold);
+    if (below.length > 0) {
+      failures.push(
+        `${below.length} claim(s) below "${args.minEvidence}" evidence strength`
+      );
+    }
+  }
+  return failures;
+}
 function printResult(result, args, startMs, droppedMissingStory = 0) {
   const durationMs = Date.now() - startMs;
   if (args.jsonSummary) {