dw-sdlc 0.21.0 → 0.21.1

package/dist/checks/skill-sections.js

@@ -3,10 +3,10 @@
 // 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 { CannotRun } from "../cannot-run.js";
 import { readCatalogue } from "../catalogue.js";
 import { headings, openFence, prose } from "../markdown.js";
-import { CannotRun } from "./check.js";
+import {} from "./check.js";
 import { catalogueFile } from "./primitives.js";
 import { matching, treeFiles } from "./tree.js";
 /** Either marker of a part: `/` before `README.md` closes it. */
@@ -111,41 +111,33 @@ function render(root, path, sources) {
     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) {
+/** The docs entries of the catalogue `gate` points at, each read from the root; it is read on the first call. */
+function listedDocs(root, gate) {
     let listed;
     return () => {
         if (listed === undefined) {
-            const file = catalogueFile(resolveConfig(root).config.gate.checks);
+            const file = catalogueFile(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
-                });
+                throw new CannotRun("the catalogue does not exist, and a skill holds a part", REMEDIES.missing, { file });
             }
             if (read.state === "invalid") {
-                throw new CannotRun({
-                    file,
-                    message: "the catalogue is not valid, and a skill holds a part",
-                    remedy: REMEDIES.invalid
-                });
+                throw new CannotRun("the catalogue is not valid, and a skill holds a part", REMEDIES.invalid, { file });
             }
             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() };
+function renderAll(root, { files }, gate) {
+    const sources = { listed: listedDocs(root, gate), 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);
+function write(root, options, gate) {
+    const changed = renderAll(root, options, gate).filter(({ rendered }) => rendered.rewritten > 0);
     for (const { path, rendered } of changed) {
         writeFileSync(join(root, path), rendered.text);
     }
@@ -158,6 +150,6 @@ function write(root, options) {
 export const skillSections = {
     name: "skill-sections",
     defaults: { files: ["**/skills/**/*.md"] },
-    run: (root, options) => renderAll(root, options).flatMap(({ rendered }) => rendered.findings),
+    run: (root, options, gate) => renderAll(root, options, gate).flatMap(({ rendered }) => rendered.findings),
     write
 };

package/dist/checks/tree.js

@@ -2,18 +2,18 @@
 // pick out of them: what the Checks that judge many files read, so a file git ignores is never judged.
 import { existsSync, lstatSync, realpathSync } from "node:fs";
 import { join, matchesGlob, posix, relative } from "node:path";
-import { exec } from "../exec.js";
-import { CannotRun } from "./check.js";
+import { CannotRun } from "../cannot-run.js";
+import { git } from "../git.js";
 /** Every file under `pathspecs`, the whole tree when there are none, that git tracks or would track and that is on disk; sorted. */
 export function treeFiles(root, pathspecs = []) {
-    const args = ["-C", root, "ls-files", "-z", "--cached", "--others", "--exclude-standard", "--", ...pathspecs];
-    const listed = exec("git", args);
-    if (listed.status !== 0) {
+    const args = ["ls-files", "-z", "--cached", "--others", "--exclude-standard", "--", ...pathspecs];
+    const listed = git(root, args, { raw: true });
+    if ("error" in listed) {
         const under = pathspecs.length === 0 ? "" : ` under ${pathspecs.join(", ")}`;
         const message = `cannot list the files${under}: not a git repository`;
-        throw new CannotRun({ message, remedy: "run the Gate inside a git repository" });
+        throw new CannotRun(message, "run the Gate inside a git repository");
     }
-    return [...new Set(listed.stdout.split("\0").filter((path) => path !== ""))]
+    return [...new Set(listed.out.split("\0").filter((path) => path !== ""))]
         .filter((path) => existsSync(join(root, path)))
         .toSorted();
 }

package/dist/cli.d.ts

@@ -1,2 +1,3 @@
 #!/usr/bin/env node
-export {};
+/** `dw-sdlc <argv>`: the command's exit code, or 2 with its line when it throws `CannotRun`. */
+export declare function dispatch(argv: string[]): number | Promise<number>;

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 // The `dw-sdlc` bin: one row per subcommand, each a module under `commands/`. A plugin's hook or skill
 // reaches it through the plugin's `dw-sdlc` link.
+import { CannotRun, messageOf } from "./cannot-run.js";
 import * as check from "./commands/check.js";
 import * as config from "./commands/config.js";
 import * as doctor from "./commands/doctor.js";
@@ -40,7 +41,13 @@ function usage() {
     const rows = [...COMMANDS].map(([name, { summary }]) => `  ${name.padEnd(width)}${summary}`);
     return `Usage: dw-sdlc <command> [options]\n\nCommands:\n${rows.join("\n")}\n\nRun dw-sdlc <command> --help for its options.`;
 }
-async function main(argv) {
+/** What the bin prints for `error`, which stopped `command`: the problem, its remedy, the lines after it. */
+function stopText(command, { message, remedy, detail }) {
+    const line = `dw-sdlc ${command}: ${message}${remedy === undefined ? "" : ` — ${remedy}`}\n`;
+    return detail.after === undefined ? line : `${line}${detail.after}\n`;
+}
+/** `dw-sdlc <argv>`: the command's exit code, or 2 with its line when it throws `CannotRun`. */
+export function dispatch(argv) {
     const [first, second] = argv;
     if (first === "--help" || first === "-h") {
         process.stdout.write(`${usage()}\n`);
@@ -48,21 +55,35 @@ async function main(argv) {
     }
     // A two-word name, as `references sync`, before its first word alone.
     const words = second !== undefined && COMMANDS.has(`${first} ${second}`) ? 2 : 1;
-    const command = COMMANDS.get(argv.slice(0, words).join(" "));
+    const name = argv.slice(0, words).join(" ");
+    const command = COMMANDS.get(name);
     if (command === undefined) {
         const problem = first === undefined ? "no command given" : `unknown command ${JSON.stringify(first)}`;
         process.stderr.write(`dw-sdlc: ${problem}\n\n${usage()}\n`);
         return 2;
     }
-    return command.run(argv.slice(words));
+    const stopped = (error) => {
+        if (!(error instanceof CannotRun)) {
+            throw error;
+        }
+        process.stderr.write(stopText(name, error));
+        return 2;
+    };
+    try {
+        const code = command.run(argv.slice(words));
+        return typeof code === "number" ? code : code.catch(stopped);
+    }
+    catch (error) {
+        return stopped(error);
+    }
 }
 if (import.meta.main) {
     try {
-        process.exitCode = await main(process.argv.slice(2));
+        process.exitCode = await dispatch(process.argv.slice(2));
     }
     catch (error) {
         // What no command answered for stopped it before a verdict: exit 1 would read as one.
-        process.stderr.write(`dw-sdlc: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.stderr.write(`dw-sdlc: ${messageOf(error)}\n`);
         process.exitCode = 2;
     }
 }

package/dist/commands/check.js

@@ -1,7 +1,6 @@
 // `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, resolveConfig } from "../agentic-config.js";
-import { CannotRun } from "../checks/check.js";
+import { CannotRun, readArgs, rootDir, usageError } from "../cannot-run.js";
 import { CHECK_NAMES, shippedCheck } from "../checks/index.js";
 import { TAIL_LINES } from "../run-command.js";
 import { printReport, runGate } from "./gate.js";
@@ -23,49 +22,45 @@ 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.
 
-Exit 0 when the Check passes, 1 when it fails, 2 when it cannot run: no Check of that name, an
-invalid config layer, a command the shell cannot find or execute, or an input the Check reads
-missing.`;
+Exit 0 when the Check passes, 1 when it fails, 2 when it cannot run: a --root that names no
+directory, no Check of that name, an invalid config layer, a command the shell cannot find or
+execute, or an input the Check reads missing.`;
 function parseCli(argv) {
-    try {
-        const { values, positionals } = parseArgs({
-            args: argv,
-            allowPositionals: true,
-            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 ")}` };
+    const { values, positionals } = readArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            help: { type: "boolean", short: "h" },
+            json: { type: "boolean" },
+            write: { type: "boolean" },
+            root: { type: "string" }
         }
-        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) };
+    }, USAGE);
+    if (positionals.length > 1) {
+        const names = positionals.map((name) => JSON.stringify(name)).join(" and ");
+        throw usageError(`one Check at a time, not ${names}`, USAGE);
     }
+    const flags = { help: values.help === true, json: values.json === true, write: values.write === true };
+    return { ...flags, root: values.root, name: positionals[0] };
 }
 /**
  * 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.
+ * wrote; stops the command 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;
+        return;
     }
-    const shipped = shippedCheck(name, config.gate.checks[name]);
+    const shipped = shippedCheck(name, config.gate);
     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;
+        return;
     }
     const write = shipped?.write;
     if (write === undefined) {
-        return `${JSON.stringify(name)} takes no --write: it derives no file`;
+        throw new CannotRun(`${JSON.stringify(name)} takes no --write: it derives no file`);
     }
     try {
         const out = json ? process.stderr : process.stdout;
@@ -76,30 +71,20 @@ function writeDerived(root, name, json) {
             throw error;
         }
     }
-    return undefined;
 }
 export async function run(argv) {
     const cli = parseCli(argv);
-    if ("error" in cli) {
-        process.stderr.write(`dw-sdlc check: ${cli.error}\n\n${USAGE}\n`);
-        return 2;
-    }
     if (cli.help) {
         process.stdout.write(`${USAGE}\n`);
         return 0;
     }
     if (cli.name === undefined) {
-        process.stderr.write(`dw-sdlc check: name the Check to run\n\n${USAGE}\n`);
-        return 2;
+        throw usageError("name the Check to run", USAGE);
     }
     const { json, name } = cli;
-    const root = repositoryRoot(cli.root ?? process.cwd());
+    const root = repositoryRoot(rootDir(cli.root));
     if (cli.write) {
-        const refused = writeDerived(root, name, json);
-        if (refused !== undefined) {
-            process.stderr.write(`dw-sdlc check: ${refused}\n`);
-            return 2;
-        }
+        writeDerived(root, name, json);
     }
     const report = await runGate(root, { json, only: name });
     return printReport(report, json, `check ${name}`);

package/dist/commands/config.js

@@ -1,37 +1,31 @@
 // `dw-sdlc config`, the config check: resolves a repository's agentic config, or validates one file
 // against the schema, and prints what the guards see.
 import { readFileSync } from "node:fs";
-import { parseArgs } from "node:util";
-import { COMMITTED_FILE, findRepository, LOCAL_FILE, repositoryRoot, resolveConfig, validateDocument } from "../agentic-config.js";
+import { COMMITTED_FILE, findRepository, invalidLayerEffect, LOCAL_FILE, repositoryRoot, resolveConfig, validateDocument } from "../agentic-config.js";
+import { messageOf, readArgs, rootDir, usageError } from "../cannot-run.js";
 export const summary = "resolve the repository's agentic config, or validate one file against the schema";
 const USAGE = `Usage: dw-sdlc config [--root <dir>] [file]
   or:  pnpm agentic:check [--root <dir>] [file], in a checkout of dw-sdlc
 
 Without a file: resolves the agentic config of the repository holding --root (default: the current
 directory) — local over committed over inferred — and prints what the guards see. With a file:
-validates that one document against the schema. Exit 1 on any problem.`;
-function messageOf(error) {
-    return error instanceof Error ? error.message : String(error);
-}
-function fail(message, code) {
-    console.error(`agentic:check: ${message}`);
-    process.exit(code);
+validates that one document against the schema. Exit 1 on any problem, 2 when --root names no
+directory.`;
+/** A problem the check reports beside the config's own: exit 1, as for an invalid layer. */
+function failed(message) {
+    console.error(`dw-sdlc config: ${message}`);
+    return 1;
 }
 function parseCli(argv) {
-    try {
-        const { values, positionals } = parseArgs({
-            args: argv,
-            allowPositionals: true,
-            options: { help: { type: "boolean", short: "h" }, root: { type: "string" } }
-        });
-        if (positionals.length > 1) {
-            throw new Error("at most one file");
-        }
-        return { help: values.help === true, root: values.root, file: positionals[0] };
-    }
-    catch (error) {
-        fail(`${messageOf(error)}\n\n${USAGE}`, 2);
+    const { values, positionals } = readArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { help: { type: "boolean", short: "h" }, root: { type: "string" } }
+    }, USAGE);
+    if (positionals.length > 1) {
+        throw usageError("at most one file", USAGE);
     }
+    return { help: values.help === true, root: values.root, file: positionals[0] };
 }
 function report(problems) {
     for (const { file, path, message } of problems) {
@@ -50,7 +44,7 @@ export function run(argv) {
             text = readFileSync(cli.file, "utf8");
         }
         catch (error) {
-            fail(messageOf(error), 1);
+            return failed(messageOf(error));
         }
         const result = validateDocument(cli.file, text);
         if ("problems" in result) {
@@ -60,9 +54,10 @@ export function run(argv) {
         console.log(`${cli.file}: valid`);
         return 0;
     }
-    const root = cli.root === undefined
-        ? (findRepository(process.cwd()) ?? fail("not inside a git repository; pass --root <dir>", 1))
-        : repositoryRoot(cli.root);
+    const root = cli.root === undefined ? findRepository(process.cwd()) : repositoryRoot(rootDir(cli.root));
+    if (root === undefined) {
+        return failed("not inside a git repository; pass --root <dir>");
+    }
     const { config, problems, layers, sources } = resolveConfig(root);
     const from = (source) => source === undefined || source === root ? "" : `, from ${source}`;
     console.log(`committed  ${COMMITTED_FILE}  ${layers.committed}${from(sources.committed)}`);
@@ -70,7 +65,7 @@ export function run(argv) {
     console.log(JSON.stringify(config, null, 2));
     if (problems.length > 0) {
         report(problems);
-        fail(`${problems.length} problem(s) above; the guards run on the strictest defaults until the file is fixed`, 1);
+        return failed(`${problems.length} problem(s) above; ${invalidLayerEffect(config)} until the file is fixed`);
     }
     return 0;
 }

package/dist/commands/doctor.d.ts

@@ -20,6 +20,8 @@ export type RepositoryConfig = {
     config: {
         commit: {
             convention?: string;
+            pattern?: string;
+            trailer?: string;
         };
     };
     problems: string[];

package/dist/commands/doctor.js

@@ -4,10 +4,10 @@
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { parseArgs } from "node:util";
-import { findRepository, resolveConfig } from "../agentic-config.js";
+import { findRepository, invalidLayerEffect, resolveConfig } from "../agentic-config.js";
+import { readArgs, rootDir } from "../cannot-run.js";
 import { checkPackage, checkPlugin, checkSessions, parseJson, runningPluginRoot, sessionsEnabled, versionBefore } from "../doctor-plugins.js";
-import { exec, TimedOut } from "../exec.js";
+import { exec, firstLine, TimedOut } from "../exec.js";
 import { isObject } from "../json-text.js";
 /** Claude Code's config dir: `$CLAUDE_CONFIG_DIR` when set, the way Claude Code reads it, else `~/.claude`. */
 export function claudeConfigDir(env, home) {
@@ -39,7 +39,7 @@ export const realProbe = {
     shell(script) {
         const shell = process.env.SHELL ?? "/bin/sh";
         const result = probed(shell, ["-l", "-c", script]);
-        return (result?.stdout ?? "").trim().split("\n")[0] ?? "";
+        return firstLine(result?.stdout ?? "") ?? "";
     }
 };
 function checkJq(probe) {
@@ -213,7 +213,7 @@ function checkConfig(config, root) {
         return {
             name: "config",
             level: "FAIL",
-            detail: `the guards run on the strictest defaults: ${config.problems.join("; ")}`
+            detail: `${invalidLayerEffect(config.config)}: ${config.problems.join("; ")}`
         };
     }
     // A worktree that lacks a layer reads the main checkout's; say so, since the file is not here.
@@ -250,7 +250,7 @@ const USAGE = `Usage: dw-sdlc doctor [--root <dir>] [--home <dir>]
   or:  pnpm guardrails:doctor [--root <dir>] [--home <dir>], in a checkout of dw-sdlc
 
 One PASS / WARN / FAIL line per machine check the sdlc plugin relies on; read-only. Exit 1 when any
-check fails. Claude Code's settings are read from $CLAUDE_CONFIG_DIR, or ~/.claude without it; a
+check fails, 2 when --root names no directory. Claude Code's settings are read from $CLAUDE_CONFIG_DIR, or ~/.claude without it; a
 --home reads <home>/.claude.`;
 function repositoryConfig(root) {
     const resolution = resolveConfig(root);
@@ -261,22 +261,15 @@ function repositoryConfig(root) {
     };
 }
 export function run(argv) {
-    let values;
-    try {
-        values = parseArgs({
-            args: argv,
-            options: { help: { type: "boolean", short: "h" }, root: { type: "string" }, home: { type: "string" } }
-        }).values;
-    }
-    catch (error) {
-        console.error(`guardrails:doctor: ${error instanceof Error ? error.message : String(error)}\n\n${USAGE}`);
-        return 2;
-    }
+    const { values } = readArgs({
+        args: argv,
+        options: { help: { type: "boolean", short: "h" }, root: { type: "string" }, home: { type: "string" } }
+    }, USAGE);
     if (values.help === true) {
         console.log(USAGE);
         return 0;
     }
-    const dir = values.root ?? process.cwd();
+    const dir = rootDir(values.root);
     const root = findRepository(dir);
     const checks = diagnose({
         root: root ?? dir,

package/dist/commands/gate.js

@@ -1,8 +1,8 @@
 // `dw-sdlc gate`: the Gate of a repository, from the `gate` key of its resolved agentic config. The
 // run and the report serve `dw-sdlc check` too, which judges one Check of it.
-import { parseArgs } from "node:util";
 import { repositoryRoot, resolveConfig, stepCommand, stepHint } from "../agentic-config.js";
-import { CannotRun } from "../checks/check.js";
+import { CannotRun, messageOf, readArgs, rootDir, usageError } from "../cannot-run.js";
+import { findingOf } from "../checks/check.js";
 import { CHECK_NAMES, enabledChecks, shippedCheck } from "../checks/index.js";
 import { watchDrift } from "../drift.js";
 import { fingerprint, isGreen, stampGreen } from "../gate-cache.js";
@@ -29,10 +29,12 @@ changed or deleted is Drift, one failure per file, and the Steps after it still
 and edits made before the run never drift, and a Step a signal stopped is not compared. gate.drift
 "allow" turns the watch off.
 
-SIGINT or SIGTERM sent while a command runs stops it and everything after it, and the report still
-prints: the stopped command's last lines, its failure line and the last line. A command that SIGINT
-or SIGTERM ends stops everything after it the same way, as Ctrl-C reaches it and the Gate together. A
-second signal, or one sent while the Checks the package ships run, ends the Gate at once.
+Each command runs in a process group of its own, which every process it starts joins. SIGINT or
+SIGTERM sent while a command runs reaches that whole group and stops everything after it, and the
+report still prints: the stopped command's last lines, its failure line and the last line. A command
+that SIGINT or SIGTERM ends stops everything after it the same way. A second signal ends the Gate at
+once and kills the command's group; one sent while the Checks the package ships run ends the Gate at
+once. SIGHUP reaches the command's group and ends the Gate.
 
 --verbose passes each command's output through as it runs instead, under a line naming the command,
 and keeps no tail. --json prints the document alone; each Step and Check in it carries tail, the last
@@ -48,8 +50,9 @@ Untracked files count and ignored files do not. Each worktree keeps its own stam
 hash runs the whole Gate.
 
 Exit 0 when everything passes, 1 when a Step or a Check fails or a Step drifts, 2 when the Gate
-cannot run: an invalid config layer, a Step or Check whose command the shell cannot find or execute,
-a Check missing an input it reads, or a tree it cannot record for Drift.`;
+cannot run: a --root that names no directory, an invalid config layer, a Step or Check whose command
+the shell cannot find or execute, a Check missing an input it reads, or a tree it cannot record for
+Drift.`;
 const EXIT_CODES = { pass: 0, fail: 1, error: 2 };
 const SKIPPED = { status: "skipped", exitCode: null, tail: null };
 const SILENT = { write: () => true };
@@ -72,30 +75,25 @@ function plural(count, noun) {
     return `${count} ${noun}${count === 1 ? "" : "s"}`;
 }
 function parseCli(argv) {
-    try {
-        const { values } = parseArgs({
-            args: argv,
-            options: {
-                help: { type: "boolean", short: "h" },
-                json: { type: "boolean" },
-                verbose: { type: "boolean" },
-                root: { type: "string" },
-                "update-baseline": { type: "boolean" },
-                cache: { type: "boolean" }
-            }
-        });
-        const refresh = values["update-baseline"] === true;
-        const cache = values.cache === true;
-        if (refresh && cache) {
-            return { error: "--cache and --update-baseline do not combine: a refresh needs the Gate to run" };
+    const { values } = readArgs({
+        args: argv,
+        options: {
+            help: { type: "boolean", short: "h" },
+            json: { type: "boolean" },
+            verbose: { type: "boolean" },
+            root: { type: "string" },
+            "update-baseline": { type: "boolean" },
+            cache: { type: "boolean" }
         }
-        const mode = refresh ? "update-baseline" : cache ? "cache" : "plain";
-        const flags = { help: values.help === true, json: values.json === true, verbose: values.verbose === true };
-        return { ...flags, root: values.root, mode };
-    }
-    catch (error) {
-        return { error: error instanceof Error ? error.message : String(error) };
+    }, USAGE);
+    const refresh = values["update-baseline"] === true;
+    const cache = values.cache === true;
+    if (refresh && cache) {
+        throw usageError("--cache and --update-baseline do not combine: a refresh needs the Gate to run", USAGE);
     }
+    const mode = refresh ? "update-baseline" : cache ? "cache" : "plain";
+    const flags = { help: values.help === true, json: values.json === true, verbose: values.verbose === true };
+    return { ...flags, root: values.root, mode };
 }
 function configFailure({ file, path, message }) {
     const where = path === "" ? message : `${path}: ${message}`;
@@ -164,8 +162,8 @@ function progressOf(options, log) {
 /** What a Check that threw reports: the input it lacks, or what stopped it. */
 function erred(check, error) {
     const finding = error instanceof CannotRun
-        ? error.finding
-        : { message: `stopped: ${error instanceof Error ? error.message : String(error)}`, remedy: REMEDIES.checkStopped };
+        ? findingOf(error, REMEDIES.checkStopped)
+        : { message: `stopped: ${messageOf(error)}`, remedy: REMEDIES.checkStopped };
     return {
         check,
         outcome: { status: "error", exitCode: EXIT_CODES.error, tail: null },
@@ -209,7 +207,8 @@ function refreshBaselines(judged, others, root) {
         }
         catch (error) {
             if (error instanceof CannotRun) {
-                notes.push(`gate: baseline ${file} not refreshed — ${error.finding.message}; ${error.finding.remedy}`);
+                const { message, remedy } = findingOf(error, REMEDIES.checkStopped);
+                notes.push(`gate: baseline ${file} not refreshed — ${message}; ${remedy}`);
             }
             else {
                 judged[index] = erred(check, error);
@@ -229,10 +228,10 @@ function worst(outcomes) {
  */
 function select(gate, only) {
     if (only === undefined) {
-        return { steps: gate.steps, run: gate.checks.run, shipped: enabledChecks(gate.checks) };
+        return { steps: gate.steps, run: gate.checks.run, shipped: enabledChecks(gate) };
     }
     const scripts = gate.checks.run.filter((check) => check.name === only);
-    const shipped = shippedCheck(only, gate.checks[only]);
+    const shipped = shippedCheck(only, gate);
     if (scripts.length === 0 && shipped === undefined) {
         const names = [...gate.checks.run.map((check) => check.name), ...CHECK_NAMES].join(", ");
         return { rule: "check", message: `no Check is named ${JSON.stringify(only)}`, remedy: `name one of ${names}` };
@@ -380,15 +379,11 @@ export function printReport(report, json, label) {
 }
 export async function run(argv) {
     const cli = parseCli(argv);
-    if ("error" in cli) {
-        process.stderr.write(`dw-sdlc gate: ${cli.error}\n\n${USAGE}\n`);
-        return 2;
-    }
     if (cli.help) {
         process.stdout.write(`${USAGE}\n`);
         return 0;
     }
     const { json, verbose, mode } = cli;
-    const report = await runGate(repositoryRoot(cli.root ?? process.cwd()), { json, verbose, mode });
+    const report = await runGate(repositoryRoot(rootDir(cli.root)), { json, verbose, mode });
     return printReport(report, json, "gate");
 }