@shadowclone/skills 0.0.0-stage → 0.0.30

package/skills/guided-pr-review/references/report.md

@@ -0,0 +1,118 @@
+# Report contract
+
+Create UTF-8 JSON outside the public checkout. The builder reads only pinned Git objects and local review results.
+It refuses an existing output file. It collects all per-PR diffs and verifies every quoted excerpt.
+
+## Input
+
+Use these fields:
+
+```json
+{
+  "title": "Review the job retry",
+  "summary": "Follow the result and notification through failures.",
+  "pulls": [
+    {
+      "id": "pr-1",
+      "repository": "example/project",
+      "number": 1,
+      "url": "<PR HTTPS URL>",
+      "title": "Retry the job",
+      "checkout": "<private local checkout>",
+      "baseSha": "<full SHA>",
+      "headSha": "<full SHA>",
+      "reviewFile": "<private local shadowclone-review JSON>",
+      "ci": []
+    }
+  ],
+  "evidence": [
+    {
+      "id": "retry-boundary",
+      "pr": "pr-1",
+      "path": "src/job.ts",
+      "side": "HEAD",
+      "start": 12,
+      "end": 14,
+      "quote": "<exact committed source>"
+    }
+  ],
+  "groups": [
+    {
+      "id": "job",
+      "title": "Follow the retry boundary",
+      "prs": ["pr-1"],
+      "summary": "The callback now repeats after a failure.",
+      "why": "A retry can repeat completed writes.",
+      "before": "One attempt.",
+      "after": "Up to three attempts.",
+      "files": [{ "pr": "pr-1", "path": "src/job.ts" }],
+      "evidence": ["retry-boundary"],
+      "steps": [
+        {
+          "title": "Read the callback",
+          "text": "<plain Markdown explanation>",
+          "evidence": ["retry-boundary"],
+          "definitions": ["retry-boundary"],
+          "files": [{ "pr": "pr-1", "path": "src/job.ts" }]
+        }
+      ],
+      "diagram": { "nodes": [], "edges": [] },
+      "dryRuns": []
+    }
+  ]
+}
+```
+
+Local reviewer JSON contains pull.repository, pull.baseSha, pull.headSha, findings, and skippedPaths.
+The stock CLI produces those fields. A host-agent review records the same pins and its actual investigation output.
+Findings retain the stock path, line, severity, explanation, failureScenario, evidence, suggestion, and refutation fields.
+Do not copy benchmark findings into another PR. Do not rewrite their claims while building the document.
+
+CI entries use name and conclusion. They become short status counts, not a badge wall.
+Markdown explanations escape raw HTML. The actual Markdown diff and rendered base and head remain inspectable.
+
+Order passages by behavior. Define the main contract before showing its callers, effects, and supporting changes.
+steps.definitions lists evidence identifiers for signature excerpts shown beside the explanation.
+steps.files orders the actual diffs after that passage. Each file must belong to the group's files list.
+Without steps.files, the builder follows changed files in steps.evidence order.
+The group's remaining files follow its main passages. Every file starts expanded and links to its exact PR diff.
+
+## Complete coverage
+
+Every changed PR/file pair must appear in groups.files. Repeating a file across related groups does not inflate totals.
+The builder rejects missing files for a complete guide. Generated artifacts and tests need an explained supporting group.
+If you did not examine a file, say so in that group's explanation. Listing its diff does not establish investigation.
+Use status=prototype only for a clearly labeled early UX check. Never present that artifact as the complete review.
+
+The builder derives each PR's merge base. It derives a combined head only when one supplied revision contains every requested head.
+Combined added lines use Git blame and the PR commit ranges for ownership.
+If removed text occurs in several PRs, its label names those possible owners. Inspect the per-PR patches before staging.
+Per-PR views remain authoritative for exact reviewer-visible anchors.
+
+## Visuals and dry runs
+
+A diagram node has id, label, and evidence identifiers.
+An edge has from, to, label, and evidence identifiers.
+Every node and transition needs committed evidence. Keep labels short; put citations behind the source disclosure.
+
+A dry run has title, kind (reasoned or executed), input, steps, and outcome.
+Each step has condition, state, effect, outcome, and evidence identifiers.
+An executed run also explains its command, fixture boundary, and observed output in the surrounding text.
+Never promote a source trace into an executed result.
+
+## Saved annotations
+
+The output embeds one application/json script named review-data, with version=2 and a stable document id.
+It contains the pinned facts, local findings, route, code evidence, and annotations.
+Read this data block without executing the HTML's scripts when staging.
+
+annotations contains notes, decisions, reviewed group identifiers, and a revision number.
+A human note contains id, pr, anchor, quote, ranges, body, originalBody, and dismissed.
+A source range contains path, side, start, end, and sha. Mixed diff selections can contain several source ranges.
+Prose notes have an empty ranges array. The staging workflow resolves them to current changed lines.
+decisions maps finding identifiers to included, dismissed, or null.
+Preserve removed notes and dismissed findings as inactive records. They must not reappear in a staged review.
+
+Save review requests a handle to the original HTML. It checks document identity and the prior annotation state before writing.
+It updates the embedded JSON only and preserves the document's remaining text.
+The original file, not browser storage or a separate JSON export, carries the portable review.

package/skills/guided-pr-review/scripts/build.mjs

@@ -0,0 +1,117 @@
+import { createHash } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+import { collectReview, source } from "./git.mjs";
+import { checkInput, checkCoverage } from "./check.mjs";
+import { renderReview } from "./render.mjs";
+
+try {
+  const [inputPath, outputPath] = process.argv.slice(2);
+  if (!inputPath || !outputPath) throw new Error("Usage: build.mjs <input.json> <review.html>");
+  const input = JSON.parse(await readFile(inputPath, "utf8"));
+  checkInput(input);
+  const { pulls, combined } = await collectReview(input);
+  for (const pull of input.pulls) {
+    const review = pull.reviewFile ? JSON.parse(await readFile(pull.reviewFile, "utf8")) : null;
+    if (
+      review &&
+      (review.pull?.headSha !== pull.headSha ||
+        review.pull?.baseSha !== pull.baseSha ||
+        review.pull?.repository !== pull.repository)
+    )
+      throw new Error("The local findings do not match the pinned PR.");
+    const result = pulls.find((entry) => entry.id === pull.id);
+    result.findings = (review?.findings ?? []).map((finding, index) => ({
+      ...finding,
+      id: pull.id + "-finding-" + index,
+      pr: pull.id,
+    }));
+    result.skippedPaths = review?.skippedPaths ?? [];
+  }
+  const evidence = input.evidence.map((item) => {
+    const pull = input.pulls.find((pull) => pull.id === item.pr);
+    const sha =
+      item.side === "BASE"
+        ? pulls.find((entry) => entry.id === pull.id).mergeBaseSha
+        : pull.headSha;
+    const text = source({ checkout: pull.checkout, sha, path: item.path })
+      ?.split("\n")
+      .slice(item.start - 1, item.end)
+      .join("\n");
+    if (text === undefined || text !== item.quote)
+      throw new Error("Source evidence does not match: " + item.path + ":" + item.start);
+    return {
+      ...item,
+      sha,
+      text,
+      url:
+        pull.url.replace(
+          /\/pull\/\d+$/,
+          "/blob/" + sha + "/" + item.path.split("/").map(encodeURIComponent).join("/"),
+        ) +
+        "#L" +
+        item.start,
+    };
+  });
+  const groups = input.groups.map((group) => {
+    const paths = [
+      ...group.steps.flatMap((step) =>
+        (
+          step.files ?? (step.evidence ?? []).map((id) => evidence.find((item) => item.id === id))
+        ).map((file) => file.path),
+      ),
+      ...group.files.map((file) => file.path),
+    ];
+    return {
+      ...group,
+      files: [...group.files].sort(
+        (first, second) => paths.indexOf(first.path) - paths.indexOf(second.path),
+      ),
+    };
+  });
+  const id = createHash("sha256")
+    .update(
+      JSON.stringify({
+        pins: pulls.map((pull) => [pull.repository, pull.number, pull.baseSha, pull.headSha]),
+        title: input.title,
+        groups: input.groups,
+        evidence,
+      }),
+    )
+    .digest("hex");
+  const review = {
+    version: 2,
+    id,
+    title: input.title,
+    summary: input.summary,
+    status: input.status ?? "complete",
+    pulls,
+    groups,
+    fileOrder: [
+      ...new Set([
+        ...groups.flatMap((group) => group.files.map((file) => file.pr + ":" + file.path)),
+        ...pulls.flatMap((pull) => pull.files.map((file) => file.id)),
+      ]),
+    ],
+    evidence,
+    combined,
+    annotations: { notes: [], decisions: {}, reviewed: [], revision: 0 },
+  };
+  const coverage = checkCoverage(review);
+  await writeFile(outputPath, await renderReview(review), { flag: "wx", mode: 0o600 });
+  console.log(
+    "build: " +
+      review.pulls.length +
+      " PRs, " +
+      review.groups.length +
+      " reading steps, " +
+      coverage.covered +
+      "/" +
+      coverage.total +
+      " changed files, " +
+      review.pulls.reduce((count, pull) => count + pull.findings.length, 0) +
+      " local findings",
+  );
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}

package/skills/guided-pr-review/scripts/check.mjs

@@ -0,0 +1,193 @@
+import { spawnSync } from "node:child_process";
+import { readFile } from "node:fs/promises";
+
+function requireText(value, label) {
+  if (typeof value !== "string" || !value.trim()) throw new Error(label + " must contain text.");
+}
+
+function unique(items, label) {
+  const values = new Set();
+  for (const item of items) {
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(item.id) || values.has(item.id))
+      throw new Error("Invalid or duplicate " + label + " id.");
+    values.add(item.id);
+  }
+  return values;
+}
+
+export function checkInput(input) {
+  requireText(input.title, "Review title");
+  if (
+    !Array.isArray(input.pulls) ||
+    !input.pulls.length ||
+    !Array.isArray(input.groups) ||
+    !input.groups.length ||
+    !Array.isArray(input.evidence)
+  )
+    throw new Error("The guide needs PRs, reading groups, and evidence.");
+  const pullIds = unique(input.pulls, "PR");
+  const evidenceIds = unique(input.evidence, "evidence");
+  unique(input.groups, "group");
+  for (const pull of input.pulls) {
+    if (![pull.baseSha, pull.headSha].every((sha) => /^[a-f0-9]{40}$/.test(sha)))
+      throw new Error("Pin each PR's full base and head SHA.");
+    if (
+      !/^[\w.-]+\/[\w.-]+$/.test(pull.repository) ||
+      !Number.isInteger(pull.number) ||
+      pull.number < 1
+    )
+      throw new Error("Each PR needs its repository and number.");
+    const url = new URL(pull.url);
+    if (
+      url.protocol !== "https:" ||
+      url.pathname !== "/" + pull.repository + "/pull/" + pull.number
+    )
+      throw new Error("The PR URL does not match its scope.");
+  }
+  for (const evidence of input.evidence) {
+    if (
+      !pullIds.has(evidence.pr) ||
+      !["BASE", "HEAD"].includes(evidence.side) ||
+      !Number.isInteger(evidence.start) ||
+      !Number.isInteger(evidence.end) ||
+      evidence.start < 1 ||
+      evidence.end < evidence.start ||
+      evidence.end - evidence.start > 100
+    )
+      throw new Error("Evidence needs a PR, side, and bounded source range.");
+    if (
+      typeof evidence.path !== "string" ||
+      evidence.path.startsWith("/") ||
+      evidence.path.split("/").some((part) => part === ".." || part === ".") ||
+      evidence.path.includes("\0")
+    )
+      throw new Error("Evidence paths must stay inside the repository.");
+    requireText(evidence.quote, "Evidence quote");
+  }
+  for (const group of input.groups) {
+    requireText(group.title, "Reading step");
+    requireText(group.summary, "Step explanation");
+    if (!Array.isArray(group.files) || !Array.isArray(group.steps))
+      throw new Error("Each reading step needs files and passages.");
+    for (const file of group.files)
+      if (!pullIds.has(file.pr)) throw new Error("A file refers to another PR.");
+    for (const file of group.steps.flatMap((step) => step.files ?? []))
+      if (!group.files.some((entry) => entry.pr === file.pr && entry.path === file.path))
+        throw new Error("A passage file must belong to its reading group.");
+    const references = [
+      ...(group.evidence ?? []),
+      ...group.steps.flatMap((step) => [...(step.evidence ?? []), ...(step.definitions ?? [])]),
+      ...(group.diagram?.nodes ?? []).flatMap((node) => node.evidence ?? []),
+      ...(group.diagram?.edges ?? []).flatMap((edge) => edge.evidence ?? []),
+      ...(group.dryRuns ?? []).flatMap((run) => run.steps.flatMap((step) => step.evidence ?? [])),
+    ];
+    if (references.some((id) => !evidenceIds.has(id)))
+      throw new Error("A passage or visual refers to missing evidence.");
+    for (const node of group.diagram?.nodes ?? [])
+      if (!node.evidence?.length) throw new Error("Every diagram node needs code evidence.");
+    for (const edge of group.diagram?.edges ?? [])
+      if (!edge.evidence?.length) throw new Error("Every diagram transition needs code evidence.");
+  }
+}
+
+export function checkCoverage(review) {
+  const files = new Set(review.pulls.flatMap((pull) => pull.files.map((file) => file.id)));
+  const covered = new Set(
+    review.groups.flatMap((group) => group.files.map((file) => file.pr + ":" + file.path)),
+  );
+  for (const key of covered)
+    if (!files.has(key)) throw new Error("A reading step refers to an unchanged file: " + key);
+  const missing = [...files].filter((key) => !covered.has(key));
+  if (missing.length && review.status !== "prototype")
+    throw new Error(
+      "The reading route omits " + missing.length + " changed files:\n" + missing.join("\n"),
+    );
+  return { total: files.size, covered: files.size - missing.length, missing };
+}
+
+export function readReviewData(html) {
+  const match = /<script type="application\/json" id="review-data">([\s\S]*?)<\/script>/.exec(html);
+  if (!match) throw new Error("The HTML has no embedded review data.");
+  const review = JSON.parse(match[1]);
+  if (review.version !== 2 || !/^[a-f0-9]{64}$/.test(review.id))
+    throw new Error("The review format or document identity is invalid.");
+  const ids = new Set(review.pulls.map((pull) => pull.id));
+  if (!Array.isArray(review.annotations?.notes))
+    throw new Error("The review annotations are invalid.");
+  for (const note of review.annotations.notes) {
+    if (
+      !ids.has(note.pr) ||
+      typeof note.id !== "string" ||
+      typeof note.body !== "string" ||
+      typeof note.quote !== "string" ||
+      typeof note.anchor !== "string" ||
+      !Array.isArray(note.ranges)
+    )
+      throw new Error("An annotation has invalid text or source references.");
+  }
+  checkCoverage(review);
+  return review;
+}
+
+if (process.argv[1] && import.meta.url === new URL(process.argv[1], "file:").href) {
+  try {
+    const html = await readFile(process.argv[2], "utf8");
+    const review = readReviewData(html);
+    if (/<script[^>]+src=|<link[^>]+href=https?:/i.test(html))
+      throw new Error("The review contains remote runtime assets.");
+    const coverage = checkCoverage(review);
+    console.log(
+      "check: " +
+        review.pulls.length +
+        " PRs, " +
+        coverage.covered +
+        "/" +
+        coverage.total +
+        " files in the route, " +
+        review.annotations.notes.length +
+        " human notes",
+    );
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}
+
+export function ancestor(options) {
+  const result = spawnSync("git", [
+    "-C",
+    options.checkout,
+    "merge-base",
+    "--is-ancestor",
+    options.base,
+    options.head,
+  ]);
+  if (result.status !== 0 && result.status !== 1)
+    throw new Error("Git ancestry could not be established.");
+  return result.status === 0;
+}
+
+export function patchRows(patch) {
+  const rows = [];
+  let oldLine = 0;
+  let newLine = 0;
+  let active = false;
+  for (const line of patch.split("\n")) {
+    const hunk = /^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(line);
+    if (hunk) {
+      oldLine = Number(hunk[1]);
+      newLine = Number(hunk[2]);
+      active = true;
+      rows.push({ kind: "hunk", text: line, oldLine: null, newLine: null });
+    } else if (active && /^[ +\-]/.test(line)) {
+      const kind = line[0] === "+" ? "add" : line[0] === "-" ? "remove" : "context";
+      rows.push({
+        kind,
+        text: line.slice(1),
+        oldLine: kind === "add" ? null : oldLine++,
+        newLine: kind === "remove" ? null : newLine++,
+      });
+    }
+  }
+  return rows;
+}

package/skills/guided-pr-review/scripts/format.mjs

@@ -0,0 +1,198 @@
+export function escapeHtml(value) {
+  return String(value).replace(
+    /[&<>"']/g,
+    (character) =>
+      ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[character],
+  );
+}
+
+export function jsonForHtml(value) {
+  return JSON.stringify(value)
+    .replace(/</g, "\\u003c")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+}
+
+export function markdown(value) {
+  const inline = (text) =>
+    escapeHtml(text)
+      .replace(/`([^`]+)`/g, "<code>$1</code>")
+      .replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>")
+      .replace(/\*([^*]+)\*/g, "<em>$1</em>")
+      .replace(
+        /\[([^\]]+)\]\((https?:\/\/[^\s)]+|#[^\s)]+)\)/g,
+        '<a href="$2" target="_blank" rel="noreferrer">$1</a>',
+      );
+  let fenced = false;
+  let list = false;
+  let table = false;
+  const output = [];
+  for (const line of String(value ?? "").split("\n")) {
+    if (table && !line.startsWith("|")) {
+      output.push("</table>");
+      table = false;
+    }
+    if (line.startsWith("```")) {
+      if (list) {
+        output.push("</ul>");
+        list = false;
+      }
+      output.push(fenced ? "</code></pre>" : "<pre><code>");
+      fenced = !fenced;
+    } else if (fenced) output.push(escapeHtml(line) + "\n");
+    else if (line.startsWith("|")) {
+      if (!table) {
+        output.push("<table>");
+        table = true;
+      }
+      if (!/^\|[\s:|-]+\|$/.test(line))
+        output.push(
+          "<tr>" +
+            line
+              .split("|")
+              .slice(1, -1)
+              .map((cell) => "<td>" + inline(cell.trim()) + "</td>")
+              .join("") +
+            "</tr>",
+        );
+    } else if (/^[-*] /.test(line)) {
+      if (!list) {
+        output.push("<ul>");
+        list = true;
+      }
+      output.push("<li>" + inline(line.slice(2)) + "</li>");
+    } else {
+      if (list) {
+        output.push("</ul>");
+        list = false;
+      }
+      const heading = /^(#{1,6}) (.*)$/.exec(line);
+      if (heading)
+        output.push(
+          "<h" + heading[1].length + ">" + inline(heading[2]) + "</h" + heading[1].length + ">",
+        );
+      else if (line.trim()) output.push("<p>" + inline(line) + "</p>");
+    }
+  }
+  if (fenced) output.push("</code></pre>");
+  if (table) output.push("</table>");
+  if (list) output.push("</ul>");
+  return output.join("");
+}
+
+export function fileMarkup(options) {
+  const { file, view = "diff", pulls, sha } = options;
+  if (view !== "diff") {
+    const text = view === "base" ? file.baseMarkdown : file.headMarkdown;
+    const prs =
+      file.pr === "stack"
+        ? pulls
+            .filter((pull) => pull.files.some((item) => item.path === file.path))
+            .map((pull) => pull.id)
+        : [file.pr];
+    const anchor = escapeHtml(file.id + ":" + view);
+    return text === null
+      ? '<p class="muted">This side has no Markdown file.</p>'
+      : `<div class="markdown passage" data-anchor="${anchor}" data-prs="${escapeHtml(prs.join(","))}">${markdown(text)}<div class="inline-notes" data-notes-at="${anchor}"></div></div>`;
+  }
+  if (!file.rows.length)
+    return (
+      '<pre class="metadata">' +
+      escapeHtml(file.patch || "No net change at the stack head. Inspect the per-PR diff.") +
+      "</pre>"
+    );
+  return (
+    '<div class="code-lines">' +
+    file.rows
+      .map((row, index) => {
+        if (row.kind === "hunk") return '<div class="hunk">' + escapeHtml(row.text) + "</div>";
+        const side = row.side ?? (row.kind === "remove" ? "BASE" : "HEAD");
+        const line = side === "BASE" ? row.oldLine : row.newLine;
+        const owners = row.owner
+          .split(",")
+          .map((id) => pulls.find((pull) => pull.id === id))
+          .filter(Boolean);
+        const owner = pulls.length > 1 ? owners.map((pull) => "#" + pull.number).join(" + ") : "";
+        return `<div class="code-line ${escapeHtml(row.kind)}" data-anchor="${escapeHtml(file.id + ":" + index)}" data-file="${escapeHtml(file.id)}" data-side="${escapeHtml(side)}" data-line="${escapeHtml(line)}" data-sha="${escapeHtml(sha[side])}" data-owner="${escapeHtml(row.owner)}"><button class="line-number" type="button" aria-label="Select line ${escapeHtml(line)}">${escapeHtml(row.oldLine ?? "")}</button><span class="line-number">${escapeHtml(row.newLine ?? "")}</span><span class="sign">${row.kind === "add" ? "+" : row.kind === "remove" ? "-" : ""}</span><code>${escapeHtml(row.text)}</code><span class="owner">${escapeHtml(owner)}</span></div><div class="inline-notes" data-notes-at="${escapeHtml(file.id + ":" + index)}"></div>`;
+      })
+      .join("") +
+    "</div>"
+  );
+}
+
+export function fileCard(options) {
+  const url = new URL(options.url);
+  url.pathname += "/files";
+  url.search = "";
+  url.hash = options.file.diffAnchor;
+  return `<details class="file-card" data-file="${escapeHtml(options.file.id)}" ${options.open ? "open" : ""}><summary><span>${escapeHtml(options.file.path)}</span><span class="file-stat">${escapeHtml(options.prLabel)} <b>+${escapeHtml(options.file.additions)}</b> / -${escapeHtml(options.file.deletions)}</span></summary><div class="file-toolbar"><button data-view="diff" class="selected" type="button">Diff</button>${options.file.baseMarkdown !== null || options.file.headMarkdown !== null ? '<button data-view="base" type="button">Base Markdown</button><button data-view="head" type="button">Head Markdown</button>' : ""}<a href="${escapeHtml(url.href)}" target="_blank" rel="noreferrer">Open file in PR</a></div><div class="file-content"></div></details>`;
+}
+
+export function noteMarkup(note) {
+  const pull = review.pulls.find((pull) => pull.id === note.pr);
+  return `<aside class="note ${note.dismissed ? "dismissed" : ""}" data-note="${escapeHtml(note.id)}"><div class="note-meta"><strong>You</strong><span>#${escapeHtml(pull.number)} · ${note.dismissed ? "removed" : "draft"}</span></div><blockquote>${escapeHtml(note.quote)}</blockquote><p>${escapeHtml(note.body)}</p><div class="note-actions"><button data-edit-note="${escapeHtml(note.id)}" type="button">Edit</button><button data-dismiss-note="${escapeHtml(note.id)}" type="button">${note.dismissed ? "Restore" : "Remove"}</button></div></aside>`;
+}
+
+export function behaviorMarkup(options) {
+  const { group, sources } = options;
+  const nodes = group.diagram?.nodes ?? [];
+  const flow = nodes.length
+    ? '<div class="flow">' +
+      nodes
+        .map(
+          (node, nodeIndex) =>
+            "<div><strong>" +
+            escapeHtml(node.label) +
+            "</strong>" +
+            (nodeIndex < nodes.length - 1 ? '<span aria-hidden="true"> →</span>' : "") +
+            "</div>",
+        )
+        .join("") +
+      '</div><details class="flow-proof"><summary>Follow the branches and source</summary>' +
+      (group.diagram.edges ?? [])
+        .map(
+          (edge) =>
+            "<p>" +
+            escapeHtml(nodes.find((node) => node.id === edge.from)?.label ?? edge.from) +
+            " → " +
+            escapeHtml(nodes.find((node) => node.id === edge.to)?.label ?? edge.to) +
+            ": " +
+            escapeHtml(edge.label) +
+            " " +
+            sources(edge.evidence) +
+            "</p>",
+        )
+        .join("") +
+      "</details>"
+    : "";
+  const dryRuns = (group.dryRuns ?? [])
+    .map(
+      (run) =>
+        '<details class="dry-run"><summary>' +
+        escapeHtml(run.title) +
+        "<span>" +
+        escapeHtml(run.kind ?? "reasoned") +
+        "</span></summary><p>" +
+        escapeHtml(run.input) +
+        "</p><table><thead><tr><th>Branch</th><th>State</th><th>Effect and outcome</th></tr></thead><tbody>" +
+        run.steps
+          .map(
+            (step) =>
+              "<tr><td>" +
+              escapeHtml(step.condition ?? step.when ?? step.branch) +
+              "</td><td>" +
+              escapeHtml(step.state) +
+              "</td><td>" +
+              escapeHtml((step.effect ?? step.effects ?? "") + " " + (step.outcome ?? "")) +
+              " " +
+              sources(step.evidence ?? []) +
+              "</td></tr>",
+          )
+          .join("") +
+        "</tbody></table><p>" +
+        escapeHtml(run.outcome) +
+        "</p></details>",
+    )
+    .join("");
+  return { flow, dryRuns };
+}