@codyswann/lisa 4.45.4 → 4.45.6

package/plugins/src/base/hooks/parity-safety-net.sh

@@ -2030,6 +2030,77 @@ readonly GIT_CONTROL_PLANE='(^|[[:space:]='"$qc"'./])\.git([/[:space:]'"$qc"']|$
 # that could not run produced no lines, the loop body never executed, and the
 # guard was skipped with the command ALLOWED. A segmentation that cannot answer
 # must refuse, exactly like a scan that cannot answer.
+# 14b. Linked worktrees, which are the same principle one level out. `.git` is
+# protected because nothing in the working tree can rebuild it; a linked
+# worktree is protected because nothing OUTSIDE it can rebuild what it holds.
+# The asymmetry is exact and it is invisible from the prompt: `.git/refs` and
+# the object store are shared by every worktree of a repository, while
+# `.git/index` and the working files are per-worktree. So `git commit` moves
+# work somewhere a deletion cannot reach, and `git add` does not — a staged file
+# shows green in `git status`, which reads as saved, and dies with the
+# directory.
+#
+# Measured twice in one evening (issue #3863): one worktree lost a 284-line
+# staged test file, and a second lost nothing from the identical event purely
+# because a gate had forced its work into a commit first. Neither deletion
+# announced itself. That is the second reason this is a block rather than a
+# warning — a worktree deletion destroys the only evidence its own case could
+# leave, so there is no after-the-fact detection to fall back on.
+#
+# `git worktree remove` (guard 12) already refuses a dirty tree, and
+# `--force` is already blocked. This closes the spelling that walks around both:
+# `rm -rf` on the directory, which git never sees.
+#
+# Matching is by REGISTERED path — `git worktree list` names them — so an
+# ordinary directory that merely lives near one is untouched. A repository that
+# cannot be read answers "no": this guard adds protection to a shape that was
+# fully allowed a moment ago, and failing it closed would deny every recursive
+# delete on every path outside a repository.
+#
+# The comparison is on WHOLE TOKENS, which is the only spelling that gets both
+# error directions right. Substring containment would let a worktree named
+# `wt-1` claim `rm -rf wt-10`, an over-block on an unrelated directory; and
+# hand-written boundary classes leak the other way, because `rm -rf <wt>/`
+# with one trailing slash ends on a character every such class treats as
+# "inside a path". So every non-path character — quote, space, parenthesis,
+# redirection — is folded to a space first, which makes each argument a
+# space-delimited token regardless of how it was quoted, and the match is then
+# an equality test on that token. A SUBPATH (`rm -rf <wt>/node_modules`) is
+# deliberately not this guard's business: it is not a worktree deletion, and
+# blocking routine cleanup inside a worktree is how a guard gets switched off.
+names_linked_worktree() {
+  local stmt="$1" probe root listed line primary wt rel
+  root="$(git -C "${CLAUDE_PROJECT_DIR:-$PWD}" rev-parse --show-toplevel 2> /dev/null)" || return 1
+  [ -n "$root" ] || return 1
+  listed="$(git -C "$root" worktree list --porcelain 2> /dev/null)" || return 1
+  probe=" $(printf '%s' "$stmt" | tr -c 'A-Za-z0-9_./-' ' ') "
+  primary=""
+  while IFS= read -r line; do
+    case "$line" in
+      worktree\ *) wt="${line#worktree }" ;;
+      *) continue ;;
+    esac
+    # First entry is the primary checkout, which is not a linked worktree.
+    if [ -z "$primary" ]; then
+      primary="$wt"
+      continue
+    fi
+    case "$probe" in
+      *" $wt "* | *" $wt/ "*) return 0 ;;
+    esac
+    rel="${wt#"$primary"/}"
+    [ "$rel" != "$wt" ] || continue
+    # `./` is the same path spelled the way an agent in the project root types
+    # it, and a token comparison is exact, so it has to be spelled here too.
+    case "$probe" in
+      *" $rel "* | *" $rel/ "* | *" ./$rel "* | *" ./$rel/ "*) return 0 ;;
+    esac
+  done <<EOF
+$listed
+EOF
+  return 1
+}
+
 git_segments_status=0
 git_segments="$(printf '%s' "$normalized_command_str" \
   | awk '{ if (/\|[ \t]*$/) printf "%s ", $0; else print }' \
@@ -2052,6 +2123,9 @@ while IFS= read -r git_stmt; do
   if scan -E "$git_stmt" "$GIT_CONTROL_PLANE"; then
     block "recursive forced delete of the git control plane (.git holds every commit, branch and stash not already pushed; nothing in the working tree can rebuild it). Delete a specific ignored artifact instead. Re-cloning is NOT a like-for-like replacement: every linked worktree stores a pointer into this .git, so discarding it discards each of them and any uncommitted work they hold — check \`git worktree list\` before treating the checkout as disposable."
   fi
+  if names_linked_worktree "$git_stmt"; then
+    block "recursive forced delete of a linked git worktree. A worktree's index and working files are private to it — only commits are shared — so this destroys any staged or unwritten-to-a-commit work another agent left there, and destroys the evidence that it did (CodySwannGT/lisa#3863). Use 'node scripts/lisa-worktree-guard.mjs remove <path>' instead: it deletes clean and already-committed trees without ceremony, names the files when they exist nowhere else, and records an explicit --force override."
+  fi
 done <<<"$git_segments"
 
 # 15. Credential stores. Reading one into an agent transcript is disclosure even

package/plugins/src/base/hooks/worktree-binding-guard.mjs

@@ -304,6 +304,11 @@ function foreignTreeIn(text, bound, cwd) {
   for (const raw of code.match(/[^\s'";|&()<>]+/gu) ?? []) {
     const token = raw.replace(/^["']|["']$/gu, "");
     if (!token.includes("/")) continue;
+    // A null base means an unliteral `cd` left the directory this script runs
+    // from unknown. An ABSOLUTE token is unambiguous either way; a relative one
+    // is exactly the thing that cannot be placed, so it is skipped rather than
+    // resolved against a directory picked for having been handy.
+    if (!isAbsolute(token) && cwd === null) continue;
     const candidate = isAbsolute(token) ? token : join(cwd, token);
     let root;
     try {
@@ -317,6 +322,63 @@ function foreignTreeIn(text, bound, cwd) {
   return null;
 }
 
+/**
+ * A `cd` target this guard cannot turn into a literal directory.
+ *
+ * Mirrors `parity-safety-net.sh`'s `follow_cd` test exactly, and the mirror is
+ * the point: two spellings of one rule are how the guards drift.
+ */
+const UNLITERAL_CD_TARGET = /[$`*?[{]/u;
+
+/**
+ * The literal target of a leading `cd`, `""` for a bare `cd`, or null when the
+ * segment does not change directory.
+ *
+ * A bare `cd` is `cd "$HOME"`. Leaving the previous directory in place for it
+ * would resolve later tokens from a directory the shell has already left.
+ * @param segment - One statement from the command
+ * @returns The target text, or null when this segment is not a `cd`
+ */
+function cdTarget(segment) {
+  const tokens = tokenise(segment);
+  if (tokens.length === 0 || tokens[0] !== "cd") return null;
+  return tokens[1] ?? "";
+}
+
+/**
+ * Apply one `cd` to the directory currently in force.
+ *
+ * Contract points 1-4 of `cwd-resolution-corpus.json`: a literal target
+ * REPLACES the directory rather than joining a list of candidates — the
+ * ordering was #3933's entire defect; a relative target composes against the
+ * directory in force; a target that is not literal text yields unknown; and
+ * unknown is sticky only until the next resolvable `cd`, because this returns
+ * a fresh answer for each one.
+ * @param current - Directory in force, or null when it is already unknown
+ * @param target - Literal `cd` target, `""` for a bare `cd`
+ * @returns The new directory, or null when it cannot be known
+ */
+function applyCd(current, target) {
+  const home = homedir();
+  let value = target === "" ? home : target;
+  if (value === "~") value = home;
+  else if (value.startsWith("~/")) value = join(home, value.slice(2));
+  if (
+    value === "" ||
+    value.startsWith("-") ||
+    UNLITERAL_CD_TARGET.test(value)
+  ) {
+    return null;
+  }
+  if (!isAbsolute(value) && current === null) return null;
+  const next = isAbsolute(value) ? resolve(value) : resolve(current, value);
+  try {
+    return statSync(next).isDirectory() ? next : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * The foreign worktree an executed script reaches, or null.
  *
@@ -340,41 +402,71 @@ function foreignTreeIn(text, bound, cwd) {
  * disagreeing. The scripted form is the one neither covers, and it is the only
  * cell this arm fills.
  *
- * ## A relative script path is resolved against `payload.cwd`, and that is a
- * KNOWN limitation shared with `parity-safety-net.sh`
+ * ## A relative script path is resolved against the cwd the command will have
+ *
+ * A leading `cd` establishes the directory this guard resolves relative tokens
+ * from, because that is the directory the shell will be in once the command
+ * runs. Resolving against `payload.cwd` instead was CodySwannGT/lisa#3933's
+ * defect, inherited here knowingly and fixed in CodySwannGT/lisa#3952: on a
+ * machine running many worktrees of one repository, every tree holds its own
+ * copy of every script at the same relative path, and they differ by whatever
+ * each lane is doing.
  *
- * CodySwannGT/lisa#3933, filed against that guard, is the same defect: a
- * relative token is resolved against the hook process's working directory, not
- * against the directory the command will have once it runs its own leading
- * `cd`. So `cd <other tree> && bash scripts/foo.sh` reads THIS tree's copy of
- * `scripts/foo.sh` and reports on it with full confidence.
+ * ## One contract, two implementations, and why that is the honest answer
  *
- * It matters here for the same reason it matters there: on a machine running
- * many worktrees of one repository, every tree holds its own copy of every
- * script at the same relative path, and they differ by whatever each lane is
- * doing. A confident scan of the wrong copy is wrong in both directions, and
- * the silent one — the copy that will run reaches out, the copy that was read
- * does not — is the direction this arm exists to prevent.
+ * `parity-safety-net.sh` answers this same question — "which file will this
+ * command actually execute?" — in POSIX shell, where `follow_cd` mutates
+ * file-scope state that `follow_locate` reads. This guard is Node. **There is
+ * no call that reaches from here into a shell function's file-scope state**, so
+ * the duplication is not a factoring somebody skipped; it is one idea that
+ * cannot cross a language boundary as a function call.
  *
- * NOT fixed here on purpose. #3933 is assigned and its options (honour a
- * leading `cd`, or fail closed when the effective cwd is uncertain) belong in
- * one place rather than two: a second implementation of the same resolution is
- * how two guards drift into disagreeing about which file a command runs.
- * When that lands, this call site should adopt whatever it produces.
+ * What binds the two is a written contract and a corpus of rows that BOTH
+ * guards are driven over in CI, so a divergence fails a test on the commit that
+ * causes it rather than surfacing later as a wrong verdict. Contract and corpus
+ * live in `tests/unit/hooks/support/cwd-resolution-corpus.json`.
  *
- * The exposure here is narrower than there. This arm is reached only after the
- * session has been confirmed to be in its bound worktree, so the common case
- * is a relative path resolving inside the tree the session is actually in.
+ * This is explicitly NOT unification, and CodySwannGT/lisa#3952 records it as
+ * such: two implementations remain. **A behaviour with no row in the corpus is
+ * free to diverge — add a row when you add a branch.**
+ *
+ * ## The two guards agree on the RESOLUTION, not on the verdict
+ *
+ * When the effective directory cannot be known, both guards decline to resolve
+ * the token. What they then do differs, and that difference is deliberate:
+ * `parity-safety-net.sh` refuses, because a destructive command it cannot see
+ * is the thing it exists to stop. This guard fails open, which is the doctrine
+ * every other undecidable case in this file follows. The corpus asserts the
+ * resolved path, not the exit code, precisely so that one contract can bind two
+ * guards whose fail directions are correctly different.
  *
  * Fails OPEN and says so, like every other undecidable case in this file.
  */
 function scriptReachingForeignTree(payload, bound) {
   const command = payload.tool_input?.command;
   if (typeof command !== "string" || !command) return null;
+  let cwd = payload.cwd;
   for (const segment of command.split(COMMAND_SEPARATORS)) {
+    const target = cdTarget(segment);
+    if (target !== null) {
+      cwd = applyCd(cwd, target);
+      continue;
+    }
     const named = executedPath(segment);
     if (!named) continue;
-    const path = isAbsolute(named) ? named : join(payload.cwd, named);
+    if (!isAbsolute(named) && cwd === null) {
+      // Contract point 3: the effective directory is unknown, so WHICH copy of
+      // a same-named script would run is unknown too. Declining to resolve is
+      // the half shared with parity-safety-net.sh; failing open rather than
+      // refusing is this guard's own doctrine, and the corpus binds the two
+      // guards on the resolution precisely so it does not have to bind them
+      // on a verdict one of them would be wrong to reach.
+      say(
+        `cannot tell which directory ${named} would run from; NOT enforcing on it`
+      );
+      continue;
+    }
+    const path = isAbsolute(named) ? resolve(named) : resolve(cwd, named);
     let text;
     try {
       if (statSync(path).size > SCRIPT_READ_LIMIT) {
@@ -386,7 +478,7 @@ function scriptReachingForeignTree(payload, bound) {
       // Not a readable file: nothing was executed that this can read.
       continue;
     }
-    const foreign = foreignTreeIn(text, bound, payload.cwd);
+    const foreign = foreignTreeIn(text, bound, cwd);
     if (foreign) return { script: path, foreign };
   }
   return null;

package/scripts/check-cwd-resolution-corpus.mjs

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+/**
+ * Refuse a cwd-resolution corpus that cannot bite.
+ *
+ * Two guards answer "which file will this command actually execute?" in two
+ * languages — POSIX shell in `parity-safety-net.sh`, Node in
+ * `worktree-binding-guard.mjs` — and one corpus of rows is what keeps their
+ * answers the same (CodySwannGT/lisa#3952). That arrangement is only worth
+ * anything while the rows are adversarial, and rows decay in one direction: a
+ * `holds` row is easy to write and always passes, so a corpus left alone drifts
+ * towards proving the resolver RAN rather than that it BITES.
+ *
+ * So the shape is enforced rather than requested:
+ *
+ * - both adversarial classes present, because a resolver is wrong in two
+ *   directions and one class of row only ever catches one of them
+ * - every contract point carried by at least one adversarial row, because a
+ *   point pinned only by rows both wrong implementations already pass is
+ *   documented rather than pinned
+ * - at least one `unknown` expectation, because the fail-closed floor is the
+ *   half nobody writes voluntarily
+ * - a row that skips a guard must say why, in the row, rather than by omission
+ *
+ * Exits 1 with the reason on any violation. Report-only otherwise.
+ * @module scripts/check-cwd-resolution-corpus
+ */
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+const CORPUS = path.resolve(
+  "tests/unit/hooks/support/cwd-resolution-corpus.json"
+);
+const GUARDS = ["shell", "node"];
+const CONTROLS = ["bites", "wall", "holds"];
+/** The classes that fail under a wrong implementation. `holds` does not. */
+const ADVERSARIAL = ["bites", "wall"];
+
+/**
+ * Read and parse the corpus.
+ * @returns The parsed corpus document
+ */
+function load() {
+  return JSON.parse(readFileSync(CORPUS, "utf8"));
+}
+
+/**
+ * Every id appears once, so a row cannot be silently replaced by a copy.
+ * @param rows - Corpus rows
+ * @returns Violation messages
+ */
+function checkIds(rows) {
+  const seen = new Set();
+  const bad = [];
+  for (const row of rows) {
+    if (seen.has(row.id)) bad.push(`duplicate row id: ${row.id}`);
+    seen.add(row.id);
+  }
+  return bad;
+}
+
+/**
+ * Each row declares a known control class and at least one guard it applies to.
+ * @param rows - Corpus rows
+ * @returns Violation messages
+ */
+function checkShape(rows) {
+  const bad = [];
+  for (const row of rows) {
+    if (!CONTROLS.includes(row.control)) {
+      bad.push(`${row.id}: control must be one of ${CONTROLS.join(", ")}`);
+    }
+    const applies = row.applies ?? [];
+    if (applies.length === 0) bad.push(`${row.id}: applies to no guard`);
+    for (const guard of applies) {
+      if (!GUARDS.includes(guard))
+        bad.push(`${row.id}: unknown guard ${guard}`);
+    }
+    if (!applies.includes("node") && !row.why_not_node) {
+      bad.push(
+        `${row.id}: skips the Node guard without saying why. A row that skips a guard by omission is how a gap becomes invisible — add why_not_node.`
+      );
+    }
+  }
+  return bad;
+}
+
+/**
+ * Both control classes are present, and the fail-closed floor is represented.
+ * @param rows - Corpus rows
+ * @returns Violation messages
+ */
+function checkControls(rows) {
+  const bad = [];
+  for (const control of ADVERSARIAL) {
+    if (rows.some(row => row.control === control)) continue;
+    bad.push(
+      control === "bites"
+        ? 'no row has control "bites". Nothing here fails under a pre-fix implementation, so the silent direction — a confident verdict about a file nobody was about to run — is unguarded.'
+        : 'no row has control "wall". Nothing here fails under an over-eager implementation, so nothing stops the fail-closed floor becoming a wall, and a wall gets switched off.'
+    );
+  }
+  if (!rows.some(row => row.expect === "unknown")) {
+    bad.push(
+      'no row expects "unknown". The fail-closed floor is the half nobody writes voluntarily, so it is required.'
+    );
+  }
+  return bad;
+}
+
+/**
+ * Every contract point is carried by at least one row that a pre-fix
+ * implementation would fail.
+ * @param contract - Contract points, keyed by number
+ * @param rows - Corpus rows
+ * @returns Violation messages
+ */
+function checkCoverage(contract, rows) {
+  const bad = [];
+  for (const point of Object.keys(contract)) {
+    const covering = rows.filter(row =>
+      (row.contract ?? []).map(String).includes(point)
+    );
+    if (covering.length === 0) {
+      bad.push(
+        `contract point ${point} has no row. Add a row when you add a branch.`
+      );
+      continue;
+    }
+    if (!covering.some(row => ADVERSARIAL.includes(row.control))) {
+      bad.push(
+        `contract point ${point} is carried only by "holds" rows, which both wrong implementations already pass. It is documented, not pinned.`
+      );
+    }
+  }
+  return bad;
+}
+
+/**
+ * Report every violation at once, then exit.
+ * @returns Process exit code
+ */
+function main() {
+  const corpus = load();
+  const rows = corpus.rows ?? [];
+  const bad = [
+    ...checkIds(rows),
+    ...checkShape(rows),
+    ...checkControls(rows),
+    ...checkCoverage(corpus.contract ?? {}, rows),
+  ];
+  if (bad.length > 0) {
+    process.stderr.write("cwd-resolution corpus is not adversarial enough:\n");
+    for (const line of bad) process.stderr.write(`  - ${line}\n`);
+    return 1;
+  }
+  const biting = rows.filter(row => ADVERSARIAL.includes(row.control)).length;
+  process.stdout.write(
+    `cwd-resolution corpus: ${rows.length} row(s), ${biting} of which a wrong implementation fails; ${Object.keys(corpus.contract).length} contract point(s) each pinned by at least one.\n`
+  );
+  return 0;
+}
+
+process.exit(main());

package/scripts/cleanup-worktrees.sh

@@ -13,8 +13,13 @@
 #   3. No modified/staged TRACKED files ("real work" is never deleted).
 #   4. Its HEAD commit is reachable from some remote ref (nothing unpushed).
 #   5. It is older than --min-age-days (default 7) by directory mtime.
+#   6. Its uncommitted content is reachable from some commit — asked of the
+#      bytes, not of the tracking state, by lisa-worktree-guard.
 #   Untracked-only dirt (node_modules, .env.local, build output) blocks
-#   removal by default; pass --force-untracked to treat it as junk.
+#   removal by default; pass --force-untracked to treat it as junk. Even then
+#   the content gate stands: --force-untracked means "untracked files are not
+#   by themselves work", not "delete bytes that exist in no commit"
+#   (CodySwannGT/lisa#3863).
 #
 # DRY-RUN BY DEFAULT. Nothing is deleted until you pass --apply.
 #
@@ -46,7 +51,12 @@ while [ $# -gt 0 ]; do
       fi
       MIN_AGE_DAYS="$1" ;;
     --delete-branches) DELETE_BRANCHES=1 ;;
-    -h|--help) sed -n '2,30p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    # Print the whole leading comment block, not a hardcoded line count. `2,30p`
+    # silently stopped covering the last option the moment the header grew by
+    # six lines, and nothing reported it — the help text is not asserted
+    # anywhere, so the only symptom is an operator who never learns an option
+    # exists. Stop at the first non-comment line instead, which cannot drift.
+    -h|--help) sed -n '2,${/^[^#]/q;p;}' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
     *) REPO="$1" ;;
   esac
   shift
@@ -61,6 +71,21 @@ fi
 NOW=$(date +%s)
 MIN_AGE_SECS=$((MIN_AGE_DAYS * 86400))
 REMOVED=0 KEPT_DIRTY=0 KEPT_UNPUSHED=0 KEPT_YOUNG=0 KEPT_UNTRACKED=0 ORPHANS=0 ERRORS=0
+KEPT_UNREACHABLE=0
+
+# Content-reachability guard. Absent node or an unresolvable script leaves the
+# older gates in charge rather than silently widening what this script deletes.
+GUARD=""
+for candidate in \
+  "$REPO/scripts/lisa-worktree-guard.mjs" \
+  "$REPO/node_modules/@codyswann/lisa/all/copy-overwrite/scripts/lisa-worktree-guard.mjs" \
+  "$REPO/all/copy-overwrite/scripts/lisa-worktree-guard.mjs"; do
+  if [ -f "$candidate" ]; then
+    GUARD="$candidate"
+    break
+  fi
+done
+command -v node > /dev/null 2>&1 || GUARD=""
 
 log() { printf '%s\n' "$*"; }
 act() { if [ "$APPLY" = 1 ]; then log "REMOVE  $*"; else log "WOULD-REMOVE  $*"; fi; }
@@ -149,6 +174,14 @@ process_worktree() {
     return
   fi
 
+  # Content gate: bytes that exist in no commit are never junk, whatever
+  # --force-untracked says about tracking state.
+  if [ -n "$GUARD" ] && ! node "$GUARD" check "$wt" > /dev/null 2>&1; then
+    KEPT_UNREACHABLE=$((KEPT_UNREACHABLE + 1))
+    log "KEEP (holds content that exists in no commit)  $wt"
+    return
+  fi
+
   local force_flag=()
   if [ -n "$(git -C "$wt" status --porcelain 2>/dev/null)" ]; then
     if [ "$FORCE_UNTRACKED" = 1 ]; then
@@ -217,6 +250,6 @@ fi
 log ""
 log "=== summary ==="
 log "removed (or would remove): $REMOVED   orphan dirs: $ORPHANS"
-log "kept: $KEPT_DIRTY modified-tracked, $KEPT_UNPUSHED unpushed, $KEPT_UNTRACKED untracked-only, $KEPT_YOUNG too-young   errors: $ERRORS"
+log "kept: $KEPT_DIRTY modified-tracked, $KEPT_UNPUSHED unpushed, $KEPT_UNTRACKED untracked-only, $KEPT_UNREACHABLE uncommitted-content, $KEPT_YOUNG too-young   errors: $ERRORS"
 [ "$APPLY" = 0 ] && log "(dry run — rerun with --apply to delete)"
 exit 0

package/scripts/two-channel-couplings.json

@@ -7,7 +7,7 @@
     "workflows": 22,
     "steps": 716,
     "couplings": 34,
-    "inventory": 76
+    "inventory": 77
   },
   "counts": {
     "package-backed": 10,

package/typescript/copy-overwrite/.prettierignore

@@ -93,6 +93,7 @@ scripts/lisa-run-gates.mjs
 scripts/lisa-schema-validate.mjs
 scripts/lisa-test-node.mjs
 scripts/lisa-work-item.mjs
+scripts/lisa-worktree-guard.mjs
 scripts/nightly-e2e-provider-action.mjs
 scripts/nightly-e2e-provider-github-jira.mjs
 scripts/nightly-e2e-provider-linear-sentry.mjs

package/typescript/create-only/.github/workflows/review-evidence.yml

@@ -123,7 +123,26 @@ concurrency:
 
 jobs:
   vacuity:
-    name: 🕵️ Did the required review checks do any work?
+    # DECLARATIVE, NOT A QUESTION (#3917). This was `🕵️ Did the required review
+    # checks do any work?`, and an unsatisfied verdict exits non-zero, so the
+    # row rendered `Did the required review checks do any work?  fail`. A yes/no
+    # question answered `fail` composes to "NO" — the row asserted that the
+    # review checks did no work at exactly the moment the verdict said
+    # `UNDETERMINED — ... is NOT reporting that nobody reviewed`. A
+    # question-shaped name cannot safely carry more than two outcomes, and the
+    # settle-timeout gives this gate a third.
+    #
+    # AND THE OBVIOUS REPLACEMENT WOULD BE A NEW FALSE CLAIM. `Required review
+    # checks did work` reads true on a failure but FALSE on a pass: this job
+    # exits 0 for a SATISFIED gate and for a WAIVED one alike, so the pass path
+    # would assert work on the very pull requests nothing reviewed. The name
+    # therefore describes the GATE and asserts nothing about the review; the
+    # three-valued answer is published next door as `🕵️ Review evidence
+    # verdict`, which is where it belongs.
+    #
+    # Only the name changed. Severity, exit codes, the wait, and the verdict
+    # vocabulary are untouched.
+    name: 🕵️ Review evidence gate
     runs-on: ubuntu-latest
     # The guard waits for the declared checks to settle before judging them: a
     # review bot posts `pending — "Review queued"` and `pending — "Review in