dw-sdlc 0.12.1 → 0.13.0

package/README.md

@@ -68,25 +68,34 @@ the `gh` account did not open is always the dev's to merge.
 ```
 
 `pr ship` answers `review`, its depth under `details`, 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. Under `off` the
-script posts that status itself, its description saying why, and goes on.
+`dw-sdlc/review`, which `dw-sdlc pr reviewed <n> --head <sha>` posts after a clean review. A Review
+that leaves a Finding open posts it with `--findings`, in state failure, "read, findings open": the
+read mark. After the next push, `details.since` names the last head a Review read, clean or marked,
+so the Review after a fix reads the fix alone. `pr reviewed` posts nothing and exits 2 once a push
+moved the head, so a new head needs a fresh review. Under `off` the script posts that status
+itself, its description saying why, and goes on.
+
+Three Reviews with no success between them end the loop: `pr ship` answers `park review-limit`
+instead of `review`, whose command, `dw-sdlc pr reviewed <n> -R <owner/name> --head <sha> --accept`,
+is the dev's. `--accept` posts the success described "accepted by the dev, findings open"; with
+`--findings` it exits 2. The limit is a constant, not a config key, and `--review <depth>` on a call
+buys one more Review past it.
 
 ## Commands
 
-| command            | what it does                                                                        |
-| ------------------ | ----------------------------------------------------------------------------------- |
-| `gate`             | the Steps of `gate.steps` in order, then every Check under `gate.checks`            |
-| `check <name>`     | one Check of the Gate by its name, without the Steps and the other Checks           |
-| `primitives`       | the Primitives that own each path, with their summaries and documents               |
-| `setup`            | this machine's local config layer, the git excludes and the permission rules        |
-| `doctor`           | one PASS / WARN / FAIL line per machine check the guardrails rely on                |
-| `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                       |
-| `recap`            | the facts a Recap rests on and whether the session can be closed                    |
+| command            | what it does                                                                               |
+| ------------------ | ------------------------------------------------------------------------------------------ |
+| `gate`             | the Steps of `gate.steps` in order, then every Check under `gate.checks`                   |
+| `check <name>`     | one Check of the Gate by its name, without the Steps and the other Checks                  |
+| `primitives`       | the Primitives that own each path, with their summaries and documents                      |
+| `setup`            | this machine's local config layer, the git excludes and the permission rules               |
+| `doctor`           | one PASS / WARN / FAIL line per machine check the guardrails rely on                       |
+| `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 Review pinned to the head it read, as a commit status: clean, Findings open, or accepted |
+| `recap`            | the facts a Recap rests on and whether the session can be closed                           |
 
 `dw-sdlc <command> --help` gives each one's options.
 

package/dist/cli.js

@@ -12,6 +12,7 @@ import * as recap from "./commands/recap.js";
 import * as referencesSetup from "./commands/references-setup.js";
 import * as referencesSync from "./commands/references-sync.js";
 import * as setup from "./commands/setup.js";
+import * as sweep from "./commands/sweep.js";
 import * as workerLs from "./commands/worker-ls.js";
 import * as workerReport from "./commands/worker-report.js";
 import * as workerStart from "./commands/worker-start.js";
@@ -27,6 +28,7 @@ const COMMANDS = new Map([
     ["pr ship", prShip],
     ["pr reviewed", prReviewed],
     ["recap", recap],
+    ["sweep", sweep],
     ["worker start", workerStart],
     ["worker ls", workerLs],
     ["worker report", workerReport]

package/dist/commands/gate.js

@@ -27,8 +27,9 @@ and edits made before the run never drift, and a Step a signal stopped is not co
 "allow" turns the watch off.
 
 SIGINT or SIGTERM sent while a command runs stops it and everything after it, and the report still
-prints: the stopped command's last lines, its failure line and the last line. A second signal, or one
-sent while the Checks the package ships run, ends the Gate at once.
+prints: the stopped command's last lines, its failure line and the last line. A command that SIGINT
+or SIGTERM ends stops everything after it the same way, as Ctrl-C reaches it and the Gate together. A
+second signal, or one sent while the Checks the package ships run, ends the Gate at once.
 
 --verbose passes each command's output through as it runs instead, under a line naming the command,
 and keeps no tail. --json prints the document alone; each Step and Check in it carries tail, the last

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

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

package/dist/commands/pr-reviewed.js

@@ -1,18 +1,29 @@
-// `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.
+// `dw-sdlc pr reviewed <n> --head <sha>`: pins a Review to the head it read, as the commit status
+// `dw-sdlc/review`: success for a clean one, --findings the read mark of one that left a Finding open,
+// --accept the dev's acceptance of a head as it stands, which the review-limit park names.
 import { parseArgs } from "node:util";
 import { REVIEW, REVIEW_STATE, reviewStatusArgs } from "../pr/decide.js";
 import { CannotRun, gh, namedProblem, read, said } from "../pr/read.js";
-export const summary = "pin a clean review to the head it read, as a commit status";
-const USAGE = `Usage: dw-sdlc pr reviewed <n> [-R owner/name] --head <sha> [--json]
+import { ACCEPTED, MARK_STATE, READ_MARK } from "../pr/state.js";
+export const summary = "pin a Review to the head it read, as a commit status";
+const USAGE = `Usage: dw-sdlc pr reviewed <n> [-R owner/name] --head <sha> [--findings | --accept] [--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.
+the commit status dw-sdlc/review in state success on it, the pull request's URL as its target: a
+clean Review of that head. --findings posts it in state failure, described "${READ_MARK}": the
+read mark of a Review that left a Finding open, from which pr ship reads the fix that follows.
+--accept posts it in state success, described "${ACCEPTED}": the dev takes the head as it stands, the
+command the park review-limit names; only the dev runs it. --findings and --accept together exit 2.
+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 DESCRIPTION = "a clean review of this head";
+/** What the status says: a clean Review, the read mark of one that left a Finding open, or the dev's acceptance. */
+const STATUS = {
+    clean: { state: REVIEW_STATE, description: "a clean review of this head" },
+    findings: { state: MARK_STATE, description: READ_MARK },
+    accept: { state: REVIEW_STATE, description: ACCEPTED }
+};
 function parseCli(argv) {
     try {
         const { values, positionals } = parseArgs({
@@ -22,7 +33,9 @@ function parseCli(argv) {
                 help: { type: "boolean", short: "h" },
                 json: { type: "boolean" },
                 repo: { type: "string", short: "R" },
-                head: { type: "string" }
+                head: { type: "string" },
+                findings: { type: "boolean" },
+                accept: { type: "boolean" }
             }
         });
         if (values.help === true) {
@@ -46,19 +59,24 @@ function parseCli(argv) {
         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 };
+        if (values.findings === true && values.accept === true) {
+            return { error: "--findings and --accept contradict: name one" };
+        }
+        const kind = values.findings === true ? "findings" : "clean";
+        const status = STATUS[values.accept === true ? "accept" : kind];
+        return { json: values.json === true, number: Number(number), repo, head, status };
     }
     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 }) {
+function post({ number, repo, head, status }) {
     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");
     }
-    const posted = gh(reviewStatusArgs(pr, DESCRIPTION));
+    const posted = gh(reviewStatusArgs(pr, status.description, status.state));
     if (posted.status !== 0) {
         throw new CannotRun(`${pr.repo}#${number}: posting ${REVIEW} failed: ${said(posted.stderr)}`, `check that gh's token may write commit statuses to ${pr.repo}, then call again`);
     }
@@ -84,9 +102,10 @@ export function run(argv) {
         throw error;
     }
     const { head } = cli;
+    const { state } = cli.status;
     const answer = cli.json
-        ? JSON.stringify({ head, context: REVIEW, state: REVIEW_STATE }, null, 2)
-        : `posted ${REVIEW} ${REVIEW_STATE} on ${head}`;
+        ? JSON.stringify({ head, context: REVIEW, state }, null, 2)
+        : `posted ${REVIEW} ${state} on ${head}`;
     process.stdout.write(`${answer}\n`);
     return 0;
 }

package/dist/commands/pr-ship.js

@@ -4,12 +4,15 @@
 import { parseArgs } from "node:util";
 import { repositoryRoot, resolveConfig, REVIEW_DEPTHS } from "../agentic-config.js";
 import { decide, declaredPolicy, devCommand, hostArgs, isScriptAction, lineOf, readyToMerge, REVIEW, shellLine } from "../pr/decide.js";
-import { CannotRun, carriesBase, gh, namedProblem, now, read, readAgain, said, withBehind } from "../pr/read.js";
+import { CannotRun, carriesBase, gh, namedProblem, nameItRemedy, now, read, readAgain, readBranch, said, withBehind } from "../pr/read.js";
+import { holds, renamedUpstream } from "../pr/upstream.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|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.
+A branch pushed under another name has an upstream of that name. Where gh resolves no pull request
+for it, the script asks for the upstream's, and reads it only when its commits hold HEAD.
 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;
@@ -23,9 +26,10 @@ why. Under auto, the default, the script routes the depth from the changes the R
 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.
+the last commit a Review read under details.since, where the Review reads from and auto routes from:
+one with a ${REVIEW} success not posted under off, or the read mark pr reviewed --findings
+posts. It carries a success over a head whose only commits since are merges of the base, unless
+--review names a depth for the call; a read mark never carries.
 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
@@ -138,14 +142,36 @@ function handedOver(pr, policy, answer, action, reason) {
     }
     return { ...answer, status: "park", actor: "dev", reason, command: devCommand(pr, action, policy) };
 }
+/**
+ * The pull request the call names, else the current branch's as `gh pr view` resolves it. Where gh finds
+ * none for a branch whose upstream has another name, the one of that name, taken only when its commits
+ * hold the local head: a branch started from another tracks that branch until its first push.
+ */
+function readTarget(cli, root, sized) {
+    const renamed = cli.number === undefined && cli.repo === undefined ? renamedUpstream(root) : undefined;
+    if (renamed === undefined) {
+        return read(cli, "pr ship", sized);
+    }
+    const { branch, head, upstream } = renamed;
+    const found = readBranch(sized, upstream);
+    const upstreamNamed = `${upstream}, the name its upstream gives`;
+    if (found === null) {
+        throw new CannotRun(`gh pr view found no pull request for ${branch}, nor for ${upstreamNamed}`, nameItRemedy("pr ship"));
+    }
+    if (found.byUpstream && !holds(found.pr, head)) {
+        const lacks = `${found.pr.url}, found by ${upstreamNamed}, lacks HEAD ${head.slice(0, 7)}`;
+        throw new CannotRun(lacks, `push HEAD if it is this branch's pull request, else ${nameItRemedy("pr ship")}`);
+    }
+    return found.pr;
+}
 /**
  * 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, policy) {
+function ship(cli, root, policy) {
     // Only pr.review auto routes the depth from the changes, so only it reads them.
     const sized = policy.review.depth === "auto";
-    let pr = withBehind(read(cli, "pr ship", sized));
+    let pr = withBehind(readTarget(cli, root, sized));
     const performed = [];
     // The head each Action ran on.
     const postedOn = new Map();
@@ -206,7 +232,8 @@ export function run(argv) {
         return 0;
     }
     // An invalid config layer resolves to ask and full, like every other strictest setting.
-    const declared = resolveConfig(repositoryRoot(process.cwd())).config.pr;
+    const root = repositoryRoot(process.cwd());
+    const declared = resolveConfig(root).config.pr;
     const policy = {
         ...declaredPolicy(declared),
         ...(cli.merge ? { merge: "auto" } : {}),
@@ -214,7 +241,7 @@ export function run(argv) {
     };
     let shipped;
     try {
-        shipped = ship(cli, policy);
+        shipped = ship(cli, root, policy);
     }
     catch (error) {
         if (error instanceof CannotRun) {

package/dist/commands/recap.js

@@ -6,8 +6,9 @@ import { parseArgs } from "node:util";
 import { findRepository, mainCheckout, resolveConfig } from "../agentic-config.js";
 import { decide, declaredPolicy, labelOf, lineOf } from "../pr/decide.js";
 import { CannotRun, defaultBranch, now, readBranch } from "../pr/read.js";
+import { holds, upstreamName } from "../pr/upstream.js";
 import { isLive, Refusal, workersOf, workingFolders } from "../worker/herdr.js";
-import { git } from "../working-tree.js";
+import { asked, git } from "../working-tree.js";
 export const summary = "the facts a Recap rests on and whether the session can be closed";
 const USAGE = `Usage: dw-sdlc recap [--json]
 
@@ -49,11 +50,6 @@ function must(root, args) {
     }
     return result.out;
 }
-/** `git <args>` at `root`, or undefined when it exits non-zero as a question answered no. */
-function asked(root, args) {
-    const result = git(root, args);
-    return "out" in result ? result.out : undefined;
-}
 function count(root, args) {
     return Number(must(root, ["rev-list", "--count", ...args]));
 }
@@ -119,23 +115,6 @@ function liveWorkers() {
 function workersText(workers) {
     return workers.map((worker) => `${worker.name} (${worker.status})`).join(", ");
 }
-/**
- * The remote branch name `branch` tracks, when it differs from `branch`. Read from the config, so it holds
- * after the remote deleted the branch.
- */
-function upstreamName(root, branch) {
-    const remote = asked(root, ["config", "--get", `branch.${branch}.remote`]);
-    const merge = asked(root, ["config", "--get", `branch.${branch}.merge`]);
-    if (remote === undefined || remote === "." || merge === undefined || !merge.startsWith("refs/heads/")) {
-        return undefined;
-    }
-    const name = merge.slice("refs/heads/".length);
-    return name === branch ? undefined : name;
-}
-/** Whether `pr`'s commits hold `head`, so the head is on GitHub whatever became of the upstream. */
-function holds(pr, head) {
-    return head !== null && pr.commits.includes(head);
-}
 /**
  * The current branch's pull request and the Action the Ship script's decision gives it, or null. The one
  * found by the upstream's name counts only when it holds the head: a branch started from another tracks

package/dist/commands/sweep.d.ts

@@ -0,0 +1,2 @@
+export declare const summary = "removes Landed branches and clean worktrees whose work has landed, names what it keeps";
+export declare function run(argv: string[]): number;