@shadowclone/cli 0.0.16 → 0.0.18

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

@@ -1,32 +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.
+
+## Guardrails
 
-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.
+- 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.
 
 ## Completion
 
-Callers express intent without coordinating internal steps, and tests exercise behavior without depending on that sequence.
+- 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,35 +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.
+
+## Guardrails
 
-If reproduction fails, report what was tried and the missing evidence. Do not turn an unverified theory into a production change.
+- 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.
 
 ## Completion
 
-The cause explains the original symptom, the fix passes both reproductions and affected checks, and temporary instrumentation is gone.
+- 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));

package/skills/research-primary-sources/SKILL.md

@@ -1,31 +1,51 @@
 ---
 name: research-primary-sources
-description: Resolve a technical implementation question against authoritative first-party evidence. Use when behavior depends on a library, platform, protocol, standard, or tool that may have changed.
+description: 'Use when a decision depends on how a library, platform, protocol, or tool behaves, and that behavior can change by version. Also use it when the user says "check the docs", "is this still true?", or "what does the spec say?". Finds the first-party source for the installed version and reads it. Separates what the source guarantees from what you infer. Not for debugging a failure in your own code (use `diagnose-before-editing`).'
 metadata:
   shadowclone-category: research
   shadowclone-section: workflow
-  shadowclone-applies-when: resolving an implementation question that depends on external facts
+  shadowclone-applies-when: when a decision depends on facts outside the repository
 ---
 # Research Primary Sources
 
 ## Use when
 
-An implementation decision depends on external facts or behavior that varies by version.
+A decision depends on outside facts about a library, a platform, a protocol, a standard, or a tool. Those facts change with versions, and memory or a search snippet can be out of date.
+
+## Gates
+
+1. Is the question specific enough to have one answer?
+2. Did you record the installed version, the runtime, and the platform that the answer must match?
+3. Did you read the first-party source itself, such as the specification, the official documents, the source code, or the release notes?
+4. Does each claim say whether the source guarantees it or you infer it?
+5. If no source answers the question, did you say so and keep the choice easy to reverse?
 
 ## Process
 
-1. State the decision as an answerable question. Record the project's relevant version, runtime, platform, and constraints.
-2. Find the specification, official documentation, implementation, release note, or first-party issue that defines the behavior.
-3. Open the exact source and check its version and date. Trace consequential claims back from summaries.
-4. Compare the evidence with the installed version and code path. Explain disagreements caused by different environments or versions.
-5. Give the conclusion with direct supporting links and the implementation constraint it creates.
+1. Write the decision as a question. Record the version, the runtime, the platform, and the limits that apply.
+2. Find the source that defines the behavior. Prefer the specification, the official documents, the source code, a release note, or a first-party issue.
+3. Open the exact page or file. Check that its version and date match yours.
+4. Compare the source with the installed code. Explain each difference that comes from a version or an environment.
+5. Write the answer, the link or `file:line` for each claim, and the limit that it puts on the change.
 
-## Guardrails
+## Example
 
-Search snippets are leads; read the underlying source. Distinguish documented guarantees from inferences and identify the observations supporting an inference.
+**Situation:** A change must know which instruction file a coding agent reads when two files exist in one folder.
+**Easy route:** Answer from memory: "it reads both".
+**Hidden cost:** If memory is wrong, an install can write a file that hides a file of the team, and nobody notices.
+**Best route:** Open the official documents for the installed version, find the section about file order, and quote it.
+**Evidence:** The documents said that the agent reads the override file first, and reads at most one file in each folder. The install now stops before it writes a file that hides another one.
+
+## Guardrails
 
-Quote sparingly and keep credentials, private URLs, and captured user data out of research notes. If authoritative evidence is unavailable, state the unknown and contain it behind a reversible implementation choice.
+- A search result is a lead. Read the source that it points to.
+- Quote only the lines that support the decision.
+- Keep credentials, private links, and user data out of research notes.
+- If the evidence is old, say so, and name the version that it covers.
 
 ## Completion
 
-The question has a supported answer or an explicit unknown, and the resulting constraint is clear enough to implement.
+- The answer, or the exact unknown.
+- Each claim with its source: a link, or a `file:line`.
+- The version that each source covers.
+- The limit that the answer puts on the change.