dw-sdlc 0.7.0 → 0.9.0

package/dist/commands/gate.js

@@ -1,39 +1,67 @@
 // `dw-sdlc gate`: the Gate of a repository, from the `gate` key of its resolved agentic config. The
 // run and the report serve `dw-sdlc check` too, which judges one Check of it.
-import { spawnSync } from "node:child_process";
 import { parseArgs } from "node:util";
 import { repositoryRoot, resolveConfig } from "../agentic-config.js";
 import { CannotRun } from "../checks/check.js";
 import { CHECK_NAMES, enabledChecks, shippedCheck } from "../checks/index.js";
+import { watchDrift } from "../drift.js";
+import { fingerprint, isGreen, stampGreen } from "../gate-cache.js";
 import { annotation, failureJson, failureLine } from "../report.js";
+import { holdingSignals, runCommand, stoppedBy, TAIL_LINES } from "../run-command.js";
 export const summary = "run the Gate: the Steps of gate.steps in order, then every Check under gate.checks";
-const USAGE = `Usage: dw-sdlc gate [--json] [--root <dir>] [--update-baseline]
+const USAGE = `Usage: dw-sdlc gate [--json] [--verbose] [--root <dir>] [--update-baseline | --cache]
 
 Runs the Gate of the repository holding --root (default: the current directory): each Step of
-gate.steps in order from the repository root, its output passed through, stopping at the first that
-fails; then every Check under gate.checks, the run scripts and then the Checks the package ships,
-none stopping the next. Prints one line per failure: the file where there is one, the rule, the
-remedy; under GitHub Actions each line is also a workflow annotation. --json prints one document
-instead and sends the commands' own output to stderr.
+gate.steps in order from the repository root, stopping at the first that fails; then every Check
+under gate.checks, the run scripts and then the Checks the package ships, none stopping the next.
+
+Prints one line per Step with its time, one per Check, one per failure and a last line, green or
+failed. A failure line names the file where there is one, the rule and the remedy; under GitHub
+Actions it is also a workflow annotation. A Step or run script prints nothing of its own unless it
+does not pass: then its last ${TAIL_LINES} lines, both streams in the order written, under its own
+line. In a terminal a Step's line shows when it starts and takes its result when it ends.
+
+Each Step runs between two records of every file git tracks or would track: a file the Step created,
+changed or deleted is Drift, one failure per file, and the Steps after it still run. Ignored files
+and edits made before the run never drift, and a Step a signal stopped is not compared. gate.drift
+"allow" turns the watch off.
+
+SIGINT or SIGTERM sent while a command runs stops it and everything after it, and the report still
+prints: the stopped command's last lines, its failure line and the last line. A second signal, or one
+sent while the Checks the package ships run, ends the Gate at once.
+
+--verbose passes each command's output through as it runs instead, under a line naming the command,
+and keeps no tail. --json prints the document alone; each Step and Check in it carries tail, the last
+${TAIL_LINES} lines of a command that did not pass, null otherwise. With --verbose, under --json, the
+commands' output goes to stderr and every tail is null.
 
 --update-baseline then rewrites the baseline of each Ratchet, only when every Step and every other
-Check passed, and only tighter: a file now within its limit leaves it and no file joins. Where there
-is no baseline, it records one. The Ratchet is judged again on what it wrote.
+Check passed and no Step drifted, and only tighter: a file now within its limit leaves it and no
+file joins. Where there is no baseline, it records one. The Ratchet is judged again on what it wrote.
+
+--cache skips the run when the working tree and the Gate match the last green run in this checkout.
+Untracked files count and ignored files do not. Each worktree keeps its own stamp. A tree it cannot
+hash runs the whole Gate.
 
-Exit 0 when everything passes, 1 when a Step or a Check fails, 2 when the Gate cannot run: an
-invalid config layer, a Step or Check whose command the shell cannot find or execute, or a Check
-missing an input it reads.`;
+Exit 0 when everything passes, 1 when a Step or a Check fails or a Step drifts, 2 when the Gate
+cannot run: an invalid config layer, a Step or Check whose command the shell cannot find or execute,
+a Check missing an input it reads, or a tree it cannot record for Drift.`;
 const EXIT_CODES = { pass: 0, fail: 1, error: 2 };
-/** What the shell answers for a command it cannot find, and for one it cannot execute. */
-const NOT_RUNNABLE = { 127: "was not found", 126: "could not be executed" };
-const SKIPPED = { status: "skipped", exitCode: null };
-/** One Check run by name says nothing before its result. */
-const QUIET = { write: () => true };
+const SKIPPED = { status: "skipped", exitCode: null, tail: null };
+const SILENT = { write: () => true };
+const STATUS_WORDS = {
+    pass: "pass",
+    fail: "failed",
+    error: "cannot run",
+    skipped: "skipped"
+};
 const REMEDIES = {
     invalidLayer: "fix the file; the Gate runs once every layer is valid",
-    failed: "fix what it printed above",
-    stepNotRunnable: "install the command or fix gate.steps in the agentic config",
-    checkNotRunnable: "install the command or fix gate.checks.run in the agentic config",
+    failed: "fix what it printed above; run it alone for the full output",
+    notRunnable: {
+        step: "install the command or fix gate.steps in the agentic config",
+        check: "install the command or fix gate.checks.run in the agentic config"
+    },
     checkStopped: "fix what stopped it, or report it to dw-sdlc"
 };
 function plural(count, noun) {
@@ -46,16 +74,20 @@ function parseCli(argv) {
             options: {
                 help: { type: "boolean", short: "h" },
                 json: { type: "boolean" },
+                verbose: { type: "boolean" },
                 root: { type: "string" },
-                "update-baseline": { type: "boolean" }
+                "update-baseline": { type: "boolean" },
+                cache: { type: "boolean" }
             }
         });
-        return {
-            help: values.help === true,
-            json: values.json === true,
-            root: values.root,
-            updateBaseline: values["update-baseline"] === true
-        };
+        const refresh = values["update-baseline"] === true;
+        const cache = values.cache === true;
+        if (refresh && cache) {
+            return { error: "--cache and --update-baseline do not combine: a refresh needs the Gate to run" };
+        }
+        const mode = refresh ? "update-baseline" : cache ? "cache" : "plain";
+        const flags = { help: values.help === true, json: values.json === true, verbose: values.verbose === true };
+        return { ...flags, root: values.root, mode };
     }
     catch (error) {
         return { error: error instanceof Error ? error.message : String(error) };
@@ -66,25 +98,64 @@ function configFailure({ file, path, message }) {
     return { file, rule: "config", message: where, remedy: REMEDIES.invalidLayer };
 }
 /**
- * Runs `command` through `sh -c` from `root`, stdin closed and stderr passed through; stdout too, or
- * onto stderr when `--json` keeps stdout for the document. `detail` says what went wrong, when it did.
+ * What follows a Step's or Check's name once it ran: pass, failed or cannot run, with a command's exit,
+ * a Step's time, and a captured tail indented under the line.
  */
-function runCommand(command, root, json) {
-    const result = spawnSync(command, { shell: true, cwd: root, stdio: ["ignore", json ? 2 : "inherit", "inherit"] });
-    if (result.error !== undefined) {
-        return { status: "error", exitCode: null, detail: `could not start: ${result.error.message}` };
+function outcomeText(kind, outcome) {
+    const isCommand = "seconds" in outcome;
+    const exit = isCommand && outcome.status !== "pass" ? howItEnded(outcome) : "";
+    const time = isCommand && kind === "step" ? ` (${Math.round(outcome.seconds)} s)` : "";
+    const head = `${STATUS_WORDS[outcome.status]}${exit}${time}`;
+    if (outcome.tail === null) {
+        return head;
+    }
+    if (outcome.tail.length === 0) {
+        return `${head}; it printed nothing`;
     }
-    if (result.status === 0) {
-        return { status: "pass", exitCode: 0 };
+    const tail = outcome.tail.map((line) => (line === "" ? "" : `  ${line}`));
+    return [`${head}; its last ${TAIL_LINES} lines:`, ...tail].join("\n");
+}
+/** How a command that did not pass ended: the signal that stopped it, or its exit code. */
+function howItEnded({ signal, exitCode }) {
+    if (signal !== null) {
+        return `, stopped by ${signal}`;
     }
-    if (result.status === null) {
-        return { status: "fail", exitCode: null, detail: `was stopped by ${result.signal ?? "a signal"}` };
+    return exitCode === null ? "" : `, exit ${exitCode}`;
+}
+function none() { }
+/** Whether a Step's line goes out before it runs, to take its result in place: only in a terminal. */
+function live(kind) {
+    return kind === "step" && process.stdout.isTTY;
+}
+/**
+ * Quiet, the Gate prints each result, a Step's name first when stdout is a terminal; `--verbose` names
+ * each command before its output; `--json` prints neither. One Check run by name prints only a tail.
+ */
+function progressOf(options, log) {
+    if ("only" in options) {
+        const end = (kind, subject, outcome) => {
+            if (!options.json && outcome.tail !== null) {
+                process.stdout.write(`${kind} ${subject} — ${outcomeText(kind, outcome)}\n`);
+            }
+        };
+        return { start: none, end };
     }
-    const notRunnable = NOT_RUNNABLE[result.status];
-    if (notRunnable !== undefined) {
-        return { status: "error", exitCode: result.status, detail: `${notRunnable} (exit ${result.status})` };
+    if (options.verbose) {
+        return { start: (kind, subject) => log.write(`gate: ${kind} ${subject}\n`), end: none };
     }
-    return { status: "fail", exitCode: result.status, detail: `exited ${result.status}` };
+    if (options.json) {
+        return { start: none, end: none };
+    }
+    return {
+        start: (kind, subject) => {
+            if (live(kind)) {
+                process.stdout.write(`gate: ${kind} ${subject}`);
+            }
+        },
+        end: (kind, subject, outcome) => {
+            process.stdout.write(`${live(kind) ? "" : `gate: ${kind} ${subject}`} — ${outcomeText(kind, outcome)}\n`);
+        }
+    };
 }
 /** What a Check that threw reports: the input it lacks, or what stopped it. */
 function erred(check, error) {
@@ -93,7 +164,7 @@ function erred(check, error) {
         : { message: `stopped: ${error instanceof Error ? error.message : String(error)}`, remedy: REMEDIES.checkStopped };
     return {
         check,
-        outcome: { status: "error", exitCode: EXIT_CODES.error },
+        outcome: { status: "error", exitCode: EXIT_CODES.error, tail: null },
         failures: [{ rule: check.name, ...finding }]
     };
 }
@@ -102,21 +173,22 @@ function runShipped(check, root) {
     try {
         const failures = check.run(root).map((finding) => ({ rule: check.name, ...finding }));
         const status = failures.length === 0 ? "pass" : "fail";
-        return { check, outcome: { status, exitCode: EXIT_CODES[status] }, failures };
+        return { check, outcome: { status, exitCode: EXIT_CODES[status], tail: null }, failures };
     }
     catch (error) {
         return erred(check, error);
     }
 }
 /**
- * Rewrites the baseline of each Ratchet while every Step, every run Check in `others` and every other
- * shipped Check passed, and judges the Ratchet again on what it wrote.
+ * Rewrites the baseline of each Ratchet while every Step, every run Check and the watch for Drift in
+ * `others` and every other shipped Check passed, and judges the Ratchet again on what it wrote.
+ * Returns a line on each.
  */
-function refreshBaselines(judged, others, root, log) {
+function refreshBaselines(judged, others, root) {
     if (!judged.some(({ check }) => check.baseline !== undefined)) {
-        log.write("gate: no Ratchet is turned on, so no baseline to refresh\n");
-        return;
+        return ["gate: no Ratchet is turned on, so no baseline to refresh"];
     }
+    const notes = [];
     for (const [index, { check }] of judged.entries()) {
         if (check.baseline === undefined) {
             continue;
@@ -124,22 +196,23 @@ function refreshBaselines(judged, others, root, log) {
         const { file, refresh } = check.baseline;
         const rest = [...others, ...judged.filter((_, at) => at !== index).map(({ outcome }) => outcome)];
         if (rest.some(({ status }) => status !== "pass")) {
-            log.write(`gate: baseline ${file} not refreshed — a Step or another Check did not pass\n`);
+            notes.push(`gate: baseline ${file} not refreshed — a Step or another Check did not pass`);
             continue;
         }
         try {
-            log.write(`gate: baseline ${file} ${refresh(root)}\n`);
+            notes.push(`gate: baseline ${file} ${refresh(root)}`);
             judged[index] = runShipped(check, root);
         }
         catch (error) {
             if (error instanceof CannotRun) {
-                log.write(`gate: baseline ${file} not refreshed — ${error.finding.message}; ${error.finding.remedy}\n`);
+                notes.push(`gate: baseline ${file} not refreshed — ${error.finding.message}; ${error.finding.remedy}`);
             }
             else {
                 judged[index] = erred(check, error);
             }
         }
     }
+    return notes;
 }
 function worst(outcomes) {
     const statuses = new Set(outcomes.map(({ status }) => status));
@@ -162,10 +235,13 @@ function select(gate, only) {
     }
     return { steps: [], run: scripts, shipped: shipped === undefined ? [] : [shipped] };
 }
-export function runGate(root, options) {
+export async function runGate(root, options) {
     const { json } = options;
     const only = "only" in options ? options.only : undefined;
-    const log = only !== undefined ? QUIET : json ? process.stderr : process.stdout;
+    const mode = "mode" in options ? options.mode : undefined;
+    const log = only !== undefined ? SILENT : json ? process.stderr : process.stdout;
+    const progress = progressOf(options, log);
+    const output = "verbose" in options && options.verbose ? (json ? "stderr" : "stdout") : "capture";
     const { config, problems } = resolveConfig(root);
     const gateCommand = config.gate.command ?? null;
     if (problems.length > 0) {
@@ -175,55 +251,94 @@ export function runGate(root, options) {
     if ("rule" in selected) {
         return { status: "error", command: gateCommand, steps: [], checks: [], failures: [selected] };
     }
+    let toStamp;
+    if (mode === "cache") {
+        const found = fingerprint(root, config.gate);
+        if ("error" in found) {
+            log.write(`gate: cannot fingerprint the tree, so the whole Gate runs — ${found.error}\n`);
+        }
+        else if (isGreen(found)) {
+            return { status: "pass", command: gateCommand, cached: true, steps: [], checks: [], failures: [] };
+        }
+        else {
+            toStamp = found;
+        }
+    }
     const failures = [];
-    /** Runs one Step or Check and records its failure under `rule`, if it has one. */
-    const runOne = (command, rule, notRunnable) => {
-        const { detail, ...outcome } = runCommand(command, root, json);
-        if (detail !== undefined) {
-            const remedy = outcome.status === "error" ? notRunnable : REMEDIES.failed;
-            failures.push({ rule, message: `${JSON.stringify(command)} ${detail}`, remedy });
+    const watch = watchDrift(root, config.gate);
+    /** Runs one Step or Check, prints its progress and records its failure under `rule`, if it has one. */
+    const runOne = async (kind, subject, command) => {
+        progress.start(kind, subject);
+        const ran = await runCommand(command, root, output);
+        progress.end(kind, subject, ran);
+        if (ran.detail !== undefined) {
+            const remedy = ran.status === "error" ? REMEDIES.notRunnable[kind] : REMEDIES.failed;
+            failures.push({
+                rule: kind === "step" ? "step" : subject,
+                message: `${JSON.stringify(command)} ${ran.detail}`,
+                remedy
+            });
         }
-        return outcome;
+        return { status: ran.status, exitCode: ran.exitCode, tail: ran.tail };
     };
-    const steps = [];
-    let stopped = false;
-    for (const step of selected.steps) {
-        if (stopped) {
-            steps.push({ command: step, ...SKIPPED });
-            continue;
+    // While commands run, SIGINT and SIGTERM stop the one running and every one after it, and the report
+    // still prints. The Checks the package ships run in this process, where a signal ends the Gate at once.
+    const commands = await holdingSignals(async () => {
+        let failedStep = false;
+        const halted = () => failedStep || stoppedBy() !== undefined;
+        const steps = [];
+        for (const step of selected.steps) {
+            const watched = halted() ? undefined : await watch.step(step, () => runOne("step", step, step));
+            failures.push(...(watched?.failures ?? []));
+            const outcome = watched?.result ?? SKIPPED;
+            steps.push({ command: step, ...outcome });
+            failedStep ||= outcome.status !== "pass";
         }
-        log.write(`gate: step ${step}\n`);
-        const outcome = runOne(step, "step", REMEDIES.stepNotRunnable);
-        steps.push({ command: step, ...outcome });
-        stopped = outcome.status !== "pass";
-    }
-    const checks = [];
-    for (const check of selected.run) {
-        if (stopped) {
-            checks.push({ ...check, ...SKIPPED });
-            continue;
+        const checks = [];
+        for (const check of selected.run) {
+            checks.push({ ...check, ...(halted() ? SKIPPED : await runOne("check", check.name, check.command)) });
         }
-        log.write(`gate: check ${check.name}\n`);
-        checks.push({ ...check, ...runOne(check.command, check.name, REMEDIES.checkNotRunnable) });
+        return { steps, checks, halted: halted() };
+    });
+    const { steps, checks } = commands;
+    const late = commands.halted ? undefined : stoppedBy();
+    if (late !== undefined) {
+        // It landed after the last command, which it could not stop: it ends the Gate as in the shipped Checks.
+        process.kill(process.pid, late);
     }
+    const stopped = commands.halted;
     const judged = selected.shipped.map((check) => {
         if (stopped) {
             return { check, outcome: SKIPPED, failures: [] };
         }
-        log.write(`gate: check ${check.name}\n`);
+        progress.start("check", check.name);
         return runShipped(check, root);
     });
-    if ("updateBaseline" in options && options.updateBaseline) {
-        refreshBaselines(judged, [...steps, ...checks], root, log);
-    }
+    const watchOutcome = { status: watch.status() };
+    const notes = mode === "update-baseline" ? refreshBaselines(judged, [...steps, ...checks, watchOutcome], root) : [];
+    // A Ratchet's result is printed after its refresh, which judges it again.
     for (const { check, outcome, failures: found } of judged) {
+        if (outcome.status !== "skipped") {
+            progress.end("check", check.name, outcome);
+        }
         failures.push(...found);
         checks.push({ name: check.name, command: null, ...outcome });
     }
-    return { status: worst([...steps, ...checks]), command: gateCommand, steps, checks, failures };
+    for (const note of notes) {
+        log.write(`${note}\n`);
+    }
+    const status = worst([...steps, ...checks, watchOutcome]);
+    // Stamped with the fingerprint taken before the run: a Gate that changed the tree runs again next time.
+    if (status === "pass" && toStamp !== undefined) {
+        stampGreen(toStamp);
+    }
+    return { status, command: gateCommand, steps, checks, failures };
 }
 /** The last line, after `label`: green with what ran, or failed or cannot run with how many failures. */
 function verdict(label, report) {
+    if (report.cached === true) {
+        return `${label}: green — cached, the tree matches the last green run`;
+    }
     if (report.status === "pass") {
         return `${label}: green — ${plural(report.steps.length, "step")}, ${plural(report.checks.length, "check")}`;
     }
@@ -250,7 +365,7 @@ export function printReport(report, json, label) {
     }
     return EXIT_CODES[report.status];
 }
-export function run(argv) {
+export async function run(argv) {
     const cli = parseCli(argv);
     if ("error" in cli) {
         process.stderr.write(`dw-sdlc gate: ${cli.error}\n\n${USAGE}\n`);
@@ -260,6 +375,7 @@ export function run(argv) {
         process.stdout.write(`${USAGE}\n`);
         return 0;
     }
-    const { json, updateBaseline } = cli;
-    return printReport(runGate(repositoryRoot(cli.root ?? process.cwd()), { json, updateBaseline }), json, "gate");
+    const { json, verbose, mode } = cli;
+    const report = await runGate(repositoryRoot(cli.root ?? process.cwd()), { json, verbose, mode });
+    return printReport(report, json, "gate");
 }

package/dist/commands/pr-reviewed.js

@@ -1,6 +1,7 @@
 // `dw-sdlc pr reviewed <n> --head <sha>`: pins a clean review to the head it read, as the commit status
 // `dw-sdlc/review` in state success, so a push after the review leaves the new head unreviewed.
 import { parseArgs } from "node:util";
+import { REVIEW, REVIEW_STATE, reviewStatusArgs } from "../pr/decide.js";
 import { CannotRun, gh, namedProblem, read, said } from "../pr/read.js";
 export const summary = "pin a clean review to the head it read, as a commit status";
 const USAGE = `Usage: dw-sdlc pr reviewed <n> [-R owner/name] --head <sha> [--json]
@@ -11,9 +12,6 @@ a push moved the head since the review, it posts nothing. One line, or one docum
 Needs an authenticated gh.
 
 Exit 0 posted, 2 when it cannot run or the head moved.`;
-const CONTEXT = "dw-sdlc/review";
-/** The one state it posts: a failure or a pending status would turn the pull request unstable. */
-const STATE = "success";
 const DESCRIPTION = "a clean review of this head";
 function parseCli(argv) {
     try {
@@ -60,23 +58,9 @@ function post({ number, repo, head }) {
     if (pr.head !== head) {
         throw new CannotRun(`${pr.repo}#${number}: the head is ${pr.head}, not ${head}: a push landed since the review`, "review the new head, then call again with its sha");
     }
-    const posted = gh([
-        "api",
-        `repos/${pr.repo}/statuses/${head}`,
-        "--method",
-        "POST",
-        "--silent",
-        "-f",
-        `state=${STATE}`,
-        "-f",
-        `context=${CONTEXT}`,
-        "-f",
-        `target_url=${pr.url}`,
-        "-f",
-        `description=${DESCRIPTION}`
-    ]);
+    const posted = gh(reviewStatusArgs(pr, DESCRIPTION));
     if (posted.status !== 0) {
-        throw new CannotRun(`${pr.repo}#${number}: posting ${CONTEXT} failed: ${said(posted.stderr)}`, `check that gh's token may write commit statuses to ${pr.repo}, then call again`);
+        throw new CannotRun(`${pr.repo}#${number}: posting ${REVIEW} failed: ${said(posted.stderr)}`, `check that gh's token may write commit statuses to ${pr.repo}, then call again`);
     }
 }
 export function run(argv) {
@@ -101,8 +85,8 @@ export function run(argv) {
     }
     const { head } = cli;
     const answer = cli.json
-        ? JSON.stringify({ head, context: CONTEXT, state: STATE }, null, 2)
-        : `posted ${CONTEXT} ${STATE} on ${head}`;
+        ? JSON.stringify({ head, context: REVIEW, state: REVIEW_STATE }, null, 2)
+        : `posted ${REVIEW} ${REVIEW_STATE} on ${head}`;
     process.stdout.write(`${answer}\n`);
     return 0;
 }

package/dist/commands/pr-ship.js

@@ -2,20 +2,24 @@
 // needs next, performs it when it is the script's and reads again, then answers the first Action that
 // is not, as a line or one JSON document, with an exit code that names whose turn it is.
 import { parseArgs } from "node:util";
-import { repositoryRoot, resolveConfig } from "../agentic-config.js";
-import { decide, devCommand, hostArgs, isScriptAction, readyToMerge, shellLine } from "../pr/decide.js";
+import { repositoryRoot, resolveConfig, STRICTNESS } from "../agentic-config.js";
+import { decide, devCommand, hostArgs, isScriptAction, readyToMerge, REVIEW, shellLine } from "../pr/decide.js";
 import { CannotRun, gh, namedProblem, read, readAgain, said } from "../pr/read.js";
 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] [--dry-run] [--json] [--verbose]
+const USAGE = `Usage: dw-sdlc pr ship [<n>] [-R owner/name] [--merge] [--review full|off] [--dry-run] [--json] [--verbose]
 
 Reads pull request <n> through gh, the one of the current branch as gh pr view resolves it when <n>
 is omitted, and answers the Action it needs next: the status, the action, whose turn it is and why.
 The script performs its own Actions, each at most once and then reads again: it updates a branch
 behind its base, marks a draft ready once nothing else holds it back, and squash merges a pull
 request ready to merge under pr.merge auto in .ai/agentic.config.json or with --merge for this call;
-under ask, the default, it parks with the merge command. --dry-run performs nothing: it parks at the
-first Action the script would perform, listed under performed. One line, or one document with
---json; --verbose adds the state as read to the document under facts. Needs an authenticated gh.
+under ask, the default, it parks with the merge command. A head without a ${REVIEW} success
+gets the Review depth --review names for this call, else pr.review: under full, the default, the
+agent reviews it with the command pr.reviewCommand names, /code-review by default; under off the
+script posts the success itself, its description saying why.
+--dry-run performs nothing: it parks at the first Action the script would perform, listed under
+performed. One line, or one document with --json; --verbose adds the state as read to the document
+under facts. Needs an authenticated gh.
 
 Exit 0 done, 10 the agent's turn, 20 wait, 30 the dev's turn, 2 when it cannot run.`;
 const EXIT = { done: 0, act: 10, wait: 20, park: 30 };
@@ -30,12 +34,14 @@ function parseCli(argv) {
                 json: { type: "boolean" },
                 verbose: { type: "boolean" },
                 merge: { type: "boolean" },
+                review: { type: "string" },
                 "dry-run": { type: "boolean" },
                 repo: { type: "string", short: "R" }
             }
         });
         const [number, ...more] = positionals;
         const { repo } = values;
+        const review = STRICTNESS.review.find((depth) => depth === values.review);
         if (values.help !== true) {
             if (more.length > 0) {
                 return { error: `name one pull request, not ${positionals.length}` };
@@ -44,12 +50,16 @@ function parseCli(argv) {
             if (problem !== undefined) {
                 return { error: problem };
             }
+            if (values.review !== undefined && review === undefined) {
+                return { error: `--review takes ${STRICTNESS.review.join(" or ")}, not ${JSON.stringify(values.review)}` };
+            }
         }
         return {
             help: values.help === true,
             json: values.json === true,
             verbose: values.verbose === true,
             merge: values.merge === true,
+            review,
             dryRun: values["dry-run"] === true,
             number: number === undefined ? undefined : Number(number),
             repo
@@ -75,45 +85,50 @@ function now() {
 const NAMED = {
     "update-branch": { would: "update the branch", act: "the update", still: "the branch still reads behind its base" },
     "mark-ready": { would: "mark it ready", act: "the mark-ready", still: "the pull request still reads as a draft" },
+    "mark-reviewed": {
+        would: "mark it reviewed",
+        act: "the mark-reviewed",
+        still: `the head still carries no ${REVIEW} success`
+    },
     merge: { would: "merge it", act: "the merge", still: "the pull request still reads open" }
 };
 /** A script Action the call leaves to the dev, `reason` saying why; a merge parks as ready-to-merge. */
-function handedOver(pr, answer, action, reason) {
+function handedOver(pr, policy, answer, action, reason) {
     if (action === "merge") {
-        return { ...readyToMerge(pr, reason), blockers: answer.blockers };
+        return { ...readyToMerge(pr, policy, reason), blockers: answer.blockers };
     }
-    return { ...answer, status: "park", actor: "dev", reason, command: devCommand(pr, action) };
+    return { ...answer, status: "park", actor: "dev", reason, command: devCommand(pr, action, policy) };
 }
 /**
  * Reads and decides until the Action is not the script's. Each script Action runs at most once, then the
  * pull request is read again; under --dry-run, or when an Action comes round again, it is the dev's.
  */
-function ship(cli, merge) {
+function ship(cli, policy) {
     let pr = read(cli, "pr ship");
     const performed = [];
     const refusals = {};
     for (;;) {
-        const answer = decide(pr, now(), merge);
+        const answer = decide(pr, now(), policy);
         const { action } = answer;
         if (!isScriptAction(action)) {
             return { pr, answer, performed };
         }
         // -R names the repository, so the checkout the script runs in plays no part.
-        const args = hostArgs(pr, action, true);
+        const args = hostArgs(pr, action, policy, true);
         const command = shellLine(["gh", ...args]);
         const { would, act, still } = NAMED[action];
         if (cli.dryRun) {
             performed.push({ action, command, ok: null });
             return {
                 pr,
-                answer: handedOver(pr, answer, action, `the script would ${would}; --dry-run performs nothing`),
+                answer: handedOver(pr, policy, answer, action, `the script would ${would}; --dry-run performs nothing`),
                 performed
             };
         }
         if (performed.some((done) => done.action === action)) {
             const refusal = refusals[action];
             const reason = refusal === undefined ? `${act} ran, and ${still}` : `gh refused ${act}: ${refusal}`;
-            return { pr, answer: handedOver(pr, answer, action, reason), performed };
+            return { pr, answer: handedOver(pr, policy, answer, action, reason), performed };
         }
         const result = gh(args);
         performed.push({ action, command, ok: result.status === 0 });
@@ -143,11 +158,16 @@ export function run(argv) {
         process.stdout.write(`${USAGE}\n`);
         return 0;
     }
-    // An invalid config layer resolves to ask, like every other strictest setting.
-    const merge = cli.merge ? "auto" : resolveConfig(repositoryRoot(process.cwd())).config.pr.merge;
+    // 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
+    };
     let shipped;
     try {
-        shipped = ship(cli, merge);
+        shipped = ship(cli, policy);
     }
     catch (error) {
         if (error instanceof CannotRun) {

package/dist/commands/references-sync.js

@@ -6,6 +6,7 @@ import { existsSync, linkSync, mkdirSync, readdirSync, readFileSync, renameSync,
 import { extname, join } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
 import { parseArgs } from "node:util";
+import { repositoryFreeEnv } from "../git-env.js";
 import { readPins, resolveRef } from "../pins.js";
 import { REFERENCES_FILE, readReferences } from "../references-key.js";
 import { renderBlock, withBlock } from "../router-block.js";
@@ -133,13 +134,11 @@ async function lock(root, seconds) {
         rmSync(own, { force: true });
     }
 }
-/** The variables that tie git to one repository, as git itself lists them. */
-const REPOSITORY_VARS = new Set((spawnSync("git", ["rev-parse", "--local-env-vars"], { encoding: "utf8" }).stdout ?? "").split("\n").filter(Boolean));
 function git(args, cwd) {
-    // Each call finds its repository from `cwd`: the GIT_DIR a git hook exports would aim it at the
-    // hook's repository. A missing credential fails the fetch instead of waiting on a prompt nobody sees.
-    const env = Object.fromEntries(Object.entries(process.env).filter(([name]) => !REPOSITORY_VARS.has(name)));
-    const result = spawnSync("git", args, { cwd, encoding: "utf8", env: { ...env, GIT_TERMINAL_PROMPT: "0" } });
+    // Each call finds its repository from `cwd`. A missing credential fails the fetch instead of waiting
+    // on a prompt nobody sees.
+    const env = { ...repositoryFreeEnv(), GIT_TERMINAL_PROMPT: "0" };
+    const result = spawnSync("git", args, { cwd, encoding: "utf8", env });
     // git's error on one line, so each Reference stays one line of the report.
     const err = (result.stderr ?? "")
         .split("\n")