@plot-pm/board 0.11.0 → 0.12.0

package/plot-pr-merged.sh

@@ -0,0 +1,180 @@
+#!/usr/bin/env bash
+# Plot helper: the ONE answer to "did the host merge ANY PR for this branch?"
+#
+# SOURCED, NOT RUN. `. "$script_dir/plot-pr-merged.sh"` defines `pr_merged` and
+# `pr_open`; the file does nothing else on load. That is what makes sourcing it
+# safe, and it is the same shape — and the same reason — as
+# `plot-worker-state.sh`: the logic could not simply stay in `plot-reap.sh`,
+# because that file parses `$@` and `exit 2`s on an unknown argument at load
+# time, so sourcing it would run the reaper's argument parser against its
+# caller's arguments.
+#
+# FOUR CALLERS. `plot-reap.sh`, `plot-release-refs.sh`, `plot-dispatch.sh`, and
+# `plot-quiet-stretch.sh` — the last sourcing it guarded and calling it behind
+# `command -v pr_merged`, so it still works with this file absent.
+#
+# WHY IT WAS EXTRACTED. `plot-reap.sh` and `plot-release-refs.sh` gate on the
+# SAME fact — has this branch's work landed — and they must never disagree
+# about it. The reaper removes a checkout, which is re-creatable with
+# `git worktree add`; ref deletion is not re-creatable at all. A second
+# implementation that drifted toward permissive would therefore fail in the
+# direction that cannot be undone. One function, one answer, no drift.
+#
+# THIS FILE IS NOW THE ADAPTER, AND THE DECISION IS THE DOMAIN'S. The two
+# functions still ask the host, because the host is asked in shell; what they no
+# longer do is decide. Each turns its lookup into one of three READINGS —
+# `found`, `none`, `unaskable` — and hands the pair to
+# `board/plot-landed.mjs`, which bundles `rules/landed.ts`. The layering runs
+# one way: caller → this adapter → the rule.
+#
+# WHAT MOVED IS THE COUPLING. `pr_merged` and `pr_open` fail in the SAME
+# direction and to OPPOSITE effect — an unreachable host makes the first refuse
+# a removal and the second release its veto — so neither is safe alone and the
+# pair is. That was a comment in this file and could not be checked. It is now
+# `mayRemove` in the rule, asserted over all nine combinations of the two
+# readings, and exactly one of them permits a removal.
+#
+# WHY THIS STILL ASKS `gh` AND NOT `plot-host.sh`. Measured 2026-09-06, and it
+# is the answer to a question this file's exemption in
+# `scripts/check-host-cli-callers.sh` was left open for.
+#
+# `plot-host.sh pr-merged` prints `merged`/`not-merged`/`unknown`, three words
+# that read like the three readings below. THEY DO NOT MATCH. An ABSENT CLI
+# arrives from the adapter as `not-merged`, where `_plot_merged_lookup` answers
+# `unaskable`:
+#
+#   plot-host.sh pr-merged <branch>   → not-merged (exit 0)
+#   _plot_merged_lookup <branch>      → unaskable
+#
+# The cause is the adapter's `is_lookup_miss`. A missing binary makes the shell
+# say `bash: gh: command not found`, and that matches the same `not found` it
+# uses to recognise a genuine "no pull requests found" — one phrase covering two
+# conditions the rule below exists to keep apart.
+#
+# THE DIRECTION IS WHY IT BLOCKS RATHER THAN ANNOYS. `not-merged` reads as
+# `none` — the host spoke and said nothing merged — so `mayRemove` may permit a
+# removal where `unaskable` refuses. `plot-release-refs.sh` deletes remote refs
+# on this answer and a deleted ref is not re-creatable.
+#
+# AND `pr_open` HAS NO OP TO CALL AT ALL. It needs found/none/unaskable about
+# ANY open PR; `pr-state` answers about ONE — the newest — and reports a failed
+# lookup with the same `state:"NONE"` payload as a real absence. It can express
+# neither "any" nor "unaskable".
+#
+# THE COST WAS MEASURED TOO, and it is the smaller objection. Ten sequential
+# calls on this machine: 4.75 s direct, 9.25 s through the adapter — +450 ms per
+# branch, from the connector's slot and budget accounting rather than from the
+# spawn. Across the 48 branches the fleet scan walks that is ~21 s. Real, but it
+# is the correctness gap above that decides this, not the clock.
+#
+# Both halves are pinned in `test/reconcile/host.test.mjs`, so the exemption
+# rests on tests that fail when it stops being true.
+#
+# `mergedAt` IS READ, NEVER `state`. A merged PR reports state CLOSED, and
+# trusting `state` would refuse every squash-merged branch — which is the whole
+# population these scripts exist for. Squash-merge rewrites the commits, so the
+# branch stays "ahead of main" forever and ancestry alone can never clear it.
+#
+# AND THE QUESTION IS "ANY", NOT "THE NEWEST". This asked with `--limit 1`
+# until 2026-08-27, which returns only the most recent PR — so a newer,
+# unmerged PR sitting in front of the real merge reported `no merged PR` about
+# a branch whose work was on main. Measured that day against the live host:
+#
+#   an-unreachable-host-says-so         newest #473 null → real merge #446
+#   the-scan-sees-a-stale-sprint-tally  newest #464 null → real merge #463
+#   a-plan-cites-a-jira-key             newest #476 null → real merge #447
+#
+# The masking PRs were ones the fleet opened ITSELF on already-merged waves,
+# which closes a loop: a leftover worktree lets auto-dispatch adopt a merged
+# branch, its worker opens a duplicate, the duplicate is newer, the reaper
+# keeps the worktree — the input to step one. Reading only the newest PR is the
+# SAME error as reading `state`, one level out: the newest PR is not the merge,
+# just as the state is not the merge.
+#
+# 100 rather than unbounded: `gh` has no "all" sentinel, and this runs on paths
+# where the estate may hold dozens of branches. A branch carrying more than 100
+# PRs whose only merge is the oldest would still be missed — a far narrower
+# window than "any duplicate at all", and it fails SAFE, toward keeping.
+
+# Where the rule lives, resolved from THIS file rather than from the cwd.
+#
+# Both callers run with their cwd wherever the operator invoked them, and the
+# reconcile suite runs them against sandbox repos in the temp directory. The
+# artifact sits beside this script in the plot checkout and in the published
+# npm package alike, which is why both are vendored together.
+_plot_landed_mjs="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/board/plot-landed.mjs"
+
+# Ask the rule about one branch's two lookups.
+#
+# $1=merged reading, $2=open reading, both `found`/`none`/`unaskable`.
+# Prints the rule's two words; returns non-zero when it could not be asked at
+# all, which every caller below reads as the refusing direction.
+_plot_landed() {
+  [ -f "$_plot_landed_mjs" ] || return 1
+  printf '%s\t%s\n' "$1" "$2" | node "$_plot_landed_mjs" 2>/dev/null
+}
+
+# What the host says about ANY PR on this branch: found / none / unaskable.
+#
+# A MISSING CLI, AN UNAUTHED ONE AND A NETWORK FAILURE ARE ALL `unaskable`, and
+# they are not `none`. The whole rule turns on that difference — a lookup that
+# ran and matched nothing is the host speaking, while a lookup that did not run
+# is silence, and silence is never permission.
+_plot_merged_lookup() {
+  local br="$1" out
+  command -v gh >/dev/null 2>&1 || { echo unaskable; return; }
+  out=$(gh pr list --head "$br" --state all --limit 100 --json mergedAt 2>/dev/null) \
+    || { echo unaskable; return; }
+  case "$out" in *'"mergedAt":"'*) echo found ;; *) echo none ;; esac
+}
+
+# What the host says about an OPEN PR on this branch: found / none / unaskable.
+_plot_open_lookup() {
+  local br="$1" out
+  command -v gh >/dev/null 2>&1 || { echo unaskable; return; }
+  out=$(gh pr list --head "$br" --state open --limit 1 --json number 2>/dev/null) \
+    || { echo unaskable; return; }
+  case "$out" in *'"number"'*) echo found ;; *) echo none ;; esac
+}
+
+# Did the host merge ANY PR for this branch?
+#
+# Returns 0 (merged) / 1 (not merged, or the host cannot be asked). The failure
+# direction is deliberate and load-bearing: an unreachable host, an unauthed
+# `gh`, a missing CLI all answer "not merged", so every caller KEEPS what it
+# was considering removing. Silence is never permission.
+#
+# The rule answers `unknown` on that silence and this function reports it as a
+# refusal, which is the same contract the four callers were written against —
+# `plot-reap.sh:385` says so explicitly. A rule that cannot be reached at all
+# refuses here too, for the same reason.
+pr_merged() {
+  local answer
+  answer=$(_plot_landed "$(_plot_merged_lookup "$1")" none) || return 1
+  case "$answer" in landed*) return 0 ;; *) return 1 ;; esac
+}
+
+# Does the branch have an OPEN PR right now?
+#
+# A DIFFERENT question from `pr_merged`, and it exists for a case measured by
+# hand on 2026-08-28. `changeset-release/main` is merged — repeatedly — and
+# Changesets RECREATES and reuses the very same branch for the next release.
+# Its ref carries a live release PR while an older PR of its own has merged, so
+# the merged gate alone says "delete" about a branch somebody is actively
+# using.
+#
+# So an open PR VETOES a deletion even where an older one merged. That is
+# strictly narrower than the merge gate rather than a second opinion on it: it
+# can only ever keep a ref, never release one.
+#
+# Returns 0 when an open PR exists. An unreachable host returns 1 — and note
+# that this is the SAME direction as `pr_merged`'s failure, but it has the
+# OPPOSITE effect, since this answer vetoes. The safety therefore does not come
+# from this function: it comes from `pr_merged` already having refused on the
+# same silence, so a host that cannot be asked deletes nothing regardless.
+# `mayRemove` is where that pair is now asserted rather than described.
+pr_open() {
+  local answer
+  answer=$(_plot_landed none "$(_plot_open_lookup "$1")") || return 1
+  case "$answer" in *"	open-pr") return 0 ;; *) return 1 ;; esac
+}

package/plot-reap.sh

@@ -18,6 +18,15 @@
 # whose agent never existed, and 2 dirty desks holding 52 and 1 files that
 # every run refused and nothing ever resolved.
 #
+# AND ONE THING IT ONLY REPORTS: a worktree git lists whose directory is gone.
+# `git worktree list --porcelain` calls it `prunable`, and it is NOT a sixth
+# refusal. A refusal says *do not remove this* and sends an operator to look; a
+# vanished entry says *there is nothing to remove and the entry is stale*, with
+# `git worktree prune` as the repair. It is reported before the refusals are
+# asked, because it is the prior question: four of the five measure something
+# inside a tree that is not there. Measured 2026-09-06 on this estate, 3 of 20
+# worktrees were prunable and this script named none of them.
+#
 # EVERY KIND KEEPS ONE SHAPE: `--dry-run` by default, acting on `--yes`,
 # bounded by `--max N`. The bound is PER KIND, because the kinds are different
 # acts on different populations — a run bounded to five worktrees has not
@@ -317,12 +326,41 @@ manifest_for() {
   return 1
 }
 
-reap=0; kept=0; removed=0; cleared=0
+reap=0; kept=0; removed=0; cleared=0; vanished=0
 printf '%-8s %-52s %s\n' "verdict" "branch" "why"
 
-while IFS=$'\t' read -r wt br; do
+while IFS=$'\t' read -r wt br prunable; do
   [ -n "$wt" ] || continue
   short=${br#refs/heads/}
+  [ "$wt" = "$ROOT" ] && continue
+
+  # 4a. GIT'S OWN ANSWER THAT THE DIRECTORY IS GONE, and it is a REPORT rather
+  #     than a sixth refusal. The five below each say *do not remove this* and
+  #     send an operator to look; this says *there is nothing to remove and the
+  #     entry is stale*, and names the repair. Blurring the two would tell
+  #     somebody to go and inspect a directory that is not there.
+  #
+  #     IT IS ASKED FIRST because it is the PRIOR question. Four of the five
+  #     refusals measure something inside the tree — a pid file, a marker, the
+  #     porcelain status, the checked-out branch — and every one of them is
+  #     unanswerable here. `rules/reapable.ts` says the same thing in the
+  #     domain: a `vanished` tree makes those four conditions `unknown`.
+  #
+  #     AND IT IS ASKED BEFORE THE DISPATCH-TREE FILTER, which would otherwise
+  #     hide exactly this population. That filter accepts a tree by its
+  #     `.plot-worker.pid` file or its legacy `plot-wt-` path — and a vanished
+  #     desk under `Worktree root` has neither, the pid file having gone with
+  #     the directory. Measured 2026-09-06: 3 of 20 worktrees here were
+  #     prunable and the reaper reported none of them.
+  #
+  #     NOTHING IS PRUNED ON THIS PATH. The reading came from the listing the
+  #     loop already makes, no `git` call was added for it, and whether to
+  #     prune stays the operator's decision — the same discipline that makes
+  #     every refusal a measurement rather than an act.
+  if [ "$prunable" = "yes" ]; then
+    printf '%-8s %-52s %s\n' "vanished" "$short" "directory gone — 'git worktree prune' clears the entry"
+    vanished=$((vanished+1)); continue
+  fi
 
   # 5. Only dispatch trees. A hand-made worktree and the main checkout are not
   #    this script's to remove, whatever state they are in.
@@ -346,7 +384,6 @@ while IFS=$'\t' read -r wt br; do
   if [ ! -f "$wt/.plot-worker.pid" ]; then
     case "$wt" in *"/plot-wt-"*) ;; *) continue ;; esac
   fi
-  [ "$wt" = "$ROOT" ] && continue
 
   # THE READINGS. Everything from here to the rule call MEASURES; nothing
   # decides. Each of the four sources that can answer is read once, into a
@@ -514,7 +551,10 @@ NODE_EOF
     fi
   fi
 done < <(git worktree list --porcelain \
-          | awk '/^worktree /{p=$2} /^branch /{print p"\t"$2}')
+          | awk '/^worktree /{ if (br != "") print p"\t"br"\t"pr; p=$2; br=""; pr="no"; next }
+                 /^branch /  { br=$2; next }
+                 /^prunable/ { pr="yes"; next }
+                 END         { if (br != "") print p"\t"br"\t"pr }')
 
 [ "$DRY" -eq 0 ] && git worktree prune 2>/dev/null
 
@@ -900,5 +940,5 @@ fi
 # which is why `plot-release-refs.sh` deletes those, plan-scoped, under its own
 # licence and its own five guards. The asymmetry between the kinds is the whole
 # safety argument and it stays.
-echo "summary: reapable=$reap removed=$removed kept=$kept cleared=$cleared branches=$swept_branches branches_deleted=$deleted_branches branches_kept=$kept_branches claims=$swept_claims claims_deleted=$deleted_claims claims_kept=$kept_claims dirty_trees=$dirty_trees dry_run=$DRY"
+echo "summary: reapable=$reap removed=$removed kept=$kept vanished=$vanished cleared=$cleared branches=$swept_branches branches_deleted=$deleted_branches branches_kept=$kept_branches claims=$swept_claims claims_deleted=$deleted_claims claims_kept=$kept_claims dirty_trees=$dirty_trees dry_run=$DRY"
 exit 0

package/plot-release-refs.sh

@@ -44,6 +44,35 @@
 #   4. a branch checked out in ANY worktree         (somebody is reading it)
 #   5. the default branch itself                    (never ours to delete)
 #
+# THE SCRIPT DOES NOT OWN THE FIVE. They are conditions in
+# `packages/domain/src/rules/reapable.ts`'s `finishedWith`, which states every
+# condition that can hold a desk and judges none of them. This script and
+# `plot-reap.sh` were asking about the same desk in two places, and they had
+# already drifted: this one never asked whether a worker was alive, and the
+# reaper never asked `pr_open`. Each was blind to a condition the other
+# measured, and neither omission was argued for anywhere.
+#
+# WHAT CHANGED IS WHERE THE CONDITIONS ARE STATED, NOT WHICH ONES THIS SCRIPT
+# ASKS. The rule also answers `liveWorker`, `uncommittedChanges` and
+# `blockedMarker` — the reaper's three — and this script reads none of them.
+# Folding them in *"would silently widen a licence that was written narrow on
+# purpose"*, which is what line 30 above has warned since this script existed.
+# The rule makes the difference VISIBLE; making it disappear is a different
+# change, and it is not this one.
+#
+# `unknown` PERMITS HERE, AND THAT IS THE CALLER'S HALF. Four of the rule's
+# conditions need a worktree and 69% of branches have none (22 of 32, measured
+# 2026-09-06), so the rule answers `unknown` rather than inventing `false`. The
+# reaper reads `unknown` as *nothing to reap*; this reads it as *no evidence
+# against deletion*, which is exactly what it did before the rule existed.
+# Refusing on silence is the estate's rule for an unreachable HOST — applied to
+# a missing tree it would keep every ref on two branches in three and make this
+# script useless where the scan cost is highest.
+#
+# The SCOPE is still this script's and is not shared. The rule answers about
+# one branch and enumerates nothing; which branches to ask about stays bounded
+# by the plan file, for the reason the paragraph above gives.
+#
 # THE RULE THIS MUST NOT BREAK. `/plot-implement` says plainly: *"leave the ref
 # in place — never delete a remote ref another session may be reading."* Read in
 # context that rule governs GIVING A BRANCH UP — work that turned out
@@ -65,7 +94,7 @@ while [ $# -gt 0 ]; do
     --yes) DRY=0 ;;
     --dry-run) DRY=1 ;;
     --max) MAX="${2:-0}"; shift ;;
-    -h|--help) sed -n '2,60p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    -h|--help) sed -n '2,86p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
     -*) echo "plot-release-refs: unknown argument: $1" >&2; exit 2 ;;
     *) slug="$1" ;;
   esac
@@ -115,7 +144,17 @@ prefix_re=$(bash "$script_dir/plot-config.sh" get "Branch prefixes" "idea/, feat
 meta=$(bash "$script_dir/plot-plan-meta.sh" --prefixes "$prefix_re" "$plan_file" 2>/dev/null) || meta=""
 [ -n "$meta" ] || die "cannot parse '$plan_file' — refusing rather than guessing"
 
-# The default branch, via the host adapter when it can answer. Guard 5 compares
+# The shared rule, resolved from THIS SCRIPT's location rather than the cwd, and
+# as a `file://` URL because `import()` needs one for an absolute path. Missing
+# or unreadable, the decision below reports "could not be asked" and keeps every
+# ref — the same fail-safe `plot-reap.sh` applies to the same module.
+#
+# THIS SCRIPT NOW NEEDS NODE. The alternative is a second implementation of the
+# guards living in shell where nothing can test it, which is what this branch
+# exists to end: the two copies had already drifted apart by three readings.
+RULE_PATH="file://$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." 2>/dev/null && pwd)/packages/domain/src/rules/reapable.ts"
+
+# The default branch, via the host adapter when it can answer. The rule compares
 # against it, and a wrong answer here can only ever protect MORE.
 HOST="$script_dir/plot-host.sh"
 DEFAULT=main
@@ -123,18 +162,31 @@ if [ -x "$HOST" ]; then
   d=$("$HOST" default-branch 2>/dev/null) && [ -n "$d" ] && DEFAULT="$d"
 fi
 
-# Every branch currently checked out ANYWHERE, for guard 4.
+# Every branch currently checked out ANYWHERE, WITH THE TREE THAT HOLDS IT.
 #
 # Collected once, before the loop, rather than asked per branch: `git worktree
 # list` walks the whole estate and this script runs on the delivery path where
 # that estate may hold dozens of trees. The answer cannot change underneath a
 # single run in a way that matters — a worktree created mid-run holds a branch
 # whose ref this run has not yet reached, and the next run sees it.
+#
+# THE TREE'S STATE IS COLLECTED TOO, and that is what the shared rule needed.
+# `finishedWith` answers four conditions from a worktree, and it answers them
+# `unknown` where there is none — so it has to be told whether one was found.
+# That is a reading, not a refusal: this script asks none of those four, and
+# passing the tree is what lets the rule say `unknown` instead of inventing
+# `false`. Git's own `prunable` distinguishes a listed tree whose directory is
+# gone from one that was never made; both are unaskable, and the rule keeps the
+# two words apart because an operator acts on them differently.
 checked_out=$(git worktree list --porcelain 2>/dev/null \
-                | sed -n 's|^branch refs/heads/||p')
+                | awk '/^worktree /{wt=substr($0,10); pr="no"}
+                       /^prunable/{pr="yes"}
+                       /^branch refs\/heads\//{print substr($0,19) "\t" wt "\t" pr}')
 
-is_checked_out() {
-  printf '%s\n' "$checked_out" | grep -qxF "$1"
+# The worktree holding a branch and whether git calls it prunable, or empty
+# when no tree holds it.
+worktree_of() {
+  printf '%s\n' "$checked_out" | awk -F'\t' -v b="$1" '$1 == b {print $2 "\t" $3; exit}'
 }
 
 released=0; kept=0; deleted=0
@@ -149,51 +201,141 @@ printf '%-8s %-52s %s\n' "verdict" "branch" "why"
 while IFS=$'\t' read -r br deferred; do
   [ -n "$br" ] || continue
 
-  # 5. The default branch is never ours to delete, whatever a plan says. A plan
-  #    that names it is malformed, and acting on that is unrecoverable.
-  if [ "$br" = "$DEFAULT" ]; then
-    printf '%-8s %-52s %s\n' "keep" "$br" "the default branch — never deleted"
-    kept=$((kept+1)); continue
-  fi
+  # THE READINGS, each taken once and none judged here. The script holds no
+  # `if` about whether a ref may go — only about which conditions it asks and
+  # what to do with the answers.
+  #
+  # `pr_merged` reads `mergedAt` on ANY PR (never `state`, never ancestry) and
+  # answers false when the host cannot be asked, so silence keeps the ref.
+  # `pr_open` is asked separately rather than derived from it: a branch carries
+  # both, and `changeset-release/main` is the measured case.
+  merge=not-merged
+  pr_merged "$br" && merge=merged
 
-  # 1. Given up, not finished. A `deferred:`/`moved:` annotation is what
-  #    `/plot-reconcile` reads to tell deliberate abandonment from a dead
-  #    worker, and it needs the REF to be there to read it against. Checked
-  #    before the host is even asked: this is a decision a person already
-  #    recorded, and no merge state overturns it.
-  if [ "$deferred" = "true" ]; then
-    printf '%-8s %-52s %s\n' "keep" "$br" "deferred — a given-up branch keeps its ref"
-    kept=$((kept+1)); continue
-  fi
+  open_pr=false
+  pr_open "$br" && open_pr=true
 
-  # 2. THE GATE. Unlanded work keeps its ref, always — `Done when` item 12, and
-  #    the assertion a naive implementation passes without, since a sweep that
-  #    deletes every ref of a delivered plan satisfies item 11 and destroys
-  #    work that exists nowhere else. `pr_merged` also returns false when the
-  #    host cannot be asked, so silence keeps the ref.
-  if ! pr_merged "$br"; then
-    printf '%-8s %-52s %s\n' "keep" "$br" "unlanded work — no merged PR"
-    kept=$((kept+1)); continue
+  # WHETHER A TREE HOLDS THE BRANCH, AND IN WHAT STATE. Three words, because
+  # the rule answers its four tree-sourced conditions `unknown` without one and
+  # `unknown` is a reading rather than a failure. `vanished` is git's own
+  # `prunable`: it reads like `absent` to every condition — there is equally
+  # nothing to measure — and stays a separate word because `git worktree prune`
+  # is the repair for one and not the other.
+  #
+  # NOTHING INSIDE THE TREE IS READ. A live pid, an uncommitted file and a
+  # `PLOT-BLOCKED` marker are the reaper's three conditions and this script
+  # asks none of them; measuring them here would put a refusal within one edit's
+  # reach of a licence written narrow on purpose. A checked-out branch keeps its
+  # ref whatever is going on inside it, which is guard 4 and needs no reading
+  # from the tree at all.
+  wt_line=$(worktree_of "$br")
+  wt=${wt_line%%$'\t'*}
+  prunable=${wt_line#*$'\t'}
+  tree=absent
+  if [ -n "$wt" ]; then
+    if [ "$prunable" = "yes" ] || [ ! -d "$wt" ]; then tree=vanished; else tree=present; fi
   fi
 
-  # 3. An OPEN PR vetoes, even where an older PR merged. Measured by hand on
-  #    2026-08-28: `changeset-release/main` is merged repeatedly, and Changesets
-  #    RECREATES and reuses that same branch for the next release — so its ref
-  #    carries a live release PR while an older PR of its own has merged.
-  #    Deleting it disturbs the release in flight.
-  if pr_open "$br"; then
-    printf '%-8s %-52s %s\n' "keep" "$br" "an open PR is using this branch"
-    kept=$((kept+1)); continue
-  fi
+  # THE DECISION. `packages/domain/src/rules/reapable.ts`, imported directly —
+  # the same shape and the same reason as `plot-reap.sh`: node 24 strips the
+  # types, so there is no build step between this script and the rule, and the
+  # JS arrives on STDIN from a QUOTED heredoc so the shell expands none of it.
+  #
+  # ONE RULE, TWO CALLERS, AND THE CALLERS STAY DIFFERENT. `finishedWith`
+  # STATES every condition that can hold a desk and JUDGES none of them; which
+  # conditions refuse a ref is this caller's half, and it names exactly the five
+  # this script has always asked. The reaper reads the same rule and names its
+  # own. Neither script gains the other's, which is what makes the difference
+  # visible instead of eliminating it.
+  #
+  # `unknown` PERMITS, AND THE ORDER OF THE TESTS IS THE ARGUMENT. Only the
+  # first two conditions are answerable without a tree, and 69% of branches have
+  # none. `=== "true"` is therefore the test at every guard: `unknown` falls
+  # through, exactly as this script behaved before the rule existed. That is
+  # deliberate and it is the caller's decision to make — the reaper reads the
+  # same `unknown` as *nothing to reap*.
+  #
+  # A rule that cannot be asked REFUSES: node missing, the import failing, the
+  # module throwing all leave `verdict` empty, and an empty verdict keeps the
+  # ref and says why. Silence is never permission on this path either — that is
+  # the module being absent, which is not the same reading as a condition
+  # answering `unknown`.
+  verdict=$(PLOT_BRANCH="$br" PLOT_DEFAULT="$DEFAULT" PLOT_MERGE="$merge" \
+            PLOT_GIVEN_UP="$deferred" PLOT_OPEN_PR="$open_pr" \
+            PLOT_TREE="$tree" \
+            PLOT_CHECKED_OUT="$([ -n "$wt" ] && echo true || echo false)" \
+            PLOT_RULE="$RULE_PATH" \
+            node --input-type=module - <<'NODE_EOF' 2>/dev/null
+// An ABSOLUTE path derived from this script, never from the cwd: this runs
+// wherever the operator invoked it, and the reconcile suite runs it against
+// sandbox repos in the temp directory.
+//
+// NO APOSTROPHE MAY APPEAR ANYWHERE IN THIS BLOCK. bash 3.2 is /bin/bash on
+// macOS, and it is what the reconcile suite runs this script under when it
+// strips PATH. It parses the body of a quoted heredoc nested inside `$(...)`,
+// so one contraction opens a string that never closes and the whole file fails
+// to parse. The error reads `unexpected EOF` and names a line 30 further down,
+// which points nowhere near the apostrophe.
+const { finishedWith } = await import(process.env.PLOT_RULE);
+
+const held = finishedWith({
+  branch: process.env.PLOT_BRANCH,
+  defaultBranch: process.env.PLOT_DEFAULT,
+  // This script never looks at the main checkout as a tree; the branch test
+  // the rule makes is what catches the default branch.
+  isMain: false,
+  // The three the reaper measures and this script does not. They are passed
+  // empty because the rule shape asks for them, and the tree reading below is
+  // what makes them honest: with no tree they answer `unknown`, and this
+  // caller reads none of the three either way.
+  workerPid: null,
+  dirtyPath: "",
+  blockedMarker: false,
+  merge: process.env.PLOT_MERGE,
+  givenUp: process.env.PLOT_GIVEN_UP === "true",
+  openPr: process.env.PLOT_OPEN_PR === "true",
+  checkedOut: process.env.PLOT_CHECKED_OUT === "true",
+  tree: process.env.PLOT_TREE,
+});
+
+// THE FIVE GUARDS, in the order they have always been tested, and each
+// satisfied only by a condition answering `true`. `unknown` permits: it means
+// no evidence against deletion, which on this estate is the majority reading
+// and the one the script already acted on. `liveWorker`, `uncommittedChanges`
+// and `blockedMarker` are in `held` and are deliberately not consulted.
+const guards = [
+  ["given-up", held.givenUp, ""],
+  ["no-merged-pr", held.noMergedPr, ""],
+  ["open-pr", held.openPr, ""],
+  ["checked-out", held.checkedOut, ""],
+  ["on-default-branch", held.onDefaultBranch, process.env.PLOT_DEFAULT],
+];
+
+const refusal = guards.find(([, reading]) => reading === "true");
+
+process.stdout.write(refusal === undefined ? "delete\t" : `${refusal[0]}\t${refusal[2]}`);
+NODE_EOF
+  )
+
+  refusal=${verdict%%$'\t'*}
+  detail=${verdict#*$'\t'}
 
-  # 4. A ref another checkout is sitting on is one somebody is reading, and
-  #    deleting it pulls the branch out from under them. Measured 2026-08-28:
-  #    `bug/a-head-counts-its-own-waves` was merged AND checked out. This runs
-  #    after the reap, so a worktree still here is one the reaper's own five
-  #    measurements declined to remove — its verdict is inherited, not
-  #    second-guessed.
-  if is_checked_out "$br"; then
-    printf '%-8s %-52s %s\n' "keep" "$br" "checked out in a worktree — somebody is reading it"
+  if [ "$refusal" != "delete" ]; then
+    # The rule named the refusal; this renders it. A verdict the rule could not
+    # produce is empty, and an empty refusal keeps the ref and says so.
+    case "$refusal" in
+      given-up)            why="deferred — a given-up branch keeps its ref" ;;
+      no-merged-pr)        why="unlanded work — no merged PR" ;;
+      open-pr)             why="an open PR is using this branch" ;;
+      checked-out)         why="checked out in a worktree — somebody is reading it" ;;
+      on-default-branch)   why="the default branch — never deleted" ;;
+      # No arm for `live-worker`, `uncommitted-changes` or `blocked-marker`.
+      # The rule answers all three and this script consults none, so none can
+      # reach here; an arm for one would be the first line of a licence this
+      # script does not hold.
+      *)                   why="the rule could not be asked — keeping the ref" ;;
+    esac
+    printf '%-8s %-52s %s\n' "keep" "$br" "$why"
     kept=$((kept+1)); continue
   fi