executable-stories-formatters 0.12.0 → 0.14.0

package/dist/index.cjs

@@ -55,12 +55,16 @@ __export(src_exports, {
   STORY_REPORT_SCHEMA_VERSION: () => STORY_REPORT_SCHEMA_VERSION,
   ScenarioIndexJsonFormatter: () => ScenarioIndexJsonFormatter,
   StoryReportJsonFormatter: () => StoryReportJsonFormatter,
+  TraceabilityMatrixFormatter: () => TraceabilityMatrixFormatter,
   adaptJestRun: () => adaptJestRun,
   adaptPlaywrightRun: () => adaptPlaywrightRun,
   adaptVitestRun: () => adaptVitestRun,
   assertValidRun: () => assertValidRun,
+  buildCheck: () => buildCheck,
+  buildGoal: () => buildGoal,
   buildHtmlDocEntry: () => buildHtmlDocEntry,
   buildReview: () => buildReview,
+  buildTriage: () => buildTriage,
   bundleAssets: () => bundleAssets,
   calculateFlakiness: () => calculateFlakiness,
   calculateStability: () => calculateStability,
@@ -110,6 +114,9 @@ __export(src_exports, {
   readPackageVersion: () => readPackageVersion,
   recordDeployment: () => recordDeployment,
   regenerateArtifacts: () => regenerateArtifacts,
+  renderCheck: () => renderCheck,
+  renderGoal: () => renderGoal,
+  renderTriage: () => renderTriage,
   resolveAttachment: () => resolveAttachment,
   resolveAttachments: () => resolveAttachments,
   resolveTheme: () => resolveTheme,
@@ -131,6 +138,7 @@ __export(src_exports, {
   toReleaseManifest: () => toReleaseManifest,
   toScenarioIndex: () => toScenarioIndex,
   toStoryReport: () => toStoryReport,
+  toTraceabilityMatrix: () => toTraceabilityMatrix,
   tryGetActiveOtelContext: () => tryGetActiveOtelContext,
   updateHistory: () => updateHistory,
   validateCanonicalRun: () => validateCanonicalRun
@@ -663,14 +671,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
     };
@@ -15261,7 +15269,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
     };
   }
   /**
@@ -15448,6 +15458,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) {
@@ -15463,6 +15478,10 @@ var MarkdownFormatter = class {
       icon = this.getStatusIcon(tc.status) + " ";
     }
     lines.push(`${headingPrefix} ${icon}${tc.story.scenario}`);
+    const badge = this.options.scenarioBadge?.(tc);
+    if (badge) {
+      lines.push(badge);
+    }
     if (this.options.includeSourceLinks && this.options.permalinkBaseUrl && tc.sourceFile !== "unknown") {
       const permalink = this.buildPermalink(tc);
       lines.push(`Source: [${tc.sourceFile}](${permalink})`);
@@ -15854,6 +15873,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((path12) => `\`${path12}\``).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((path12) => `\`${path12}\``).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) {
@@ -18153,12 +18298,16 @@ function groupBy7(items, keyFn) {
 var fs5 = __toESM(require("fs"), 1);
 var path6 = __toESM(require("path"), 1);
 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, "");
@@ -18174,21 +18323,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);
     }
   }
@@ -18214,48 +18363,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("");
@@ -18272,8 +18394,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}`);
       }
@@ -20602,6 +20725,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:";
@@ -21403,6 +21800,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",
@@ -21625,7 +22023,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",
@@ -21829,6 +22229,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
@@ -21909,12 +22313,16 @@ function normalizePlaywrightResults(testResults, adapterOptions, canonicalizeOpt
   STORY_REPORT_SCHEMA_VERSION,
   ScenarioIndexJsonFormatter,
   StoryReportJsonFormatter,
+  TraceabilityMatrixFormatter,
   adaptJestRun,
   adaptPlaywrightRun,
   adaptVitestRun,
   assertValidRun,
+  buildCheck,
+  buildGoal,
   buildHtmlDocEntry,
   buildReview,
+  buildTriage,
   bundleAssets,
   calculateFlakiness,
   calculateStability,
@@ -21964,6 +22372,9 @@ function normalizePlaywrightResults(testResults, adapterOptions, canonicalizeOpt
   readPackageVersion,
   recordDeployment,
   regenerateArtifacts,
+  renderCheck,
+  renderGoal,
+  renderTriage,
   resolveAttachment,
   resolveAttachments,
   resolveTheme,
@@ -21985,6 +22396,7 @@ function normalizePlaywrightResults(testResults, adapterOptions, canonicalizeOpt
   toReleaseManifest,
   toScenarioIndex,
   toStoryReport,
+  toTraceabilityMatrix,
   tryGetActiveOtelContext,
   updateHistory,
   validateCanonicalRun