dw-sdlc 0.17.0 → 0.18.0

package/README.md

@@ -50,6 +50,20 @@ its `roots` to `maxProseLines` lines of prose, 3 by default.
 `eslint-disable*`, `@ts-expect-error`, `@ts-ignore`, `rubocop:disable` and `noqa`. A reason follows `--`
 on the directive's line, follows an `@ts-` directive, or is a comment on the line above.
 
+`skill-sections` holds each README section a skill copies to its source. A part sits between two
+markers, each on its own line, and `dw-sdlc check skill-sections --write` fills an empty pair:
+
+```md
+<!-- README.md#errors -->
+<!-- /README.md#errors -->
+```
+
+The anchor is GitHub's, and the section runs from its heading to the next heading of its level or
+above, in the `README.md` beside the `skills` directory that holds the file, or beside the file
+outside one. The Check fails a part that differs from its section, a part whose anchor names no
+heading of the README, a part from a section no Primitive in `.ai/primitives.json` names among its
+docs, a marker without its pair, and a code fence that never closes above a marker, which hides it.
+
 ## The Ship script
 
 `dw-sdlc pr ship [<n>] [-R owner/name]` reads one pull request through an authenticated `gh` and
@@ -94,7 +108,7 @@ buys one more Review past it.
 | ------------------ | ------------------------------------------------------------------------------------------ |
 | `gate`             | the Steps of `gate.steps` in order, then every Check under `gate.checks`                   |
 | `check <name>`     | one Check of the Gate by its name, without the Steps and the other Checks                  |
-| `primitives`       | the Primitives that own each path, with their summaries and documents                      |
+| `primitives`       | the Primitives that own each path, or that a change removes, adds or extends               |
 | `setup`            | this machine's local config layer, the git excludes and the permission rules               |
 | `doctor`           | one PASS / WARN / FAIL line per machine check the guardrails rely on                       |
 | `config`           | the resolved agentic config, or one file validated against the schema                      |

package/config/agentic.config.schema.json

@@ -428,6 +428,22 @@
                 }
               },
               "additionalProperties": false
+            },
+            "skill-sections": {
+              "description": "Every README section a skill copies matches its source. A part is the section of the README under the heading with GitHub's anchor `<anchor>`, up to the next heading of its level or above, copied whole between `<!-- README.md#<anchor> -->` and `<!-- /README.md#<anchor> -->`, each on its own line, with a blank line inside each. The README is the `README.md` of the directory that holds the `skills` directory the file is in, or of the file's own directory outside one. A part fails when it differs from its section, when the README has no heading with its anchor, and when no Primitive in the catalogue `primitives` reads names `<README>#<anchor>` among its docs; a marker without its pair fails too. A marker inside code is none, and a code fence that never closes above a marker fails, since it hides that marker. `dw-sdlc check skill-sections --write` writes each part from its section. A repository with no part passes without reading the catalogue; one with a part and no valid catalogue cannot run.",
+              "type": ["boolean", "object"],
+              "properties": {
+                "files": {
+                  "description": "Globs of the skill files, against the files git tracks or would track; `*` and `**` skip a name that starts with a dot. Default `**/skills/**/*.md`.",
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "uniqueItems": true
+                }
+              },
+              "additionalProperties": false
             }
           },
           "additionalProperties": false

package/dist/catalogue.d.ts

@@ -27,6 +27,10 @@ export type CatalogueRead = {
     catalogue: Catalogue;
     text: string;
 };
+/** The catalogue `text` holds, or why it is not one. */
+export declare function parseCatalogue(text: string): Exclude<CatalogueRead, {
+    state: "missing";
+}>;
 /** The catalogue at `file` under `root`, or why there is none to read. */
 export declare function readCatalogue(root: string, file: string): CatalogueRead;
 /**

package/dist/catalogue.js

@@ -34,13 +34,8 @@ const SCHEMA = {
     },
     additionalProperties: false
 };
-/** The catalogue at `file` under `root`, or why there is none to read. */
-export function readCatalogue(root, file) {
-    const path = join(root, file);
-    if (!existsSync(path)) {
-        return { state: "missing" };
-    }
-    const text = readFileSync(path, "utf8");
+/** The catalogue `text` holds, or why it is not one. */
+export function parseCatalogue(text) {
     let parsed;
     try {
         parsed = JSON.parse(text);
@@ -55,6 +50,11 @@ export function readCatalogue(root, file) {
     // The schema above is the runtime twin of `Catalogue`: a document it accepts has this shape.
     return { state: "valid", catalogue: parsed, text };
 }
+/** The catalogue at `file` under `root`, or why there is none to read. */
+export function readCatalogue(root, file) {
+    const path = join(root, file);
+    return existsSync(path) ? parseCatalogue(readFileSync(path, "utf8")) : { state: "missing" };
+}
 /**
  * How near the `code` entry `entry`, a file or a directory, names `path`: the length of the entry when
  * it is the path or a directory above it, -1 when it is neither.

package/dist/checks/check.d.ts

@@ -22,6 +22,8 @@ export type Check<Options extends object> = {
     run: (root: string, options: Options) => Finding[];
     /** Present on a Ratchet. */
     baseline?: Baseline<Options>;
+    /** Present on a Check that derives files from their sources: writes them, says what it wrote. */
+    write?: (root: string, options: Options) => string;
 };
 /** The options `setting` turns the Check on with: the defaults under `true`, an object over them, else off. */
 export declare function optionsOf<Options extends object>(check: Check<Options>, setting: unknown): Options | undefined;

package/dist/checks/decision-records.d.ts

@@ -7,5 +7,20 @@ export type DecisionRecordsOptions = {
     statuses: string[];
     fields: DecisionField[];
 };
+/** The first words of a status that say a record once governed and no longer does. */
+export declare const OUT_OF_FORCE: Set<string>;
+/**
+ * The `status` of the frontmatter `text` opens with, its quotes dropped, and its 1-based line. It keeps a
+ * reader apart from `frontmatter`, which a status never goes through: a ` #` is part of it.
+ */
+export declare function statusOf(text: string): {
+    value: string;
+    line: number;
+} | undefined;
+/**
+ * The status of the decision record `path` names, whole, or "" when it has none; undefined when `path` is
+ * no record of `dirs` or is not on disk. A record is a file `<number>-<slug>.md` directly under a directory.
+ */
+export declare function recordStatus(root: string, dirs: string[], path: string): string | undefined;
 export declare const decisionRecords: Check<DecisionRecordsOptions>;
 export {};

package/dist/checks/decision-records.js

@@ -12,6 +12,8 @@ const FIELDS = ["date", "touches", "superseded-by", "amended-by"];
 const RECORD = /^(\d+)-[^/]+\.md$/;
 /** The first words of a status that put a record in force, so it governs the paths under its `touches`. */
 const IN_FORCE = new Set(["accepted", "active"]);
+/** The first words of a status that say a record once governed and no longer does. */
+export const OUT_OF_FORCE = new Set(["deprecated", "superseded"]);
 /** A character that makes a path under `touches` a glob. */
 const GLOB = /[*?[\]{}]/;
 const REMEDIES = {
@@ -37,7 +39,7 @@ function isDirectory(path) {
  * The `status` of the frontmatter `text` opens with, its quotes dropped, and its 1-based line. It keeps a
  * reader apart from `frontmatter`, which a status never goes through: a ` #` is part of it.
  */
-function statusOf(text) {
+export function statusOf(text) {
     const lines = text.split("\n");
     if (lines[0]?.trim() !== "---") {
         return undefined;
@@ -55,6 +57,18 @@ function isDay(value) {
     const date = new Date(`${value}T00:00:00Z`);
     return /^\d{4}-\d{2}-\d{2}$/.test(value) && !Number.isNaN(date.getTime()) && date.toISOString().startsWith(value);
 }
+/**
+ * The status of the decision record `path` names, whole, or "" when it has none; undefined when `path` is
+ * no record of `dirs` or is not on disk. A record is a file `<number>-<slug>.md` directly under a directory.
+ */
+export function recordStatus(root, dirs, path) {
+    const inDirs = dirs.some((dir) => {
+        const prefix = `${dir.replace(/\/+$/, "")}/`;
+        return path.startsWith(prefix) && RECORD.test(path.slice(prefix.length));
+    });
+    const file = join(root, path);
+    return inDirs && existsSync(file) ? (statusOf(readFileSync(file, "utf8"))?.value ?? "") : undefined;
+}
 function judgeDate({ file, keys }) {
     const date = keys.get("date");
     if (date === undefined || date.value === "") {

package/dist/checks/index.d.ts

@@ -7,6 +7,7 @@ export type EnabledCheck = {
         file: string;
         refresh: (root: string) => string;
     };
+    write?: (root: string) => string;
 };
 /** The name of every Check the package ships, in the order the Gate runs them. */
 export declare const CHECK_NAMES: readonly string[];

package/dist/checks/index.js

@@ -10,6 +10,7 @@ import { markdownBudget } from "./markdown-budget.js";
 import { markdownRefs } from "./markdown-refs.js";
 import { primitives } from "./primitives.js";
 import { routedDocs } from "./routed-docs.js";
+import { skillSections } from "./skill-sections.js";
 import { temporalLanguage } from "./temporal-language.js";
 function ship(check) {
     return {
@@ -24,6 +25,10 @@ function ship(check) {
             if (baseline !== undefined) {
                 enabled.baseline = { file: baseline.file, refresh: (root) => baseline.refresh(root, options) };
             }
+            const { write } = check;
+            if (write !== undefined) {
+                enabled.write = (root) => write(root, options);
+            }
             return enabled;
         }
     };
@@ -38,7 +43,8 @@ const SHIPPED = [
     ship(decisionRecords),
     ship(fileSizeRatchet),
     ship(commentBudget),
-    ship(disableDirectives)
+    ship(disableDirectives),
+    ship(skillSections)
 ];
 /** The name of every Check the package ships, in the order the Gate runs them. */
 export const CHECK_NAMES = SHIPPED.map(({ name }) => name);

package/dist/checks/primitives.js

@@ -1,11 +1,12 @@
-// `primitives`: the catalogue says what is true of the tree. Unique ids, a known group, a one-line
-// summary, every code and docs path on disk with its anchor resolving, and every file under the roots
-// named by a Primitive.
+// `primitives`: the catalogue says what is true of the tree. Unique ids that start with their group, a
+// one-line summary, real code and docs paths, no decision record out of force, every file named.
 import { existsSync } from "node:fs";
 import { join } from "node:path";
+import { resolveConfig } from "../agentic-config.js";
 import { CATALOGUE_FILE, primitivesNaming, readCatalogue } from "../catalogue.js";
 import { anchorsOf } from "../markdown.js";
 import { CannotRun, optionsOf } from "./check.js";
+import { decisionRecords, OUT_OF_FORCE, recordStatus } from "./decision-records.js";
 import { treeFiles } from "./tree.js";
 const MAX_SUMMARY = 120;
 /** A file a test runs, never shipped: under a test directory, or named as a test. */
@@ -14,6 +15,8 @@ const REMEDIES = {
     missing: "create it, or point gate.checks.primitives.file at the catalogue",
     shape: "give it the catalogue's shape: version 1, groups of id and name, primitives of id, name, group, summary, code and docs",
     duplicate: "give each Primitive an id of its own",
+    prefix: "start the id with its group and a . or a -, or move the Primitive into the group its id starts with",
+    record: "name the record that replaces it, or drop the entry",
     group: "add the group to groups, or move the Primitive into one listed there",
     summary: `keep the summary to one line of ${MAX_SUMMARY} characters or fewer`,
     path: "fix the path or drop it",
@@ -30,10 +33,13 @@ function lineOf(text, id, nth) {
     return match?.index === undefined ? undefined : text.slice(0, start + match.index).split("\n").length;
 }
 /** What is wrong with one Primitive, declared at `at`: its group, its summary, each code and docs entry. */
-function judge(root, catalogue, primitive, at, cache) {
+function judge(root, catalogue, primitive, at, cache, records) {
     const { id, group, summary, code, docs } = primitive;
     const findings = [];
     const fail = (message, remedy) => findings.push({ ...at, message, remedy });
+    if (!id.startsWith(`${group}.`) && !id.startsWith(`${group}-`)) {
+        fail(`the id ${show(id)} does not start with its group ${show(group)} and a "." or a "-"`, REMEDIES.prefix);
+    }
     if (!catalogue.groups.some((known) => known.id === group)) {
         fail(`${show(id)} is in group ${show(group)}, which groups does not list`, REMEDIES.group);
     }
@@ -55,6 +61,10 @@ function judge(root, catalogue, primitive, at, cache) {
         else if (anchor !== undefined && !anchorsOf(root, path, cache).has(anchor)) {
             fail(`${show(id)} names the doc ${show(entry)}, which has no heading with that anchor`, REMEDIES.anchor);
         }
+        const status = recordStatus(root, records, path);
+        if (status !== undefined && OUT_OF_FORCE.has(status.split(/\s+/)[0] ?? "")) {
+            fail(`${show(id)} names the decision record ${show(entry)}, whose status ${show(status)} is no longer in force`, REMEDIES.record);
+        }
     }
     return findings;
 }
@@ -67,6 +77,7 @@ function run(root, { file, roots }) {
         return read.problems.map((message) => ({ file, message, remedy: REMEDIES.shape }));
     }
     const { catalogue, text } = read;
+    const records = (optionsOf(decisionRecords, resolveConfig(root).config.gate.checks["decision-records"]) ?? decisionRecords.defaults).dirs;
     const findings = [];
     const seen = new Map();
     const cache = new Map();
@@ -82,7 +93,7 @@ function run(root, { file, roots }) {
                 remedy: REMEDIES.duplicate
             });
         }
-        findings.push(...judge(root, catalogue, primitive, at, cache));
+        findings.push(...judge(root, catalogue, primitive, at, cache, records));
     }
     for (const path of treeFiles(root, roots)) {
         if (!TEST_FILE.test(path) && primitivesNaming(catalogue, path).length === 0) {

package/dist/checks/skill-sections.d.ts

@@ -0,0 +1,5 @@
+import { type Check } from "./check.ts";
+export type SkillSectionsOptions = {
+    files: string[];
+};
+export declare const skillSections: Check<SkillSectionsOptions>;

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/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/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;

package/dist/primitives-diff.js

@@ -0,0 +1,123 @@
+// The Primitives a change removes, adds or extends, decided from the paths it changes and the catalogue
+// at both ends of `base...HEAD`: nothing is judged. `dw-sdlc primitives --diff` prints it and `recap`
+// rolls it up for the session's branch.
+import { resolveConfig } from "./agentic-config.js";
+import { parseCatalogue, primitivesNaming } from "./catalogue.js";
+import { catalogueFile } from "./checks/primitives.js";
+import { asked, git } from "./working-tree.js";
+const CLASSES = ["removes", "adds", "extends"];
+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",
+    base: "fetch it, or name a ref that exists",
+    git: "check the repository with git status"
+};
+function refuse(problem, remedy) {
+    return { problems: [`${problem} — ${remedy}`] };
+}
+/** The catalogue `file` holds at `rev`, `missing` when `rev` has no such file. */
+function readAt(root, rev, file) {
+    if (asked(root, ["cat-file", "-e", `${rev}:${file}`]) === undefined) {
+        return { state: "missing" };
+    }
+    const shown = git(root, ["show", `${rev}:${file}`]);
+    return "error" in shown ? { state: "invalid", problems: [shown.error] } : parseCatalogue(shown.out);
+}
+/** The merge-base of `base` and `HEAD`, and the files `base...HEAD` changes: a deleted one and both ends of a rename too. */
+function changeSince(root, base) {
+    const resolved = asked(root, ["rev-parse", "--verify", "--quiet", `${base}^{commit}`]);
+    if (resolved === undefined) {
+        return refuse(`the base ${JSON.stringify(base)} does not resolve to a commit`, REMEDIES.base);
+    }
+    const mergeBase = asked(root, ["merge-base", resolved, "HEAD"]);
+    if (mergeBase === undefined) {
+        return refuse(`the base ${JSON.stringify(base)} shares no history with HEAD`, REMEDIES.base);
+    }
+    const diff = git(root, ["diff", "--name-only", "-z", "--no-renames", mergeBase, "HEAD"]);
+    if ("error" in diff) {
+        return refuse(diff.error, REMEDIES.git);
+    }
+    return { mergeBase, files: diff.out.split("\0").filter((path) => path !== "") };
+}
+/** How many of `files` the Primitive `id` owns in any of `catalogues`. */
+function owned(catalogues, files, id) {
+    return files.filter((file) => catalogues.some((catalogue) => primitivesNaming(catalogue, file).some((primitive) => primitive.id === id))).length;
+}
+function describe(primitive, kind, files, changed) {
+    const docs = primitive.docs.map((entry) => ({ entry, touched: changed.has(entry.split("#")[0] ?? entry) }));
+    return { id: primitive.id, name: primitive.name, class: kind, files, summary: primitive.summary, docs };
+}
+/**
+ * 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 function primitivesDiff(root, base) {
+    const file = catalogueFile(resolveConfig(root).config.gate.checks);
+    const head = readAt(root, "HEAD", file);
+    if (head.state === "missing") {
+        return refuse(`${file}: the catalogue does not exist at HEAD`, REMEDIES.missing);
+    }
+    if (head.state === "invalid") {
+        return { problems: head.problems.map((problem) => `${file}: ${problem} — ${REMEDIES.invalid}`) };
+    }
+    const since = changeSince(root, base);
+    if ("problems" in since) {
+        return since;
+    }
+    const { mergeBase, files } = since;
+    const before = readAt(root, mergeBase, file);
+    if (before.state === "invalid") {
+        const at = `${file} at ${JSON.stringify(base)}`;
+        return { problems: before.problems.map((problem) => `${at}: ${problem} — ${REMEDIES.invalid}`) };
+    }
+    const atBase = before.state === "valid" ? before.catalogue : { version: 1, groups: [], primitives: [] };
+    const atHead = head.catalogue;
+    const changed = new Set(files);
+    const inBase = new Set(atBase.primitives.map(({ id }) => id));
+    const inHead = new Set(atHead.primitives.map(({ id }) => id));
+    const changes = [
+        ...atBase.primitives
+            .filter(({ id }) => !inHead.has(id))
+            .map((primitive) => describe(primitive, "removes", owned([atBase], files, primitive.id), changed)),
+        ...atHead.primitives.flatMap((primitive) => {
+            const kind = inBase.has(primitive.id) ? "extends" : "adds";
+            const count = owned(kind === "adds" ? [atHead] : [atBase, atHead], files, primitive.id);
+            return kind === "adds" || count > 0 ? [describe(primitive, kind, count, changed)] : [];
+        })
+    ];
+    const outside = files.filter((path) => primitivesNaming(atHead, path).length + primitivesNaming(atBase, path).length === 0);
+    const rank = ({ class: kind }) => CLASSES.indexOf(kind);
+    changes.sort((a, b) => rank(a) - rank(b) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    return { base, primitives: changes, outside: outside.length };
+}
+function plural(howMany, word) {
+    return `${howMany} ${word}${howMany === 1 ? "" : "s"}`;
+}
+function cell(text) {
+    return text.replaceAll("|", "\\|");
+}
+/** The markdown block between its markers, which a later run replaces whole. */
+export function blockOf({ primitives, outside }) {
+    const start = "<!-- primitives:start -->";
+    const end = "<!-- primitives:end -->";
+    if (primitives.length === 0) {
+        return [start, "No Primitive changes.", end].join("\n");
+    }
+    const counts = CLASSES.map((kind) => ({ kind, howMany: primitives.filter((change) => change.class === kind).length }));
+    const clauses = counts
+        .filter(({ howMany }) => howMany > 0)
+        .map(({ kind, howMany }, position) => position === 0
+        ? `${kind[0]?.toUpperCase()}${kind.slice(1)} ${plural(howMany, "Primitive")}`
+        : `${kind} ${howMany}`);
+    const rows = primitives.map((change) => `| \`${cell(change.id)}\` (${cell(change.name)}) | ${change.class} | ${change.files} |`);
+    return [
+        start,
+        `**${clauses.join(", ")}.** ${plural(outside, "file")} outside the catalogue.`,
+        "",
+        "| Primitive | Class | Files |",
+        "| --- | --- | --- |",
+        ...rows,
+        end
+    ].join("\n");
+}

package/dist/recap-primitives.d.ts

@@ -0,0 +1,12 @@
+import { type PrimitiveClass } from "./primitives-diff.ts";
+export type Rolled = {
+    id: string;
+    class: PrimitiveClass;
+};
+/** What the rollup read: the Primitives, and why it could not read them when it could not. */
+export type Rollup = {
+    primitives: Rolled[];
+    unread?: string;
+};
+/** `defaultOf` names the default branch and is asked only once the repository has a catalogue and `branch` is no base. */
+export declare function rollup(root: string, branch: string, defaultOf: () => string): Rollup;

package/dist/recap-primitives.js

@@ -0,0 +1,26 @@
+// The Primitives a session's branch changed, for `dw-sdlc recap`: the rollup of `primitives --diff` from
+// the branch's merge-base with `origin/<default>`, ids and classes only. A branch the config protects,
+// the default branch and a repository with no catalogue roll up to none.
+import { resolveConfig } from "./agentic-config.js";
+import { catalogueFile } from "./checks/primitives.js";
+import { primitivesDiff } from "./primitives-diff.js";
+import { asked } from "./working-tree.js";
+/** `defaultOf` names the default branch and is asked only once the repository has a catalogue and `branch` is no base. */
+export function rollup(root, branch, defaultOf) {
+    const { guardrails, gate } = resolveConfig(root).config;
+    if (guardrails.protectedBranches.includes(branch)) {
+        return { primitives: [] };
+    }
+    if (asked(root, ["cat-file", "-e", `HEAD:${catalogueFile(gate.checks)}`]) === undefined) {
+        return { primitives: [] };
+    }
+    const base = defaultOf();
+    if (branch === base) {
+        return { primitives: [] };
+    }
+    const answer = primitivesDiff(root, `origin/${base}`);
+    if ("problems" in answer) {
+        return { primitives: [], unread: answer.problems.join("; ") };
+    }
+    return { primitives: answer.primitives.map(({ id, class: kind }) => ({ id, class: kind })) };
+}

package/dist/run-command.js

@@ -46,8 +46,10 @@ export async function holdingSignals(body) {
         return await body();
     }
     finally {
-        // One turn of the event loop hands a signal that landed after the last command to its handler.
-        await new Promise((resolve) => setImmediate(resolve));
+        // libuv takes a signal at once but hands it to its handler only when the loop next polls, and a
+        // handler released before that poll loses it. The last command's exit is read in a poll and the
+        // first immediate runs right after it, so the second waits for one more poll.
+        await new Promise((resolve) => setImmediate(() => setImmediate(resolve)));
         // The Gate's own signal may still be on its way after a command it ended: the handlers stay, so
         // that signal does not end the Gate before its report.
         if (commandEndedBy === undefined || received !== undefined) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dw-sdlc",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "The Gate and the agentic config of a repository: the dw-sdlc bin with the Gate, the setup, the doctor, the config check, the Sync and setup of References, and the Ship script that drives a pull request to merged; the resolver of the config's layers, its JSON Schema and the validator that reads it.",
   "license": "MIT",
   "repository": {