dw-sdlc 0.6.0 → 0.7.0

package/README.md

@@ -1,8 +1,8 @@
 # dw-sdlc
 
 The Gate and the agentic config of a repository. `.ai/agentic.config.json` declares how a repository
-works for an agent: its package manager, protected branches, env-file policy, commit convention and
-the Gate. The package ships the `dw-sdlc` bin that runs on that file, its JSON Schema, and the
+works for an agent: its package manager, protected branches, env-file policy, commit convention, the
+Gate and who merges a pull request. The package ships the `dw-sdlc` bin that runs on that file, its JSON Schema, and the
 resolver of its layers.
 
 ## Install
@@ -38,6 +38,29 @@ Under `gate.checks`, a Check the package ships is `true` for its defaults or an
 `comment-budget` holds each comment block in the JavaScript, TypeScript and shell (`.sh`) files under
 its `roots` to `maxProseLines` lines of prose, 3 by default.
 
+## The Ship script
+
+`dw-sdlc pr ship [<n>] [-R owner/name]` reads one pull request through an authenticated `gh` and
+answers the one Action it needs next, as a line or, with `--json`, one document. The exit code says
+whose turn it is: 0 done, 10 the agent's, 20 wait, 30 the dev's, 2 it cannot run. The script
+performs its own Actions: it updates a branch behind its base, marks a draft ready once nothing else
+holds it back, and squash merges a pull request that is green, reviewed and opened by the `gh`
+account, when the merge is its own. `--dry-run` performs nothing: it answers the first Action the
+script would perform as the dev's. It never deletes a branch; a merged pull request answers with
+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. The local layer may tighten it and never loosen it, and `--merge` acts
+as `auto` for one call. A pull request the `gh` account did not open is always the dev's to merge.
+
+```json
+{ "pr": { "merge": "auto" } }
+```
+
+`pr ship` answers `review` until the head carries the commit status `dw-sdlc/review`, which
+`dw-sdlc pr reviewed <n> --head <sha>` posts after a clean review. It posts nothing and exits 2 once
+a push moved the head, so a new head needs a fresh review.
+
 ## Commands
 
 | command            | what it does                                                                        |
@@ -50,6 +73,8 @@ its `roots` to `maxProseLines` lines of prose, 3 by default.
 | `config`           | the resolved agentic config, or one file validated against the schema               |
 | `references sync`  | every declared Reference brought to its ref under `references/`                     |
 | `references setup` | the Router, its table and the ignore rules a repository needs to declare References |
+| `pr ship [<n>]`    | the Action one pull request needs next, performing the script's own                 |
+| `pr reviewed <n>`  | a clean review pinned to the head it read, as a commit status                       |
 
 `dw-sdlc <command> --help` gives each one's options.
 

package/config/agentic.config.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://raw.githubusercontent.com/dominikwozniak/dw-sdlc/main/plugins/guardrails/config/agentic.config.schema.json",
   "title": "agentic.config",
-  "description": "How a repository works for an agent. `.ai/agentic.config.json` is committed; `.ai/agentic.config.local.json` overrides it on one machine and may tighten `guardrails` but never loosen it. A key neither file sets is inferred: the Node package manager from the lockfile, the `conventional` commit preset, and `gate.command` from the manifest's `check` script. Unknown top-level keys are tolerated so other tool families can share the file; the keys named here refuse unknown children.",
+  "description": "How a repository works for an agent. `.ai/agentic.config.json` is committed; `.ai/agentic.config.local.json` overrides it on one machine and may tighten `guardrails` and `pr.merge` but never loosen them. A key neither file sets is inferred: the Node package manager from the lockfile, the `conventional` commit preset, and `gate.command` from the manifest's `check` script. Unknown top-level keys are tolerated so other tool families can share the file; the keys named here refuse unknown children.",
   "type": "object",
   "properties": {
     "$schema": {
@@ -357,6 +357,17 @@
       },
       "additionalProperties": false
     },
+    "pr": {
+      "description": "How the Ship script, `dw-sdlc pr ship`, ends a pull request. The local override may tighten it and never loosen it.",
+      "type": "object",
+      "properties": {
+        "merge": {
+          "description": "Who merges a pull request that is green, reviewed and authored by the account `gh` runs as. `auto`: the script squash merges it, naming the head it read. `ask`: it parks with the merge command for the dev. Default `ask`, which an invalid layer runs too. Strictest first: ask, auto.",
+          "enum": ["ask", "auto"]
+        }
+      },
+      "additionalProperties": false
+    },
     "worktree": {
       "type": "object",
       "properties": {

package/dist/agentic-config.d.ts

@@ -15,6 +15,8 @@ export type EnvFiles = {
     allow: string[];
     deny: string[];
 };
+/** Who merges a pull request the Ship script finds ready: the script under `auto`, the dev under `ask`. */
+export type PrMerge = "ask" | "auto";
 export type Guardrails = {
     forcePush: ForcePush;
     commitOnProtected: CommitOnProtected;
@@ -66,6 +68,9 @@ export type AgenticConfig = {
         trailer?: string;
     };
     gate?: GateLayer;
+    pr?: {
+        merge?: PrMerge;
+    };
     worktree?: {
         setup?: string[];
     };
@@ -85,6 +90,9 @@ export type ResolvedConfig = {
         trailer?: string;
     };
     gate: Gate;
+    pr: {
+        merge: PrMerge;
+    };
     worktree: {
         setup: string[];
     };
@@ -121,9 +129,12 @@ export declare const STRICTNESS: {
     readonly forcePush: readonly ["deny", "ask", "lease"];
     readonly commitOnProtected: readonly ["deny", "allow"];
     readonly envFiles: readonly ["deny", "git"];
+    readonly merge: readonly ["ask", "auto"];
 };
 /** 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;
 /** What a repository gets with nothing declared. */
 export declare const DEFAULT_GUARDRAILS: Guardrails;
 /**

package/dist/agentic-config.js

@@ -15,7 +15,8 @@ export const COMMIT_CONVENTIONS = ["ticket-key", "conventional"];
 export const STRICTNESS = {
     forcePush: ["deny", "ask", "lease"],
     commitOnProtected: ["deny", "allow"],
-    envFiles: ["deny", "git"]
+    envFiles: ["deny", "git"],
+    merge: ["ask", "auto"]
 };
 /** What the guards run on while any layer is invalid. */
 export const STRICTEST_GUARDRAILS = {
@@ -24,6 +25,8 @@ export const STRICTEST_GUARDRAILS = {
     envFiles: { policy: "deny", allow: [], deny: [] },
     protectedBranches: ["master", "main", "production"]
 };
+/** 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";
 /** What a repository gets with nothing declared. */
 export const DEFAULT_GUARDRAILS = {
     forcePush: "lease",
@@ -190,6 +193,7 @@ export function inferConfig(root) {
         guardrails: cloneGuardrails(DEFAULT_GUARDRAILS),
         commit: { convention: "conventional" },
         gate: inferGate(root),
+        pr: { merge: STRICTEST_PR_MERGE },
         worktree: { setup: [] }
     };
 }
@@ -205,6 +209,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 },
         worktree: { setup: layer.worktree?.setup ?? base.worktree.setup }
     };
 }
@@ -263,6 +268,14 @@ function loosenings(base, local) {
     }
     return problems;
 }
+/** A local `pr.merge` less strict than the one it would override: `auto` over `ask`. */
+function prLoosenings(base, local) {
+    if (local === undefined || rank("merge", local) <= rank("merge", base)) {
+        return [];
+    }
+    const message = `${show(local)} loosens ${show(base)}; the local file may tighten pr.merge, never loosen it`;
+    return [{ file: LOCAL_FILE, path: "pr.merge", message }];
+}
 /** `commit.pattern` from the convention's preset when no layer set one; a set pattern wins. */
 function finalize(merged) {
     const pattern = merged.commit.pattern ?? COMMIT_PATTERNS[merged.commit.convention];
@@ -284,7 +297,10 @@ export function resolveConfig(root) {
         config = applyLayer(config, committed.value);
     }
     if (local.value !== undefined) {
-        const loosened = loosenings(config.guardrails, local.value.guardrails);
+        const loosened = [
+            ...loosenings(config.guardrails, local.value.guardrails),
+            ...prLoosenings(config.pr.merge, local.value.pr?.merge)
+        ];
         if (loosened.length > 0) {
             problems.push(...loosened);
             localState = "invalid";
@@ -294,7 +310,7 @@ export function resolveConfig(root) {
         }
     }
     if (problems.length > 0) {
-        config = { ...config, guardrails: cloneGuardrails(STRICTEST_GUARDRAILS) };
+        config = { ...config, guardrails: cloneGuardrails(STRICTEST_GUARDRAILS), pr: { merge: STRICTEST_PR_MERGE } };
     }
     return {
         config: finalize(config),

package/dist/cli.js

@@ -5,6 +5,8 @@ import * as check from "./commands/check.js";
 import * as config from "./commands/config.js";
 import * as doctor from "./commands/doctor.js";
 import * as gate from "./commands/gate.js";
+import * as prReviewed from "./commands/pr-reviewed.js";
+import * as prShip from "./commands/pr-ship.js";
 import * as primitives from "./commands/primitives.js";
 import * as referencesSetup from "./commands/references-setup.js";
 import * as referencesSync from "./commands/references-sync.js";
@@ -17,7 +19,9 @@ const COMMANDS = new Map([
     ["doctor", doctor],
     ["config", config],
     ["references sync", referencesSync],
-    ["references setup", referencesSetup]
+    ["references setup", referencesSetup],
+    ["pr ship", prShip],
+    ["pr reviewed", prReviewed]
 ]);
 function usage() {
     const width = Math.max(...[...COMMANDS.keys()].map((name) => name.length)) + 2;

package/dist/commands/pr-reviewed.d.ts

@@ -0,0 +1,2 @@
+export declare const summary = "pin a clean review to the head it read, as a commit status";
+export declare function run(argv: string[]): number;

package/dist/commands/pr-reviewed.js

@@ -0,0 +1,108 @@
+// `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 { 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]
+
+Reads pull request <n> through gh, the read pr ship makes, and when its head is still <sha> posts
+the commit status dw-sdlc/review in state success on it, the pull request's URL as its target. When
+a push moved the head since the review, it posts nothing. One line, or one document with --json.
+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 {
+        const { values, positionals } = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                help: { type: "boolean", short: "h" },
+                json: { type: "boolean" },
+                repo: { type: "string", short: "R" },
+                head: { type: "string" }
+            }
+        });
+        if (values.help === true) {
+            return "help";
+        }
+        const [number, ...more] = positionals;
+        const { repo, head } = values;
+        if (number === undefined) {
+            return { error: "name the pull request: dw-sdlc pr reviewed <n> --head <sha>" };
+        }
+        if (more.length > 0) {
+            return { error: `name one pull request, not ${positionals.length}` };
+        }
+        const problem = namedProblem(number, repo);
+        if (problem !== undefined) {
+            return { error: problem };
+        }
+        if (head === undefined) {
+            return { error: "name the head the review read: --head <sha>" };
+        }
+        if (!/^[0-9a-f]{40}$/.test(head)) {
+            return { error: `--head takes the full 40-character sha, not ${JSON.stringify(head)}` };
+        }
+        return { json: values.json === true, number: Number(number), repo, head };
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) };
+    }
+}
+/** 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");
+    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}`
+    ]);
+    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`);
+    }
+}
+export function run(argv) {
+    const cli = parseCli(argv);
+    if (cli === "help") {
+        process.stdout.write(`${USAGE}\n`);
+        return 0;
+    }
+    if ("error" in cli) {
+        process.stderr.write(`dw-sdlc pr reviewed: ${cli.error}\n\n${USAGE}\n`);
+        return 2;
+    }
+    try {
+        post(cli);
+    }
+    catch (error) {
+        if (error instanceof CannotRun) {
+            process.stderr.write(`dw-sdlc pr reviewed: ${error.message} — ${error.remedy}\n`);
+            return 2;
+        }
+        throw error;
+    }
+    const { head } = cli;
+    const answer = cli.json
+        ? JSON.stringify({ head, context: CONTEXT, state: STATE }, null, 2)
+        : `posted ${CONTEXT} ${STATE} on ${head}`;
+    process.stdout.write(`${answer}\n`);
+    return 0;
+}

package/dist/commands/pr-ship.d.ts

@@ -0,0 +1,2 @@
+export declare const summary = "decide the Action one pull request needs next, as a line or JSON";
+export declare function run(argv: string[]): number;

package/dist/commands/pr-ship.js

@@ -0,0 +1,163 @@
+// `dw-sdlc pr ship [<n>]`, the Ship script: reads one pull request through gh, decides the Action it
+// 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 { 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]
+
+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.
+
+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 };
+const REMEDIES = { clock: "unset it: it stands in for the clock in tests" };
+function parseCli(argv) {
+    try {
+        const { values, positionals } = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                help: { type: "boolean", short: "h" },
+                json: { type: "boolean" },
+                verbose: { type: "boolean" },
+                merge: { type: "boolean" },
+                "dry-run": { type: "boolean" },
+                repo: { type: "string", short: "R" }
+            }
+        });
+        const [number, ...more] = positionals;
+        const { repo } = values;
+        if (values.help !== true) {
+            if (more.length > 0) {
+                return { error: `name one pull request, not ${positionals.length}` };
+            }
+            const problem = namedProblem(number, repo);
+            if (problem !== undefined) {
+                return { error: problem };
+            }
+        }
+        return {
+            help: values.help === true,
+            json: values.json === true,
+            verbose: values.verbose === true,
+            merge: values.merge === true,
+            dryRun: values["dry-run"] === true,
+            number: number === undefined ? undefined : Number(number),
+            repo
+        };
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) };
+    }
+}
+/** The time the decision reads: DW_SDLC_NOW, an ISO 8601 time a test sets, else the system clock. */
+function now() {
+    const given = process.env.DW_SDLC_NOW?.trim();
+    if (given === undefined || given === "") {
+        return Date.now();
+    }
+    const time = Date.parse(given);
+    if (Number.isNaN(time)) {
+        throw new CannotRun(`DW_SDLC_NOW is ${JSON.stringify(given)}, not an ISO 8601 time`, REMEDIES.clock);
+    }
+    return time;
+}
+/** How a reason names each script Action: what the script would do, the act, and the state it acts on. */
+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" },
+    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) {
+    if (action === "merge") {
+        return { ...readyToMerge(pr, reason), blockers: answer.blockers };
+    }
+    return { ...answer, status: "park", actor: "dev", reason, command: devCommand(pr, action) };
+}
+/**
+ * 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) {
+    let pr = read(cli, "pr ship");
+    const performed = [];
+    const refusals = {};
+    for (;;) {
+        const answer = decide(pr, now(), merge);
+        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 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`),
+                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 };
+        }
+        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}`;
+        }
+        pr = readAgain(pr);
+    }
+}
+/** `<status> <action>: <reason>`, the action dropped when it repeats the status, then the recheck and the command. */
+function lineOf({ status, action, reason, command, recheckAfter }) {
+    const label = status === action ? status : `${status} ${action}`;
+    const recheck = recheckAfter === undefined ? "" : `, recheck in ${recheckAfter} s`;
+    return `${label}: ${reason}${recheck}${command === undefined ? "" : ` — ${command}`}`;
+}
+function documentOf(pr, answer, performed, verbose) {
+    const facts = verbose ? { facts: pr } : {};
+    return { pr: pr.url, head: pr.head, base: pr.base, ...answer, performed, ...facts };
+}
+export function run(argv) {
+    const cli = parseCli(argv);
+    if ("error" in cli) {
+        process.stderr.write(`dw-sdlc pr ship: ${cli.error}\n\n${USAGE}\n`);
+        return 2;
+    }
+    if (cli.help) {
+        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;
+    let shipped;
+    try {
+        shipped = ship(cli, merge);
+    }
+    catch (error) {
+        if (error instanceof CannotRun) {
+            process.stderr.write(`dw-sdlc pr ship: ${error.message} — ${error.remedy}\n`);
+            return 2;
+        }
+        throw error;
+    }
+    const { pr, answer, performed } = shipped;
+    const output = cli.json ? JSON.stringify(documentOf(pr, answer, performed, cli.verbose), null, 2) : lineOf(answer);
+    process.stdout.write(`${output}\n`);
+    return EXIT[answer.status];
+}

package/dist/pr/decide.d.ts

@@ -0,0 +1,36 @@
+import type { PrMerge } from "../agentic-config.ts";
+import type { PrState } from "./state.ts";
+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" | "unverified" | "ci-stuck" | "awaiting-reply" | "mark-ready" | "awaiting-approval" | "ready-to-merge" | "merge";
+/** The Actions the script performs itself, each one gh command. */
+export type ScriptAction = "update-branch" | "mark-ready" | "merge";
+/** An Action the pull request needs beside the one its answer names, so one push can fix several. */
+export type Blocker = {
+    action: Action;
+    actor: Actor;
+    reason: string;
+    details?: Record<string, unknown>;
+};
+export type Answer = Blocker & {
+    status: Status;
+    /** A shell-quoted command, when there is one to run. */
+    command?: string;
+    /** Seconds to wait before calling again. */
+    recheckAfter?: number;
+    blockers: Blocker[];
+};
+/** The words as one POSIX shell command line, each word that needs it single-quoted. */
+export declare function shellLine(words: string[]): string;
+export declare function isScriptAction(action: Action): action is ScriptAction;
+/**
+ * The gh arguments of a script Action, `-R` naming the repository when `named`. The update merges the
+ * base in, never --rebase, which rewrites the branch on GitHub; the merge names the head it read.
+ */
+export declare function hostArgs(pr: PrState, action: ScriptAction, named: boolean): string[];
+/** The command a script Action leaves the dev to run, from a checkout of the repository. */
+export declare function devCommand(pr: PrState, action: ScriptAction): string;
+/** The merge left to the dev, `reason` saying why it is theirs. */
+export declare function readyToMerge(pr: PrState, reason: string): Omit<Answer, "blockers">;
+/** The Action `pr` needs at `now`, milliseconds since the epoch, when `merge` says who merges it. */
+export declare function decide(pr: PrState, now: number, merge: PrMerge): Answer;

package/dist/pr/decide.js

@@ -0,0 +1,216 @@
+// 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.
+/** 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. */
+const REVIEW = "dw-sdlc/review";
+/** The words as one POSIX shell command line, each word that needs it single-quoted. */
+export function shellLine(words) {
+    return words.map((word) => (/^[\w./:=@%+,-]+$/.test(word) ? word : `'${word.replaceAll("'", `'\\''`)}'`)).join(" ");
+}
+function ciOf(pr) {
+    return pr.checks.filter((check) => !check.name.startsWith(OWN_PREFIX));
+}
+function pendingOf(pr) {
+    return ciOf(pr).filter((check) => check.bucket === "pending");
+}
+function failingOf(pr) {
+    return ciOf(pr).filter((check) => check.bucket === "fail");
+}
+/** A failing check as the agent reads it: its link, and the command that prints a GitHub Actions job's log. */
+function failure({ name, link, log }) {
+    return { name, link, ...(log === null ? {} : { log: shellLine(log) }) };
+}
+/** The unresolved threads whose last comment is the viewer's, or with `false` someone else's. */
+function threads(pr, lastByViewer) {
+    return pr.unresolvedThreads.filter((thread) => thread.lastByViewer === lastByViewer);
+}
+function listed({ id, path, line, author, body }) {
+    return { id, path, line, author, body };
+}
+const HOST = {
+    "update-branch": { verb: "update-branch", flags: () => [] },
+    "mark-ready": { verb: "ready", flags: () => [] },
+    merge: { verb: "merge", flags: (pr) => ["--squash", "--match-head-commit", pr.head] }
+};
+export function isScriptAction(action) {
+    return Object.hasOwn(HOST, action);
+}
+/**
+ * The gh arguments of a script Action, `-R` naming the repository when `named`. The update merges the
+ * base in, never --rebase, which rewrites the branch on GitHub; the merge names the head it read.
+ */
+export function hostArgs(pr, action, named) {
+    const { verb, flags } = HOST[action];
+    return ["pr", verb, String(pr.number), ...(named ? ["-R", pr.repo] : []), ...flags(pr)];
+}
+/** The command a script Action leaves the dev to run, from a checkout of the repository. */
+export function devCommand(pr, action) {
+    return shellLine(["gh", ...hostArgs(pr, action, false)]);
+}
+/** The merge left to the dev, `reason` saying why it is theirs. */
+export function readyToMerge(pr, reason) {
+    return { status: "park", action: "ready-to-merge", actor: "dev", reason, command: devCommand(pr, "merge") };
+}
+const ROWS = [
+    {
+        when: (pr) => pr.state === "MERGED",
+        answer: (pr) => ({
+            status: "done",
+            action: "done",
+            actor: "dev",
+            reason: pr.mergeCommit === null ? "merged" : `merged as ${pr.mergeCommit.slice(0, 7)}`,
+            command: shellLine(["git", "push", "origin", "--delete", pr.branch]),
+            ...(pr.mergeCommit === null ? {} : { details: { mergeCommit: pr.mergeCommit } })
+        }),
+        alone: true
+    },
+    {
+        when: (pr) => pr.state === "CLOSED",
+        answer: () => ({ status: "park", action: "stop", actor: "dev", reason: "closed without merging" }),
+        alone: true
+    },
+    {
+        when: (pr) => pr.mergeable === "UNKNOWN",
+        answer: () => ({
+            status: "wait",
+            action: "wait",
+            actor: "script",
+            reason: "mergeability-unknown",
+            recheckAfter: 15
+        }),
+        alone: true
+    },
+    {
+        when: (pr) => pr.mergeable === "CONFLICTING",
+        answer: (pr) => ({
+            status: "act",
+            action: "fix-conflicts",
+            actor: "agent",
+            reason: `conflicts with ${pr.base}`,
+            details: { base: pr.base }
+        })
+    },
+    {
+        when: (pr) => pr.mergeStateStatus === "BEHIND",
+        answer: (pr) => ({ status: "act", action: "update-branch", actor: "script", reason: `behind ${pr.base}` })
+    },
+    {
+        when: (pr) => failingOf(pr).length > 0,
+        answer: (pr) => ({
+            status: "act",
+            action: "fix-ci",
+            actor: "agent",
+            reason: `${failingOf(pr).length} check(s) failing`,
+            details: { checks: failingOf(pr).map(failure) }
+        })
+    },
+    {
+        when: (pr) => threads(pr, false).length > 0,
+        answer: (pr) => ({
+            status: "act",
+            action: "address-review",
+            actor: "agent",
+            reason: `${threads(pr, false).length} unresolved thread(s)`,
+            details: { threads: threads(pr, false).map(listed) }
+        })
+    },
+    {
+        when: (pr) => pr.reviewDecision === "CHANGES_REQUESTED",
+        answer: () => ({ status: "act", action: "address-review", actor: "agent", reason: "changes requested" })
+    },
+    {
+        when: (pr) => !pr.checks.some((check) => check.name === REVIEW && check.bucket === "pass"),
+        answer: (pr) => ({
+            status: "act",
+            action: "review",
+            actor: "agent",
+            reason: `no ${REVIEW} success on ${pr.head.slice(0, 7)}`
+        })
+    },
+    {
+        when: (pr) => ciOf(pr).length === 0,
+        answer: (pr, now) => now - Date.parse(pr.headCommittedAt) <= GRACE_SECONDS * 1000
+            ? { status: "wait", action: "wait", actor: "script", reason: "unverified", recheckAfter: 15 }
+            : {
+                status: "park",
+                action: "unverified",
+                actor: "dev",
+                reason: `no check reported on ${pr.head.slice(0, 7)} within ${GRACE_SECONDS} s of its commit`,
+                command: devCommand(pr, "merge")
+            }
+    },
+    {
+        when: (pr) => pendingOf(pr).length > 0,
+        answer: (pr, now) => {
+            const pending = pendingOf(pr);
+            // A check queued and not yet started counts from the head's commit.
+            const start = Math.min(...pending.map((check) => Date.parse(check.startedAt ?? pr.headCommittedAt)));
+            const minutes = Math.floor((now - start) / 60_000);
+            return now - start <= BUDGET_MINUTES * 60_000
+                ? { status: "wait", action: "wait", actor: "script", reason: "ci-pending", recheckAfter: 60 }
+                : {
+                    status: "park",
+                    action: "ci-stuck",
+                    actor: "dev",
+                    reason: `${pending.length} check(s) pending for ${minutes} min, past the ${BUDGET_MINUTES} min budget`
+                };
+        }
+    },
+    {
+        when: (pr) => threads(pr, true).length > 0,
+        answer: (pr) => ({
+            status: "park",
+            action: "awaiting-reply",
+            actor: "dev",
+            reason: `${threads(pr, true).length} thread(s) await a reply`,
+            details: { threads: threads(pr, true).map(listed) }
+        })
+    },
+    {
+        when: (pr) => pr.draft,
+        answer: () => ({ status: "act", action: "mark-ready", actor: "script", reason: "still a draft" })
+    },
+    {
+        when: (pr) => pr.reviewDecision === "REVIEW_REQUIRED",
+        answer: () => ({
+            status: "park",
+            action: "awaiting-approval",
+            actor: "dev",
+            reason: "an approving review is required"
+        })
+    },
+    {
+        when: (pr) => !pr.viewerDidAuthor,
+        answer: (pr) => readyToMerge(pr, "another author's pull request: the merge is the dev's"),
+        merging: true
+    },
+    {
+        when: (_, merge) => merge === "auto",
+        answer: () => ({ status: "act", action: "merge", actor: "script", reason: "green, reviewed and the viewer's own" }),
+        merging: true
+    },
+    {
+        when: (_, merge) => merge === "ask",
+        answer: (pr) => readyToMerge(pr, "pr.merge is ask: the merge is the dev's"),
+        merging: true
+    }
+];
+function blockerOf({ action, actor, reason, details }) {
+    return { action, actor, reason, ...(details === undefined ? {} : { details }) };
+}
+/** The Action `pr` needs at `now`, milliseconds since the epoch, when `merge` says who merges it. */
+export function decide(pr, now, merge) {
+    const index = ROWS.findIndex((row) => row.when(pr, merge));
+    const row = ROWS[index];
+    if (row === undefined) {
+        throw new Error(`no row of the decision matches ${pr.url} under pr.merge ${merge}`);
+    }
+    const later = row.alone === true ? [] : ROWS.slice(index + 1).filter((other) => !other.merging && other.when(pr, merge));
+    return { ...row.answer(pr, now), blockers: later.map((other) => blockerOf(other.answer(pr, now))) };
+}

package/dist/pr/read.d.ts

@@ -0,0 +1,24 @@
+import { type PrState } from "./state.ts";
+/** What stops a pr command before it answers: exit 2, the problem and its remedy on one line. */
+export declare class CannotRun extends Error {
+    remedy: string;
+    constructor(message: string, remedy: string);
+}
+/** The pull request a command line names; what it leaves out, `gh pr view` resolves. */
+export type Named = {
+    number: number | undefined;
+    repo: string | undefined;
+};
+/** The problem with `<n>` or `-R` as given on a command line, if there is one. */
+export declare function namedProblem(number: string | undefined, repo: string | undefined): string | undefined;
+/** What gh said went wrong: the first line of its stderr, without its `gh: ` prefix or its `X` icon. */
+export declare function said(stderr: string): string;
+export declare function gh(args: string[]): {
+    status: number;
+    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 `pr` once more, after an action the script performed on it: the same pull request. */
+export declare function readAgain(pr: PrState): PrState;

package/dist/pr/read.js

@@ -0,0 +1,112 @@
+// 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.
+import { spawnSync } from "node:child_process";
+import { 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;
+    constructor(message, remedy) {
+        super(message);
+        this.remedy = remedy;
+    }
+}
+const REMEDIES = {
+    missing: "install the GitHub CLI from https://cli.github.com",
+    auth: "run gh auth login, or set GH_TOKEN",
+    target: "check the number, or name the repository with -R owner/name",
+    read: "check gh auth status and the network, then call again",
+    reply: "gh answered a shape dw-sdlc does not read; report it with the output of gh --version"
+};
+/** The problem with `<n>` or `-R` as given on a command line, if there is one. */
+export function namedProblem(number, repo) {
+    if (number !== undefined && !/^[1-9]\d*$/.test(number)) {
+        return `${JSON.stringify(number)} is not a pull request number`;
+    }
+    if (repo !== undefined && !/^[\w.-]+\/[\w.-]+$/.test(repo)) {
+        return `-R takes owner/name, not ${JSON.stringify(repo)}`;
+    }
+    return undefined;
+}
+function firstLine(text) {
+    return text.trim().split("\n")[0] ?? "";
+}
+/** What gh said went wrong: the first line of its stderr, without its `gh: ` prefix or its `X` icon. */
+export function said(stderr) {
+    return firstLine(stderr).replace(/^(?:gh: |X )/, "");
+}
+/** The problem `gh auth status` reports: its line marked `X` under the host, else its first line. */
+function authProblem(stderr) {
+    const marked = stderr.split("\n").find((line) => line.trimStart().startsWith("X "));
+    return marked === undefined ? firstLine(stderr) : marked.trim().slice(2);
+}
+export function gh(args) {
+    const result = spawnSync("gh", args, { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+    if (result.error !== undefined) {
+        if ("code" in result.error && result.error.code === "ENOENT") {
+            throw new CannotRun("gh is not on PATH", REMEDIES.missing);
+        }
+        throw result.error;
+    }
+    return { status: result.status ?? 1, stdout: result.stdout, stderr: result.stderr };
+}
+/** What `parse` returns; a reply it cannot parse stops the command, naming the field. */
+function parseOrCannotRun(parse) {
+    try {
+        return parse();
+    }
+    catch (error) {
+        if (error instanceof ReplyError) {
+            throw new CannotRun(`the reply does not parse: ${error.message}`, REMEDIES.reply);
+        }
+        throw error;
+    }
+}
+/** The pull request named in full, or the one `gh pr view` resolves from what is given. */
+function targetOf({ number, repo }, command) {
+    if (number !== undefined && repo !== undefined) {
+        return { repo, number };
+    }
+    const named = [...(number === undefined ? [] : [String(number)]), ...(repo === undefined ? [] : ["-R", repo])];
+    const view = gh(["pr", "view", ...named, "--json", "url"]);
+    if (view.status !== 0) {
+        const remedy = `name it: dw-sdlc ${command} <n> -R owner/name`;
+        throw new CannotRun(`gh pr view found no pull request: ${firstLine(view.stderr)}`, remedy);
+    }
+    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 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));
+}
+/** 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);
+}
+/** The state of pull request `number` of `repo`, from one GraphQL request. */
+function query({ repo, number }) {
+    const [owner = "", name = ""] = repo.split("/");
+    const reply = gh([
+        "api",
+        "graphql",
+        "-f",
+        `query=${QUERY}`,
+        "-f",
+        `owner=${owner}`,
+        "-f",
+        `name=${name}`,
+        "-F",
+        `number=${number}`
+    ]);
+    if (reply.status !== 0) {
+        const problem = said(reply.stderr);
+        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));
+}

package/dist/pr/state.d.ts

@@ -0,0 +1,54 @@
+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}";
+export type Bucket = "pass" | "fail" | "pending" | "skipping";
+export type CiCheck = {
+    name: string;
+    bucket: Bucket;
+    required: boolean;
+    link: string | null;
+    /** The command that prints a failed GitHub Actions job's log; null for any other CI. */
+    log: string[] | null;
+    startedAt: string | null;
+};
+export type Thread = {
+    id: string;
+    path: string;
+    line: number | null;
+    author: string;
+    body: string;
+    /** Whether the viewer, the account gh reads as, wrote the thread's last comment. */
+    lastByViewer: boolean;
+};
+declare const STATES: readonly ["OPEN", "CLOSED", "MERGED"];
+declare const MERGEABLE: readonly ["MERGEABLE", "CONFLICTING", "UNKNOWN"];
+declare const REVIEW_DECISIONS: readonly ["APPROVED", "CHANGES_REQUESTED", "REVIEW_REQUIRED"];
+export type PrState = {
+    url: string;
+    repo: string;
+    number: number;
+    state: (typeof STATES)[number];
+    draft: boolean;
+    mergeable: (typeof MERGEABLE)[number];
+    /** BEHIND, BLOCKED, CLEAN, DIRTY, HAS_HOOKS, UNKNOWN or UNSTABLE, as GitHub reports it. */
+    mergeStateStatus: string;
+    reviewDecision: (typeof REVIEW_DECISIONS)[number] | null;
+    viewerDidAuthor: boolean;
+    head: string;
+    headCommittedAt: string;
+    branch: string;
+    base: string;
+    mergeCommit: string | null;
+    checks: CiCheck[];
+    /** The threads neither resolved nor outdated. */
+    unresolvedThreads: Thread[];
+};
+/** A reply that is not the shape the query asks for; the message names the field. */
+export declare class ReplyError extends Error {
+}
+/** 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 {};

package/dist/pr/state.js

@@ -0,0 +1,220 @@
+// 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.
+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
+      viewerDidAuthor mergeCommit { oid }
+      reviewThreads(first: 100) { nodes { id isResolved isOutdated path line
+        comments(first: 1) { nodes { author { login } body } }
+        latest: comments(last: 1) { nodes { viewerDidAuthor } } } }
+      commits(last: 1) { nodes { commit { committedDate statusCheckRollup {
+        contexts(first: 50) { nodes {
+          ... on CheckRun { name status conclusion detailsUrl startedAt isRequired(pullRequestNumber: $number) }
+          ... on StatusContext { context state targetUrl createdAt isRequired(pullRequestNumber: $number) } } } } } } }
+    }
+  }
+}`;
+const STATES = ["OPEN", "CLOSED", "MERGED"];
+const MERGEABLE = ["MERGEABLE", "CONFLICTING", "UNKNOWN"];
+const REVIEW_DECISIONS = ["APPROVED", "CHANGES_REQUESTED", "REVIEW_REQUIRED"];
+/** A reply that is not the shape the query asks for; the message names the field. */
+export class ReplyError extends Error {
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+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) {
+    let json;
+    try {
+        json = JSON.parse(reply);
+    }
+    catch {
+        throw new ReplyError(`${what} is not JSON`);
+    }
+    if (!isRecord(json)) {
+        throw new ReplyError(`${what} is not a JSON object`);
+    }
+    return { value: json, at: "" };
+}
+function fieldOf(node, key) {
+    return { value: node.value[key], at: node.at === "" ? key : `${node.at}.${key}` };
+}
+function object(value, at) {
+    if (!isRecord(value)) {
+        throw new ReplyError(`${at} is ${shown(value)}, not an object`);
+    }
+    return { value, at };
+}
+function child(node, key) {
+    const { value, at } = fieldOf(node, key);
+    return object(value, at);
+}
+function childOrNull(node, key) {
+    const { value, at } = fieldOf(node, key);
+    return value === null ? null : object(value, at);
+}
+function string(node, key) {
+    const { value, at } = fieldOf(node, key);
+    if (typeof value !== "string") {
+        throw new ReplyError(`${at} is ${shown(value)}, not a string`);
+    }
+    return value;
+}
+function stringOrNull(node, key) {
+    return node.value[key] === null ? null : string(node, key);
+}
+function boolean(node, key) {
+    const { value, at } = fieldOf(node, key);
+    if (typeof value !== "boolean") {
+        throw new ReplyError(`${at} is ${shown(value)}, not a boolean`);
+    }
+    return value;
+}
+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`);
+    }
+    return value;
+}
+function integerOrNull(node, key) {
+    const { value, at } = fieldOf(node, key);
+    if (value !== null && !Number.isInteger(value)) {
+        throw new ReplyError(`${at} is ${shown(value)}, not an integer or null`);
+    }
+    return typeof value === "number" ? value : null;
+}
+/** A time as GitHub writes it, ISO 8601; the decision reads it as one. */
+function time(node, key) {
+    const value = string(node, key);
+    if (Number.isNaN(Date.parse(value))) {
+        throw new ReplyError(`${fieldOf(node, key).at} is ${shown(value)}, not a time`);
+    }
+    return value;
+}
+function timeOrNull(node, key) {
+    return node.value[key] === null ? null : time(node, key);
+}
+function isOneOf(values, value) {
+    return values.some((known) => known === value);
+}
+function oneOf(node, key, values) {
+    const { value, at } = fieldOf(node, key);
+    if (!isOneOf(values, value)) {
+        throw new ReplyError(`${at} is ${shown(value)}, not one of ${values.join(", ")}`);
+    }
+    return value;
+}
+/** The objects of a connection's `nodes`. */
+function nodes(node, key) {
+    const { value, at } = fieldOf(child(node, key), "nodes");
+    if (!Array.isArray(value)) {
+        throw new ReplyError(`${at} is ${shown(value)}, not a list`);
+    }
+    return value.map((item, index) => object(item, `${at}[${index}]`));
+}
+/** The first object of a connection's `nodes`; an empty connection does not parse. */
+function firstNode(node, key) {
+    const [first] = nodes(node, key);
+    if (first === undefined) {
+        throw new ReplyError(`${node.at}.${key}.nodes is empty`);
+    }
+    return first;
+}
+const FAIL = new Set(["ERROR", "FAILURE", "TIMED_OUT", "ACTION_REQUIRED", "CANCELLED", "STARTUP_FAILURE"]);
+const SKIPPING = new Set(["SKIPPED", "NEUTRAL"]);
+/** A check's bucket as `gh pr checks` sorts it: every word not passed, failed or skipped is pending. */
+function bucketOf(word) {
+    if (word === "SUCCESS") {
+        return "pass";
+    }
+    if (word !== null && FAIL.has(word)) {
+        return "fail";
+    }
+    return word !== null && SKIPPING.has(word) ? "skipping" : "pending";
+}
+function logCommand(link, repo) {
+    const job = link?.match(/\/actions\/runs\/\d+\/job\/(\d+)/)?.[1];
+    return job === undefined ? null : ["gh", "run", "view", "--job", job, "-R", repo, "--log-failed"];
+}
+/** A CheckRun has a name and a status; a StatusContext has a context and a state. */
+function checkOf(context, repo) {
+    if ("name" in context.value) {
+        const status = string(context, "status");
+        const link = stringOrNull(context, "detailsUrl");
+        return {
+            name: string(context, "name"),
+            bucket: bucketOf(status === "COMPLETED" ? stringOrNull(context, "conclusion") : status),
+            required: boolean(context, "isRequired"),
+            link,
+            log: logCommand(link, repo),
+            startedAt: timeOrNull(context, "startedAt")
+        };
+    }
+    if ("context" in context.value) {
+        const link = stringOrNull(context, "targetUrl");
+        return {
+            name: string(context, "context"),
+            bucket: bucketOf(string(context, "state")),
+            required: boolean(context, "isRequired"),
+            link,
+            log: logCommand(link, repo),
+            startedAt: time(context, "createdAt")
+        };
+    }
+    throw new ReplyError(`${context.at} is neither a CheckRun nor a StatusContext`);
+}
+/** A thread by its opening comment; a deleted account's comment has no author and reads as GitHub's ghost. */
+function threadOf(thread) {
+    const first = firstNode(thread, "comments");
+    const author = childOrNull(first, "author");
+    return {
+        id: string(thread, "id"),
+        path: string(thread, "path"),
+        line: integerOrNull(thread, "line"),
+        author: author === null ? "ghost" : string(author, "login"),
+        body: string(first, "body"),
+        lastByViewer: boolean(firstNode(thread, "latest"), "viewerDidAuthor")
+    };
+}
+/** 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");
+    const [, repo, number] = /^https:\/\/[^/]+\/([^/]+\/[^/]+)\/pull\/(\d+)$/.exec(url) ?? [];
+    if (repo === undefined || number === undefined) {
+        throw new ReplyError(`url is ${JSON.stringify(url)}, not a pull request's URL`);
+    }
+    return { repo, number: Number(number) };
+}
+/** The state of the pull request in `reply`, the text `gh api graphql` printed for QUERY on `repo`. */
+export function parsePr(reply, repo) {
+    const pr = child(child(child(rootOf(reply, "the reply"), "data"), "repository"), "pullRequest");
+    const commit = child(firstNode(pr, "commits"), "commit");
+    const rollup = childOrNull(commit, "statusCheckRollup");
+    const mergeCommit = childOrNull(pr, "mergeCommit");
+    return {
+        url: string(pr, "url"),
+        repo,
+        number: integer(pr, "number"),
+        state: oneOf(pr, "state", STATES),
+        draft: boolean(pr, "isDraft"),
+        mergeable: oneOf(pr, "mergeable", MERGEABLE),
+        mergeStateStatus: string(pr, "mergeStateStatus"),
+        reviewDecision: pr.value.reviewDecision === null ? null : oneOf(pr, "reviewDecision", REVIEW_DECISIONS),
+        viewerDidAuthor: boolean(pr, "viewerDidAuthor"),
+        head: string(pr, "headRefOid"),
+        headCommittedAt: time(commit, "committedDate"),
+        branch: string(pr, "headRefName"),
+        base: string(pr, "baseRefName"),
+        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)
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dw-sdlc",
-  "version": "0.6.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, and the Sync and setup of References; the resolver of the config's layers, its JSON Schema and the validator that reads it.",
+  "version": "0.7.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": {
     "type": "git",