dw-sdlc 0.12.1 → 0.14.0

package/dist/commands/sweep.js

@@ -0,0 +1,406 @@
+// `dw-sdlc sweep`: removes each linked worktree whose whole set passes and each Landed local branch.
+// docs/adr/0015 sets its bounds: it runs from the main checkout, never forces and never writes to a remote.
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { findRepository, mainCheckout, resolveConfig } from "../agentic-config.js";
+import { repositoryFreeEnv } from "../git-env.js";
+import { isCommitLanded, isLanded } from "../landed.js";
+import { shellLine } from "../pr/decide.js";
+import { CannotRun } from "../pr/read.js";
+import { byHand, holdersOf, keptIn, lockAfterStop, lockHolder, outsideWorktrees, readTerminals, removeTerminal, stopsOf, sweepingTerminal, whyHeld } from "../sweep-terminals.js";
+import { dirtyFiles, must, pausedOperation, worktreesOf } from "../sweep-trees.js";
+import { asked, git } from "../working-tree.js";
+import { lockVerdict } from "../worktree-lock.js";
+export const summary = "removes Landed branches and clean worktrees whose work has landed, names what it keeps";
+const USAGE = `Usage: dw-sdlc sweep [--dry-run] [--json]
+
+Run from the main checkout. Fetches origin, reads the base branch as the guards do (baseBranch of the
+config, else the branch origin/HEAD names) and removes, never forcing:
+  every linked worktree, wherever it lies, whose whole set passes: no modified or untracked file (ignored
+  files aside), no paused rebase, merge, cherry-pick, revert or bisect, no lock but a stale Claude Code
+  one, and its HEAD Landed, on a branch or detached; the branch it had checked out goes right after it. A
+  Claude Code lock, "claude session <name> (pid <N> start <time>)", is stale when no process N runs or N
+  started at another time; it is lifted just before its worktree goes, and lifted for no worktree that stays;
+  every other local branch that is Landed: its work is on the base, as a squash merge leaves it.
+It keeps, and names with the reason and the command to run yourself:
+  a worktree that fails the set: the files that hold it with the forced removal, the paused operation, the
+  lock's reason with git worktree unlock, a live Claude Code lock named by its pid, a HEAD that is not Landed;
+  the default branch, the base branch, a protected branch and a branch a kept worktree has checked out;
+  a branch whose work is on no commit of the base, with the forced delete.
+It never changes anything on a remote: the fetch only writes remote-tracking refs. A removal git refuses is
+kept with git's words, and the sweep goes on.
+
+In herdr ($HC_TERMINAL_ID set) it reads, with hc, the Workers of this session, the terminals whose parent is
+this one, and every other live terminal. A Worker whose status is none of working, blocked or yet to report
+is stopped (hc kill) then removed (hc rm) when its worktree goes in the same Sweep or its folder is already
+gone; a worktree is judged whole first, so no Worker is stopped beside work it could still commit. A live
+Claude Code lock on that worktree that names the Worker's own program, the pid hc get reports, does not keep
+it: once the Worker is stopped the lock is read again and lifted only when it is stale then, else the
+worktree stays. A finished Worker of this session is removed. This session's own terminal and another
+session's are never stopped: a worktree one is in stays, named with the terminal's address and place and
+hc kill as the dev's command. Outside herdr no terminal is read, and the output says so. An hc that fails
+ends the Sweep with exit 2 before anything is removed.
+
+--dry-run removes and stops nothing and answers the same items. One line an item, or one document with --json:
+  { dryRun, terminalsRead, base, removed: [item], kept: [item] }, an item { kind, name, reason, command? },
+  kind branch, worktree, lock (a lifted one) or terminal, name its path or its address, command the one the
+  dev would run for a kept item.
+
+Exit 0 nothing is kept but the default, the base or a protected branch, 1 something else is, 2 when it
+cannot run: in a linked worktree, with no base to read, when the fetch fails or when hc fails in herdr.`;
+function forcedDelete(branch) {
+    return shellLine(["git", "branch", "-D", branch]);
+}
+/** The forced removal; git wants --force twice for a worktree still locked. */
+function forcedRemoval(path, locked = false) {
+    return shellLine(["git", "worktree", "remove", "--force", ...(locked ? ["--force"] : []), path]);
+}
+function fetchOrigin(root) {
+    if (asked(root, ["remote", "get-url", "origin"]) === undefined) {
+        return;
+    }
+    const env = { ...repositoryFreeEnv(), GIT_TERMINAL_PROMPT: "0" };
+    const result = spawnSync("git", ["-C", root, "fetch", "--quiet", "origin"], { encoding: "utf8", env, stdio: "pipe" });
+    if (result.status !== 0) {
+        const said = result.stderr.split("\n").find((line) => line.trim() !== "");
+        throw new CannotRun(`git fetch origin failed: ${said?.trim() ?? `exited ${result.status}`}`, "check the network, then call again");
+    }
+}
+/** The branch refs/remotes/origin/HEAD names, if it names one of origin. */
+function originHead(root) {
+    const prefix = "refs/remotes/origin/";
+    const ref = asked(root, ["symbolic-ref", "-q", "refs/remotes/origin/HEAD"]);
+    return ref !== undefined && ref.startsWith(prefix) && ref.length > prefix.length
+        ? ref.slice(prefix.length)
+        : undefined;
+}
+/** The base branch the guard reads: `baseBranch` of the config, under `auto` the branch origin/HEAD names. */
+function baseOf(root, head) {
+    const configured = resolveConfig(root).config.baseBranch;
+    const name = configured === "" || configured === "auto" ? head : configured;
+    if (name === undefined) {
+        throw new CannotRun("no base branch is known to check the branches against: origin/HEAD names no branch of origin", "run git remote set-head origin --auto, or set baseBranch in .ai/agentic.config.json");
+    }
+    const ref = `refs/remotes/origin/${name}`;
+    if (asked(root, ["check-ref-format", ref]) === undefined ||
+        asked(root, ["rev-parse", "--verify", "-q", `${ref}^{commit}`]) === undefined) {
+        throw new CannotRun(`the base branch origin/${name} is not here to check the branches against`, "run git fetch origin, or fix baseBranch in .ai/agentic.config.json");
+    }
+    return { name, ref };
+}
+function branchesOf(root) {
+    return must(root, ["for-each-ref", "--format=%(refname:lstrip=2)", "refs/heads"])
+        .split("\n")
+        .filter((name) => name !== "");
+}
+/** Why the worktree stays, with the dev's command when there is one, or null when its whole set passes. */
+function whyTreeStays(root, baseRef, tree, lock, holders) {
+    const { path } = tree;
+    if (lock.state === "stays") {
+        return lock;
+    }
+    const held = whyHeld(holders);
+    if (held !== null) {
+        return held;
+    }
+    if (tree.prunable || !existsSync(path)) {
+        const prune = shellLine(["git", "worktree", "prune"]);
+        return {
+            reason: "its folder is gone",
+            command: lock.state === "stale" ? `${shellLine(["git", "worktree", "unlock", path])} && ${prune}` : prune
+        };
+    }
+    const operation = pausedOperation(path);
+    if (operation !== undefined) {
+        return { reason: `a ${operation} is paused in it`, command: null };
+    }
+    const files = dirtyFiles(path);
+    if ("error" in files) {
+        return { reason: files.error, command: null };
+    }
+    if (files.length > 0) {
+        return {
+            reason: `modified or untracked: ${files.join(", ")}`,
+            command: forcedRemoval(path, lock.state === "stale")
+        };
+    }
+    if (!isCommitLanded(root, baseRef, tree.head)) {
+        const at = tree.branch === undefined ? `its detached HEAD ${tree.head.slice(0, 9)}` : `its HEAD on ${tree.branch}`;
+        return { reason: `${at} is on no commit of ${baseRef.replace("refs/remotes/", "")} since it forked`, command: null };
+    }
+    return null;
+}
+/** A branch kept for what it is, never the dev's to decide. */
+function standing(reason) {
+    return { reason, command: null, dev: false };
+}
+/** Why `branch` stays whatever its work, or null when only its work decides. */
+function stays(branch, { head, baseBranch, protectedBranches, held }) {
+    if (branch === head) {
+        return standing("the default branch");
+    }
+    if (branch === baseBranch) {
+        return standing("the base branch");
+    }
+    if (protectedBranches.includes(branch)) {
+        return standing("a protected branch");
+    }
+    const path = held.get(branch);
+    return path === undefined ? null : { reason: `checked out in the worktree at ${path}`, command: null, dev: true };
+}
+/** Fetches origin, then sorts each linked worktree, local branch and Worker's terminal into what goes and what stays. */
+function judge(root, terminals) {
+    fetchOrigin(root);
+    const head = originHead(root);
+    const base = baseOf(root, head);
+    const baseName = `origin/${base.name}`;
+    const [checkout, ...linked] = worktreesOf(root);
+    if (checkout === undefined) {
+        throw new CannotRun("git lists no worktree", "check the repository with git worktree list");
+    }
+    const holders = terminals === undefined
+        ? new Map()
+        : holdersOf(terminals, checkout.path, linked.map(({ path }) => path));
+    const verdicts = linked.map((tree) => {
+        const lock = lockVerdict(tree.path, tree.lock);
+        const here = holders.get(tree.path) ?? [];
+        const pid = lock.state === "stays" ? lock.pid : undefined;
+        const workerLock = pid !== undefined && lockHolder(pid, here) !== undefined ? { pid } : undefined;
+        const why = whyTreeStays(root, base.ref, tree, workerLock === undefined ? lock : { state: "none" }, here);
+        return { tree, lock, here, why, workerLock };
+    });
+    const staying = verdicts.filter(({ why }) => why !== null).map(({ tree }) => tree);
+    const held = new Map();
+    for (const { path, branch } of [checkout, ...staying]) {
+        if (branch !== undefined) {
+            held.set(branch, path);
+        }
+    }
+    const footing = {
+        head,
+        baseBranch: base.name,
+        protectedBranches: resolveConfig(root).config.guardrails.protectedBranches,
+        held
+    };
+    const removed = [];
+    const kept = [];
+    const judged = new Set();
+    const judgeBranch = (name) => {
+        if (judged.has(name)) {
+            return;
+        }
+        judged.add(name);
+        const why = stays(name, footing);
+        if (why !== null) {
+            kept.push({ kind: "branch", name, ...why });
+        }
+        else if (isLanded(root, base.ref, name)) {
+            removed.push({ kind: "branch", name, reason: `Landed on ${baseName}` });
+        }
+        else {
+            const reason = `its work is on no commit of ${baseName} since it forked`;
+            kept.push({ kind: "branch", name, reason, command: forcedDelete(name), dev: true });
+        }
+    };
+    const outside = terminals === undefined
+        ? { remove: [], keep: [] }
+        : outsideWorktrees(terminals, [checkout.path, ...linked.map(({ path }) => path)]);
+    removed.push(...outside.remove);
+    for (const { name, reason } of outside.keep) {
+        kept.push({ kind: "terminal", name, reason, command: null, dev: true });
+    }
+    for (const { tree, lock, here, why, workerLock } of verdicts) {
+        if (why !== null) {
+            kept.push({ kind: "worktree", name: tree.path, ...why, dev: true });
+            kept.push(...keptIn(here, tree.path).map((item) => ({ kind: "terminal", ...item, dev: true })));
+            continue;
+        }
+        removed.push(...stopsOf(here, tree.path));
+        const reason = `clean, its HEAD is Landed on ${baseName}`;
+        removed.push({
+            kind: "worktree",
+            name: tree.path,
+            reason,
+            ...(tree.branch === undefined ? {} : { holds: tree.branch }),
+            ...(lock.state === "stale" ? { stale: lock } : {}),
+            ...(workerLock === undefined ? {} : { workerLock })
+        });
+        if (tree.branch !== undefined) {
+            judgeBranch(tree.branch);
+        }
+    }
+    branchesOf(root).forEach(judgeBranch);
+    return { base: baseName, removed, kept };
+}
+/** Removes `item`; the item kept when git refuses it, with git's words, or undefined once it is gone. */
+function removal(root, item, heldBy, unstopped) {
+    const refused = (reason, command) => ({
+        kind: item.kind,
+        name: item.name,
+        reason,
+        command,
+        dev: true
+    });
+    if (item.kind === "terminal") {
+        const failed = removeTerminal(item);
+        if (failed === undefined) {
+            return undefined;
+        }
+        if (item.tree !== undefined) {
+            unstopped.set(item.tree, `its Worker's terminal ${item.name} stays: ${failed}`);
+        }
+        return refused(failed, byHand(item));
+    }
+    if (item.kind === "worktree") {
+        const refusedWith = (reason, command) => {
+            if (item.holds !== undefined) {
+                heldBy.set(item.holds, item.name);
+            }
+            return refused(reason, command);
+        };
+        const unstoppable = unstopped.get(item.name);
+        if (unstoppable !== undefined) {
+            return refusedWith(unstoppable, null);
+        }
+        if (item.workerLock !== undefined) {
+            const now = lockAfterStop(root, item.name);
+            if (now.state === "stays") {
+                return refusedWith(`its Worker's terminal was stopped, but ${now.reason}`, now.command);
+            }
+            if (now.state === "stale") {
+                item.stale = now;
+            }
+            delete item.workerLock;
+        }
+        if (item.stale !== undefined) {
+            const lifted = git(root, ["worktree", "unlock", "--", item.name]);
+            if ("error" in lifted) {
+                return refusedWith(lifted.error, shellLine(["git", "worktree", "unlock", item.name]));
+            }
+        }
+        const result = git(root, ["worktree", "remove", "--", item.name]);
+        if (!("error" in result)) {
+            return undefined;
+        }
+        const relocked = item.stale === undefined
+            ? undefined
+            : git(root, ["worktree", "lock", "--reason", item.stale.held, "--", item.name]);
+        const lost = relocked !== undefined && "error" in relocked ? `; its lock could not be put back: ${relocked.error}` : "";
+        return refusedWith(`${result.error}${lost}`, forcedRemoval(item.name, item.stale !== undefined));
+    }
+    const path = heldBy.get(item.name);
+    if (path !== undefined) {
+        return refused(`checked out in the worktree at ${path}`, null);
+    }
+    const result = git(root, ["branch", "-D", "--", item.name]);
+    return "error" in result ? refused(result.error, forcedDelete(item.name)) : undefined;
+}
+/** Removes each item judged to go, in order; a refused worktree keeps the branch it holds as well. */
+function apply({ base, removed, kept }, root) {
+    const gone = [];
+    const refused = [];
+    const heldBy = new Map();
+    const unstopped = new Map();
+    for (const item of removed) {
+        const stayed = removal(root, item, heldBy, unstopped);
+        if (stayed === undefined) {
+            gone.push(item);
+        }
+        else {
+            refused.push(stayed);
+        }
+    }
+    return { base, removed: gone, kept: [...kept, ...refused] };
+}
+/** The removed items as the Sweep tells them: a stale lock lifted comes just before its worktree. */
+function shownOf(removed) {
+    return removed.flatMap(({ kind, name, reason, stale, workerLock }) => {
+        const item = { kind, name, reason };
+        if (workerLock !== undefined) {
+            const why = `held by its Worker's program, pid ${workerLock.pid}: lifted once the stop leaves it stale`;
+            return [{ kind: "lock", name, reason: why }, item];
+        }
+        return stale === undefined ? [item] : [{ kind: "lock", name, reason: stale.why }, item];
+    });
+}
+function verbOf(kind, dryRun) {
+    if (kind === "lock") {
+        return dryRun ? "would lift" : "lifted";
+    }
+    return dryRun ? "would remove" : "removed";
+}
+function linesOf({ dryRun, terminalsRead, removed, kept }) {
+    const out = [
+        ...removed.map(({ kind, name, reason }) => `${verbOf(kind, dryRun)} ${kind} ${name} — ${reason}`),
+        ...kept.map(({ kind, name, reason, command }) => {
+            return `kept ${kind} ${name} — ${reason}${command === null || command === undefined ? "" : `; to remove it yourself: ${command}`}`;
+        })
+    ];
+    const note = terminalsRead ? [] : ["terminals not read — outside herdr, $HC_TERMINAL_ID is not set"];
+    return [...(out.length === 0 ? ["nothing to sweep"] : out), ...note].join("\n");
+}
+function parseCli(argv) {
+    try {
+        const { values, positionals } = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                help: { type: "boolean", short: "h" },
+                json: { type: "boolean" },
+                "dry-run": { 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, dryRun: values["dry-run"] === true };
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) };
+    }
+}
+function sweep(json, dryRun) {
+    const root = findRepository(process.cwd());
+    if (root === undefined) {
+        throw new CannotRun(`no git repository holds ${process.cwd()}`, "run it from the main checkout");
+    }
+    const main = mainCheckout(root);
+    if (main !== undefined) {
+        throw new CannotRun(`${root} is a linked worktree`, `run it from the main checkout: ${shellLine(["cd", main])} && dw-sdlc sweep`);
+    }
+    const own = sweepingTerminal();
+    const terminals = own === undefined ? undefined : readTerminals(own);
+    const judged = judge(root, terminals);
+    const { base, removed, kept } = dryRun ? judged : apply(judged, root);
+    const done = {
+        dryRun,
+        terminalsRead: terminals !== undefined,
+        base,
+        removed: shownOf(removed),
+        kept: kept.map(({ kind, name, reason, command }) => ({ kind, name, reason, command }))
+    };
+    process.stdout.write(`${json ? JSON.stringify(done, null, 2) : linesOf(done)}\n`);
+    return kept.some(({ dev }) => dev) ? 1 : 0;
+}
+export function run(argv) {
+    const cli = parseCli(argv);
+    if ("error" in cli) {
+        process.stderr.write(`dw-sdlc sweep: ${cli.error}\n\n${USAGE}\n`);
+        return 2;
+    }
+    if (cli.help) {
+        process.stdout.write(`${USAGE}\n`);
+        return 0;
+    }
+    try {
+        return sweep(cli.json, cli.dryRun);
+    }
+    catch (error) {
+        if (error instanceof CannotRun) {
+            process.stderr.write(`dw-sdlc sweep: ${error.message} — ${error.remedy}\n`);
+            return 2;
+        }
+        throw error;
+    }
+}

package/dist/landed.d.ts

@@ -0,0 +1,7 @@
+/** Whether the work of the local `branch` is on `baseRef`; see `isCommitLanded`. */
+export declare function isLanded(root: string, baseRef: string, branch: string): boolean;
+/**
+ * Whether the work of the commit `tip` is on `baseRef`: it is on it, or a base commit since the fork holds
+ * its tree or the verbatim patch-id of its whole diff, as a squash merge leaves them.
+ */
+export declare function isCommitLanded(root: string, baseRef: string, tip: string): boolean;

package/dist/landed.js

@@ -0,0 +1,86 @@
+// Whether a local branch is Landed: its work is on the base, as the guard's `guard_landed`
+// (plugins/sdlc/hooks/lib-git.sh) judges it. The guard keeps its own bash version; docs/adr/0015 says why there
+// are two, and the shared table of scenarios, plugins/sdlc/test/landed-scenarios.ts, holds them to one meaning.
+import { spawnSync } from "node:child_process";
+import { repositoryFreeEnv } from "./git-env.js";
+/** The base commits read, newest first: a branch that forked further back is kept rather than read for seconds. */
+const SCAN = 5000;
+/** Only local objects: a partial clone's missing blob is no reason to ask its remote. */
+function localEnv() {
+    return { ...repositoryFreeEnv(), GIT_NO_LAZY_FETCH: "1" };
+}
+function git(root, args, input) {
+    const result = spawnSync("git", ["-C", root, ...args], {
+        encoding: "utf8",
+        env: localEnv(),
+        input,
+        maxBuffer: 64 * 1024 * 1024
+    });
+    return { status: result.status ?? 1, stdout: result.stdout ?? "" };
+}
+/** What `git <args>` prints, or undefined when it exits non-zero. */
+function answer(root, args, input) {
+    const ran = git(root, args, input);
+    return ran.status === 0 ? ran.stdout.trim() : undefined;
+}
+/** The patch-id of the whole diff from `from` to `to`; undefined for an empty diff or one git could not finish. */
+function patchIdOf(root, from, to) {
+    const diff = git(root, ["diff-tree", "-p", "--binary", "--no-renames", from, to]);
+    if (diff.status !== 0) {
+        return undefined;
+    }
+    const id = answer(root, ["patch-id", "--verbatim"], diff.stdout)?.split(" ")[0];
+    return id === undefined || id === "" ? undefined : id;
+}
+/** Whether a base commit in `range`, merges aside, has `patch` for the patch-id of its diff. */
+function baseHoldsPatch(root, range, patch) {
+    // The diffs stream from git to git, never into this process: SCAN commits can print far past a buffer.
+    // pipefail: a diff cut short by a missing object fails the scan instead of naming part of the work.
+    const pipeline = [
+        "set -o pipefail",
+        [
+            'git -C "$1" rev-list --no-merges --max-count="$2" "$3"',
+            'git -C "$1" diff-tree --stdin -p --binary --no-renames 2>/dev/null',
+            "git patch-id --verbatim"
+        ].join(" | ")
+    ].join("; ");
+    const result = spawnSync("bash", ["-c", pipeline, "bash", root, String(SCAN), range], {
+        encoding: "utf8",
+        env: localEnv(),
+        maxBuffer: 64 * 1024 * 1024
+    });
+    if (result.status !== 0) {
+        return false;
+    }
+    return result.stdout.split("\n").some((line) => line.split(" ")[0] === patch);
+}
+/** Whether the work of the local `branch` is on `baseRef`; see `isCommitLanded`. */
+export function isLanded(root, baseRef, branch) {
+    const ref = `refs/heads/${branch}`;
+    if (answer(root, ["check-ref-format", ref]) === undefined) {
+        return false;
+    }
+    const tip = answer(root, ["rev-parse", "--verify", "-q", `${ref}^{commit}`]);
+    return tip !== undefined && isCommitLanded(root, baseRef, tip);
+}
+/**
+ * Whether the work of the commit `tip` is on `baseRef`: it is on it, or a base commit since the fork holds
+ * its tree or the verbatim patch-id of its whole diff, as a squash merge leaves them.
+ */
+export function isCommitLanded(root, baseRef, tip) {
+    if (git(root, ["merge-base", "--is-ancestor", tip, baseRef]).status === 0) {
+        return true;
+    }
+    const fork = answer(root, ["merge-base", tip, baseRef]);
+    const tree = answer(root, ["rev-parse", `${tip}^{tree}`]);
+    if (fork === undefined || tree === undefined || tree === answer(root, ["rev-parse", `${fork}^{tree}`])) {
+        return false;
+    }
+    const range = `${fork}..${baseRef}`;
+    const trees = answer(root, ["log", "--format=%T", `--max-count=${SCAN}`, range]) ?? "";
+    if (trees.split("\n").includes(tree)) {
+        return true;
+    }
+    const patch = patchIdOf(root, fork, tip);
+    return patch !== undefined && baseHoldsPatch(root, range, patch);
+}

package/dist/pr/decide.d.ts

@@ -3,7 +3,7 @@ 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";
+export type Action = "done" | "stop" | "wait" | "fix-conflicts" | "update-branch" | "fix-ci" | "address-review" | "review" | "review-limit" | "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";
 /**
@@ -43,15 +43,19 @@ export type Answer = Blocker & {
     recheckAfter?: number;
     blockers: Blocker[];
 };
-/** Its one state: a failure or a pending status would turn the pull request unstable. */
+/**
+ * The state of the review status a clean or skipped Review leaves; the read mark's is failure, on a
+ * head the fix then leaves behind. 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. */
 export declare function shellLine(words: string[]): string;
 /**
- * The gh arguments that post the `dw-sdlc/review` success on the head, `description` saying how it was
- * read. The path names the repository, so the call reads the same from any checkout.
+ * The gh arguments that post `dw-sdlc/review` on the head, a success unless `state` says otherwise,
+ * `description` saying how it was read. The path names the repository, so the call reads the same from
+ * any checkout.
  */
-export declare function reviewStatusArgs(pr: PrState, description: string): string[];
+export declare function reviewStatusArgs(pr: PrState, description: string, state?: string): string[];
 export declare function isScriptAction(action: Action): action is ScriptAction;
 /**
  * The gh arguments of a script Action, `-R` naming the repository when `named`. The update merges the

package/dist/pr/decide.js

@@ -12,9 +12,18 @@ export function declaredPolicy({ merge, review, reviewCommand }) {
 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;
+/**
+ * How many Reviews that each left a Finding open, with no success between them, the script lets run: the
+ * next call parks the pull request for the dev. A constant, like the depth rules, so no repository turns
+ * the loop back on.
+ */
+const REVIEW_LIMIT = 3;
 /** The prefix of the contexts the script posts itself, as `dw-sdlc/review`: never CI. */
 const OWN_PREFIX = "dw-sdlc/";
-/** Its one state: a failure or a pending status would turn the pull request unstable. */
+/**
+ * The state of the review status a clean or skipped Review leaves; the read mark's is failure, on a
+ * head the fix then leaves behind. 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. */
 export function shellLine(words) {
@@ -41,11 +50,12 @@ function listed({ id, path, line, author, body }) {
     return { id, path, line, author, body };
 }
 /**
- * The gh arguments that post the `dw-sdlc/review` success on the head, `description` saying how it was
- * read. The path names the repository, so the call reads the same from any checkout.
+ * The gh arguments that post `dw-sdlc/review` on the head, a success unless `state` says otherwise,
+ * `description` saying how it was read. The path names the repository, so the call reads the same from
+ * any checkout.
  */
-export function reviewStatusArgs(pr, description) {
-    const fields = { state: REVIEW_STATE, context: REVIEW, target_url: pr.url, description };
+export function reviewStatusArgs(pr, description, state = REVIEW_STATE) {
+    const fields = { state, context: REVIEW, target_url: pr.url, description };
     const flags = Object.entries(fields).flatMap(([key, value]) => ["-f", `${key}=${value}`]);
     return ["api", `repos/${pr.repo}/statuses/${pr.head}`, "--method", "POST", "--silent", ...flags];
 }
@@ -55,14 +65,15 @@ function flagOverCarry(pr, { review }) {
 }
 /** 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;
+    return pr.carried && !flagOverCarry(pr, policy) ? (pr.lastRead?.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.
+ * The commit the Review reads from: the last one a Review read, clean or not, so the Review after a fix
+ * reads the fix. 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);
+    return flagOverCarry(pr, policy) ? null : (pr.lastRead?.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 }) {
@@ -87,6 +98,18 @@ function markedDescription(pr, policy) {
     }
     return `${OFF_PREFIX} ${depth.why}`;
 }
+/** The park at the limit: the dev accepts the head as it stands, or names a depth for one more Review. */
+function reviewLimit(pr) {
+    const { count, since } = pr.marks;
+    const from = since === null ? "the start of the pull request" : `the success on ${since.slice(0, 7)}`;
+    return {
+        status: "park",
+        action: "review-limit",
+        actor: "dev",
+        reason: `${count} Reviews since ${from} left a Finding open: accepting the head is the dev's`,
+        command: shellLine(["dw-sdlc", "pr", "reviewed", String(pr.number), "-R", pr.repo, "--head", pr.head, "--accept"])
+    };
+}
 /** 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],
@@ -192,6 +215,10 @@ const ROWS = [
                 return { ...head, action: "mark-reviewed", actor: "script", details: after };
             }
             const { depth, source } = depthOf(pr, policy);
+            // The dev's own depth buys one Review past the limit; a Review under off needs none.
+            if (depth !== "off" && source !== "flag" && pr.marks.count >= REVIEW_LIMIT) {
+                return reviewLimit(pr);
+            }
             const byScript = depth === "off";
             return {
                 ...head,

package/dist/pr/read.d.ts

@@ -18,6 +18,8 @@ export declare function gh(args: string[]): {
     stdout: string;
     stderr: string;
 };
+/** The remedy for a pull request `command`, as `pr ship`, cannot find by itself: name it in full. */
+export declare function nameItRemedy(command: string): string;
 /**
  * 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.