dw-sdlc 0.11.0 → 0.12.1

package/dist/commands/worker-report.js

@@ -0,0 +1,117 @@
+// `dw-sdlc worker report`: delivers a Worker's Recap to its Lead, and keeps trying while the Lead is blocked.
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { parseArgs } from "node:util";
+import { call, describe, lead, refuse, Refusal, said, wholeNumber } from "../worker/herdr.js";
+export const summary = "deliver a Recap to the Lead, retrying while it is blocked";
+const USAGE = `Usage: dw-sdlc worker report --to <lead> --recap <file> [--attempts <n>] [--interval <seconds>]
+
+Sends the Recap in <file> to the Lead's terminal with hc send. A Recap of one short line goes as itself;
+anything longer goes as the absolute path of its file, which the Lead reads.
+
+hc send exits 9 when the Lead is blocked on a dialog. The command then waits --interval seconds (default
+60) and sends again, up to --attempts sends (default 30), and exits 1 when the Lead is still blocked. It
+never passes --force: typing into a blocked Lead may answer its dialog. Any other refusal of hc send ends
+it at once with exit 1.
+
+Needs a terminal herdr started ($HC_TERMINAL_ID) and hc on PATH.
+
+Exit 0 delivered, 1 not delivered, 2 when it cannot run.`;
+/** `hc send` exits with this when the target is blocked on a permission or a question. */
+const BLOCKED = 9;
+const DEFAULT_ATTEMPTS = 30;
+const DEFAULT_INTERVAL = 60;
+/** The longest Recap that goes as itself, in characters; a longer one goes as a path. */
+const SHORT = 300;
+function parseCli(argv) {
+    try {
+        const { values } = parseArgs({
+            args: argv,
+            options: {
+                help: { type: "boolean", short: "h" },
+                to: { type: "string" },
+                recap: { type: "string" },
+                attempts: { type: "string" },
+                interval: { type: "string" }
+            }
+        });
+        if (values.help === true) {
+            return "help";
+        }
+        const { to, recap } = values;
+        if (to === undefined || to === "") {
+            return { error: "name the Lead's terminal: --to <lead>" };
+        }
+        if (recap === undefined) {
+            return { error: "name the Recap file: --recap <file>" };
+        }
+        const attempts = wholeNumber("--attempts", values.attempts, DEFAULT_ATTEMPTS, 1);
+        const interval = wholeNumber("--interval", values.interval, DEFAULT_INTERVAL, 0);
+        if (typeof attempts === "object") {
+            return attempts;
+        }
+        if (typeof interval === "object") {
+            return interval;
+        }
+        return { to, recap, attempts, interval };
+    }
+    catch (error) {
+        return { error: describe(error) };
+    }
+}
+/** What to send for the Recap in `file`: the Recap itself when it is one short line, else the file's path. */
+function messageFor(file) {
+    const path = resolve(file);
+    let text;
+    try {
+        text = readFileSync(path, "utf8").trim();
+    }
+    catch (error) {
+        throw new Refusal(`cannot read the Recap ${file}: ${describe(error)}`);
+    }
+    if (text === "") {
+        throw new Refusal(`the Recap ${file} is empty`);
+    }
+    return { message: text.includes("\n") || text.length > SHORT ? path : text, path };
+}
+async function report({ to, recap, attempts, interval }) {
+    lead();
+    const { message, path } = messageFor(recap);
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+        const sent = call("hc", ["send", to, message]);
+        if (sent.status === 0) {
+            process.stdout.write(`reported to ${to}\n`);
+            return 0;
+        }
+        if (sent.status !== BLOCKED) {
+            process.stderr.write(`dw-sdlc worker report: hc send failed: ${said(sent)} — the Recap stays at ${path}\n`);
+            return 1;
+        }
+        if (attempt === attempts) {
+            break;
+        }
+        process.stderr.write(`dw-sdlc worker report: ${to} is blocked; waiting ${interval} s (attempt ${attempt} of ${attempts})\n`);
+        await sleep(interval * 1000);
+    }
+    process.stderr.write(`dw-sdlc worker report: gave up after ${attempts} attempts: ${to} is still blocked — ` +
+        `the Recap stays at ${path}; say so on your screen so the dev can open ${to}\n`);
+    return 1;
+}
+export async function run(argv) {
+    const cli = parseCli(argv);
+    if (cli === "help") {
+        process.stdout.write(`${USAGE}\n`);
+        return 0;
+    }
+    if ("error" in cli) {
+        process.stderr.write(`dw-sdlc worker report: ${cli.error}\n\n${USAGE}\n`);
+        return 2;
+    }
+    try {
+        return await report(cli);
+    }
+    catch (error) {
+        return refuse("worker report", error);
+    }
+}

package/dist/commands/worker-start.d.ts

@@ -0,0 +1,2 @@
+export declare const summary = "start a Worker on a Brief in a herdr terminal";
+export declare function run(argv: string[]): Promise<number>;

package/dist/commands/worker-start.js

@@ -0,0 +1,234 @@
+// `dw-sdlc worker start`: puts a Brief in a herdr terminal as a Worker's first message, on the command, model
+// and effort the config names, and reads back whether the Worker took it.
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { parseArgs } from "node:util";
+import { mainCheckout, repositoryRoot, resolveConfig, WORKER_EFFORTS } from "../agentic-config.js";
+import { isObject } from "../json-text.js";
+import { describe, hcObject, isLive, lead, refuse, Refusal, wholeNumber, workersOf } from "../worker/herdr.js";
+import { nameTab } from "../worker/tabs.js";
+export const summary = "start a Worker on a Brief in a herdr terminal";
+/** The most seconds the command looks for the Worker's tab in the window, beside the read-back. */
+const TAB_WAIT = 10;
+const USAGE = `Usage: dw-sdlc worker start --brief <file> --name <name> [--model <model>] [--effort <effort>]
+                            [--max-workers <n>] [--wait <seconds>] [--json]
+
+Starts a Worker in the background and gives it the Brief as its first message. It runs hc run with the name,
+the label role=worker, --outlive-parent and the repository as the folder, then worker.command of the config
+with --worktree <name>, --model, --effort and the Brief. worker.command is split on whitespace, so it holds
+no quoted word. --model and --effort default to worker.model and worker.effort. When the Lead sits in a
+herdr space the Worker joins it, and its tab, which herdr numbers, takes the Worker's name: the window lists
+the tab a moment after hc run, so the command looks for it for up to ${TAB_WAIT} seconds, or --wait when shorter,
+while it reads the terminal back.
+
+It reads the terminal back for up to --wait seconds (default 30), until the Worker shows work: its status
+turns working, blocked or done. It fails when herdr reports the first message as unsent, the terminal has
+ended, the Worker reports an error, or the Worker is still idle or silent when the time is up. It never sends
+the Brief again: read the terminal with hc read first.
+
+It refuses outside herdr ($HC_TERMINAL_ID unset) and when the Lead already has --max-workers live
+Workers (default 3). The name is 1-32 of a-z, 0-9, - and _; it names the worktree too.
+
+One line, or one JSON document with --json.
+
+Exit 0 started and delivered, 1 started but not delivered, 2 when it cannot run.`;
+const DEFAULT_MAX_WORKERS = 3;
+const DEFAULT_WAIT = 30;
+/** hc names a terminal with 1-32 of a-z, 0-9, - and _. */
+const NAME = /^[a-z0-9][a-z0-9_-]{0,31}$/;
+/** What a Worker reports once it has taken its first message. */
+const WORKING = new Set(["working", "blocked", "done"]);
+/** How long the read-back waits between two reads of the terminal. */
+const POLL_MS = 1000;
+function parseCli(argv) {
+    try {
+        const { values } = parseArgs({
+            args: argv,
+            options: {
+                help: { type: "boolean", short: "h" },
+                json: { type: "boolean" },
+                brief: { type: "string" },
+                name: { type: "string" },
+                model: { type: "string" },
+                effort: { type: "string" },
+                "max-workers": { type: "string" },
+                wait: { type: "string" }
+            }
+        });
+        if (values.help === true) {
+            return "help";
+        }
+        const { brief, name, model, effort } = values;
+        if (brief === undefined) {
+            return { error: "name the Brief file: --brief <file>" };
+        }
+        if (name === undefined || !NAME.test(name)) {
+            return { error: `--name takes 1-32 of a-z, 0-9, - and _, not ${JSON.stringify(name ?? "")}` };
+        }
+        if (model !== undefined && (model.trim() === "" || model.startsWith("-"))) {
+            return { error: `--model takes a model name, not ${JSON.stringify(model)}` };
+        }
+        if (effort !== undefined && !WORKER_EFFORTS.includes(effort)) {
+            return { error: `--effort takes one of ${WORKER_EFFORTS.join(", ")}, not ${JSON.stringify(effort)}` };
+        }
+        const max = wholeNumber("--max-workers", values["max-workers"], DEFAULT_MAX_WORKERS, 1);
+        const wait = wholeNumber("--wait", values.wait, DEFAULT_WAIT, 0);
+        if (typeof max === "object") {
+            return max;
+        }
+        if (typeof wait === "object") {
+            return wait;
+        }
+        return { brief, name, model, effort, max, wait, json: values.json === true };
+    }
+    catch (error) {
+        return { error: describe(error) };
+    }
+}
+/** The Brief's text; a file that is missing or holds only whitespace stops the command. */
+function readBrief(file) {
+    let text;
+    try {
+        text = readFileSync(resolve(file), "utf8");
+    }
+    catch (error) {
+        throw new Refusal(`cannot read the Brief ${file}: ${describe(error)}`);
+    }
+    if (text.trim() === "") {
+        throw new Refusal(`the Brief ${file} is empty`);
+    }
+    return text;
+}
+/** The status a Worker reports, if it has reported one. */
+function reportedStatus(terminal) {
+    const { status } = terminal;
+    return isObject(status) && typeof status.state === "string" ? status.state : undefined;
+}
+/** Why the Worker can no longer take the Brief, or undefined while it still may. */
+function failure(terminal) {
+    const { first_message: first, state } = terminal;
+    if (isObject(first) && first.sent === false) {
+        return typeof first.reason === "string" ? first.reason : "herdr gave no reason";
+    }
+    if (state !== "live") {
+        return "the terminal has finished";
+    }
+    return reportedStatus(terminal) === "error" ? "the Worker reports its status as error" : undefined;
+}
+/** Reads the terminal until the Worker shows work, for up to `wait` seconds; why it did not, or undefined once it did. */
+async function delivery(address, wait) {
+    const deadline = Date.now() + wait * 1000;
+    for (;;) {
+        let terminal;
+        try {
+            terminal = hcObject(["get", address, "--json"]);
+        }
+        catch (error) {
+            if (!(error instanceof Refusal)) {
+                throw error;
+            }
+            // The Worker is running by now, so a failed read is a Brief not confirmed, never a start that did not happen.
+            return `the terminal could not be read back: ${describe(error)}`;
+        }
+        const failed = failure(terminal);
+        if (failed !== undefined) {
+            return failed;
+        }
+        if (WORKING.has(reportedStatus(terminal) ?? "")) {
+            return undefined;
+        }
+        if (Date.now() >= deadline) {
+            return `the Worker showed no sign of work within ${wait} s`;
+        }
+        await sleep(POLL_MS);
+    }
+}
+/** The id of the herdr space the Lead sits in, if it sits in one. */
+function spaceOf(leadId) {
+    const { labels } = hcObject(["get", leadId, "--json"]);
+    const space = isObject(labels) ? labels["herdr.space"] : undefined;
+    return typeof space === "string" ? space : undefined;
+}
+async function start(cli) {
+    const brief = readBrief(cli.brief);
+    const leadId = lead();
+    const checkout = repositoryRoot(process.cwd());
+    // The Worker's --worktree makes a worktree of the repository itself, never of a linked one.
+    const root = mainCheckout(checkout) ?? checkout;
+    const worker = resolveConfig(checkout).config.worker;
+    const command = worker.command.split(/\s+/).filter(Boolean);
+    if (command.length === 0) {
+        throw new Refusal("worker.command holds no command", "set it in .ai/agentic.config.local.json, or remove the key");
+    }
+    const model = cli.model ?? worker.model;
+    const effort = cli.effort ?? worker.effort;
+    const live = workersOf(leadId, false).filter(isLive);
+    if (live.length >= cli.max) {
+        throw new Refusal(`${leadId} already has ${live.length} live Workers (the limit is ${cli.max})`, `carry one through first, or raise the limit with --max-workers ${live.length + 1}`);
+    }
+    const space = spaceOf(leadId);
+    const { address } = hcObject([
+        "run",
+        "--bg",
+        "--json",
+        "--name",
+        cli.name,
+        "--label",
+        "role=worker",
+        ...(space === undefined ? [] : ["--label", `herdr.space=${space}`]),
+        "--outlive-parent",
+        "--cwd",
+        root,
+        "--",
+        ...command,
+        "--worktree",
+        cli.name,
+        "--model",
+        model,
+        "--effort",
+        effort,
+        brief
+    ]);
+    if (typeof address !== "string") {
+        throw new Refusal("hc run answered no address for the terminal it started", "check hc ls before starting it again");
+    }
+    // Side by side, so the wait for the tab overlaps the wait for the Worker to start.
+    const naming = space === undefined ? Promise.resolve("none") : nameTab(address, cli.name, Math.min(TAB_WAIT, cli.wait));
+    const [named, reason] = await Promise.all([naming, delivery(address, cli.wait)]);
+    if (typeof named === "object") {
+        process.stderr.write(`dw-sdlc worker start: warning: ${named.kept}\n`);
+    }
+    if (cli.json) {
+        const tab = typeof named === "object" ? "kept" : named;
+        const started = { name: cli.name, address, command: worker.command, model, effort, cwd: root };
+        const document = { ...started, delivered: reason === undefined, ...(reason === undefined ? {} : { reason }), tab };
+        process.stdout.write(`${JSON.stringify(document, null, 2)}\n`);
+    }
+    if (reason !== undefined) {
+        process.stderr.write(`dw-sdlc worker start: ${cli.name} (${address}) started but its first message was not delivered: ${reason} — ` +
+            `run hc read ${address} to see why; do not send the Brief again before you have read it\n`);
+        return 1;
+    }
+    if (!cli.json) {
+        process.stdout.write(`started ${cli.name} (${address}) on ${model} at ${effort} effort\n`);
+    }
+    return 0;
+}
+export async function run(argv) {
+    const cli = parseCli(argv);
+    if (cli === "help") {
+        process.stdout.write(`${USAGE}\n`);
+        return 0;
+    }
+    if ("error" in cli) {
+        process.stderr.write(`dw-sdlc worker start: ${cli.error}\n\n${USAGE}\n`);
+        return 2;
+    }
+    try {
+        return await start(cli);
+    }
+    catch (error) {
+        return refuse("worker start", error);
+    }
+}

package/dist/doctor-plugins.d.ts

@@ -0,0 +1,14 @@
+import type { Check, Probe } from "./commands/doctor.ts";
+/** The JSON `text` holds, whatever its kind: `claude plugin list --json` prints an array. */
+export declare function parseJson(text: string | undefined): unknown;
+/** The directory `plugin` runs from on this machine: the checkout of a directory marketplace, else the installed snapshot. */
+export declare function runningPluginRoot(probe: Probe, claude: string, plugin?: string): string | undefined;
+export declare function checkPlugin(probe: Probe, claude: string): Check;
+/** Whether the plugin's hooks and skills run the dw-sdlc the repository pins, the one its Gate runs. */
+export declare function checkPackage(probe: Probe, claude: string, root: string | undefined): Check;
+/**
+ * `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.
+ */
+export declare function checkSessions(probe: Probe, claude: string): Check;
+export declare function versionBefore(version: string, threshold: string): boolean;

package/dist/doctor-plugins.js

@@ -0,0 +1,182 @@
+// The doctor's lines on the plugins: `sdlc` installed and enabled, the package it links against the one the
+// repository pins, and the optional `sdlc-sessions` with its own copy of the package.
+import { join } from "node:path";
+import { isObject } from "./json-text.js";
+import { EXACT_VERSION, parseCatalog, parsePins } from "./pins.js";
+/** The marketplace Claude Code registers this repository under, the plugin in it, and the package the plugin links to. */
+const MARKETPLACE = "dw-sdlc";
+const PLUGIN = "sdlc";
+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}`;
+const PACKAGE = "dw-sdlc";
+/** The JSON `text` holds, whatever its kind: `claude plugin list --json` prints an array. */
+export function parseJson(text) {
+    if (text === undefined) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 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")));
+    const entry = isObject(known) && isObject(known[MARKETPLACE]) ? known[MARKETPLACE] : undefined;
+    const source = entry !== undefined && isObject(entry.source) ? entry.source : undefined;
+    return source?.source === "directory" && typeof source.path === "string" ? source.path : undefined;
+}
+function pluginOrigin(probe, claude, installPath) {
+    const checkout = liveCheckout(probe, claude);
+    if (checkout !== undefined) {
+        return `runs live from ${checkout}/plugins/${PLUGIN}; a change there is in the next session`;
+    }
+    return `installed at ${installPath}; a change reaches it through claude plugin update`;
+}
+/** 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;
+    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. */
+export function runningPluginRoot(probe, claude, plugin = PLUGIN) {
+    const checkout = liveCheckout(probe, claude);
+    if (checkout !== undefined) {
+        return join(checkout, "plugins", plugin);
+    }
+    const entry = listedPlugins(probe)?.find((item) => item.id === `${plugin}@${MARKETPLACE}`);
+    return entry !== undefined && typeof entry.installPath === "string" ? entry.installPath : undefined;
+}
+export function checkPlugin(probe, claude) {
+    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) => item.id === PLUGIN_ID);
+    if (entry === undefined) {
+        return {
+            name: "plugin",
+            level: "FAIL",
+            detail: `${PLUGIN_ID} is not installed. claude plugin marketplace add dominikwozniak/dw-sdlc --sparse .claude-plugin plugins packages && claude plugin install ${PLUGIN_ID} --scope user`
+        };
+    }
+    const version = typeof entry.version === "string" ? entry.version : "?";
+    const installPath = typeof entry.installPath === "string" ? entry.installPath : "?";
+    if (entry.enabled !== true) {
+        return {
+            name: "plugin",
+            level: "FAIL",
+            detail: `${version} installed but disabled, so no guard runs. claude plugin enable ${PLUGIN_ID}`
+        };
+    }
+    return {
+        name: "plugin",
+        level: "PASS",
+        detail: `${version} enabled; ${pluginOrigin(probe, claude, installPath)}`
+    };
+}
+/** The `version` of the package.json in `dir`, or undefined when there is none. */
+function manifestVersion(probe, dir) {
+    const manifest = parseJson(probe.read(join(dir, "package.json")));
+    return isObject(manifest) && typeof manifest.version === "string" ? manifest.version : undefined;
+}
+/** Whether the plugin's hooks and skills run the dw-sdlc the repository pins, the one its Gate runs. */
+export function checkPackage(probe, claude, root) {
+    const name = "package";
+    const manifest = root === undefined ? undefined : probe.read(join(root, "package.json"));
+    if (root === undefined || manifest === undefined) {
+        return { name, level: "INFO", detail: `no package.json here to pin ${PACKAGE}` };
+    }
+    let spec;
+    try {
+        spec = parsePins(manifest, parseCatalog(probe.read(join(root, "pnpm-workspace.yaml")) ?? ""))[PACKAGE];
+    }
+    catch {
+        return { name, level: "INFO", detail: `${join(root, "package.json")} is not JSON` };
+    }
+    if (spec === undefined) {
+        return { name, level: "INFO", detail: `the repository does not pin ${PACKAGE}` };
+    }
+    // `workspace:` or a range names no one version: the copy installed under node_modules is the one that runs.
+    const pinned = EXACT_VERSION.test(spec) ? spec : manifestVersion(probe, join(root, "node_modules", PACKAGE));
+    if (pinned === undefined) {
+        return { name, level: "WARN", detail: `the repository pins ${PACKAGE} ${spec}, not installed: pnpm install` };
+    }
+    const plugin = runningPluginRoot(probe, claude);
+    if (plugin === undefined) {
+        return { name, level: "INFO", detail: `no ${PLUGIN_ID} runs here to compare with the pinned ${pinned}` };
+    }
+    const linked = manifestVersion(probe, join(plugin, PACKAGE));
+    if (linked === undefined) {
+        return {
+            name,
+            level: "WARN",
+            detail: `the plugin at ${plugin} carries no ${PACKAGE}: an install from GitHub needs packages in its --sparse set`
+        };
+    }
+    if (linked !== pinned) {
+        const remedy = versionBefore(linked, pinned)
+            ? `claude plugin update ${PLUGIN_ID}`
+            : `pnpm add --save-dev --save-exact ${PACKAGE}@${linked}`;
+        return {
+            name,
+            level: "WARN",
+            detail: `drift: the plugin runs ${PACKAGE} ${linked} and the repository pins ${pinned}, so its hooks and skills run other code than the Gate. ${remedy}`
+        };
+    }
+    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.
+ */
+export 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}` };
+}
+export function versionBefore(version, threshold) {
+    const a = version.split(".").map((part) => Number.parseInt(part, 10));
+    const b = threshold.split(".").map((part) => Number.parseInt(part, 10));
+    for (let i = 0; i < Math.max(a.length, b.length); i += 1) {
+        const x = a[i] ?? 0;
+        const y = b[i] ?? 0;
+        if (x !== y) {
+            return x < y;
+        }
+    }
+    return false;
+}

package/dist/pr/decide.js

@@ -152,7 +152,8 @@ const ROWS = [
         })
     },
     {
-        when: (pr) => pr.mergeStateStatus === "BEHIND",
+        // GitHub reports BEHIND only under a rule that a branch be up to date; the compare tells it anywhere.
+        when: (pr) => pr.mergeStateStatus === "BEHIND" || (pr.behindBy ?? 0) > 0,
         answer: (pr) => ({ status: "act", action: "update-branch", actor: "script", reason: `behind ${pr.base}` })
     },
     {

package/dist/pr/read.d.ts

@@ -23,8 +23,14 @@ 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 current branch's pull request, open or not, or null. gh tries `@{push}`, else the local name, which
+ * misses a branch pushed under another name; then `upstreamName` is asked, and `byUpstream` says so.
+ */
+export declare function readBranch(sized: boolean, upstreamName: string | undefined): {
+    pr: PrState;
+    byUpstream: boolean;
+} | 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. */
@@ -33,3 +39,8 @@ export declare function now(): number;
 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. */
 export declare function carriesBase(before: PrState, after: PrState): boolean;
+/**
+ * `pr` and how many commits of its base its head lacks, from the compare of the base with the head,
+ * read only where the decision can reach the update: open, mergeable, not reported BEHIND already.
+ */
+export declare function withBehind(pr: PrState): PrState;