dw-sdlc 0.9.0 → 0.11.0

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/commands/setup.d.ts

@@ -21,6 +21,8 @@ export type SetupOptions = {
     commitOnProtected?: CommitOnProtected | undefined;
     /** The owner's yes to pinning dw-sdlc as a devDependency where package.json lacks it. */
     addPackage?: boolean;
+    /** The PATH the setup looks for `cswap` on; `$PATH` when absent. */
+    path?: string | undefined;
 };
 export declare const summary = "adopt the Gate where asked, and write this machine's local config layer, the git excludes and the permission rules";
 /**

package/dist/commands/setup.js

@@ -11,6 +11,7 @@ import { COMMIT_CONVENTIONS, COMMITTED_FILE, DEFAULT_GUARDRAILS, LOCAL_FILE, SCH
 import { isObject, parseObject, render } from "../json-text.js";
 import { withGate, withPackage } from "../setup-gate.js";
 import { GLOBAL_DENY, LEASE_RULE, RETIRED_DENY, repositoryDeny } from "../setup-rules.js";
+import { keptWorker, pinnedWorker } from "../setup-worker.js";
 export const summary = "adopt the Gate where asked, and write this machine's local config layer, the git excludes and the permission rules";
 const USAGE = `Usage: dw-sdlc setup [--root <dir>] [--home <dir>]
        [--convention <preset>] [--force-push deny|ask|lease] [--commit-on-protected deny|allow]
@@ -25,7 +26,9 @@ written only when it would change; --convention ticket-key | conventional pins c
 the local config, and a run without it keeps the pin as it is; a guardrails block in the local config
 is kept, and --force-push and --commit-on-protected pin those two keys in it, refused where they would
 loosen what the committed config sets; --force overwrites a local config that differs in anything
-else; --dry-run reports without writing.
+else; --dry-run reports without writing. Where cswap is on PATH, the local config also gets
+worker.command, the command a Worker starts with: cswap run -- --dangerously-skip-permissions. A
+worker block the file holds is kept as it is, and without cswap nothing is written.
 
 Where the repository has a package.json, the setup adopts the Gate. --add-package pins dw-sdlc
 there as a devDependency, at the version running the setup; a new dependency needs the owner's yes,
@@ -99,12 +102,13 @@ function keptGuardrails(existing) {
 }
 /**
  * A layer without the keys the setup owns: `$schema`, which moves with the clone, a pinned
- * convention, which `--convention` may replace, and a `guardrails` object, which the setup carries
- * and the flags pin keys in. Everything left is someone's content.
+ * convention, which `--convention` may replace, and a `guardrails` and a `worker` object, which the
+ * setup carries and adds keys to. Everything left is someone's content.
  */
 function unowned(layer) {
-    const { $schema: _schema, commit, guardrails, ...other } = layer;
-    const rest = guardrails === undefined || isObject(guardrails) ? other : { ...other, guardrails };
+    const { $schema: _schema, commit, ...other } = layer;
+    const blocks = ["guardrails", "worker"];
+    const rest = Object.fromEntries(Object.entries(other).filter(([key, value]) => !blocks.includes(key) || !isObject(value)));
     if (!isObject(commit) || pinnedConvention(layer) === undefined) {
         return commit === undefined ? rest : { ...rest, commit };
     }
@@ -144,9 +148,9 @@ function sameContent(existing, config) {
 }
 /**
  * The machine's layer: what inference finds, minus every key the committed config already sets, which an
- * inferred key here would override, plus the `guardrails` block the file holds and the convention asked for.
+ * inferred key here would override, plus the `guardrails` and `worker` blocks and the convention asked for.
  */
-function localConfig(root, claudeDir, convention, guardrails) {
+function localConfig(root, claudeDir, convention, guardrails, worker) {
     const inferred = inferConfig(root);
     const committed = committedConfig(root);
     const config = { $schema: schemaReference(claudeDir) };
@@ -160,6 +164,9 @@ function localConfig(root, claudeDir, convention, guardrails) {
     if (guardrails !== undefined) {
         config.guardrails = guardrails;
     }
+    if (worker !== undefined) {
+        config.worker = worker;
+    }
     // Only one asked for, by `--convention` or the file's pin: inference always gives `conventional`, and
     // pinning it here would override a convention the repository commits later.
     if (convention !== undefined) {
@@ -255,12 +262,13 @@ export function setup(options) {
         writer.refuse(LOCAL_FILE, pinned.refusal);
     }
     else {
-        const local = localConfig(checkout, claudeDir, convention, pinned.guardrails);
+        const { worker, detail } = pinnedWorker(keptWorker(existing), options.path ?? process.env.PATH);
+        const local = localConfig(checkout, claudeDir, convention, pinned.guardrails, worker);
         if (localCurrent !== undefined && !sameContent(existing, local) && !options.force) {
             writer.refuse(LOCAL_FILE, "exists with other content; pass --force to overwrite it");
         }
         else {
-            writer.put(LOCAL_FILE, localPath, render(local));
+            writer.put(LOCAL_FILE, localPath, render(local), detail);
         }
     }
     // 2. The exclude entries, appended to whatever the file holds: they keep both local files out of git

package/dist/pr/decide.d.ts

@@ -1,24 +1,33 @@
-import type { PrMerge, PrReview } from "../agentic-config.ts";
-import type { PrState } from "./state.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";
 export type Actor = "script" | "agent" | "dev";
 export type Action = "done" | "stop" | "wait" | "fix-conflicts" | "update-branch" | "fix-ci" | "address-review" | "review" | "mark-reviewed" | "unverified" | "ci-stuck" | "awaiting-reply" | "mark-ready" | "awaiting-author" | "awaiting-approval" | "ready-to-merge" | "merge";
 /** The Actions the script performs itself, each one gh command. */
 export type ScriptAction = "update-branch" | "mark-ready" | "mark-reviewed" | "merge";
-/** Where a Review depth comes from: the dev's `--review` for this call, or `pr.review`. */
-export type DepthSource = "flag" | "config";
 /**
- * What the decision reads beside the pull request: who merges it, how closely a Review reads it, and
- * the slash command a `full` Review runs.
+ * Where a Review depth comes from: the dev's `--review` for this call, a depth `pr.review` sets, or the
+ * rules `pr.review: auto` routes it by.
+ */
+export type DepthSource = "flag" | "config" | "auto";
+/**
+ * What the decision reads beside the pull request: who merges it, how closely a Review reads it, the
+ * dev's word or `pr.review`, and the slash command a `full` Review runs.
  */
 export type Policy = {
     merge: PrMerge;
     review: {
+        depth: ReviewDepth;
+        source: "flag";
+    } | {
         depth: PrReview;
-        source: DepthSource;
+        source: "config";
     };
     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;
@@ -34,8 +43,6 @@ export type Answer = Blocker & {
     recheckAfter?: number;
     blockers: Blocker[];
 };
-/** The commit status a clean review of the head leaves on it. */
-export declare const REVIEW = "dw-sdlc/review";
 /** Its one state: a failure or a pending status would turn the pull request unstable. */
 export declare const REVIEW_STATE = "success";
 /** The words as one POSIX shell command line, each word that needs it single-quoted. */
@@ -55,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

@@ -1,14 +1,19 @@
 // The decision of the Ship script: one ordered list of rows, and the first row whose `when` holds for
 // the pull request answers its Action at the time given; every later row that holds rides in its
 // blockers. The last rows say who merges what no row before them holds back.
+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. */
 const BUDGET_MINUTES = 40;
 /** The prefix of the contexts the script posts itself, as `dw-sdlc/review`: never CI. */
 const OWN_PREFIX = "dw-sdlc/";
-/** The commit status a clean review of the head leaves on it. */
-export const REVIEW = "dw-sdlc/review";
 /** Its one state: a failure or a pending status would turn the pull request unstable. */
 export const REVIEW_STATE = "success";
 /** The words as one POSIX shell command line, each word that needs it single-quoted. */
@@ -44,15 +49,49 @@ export function reviewStatusArgs(pr, description) {
     const flags = Object.entries(fields).flatMap(([key, value]) => ["-f", `${key}=${value}`]);
     return ["api", `repos/${pr.repo}/statuses/${pr.head}`, "--method", "POST", "--silent", ...flags];
 }
-/** Why a head no one reads carries the success: the dev's word or the config. */
-function offDescription(policy) {
-    return `off: ${policy.review.source === "flag" ? "--review off" : "pr.review"}`;
+/** Whether the dev named a depth for a head that would carry the status: their word beats the carry. */
+function flagOverCarry(pr, { review }) {
+    return pr.carried && review.source === "flag";
+}
+/** The reviewed commit whose success the head carries, if it does and the dev named no depth. */
+function carriedFrom(pr, policy) {
+    return pr.carried && !flagOverCarry(pr, policy) ? (pr.lastReviewed?.commit ?? null) : null;
+}
+/**
+ * The commit the Review reads from: the last reviewed one. Over a carry the dev's depth reads the whole
+ * diff, since the changes after that commit are only the base's.
+ */
+function sinceOf(pr, policy) {
+    return flagOverCarry(pr, policy) ? null : (pr.lastReviewed?.commit ?? null);
+}
+/** The depth a Review reads the head at: the dev's or the one `pr.review` sets, else the one the rules route. */
+function depthOf(pr, { review }) {
+    const { depth, source } = review;
+    if (depth === "off") {
+        return { depth, source, why: source === "flag" ? "--review off" : "pr.review" };
+    }
+    if (depth !== "auto") {
+        return { depth, source };
+    }
+    return { ...route(pr.changed), source: "auto" };
+}
+/** Why the head carries the success the script posts: the Review it carries, else why its depth is off. */
+function markedDescription(pr, policy) {
+    const carried = carriedFrom(pr, policy);
+    if (carried !== null) {
+        return `carried from ${carried.slice(0, 7)}`;
+    }
+    const depth = depthOf(pr, policy);
+    if (depth.depth !== "off") {
+        throw new Error(`the script marks ${pr.url} reviewed at ${depth.depth}, neither off nor a carry`);
+    }
+    return `${OFF_PREFIX} ${depth.why}`;
 }
 /** A script Action's gh arguments; `repo` is `-R` and the repository when the call names it, else empty. */
 const HOST = {
     "update-branch": (pr, repo) => ["pr", "update-branch", String(pr.number), ...repo],
     "mark-ready": (pr, repo) => ["pr", "ready", String(pr.number), ...repo],
-    "mark-reviewed": (pr, _, policy) => reviewStatusArgs(pr, offDescription(policy)),
+    "mark-reviewed": (pr, _, policy) => reviewStatusArgs(pr, markedDescription(pr, policy)),
     merge: (pr, repo) => ["pr", "merge", String(pr.number), ...repo, "--squash", "--match-head-commit", pr.head]
 };
 export function isScriptAction(action) {
@@ -141,17 +180,29 @@ const ROWS = [
         answer: () => ({ status: "act", action: "address-review", actor: "agent", reason: "changes requested" })
     },
     {
-        // The dev merges another author's pull request, so it needs no Review. Under off no one reads
-        // the head: the script posts the success itself.
-        when: (pr) => pr.viewerDidAuthor && !pr.checks.some((check) => check.name === REVIEW && check.bucket === "pass"),
-        answer: (pr, _, { review, reviewCommand }) => {
-            const off = review.depth === "off";
+        // Another author's pull request needs no Review: the dev merges it. The script posts the success
+        // under off, and over a carry, which reads at no depth.
+        when: awaitsReview,
+        answer: (pr, _, policy) => {
+            const since = sinceOf(pr, policy);
+            const head = { status: "act", reason: `no ${REVIEW} success on ${pr.head.slice(0, 7)}` };
+            const after = since === null ? {} : { since };
+            if (carriedFrom(pr, policy) !== null) {
+                return { ...head, action: "mark-reviewed", actor: "script", details: after };
+            }
+            const { depth, source } = depthOf(pr, policy);
+            const byScript = depth === "off";
             return {
-                status: "act",
-                action: off ? "mark-reviewed" : "review",
-                actor: off ? "script" : "agent",
-                reason: `no ${REVIEW} success on ${pr.head.slice(0, 7)}`,
-                details: { ...review, ...(review.depth === "full" ? { reviewCommand } : {}) }
+                ...head,
+                action: byScript ? "mark-reviewed" : "review",
+                actor: byScript ? "script" : "agent",
+                details: {
+                    depth,
+                    source,
+                    // The agent may raise a routed depth to full, so auto names the command at any depth.
+                    ...(depth === "full" || source === "auto" ? { reviewCommand: policy.reviewCommand } : {}),
+                    ...after
+                }
             };
         }
     },
@@ -232,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/delta.d.ts

@@ -0,0 +1,11 @@
+import { type ChangedFile } from "./state.ts";
+/** The gh arguments of the compare from `from` to `commit`, the files on its one page. */
+export declare function compareArgs(repo: string, from: string, commit: string): string[];
+/** How many commits of the compare's base its head lacks: 0 when the head carries all of it. */
+export declare function behindOf(reply: string): number;
+/** The own changes a compare reply lists, file by file; null when it cannot show them whole. */
+export declare function changesOf(reply: string): string[] | null;
+/** The files a compare reply lists with their changed lines; `unsized` when it may hold some back. */
+export declare function changedOf(reply: string): ChangedFile[] | "unsized";
+/** Whether the own changes at the head are those at the reviewed commit; unknown changes never are. */
+export declare function sameChanges(then: string[] | null, now: string[] | null): boolean;