dw-sdlc 0.7.0 → 0.10.0

package/dist/commands/pr-ship.js

@@ -2,24 +2,51 @@
 // needs next, performs it when it is the script's and reads again, then answers the first Action that
 // is not, as a line or one JSON document, with an exit code that names whose turn it is.
 import { parseArgs } from "node:util";
-import { repositoryRoot, resolveConfig } from "../agentic-config.js";
-import { decide, devCommand, hostArgs, isScriptAction, readyToMerge, shellLine } from "../pr/decide.js";
-import { CannotRun, gh, namedProblem, read, readAgain, said } from "../pr/read.js";
+import { repositoryRoot, resolveConfig, REVIEW_DEPTHS } from "../agentic-config.js";
+import { decide, devCommand, hostArgs, isScriptAction, readyToMerge, REVIEW, shellLine } from "../pr/decide.js";
+import { CannotRun, carriesBase, gh, namedProblem, read, readAgain, said } from "../pr/read.js";
 export const summary = "decide the Action one pull request needs next, as a line or JSON";
-const USAGE = `Usage: dw-sdlc pr ship [<n>] [-R owner/name] [--merge] [--dry-run] [--json] [--verbose]
+const USAGE = `Usage: dw-sdlc pr ship [<n>] [-R owner/name] [--merge] [--review full|light|off] [--dry-run] [--json] [--verbose]
 
 Reads pull request <n> through gh, the one of the current branch as gh pr view resolves it when <n>
 is omitted, and answers the Action it needs next: the status, the action, whose turn it is and why.
 The script performs its own Actions, each at most once and then reads again: it updates a branch
 behind its base, marks a draft ready once nothing else holds it back, and squash merges a pull
 request ready to merge under pr.merge auto in .ai/agentic.config.json or with --merge for this call;
-under ask, the default, it parks with the merge command. --dry-run performs nothing: it parks at the
-first Action the script would perform, listed under performed. One line, or one document with
---json; --verbose adds the state as read to the document under facts. Needs an authenticated gh.
+under ask, the default, it parks with the merge command. A head without a ${REVIEW} success
+gets the Review depth --review names for this call, else pr.review: under full the agent reviews it
+with the command pr.reviewCommand names, /code-review by default; under light one sdlc-reviewer
+subagent reads the diff; under off the script posts the success itself, its description saying
+why. Under auto, the default, the script routes the depth from the changes the Review would read:
+lockfiles alone off; a file under .github/workflows/, more than 100 changed lines outside
+lockfiles, or a change it cannot size, more files than GitHub's compare lists or a file outside
+lockfiles with no patch, full; the rest light. After a push it names
+the last reviewed commit under details.since, where the Review reads from and auto routes from. It
+carries that commit's success over a head whose only commits since are merges of the base, unless
+--review names a depth for the call.
+Each Action the call runs is listed under performed. Its ok says whether the read after it shows the
+Action took effect, whatever gh's exit status; gh's exit status and stderr stand beside it, so an ok
+false with exit 0 is an Action gh accepted that the read does not show yet. An update counts when
+the head carries the base it read. When the read after an Action fails, the call exits 2 and names
+each Action that ran with gh's exit, under performed too with --json: it may have landed, so do not
+run it blind again. --dry-run performs nothing: it parks at the first Action the script would
+perform, under performed with ok null.
+One line, or one document with --json; --verbose adds the state as read to the document under
+facts. Needs an authenticated gh.
 
 Exit 0 done, 10 the agent's turn, 20 wait, 30 the dev's turn, 2 when it cannot run.`;
+/** The depths --review takes, strictest first, as a sentence lists them. */
+const DEPTHS_SENTENCE = `${REVIEW_DEPTHS.slice(0, -1).join(", ")} or ${REVIEW_DEPTHS.at(-1)}`;
 const EXIT = { done: 0, act: 10, wait: 20, park: 30 };
 const REMEDIES = { clock: "unset it: it stands in for the clock in tests" };
+/** A call that stopped after it ran Actions: what it ran stands in `performed`, `ok` null where no read followed. */
+class Interrupted extends CannotRun {
+    performed;
+    constructor({ message, remedy }, performed) {
+        super(message, remedy);
+        this.performed = performed;
+    }
+}
 function parseCli(argv) {
     try {
         const { values, positionals } = parseArgs({
@@ -30,12 +57,14 @@ function parseCli(argv) {
                 json: { type: "boolean" },
                 verbose: { type: "boolean" },
                 merge: { type: "boolean" },
+                review: { type: "string" },
                 "dry-run": { type: "boolean" },
                 repo: { type: "string", short: "R" }
             }
         });
         const [number, ...more] = positionals;
         const { repo } = values;
+        const review = REVIEW_DEPTHS.find((depth) => depth === values.review);
         if (values.help !== true) {
             if (more.length > 0) {
                 return { error: `name one pull request, not ${positionals.length}` };
@@ -44,12 +73,16 @@ function parseCli(argv) {
             if (problem !== undefined) {
                 return { error: problem };
             }
+            if (values.review !== undefined && review === undefined) {
+                return { error: `--review takes ${DEPTHS_SENTENCE}, not ${JSON.stringify(values.review)}` };
+            }
         }
         return {
             help: values.help === true,
             json: values.json === true,
             verbose: values.verbose === true,
             merge: values.merge === true,
+            review,
             dryRun: values["dry-run"] === true,
             number: number === undefined ? undefined : Number(number),
             repo
@@ -75,52 +108,98 @@ function now() {
 const NAMED = {
     "update-branch": { would: "update the branch", act: "the update", still: "the branch still reads behind its base" },
     "mark-ready": { would: "mark it ready", act: "the mark-ready", still: "the pull request still reads as a draft" },
+    "mark-reviewed": {
+        would: "mark it reviewed",
+        act: "the mark-reviewed",
+        still: `the head still carries no ${REVIEW} success`
+    },
     merge: { would: "merge it", act: "the merge", still: "the pull request still reads open" }
 };
+/**
+ * Whether the read after a script Action shows it took effect. gh's exit status cannot tell: a reply
+ * lost on the way back exits non-zero after GitHub applied the Action.
+ */
+const TOOK = {
+    // A moved head alone may be a push: the update took effect when the head carries the base it read.
+    "update-branch": (before, after) => after.head !== before.head && carriesBase(before, after),
+    "mark-ready": (_, after) => !after.draft,
+    // The post names the head it read: a head moved since carries none of it.
+    "mark-reviewed": (before, after) => after.head === before.head && after.checks.some((check) => check.name === REVIEW && check.bucket === "pass"),
+    merge: (_, after) => after.state === "MERGED"
+};
+/**
+ * Why an Action that ran comes round again. A head that moved after a mark-reviewed names both heads;
+ * otherwise gh refused it, or accepted it and the read shows nothing yet, or the effect is gone again.
+ */
+function reasonOf({ action, ok, exit, stderr = "" }, pr, ranOn, { act, still }) {
+    if (action === "mark-reviewed" && exit === 0 && ranOn !== undefined && ranOn !== pr.head) {
+        return `${act} posted on ${ranOn.slice(0, 7)}, and the head moved to ${pr.head.slice(0, 7)}`;
+    }
+    if (ok) {
+        return `${act} ran, and ${still}`;
+    }
+    return exit === 0
+        ? `gh accepted ${act}; the read does not show it yet`
+        : `gh refused ${act}: ${said(stderr) || `gh exited ${exit}`}`;
+}
 /** A script Action the call leaves to the dev, `reason` saying why; a merge parks as ready-to-merge. */
-function handedOver(pr, answer, action, reason) {
+function handedOver(pr, policy, answer, action, reason) {
     if (action === "merge") {
-        return { ...readyToMerge(pr, reason), blockers: answer.blockers };
+        return { ...readyToMerge(pr, policy, reason), blockers: answer.blockers };
     }
-    return { ...answer, status: "park", actor: "dev", reason, command: devCommand(pr, action) };
+    return { ...answer, status: "park", actor: "dev", reason, command: devCommand(pr, action, policy) };
 }
 /**
  * Reads and decides until the Action is not the script's. Each script Action runs at most once, then the
  * pull request is read again; under --dry-run, or when an Action comes round again, it is the dev's.
  */
-function ship(cli, merge) {
-    let pr = read(cli, "pr ship");
+function ship(cli, policy) {
+    // Only pr.review auto routes the depth from the changes, so only it reads them.
+    const sized = policy.review.depth === "auto";
+    let pr = read(cli, "pr ship", sized);
     const performed = [];
-    const refusals = {};
+    // The head each Action ran on.
+    const postedOn = new Map();
     for (;;) {
-        const answer = decide(pr, now(), merge);
+        const answer = decide(pr, now(), policy);
         const { action } = answer;
         if (!isScriptAction(action)) {
             return { pr, answer, performed };
         }
         // -R names the repository, so the checkout the script runs in plays no part.
-        const args = hostArgs(pr, action, true);
+        const args = hostArgs(pr, action, policy, true);
         const command = shellLine(["gh", ...args]);
-        const { would, act, still } = NAMED[action];
+        const { would } = NAMED[action];
         if (cli.dryRun) {
             performed.push({ action, command, ok: null });
             return {
                 pr,
-                answer: handedOver(pr, answer, action, `the script would ${would}; --dry-run performs nothing`),
+                answer: handedOver(pr, policy, answer, action, `the script would ${would}; --dry-run performs nothing`),
                 performed
             };
         }
-        if (performed.some((done) => done.action === action)) {
-            const refusal = refusals[action];
-            const reason = refusal === undefined ? `${act} ran, and ${still}` : `gh refused ${act}: ${refusal}`;
-            return { pr, answer: handedOver(pr, answer, action, reason), performed };
+        const done = performed.find((earlier) => earlier.action === action);
+        // --dry-run returns before any Action runs, so an earlier one always carries gh's exit.
+        if (done !== undefined && done.ok !== null) {
+            const reason = reasonOf(done, pr, postedOn.get(action), NAMED[action]);
+            return { pr, answer: handedOver(pr, policy, answer, action, reason), performed };
         }
-        const result = gh(args);
-        performed.push({ action, command, ok: result.status === 0 });
-        if (result.status !== 0) {
-            refusals[action] = said(result.stderr) || `gh exited ${result.status}`;
+        const { status, stderr } = gh(args);
+        const before = pr;
+        const message = stderr.trim();
+        const record = { action, command, exit: status, ...(message === "" ? {} : { stderr: message }) };
+        postedOn.set(action, before.head);
+        try {
+            pr = readAgain(pr, sized);
+            performed.push({ ...record, ok: TOOK[action](before, pr) });
+        }
+        catch (error) {
+            if (error instanceof CannotRun) {
+                // The Action may have landed: the caller must not run it blind again.
+                throw new Interrupted(error, [...performed, { ...record, ok: null }]);
+            }
+            throw error;
         }
-        pr = readAgain(pr);
     }
 }
 /** `<status> <action>: <reason>`, the action dropped when it repeats the status, then the recheck and the command. */
@@ -143,15 +222,25 @@ export function run(argv) {
         process.stdout.write(`${USAGE}\n`);
         return 0;
     }
-    // An invalid config layer resolves to ask, like every other strictest setting.
-    const merge = cli.merge ? "auto" : resolveConfig(repositoryRoot(process.cwd())).config.pr.merge;
+    // An invalid config layer resolves to ask and full, like every other strictest setting.
+    const declared = resolveConfig(repositoryRoot(process.cwd())).config.pr;
+    const policy = {
+        merge: cli.merge ? "auto" : declared.merge,
+        review: cli.review === undefined ? { depth: declared.review, source: "config" } : { depth: cli.review, source: "flag" },
+        reviewCommand: declared.reviewCommand
+    };
     let shipped;
     try {
-        shipped = ship(cli, merge);
+        shipped = ship(cli, policy);
     }
     catch (error) {
         if (error instanceof CannotRun) {
-            process.stderr.write(`dw-sdlc pr ship: ${error.message} — ${error.remedy}\n`);
+            const ran = error instanceof Interrupted ? error.performed : [];
+            const named = ran.map(({ action, ...rest }) => `${action} ran (gh exit ${rest.exit ?? "unknown"})\n`);
+            process.stderr.write(`dw-sdlc pr ship: ${error.message} — ${error.remedy}\n${named.join("")}`);
+            if (cli.json && ran.length > 0) {
+                process.stdout.write(`${JSON.stringify({ error: error.message, remedy: error.remedy, performed: ran }, null, 2)}\n`);
+            }
             return 2;
         }
         throw error;

package/dist/commands/references-sync.js

@@ -6,6 +6,7 @@ import { existsSync, linkSync, mkdirSync, readdirSync, readFileSync, renameSync,
 import { extname, join } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
 import { parseArgs } from "node:util";
+import { repositoryFreeEnv } from "../git-env.js";
 import { readPins, resolveRef } from "../pins.js";
 import { REFERENCES_FILE, readReferences } from "../references-key.js";
 import { renderBlock, withBlock } from "../router-block.js";
@@ -133,13 +134,11 @@ async function lock(root, seconds) {
         rmSync(own, { force: true });
     }
 }
-/** The variables that tie git to one repository, as git itself lists them. */
-const REPOSITORY_VARS = new Set((spawnSync("git", ["rev-parse", "--local-env-vars"], { encoding: "utf8" }).stdout ?? "").split("\n").filter(Boolean));
 function git(args, cwd) {
-    // Each call finds its repository from `cwd`: the GIT_DIR a git hook exports would aim it at the
-    // hook's repository. A missing credential fails the fetch instead of waiting on a prompt nobody sees.
-    const env = Object.fromEntries(Object.entries(process.env).filter(([name]) => !REPOSITORY_VARS.has(name)));
-    const result = spawnSync("git", args, { cwd, encoding: "utf8", env: { ...env, GIT_TERMINAL_PROMPT: "0" } });
+    // Each call finds its repository from `cwd`. A missing credential fails the fetch instead of waiting
+    // on a prompt nobody sees.
+    const env = { ...repositoryFreeEnv(), GIT_TERMINAL_PROMPT: "0" };
+    const result = spawnSync("git", args, { cwd, encoding: "utf8", env });
     // git's error on one line, so each Reference stays one line of the report.
     const err = (result.stderr ?? "")
         .split("\n")

package/dist/commands/setup.d.ts

@@ -21,6 +21,8 @@ export type SetupOptions = {
     commitOnProtected?: CommitOnProtected | undefined;
     /** The owner's yes to pinning dw-sdlc as a devDependency where package.json lacks it. */
     addPackage?: boolean;
+    /** The PATH the setup looks for `cswap` on; `$PATH` when absent. */
+    path?: string | undefined;
 };
 export declare const summary = "adopt the Gate where asked, and write this machine's local config layer, the git excludes and the permission rules";
 /**

package/dist/commands/setup.js

@@ -11,6 +11,7 @@ import { COMMIT_CONVENTIONS, COMMITTED_FILE, DEFAULT_GUARDRAILS, LOCAL_FILE, SCH
 import { isObject, parseObject, render } from "../json-text.js";
 import { withGate, withPackage } from "../setup-gate.js";
 import { GLOBAL_DENY, LEASE_RULE, RETIRED_DENY, repositoryDeny } from "../setup-rules.js";
+import { keptWorker, pinnedWorker } from "../setup-worker.js";
 export const summary = "adopt the Gate where asked, and write this machine's local config layer, the git excludes and the permission rules";
 const USAGE = `Usage: dw-sdlc setup [--root <dir>] [--home <dir>]
        [--convention <preset>] [--force-push deny|ask|lease] [--commit-on-protected deny|allow]
@@ -25,7 +26,9 @@ written only when it would change; --convention ticket-key | conventional pins c
 the local config, and a run without it keeps the pin as it is; a guardrails block in the local config
 is kept, and --force-push and --commit-on-protected pin those two keys in it, refused where they would
 loosen what the committed config sets; --force overwrites a local config that differs in anything
-else; --dry-run reports without writing.
+else; --dry-run reports without writing. Where cswap is on PATH, the local config also gets
+worker.command, the command a Worker starts with: cswap run -- --dangerously-skip-permissions. A
+worker block the file holds is kept as it is, and without cswap nothing is written.
 
 Where the repository has a package.json, the setup adopts the Gate. --add-package pins dw-sdlc
 there as a devDependency, at the version running the setup; a new dependency needs the owner's yes,
@@ -99,12 +102,13 @@ function keptGuardrails(existing) {
 }
 /**
  * A layer without the keys the setup owns: `$schema`, which moves with the clone, a pinned
- * convention, which `--convention` may replace, and a `guardrails` object, which the setup carries
- * and the flags pin keys in. Everything left is someone's content.
+ * convention, which `--convention` may replace, and a `guardrails` and a `worker` object, which the
+ * setup carries and adds keys to. Everything left is someone's content.
  */
 function unowned(layer) {
-    const { $schema: _schema, commit, guardrails, ...other } = layer;
-    const rest = guardrails === undefined || isObject(guardrails) ? other : { ...other, guardrails };
+    const { $schema: _schema, commit, ...other } = layer;
+    const blocks = ["guardrails", "worker"];
+    const rest = Object.fromEntries(Object.entries(other).filter(([key, value]) => !blocks.includes(key) || !isObject(value)));
     if (!isObject(commit) || pinnedConvention(layer) === undefined) {
         return commit === undefined ? rest : { ...rest, commit };
     }
@@ -144,9 +148,9 @@ function sameContent(existing, config) {
 }
 /**
  * The machine's layer: what inference finds, minus every key the committed config already sets, which an
- * inferred key here would override, plus the `guardrails` block the file holds and the convention asked for.
+ * inferred key here would override, plus the `guardrails` and `worker` blocks and the convention asked for.
  */
-function localConfig(root, claudeDir, convention, guardrails) {
+function localConfig(root, claudeDir, convention, guardrails, worker) {
     const inferred = inferConfig(root);
     const committed = committedConfig(root);
     const config = { $schema: schemaReference(claudeDir) };
@@ -160,6 +164,9 @@ function localConfig(root, claudeDir, convention, guardrails) {
     if (guardrails !== undefined) {
         config.guardrails = guardrails;
     }
+    if (worker !== undefined) {
+        config.worker = worker;
+    }
     // Only one asked for, by `--convention` or the file's pin: inference always gives `conventional`, and
     // pinning it here would override a convention the repository commits later.
     if (convention !== undefined) {
@@ -255,12 +262,13 @@ export function setup(options) {
         writer.refuse(LOCAL_FILE, pinned.refusal);
     }
     else {
-        const local = localConfig(checkout, claudeDir, convention, pinned.guardrails);
+        const { worker, detail } = pinnedWorker(keptWorker(existing), options.path ?? process.env.PATH);
+        const local = localConfig(checkout, claudeDir, convention, pinned.guardrails, worker);
         if (localCurrent !== undefined && !sameContent(existing, local) && !options.force) {
             writer.refuse(LOCAL_FILE, "exists with other content; pass --force to overwrite it");
         }
         else {
-            writer.put(LOCAL_FILE, localPath, render(local));
+            writer.put(LOCAL_FILE, localPath, render(local), detail);
         }
     }
     // 2. The exclude entries, appended to whatever the file holds: they keep both local files out of git

package/dist/drift.d.ts

@@ -0,0 +1,17 @@
+import type { Gate } from "./agentic-config.ts";
+import type { Failure } from "./report.ts";
+import { type Status } from "./run-command.ts";
+/** What a Step answered, and one failure per file it created, changed or deleted. */
+export type Watched<T> = {
+    result: T;
+    failures: Failure[];
+};
+/** Steps run under watch, and what the watch found. */
+export type DriftWatch = {
+    /** Runs one Step by `run` between two records of the tree. */
+    step: <T>(command: string, run: () => Promise<T>) => Promise<Watched<T>>;
+    /** `fail` once a Step drifted, `error` once the tree could not be recorded, `pass` otherwise. */
+    status: () => Status;
+};
+/** A watch over the Steps of `gate` at `root`; under `gate.drift: "allow"` it only runs them. */
+export declare function watchDrift(root: string, gate: Gate): DriftWatch;

package/dist/drift.js

@@ -0,0 +1,68 @@
+// Drift: a file a Step creates, changes or deletes while the Gate runs. Before and after each Step the
+// Gate records the tree of every file git tracks or would track, never against HEAD, so an ignored
+// file never drifts and an edit made before the run sits in both records.
+import { stoppedBy } from "./run-command.js";
+import { git, workingTree } from "./working-tree.js";
+const REMEDIES = {
+    drift: "commit the change, or make the Step only read",
+    cannotWatch: 'run the Gate in a git checkout, or set gate.drift to "allow"'
+};
+/** What a letter of `git diff-tree --name-status` did to the file; T is a change of type, as a link to a file. */
+const CHANGES = { A: "created", D: "deleted", M: "changed", T: "changed" };
+/** One failure per file that differs between the trees `before` and `after`, naming `command`. */
+function drifted(root, command, before, after) {
+    if (before === after) {
+        return [];
+    }
+    const diff = git(root, ["diff-tree", "-r", "-z", "--no-renames", "--name-status", before, after]);
+    if ("error" in diff) {
+        return diff;
+    }
+    // NUL-terminated pairs: the letter, then the path, which may hold any byte but NUL.
+    return [...diff.out.matchAll(/([A-Z])\0([^\0]+)\0/g)].map(([, letter = "", file = ""]) => {
+        const message = `${JSON.stringify(command)} ${CHANGES[letter] ?? "changed"} it`;
+        return { file, rule: "drift", message, remedy: REMEDIES.drift };
+    });
+}
+/** A watch over the Steps of `gate` at `root`; under `gate.drift: "allow"` it only runs them. */
+export function watchDrift(root, gate) {
+    let status = "pass";
+    let watching = gate.drift !== "allow";
+    /** The tree after the last Step, the record before the next: nothing runs between two Steps. */
+    let last;
+    /** The one failure of a tree that cannot be recorded; the watch stops there. */
+    const cannotWatch = (command, error) => {
+        watching = false;
+        status = "error";
+        const message = `cannot watch ${JSON.stringify(command)}: ${error}`;
+        return [{ rule: "drift", message, remedy: REMEDIES.cannotWatch }];
+    };
+    const step = async (command, run) => {
+        if (!watching) {
+            return { result: await run(), failures: [] };
+        }
+        const before = last === undefined ? workingTree(root) : { tree: last };
+        const result = await run();
+        if ("error" in before) {
+            return { result, failures: cannotWatch(command, before.error) };
+        }
+        if (stoppedBy() !== undefined) {
+            // A signal cut the Step short and ends the Gate, so nothing is compared after it.
+            return { result, failures: [] };
+        }
+        const after = workingTree(root);
+        if ("error" in after) {
+            return { result, failures: cannotWatch(command, after.error) };
+        }
+        last = after.tree;
+        const found = drifted(root, command, before.tree, after.tree);
+        if ("error" in found) {
+            return { result, failures: cannotWatch(command, found.error) };
+        }
+        if (found.length > 0) {
+            status = "fail";
+        }
+        return { result, failures: found };
+    };
+    return { step, status: () => status };
+}

package/dist/gate-cache.d.ts

@@ -0,0 +1,13 @@
+import type { Gate } from "./agentic-config.ts";
+/** A checkout's fingerprint and the file its last green run is stamped in. */
+export type Fingerprint = {
+    key: string;
+    stampFile: string;
+};
+/** The fingerprint of the checkout at `root` judged by `gate`, or why it has none. */
+export declare function fingerprint(root: string, gate: Gate): Fingerprint | {
+    error: string;
+};
+/** Whether the last green run of this checkout was stamped with this fingerprint. */
+export declare function isGreen({ key, stampFile }: Fingerprint): boolean;
+export declare function stampGreen({ key, stampFile }: Fingerprint): void;

package/dist/gate-cache.js

@@ -0,0 +1,39 @@
+// The Gate's cache. A checkout's fingerprint is its working tree's content and the Gate that judges
+// it. A green run stamps it in the checkout's own git dir, so each worktree keeps its own stamp.
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { packageVersion } from "./package-version.js";
+import { workingTree } from "./working-tree.js";
+const STAMP_FILE = "dw-sdlc-gate.green";
+/** The fingerprint of the checkout at `root` judged by `gate`, or why it has none. */
+export function fingerprint(root, gate) {
+    const found = workingTree(root);
+    if ("error" in found) {
+        return found;
+    }
+    try {
+        const judge = createHash("sha256").update(JSON.stringify({ version: packageVersion(), gate }));
+        return { key: `${found.tree} ${judge.digest("hex")}`, stampFile: join(found.gitDir, STAMP_FILE) };
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) };
+    }
+}
+/** Whether the last green run of this checkout was stamped with this fingerprint. */
+export function isGreen({ key, stampFile }) {
+    try {
+        return readFileSync(stampFile, "utf8").trim() === key;
+    }
+    catch {
+        return false;
+    }
+}
+export function stampGreen({ key, stampFile }) {
+    try {
+        writeFileSync(stampFile, `${key}\n`);
+    }
+    catch {
+        // A stamp that cannot be written only means the next run does not skip.
+    }
+}

package/dist/git-env.d.ts

@@ -0,0 +1,2 @@
+/** This process's environment without the variables that tie git to one repository, as git lists them. */
+export declare function repositoryFreeEnv(): NodeJS.ProcessEnv;

package/dist/git-env.js

@@ -0,0 +1,10 @@
+// The environment a git command runs under to find its repository from its own directory, as a git
+// hook's GIT_DIR or GIT_INDEX_FILE would otherwise aim it at the hook's repository.
+import { spawnSync } from "node:child_process";
+let repositoryVars;
+/** This process's environment without the variables that tie git to one repository, as git lists them. */
+export function repositoryFreeEnv() {
+    repositoryVars ??= new Set((spawnSync("git", ["rev-parse", "--local-env-vars"], { encoding: "utf8" }).stdout ?? "").split("\n").filter(Boolean));
+    const vars = repositoryVars;
+    return Object.fromEntries(Object.entries(process.env).filter(([name]) => !vars.has(name)));
+}

package/dist/markdown.d.ts

@@ -25,6 +25,25 @@ export declare function codeSpans(text: string): string[];
 export declare function prose(text: string): string;
 /** Every link target in the prose of `text`, its angle brackets dropped, with its 1-based line. */
 export declare function links(text: string): Link[];
+/** A value of a frontmatter, with its 1-based line. */
+export type FrontmatterValue = {
+    value: string;
+    line: number;
+};
+/** A top-level key of a frontmatter: the value after its colon, and the items of the block list under it. */
+export type FrontmatterEntry = FrontmatterValue & {
+    items: FrontmatterValue[];
+};
+/**
+ * The top-level keys of the frontmatter `text` opens with, none when it opens with none. A key written
+ * twice is read where it first appears.
+ */
+export declare function frontmatter(text: string): Map<string, FrontmatterEntry>;
+/**
+ * The values a list key names: comma-separated after its colon, in `[…]` or not, or else its items. A comma
+ * inside a glob's `{…}` separates none, and an empty value is dropped.
+ */
+export declare function frontmatterList(key: FrontmatterEntry | undefined): FrontmatterValue[];
 /** The anchors of each markdown file read so far, by path. */
 export type Anchors = Map<string, Set<string>>;
 /** The anchors of the headings of `path` under `root`; none when it is not a file. */

package/dist/markdown.js

@@ -1,6 +1,6 @@
 // The parts of a markdown file the Checks read: its ATX headings with the anchors GitHub gives them,
-// the rows of a table under a heading, its links, and its prose with the code masked; and the anchors
-// of a file on disk. A line inside a fenced code block is never any of them.
+// the rows of a table under a heading, its links, its prose with the code masked and the keys of its
+// frontmatter; and the anchors of a file on disk. A line inside a fenced code block is never any of them.
 import { readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 /** A code fence at any indent, so one inside a list item counts. */
@@ -103,6 +103,50 @@ export function links(text) {
         return targets.map((target) => ({ target: target.replace(/^<(.*)>$/, "$1"), line: index + 1 }));
     });
 }
+/** A scalar as YAML reads it: the text between its quotes, or else the text before a ` #` comment. */
+function scalar(text) {
+    const quoted = /^\s*(["'])(.*?)\1\s*(#.*)?$/.exec(text);
+    return quoted?.[2] ?? text.replace(/(^|\s)#.*$/, "").trim();
+}
+/**
+ * The top-level keys of the frontmatter `text` opens with, none when it opens with none. A key written
+ * twice is read where it first appears.
+ */
+export function frontmatter(text) {
+    const keys = new Map();
+    const lines = text.split("\n");
+    if (lines[0]?.trim() !== "---") {
+        return keys;
+    }
+    let current;
+    for (let index = 1; index < lines.length && lines[index]?.trim() !== "---"; index++) {
+        const line = lines[index] ?? "";
+        const [, name, rest = ""] = /^([\w-]+):(.*)$/.exec(line) ?? [];
+        const item = /^\s*-(?:\s+(.*))?$/.exec(line);
+        if (name !== undefined) {
+            current = keys.has(name) ? undefined : { value: scalar(rest), line: index + 1, items: [] };
+            if (current !== undefined) {
+                keys.set(name, current);
+            }
+        }
+        else if (item !== null) {
+            current?.items.push({ value: scalar(item[1] ?? ""), line: index + 1 });
+        }
+    }
+    return keys;
+}
+/**
+ * The values a list key names: comma-separated after its colon, in `[…]` or not, or else its items. A comma
+ * inside a glob's `{…}` separates none, and an empty value is dropped.
+ */
+export function frontmatterList(key) {
+    if (key === undefined) {
+        return [];
+    }
+    const inline = key.value.replace(/^\[(.*)\]$/, "$1");
+    const values = inline === "" ? key.items : inline.split(/,(?![^{]*\})/).map((value) => ({ value: scalar(value), line: key.line }));
+    return values.filter(({ value }) => value !== "");
+}
 /** The anchors of the headings of `path` under `root`; none when it is not a file. */
 export function anchorsOf(root, path, cache) {
     let anchors = cache.get(path);

package/dist/package-version.d.ts

@@ -0,0 +1,2 @@
+/** This package's version; throws when its manifest names none. */
+export declare function packageVersion(): string;

package/dist/package-version.js

@@ -0,0 +1,13 @@
+// The version of this package, read from its own manifest: one directory above `src/` in the source
+// and above `dist/` in what npm installs.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseObject } from "./json-text.js";
+/** This package's version; throws when its manifest names none. */
+export function packageVersion() {
+    const manifest = parseObject(readFileSync(join(import.meta.dirname, "..", "package.json"), "utf8"));
+    if (typeof manifest?.version !== "string") {
+        throw new Error("dw-sdlc's package.json names no version");
+    }
+    return manifest.version;
+}