@plot-pm/board 0.9.0 → 0.10.0

package/plot-plan-meta.sh

@@ -37,7 +37,7 @@
 # A file with neither is reported as format "none" (pre-plot / legacy plan).
 #
 # The IMPLEMENTATION section (which branches, in which waves, with which PRs)
-# has TWO spellings, and this parser reads both:
+# has THREE spellings, and this parser reads all of them:
 #
 #   ## Branches  (old)   the branch rides the list line, meta mixed with prose:
 #                            ### Removed
@@ -47,6 +47,14 @@
 #                            ### Removed (Branch: bug/foo, PR: #300)
 #                            - loses its half
 #
+#   ## Slices            the design-spec word for the same shape as `## Waves`,
+#                        read by the same handler. A Slice holds one branch and
+#                        belongs to one plan; a Wave is the fleet cohort that
+#                        spans plans. The section here was always the former, so
+#                        `## Slices` is the accurate name and `## Waves` is the
+#                        one 132 delivered plans already carry. No plan is
+#                        rewritten: both are read, forever if need be.
+#
 # Both emit the SAME branches/prs/waves arrays. The new shape is the format Plot
 # writes and documents; the old one is kept readable because a format change owes
 # its estate a migration that moves files one at a time, and a plan moved one
@@ -95,8 +103,9 @@
 #   branches       branch names, sorted and unique, read from EITHER spelling:
 #                  the old `## Branches` section (a LIST ITEM whose first token
 #                  is the backtick-quoted name, matching the known prefixes) OR
-#                  the new `## Waves` section (`Branch:` in a `### ` heading —
-#                  see below). A backticked branch name anywhere else under
+#                  the new `## Waves` / `## Slices` section (`Branch:` in a
+#                  `### ` heading — see below). A backticked branch name
+#                  anywhere else under
 #                  `## Branches` — mid-sentence, in a blockquote, in a comment,
 #                  on a wrapped continuation line — is a CITATION and claims
 #                  nothing: plans name each other branches to declare
@@ -658,7 +667,14 @@ in_fence { next }
   # does. A plan carries one or the other — but the parser reads both while the
   # migration moves 85 files, so a file moved one commit early never reads
   # as silently empty.
-  else if ($0 ~ /^## Waves/) { section = waves_seen ? "" : "waves"; waves_seen = 1 }
+  # `## Slices` is the spelling the design spec uses, and `## Waves` is what 132
+  # plans already say. They are ONE section here, sharing waves_seen, because the
+  # shape is identical: the branch and PR ride the `### ` heading either way. A
+  # third arm would be a second implementation of a re-spelling, and the two
+  # would drift. No existing plan is rewritten to say Slices — a delivered plan
+  # describes what was built in the vocabulary of its day, and churning 132
+  # files git blame for a word buys nothing. New plans may use either.
+  else if ($0 ~ /^## Waves/ || $0 ~ /^## Slices/) { section = waves_seen ? "" : "waves"; waves_seen = 1 }
   else if ($0 ~ /^## Approval/) section = "approval"
   # First `## Changelog` wins, for the same reason `## Branches` does: a plan
   # about the plan format quotes the section in prose, and the later heading is

package/plot-reap.sh

@@ -0,0 +1,286 @@
+#!/usr/bin/env bash
+# Remove worktrees whose work has landed, their dead worker files, and the
+# registry manifests that named them.
+#
+# The gap this fills was named by a comment before it existed:
+# `plot-reconcile-scan.sh:323` says "with a deferred: annotation the reaper
+# would offer to DELETE real work" — describing a reaper that was never
+# written. The scan reports; nothing reaped. Measured 2026-08-25 on this
+# estate: 56 worktrees, 42 of them dispatch trees, of which 29 were finished.
+#
+# WHY A SCRIPT RATHER THAN AN AGENT (Manifesto Principle 3, and the licence
+# `plot-resolve-artifact.sh` states for the one other automatic write): every
+# refusal below is a MEASUREMENT, not a judgement. Is a process alive; is the
+# tree dirty; did the host merge the PR. An agent asked "is this safe to
+# delete?" can talk itself past any of the three. A script cannot, and
+# judgement's absence is exactly what licenses the delete.
+#
+# DEFAULT IS --dry-run. Removal happens only under --yes.
+#
+#   plot-reap.sh                # report what WOULD be reaped
+#   plot-reap.sh --yes          # actually remove them
+#   plot-reap.sh --yes --max 5  # bound it
+#
+# What is NEVER reaped, in the order the tests run:
+#   1. a worktree with a LIVE worker process        (a desk someone is at)
+#   2. a worktree with uncommitted changes           (work that exists nowhere else)
+#   3. a worktree carrying a PLOT-BLOCKED* marker    (a worker waiting on a person)
+#   4. a branch NO PR of which merged                (the host is the authority)
+#   5. the main checkout, and any non-dispatch tree  (not ours to remove)
+#
+# THE MANIFEST GOES WITH THE WORKTREE. `readAgentRegistry` renders one row per
+# manifest, so a reap that removes only the checkout converts a finished agent
+# into an `unknown` row naming a directory that no longer exists — measured
+# 2026-08-26, twelve worktrees removed and seven such rows appearing at once.
+# Nothing further needs deciding to remove it: an entry whose worktree the five
+# tests above just cleared is covered by exactly those measurements.
+#
+# ORDER: worktree FIRST, manifest second. The reverse leaves a live worktree
+# with no registration, which `readAgentRegistry` answers by SYNTHESIZING an
+# `unknown` entry — the same bad row, earned a different way. A failure between
+# the two steps this way round leaves an orphaned manifest, which the sweep
+# below clears on the next run.
+set -u
+
+DRY=1; MAX=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --yes) DRY=0 ;;
+    --dry-run) DRY=1 ;;
+    --max) MAX="${2:-0}"; shift ;;
+    -h|--help) sed -n '2,42p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *) echo "plot-reap: unknown argument: $1" >&2; exit 2 ;;
+  esac
+  shift
+done
+
+command -v git >/dev/null 2>&1 || { echo "plot-reap: git not found" >&2; exit 2; }
+ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || {
+  echo "plot-reap: not a git repository" >&2; exit 2; }
+
+# The default branch, via the host adapter when it can answer and `main`
+# otherwise. A wrong answer here would only ever make the ancestry test MORE
+# conservative, never less.
+HOST="$(dirname "${BASH_SOURCE[0]}")/plot-host.sh"
+DEFAULT=main
+if [ -x "$HOST" ]; then
+  d=$("$HOST" default-branch 2>/dev/null) && [ -n "$d" ] && DEFAULT="$d"
+fi
+git fetch origin "$DEFAULT" --quiet 2>/dev/null || true
+
+# Does the host say ANY PR for this branch merged?
+#
+# SOURCED from `plot-pr-merged.sh` rather than defined here, since 2026-08-28.
+# It lived in this file until `plot-release-refs.sh` needed the SAME gate: both
+# scripts ask "has this branch's work landed", and a second implementation that
+# drifted toward permissive would delete a ref that cannot be restored. The
+# helper carries the reasoning — `mergedAt` never `state`, ANY PR never the
+# newest — and defines `pr_merged` and nothing else on load.
+. "$(dirname "${BASH_SOURCE[0]}")/plot-pr-merged.sh"
+
+# Where the registry lives, resolved through `plot-config.sh` — the SAME key and
+# default the board's reader uses (`resolveManifestDir` in `registry.ts` shells
+# out to exactly this). Two implementations of "where is the registry" is how
+# they drift, so this asks the config rather than hard-coding `.plot/agents`: a
+# project whose board is served from another checkout points the key elsewhere,
+# and a reaper writing to the wrong directory would report success over a
+# manifest the board still renders.
+# Tested with -r, not -x: the helper is invoked through `bash "$CONFIG"`, which
+# needs the file READABLE and not executable. `-x` would silently fall back to
+# the default on a checkout whose exec bits did not survive — and a reaper
+# reading the wrong directory reports success over a manifest the board still
+# renders, which is exactly the failure #420 fixed on the board's own side.
+CONFIG="$(dirname "${BASH_SOURCE[0]}")/plot-config.sh"
+MANIFEST_DIR=".plot/agents"
+if [ -r "$CONFIG" ]; then
+  d=$(bash "$CONFIG" get "Agent registry" ".plot/agents" 2>/dev/null) && [ -n "$d" ] && MANIFEST_DIR="$d"
+fi
+case "$MANIFEST_DIR" in /*) ;; *) MANIFEST_DIR="$ROOT/$MANIFEST_DIR" ;; esac
+
+# The manifest naming a given worktree, or nothing.
+#
+# Manifests are keyed by SESSION id, not by branch, so the file cannot be
+# derived from the worktree path — it is found by reading the `worktree` field
+# out of each one. The match is on the exact recorded path: a prefix match would
+# let `plot-wt-foo` claim `plot-wt-foo-bar`'s manifest.
+#
+# Parsed with `sed`, not a JSON reader, deliberately — this script must run
+# where node does not, and the field it needs is one flat string written by the
+# dispatcher. A manifest whose `worktree` cannot be read simply does not match,
+# which keeps an unparseable file OUT of the removal set rather than in it.
+# A path with its symlinks resolved, or the path unchanged when it does not
+# exist (nothing to resolve, and the caller still needs a string to compare).
+#
+# NOT cosmetic. `git worktree list` reports RESOLVED paths, while a manifest
+# records whatever the dispatcher was handed — and on macOS `/tmp`, `/var` and
+# `/etc` are symlinks into `/private`, so the same directory arrives as two
+# different strings. Measured while writing this: a worktree git called
+# `/private/var/.../repo` against a manifest saying `/var/.../repo`, matching
+# nothing and stranding the manifest the reap was supposed to take.
+canonical() {
+  local p="$1"
+  [ -n "$p" ] || return 0
+  # Resolve through the filesystem while the directory is still there — the
+  # authoritative answer, and the only one that handles an arbitrary symlink.
+  if [ -d "$p" ]; then
+    p=$( (cd "$p" 2>/dev/null && pwd -P) || printf '%s' "$p" )
+  fi
+  # Then normalise the macOS `/private` prefix TEXTUALLY, because the manifest
+  # side is compared AFTER its directory has been removed and there is no
+  # longer anything to resolve. `/tmp`, `/var` and `/etc` are symlinks into
+  # `/private`, so git's `/private/var/...` and a manifest's `/var/...` name
+  # one directory; stripping the prefix from both makes them one string
+  # whether or not either still exists.
+  case "$p" in
+    /private/tmp/*|/private/var/*|/private/etc/*) p=${p#/private} ;;
+  esac
+  printf '%s\n' "$p"
+}
+
+manifest_for() {
+  local target="$1" f wt
+  [ -d "$MANIFEST_DIR" ] || return 1
+  target=$(canonical "$target")
+  for f in "$MANIFEST_DIR"/*.json; do
+    [ -f "$f" ] || continue
+    wt=$(sed -n 's/.*"worktree"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$f" | head -1)
+    [ -n "$wt" ] || continue
+    [ "$(canonical "$wt")" = "$target" ] && { printf '%s\n' "$f"; return 0; }
+  done
+  return 1
+}
+
+reap=0; kept=0; removed=0; cleared=0
+printf '%-8s %-52s %s\n' "verdict" "branch" "why"
+
+while IFS=$'\t' read -r wt br; do
+  [ -n "$wt" ] || continue
+  short=${br#refs/heads/}
+
+  # 5. Only dispatch trees. A hand-made worktree and the main checkout are not
+  #    this script's to remove, whatever state they are in.
+  case "$wt" in *"/plot-wt-"*) ;; *) continue ;; esac
+  [ "$wt" = "$ROOT" ] && continue
+
+  # 1. A live worker outranks every other signal. Checked FIRST because it is
+  #    the only one describing a person or process acting right now.
+  if [ -f "$wt/.plot-worker.pid" ]; then
+    pid=$(cat "$wt/.plot-worker.pid" 2>/dev/null)
+    if [ -n "$pid" ] && ps -p "$pid" >/dev/null 2>&1; then
+      printf '%-8s %-52s %s\n' "keep" "$short" "worker alive (pid $pid)"; kept=$((kept+1)); continue
+    fi
+  fi
+
+  # 3. A marker means a worker stopped to ask a person something. Reaping it
+  #    discards the question along with the tree.
+  if ls "$wt"/PLOT-BLOCKED* >/dev/null 2>&1; then
+    printf '%-8s %-52s %s\n' "keep" "$short" "PLOT-BLOCKED marker — needs a person"; kept=$((kept+1)); continue
+  fi
+
+  # 2. Uncommitted work exists in exactly one place. The tiny-garden pulse is
+  #    excused because every board suite rewrites it — a worker that did
+  #    nothing but run the tests would otherwise never be reapable. Any OTHER
+  #    dirty path still keeps the tree, which is what keeps this an exception
+  #    rather than a hole.
+  dirty=$(git -C "$wt" status --porcelain 2>/dev/null \
+            | grep -v 'tiny-garden/\.plot/state' | head -1)
+  if [ -n "$dirty" ]; then
+    printf '%-8s %-52s %s\n' "keep" "$short" "uncommitted: ${dirty:0:40}"; kept=$((kept+1)); continue
+  fi
+
+  # 4a. A tree sitting ON the default branch answers the ancestry test
+  #     trivially — `origin/main..main` is empty — and would be reaped with the
+  #     reason "merged into main", which says nothing about the work it was
+  #     dispatched for. Measured here 2026-08-25: one dispatch tree had been
+  #     left on `main` by its worker, and the first draft of this script
+  #     offered to reap it for a reason that was true and irrelevant.
+  #
+  #     It is KEPT and named. Deleting a tree whose dispatched branch is no
+  #     longer checked out means deleting something whose state was never
+  #     measured — and "probably fine" is the judgement this script exists to
+  #     not make.
+  if [ "$short" = "$DEFAULT" ]; then
+    printf '%-8s %-52s %s\n' "keep" "$short" "on $DEFAULT — dispatched branch not checked out"
+    kept=$((kept+1)); continue
+  fi
+
+  # 4b. Landed, by either route: ancestry for a merge commit, the host for a
+  #     squash. Ancestry is tried first because it needs no network.
+  why=""
+  if [ -n "$short" ] && [ "$(git -C "$wt" rev-list --count "origin/$DEFAULT..$short" 2>/dev/null || echo 1)" = "0" ]; then
+    why="merged into $DEFAULT"
+  elif [ -n "$short" ] && pr_merged "$short"; then
+    why="PR merged (squash)"
+  else
+    printf '%-8s %-52s %s\n' "keep" "$short" "unlanded work — no merged PR"; kept=$((kept+1)); continue
+  fi
+
+  if [ "$MAX" -gt 0 ] && [ "$reap" -ge "$MAX" ]; then
+    printf '%-8s %-52s %s\n' "keep" "$short" "--max $MAX reached"; kept=$((kept+1)); continue
+  fi
+
+  # Resolved BEFORE the removal, because `canonical` needs the directory to
+  # still exist to resolve it. After `git worktree remove` there is nothing to
+  # follow, and the manifest's spelling would never converge with git's.
+  wt_real=$(canonical "$wt")
+
+  reap=$((reap+1))
+  if [ "$DRY" -eq 1 ]; then
+    printf '%-8s %-52s %s\n' "would" "$short" "$why"
+  else
+    if git worktree remove --force "$wt" 2>/dev/null; then
+      # The worktree is gone; NOW the manifest may go. Inside the success arm
+      # and nowhere else — a manifest removed before a removal that then
+      # refuses leaves a live worktree unregistered, which the registry answers
+      # by synthesizing an `unknown` row. Failing this way round strands a
+      # manifest instead, which the sweep below clears.
+      if m=$(manifest_for "$wt_real"); then
+        rm -f "$m" && why="$why, manifest cleared"
+      fi
+      printf '%-8s %-52s %s\n' "reaped" "$short" "$why"; removed=$((removed+1))
+    else
+      printf '%-8s %-52s %s\n' "FAILED" "$short" "git worktree remove refused"; kept=$((kept+1))
+    fi
+  fi
+done < <(git worktree list --porcelain \
+          | awk '/^worktree /{p=$2} /^branch /{print p"\t"$2}')
+
+[ "$DRY" -eq 0 ] && git worktree prune 2>/dev/null
+
+# The manifests whose worktree is ALREADY gone.
+#
+# Every reap before this script learned about the registry left one, and the
+# board renders each as an `unknown` row naming a directory that does not
+# exist. They are the population this plan was written from — seven of them,
+# measured 2026-08-26 — and a fix that only stops NEW ones leaves those on the
+# board forever.
+#
+# The predicate is the same one the loop above satisfies by construction: the
+# recorded worktree is not there. It needs no PR check and no liveness check —
+# nothing runs in a directory that does not exist, which is the strongest
+# evidence of "dead" available, not the weakest.
+#
+# A manifest recording NO worktree path is left alone: it names an agent
+# between checkouts, and absence of a path is not absence of an agent.
+if [ -d "$MANIFEST_DIR" ]; then
+  for m in "$MANIFEST_DIR"/*.json; do
+    [ -f "$m" ] || continue
+    mwt=$(sed -n 's/.*"worktree"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$m" | head -1)
+    [ -n "$mwt" ] || continue
+    [ -d "$mwt" ] && continue
+    cleared=$((cleared+1))
+    if [ "$DRY" -eq 1 ]; then
+      printf '%-8s %-52s %s\n' "would" "$(basename "${mwt}")" "orphaned manifest — worktree absent"
+    else
+      rm -f "$m"
+      printf '%-8s %-52s %s\n' "cleared" "$(basename "${mwt}")" "orphaned manifest — worktree absent"
+    fi
+  done
+fi
+
+# The branches and refs are untouched, deliberately: this removes CHECKOUTS and
+# the registrations that named them. A reaped tree is re-creatable with
+# `git worktree add`, so the destructive act is bounded to disk space and to a
+# record of an agent that has already finished — never to history.
+echo "summary: reapable=$reap removed=$removed kept=$kept cleared=$cleared dry_run=$DRY"
+exit 0

package/plot-release-refs.sh

@@ -0,0 +1,234 @@
+#!/usr/bin/env bash
+# Delete the REMOTE REFS of a delivered plan's merged branches.
+#
+# Usage: plot-release-refs.sh [--yes] [--max N] <slug>
+#
+#   <slug>   the plan whose branches to release
+#   --yes    actually delete; without it this reports and deletes nothing
+#   --max N  bound the number of deletions
+#
+# WHY THIS EXISTS: branches are what the scan actually costs. Measured
+# 2026-08-27 across four runs of the fleet scan:
+#
+#   worktrees  branches  scan
+#   54         43        462.9 s
+#   42         43         51.3 s
+#   11         43        218.5 s
+#   11         34        111.5 s
+#
+# Worktree count does not order those runs — 11 worktrees was SLOWER than 42.
+# What moved reliably was deleting nine merged branches: 218.5 s → 111.5 s,
+# roughly halving it. The estate the scan walks is branches, and merged ones
+# are pure cost. Reaping clears desks; this is what the scan notices.
+#
+# WHY A SEPARATE SCRIPT AND NOT PART OF `plot-reap.sh`. The reaper ends by
+# saying what it is: "the branches and refs are untouched, deliberately — this
+# removes CHECKOUTS... A reaped tree is re-creatable with `git worktree add`,
+# so the destructive act is bounded to disk space... never to history." That is
+# a stated LICENCE, and it does not extend here. A deleted ref is not
+# re-creatable, so this act needs its own argument, its own guards and its own
+# `--yes`. Folding it into the reaper would silently widen a licence that was
+# written narrow on purpose.
+#
+# It is also SCOPED TO ONE PLAN, where the reaper is deliberately slug-blind.
+# The reaper sweeps every worktree because a checkout is cheap to restore; this
+# touches only the branches its plan names. A sweep that deleted every merged
+# ref on the estate would satisfy "a delivered plan's merged branches lose
+# their refs" and destroy unlanded work belonging to plans nobody delivered.
+# The blast radius is bounded by the plan file.
+#
+# WHAT IS NEVER DELETED, in the order the tests run:
+#   1. a branch annotated `deferred:` or `moved:`   (given up, not finished)
+#   2. a branch NO PR of which merged               (unlanded work)
+#   3. a branch with an OPEN PR                     (changeset-release/main)
+#   4. a branch checked out in ANY worktree         (somebody is reading it)
+#   5. the default branch itself                    (never ours to delete)
+#
+# 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
+# unnecessary, wrongly cut, or blocked — and its reason is that
+# `/plot-reconcile` needs the ref PLUS its `deferred:`/`moved:` annotation to
+# tell deliberate abandonment from a dead worker.
+#
+# A branch whose PR merged is neither abandoned nor ambiguous: its work is on
+# main, its PR is closed, and there is nothing for `/plot-reconcile` to resolve.
+# The rule protects UNLANDED refs, and this touches only landed ones. Guards 1
+# and 2 are that reconciliation, enforced.
+set -u
+
+script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+
+DRY=1; MAX=0; slug=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --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 ;;
+    -*) echo "plot-release-refs: unknown argument: $1" >&2; exit 2 ;;
+    *) slug="$1" ;;
+  esac
+  shift
+done
+
+die() { echo "plot-release-refs: $*" >&2; exit 2; }
+
+[ -n "$slug" ] || die "need a plan slug (usage: plot-release-refs.sh [--yes] <slug>)"
+command -v git >/dev/null 2>&1 || die "git not found"
+git rev-parse --git-dir >/dev/null 2>&1 || die "not a git repository"
+
+# The SAME gate the reaper uses, sourced rather than re-derived. `pr_merged`
+# reads `mergedAt` on ANY PR (never `state`, never ancestry); `pr_open` answers
+# the veto in guard 3.
+. "$script_dir/plot-pr-merged.sh"
+
+cfg() { bash "$script_dir/plot-config.sh" get "$1" "$2"; }
+
+PLAN_DIR=$(cfg "Plan directory" "docs/plans/")
+ACTIVE_DIR=$(cfg "Active index" "docs/plans/active/")
+DELIVERED_DIR=$(cfg "Delivered index" "docs/plans/delivered/")
+
+# The plan is resolved exactly as `plot-deliver.sh` resolves it, including the
+# `delivered/` directory — which is not incidental. This runs AFTER a delivery,
+# so by the time it looks the symlink has already moved, and a resolver that
+# knew only `active/` would find nothing for every plan it is called about.
+plan_file=""
+for cand in "$PLAN_DIR"*"$slug".md "$ACTIVE_DIR$slug.md" "$DELIVERED_DIR$slug.md"; do
+  [ -e "$cand" ] && { plan_file="$cand"; break; }
+done
+[ -n "$plan_file" ] || die "no plan found for '$slug' — looked in $PLAN_DIR, $ACTIVE_DIR, $DELIVERED_DIR"
+
+# The prefixes come from `Branch prefixes`, never a hardcoded list — the same
+# derivation `plot-deliver.sh:144` and `plot-fleet-scan.sh:187` use. Without it
+# this reads the parser's built-in default, and a project with its own prefixes
+# would have EVERY branch of a plan silently disappear before the loop: the
+# script would report `releasable=0` and look like it had nothing to do. That
+# exact bug cost `plot-deliver.sh` four undeliverable plans on 2026-08-27.
+#
+# It fails safe (nothing is deleted) and is wrong all the same, and being wrong
+# quietly is what makes it worth passing explicitly.
+prefix_re=$(bash "$script_dir/plot-config.sh" get "Branch prefixes" "idea/, feature/, bug/, docs/, infra/" \
+  | tr -d ' ' | tr ',' '\n' | sed 's#/$##' | grep -v '^$' | paste -sd'|' - )
+[ -n "$prefix_re" ] || prefix_re="idea|feature|bug|docs|infra"
+
+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
+# against it, and a wrong answer here can only ever protect MORE.
+HOST="$script_dir/plot-host.sh"
+DEFAULT=main
+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.
+#
+# 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.
+checked_out=$(git worktree list --porcelain 2>/dev/null \
+                | sed -n 's|^branch refs/heads/||p')
+
+is_checked_out() {
+  printf '%s\n' "$checked_out" | grep -qxF "$1"
+}
+
+released=0; kept=0; deleted=0
+printf '%-8s %-52s %s\n' "verdict" "branch" "why"
+
+# Branch and its deferred flag, one per line, from the plan's own parser.
+#
+# `plot-plan-meta.sh` is the plan-format contract, and asking it rather than
+# grepping the file is what keeps this working across both plan dialects —
+# `## Branches` lists and `## Waves` headings — without this script knowing
+# which one it is reading.
+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
+
+  # 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
+
+  # 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
+  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
+
+  # 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"
+    kept=$((kept+1)); continue
+  fi
+
+  if [ "$MAX" -gt 0 ] && [ "$released" -ge "$MAX" ]; then
+    printf '%-8s %-52s %s\n' "keep" "$br" "--max $MAX reached"
+    kept=$((kept+1)); continue
+  fi
+
+  released=$((released+1))
+  if [ "$DRY" -eq 1 ]; then
+    printf '%-8s %-52s %s\n' "would" "$br" "merged — ref would be deleted"
+  else
+    # The REMOTE ref only. The local branch is left alone deliberately: it costs
+    # the scan nothing (the scan derives from `origin/<branch>`), and a local
+    # branch is the last copy of a reflog somebody may still want.
+    if git push origin --delete "$br" >/dev/null 2>&1; then
+      printf '%-8s %-52s %s\n' "released" "$br" "merged — remote ref deleted"
+      deleted=$((deleted+1))
+    else
+      # A ref already gone is the common case on a re-run, and it is a SUCCESS
+      # for this script's purpose: the end state asked for is the ref's absence.
+      if git ls-remote --exit-code --heads origin "$br" >/dev/null 2>&1; then
+        printf '%-8s %-52s %s\n' "FAILED" "$br" "git push --delete refused"
+        kept=$((kept+1))
+      else
+        printf '%-8s %-52s %s\n' "released" "$br" "remote ref already absent"
+        deleted=$((deleted+1))
+      fi
+    fi
+  fi
+done < <(printf '%s' "$meta" | jq -r '
+  ([.waves[]?.branches[]?] as $w
+   | if ($w | length) > 0 then $w
+     else [.branches[]? | {branch: ., deferred: false}] end)
+  | .[] | [.branch, (.deferred | tostring)] | @tsv' 2>/dev/null)
+
+echo "summary: releasable=$released deleted=$deleted kept=$kept dry_run=$DRY"
+exit 0