dw-sdlc 0.17.0 → 0.19.0

package/dist/checks/skill-sections.js

@@ -0,0 +1,163 @@
+// `skill-sections`: each README section a skill copies, a part, matches its source. A part sits between
+// `<!-- README.md#<anchor> -->` and `<!-- /README.md#<anchor> -->` and repeats only a section a Primitive's
+// docs name. `dw-sdlc check skill-sections --write` writes each part from its section.
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join, posix } from "node:path";
+import { resolveConfig } from "../agentic-config.js";
+import { readCatalogue } from "../catalogue.js";
+import { headings, openFence, prose } from "../markdown.js";
+import { CannotRun } from "./check.js";
+import { catalogueFile } from "./primitives.js";
+import { matching, treeFiles } from "./tree.js";
+/** Either marker of a part: `/` before `README.md` closes it. */
+const MARKER = /<!-- (\/?)README\.md#(\S+) -->/g;
+const WRITE = "dw-sdlc check skill-sections --write";
+const REMEDIES = {
+    stale: `edit the README, not the part, then run ${WRITE}`,
+    readme: "write the README, or drop the part",
+    section: "point it at a heading the README has",
+    unpaired: "open a part with <!-- README.md#<anchor> --> and close it with <!-- /README.md#<anchor> -->, each on its own line",
+    missing: "create it, or point gate.checks.primitives.file at the catalogue",
+    invalid: "fix what dw-sdlc check primitives names",
+    fence: "close the fence"
+};
+/** The markers outside code in `text`, in order. */
+function markers(text) {
+    return Array.from(prose(text).matchAll(MARKER), (match) => ({
+        close: match[1] === "/",
+        anchor: match[2] ?? "",
+        start: match.index,
+        end: match.index + match[0].length
+    }));
+}
+/** The README a skill file copies from: the one beside the `skills` directory it is in, else beside it. */
+function readmeOf(path) {
+    const directories = path.split("/").slice(0, -1);
+    const at = directories.lastIndexOf("skills");
+    const unit = at === -1 ? directories : directories.slice(0, at);
+    return posix.join(...unit, "README.md");
+}
+/** The section under the heading with `anchor`, up to the next heading of its level or above, its end trimmed. */
+function sectionOf(markdown, anchor) {
+    const all = headings(markdown);
+    const start = all.find((heading) => heading.anchor === anchor);
+    if (start === undefined) {
+        return undefined;
+    }
+    const end = all.find((heading) => heading.line > start.line && heading.level <= start.level);
+    return markdown
+        .split("\n")
+        .slice(start.line - 1, end === undefined ? undefined : end.line - 1)
+        .join("\n")
+        .trimEnd();
+}
+function lineAt(text, offset) {
+    return text.slice(0, offset).split("\n").length;
+}
+function readmeText(root, path, sources) {
+    if (!sources.readmes.has(path)) {
+        const full = join(root, path);
+        sources.readmes.set(path, existsSync(full) ? readFileSync(full, "utf8") : undefined);
+    }
+    return sources.readmes.get(path);
+}
+function render(root, path, sources) {
+    const text = readFileSync(join(root, path), "utf8");
+    const readme = readmeOf(path);
+    const found = markers(text);
+    const findings = [];
+    const pieces = [];
+    let copied = 0;
+    let rewritten = 0;
+    for (let index = 0, open = found[0]; open !== undefined; open = found[++index]) {
+        const close = found[index + 1];
+        const line = lineAt(text, open.start);
+        const fail = (message, remedy) => findings.push({ file: path, line, message, remedy });
+        if (open.close || close === undefined || !close.close || close.anchor !== open.anchor) {
+            const marker = `README.md#${open.anchor}`;
+            const message = open.close
+                ? `the closing marker of ${marker} has no opening marker`
+                : `the opening marker of ${marker} has no closing marker`;
+            fail(message, REMEDIES.unpaired);
+            continue;
+        }
+        index++;
+        const part = `the part from README.md#${open.anchor}`;
+        const source = readmeText(root, readme, sources);
+        const section = source === undefined ? undefined : sectionOf(source, open.anchor);
+        if (!sources.listed().has(`${readme}#${open.anchor}`)) {
+            const remedy = `name ${readme}#${open.anchor} in a Primitive's docs, or point the part at a section they name`;
+            fail(`${part} copies a section no Primitive's docs name`, remedy);
+        }
+        else if (source === undefined) {
+            fail(`${part} reads ${readme}, which does not exist`, REMEDIES.readme);
+        }
+        else if (section === undefined) {
+            fail(`${part} names no heading of ${readme}`, REMEDIES.section);
+        }
+        else if (text.slice(open.end, close.start) !== `\n\n${section}\n\n`) {
+            fail(`${part} differs from that section of ${readme}`, REMEDIES.stale);
+            pieces.push(text.slice(copied, open.end), `\n\n${section}\n\n`);
+            copied = close.start;
+            rewritten++;
+        }
+    }
+    const fence = openFence(text);
+    const hidden = fence === undefined ? "" : text.split("\n").slice(fence).join("\n");
+    if (fence !== undefined && hidden.search(MARKER) !== -1) {
+        const message = "a code fence opens here and never closes, so the markers after it are not read";
+        findings.push({ file: path, line: fence, message, remedy: REMEDIES.fence });
+    }
+    pieces.push(text.slice(copied));
+    return { text: pieces.join(""), findings, rewritten };
+}
+/** The docs entries the catalogue names, each read from the root; the catalogue is read on the first call. */
+function listedDocs(root) {
+    let listed;
+    return () => {
+        if (listed === undefined) {
+            const file = catalogueFile(resolveConfig(root).config.gate.checks);
+            const read = readCatalogue(root, file);
+            if (read.state === "missing") {
+                throw new CannotRun({
+                    file,
+                    message: "the catalogue does not exist, and a skill holds a part",
+                    remedy: REMEDIES.missing
+                });
+            }
+            if (read.state === "invalid") {
+                throw new CannotRun({
+                    file,
+                    message: "the catalogue is not valid, and a skill holds a part",
+                    remedy: REMEDIES.invalid
+                });
+            }
+            listed = new Set(read.catalogue.primitives.flatMap(({ docs }) => docs).map((entry) => posix.join(".", entry)));
+        }
+        return listed;
+    };
+}
+function renderAll(root, { files }) {
+    const sources = { listed: listedDocs(root), readmes: new Map() };
+    return matching(root, treeFiles(root), files).map((path) => ({ path, rendered: render(root, path, sources) }));
+}
+function plural(count, noun) {
+    return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}
+function write(root, options) {
+    const changed = renderAll(root, options).filter(({ rendered }) => rendered.rewritten > 0);
+    for (const { path, rendered } of changed) {
+        writeFileSync(join(root, path), rendered.text);
+    }
+    if (changed.length === 0) {
+        return "every part matches its section, so nothing was written";
+    }
+    const parts = changed.reduce((sum, { rendered }) => sum + rendered.rewritten, 0);
+    return `wrote ${plural(parts, "part")} in ${plural(changed.length, "file")}`;
+}
+export const skillSections = {
+    name: "skill-sections",
+    defaults: { files: ["**/skills/**/*.md"] },
+    run: (root, options) => renderAll(root, options).flatMap(({ rendered }) => rendered.findings),
+    write
+};

package/dist/commands/check.js

@@ -1,11 +1,12 @@
 // `dw-sdlc check <name>`: one Check of the Gate by its name, without the Steps and the other Checks.
 import { parseArgs } from "node:util";
-import { repositoryRoot } from "../agentic-config.js";
-import { CHECK_NAMES } from "../checks/index.js";
+import { repositoryRoot, resolveConfig } from "../agentic-config.js";
+import { CannotRun } from "../checks/check.js";
+import { CHECK_NAMES, shippedCheck } from "../checks/index.js";
 import { TAIL_LINES } from "../run-command.js";
 import { printReport, runGate } from "./gate.js";
 export const summary = "run one Check of the Gate by its name, without the Steps and the other Checks";
-const USAGE = `Usage: dw-sdlc check <name> [--json] [--root <dir>]
+const USAGE = `Usage: dw-sdlc check <name> [--json] [--write] [--root <dir>]
 
 Runs the Check named <name> in the Gate of the repository holding --root (default: the current
 directory): a script under gate.checks.run, or a Check the package ships, one of
@@ -15,6 +16,10 @@ false or leaves it out. No Step runs. A run script prints nothing of its own unl
 pass: then its last ${TAIL_LINES} lines, both streams in the order written. Prints one line per failure,
 as the Gate does; --json prints the Gate's document alone, with no Step.
 
+--write first writes what the Check derives from its sources, then judges the tree it wrote, and
+prints a line on what it wrote, to stderr under --json. Only a Check that derives files takes it:
+skill-sections writes each part of a skill from its README section.
+
 A Ratchet's baseline is refreshed by dw-sdlc gate --update-baseline, which needs every other Check to
 pass.
 
@@ -29,18 +34,50 @@ function parseCli(argv) {
             options: {
                 help: { type: "boolean", short: "h" },
                 json: { type: "boolean" },
+                write: { type: "boolean" },
                 root: { type: "string" }
             }
         });
         if (positionals.length > 1) {
             return { error: `one Check at a time, not ${positionals.map((name) => JSON.stringify(name)).join(" and ")}` };
         }
-        return { help: values.help === true, json: values.json === true, root: values.root, name: positionals[0] };
+        const flags = { help: values.help === true, json: values.json === true, write: values.write === true };
+        return { ...flags, root: values.root, name: positionals[0] };
     }
     catch (error) {
         return { error: error instanceof Error ? error.message : String(error) };
     }
 }
+/**
+ * Writes what the shipped Check `name` derives, on the setting the config gives it, and prints what it
+ * wrote; why it cannot when it takes no --write. An invalid config or a missing input writes nothing,
+ * and the run after it reports why.
+ */
+function writeDerived(root, name, json) {
+    const { config, problems } = resolveConfig(root);
+    if (problems.length > 0) {
+        return undefined;
+    }
+    const shipped = shippedCheck(name, config.gate.checks[name]);
+    if (shipped === undefined && !config.gate.checks.run.some((check) => check.name === name)) {
+        // No Check of that name: the run after it says so, with the names there are.
+        return undefined;
+    }
+    const write = shipped?.write;
+    if (write === undefined) {
+        return `${JSON.stringify(name)} takes no --write: it derives no file`;
+    }
+    try {
+        const out = json ? process.stderr : process.stdout;
+        out.write(`check ${name}: ${write(root)}\n`);
+    }
+    catch (error) {
+        if (!(error instanceof CannotRun)) {
+            throw error;
+        }
+    }
+    return undefined;
+}
 export async function run(argv) {
     const cli = parseCli(argv);
     if ("error" in cli) {
@@ -56,6 +93,14 @@ export async function run(argv) {
         return 2;
     }
     const { json, name } = cli;
-    const report = await runGate(repositoryRoot(cli.root ?? process.cwd()), { json, only: name });
+    const root = repositoryRoot(cli.root ?? process.cwd());
+    if (cli.write) {
+        const refused = writeDerived(root, name, json);
+        if (refused !== undefined) {
+            process.stderr.write(`dw-sdlc check: ${refused}\n`);
+            return 2;
+        }
+    }
+    const report = await runGate(root, { json, only: name });
     return printReport(report, json, `check ${name}`);
 }

package/dist/commands/doctor.js

@@ -47,7 +47,11 @@ function checkJq(probe) {
     if (status === 0) {
         return { name: "jq", level: "PASS", detail: stdout.trim() };
     }
-    return { name: "jq", level: "FAIL", detail: "missing: every guard is silent without it. brew install jq" };
+    return {
+        name: "jq",
+        level: "FAIL",
+        detail: "missing: every guard is silent without it. https://jqlang.org/download/"
+    };
 }
 /** Every hook command string in a settings file, whatever the event and matcher. */
 function hookCommands(settings) {

package/dist/commands/primitives.d.ts

@@ -1,2 +1,2 @@
-export declare const summary = "name the Primitives that own each path, with their summaries and documents";
+export declare const summary = "name the Primitives that own each path, or that a change removes, adds or extends";
 export declare function run(argv: string[]): number;

package/dist/commands/primitives.js

@@ -1,21 +1,32 @@
-// `dw-sdlc primitives --paths <files>`: for each path, the Primitives of the catalogue that name it,
-// with their summaries and the documents to read, or that none does.
+// `dw-sdlc primitives`: with `--paths <files>`, for each path the Primitives of the catalogue that name
+// it, with their summaries and the documents to read, or that none does; with `--diff <base>`, the
+// Primitives a change removes, adds or extends.
 import { existsSync, realpathSync } from "node:fs";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { repositoryRoot, resolveConfig } from "../agentic-config.js";
 import { primitivesNaming, readCatalogue } from "../catalogue.js";
 import { catalogueFile } from "../checks/primitives.js";
-export const summary = "name the Primitives that own each path, with their summaries and documents";
+import { blockOf, primitivesDiff } from "../primitives-diff.js";
+export const summary = "name the Primitives that own each path, or that a change removes, adds or extends";
 const USAGE = `Usage: dw-sdlc primitives --paths <file>... [--json] [--root <dir>]
+       dw-sdlc primitives --diff <base> [--json] [--root <dir>]
 
-Prints, for each path, the Primitives of the catalogue whose code names it, the file itself or the
-nearest directory above it: the id, the name, the summary and the documents to read; or that no
+--paths prints, for each path, the Primitives of the catalogue whose code names it, the file itself or
+the nearest directory above it: the id, the name, the summary and the documents to read; or that no
 Primitive names it. A path is read from the current directory. The catalogue is the one the
 primitives Check reads, in the repository holding --root (default: the current directory). --json
 prints one document instead.
 
-Exit 0 with an answer for every path, 2 when there is no catalogue to read or it is not one.`;
+--diff prints the Primitives the committed change from the merge-base of <base> and HEAD to HEAD
+removes (an id gone from the catalogue), adds (a new id) and extends (a changed file in the code of a
+Primitive that was there): a markdown block between <!-- primitives:start --> and <!-- primitives:end -->
+for a pull request body, which a later run replaces. --json prints instead, per Primitive, its id, name,
+class, file count, summary and docs, each doc with whether the change touches its file, and the count of
+changed files outside every Primitive. It takes no --paths.
+
+Exit 0 with an answer, 2 when there is no catalogue to read or it is not one, and for --diff when <base>
+does not resolve.`;
 const REMEDIES = {
     missing: "create it, or point gate.checks.primitives.file at the catalogue",
     invalid: "fix the catalogue; dw-sdlc gate names each problem under the primitives Check"
@@ -29,6 +40,7 @@ function parseCli(argv) {
                 help: { type: "boolean", short: "h" },
                 json: { type: "boolean" },
                 paths: { type: "boolean" },
+                diff: { type: "string" },
                 root: { type: "string" }
             }
         });
@@ -36,10 +48,17 @@ function parseCli(argv) {
             help: values.help === true,
             json: values.json === true,
             paths: values.paths === true,
+            diff: values.diff,
             files: positionals,
             root: values.root
         };
-        return cli.help || cli.paths ? cli : { error: "name the paths with --paths" };
+        if (cli.help) {
+            return cli;
+        }
+        if (cli.diff !== undefined && (cli.paths || cli.files.length > 0)) {
+            return { error: "--diff and --paths exclude each other — ask one question at a time" };
+        }
+        return cli.paths || cli.diff !== undefined ? cli : { error: "name the paths with --paths, or a base with --diff" };
     }
     catch (error) {
         return { error: error instanceof Error ? error.message : String(error) };
@@ -68,6 +87,15 @@ function plain(path, primitives) {
         `  read: ${docs.join(", ")}`
     ]);
 }
+function runDiff(root, base, json) {
+    const answer = primitivesDiff(root, base);
+    if ("problems" in answer) {
+        process.stderr.write(answer.problems.map((problem) => `dw-sdlc primitives: ${problem}\n`).join(""));
+        return 2;
+    }
+    process.stdout.write(json ? `${JSON.stringify(answer, null, 2)}\n` : `${blockOf(answer)}\n`);
+    return 0;
+}
 export function run(argv) {
     const cli = parseCli(argv);
     if ("error" in cli) {
@@ -79,6 +107,9 @@ export function run(argv) {
         return 0;
     }
     const root = repositoryRoot(cli.root ?? process.cwd());
+    if (cli.diff !== undefined) {
+        return runDiff(root, cli.diff, cli.json);
+    }
     const file = catalogueFile(resolveConfig(root).config.gate.checks);
     const read = readCatalogue(root, file);
     if (read.state !== "valid") {

package/dist/commands/recap.js

@@ -8,6 +8,7 @@ import { decide, declaredPolicy, labelOf, lineOf } from "../pr/decide.js";
 import { CannotRun, defaultBranch, now, readBranch } from "../pr/read.js";
 import { holds, upstreamName } from "../pr/upstream.js";
 import { READY_LABEL, readNext } from "../recap-next.js";
+import { rollup } from "../recap-primitives.js";
 import { isLive, Refusal, workersOf, workingFolders } from "../worker/herdr.js";
 import { asked, git } from "../working-tree.js";
 export const summary = "the facts a Recap rests on, whether the session can be closed and what could come next";
@@ -32,6 +33,10 @@ A pull request closed without merging merges nothing, and a detached HEAD names
 commit counts as pushed only on a remote branch, and the command asks the remote which branches still
 stand. A branch force-pushed since the last fetch can still read as holding it, so fetch first to be exact.
 
+Beside the facts it lists the Primitives the session's branch changed, as primitives --diff classes them
+from its merge-base with origin/<default>: ids and classes, none on the default branch or in a repository
+with no catalogue. A catalogue it cannot read lists none, with a warning.
+
 A linked worktree is a reason beside the verdict, never against it: the session cannot remove the
 directory it runs in.
 
@@ -192,11 +197,11 @@ function orphanedOf(root, read, shipped, held) {
  * The commits on top of the base that no pull request holds. A branch the config protects takes changes
  * through pull requests rather than making one, and so does the default branch: neither needs one.
  */
-function aheadOf(root, branch, shipped) {
+function aheadOf(root, branch, baseOf) {
     if (resolveConfig(root).config.guardrails.protectedBranches.includes(branch)) {
         return null;
     }
-    const base = shipped?.pr.base ?? defaultBranch();
+    const base = baseOf();
     if (branch === base) {
         return null;
     }
@@ -285,7 +290,11 @@ function nextLine(next) {
     const named = next.candidates.map(({ number, parent }) => `#${number}${parent === null ? "" : ` (sub-issue of #${parent})`}`);
     return named.length === 0 ? "none" : named.join(", ");
 }
-function linesOf(local, { shipped, askedGh, workers, next }, line) {
+function primitivesLine(primitives) {
+    const named = primitives.map(({ id, class: kind }) => `${kind} ${id}`);
+    return named.length === 0 ? [] : [`primitives: ${named.join(", ")}`];
+}
+function linesOf(local, { shipped, askedGh, workers, next }, primitives, line) {
     const none = askedGh ? "none" : "gh not asked";
     return [
         `branch: ${local.branch ?? "detached HEAD"}`,
@@ -295,6 +304,7 @@ function linesOf(local, { shipped, askedGh, workers, next }, line) {
         `worktree: ${local.worktree.linked ? `linked at ${local.worktree.path}` : "main checkout"}`,
         `workers: ${workersLine(workers)}`,
         `next: ${nextLine(next)}`,
+        ...primitivesLine(primitives),
         line
     ].join("\n");
 }
@@ -328,7 +338,9 @@ function report(json) {
     const local = standing(root, read, shipped, held);
     // An open pull request can still take the head, and a commit-less repository has nothing to merge.
     const nothingToMerge = held || shipped?.pr.state === "OPEN" || head === null;
-    const ahead = asksGh && !nothingToMerge ? aheadOf(root, branch, shipped) : null;
+    let named;
+    const baseOf = () => (named ??= shipped?.pr.base ?? defaultBranch());
+    const ahead = asksGh && !nothingToMerge ? aheadOf(root, branch, baseOf) : null;
     const facts = {
         shipped,
         ahead,
@@ -340,14 +352,18 @@ function report(json) {
     if (facts.next !== null && "unread" in facts.next) {
         process.stderr.write(`dw-sdlc recap: warning: the backlog was not read: ${facts.next.unread}\n`);
     }
+    const rolled = asksGh ? rollup(root, branch, defaultBranch) : { primitives: [] };
+    if ("unread" in rolled) {
+        process.stderr.write(`dw-sdlc recap: warning: the Primitives were not read: ${rolled.unread}\n`);
+    }
     const next = facts.next !== null && "candidates" in facts.next ? facts.next.candidates : null;
     const close = closeOf(reasonsOf(local, facts));
     const pullRequest = shipped === null
         ? null
         : { url: shipped.pr.url, number: shipped.pr.number, state: shipped.pr.state, ...shipped.answer };
     const output = json
-        ? JSON.stringify({ ...local, askedGh: asksGh, pullRequest, workers: facts.workers, close, next }, null, 2)
-        : linesOf(local, facts, close.line);
+        ? JSON.stringify({ ...local, askedGh: asksGh, pullRequest, workers: facts.workers, primitives: rolled.primitives, close, next }, null, 2)
+        : linesOf(local, facts, rolled.primitives, close.line);
     process.stdout.write(`${output}\n`);
     return close.verdict === "yes" ? 0 : 1;
 }

package/dist/commands/setup.d.ts

@@ -27,8 +27,8 @@ export type SetupOptions = {
 export declare const summary = "adopt the Gate where asked, and write this machine's local config layer, the git excludes and the permission rules";
 /**
  * What the machine's layer points `$schema` at: the marketplace clone's schema as a `file://` URL, as an
- * editor cannot fetch the `$id` from a private repository and the clone, unlike the install cache, keeps
- * its path across plugin updates. Without a registered clone holding the schema, the `$id`.
+ * editor reads it offline at the installed version and the clone, unlike the install cache, keeps its
+ * path across plugin updates. Without a registered clone holding the schema, the `$id`.
  */
 export declare function schemaReference(claudeDir: string): string;
 export declare function setup(options: SetupOptions): Step[];

package/dist/commands/setup.js

@@ -69,8 +69,8 @@ function committedConfig(root) {
 }
 /**
  * What the machine's layer points `$schema` at: the marketplace clone's schema as a `file://` URL, as an
- * editor cannot fetch the `$id` from a private repository and the clone, unlike the install cache, keeps
- * its path across plugin updates. Without a registered clone holding the schema, the `$id`.
+ * editor reads it offline at the installed version and the clone, unlike the install cache, keeps its
+ * path across plugin updates. Without a registered clone holding the schema, the `$id`.
  */
 export function schemaReference(claudeDir) {
     const registry = readJson(join(claudeDir, "plugins", "known_marketplaces.json"));

package/dist/commands/sweep.js

@@ -9,7 +9,7 @@ import { isCommitLanded, isLanded } from "../landed.js";
 import { shellLine } from "../pr/decide.js";
 import { CannotRun } from "../pr/read.js";
 import { byHand, holdersOf, keptIn, lockAfterStop, lockHolder, outsideWorktrees, readTerminals, removeTerminal, stopsOf, sweepingTerminal, whyHeld } from "../sweep-terminals.js";
-import { dirtyFiles, must, pausedOperation, worktreesOf } from "../sweep-trees.js";
+import { branchesOf, dirtyFiles, pausedOperation, switchOff, worktreesOf } from "../sweep-trees.js";
 import { asked, git } from "../working-tree.js";
 import { lockVerdict } from "../worktree-lock.js";
 export const summary = "removes Landed branches and clean worktrees whose work has landed, names what it keeps";
@@ -26,7 +26,8 @@ config, else the branch origin/HEAD names) and removes, never forcing:
 It keeps, and names with the reason and the command to run yourself:
   a worktree that fails the set: the files that hold it with the forced removal, the paused operation, the
   lock's reason with git worktree unlock, a live Claude Code lock named by its pid, a HEAD that is not Landed;
-  the default branch, the base branch, a protected branch and a branch a kept worktree has checked out;
+  the default branch, the base branch, a protected branch and a branch a kept worktree has checked out; a
+  Landed branch the main checkout has checked out, clean and with nothing paused, with git switch to the base;
   a branch whose work is on no commit of the base, with the forced delete.
 It never changes anything on a remote: the fetch only writes remote-tracking refs. A removal git refuses is
 kept with git's words, and the sweep goes on.
@@ -91,11 +92,6 @@ function baseOf(root, head) {
     }
     return { name, ref };
 }
-function branchesOf(root) {
-    return must(root, ["for-each-ref", "--format=%(refname:lstrip=2)", "refs/heads"])
-        .split("\n")
-        .filter((name) => name !== "");
-}
 /** Why the worktree stays, with the dev's command when there is one, or null when its whole set passes. */
 function whyTreeStays(root, baseRef, tree, lock, holders) {
     const { path } = tree;
@@ -194,8 +190,9 @@ function judge(root, terminals) {
         }
         judged.add(name);
         const why = stays(name, footing);
+        const off = why?.dev === true && held.get(name) === checkout.path ? switchOff(root, base, name) : null;
         if (why !== null) {
-            kept.push({ kind: "branch", name, ...why });
+            kept.push({ kind: "branch", name, ...why, ...off });
         }
         else if (isLanded(root, base.ref, name)) {
             removed.push({ kind: "branch", name, reason: `Landed on ${baseName}` });

package/dist/markdown.d.ts

@@ -12,6 +12,8 @@ export type Link = {
     target: string;
     line: number;
 };
+/** The 1-based line of the code fence `text` leaves open at its end; none when every fence closes. */
+export declare function openFence(text: string): number | undefined;
 /** Every ATX heading in `text`, a repeated anchor numbered `-1`, `-2` as GitHub numbers it. */
 export declare function headings(text: string): Heading[];
 /**

package/dist/markdown.js

@@ -13,15 +13,24 @@ function scan(text) {
         const marker = FENCE.exec(line)?.[1];
         if (fence === undefined && marker !== undefined) {
             fence = marker;
-            return { text: line, line: index + 1, fenced: true };
+            return { text: line, line: index + 1, fenced: true, edge: "open" };
         }
         if (fence !== undefined && marker !== undefined && marker[0] === fence[0] && marker.length >= fence.length) {
             fence = undefined;
-            return { text: line, line: index + 1, fenced: true };
+            return { text: line, line: index + 1, fenced: true, edge: "close" };
         }
         return { text: line, line: index + 1, fenced: fence !== undefined };
     });
 }
+/** The 1-based line of the code fence `text` leaves open at its end; none when every fence closes. */
+export function openFence(text) {
+    const lines = scan(text);
+    const last = lines.at(-1);
+    if (last === undefined || !last.fenced || last.edge === "close") {
+        return undefined;
+    }
+    return lines.findLast(({ edge }) => edge === "open")?.line;
+}
 /**
  * GitHub's anchor for a heading: its text as rendered, lowercased, every character but a letter, a
  * digit, a space, `-` and `_` dropped, each space a hyphen.

package/dist/primitives-diff.d.ts

@@ -0,0 +1,31 @@
+export type PrimitiveClass = "removes" | "adds" | "extends";
+export type Change = {
+    id: string;
+    name: string;
+    class: PrimitiveClass;
+    /** The changed files the Primitive owns. */
+    files: number;
+    summary: string;
+    /** Each `docs` entry, and whether the diff changes its file, whatever its anchor. */
+    docs: {
+        entry: string;
+        touched: boolean;
+    }[];
+};
+export type PrimitivesDiff = {
+    base: string;
+    primitives: Change[];
+    outside: number;
+};
+/** Why a diff cannot be answered: each problem with its remedy. */
+export type Refusal = {
+    problems: string[];
+};
+/**
+ * The Primitives `base...HEAD` removes, adds and extends. The catalogue's path comes from the config of
+ * the checkout; the catalogue is read at `HEAD` and at the merge-base, from the commits and not the tree.
+ * A file's owners are the nearest entries of the catalogue it is read against, as `--paths` answers.
+ */
+export declare function primitivesDiff(root: string, base: string): PrimitivesDiff | Refusal;
+/** The markdown block between its markers, which a later run replaces whole. */
+export declare function blockOf({ primitives, outside }: PrimitivesDiff): string;