@shadowclone/cli 0.0.27 → 0.0.29

package/skills/guided-pr-review/assets/notes.mjs

@@ -0,0 +1,195 @@
+let selectedContext = null;
+let editingNote = null;
+let dragStart = null;
+
+function showReviewPanel(view) {
+  const panel = document.getElementById("notes-panel");
+  panel.dataset.view = view;
+  panel.hidden = false;
+  panel.scrollTop = 0;
+  showFindings = view === "findings";
+  document.getElementById("toggle-findings").classList.toggle("selected", showFindings);
+  renderNotes();
+}
+
+function changed() {
+  review.annotations.revision += 1;
+  dirty = true;
+  document.getElementById("save-status").textContent = "Unsaved changes";
+  try {
+    localStorage.setItem("guided-review-v2:" + review.id, JSON.stringify(review.annotations));
+  } catch {
+    document.getElementById("save-status").textContent =
+      "Unsaved changes. This browser cannot keep a recovery copy.";
+  }
+}
+
+function renderNotes() {
+  document.querySelectorAll(".inline-notes").forEach((element) => {
+    element.innerHTML = review.annotations.notes
+      .filter((note) => !note.dismissed && note.anchor === element.dataset.notesAt)
+      .map(noteMarkup)
+      .join("");
+  });
+  document.querySelectorAll(".group-findings").forEach((element) => {
+    const group = review.groups.find((group) => group.id === element.dataset.findingsFor);
+    const remaining = [];
+    for (const finding of review.pulls.flatMap((pull) => pull.findings)) {
+      if (!group.files.some((file) => file.pr === finding.pr && file.path === finding.path))
+        continue;
+      const rows = [...element.closest(".reading-step").querySelectorAll(".code-line")];
+      const row = rows.find(
+        (row) =>
+          row.dataset.file === finding.pr + ":" + finding.path &&
+          row.dataset.side === "HEAD" &&
+          Number(row.dataset.line) === finding.line,
+      );
+      if (showFindings && row && row.closest(".file-card")?.hidden !== true)
+        row.nextElementSibling.insertAdjacentHTML("beforeend", findingMarkup(finding));
+      else remaining.push(finding);
+    }
+    element.hidden = !showFindings;
+    element.innerHTML = remaining.map(findingMarkup).join("");
+  });
+  document.getElementById("note-count").textContent = review.annotations.notes.filter(
+    (note) => !note.dismissed,
+  ).length;
+  document.getElementById("notes-list").innerHTML = review.annotations.notes.length
+    ? review.annotations.notes.map(noteMarkup).join("")
+    : '<p class="muted">Select code or an explanation, then choose Comment.</p>';
+  document.getElementById("findings-heading").hidden = !showFindings;
+  document.getElementById("findings-list").innerHTML = showFindings
+    ? review.pulls
+        .flatMap((pull) => pull.findings)
+        .map(findingMarkup)
+        .join("")
+    : "";
+}
+
+function captureSelection(event) {
+  if (!document.getElementById("composer").hidden) return;
+  if (event.target.closest("#composer, #notes-panel, .note, .finding, button, textarea, select"))
+    return;
+  const selection = window.getSelection();
+  if (!selection?.rangeCount || !selection.toString().trim()) return;
+  const range = selection.getRangeAt(0);
+  const start = selection.anchorNode.parentElement;
+  const end = selection.focusNode.parentElement;
+  const card = start.closest(".file-card, .source-card, #source-dialog");
+  const rows =
+    card && end.closest(".file-card, .source-card, #source-dialog") === card
+      ? [...card.querySelectorAll(".code-line")].filter((row) =>
+          range.intersectsNode(row.querySelector("code")),
+        )
+      : [];
+  if (rows.length) selectedContext = codeContext(rows);
+  else {
+    const passage = start.closest(".passage");
+    if (!passage || end.closest(".passage") !== passage) return;
+    selectedContext = {
+      anchor: passage.dataset.anchor,
+      quote: selection.toString(),
+      ranges: [],
+      prs: passage.dataset.prs?.split(",") ?? review.pulls.map((pull) => pull.id),
+    };
+  }
+  if (!selectedContext) return;
+  const button = document.getElementById("selection-comment");
+  const dialog = start.closest("dialog");
+  (dialog ?? document.body).append(button);
+  button.hidden = false;
+  const bounds = range.getBoundingClientRect();
+  button.style.left = Math.max(12, Math.min(bounds.left, innerWidth - 110)) + "px";
+  button.style.top = Math.max(70, bounds.top - 40) + "px";
+}
+
+function openComposer(note) {
+  if (!document.getElementById("composer").hidden) return;
+  editingNote = note?.id ?? null;
+  if (note)
+    selectedContext = {
+      anchor: note.anchor,
+      quote: note.quote,
+      ranges: note.ranges,
+      prs: [note.pr],
+    };
+  if (!selectedContext) return;
+  const composer = document.getElementById("composer");
+  (document.getElementById("source-dialog").open
+    ? document.getElementById("source-dialog")
+    : document.body
+  ).append(composer);
+  document.getElementById("selection-comment").hidden = true;
+  document.getElementById("selected-quote").textContent = selectedContext.quote;
+  document.getElementById("target-pr").innerHTML =
+    (selectedContext.prs.length > 1 ? '<option value="">Choose a PR</option>' : "") +
+    selectedContext.prs
+      .map(
+        (id) =>
+          '<option value="' +
+          id +
+          '">#' +
+          review.pulls.find((pull) => pull.id === id).number +
+          "</option>",
+      )
+      .join("");
+  document.getElementById("target-label").hidden = selectedContext.prs.length === 1;
+  document.getElementById("note-body").value = note?.body ?? "";
+  composer.hidden = false;
+  document.getElementById("note-body").focus();
+}
+
+function notesAction(event) {
+  const button = event.target.closest("button");
+  if (!button) return;
+  const note = review.annotations.notes.find(
+    (note) => note.id === (button.dataset.editNote ?? button.dataset.dismissNote),
+  );
+  if (button.dataset.editNote && note) openComposer(note);
+  if (button.dataset.dismissNote && note) {
+    note.dismissed = !note.dismissed;
+    changed();
+    renderNotes();
+  }
+  const finding = button.dataset.includeFinding ?? button.dataset.dismissFinding;
+  if (finding) {
+    const state = review.annotations.decisions[finding];
+    review.annotations.decisions[finding] = button.dataset.includeFinding
+      ? state === "included"
+        ? null
+        : "included"
+      : state === "dismissed"
+        ? null
+        : "dismissed";
+    changed();
+    renderNotes();
+  }
+}
+
+function startLineSelection(event) {
+  if (!document.getElementById("composer").hidden) return;
+  if (!event.target.closest(".line-number")) return;
+  event.preventDefault();
+  dragStart = event.target.closest(".code-line");
+}
+
+function finishLineSelection(event) {
+  if (!dragStart) return;
+  const end = event.target.closest(".code-line");
+  if (
+    end &&
+    dragStart.closest(".file-card") === end.closest(".file-card") &&
+    dragStart.dataset.file === end.dataset.file
+  ) {
+    const parent = dragStart.closest(".code-lines");
+    const rows = [...parent.querySelectorAll(".code-line")];
+    const indices = [rows.indexOf(dragStart), rows.indexOf(end)].sort(
+      (first, second) => first - second,
+    );
+    selectedContext = codeContext(rows.slice(indices[0], indices[1] + 1));
+    const selectedRows = rows.slice(indices[0], indices[1] + 1);
+    rows.forEach((row) => row.classList.toggle("chosen", selectedRows.includes(row)));
+    openComposer();
+  }
+  dragStart = null;
+}

package/skills/guided-pr-review/assets/presentation.mjs

@@ -0,0 +1,180 @@
+import { escapeHtml, fileMarkup } from "../scripts/format.mjs";
+
+export const reviewStyle = String.raw`:root { color-scheme: dark; --background: #090a10; --panel: #141620; --border: #303246; --text: #e5e4ed; --muted: #9c9bae; --accent: #b6a2ee; }
+* { box-sizing: border-box; }
+[hidden] { display: none !important; }
+body { margin: 0; background: var(--background); color: var(--text); font: 15px/1.6 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+button, input, textarea, select { font: inherit; color: inherit; }
+button { cursor: pointer; border: 1px solid var(--border); border-radius: 6px; background: var(--panel); padding: 7px 12px; }
+button:hover, button.selected { border-color: var(--accent); color: var(--accent); }
+button:disabled { cursor: default; opacity: .45; }
+a, .source-link { color: var(--accent); }
+input, textarea, select { background: var(--background); border: 1px solid var(--border); border-radius: 5px; padding: 8px; }
+textarea { resize: vertical; }
+:focus-visible { outline: 2px solid var(--accent); outline-offset: 3px; }
+header { position: sticky; top: 0; z-index: 20; display: flex; align-items: center; justify-content: space-between; gap: 16px; padding: 12px 24px; background: #10121b; border-bottom: 1px solid var(--border); }
+.brand { white-space: nowrap; font-size: 14px; }
+.brand span { color: var(--accent); }
+.header-actions, .pr-tabs, .view-tabs, .file-toolbar { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; }
+.header-actions { font-size: 13px; }
+#save-review { background: var(--accent); color: var(--background); }
+#save-status { max-width: 260px; color: var(--muted); font-size: 12px; }
+.document { display: grid; grid-template-columns: 236px minmax(0, 1fr); max-width: 1440px; margin: auto; }
+.route { position: sticky; top: 64px; height: calc(100vh - 64px); overflow: auto; padding: 24px 14px; border-right: 1px solid var(--border); }
+.route h2 { margin: 0 10px 16px; color: var(--muted); font-size: 12px; letter-spacing: .08em; text-transform: uppercase; }
+.route-step { display: flex; gap: 12px; width: 100%; margin: 4px 0; padding: 12px 10px; text-align: left; border-color: transparent; background: transparent; }
+.route-step.selected { border-left: 2px solid var(--accent); background: var(--panel); }
+.route-step small { display: block; margin-top: 4px; color: var(--muted); font-size: 11px; }
+.route-footer { margin: 28px 10px; color: var(--muted); font-size: 12px; }
+main { min-width: 0; padding: 24px 40px 64px; }
+.overview { margin-bottom: 28px; }
+.overview h2 { margin: 0; font-size: 17px; }
+.overview > p { margin: 8px 0 16px; color: var(--muted); font-size: 14px; }
+.pr-tabs { margin: 16px 0; font-size: 12px; }
+.view-tabs { margin: 12px 0; }
+.view-tabs button { padding: 5px 12px; font-size: 12px; }
+.pr-details { color: var(--muted); font-size: 12px; }
+summary { cursor: pointer; }
+.pr-details p { padding-left: 18px; }
+.step-meta { display: flex; align-items: center; justify-content: space-between; color: var(--muted); font-size: 12px; }
+h1 { margin: 14px 0 18px; font-size: 27px; line-height: 1.25; }
+h3 { margin: 0 0 6px; font-size: 16px; }
+p { margin: 10px 0; }
+.why { padding-left: 14px; border-left: 2px solid var(--accent); }
+.before-after { display: grid; grid-template-columns: 1fr 1fr; gap: 14px; margin: 22px 0; }
+.before-after > div { padding: 16px; border: 1px solid var(--border); border-radius: 8px; background: var(--panel); }
+.before-after span { color: var(--muted); font-size: 11px; text-transform: uppercase; letter-spacing: .08em; }
+.before-after p { margin-bottom: 0; font-size: 14px; }
+.flow { display: flex; flex-wrap: wrap; gap: 10px; margin: 18px 0; }
+.flow > div { flex: 1; min-width: 130px; padding: 12px; border: 1px solid #554875; border-radius: 7px; font-size: 13px; }
+.flow span { color: var(--accent); }
+.flow-proof, .sources { margin: 8px 0 18px; color: var(--muted); font-size: 12px; }
+.source-link { padding: 0; border: 0; background: none; font-size: 12px; text-decoration: underline; }
+.passage { margin: 20px 0; }
+.step-files { margin: 24px 0; }
+.file-card { margin: 16px 0; border: 1px solid var(--border); border-radius: 8px; overflow: hidden; }
+.file-card > summary { display: flex; align-items: center; justify-content: space-between; gap: 12px; padding: 12px 14px; background: var(--panel); font: 12px/1.5 ui-monospace, monospace; overflow-wrap: anywhere; }
+.file-stat { flex-shrink: 0; color: var(--muted); font-size: 11px; }
+.file-stat b { color: #8fc9a5; }
+.file-toolbar { padding: 10px 14px; border-top: 1px solid var(--border); font-size: 12px; }
+.file-toolbar button { padding: 3px 10px; font-size: 12px; }
+.file-toolbar a { margin-left: auto; }
+.file-content { max-height: 540px; overflow: auto; background: #0b1011; }
+.source-card { margin: 16px 0; border: 1px solid var(--border); border-radius: 8px; overflow: hidden; }
+.source-card figcaption { padding: 10px 14px; background: var(--panel); color: var(--muted); font-size: 12px; overflow-wrap: anywhere; }
+.source-card figcaption a { float: right; margin-left: 12px; }
+.source-card .code-lines { overflow: auto; background: #0b1011; }
+.source-card .code-line { grid-template-columns: 40px 0 0 minmax(max-content, 1fr) auto; }
+.source-card .code-line > span.line-number { visibility: hidden; padding: 0; }
+.code-line { display: grid; grid-template-columns: 34px 34px 18px minmax(max-content, 1fr) auto; min-width: max-content; padding-right: 12px; font: 12px/1.8 ui-monospace, SFMono-Regular, monospace; }
+.code-line.add { background: #10251e; }
+.code-line.remove { background: #2b171c; }
+.code-line.chosen { background: #332a4b; }
+.line-number { padding: 0 6px; text-align: right; color: #76818a; border: 0; border-radius: 0; background: none; user-select: none; font: inherit; }
+.line-number:hover { color: var(--accent); }
+.sign, .owner { user-select: none; color: var(--muted); }
+.owner { padding-left: 18px; font-size: 10px; }
+.code-line code { white-space: pre; color: #c6d8d3; }
+.hunk { padding: 6px 14px; background: #181827; color: var(--muted); font: 11px ui-monospace, monospace; }
+.metadata, .markdown { margin: 0; padding: 16px; }
+.markdown pre, pre { overflow: auto; font-size: 12px; }
+code { font-family: ui-monospace, SFMono-Regular, monospace; }
+.dry-run { margin: 16px 0; padding: 14px 16px; border: 1px solid var(--border); border-radius: 7px; }
+.dry-run summary span { float: right; color: var(--muted); font-size: 11px; }
+table { width: 100%; border-collapse: collapse; font-size: 13px; }
+th, td { padding: 10px; text-align: left; vertical-align: top; border-bottom: 1px solid var(--border); }
+th { color: var(--muted); font-size: 12px; }
+.step-navigation { display: flex; justify-content: space-between; margin-top: 28px; }
+.step-navigation button { max-width: 48%; text-align: left; }
+.reading-step { scroll-margin-top: 80px; }
+.note, .finding { margin: 12px 16px; padding: 14px; border-left: 3px solid var(--accent); border-radius: 6px; background: #211b31; font-size: 13px; }
+.finding { background: #171d29; border-color: #879fc4; }
+.note-meta { display: flex; gap: 10px; align-items: center; color: var(--muted); font-size: 11px; }
+.note blockquote, .finding blockquote { margin: 8px 0; padding-left: 10px; color: var(--muted); border-left: 1px solid var(--border); white-space: pre-wrap; }
+.note-actions { display: flex; gap: 8px; margin-top: 8px; }
+.note-actions button { padding: 2px 8px; font-size: 11px; }
+.finding.dismissed { opacity: .55; }
+.finding.included { border-color: var(--accent); }
+#notes-panel { position: fixed; z-index: 40; top: 64px; right: 0; bottom: 0; width: min(460px, 100vw); overflow: auto; padding: 24px 16px; background: #10121b; border-left: 1px solid var(--border); box-shadow: -12px 0 40px #0006; }
+#notes-panel h2 { margin: 18px 14px 8px; font-size: 18px; }
+.human-notes > p { margin: 12px 14px; color: var(--muted); font-size: 13px; }
+#notes-panel[data-view="findings"] .human-notes, #notes-panel[data-view="notes"] .agent-findings { display: none; }
+#close-notes { float: right; }
+#composer { position: fixed; z-index: 60; right: 24px; top: 96px; width: min(380px, calc(100vw - 32px)); padding: 18px; border: 1px solid var(--accent); border-radius: 10px; background: var(--panel); box-shadow: 0 12px 60px #0008; }
+.composer-title { display: flex; justify-content: space-between; align-items: center; }
+#composer blockquote { max-height: 100px; overflow: auto; margin: 12px 0; padding-left: 10px; border-left: 2px solid var(--border); color: var(--muted); white-space: pre-wrap; font-size: 12px; }
+#target-label { display: flex; gap: 8px; align-items: center; font-size: 12px; }
+#composer textarea { width: 100%; min-height: 100px; margin: 12px 0; }
+#selection-comment { position: fixed; z-index: 70; background: var(--accent); color: var(--background); padding: 4px 12px; box-shadow: 0 4px 16px #0008; }
+dialog { position: fixed; width: min(820px, 90vw); max-height: 85vh; overflow: auto; padding: 24px; color: var(--text); background: var(--panel); border: 1px solid var(--border); border-radius: 8px; }
+dialog::backdrop { background: #0008; }
+dialog h2 { font-size: 17px; }
+#close-source { float: right; }
+#source-pin { color: var(--muted); font-size: 12px; }
+#source-code { white-space: pre; }
+#file-search { width: 100%; margin: 8px 0; }
+.prototype { color: #e4c486; }
+.muted { color: var(--muted); }
+@media (max-width: 760px) {
+  header { padding: 10px 14px; flex-wrap: wrap; }
+  .document { display: block; }
+  .route { position: static; display: flex; height: auto; padding: 10px; overflow: auto; border-bottom: 1px solid var(--border); }
+  .route h2, .route-footer { display: none; }
+  .route-step { min-width: 180px; }
+  main { padding: 20px 16px 40px; }
+  .before-after { grid-template-columns: 1fr; }
+  .file-card > summary { align-items: flex-start; flex-direction: column; }
+  .header-actions { gap: 6px; }
+  #composer { right: 16px; top: 128px; }
+}
+`;
+
+export function sourceExcerptMarkup(options) {
+  const { item, pulls } = options;
+  const pull = pulls.find((pull) => pull.id === item.pr);
+  const file = {
+    id: "evidence:" + item.id,
+    pr: item.pr,
+    rows: item.text.split("\n").map((text, index) => ({
+      kind: "context",
+      side: item.side,
+      text,
+      oldLine: item.start + index,
+      newLine: item.start + index,
+      owner: item.pr,
+    })),
+  };
+  return `<figure class="source-card"><figcaption>#${pull.number} · ${escapeHtml(item.path)}:${item.start} to ${item.end} · ${item.side}<a href="${escapeHtml(item.url)}" target="_blank" rel="noreferrer">Open pinned source</a></figcaption>${fileMarkup({ file, pulls, sha: { BASE: item.sha, HEAD: item.sha } })}</figure>`;
+}
+
+export function findingMarkup(finding) {
+  const state = review.annotations.decisions[finding.id];
+  const pull = review.pulls.find((pull) => pull.id === finding.pr);
+  const sourceUrl =
+    pull.url.replace(
+      /\/pull\/\d+$/,
+      "/blob/" + pull.headSha + "/" + finding.path.split("/").map(encodeURIComponent).join("/"),
+    ) +
+    "#L" +
+    finding.line;
+  const proof = finding.evidence
+    .map(
+      (item) =>
+        "<p><code>" +
+        escapeHtml(item.location) +
+        "</code></p><blockquote>" +
+        escapeHtml(item.quote) +
+        "</blockquote>",
+    )
+    .join("");
+  return `<aside class="finding ${escapeHtml(state ?? "")}" data-finding="${escapeHtml(finding.id)}"><div class="note-meta"><strong>Agent</strong><span>#${escapeHtml(pull.number)} · <a href="${escapeHtml(sourceUrl)}" target="_blank" rel="noreferrer">${escapeHtml(finding.path)}:${escapeHtml(finding.line)}</a></span><span>${state === "included" ? "in your review" : state === "dismissed" ? "dismissed" : "proposal"}</span></div><p>${escapeHtml(finding.explanation)}</p><details><summary>Inspect the reasoning</summary><p><strong>Trigger:</strong> ${escapeHtml(finding.failureScenario)}</p>${proof}<p><strong>Countercheck:</strong> ${escapeHtml(finding.refutation)}</p><p><strong>Suggested direction:</strong> ${escapeHtml(finding.suggestion ?? "Inspect the affected contract before choosing a fix.")}</p></details><div class="note-actions"><button data-include-finding="${escapeHtml(finding.id)}" type="button">${state === "included" ? "Remove from review" : "Add to my review"}</button><button data-dismiss-finding="${escapeHtml(finding.id)}" type="button">${state === "dismissed" ? "Restore" : "Dismiss"}</button></div></aside>`;
+}
+
+export function setSourceLink(options) {
+  options.element.removeAttribute("href");
+  options.element.textContent = "Source link unavailable.";
+  if (options.url.startsWith("https://")) {
+    options.element.href = options.url;
+    options.element.textContent = "Open pinned source";
+  }
+}

package/skills/guided-pr-review/assets/review.html

@@ -0,0 +1,18 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{{TITLE}}</title>
+    <style>
+      {{STYLE}}
+    </style>
+  </head>
+  <body>
+    {{BODY}}
+    <script type="application/json" id="review-data">
+      {{DATA}}
+    </script>
+    <script type="module" id="review-runtime"></script>
+  </body>
+</html>

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;
+}