@codyswann/lisa 4.48.0 → 4.50.0

package/all/copy-overwrite/scripts/lisa-work-item.mjs

@@ -326,6 +326,12 @@ export function run(command, args, options = {}) {
     encoding: "utf8",
     env: options.env ?? process.env,
     input: options.input,
+    // Node's default is 1 MiB, and it is silent in exactly the wrong way: an
+    // over-large stdout sets `error` while leaving `status` null, so a caller
+    // passing `allowFailure` and testing `status !== 0` reads "the command
+    // returned nothing" when what happened is "the command was cut off". A
+    // caller that needs more says so; the default stays.
+    maxBuffer: options.maxBuffer,
     timeout: options.timeout ?? CHILD_TIMEOUT_MS,
     // SIGKILL, not the default SIGTERM. `timeout` sends killSignal and then
     // keeps waiting for the child to exit, so a child that traps or ignores
@@ -1837,11 +1843,74 @@ function carriesMarker(body) {
   return JSON.stringify(body ?? "").includes(MARKER);
 }
 
+/**
+ * Lisa's managed backlink comments, split by whether one is THIS pull request's.
+ *
+ * The whole defect this exists to remove is in the word "the": the writers used
+ * to look for *a* managed comment and rewrite it, so a work item with a second
+ * pull request against it had the first one's backlink silently repointed. The
+ * earlier pull request then failed a gate it had already passed, for a reason
+ * that was not in front of anyone looking at it, and the tool said `updated` —
+ * which reads as "added a link", not "took someone else's away".
+ *
+ * `[lisa-pr-link]` is a statement about a PAIR: *this pull request is linked to
+ * this item*. Storing a pair in a single slot means every new pair evicts the
+ * last, so the comment is keyed on the pull request it names and a work item
+ * carries one per pull request. Nothing here needs a migration: an item holding
+ * one legacy comment is simply an item where `mine` matches or it does not.
+ *
+ * This is deliberately NOT stack-awareness. A fix and its follow-up, a revert
+ * and its replacement, a pull request reopened or recreated against a different
+ * base, and work split across repositories all put two pull requests on one
+ * item, and none of them involve a stack.
+ * @param {readonly unknown[]} comments Comments as the provider returned them.
+ * @param {string} prUrl The pull request being discharged.
+ * @param {(comment: unknown) => unknown} bodyOf Reads a comment's body.
+ * @returns {{mine: unknown, others: number}} This PR's comment, and how many
+ *   managed comments belong to OTHER pull requests.
+ */
+function partitionBacklinks(comments, prUrl, bodyOf) {
+  const mine = [];
+  let others = 0;
+  for (const comment of comments) {
+    const body = bodyOf(comment);
+    if (!carriesMarker(body)) continue;
+    if (textContainsBacklink(body, prUrl)) mine.push(comment);
+    else others += 1;
+  }
+  return { mine: mine[0], others };
+}
+
+/**
+ * Say what a backlink write did, including what it did NOT touch.
+ *
+ * The sibling count is reported rather than left implicit because a tool that
+ * writes to a shared surface should say what else is on it. `updated` was the
+ * only signal the old writer gave before it evicted another pull request's
+ * link, and one word is not enough to distinguish "added" from "replaced".
+ * Exported so the wording can be asserted without a tracker.
+ * @param {{change: string, others: number}} outcome What the writer did.
+ * @param {string} ref Canonical work-item reference.
+ * @param {string} prUrl Pull request URL.
+ * @returns {string} The operator-readable report.
+ */
+export function backlinkReport(outcome, ref, prUrl) {
+  const line = `work-item backlink ${outcome.change} on ${ref}: ${MARKER} ${prUrl}`;
+  if (!outcome.others) return line;
+  const plural = outcome.others === 1 ? "" : "s";
+  return (
+    `${line}\n  ${outcome.others} other pull request${plural} already linked ` +
+    `to ${ref}, left untouched — an item carries one backlink per pull ` +
+    `request, and discharging one never removes another.`
+  );
+}
+
 /**
  * Establish the backlink on a GitHub issue.
  * @param {string} ref Canonical `owner/repo#number` reference.
  * @param {string} prUrl Pull request URL.
- * @returns {string} What changed: created, updated, or unchanged.
+ * @returns {{change: string, others: number}} What changed, and how many other
+ *   pull requests are linked to this item and were left alone.
  */
 function githubBacklink(ref, prUrl) {
   const [repository, number] = ref.split("#");
@@ -1856,18 +1925,26 @@ function githubBacklink(ref, prUrl) {
   );
   if (listing.status !== 0) throw githubFailure(listing, ref);
   const comments = safeJson(listing.stdout, `GitHub comments on ${ref}`);
-  const managed = (Array.isArray(comments) ? comments : []).find(comment =>
-    carriesMarker(comment?.body)
+  // This listing is the read-before-write, and it is fetched here rather than
+  // passed in for exactly that reason: the version you last wrote is not the
+  // version that is live on a surface other agents also comment on.
+  const { mine, others } = partitionBacklinks(
+    Array.isArray(comments) ? comments : [],
+    prUrl,
+    comment => comment?.body
   );
   const body = backlinkBody(prUrl);
-  if (managed && managed.body === body) return "unchanged";
-  const [method, endpoint] = managed
-    ? ["PATCH", `repos/${repository}/issues/comments/${managed.id}`]
+  if (mine && mine.body === body) return { change: "unchanged", others };
+  // PATCH only ever targets THIS pull request's own comment. A managed comment
+  // naming a different pull request is that pull request's proof of gate 5,
+  // and rewriting it would fail a gate that had already passed.
+  const [method, endpoint] = mine
+    ? ["PATCH", `repos/${repository}/issues/comments/${mine.id}`]
     : ["POST", `repos/${repository}/issues/${number}/comments`];
   run("gh", ["api", "--method", method, endpoint, "--field", `body=${body}`], {
     error: `could not write the backlink comment on ${ref}`,
   });
-  return managed ? "updated" : "created";
+  return { change: mine ? "updated" : "created", others };
 }
 
 /**
@@ -1906,7 +1983,8 @@ function linearGraphql(token, query, variables, context) {
  * @param {string} ref Canonical `KEY-123` identifier.
  * @param {string} prUrl Pull request URL.
  * @param {object} contract Resolved tracker contract.
- * @returns {string} What changed: created, updated, or unchanged.
+ * @returns {{change: string, others: number}} What changed, and how many other
+ *   pull requests are linked to this item and were left alone.
  */
 function linearBacklink(ref, prUrl, contract) {
   const token = readLinearKey(contract.workspace);
@@ -1930,19 +2008,21 @@ function linearBacklink(ref, prUrl, contract) {
     throw new TrackingError(
       `Linear issue ${ref} does not exist or is inaccessible`
     );
-  const managed = (issue.comments?.nodes ?? []).find(comment =>
-    carriesMarker(comment?.body)
+  const { mine, others } = partitionBacklinks(
+    issue.comments?.nodes ?? [],
+    prUrl,
+    comment => comment?.body
   );
   const body = backlinkBody(prUrl);
-  if (managed && managed.body === body) return "unchanged";
-  if (managed) {
+  if (mine && mine.body === body) return { change: "unchanged", others };
+  if (mine) {
     linearGraphql(
       token,
       "mutation($id:String!,$body:String!){commentUpdate(id:$id,input:{body:$body}){success}}",
-      { body, id: managed.id },
+      { body, id: mine.id },
       `Linear backlink update on ${ref}`
     );
-    return "updated";
+    return { change: "updated", others };
   }
   linearGraphql(
     token,
@@ -1950,7 +2030,7 @@ function linearBacklink(ref, prUrl, contract) {
     { body, id: issue.id },
     `Linear backlink comment on ${ref}`
   );
-  return "created";
+  return { change: "created", others };
 }
 
 /**
@@ -1985,7 +2065,8 @@ function jiraCommentDocument(prUrl) {
  * @param {string} ref Canonical `KEY-123` reference.
  * @param {string} prUrl Pull request URL.
  * @param {object} contract Resolved tracker contract.
- * @returns {string} What changed: created, updated, or unchanged.
+ * @returns {{change: string, others: number}} What changed, and how many other
+ *   pull requests are linked to this item and were left alone.
  */
 function jiraBacklink(ref, prUrl, contract) {
   const credentials = jiraCredentials(contract);
@@ -2004,24 +2085,26 @@ function jiraBacklink(ref, prUrl, contract) {
   if (listing.status !== 0)
     throw new TrackingError(`Jira ticket ${ref} comments are inaccessible`);
   const existing = safeJson(listing.stdout, `Jira comments on ${ref}`);
-  const managed = (existing.comments ?? []).find(comment =>
-    carriesMarker(comment?.body)
+  const { mine, others } = partitionBacklinks(
+    existing.comments ?? [],
+    prUrl,
+    comment => comment?.body
   );
   const document = jiraCommentDocument(prUrl);
   const payload = JSON.stringify({ body: document });
-  if (managed && JSON.stringify(managed.body) === JSON.stringify(document))
-    return "unchanged";
+  if (mine && JSON.stringify(mine.body) === JSON.stringify(document))
+    return { change: "unchanged", others };
   secureCurl(
-    [managed ? `${issueUrl}/${encodeURIComponent(managed.id)}` : issueUrl],
+    [mine ? `${issueUrl}/${encodeURIComponent(mine.id)}` : issueUrl],
     [
       ...auth,
-      ["request", managed ? "PUT" : "POST"],
+      ["request", mine ? "PUT" : "POST"],
       ["header", CONTENT_TYPE_JSON],
       [DATA_BINARY, payload],
     ],
     { error: `could not write the backlink comment on ${ref}` }
   );
-  return managed ? "updated" : "created";
+  return { change: mine ? "updated" : "created", others };
 }
 
 /**
@@ -2039,7 +2122,8 @@ function jiraBacklink(ref, prUrl, contract) {
  * @param {string} ref Canonical work-item reference.
  * @param {string} prUrl Pull request URL.
  * @param {object} contract Resolved tracker contract.
- * @returns {string} What changed: created, updated, or unchanged.
+ * @returns {{change: string, others: number}} What changed, and how many other
+ *   pull requests are linked to this item and were left alone.
  */
 function postBacklink(ref, prUrl, contract) {
   if (contract.provider === "github") return githubBacklink(ref, prUrl);
@@ -2442,6 +2526,74 @@ function remoteDefaultRef(remote) {
   return exists.status === 0 ? target : undefined;
 }
 
+/**
+ * The scope `validate-push` reports when it never saw the pushed refs at all.
+ *
+ * Named rather than left blank because this is the exact case #3874 measured:
+ * with no refs to read, the range falls back to the PUSHER'S `HEAD` — which on
+ * a cross-worktree push is a different branch than the one being pushed. The
+ * answer computed there is accurate about the local checkout and says nothing
+ * whatsoever about what is leaving the machine, so the verdict has to carry the
+ * scope it was computed over or a reader cannot tell the two apart.
+ */
+const HEAD_FALLBACK_SCOPE =
+  "local HEAD (the pushed refs were not readable, so this is NOT the pushed range)";
+
+/**
+ * An object id, short enough to read and long enough to be unambiguous.
+ * @param {string} oid A 40-character object id.
+ * @returns {string} The first twelve characters.
+ */
+function abbreviate(oid) {
+  return oid.slice(0, 12);
+}
+
+/**
+ * The pushed refs, from wherever this invocation can actually reach them.
+ *
+ * READING THE STREAM SPENDS IT, and the pre-push hook has several readers: the
+ * deletion guard, the destination guard, every declared gate, and this. The
+ * hook therefore captures git's stdin to a file once and names it in
+ * `LISA_PUSHED_REFS_FILE`, which is the only source that survives a gate having
+ * already drained the stream — and the gate runner is exactly where this runs
+ * on a project that declares `gates.traceability`.
+ *
+ * Stdin stays the fallback so driving the subcommand by hand with a pipe still
+ * works, and an unreadable file falls through to it rather than failing: a
+ * scratch file that vanished must not turn a push into an error about
+ * plumbing.
+ * @param {string|undefined} refsFile Path named by `--refs` or the environment.
+ * @returns {string} The raw stream, possibly empty.
+ */
+function readPushRefs(refsFile) {
+  if (refsFile !== undefined) {
+    try {
+      return readFileSync(refsFile, "utf8");
+    } catch {
+      // Fall through to stdin below.
+    }
+  }
+  try {
+    return readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * The scope clause every push verdict carries, pass or fail.
+ *
+ * A green that does not say what it looked at is indistinguishable from a green
+ * that looked at the wrong thing, which is the whole of #3874: `0 commit(s)`
+ * printed for a branch carrying a traced commit, because the range came from
+ * the pusher's checkout instead of the pushed ref.
+ * @param {string} scope The range or tree examined.
+ * @returns {string} The clause, ready to append to a verdict line.
+ */
+function examined(scope) {
+  return ` [examined ${scope}]`;
+}
+
 /**
  * One pushed ref and the commits it introduces, per line git sent.
  *
@@ -2460,7 +2612,8 @@ function remoteDefaultRef(remote) {
  * the rule is unchanged and now applied to the unit it was always about.
  * @param {string} input The pre-push stdin stream.
  * @param {string} remote Remote being pushed to.
- * @returns {{localRef: string|undefined, commits: string[], scope: string[]}[]}
+ * @returns {{localRef: string|undefined, commits: string[], scope: string[],
+ *   examinedScope: string}[]}
  *   One entry per ref update that introduces commits. `scope` is the rev-list
  *   argument vector the commit list came from, kept so a later question about
  *   the same range — see {@link ancestryUnreachable} — is asked of the range
@@ -2475,30 +2628,34 @@ function parsePushGroups(input, remote) {
   for (const line of input.trim().split(/\r?\n/).filter(Boolean)) {
     const [localRef, localOid, , remoteOid] = line.trim().split(/\s+/);
     if (!localOid || ZERO_OID.test(localOid)) continue;
-    const args =
-      remoteOid && !ZERO_OID.test(remoteOid)
-        ? [
-            "rev-list",
-            `${remoteOid}..${localOid}`,
-            ...(defaultRef ? ["--not", defaultRef] : []),
-          ]
-        : // New-branch lane: `--remotes=<remote>` is safe HERE because the branch
-          // being pushed has no remote-tracking ref yet — the exclusion set can
-          // only contain refs that already passed validation on earlier pushes.
-          // The existing-branch lane above must NOT use it (its tracking ref is
-          // pusher-controlled); it excludes only the remote default branch.
-          ["rev-list", localOid, "--not", `--remotes=${remote}`];
+    const existing = Boolean(remoteOid) && !ZERO_OID.test(remoteOid);
+    const args = existing
+      ? [
+          "rev-list",
+          `${remoteOid}..${localOid}`,
+          ...(defaultRef ? ["--not", defaultRef] : []),
+        ]
+      : // New-branch lane: `--remotes=<remote>` is safe HERE because the branch
+        // being pushed has no remote-tracking ref yet — the exclusion set can
+        // only contain refs that already passed validation on earlier pushes.
+        // The existing-branch lane above must NOT use it (its tracking ref is
+        // pusher-controlled); it excludes only the remote default branch.
+        ["rev-list", localOid, "--not", `--remotes=${remote}`];
     groups.push({
-      localRef,
       commits: git(args).split("\n").filter(Boolean),
+      examinedScope: existing
+        ? `${localRef} ${abbreviate(remoteOid)}..${abbreviate(localOid)}`
+        : `${localRef} (new branch) ${abbreviate(localOid)}`,
+      localRef,
       scope: args,
     });
   }
   if (groups.length === 0 && input.trim() === "") {
     const args = ["rev-list", "HEAD", "--not", `--remotes=${remote}`];
     groups.push({
-      localRef: undefined,
       commits: git(args).split("\n").filter(Boolean),
+      examinedScope: HEAD_FALLBACK_SCOPE,
+      localRef: undefined,
       scope: args,
     });
   }
@@ -2783,6 +2940,14 @@ function collect(findings, scope, gate, check) {
  * ticket id in it can never acquire one — that requirement is unreachable from
  * inside the pull request and the message has to say so, rather than leaving a
  * reader to try edits that cannot work.
+ *
+ * The closing sentence used to read "creates that comment or updates the
+ * existing one", and that was the whole problem: the existing one could belong
+ * to a DIFFERENT pull request, so following this printed remedy broke a pull
+ * request that had done nothing wrong (CodySwannGT/lisa#3916). The remedy is
+ * now safe by construction rather than by the reader noticing, and it says so —
+ * a reader who has just been told a gate is unmet needs to know that running
+ * the fix cannot un-fix somebody else.
  * @param {string} ref Canonical work-item reference.
  * @param {string} prUrl Pull request URL.
  * @param {object} contract Resolved tracker contract.
@@ -2797,7 +2962,10 @@ function backlinkAdvice(ref, prUrl, contract) {
     `${branchDerived}The one remedy that needs no new branch is the managed comment ` +
     `\`${MARKER} ${prUrl}\` on ${ref}. Do not post it by hand — run:\n\n` +
     `    ${BACKLINK_COMMAND} --ref ${ref} --pr-url ${prUrl}\n\n` +
-    `which creates that comment or updates the existing one, so running it twice is safe`
+    `which creates that comment, or updates the one already naming THIS pull ` +
+    `request. A backlink belonging to another pull request on ${ref} is left ` +
+    `alone, so running this twice — or for a second pull request against the ` +
+    `same item — is safe`
   );
 }
 
@@ -3446,8 +3614,72 @@ function backlink(args) {
   const prUrl = pullRequestUrlOption(args);
   if (!prUrl)
     throw new TrackingError(`${BACKLINK_COMMAND} requires --pr-url <url>`);
-  const outcome = postBacklink(ref, prUrl, contract);
-  console.log(`work-item backlink ${outcome} on ${ref}: ${MARKER} ${prUrl}`);
+  console.log(backlinkReport(postBacklink(ref, prUrl, contract), ref, prUrl));
+}
+
+/**
+ * Every work item a commit body DECLARES, by full-body scan.
+ *
+ * A declaration is the commit's own `Work-Item:` line. It is written by the
+ * author of the work, enforced on every non-merge commit by the commit-msg
+ * gate, and says "this commit is that item". A cross-reference says only that
+ * somebody's pull request NAMED the item somewhere, which is a different and
+ * much weaker claim — see `sweepDeclarations` for what that difference cost.
+ *
+ * Scanned with the `m` flag over the WHOLE body rather than read through git's
+ * `%(trailers:key=Work-Item)`, and that is the load-bearing part. Git's trailer
+ * parser only considers the LAST paragraph of a message, and this project's
+ * commits put `Work-Item:` above the trailing co-author block, so the parser
+ * does not see it as a trailer at all. Measured on `origin/main`: the parser
+ * finds 602 distinct issues where a full-body scan finds 835 — it misses 233,
+ * and the undercount is clean, plausible and well-formed, which is why it
+ * survived. Anything in this fleet that counts or verifies trailers has to
+ * scan the body (CodySwannGT/lisa#3859).
+ * @param {string} body A commit message body.
+ * @param {string} repository `owner/name` the item must belong to.
+ * @returns {number[]} Declared issue numbers, de-duplicated, in first-seen order.
+ */
+export function declaredWorkItemNumbers(body, repository) {
+  const escaped = String(repository ?? "").replace(
+    /[.*+?^${}()|[\]\\]/g,
+    "\\$&"
+  );
+  if (!escaped) return [];
+  const pattern = new RegExp(
+    `^[ \\t]*Work-Item:[ \\t]*${escaped}#([1-9]\\d*)[ \\t]*$`,
+    "gim"
+  );
+  const numbers = [];
+  let match;
+  while ((match = pattern.exec(String(body ?? ""))) !== null)
+    numbers.push(Number(match[1]));
+  return [...new Set(numbers)];
+}
+
+/**
+ * Work items declared by commits in a `git log` transcript.
+ *
+ * Pure over the transcript text so the whole attribution can be asserted
+ * without a repository. Records are NUL-separated (`git log -z`) because a
+ * commit body contains newlines and blank lines by construction, and any
+ * newline-based framing would split one commit into several.
+ * @param {string} logText Output of `git log -z --format=%H%n%B`.
+ * @param {string} repository `owner/name` the item must belong to.
+ * @returns {Map<number, string[]>} Issue number to the commits declaring it.
+ */
+export function shippedDeclarations(logText, repository) {
+  const declarations = new Map();
+  for (const record of String(logText ?? "").split("\0")) {
+    if (record.trim() === "") continue;
+    const newline = record.indexOf("\n");
+    const sha = (newline === -1 ? record : record.slice(0, newline)).trim();
+    const body = newline === -1 ? "" : record.slice(newline + 1);
+    for (const number of declaredWorkItemNumbers(body, repository)) {
+      if (!declarations.has(number)) declarations.set(number, []);
+      declarations.get(number).push(sha);
+    }
+  }
+  return declarations;
 }
 
 /**
@@ -4210,17 +4442,42 @@ function complete(args) {
  * Reports by default and only acts under `--apply`, because a sweep that closes
  * things as a side effect of being run is not something anyone will run twice.
  */
-function sweep(args) {
-  const contract = trackerContract();
-  if (contract.provider !== "github") {
-    throw new TrackingError(
-      `no sweep for tracker '${contract.provider}'; only github is supported so far.`
-    );
-  }
-  const repository = currentRepository();
-  if (!repository)
-    throw new TrackingError("could not resolve the current GitHub repository");
-  const claimed = contract.lifecycle.claimed;
+/**
+ * Buffer bound for a deploy branch's commit log.
+ *
+ * Sized against measurement rather than taste: `origin/main` here is 4.6 MiB
+ * of `%H%n%B` across ~1,600 commits, so 64 MiB leaves an order of magnitude of
+ * headroom and still bounds a runaway. It is a ceiling, not a target — and
+ * exceeding it now refuses loudly instead of reading as "no drift".
+ */
+const DECLARATION_LOG_MAX_BYTES = 64 * 1024 * 1024;
+
+/**
+ * The lifecycle roles the sweep examines, in report order.
+ *
+ * Both open lanes, not just the claimed one. An item whose work shipped while
+ * it still carried the ready role is structurally invisible to a claimed-only
+ * subject list — the flow never claimed it, or the claim was reverted, or the
+ * pull request came from a session that never transitioned it. Measured on
+ * this repository: of 122 open ready items, 11 had commits on `origin/main`
+ * carrying their `Work-Item:` trailer, and the sweep reported none of them in
+ * either mode (CodySwannGT/lisa#3907).
+ * @param {object} lifecycle Resolved lifecycle contract.
+ * @returns {string[]} Role names to query, de-duplicated.
+ */
+function sweptRoles(lifecycle) {
+  return [...new Set([lifecycle.ready, lifecycle.claimed])].filter(
+    role => typeof role === "string" && role !== ""
+  );
+}
+
+/**
+ * Open issues carrying one lifecycle role.
+ * @param {string} repository `owner/name` to list from.
+ * @param {string} role The label to filter by.
+ * @returns {object[]} Issues with `number` and `title`.
+ */
+function openIssuesWithRole(repository, role) {
   const listing = run(
     "gh",
     [
@@ -4231,7 +4488,7 @@ function sweep(args) {
       "--state",
       "open",
       "--label",
-      claimed,
+      role,
       "--limit",
       "200",
       "--json",
@@ -4241,33 +4498,157 @@ function sweep(args) {
   );
   if (listing.status !== 0) throw githubFailure(listing, repository);
   const issues = safeJson(listing.stdout, "GitHub issue listing");
+  return Array.isArray(issues) ? issues : [];
+}
+
+/**
+ * The first of `origin/<branch>` and `<branch>` that resolves to a commit.
+ * @param {string} branch Configured deploy branch name.
+ * @returns {string|undefined} A resolvable rev, or undefined.
+ */
+function resolvedBranchRev(branch) {
+  for (const candidate of [`origin/${branch}`, branch]) {
+    const result = run(
+      "git",
+      ["rev-parse", "--verify", "--quiet", `${candidate}^{commit}`],
+      { allowFailure: true }
+    );
+    if (result.status === 0 && result.stdout.trim() !== "") return candidate;
+  }
+  return undefined;
+}
+
+/**
+ * Work items DECLARED by commits reachable from a deploy branch.
+ *
+ * This is the sweep's evidence, and it replaced a timeline cross-reference
+ * scan. The difference is not academic. A cross-reference is created by any
+ * pull request that so much as NAMES `#N` — so one merged land-stack pull
+ * request made every sibling in its batch look shipped, and a single pull
+ * request was counted as evidence for several unrelated items at once.
+ * Measured before this change: of 53 items the sweep reported as drifted, 8
+ * had no commit on `main` declaring them at all — 15%, and every one of the 8
+ * had a live worktree branch open against it. Applying the sweep would have
+ * closed eight in-flight work items, and by this file's own words the closure
+ * "would be indistinguishable from a real one afterwards".
+ *
+ * Reachability is also what confirms the work actually landed, rather than
+ * trusting a pull request's `baseRefName` to say where it went.
+ * @param {string} repository `owner/name` the items belong to.
+ * @param {object} contract Resolved tracker contract.
+ * @returns {Map<number, string[]>} Issue number to declaring commits.
+ */
+function deployedDeclarations(repository, contract) {
+  const declarations = new Map();
+  for (const branch of contract.deployBranches.keys()) {
+    const rev = resolvedBranchRev(branch);
+    if (!rev) continue;
+    const result = run("git", ["log", rev, "-z", "--format=%H%n%B"], {
+      allowFailure: true,
+      maxBuffer: DECLARATION_LOG_MAX_BYTES,
+    });
+    // Loudly, not `continue`. This sweep's whole output is an absence claim,
+    // and a read that failed is not an absence — under the default 1 MiB
+    // buffer the real `origin/main` log (4.6 MiB) was truncated into an
+    // `error` with a null status, and the run reported "No drift" over 194
+    // items while having read nothing. Refusing is the only safe answer,
+    // because the alternative is the tool's most reassuring output being its
+    // least trustworthy one.
+    if (result.error || result.status !== 0) {
+      throw new TrackingError(
+        `could not read the commit log of ${rev}, so no absence of drift can be reported: ` +
+          `${result.error ? result.error.message : result.stderr.trim() || "git log failed"}.\n` +
+          `The sweep reports what a deploy branch declares; a log it could not read is not an empty one.`
+      );
+    }
+    for (const [number, shas] of shippedDeclarations(
+      result.stdout,
+      repository
+    )) {
+      declarations.set(number, [
+        ...new Set([...(declarations.get(number) ?? []), ...shas]),
+      ]);
+    }
+  }
+  return declarations;
+}
+
+/**
+ * Render the commits that declare an item, without printing a wall of hashes.
+ * @param {string[]} shas Declaring commits.
+ * @returns {string} A short, readable citation.
+ */
+function describeDeclarations(shas) {
+  const shown = shas.slice(0, 3).map(sha => sha.slice(0, 9));
+  const rest = shas.length - shown.length;
+  return rest > 0 ? `${shown.join(", ")}, +${rest} more` : shown.join(", ");
+}
+
+function sweep(args) {
+  const contract = trackerContract();
+  if (contract.provider !== "github") {
+    throw new TrackingError(
+      `no sweep for tracker '${contract.provider}'; only github is supported so far.`
+    );
+  }
+  const repository = currentRepository();
+  if (!repository)
+    throw new TrackingError("could not resolve the current GitHub repository");
+  const roles = sweptRoles(contract.lifecycle);
+  const subjects = new Map();
+  for (const role of roles) {
+    for (const issue of openIssuesWithRole(repository, role)) {
+      const existing = subjects.get(issue.number);
+      if (existing) existing.roles.push(role);
+      else subjects.set(issue.number, { ...issue, roles: [role] });
+    }
+  }
+  const declarations = deployedDeclarations(repository, contract);
   const apply = args.includes("--apply");
+  // Named in every report, clean or not. The old clean-result sentence spoke
+  // only of the claimed role while the subject list excluded the ready lane
+  // entirely — a true sentence that answered a narrower question than the one
+  // its reader was asking. An instrument that reports an absence has to say
+  // what it looked at.
+  const examined = roles.map(role => `"${role}"`).join(" and ");
   let drifted = 0;
-  for (const issue of Array.isArray(issues) ? issues : []) {
-    const ref = `${repository}#${issue.number}`;
-    const merged = mergedPullRequestsIn(githubTimeline(ref), repository);
-    if (merged.length === 0) continue;
+  for (const issue of [...subjects.values()].sort(
+    (left, right) => right.number - left.number
+  )) {
+    const shas = declarations.get(issue.number) ?? [];
+    if (shas.length === 0) continue;
     drifted += 1;
-    const evidence = merged.map(number => `#${number}`).join(", ");
+    const ref = `${repository}#${issue.number}`;
     if (!apply) {
-      console.log(`DRIFT  ${ref}  merged: ${evidence}  ${issue.title}`);
+      console.log(
+        `DRIFT  ${ref}  declared by: ${describeDeclarations(shas)}  [${issue.roles.join(", ")}]  ${issue.title}`
+      );
       continue;
     }
-    const outcome = completeWorkItem(ref, contract);
-    // A sweep must not abort on the first item whose merges have not reached a
-    // deploy branch. It reports that item and carries on, which is what makes
-    // the backstop safe to run over a whole queue.
-    console.log(outcome.report);
+    // A sweep must not abort on an item the applying arm refuses — whether it
+    // refuses because the merge reached no deploy branch, or because the
+    // tracker rejected the write. It reports that item and carries on, which
+    // is what makes the backstop safe to run over a whole queue.
+    try {
+      console.log(completeWorkItem(ref, contract).report);
+    } catch (error) {
+      console.log(
+        `work-item NOT completed: ${ref}\n${error instanceof Error ? error.message : String(error)}`
+      );
+    }
   }
   if (drifted === 0) {
     console.log(
-      `No drift: every item carrying "${claimed}" is genuinely in flight.`
+      `No drift: every open item carrying ${examined} is genuinely in flight.\n` +
+        `Examined ${subjects.size} item(s) across ${roles.length} lifecycle role(s); ` +
+        `no role outside ${examined} was queried.`
     );
     return;
   }
   if (!apply) {
     console.log(
-      `\n${drifted} claimed item(s) already have a merged pull request. Re-run with --apply to complete them.`
+      `\n${drifted} open item(s) carrying ${examined} are declared by a commit on a deploy branch. ` +
+        `Re-run with --apply to complete them.`
     );
   }
 }
@@ -4327,7 +4708,8 @@ function validateCommit(args) {
  * that answer into silence.
  * @param {string} input The pre-push stdin stream.
  * @param {string} remote Remote being pushed to.
- * @returns {{localRef: string|undefined, commits: string[], scope: string[]}[]}
+ * @returns {{localRef: string|undefined, commits: string[], scope: string[],
+ *   examinedScope: string}[]}
  *   Groups to check.
  */
 function pushGroups(input, remote) {
@@ -4335,7 +4717,17 @@ function pushGroups(input, remote) {
   const carrying = parsed.filter(group => group.commits.length > 0);
   return carrying.length > 0
     ? carrying
-    : [{ localRef: parsed[0]?.localRef, commits: [], scope: [] }];
+    : [
+        {
+          commits: [],
+          examinedScope: parsed[0]?.examinedScope ?? HEAD_FALLBACK_SCOPE,
+          localRef: parsed[0]?.localRef,
+          // Empty on purpose: `ancestryUnreachable` asks a question OF A RANGE,
+          // and there is no range here. `examinedScope` above is the separate,
+          // human-readable answer to "what did this verdict look at".
+          scope: [],
+        },
+      ];
 }
 
 /**
@@ -4495,9 +4887,14 @@ function pushDeferralNote(result) {
  * the WIRING and the direct cases prove the WORDS.
  * @param {object} result Commit-side result.
  * @param {string} label Prefix naming the ref, empty for a single-ref push.
+ * @param {string} [scope] The range or tree this verdict was computed over.
  * @returns {string} The whole report, replacing the success line.
  */
-export function unresolvedPushReport(result, label) {
+export function unresolvedPushReport(
+  result,
+  label,
+  scope = HEAD_FALLBACK_SCOPE
+) {
   const contract = result.contract;
   const refs = result.refs ?? [];
   const declaration = refs.map(ref => `Work-Item: ${ref}`).join("\n     ");
@@ -4506,7 +4903,7 @@ export function unresolvedPushReport(result, label) {
       ? `  UNRESOLVED gate 5 — each item needs a managed \`${MARKER}\` backlink comment pointing at the pull request. \`discharge-pr-gates\` posts it; nothing else has to remember to.`
       : `  n/a         gate 5 — the tracker backlink is not required here: workItem.verify is "trailer".`;
   return [
-    `WORK_ITEM_TRACKING_INCOMPLETE ${label}${result.relevant} commit(s)${alreadyTraced(result)}: gates 1-3 proved here, 2 of 5 gates NOT CHECKED.`,
+    `WORK_ITEM_TRACKING_INCOMPLETE ${label}${result.relevant} commit(s)${alreadyTraced(result)}${examined(scope)}: gates 1-3 proved here, 2 of 5 gates NOT CHECKED.`,
     `  This push is not a clean bill of health for ${refs.join(", ")}. ${pushDeferralNote(result)}`,
     `  UNRESOLVED gate 4 — the pull-request BODY must carry, on its own line${refs.length > 1 ? "s" : ""}:`,
     `     ${declaration}`,
@@ -4546,15 +4943,20 @@ export function pushSuccessLine(result, label) {
  * @param {{result?: object, error?: Error}} outcome Commit-side outcome.
  * @param {object|undefined} pr The pull request this ref is about, if any.
  * @param {string} label Prefix naming the ref, empty for a single-ref push.
+ * @param {string} scope The range or tree this verdict was computed over.
  */
-function reportPushGroup(outcome, pr, label) {
+function reportPushGroup(outcome, pr, label, scope) {
   if (pr) {
     // `true`: a push range is ALWAYS a subset of the pull request's — it drops
     // commits already on the remote branch and everything reachable from the
     // remote default branch. So a commit side with nothing in it means "no
     // subject in THIS push", never "no subject in the pull request".
     validatePrData(outcome, pr.url, pr.body, true);
-    console.log(pushSuccessLine(outcome.result, label));
+    // The scope clause is appended HERE rather than inside `pushSuccessLine`
+    // so that function keeps the two-argument shape #3886's inequality test
+    // calls it with. What it returns is the verdict; what this adds is the
+    // range the verdict was computed over.
+    console.log(`${pushSuccessLine(outcome.result, label)}${examined(scope)}`);
     return;
   }
   // No pull request means gates 4 and 5 cannot be CHECKED here. They are
@@ -4571,16 +4973,22 @@ function reportPushGroup(outcome, pr, label) {
   // checklist teaches the reader to skip it.
   if ((outcome.result.refs ?? []).length === 0) {
     console.log(
-      `WORK_ITEM_TRACKING_OK ${label}${outcome.result.relevant} commit(s)${alreadyTraced(outcome.result)}; this range names no work item, so gates 4 and 5 have nothing to check here.`
+      `WORK_ITEM_TRACKING_OK ${label}${outcome.result.relevant} commit(s)${alreadyTraced(outcome.result)}; this range names no work item, so gates 4 and 5 have nothing to check here.${examined(scope)}`
     );
     return;
   }
-  console.log(unresolvedPushReport(outcome.result, label));
+  console.log(unresolvedPushReport(outcome.result, label, scope));
 }
 
 function validatePush(args) {
-  const remote = args[0] || "origin";
-  const input = readFileSync(0, "utf8");
+  const remote = args[0] && !args[0].startsWith("-") ? args[0] : "origin";
+  // `--refs <file>` / `LISA_PUSHED_REFS_FILE` names the captured pre-push
+  // stream, exactly as `validate-push-destination` reads it. Without it this
+  // command is reachable — through the gate runner — only after some earlier
+  // reader has already spent git's stdin, and the empty-stream fallback below
+  // then answers about the PUSHER'S `HEAD` rather than the pushed ref
+  // (CodySwannGT/lisa#3874).
+  const input = readPushRefs(option(args, "--refs", "LISA_PUSHED_REFS_FILE"));
   // The deploy chain is read from the remote default branch, the same ref this
   // path already trusts to bound the range. A local working tree could declare
   // anything, but so could a `--no-verify`; CI is the enforcing copy.
@@ -4599,7 +5007,8 @@ function validatePush(args) {
     reportPushGroup(
       outcome,
       group === target ? pr : undefined,
-      groups.length > 1 ? `${group.localRef ?? "(stdin)"}: ` : ""
+      groups.length > 1 ? `${group.localRef ?? "(stdin)"}: ` : "",
+      group.examinedScope
     );
   }
 }
@@ -4708,8 +5117,8 @@ export function postDischargeBacklinks(
   let changed = false;
   for (const ref of refs) {
     const outcome = post(ref, prUrl, contract);
-    changed ||= outcome !== "unchanged";
-    console.log(`work-item backlink ${outcome} on ${ref}: ${MARKER} ${prUrl}`);
+    changed ||= outcome.change !== "unchanged";
+    console.log(backlinkReport(outcome, ref, prUrl));
   }
   return changed;
 }