dw-sdlc 0.5.1 → 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/config/references.schema.json

@@ -1,56 +1,70 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://raw.githubusercontent.com/dominikwozniak/dw-sdlc/main/plugins/references/config/references.schema.json",
+  "$id": "https://raw.githubusercontent.com/dominikwozniak/dw-sdlc/main/packages/dw-sdlc/config/references.schema.json",
   "title": "references",
-  "description": "The `references` key of `.ai/agentic.config.json`: the repositories an agent reads to see how a problem was solved before, each brought to its ref under `references/<dir>` by the Sync. Only the committed file is read; the local layer adds no References. Every `dir` is unique in the list, which this schema cannot say and the Sync refuses. A key the Sync refuses syncs nothing.",
-  "type": "array",
-  "items": {
-    "type": "object",
-    "properties": {
-      "dir": {
-        "description": "The one directory under `references/` the clone lives in: letters, digits, `_`, `.` and `-`, not starting with `.` or `-`.",
-        "type": "string",
-        "pattern": "^[A-Za-z0-9_][A-Za-z0-9_.-]*$"
-      },
-      "repository": {
-        "description": "A URL `git` can fetch. A `https://github.com/` one fetches with the GitHub CLI's credentials. No whitespace, and no leading `-`, which `git` would read as an option.",
-        "type": "string",
-        "pattern": "^[^\\s-]\\S*$"
-      },
-      "ref": {
-        "description": "A branch, whose head the clone moves to, or a tag. `{name}` in it stands for the exact version the root `package.json` pins for package `name`, read through the default catalog of `pnpm-workspace.yaml` when the pin says `catalog:` or `catalog:default`. No whitespace, and no leading `-`.",
-        "type": "string",
-        "pattern": "^[^\\s-]\\S*$"
-      },
-      "only": {
-        "description": "Paths the sparse checkout holds beside the repository's top-level files, relative to the clone and inside it; a directory ends in `/`. Absent, the whole tree is checked out. Present, it names at least one path, and a path the ref's tree lacks fails the Reference.",
-        "type": "array",
-        "minItems": 1,
-        "items": {
-          "type": "string",
-          "pattern": "^(?!/)(?!(?:.*/)?\\.\\.(?:/|$)).+$"
-        }
-      },
-      "skip": {
-        "description": "Paths the sparse checkout leaves out, relative to the clone and inside it. Empty or absent, nothing is left out. With `only`, each lies inside one of its paths, which this schema cannot say and the Sync refuses.",
-        "type": "array",
-        "items": {
-          "type": "string",
-          "pattern": "^(?!/)(?!(?:.*/)?\\.\\.(?:/|$)).+$"
-        }
-      },
-      "what": {
-        "description": "What the Reference is.",
-        "type": "string",
-        "minLength": 1
-      },
-      "when": {
-        "description": "When an agent reaches for it.",
-        "type": "string",
-        "minLength": 1
-      }
+  "description": "`.ai/references.json`: the repositories an agent reads to see how a problem was solved before, each brought to its ref under `references/<dir>` by the Sync. Only the committed file is read. A `references` key in `.ai/agentic.config.json` is refused: `dw-sdlc references setup` moves it here. A file the Sync refuses syncs nothing.",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "version": {
+      "const": 1
     },
-    "required": ["dir", "repository", "ref", "what", "when"],
-    "additionalProperties": false
-  }
+    "references": {
+      "description": "The References, in the order the Router lists them. Every `dir` is unique in the list, which this schema cannot say and the Sync refuses.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "dir": {
+            "description": "The one directory under `references/` the clone lives in: letters, digits, `_`, `.` and `-`, not starting with `.` or `-`.",
+            "type": "string",
+            "pattern": "^[A-Za-z0-9_][A-Za-z0-9_.-]*$"
+          },
+          "repository": {
+            "description": "A URL `git` can fetch. A `https://github.com/` one fetches with the GitHub CLI's credentials. No whitespace, and no leading `-`, which `git` would read as an option.",
+            "type": "string",
+            "pattern": "^[^\\s-]\\S*$"
+          },
+          "ref": {
+            "description": "A branch, whose head the clone moves to, or a tag. `{name}` in it stands for the exact version the root `package.json` pins for package `name`, read through the default catalog of `pnpm-workspace.yaml` when the pin says `catalog:` or `catalog:default`. No whitespace, and no leading `-`.",
+            "type": "string",
+            "pattern": "^[^\\s-]\\S*$"
+          },
+          "only": {
+            "description": "Paths the sparse checkout holds beside the repository's top-level files, relative to the clone and inside it; a directory ends in `/`. Absent, the whole tree is checked out. Present, it names at least one path, and a path the ref's tree lacks fails the Reference.",
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string",
+              "pattern": "^(?!/)(?!(?:.*/)?\\.\\.(?:/|$)).+$"
+            }
+          },
+          "skip": {
+            "description": "Paths the sparse checkout leaves out, relative to the clone and inside it. Empty or absent, nothing is left out. With `only`, each lies inside one of its paths, which this schema cannot say and the Sync refuses.",
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^(?!/)(?!(?:.*/)?\\.\\.(?:/|$)).+$"
+            }
+          },
+          "what": {
+            "description": "What the Reference is.",
+            "type": "string",
+            "minLength": 1
+          },
+          "when": {
+            "description": "When an agent reaches for it.",
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "required": ["dir", "repository", "ref", "what", "when"],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": ["version", "references"],
+  "additionalProperties": false
 }

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];
+}