dw-sdlc 0.10.0 → 0.11.0

package/README.md

@@ -86,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/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-ship.js

@@ -3,8 +3,8 @@
 // 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, devCommand, hostArgs, isScriptAction, readyToMerge, REVIEW, shellLine } from "../pr/decide.js";
-import { CannotRun, carriesBase, gh, namedProblem, read, readAgain, said } from "../pr/read.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|light|off] [--dry-run] [--json] [--verbose]
 
@@ -38,7 +38,6 @@ 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 };
-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;
@@ -92,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" },
@@ -202,12 +189,6 @@ function ship(cli, policy) {
         }
     }
 }
-/** `<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 };
@@ -225,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 {

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;

package/dist/commands/recap.js

@@ -0,0 +1,310 @@
+// `dw-sdlc recap`: the facts a Recap rests on and whether the session can be closed, read from git and
+// gh. It writes nothing: the Action of the branch's pull request is the Ship script's decision, read.
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { parseArgs } from "node:util";
+import { findRepository, mainCheckout, resolveConfig } from "../agentic-config.js";
+import { decide, declaredPolicy, labelOf, lineOf } from "../pr/decide.js";
+import { CannotRun, defaultBranch, now, readBranch } from "../pr/read.js";
+import { git } from "../working-tree.js";
+export const summary = "the facts a Recap rests on and whether the session can be closed";
+const USAGE = `Usage: dw-sdlc recap [--json]
+
+Reads the current branch, its uncommitted changes, the commits that reach no remote, its pull request
+and whether the session sits in a linked worktree, and answers whether the session can be closed, with
+every reason. It writes nothing: the pull request's Action is the one dw-sdlc pr ship would answer, read
+and never performed.
+
+The session cannot be closed over any of these:
+  a paused rebase, merge, cherry-pick, revert or bisect;
+  an uncommitted change;
+  a commit pushed nowhere or only part of the way;
+  an open pull request, whatever its Action;
+  commits on top of the base that no pull request holds. The default branch and a branch
+  guardrails.protectedBranches names need no pull request.
+
+A pull request closed without merging merges nothing, and a detached HEAD names no pull request. There a
+commit counts as pushed only on a remote branch, and the command asks the remote which branches still
+stand. A branch force-pushed since the last fetch can still read as holding it, so fetch first to be exact.
+
+A linked worktree is a reason beside the verdict, never against it: the session cannot remove the
+directory it runs in.
+
+One line a fact, or one document with --json. Needs an authenticated gh and a remote it can read. A
+detached HEAD or a repository with no remote asks gh nothing, and the pull request fact says so.
+
+Exit 0 the session can be closed, 1 it cannot, 2 when it cannot run.`;
+function plural(howMany, word) {
+    return `${howMany} ${word}${howMany === 1 ? "" : "s"}`;
+}
+/** `git <args>` at `root`; what it prints, or a stop naming its problem. */
+function must(root, args) {
+    const result = git(root, args);
+    if ("error" in result) {
+        throw new CannotRun(result.error, "check the repository with git status");
+    }
+    return result.out;
+}
+/** `git <args>` at `root`, or undefined when it exits non-zero as a question answered no. */
+function asked(root, args) {
+    const result = git(root, args);
+    return "out" in result ? result.out : undefined;
+}
+function count(root, args) {
+    return Number(must(root, ["rev-list", "--count", ...args]));
+}
+function remotesOf(root) {
+    return must(root, ["remote"])
+        .split("\n")
+        .filter((remote) => remote !== "");
+}
+/** The remote-tracking upstream of `branch`, as `--remotes` names it, unless git reports its ref gone. */
+function upstreamOf(root, branch) {
+    const prefix = "refs/remotes/";
+    const format = "%(upstream) %(upstream:track)";
+    const [ref = "", track] = must(root, ["for-each-ref", `--format=${format}`, `refs/heads/${branch}`]).split(" ");
+    return ref.startsWith(prefix) && track !== "[gone]" ? ref.slice(prefix.length) : null;
+}
+/** Git's own record of each paused operation, in the git directory a linked worktree keeps apart. */
+const PAUSES = [
+    { record: "rebase-merge", name: "rebase" },
+    { record: "rebase-apply", name: "rebase or am" },
+    { record: "MERGE_HEAD", name: "merge" },
+    { record: "CHERRY_PICK_HEAD", name: "cherry-pick" },
+    { record: "REVERT_HEAD", name: "revert" },
+    { record: "sequencer", name: "cherry-pick or revert" },
+    { record: "BISECT_LOG", name: "bisect" }
+];
+function pausedIn(root) {
+    const gitDir = must(root, ["rev-parse", "--absolute-git-dir"]);
+    return PAUSES.find(({ record }) => existsSync(join(gitDir, record)))?.name ?? null;
+}
+function readLocal(root) {
+    const branch = asked(root, ["symbolic-ref", "--quiet", "--short", "HEAD"]) ?? null;
+    const head = asked(root, ["rev-parse", "--verify", "--quiet", "HEAD"]) ?? null;
+    // Without the flag, git status refreshes the index, a write under a session working in this checkout.
+    const status = must(root, ["--no-optional-locks", "status", "--porcelain", "--untracked-files=normal"]);
+    const upstream = branch === null ? null : upstreamOf(root, branch);
+    const pushed = upstream === null ? ["HEAD", "--not", "--remotes"] : ["@{upstream}..HEAD"];
+    return {
+        branch,
+        head,
+        uncommitted: status === "" ? 0 : status.split("\n").length,
+        upstream,
+        unpushed: head === null ? 0 : count(root, pushed),
+        paused: pausedIn(root),
+        worktree: { linked: mainCheckout(root) !== undefined, path: root }
+    };
+}
+/** The current branch's pull request and the Action the Ship script's decision gives it, or null. */
+function readShipped(root) {
+    // An invalid config layer resolves to ask and full, as in the Ship script.
+    const policy = declaredPolicy(resolveConfig(root).config.pr);
+    const pr = readBranch(policy.review.depth === "auto");
+    return pr === null ? null : { pr, answer: decide(pr, now(), policy) };
+}
+/**
+ * The tracking refs, as `--remotes` names them, that the remote contradicts, which only a fetch would show:
+ * a branch it no longer has, its `HEAD`, and the session's own branch where it moved. Any other branch that
+ * moved, such as the base, counts as holding what it held; plugins/sdlc-sessions/README.md says why.
+ */
+function staleTracking(root, { branch, upstream }) {
+    return remotesOf(root).flatMap((remote) => {
+        const live = new Map(must(root, ["ls-remote", "--heads", remote])
+            .split("\n")
+            .map((line) => {
+            const [oid = "", ref = ""] = line.split("\t");
+            return [ref.replace("refs/heads/", `${remote}/`), oid];
+        }));
+        return must(root, ["for-each-ref", "--format=%(refname:lstrip=2) %(objectname)", `refs/remotes/${remote}`])
+            .split("\n")
+            .map((line) => line.split(" "))
+            .filter(([tracking = "", oid]) => {
+            const own = tracking === upstream || tracking === `${remote}/${branch}`;
+            return tracking !== "" && (!live.has(tracking) || (own && live.get(tracking) !== oid));
+        })
+            .map(([tracking = ""]) => tracking);
+    });
+}
+/**
+ * Where the head stands once the pull request is read. A commit an open or merged one holds is on GitHub,
+ * whatever became of the upstream. A closed one merges nothing and a detached HEAD names none, so there only
+ * a remote branch that still stands counts for the head. A paused operation has answered already.
+ */
+function standing(root, read, shipped, held) {
+    const asksRemote = read.paused === null && (read.branch === null || shipped?.pr.state === "CLOSED");
+    if (!asksRemote || read.head === null) {
+        return held ? { ...read, unpushed: 0 } : read;
+    }
+    const stale = staleTracking(root, read);
+    if (read.upstream !== null && !stale.includes(read.upstream)) {
+        return read;
+    }
+    const unpushed = count(root, ["HEAD", ...notOnRemotes(stale)]);
+    return { ...read, upstream: null, unpushed };
+}
+/** `rev-list` arguments that leave out what a remote branch holds, by the tracking refs still true. */
+function notOnRemotes(stale) {
+    return ["--not", ...stale.map((tracking) => `--exclude=${tracking}`), "--remotes"];
+}
+/**
+ * The commits of a closed pull request that left the branch, as by a reset, and that no remote branch holds.
+ * A head this checkout never had was never this session's to lose.
+ */
+function orphanedOf(root, read, shipped, held) {
+    if (shipped?.pr.state !== "CLOSED" || held || read.paused !== null) {
+        return 0;
+    }
+    return Number(asked(root, ["rev-list", "--count", shipped.pr.head, ...notOnRemotes(staleTracking(root, read))]) ?? 0);
+}
+/**
+ * The commits on top of the base that no pull request holds. A branch the config protects takes changes
+ * through pull requests rather than making one, and so does the default branch: neither needs one.
+ */
+function aheadOf(root, branch, shipped) {
+    if (resolveConfig(root).config.guardrails.protectedBranches.includes(branch)) {
+        return null;
+    }
+    const base = shipped?.pr.base ?? defaultBranch();
+    if (branch === base) {
+        return null;
+    }
+    const refs = remotesOf(root)
+        .map((remote) => `refs/remotes/${remote}/${base}`)
+        .filter((ref) => asked(root, ["rev-parse", "--verify", "--quiet", ref]) !== undefined);
+    return { base, commits: count(root, ["HEAD", "--not", ...refs]) };
+}
+function unpushedReason({ branch, upstream, unpushed }) {
+    const commits = plural(unpushed, "commit");
+    if (upstream !== null) {
+        return { id: "unpushed", blocks: true, text: `${commits} not pushed to ${upstream}` };
+    }
+    const where = branch === null ? "on a detached HEAD, on no remote" : "on a branch with no upstream";
+    return { id: "no-upstream", blocks: true, text: `${commits} ${where}` };
+}
+function pullRequestReason({ pr, answer }) {
+    const name = `pull request #${pr.number}`;
+    if (pr.state === "OPEN") {
+        return { id: "open-pull-request", blocks: true, text: `${name} is open: ${labelOf(answer)}: ${answer.reason}` };
+    }
+    return { id: pr.state === "MERGED" ? "merged" : "closed", blocks: false, text: `${name} ${answer.reason}` };
+}
+/** The reason when none blocks; `askedGh` false says what the verdict never read, so it claims no more. */
+function cleanReason(askedGh) {
+    const text = askedGh
+        ? "nothing is uncommitted, unpushed or open"
+        : "nothing is uncommitted or unpushed; gh was not asked";
+    return { id: "clean", blocks: false, text };
+}
+function reasonsOf(local, shipped, ahead, orphaned, askedGh) {
+    const all = [];
+    if (local.paused !== null) {
+        all.push({ id: "paused", blocks: true, text: `a ${local.paused} is paused` });
+    }
+    if (local.uncommitted > 0) {
+        all.push({ id: "uncommitted", blocks: true, text: plural(local.uncommitted, "uncommitted change") });
+    }
+    if (local.unpushed > 0) {
+        all.push(unpushedReason(local));
+    }
+    if (ahead !== null && ahead.commits > 0) {
+        const text = `${plural(ahead.commits, "commit")} on top of ${ahead.base} in no pull request`;
+        all.push({ id: "no-pull-request", blocks: true, text });
+    }
+    if (shipped !== null && orphaned > 0) {
+        const text = `${plural(orphaned, "commit")} of pull request #${shipped.pr.number} on no remote branch`;
+        all.push({ id: "orphaned", blocks: true, text });
+    }
+    if (shipped !== null) {
+        all.push(pullRequestReason(shipped));
+    }
+    if (!all.some((reason) => reason.blocks)) {
+        all.unshift(cleanReason(askedGh));
+    }
+    if (local.worktree.linked) {
+        all.push({ id: "worktree", blocks: false, text: `the worktree at ${local.worktree.path} is left to remove` });
+    }
+    return all;
+}
+/** The verdict and the line a Recap quotes: after "no" only what blocks, after "yes" every reason. */
+function closeOf(reasons) {
+    const blocking = reasons.filter((reason) => reason.blocks);
+    const verdict = blocking.length > 0 ? "no" : "yes";
+    const shown = blocking.length > 0 ? blocking : reasons;
+    const line = `Close the session: ${verdict}, because ${shown.map((reason) => reason.text).join("; ")}`;
+    return { verdict, line, reasons };
+}
+function linesOf(local, shipped, askedGh, line) {
+    const none = askedGh ? "none" : "gh not asked";
+    return [
+        `branch: ${local.branch ?? "detached HEAD"}`,
+        `uncommitted: ${local.uncommitted}`,
+        `upstream: ${local.upstream ?? "none"}, ${local.unpushed} unpushed`,
+        `pull request: ${shipped === null ? none : `${shipped.pr.url} ${lineOf(shipped.answer)}`}`,
+        `worktree: ${local.worktree.linked ? `linked at ${local.worktree.path}` : "main checkout"}`,
+        line
+    ].join("\n");
+}
+function parseCli(argv) {
+    try {
+        const { values, positionals } = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: { help: { type: "boolean", short: "h" }, json: { type: "boolean" } }
+        });
+        if (positionals.length > 0 && values.help !== true) {
+            return { error: `it takes no argument, not ${JSON.stringify(positionals[0])}` };
+        }
+        return { help: values.help === true, json: values.json === true };
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) };
+    }
+}
+function report(json) {
+    const root = findRepository(process.cwd());
+    if (root === undefined) {
+        throw new CannotRun(`no git repository holds ${process.cwd()}`, "run it from a checkout");
+    }
+    const read = readLocal(root);
+    const { branch, head } = read;
+    // A detached HEAD names no branch for gh to look up, and a repository with no remote has no GitHub.
+    const asksGh = branch !== null && remotesOf(root).length > 0;
+    const shipped = asksGh ? readShipped(root) : null;
+    const held = shipped !== null && head !== null && shipped.pr.commits.includes(head);
+    const local = standing(root, read, shipped, held);
+    // An open pull request can still take the head, and a commit-less repository has nothing to merge.
+    const nothingToMerge = held || shipped?.pr.state === "OPEN" || head === null;
+    const ahead = asksGh && !nothingToMerge ? aheadOf(root, branch, shipped) : null;
+    const orphaned = orphanedOf(root, read, shipped, held);
+    const close = closeOf(reasonsOf(local, shipped, ahead, orphaned, asksGh));
+    const pullRequest = shipped === null
+        ? null
+        : { url: shipped.pr.url, number: shipped.pr.number, state: shipped.pr.state, ...shipped.answer };
+    const output = json
+        ? JSON.stringify({ ...local, askedGh: asksGh, pullRequest, close }, null, 2)
+        : linesOf(local, shipped, asksGh, close.line);
+    process.stdout.write(`${output}\n`);
+    return close.verdict === "yes" ? 0 : 1;
+}
+export function run(argv) {
+    const cli = parseCli(argv);
+    if ("error" in cli) {
+        process.stderr.write(`dw-sdlc recap: ${cli.error}\n\n${USAGE}\n`);
+        return 2;
+    }
+    if (cli.help) {
+        process.stdout.write(`${USAGE}\n`);
+        return 0;
+    }
+    try {
+        return report(cli.json);
+    }
+    catch (error) {
+        if (error instanceof CannotRun) {
+            process.stderr.write(`dw-sdlc recap: ${error.message} — ${error.remedy}\n`);
+            return 2;
+        }
+        throw error;
+    }
+}

package/dist/pr/decide.d.ts

@@ -1,4 +1,4 @@
-import type { PrMerge, PrReview, ReviewDepth } from "../agentic-config.ts";
+import type { PrMerge, PrReview, ResolvedConfig, ReviewDepth } from "../agentic-config.ts";
 import { type PrState, REVIEW } from "./state.ts";
 export { REVIEW };
 export type Status = "act" | "wait" | "park" | "done";
@@ -26,6 +26,8 @@ export type Policy = {
     };
     reviewCommand: string;
 };
+/** The policy a repository's `pr` key declares; a flag for one call goes over it. */
+export declare function declaredPolicy({ merge, review, reviewCommand }: ResolvedConfig["pr"]): Policy;
 /** An Action the pull request needs beside the one its answer names, so one push can fix several. */
 export type Blocker = {
     action: Action;
@@ -60,5 +62,9 @@ export declare function hostArgs(pr: PrState, action: ScriptAction, policy: Poli
 export declare function devCommand(pr: PrState, action: ScriptAction, policy: Policy): string;
 /** The merge left to the dev, `reason` saying why it is theirs. */
 export declare function readyToMerge(pr: PrState, policy: Policy, reason: string): Omit<Answer, "blockers">;
+/** `<status> <action>`, the action dropped when it repeats the status. */
+export declare function labelOf({ status, action }: Pick<Answer, "status" | "action">): string;
+/** The label and the reason, then the recheck and the command. */
+export declare function lineOf(answer: Answer): string;
 /** The Action `pr` needs at `now`, milliseconds since the epoch, under `policy`. */
 export declare function decide(pr: PrState, now: number, policy: Policy): Answer;

package/dist/pr/decide.js

@@ -4,6 +4,10 @@
 import { route } from "./route.js";
 import { awaitsReview, OFF_PREFIX, REVIEW } from "./state.js";
 export { REVIEW };
+/** The policy a repository's `pr` key declares; a flag for one call goes over it. */
+export function declaredPolicy({ merge, review, reviewCommand }) {
+    return { merge, review: { depth: review, source: "config" }, reviewCommand };
+}
 /** How long a head may carry no check before it parks as unverified, from its commit. */
 const GRACE_SECONDS = 120;
 /** How long CI may stay pending before it parks as stuck, from the first start among the pending checks. */
@@ -279,6 +283,16 @@ const ROWS = [
         merging: true
     }
 ];
+/** `<status> <action>`, the action dropped when it repeats the status. */
+export function labelOf({ status, action }) {
+    return status === action ? status : `${status} ${action}`;
+}
+/** The label and the reason, then the recheck and the command. */
+export function lineOf(answer) {
+    const { reason, command, recheckAfter } = answer;
+    const recheck = recheckAfter === undefined ? "" : `, recheck in ${recheckAfter} s`;
+    return `${labelOf(answer)}: ${reason}${recheck}${command === undefined ? "" : ` — ${command}`}`;
+}
 function blockerOf({ action, actor, reason, details }) {
     return { action, actor, reason, ...(details === undefined ? {} : { details }) };
 }

package/dist/pr/read.d.ts

@@ -1,5 +1,5 @@
 import { type PrState } from "./state.ts";
-/** What stops a pr command before it answers: exit 2, the problem and its remedy on one line. */
+/** What stops a pr command or recap before it answers: exit 2, the problem and its remedy on one line. */
 export declare class CannotRun extends Error {
     remedy: string;
     constructor(message: string, remedy: string);
@@ -23,6 +23,12 @@ export declare function gh(args: string[]): {
  * `sized`, as `pr.review: auto` needs, the read sizes the changes a Review would read.
  */
 export declare function read(named: Named, command: string, sized: boolean): PrState;
+/** The state of the current branch's pull request, open or not, or null when gh finds none. */
+export declare function readBranch(sized: boolean): PrState | null;
+/** The default branch of the repository gh resolves from the current directory. */
+export declare function defaultBranch(): string;
+/** The time the decision reads: DW_SDLC_NOW, an ISO 8601 time a test sets, else the system clock. */
+export declare function now(): number;
 /** The state of `pr` once more, after an action the script performed on it: the same pull request. */
 export declare function readAgain(pr: PrState, sized: boolean): PrState;
 /** Whether the head of `after` carries the base `before` read: the compare shows it behind by none. */

package/dist/pr/read.js

@@ -1,10 +1,10 @@
-// The read both pr commands make: gh as a child process, its auth on the host gh api reads from, the
-// pull request a command names, and that pull request's state from one GraphQL request, with the two
-// compares that tell whether its head carries an earlier Review and the one that sizes its changes.
+// The read the pr commands and recap make: gh as a child process, its auth, the pull request a command names,
+// its state from one GraphQL request with the compares that tell whether its head carries an earlier Review
+// and that size its changes, and beside them the default branch and the clock the decision reads.
 import { spawnSync } from "node:child_process";
 import { behindOf, changedOf, changesOf, compareArgs, sameChanges } from "./delta.js";
-import { awaitsReview, parsePr, parseView, QUERY, ReplyError } from "./state.js";
-/** What stops a pr command before it answers: exit 2, the problem and its remedy on one line. */
+import { awaitsReview, parseDefaultBranch, parsePr, parseView, QUERY, ReplyError } from "./state.js";
+/** What stops a pr command or recap before it answers: exit 2, the problem and its remedy on one line. */
 export class CannotRun extends Error {
     remedy;
     constructor(message, remedy) {
@@ -17,7 +17,8 @@ const REMEDIES = {
     auth: "run gh auth login, or set GH_TOKEN",
     target: "check the number, or name the repository with -R owner/name",
     read: "check gh auth status and the network, then call again",
-    reply: "gh answered a shape dw-sdlc does not read; report it with the output of gh --version"
+    reply: "gh answered a shape dw-sdlc does not read; report it with the output of gh --version",
+    clock: "unset it: it stands in for the clock in tests"
 };
 /** The problem with `<n>` or `-R` as given on a command line, if there is one. */
 export function namedProblem(number, repo) {
@@ -76,19 +77,54 @@ function targetOf({ number, repo }, command) {
     }
     return parseOrCannotRun(() => parseView(view.stdout));
 }
-/**
- * The state of the pull request `named`; `command`, as `pr ship`, names the call in a remedy. With
- * `sized`, as `pr.review: auto` needs, the read sizes the changes a Review would read.
- */
-export function read(named, command, sized) {
+function requireAuth() {
     // The host gh api reads from: an account on any other host has no say in this call.
     const host = process.env.GH_HOST?.trim() || "github.com";
     const auth = gh(["auth", "status", "--active", "--hostname", host]);
     if (auth.status !== 0) {
         throw new CannotRun(`gh auth status failed: ${authProblem(auth.stderr)}`, REMEDIES.auth);
     }
+}
+/**
+ * The state of the pull request `named`; `command`, as `pr ship`, names the call in a remedy. With
+ * `sized`, as `pr.review: auto` needs, the read sizes the changes a Review would read.
+ */
+export function read(named, command, sized) {
+    requireAuth();
     return query(targetOf(named, command), sized);
 }
+/** The state of the current branch's pull request, open or not, or null when gh finds none. */
+export function readBranch(sized) {
+    requireAuth();
+    const view = gh(["pr", "view", "--json", "url"]);
+    if (view.status === 0) {
+        return query(parseOrCannotRun(() => parseView(view.stdout)), sized);
+    }
+    if (said(view.stderr).startsWith("no pull requests found")) {
+        return null;
+    }
+    throw new CannotRun(`gh pr view failed: ${said(view.stderr)}`, REMEDIES.read);
+}
+/** The default branch of the repository gh resolves from the current directory. */
+export function defaultBranch() {
+    const view = gh(["repo", "view", "--json", "defaultBranchRef"]);
+    if (view.status !== 0) {
+        throw new CannotRun(`gh repo view failed: ${said(view.stderr)}`, REMEDIES.read);
+    }
+    return parseOrCannotRun(() => parseDefaultBranch(view.stdout));
+}
+/** The time the decision reads: DW_SDLC_NOW, an ISO 8601 time a test sets, else the system clock. */
+export 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;
+}
 /** The state of `pr` once more, after an action the script performed on it: the same pull request. */
 export function readAgain(pr, sized) {
     return query(pr, sized);

package/dist/pr/state.d.ts

@@ -46,6 +46,8 @@ export type PrState = {
     checks: CiCheck[];
     /** The threads neither resolved nor outdated. */
     unresolvedThreads: Thread[];
+    /** The oids of the pull request's last 100 commits, oldest first, the head last. */
+    commits: string[];
     /** The last commit before the head with a review success not posted under off, of the last 100. */
     lastReviewed: LastReviewed | null;
     /** Whether the head carries the success of `lastReviewed`: the read decides it from two compares. */
@@ -95,6 +97,8 @@ export declare function parseView(reply: string): {
     repo: string;
     number: number;
 };
+/** The default branch of the repository whose `gh repo view --json defaultBranchRef` printed `reply`. */
+export declare function parseDefaultBranch(reply: string): string;
 /** The state of the pull request in `reply`, the text `gh api graphql` printed for QUERY on `repo`. */
 export declare function parsePr(reply: string, repo: string): Omit<PrState, "carried" | "changed">;
 export {};

package/dist/pr/state.js

@@ -221,6 +221,10 @@ export function parseView(reply) {
     }
     return { repo, number: Number(number) };
 }
+/** The default branch of the repository whose `gh repo view --json defaultBranchRef` printed `reply`. */
+export function parseDefaultBranch(reply) {
+    return string(child(rootOf(reply, "the reply of gh repo view"), "defaultBranchRef"), "name");
+}
 /** The state of the pull request in `reply`, the text `gh api graphql` printed for QUERY on `repo`. */
 export function parsePr(reply, repo) {
     const pr = child(child(child(rootOf(reply, "the reply"), "data"), "repository"), "pullRequest");
@@ -248,6 +252,7 @@ export function parsePr(reply, repo) {
         unresolvedThreads: nodes(pr, "reviewThreads")
             .filter((thread) => !boolean(thread, "isResolved") && !boolean(thread, "isOutdated"))
             .map(threadOf),
+        commits: nodes(pr, "history").map((node) => string(child(node, "commit"), "oid")),
         lastReviewed: lastReviewedOf(pr, head)
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dw-sdlc",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "The Gate and the agentic config of a repository: the dw-sdlc bin with the Gate, the setup, the doctor, the config check, the Sync and setup of References, and the Ship script that drives a pull request to merged; the resolver of the config's layers, its JSON Schema and the validator that reads it.",
   "license": "MIT",
   "repository": {