@shadowclone/skills 0.0.0-stage → 0.0.30

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

@@ -0,0 +1,199 @@
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { ancestor, patchRows } from "./check.mjs";
+
+function fileKey(options) {
+  return options.pr + ":" + options.path;
+}
+
+function git(options) {
+  const result = spawnSync(
+    "git",
+    ["--literal-pathspecs", "-C", options.checkout, ...options.arguments],
+    {
+      encoding: "utf8",
+      maxBuffer: 64 * 1024 * 1024,
+    },
+  );
+  if (result.error) throw result.error;
+  if (result.status !== 0)
+    throw new Error("Git evidence failed: " + result.stderr.trim().slice(0, 400));
+  return result.stdout;
+}
+
+export function source(options) {
+  const result = spawnSync(
+    "git",
+    ["-C", options.checkout, "show", options.sha + ":" + options.path],
+    { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 },
+  );
+  if (result.status !== 0) {
+    const exists = spawnSync("git", [
+      "-C",
+      options.checkout,
+      "cat-file",
+      "-e",
+      options.sha + ":" + options.path,
+    ]);
+    if (exists.status === 1 || exists.status === 128) return null;
+    throw new Error("A committed source file could not be read.");
+  }
+  return result.stdout.includes("\0") ? null : result.stdout;
+}
+
+function filesAt(options) {
+  const names = git({
+    checkout: options.checkout,
+    arguments: ["diff", "--name-status", "-z", "--find-renames", options.base, options.head],
+  }).split("\0");
+  const files = [];
+  while (names.length && names[0]) {
+    const status = names.shift();
+    const oldPath = names.shift();
+    const path = /^[RC]/.test(status) ? names.shift() : oldPath;
+    const patch = git({
+      checkout: options.checkout,
+      arguments: [
+        "diff",
+        "--no-color",
+        "--no-ext-diff",
+        "--no-textconv",
+        "--find-renames",
+        "--unified=5",
+        options.base,
+        options.head,
+        "--",
+        ...new Set([oldPath, path]),
+      ],
+    });
+    const rows = patchRows(patch).map((row) => ({ ...row, owner: options.pr }));
+    const isMarkdown = /\.(md|mdx|markdown)$/i.test(path);
+    files.push({
+      id: fileKey({ pr: options.pr, path }),
+      pr: options.pr,
+      path,
+      diffAnchor: "diff-" + createHash("sha256").update(path).digest("hex"),
+      oldPath,
+      status,
+      rows,
+      patch: rows.length ? null : patch,
+      additions: rows.filter((row) => row.kind === "add").length,
+      deletions: rows.filter((row) => row.kind === "remove").length,
+      baseMarkdown: isMarkdown ? source({ ...options, sha: options.base, path: oldPath }) : null,
+      headMarkdown: isMarkdown ? source({ ...options, sha: options.head, path }) : null,
+    });
+  }
+  return files;
+}
+
+function addedOwners(options) {
+  const text = git({
+    checkout: options.checkout,
+    arguments: ["blame", "--line-porcelain", options.head, "--", options.path],
+  });
+  const owners = new Map();
+  let line = 0;
+  let commit = "";
+  for (const value of text.split("\n")) {
+    const header = /^([a-f0-9]{40}) \d+ (\d+)/.exec(value);
+    if (header) {
+      commit = header[1];
+      line = Number(header[2]);
+    }
+    if (value.startsWith("\t"))
+      owners.set(line, options.pulls.find((pull) => pull.commits.has(commit))?.id ?? "context");
+  }
+  return owners;
+}
+
+export async function collectReview(input) {
+  const pulls = [];
+  for (const pull of input.pulls) {
+    for (const sha of [pull.baseSha, pull.headSha])
+      git({ checkout: pull.checkout, arguments: ["cat-file", "-e", sha + "^{commit}"] });
+    const mergeBaseSha = git({
+      checkout: pull.checkout,
+      arguments: ["merge-base", pull.baseSha, pull.headSha],
+    }).trim();
+    const files = filesAt({
+      checkout: pull.checkout,
+      base: mergeBaseSha,
+      head: pull.headSha,
+      pr: pull.id,
+    });
+    const { checkout, reviewFile, ...publicPull } = pull;
+    pulls.push({
+      ...publicPull,
+      mergeBaseSha,
+      files,
+      findings: [],
+      skippedPaths: [],
+    });
+  }
+  let combined = null;
+  const endpoint =
+    input.pulls.length > 1 &&
+    input.pulls.find((candidate) =>
+      input.pulls.every(
+        (pull) =>
+          pull.repository === candidate.repository &&
+          ancestor({ checkout: candidate.checkout, base: pull.headSha, head: candidate.headSha }),
+      ),
+    );
+  if (endpoint) {
+    const baseSha = git({
+      checkout: endpoint.checkout,
+      arguments: ["merge-base", "--octopus", ...pulls.map((pull) => pull.mergeBaseSha)],
+    }).trim();
+    const ordered = [...pulls].sort((first, second) =>
+      ancestor({ checkout: endpoint.checkout, base: first.headSha, head: second.headSha }) ? -1 : 1,
+    );
+    const ownership = ordered.map((pull) => ({
+      ...pull,
+      commits: new Set(
+        git({
+          checkout: endpoint.checkout,
+          arguments: ["rev-list", pull.headSha, "^" + pull.mergeBaseSha],
+        })
+          .trim()
+          .split("\n"),
+      ),
+    }));
+    const files = filesAt({
+      checkout: endpoint.checkout,
+      base: baseSha,
+      head: endpoint.headSha,
+      pr: "stack",
+    });
+    for (const file of files) {
+      const owners = file.rows.some((row) => row.newLine !== null)
+        ? addedOwners({
+            checkout: endpoint.checkout,
+            head: endpoint.headSha,
+            path: file.path,
+            pulls: ownership,
+          })
+        : new Map();
+      for (const row of file.rows) {
+        if (row.kind === "add") row.owner = owners.get(row.newLine) ?? "context";
+        else if (row.kind === "remove")
+          row.owner =
+            ordered
+              .filter((pull) =>
+                pull.files.some(
+                  (entry) =>
+                    entry.oldPath === file.oldPath &&
+                    entry.rows.some(
+                      (removed) => removed.kind === "remove" && removed.text === row.text,
+                    ),
+                ),
+              )
+              .map((pull) => pull.id)
+              .join(",") || "stack";
+        else row.owner = "context";
+      }
+    }
+    combined = { baseSha, headSha: endpoint.headSha, files };
+  }
+  return { pulls, combined };
+}

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

@@ -0,0 +1,195 @@
+import { readFile } from "node:fs/promises";
+import {
+  reviewStyle,
+  findingMarkup,
+  setSourceLink,
+  sourceExcerptMarkup,
+} from "../assets/presentation.mjs";
+import { escapeHtml, jsonForHtml, markdown, fileCard, behaviorMarkup } from "./format.mjs";
+
+function sourceLinks(options) {
+  return [...new Set(options.ids)]
+    .map((id) => {
+      const item = options.review.evidence.find((item) => item.id === id);
+      return (
+        '<button class="source-link" data-evidence="' +
+        id +
+        '" type="button" title="' +
+        escapeHtml(item.path) +
+        '">' +
+        escapeHtml(item.label ?? item.path.split("/").pop() + ":" + item.start) +
+        "</button>"
+      );
+    })
+    .join(" ");
+}
+
+function groupMarkup(options) {
+  const { group, review, index } = options;
+  const numbers = group.prs
+    .map((id) => "#" + review.pulls.find((pull) => pull.id === id).number)
+    .join(" + ");
+  const placedPaths = new Set();
+  const { flow, dryRuns } = behaviorMarkup({
+    group,
+    sources: (ids) => sourceLinks({ review, ids }),
+  });
+  const fileSlots = (paths) =>
+    [...new Set(paths)]
+      .filter((path) => !placedPaths.has(path))
+      .map((path) => {
+        placedPaths.add(path);
+        const related = group.files.filter((item) => item.path === path);
+        const combinedFile = review.combined?.files.find((file) => file.path === path);
+        const combinedCard = combinedFile
+          ? fileCard({
+              file: combinedFile,
+              open: true,
+              prLabel: "Combined stack",
+              url: review.pulls.find((pull) => pull.id === related.at(-1).pr).url,
+            })
+          : "";
+        const cards = related
+          .map((item) => {
+            const pull = review.pulls.find((pull) => pull.id === item.pr);
+            return fileCard({
+              file: pull.files.find((file) => file.path === path),
+              open: true,
+              prLabel: "#" + pull.number,
+              url: pull.url,
+            });
+          })
+          .join("");
+        return (
+          '<div class="file-slot" data-path="' +
+          escapeHtml(path) +
+          '" data-prs="' +
+          related.map((item) => item.pr).join(",") +
+          '">' +
+          combinedCard +
+          cards +
+          "</div>"
+        );
+      })
+      .join("");
+  const passages = group.steps
+    .map((step, stepIndex) => {
+      const files =
+        step.files ??
+        (step.evidence ?? [])
+          .map((id) => review.evidence.find((item) => item.id === id))
+          .filter((item) =>
+            group.files.some((file) => file.pr === item.pr && file.path === item.path),
+          );
+      const definitions = (step.definitions ?? [])
+        .map((id) =>
+          sourceExcerptMarkup({
+            item: review.evidence.find((item) => item.id === id),
+            pulls: review.pulls,
+          }),
+        )
+        .join("");
+      return `<section class="passage" data-anchor="${group.id}:passage:${stepIndex}" data-prs="${group.prs.join(",")}"><h3>${escapeHtml(step.title)}</h3>${markdown(step.text)}${definitions}<div class="sources">${sourceLinks({ review, ids: step.evidence ?? [] })}</div><div class="inline-notes" data-notes-at="${group.id}:passage:${stepIndex}"></div></section>${fileSlots(files.map((file) => file.path))}`;
+    })
+    .join("");
+  const remaining = fileSlots(group.files.map((file) => file.path));
+  return `<article class="reading-step" id="step-${group.id}" data-group="${group.id}" ${index ? "hidden" : ""}><div class="step-meta"><span>Step ${index + 1} of ${review.groups.length} · ${numbers}</span><label><input type="checkbox" data-reviewed="${group.id}"> Reviewed</label></div><h1>${escapeHtml(group.title)}</h1><div class="passage" data-anchor="${group.id}:summary" data-prs="${group.prs.join(",")}">${markdown(group.summary)}<div class="inline-notes" data-notes-at="${group.id}:summary"></div></div><p class="why">${escapeHtml(group.why)}</p><div class="before-after"><div><span>Before</span><p>${escapeHtml(group.before)}</p></div><div><span>After</span><p>${escapeHtml(group.after)}</p></div></div>${flow}${passages}${remaining ? '<div class="step-files"><h3>Remaining file changes</h3>' + remaining + "</div>" : ""}<div class="group-findings" data-findings-for="${group.id}"></div>${dryRuns}</article>`;
+}
+
+export async function renderReview(review) {
+  const asset = async (name) => readFile(new URL("../assets/" + name, import.meta.url), "utf8");
+  const count = review.pulls.reduce((total, pull) => total + pull.files.length, 0);
+  const findings = review.pulls.reduce((total, pull) => total + pull.findings.length, 0);
+  const prTabs =
+    review.pulls.length > 1
+      ? '<div class="pr-tabs">' +
+        (review.combined ? '<button data-pr="stack" type="button">Combined stack</button>' : "") +
+        review.pulls
+          .map(
+            (pull) =>
+              '<button data-pr="' +
+              pull.id +
+              '" type="button">#' +
+              pull.number +
+              " " +
+              escapeHtml(pull.title) +
+              "</button>",
+          )
+          .join("") +
+        "</div>"
+      : "";
+  const sidebar =
+    '<aside class="route"><h2>Reading route</h2>' +
+    review.groups
+      .map(
+        (group, index) =>
+          '<button class="route-step" data-step="' +
+          index +
+          '" type="button"><span>' +
+          (index + 1) +
+          "</span><span>" +
+          escapeHtml(group.title) +
+          "<small>" +
+          group.prs
+            .map((id) => "#" + review.pulls.find((pull) => pull.id === id).number)
+            .join(" + ") +
+          " · " +
+          group.files.length +
+          " file changes</small></span></button>",
+      )
+      .join("") +
+    '<div class="route-footer">' +
+    count +
+    " file changes across " +
+    review.pulls.length +
+    " PR" +
+    (review.pulls.length === 1 ? "" : "s") +
+    "<p>Read the code. Make your own notes. Then compare the agent findings.</p></div></aside>";
+  const ci = review.pulls
+    .map((pull) => {
+      const counts = new Map();
+      for (const check of pull.ci ?? [])
+        counts.set(
+          check.conclusion ?? check.state ?? "pending",
+          (counts.get(check.conclusion ?? check.state ?? "pending") ?? 0) + 1,
+        );
+      return (
+        '<p><a href="' +
+        escapeHtml(pull.url) +
+        '" target="_blank" rel="noreferrer">#' +
+        pull.number +
+        " " +
+        escapeHtml(pull.title) +
+        "</a><br><code>" +
+        pull.headSha.slice(0, 10) +
+        "</code> · " +
+        pull.files.length +
+        " files · " +
+        [...counts].map(([status, total]) => total + " " + status.toLowerCase()).join(", ") +
+        "</p>"
+      );
+    })
+    .join("");
+  const body = `<header><strong class="brand">◇ shadowclone <span>/ guided review</span></strong><div class="header-actions"><button id="toggle-findings" type="button">Agent findings <span>${findings}</span></button><button id="toggle-notes" type="button">Your notes <span id="note-count">0</span></button><button id="save-review" type="button">Save review</button><span id="save-status" role="status">Saved HTML</span></div></header><div class="document">${sidebar}<main><div class="overview"><h2>${escapeHtml(review.title)}</h2>${markdown(review.summary)}${review.status === "prototype" ? '<p class="prototype">Prototype: one part of the reading route. The full file inventory remains available.</p>' : ""}${prTabs}<div class="view-tabs"><button data-mode="guide" type="button">Guide</button><button data-mode="files" type="button">All changes (${count})</button></div><details class="pr-details"><summary>PR details and CI</summary>${ci}</details></div><div id="guide">${review.groups.map((group, index) => groupMarkup({ group, review, index })).join("")}<nav class="step-navigation"><button id="previous" type="button">Previous</button><button id="next" type="button">Next</button></nav></div><section id="files" hidden><h1>Every changed file</h1><p>These are the actual per-PR changes, including files outside the main reading step.</p><input id="file-search" type="search" placeholder="Find a file" aria-label="Find a changed file"><div id="file-list"></div></section></main></div><aside id="notes-panel" hidden><button id="close-notes" type="button">Close</button><section class="human-notes"><h2>Your review notes</h2><p>Save this HTML, then attach it to your chat and request staging.</p><div id="notes-list"></div></section><section class="agent-findings"><h2 id="findings-heading" hidden>Agent findings</h2><div id="findings-list"></div></section></aside><aside id="composer" hidden><form id="note-form"><div class="composer-title"><strong>Your note</strong><button id="cancel-note" type="button" aria-label="Cancel note">×</button></div><blockquote id="selected-quote"></blockquote><label id="target-label">Post on <select id="target-pr"></select></label><textarea id="note-body" aria-label="Your rough note" placeholder="Write the concern or question in your words." required></textarea><button type="submit">Save note</button></form></aside><button id="selection-comment" type="button" hidden>Comment</button><dialog id="source-dialog"><button id="close-source" type="button">Close</button><h2 id="source-title"></h2><p id="source-pin"></p><pre><code id="source-code"></code></pre><a id="source-link" target="_blank" rel="noreferrer">Open pinned source</a></dialog>`;
+  const format = (await readFile(new URL("./format.mjs", import.meta.url), "utf8")).replace(
+    /^export /gm,
+    "",
+  );
+  const scripts = [
+    format,
+    findingMarkup.toString(),
+    setSourceLink.toString(),
+    ...(await Promise.all(["document.mjs", "notes.mjs", "guide.mjs"].map(asset))),
+  ]
+    .map((script) => script.replace(/^export /gm, ""))
+    .join("\n");
+  return (await asset("review.html"))
+    .replace("{{TITLE}}", () => escapeHtml(review.title))
+    .replace("{{STYLE}}", () => reviewStyle)
+    .replace("{{BODY}}", () => body)
+    .replace("{{DATA}}", () => jsonForHtml(review))
+    .replace(
+      '<script type="module" id="review-runtime"></script>',
+      () => '<script type="module" id="review-runtime">' + scripts + "</script>",
+    );
+}

package/skills/plan-with-review-page/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: plan-with-review-page
+description: 'Use before a change that touches many files, needs many steps, or has open design choices. Also use it when the user says "plan this first", "what is your approach?", or "do not code yet". Explores the code read-only, asks one round of decisions with the recommended option first, and writes one plan. Builds a self-contained HTML review page from a template, and checks the page with a validator. Not for checking finished work (use `verify-and-review`).'
+metadata:
+  shadowclone-category: workflow
+  shadowclone-section: workflow
+  shadowclone-applies-when: before a change that has many steps or open design choices
+---
+# Plan With a Review Page
+
+## Use when
+
+A change touches many files, needs many steps, or has a design choice that belongs to the user. An approved plan stops work in the wrong direction. A small and clear change does not need this skill.
+
+## Gates
+
+1. Are you read-only until the user approves? Before approval, write only the plan file and the review page.
+2. Did you read the code, the documents, and the history before you asked? Never ask what the code can answer.
+3. Did you ask one round of at most 4 questions, each with 2 to 4 options and the recommended option first?
+4. Is each risky behavior choice in that round, such as a skip, a block, a fallback, or a default?
+5. Is there one plan file for this conversation, with each skipped step still visible and its reason?
+6. Does the review page pass `scripts/validate-page.mjs` with 0 errors?
+
+## Process
+
+### Explore
+
+1. Read the code that the request touches, and the instructions of the repository for that code.
+2. Find the functions and patterns that the change can use again.
+
+### Ask
+
+1. List each open decision about scope, behavior, edge cases, data, release, and tests.
+2. Ask the decisions in one round of at most 4 questions. Put the recommended option first, with one reason.
+3. If an answer is not clear, ask again. Do not guess.
+
+### Write
+
+1. Put the plan at `/tmp/agent-artifacts/<repo>/<date>-<slug>/plan.md`. If the sandbox blocks `/tmp`, use the temporary folder of the agent.
+2. Write the context, the decisions with their source, the approach, the files, the steps, and the verification commands.
+3. Copy `assets/review-page.html` to the same folder as `index.html`. Edit only the JSON block with the id `plan`, and replace each value that starts with `TEMPLATE:`.
+4. Add Mermaid source in `diagram` when the change has more than two parts. The page shows the source as text, and draws it when the pinned Mermaid file loads.
+5. Run `node scripts/validate-page.mjs <page>`. If Node is not available, run the script with `bun`. Fix each error.
+6. Give the user both paths, the approach, and the main risk. Wait for approval.
+
+### Execute
+
+1. Do the steps in order. After each step, update its status in the page and in the plan.
+2. If a fact changes a decision, stop. Update the plan, and ask again.
+3. Keep a step that you skip in the list, with the status `skipped` and the reason in its note.
+
+## Example
+
+**Situation:** The user asks for a sync command that updates installed skills. Some installed copies contain edits that the user made.
+**Easy route:** Plan to replace each copy with the new version, and do not ask.
+**Hidden cost:** The plan hides a choice that deletes the work of the user. The user finds the loss after the release.
+**Best route:** Put the choice in the question round: keep each edited copy and list it (recommended), or replace it and save a backup. Record the answer in the plan.
+**Evidence:** The decision table of the page shows "Edited copies: keep and list" with the source "user". The validator printed "validate-page: 0 errors in 1 file".
+
+## Guardrails
+
+- Approval covers only the steps in the plan. Ask before a step that the plan does not list.
+- Never commit the plan or the review page to a repository.
+- Keep the review page self-contained. Do not add scripts, styles, or fonts from the network.
+- Do not open a decision again unless a new fact changes it.
+- Keep the plan short enough to scan. Write the recommended approach, not each option that you considered.
+
+## Completion
+
+- The plan path and the review page path.
+- The validator command and its result line.
+- The question round, with the recommended option first in each question.
+- Each step with its status, and each skipped step with its reason.

package/skills/plan-with-review-page/assets/review-page.html

@@ -0,0 +1,160 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Plan review</title>
+<style>
+:root {
+  --page: #fbfaf7; --text: #1d1d1b; --muted: #66645f; --card: #ffffff; --line: #e2dfd8;
+  --done: #2f7d4f; --doing: #a8701c; --todo: #77756f; --blocked: #b5443b; --skipped: #6d5fa8;
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --page: #161615; --text: #ecebe7; --muted: #a09e98; --card: #1f1f1d; --line: #34332f;
+    --done: #5fbf83; --doing: #e0a84a; --todo: #8f8c85; --blocked: #e57b72; --skipped: #a99be8;
+  }
+}
+* { box-sizing: border-box; }
+body { margin: 0; background: var(--page); color: var(--text); font: 15px/1.55 system-ui, sans-serif; }
+main { max-width: 960px; margin: 0 auto; padding: 32px 16px 64px; }
+h1 { font-size: 24px; margin: 0 0 6px; }
+h2 { font-size: 17px; margin: 28px 0 10px; }
+.meta { color: var(--muted); margin: 0 0 18px; }
+.card { background: var(--card); border: 1px solid var(--line); border-radius: 10px; padding: 14px 16px; }
+.counts { display: grid; grid-template-columns: repeat(auto-fit, minmax(150px, 1fr)); gap: 10px; }
+.counts b { display: block; font-size: 22px; }
+.counts span { color: var(--muted); font-size: 13px; }
+ol.steps { list-style: none; margin: 0; padding: 0; }
+ol.steps li { display: grid; grid-template-columns: 84px 1fr; gap: 12px; padding: 9px 0; border-bottom: 1px solid var(--line); }
+ol.steps li:last-child { border-bottom: 0; }
+.status { font-size: 12px; font-weight: 600; letter-spacing: 0.04em; text-transform: uppercase; }
+.done { color: var(--done); } .doing { color: var(--doing); } .todo { color: var(--todo); }
+.blocked { color: var(--blocked); } .skipped { color: var(--skipped); }
+.note { display: block; color: var(--muted); font-size: 13px; }
+.scroll { overflow-x: auto; }
+table { width: 100%; border-collapse: collapse; font-size: 14px; }
+th, td { text-align: left; vertical-align: top; padding: 7px 8px; border-bottom: 1px solid var(--line); }
+th { color: var(--muted); font-weight: 600; }
+code, pre { font: 13px ui-monospace, SFMono-Regular, Menlo, monospace; }
+pre { white-space: pre-wrap; margin: 0; }
+#diagram img { display: block; max-width: 100%; height: auto; margin-bottom: 10px; }
+</style>
+</head>
+<body>
+<main>
+  <h1 id="title"></h1>
+  <p id="goal"></p>
+  <p class="meta">Plan file: <code id="plan-path"></code>. Updated: <span id="updated"></span>.</p>
+  <div class="counts">
+    <div class="card"><b id="count-done">0</b><span>steps done</span></div>
+    <div class="card"><b id="count-left">0</b><span>steps left</span></div>
+    <div class="card"><b id="count-open">0</b><span>open questions</span></div>
+  </div>
+  <section id="diagram-section" hidden>
+    <h2>Diagram</h2>
+    <div class="card scroll">
+      <div id="diagram"></div>
+      <p class="note" id="diagram-note">The diagram shows as source text until the pinned Mermaid file loads.</p>
+      <pre id="diagram-source"></pre>
+    </div>
+  </section>
+  <h2>Steps</h2>
+  <div class="card"><ol class="steps" id="steps"></ol></div>
+  <h2>Decisions</h2>
+  <div class="card scroll">
+    <table>
+      <thead><tr><th>Question</th><th>Answer</th><th>Source</th></tr></thead>
+      <tbody id="decisions"></tbody>
+    </table>
+  </div>
+  <h2>Open questions</h2>
+  <div class="card"><ul id="open"></ul></div>
+</main>
+<script type="application/json" id="plan">
+{
+  "title": "TEMPLATE: A short name for the change",
+  "goal": "TEMPLATE: One sentence about the result that the user wants.",
+  "planPath": "TEMPLATE: The absolute path of the plan file",
+  "updated": "TEMPLATE: The date and time of this update",
+  "steps": [
+    { "status": "done", "text": "TEMPLATE: Read the code that the request touches.", "note": "" },
+    { "status": "doing", "text": "TEMPLATE: Ask one round of decisions.", "note": "" },
+    { "status": "todo", "text": "TEMPLATE: Write the plan and this page.", "note": "" },
+    { "status": "skipped", "text": "TEMPLATE: A step that you skipped.", "note": "TEMPLATE: The reason for the skip." }
+  ],
+  "decisions": [
+    { "question": "TEMPLATE: A decision that the user made.", "answer": "TEMPLATE: The answer.", "source": "user" }
+  ],
+  "open": ["TEMPLATE: A question that is still open."],
+  "diagram": "flowchart LR\n  Request --> Plan --> Approval --> Steps"
+}
+</script>
+<script>
+const plan = JSON.parse(document.getElementById("plan").textContent);
+const element = (name, text, className) => {
+  const node = document.createElement(name);
+  node.textContent = text;
+  if (className) node.className = className;
+  return node;
+};
+
+document.title = plan.title;
+document.getElementById("title").textContent = plan.title;
+document.getElementById("goal").textContent = plan.goal;
+document.getElementById("plan-path").textContent = plan.planPath;
+document.getElementById("updated").textContent = plan.updated;
+document.getElementById("count-done").textContent = plan.steps.filter((step) => step.status === "done").length;
+document.getElementById("count-left").textContent = plan.steps.filter((step) => step.status !== "done" && step.status !== "skipped").length;
+document.getElementById("count-open").textContent = plan.open.length;
+
+for (const step of plan.steps) {
+  const item = document.createElement("li");
+  const body = element("div", step.text);
+  if (step.note) body.append(element("span", step.note, "note"));
+  item.append(element("span", step.status, `status ${step.status}`), body);
+  document.getElementById("steps").append(item);
+}
+
+for (const decision of plan.decisions) {
+  const row = document.createElement("tr");
+  row.append(element("td", decision.question), element("td", decision.answer), element("td", decision.source));
+  document.getElementById("decisions").append(row);
+}
+
+for (const question of plan.open) {
+  document.getElementById("open").append(element("li", question));
+}
+
+if (plan.diagram) {
+  document.getElementById("diagram-section").hidden = false;
+  document.getElementById("diagram-source").textContent = plan.diagram;
+
+  const script = document.createElement("script");
+  script.src = "https://cdn.jsdelivr.net/npm/mermaid@12.1.0/dist/mermaid.min.js";
+  script.integrity = "sha384-EbBpjO7rlR6eqZEcG7GaPpyk9H9WrMyPWX4d3KvPYltgt8Z8l0z6R56B1qP40pR4";
+  script.crossOrigin = "anonymous";
+  script.onload = async () => {
+    const dark = window.matchMedia("(prefers-color-scheme: dark)").matches;
+    window.mermaid.initialize({
+      startOnLoad: false,
+      securityLevel: "strict",
+      htmlLabels: false,
+      flowchart: { htmlLabels: false },
+      theme: dark ? "dark" : "default",
+    });
+    const { svg } = await window.mermaid.render("plan-diagram", plan.diagram);
+    const image = document.createElement("img");
+    image.alt = "Plan diagram";
+    image.src = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;
+    document.getElementById("diagram").replaceChildren(image);
+    document.getElementById("diagram-note").textContent = "Diagram source:";
+  };
+  script.onerror = () => {
+    document.getElementById("diagram-note").textContent = "Mermaid did not load, so the diagram shows as source text.";
+  };
+  document.head.append(script);
+}
+</script>
+</body>
+</html>