dw-sdlc 0.9.0 → 0.10.0

package/README.md

@@ -56,9 +56,12 @@ the delete command for the dev.
 
 `pr.merge` in the committed `.ai/agentic.config.json` says who merges: the script under `auto`, the
 dev under `ask`, the default. `pr.review` says how closely a head no one has reviewed is read: the
-agent reviews it under `full`, the default, and no one does under `off`. The local layer may tighten
-either and never loosen it; `--merge` acts as `auto` and `--review full|off` sets the depth for one
-call. A pull request the `gh` account did not open is always the dev's to merge.
+agent reviews it under `full`, one `sdlc-reviewer` subagent of the plugin does under `light`, and no
+one does under `off`. Under `auto`, the default, the script routes the depth from the changes:
+lockfiles alone `off`; a workflow file, more than 100 changed lines outside lockfiles, or a change
+too large to size `full`; the rest `light`. The local layer may tighten either and never loosen it;
+`--merge` acts as `auto` and `--review full|light|off` sets the depth for one call. A pull request
+the `gh` account did not open is always the dev's to merge.
 
 ```json
 { "pr": { "merge": "auto", "review": "full" } }

package/config/agentic.config.schema.json

@@ -395,8 +395,8 @@
           "enum": ["ask", "auto"]
         },
         "review": {
-          "description": "The Review depth of a head the Ship script finds unreviewed, which the dev's `--review` overrides for one call. `full`: the agent reviews the changes. `off`: the script posts the `dw-sdlc/review` success itself and no one reads them. Default `full`, which an invalid layer runs too. Strictest first: full, off.",
-          "enum": ["full", "off"]
+          "description": "The Review depth of a head the Ship script finds unreviewed, which the dev's `--review` overrides for one call. `full`: the agent runs the command `pr.reviewCommand` names over the changes. `light`: one `sdlc-reviewer` subagent reads the diff at medium effort. `off`: the script posts the `dw-sdlc/review` success itself and no one reads them. `auto`: built-in rules route the depth from the changes the Review would read: lockfiles alone `off`; a file under `.github/workflows/`, more than 100 changed lines outside lockfiles, or a change the script cannot size, more files than GitHub's compare lists or a file outside lockfiles with no patch, `full`; the rest `light`. Default `auto`; an invalid layer runs `full`. Strictest first: full, auto, light, off.",
+          "enum": ["full", "auto", "light", "off"]
         },
         "reviewCommand": {
           "description": "The slash command a `full` Review runs over the pull request's changes, as `/pr-review-toolkit:review-pr code errors`. Default `/code-review`. No strictness order: the local override sets it freely.",
@@ -406,6 +406,27 @@
       },
       "additionalProperties": false
     },
+    "worker": {
+      "description": "How a Worker's Claude Code session starts: the command, the model and the effort. No strictness order, as with `pr.reviewCommand`: any layer sets any key freely.",
+      "type": "object",
+      "properties": {
+        "command": {
+          "description": "The command a Worker starts with: the words that start its Claude Code session, before the flags of its own, such as `--model` and `--effort`. Default `claude`. It belongs to one machine, so it sits in the local layer, where `dw-sdlc setup` writes `cswap run -- --dangerously-skip-permissions` when `cswap` is on PATH.",
+          "type": "string",
+          "minLength": 1
+        },
+        "model": {
+          "description": "The model a Worker runs on, as Claude Code's `--model` takes it. Default `sonnet`.",
+          "type": "string",
+          "minLength": 1
+        },
+        "effort": {
+          "description": "The effort a Worker runs at, one of Claude Code's effort levels. Default `high`.",
+          "enum": ["low", "medium", "high", "xhigh", "max"]
+        }
+      },
+      "additionalProperties": false
+    },
     "worktree": {
       "type": "object",
       "properties": {

package/dist/agentic-config.d.ts

@@ -17,8 +17,15 @@ export type EnvFiles = {
 };
 /** Who merges a pull request the Ship script finds ready: the script under `auto`, the dev under `ask`. */
 export type PrMerge = "ask" | "auto";
-/** How closely a Review reads an unreviewed head: the agent reads it under `full`, no one under `off`. */
-export type PrReview = "full" | "off";
+/**
+ * How closely a Review reads an unreviewed head: the command `pr.reviewCommand` names under `full`,
+ * one `sdlc-reviewer` subagent under `light`, no one under `off`.
+ */
+export type ReviewDepth = "full" | "light" | "off";
+/** The Review depths, strictest first: what the dev's `--review` names. */
+export declare const REVIEW_DEPTHS: readonly ["full", "light", "off"];
+/** `pr.review`: a Review depth, or `auto`, which routes one from the changes by built-in rules. */
+export type PrReview = ReviewDepth | "auto";
 /**
  * How the Ship script ends a pull request: who merges it, how closely it is reviewed, and the slash
  * command a `full` Review runs.
@@ -28,6 +35,15 @@ export type PrConfig = {
     review: PrReview;
     reviewCommand: string;
 };
+/** Claude Code's effort levels, lowest first: what `worker.effort` takes. */
+declare const WORKER_EFFORTS: readonly ["low", "medium", "high", "xhigh", "max"];
+export type WorkerEffort = (typeof WORKER_EFFORTS)[number];
+/** How a Worker's Claude Code session starts: the words that start it, its model and its effort. */
+export type WorkerConfig = {
+    command: string;
+    model: string;
+    effort: WorkerEffort;
+};
 export type Guardrails = {
     forcePush: ForcePush;
     commitOnProtected: CommitOnProtected;
@@ -84,6 +100,7 @@ export type AgenticConfig = {
     };
     gate?: GateLayer;
     pr?: Partial<PrConfig>;
+    worker?: Partial<WorkerConfig>;
     worktree?: {
         setup?: string[];
     };
@@ -104,6 +121,7 @@ export type ResolvedConfig = {
     };
     gate: Gate;
     pr: PrConfig;
+    worker: WorkerConfig;
     worktree: {
         setup: string[];
     };
@@ -141,13 +159,13 @@ export declare const STRICTNESS: {
     readonly commitOnProtected: readonly ["deny", "allow"];
     readonly envFiles: readonly ["deny", "git"];
     readonly merge: readonly ["ask", "auto"];
-    readonly review: readonly ["full", "off"];
+    readonly review: readonly ["full", "auto", "light", "off"];
 };
 /** What the guards run on while any layer is invalid. */
 export declare const STRICTEST_GUARDRAILS: Guardrails;
 /** What the Ship script runs on while any layer is invalid, and with nothing declared: it merges nothing itself. */
 export declare const STRICTEST_PR_MERGE: PrMerge;
-/** The Review depth while any layer is invalid, and with nothing declared: the agent reads every head. */
+/** The Review depth while any layer is invalid: the agent reads every head in full. */
 export declare const STRICTEST_PR_REVIEW: PrReview;
 /** The command a `full` Review runs with nothing declared; it has no strictness order. */
 export declare const DEFAULT_REVIEW_COMMAND = "/code-review";

package/dist/agentic-config.js

@@ -11,13 +11,17 @@ export const LOCAL_FILE = ".ai/agentic.config.local.json";
 export const SCHEMA_FILE = "config/agentic.config.schema.json";
 export const SCHEMA_PATH = join(import.meta.dirname, "..", SCHEMA_FILE);
 export const COMMIT_CONVENTIONS = ["ticket-key", "conventional"];
+/** The Review depths, strictest first: what the dev's `--review` names. */
+export const REVIEW_DEPTHS = ["full", "light", "off"];
+/** Claude Code's effort levels, lowest first: what `worker.effort` takes. */
+const WORKER_EFFORTS = ["low", "medium", "high", "xhigh", "max"];
 /** Strictest value first; the local override may only move towards the front. */
 export const STRICTNESS = {
     forcePush: ["deny", "ask", "lease"],
     commitOnProtected: ["deny", "allow"],
     envFiles: ["deny", "git"],
     merge: ["ask", "auto"],
-    review: ["full", "off"]
+    review: ["full", "auto", "light", "off"]
 };
 /** What the guards run on while any layer is invalid. */
 export const STRICTEST_GUARDRAILS = {
@@ -28,11 +32,15 @@ export const STRICTEST_GUARDRAILS = {
 };
 /** What the Ship script runs on while any layer is invalid, and with nothing declared: it merges nothing itself. */
 export const STRICTEST_PR_MERGE = "ask";
-/** The Review depth while any layer is invalid, and with nothing declared: the agent reads every head. */
+/** The Review depth while any layer is invalid: the agent reads every head in full. */
 export const STRICTEST_PR_REVIEW = "full";
 const STRICTEST_PR = { merge: STRICTEST_PR_MERGE, review: STRICTEST_PR_REVIEW };
 /** The command a `full` Review runs with nothing declared; it has no strictness order. */
 export const DEFAULT_REVIEW_COMMAND = "/code-review";
+/** What a repository gets with nothing declared: the merge the dev's, the depth routed from the changes. */
+const DEFAULT_PR = { merge: STRICTEST_PR_MERGE, review: "auto", reviewCommand: DEFAULT_REVIEW_COMMAND };
+/** What a Worker starts with when no layer says otherwise; no key has a strictness order. */
+const DEFAULT_WORKER = { command: "claude", model: "sonnet", effort: "high" };
 /** What a repository gets with nothing declared. */
 export const DEFAULT_GUARDRAILS = {
     forcePush: "lease",
@@ -202,7 +210,8 @@ export function inferConfig(root) {
         guardrails: cloneGuardrails(DEFAULT_GUARDRAILS),
         commit: { convention: "conventional" },
         gate: inferGate(root),
-        pr: { ...STRICTEST_PR, reviewCommand: DEFAULT_REVIEW_COMMAND },
+        pr: { ...DEFAULT_PR },
+        worker: { ...DEFAULT_WORKER },
         worktree: { setup: [] }
     };
 }
@@ -219,6 +228,7 @@ function applyLayer(base, layer) {
         commit: { ...base.commit, ...layer.commit },
         gate: { ...base.gate, ...layer.gate, checks: { ...base.gate.checks, ...layer.gate?.checks } },
         pr: { ...base.pr, ...layer.pr },
+        worker: { ...base.worker, ...layer.worker },
         worktree: { setup: layer.worktree?.setup ?? base.worktree.setup }
     };
 }
@@ -277,7 +287,7 @@ function loosenings(base, local) {
     }
     return problems;
 }
-/** Each local `pr` key less strict than the one it would override: `merge` auto over ask, `review` off over full. */
+/** Each local `pr` key less strict than the one it would override: `merge` auto over ask, `review` off over light over auto over full. */
 function prLoosenings(base, local) {
     const keys = ["merge", "review"];
     return keys.flatMap((key) => {
@@ -323,7 +333,7 @@ export function resolveConfig(root) {
         }
     }
     if (problems.length > 0) {
-        // `reviewCommand` has no strictest value: it keeps what the valid layers name.
+        // `reviewCommand` and `worker` have no strictest value: they keep what the valid layers name.
         config = { ...config, guardrails: cloneGuardrails(STRICTEST_GUARDRAILS), pr: { ...config.pr, ...STRICTEST_PR } };
     }
     return {

package/dist/commands/pr-reviewed.js

@@ -54,7 +54,7 @@ function parseCli(argv) {
 }
 /** Posts the review status on `head` once the read shows it is still the pull request's head. */
 function post({ number, repo, head }) {
-    const pr = read({ number, repo }, "pr reviewed");
+    const pr = read({ number, repo }, "pr reviewed", false);
     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");
     }

package/dist/commands/pr-ship.js

@@ -2,11 +2,11 @@
 // 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, STRICTNESS } from "../agentic-config.js";
+import { repositoryRoot, resolveConfig, REVIEW_DEPTHS } 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";
+import { CannotRun, carriesBase, 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] [--review full|off] [--dry-run] [--json] [--verbose]
+const USAGE = `Usage: dw-sdlc pr ship [<n>] [-R owner/name] [--merge] [--review full|light|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.
@@ -14,16 +14,39 @@ The script performs its own Actions, each at most once and then reads again: it
 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. 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.
+gets the Review depth --review names for this call, else pr.review: under full the agent reviews it
+with the command pr.reviewCommand names, /code-review by default; under light one sdlc-reviewer
+subagent reads the diff; under off the script posts the success itself, its description saying
+why. Under auto, the default, the script routes the depth from the changes the Review would read:
+lockfiles alone off; a file under .github/workflows/, more than 100 changed lines outside
+lockfiles, or a change it cannot size, more files than GitHub's compare lists or a file outside
+lockfiles with no patch, full; the rest light. After a push it names
+the last reviewed commit under details.since, where the Review reads from and auto routes from. It
+carries that commit's success over a head whose only commits since are merges of the base, unless
+--review names a depth for the call.
+Each Action the call runs is listed under performed. Its ok says whether the read after it shows the
+Action took effect, whatever gh's exit status; gh's exit status and stderr stand beside it, so an ok
+false with exit 0 is an Action gh accepted that the read does not show yet. An update counts when
+the head carries the base it read. When the read after an Action fails, the call exits 2 and names
+each Action that ran with gh's exit, under performed too with --json: it may have landed, so do not
+run it blind again. --dry-run performs nothing: it parks at the first Action the script would
+perform, under performed with ok null.
+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.`;
+/** The depths --review takes, strictest first, as a sentence lists them. */
+const DEPTHS_SENTENCE = `${REVIEW_DEPTHS.slice(0, -1).join(", ")} or ${REVIEW_DEPTHS.at(-1)}`;
 const EXIT = { done: 0, act: 10, wait: 20, park: 30 };
 const REMEDIES = { clock: "unset it: it stands in for the clock in tests" };
+/** A call that stopped after it ran Actions: what it ran stands in `performed`, `ok` null where no read followed. */
+class Interrupted extends CannotRun {
+    performed;
+    constructor({ message, remedy }, performed) {
+        super(message, remedy);
+        this.performed = performed;
+    }
+}
 function parseCli(argv) {
     try {
         const { values, positionals } = parseArgs({
@@ -41,7 +64,7 @@ function parseCli(argv) {
         });
         const [number, ...more] = positionals;
         const { repo } = values;
-        const review = STRICTNESS.review.find((depth) => depth === values.review);
+        const review = REVIEW_DEPTHS.find((depth) => depth === values.review);
         if (values.help !== true) {
             if (more.length > 0) {
                 return { error: `name one pull request, not ${positionals.length}` };
@@ -51,7 +74,7 @@ function parseCli(argv) {
                 return { error: problem };
             }
             if (values.review !== undefined && review === undefined) {
-                return { error: `--review takes ${STRICTNESS.review.join(" or ")}, not ${JSON.stringify(values.review)}` };
+                return { error: `--review takes ${DEPTHS_SENTENCE}, not ${JSON.stringify(values.review)}` };
             }
         }
         return {
@@ -92,6 +115,33 @@ const NAMED = {
     },
     merge: { would: "merge it", act: "the merge", still: "the pull request still reads open" }
 };
+/**
+ * Whether the read after a script Action shows it took effect. gh's exit status cannot tell: a reply
+ * lost on the way back exits non-zero after GitHub applied the Action.
+ */
+const TOOK = {
+    // A moved head alone may be a push: the update took effect when the head carries the base it read.
+    "update-branch": (before, after) => after.head !== before.head && carriesBase(before, after),
+    "mark-ready": (_, after) => !after.draft,
+    // The post names the head it read: a head moved since carries none of it.
+    "mark-reviewed": (before, after) => after.head === before.head && after.checks.some((check) => check.name === REVIEW && check.bucket === "pass"),
+    merge: (_, after) => after.state === "MERGED"
+};
+/**
+ * Why an Action that ran comes round again. A head that moved after a mark-reviewed names both heads;
+ * otherwise gh refused it, or accepted it and the read shows nothing yet, or the effect is gone again.
+ */
+function reasonOf({ action, ok, exit, stderr = "" }, pr, ranOn, { act, still }) {
+    if (action === "mark-reviewed" && exit === 0 && ranOn !== undefined && ranOn !== pr.head) {
+        return `${act} posted on ${ranOn.slice(0, 7)}, and the head moved to ${pr.head.slice(0, 7)}`;
+    }
+    if (ok) {
+        return `${act} ran, and ${still}`;
+    }
+    return exit === 0
+        ? `gh accepted ${act}; the read does not show it yet`
+        : `gh refused ${act}: ${said(stderr) || `gh exited ${exit}`}`;
+}
 /** A script Action the call leaves to the dev, `reason` saying why; a merge parks as ready-to-merge. */
 function handedOver(pr, policy, answer, action, reason) {
     if (action === "merge") {
@@ -104,9 +154,12 @@ function handedOver(pr, policy, answer, action, reason) {
  * pull request is read again; under --dry-run, or when an Action comes round again, it is the dev's.
  */
 function ship(cli, policy) {
-    let pr = read(cli, "pr ship");
+    // Only pr.review auto routes the depth from the changes, so only it reads them.
+    const sized = policy.review.depth === "auto";
+    let pr = read(cli, "pr ship", sized);
     const performed = [];
-    const refusals = {};
+    // The head each Action ran on.
+    const postedOn = new Map();
     for (;;) {
         const answer = decide(pr, now(), policy);
         const { action } = answer;
@@ -116,7 +169,7 @@ function ship(cli, policy) {
         // -R names the repository, so the checkout the script runs in plays no part.
         const args = hostArgs(pr, action, policy, true);
         const command = shellLine(["gh", ...args]);
-        const { would, act, still } = NAMED[action];
+        const { would } = NAMED[action];
         if (cli.dryRun) {
             performed.push({ action, command, ok: null });
             return {
@@ -125,17 +178,28 @@ function ship(cli, policy) {
                 performed
             };
         }
-        if (performed.some((done) => done.action === action)) {
-            const refusal = refusals[action];
-            const reason = refusal === undefined ? `${act} ran, and ${still}` : `gh refused ${act}: ${refusal}`;
+        const done = performed.find((earlier) => earlier.action === action);
+        // --dry-run returns before any Action runs, so an earlier one always carries gh's exit.
+        if (done !== undefined && done.ok !== null) {
+            const reason = reasonOf(done, pr, postedOn.get(action), NAMED[action]);
             return { pr, answer: handedOver(pr, policy, answer, action, reason), performed };
         }
-        const result = gh(args);
-        performed.push({ action, command, ok: result.status === 0 });
-        if (result.status !== 0) {
-            refusals[action] = said(result.stderr) || `gh exited ${result.status}`;
+        const { status, stderr } = gh(args);
+        const before = pr;
+        const message = stderr.trim();
+        const record = { action, command, exit: status, ...(message === "" ? {} : { stderr: message }) };
+        postedOn.set(action, before.head);
+        try {
+            pr = readAgain(pr, sized);
+            performed.push({ ...record, ok: TOOK[action](before, pr) });
+        }
+        catch (error) {
+            if (error instanceof CannotRun) {
+                // The Action may have landed: the caller must not run it blind again.
+                throw new Interrupted(error, [...performed, { ...record, ok: null }]);
+            }
+            throw error;
         }
-        pr = readAgain(pr);
     }
 }
 /** `<status> <action>: <reason>`, the action dropped when it repeats the status, then the recheck and the command. */
@@ -171,7 +235,12 @@ export function run(argv) {
     }
     catch (error) {
         if (error instanceof CannotRun) {
-            process.stderr.write(`dw-sdlc pr ship: ${error.message} — ${error.remedy}\n`);
+            const ran = error instanceof Interrupted ? error.performed : [];
+            const named = ran.map(({ action, ...rest }) => `${action} ran (gh exit ${rest.exit ?? "unknown"})\n`);
+            process.stderr.write(`dw-sdlc pr ship: ${error.message} — ${error.remedy}\n${named.join("")}`);
+            if (cli.json && ran.length > 0) {
+                process.stdout.write(`${JSON.stringify({ error: error.message, remedy: error.remedy, performed: ran }, null, 2)}\n`);
+            }
             return 2;
         }
         throw error;

package/dist/commands/setup.d.ts

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

package/dist/commands/setup.js

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

package/dist/pr/decide.d.ts

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

package/dist/pr/decide.js

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

package/dist/pr/delta.d.ts

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

package/dist/pr/delta.js

@@ -0,0 +1,60 @@
+// GitHub's compare of two commits, read two ways: whether a head carries the Review of an earlier commit,
+// the pull request's own changes from the base the same at both, since a merge of the base in adds none
+// of its own; and the files a Review would read, with their changed lines, for `pr.review: auto`.
+import { fieldOf, integer, object, ReplyError, rootOf, shown, string } from "./state.js";
+/** GitHub's compare lists at most this many files; one that lists as many may hold back the rest. */
+const FILE_LIMIT = 300;
+/** The gh arguments of the compare from `from` to `commit`, the files on its one page. */
+export function compareArgs(repo, from, commit) {
+    return ["api", `repos/${repo}/compare/${from}...${commit}?per_page=1`];
+}
+/** The files a compare reply lists. */
+function filesOf(reply) {
+    const { value, at } = fieldOf(rootOf(reply, "the compare"), "files");
+    if (!Array.isArray(value)) {
+        throw new ReplyError(`${at} is ${shown(value)}, not a list`);
+    }
+    return value.map((item, index) => object(item, `${at}[${index}]`));
+}
+/** How many commits of the compare's base its head lacks: 0 when the head carries all of it. */
+export function behindOf(reply) {
+    return integer(rootOf(reply, "the compare"), "behind_by");
+}
+/** A field the compare may leave out, as a file's patch or its previous name. */
+function optional(file, key) {
+    return file.value[key] === undefined || file.value[key] === null ? null : string(file, key);
+}
+/**
+ * A file's own change: its status, its names and the lines its patch adds and removes, in order,
+ * without the hunk headers and context a moved base shifts; null when the compare shows no patch.
+ */
+function changeOf(file) {
+    const names = [string(file, "filename"), string(file, "status"), optional(file, "previous_filename")];
+    const patch = optional(file, "patch");
+    if (patch === null) {
+        return null;
+    }
+    return JSON.stringify([...names, patch.split("\n").filter((line) => /^[-+\\]/.test(line))]);
+}
+/** The own changes a compare reply lists, file by file; null when it cannot show them whole. */
+export function changesOf(reply) {
+    const changes = filesOf(reply).map(changeOf);
+    const whole = changes.filter((change) => change !== null);
+    return changes.length >= FILE_LIMIT || whole.length < changes.length ? null : whole;
+}
+/** The files a compare reply lists with their changed lines; `unsized` when it may hold some back. */
+export function changedOf(reply) {
+    const files = filesOf(reply).map((file) => ({
+        path: string(file, "filename"),
+        previous: optional(file, "previous_filename"),
+        lines: optional(file, "patch") === null ? null : integer(file, "additions") + integer(file, "deletions")
+    }));
+    return files.length >= FILE_LIMIT ? "unsized" : files;
+}
+/** Whether the own changes at the head are those at the reviewed commit; unknown changes never are. */
+export function sameChanges(then, now) {
+    if (then === null || now === null) {
+        return false;
+    }
+    return JSON.stringify(then.toSorted()) === JSON.stringify(now.toSorted());
+}

package/dist/pr/read.d.ts

@@ -18,7 +18,12 @@ export declare function gh(args: string[]): {
     stdout: string;
     stderr: string;
 };
-/** The state of the pull request `named`; `command`, as `pr ship`, names the call in a remedy. */
-export declare function read(named: Named, command: string): PrState;
+/**
+ * The state of the pull request `named`; `command`, as `pr ship`, names the call in a remedy. With
+ * `sized`, as `pr.review: auto` needs, the read sizes the changes a Review would read.
+ */
+export declare function read(named: Named, command: string, sized: boolean): PrState;
 /** The state of `pr` once more, after an action the script performed on it: the same pull request. */
-export declare function readAgain(pr: PrState): PrState;
+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;

package/dist/pr/read.js

@@ -1,7 +1,9 @@
 // The read both pr commands make: gh as a child process, its auth on the host gh api reads from, the
-// pull request a command names, and that pull request's state from one GraphQL request.
+// pull request a command names, and that pull request's state from one GraphQL request, with the two
+// compares that tell whether its head carries an earlier Review and the one that sizes its changes.
 import { spawnSync } from "node:child_process";
-import { parsePr, parseView, QUERY, ReplyError } from "./state.js";
+import { behindOf, changedOf, changesOf, compareArgs, sameChanges } from "./delta.js";
+import { awaitsReview, parsePr, parseView, QUERY, ReplyError } from "./state.js";
 /** What stops a pr command before it answers: exit 2, the problem and its remedy on one line. */
 export class CannotRun extends Error {
     remedy;
@@ -74,22 +76,66 @@ function targetOf({ number, repo }, command) {
     }
     return parseOrCannotRun(() => parseView(view.stdout));
 }
-/** The state of the pull request `named`; `command`, as `pr ship`, names the call in a remedy. */
-export function read(named, command) {
+/**
+ * The state of the pull request `named`; `command`, as `pr ship`, names the call in a remedy. With
+ * `sized`, as `pr.review: auto` needs, the read sizes the changes a Review would read.
+ */
+export function read(named, command, sized) {
     // The host gh api reads from: an account on any other host has no say in this call.
     const host = process.env.GH_HOST?.trim() || "github.com";
     const auth = gh(["auth", "status", "--active", "--hostname", host]);
     if (auth.status !== 0) {
         throw new CannotRun(`gh auth status failed: ${authProblem(auth.stderr)}`, REMEDIES.auth);
     }
-    return query(targetOf(named, command));
+    return query(targetOf(named, command), sized);
 }
 /** The state of `pr` once more, after an action the script performed on it: the same pull request. */
-export function readAgain(pr) {
-    return query(pr);
+export function readAgain(pr, sized) {
+    return query(pr, sized);
 }
-/** The state of pull request `number` of `repo`, from one GraphQL request. */
-function query({ repo, number }) {
+/** The reply of the compare from `from` to `commit`; `what` names it when gh refuses it. */
+function compared(pr, from, commit, what) {
+    const reply = gh(compareArgs(pr.repo, from, commit));
+    if (reply.status !== 0) {
+        throw new CannotRun(`${pr.repo}#${pr.number}: ${what}: ${said(reply.stderr)}`, REMEDIES.read);
+    }
+    return reply.stdout;
+}
+/** Whether the head of `after` carries the base `before` read: the compare shows it behind by none. */
+export function carriesBase(before, after) {
+    const reply = compared(after, before.baseOid, after.head, `the compare with ${before.baseOid.slice(0, 7)}`);
+    return parseOrCannotRun(() => behindOf(reply)) === 0;
+}
+/** The own changes of `pr` at `commit`, from the compare with its base; null when it cannot show them whole. */
+function ownChanges(pr, commit) {
+    const reply = compared(pr, pr.baseOid, commit, `the compare with ${commit.slice(0, 7)}`);
+    return parseOrCannotRun(() => changesOf(reply));
+}
+/**
+ * `pr` and whether its head carries the last reviewed commit's status: only merges since it, and the
+ * same own changes at both. The compares run only when a Review awaits the head.
+ */
+function withCarried(pr) {
+    const last = pr.lastReviewed;
+    if (last === null || !last.mergesOnly || pr.state !== "OPEN" || !awaitsReview(pr)) {
+        return { ...pr, carried: false };
+    }
+    return { ...pr, carried: sameChanges(ownChanges(pr, last.commit), ownChanges(pr, pr.head)) };
+}
+/**
+ * `pr` and, when `sized` and a Review awaits a head that carries none, the files the Review would read:
+ * the compare from the last reviewed commit, else from the base, to the head.
+ */
+function withChanged(pr, sized) {
+    if (!sized || pr.carried || pr.state !== "OPEN" || !awaitsReview(pr)) {
+        return { ...pr, changed: null };
+    }
+    const from = pr.lastReviewed?.commit ?? pr.baseOid;
+    const reply = compared(pr, from, pr.head, `the compare of ${from.slice(0, 7)}...${pr.head.slice(0, 7)}`);
+    return { ...pr, changed: parseOrCannotRun(() => changedOf(reply)) };
+}
+/** The state of pull request `number` of `repo`, from one GraphQL request and the compares a Review needs. */
+function query({ repo, number }, sized) {
     const [owner = "", name = ""] = repo.split("/");
     const reply = gh([
         "api",
@@ -108,5 +154,5 @@ function query({ repo, number }) {
         const remedy = problem.startsWith("Could not resolve to a") ? REMEDIES.target : REMEDIES.read;
         throw new CannotRun(`${repo}#${number}: ${problem}`, remedy);
     }
-    return parseOrCannotRun(() => parsePr(reply.stdout, repo));
+    return withChanged(withCarried(parseOrCannotRun(() => parsePr(reply.stdout, repo))), sized);
 }

package/dist/pr/route.d.ts

@@ -0,0 +1,14 @@
+import type { ReviewDepth } from "../agentic-config.ts";
+import type { ChangedFile } from "./state.ts";
+/** A routed depth, and under off why no one reads the changes, as the status the script posts says. */
+export type Routed = {
+    depth: Exclude<ReviewDepth, "off">;
+} | {
+    depth: "off";
+    why: string;
+};
+/**
+ * The depth the rules route `changed` to. A change not read or not sized reads in full, as does a file
+ * outside lockfiles the compare shows no patch for.
+ */
+export declare function route(changed: ChangedFile[] | "unsized" | null): Routed;

package/dist/pr/route.js

@@ -0,0 +1,52 @@
+// The built-in rules `pr.review: auto` routes a Review depth by, from the files the Review would read:
+// lockfiles alone are off; a workflow file, more than 100 changed lines outside lockfiles, or a change
+// the compare cannot size is full; the rest is light. No config key moves them.
+/** The lockfiles a package manager writes, by file name in any directory. */
+const LOCKFILES = new Set([
+    "pnpm-lock.yaml",
+    "package-lock.json",
+    "npm-shrinkwrap.json",
+    "yarn.lock",
+    "bun.lock",
+    "bun.lockb",
+    "Gemfile.lock",
+    "Cargo.lock",
+    "poetry.lock",
+    "uv.lock",
+    "Pipfile.lock",
+    "composer.lock",
+    "go.sum",
+    "Podfile.lock",
+    "pubspec.lock",
+    "mix.lock",
+    "flake.lock"
+]);
+/** Where GitHub Actions reads its workflows: a change there runs with the repository's secrets. */
+const WORKFLOWS = ".github/workflows/";
+/** The most changed lines outside lockfiles a light Review reads. */
+const LINE_LIMIT = 100;
+function isLockfile(path) {
+    return LOCKFILES.has(path.slice(path.lastIndexOf("/") + 1));
+}
+function isWorkflow({ path, previous }) {
+    return [path, previous].some((name) => name?.startsWith(WORKFLOWS) === true);
+}
+/**
+ * The depth the rules route `changed` to. A change not read or not sized reads in full, as does a file
+ * outside lockfiles the compare shows no patch for.
+ */
+export function route(changed) {
+    if (changed === null || changed === "unsized") {
+        return { depth: "full" };
+    }
+    const code = changed.filter((file) => !isLockfile(file.path));
+    if (changed.length > 0 && code.length === 0) {
+        return { depth: "off", why: "lockfiles only" };
+    }
+    const lines = code.map((file) => file.lines);
+    if (changed.some(isWorkflow) || lines.includes(null)) {
+        return { depth: "full" };
+    }
+    const total = lines.reduce((sum, count) => sum + (count ?? 0), 0);
+    return { depth: total > LINE_LIMIT ? "full" : "light" };
+}

package/dist/pr/state.d.ts

@@ -1,4 +1,8 @@
-export declare const QUERY = "query($owner: String!, $name: String!, $number: Int!) {\n  repository(owner: $owner, name: $name) {\n    pullRequest(number: $number) {\n      url number state isDraft mergeable mergeStateStatus reviewDecision headRefOid headRefName baseRefName\n      viewerDidAuthor mergeCommit { oid }\n      reviewThreads(first: 100) { nodes { id isResolved isOutdated path line\n        comments(first: 1) { nodes { author { login } body } }\n        latest: comments(last: 1) { nodes { viewerDidAuthor } } } }\n      commits(last: 1) { nodes { commit { committedDate statusCheckRollup {\n        contexts(first: 50) { nodes {\n          ... on CheckRun { name status conclusion detailsUrl startedAt isRequired(pullRequestNumber: $number) }\n          ... on StatusContext { context state targetUrl createdAt isRequired(pullRequestNumber: $number) } } } } } } }\n    }\n  }\n}";
+/** The commit status a clean review of the head leaves on it. */
+export declare const REVIEW = "dw-sdlc/review";
+/** How the description of a success the script posts under off begins: no one read that head. */
+export declare const OFF_PREFIX = "off:";
+export declare const QUERY = "query($owner: String!, $name: String!, $number: Int!) {\n  repository(owner: $owner, name: $name) {\n    pullRequest(number: $number) {\n      url number state isDraft mergeable mergeStateStatus reviewDecision headRefOid headRefName baseRefName baseRefOid\n      viewerDidAuthor mergeCommit { oid }\n      reviewThreads(first: 100) { nodes { id isResolved isOutdated path line\n        comments(first: 1) { nodes { author { login } body } }\n        latest: comments(last: 1) { nodes { viewerDidAuthor } } } }\n      commits(last: 1) { nodes { commit { committedDate statusCheckRollup {\n        contexts(first: 50) { nodes {\n          ... on CheckRun { name status conclusion detailsUrl startedAt isRequired(pullRequestNumber: $number) }\n          ... on StatusContext { context state targetUrl createdAt isRequired(pullRequestNumber: $number) } } } } } } }\n      history: commits(last: 100) { nodes { commit { oid parents { totalCount } status { context(name: \"dw-sdlc/review\") { state description } } } } }\n    }\n  }\n}";
 export type Bucket = "pass" | "fail" | "pending" | "skipping";
 export type CiCheck = {
     name: string;
@@ -36,19 +40,61 @@ export type PrState = {
     headCommittedAt: string;
     branch: string;
     base: string;
+    /** The commit the base branch points at. */
+    baseOid: string;
     mergeCommit: string | null;
     checks: CiCheck[];
     /** The threads neither resolved nor outdated. */
     unresolvedThreads: Thread[];
+    /** The last commit before the head with a review success not posted under off, of the last 100. */
+    lastReviewed: LastReviewed | null;
+    /** Whether the head carries the success of `lastReviewed`: the read decides it from two compares. */
+    carried: boolean;
+    /**
+     * The files a Review would read, from `lastReviewed` or the base to the head, read only for `pr.review:
+     * auto` to route on: `unsized` when the compare cannot list them all, null when not read.
+     */
+    changed: ChangedFile[] | "unsized" | null;
+};
+/**
+ * A file a Review would read: its name, its name before a rename, and the lines it adds and removes,
+ * null when the compare shows no patch for it, as for a binary file.
+ */
+export type ChangedFile = {
+    path: string;
+    previous: string | null;
+    lines: number | null;
+};
+/** A reviewed commit, and whether every commit after it, the head included, is a merge. */
+export type LastReviewed = {
+    commit: string;
+    mergesOnly: boolean;
 };
 /** A reply that is not the shape the query asks for; the message names the field. */
 export declare class ReplyError extends Error {
 }
+/** A JSON object of the reply and the path that reached it, as `data.repository.pullRequest`. */
+export type Node = {
+    value: Record<string, unknown>;
+    at: string;
+};
+export declare function shown(value: unknown): string;
+/** The JSON object `reply` holds, the root its fields' paths start from; `what` names it in a problem. */
+export declare function rootOf(reply: string, what: string): Node;
+export declare function fieldOf(node: Node, key: string): {
+    value: unknown;
+    at: string;
+};
+export declare function object(value: unknown, at: string): Node;
+export declare function string(node: Node, key: string): string;
+export declare function integer(node: Node, key: string): number;
+/** The viewer's own pull request without a review success on its head: the one a Review reads. */
+export declare function awaitsReview(pr: Pick<PrState, "viewerDidAuthor" | "checks">): boolean;
 /** The repository and number of the pull request whose URL `gh pr view --json url` printed. */
 export declare function parseView(reply: string): {
     repo: string;
     number: number;
 };
 /** The state of the pull request in `reply`, the text `gh api graphql` printed for QUERY on `repo`. */
-export declare function parsePr(reply: string, repo: string): PrState;
+export declare function parsePr(reply: string, repo: string): Omit<PrState, "carried" | "changed">;
 export {};

package/dist/pr/state.js

@@ -1,9 +1,13 @@
 // One pull request as the Ship script reads it: the one GraphQL query, and its reply parsed into the
 // state the decision reads. Every field the state needs is checked; a reply that fails names the field.
+/** The commit status a clean review of the head leaves on it. */
+export const REVIEW = "dw-sdlc/review";
+/** How the description of a success the script posts under off begins: no one read that head. */
+export const OFF_PREFIX = "off:";
 export const QUERY = `query($owner: String!, $name: String!, $number: Int!) {
   repository(owner: $owner, name: $name) {
     pullRequest(number: $number) {
-      url number state isDraft mergeable mergeStateStatus reviewDecision headRefOid headRefName baseRefName
+      url number state isDraft mergeable mergeStateStatus reviewDecision headRefOid headRefName baseRefName baseRefOid
       viewerDidAuthor mergeCommit { oid }
       reviewThreads(first: 100) { nodes { id isResolved isOutdated path line
         comments(first: 1) { nodes { author { login } body } }
@@ -12,6 +16,7 @@ export const QUERY = `query($owner: String!, $name: String!, $number: Int!) {
         contexts(first: 50) { nodes {
           ... on CheckRun { name status conclusion detailsUrl startedAt isRequired(pullRequestNumber: $number) }
           ... on StatusContext { context state targetUrl createdAt isRequired(pullRequestNumber: $number) } } } } } } }
+      history: commits(last: 100) { nodes { commit { oid parents { totalCount } status { context(name: "${REVIEW}") { state description } } } } }
     }
   }
 }`;
@@ -24,11 +29,11 @@ export class ReplyError extends Error {
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function shown(value) {
+export function shown(value) {
     return value === undefined ? "missing" : JSON.stringify(value);
 }
 /** The JSON object `reply` holds, the root its fields' paths start from; `what` names it in a problem. */
-function rootOf(reply, what) {
+export function rootOf(reply, what) {
     let json;
     try {
         json = JSON.parse(reply);
@@ -41,10 +46,10 @@ function rootOf(reply, what) {
     }
     return { value: json, at: "" };
 }
-function fieldOf(node, key) {
+export function fieldOf(node, key) {
     return { value: node.value[key], at: node.at === "" ? key : `${node.at}.${key}` };
 }
-function object(value, at) {
+export function object(value, at) {
     if (!isRecord(value)) {
         throw new ReplyError(`${at} is ${shown(value)}, not an object`);
     }
@@ -58,7 +63,7 @@ function childOrNull(node, key) {
     const { value, at } = fieldOf(node, key);
     return value === null ? null : object(value, at);
 }
-function string(node, key) {
+export function string(node, key) {
     const { value, at } = fieldOf(node, key);
     if (typeof value !== "string") {
         throw new ReplyError(`${at} is ${shown(value)}, not a string`);
@@ -75,7 +80,7 @@ function boolean(node, key) {
     }
     return value;
 }
-function integer(node, key) {
+export function integer(node, key) {
     const { value, at } = fieldOf(node, key);
     if (typeof value !== "number" || !Number.isInteger(value)) {
         throw new ReplyError(`${at} is ${shown(value)}, not an integer`);
@@ -182,6 +187,31 @@ function threadOf(thread) {
         lastByViewer: boolean(firstNode(thread, "latest"), "viewerDidAuthor")
     };
 }
+/** The viewer's own pull request without a review success on its head: the one a Review reads. */
+export function awaitsReview(pr) {
+    return pr.viewerDidAuthor && !pr.checks.some((check) => check.name === REVIEW && check.bucket === "pass");
+}
+/** A commit whose review success says someone read it: a status posted under off never does. */
+function isReviewed(commit) {
+    const status = childOrNull(commit, "status");
+    const context = status === null ? null : childOrNull(status, "context");
+    if (context === null || string(context, "state") !== "SUCCESS") {
+        return false;
+    }
+    return !(stringOrNull(context, "description") ?? "").startsWith(OFF_PREFIX);
+}
+/** The last commit before `head` that `isReviewed` takes, the history oldest first. */
+function lastReviewedOf(pr, head) {
+    const commits = nodes(pr, "history").map((node) => child(node, "commit"));
+    const index = commits.findLastIndex((commit) => string(commit, "oid") !== head && isReviewed(commit));
+    const reviewed = commits[index];
+    if (reviewed === undefined) {
+        return null;
+    }
+    const after = commits.slice(index + 1);
+    const mergesOnly = after.every((commit) => integer(child(commit, "parents"), "totalCount") > 1);
+    return { commit: string(reviewed, "oid"), mergesOnly };
+}
 /** The repository and number of the pull request whose URL `gh pr view --json url` printed. */
 export function parseView(reply) {
     const url = string(rootOf(reply, "the reply of gh pr view"), "url");
@@ -197,6 +227,7 @@ export function parsePr(reply, repo) {
     const commit = child(firstNode(pr, "commits"), "commit");
     const rollup = childOrNull(commit, "statusCheckRollup");
     const mergeCommit = childOrNull(pr, "mergeCommit");
+    const head = string(pr, "headRefOid");
     return {
         url: string(pr, "url"),
         repo,
@@ -207,14 +238,16 @@ export function parsePr(reply, repo) {
         mergeStateStatus: string(pr, "mergeStateStatus"),
         reviewDecision: pr.value.reviewDecision === null ? null : oneOf(pr, "reviewDecision", REVIEW_DECISIONS),
         viewerDidAuthor: boolean(pr, "viewerDidAuthor"),
-        head: string(pr, "headRefOid"),
+        head,
         headCommittedAt: time(commit, "committedDate"),
         branch: string(pr, "headRefName"),
         base: string(pr, "baseRefName"),
+        baseOid: string(pr, "baseRefOid"),
         mergeCommit: mergeCommit === null ? null : string(mergeCommit, "oid"),
         checks: rollup === null ? [] : nodes(rollup, "contexts").map((context) => checkOf(context, repo)),
         unresolvedThreads: nodes(pr, "reviewThreads")
             .filter((thread) => !boolean(thread, "isResolved") && !boolean(thread, "isOutdated"))
-            .map(threadOf)
+            .map(threadOf),
+        lastReviewed: lastReviewedOf(pr, head)
     };
 }

package/dist/setup-worker.d.ts

@@ -0,0 +1,11 @@
+import { type JsonObject } from "./json-text.ts";
+/** The `worker` block a local file holds, carried through on every run, `--force` included. */
+export declare function keptWorker(existing: unknown): JsonObject | undefined;
+/**
+ * The `worker` block to write: the one the file holds, with `command` added when it has none and `cswap`
+ * is on PATH. A command already there, whatever it holds, stays; without `cswap` nothing is added.
+ */
+export declare function pinnedWorker(kept: JsonObject | undefined, pathVariable: string | undefined): {
+    worker: JsonObject | undefined;
+    detail?: string;
+};

package/dist/setup-worker.js

@@ -0,0 +1,37 @@
+// The `worker` block of the machine's local layer: the command a Worker starts with, which the setup
+// writes once when `cswap` is on PATH so no prompt ever carries it.
+import { accessSync, constants, statSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import { isObject } from "./json-text.js";
+/** The command that starts a Worker on the account `cswap` maps to the repository, prompts bypassed. */
+const CSWAP_WORKER_COMMAND = "cswap run -- --dangerously-skip-permissions";
+/** Whether an executable file `name` sits in a directory of `pathVariable`, a PATH as the shell reads it. */
+function onPath(name, pathVariable) {
+    return (pathVariable ?? "").split(delimiter).some((dir) => {
+        if (dir === "") {
+            return false;
+        }
+        try {
+            const file = join(dir, name);
+            accessSync(file, constants.X_OK);
+            return statSync(file).isFile();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** The `worker` block a local file holds, carried through on every run, `--force` included. */
+export function keptWorker(existing) {
+    return isObject(existing) && isObject(existing.worker) ? existing.worker : undefined;
+}
+/**
+ * The `worker` block to write: the one the file holds, with `command` added when it has none and `cswap`
+ * is on PATH. A command already there, whatever it holds, stays; without `cswap` nothing is added.
+ */
+export function pinnedWorker(kept, pathVariable) {
+    if ((kept !== undefined && "command" in kept) || !onPath("cswap", pathVariable)) {
+        return { worker: kept };
+    }
+    return { worker: { ...kept, command: CSWAP_WORKER_COMMAND }, detail: `worker.command: ${CSWAP_WORKER_COMMAND}` };
+}

package/package.json

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