dw-sdlc 0.9.0 → 0.11.0

package/README.md

@@ -56,9 +56,12 @@ the delete command for the dev.
 
 `pr.merge` in the committed `.ai/agentic.config.json` says who merges: the script under `auto`, the
 dev under `ask`, the default. `pr.review` says how closely a head no one has reviewed is read: the
-agent reviews it under `full`, the default, and no one does under `off`. The local layer may tighten
-either and never loosen it; `--merge` acts as `auto` and `--review full|off` sets the depth for one
-call. A pull request the `gh` account did not open is always the dev's to merge.
+agent reviews it under `full`, one `sdlc-reviewer` subagent of the plugin does under `light`, and no
+one does under `off`. Under `auto`, the default, the script routes the depth from the changes:
+lockfiles alone `off`; a workflow file, more than 100 changed lines outside lockfiles, or a change
+too large to size `full`; the rest `light`. The local layer may tighten either and never loosen it;
+`--merge` acts as `auto` and `--review full|light|off` sets the depth for one call. A pull request
+the `gh` account did not open is always the dev's to merge.
 
 ```json
 { "pr": { "merge": "auto", "review": "full" } }
@@ -83,6 +86,7 @@ script posts that status itself, its description saying why, and goes on.
 | `references setup` | the Router, its table and the ignore rules a repository needs to declare References |
 | `pr ship [<n>]`    | the Action one pull request needs next, performing the script's own                 |
 | `pr reviewed <n>`  | a clean review pinned to the head it read, as a commit status                       |
+| `recap`            | the facts a Recap rests on and whether the session can be closed                    |
 
 `dw-sdlc <command> --help` gives each one's options.
 

package/config/agentic.config.schema.json

@@ -395,8 +395,8 @@
           "enum": ["ask", "auto"]
         },
         "review": {
-          "description": "The Review depth of a head the Ship script finds unreviewed, which the dev's `--review` overrides for one call. `full`: the agent reviews the changes. `off`: the script posts the `dw-sdlc/review` success itself and no one reads them. Default `full`, which an invalid layer runs too. Strictest first: full, off.",
-          "enum": ["full", "off"]
+          "description": "The Review depth of a head the Ship script finds unreviewed, which the dev's `--review` overrides for one call. `full`: the agent runs the command `pr.reviewCommand` names over the changes. `light`: one `sdlc-reviewer` subagent reads the diff at medium effort. `off`: the script posts the `dw-sdlc/review` success itself and no one reads them. `auto`: built-in rules route 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 the script cannot size, more files than GitHub's compare lists or a file outside lockfiles with no patch, `full`; the rest `light`. Default `auto`; an invalid layer runs `full`. Strictest first: full, auto, light, off.",
+          "enum": ["full", "auto", "light", "off"]
         },
         "reviewCommand": {
           "description": "The slash command a `full` Review runs over the pull request's changes, as `/pr-review-toolkit:review-pr code errors`. Default `/code-review`. No strictness order: the local override sets it freely.",
@@ -406,6 +406,27 @@
       },
       "additionalProperties": false
     },
+    "worker": {
+      "description": "How a Worker's Claude Code session starts: the command, the model and the effort. No strictness order, as with `pr.reviewCommand`: any layer sets any key freely.",
+      "type": "object",
+      "properties": {
+        "command": {
+          "description": "The command a Worker starts with: the words that start its Claude Code session, before the flags of its own, such as `--model` and `--effort`. Default `claude`. It belongs to one machine, so it sits in the local layer, where `dw-sdlc setup` writes `cswap run -- --dangerously-skip-permissions` when `cswap` is on PATH.",
+          "type": "string",
+          "minLength": 1
+        },
+        "model": {
+          "description": "The model a Worker runs on, as Claude Code's `--model` takes it. Default `sonnet`.",
+          "type": "string",
+          "minLength": 1
+        },
+        "effort": {
+          "description": "The effort a Worker runs at, one of Claude Code's effort levels. Default `high`.",
+          "enum": ["low", "medium", "high", "xhigh", "max"]
+        }
+      },
+      "additionalProperties": false
+    },
     "worktree": {
       "type": "object",
       "properties": {

package/dist/agentic-config.d.ts

@@ -17,8 +17,15 @@ export type EnvFiles = {
 };
 /** Who merges a pull request the Ship script finds ready: the script under `auto`, the dev under `ask`. */
 export type PrMerge = "ask" | "auto";
-/** How closely a Review reads an unreviewed head: the agent reads it under `full`, no one under `off`. */
-export type PrReview = "full" | "off";
+/**
+ * How closely a Review reads an unreviewed head: the command `pr.reviewCommand` names under `full`,
+ * one `sdlc-reviewer` subagent under `light`, no one under `off`.
+ */
+export type ReviewDepth = "full" | "light" | "off";
+/** The Review depths, strictest first: what the dev's `--review` names. */
+export declare const REVIEW_DEPTHS: readonly ["full", "light", "off"];
+/** `pr.review`: a Review depth, or `auto`, which routes one from the changes by built-in rules. */
+export type PrReview = ReviewDepth | "auto";
 /**
  * How the Ship script ends a pull request: who merges it, how closely it is reviewed, and the slash
  * command a `full` Review runs.
@@ -28,6 +35,15 @@ export type PrConfig = {
     review: PrReview;
     reviewCommand: string;
 };
+/** Claude Code's effort levels, lowest first: what `worker.effort` takes. */
+declare const WORKER_EFFORTS: readonly ["low", "medium", "high", "xhigh", "max"];
+export type WorkerEffort = (typeof WORKER_EFFORTS)[number];
+/** How a Worker's Claude Code session starts: the words that start it, its model and its effort. */
+export type WorkerConfig = {
+    command: string;
+    model: string;
+    effort: WorkerEffort;
+};
 export type Guardrails = {
     forcePush: ForcePush;
     commitOnProtected: CommitOnProtected;
@@ -84,6 +100,7 @@ export type AgenticConfig = {
     };
     gate?: GateLayer;
     pr?: Partial<PrConfig>;
+    worker?: Partial<WorkerConfig>;
     worktree?: {
         setup?: string[];
     };
@@ -104,6 +121,7 @@ export type ResolvedConfig = {
     };
     gate: Gate;
     pr: PrConfig;
+    worker: WorkerConfig;
     worktree: {
         setup: string[];
     };
@@ -141,13 +159,13 @@ export declare const STRICTNESS: {
     readonly commitOnProtected: readonly ["deny", "allow"];
     readonly envFiles: readonly ["deny", "git"];
     readonly merge: readonly ["ask", "auto"];
-    readonly review: readonly ["full", "off"];
+    readonly review: readonly ["full", "auto", "light", "off"];
 };
 /** What the guards run on while any layer is invalid. */
 export declare const STRICTEST_GUARDRAILS: Guardrails;
 /** What the Ship script runs on while any layer is invalid, and with nothing declared: it merges nothing itself. */
 export declare const STRICTEST_PR_MERGE: PrMerge;
-/** The Review depth while any layer is invalid, and with nothing declared: the agent reads every head. */
+/** The Review depth while any layer is invalid: the agent reads every head in full. */
 export declare const STRICTEST_PR_REVIEW: PrReview;
 /** The command a `full` Review runs with nothing declared; it has no strictness order. */
 export declare const DEFAULT_REVIEW_COMMAND = "/code-review";

package/dist/agentic-config.js

@@ -11,13 +11,17 @@ export const LOCAL_FILE = ".ai/agentic.config.local.json";
 export const SCHEMA_FILE = "config/agentic.config.schema.json";
 export const SCHEMA_PATH = join(import.meta.dirname, "..", SCHEMA_FILE);
 export const COMMIT_CONVENTIONS = ["ticket-key", "conventional"];
+/** The Review depths, strictest first: what the dev's `--review` names. */
+export const REVIEW_DEPTHS = ["full", "light", "off"];
+/** Claude Code's effort levels, lowest first: what `worker.effort` takes. */
+const WORKER_EFFORTS = ["low", "medium", "high", "xhigh", "max"];
 /** Strictest value first; the local override may only move towards the front. */
 export const STRICTNESS = {
     forcePush: ["deny", "ask", "lease"],
     commitOnProtected: ["deny", "allow"],
     envFiles: ["deny", "git"],
     merge: ["ask", "auto"],
-    review: ["full", "off"]
+    review: ["full", "auto", "light", "off"]
 };
 /** What the guards run on while any layer is invalid. */
 export const STRICTEST_GUARDRAILS = {
@@ -28,11 +32,15 @@ export const STRICTEST_GUARDRAILS = {
 };
 /** What the Ship script runs on while any layer is invalid, and with nothing declared: it merges nothing itself. */
 export const STRICTEST_PR_MERGE = "ask";
-/** The Review depth while any layer is invalid, and with nothing declared: the agent reads every head. */
+/** The Review depth while any layer is invalid: the agent reads every head in full. */
 export const STRICTEST_PR_REVIEW = "full";
 const STRICTEST_PR = { merge: STRICTEST_PR_MERGE, review: STRICTEST_PR_REVIEW };
 /** The command a `full` Review runs with nothing declared; it has no strictness order. */
 export const DEFAULT_REVIEW_COMMAND = "/code-review";
+/** What a repository gets with nothing declared: the merge the dev's, the depth routed from the changes. */
+const DEFAULT_PR = { merge: STRICTEST_PR_MERGE, review: "auto", reviewCommand: DEFAULT_REVIEW_COMMAND };
+/** What a Worker starts with when no layer says otherwise; no key has a strictness order. */
+const DEFAULT_WORKER = { command: "claude", model: "sonnet", effort: "high" };
 /** What a repository gets with nothing declared. */
 export const DEFAULT_GUARDRAILS = {
     forcePush: "lease",
@@ -202,7 +210,8 @@ export function inferConfig(root) {
         guardrails: cloneGuardrails(DEFAULT_GUARDRAILS),
         commit: { convention: "conventional" },
         gate: inferGate(root),
-        pr: { ...STRICTEST_PR, reviewCommand: DEFAULT_REVIEW_COMMAND },
+        pr: { ...DEFAULT_PR },
+        worker: { ...DEFAULT_WORKER },
         worktree: { setup: [] }
     };
 }
@@ -219,6 +228,7 @@ function applyLayer(base, layer) {
         commit: { ...base.commit, ...layer.commit },
         gate: { ...base.gate, ...layer.gate, checks: { ...base.gate.checks, ...layer.gate?.checks } },
         pr: { ...base.pr, ...layer.pr },
+        worker: { ...base.worker, ...layer.worker },
         worktree: { setup: layer.worktree?.setup ?? base.worktree.setup }
     };
 }
@@ -277,7 +287,7 @@ function loosenings(base, local) {
     }
     return problems;
 }
-/** Each local `pr` key less strict than the one it would override: `merge` auto over ask, `review` off over full. */
+/** Each local `pr` key less strict than the one it would override: `merge` auto over ask, `review` off over light over auto over full. */
 function prLoosenings(base, local) {
     const keys = ["merge", "review"];
     return keys.flatMap((key) => {
@@ -323,7 +333,7 @@ export function resolveConfig(root) {
         }
     }
     if (problems.length > 0) {
-        // `reviewCommand` has no strictest value: it keeps what the valid layers name.
+        // `reviewCommand` and `worker` have no strictest value: they keep what the valid layers name.
         config = { ...config, guardrails: cloneGuardrails(STRICTEST_GUARDRAILS), pr: { ...config.pr, ...STRICTEST_PR } };
     }
     return {

package/dist/cli.js

@@ -8,6 +8,7 @@ import * as gate from "./commands/gate.js";
 import * as prReviewed from "./commands/pr-reviewed.js";
 import * as prShip from "./commands/pr-ship.js";
 import * as primitives from "./commands/primitives.js";
+import * as recap from "./commands/recap.js";
 import * as referencesSetup from "./commands/references-setup.js";
 import * as referencesSync from "./commands/references-sync.js";
 import * as setup from "./commands/setup.js";
@@ -21,7 +22,8 @@ const COMMANDS = new Map([
     ["references sync", referencesSync],
     ["references setup", referencesSetup],
     ["pr ship", prShip],
-    ["pr reviewed", prReviewed]
+    ["pr reviewed", prReviewed],
+    ["recap", recap]
 ]);
 function usage() {
     const width = Math.max(...[...COMMANDS.keys()].map((name) => name.length)) + 2;

package/dist/commands/doctor.js

@@ -16,6 +16,9 @@ export function claudeConfigDir(env, home) {
 export const MARKETPLACE = "dw-sdlc";
 export const PLUGIN = "sdlc";
 export const PLUGIN_ID = `${PLUGIN}@${MARKETPLACE}`;
+/** The plugin of the session helpers: optional, and it links a copy of the package of its own. */
+const SESSIONS = "sdlc-sessions";
+const SESSIONS_ID = `${SESSIONS}@${MARKETPLACE}`;
 export const PACKAGE = "dw-sdlc";
 /** rtk find passes -exec through verbatim from this release; before it, `rtk find … -exec` exits 1. */
 export const RTK_FIND_EXEC_FIXED = "0.46.0";
@@ -55,8 +58,6 @@ function checkJq(probe) {
     }
     return { name: "jq", level: "FAIL", detail: "missing: every guard is silent without it. brew install jq" };
 }
-/** Where the plugin's hooks run: live from the checkout for a marketplace added from a directory, a
- *  cached snapshot for one added from git. A marker placed in only one of the two settled it. */
 /** The checkout a directory marketplace runs the plugin from, or undefined for a snapshot. */
 function liveCheckout(probe, claude) {
     const known = parseJson(probe.read(join(claude, "plugins", "known_marketplaces.json")));
@@ -71,27 +72,27 @@ function pluginOrigin(probe, claude, installPath) {
     }
     return `installed at ${installPath}; a change reaches it through claude plugin update`;
 }
-/** The directory whose hooks run on this machine: the checkout of a directory marketplace, else the installed snapshot. */
-function runningPluginRoot(probe, claude) {
-    const checkout = liveCheckout(probe, claude);
-    if (checkout !== undefined) {
-        return join(checkout, "plugins", PLUGIN);
-    }
+/** What `claude plugin list --json` prints, one object a plugin, or undefined when it does not answer. */
+function listedPlugins(probe) {
     const { status, stdout } = probe.run("claude", ["plugin", "list", "--json"]);
     const list = status === 0 ? parseJson(stdout) : undefined;
-    if (!Array.isArray(list)) {
-        return undefined;
+    return Array.isArray(list) ? list.filter(isObject) : undefined;
+}
+/** The directory `plugin` runs from on this machine: the checkout of a directory marketplace, else the installed snapshot. */
+function runningPluginRoot(probe, claude, plugin = PLUGIN) {
+    const checkout = liveCheckout(probe, claude);
+    if (checkout !== undefined) {
+        return join(checkout, "plugins", plugin);
     }
-    const entry = list.find((item) => isObject(item) && item.id === PLUGIN_ID);
+    const entry = listedPlugins(probe)?.find((item) => item.id === `${plugin}@${MARKETPLACE}`);
     return entry !== undefined && typeof entry.installPath === "string" ? entry.installPath : undefined;
 }
 function checkPlugin(probe, claude) {
-    const { status, stdout } = probe.run("claude", ["plugin", "list", "--json"]);
-    const list = status === 0 ? parseJson(stdout) : undefined;
-    if (!Array.isArray(list)) {
+    const list = listedPlugins(probe);
+    if (list === undefined) {
         return { name: "plugin", level: "FAIL", detail: "claude plugin list did not answer; is Claude Code installed?" };
     }
-    const entry = list.find((item) => isObject(item) && item.id === PLUGIN_ID);
+    const entry = list.find((item) => item.id === PLUGIN_ID);
     if (entry === undefined) {
         return {
             name: "plugin",
@@ -165,6 +166,43 @@ function checkPackage(probe, claude, root) {
     }
     return { name, level: "PASS", detail: `${PACKAGE} ${linked} in the plugin and in the repository` };
 }
+/**
+ * `sdlc-sessions`, which a machine may go without, so it never fails. Its copy of the package against
+ * the sdlc plugin's copy: the `package` line holds that one to the repository's pin.
+ */
+function checkSessions(probe, claude) {
+    const name = "sessions";
+    const list = listedPlugins(probe);
+    const entry = list?.find((item) => item.id === SESSIONS_ID);
+    if (entry === undefined) {
+        const detail = list === undefined ? "claude plugin list did not answer" : `no ${SESSIONS_ID}, so no /sdlc-recap`;
+        return { name, level: "INFO", detail };
+    }
+    const version = typeof entry.version === "string" ? entry.version : "?";
+    if (entry.enabled !== true) {
+        return { name, level: "WARN", detail: `${version} installed but disabled. claude plugin enable ${SESSIONS_ID}` };
+    }
+    const root = runningPluginRoot(probe, claude, SESSIONS);
+    const copy = root === undefined ? undefined : manifestVersion(probe, join(root, PACKAGE));
+    if (copy === undefined) {
+        return {
+            name,
+            level: "WARN",
+            detail: `${version} carries no ${PACKAGE}: an install from GitHub needs packages in its --sparse set`
+        };
+    }
+    const guards = runningPluginRoot(probe, claude);
+    const other = guards === undefined ? undefined : manifestVersion(probe, join(guards, PACKAGE));
+    if (other !== undefined && other !== copy) {
+        const behind = versionBefore(copy, other) ? SESSIONS_ID : PLUGIN_ID;
+        return {
+            name,
+            level: "WARN",
+            detail: `drift: ${SESSIONS} runs ${PACKAGE} ${copy} and ${PLUGIN} runs ${other}. claude plugin update ${behind}`
+        };
+    }
+    return { name, level: "PASS", detail: `${version} enabled, on ${PACKAGE} ${copy}` };
+}
 /** Every hook command string in a settings file, whatever the event and matcher. */
 function hookCommands(settings) {
     if (!isObject(settings) || !isObject(settings.hooks)) {
@@ -342,6 +380,7 @@ export function diagnose(inputs) {
         checkJq(probe),
         checkPlugin(probe, claude),
         checkPackage(probe, claude, inputs.config === undefined ? undefined : inputs.root),
+        checkSessions(probe, claude),
         checkRtk(probe, home, claude),
         checkSafeChain(probe),
         checkPnpmReleaseAge(probe, home),

package/dist/commands/pr-reviewed.js

@@ -54,7 +54,7 @@ function parseCli(argv) {
 }
 /** Posts the review status on `head` once the read shows it is still the pull request's head. */
 function post({ number, repo, head }) {
-    const pr = read({ number, repo }, "pr reviewed");
+    const pr = read({ number, repo }, "pr reviewed", false);
     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");
     }

package/dist/commands/pr-ship.js

@@ -2,11 +2,11 @@
 // 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, STRICTNESS } from "../agentic-config.js";
-import { decide, devCommand, hostArgs, isScriptAction, readyToMerge, REVIEW, 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, declaredPolicy, devCommand, hostArgs, isScriptAction, lineOf, readyToMerge, REVIEW, shellLine } from "../pr/decide.js";
+import { CannotRun, carriesBase, gh, namedProblem, now, 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] [--review full|off] [--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.
@@ -14,16 +14,38 @@ The script performs its own Actions, each at most once and then reads again: it
 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. A head without a ${REVIEW} success
-gets the Review depth --review names for this call, else pr.review: under full, the default, the
-agent reviews it with the command pr.reviewCommand names, /code-review by default; under off the
-script posts the success itself, its description saying why.
---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.
+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({
@@ -41,7 +63,7 @@ function parseCli(argv) {
         });
         const [number, ...more] = positionals;
         const { repo } = values;
-        const review = STRICTNESS.review.find((depth) => depth === values.review);
+        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}` };
@@ -51,7 +73,7 @@ function parseCli(argv) {
                 return { error: problem };
             }
             if (values.review !== undefined && review === undefined) {
-                return { error: `--review takes ${STRICTNESS.review.join(" or ")}, not ${JSON.stringify(values.review)}` };
+                return { error: `--review takes ${DEPTHS_SENTENCE}, not ${JSON.stringify(values.review)}` };
             }
         }
         return {
@@ -69,18 +91,6 @@ function parseCli(argv) {
         return { error: error instanceof Error ? error.message : String(error) };
     }
 }
-/** The time the decision reads: DW_SDLC_NOW, an ISO 8601 time a test sets, else the system clock. */
-function now() {
-    const given = process.env.DW_SDLC_NOW?.trim();
-    if (given === undefined || given === "") {
-        return Date.now();
-    }
-    const time = Date.parse(given);
-    if (Number.isNaN(time)) {
-        throw new CannotRun(`DW_SDLC_NOW is ${JSON.stringify(given)}, not an ISO 8601 time`, REMEDIES.clock);
-    }
-    return time;
-}
 /** How a reason names each script Action: what the script would do, the act, and the state it acts on. */
 const NAMED = {
     "update-branch": { would: "update the branch", act: "the update", still: "the branch still reads behind its base" },
@@ -92,6 +102,33 @@ const NAMED = {
     },
     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, policy, answer, action, reason) {
     if (action === "merge") {
@@ -104,9 +141,12 @@ function handedOver(pr, policy, answer, action, reason) {
  * pull request is read again; under --dry-run, or when an Action comes round again, it is the dev's.
  */
 function ship(cli, policy) {
-    let pr = read(cli, "pr ship");
+    // 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(), policy);
         const { action } = answer;
@@ -116,7 +156,7 @@ function ship(cli, policy) {
         // -R names the repository, so the checkout the script runs in plays no part.
         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 {
@@ -125,25 +165,30 @@ function ship(cli, policy) {
                 performed
             };
         }
-        if (performed.some((done) => done.action === action)) {
-            const refusal = refusals[action];
-            const reason = refusal === undefined ? `${act} ran, and ${still}` : `gh refused ${act}: ${refusal}`;
+        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. */
-function lineOf({ status, action, reason, command, recheckAfter }) {
-    const label = status === action ? status : `${status} ${action}`;
-    const recheck = recheckAfter === undefined ? "" : `, recheck in ${recheckAfter} s`;
-    return `${label}: ${reason}${recheck}${command === undefined ? "" : ` — ${command}`}`;
-}
 function documentOf(pr, answer, performed, verbose) {
     const facts = verbose ? { facts: pr } : {};
     return { pr: pr.url, head: pr.head, base: pr.base, ...answer, performed, ...facts };
@@ -161,9 +206,9 @@ export function run(argv) {
     // 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
+        ...declaredPolicy(declared),
+        ...(cli.merge ? { merge: "auto" } : {}),
+        ...(cli.review === undefined ? {} : { review: { depth: cli.review, source: "flag" } })
     };
     let shipped;
     try {
@@ -171,7 +216,12 @@ export function run(argv) {
     }
     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/recap.d.ts

@@ -0,0 +1,2 @@
+export declare const summary = "the facts a Recap rests on and whether the session can be closed";
+export declare function run(argv: string[]): number;