dw-sdlc 0.21.0 → 0.21.1

package/dist/commands/lead-start.js

@@ -1,8 +1,8 @@
 // `dw-sdlc lead start`: starts the next session as a Lead in a herdr terminal of its own, beside the caller and
 // outliving it, on the command the config names for a Worker, without what makes it unsafe or isolated.
-import { parseArgs } from "node:util";
 import { mainCheckout, repositoryRoot, resolveConfig } from "../agentic-config.js";
-import { describe, lead, refuse, Refusal, wholeNumber } from "../worker/herdr.js";
+import { CannotRun, readArgs, usageError } from "../cannot-run.js";
+import { lead, wholeNumber } from "../worker/herdr.js";
 import { launch, NAME, spaceOf, TAB_WAIT, undelivered } from "../worker/launch.js";
 export const summary = "start the next session as a Lead in a herdr terminal of its own";
 const USAGE = `Usage: dw-sdlc lead start --name <name> --prompt <first message> [--wait <seconds>] [--json]
@@ -33,36 +33,31 @@ const UNSAFE = "--dangerously-skip-permissions";
 /** The flags that put a Claude Code session in a worktree of its own, each taking an optional name. */
 const WORKTREE = new Set(["--worktree", "-w"]);
 function parseCli(argv) {
-    try {
-        const { values } = parseArgs({
-            args: argv,
-            options: {
-                help: { type: "boolean", short: "h" },
-                json: { type: "boolean" },
-                name: { type: "string" },
-                prompt: { type: "string" },
-                wait: { type: "string" }
-            }
-        });
-        if (values.help === true) {
-            return "help";
-        }
-        const { name, prompt } = values;
-        if (name === undefined || !NAME.test(name)) {
-            return { error: `--name takes 1-32 of a-z, 0-9, - and _, not ${JSON.stringify(name ?? "")}` };
-        }
-        if (prompt === undefined || prompt.trim() === "") {
-            return { error: "give the Lead its first message: --prompt <first message>" };
+    const { values } = readArgs({
+        args: argv,
+        options: {
+            help: { type: "boolean", short: "h" },
+            json: { type: "boolean" },
+            name: { type: "string" },
+            prompt: { type: "string" },
+            wait: { type: "string" }
         }
-        const wait = wholeNumber("--wait", values.wait, DEFAULT_WAIT, 0);
-        if (typeof wait === "object") {
-            return wait;
-        }
-        return { name, prompt, wait, json: values.json === true };
+    }, USAGE);
+    if (values.help === true) {
+        return { help: true };
+    }
+    const { name, prompt } = values;
+    if (name === undefined || !NAME.test(name)) {
+        throw usageError(`--name takes 1-32 of a-z, 0-9, - and _, not ${JSON.stringify(name ?? "")}`, USAGE);
     }
-    catch (error) {
-        return { error: describe(error) };
+    if (prompt === undefined || prompt.trim() === "") {
+        throw usageError("give the Lead its first message: --prompt <first message>", USAGE);
     }
+    const wait = wholeNumber("--wait", values.wait, DEFAULT_WAIT, 0);
+    if (typeof wait === "object") {
+        throw usageError(wait.error, USAGE);
+    }
+    return { help: false, name, prompt, wait, json: values.json === true };
 }
 /** `words` without the flag that skips permissions and without a worktree flag, its name with it when it has one. */
 function leadCommand(words) {
@@ -88,11 +83,11 @@ async function start(cli) {
     const checkout = repositoryRoot(process.cwd());
     const main = mainCheckout(checkout);
     if (main !== undefined) {
-        throw new Refusal(`in a linked worktree, ${checkout}: a Lead works in the main checkout, and this session cannot start one there`, `run it from the main checkout, ${main}, or start the Lead there by hand`);
+        throw new CannotRun(`in a linked worktree, ${checkout}: a Lead works in the main checkout, and this session cannot start one there`, `run it from the main checkout, ${main}, or start the Lead there by hand`);
     }
     const command = leadCommand(resolveConfig(checkout).config.worker.command.split(/\s+/).filter(Boolean));
     if (command.length === 0) {
-        throw new Refusal("worker.command holds no command", "set it in .ai/agentic.config.local.json, or remove the key");
+        throw new CannotRun("worker.command holds no command", "set it in .ai/agentic.config.local.json, or remove the key");
     }
     const { address, tab, reason } = await launch("lead start", {
         name: cli.name,
@@ -118,18 +113,9 @@ async function start(cli) {
 }
 export async function run(argv) {
     const cli = parseCli(argv);
-    if (cli === "help") {
+    if (cli.help) {
         process.stdout.write(`${USAGE}\n`);
         return 0;
     }
-    if ("error" in cli) {
-        process.stderr.write(`dw-sdlc lead start: ${cli.error}\n\n${USAGE}\n`);
-        return 2;
-    }
-    try {
-        return await start(cli);
-    }
-    catch (error) {
-        return refuse("lead start", error);
-    }
+    return start(cli);
 }

package/dist/commands/pr-reviewed.js

@@ -1,9 +1,9 @@
 // `dw-sdlc pr reviewed <n> --head <sha>`: pins a Review to the head it read, as the commit status
 // `dw-sdlc/review`: success for a clean one, --findings the read mark of one that left a Finding open,
 // --accept the dev's acceptance of a head as it stands, which the review-limit park names.
-import { parseArgs } from "node:util";
+import { CannotRun, readArgs, usageError } from "../cannot-run.js";
 import { REVIEW, REVIEW_STATE, reviewStatusArgs } from "../pr/decide.js";
-import { CannotRun, gh, namedProblem, read, said } from "../pr/read.js";
+import { gh, namedProblem, pullRequestNamed, said } from "../pr/read.js";
 import { ACCEPTED, MARK_STATE, READ_MARK } from "../pr/state.js";
 export const summary = "pin a Review to the head it read, as a commit status";
 const USAGE = `Usage: dw-sdlc pr reviewed <n> [-R owner/name] --head <sha> [--findings | --accept] [--json]
@@ -25,54 +25,49 @@ const STATUS = {
     accept: { state: REVIEW_STATE, description: ACCEPTED }
 };
 function parseCli(argv) {
-    try {
-        const { values, positionals } = parseArgs({
-            args: argv,
-            allowPositionals: true,
-            options: {
-                help: { type: "boolean", short: "h" },
-                json: { type: "boolean" },
-                repo: { type: "string", short: "R" },
-                head: { type: "string" },
-                findings: { type: "boolean" },
-                accept: { type: "boolean" }
-            }
-        });
-        if (values.help === true) {
-            return "help";
+    const { values, positionals } = readArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            help: { type: "boolean", short: "h" },
+            json: { type: "boolean" },
+            repo: { type: "string", short: "R" },
+            head: { type: "string" },
+            findings: { type: "boolean" },
+            accept: { type: "boolean" }
         }
-        const [number, ...more] = positionals;
-        const { repo, head } = values;
-        if (number === undefined) {
-            return { error: "name the pull request: dw-sdlc pr reviewed <n> --head <sha>" };
-        }
-        if (more.length > 0) {
-            return { error: `name one pull request, not ${positionals.length}` };
-        }
-        const problem = namedProblem(number, repo);
-        if (problem !== undefined) {
-            return { error: problem };
-        }
-        if (head === undefined) {
-            return { error: "name the head the review read: --head <sha>" };
-        }
-        if (!/^[0-9a-f]{40}$/.test(head)) {
-            return { error: `--head takes the full 40-character sha, not ${JSON.stringify(head)}` };
-        }
-        if (values.findings === true && values.accept === true) {
-            return { error: "--findings and --accept contradict: name one" };
-        }
-        const kind = values.findings === true ? "findings" : "clean";
-        const status = STATUS[values.accept === true ? "accept" : kind];
-        return { json: values.json === true, number: Number(number), repo, head, status };
+    }, USAGE);
+    if (values.help === true) {
+        return { help: true };
+    }
+    const [number, ...more] = positionals;
+    const { repo, head } = values;
+    if (number === undefined) {
+        throw usageError("name the pull request: dw-sdlc pr reviewed <n> --head <sha>", USAGE);
+    }
+    if (more.length > 0) {
+        throw usageError(`name one pull request, not ${positionals.length}`, USAGE);
     }
-    catch (error) {
-        return { error: error instanceof Error ? error.message : String(error) };
+    const problem = namedProblem(number, repo);
+    if (problem !== undefined) {
+        throw usageError(problem, USAGE);
     }
+    if (head === undefined) {
+        throw usageError("name the head the review read: --head <sha>", USAGE);
+    }
+    if (!/^[0-9a-f]{40}$/.test(head)) {
+        throw usageError(`--head takes the full 40-character sha, not ${JSON.stringify(head)}`, USAGE);
+    }
+    if (values.findings === true && values.accept === true) {
+        throw usageError("--findings and --accept contradict: name one", USAGE);
+    }
+    const kind = values.findings === true ? "findings" : "clean";
+    const status = STATUS[values.accept === true ? "accept" : kind];
+    return { help: false, json: values.json === true, number: Number(number), repo, head, status };
 }
 /** Posts the review status on `head` once the read shows it is still the pull request's head. */
 function post({ number, repo, head, status }) {
-    const pr = read({ number, repo }, "pr reviewed", false);
+    const pr = pullRequestNamed({ number, repo }, "pr reviewed");
     if (pr.head !== head) {
         throw new CannotRun(`${pr.repo}#${number}: the head is ${pr.head}, not ${head}: a push landed since the review`, "review the new head, then call again with its sha");
     }
@@ -83,24 +78,11 @@ function post({ number, repo, head, status }) {
 }
 export function run(argv) {
     const cli = parseCli(argv);
-    if (cli === "help") {
+    if (cli.help) {
         process.stdout.write(`${USAGE}\n`);
         return 0;
     }
-    if ("error" in cli) {
-        process.stderr.write(`dw-sdlc pr reviewed: ${cli.error}\n\n${USAGE}\n`);
-        return 2;
-    }
-    try {
-        post(cli);
-    }
-    catch (error) {
-        if (error instanceof CannotRun) {
-            process.stderr.write(`dw-sdlc pr reviewed: ${error.message} — ${error.remedy}\n`);
-            return 2;
-        }
-        throw error;
-    }
+    post(cli);
     const { head } = cli;
     const { state } = cli.status;
     const answer = cli.json

package/dist/commands/pr-ship.js

@@ -1,11 +1,11 @@
 // `dw-sdlc pr ship [<n>]`, the Ship script: reads one pull request through gh, decides the Action it
 // 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, REVIEW_DEPTHS } from "../agentic-config.js";
-import { decide, declaredPolicy, devCommand, hostArgs, isScriptAction, lineOf, readyToMerge, REVIEW, shellLine } from "../pr/decide.js";
-import { CannotRun, carriesBase, gh, namedProblem, nameItRemedy, now, read, readAgain, readBranch, said } from "../pr/read.js";
-import { holds, renamedUpstream } from "../pr/upstream.js";
+import { CannotRun, readArgs, usageError } from "../cannot-run.js";
+import { decide, declaredPolicy, devCommand, hostArgs, isScriptAction, lineOf, readyToMerge, REVIEW } from "../pr/decide.js";
+import { gh, ghReads, namedProblem, nameItRemedy, now, said } from "../pr/read.js";
+import { shellLine } from "../shell-line.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] [--review full|light|off] [--dry-run] [--json] [--verbose]
 
@@ -22,16 +22,18 @@ ${REVIEW} success gets the Review depth --review names for this call, else pr.re
 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
+Review would read: lockfiles alone off, unless a Finding is open; 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 commit a Review read under details.since, where the Review reads from and auto routes from:
 one with a ${REVIEW} success not posted under off, or the read mark pr reviewed --findings
 posts. It carries a success over a head whose only commits since are merges of the base, unless
 --review names a depth for the call; a read mark never carries. A read mark no later commit answers,
-on the head or before only merges or a rebase, is named under details.open: the Review then reads
-the whole pull request, and nothing carries over it. After a merge or a rebase, details.paths names
-the files whose own change moved, the only ones the Review reads.
+on the head or before commits that leave the own changes as it read them, is named under
+details.open: the Review then reads the whole pull request, and nothing carries over it. After a merge or a rebase, details.paths names
+the files whose own change moved, the only ones the Review reads. Three Reviews that left a Finding
+open with no success between them park as review-limit at every depth, pr reviewed --accept the
+dev's command: the dev's --review <depth> buys one more Review, and their --review off posts past it.
 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
@@ -46,58 +48,57 @@ Exit 0 done, 10 the agent's turn, 20 wait, 30 the dev's turn, 2 when it cannot r
 /** 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 };
-/** A call that stopped after it ran Actions: what it ran stands in `performed`, `ok` null where no read followed. */
+/**
+ * A call that stopped after it ran Actions: what it ran stands in `performed`, `ok` null where no read
+ * followed, and each Action is named with gh's exit under the problem.
+ */
 class Interrupted extends CannotRun {
     performed;
     constructor({ message, remedy }, performed) {
-        super(message, remedy);
+        const ran = performed.map(({ action, exit }) => `${action} ran (gh exit ${exit ?? "unknown"})`);
+        super(message, remedy, { after: ran.join("\n") });
         this.performed = performed;
     }
 }
 function parseCli(argv) {
-    try {
-        const { values, positionals } = parseArgs({
-            args: argv,
-            allowPositionals: true,
-            options: {
-                help: { type: "boolean", short: "h" },
-                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}` };
-            }
-            const problem = namedProblem(number, repo);
-            if (problem !== undefined) {
-                return { error: problem };
-            }
-            if (values.review !== undefined && review === undefined) {
-                return { error: `--review takes ${DEPTHS_SENTENCE}, not ${JSON.stringify(values.review)}` };
-            }
+    const { values, positionals } = readArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            help: { type: "boolean", short: "h" },
+            json: { type: "boolean" },
+            verbose: { type: "boolean" },
+            merge: { type: "boolean" },
+            review: { type: "string" },
+            "dry-run": { type: "boolean" },
+            repo: { type: "string", short: "R" }
+        }
+    }, USAGE);
+    const [number, ...more] = positionals;
+    const { repo } = values;
+    const review = REVIEW_DEPTHS.find((depth) => depth === values.review);
+    if (values.help !== true) {
+        if (more.length > 0) {
+            throw usageError(`name one pull request, not ${positionals.length}`, USAGE);
+        }
+        const problem = namedProblem(number, repo);
+        if (problem !== undefined) {
+            throw usageError(problem, USAGE);
+        }
+        if (values.review !== undefined && review === undefined) {
+            throw usageError(`--review takes ${DEPTHS_SENTENCE}, not ${JSON.stringify(values.review)}`, USAGE);
         }
-        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
-        };
-    }
-    catch (error) {
-        return { error: error instanceof Error ? error.message : String(error) };
     }
+    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
+    };
 }
 /** How a reason names each script Action: what the script would do, the act, and the state it acts on. */
 const NAMED = {
@@ -116,7 +117,7 @@ const NAMED = {
  */
 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),
+    "update-branch": (before, after, reads) => after.head !== before.head && reads.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"),
@@ -144,27 +145,17 @@ function handedOver(pr, policy, answer, action, reason) {
     }
     return { ...answer, status: "park", actor: "dev", reason, command: devCommand(pr, action, policy) };
 }
-/**
- * The pull request the call names, else the current branch's as `gh pr view` resolves it. Where gh finds
- * none for a branch whose upstream has another name, the one of that name, taken only when its commits
- * hold the local head: a branch started from another tracks that branch until its first push.
- */
-function readTarget(cli, root, sized) {
-    const renamed = cli.number === undefined && cli.repo === undefined ? renamedUpstream(root) : undefined;
-    if (renamed === undefined) {
-        return read(cli, "pr ship", sized);
-    }
-    const { branch, head, upstream } = renamed;
-    const found = readBranch(sized, upstream);
-    const upstreamNamed = `${upstream}, the name its upstream gives`;
-    if (found === null) {
-        throw new CannotRun(`gh pr view found no pull request for ${branch}, nor for ${upstreamNamed}`, nameItRemedy("pr ship"));
+/** The pull request the call names, else this checkout's; none found stops the call with what to name. */
+function readTarget(cli, root, reads) {
+    if (cli.number !== undefined || cli.repo !== undefined) {
+        return reads.named(cli, "pr ship");
     }
-    if (found.byUpstream && !holds(found.pr, head)) {
-        const lacks = `${found.pr.url}, found by ${upstreamNamed}, lacks HEAD ${head.slice(0, 7)}`;
-        throw new CannotRun(lacks, `push HEAD if it is this branch's pull request, else ${nameItRemedy("pr ship")}`);
+    const found = reads.checkout(root);
+    if ("problem" in found) {
+        const nameIt = nameItRemedy("pr ship");
+        throw new CannotRun(found.problem, found.lacksHead ? `push HEAD if it is this branch's pull request, else ${nameIt}` : nameIt);
     }
-    return found.pr;
+    return found;
 }
 /**
  * Reads and decides until the Action is not the script's. Each script Action runs at most once, then the
@@ -172,8 +163,8 @@ function readTarget(cli, root, sized) {
  */
 function ship(cli, root, policy) {
     // Only pr.review auto routes the depth from the changes, so only it reads them.
-    const sized = policy.review.depth === "auto";
-    let pr = readTarget(cli, root, sized);
+    const reads = ghReads(policy.review.depth === "auto");
+    let pr = readTarget(cli, root, reads);
     const performed = [];
     // The head each Action ran on.
     const postedOn = new Map();
@@ -207,8 +198,8 @@ function ship(cli, root, policy) {
         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) });
+            pr = reads.again(pr);
+            performed.push({ ...record, ok: TOOK[action](before, pr, reads) });
         }
         catch (error) {
             if (error instanceof CannotRun) {
@@ -225,10 +216,6 @@ function documentOf(pr, answer, performed, verbose) {
 }
 export function run(argv) {
     const cli = parseCli(argv);
-    if ("error" in cli) {
-        process.stderr.write(`dw-sdlc pr ship: ${cli.error}\n\n${USAGE}\n`);
-        return 2;
-    }
     if (cli.help) {
         process.stdout.write(`${USAGE}\n`);
         return 0;
@@ -246,14 +233,9 @@ export function run(argv) {
         shipped = ship(cli, root, policy);
     }
     catch (error) {
-        if (error instanceof CannotRun) {
-            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;
+        if (cli.json && error instanceof Interrupted) {
+            const { message, remedy, performed } = error;
+            process.stdout.write(`${JSON.stringify({ error: message, remedy, performed }, null, 2)}\n`);
         }
         throw error;
     }

package/dist/commands/primitives.js

@@ -3,8 +3,8 @@
 // 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 { CannotRun, readArgs, rootDir, usageError } from "../cannot-run.js";
 import { primitivesNaming, readCatalogue } from "../catalogue.js";
 import { catalogueFile } from "../checks/primitives.js";
 import { blockOf, primitivesDiff } from "../primitives-diff.js";
@@ -25,44 +25,42 @@ for a pull request body, which a later run replaces. --json prints instead, per
 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.`;
+Exit 0 with an answer, 2 when --root names no directory, 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"
 };
 function parseCli(argv) {
-    try {
-        const { values, positionals } = parseArgs({
-            args: argv,
-            allowPositionals: true,
-            options: {
-                help: { type: "boolean", short: "h" },
-                json: { type: "boolean" },
-                paths: { type: "boolean" },
-                diff: { type: "string" },
-                root: { type: "string" }
-            }
-        });
-        const cli = {
-            help: values.help === true,
-            json: values.json === true,
-            paths: values.paths === true,
-            diff: values.diff,
-            files: positionals,
-            root: values.root
-        };
-        if (cli.help) {
-            return cli;
+    const { values, positionals } = readArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            help: { type: "boolean", short: "h" },
+            json: { type: "boolean" },
+            paths: { type: "boolean" },
+            diff: { type: "string" },
+            root: { type: "string" }
         }
-        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" };
+    }, USAGE);
+    const cli = {
+        help: values.help === true,
+        json: values.json === true,
+        paths: values.paths === true,
+        diff: values.diff,
+        files: positionals,
+        root: values.root
+    };
+    if (cli.help) {
+        return cli;
+    }
+    if (cli.diff !== undefined && (cli.paths || cli.files.length > 0)) {
+        throw usageError("--diff and --paths exclude each other — ask one question at a time", USAGE);
     }
-    catch (error) {
-        return { error: error instanceof Error ? error.message : String(error) };
+    if (!cli.paths && cli.diff === undefined) {
+        throw usageError("name the paths with --paths, or a base with --diff", USAGE);
     }
+    return cli;
 }
 /**
  * `path` with every symbolic link in it resolved, as git reports the root: the nearest part on disk
@@ -87,26 +85,27 @@ function plain(path, primitives) {
         `  read: ${docs.join(", ")}`
     ]);
 }
+/** Stops the command on every one of `problems`, each on a line of its own, as the bin prints the first. */
+function stopOn(problems) {
+    const [first = "the catalogue cannot be read", ...rest] = problems;
+    const after = rest.map((problem) => `dw-sdlc primitives: ${problem}`).join("\n");
+    throw new CannotRun(first, undefined, rest.length === 0 ? {} : { after });
+}
 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;
+        stopOn(answer.problems);
     }
     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) {
-        process.stderr.write(`dw-sdlc primitives: ${cli.error}\n\n${USAGE}\n`);
-        return 2;
-    }
     if (cli.help) {
         process.stdout.write(`${USAGE}\n`);
         return 0;
     }
-    const root = repositoryRoot(cli.root ?? process.cwd());
+    const root = repositoryRoot(rootDir(cli.root));
     if (cli.diff !== undefined) {
         return runDiff(root, cli.diff, cli.json);
     }
@@ -116,8 +115,7 @@ export function run(argv) {
         const problems = read.state === "missing"
             ? [`the catalogue does not exist — ${REMEDIES.missing}`]
             : read.problems.map((problem) => `${problem} — ${REMEDIES.invalid}`);
-        process.stderr.write(problems.map((problem) => `dw-sdlc primitives: ${file}: ${problem}\n`).join(""));
-        return 2;
+        stopOn(problems.map((problem) => `${file}: ${problem}`));
     }
     const answers = cli.files.map((path) => {
         const fromRoot = relative(root, realPath(resolve(path)));