executable-stories-formatters 0.8.0 → 0.10.0

package/dist/cli.js

@@ -2,8 +2,8 @@
 
 // src/cli.ts
 import { parseArgs } from "util";
-import * as fs8 from "fs";
-import * as path9 from "path";
+import * as fs9 from "fs";
+import * as path10 from "path";
 
 // src/validation/schema-validator.ts
 import Ajv from "ajv/dist/2020.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"],
@@ -492,17 +539,17 @@ function validateRawRun(data) {
     return { valid: true, errors: [] };
   }
   const errors = (validate.errors ?? []).map((err) => {
-    const path10 = err.instancePath || "/";
+    const path11 = err.instancePath || "/";
     const message = err.message ?? "unknown error";
     if (err.keyword === "additionalProperties") {
       const extra = err.params.additionalProperty;
-      return `${path10}: ${message} \u2014 '${extra}'`;
+      return `${path11}: ${message} \u2014 '${extra}'`;
     }
     if (err.keyword === "enum") {
       const allowed = err.params.allowedValues;
-      return `${path10}: ${message} \u2014 allowed: ${JSON.stringify(allowed)}`;
+      return `${path11}: ${message} \u2014 allowed: ${JSON.stringify(allowed)}`;
     }
-    return `${path10}: ${message}`;
+    return `${path11}: ${message}`;
   });
   return { valid: false, errors };
 }
@@ -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) {
@@ -976,7 +1024,7 @@ ${result.errors.join("\n")}`);
 
 // src/index.ts
 import "fs";
-import * as path7 from "path";
+import * as path8 from "path";
 import * as fsPromises from "fs/promises";
 
 // src/converters/acl/lines.ts
@@ -1521,6 +1569,9 @@ function buildScenario(tc, featureId) {
   if (tickets && tickets.length > 0) {
     scenario.tickets = tickets.map((t) => t.url ? { id: t.id, url: t.url } : { id: t.id });
   }
+  if (tc.story.covers && tc.story.covers.length > 0) {
+    scenario.covers = [...tc.story.covers];
+  }
   return scenario;
 }
 function deriveFeatureTitle(group, relSourceFile) {
@@ -1644,6 +1695,181 @@ var StoryReportJsonFormatter = class {
   }
 };
 
+// src/formatters/scenario-index-json.ts
+var ScenarioIndexJsonFormatter = class {
+  options;
+  constructor(options = {}) {
+    this.options = {
+      pretty: options.pretty ?? true,
+      filters: options.filters
+    };
+  }
+  toIndex(run) {
+    return toScenarioIndex(toStoryReport(run), this.options.filters);
+  }
+  format(run) {
+    const index = this.toIndex(run);
+    return this.options.pretty ? JSON.stringify(index, null, 2) : JSON.stringify(index);
+  }
+};
+function toScenarioIndex(report, filters = {}) {
+  const scenarios = report.features.flatMap(
+    (feature) => feature.scenarios.map((scenario) => toScenarioIndexItem(feature, scenario))
+  ).filter((scenario) => matchesFilters(scenario, filters));
+  return {
+    schemaVersion: "1.0",
+    runId: report.runId,
+    generatedAtMs: report.finishedAtMs,
+    summary: summarize(scenarios),
+    scenarios
+  };
+}
+function toScenarioIndexItem(feature, scenario) {
+  return {
+    id: scenario.id,
+    title: scenario.title,
+    status: scenario.status,
+    feature: feature.title,
+    sourceFile: feature.sourceFile,
+    sourceLine: scenario.sourceLine,
+    tags: scenario.tags,
+    tickets: scenario.tickets ?? [],
+    covers: scenario.covers ?? [],
+    durationMs: scenario.durationMs,
+    steps: scenario.steps.map((step) => ({
+      id: step.id,
+      index: step.index,
+      keyword: step.keyword,
+      text: step.text,
+      status: step.status,
+      durationMs: step.durationMs,
+      errorMessage: step.errorMessage,
+      docKinds: step.docEntries.map((entry) => entry.kind)
+    })),
+    docKinds: scenario.docEntries.map((entry) => entry.kind),
+    error: scenario.errorMessage ? { message: scenario.errorMessage, stack: scenario.errorStack } : void 0
+  };
+}
+function matchesFilters(scenario, filters) {
+  if (filters.statuses?.length && !filters.statuses.includes(scenario.status)) {
+    return false;
+  }
+  if (filters.tags?.length && !filters.tags.some((tag) => scenario.tags.includes(tag))) {
+    return false;
+  }
+  if (filters.sourceFiles?.length && !filters.sourceFiles.some((sourceFile) => scenario.sourceFile.includes(sourceFile))) {
+    return false;
+  }
+  return true;
+}
+function summarize(scenarios) {
+  return {
+    total: scenarios.length,
+    passed: scenarios.filter((scenario) => scenario.status === "passed").length,
+    failed: scenarios.filter((scenario) => scenario.status === "failed").length,
+    skipped: scenarios.filter((scenario) => scenario.status === "skipped").length,
+    pending: scenarios.filter((scenario) => scenario.status === "pending").length,
+    durationMs: scenarios.reduce((total, scenario) => total + scenario.durationMs, 0)
+  };
+}
+
+// src/formatters/behavior-manifest-json.ts
+var BehaviorManifestJsonFormatter = class {
+  pretty;
+  constructor(options = {}) {
+    this.pretty = options.pretty ?? true;
+  }
+  toManifest(run) {
+    return toBehaviorManifest(toStoryReport(run));
+  }
+  format(run) {
+    const manifest = this.toManifest(run);
+    return this.pretty ? JSON.stringify(manifest, null, 2) : JSON.stringify(manifest);
+  }
+};
+function toBehaviorManifest(report) {
+  const index = toScenarioIndex(report);
+  const bySource = /* @__PURE__ */ new Map();
+  const byTag = /* @__PURE__ */ new Map();
+  const docKinds = /* @__PURE__ */ new Set();
+  const debuggerIssues = [];
+  for (const scenario of index.scenarios) {
+    const source = bySource.get(scenario.sourceFile) ?? {
+      path: scenario.sourceFile,
+      scenarioCount: 0,
+      failed: 0,
+      tags: []
+    };
+    source.scenarioCount += 1;
+    if (scenario.status === "failed") source.failed += 1;
+    source.tags = [.../* @__PURE__ */ new Set([...source.tags, ...scenario.tags])].sort();
+    bySource.set(scenario.sourceFile, source);
+    for (const tag of scenario.tags) {
+      const tagEntry = byTag.get(tag) ?? { name: tag, scenarioCount: 0 };
+      tagEntry.scenarioCount += 1;
+      byTag.set(tag, tagEntry);
+    }
+    for (const kind of scenario.docKinds) docKinds.add(kind);
+    for (const step of scenario.steps) {
+      for (const kind of step.docKinds) docKinds.add(kind);
+    }
+    if (!scenarioHasDocs(scenario)) {
+      debuggerIssues.push({
+        severity: "warning",
+        code: "missing-docs",
+        scenarioId: scenario.id,
+        title: scenario.title,
+        message: "Scenario has no doc entries."
+      });
+    }
+    if (scenario.tags.length === 0) {
+      debuggerIssues.push({
+        severity: "warning",
+        code: "missing-tags",
+        scenarioId: scenario.id,
+        title: scenario.title,
+        message: "Scenario has no tags."
+      });
+    }
+    if (scenario.covers.length === 0) {
+      debuggerIssues.push({
+        severity: "warning",
+        code: "missing-covers",
+        scenarioId: scenario.id,
+        title: scenario.title,
+        message: "Scenario declares no covers (product-code paths), so code\u2192scenario lookup cannot find it."
+      });
+    }
+    if (scenario.sourceLine === void 0) {
+      debuggerIssues.push({
+        severity: "warning",
+        code: "missing-source-line",
+        scenarioId: scenario.id,
+        title: scenario.title,
+        message: "Scenario has no source line."
+      });
+    }
+  }
+  const scenariosWithDocs = index.scenarios.filter(scenarioHasDocs).length;
+  return {
+    schemaVersion: "1.0",
+    runId: report.runId,
+    generatedAtMs: report.finishedAtMs,
+    summary: index.summary,
+    sourceFiles: [...bySource.values()].sort((a, b) => a.path.localeCompare(b.path)),
+    tags: [...byTag.values()].sort((a, b) => a.name.localeCompare(b.name)),
+    docCoverage: {
+      scenariosWithDocs,
+      scenariosWithoutDocs: index.scenarios.length - scenariosWithDocs,
+      docKinds: [...docKinds].sort()
+    },
+    debugger: debuggerIssues
+  };
+}
+function scenarioHasDocs(scenario) {
+  return scenario.docKinds.length > 0 || scenario.steps.some((step) => step.docKinds.length > 0);
+}
+
 // src/formatters/html/renderers/index.ts
 import * as fs2 from "fs";
 import * as path3 from "path";
@@ -14461,7 +14687,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 +14696,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 +14741,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 +14820,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 +14946,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 +14964,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 +15187,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");
@@ -16478,8 +16704,8 @@ function extractDocAttachments(step) {
   }
   return attachments;
 }
-function guessMediaType(path10) {
-  const lower = path10.toLowerCase();
+function guessMediaType(path11) {
+  const lower = path11.toLowerCase();
   if (lower.endsWith(".png")) return "image/png";
   if (lower.endsWith(".jpg") || lower.endsWith(".jpeg")) return "image/jpeg";
   if (lower.endsWith(".gif")) return "image/gif";
@@ -16620,11 +16846,11 @@ var CucumberHtmlFormatter = class {
     for (const envelope of envelopes) {
       const accepted = htmlStream.write(envelope);
       if (!accepted) {
-        await new Promise((resolve8) => htmlStream.once("drain", resolve8));
+        await new Promise((resolve9) => htmlStream.once("drain", resolve9));
       }
     }
-    await new Promise((resolve8, reject) => {
-      collector.on("finish", resolve8);
+    await new Promise((resolve9, reject) => {
+      collector.on("finish", resolve9);
       collector.on("error", reject);
       htmlStream.end();
     });
@@ -18235,6 +18461,68 @@ function copyMarkdownAssets(options) {
   };
 }
 
+// src/watch.ts
+import * as fs6 from "fs";
+import * as path7 from "path";
+function toRun(data, inputType, synthesize) {
+  if (inputType === "canonical") return data;
+  let raw = data;
+  if (synthesize) raw = synthesizeStories(raw);
+  return canonicalizeRun(raw);
+}
+async function regenerateArtifacts(options, deps = {}) {
+  const read = deps.readFile ?? ((filePath) => fs6.readFileSync(filePath, "utf8"));
+  const data = JSON.parse(read(path7.resolve(options.input)));
+  const run = toRun(data, options.inputType ?? "raw", options.synthesize !== false);
+  const generator = new ReportGenerator({
+    formats: options.formats,
+    outputDir: options.outputDir,
+    outputName: options.outputName
+  });
+  const result = await generator.generate(run);
+  return [...result.values()].flat();
+}
+function startWatch(options, deps = {}) {
+  const log = deps.log ?? ((message) => console.log(message));
+  const regenerate = deps.regenerate ?? ((input) => regenerateArtifacts({ ...options, input }, deps));
+  const watchFn = deps.watch ?? ((filePath, listener) => fs6.watch(filePath, listener));
+  const debounceMs = options.debounceMs ?? 150;
+  let timer;
+  let running = false;
+  let pending = false;
+  const run = async () => {
+    if (running) {
+      pending = true;
+      return;
+    }
+    running = true;
+    try {
+      const files = await regenerate(options.input);
+      log(`Regenerated ${files.length} artifact file(s) from ${options.input}`);
+    } catch (error) {
+      log(`Watch regeneration failed: ${error.message}`);
+    } finally {
+      running = false;
+      if (pending) {
+        pending = false;
+        trigger();
+      }
+    }
+  };
+  const trigger = () => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => void run(), debounceMs);
+  };
+  trigger();
+  const watcher = watchFn(path7.resolve(options.input), trigger);
+  return {
+    close: () => {
+      if (timer) clearTimeout(timer);
+      watcher.close();
+    }
+  };
+}
+
 // src/publishers/confluence.ts
 function parseAdf(adf) {
   let parsed;
@@ -19403,12 +19691,22 @@ function listScenarios(args, _deps) {
   const { testCases, format } = args;
   if (format === "json") {
     const items = testCases.map((tc) => ({
+      id: tc.id,
       scenario: tc.story.scenario,
       status: tc.status,
       sourceFile: tc.sourceFile,
       sourceLine: tc.sourceLine,
+      suitePath: tc.story.suitePath ?? tc.titlePath.slice(0, -1),
       tags: tc.tags,
-      id: tc.id
+      tickets: tc.story.tickets ?? [],
+      covers: tc.story.covers ?? [],
+      durationMs: tc.durationMs,
+      error: tc.errorMessage ? {
+        message: tc.errorMessage,
+        stack: tc.errorStack
+      } : void 0,
+      steps: tc.story.steps.map((step, index) => toScenarioStep(step, index, tc)),
+      docKinds: collectDocKinds(tc)
     }));
     return JSON.stringify(items, null, 2);
   }
@@ -19481,10 +19779,730 @@ function listScenarios(args, _deps) {
   ];
   return lines.join("\n");
 }
+function toScenarioStep(step, index, testCase) {
+  const result = testCase.stepResults.find(
+    (candidate) => candidate.index === index || candidate.stepId === step.id
+  );
+  return {
+    id: step.id,
+    index,
+    keyword: step.keyword,
+    text: step.text,
+    status: result?.status ?? testCase.status,
+    durationMs: result?.durationMs ?? step.durationMs ?? 0,
+    errorMessage: result?.errorMessage,
+    mode: step.mode,
+    docKinds: (step.docs ?? []).map((doc) => doc.kind)
+  };
+}
+function collectDocKinds(testCase) {
+  const kinds = /* @__PURE__ */ new Set();
+  for (const doc of testCase.story.docs ?? []) {
+    kinds.add(doc.kind);
+  }
+  for (const step of testCase.story.steps) {
+    for (const doc of step.docs ?? []) {
+      kinds.add(doc.kind);
+    }
+  }
+  return [...kinds].sort();
+}
+
+// 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(path11) {
+  const base = path11.split("/").pop() ?? path11;
+  const dot = base.lastIndexOf(".");
+  return dot === -1 ? "" : base.slice(dot + 1).toLowerCase();
+}
+function isTestFile(path11) {
+  return TEST_INFIX.test(path11);
+}
+function isReviewableSource(path11) {
+  if (isTestFile(path11)) return false;
+  if (path11.endsWith(".d.ts")) return false;
+  return CODE_EXTENSIONS.has(extensionOf(path11));
+}
+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(
+    (path11) => sourceBaseKey(path11) === 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",
+  "behavior-manifest-json": ".behavior-manifest.json",
   markdown: ".md",
   html: ".html",
   "cucumber-html": ".cucumber.html",
@@ -19492,6 +20510,7 @@ var FORMAT_EXTENSIONS = {
   "cucumber-json": ".cucumber.json",
   "cucumber-messages": ".ndjson",
   confluence: ".adf.json",
+  "scenario-index-json": ".scenarios-index.json",
   "story-report-json": ".story-report.json"
 };
 var TEST_EXTENSIONS = [
@@ -19519,11 +20538,11 @@ function computeOutputPath(sourceFile, format, mode, colocatedStyle, baseOutputD
   const ext = FORMAT_EXTENSIONS[format];
   const effectiveName = outputName + (outputNameSuffix ?? "");
   if (mode === "aggregated") {
-    return toPosix(path7.join(baseOutputDir, `${effectiveName}${ext}`));
+    return toPosix(path8.join(baseOutputDir, `${effectiveName}${ext}`));
   }
   const normalizedSource = toPosix(sourceFile);
-  const dirOfSource = path7.posix.dirname(normalizedSource);
-  let baseName = path7.posix.basename(normalizedSource);
+  const dirOfSource = path8.posix.dirname(normalizedSource);
+  let baseName = path8.posix.basename(normalizedSource);
   for (const testExt of TEST_EXTENSIONS) {
     if (baseName.endsWith(testExt)) {
       baseName = baseName.slice(0, -testExt.length);
@@ -19532,9 +20551,9 @@ function computeOutputPath(sourceFile, format, mode, colocatedStyle, baseOutputD
   }
   const fileName = `${baseName}.${effectiveName}${ext}`;
   if (colocatedStyle === "adjacent") {
-    return toPosix(path7.posix.join(dirOfSource, fileName));
+    return toPosix(path8.posix.join(dirOfSource, fileName));
   }
-  return toPosix(path7.posix.join(baseOutputDir, dirOfSource, fileName));
+  return toPosix(path8.posix.join(baseOutputDir, dirOfSource, fileName));
 }
 function groupTestCasesByOutput(testCases, format, options, logger, outputNameSuffix) {
   const groups = /* @__PURE__ */ new Map();
@@ -19620,6 +20639,12 @@ var ReportGenerator = class {
       storyReportJson: {
         pretty: options.storyReportJson?.pretty ?? true
       },
+      scenarioIndexJson: {
+        pretty: options.scenarioIndexJson?.pretty ?? true
+      },
+      behaviorManifestJson: {
+        pretty: options.behaviorManifestJson?.pretty ?? true
+      },
       cucumberMessages: {
         uriStrategy: options.cucumberMessages?.uriStrategy ?? "sourceFile",
         includeSynthetics: options.cucumberMessages?.includeSynthetics ?? true,
@@ -19735,8 +20760,8 @@ var ReportGenerator = class {
       if (astroPaths) {
         for (const mdPath of astroPaths) {
           const content = await fsPromises.readFile(mdPath, "utf8");
-          const mdDir = path7.dirname(mdPath);
-          const assetsDir = path7.resolve(this.options.astro.assetsDir);
+          const mdDir = path8.dirname(mdPath);
+          const assetsDir = path8.resolve(this.options.astro.assetsDir);
           const result = copyMarkdownAssets({
             markdown: content,
             markdownDir: mdDir,
@@ -19767,9 +20792,9 @@ var ReportGenerator = class {
     if (groups.size === 0 && this.options.output.mode === "aggregated") {
       const ext = FORMAT_EXTENSIONS[format];
       const effectiveName = this.options.outputName + (outputNameSuffix ?? "");
-      const outputPath = toPosix(path7.join(this.options.outputDir, `${effectiveName}${ext}`));
+      const outputPath = toPosix(path8.join(this.options.outputDir, `${effectiveName}${ext}`));
       const content = await this.formatContent(run, format);
-      const dir = path7.dirname(outputPath);
+      const dir = path8.dirname(outputPath);
       await fsPromises.mkdir(dir, { recursive: true });
       await this.deps.writeFile(outputPath, content);
       return [outputPath];
@@ -19781,7 +20806,7 @@ var ReportGenerator = class {
         testCases
       };
       const content = await this.formatContent(groupRun, format);
-      const dir = path7.dirname(outputPath);
+      const dir = path8.dirname(outputPath);
       await fsPromises.mkdir(dir, { recursive: true });
       await this.deps.writeFile(outputPath, content);
       writtenPaths.push(outputPath);
@@ -19894,6 +20919,18 @@ var ReportGenerator = class {
         });
         return formatter.format(run);
       }
+      case "scenario-index-json": {
+        const formatter = new ScenarioIndexJsonFormatter({
+          pretty: this.options.scenarioIndexJson.pretty
+        });
+        return formatter.format(run);
+      }
+      case "behavior-manifest-json": {
+        const formatter = new BehaviorManifestJsonFormatter({
+          pretty: this.options.behaviorManifestJson.pretty
+        });
+        return formatter.format(run);
+      }
       default:
         throw new Error(`Unknown format: ${format}`);
     }
@@ -19907,7 +20944,7 @@ async function generateRunComparison(args) {
   await fsPromises.mkdir(outputDir, { recursive: true });
   for (const format of args.formats) {
     const ext = format === "html" ? ".html" : ".md";
-    const outputPath = toPosix(path7.join(outputDir, `${outputName}${ext}`));
+    const outputPath = toPosix(path8.join(outputDir, `${outputName}${ext}`));
     const content = format === "html" ? new RunDiffHtmlFormatter({ title: args.title }).format(diff) : new RunDiffMarkdownFormatter({ title: args.title }).format(diff);
     await fsPromises.writeFile(outputPath, content, "utf8");
     files.push(outputPath);
@@ -19916,23 +20953,23 @@ async function generateRunComparison(args) {
 }
 
 // src/init-astro.ts
-import * as fs7 from "fs";
-import * as path8 from "path";
+import * as fs8 from "fs";
+import * as path9 from "path";
 import { fileURLToPath } from "url";
-var __dirname = path8.dirname(fileURLToPath(import.meta.url));
+var __dirname = path9.dirname(fileURLToPath(import.meta.url));
 function initAstro(options = {}) {
   const targetDir = options.targetDir ?? "./story-docs";
   const force = options.force ?? false;
-  if (fs7.existsSync(targetDir)) {
-    const entries = fs7.readdirSync(targetDir);
+  if (fs8.existsSync(targetDir)) {
+    const entries = fs8.readdirSync(targetDir);
     if (entries.length > 0 && !force) {
       throw new Error(
         `Directory "${targetDir}" already exists and is not empty. Use --force to overwrite.`
       );
     }
   }
-  const templateDir = path8.resolve(__dirname, "..", "templates", "astro-starlight");
-  if (!fs7.existsSync(templateDir)) {
+  const templateDir = path9.resolve(__dirname, "..", "templates", "astro-starlight");
+  if (!fs8.existsSync(templateDir)) {
     throw new Error(
       `Template directory not found at ${templateDir}. Ensure the package is installed correctly.`
     );
@@ -19941,24 +20978,24 @@ function initAstro(options = {}) {
   return { targetDir };
 }
 function copyDirRecursive(src, dest) {
-  fs7.mkdirSync(dest, { recursive: true });
-  const entries = fs7.readdirSync(src, { withFileTypes: true });
+  fs8.mkdirSync(dest, { recursive: true });
+  const entries = fs8.readdirSync(src, { withFileTypes: true });
   for (const entry of entries) {
-    const srcPath = path8.join(src, entry.name);
-    const destPath = path8.join(dest, entry.name);
+    const srcPath = path9.join(src, entry.name);
+    const destPath = path9.join(dest, entry.name);
     if (entry.isDirectory()) {
       copyDirRecursive(srcPath, destPath);
     } else {
-      fs7.copyFileSync(srcPath, destPath);
+      fs8.copyFileSync(srcPath, destPath);
     }
   }
 }
 
 // src/config.ts
 import { existsSync as existsSync7 } from "fs";
-import { resolve as resolve6 } from "path";
+import { resolve as resolve7 } from "path";
 async function loadConfig(configPath) {
-  const resolved = configPath ? resolve6(configPath) : resolve6(process.cwd(), "executable-stories.config.js");
+  const resolved = configPath ? resolve7(configPath) : resolve7(process.cwd(), "executable-stories.config.js");
   if (!existsSync7(resolved)) return {};
   const mod = await import(resolved);
   const config = mod.default;
@@ -19977,6 +21014,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 +21022,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
@@ -19993,7 +21032,9 @@ USAGE
 
 SUBCOMMANDS
   format             Read raw test results and generate reports
+  watch              Regenerate reports whenever the raw-run file changes (live agent index)
   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)
@@ -20001,9 +21042,10 @@ SUBCOMMANDS
   publish-jira       Publish an ADF JSON file to a Jira issue (as comment or description)
 
 OPTIONS
-  --format <formats>            Comma-separated formats: html, markdown, junit, cucumber-json, cucumber-messages, cucumber-html, astro, confluence, story-report-json, or custom names from config (default: html)
+  --format <formats>            Comma-separated formats: html, markdown, junit, cucumber-json, cucumber-messages, cucumber-html, astro, confluence, story-report-json, scenario-index-json, behavior-manifest-json, or custom names from config (default: html)
                                   astro             Themed Markdown (for Astro docs sites with matching CSS)
                                   confluence        Atlassian Document Format (ADF) JSON for Confluence / Jira
+                                  behavior-manifest-json Agent-readable behavior manifest and debugger warnings
                                   html              Custom HTML report (accessible, dark mode, mermaid)
                                   cucumber-html     Official Cucumber HTML report
                                   markdown          Markdown documentation
@@ -20011,6 +21053,7 @@ OPTIONS
                                   cucumber-json     Cucumber JSON
                                   cucumber-messages Raw NDJSON (Cucumber Messages)
                                   story-report-json StoryReport v1 JSON (consumed by executable-stories-react and other UI renderers)
+                                  scenario-index-json Storybook-like scenario index for agents and explorers
   --config <path>               Path to executable-stories.config.js (default: ./executable-stories.config.js)
   --input-type <type>           Input type: raw, canonical, or ndjson (default: raw)
   --output-dir <dir>            Output directory (default: reports)
@@ -20044,6 +21087,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 +21164,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 !== "watch" && 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", "watch", "compare", "review", "list", "validate", "init-astro", "publish-confluence", or "publish-jira".`
     );
     process.exit(EXIT_USAGE);
   }
@@ -20156,6 +21204,9 @@ async function parseCliArgs(argv) {
       console.log("");
       console.log("Generate story docs with:");
       console.log(`  executable-stories format run.json --format astro --output-dir ${result.targetDir}/src/content/docs/stories --asset-mode copy`);
+      console.log("");
+      console.log("Generate the Storybook-like scenario explorer data with:");
+      console.log(`  executable-stories format run.json --format story-report-json --output-dir ${result.targetDir}/public/stories --output-name story-report`);
       process.exit(EXIT_SUCCESS);
     } catch (err) {
       console.error(`Error: ${err.message}`);
@@ -20212,6 +21263,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 }
     },
@@ -20252,7 +21308,7 @@ async function parseCliArgs(argv) {
   }
   const pluginConfig = await loadConfig(values["config"]);
   const customFormatterNames = new Set(Object.keys(pluginConfig.formatters ?? {}));
-  const builtInFormats = /* @__PURE__ */ new Set(["astro", "confluence", "html", "markdown", "junit", "cucumber-json", "cucumber-messages", "cucumber-html", "story-report-json"]);
+  const builtInFormats = /* @__PURE__ */ new Set(["astro", "behavior-manifest-json", "confluence", "html", "markdown", "junit", "cucumber-json", "cucumber-messages", "cucumber-html", "scenario-index-json", "story-report-json"]);
   const formatStr = values.format;
   const allRequestedFormats = formatStr.split(",").map((f) => f.trim());
   const builtInRequested = allRequestedFormats.filter((f) => builtInFormats.has(f));
@@ -20260,7 +21316,7 @@ async function parseCliArgs(argv) {
   const unknownFormats = allRequestedFormats.filter((f) => !builtInFormats.has(f) && !customFormatterNames.has(f));
   if (unknownFormats.length > 0) {
     const knownCustom = customFormatterNames.size > 0 ? `, ${[...customFormatterNames].join(", ")}` : "";
-    console.error(`Error: Unknown format(s): ${unknownFormats.join(", ")}. Valid built-in: astro, confluence, html, markdown, junit, cucumber-json, cucumber-messages, cucumber-html, story-report-json${knownCustom}.`);
+    console.error(`Error: Unknown format(s): ${unknownFormats.join(", ")}. Valid built-in: astro, behavior-manifest-json, confluence, html, markdown, junit, cucumber-json, cucumber-messages, cucumber-html, scenario-index-json, story-report-json${knownCustom}.`);
     process.exit(EXIT_USAGE);
   }
   const formats = builtInRequested;
@@ -20337,6 +21393,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 +21455,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 };
@@ -20396,27 +21468,27 @@ async function readInput(args) {
   if (args.stdin) {
     return readStdin();
   }
-  const filePath = path9.resolve(args.inputFile);
-  if (!fs8.existsSync(filePath)) {
+  const filePath = path10.resolve(args.inputFile);
+  if (!fs9.existsSync(filePath)) {
     console.error(`Error: File not found: ${filePath}`);
     process.exit(EXIT_USAGE);
   }
-  return fs8.readFileSync(filePath, "utf8");
+  return fs9.readFileSync(filePath, "utf8");
 }
 function readFileInput(filePath) {
-  const resolved = path9.resolve(filePath);
-  if (!fs8.existsSync(resolved)) {
+  const resolved = path10.resolve(filePath);
+  if (!fs9.existsSync(resolved)) {
     console.error(`Error: File not found: ${resolved}`);
     process.exit(EXIT_USAGE);
   }
-  return fs8.readFileSync(resolved, "utf8");
+  return fs9.readFileSync(resolved, "utf8");
 }
 function readStdin() {
-  return new Promise((resolve8, reject) => {
+  return new Promise((resolve9, reject) => {
     const chunks = [];
     process.stdin.setEncoding("utf8");
     process.stdin.on("data", (chunk) => chunks.push(chunk));
-    process.stdin.on("end", () => resolve8(chunks.join("")));
+    process.stdin.on("end", () => resolve9(chunks.join("")));
     process.stdin.on("error", reject);
   });
 }
@@ -20542,14 +21614,14 @@ function tryNormalizeRunFromText(text2, args) {
   }
 }
 function listBaselineCandidates(currentFile, args) {
-  const baselineDir = path9.resolve(args.baselineDir ?? path9.dirname(currentFile));
-  const currentResolved = path9.resolve(currentFile);
-  if (!fs8.existsSync(baselineDir)) {
+  const baselineDir = path10.resolve(args.baselineDir ?? path10.dirname(currentFile));
+  const currentResolved = path10.resolve(currentFile);
+  if (!fs9.existsSync(baselineDir)) {
     console.error(`Error: baseline directory not found: ${baselineDir}`);
     process.exit(EXIT_USAGE);
   }
-  const entries = fs8.readdirSync(baselineDir, { withFileTypes: true });
-  return entries.filter((entry) => entry.isFile()).map((entry) => path9.join(baselineDir, entry.name)).filter((candidate) => path9.resolve(candidate) !== currentResolved).filter(
+  const entries = fs9.readdirSync(baselineDir, { withFileTypes: true });
+  return entries.filter((entry) => entry.isFile()).map((entry) => path10.join(baselineDir, entry.name)).filter((candidate) => path10.resolve(candidate) !== currentResolved).filter(
     (candidate) => args.inputType === "ndjson" ? candidate.endsWith(".ndjson") : candidate.endsWith(".json")
   );
 }
@@ -20557,14 +21629,14 @@ function resolveBaselineAuto(currentFile, currentRun, args) {
   const candidates = listBaselineCandidates(currentFile, args);
   const comparable = [];
   for (const candidate of candidates) {
-    const run = tryNormalizeRunFromText(fs8.readFileSync(candidate, "utf8"), args);
+    const run = tryNormalizeRunFromText(fs9.readFileSync(candidate, "utf8"), args);
     if (run) {
       comparable.push({ file: candidate, run });
     }
   }
   if (comparable.length === 0) {
     console.error(
-      `Error: no compatible baseline files found in ${path9.resolve(args.baselineDir ?? path9.dirname(currentFile))}.`
+      `Error: no compatible baseline files found in ${path10.resolve(args.baselineDir ?? path10.dirname(currentFile))}.`
     );
     process.exit(EXIT_USAGE);
   }
@@ -20601,6 +21673,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);
@@ -20617,6 +21713,24 @@ async function main() {
     console.log(output);
     process.exit(EXIT_SUCCESS);
   }
+  if (args.subcommand === "watch") {
+    if (!args.inputFile) {
+      console.error("Error: watch requires an input file (the raw-run JSON the framework writes).");
+      process.exit(EXIT_USAGE);
+    }
+    console.log(
+      `Watching ${args.inputFile} \u2192 regenerating [${args.formats.join(", ")}] into ${args.outputDir}/ (Ctrl+C to stop)`
+    );
+    startWatch({
+      input: args.inputFile,
+      outputDir: args.outputDir,
+      outputName: args.outputName,
+      formats: args.formats,
+      inputType: args.inputType === "canonical" ? "canonical" : "raw",
+      synthesize: args.synthesizeStories
+    });
+    return;
+  }
   const text2 = await readInput(args);
   if (args.inputType === "ndjson") {
     if (args.subcommand === "validate") {
@@ -20660,9 +21774,9 @@ async function main() {
       process.exit(EXIT_SCHEMA_VALIDATION);
     }
     if (args.emitCanonical) {
-      const outPath = path9.resolve(args.emitCanonical);
-      fs8.mkdirSync(path9.dirname(outPath), { recursive: true });
-      fs8.writeFileSync(outPath, JSON.stringify(run, null, 2), "utf8");
+      const outPath = path10.resolve(args.emitCanonical);
+      fs9.mkdirSync(path10.dirname(outPath), { recursive: true });
+      fs9.writeFileSync(outPath, JSON.stringify(run, null, 2), "utf8");
     }
     try {
       const result = await generateReports(run, args);
@@ -20719,9 +21833,9 @@ ${msg}`);
     }
     const run = data;
     if (args.emitCanonical) {
-      const outPath = path9.resolve(args.emitCanonical);
-      fs8.mkdirSync(path9.dirname(outPath), { recursive: true });
-      fs8.writeFileSync(outPath, JSON.stringify(run, null, 2), "utf8");
+      const outPath = path10.resolve(args.emitCanonical);
+      fs9.mkdirSync(path10.dirname(outPath), { recursive: true });
+      fs9.writeFileSync(outPath, JSON.stringify(run, null, 2), "utf8");
     }
     try {
       const result = await generateReports(run, args);
@@ -20777,9 +21891,9 @@ ${msg}`);
     process.exit(EXIT_CANONICAL_VALIDATION);
   }
   if (args.emitCanonical) {
-    const outPath = path9.resolve(args.emitCanonical);
-    fs8.mkdirSync(path9.dirname(outPath), { recursive: true });
-    fs8.writeFileSync(outPath, JSON.stringify(canonical, null, 2), "utf8");
+    const outPath = path10.resolve(args.emitCanonical);
+    fs9.mkdirSync(path10.dirname(outPath), { recursive: true });
+    fs9.writeFileSync(outPath, JSON.stringify(canonical, null, 2), "utf8");
   }
   try {
     const result = await generateReports(canonical, args, droppedMissingStory);
@@ -20804,9 +21918,9 @@ function runCustomFormatters(run, customRequested, formatters, args) {
       const ext = formatter.fileExtension ?? formatName;
       const baseName = args.outputName ?? "report";
       const filename = args.outputNameTimestamp ? `${baseName}-${Math.floor(run.startedAtMs / 1e3)}.${ext}` : `${baseName}.${ext}`;
-      const filepath = path9.join(outputDir, filename);
-      fs8.mkdirSync(outputDir, { recursive: true });
-      fs8.writeFileSync(filepath, content, "utf8");
+      const filepath = path10.join(outputDir, filename);
+      fs9.mkdirSync(outputDir, { recursive: true });
+      fs9.writeFileSync(filepath, content, "utf8");
       console.log(`Generated: ${filepath}`);
     } catch (err) {
       console.error(`Error running custom formatter "${formatName}": ${err instanceof Error ? err.message : String(err)}`);
@@ -20856,13 +21970,13 @@ async function dispatchNotifications(run, args) {
 }
 function runHistoryPipeline(run, args) {
   if (!args.historyFile) return;
-  const historyPath = path9.resolve(args.historyFile);
+  const historyPath = path10.resolve(args.historyFile);
   const store = loadHistory(
     { filePath: historyPath },
     {
       readFile: (p) => {
         try {
-          return fs8.readFileSync(p, "utf8");
+          return fs9.readFileSync(p, "utf8");
         } catch {
           return void 0;
         }
@@ -20875,11 +21989,11 @@ function runHistoryPipeline(run, args) {
     run,
     maxRuns: args.maxHistoryRuns
   });
-  const dir = path9.dirname(historyPath);
-  fs8.mkdirSync(dir, { recursive: true });
+  const dir = path10.dirname(historyPath);
+  fs9.mkdirSync(dir, { recursive: true });
   saveHistory(
     { filePath: historyPath, store: updated },
-    { writeFile: (p, content) => fs8.writeFileSync(p, content, "utf8") }
+    { writeFile: (p, content) => fs9.writeFileSync(p, content, "utf8") }
   );
   let metricsCount = 0;
   for (const testId of Object.keys(updated.tests)) {
@@ -20959,6 +22073,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)}` : "";
+  fs9.mkdirSync(outputDir, { recursive: true });
+  const mdPath = path10.join(outputDir, `${baseName}${suffix}.md`);
+  const htmlPath = path10.join(outputDir, `${baseName}${suffix}.html`);
+  fs9.writeFileSync(mdPath, markdown, "utf8");
+  fs9.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) {
@@ -20980,9 +22190,9 @@ function printResult(result, args, startMs, droppedMissingStory = 0) {
 function printCompareResult(result, args, startMs) {
   const durationMs = Date.now() - startMs;
   if (result.prSummary && args.prSummaryFile) {
-    const outputPath = path9.resolve(args.prSummaryFile);
-    fs8.mkdirSync(path9.dirname(outputPath), { recursive: true });
-    fs8.writeFileSync(outputPath, result.prSummary, "utf8");
+    const outputPath = path10.resolve(args.prSummaryFile);
+    fs9.mkdirSync(path10.dirname(outputPath), { recursive: true });
+    fs9.writeFileSync(outputPath, result.prSummary, "utf8");
   }
   if (args.jsonSummary) {
     console.log(
@@ -21073,7 +22283,7 @@ Generate an API token at https://id.atlassian.com/manage-profile/security/api-to
     console.error("Error: missing ADF file argument. Run with --help for usage.");
     process.exit(EXIT_USAGE);
   }
-  if (!fs8.existsSync(inputFile)) {
+  if (!fs9.existsSync(inputFile)) {
     console.error(`Error: file not found: ${inputFile}`);
     process.exit(EXIT_USAGE);
   }
@@ -21101,7 +22311,7 @@ Generate an API token at https://id.atlassian.com/manage-profile/security/api-to
     console.error("Error: --title is required when creating a new page");
     process.exit(EXIT_USAGE);
   }
-  const adf = fs8.readFileSync(path9.resolve(inputFile), "utf8");
+  const adf = fs9.readFileSync(path10.resolve(inputFile), "utf8");
   if (dryRun) {
     console.log(
       JSON.stringify(
@@ -21180,7 +22390,7 @@ Generate an API token at https://id.atlassian.com/manage-profile/security/api-to
     console.error("Error: missing ADF file argument. Run with --help for usage.");
     process.exit(EXIT_USAGE);
   }
-  if (!fs8.existsSync(inputFile)) {
+  if (!fs9.existsSync(inputFile)) {
     console.error(`Error: file not found: ${inputFile}`);
     process.exit(EXIT_USAGE);
   }
@@ -21207,7 +22417,7 @@ Generate an API token at https://id.atlassian.com/manage-profile/security/api-to
     process.exit(EXIT_USAGE);
   }
   const mode = modeRaw;
-  const adf = fs8.readFileSync(path9.resolve(inputFile), "utf8");
+  const adf = fs9.readFileSync(path10.resolve(inputFile), "utf8");
   if (dryRun) {
     console.log(
       JSON.stringify(