@shadowclone/cli 0.0.17 → 0.0.18

package/skills/choose-by-consequence/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: choose-by-consequence
+description: 'Use when code must decide what happens on an unusual or failing path. Also use it when the user says "just handle that case", "skip it if it fails", or "is this the best way?". Compares the easy route with each alternative by what it does to the user''s files, data, and output. Picks the option that fails loudly and keeps every count and exit code true. Never writes through a file that the change does not own. Not for checking finished work against the real command output (use `verify-and-review`).'
+metadata:
+  shadowclone-category: change-control
+  shadowclone-section: workflow
+  shadowclone-applies-when: when a change adds a skip, block, fallback, default, or retry
+---
+# Choose by Consequence
+
+## Use when
+
+The code must decide what happens when something is unusual or fails. Examples: a file is a symbolic link, a tool is missing, or a step times out. Each of these is a behavior choice. A choice is risky when it touches owned or shared files, data, security, or public behavior such as output and exit codes.
+
+## Gates
+
+1. For each option, can you say what the user sees and what happens to their files and data? If not, check before you choose.
+2. While you plan, did you give each risky choice to the user as an open decision? Put the option that fails loudly first.
+3. While you execute, did you pick the option that fails loudly? A skip is loud only when the summary counts it, the final output names it, and the exit code shows it.
+4. Do all counts, totals, and statuses in the output still match what happened?
+5. Does any write go through a file that the change does not own, such as a symbolic link target? If so, block, and name both paths.
+6. Does the handoff list each choice with the real output line that shows it?
+
+## Process
+
+### While you plan
+
+1. List the options. Usual options: do the full job safely, block with an error, skip with a visible line, ask, or fall back.
+2. For each option, write its hidden cost: who finds the problem, when, and what the recovery costs.
+3. Put each risky choice to the user as one question with 2 to 4 options. Put the option that fails loudly first, and give one reason for it.
+
+### While you execute
+
+1. Do not ask again about a choice that the user made while planning. Follow it.
+2. For a new choice, act without asking. Pick the first option that applies:
+   - Do the full job safely.
+   - Block with a message that names the file, the cause, and the next action.
+   - Skip with a counted line at the end of the output, and a nonzero exit code.
+3. Never use a silent fallback. A fallback is acceptable only when the output names it and the result is still correct.
+4. Write the message that the user reads before you write the code that prints it.
+5. Run the real command, and read the summary line, the final lines, and the exit code.
+6. Write down each choice and its output line for the handoff.
+
+## Example
+
+**Situation:** A setup command installs guidance for several agents. The instruction file of one agent is a symbolic link to a file that other tools share.
+**Easy route:** Skip that agent, print the skip in the middle of the output, and report success.
+**Hidden cost:** The summary still said "Installed for 2 agents". The user believed that the setup installed the agent, and nothing told them that the shared file was left alone.
+**Best route:** Do not write through the link. Count the agent as not installed. End the output with a line that names the agent and the link target. Exit with a nonzero code.
+**Evidence:** The last line is "Not installed for codex: its AGENTS.md is a symbolic link to a shared file". The summary says "Installed for 1 agent", and the exit code is 1.
+
+## Guardrails
+
+- Never write through a symbolic link, a shared file, or a file that another tool owns. Block, and name both paths.
+- Do not catch an error only to continue. Catch it to add context, then report it.
+- Do not change a default that people rely on without a line in the output and in the handoff.
+- Make each error message specific: the path, the cause, and one next action. "Something went wrong" is not a message.
+- Keep the decision in one place. A second copy of the same check drifts, and then the two paths disagree.
+
+## Completion
+
+- Each risky choice in one line: the option that you picked and the hidden cost that it avoids.
+- The command that you ran and the output line that shows each skip, block, or fallback.
+- The exit code of that command.
+- The summary or count line, checked against what happened.
+- The `file:line` of each new block, skip, or fallback.

package/skills/design-deep-modules/SKILL.md

@@ -1,34 +1,51 @@
 ---
 name: design-deep-modules
-description: Design or improve a module so callers get substantial behavior through a small stable interface. Use when choosing seams, reducing orchestration in callers, or making a subsystem easier to test and change.
+description: 'Use when designing or reshaping a module, or when callers coordinate too many steps. Also use it when the user says "this is hard to test", "callers know too much", or "simplify this interface". Puts related state and decisions behind a small interface that states what the caller wants. Tests then use that interface instead of the internal steps. Not for typing values at a boundary (use `typescript-type-safety`).'
 metadata:
   shadowclone-category: architecture
   shadowclone-section: engineering
-  shadowclone-applies-when: designing or reshaping a module or subsystem
+  shadowclone-applies-when: when designing or reshaping a module or subsystem
 ---
 # Design Deep Modules
 
 ## Use when
 
-Callers coordinate too many steps, an abstraction only forwards arguments, or tests must reach through layers to observe behavior. A deep module provides substantial behavior through a small interface.
+Callers repeat the same sequence of calls, a layer only forwards arguments, or tests must reach through layers to see behavior. A deep module gives callers a lot of behavior through a small interface.
+
+## Gates
+
+1. Can each caller state its intent in one call, without knowing the internal order of steps?
+2. Does one owner hold each piece of related state and each decision about it?
+3. Does each new layer serve a real variation or isolation need, not only forwarding?
+4. Do the tests use the public interface, and replace dependencies only at outside boundaries?
+5. Are the invariants and the error behavior part of the interface contract?
 
 ## Process
 
-1. Read the callers and identify the state, ordering, and policy they currently coordinate.
-2. Put related state and decisions under one owner. Define an operation that expresses the caller's intent.
-3. When the boundary is unclear, compare two placements by caller burden, error handling, and testability.
-4. Move internal sequencing behind the interface. Remove forwarding layers that provide no useful variation or isolation.
-5. Test through the public interface, replacing dependencies only at real external boundaries.
-6. Revisit callers and remove knowledge now owned by the module.
+1. Read the callers. List the state, the order of steps, and the rules that they coordinate.
+2. Put that state and those decisions under one owner. Name an operation for what the caller wants.
+3. If the boundary is not clear, compare two placements by caller effort, error handling, and test effort.
+4. Move the internal order of steps behind the interface.
+5. Remove each layer that only forwards calls.
+6. Write tests against the new interface, then remove the knowledge that callers no longer need.
 
-## Guardrails
+## Example
 
-Keep invariants and error behavior in the interface contract. Use an options object when callers would otherwise correlate primitive arguments. Return outcomes callers need, and contain side effects within their owner.
+**Situation:** Three commands each read a config file, merge it with defaults, check a policy, and take a lock before they write.
+**Easy route:** Add a helper for each of the four steps, and keep the order in each command.
+**Hidden cost:** Each command still owns the order. A new command can skip the policy check, and each test must repeat the four steps.
+**Best route:** Add one operation that takes the intended change and does the four steps inside. The commands call that operation.
+**Evidence:** Each command became one call. A test through the new operation failed without the policy check, and the step tests in each command were no longer needed.
 
-Add an abstraction for a concrete variation or isolation need. A short interface still imposes complexity if callers must know a hidden sequence of calls.
+## Guardrails
 
-## Completion
+- Use an options object when callers would otherwise pass related values in a fixed order.
+- Return the outcomes that callers need, and keep side effects inside their owner.
+- Do not add an abstraction without a concrete variation or isolation need.
+- A short interface still costs effort if callers must call it in a hidden order.
 
-Callers express intent without coordinating internal steps, and tests exercise behavior without depending on that sequence.
+## Completion
 
-Report the module's new interface (its exported names and one call example), the caller steps it absorbed, and the test command with its result. Keep the reply to these facts. When a pull request exists, put full command output in its verification section instead of the reply.
+- The new interface: its exported names and one call example.
+- The caller steps that the module now owns.
+- The test command for the new interface, with its result line.

package/skills/diagnose-before-editing/SKILL.md

@@ -1,37 +1,58 @@
 ---
 name: diagnose-before-editing
-description: Diagnose a reproducible defect or performance regression before changing production code. Use when behavior is broken, failing, throwing, flaky, or unexpectedly slow.
+description: 'Use when behavior fails, flakes, or slows down, and nobody knows the cause yet. Also use it when the user says "why does this fail?", "it worked yesterday", or "this got slow". Reproduces the failure, makes it smaller, and tests one cause at a time until one cause predicts the symptom. Then fixes the cause at its origin, not the symptom. Not for scoping a fix whose cause you already know (use `scope-confirmed-changes`).'
 metadata:
   shadowclone-category: debugging
   shadowclone-section: workflow
-  shadowclone-applies-when: diagnosing a reported defect or performance regression
+  shadowclone-applies-when: when behavior is wrong or slow and the cause is not known
 ---
 # Diagnose Before Editing
 
 ## Use when
 
-A defect or performance regression has no demonstrated cause yet.
+Something fails, throws, flakes, or slows down, and nobody has shown the cause yet. A change before the cause is known can hide the bug instead of fixing it.
+
+## Gates
+
+1. Can you make the failure happen on demand with one command or test?
+2. Did you write down the input, the actual result, and the expected result?
+3. For each suspected cause, did you name an observation that would prove it wrong?
+4. Did you change one variable in each probe?
+5. Does the cause that you found predict the symptom, and does a controlled change remove it?
+6. Did you remove each temporary log line and probe before the handoff?
 
 ## Process
 
-1. State the input, actual result, and expected result. Find the fastest repeatable command that reaches the failing path.
-2. Reproduce the reported failure, then remove inputs or steps while preserving it.
-3. Trace where correct state first becomes incorrect. List plausible causes and an observation that would disprove each.
-4. Probe one cause at a time with a debugger, targeted instrumentation, timings, or controlled inputs.
-5. Stop when a cause predicts the symptom and a controlled change removes it.
-6. Preserve the reproduction as a regression test through a stable public interface where practical. Fix the cause at its origin.
-7. Run the reduced and original reproductions, then remove temporary diagnostics.
+1. Find the fastest command that reaches the failing path. Run it until you see the failure.
+2. Remove inputs and steps while the failure stays. Stop when no further removal keeps it.
+3. Trace the state from the input. Find the first place where a correct value becomes wrong.
+4. List the possible causes. For each one, write the observation that would rule it out.
+5. Test one cause at a time with a debugger, a log line, a timer, or a controlled input.
+6. When one cause predicts the symptom, fix it at its origin.
+7. Run the small and the original reproductions. Keep one as a regression test where practical.
 
-For flaky behavior, measure the reproduction rate and control clocks, randomness, concurrency, or external responses. For performance work, establish a baseline and measure the suspected cost before changing it.
+For a flaky failure, measure how often it happens. Control the clock, the random values, the concurrency, and the outside responses. For a slow path, measure a baseline first, and measure the suspected cost before you change it.
 
-## Guardrails
+## Example
 
-Redact sensitive traces and paths before reporting them. Change one causal variable per probe. Keep unrelated defects out of the fix and avoid fallbacks that merely hide invalid state.
+**Situation:** A test fails one run in ten on a busy machine. A teammate suggests a longer timeout.
+**Easy route:** Raise the timeout from 5 to 30 seconds. The test passes.
+**Hidden cost:** The cause stays. The real command can still hang for users, and the slow test now hides other delays.
+**Best route:** Measure the failure rate, then control the clock in the test. The failure now shows on each run, when two writes wait for one lock.
+**Evidence:** With the clock fixed, the test failed 10 of 10 runs before the fix and passed 10 of 10 after it. The timeout stayed at 5 seconds.
 
-If reproduction fails, report what was tried and the missing evidence. Do not turn an unverified theory into a production change.
+## Guardrails
 
-## Completion
+- Do not turn a theory that you did not test into a production change.
+- Do not add a fallback that only hides invalid state.
+- Remove secrets and private paths from traces before you report them.
+- Do not fix other defects in this change. List them in the handoff.
+- If you cannot reproduce the failure, report what you tried and what evidence is missing.
 
-The cause explains the original symptom, the fix passes both reproductions and affected checks, and temporary instrumentation is gone.
+## Completion
 
-Report the reproduction command with its failing line before the fix and its passing line after, the cause in one sentence with the file and line where state first goes wrong, and anything you could not reproduce. Keep the reply to these facts. When a pull request exists, put full command output in its verification section instead of the reply.
+- The reproduction command, with its failing line before the fix.
+- The same command after the fix, with its passing line.
+- The cause in one sentence, with the `file:line` where the state first goes wrong.
+- Each cause that you ruled out, with the observation that ruled it out.
+- Anything that you could not reproduce.

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>

package/skills/plan-with-review-page/scripts/validate-page.mjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+
+const statuses = ["todo", "doing", "done", "blocked", "skipped"];
+const dashes = new RegExp(`[${String.fromCharCode(0x2013, 0x2014)}]`);
+const mermaidUrl = "https://cdn.jsdelivr.net/npm/mermaid@12.1.0/dist/mermaid.min.js";
+const mermaidIntegrity = "sha384-EbBpjO7rlR6eqZEcG7GaPpyk9H9WrMyPWX4d3KvPYltgt8Z8l0z6R56B1qP40pR4";
+
+function readPlan(html) {
+  const blocks = [
+    ...html.matchAll(/<script type="application\/json" id="plan">([\s\S]*?)<\/script>/g),
+  ];
+
+  if (blocks.length !== 1) {
+    return {
+      error: `found ${blocks.length} plan blocks, keep exactly one JSON block with the id plan`,
+    };
+  }
+
+  try {
+    return { plan: JSON.parse(blocks[0][1]) };
+  } catch (error) {
+    return { error: `the plan block is not valid JSON: ${error.message}` };
+  }
+}
+
+function textValues(value, at) {
+  if (typeof value === "string") {
+    return [[at, value]];
+  }
+
+  if (Array.isArray(value)) {
+    return value.flatMap((entry, index) => textValues(entry, `${at}[${index}]`));
+  }
+
+  if (value !== null && typeof value === "object") {
+    return Object.entries(value).flatMap(([key, entry]) =>
+      textValues(entry, at ? `${at}.${key}` : key),
+    );
+  }
+
+  return [];
+}
+
+const filled = (value) => typeof value === "string" && value.trim().length > 0;
+
+function validate(html) {
+  const { plan, error } = readPlan(html);
+
+  if (error) {
+    return [error];
+  }
+
+  const errors = [];
+  const steps = Array.isArray(plan.steps) ? plan.steps : [];
+  const decisions = Array.isArray(plan.decisions) ? plan.decisions : [];
+
+  for (const key of ["title", "goal", "planPath", "updated"]) {
+    if (!filled(plan[key])) {
+      errors.push(`${key} must be filled in`);
+    }
+  }
+
+  if (steps.length === 0) {
+    errors.push("steps must list at least one step");
+  }
+
+  for (const [index, step] of steps.entries()) {
+    if (!statuses.includes(step?.status)) {
+      errors.push(`steps[${index}].status must be one of ${statuses.join(", ")}`);
+    }
+
+    if (!filled(step?.text)) {
+      errors.push(`steps[${index}].text must be filled in`);
+    }
+
+    if ((step?.status === "skipped" || step?.status === "blocked") && !filled(step.note)) {
+      errors.push(`steps[${index}] is ${step.status}, so its note must give the reason`);
+    }
+  }
+
+  if (!Array.isArray(plan.decisions)) {
+    errors.push("decisions must be a list");
+  }
+
+  for (const [index, decision] of decisions.entries()) {
+    for (const key of ["question", "answer", "source"]) {
+      if (!filled(decision?.[key])) {
+        errors.push(`decisions[${index}].${key} must be filled in`);
+      }
+    }
+  }
+
+  if (!Array.isArray(plan.open) || plan.open.some((entry) => typeof entry !== "string")) {
+    errors.push("open must be a list of questions");
+  }
+
+  if (typeof plan.diagram !== "string") {
+    errors.push("diagram must be Mermaid source, or empty when there is no diagram");
+  }
+
+  for (const [at, text] of textValues(plan, "")) {
+    if (text.startsWith("TEMPLATE:")) {
+      errors.push(`${at} still has template text, replace it`);
+    }
+
+    if (dashes.test(text)) {
+      errors.push(`${at} has an em or en dash, use a comma, a period, or parentheses`);
+    }
+  }
+
+  for (const [url] of html.matchAll(/https?:\/\/[^\s"'<>)]+/g)) {
+    if (url !== mermaidUrl) {
+      errors.push(`${url} loads from the network, keep the page self-contained`);
+    }
+  }
+
+  if (html.includes(mermaidUrl) && !html.includes(mermaidIntegrity)) {
+    errors.push("the Mermaid script must keep its pinned integrity hash");
+  }
+
+  return errors;
+}
+
+async function main(files) {
+  if (files.length === 0) {
+    console.error("Usage: validate-page.mjs <page.html>...");
+
+    return 2;
+  }
+
+  let total = 0;
+
+  for (const file of files) {
+    let html;
+
+    try {
+      html = await readFile(file, "utf8");
+    } catch (error) {
+      console.error(`${file}: cannot read the file (${error.code ?? error.message})`);
+
+      return 2;
+    }
+
+    for (const message of validate(html)) {
+      console.log(`${file}: error ${message}`);
+      total += 1;
+    }
+  }
+
+  const plural = (count, word) => `${count} ${word}${count === 1 ? "" : "s"}`;
+
+  console.log(`validate-page: ${plural(total, "error")} in ${plural(files.length, "file")}`);
+
+  return total > 0 ? 1 : 0;
+}
+
+process.exitCode = await main(process.argv.slice(2));