dw-sdlc 0.20.0 → 0.21.0

package/README.md

@@ -65,19 +65,19 @@ line; a `gate.checks.run` entry takes a `hint` beside `name` and `command`.
 Under `gate.checks`, a Check is `true` for its defaults, an object of its options, or `false`. The
 schema's description of each one names its options and defaults.
 
-| Check                | fails                                                                       | reads first               |
-| -------------------- | --------------------------------------------------------------------------- | ------------------------- |
-| `markdown-refs`      | a relative link or image whose path or heading anchor does not resolve      | nothing                   |
-| `temporal-language`  | a changelog phrase in a durable document, outside code                      | nothing                   |
-| `comment-budget`     | a comment block over 3 lines of prose in JS, TS or shell                    | nothing                   |
-| `disable-directives` | a linter or type-checker disable comment with no reason                     | nothing                   |
-| `agents-map`         | an `AGENTS.md` over budget, missing the Gate command or pointing at nothing | `AGENTS.md`               |
-| `primitives`         | a catalogue entry out of step with the tree, or a file no entry owns        | `.ai/primitives.json`     |
-| `routed-docs`        | a document under `docs/` no Task Router row or Primitive leads to           | the map, the catalogue    |
-| `markdown-budget`    | a markdown file over the byte budget of its glob                            | the files its globs match |
-| `decision-records`   | a decision record misnamed, misnumbered or without a valid status           | a records directory       |
-| `file-size-ratchet`  | a code file over its line limit that the baseline does not allow            | its baseline              |
-| `skill-sections`     | a README section a skill copies that differs from its source                | the catalogue             |
+| Check                | fails                                                                          | reads first               |
+| -------------------- | ------------------------------------------------------------------------------ | ------------------------- |
+| `markdown-refs`      | a relative link, image or repository URL whose path or anchor does not resolve | nothing                   |
+| `temporal-language`  | a changelog phrase in a durable document, outside code                         | nothing                   |
+| `comment-budget`     | a comment block over 3 lines of prose in JS, TS or shell                       | nothing                   |
+| `disable-directives` | a linter or type-checker disable comment with no reason                        | nothing                   |
+| `agents-map`         | an `AGENTS.md` over budget, missing the Gate command or pointing at nothing    | `AGENTS.md`               |
+| `primitives`         | a catalogue entry out of step with the tree, or a file no entry owns           | `.ai/primitives.json`     |
+| `routed-docs`        | a document under `docs/` no Task Router row or Primitive leads to              | the map, the catalogue    |
+| `markdown-budget`    | a markdown file over the byte budget of its glob                               | the files its globs match |
+| `decision-records`   | a decision record misnamed, misnumbered or without a valid status              | a records directory       |
+| `file-size-ratchet`  | a code file over its line limit that the baseline does not allow               | its baseline              |
+| `skill-sections`     | a README section a skill copies that differs from its source                   | the catalogue             |
 
 Each Check's options and defaults:
 [its description in the schema](https://github.com/dominikwozniak/dw-sdlc/blob/main/packages/dw-sdlc/config/agentic.config.schema.json).

package/config/agentic.config.schema.json

@@ -264,7 +264,7 @@
               "additionalProperties": false
             },
             "markdown-refs": {
-              "description": "Every relative link and image in the markdown files resolves: its path to a file or directory git tracks or would track, its heading anchor to a heading of the markdown file it names, and `#anchor` alone to a heading of its own file. A link with a scheme, such as `https:`, and a link inside code are not judged.",
+              "description": "Every relative link and image in the markdown files resolves: its path to a file or directory git tracks or would track, its heading anchor to a heading of the markdown file it names, and `#anchor` alone to a heading of its own file. A URL into the GitHub repository `origin` names, at its default branch (the one `origin/HEAD` names, else `main`), as a `blob`, `tree` or raw file URL, resolves the same way, inside code too. Any other link with a scheme, such as `https:`, and a relative link inside code are not judged.",
               "type": ["boolean", "object"],
               "properties": {
                 "files": {

package/dist/checks/markdown-refs.js

@@ -1,9 +1,10 @@
-// `markdown-refs`: every relative link and image in the markdown resolves, its path to a file or a
-// directory git tracks or would track and its heading anchor to a heading of the file it names, so a
-// link to an ignored file or to another case of a file's name fails here as it fails in CI.
+// `markdown-refs`: every relative link and image, and every URL into origin's default branch even in
+// code, resolves to a file or directory git tracks or would track and its anchor to a heading there, so
+// a link to an ignored file or to another case of a file's name fails here as it fails in CI.
 import { readFileSync } from "node:fs";
 import { join, posix } from "node:path";
 import { anchorsOf, links } from "../markdown.js";
+import { asked } from "../working-tree.js";
 import { directoriesOf, matching, treeFiles } from "./tree.js";
 const REMEDIES = {
     path: "fix the path or drop the link",
@@ -12,6 +13,51 @@ const REMEDIES = {
 };
 /** A target with a scheme, such as `https:` or `mailto:`, or a host: no file of the tree answers it. */
 const EXTERNAL = /^([a-z][a-z\d+.-]*:|\/\/)/i;
+/** `owner/name` in the URL of a GitHub remote, over SSH or HTTPS, with a user, a token or a port, `.git` or not. */
+const GITHUB_REMOTE = /^(?:git@github\.com:|(?:ssh|https?):\/\/(?:[^@/]+@)?github\.com(?::\d+)?\/)([^/]+\/[^/]+?)(?:\.git)?\/?$/i;
+const REMOTE_HEAD = "refs/remotes/origin/HEAD";
+/** The branch a URL is judged at when origin/HEAD names none, as in a CI checkout. */
+const FALLBACK_BRANCH = "main";
+/** A URL into a GitHub repository: a file page, a directory page or a raw file, up to a space, a quote or a bracket. */
+const REPOSITORY_URL = /https:\/\/(?:github\.com\/[^/\s]+\/[^/\s]+\/(?:blob|tree)|raw\.githubusercontent\.com\/[^/\s]+\/[^/\s]+)\/[^\s"'`<>()[\]]+/gi;
+/** Closing punctuation and emphasis markers after a URL, which GitHub leaves out of it. */
+const TRAILING = /[.,;:!?*_~]+$/;
+/** A GitHub anchor to a line or a range of lines, which names no heading. */
+const LINE_ANCHOR = /#L\d+(C\d+)?(-L\d+(C\d+)?)?$/;
+/** The prefixes of URLs into origin's default branch; none when origin is not on GitHub. */
+function prefixesOf(root) {
+    const slug = GITHUB_REMOTE.exec(asked(root, ["remote", "get-url", "origin"]) ?? "")?.[1]?.toLowerCase();
+    if (slug === undefined) {
+        return [];
+    }
+    const head = asked(root, ["symbolic-ref", "-q", REMOTE_HEAD])?.replace(/^refs\/remotes\/origin\//, "");
+    const branch = head === undefined || head === "" ? FALLBACK_BRANCH : head;
+    return [
+        `https://github.com/${slug}/blob/`,
+        `https://github.com/${slug}/tree/`,
+        `https://raw.githubusercontent.com/${slug}/`
+    ].map((repository) => ({ repository, branch }));
+}
+/** The path from the root `url` names under one of `prefixes`, its line anchor dropped; undefined under none. */
+function pathOf(url, prefixes) {
+    const prefix = prefixes.find(({ repository, branch }) => url.toLowerCase().startsWith(repository) && url.slice(repository.length).startsWith(`${branch}/`));
+    return prefix === undefined
+        ? undefined
+        : `/${url.slice(prefix.repository.length + prefix.branch.length + 1).replace(LINE_ANCHOR, "")}`;
+}
+/** Every URL of `text` into the repository's default branch, a fenced line's included, once per line. */
+function repositoryLinks(text, prefixes) {
+    if (prefixes.length === 0) {
+        return [];
+    }
+    return text.split("\n").flatMap((line, index) => {
+        const urls = new Set(Array.from(line.matchAll(REPOSITORY_URL), ([url]) => url.replace(TRAILING, "")));
+        return [...urls].flatMap((url) => {
+            const target = pathOf(url, prefixes);
+            return target === undefined ? [] : [{ target, line: index + 1, shown: url }];
+        });
+    });
+}
 function decode(text) {
     try {
         return decodeURIComponent(text);
@@ -30,13 +76,13 @@ function resolve(file, path) {
     return normal.length > 1 ? normal.replace(/\/$/, "") : normal;
 }
 /** What is wrong with one link of `file`: a path out of the repository or not in it, or an anchor with no heading. */
-function judge(repository, file, { target, line }) {
+function judge(repository, file, { target, line, shown = target }) {
     if (EXTERNAL.test(target)) {
         return [];
     }
     const [beforeAnchor = "", anchor = ""] = target.split("#", 2);
     const resolved = resolve(file, decode(beforeAnchor.split("?", 1)[0] ?? ""));
-    const quoted = JSON.stringify(target);
+    const quoted = JSON.stringify(shown);
     if (resolved === ".." || resolved.startsWith("../")) {
         return [{ file, line, message: `links to ${quoted}, which is outside the repository`, remedy: REMEDIES.outside }];
     }
@@ -53,8 +99,14 @@ function judge(repository, file, { target, line }) {
 function run(root, { files, exempt }) {
     const tree = treeFiles(root);
     const known = new Set(tree);
+    const prefixes = prefixesOf(root);
     const repository = { root, files: known, directories: directoriesOf(known), anchors: new Map() };
-    return matching(root, tree, files, exempt).flatMap((file) => links(readFileSync(join(root, file), "utf8")).flatMap((link) => judge(repository, file, link)));
+    return matching(root, tree, files, exempt).flatMap((file) => {
+        const text = readFileSync(join(root, file), "utf8");
+        return [...links(text), ...repositoryLinks(text, prefixes)]
+            .toSorted((left, right) => left.line - right.line)
+            .flatMap((link) => judge(repository, file, link));
+    });
 }
 export const markdownRefs = {
     name: "markdown-refs",

package/dist/commands/pr-ship.js

@@ -28,7 +28,10 @@ file outside lockfiles with no patch, full; the rest light. After a push it name
 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.
+--review names a depth for the call; a read mark never carries. A read mark no later commit answers,
+on the head or before only merges or a rebase, is named under details.open: the Review then reads
+the whole pull request, and nothing carries over it. After a merge or a rebase, details.paths names
+the files whose own change moved, the only ones the Review reads.
 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

package/dist/pr/decide.js

@@ -249,7 +249,8 @@ const ROWS = [
                     // The agent may raise a routed depth to full, so auto names the command at any depth.
                     ...(depth === "full" || source === "auto" ? { reviewCommand: policy.reviewCommand } : {}),
                     ...after,
-                    ...(pr.scope === null ? {} : { paths: pr.scope })
+                    ...(pr.scope === null ? {} : { paths: pr.scope }),
+                    ...(pr.open === null ? {} : { open: pr.open })
                 }
             };
         }

package/dist/pr/delta.d.ts

@@ -1,4 +1,4 @@
-import { type ChangedFile } from "./state.ts";
+import type { ChangedFile } from "./state.ts";
 /** The gh arguments of the compare from `from` to `commit`, the files on its one page. */
 export declare function compareArgs(repo: string, from: string, commit: string): string[];
 /** How many commits of the compare's base its head lacks: 0 when the head carries all of it. */

package/dist/pr/delta.js

@@ -1,7 +1,7 @@
 // GitHub's compare of two commits, read two ways: whether a head carries the Review of an earlier commit,
 // the pull request's own changes from the base the same at both, since a merge of the base in adds none
 // of its own; and the files a Review would read, with their changed lines, for `pr.review: auto`.
-import { fieldOf, integer, object, ReplyError, rootOf, shown, string } from "./state.js";
+import { fieldOf, integer, object, ReplyError, rootOf, shown, string } from "./reply.js";
 /** GitHub's compare lists at most this many files; one that lists as many may hold back the rest. */
 const FILE_LIMIT = 300;
 /** The gh arguments of the compare from `from` to `commit`, the files on its one page. */

package/dist/pr/read.js

@@ -3,7 +3,8 @@
 // and that size its changes, and beside them the default branch and the clock the decision reads.
 import { exec, TimedOut } from "../exec.js";
 import { behindOf, changedOf, changesOf, compareArgs, sameChanges } from "./delta.js";
-import { awaitsReview, parseDefaultBranch, parsePr, parseView, QUERY, ReplyError } from "./state.js";
+import { ReplyError } from "./reply.js";
+import { awaitsReview, parseDefaultBranch, parsePr, parseView, QUERY } from "./state.js";
 /** What stops a pr command or recap before it answers: exit 2, the problem and its remedy on one line. */
 export class CannotRun extends Error {
     remedy;
@@ -192,14 +193,39 @@ function ownChanges(pr, commit) {
     const reply = compared(pr, pr.baseOid, commit, `the compare with ${commit.slice(0, 7)}`);
     return parseOrCannotRun(() => changesOf(reply));
 }
+/** `pr` and, with no read in its history, the newest commit force pushes left behind that a Review read. */
+function withRewritten(pr, rewritten) {
+    const [newest] = rewritten;
+    if (newest === undefined || pr.lastRead !== null || pr.open !== null) {
+        return pr;
+    }
+    return { ...pr, lastRead: { ...newest, baseOnly: true, baseMoved: true } };
+}
+/**
+ * `pr` with its last read mark `open` when a merge of the base or a rebase came after it and no fix
+ * shows: the own changes are as it read them, or a compare cannot show them whole (ADR 0023). The
+ * compares run only when a Review awaits the head.
+ */
+function withOpen(pr) {
+    const last = pr.lastRead;
+    if (last === null || last.clean || !last.baseMoved || pr.state !== "OPEN" || !awaitsReview(pr)) {
+        return pr;
+    }
+    const atRead = ownChanges(pr, last.commit);
+    const atHead = ownChanges(pr, pr.head);
+    if (atRead !== null && atHead !== null && !sameChanges(atRead, atHead)) {
+        return pr;
+    }
+    return { ...pr, lastRead: null, open: last.commit };
+}
 /**
  * `pr` and whether its head carries the success of the last commit a Review read: a clean read, only
- * merges since it, and the same own changes at both. A read mark never carries. The compares run only
- * when a Review awaits the head.
+ * the base's changes since it, and the same own changes at both. A read mark never carries. The
+ * compares run only when a Review awaits the head.
  */
 function withCarried(pr) {
     const last = pr.lastRead;
-    if (last === null || !last.clean || !last.mergesOnly || pr.state !== "OPEN" || !awaitsReview(pr)) {
+    if (last === null || !last.clean || !last.baseOnly || pr.state !== "OPEN" || !awaitsReview(pr)) {
         return { ...pr, carried: false };
     }
     return { ...pr, carried: sameChanges(ownChanges(pr, last.commit), ownChanges(pr, pr.head)) };
@@ -226,15 +252,15 @@ function ownScope(pr, from) {
     return [...new Set(names)].toSorted();
 }
 /**
- * `pr` and, when a Review awaits a head that carries none, its `scope` after a merge of the base, and
- * when `sized`, the files the Review would read: the compare from the last commit a Review read, else
- * from the base, to the head, kept to the scope when there is one.
+ * `pr` and, when a Review awaits a head that carries none, its `scope` after a merge of the base or a
+ * rebase, and when `sized`, the files the Review would read: the compare from the last commit a Review
+ * read, else from the base, to the head, kept to the scope when there is one.
  */
 function withChanged(pr, sized) {
     if (pr.carried || pr.state !== "OPEN" || !awaitsReview(pr)) {
         return { ...pr, changed: null, scope: null };
     }
-    const scope = pr.lastRead?.merges === true ? ownScope(pr, pr.lastRead.commit) : null;
+    const scope = pr.lastRead?.baseMoved === true ? ownScope(pr, pr.lastRead.commit) : null;
     if (!sized) {
         return { ...pr, changed: null, scope };
     }
@@ -267,6 +293,6 @@ function query({ repo, number }, sized) {
         const remedy = problem.startsWith("Could not resolve to a") ? REMEDIES.target : REMEDIES.read;
         throw new CannotRun(`${repo}#${number}: ${problem}`, remedy);
     }
-    const parsed = parseOrCannotRun(() => parsePr(reply.stdout, repo));
-    return withChanged(withCarried(parsed), sized);
+    const { pr, rewritten } = parseOrCannotRun(() => parsePr(reply.stdout, repo));
+    return withChanged(withCarried(withOpen(withRewritten(pr, rewritten))), sized);
 }

package/dist/pr/reply.d.ts

@@ -0,0 +1,34 @@
+/** A reply that is not the shape the query asks for; the message names the field. */
+export declare class ReplyError extends Error {
+}
+/** A JSON object of the reply and the path that reached it, as `data.repository.pullRequest`. */
+export type Node = {
+    value: Record<string, unknown>;
+    at: string;
+};
+export declare function shown(value: unknown): string;
+/** The JSON object `reply` holds, the root its fields' paths start from; `what` names it in a problem. */
+export declare function rootOf(reply: string, what: string): Node;
+export declare function fieldOf(node: Node, key: string): {
+    value: unknown;
+    at: string;
+};
+export declare function object(value: unknown, at: string): Node;
+export declare function child(node: Node, key: string): Node;
+export declare function childOrNull(node: Node, key: string): Node | null;
+export declare function string(node: Node, key: string): string;
+export declare function stringOrNull(node: Node, key: string): string | null;
+export declare function boolean(node: Node, key: string): boolean;
+export declare function integer(node: Node, key: string): number;
+export declare function integerOrNull(node: Node, key: string): number | null;
+/** A time as GitHub writes it, ISO 8601; the decision reads it as one. */
+export declare function time(node: Node, key: string): string;
+export declare function timeOrNull(node: Node, key: string): string | null;
+export declare function isOneOf<T extends string>(values: readonly T[], value: unknown): value is T;
+export declare function oneOf<T extends string>(node: Node, key: string, values: readonly T[]): T;
+/** The objects of a connection's `nodes`. */
+export declare function nodes(node: Node, key: string): Node[];
+/** Whether a connection has more nodes after the ones the reply holds. */
+export declare function hasMore(node: Node, key: string): boolean;
+/** The first object of a connection's `nodes`; an empty connection does not parse. */
+export declare function firstNode(node: Node, key: string): Node;

package/dist/pr/reply.js

@@ -0,0 +1,114 @@
+// The reply of a gh call read as JSON: each field checked as the type the reader asks for, and a
+// reply that fails names the field by its path.
+/** 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);
+}
+export function shown(value) {
+    return value === undefined ? "missing" : JSON.stringify(value);
+}
+/** The JSON object `reply` holds, the root its fields' paths start from; `what` names it in a problem. */
+export 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: "" };
+}
+export function fieldOf(node, key) {
+    return { value: node.value[key], at: node.at === "" ? key : `${node.at}.${key}` };
+}
+export function object(value, at) {
+    if (!isRecord(value)) {
+        throw new ReplyError(`${at} is ${shown(value)}, not an object`);
+    }
+    return { value, at };
+}
+export function child(node, key) {
+    const { value, at } = fieldOf(node, key);
+    return object(value, at);
+}
+export function childOrNull(node, key) {
+    const { value, at } = fieldOf(node, key);
+    return value === null ? null : object(value, at);
+}
+export function string(node, key) {
+    const { value, at } = fieldOf(node, key);
+    if (typeof value !== "string") {
+        throw new ReplyError(`${at} is ${shown(value)}, not a string`);
+    }
+    return value;
+}
+export function stringOrNull(node, key) {
+    return node.value[key] === null ? null : string(node, key);
+}
+export 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;
+}
+export function integer(node, key) {
+    const { value, at } = fieldOf(node, key);
+    if (typeof value !== "number" || !Number.isInteger(value)) {
+        throw new ReplyError(`${at} is ${shown(value)}, not an integer`);
+    }
+    return value;
+}
+export 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. */
+export 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;
+}
+export function timeOrNull(node, key) {
+    return node.value[key] === null ? null : time(node, key);
+}
+export function isOneOf(values, value) {
+    return values.some((known) => known === value);
+}
+export 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`. */
+export 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}]`));
+}
+/** Whether a connection has more nodes after the ones the reply holds. */
+export function hasMore(node, key) {
+    return boolean(child(child(node, key), "pageInfo"), "hasNextPage");
+}
+/** The first object of a connection's `nodes`; an empty connection does not parse. */
+export function firstNode(node, key) {
+    const [first] = nodes(node, key);
+    if (first === undefined) {
+        throw new ReplyError(`${node.at}.${key}.nodes is empty`);
+    }
+    return first;
+}

package/dist/pr/state.d.ts

@@ -10,7 +10,7 @@ export declare const MARK_STATE = "failure";
 export declare const READ_MARK = "read, findings open";
 /** How the description of the success the dev's `--accept` posts reads: the head, taken with its Findings open. */
 export declare const ACCEPTED = "accepted by the dev, findings open";
-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 headRef { name } isCrossRepository baseRefName\n      baseRefOid baseRef { target { oid } } viewerDidAuthor mergeCommit { oid }\n      ready: timelineItems(last: 1, itemTypes: [READY_FOR_REVIEW_EVENT]) { nodes { ... on ReadyForReviewEvent { createdAt } } }\n      latestReviews(first: 100) { nodes { state author { login } commit { oid } } }\n      reviewThreads(first: 100) { pageInfo { hasNextPage } 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) { pageInfo { hasNextPage } nodes {\n          ... on CheckRun { name status conclusion detailsUrl startedAt isRequired(pullRequestNumber: $number) }\n          ... on StatusContext { context state targetUrl createdAt isRequired(pullRequestNumber: $number) } } } } } } }\n      history: commits(last: 100) { nodes { commit { oid parents { totalCount } status { context(name: \"dw-sdlc/review\") { state description } } } } }\n    }\n  }\n}";
+export 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 headRef { name } isCrossRepository baseRefName\n      baseRefOid baseRef { target { oid } } viewerDidAuthor mergeCommit { oid }\n      ready: timelineItems(last: 1, itemTypes: [READY_FOR_REVIEW_EVENT]) { nodes { ... on ReadyForReviewEvent { createdAt } } }\n      latestReviews(first: 100) { nodes { state author { login } commit { oid } } }\n      reviewThreads(first: 100) { pageInfo { hasNextPage } 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) { pageInfo { hasNextPage } nodes {\n          ... on CheckRun { name status conclusion detailsUrl startedAt isRequired(pullRequestNumber: $number) }\n          ... on StatusContext { context state targetUrl createdAt isRequired(pullRequestNumber: $number) } } } } } } }\n      history: commits(last: 100) { nodes { commit { oid parents { totalCount } status { context(name: \"dw-sdlc/review\") { state description } } } } }\n      rewritten: timelineItems(last: 20, itemTypes: [HEAD_REF_FORCE_PUSHED_EVENT]) { nodes { ... on HeadRefForcePushedEvent {\n        beforeCommit { oid history(first: 20) { nodes { oid parents(first: 1) { nodes { oid } }\n          status { context(name: \"dw-sdlc/review\") { state description } } } } } } } }\n    }\n  }\n}";
 export type Bucket = "pass" | "fail" | "pending" | "skipping";
 export type CiCheck = {
     name: string;
@@ -76,10 +76,19 @@ export type PrState = {
     commits: string[];
     /**
      * The last commit before the head a Review read, of the last 100: a review success not posted under
-     * off, or a read mark.
+     * off, or a read mark. With none there, a commit force pushes left behind that a Review read.
      */
     lastRead: LastRead | null;
-    /** The read marks since the last review success of any kind, of the last 100 commits. */
+    /**
+     * A read mark whose Findings no later commit answers: the head's own, or one a merge of the base or a
+     * rebase came after with no fix showing. Then `lastRead` is null, the Review reads the whole pull
+     * request, and nothing carries (ADR 0023).
+     */
+    open: string | null;
+    /**
+     * The read marks since the last review success of any kind, of the last 100 commits, then, when they
+     * hold no success, of the commits force pushes left behind.
+     */
     marks: ReadMarks;
     /** Whether the head carries the success of `lastRead`: the read decides it from two compares. */
     carried: boolean;
@@ -103,15 +112,19 @@ export type ChangedFile = {
     previous: string | null;
     lines: number | null;
 };
-/**
- * A commit a Review read; `clean` when that Review left a success on it, not a read mark; and whether
- * every commit after it, the head included, is a merge.
- */
-export type LastRead = {
+/** A commit a Review read; `clean` when that Review left a success on it, not a read mark. */
+export type Read = {
     commit: string;
     clean: boolean;
-    mergesOnly: boolean;
-    merges: boolean;
+};
+/**
+ * A commit a Review read; `baseOnly` when every change after it is the base's, the head included: only
+ * merges of the base, or a rebase past no other read; `baseMoved` when a merge of the base or a rebase
+ * came after it.
+ */
+export type LastRead = Read & {
+    baseOnly: boolean;
+    baseMoved: boolean;
 };
 /**
  * The Reviews that left a Finding open since the last review success, a success under off and the dev's
@@ -122,24 +135,6 @@ export type ReadMarks = {
     count: number;
     since: string | null;
 };
-/** A reply that is not the shape the query asks for; the message names the field. */
-export declare class ReplyError extends Error {
-}
-/** A JSON object of the reply and the path that reached it, as `data.repository.pullRequest`. */
-export type Node = {
-    value: Record<string, unknown>;
-    at: string;
-};
-export declare function shown(value: unknown): string;
-/** The JSON object `reply` holds, the root its fields' paths start from; `what` names it in a problem. */
-export declare function rootOf(reply: string, what: string): Node;
-export declare function fieldOf(node: Node, key: string): {
-    value: unknown;
-    at: string;
-};
-export declare function object(value: unknown, at: string): Node;
-export declare function string(node: Node, key: string): string;
-export declare function integer(node: Node, key: string): number;
 /** The viewer's own pull request without a review success on its head: the one a Review reads. */
 export declare function awaitsReview(pr: Pick<PrState, "viewerDidAuthor" | "checks">): boolean;
 /** The repository and number of the pull request whose URL `gh pr view --json url` printed. */
@@ -149,6 +144,15 @@ export declare function parseView(reply: string): {
 };
 /** The default branch of the repository whose `gh repo view --json defaultBranchRef` printed `reply`. */
 export declare function parseDefaultBranch(reply: string): string;
-/** 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): Omit<PrState, "carried" | "changed" | "scope">;
+/** The state as the reply holds it, before the compares decide what the head carries and a Review reads. */
+export type Parsed = Omit<PrState, "carried" | "changed" | "scope">;
+/**
+ * The state of the pull request in `reply`, the text `gh api graphql` printed for QUERY on `repo`, and
+ * `rewritten`: the commits the last 20 force pushes left behind that a Review read, newest first, none the
+ * history still holds, where a Review's read stands once a rebase rewrote every commit it read.
+ */
+export declare function parsePr(reply: string, repo: string): {
+    pr: Parsed;
+    rewritten: Read[];
+};
 export {};

package/dist/pr/state.js

@@ -1,5 +1,6 @@
 // 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.
+import { boolean, child, childOrNull, firstNode, hasMore, integer, integerOrNull, nodes, oneOf, ReplyError, rootOf, string, stringOrNull, time, timeOrNull } from "./reply.js";
 /** The commit status a clean review of the head leaves on it. */
 export const REVIEW = "dw-sdlc/review";
 /** How the description of a success the script posts under off begins: no one read that head. */
@@ -15,6 +16,12 @@ export const ACCEPTED = "accepted by the dev, findings open";
 /** How many checks and review threads the one read holds; each list's `pageInfo` says when more follow. */
 const CHECKS_READ = 50;
 const THREADS_READ = 100;
+/**
+ * How many of the last force pushes the read holds, each with the head it left behind, and how many
+ * commits of that head's history.
+ */
+const FORCE_PUSHES_READ = 20;
+const LEFT_BEHIND_READ = 20;
 export const QUERY = `query($owner: String!, $name: String!, $number: Int!) {
   repository(owner: $owner, name: $name) {
     pullRequest(number: $number) {
@@ -30,124 +37,15 @@ export const QUERY = `query($owner: String!, $name: String!, $number: Int!) {
           ... on CheckRun { name status conclusion detailsUrl startedAt isRequired(pullRequestNumber: $number) }
           ... on StatusContext { context state targetUrl createdAt isRequired(pullRequestNumber: $number) } } } } } } }
       history: commits(last: 100) { nodes { commit { oid parents { totalCount } status { context(name: "${REVIEW}") { state description } } } } }
+      rewritten: timelineItems(last: ${FORCE_PUSHES_READ}, itemTypes: [HEAD_REF_FORCE_PUSHED_EVENT]) { nodes { ... on HeadRefForcePushedEvent {
+        beforeCommit { oid history(first: ${LEFT_BEHIND_READ}) { nodes { oid parents(first: 1) { nodes { oid } }
+          status { context(name: "${REVIEW}") { state description } } } } } } } }
     }
   }
 }`;
 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);
-}
-export function shown(value) {
-    return value === undefined ? "missing" : JSON.stringify(value);
-}
-/** The JSON object `reply` holds, the root its fields' paths start from; `what` names it in a problem. */
-export 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: "" };
-}
-export function fieldOf(node, key) {
-    return { value: node.value[key], at: node.at === "" ? key : `${node.at}.${key}` };
-}
-export 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);
-}
-export function string(node, key) {
-    const { value, at } = fieldOf(node, key);
-    if (typeof value !== "string") {
-        throw new ReplyError(`${at} is ${shown(value)}, not a string`);
-    }
-    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;
-}
-export function integer(node, key) {
-    const { value, at } = fieldOf(node, key);
-    if (typeof value !== "number" || !Number.isInteger(value)) {
-        throw new ReplyError(`${at} is ${shown(value)}, not an integer`);
-    }
-    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}]`));
-}
-/** Whether a connection has more nodes after the ones the reply holds. */
-function hasMore(node, key) {
-    return boolean(child(child(node, key), "pageInfo"), "hasNextPage");
-}
-/** 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. */
@@ -237,29 +135,71 @@ function historyOf(pr) {
     });
 }
 /**
- * The last commit before `head` a Review read, the history oldest first. A read mark with only merges
- * after it is passed over: no fix answers its Findings yet, and a Review from it would read only the
- * base's changes, so the Review reads from the read before it and finds them again.
+ * The last commit before `head` a Review read, the history oldest first, or `open`: a read mark on the
+ * head, or with only merges after it. No fix answers its Findings, so no read stands in (ADR 0023).
  */
 function lastReadOf(history, head) {
-    const commits = history.map(({ oid, posted, merge }) => ({
-        oid,
-        read: oid === head || posted === "off" ? null : posted,
-        merge
-    }));
-    const mergesOnlyAfter = (index) => commits.slice(index + 1).every(({ merge }) => merge);
-    const index = commits.findLastIndex(({ read }, at) => read === "clean" || (read === "findings" && !mergesOnlyAfter(at)));
-    const last = commits[index];
+    if (history.some(({ oid, posted }) => oid === head && posted === "findings")) {
+        return { lastRead: null, open: head };
+    }
+    const index = history.findLastIndex(({ oid, posted }) => oid !== head && (posted === "clean" || posted === "findings"));
+    const last = history[index];
     if (last === undefined) {
-        return null;
+        return { lastRead: null, open: null };
+    }
+    const after = history.slice(index + 1);
+    const baseOnly = after.every(({ merge }) => merge);
+    if (last.posted === "findings" && baseOnly) {
+        return { lastRead: null, open: last.oid };
     }
     return {
-        commit: last.oid,
-        clean: last.read === "clean",
-        mergesOnly: mergesOnlyAfter(index),
-        merges: commits.slice(index + 1).some(({ merge }) => merge)
+        lastRead: {
+            commit: last.oid,
+            clean: last.posted === "clean",
+            baseOnly,
+            baseMoved: after.some(({ merge }) => merge)
+        },
+        open: null
     };
 }
+/**
+ * The commits a force push left behind: the head, then down its first parents within the history the
+ * read holds of it. A merge's first parent is the branch, so the walk stays off the base's side.
+ */
+function lineOf(left) {
+    const held = new Map(nodes(left, "history").map((commit) => [string(commit, "oid"), commit]));
+    const line = [];
+    let commit = held.get(string(left, "oid"));
+    while (commit !== undefined && line.length < held.size) {
+        line.push({ oid: string(commit, "oid"), posted: postedOn(commit) });
+        const [parent] = nodes(commit, "parents");
+        commit = parent === undefined ? undefined : held.get(string(parent, "oid"));
+    }
+    return line;
+}
+/**
+ * The commits the force pushes left behind, newest push first, each once and none the history still
+ * holds: a line stops where it meets the history, as under an amend, or a newer push's line.
+ */
+function forcePushedOf(pr, history) {
+    const seen = new Set(history.map(({ oid }) => oid));
+    const left = [];
+    for (const event of nodes(pr, "rewritten").toReversed()) {
+        const head = childOrNull(event, "beforeCommit");
+        for (const commit of head === null ? [] : lineOf(head)) {
+            if (seen.has(commit.oid)) {
+                break;
+            }
+            seen.add(commit.oid);
+            left.push(commit);
+        }
+    }
+    return left;
+}
+/** The commits of `forcePushed` a Review read; a success under off says no one read its commit. */
+function rewrittenOf(forcePushed) {
+    return forcePushed.flatMap(({ oid, posted }) => posted === "clean" || posted === "findings" ? [{ commit: oid, clean: posted === "clean" }] : []);
+}
 /**
  * Whether a non-merge commit follows `commit` in the history, oldest first, as `lastReadOf` judges a read
  * mark. A commit outside the history, after a force-push or past the last 100, is not answered.
@@ -281,10 +221,22 @@ function changeRequestsOf(pr, history) {
         };
     });
 }
-function readMarksOf(history) {
-    const success = history.findLastIndex(({ posted }) => posted === "clean" || posted === "off");
-    const count = history.slice(success + 1).filter(({ posted }) => posted === "findings").length;
-    return { count, since: history[success]?.oid ?? null };
+/**
+ * The read marks since the last success, the history's first; with no success there, the marks on the
+ * commits force pushes left behind go on the count, newest first, up to the first success among them.
+ */
+function readMarksOf(history, forcePushed) {
+    const isSuccess = ({ posted }) => posted === "clean" || posted === "off";
+    const findings = (commits) => commits.filter(({ posted }) => posted === "findings").length;
+    const success = history.findLastIndex(isSuccess);
+    const count = findings(history.slice(success + 1));
+    const lastSuccess = history[success];
+    if (lastSuccess !== undefined) {
+        return { count, since: lastSuccess.oid };
+    }
+    const pushedSuccess = forcePushed.findIndex(isSuccess);
+    const sincePushed = pushedSuccess < 0 ? forcePushed : forcePushed.slice(0, pushedSuccess);
+    return { count: count + findings(sincePushed), since: forcePushed[pushedSuccess]?.oid ?? null };
 }
 /** The repository and number of the pull request whose URL `gh pr view --json url` printed. */
 export function parseView(reply) {
@@ -299,7 +251,11 @@ export function parseView(reply) {
 export function parseDefaultBranch(reply) {
     return string(child(rootOf(reply, "the reply of gh repo view"), "defaultBranchRef"), "name");
 }
-/** The state of the pull request in `reply`, the text `gh api graphql` printed for QUERY on `repo`. */
+/**
+ * The state of the pull request in `reply`, the text `gh api graphql` printed for QUERY on `repo`, and
+ * `rewritten`: the commits the last 20 force pushes left behind that a Review read, newest first, none the
+ * history still holds, where a Review's read stands once a rebase rewrote every commit it read.
+ */
 export function parsePr(reply, repo) {
     const pr = child(child(child(rootOf(reply, "the reply"), "data"), "repository"), "pullRequest");
     const commit = child(firstNode(pr, "commits"), "commit");
@@ -309,7 +265,7 @@ export function parsePr(reply, repo) {
     const baseRef = childOrNull(pr, "baseRef");
     const history = historyOf(pr);
     const [ready] = nodes(pr, "ready");
-    return {
+    const state = {
         url: string(pr, "url"),
         repo,
         number: integer(pr, "number"),
@@ -338,7 +294,8 @@ export function parsePr(reply, repo) {
             ...(hasMore(pr, "reviewThreads") ? [`the first ${THREADS_READ} threads`] : [])
         ],
         commits: history.map(({ oid }) => oid),
-        lastRead: lastReadOf(history, head),
-        marks: readMarksOf(history)
+        ...lastReadOf(history, head)
     };
+    const forcePushed = forcePushedOf(pr, history);
+    return { pr: { ...state, marks: readMarksOf(history, forcePushed) }, rewritten: rewrittenOf(forcePushed) };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dw-sdlc",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "The Gate and the agentic config behind the sdlc Claude Code plugin: a bin with the Gate and its Checks, the setup, the doctor, the Sync of References, the Ship script that drives a pull request to merged, the Sweep, and Lead and Worker sessions in herdr; the resolver of a repository's .ai/agentic.config.json layers and its JSON Schema.",
   "license": "MIT",
   "repository": {