executable-stories-formatters 1.3.0 → 1.4.0

package/dist/cli.js

@@ -7539,6 +7539,157 @@ function renderTriage(report, format) {
   return lines.join("\n").trimEnd();
 }
 
+// src/review/diff-anchor.ts
+import { createHash as createHash6 } from "crypto";
+var CONTEXT_WINDOW = 3;
+var MAX_FUZZ = 2;
+var normalize = (line) => line.trim();
+var HUNK_HEADER = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@ ?(.*)$/;
+function stripPathPrefix(raw) {
+  const path17 = raw.split("	")[0].trim();
+  if (path17 === "/dev/null") return void 0;
+  return path17.replace(/^[ab]\//, "");
+}
+function parseUnifiedDiff(patch) {
+  const files = [];
+  let current;
+  let hunk;
+  let oldRemaining = 0;
+  let newRemaining = 0;
+  for (const line of patch.split("\n")) {
+    if (hunk && (oldRemaining > 0 || newRemaining > 0)) {
+      if (line.startsWith("\\")) continue;
+      const kind = line.startsWith("+") ? "add" : line.startsWith("-") ? "del" : "context";
+      hunk.lines.push({ kind, text: line.slice(1) });
+      if (kind !== "add") oldRemaining--;
+      if (kind !== "del") newRemaining--;
+      continue;
+    }
+    hunk = void 0;
+    if (line.startsWith("diff --git ")) {
+      current = { hunks: [] };
+      files.push(current);
+      continue;
+    }
+    if (line.startsWith("--- ")) {
+      if (!current || current.oldPath !== void 0 || current.hunks.length > 0) {
+        current = { hunks: [] };
+        files.push(current);
+      }
+      current.oldPath = stripPathPrefix(line.slice(4));
+      continue;
+    }
+    if (line.startsWith("+++ ") && current) {
+      current.newPath = stripPathPrefix(line.slice(4));
+      continue;
+    }
+    const match = HUNK_HEADER.exec(line);
+    if (match && current) {
+      hunk = {
+        oldStart: Number(match[1]),
+        newStart: Number(match[3]),
+        header: match[5] ?? "",
+        lines: []
+      };
+      oldRemaining = match[2] === void 0 ? 1 : Number(match[2]);
+      newRemaining = match[4] === void 0 ? 1 : Number(match[4]);
+      current.hunks.push(hunk);
+    }
+  }
+  return files;
+}
+function createAnchor(args) {
+  const { file, hunkIndex, lineIndex } = args;
+  const lines = file.hunks[hunkIndex].lines;
+  if (lines[lineIndex].kind === "context") {
+    throw new Error(`Line ${lineIndex} is a context line; anchors target changed lines`);
+  }
+  const changed = [];
+  let end = lineIndex;
+  while (end < lines.length && lines[end].kind !== "context") {
+    changed.push({ kind: lines[end].kind, text: lines[end].text });
+    end++;
+  }
+  const contextBefore = lines.slice(Math.max(0, lineIndex - CONTEXT_WINDOW), lineIndex).map((l) => l.text);
+  const contextAfter = lines.slice(end, end + CONTEXT_WINDOW).map((l) => l.text);
+  const hash = createHash6("sha256").update(
+    JSON.stringify({
+      changed: changed.map((l) => `${l.kind}:${normalize(l.text)}`),
+      before: contextBefore.map(normalize),
+      after: contextAfter.map(normalize)
+    })
+  ).digest("hex");
+  return {
+    hash,
+    file: file.newPath ?? file.oldPath ?? "",
+    changed,
+    contextBefore,
+    contextAfter
+  };
+}
+function changedRunCandidates(anchor, file, fileIndex) {
+  const path17 = file.newPath ?? file.oldPath ?? "";
+  const out = [];
+  file.hunks.forEach((hunk, hunkIndex) => {
+    outer: for (let i = 0; i + anchor.changed.length <= hunk.lines.length; i++) {
+      for (let j = 0; j < anchor.changed.length; j++) {
+        const line = hunk.lines[i + j];
+        const want = anchor.changed[j];
+        if (line.kind !== want.kind || normalize(line.text) !== normalize(want.text)) {
+          continue outer;
+        }
+      }
+      out.push({ fileIndex, file: path17, hunkIndex, lineIndex: i, lines: hunk.lines });
+    }
+  });
+  return out;
+}
+function contextMatches(anchor, candidate, fuzz) {
+  const before = anchor.contextBefore.slice(Math.min(fuzz, anchor.contextBefore.length));
+  const after = anchor.contextAfter.slice(
+    0,
+    Math.max(0, anchor.contextAfter.length - fuzz)
+  );
+  for (let i = 0; i < before.length; i++) {
+    const line = candidate.lines[candidate.lineIndex - before.length + i];
+    if (line === void 0 || normalize(line.text) !== normalize(before[i])) return false;
+  }
+  const end = candidate.lineIndex + anchor.changed.length;
+  for (let i = 0; i < after.length; i++) {
+    const line = candidate.lines[end + i];
+    if (line === void 0 || normalize(line.text) !== normalize(after[i])) return false;
+  }
+  return true;
+}
+function resolveCandidates(anchor, candidates) {
+  for (let fuzz = 0; fuzz <= MAX_FUZZ; fuzz++) {
+    const matches = candidates.filter((c) => contextMatches(anchor, c, fuzz));
+    if (matches.length === 1) {
+      const m = matches[0];
+      return {
+        state: "anchored",
+        fileIndex: m.fileIndex,
+        file: m.file,
+        hunkIndex: m.hunkIndex,
+        lineIndex: m.lineIndex,
+        lineCount: anchor.changed.length,
+        fuzz
+      };
+    }
+    if (matches.length > 1) return { state: "ambiguous" };
+  }
+  return void 0;
+}
+function relocateAnchor(anchor, files) {
+  const own = [];
+  const others = [];
+  files.forEach((file, fileIndex) => {
+    const isOwn = file.newPath === anchor.file || file.oldPath === anchor.file;
+    (isOwn ? own : others).push(...changedRunCandidates(anchor, file, fileIndex));
+  });
+  return resolveCandidates(anchor, own) ?? resolveCandidates(anchor, others) ?? { state: "orphaned" };
+}
+
 // src/review/conventions.ts
 var CHANGE_TAG_PREFIX = "change:";
 var AUDIENCE_TAG_PREFIX = "audience:";
@@ -7726,6 +7877,33 @@ var AUDIENCE_ORDER = {
   stakeholder: 0,
   engineer: 1
 };
+function buildCodeDiff(input, run, context) {
+  const files = parseUnifiedDiff(input.patch);
+  const byId = new Map(run.testCases.map((tc) => [tc.id, tc]));
+  return {
+    title: input.title,
+    patch: input.patch,
+    patchUrl: input.patchUrl,
+    baseLabel: input.baseLabel ?? context.baseRef,
+    headLabel: input.headLabel ?? context.headRef,
+    files,
+    annotations: input.annotations.map((annotation) => ({
+      anchorHash: annotation.anchor?.hash,
+      text: annotation.text,
+      label: annotation.label,
+      resolution: annotation.anchor ? relocateAnchor(annotation.anchor, files) : { state: annotation.unresolved ?? "orphaned" },
+      scenarios: (annotation.scenarioIds ?? []).map((id) => {
+        const testCase = byId.get(id);
+        return testCase ? {
+          id,
+          resolved: true,
+          scenario: testCase.story.scenario,
+          status: testCase.status
+        } : { id, resolved: false };
+      })
+    }))
+  };
+}
 function buildReview(run, context = { changedFiles: [] }) {
   const changedSource = context.changedFiles.filter(
     (f) => isReviewableSource(f.path)
@@ -7770,9 +7948,31 @@ function buildReview(run, context = { changedFiles: [] }) {
     context,
     summary,
     claims: sortedClaims,
-    changedFiles: sortedFiles
+    changedFiles: sortedFiles,
+    codeDiffs: (context.codeDiffs ?? []).map((d) => buildCodeDiff(d, run, context))
   };
 }
+function codeDiffDiagnostics(review) {
+  const issues = [];
+  for (const evidence of review.codeDiffs) {
+    evidence.annotations.forEach((annotation, i) => {
+      const name = annotation.label ?? `annotation ${i + 1}`;
+      if (annotation.resolution.state !== "anchored") {
+        issues.push(
+          `"${evidence.title}" ${name}: anchor is ${annotation.resolution.state} in the current patch`
+        );
+      }
+      for (const ref of annotation.scenarios) {
+        if (!ref.resolved) {
+          issues.push(
+            `"${evidence.title}" ${name}: cites scenario "${ref.id}" which is not in this run`
+          );
+        }
+      }
+    });
+  }
+  return issues;
+}
 function buildSummary2(claims, changedFiles) {
   const byAudience = {
     stakeholder: 0,
@@ -7799,6 +7999,75 @@ function buildSummary2(claims, changedFiles) {
   };
 }
 
+// src/review/code-diff-sidecar.ts
+function locateMatches(file, match) {
+  const out = [];
+  file.hunks.forEach((hunk, hunkIndex) => {
+    hunk.lines.forEach((line, lineIndex) => {
+      if (line.kind !== "context" && line.text.includes(match)) {
+        out.push({ hunkIndex, lineIndex });
+      }
+    });
+  });
+  return out;
+}
+function runStart(file, hunkIndex, lineIndex) {
+  const lines = file.hunks[hunkIndex].lines;
+  let start = lineIndex;
+  while (start > 0 && lines[start - 1].kind !== "context") start--;
+  return start;
+}
+function assembleCodeDiff(args) {
+  const { sidecar, patch } = args;
+  const files = parseUnifiedDiff(patch);
+  const warnings = [];
+  if (sidecar.patchUrl !== void 0 && !sidecar.patchUrl.startsWith("https://")) {
+    warnings.push(
+      `patchUrl "${sidecar.patchUrl}" is not https: \u2014 it will render as inert text, not a link`
+    );
+  }
+  const annotations = sidecar.annotations.map(
+    (entry) => {
+      const base = {
+        text: entry.text,
+        label: entry.label,
+        scenarioIds: entry.scenarioIds
+      };
+      const file = files.find(
+        (f) => f.newPath === entry.file || f.oldPath === entry.file
+      );
+      const matches = file ? locateMatches(file, entry.match) : [];
+      if (file && matches.length === 1) {
+        const { hunkIndex, lineIndex } = matches[0];
+        const anchor = createAnchor({
+          file,
+          hunkIndex,
+          lineIndex: runStart(file, hunkIndex, lineIndex)
+        });
+        return { ...base, anchor };
+      }
+      warnings.push(
+        !file ? `annotation "${entry.label ?? entry.match}": file "${entry.file}" is not in the patch` : matches.length === 0 ? `annotation "${entry.label ?? entry.match}": no changed line in "${entry.file}" contains "${entry.match}"` : `annotation "${entry.label ?? entry.match}": "${entry.match}" matches ${matches.length} changed lines in "${entry.file}" \u2014 make it unique`
+      );
+      return {
+        ...base,
+        unresolved: file && matches.length > 1 ? "ambiguous" : "orphaned"
+      };
+    }
+  );
+  return {
+    input: {
+      title: sidecar.title,
+      patch,
+      patchUrl: sidecar.patchUrl,
+      baseLabel: sidecar.baseLabel,
+      headLabel: sidecar.headLabel,
+      annotations
+    },
+    warnings
+  };
+}
+
 // src/formatters/review-markdown.ts
 var STRENGTH_BADGE = {
   strong: "\u{1F7E2} strong",
@@ -7884,6 +8153,73 @@ function renderAudienceSection(lines, title, claims) {
     renderClaim(lines, claim);
   }
 }
+var MAX_PATCH_EMBED_BYTES = 64 * 1024;
+function fenceFor(content) {
+  const runs = content.match(/`{3,}/g);
+  const length = runs ? Math.max(...runs.map((r) => r.length)) + 1 : 3;
+  return "`".repeat(length);
+}
+function renderCodeDiff(lines, evidence) {
+  lines.push(`## Code diff evidence: ${evidence.title}`);
+  lines.push("");
+  if (evidence.baseLabel || evidence.headLabel) {
+    lines.push(
+      `Comparing \`${evidence.baseLabel ?? "base"}\` \u2192 \`${evidence.headLabel ?? "head"}\`.`
+    );
+    lines.push("");
+  }
+  if (evidence.patchUrl !== void 0) {
+    lines.push(
+      evidence.patchUrl.startsWith("https://") ? `Canonical patch: ${evidence.patchUrl}` : `Canonical patch: \`${evidence.patchUrl.replace(/`/g, "")}\``
+    );
+    lines.push("");
+  }
+  evidence.annotations.forEach((annotation, i) => {
+    lines.push(`### ${annotation.label ?? `Annotation ${i + 1}`}`);
+    lines.push("");
+    lines.push(annotation.text);
+    lines.push("");
+    if (annotation.resolution.state === "orphaned") {
+      lines.push(
+        "> \u26A0\uFE0F Orphaned annotation \u2014 could not locate these lines in the current patch."
+      );
+      lines.push("");
+    } else if (annotation.resolution.state === "ambiguous") {
+      lines.push(
+        "> \u26A0\uFE0F Ambiguous anchor \u2014 these lines appear in more than one place in the current patch."
+      );
+      lines.push("");
+    } else if (annotation.resolution.file !== void 0) {
+      lines.push(`Location: \`${annotation.resolution.file}\``);
+      lines.push("");
+    }
+    if (annotation.scenarios.length === 0) {
+      lines.push("_Not covered by a scenario._");
+    } else {
+      for (const ref of annotation.scenarios) {
+        lines.push(
+          ref.resolved && ref.status ? `- ${statusIcon2(ref.status)} ${escapeCell2(ref.scenario ?? ref.id)} (\`${ref.id}\`)` : `- \u26A0\uFE0F \`${ref.id}\` \u2014 unverified reference (scenario not in this run)`
+        );
+      }
+    }
+    lines.push("");
+  });
+  if (Buffer.byteLength(evidence.patch, "utf8") <= MAX_PATCH_EMBED_BYTES) {
+    const fence = fenceFor(evidence.patch);
+    lines.push("<details><summary>Raw patch (audit)</summary>");
+    lines.push("");
+    lines.push(`${fence}diff`);
+    lines.push(evidence.patch.trimEnd());
+    lines.push(fence);
+    lines.push("");
+    lines.push("</details>");
+  } else {
+    lines.push(
+      `_Patch too large to embed${evidence.patchUrl ? " \u2014 see the canonical patch link above" : ""}._`
+    );
+  }
+  lines.push("");
+}
 var ReviewMarkdownFormatter = class {
   title;
   constructor(options = {}) {
@@ -7944,6 +8280,9 @@ var ReviewMarkdownFormatter = class {
       "Engineer changes",
       review.claims.filter((c) => c.audience === "engineer")
     );
+    for (const evidence of review.codeDiffs) {
+      renderCodeDiff(lines, evidence);
+    }
     return lines.join("\n").trimEnd();
   }
 };
@@ -8030,7 +8369,7 @@ function renderClaimCard(claim) {
   );
   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}">
+    <article class="claim-card" id="claim-${escapeHtml2(claim.id)}" 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>
@@ -8059,6 +8398,66 @@ function renderChangedFileRow(file) {
     <td>${claims}</td>
   </tr>`;
 }
+var MAX_PATCH_EMBED_BYTES2 = 256 * 1024;
+function renderScenarioRef(ref) {
+  if (!ref.resolved) {
+    return `<span class="scenario-ref unverified">\u26A0\uFE0F ${escapeHtml2(ref.id)} (unverified reference)</span>`;
+  }
+  const icon = ref.status === "passed" ? "\u2705" : ref.status === "failed" ? "\u274C" : "\u2298";
+  return `<a class="scenario-ref" href="#claim-${escapeHtml2(ref.id)}">${icon} ${escapeHtml2(ref.scenario ?? ref.id)}</a>`;
+}
+function renderDiffHunk(file, hunk, anchoredStart, anchoredCount) {
+  let oldLn = hunk.oldStart;
+  let newLn = hunk.newStart;
+  const rows = hunk.lines.map((line, i) => {
+    const anchored = anchoredStart !== void 0 && anchoredCount !== void 0 && i >= anchoredStart && i < anchoredStart + anchoredCount;
+    const cls = `diff-${line.kind}${anchored ? " diff-anchored" : ""}`;
+    const o = line.kind === "add" ? "" : String(oldLn++);
+    const n = line.kind === "del" ? "" : String(newLn++);
+    const sign = line.kind === "add" ? "+" : line.kind === "del" ? "-" : " ";
+    return `<tr class="${cls}"><td class="diff-ln">${o}</td><td class="diff-ln">${n}</td><td class="diff-sign">${sign}</td><td class="diff-code">${escapeHtml2(line.text)}</td></tr>`;
+  });
+  const path17 = file.newPath ?? file.oldPath ?? "";
+  return `<div class="diff-hunk">
+    <div class="diff-file-header"><code>${escapeHtml2(path17)}</code> <span class="subtle">@@ -${hunk.oldStart} +${hunk.newStart} @@ ${escapeHtml2(hunk.header)}</span></div>
+    <table class="diff-table"><tbody>${rows.join("")}</tbody></table>
+  </div>`;
+}
+function renderAnnotation(evidence, annotation, diffIndex, index) {
+  const scenarios = annotation.scenarios.length > 0 ? `<div class="scenario-row">${annotation.scenarios.map(renderScenarioRef).join("")}</div>` : `<p class="no-scenario">Not covered by a scenario \u2014 implementation claim without behavioural evidence.</p>`;
+  const res = annotation.resolution;
+  let body;
+  if (res.state === "anchored" && res.fileIndex !== void 0 && res.hunkIndex !== void 0) {
+    const file = evidence.files[res.fileIndex];
+    body = renderDiffHunk(file, file.hunks[res.hunkIndex], res.lineIndex, res.lineCount);
+  } else if (res.state === "ambiguous") {
+    body = `<p class="anchor-notice">\u26A0\uFE0F Ambiguous anchor \u2014 these lines appear in more than one place in the current patch, so the annotation is not attached to any of them.</p>`;
+  } else {
+    body = `<p class="anchor-notice">\u26A0\uFE0F Orphaned annotation \u2014 could not locate these lines in the current patch. The prose below may describe code that has since changed.</p>`;
+  }
+  return `<article class="annotation" id="code-diff-${diffIndex}-a${index}" data-anchor-state="${res.state}">
+    <h4>${escapeHtml2(annotation.label ?? `Annotation ${index + 1}`)}</h4>
+    <p class="annotation-text">${escapeHtml2(annotation.text)}</p>
+    ${scenarios}
+    ${body}
+  </article>`;
+}
+function renderCodeDiffSection(evidence, diffIndex) {
+  const comparing = evidence.baseLabel || evidence.headLabel ? `<p class="subtle">Comparing ${escapeHtml2(evidence.baseLabel ?? "base")} \u2192 ${escapeHtml2(evidence.headLabel ?? "head")}</p>` : "";
+  const audit = evidence.patchUrl === void 0 ? "" : evidence.patchUrl.startsWith("https://") ? `<p class="subtle">Canonical patch: <a href="${escapeHtml2(evidence.patchUrl)}" rel="noopener noreferrer">${escapeHtml2(evidence.patchUrl)}</a></p>` : `<p class="subtle">Canonical patch: <code>${escapeHtml2(evidence.patchUrl)}</code></p>`;
+  const outline = evidence.annotations.length > 1 ? `<ol class="diff-outline">${evidence.annotations.map(
+    (a, i) => `<li><a href="#code-diff-${diffIndex}-a${i}">${escapeHtml2(a.label ?? `Annotation ${i + 1}`)}</a></li>`
+  ).join("")}</ol>` : "";
+  const rawPatch = Buffer.byteLength(evidence.patch, "utf8") <= MAX_PATCH_EMBED_BYTES2 ? `<details class="raw-patch"><summary>Raw patch (audit)</summary><pre><code>${escapeHtml2(evidence.patch)}</code></pre></details>` : `<p class="anchor-notice">Patch too large to embed${evidence.patchUrl ? " \u2014 use the canonical patch link above" : ""}.</p>`;
+  return `<section class="panel code-diff" id="code-diff-${diffIndex}">
+    <h2>Code diff: ${escapeHtml2(evidence.title)}</h2>
+    ${comparing}
+    ${audit}
+    ${outline}
+    ${evidence.annotations.map((a, i) => renderAnnotation(evidence, a, diffIndex, i)).join("\n")}
+    ${rawPatch}
+  </section>`;
+}
 function renderAudienceSection2(title, claims) {
   if (claims.length === 0) return "";
   return `<section class="audience-section">
@@ -8118,6 +8517,29 @@ var REVIEW_CSS = `
   .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); }
+  .code-diff h2 { margin-bottom: 6px; }
+  .code-diff a { color: var(--foreground); }
+  .diff-outline { margin: 12px 0; padding-left: 20px; }
+  .annotation { margin: 18px 0; padding: 14px 16px; border: 1px solid var(--border); border-radius: 10px; background: color-mix(in srgb, var(--card) 60%, var(--background)); }
+  .annotation h4 { margin: 0 0 6px; }
+  .annotation-text { margin: 0 0 10px; }
+  .scenario-row { display: flex; flex-wrap: wrap; gap: 8px; margin-bottom: 10px; }
+  .scenario-ref { display: inline-flex; align-items: center; gap: 4px; border: 1px solid var(--border); border-radius: 999px; padding: 3px 10px; font-size: 0.82rem; text-decoration: none; color: var(--foreground); background: var(--background); }
+  .scenario-ref.unverified { color: var(--warning, #b58900); border-color: var(--warning, #b58900); }
+  .no-scenario { color: var(--warning, #b58900); font-size: 0.9rem; margin: 0 0 10px; }
+  .anchor-notice { color: var(--warning, #b58900); background: color-mix(in srgb, var(--warning, #b58900) 10%, transparent); border-radius: 6px; padding: 8px 10px; margin: 0; }
+  .diff-hunk { border: 1px solid var(--border); border-radius: 8px; overflow: hidden; }
+  .diff-file-header { padding: 6px 10px; background: var(--secondary); border-bottom: 1px solid var(--border); font-size: 0.85rem; }
+  .diff-table { font-family: var(--font-mono, ui-monospace, monospace); font-size: 0.82rem; }
+  .diff-table td { padding: 1px 8px; border-bottom: none; }
+  .diff-code { white-space: pre-wrap; word-break: break-all; }
+  .diff-ln { color: var(--muted-foreground); text-align: right; user-select: none; width: 1%; white-space: nowrap; }
+  .diff-sign { user-select: none; width: 1%; }
+  .diff-add { background: color-mix(in srgb, var(--success, #2e7d32) 12%, transparent); }
+  .diff-del { background: color-mix(in srgb, var(--destructive) 10%, transparent); }
+  .diff-anchored .diff-code { box-shadow: inset 3px 0 0 var(--primary, #2e7d32); }
+  .raw-patch { margin-top: 16px; }
+  .raw-patch pre { overflow-x: auto; background: var(--secondary); border-radius: 8px; padding: 12px; }
 `;
 var JS_THEME_TOGGLE2 = `
 function getSystemTheme() { return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'; }
@@ -8184,15 +8606,18 @@ applyTheme(getEffectiveTheme());` : "";
         <p class="subtle">${escapeHtml2(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"))}
+      <div class="claims-region">
+        <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"))}
+      </div>
+      ${review.codeDiffs.map((d, i) => renderCodeDiffSection(d, i)).join("\n")}
     </main>
     <script>
       ${themeInitJs}
@@ -9885,6 +10310,9 @@ OPTIONS
   --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)
+  --code-diff <path>            (review) Code Diff annotation sidecar (JSON: {title, annotations: [{file, match, text, label?, scenarioIds?}]})
+  --patch <path>                (review) Unified patch for --code-diff; generate with "git diff --histogram"
+  --strict-code-diff            (review) Gate: exit non-zero on orphaned/ambiguous anchors or unverified scenario references (default: off)
   --emit-canonical <path>       Write canonical JSON to given path
   --help                        Show this help message
 
@@ -10167,6 +10595,9 @@ See: https://github.com/jagreehal/executable-stories (executable-stories-astro).
       "head-ref": { type: "string" },
       "fail-on": { type: "string" },
       "min-evidence": { type: "string" },
+      "code-diff": { type: "string" },
+      "patch": { type: "string" },
+      "strict-code-diff": { type: "boolean", default: false },
       "config": { type: "string" },
       help: { type: "boolean", default: false }
     },
@@ -10380,6 +10811,9 @@ See: https://github.com/jagreehal/executable-stories (executable-stories-astro).
     headRef: values["head-ref"],
     failOn: failOnRaw,
     minEvidence: minEvidenceRaw,
+    codeDiffPath: values["code-diff"],
+    patchPath: values["patch"],
+    strictCodeDiff: values["strict-code-diff"],
     config: values["config"]
   };
   return { args: cliArgs, pluginConfig, customRequested };
@@ -10682,7 +11116,14 @@ async function runReview(ctx) {
     for (const f of files) {
       console.log(f);
     }
+    const diffIssues = codeDiffDiagnostics(review);
+    for (const issue of diffIssues) {
+      console.error(`Code diff warning: ${issue}`);
+    }
     const gateFailures = evaluateReviewGate(review, args);
+    if (args.strictCodeDiff) {
+      gateFailures.push(...diffIssues);
+    }
     if (gateFailures.length > 0) {
       for (const failure of gateFailures) {
         console.error(`Review gate failed: ${failure}`);
@@ -11211,7 +11652,23 @@ function loadReviewContext(args) {
       changedFiles = parseNameStatus(text2);
     }
   }
-  return { changedFiles, baseRef, headRef };
+  let codeDiffs;
+  if (args.codeDiffPath) {
+    if (!args.patchPath) {
+      console.error(
+        "Error: --code-diff requires --patch <file> (generate it with: git diff --histogram > changes.patch)."
+      );
+      process.exit(EXIT_USAGE);
+    }
+    const sidecar = JSON.parse(readFileInput(args.codeDiffPath));
+    const patch = readFileInput(args.patchPath);
+    const { input, warnings } = assembleCodeDiff({ sidecar, patch });
+    for (const warning of warnings) {
+      console.error(`Code diff warning: ${warning}`);
+    }
+    codeDiffs = [input];
+  }
+  return { changedFiles, baseRef, headRef, codeDiffs };
 }
 function writeReviewReport(review, args) {
   const title = args.htmlTitle && args.htmlTitle !== "Test Results" ? args.htmlTitle : void 0;
@@ -11896,6 +12353,7 @@ function createDefaultCliArgs() {
     failOnAddedFailures: false,
     failOnRemoval: false,
     failOnNew: false,
+    strictCodeDiff: false,
     baselineMode: "explicit"
   };
 }