dw-sdlc 0.20.0 → 0.21.1

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");
 }

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,13 +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.
+--review names a depth for the call; a read mark never carries. A read mark no later commit answers,
+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
@@ -43,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 = {
@@ -113,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"),
@@ -141,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
@@ -169,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();
@@ -204,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) {
@@ -222,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;
@@ -243,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;
     }