executable-stories-formatters 0.12.0 → 0.14.0

package/dist/cli.js

@@ -191,6 +191,11 @@ var raw_run_schema_default = {
           },
           description: "Ticket/issue references. Each item is either a string ID or an object with id and optional url."
         },
+        covers: {
+          type: "array",
+          items: { type: "string" },
+          description: "Product-code paths/globs this scenario exercises (project-root-relative). Used to map code changes to at-risk scenarios."
+        },
         meta: {
           type: "object",
           description: "User-defined metadata for this story."
@@ -512,6 +517,10 @@ var raw_run_schema_default = {
           minimum: 0,
           description: "Step index (0-based)."
         },
+        stepId: {
+          type: "string",
+          description: "Stable step ID when the framework provides one (correlates with StoryStep.id)."
+        },
         title: {
           type: "string",
           description: "Step title/description."
@@ -1228,7 +1237,7 @@ var CucumberJsonFormatter = class {
   /**
    * Build a single step.
    */
-  buildStep(step, result, line, index, attachments, isLastStep, hasFailedStep) {
+  buildStep(step, result, line2, index, attachments, isLastStep, hasFailedStep) {
     const keyword = this.options.keywordSpacing ? `${step.keyword} ` : step.keyword;
     const stepResult = this.buildStepResult(result);
     const embeddings = this.buildEmbeddings(attachments, result, isLastStep, hasFailedStep);
@@ -1236,7 +1245,7 @@ var CucumberJsonFormatter = class {
     embeddings.push(...screenshotEmbeddings);
     const jsonStep = {
       keyword,
-      line,
+      line: line2,
       name: step.text,
       result: stepResult
     };
@@ -1290,14 +1299,14 @@ var CucumberJsonFormatter = class {
         duration: 0
       };
     }
-    const statusMap = {
+    const statusMap2 = {
       passed: "passed",
       failed: "failed",
       skipped: "skipped",
       pending: "pending"
     };
     const stepResult = {
-      status: statusMap[result.status] ?? "undefined",
+      status: statusMap2[result.status] ?? "undefined",
       // Duration in nanoseconds (Cucumber uses nanoseconds)
       duration: result.durationMs * 1e6
     };
@@ -15783,8 +15792,8 @@ var JUnitFormatter = class {
       case "section": {
         const lines = [];
         lines.push(`${indent}${entry.title}:`);
-        for (const line of entry.markdown.split("\n")) {
-          lines.push(`${indent}  ${line}`);
+        for (const line2 of entry.markdown.split("\n")) {
+          lines.push(`${indent}  ${line2}`);
         }
         return lines.join("\n");
       }
@@ -15793,8 +15802,8 @@ var JUnitFormatter = class {
         if (entry.title) {
           lines.push(`${indent}${entry.title}:`);
         }
-        for (const line of entry.code.split("\n")) {
-          lines.push(`${indent}  ${line}`);
+        for (const line2 of entry.code.split("\n")) {
+          lines.push(`${indent}  ${line2}`);
         }
         return lines.join("\n");
       }
@@ -15806,8 +15815,8 @@ var JUnitFormatter = class {
         const dataStr = JSON.stringify(entry.data, null, 2);
         const lines = [];
         lines.push(`${indent}[${entry.type}]:`);
-        for (const line of dataStr.split("\n")) {
-          lines.push(`${indent}  ${line}`);
+        for (const line2 of dataStr.split("\n")) {
+          lines.push(`${indent}  ${line2}`);
         }
         return lines.join("\n");
       }
@@ -15853,7 +15862,9 @@ var MarkdownFormatter = class {
       ticketUrlTemplate: options.ticketUrlTemplate,
       traceUrlTemplate: options.traceUrlTemplate,
       includeSourceLinks: options.includeSourceLinks ?? true,
-      customRenderers: options.customRenderers
+      customRenderers: options.customRenderers,
+      scenarioAnchor: options.scenarioAnchor,
+      scenarioBadge: options.scenarioBadge
     };
   }
   /**
@@ -16040,6 +16051,11 @@ var MarkdownFormatter = class {
    * Render a single scenario.
    */
   renderScenario(lines, tc) {
+    const anchorId = this.options.scenarioAnchor?.(tc);
+    if (anchorId) {
+      lines.push(`<a id="${anchorId}"></a>`);
+      lines.push("");
+    }
     if (this.options.customRenderers?.renderScenarioHeader) {
       const custom = this.options.customRenderers.renderScenarioHeader(tc);
       if (custom !== null) {
@@ -16055,6 +16071,10 @@ var MarkdownFormatter = class {
       icon = this.getStatusIcon(tc.status) + " ";
     }
     lines.push(`${headingPrefix} ${icon}${tc.story.scenario}`);
+    const badge2 = this.options.scenarioBadge?.(tc);
+    if (badge2) {
+      lines.push(badge2);
+    }
     if (this.options.includeSourceLinks && this.options.permalinkBaseUrl && tc.sourceFile !== "unknown") {
       const permalink = this.buildPermalink(tc);
       lines.push(`Source: [${tc.sourceFile}](${permalink})`);
@@ -16129,8 +16149,8 @@ var MarkdownFormatter = class {
   buildPermalink(tc) {
     const base = this.options.permalinkBaseUrl.replace(/\/$/, "");
     const file = tc.sourceFile;
-    const line = tc.sourceLine > 0 ? `#L${tc.sourceLine}` : "";
-    return `${base}/${file}${line}`;
+    const line2 = tc.sourceLine > 0 ? `#L${tc.sourceLine}` : "";
+    return `${base}/${file}${line2}`;
   }
   /**
    * Render a step.
@@ -16198,8 +16218,8 @@ var MarkdownFormatter = class {
           lines.push(`${indent}`);
         }
         lines.push(`${indent}\`\`\`${entry.lang ?? ""}`);
-        for (const line of (entry.content ?? "").split("\n")) {
-          lines.push(`${indent}${line}`);
+        for (const line2 of (entry.content ?? "").split("\n")) {
+          lines.push(`${indent}${line2}`);
         }
         lines.push(`${indent}\`\`\``);
         lines.push(`${indent}`);
@@ -16222,8 +16242,8 @@ var MarkdownFormatter = class {
       case "section":
         lines.push(`${indent}**${entry.title}**`);
         lines.push(`${indent}`);
-        for (const line of (entry.markdown ?? "").split("\n")) {
-          lines.push(`${indent}${line}`);
+        for (const line2 of (entry.markdown ?? "").split("\n")) {
+          lines.push(`${indent}${line2}`);
         }
         lines.push(`${indent}`);
         break;
@@ -16232,8 +16252,8 @@ var MarkdownFormatter = class {
           lines.push(`${indent}**${entry.title}**`);
         }
         lines.push(`${indent}\`\`\`mermaid`);
-        for (const line of (entry.code ?? "").split("\n")) {
-          lines.push(`${indent}${line}`);
+        for (const line2 of (entry.code ?? "").split("\n")) {
+          lines.push(`${indent}${line2}`);
         }
         lines.push(`${indent}\`\`\``);
         break;
@@ -16263,8 +16283,8 @@ var MarkdownFormatter = class {
         lines.push(`${indent}<summary>${htmlLabel}</summary>`);
         lines.push(`${indent}`);
         lines.push(`${indent}\`\`\`html`);
-        for (const line of (entry.content ?? "").split("\n")) {
-          lines.push(`${indent}${line}`);
+        for (const line2 of (entry.content ?? "").split("\n")) {
+          lines.push(`${indent}${line2}`);
         }
         lines.push(`${indent}\`\`\``);
         lines.push(`${indent}`);
@@ -16286,8 +16306,8 @@ var MarkdownFormatter = class {
         lines.push(`${indent}**[${entry.type}]**`);
         lines.push(`${indent}`);
         lines.push(`${indent}\`\`\`json`);
-        for (const line of JSON.stringify(entry.data ?? null, null, 2).split("\n")) {
-          lines.push(`${indent}${line}`);
+        for (const line2 of JSON.stringify(entry.data ?? null, null, 2).split("\n")) {
+          lines.push(`${indent}${line2}`);
         }
         lines.push(`${indent}\`\`\``);
         lines.push(`${indent}`);
@@ -16446,6 +16466,132 @@ function escapePipe(value) {
   return value.replace(/\|/g, "\\|");
 }
 
+// src/formatters/traceability-matrix.ts
+var TraceabilityMatrixFormatter = class {
+  format(run) {
+    const matrix = toTraceabilityMatrix(run);
+    const lines = [];
+    lines.push("# Traceability Matrix");
+    lines.push("");
+    lines.push(`Generated: ${matrix.generatedAt}`);
+    lines.push(`Run: ${matrix.run.startedAt} to ${matrix.run.finishedAt}`);
+    if (matrix.run.branch) lines.push(`Branch: ${matrix.run.branch}`);
+    if (matrix.run.gitSha) lines.push(`Commit: ${matrix.run.gitSha}`);
+    lines.push("");
+    lines.push("| Requirements | Verified | Failing | Scenarios | Untraced |");
+    lines.push("| ---: | ---: | ---: | ---: | ---: |");
+    lines.push(
+      `| ${matrix.summary.requirements} | ${matrix.summary.requirementsVerified} | ${matrix.summary.requirementsFailing} | ${matrix.summary.scenarios} | ${matrix.summary.untracedScenarios} |`
+    );
+    lines.push("");
+    for (const req of matrix.requirements) {
+      const heading2 = req.url ? `[${req.ticket}](${req.url})` : req.ticket;
+      lines.push(`## ${heading2}`);
+      lines.push("");
+      lines.push(`Status: ${renderRequirementStatus(req.status)}`);
+      if (req.covers.length > 0) {
+        lines.push(`Covers: ${req.covers.map((path16) => `\`${path16}\``).join(", ")}`);
+      }
+      lines.push("");
+      lines.push("| Status | Scenario | Source | Covers |");
+      lines.push("| --- | --- | --- | --- |");
+      for (const scenario of req.scenarios) {
+        const source = `${scenario.sourceFile}:${scenario.sourceLine}`;
+        const covers = scenario.covers.length > 0 ? scenario.covers.map((path16) => `\`${path16}\``).join(", ") : "";
+        lines.push(`| ${scenario.status} | ${escapePipe2(scenario.title)} | \`${source}\` | ${covers} |`);
+      }
+      lines.push("");
+    }
+    if (matrix.untraced.length > 0) {
+      lines.push("## Untraced scenarios");
+      lines.push("");
+      lines.push("Behavior with no requirement link. Add a `ticket` to each so it appears against a requirement.");
+      lines.push("");
+      lines.push("| Status | Scenario | Source |");
+      lines.push("| --- | --- | --- |");
+      for (const scenario of matrix.untraced) {
+        const source = `${scenario.sourceFile}:${scenario.sourceLine}`;
+        lines.push(`| ${scenario.status} | ${escapePipe2(scenario.title)} | \`${source}\` |`);
+      }
+      lines.push("");
+    }
+    return lines.join("\n").trimEnd();
+  }
+};
+function toTraceabilityMatrix(run) {
+  const sorted = [...run.testCases].sort((a, b) => a.id.localeCompare(b.id));
+  const byTicket = /* @__PURE__ */ new Map();
+  const untraced = [];
+  for (const tc of sorted) {
+    const tickets = tc.story.tickets ?? [];
+    if (tickets.length === 0) {
+      untraced.push({
+        id: tc.id,
+        title: tc.story.scenario,
+        status: tc.status,
+        sourceFile: tc.sourceFile,
+        sourceLine: tc.sourceLine
+      });
+      continue;
+    }
+    for (const ticket of tickets) {
+      const entry = byTicket.get(ticket.id) ?? { url: ticket.url, cases: [] };
+      if (!entry.url && ticket.url) entry.url = ticket.url;
+      entry.cases.push(tc);
+      byTicket.set(ticket.id, entry);
+    }
+  }
+  const requirements = [...byTicket.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([ticket, entry]) => {
+    const scenarios = entry.cases.map((tc) => ({
+      id: tc.id,
+      title: tc.story.scenario,
+      status: tc.status,
+      sourceFile: tc.sourceFile,
+      sourceLine: tc.sourceLine,
+      covers: tc.story.covers ?? []
+    }));
+    const covers = [...new Set(scenarios.flatMap((s) => s.covers))].sort();
+    return { ticket, url: entry.url, status: requirementStatus(entry.cases), scenarios, covers };
+  });
+  return {
+    schemaVersion: "1.0",
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    run: {
+      startedAt: new Date(run.startedAtMs).toISOString(),
+      finishedAt: new Date(run.finishedAtMs).toISOString(),
+      gitSha: run.gitSha,
+      branch: run.ci?.branch
+    },
+    summary: {
+      requirements: requirements.length,
+      requirementsVerified: requirements.filter((r) => r.status === "verified").length,
+      requirementsFailing: requirements.filter((r) => r.status === "failing").length,
+      scenarios: run.testCases.length,
+      untracedScenarios: untraced.length
+    },
+    requirements,
+    untraced
+  };
+}
+function requirementStatus(cases) {
+  if (cases.some((tc) => tc.status === "failed")) return "failing";
+  if (cases.some((tc) => tc.status === "passed")) return "verified";
+  return "incomplete";
+}
+function renderRequirementStatus(status) {
+  switch (status) {
+    case "verified":
+      return "verified (all scenarios passed)";
+    case "failing":
+      return "failing (a scenario failed)";
+    default:
+      return "incomplete (no scenario passed yet)";
+  }
+}
+function escapePipe2(value) {
+  return value.replace(/\|/g, "\\|");
+}
+
 // src/formatters/cucumber-messages/synthesize-feature.ts
 function extractFeatureName(testCases, uri) {
   for (const tc of testCases) {
@@ -16672,60 +16818,60 @@ function buildStepArguments(step, stepLine) {
   }
   return {};
 }
-function docEntryToDocString(doc, line) {
+function docEntryToDocString(doc, line2) {
   switch (doc.kind) {
     case "code":
       return {
-        location: { line },
+        location: { line: line2 },
         mediaType: doc.lang,
         content: doc.content,
         delimiter: '"""'
       };
     case "note":
       return {
-        location: { line },
+        location: { line: line2 },
         mediaType: "text/plain",
         content: doc.text,
         delimiter: '"""'
       };
     case "section":
       return {
-        location: { line },
+        location: { line: line2 },
         mediaType: "text/markdown",
         content: doc.markdown,
         delimiter: '"""'
       };
     case "mermaid":
       return {
-        location: { line },
+        location: { line: line2 },
         mediaType: "text/x-mermaid",
         content: doc.code,
         delimiter: '"""'
       };
     case "kv":
       return {
-        location: { line },
+        location: { line: line2 },
         mediaType: "text/plain",
         content: `${doc.label}: ${typeof doc.value === "string" ? doc.value : JSON.stringify(doc.value)}`,
         delimiter: '"""'
       };
     case "link":
       return {
-        location: { line },
+        location: { line: line2 },
         mediaType: "text/markdown",
         content: `[${doc.label}](${doc.url})`,
         delimiter: '"""'
       };
     case "custom":
       return {
-        location: { line },
+        location: { line: line2 },
         mediaType: "application/json",
         content: JSON.stringify(doc.data, null, 2),
         delimiter: '"""'
       };
     case "tag":
       return {
-        location: { line },
+        location: { line: line2 },
         mediaType: "text/plain",
         content: doc.names.map((n) => `@${n}`).join(" "),
         delimiter: '"""'
@@ -16735,18 +16881,18 @@ function docEntryToDocString(doc, line) {
       return void 0;
   }
 }
-function buildDataTable(table2, line) {
+function buildDataTable(table2, line2) {
   const rows = [];
   rows.push({
-    location: { line },
+    location: { line: line2 },
     cells: table2.columns.map((col) => ({
-      location: { line },
+      location: { line: line2 },
       value: col
     })),
     id: ""
   });
   for (let r = 0; r < table2.rows.length; r++) {
-    const rowLine = line + 1 + r;
+    const rowLine = line2 + 1 + r;
     rows.push({
       location: { line: rowLine },
       cells: table2.rows[r].map((cell) => ({
@@ -16757,7 +16903,7 @@ function buildDataTable(table2, line) {
     });
   }
   return {
-    location: { line },
+    location: { line: line2 },
     rows
   };
 }
@@ -18309,17 +18455,17 @@ ${body}`;
     return humanizeSourceFile([...sourceFiles][0]) || this.title;
   }
   buildFrontmatter(run) {
-    const badge = _AstroFormatter.computeBadge(run.testCases);
+    const badge2 = _AstroFormatter.computeBadge(run.testCases);
     const count2 = run.testCases.length;
-    const description = `${count2} scenario${count2 !== 1 ? "s" : ""} \u2014 ${badge.text.toLowerCase()}`;
+    const description = `${count2} scenario${count2 !== 1 ? "s" : ""} \u2014 ${badge2.text.toLowerCase()}`;
     const lines = [
       "---",
       `title: ${yamlScalar(this.deriveTitle(run))}`,
       `description: ${description}`,
       "sidebar:",
       "  badge:",
-      `    text: ${badge.text}`,
-      `    variant: ${badge.variant}`,
+      `    text: ${badge2.text}`,
+      `    variant: ${badge2.variant}`,
       "---"
     ];
     return lines.join("\n");
@@ -18775,12 +18921,16 @@ function groupBy7(items, keyFn) {
 import * as fs5 from "fs";
 import * as path6 from "path";
 var SKIP_PREFIXES = ["http://", "https://", "data:", "#"];
-function isLocalPath(src) {
+function isRemoteRef(src) {
   const trimmed = src.trim();
-  if (SKIP_PREFIXES.some((prefix) => trimmed.startsWith(prefix))) {
-    return false;
-  }
-  return !path6.posix.isAbsolute(trimmed) && !path6.win32.isAbsolute(trimmed);
+  return SKIP_PREFIXES.some((prefix) => trimmed.startsWith(prefix));
+}
+function isAbsoluteRef(src) {
+  const trimmed = src.trim();
+  return path6.posix.isAbsolute(trimmed) || path6.win32.isAbsolute(trimmed);
+}
+function isRelativeLocalPath(src) {
+  return !isRemoteRef(src) && !isAbsoluteRef(src);
 }
 function stripCodeContent(markdown) {
   let result = markdown.replace(/^[ \t]*(`{3,}|~{3,})[^\n]*\n[\s\S]*?^[ \t]*\1\s*$/gm, "");
@@ -18796,21 +18946,21 @@ function scanMarkdownAssets(markdown) {
   let match;
   while ((match = mdImageRe.exec(stripped)) !== null) {
     const src = match[1].trim();
-    if (isLocalPath(src)) {
+    if (!isRemoteRef(src)) {
       found.add(src);
     }
   }
   const htmlSrcRe = /<(?:img|source|video)[^>]+\bsrc=["']([^"']+)["'][^>]*>/gi;
   while ((match = htmlSrcRe.exec(stripped)) !== null) {
     const src = match[1].trim();
-    if (isLocalPath(src)) {
+    if (!isRemoteRef(src)) {
       found.add(src);
     }
   }
   const posterRe = /<video[^>]+\bposter=["']([^"']+)["'][^>]*>/gi;
   while ((match = posterRe.exec(stripped)) !== null) {
     const src = match[1].trim();
-    if (isLocalPath(src)) {
+    if (!isRemoteRef(src)) {
       found.add(src);
     }
   }
@@ -18836,48 +18986,21 @@ function isCode(segment) {
   const trimmed = segment.trimStart();
   return trimmed.startsWith("`") || trimmed.startsWith("~") || trimmed.startsWith("<pre") || trimmed.startsWith("<code");
 }
+function resolveRewrite(trimmed, assetsBaseUrl, pathMap) {
+  if (isRemoteRef(trimmed)) return null;
+  if (pathMap) {
+    const mapped = pathMap.get(trimmed);
+    return mapped === void 0 ? null : `${assetsBaseUrl}/${mapped}`;
+  }
+  if (!isRelativeLocalPath(trimmed)) return null;
+  return `${assetsBaseUrl}/${trimmed}`;
+}
 function rewriteProseSegment(prose, assetsBaseUrl, pathMap) {
-  let result = prose;
-  result = result.replace(
-    /(!\[[^\]]*\]\()([^)"'\s]+)((?:\s+["'][^"']*["'])?\s*\))/g,
-    (full, pre, src, post) => {
-      const trimmed = src.trim();
-      if (!isLocalPath(trimmed)) return full;
-      if (pathMap) {
-        const mapped = pathMap.get(trimmed);
-        if (mapped === void 0) return full;
-        return `${pre}${assetsBaseUrl}/${mapped}${post}`;
-      }
-      return `${pre}${assetsBaseUrl}/${trimmed}${post}`;
-    }
-  );
-  result = result.replace(
-    /(<(?:img|source|video)[^>]+\bsrc=["'])([^"']+)(["'][^>]*>)/gi,
-    (full, pre, src, post) => {
-      const trimmed = src.trim();
-      if (!isLocalPath(trimmed)) return full;
-      if (pathMap) {
-        const mapped = pathMap.get(trimmed);
-        if (mapped === void 0) return full;
-        return `${pre}${assetsBaseUrl}/${mapped}${post}`;
-      }
-      return `${pre}${assetsBaseUrl}/${trimmed}${post}`;
-    }
-  );
-  result = result.replace(
-    /(<video[^>]+\bposter=["'])([^"']+)(["'][^>]*>)/gi,
-    (full, pre, src, post) => {
-      const trimmed = src.trim();
-      if (!isLocalPath(trimmed)) return full;
-      if (pathMap) {
-        const mapped = pathMap.get(trimmed);
-        if (mapped === void 0) return full;
-        return `${pre}${assetsBaseUrl}/${mapped}${post}`;
-      }
-      return `${pre}${assetsBaseUrl}/${trimmed}${post}`;
-    }
-  );
-  return result;
+  const rewrite = (full, pre, src, post) => {
+    const target = resolveRewrite(src.trim(), assetsBaseUrl, pathMap);
+    return target === null ? full : `${pre}${target}${post}`;
+  };
+  return prose.replace(/(!\[[^\]]*\]\()([^)"'\s]+)((?:\s+["'][^"']*["'])?\s*\))/g, rewrite).replace(/(<(?:img|source|video)[^>]+\bsrc=["'])([^"']+)(["'][^>]*>)/gi, rewrite).replace(/(<video[^>]+\bposter=["'])([^"']+)(["'][^>]*>)/gi, rewrite);
 }
 function rewriteAssetPaths(markdown, assetsBaseUrl, pathMap) {
   return splitByCode(markdown).map((seg) => isCode(seg) ? seg : rewriteProseSegment(seg, assetsBaseUrl, pathMap)).join("");
@@ -18894,8 +19017,9 @@ function copyMarkdownAssets(options) {
   const pathMap = /* @__PURE__ */ new Map();
   const missing = [];
   for (const ref of refs) {
-    const absPath = path6.resolve(markdownDir, ref);
+    const absPath = isAbsoluteRef(ref) ? ref : path6.resolve(markdownDir, ref);
     if (!fs5.existsSync(absPath)) {
+      if (isAbsoluteRef(ref)) continue;
       if (!allowMissing) {
         throw new Error(`Asset not found: ${absPath}`);
       }
@@ -18977,6 +19101,47 @@ function startWatch(options, deps = {}) {
   };
 }
 
+// src/behavior-diff.ts
+function classifyStatusChange(baseline, current) {
+  if (baseline === void 0) return "added";
+  if (current === void 0) return "removed";
+  if (baseline === current) return "unchanged";
+  if (baseline === "passed" && current === "failed") return "regressed";
+  if (baseline === "failed" && current === "passed") return "fixed";
+  return "changed";
+}
+function scenarioMap(report) {
+  const map = /* @__PURE__ */ new Map();
+  for (const feature of report.features) {
+    for (const scenario of feature.scenarios) {
+      map.set(scenario.id, { scenario, sourceFile: feature.sourceFile });
+    }
+  }
+  return map;
+}
+function diffStoryReports(baseline, current) {
+  const base = scenarioMap(baseline);
+  const curr = scenarioMap(current);
+  const ids = [.../* @__PURE__ */ new Set([...base.keys(), ...curr.keys()])];
+  const scenarios = ids.map((id) => {
+    const b = base.get(id);
+    const c = curr.get(id);
+    const kind = classifyStatusChange(b?.scenario.status, c?.scenario.status);
+    const meta = c ?? b;
+    return {
+      id,
+      title: meta.scenario.title,
+      sourceFile: meta.sourceFile,
+      kind,
+      baselineStatus: b?.scenario.status,
+      currentStatus: c?.scenario.status
+    };
+  });
+  const summary = { added: 0, removed: 0, regressed: 0, fixed: 0, changed: 0, unchanged: 0 };
+  for (const s of scenarios) summary[s.kind] += 1;
+  return { schemaVersion: "1.0", summary, scenarios };
+}
+
 // src/publishers/confluence.ts
 function parseAdf(adf) {
   let parsed;
@@ -19209,7 +19374,7 @@ async function updateDescription(issueKey, base, adf, headers, fetchFn) {
 // src/converters/ndjson-parser.ts
 function parseNdjson(ndjson) {
   const lines = ndjson.trim().split("\n").filter(Boolean);
-  const envelopes = lines.map((line) => JSON.parse(line));
+  const envelopes = lines.map((line2) => JSON.parse(line2));
   return parseEnvelopes(envelopes);
 }
 function parseEnvelopes(envelopes) {
@@ -20262,6 +20427,280 @@ function collectDocKinds(testCase) {
   return [...kinds].sort();
 }
 
+// src/scenario-failure.ts
+function failingScenarioMessage(tc) {
+  const failingStep = tc.stepResults.find((s) => s.status === "failed" && s.errorMessage);
+  return failingStep?.errorMessage ?? tc.errorMessage;
+}
+
+// src/check.ts
+var ICON_PASS = "\u2713";
+var ICON_FAIL = "\u2717";
+var ICON_SKIP = "\u2298";
+var ICON_PENDING = "\u23F3";
+var ICON_WARN = "\u26A0";
+function buildCheck(args, _deps = {}) {
+  const { testCases, baseline } = args;
+  const summary = {
+    total: testCases.length,
+    passed: testCases.filter((tc) => tc.status === "passed").length,
+    failed: testCases.filter((tc) => tc.status === "failed").length,
+    skipped: testCases.filter((tc) => tc.status === "skipped").length,
+    pending: testCases.filter((tc) => tc.status === "pending").length
+  };
+  let regressed = 0;
+  let fixed = 0;
+  if (baseline) {
+    for (const tc of testCases) {
+      const before = baseline.get(tc.id);
+      if (before === "passed" && tc.status === "failed") regressed += 1;
+      if (before === "failed" && tc.status === "passed") fixed += 1;
+    }
+  }
+  const failures = testCases.filter((tc) => tc.status === "failed").map((tc) => toFailure(tc, baseline)).sort((a, b) => {
+    if (a.regressed !== b.regressed) return a.regressed ? -1 : 1;
+    return a.location.localeCompare(b.location);
+  });
+  return {
+    summary,
+    failures,
+    regressed,
+    fixed,
+    comparedToBaseline: baseline !== void 0
+  };
+}
+function toFailure(tc, baseline) {
+  const failedIndexes = new Set(
+    tc.stepResults.filter((s) => s.status === "failed").map((s) => s.index)
+  );
+  const steps = tc.story.steps.map((step, index) => ({
+    keyword: step.keyword,
+    text: step.text,
+    failed: failedIndexes.has(index)
+  }));
+  return {
+    id: tc.id,
+    scenario: tc.story.scenario,
+    location: `${tc.sourceFile}:${tc.sourceLine}`,
+    steps,
+    errorMessage: failingScenarioMessage(tc),
+    covers: tc.story.covers ?? [],
+    tickets: (tc.story.tickets ?? []).map((t) => t.id),
+    regressed: baseline?.get(tc.id) === "passed"
+  };
+}
+function renderCheck(report, format) {
+  return format === "json" ? JSON.stringify(report, null, 2) : renderCheckText(report);
+}
+function renderCheckText(report) {
+  const { summary, failures } = report;
+  const headlineParts = [`${ICON_PASS} ${summary.passed} passed`];
+  if (summary.failed > 0) headlineParts.push(`${ICON_FAIL} ${summary.failed} failed`);
+  if (summary.skipped > 0) headlineParts.push(`${ICON_SKIP} ${summary.skipped} skipped`);
+  if (summary.pending > 0) headlineParts.push(`${ICON_PENDING} ${summary.pending} pending`);
+  const headline = `${headlineParts.join("   ")}   (${summary.total} scenarios)`;
+  if (failures.length === 0) {
+    const lines2 = [headline];
+    if (report.comparedToBaseline && report.fixed > 0) {
+      lines2.push(`${ICON_PASS} ${report.fixed} fixed since baseline.`);
+    }
+    lines2.push("All scenarios green.");
+    return lines2.join("\n");
+  }
+  const lines = [headline, ""];
+  for (const f of failures) {
+    lines.push(`${ICON_FAIL} ${f.scenario}${f.regressed ? "  (regressed)" : ""}`);
+    lines.push(`  ${f.location}`);
+    for (const step of f.steps) {
+      const marker = step.failed ? `  ${ICON_FAIL} ` : "    ";
+      lines.push(`${marker}${step.keyword} ${step.text}`);
+    }
+    if (f.errorMessage) {
+      const firstLine = f.errorMessage.split("\n")[0];
+      lines.push(`    \u2192 ${firstLine}`);
+    }
+    if (f.covers.length > 0) {
+      lines.push(`  covers: ${f.covers.join(", ")}`);
+    }
+    if (f.tickets.length > 0) {
+      lines.push(`  ticket: ${f.tickets.join(", ")}`);
+    }
+    lines.push("");
+  }
+  if (report.comparedToBaseline) {
+    if (report.regressed > 0) {
+      lines.push(`${ICON_WARN} ${report.regressed} regressed since baseline (was passing).`);
+    }
+    if (report.fixed > 0) {
+      lines.push(`${ICON_PASS} ${report.fixed} fixed since baseline.`);
+    }
+    if (report.regressed === 0 && report.fixed === 0) {
+      lines.push("No status changes vs. baseline.");
+    }
+  }
+  return lines.join("\n").trimEnd();
+}
+
+// src/goal.ts
+var ACTIVE = ["passed", "failed"];
+function buildGoal(args, _deps = {}) {
+  const { run, baseline } = args;
+  const cases = run.testCases;
+  const selectors = [
+    ...args.requireTags.map((tag) => ({ label: `tag:${tag}`, match: (tc) => tc.tags.includes(tag) })),
+    ...args.requireTickets.map((id) => ({ label: `ticket:${id}`, match: (tc) => (tc.story.tickets ?? []).some((t) => t.id === id) })),
+    ...args.requireScenarios.map((sel) => ({ label: `scenario:${sel}`, match: (tc) => tc.id === sel || tc.story.scenario === sel }))
+  ];
+  const requirements = selectors.length === 0 ? [evaluate("all scenarios", cases)] : selectors.map((s) => evaluate(s.label, cases.filter(s.match)));
+  const regressions = [];
+  if (baseline && args.enforceNoRegressions) {
+    const before = statusMap(baseline);
+    for (const tc of cases) {
+      if (before.get(tc.id) === "passed" && tc.status === "failed") {
+        regressions.push({ id: tc.id, title: tc.story.scenario });
+      }
+    }
+  }
+  const violations = [];
+  if (baseline && args.enforceRatchet) {
+    const current = new Map(cases.map((tc) => [tc.id, tc]));
+    for (const base of baseline.testCases) {
+      const now = current.get(base.id);
+      if (!now) {
+        violations.push({ id: base.id, title: base.story.scenario, kind: "removed", detail: "scenario no longer present" });
+        continue;
+      }
+      if (ACTIVE.includes(base.status) && (now.status === "skipped" || now.status === "pending")) {
+        violations.push({ id: base.id, title: base.story.scenario, kind: "disabled", detail: `${base.status} -> ${now.status}` });
+      }
+      const baseSteps = base.story.steps.length;
+      const nowSteps = now.story.steps.length;
+      if (nowSteps < baseSteps) {
+        violations.push({ id: base.id, title: base.story.scenario, kind: "weakened", detail: `${baseSteps} steps -> ${nowSteps} steps` });
+      }
+    }
+  }
+  const met = requirements.every((r) => r.met) && regressions.length === 0 && violations.length === 0;
+  return {
+    met,
+    requirements,
+    regressions,
+    regressionsEnforced: Boolean(baseline && args.enforceNoRegressions),
+    ratchet: { enforced: Boolean(baseline && args.enforceRatchet), violations }
+  };
+}
+function evaluate(selector, matched) {
+  const passed = matched.filter((tc) => tc.status === "passed").length;
+  const failing = matched.filter((tc) => tc.status !== "passed").map((tc) => tc.story.scenario);
+  return {
+    selector,
+    matched: matched.length,
+    passed,
+    failing,
+    met: matched.length > 0 && failing.length === 0
+  };
+}
+function statusMap(run) {
+  return new Map(run.testCases.map((tc) => [tc.id, tc.status]));
+}
+function renderGoal(report, format) {
+  if (format === "json") return JSON.stringify(report, null, 2);
+  const lines = [`GOAL: ${report.met ? "met" : "not met"}`];
+  for (const req of report.requirements) {
+    if (req.matched === 0) {
+      lines.push(`  ${req.selector}: no matching scenario (no proof)`);
+      continue;
+    }
+    const tail = req.failing.length > 0 ? ` (${req.failing.length} failing)` : "";
+    lines.push(`  ${req.selector}: ${req.passed}/${req.matched} scenarios pass${tail}`);
+  }
+  if (report.regressionsEnforced) {
+    if (report.regressions.length === 0) {
+      lines.push("  regressions: 0");
+    } else {
+      lines.push(`  regressions: ${report.regressions.length} (${report.regressions.map((r) => r.title).join(", ")})`);
+    }
+  }
+  if (report.ratchet.enforced) {
+    if (report.ratchet.violations.length === 0) {
+      lines.push("  ratchet: clean (0 scenarios removed/weakened)");
+    } else {
+      lines.push(`  ratchet: ${report.ratchet.violations.length} removed/weakened`);
+      for (const v of report.ratchet.violations) {
+        lines.push(`    ${v.kind}: ${v.title} (${v.detail})`);
+      }
+    }
+  }
+  return lines.join("\n");
+}
+
+// src/triage.ts
+function buildTriage(args, _deps = {}) {
+  const { testCases, baseline } = args;
+  const failing = testCases.filter((tc) => tc.status === "failed");
+  const ranked = failing.map((tc) => {
+    const regressed = baseline?.get(tc.id) === "passed";
+    return {
+      tc,
+      regressed,
+      covers: tc.story.covers ?? []
+    };
+  }).sort((a, b) => {
+    if (a.regressed !== b.regressed) return a.regressed ? -1 : 1;
+    const la = `${a.tc.sourceFile}:${a.tc.sourceLine}`;
+    const lb = `${b.tc.sourceFile}:${b.tc.sourceLine}`;
+    return la.localeCompare(lb);
+  });
+  const items = ranked.map((entry, index) => ({
+    rank: index + 1,
+    id: entry.tc.id,
+    scenario: entry.tc.story.scenario,
+    status: entry.tc.status,
+    location: `${entry.tc.sourceFile}:${entry.tc.sourceLine}`,
+    covers: entry.covers,
+    tickets: (entry.tc.story.tickets ?? []).map((t) => t.id),
+    errorMessage: failingScenarioMessage(entry.tc),
+    regressed: entry.regressed,
+    reason: entry.regressed ? "regression" : "failing"
+  }));
+  return {
+    total: testCases.length,
+    failing: failing.length,
+    regressions: items.filter((i) => i.regressed).length,
+    needsCovers: items.filter((i) => i.covers.length === 0).length,
+    items
+  };
+}
+function renderTriage(report, format) {
+  if (format === "json") return JSON.stringify(report, null, 2);
+  if (report.items.length === 0) {
+    return "Nothing to triage. No failing scenarios.";
+  }
+  const header = report.regressions > 0 ? `${report.items.length} items to triage (${report.regressions} regression${report.regressions === 1 ? "" : "s"})` : `${report.items.length} items to triage`;
+  const lines = [header, ""];
+  for (const item of report.items) {
+    const tag = item.regressed ? "[regression] " : "";
+    lines.push(`${item.rank}. ${tag}${item.scenario}`);
+    lines.push(`   ${item.location}`);
+    if (item.errorMessage) {
+      lines.push(`   \u2192 ${item.errorMessage.split("\n")[0]}`);
+    }
+    if (item.covers.length > 0) {
+      lines.push(`   fix: ${item.covers.join(", ")}`);
+    } else {
+      lines.push("   fix: (no covers declared \u2014 add `covers` to route this to code)");
+    }
+    if (item.tickets.length > 0) {
+      lines.push(`   ticket: ${item.tickets.join(", ")}`);
+    }
+    lines.push("");
+  }
+  if (report.needsCovers > 0) {
+    lines.push(`${report.needsCovers} failing scenario(s) have no covers and can't be routed to code automatically.`);
+  }
+  return lines.join("\n").trimEnd();
+}
+
 // src/review/conventions.ts
 var CHANGE_TAG_PREFIX = "change:";
 var AUDIENCE_TAG_PREFIX = "audience:";
@@ -21063,6 +21502,7 @@ var FORMAT_EXTENSIONS = {
   "behavior-manifest-json": ".behavior-manifest.json",
   markdown: ".md",
   "release-manifest": ".release-manifest.md",
+  "traceability-matrix": ".traceability-matrix.md",
   html: ".html",
   "cucumber-html": ".cucumber.html",
   junit: ".junit.xml",
@@ -21285,7 +21725,9 @@ var ReportGenerator = class {
           permalinkBaseUrl: options.astro?.markdown?.permalinkBaseUrl,
           ticketUrlTemplate: options.astro?.markdown?.ticketUrlTemplate,
           traceUrlTemplate: options.astro?.markdown?.traceUrlTemplate,
-          customRenderers: options.astro?.markdown?.customRenderers
+          customRenderers: options.astro?.markdown?.customRenderers,
+          scenarioAnchor: options.astro?.markdown?.scenarioAnchor,
+          scenarioBadge: options.astro?.markdown?.scenarioBadge
         }
       },
       assetMode: options.assetMode ?? "none",
@@ -21489,6 +21931,10 @@ var ReportGenerator = class {
         const formatter = new ReleaseManifestFormatter();
         return formatter.format(run);
       }
+      case "traceability-matrix": {
+        const formatter = new TraceabilityMatrixFormatter();
+        return formatter.format(run);
+      }
       case "story-report-json": {
         const formatter = new StoryReportJsonFormatter({
           pretty: this.options.storyReportJson.pretty
@@ -22144,6 +22590,189 @@ async function importOpenApi(options) {
 // src/build-docs.ts
 import * as fs13 from "fs";
 import * as path14 from "path";
+
+// src/scenario-links.ts
+function scenarioAnchor(title) {
+  return `scenario-${slugify(title)}`;
+}
+function buildScenarioLinks(report, options = {}) {
+  const audienceSplit = options.audienceSplit ?? false;
+  const baseUrl = (options.baseUrl ?? "/stories").replace(/\/$/, "");
+  const scenarios = {};
+  for (const feature of report.features) {
+    const stem = slugify(cleanTestStem(feature.sourceFile));
+    for (const scenario of feature.scenarios) {
+      const audience = deriveAudience(feature.sourceFile, scenario.tags);
+      const url = audienceSplit ? `${baseUrl}/${audience}/${stem}/` : `${baseUrl}/${stem}/`;
+      const anchor = scenarioAnchor(scenario.title);
+      scenarios[scenario.id] = {
+        id: scenario.id,
+        title: scenario.title,
+        audience,
+        status: scenario.status,
+        sourceFile: feature.sourceFile,
+        url,
+        anchor,
+        deepLink: `${url}#${anchor}`
+      };
+    }
+  }
+  return { schemaVersion: "1.0", runId: report.runId, baseUrl, scenarios };
+}
+
+// src/changes-page.ts
+var GROUPS = [
+  { kind: "regressed", heading: "Regressed", icon: "\u26A0\uFE0F" },
+  { kind: "removed", heading: "Removed", icon: "\u{1F5D1}\uFE0F" },
+  { kind: "added", heading: "Added", icon: "\u2728" },
+  { kind: "fixed", heading: "Fixed", icon: "\u2705" },
+  { kind: "changed", heading: "Changed", icon: "\u{1F501}" }
+];
+function yamlScalar2(value) {
+  if (/[:#[\]{}&*!|>'"%@`]|^[\s-]|\s$/.test(value)) {
+    return `'${value.replace(/'/g, "''")}'`;
+  }
+  return value;
+}
+function badge(summary) {
+  if (summary.regressed > 0 || summary.removed > 0) return { text: "Regressed", variant: "danger" };
+  if (summary.added > 0 || summary.fixed > 0 || summary.changed > 0)
+    return { text: "Updated", variant: "tip" };
+  return { text: "No changes", variant: "note" };
+}
+function line(entry, links) {
+  const link2 = links.scenarios[entry.id];
+  const label = link2 ? `[${entry.title}](${link2.deepLink})` : entry.title;
+  const transition = entry.baselineStatus && entry.currentStatus && entry.baselineStatus !== entry.currentStatus ? ` \u2014 \`${entry.baselineStatus}\` \u2192 \`${entry.currentStatus}\`` : "";
+  return `- ${label} \`${entry.sourceFile}\`${transition}`;
+}
+function renderChangesPage(diff, links) {
+  const b = badge(diff.summary);
+  const { added, removed, regressed, fixed, changed } = diff.summary;
+  const totalChanged = added + removed + regressed + fixed + changed;
+  const frontmatter = [
+    "---",
+    "title: What's changed",
+    `description: ${yamlScalar2(
+      totalChanged === 0 ? "No behavioural changes since the baseline" : `${totalChanged} scenario${totalChanged !== 1 ? "s" : ""} changed since the baseline`
+    )}`,
+    "sidebar:",
+    "  order: 0",
+    "  badge:",
+    `    text: ${b.text}`,
+    `    variant: ${b.variant}`,
+    "---"
+  ].join("\n");
+  const body = [];
+  if (totalChanged === 0) {
+    body.push("No behavioural changes since the baseline run. \u2705");
+  } else {
+    body.push(
+      `**${regressed}** regressed \xB7 **${removed}** removed \xB7 **${added}** added \xB7 **${fixed}** fixed \xB7 **${changed}** changed`,
+      ""
+    );
+    for (const group of GROUPS) {
+      const entries = diff.scenarios.filter((s) => s.kind === group.kind);
+      if (entries.length === 0) continue;
+      body.push(`## ${group.icon} ${group.heading} (${entries.length})`, "");
+      for (const entry of entries) body.push(line(entry, links));
+      body.push("");
+    }
+  }
+  return `${frontmatter}
+
+${body.join("\n")}
+`;
+}
+
+// src/overview-page.ts
+var AUDIENCE_CARDS = [
+  {
+    key: "engineer",
+    label: "Engineer",
+    icon: "\u{1F527}",
+    blurb: "Unit & integration behaviour \u2014 how the system works under the hood."
+  },
+  {
+    key: "stakeholder",
+    label: "Stakeholder",
+    icon: "\u{1F3AC}",
+    blurb: "End-to-end journeys \u2014 what the product does, with video and traces."
+  }
+];
+var STATUS_ICON = {
+  passed: "\u2705",
+  failed: "\u274C",
+  skipped: "\u23ED\uFE0F",
+  pending: "\u{1F6A7}"
+};
+function yamlScalar3(value) {
+  if (/[:#[\]{}&*!|>'"%@`]|^[\s-]|\s$/.test(value)) {
+    return `'${value.replace(/'/g, "''")}'`;
+  }
+  return value;
+}
+function renderOverviewPage(links) {
+  const all = Object.values(links.scenarios);
+  const total = all.length;
+  const passed = all.filter((s) => s.status === "passed").length;
+  const failed = all.filter((s) => s.status === "failed").length;
+  const frontmatter = [
+    "---",
+    "title: Stories",
+    `description: ${yamlScalar3(
+      `${total} scenario${total !== 1 ? "s" : ""} \u2014 ${passed} passed, ${failed} failed`
+    )}`,
+    "sidebar:",
+    "  order: 1",
+    "---"
+  ].join("\n");
+  const body = [
+    `**${total}** scenarios \xB7 **${passed}** passed \xB7 **${failed}** failed`,
+    ""
+  ];
+  for (const card of AUDIENCE_CARDS) {
+    const scenarios = all.filter((s) => s.audience === card.key);
+    if (scenarios.length === 0) continue;
+    const cardPassed = scenarios.filter((s) => s.status === "passed").length;
+    const cardFailed = scenarios.filter((s) => s.status === "failed").length;
+    const counts = cardFailed > 0 ? `${cardPassed} passed, ${cardFailed} failed` : `${cardPassed} passed`;
+    body.push(`## ${card.icon} ${card.label} (${scenarios.length} \u2014 ${counts})`, "");
+    body.push(`${card.blurb}`, "");
+    for (const s of scenariosSorted(scenarios)) {
+      body.push(`- ${STATUS_ICON[s.status] ?? "\u2022"} [${s.title}](${s.deepLink})`);
+    }
+    body.push("");
+  }
+  return `${frontmatter}
+
+${body.join("\n")}
+`;
+}
+function scenariosSorted(scenarios) {
+  return [...scenarios].sort((a, b) => {
+    const aFail = a.status === "failed" ? 0 : 1;
+    const bFail = b.status === "failed" ? 0 : 1;
+    if (aFail !== bFail) return aFail - bFail;
+    return a.title.localeCompare(b.title);
+  });
+}
+
+// src/build-docs.ts
+var AUDIENCES = ["engineer", "stakeholder"];
+function partitionByAudience(run) {
+  const buckets = {
+    engineer: [],
+    stakeholder: []
+  };
+  for (const tc of run.testCases) {
+    buckets[deriveAudience(tc.sourceFile, tc.tags)].push(tc);
+  }
+  return {
+    engineer: { ...run, testCases: buckets.engineer },
+    stakeholder: { ...run, testCases: buckets.stakeholder }
+  };
+}
 var BuildDocsError = class extends Error {
   constructor(message, kind) {
     super(message);
@@ -22185,6 +22814,40 @@ function bundleExplorerAssets(reportPath, assetsDir, baseUrl = "/stories/assets"
   }
   return copied;
 }
+var CHANGE_BADGE = {
+  added: "\u{1F195} **New** _since last run_",
+  fixed: "\u2705 **Fixed** _since last run_",
+  regressed: "\u26A0\uFE0F **Regressed** _since last run_"
+};
+function changeBadgeLookup(diff) {
+  if (!diff) return void 0;
+  const byKey = /* @__PURE__ */ new Map();
+  for (const s of diff.scenarios) {
+    const badge2 = CHANGE_BADGE[s.kind];
+    if (badge2) byKey.set(`${s.sourceFile}\0${s.title}`, badge2);
+  }
+  if (byKey.size === 0) return void 0;
+  return (tc) => byKey.get(`${tc.sourceFile}\0${tc.story.scenario}`);
+}
+function readStoryReport(reportPath) {
+  if (!fs13.existsSync(reportPath)) return null;
+  try {
+    return JSON.parse(fs13.readFileSync(reportPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function writeScenarioLinks(reportPath, outDir, options = {}) {
+  const report = readStoryReport(reportPath);
+  if (!report) return null;
+  const index = buildScenarioLinks(report, { audienceSplit: options.audienceSplit });
+  fs13.writeFileSync(
+    path14.join(outDir, "scenario-links.json"),
+    JSON.stringify(index, null, 2),
+    "utf8"
+  );
+  return index;
+}
 function clearGeneratedPages(dir) {
   if (!fs13.existsSync(dir)) return;
   for (const entry of fs13.readdirSync(dir, { withFileTypes: true })) {
@@ -22235,16 +22898,72 @@ async function buildDocs(options) {
       outputDir: storiesPublicDir,
       outputName: "story-report"
     }).generate(canonical);
+    let diff;
+    if (options.baselinePath) {
+      const baselineResolved = path14.resolve(options.baselinePath);
+      const baseline = readStoryReport(baselineResolved);
+      if (!baseline) {
+        throw new BuildDocsError(
+          `Baseline story-report not found or unreadable: ${baselineResolved}`,
+          "input"
+        );
+      }
+      const current = readStoryReport(reportPath);
+      if (current) diff = diffStoryReports(baseline, current);
+    }
+    const scenarioBadge = changeBadgeLookup(diff);
     clearGeneratedPages(storyPagesDir);
-    await new ReportGenerator({
+    const genPages = (run, outDir) => new ReportGenerator({
       formats: ["astro"],
-      outputDir: storyPagesDir,
+      outputDir: outDir,
       outputName: "index",
       output: { mode: "colocated", colocatedStyle: "flat" },
       assetMode: "copy",
-      astro: { assetsDir, assetsBaseUrl: "/stories/assets" }
-    }).generate(canonical);
+      astro: {
+        assetsDir,
+        assetsBaseUrl: "/stories/assets",
+        markdown: {
+          // Emit the same anchor scenario-links.json points at, so fragments resolve.
+          scenarioAnchor: (tc) => scenarioAnchor(tc.story.scenario),
+          scenarioBadge
+        }
+      }
+    }).generate(run);
+    const audiences = { engineer: 0, stakeholder: 0 };
+    if (options.audienceSplit ?? false) {
+      const partitioned = partitionByAudience(canonical);
+      for (const audience of AUDIENCES) {
+        const sub = partitioned[audience];
+        audiences[audience] = sub.testCases.length;
+        if (sub.testCases.length === 0) continue;
+        await genPages(sub, path14.join(storyPagesDir, audience));
+      }
+    } else {
+      await genPages(canonical, storyPagesDir);
+    }
     const bundledAssets = bundleExplorerAssets(reportPath, assetsDir);
+    const linksIndex = writeScenarioLinks(reportPath, storiesPublicDir, {
+      audienceSplit: options.audienceSplit ?? false
+    });
+    const scenarioLinks = linksIndex ? Object.keys(linksIndex.scenarios).length : 0;
+    if (linksIndex) {
+      fs13.writeFileSync(
+        path14.join(storyPagesDir, "index.md"),
+        renderOverviewPage(linksIndex),
+        "utf8"
+      );
+    }
+    const changesJsonPath = path14.join(storiesPublicDir, "changes.json");
+    const changesMdPath = path14.join(storyPagesDir, "changes.md");
+    let changes;
+    if (diff && linksIndex) {
+      fs13.writeFileSync(changesJsonPath, JSON.stringify(diff, null, 2), "utf8");
+      fs13.writeFileSync(changesMdPath, renderChangesPage(diff, linksIndex), "utf8");
+      changes = diff.summary;
+    } else {
+      fs13.rmSync(changesJsonPath, { force: true });
+      fs13.rmSync(changesMdPath, { force: true });
+    }
     let apiPages = 0;
     if (options.openapiPath) {
       const res = await importOpenApi({
@@ -22255,7 +22974,7 @@ async function buildDocs(options) {
       });
       apiPages = res.pageCount;
     }
-    return { siteDir, bundledAssets, apiPages };
+    return { siteDir, bundledAssets, apiPages, audiences, scenarioLinks, changes };
   } catch (err) {
     if (err instanceof BuildDocsError) throw err;
     throw new BuildDocsError(`Generation failed: ${err.message}`, "generation");
@@ -22286,6 +23005,7 @@ var EXIT_GENERATION = 3;
 var EXIT_USAGE = 4;
 var EXIT_COMPARE_GATE = 5;
 var EXIT_REVIEW_GATE = 5;
+var EXIT_AGENT_GATE = 5;
 var EXIT_RELEASE_GATE = 6;
 var HELP_TEXT = `
 executable-stories \u2014 Generate reports from test results JSON.
@@ -22297,6 +23017,9 @@ USAGE
   executable-stories gate-release <dev-run.json> <rc-run.json> [options]
   executable-stories review <file> --changed-files <path> [options]
   executable-stories list <file> [options]
+  executable-stories check <file> [--baseline <path|auto>] [--check-format text|json] [--no-fail]
+  executable-stories goal <file> [--require-tags <csv>] [--require-tickets <csv>] [--require-scenarios <csv>] [--baseline <path|auto>] [--no-regressions] [--goal-format text|json]
+  executable-stories triage <file> [--baseline <path|auto>] [--triage-format text|json]
   executable-stories validate <file>
   executable-stories validate --stdin
   executable-stories init-astro [directory]
@@ -22316,6 +23039,9 @@ SUBCOMMANDS
   gate-release       Verify a release candidate against the dev test baseline (RC gate)
   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)
+  check              Backpressure summary: compress passing, expand failing (GWT + error + covers); non-zero exit on failures
+  goal               Behavioral definition-of-done for agent loops: required scenarios pass, no regressions, no weakened scenarios (exit 0 = met, 5 = not)
+  triage             Discovery worklist for agent loops: failing scenarios, regressions first, each with the code it covers
   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)
   new                Scaffold a docs page from a template (adr, runbook, decision-log, incident)
@@ -22326,7 +23052,7 @@ SUBCOMMANDS
   deploy             Record deployments, show environment status, detect drift
 
 OPTIONS
-  --format <formats>            Comma-separated formats: html, markdown, release-manifest, 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)
+  --format <formats>            Comma-separated formats: html, markdown, release-manifest, traceability-matrix, 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
@@ -22338,6 +23064,7 @@ OPTIONS
                                   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
+                                  traceability-matrix Requirement-first matrix (ticket -> scenarios -> covered code -> status)
   --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)
@@ -22364,6 +23091,15 @@ OPTIONS
   --stdin                       Read JSON from stdin instead of file
   --list-format <format>        list output format: text (default), json, csv, markdown-table
   --json-summary                Deprecated alias for --list-format json
+  --check-format <format>       check output format: text (default) or json
+  --no-fail                     (check) Report only \u2014 always exit 0 even when scenarios failed
+  --require-tags <csv>          (goal) Every scenario carrying any of these tags must pass
+  --require-tickets <csv>       (goal) Every scenario carrying any of these tickets must pass
+  --require-scenarios <csv>     (goal) These scenarios (by id or exact title) must pass
+  --no-regressions              (goal) Not met if any scenario regressed vs --baseline
+  --no-ratchet                  (goal) Disable the removed/weakened-scenario guard (on by default with --baseline)
+  --goal-format <format>        goal output format: text (default) or json
+  --triage-format <format>      triage output format: text (default) or json
   --baseline <path|auto>        Compare baseline file, or auto-pick a prior run for compare
   --baseline-dir <dir>          Directory to scan when --baseline auto is used
   --pr-summary                  Print a PR-friendly markdown summary after compare
@@ -22388,6 +23124,31 @@ LIST
   list supports --include-tags, --exclude-tags for filtering
   list supports --input-type and --stdin
 
+CHECK
+  check is the inner-loop "backpressure" view for coding agents: run it after tests.
+  Passing scenarios collapse to a single count line; each failing scenario expands
+  to its Given/When/Then steps, the step that broke, the error, and the product
+  code it covers \u2014 so the agent gets an actionable signal, not a wall of green.
+  check exits 5 when any scenario failed (so the agent loop pushes back); pass
+  --no-fail to report only. --baseline <path|auto> adds "N regressed / N fixed"
+  since the prior run. --check-format json emits the structured report.
+
+GOAL
+  goal is the behavioral stopping condition for an agent loop (the /goal pattern).
+  It is "met" when the required scenarios pass, nothing regressed (with
+  --no-regressions), and no scenario was removed, disabled, or had steps deleted
+  versus --baseline (the ratchet, on by default when a baseline is given). Declare
+  the target with --require-tags / --require-tickets / --require-scenarios; with
+  none given, the goal is "every scenario passes". Exit 0 means met, 5 means not
+  yet, so a loop can run until the verdict flips. --goal-format json for machines.
+
+TRIAGE
+  triage is the discovery-phase worklist for a loop. It lists failing scenarios,
+  regressions first (with --baseline), each with the product code it covers, the
+  error, and its tickets, so the loop can route each fix to a sub-agent. Failures
+  with no covers are flagged. --triage-format json emits the work queue. triage
+  always exits 0 \u2014 it reports work, it does not gate.
+
 COMPARE
   compare supports --format html,markdown
   compare uses the same --input-type for both baseline and current files
@@ -22460,9 +23221,16 @@ EXIT CODES
   2  Canonical validation failure
   3  Formatter/generation failure
   4  Bad arguments / usage error
-  5  Compare gate failed
+  5  Compare / review / check gate failed
   6  Release gate failed
 `.trim();
+function parseTextJsonFormat(flag, value) {
+  if (value !== "text" && value !== "json") {
+    console.error(`Error: ${flag} must be "text" or "json", got "${value}".`);
+    process.exit(EXIT_USAGE);
+  }
+  return value;
+}
 async function parseCliArgs(argv) {
   const args = argv.slice(2);
   if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
@@ -22470,9 +23238,9 @@ async function parseCliArgs(argv) {
     process.exit(EXIT_SUCCESS);
   }
   const subcommand = args[0];
-  if (subcommand !== "format" && subcommand !== "watch" && subcommand !== "compare" && subcommand !== "gate-release" && subcommand !== "deploy" && subcommand !== "review" && subcommand !== "list" && subcommand !== "validate" && subcommand !== "init-astro" && subcommand !== "build-docs" && subcommand !== "new" && subcommand !== "check-links" && subcommand !== "import-openapi" && subcommand !== "publish-confluence" && subcommand !== "publish-jira") {
+  if (subcommand !== "format" && subcommand !== "watch" && subcommand !== "compare" && subcommand !== "gate-release" && subcommand !== "deploy" && subcommand !== "review" && subcommand !== "list" && subcommand !== "check" && subcommand !== "goal" && subcommand !== "triage" && subcommand !== "validate" && subcommand !== "init-astro" && subcommand !== "build-docs" && subcommand !== "new" && subcommand !== "check-links" && subcommand !== "import-openapi" && subcommand !== "publish-confluence" && subcommand !== "publish-jira") {
     console.error(
-      `Unknown subcommand: "${subcommand}". Use "format", "watch", "compare", "gate-release", "deploy", "review", "list", "validate", "init-astro", "build-docs", "new", "check-links", "import-openapi", "publish-confluence", or "publish-jira".`
+      `Unknown subcommand: "${subcommand}". Use "format", "watch", "compare", "gate-release", "deploy", "review", "list", "check", "goal", "triage", "validate", "init-astro", "build-docs", "new", "check-links", "import-openapi", "publish-confluence", or "publish-jira".`
     );
     process.exit(EXIT_USAGE);
   }
@@ -22560,6 +23328,15 @@ async function parseCliArgs(argv) {
       stdin: { type: "boolean", default: false },
       "json-summary": { type: "boolean", default: false },
       "list-format": { type: "string", default: "text" },
+      "check-format": { type: "string", default: "text" },
+      "no-fail": { type: "boolean", default: false },
+      "require-tags": { type: "string" },
+      "require-tickets": { type: "string" },
+      "require-scenarios": { type: "string" },
+      "no-regressions": { type: "boolean", default: false },
+      "no-ratchet": { type: "boolean", default: false },
+      "goal-format": { type: "string", default: "text" },
+      "triage-format": { type: "string", default: "text" },
       "emit-canonical": { type: "string" },
       "slack-webhook": { type: "string" },
       "teams-webhook": { type: "string" },
@@ -22630,7 +23407,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", "behavior-manifest-json", "confluence", "html", "markdown", "release-manifest", "junit", "cucumber-json", "cucumber-messages", "cucumber-html", "scenario-index-json", "story-report-json"]);
+  const builtInFormats = /* @__PURE__ */ new Set(["astro", "behavior-manifest-json", "confluence", "html", "markdown", "release-manifest", "traceability-matrix", "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));
@@ -22638,7 +23415,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, behavior-manifest-json, confluence, html, markdown, release-manifest, junit, cucumber-json, cucumber-messages, cucumber-html, scenario-index-json, story-report-json${knownCustom}.`);
+    console.error(`Error: Unknown format(s): ${unknownFormats.join(", ")}. Valid built-in: astro, behavior-manifest-json, confluence, html, markdown, release-manifest, traceability-matrix, junit, cucumber-json, cucumber-messages, cucumber-html, scenario-index-json, story-report-json${knownCustom}.`);
     process.exit(EXIT_USAGE);
   }
   const formats = builtInRequested;
@@ -22726,10 +23503,14 @@ async function parseCliArgs(argv) {
     console.error(`Error: --min-evidence must be "weak", "moderate", or "strong", got "${minEvidenceRaw}".`);
     process.exit(EXIT_USAGE);
   }
+  const checkFormat = parseTextJsonFormat("--check-format", values["check-format"]);
+  const goalFormat = parseTextJsonFormat("--goal-format", values["goal-format"]);
+  const triageFormat = parseTextJsonFormat("--triage-format", values["triage-format"]);
   const cliArgs = {
     subcommand,
     inputFile,
     baselineFile,
+    baselineArg: baselineValue,
     currentFile,
     baselineMode,
     baselineDir: values["baseline-dir"],
@@ -22756,6 +23537,15 @@ async function parseCliArgs(argv) {
     htmlThemePicker: values["html-theme-picker"],
     jsonSummary: values["json-summary"],
     listFormat: values["list-format"],
+    checkFormat,
+    noFail: values["no-fail"],
+    requireTags: parseGlobs(values["require-tags"]),
+    requireTickets: parseGlobs(values["require-tickets"]),
+    requireScenarios: parseGlobs(values["require-scenarios"]),
+    noRegressions: values["no-regressions"],
+    noRatchet: values["no-ratchet"],
+    goalFormat,
+    triageFormat,
     emitCanonical: values["emit-canonical"],
     slackWebhook,
     teamsWebhook,
@@ -22972,6 +23762,24 @@ function resolveBaselineAuto(currentFile, currentRun, args) {
   }
   return picked.file;
 }
+function resolveBaselineRun(args, currentRun) {
+  if (!args.baselineArg) return void 0;
+  let baselineFile;
+  if (args.baselineArg === "auto") {
+    if (!args.inputFile) {
+      console.error("Error: --baseline auto requires a current input file (not --stdin).");
+      process.exit(EXIT_USAGE);
+    }
+    baselineFile = resolveBaselineAuto(args.inputFile, currentRun, args);
+  } else {
+    baselineFile = args.baselineArg;
+  }
+  return applySelection(normalizeRunFromText(readFileInput(baselineFile), args).run, args);
+}
+function resolveBaselineStatusMap(args, currentRun) {
+  const baselineRun = resolveBaselineRun(args, currentRun);
+  return baselineRun ? new Map(baselineRun.testCases.map((tc) => [tc.id, tc.status])) : void 0;
+}
 async function main() {
   const { args, pluginConfig, customRequested } = await parseCliArgs(process.argv);
   const startMs = Date.now();
@@ -23082,6 +23890,51 @@ async function main() {
     console.log(output);
     process.exit(EXIT_SUCCESS);
   }
+  if (args.subcommand === "check") {
+    const text3 = await readInput(args);
+    const run = applySelection(normalizeRunFromText(text3, args).run, args);
+    const baseline = resolveBaselineStatusMap(args, run);
+    const report = buildCheck(
+      { testCases: run.testCases, baseline, format: args.checkFormat },
+      {}
+    );
+    console.log(renderCheck(report, args.checkFormat));
+    if (report.summary.failed > 0 && !args.noFail) {
+      process.exit(EXIT_AGENT_GATE);
+    }
+    process.exit(EXIT_SUCCESS);
+  }
+  if (args.subcommand === "goal") {
+    const text3 = await readInput(args);
+    const run = applySelection(normalizeRunFromText(text3, args).run, args);
+    const baseline = resolveBaselineRun(args, run);
+    const report = buildGoal(
+      {
+        run,
+        baseline,
+        requireTags: args.requireTags,
+        requireTickets: args.requireTickets,
+        requireScenarios: args.requireScenarios,
+        enforceNoRegressions: args.noRegressions,
+        enforceRatchet: !args.noRatchet,
+        format: args.goalFormat
+      },
+      {}
+    );
+    console.log(renderGoal(report, args.goalFormat));
+    process.exit(report.met ? EXIT_SUCCESS : EXIT_AGENT_GATE);
+  }
+  if (args.subcommand === "triage") {
+    const text3 = await readInput(args);
+    const run = applySelection(normalizeRunFromText(text3, args).run, args);
+    const baseline = resolveBaselineStatusMap(args, run);
+    const report = buildTriage(
+      { testCases: run.testCases, baseline, format: args.triageFormat },
+      {}
+    );
+    console.log(renderTriage(report, args.triageFormat));
+    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).");
@@ -23460,9 +24313,9 @@ function mapStatus(status) {
 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 line2 = raw.trim();
+    if (!line2) continue;
+    const cols = line2.includes("	") ? line2.split("	") : line2.split(/\s+/);
     const status = cols[0];
     if (!status) continue;
     const filePath = /^[RC]/i.test(status) && cols.length >= 3 ? cols[cols.length - 1] : cols[1];
@@ -23969,7 +24822,9 @@ async function runBuildDocs(rawArgs) {
     options: {
       "site-dir": { type: "string" },
       openapi: { type: "string" },
-      "no-synthesize-stories": { type: "boolean", default: false }
+      "no-synthesize-stories": { type: "boolean", default: false },
+      "audience-split": { type: "boolean", default: false },
+      baseline: { type: "string" }
     },
     allowPositionals: true,
     strict: true
@@ -23977,26 +24832,42 @@ async function runBuildDocs(rawArgs) {
   const rawRunPath = positionals[0];
   if (!rawRunPath) {
     console.error(
-      `Usage: executable-stories build-docs <raw-run.json> [--site-dir <dir>] [--openapi <spec>]`
+      `Usage: executable-stories build-docs <raw-run.json> [--site-dir <dir>] [--openapi <spec>] [--baseline <prev-story-report.json>] [--audience-split]`
     );
     return EXIT_USAGE;
   }
+  const audienceSplit = values["audience-split"];
   try {
     const result = await buildDocs({
       rawRunPath,
       siteDir: values["site-dir"] ?? ".",
       openapiPath: values.openapi,
-      synthesizeStories: !values["no-synthesize-stories"]
+      synthesizeStories: !values["no-synthesize-stories"],
+      audienceSplit,
+      baselinePath: values.baseline
     });
     console.log(`\u2713 Living docs generated in ${result.siteDir}`);
     console.log(`  \u2022 Explorer data   \u2192 public/stories/story-report.json`);
-    console.log(`  \u2022 Story pages     \u2192 src/content/docs/stories`);
+    console.log(`  \u2022 Deep links      \u2192 public/stories/scenario-links.json (${result.scenarioLinks})`);
+    if (audienceSplit) {
+      console.log(
+        `  \u2022 Story pages     \u2192 src/content/docs/stories/{engineer,stakeholder} (engineer: ${result.audiences.engineer}, stakeholder: ${result.audiences.stakeholder})`
+      );
+    } else {
+      console.log(`  \u2022 Story pages     \u2192 src/content/docs/stories`);
+    }
     if (result.bundledAssets > 0) {
       console.log(`  \u2022 Bundled assets  \u2192 public/stories/assets (${result.bundledAssets})`);
     }
     if (result.apiPages > 0) {
       console.log(`  \u2022 API pages       \u2192 src/content/docs/api (${result.apiPages})`);
     }
+    if (result.changes) {
+      const c = result.changes;
+      console.log(
+        `  \u2022 What's changed  \u2192 src/content/docs/stories/changes.md (+${c.added} added, ${c.regressed} regressed, ${c.fixed} fixed, ${c.removed} removed)`
+      );
+    }
     const rel = path15.relative(process.cwd(), result.siteDir) || ".";
     console.log(`
 Preview: cd ${rel} && npm run dev`);
@@ -24200,6 +25071,15 @@ function createDefaultCliArgs() {
     htmlThemePicker: false,
     jsonSummary: false,
     listFormat: "text",
+    checkFormat: "text",
+    noFail: false,
+    requireTags: [],
+    requireTickets: [],
+    requireScenarios: [],
+    noRegressions: false,
+    noRatchet: false,
+    goalFormat: "text",
+    triageFormat: "text",
     notify: "never",
     maxFailedTests: 5,
     maxHistoryRuns: 10,