@plot-pm/board 0.8.1 → 0.9.1

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

package/plot-resolve-artifact.sh

@@ -0,0 +1,334 @@
+#!/usr/bin/env bash
+# Plot helper: repair an ARTIFACT-ONLY merge conflict on one branch.
+# Usage: plot-resolve-artifact.sh [--dry-run] <branch>
+#   --dry-run   print the sequence and the worktree it would use; change nothing
+#   <branch>    the branch to repair — must already exist on origin
+# Output: one `step:` line per stage, then a machine-countable footer:
+#     summary: branch=<name> outcome=pushed|abandoned|refused reason=<word>
+#
+# THE ONLY AUTOMATIC WRITE THIS SYSTEM GRANTS, and it is granted for three
+# verified reasons rather than for convenience:
+#
+#   1. `-merge` KEEPS THE FILE VALID. `.gitattributes` marks the artifact
+#      `-merge`, so git keeps one side whole and writes NO conflict markers.
+#      The artifact stays buildable JavaScript *through* a conflict — which is
+#      why a script may touch it at all.
+#   2. THE REBUILD IS DETERMINISTIC. Measured: `build.mjs` embeds no timestamp
+#      and no randomness, so the output does not depend on which side was kept.
+#   3. CI PROVES IT. The no-diff gate fails the build if the committed artifact
+#      does not match a fresh rebuild.
+#
+# Together those make this the one repair whose correctness is checkable
+# WITHOUT JUDGEMENT. That is the whole licence. No other failure has these
+# three properties, and none may be added to this path — widening the entry
+# condition removes the argument that grants the permission, even if the code
+# looks correct.
+#
+# THIS IS A SCRIPT AND NOT AN AGENT, deliberately. Every step below is fixed
+# and nothing between them is a decision, which is *precisely* what licenses the
+# automation. Handing the sequence to an agent would introduce judgement exactly
+# where its absence is the permission. (Measured on 2026-08-17: this repo has no
+# `Worker command` configured either, so plot-dispatch.sh would report
+# `worker=unconfigured` and start nothing — but the shape is the reason, not
+# the measurement.)
+#
+# TESTS RUN BEFORE THE PUSH. The CI no-diff gate is what makes the repair
+# checkable, and CI runs only AFTER a push — so a resolver that pushed and
+# waited would manufacture exactly the state this exists to remove: a red PR in
+# the queue. The sequence therefore ends on `pnpm run test:board` green in the
+# branch's own worktree, and CI becomes confirmation rather than discovery.
+#
+# IF THE SUITE FAILS, NOTHING IS PUSHED. The repair stopped being mechanical the
+# moment its own gate said so; the branch is left exactly as it was, and the
+# board reports it as a conflict a human owns.
+#
+# IT MERGES ONLY IN A WORKTREE THAT IS IDLE. A worktree carrying modifications
+# belongs to whoever made them — measured on 2026-08-17, the resolver ran its
+# merge inside one an agent was actively editing. It refuses `worktree-busy`
+# rather than reaching in, which the plan names the honest minimum: a second
+# worktree on the same branch is not available to it anyway, since git refuses a
+# second checkout of one branch.
+#
+# AN EMPTY CONFLICT SET IS NOT A REFUSAL ABOUT FILES. Three cases, named apart,
+# because two of them were once one:
+#
+#   exactly the artifact  → the licensed case                    → repair
+#   other files present   → needs judgement                      → not-artifact-only
+#   empty, no merge ran   → nothing was observed                 → not-observed
+#
+# The last is not a smaller version of the middle. `not-artifact-only` asserts
+# something about the files that conflicted, and a set of zero has none to
+# assert it about — saying it there sends a reader to look for files nobody ever
+# examined.
+#
+# WHICH SIDE IS TAKEN CANNOT MATTER, and the diff is never read. `--theirs` is
+# named here only because `git checkout` needs a word: the rebuild overwrites
+# whichever side was kept. Never phrase it as "take ours" — under `git merge`
+# *ours* is the branch being merged into, under `git rebase` it is the upstream,
+# and this repo rebases routinely.
+set -uo pipefail
+
+script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+
+# The one file this script may resolve. Named here as well as in the board's
+# contract because the two run in different languages and neither can import
+# the other's constant; the pairing is asserted by a test rather than trusted.
+ARTIFACT_PATH="skills/plot/scripts/board/board-server.mjs"
+
+dry_run=0
+branch=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --dry-run) dry_run=1 ;;
+    -*) echo "plot-resolve-artifact: unknown option '$1'" >&2; exit 2 ;;
+    *) branch="$1" ;;
+  esac
+  shift
+done
+
+# The footer travels on EVERY exit path, including the refusals. A run that
+# ends without one is indistinguishable from a crash, and a silent automatic
+# write is the failure mode this whole plan exists to remove.
+finish() { # $1=outcome $2=reason
+  echo "summary: branch=$branch outcome=$1 reason=$2"
+  case "$1" in
+    pushed) exit 0 ;;
+    *) exit 1 ;;
+  esac
+}
+
+[ -n "$branch" ] || { echo "usage: plot-resolve-artifact.sh [--dry-run] <branch>" >&2; exit 2; }
+
+git rev-parse --git-dir >/dev/null 2>&1 || {
+  echo "plot-resolve-artifact: not a git repository" >&2
+  finish refused not-a-repo
+}
+
+MAIN=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's#^origin/##')
+[ -n "$MAIN" ] || MAIN="main"
+
+repo_root=$(git rev-parse --show-toplevel)
+
+# WHICH WORKTREE HOLDS THIS BRANCH — ASK GIT, do not reconstruct the path from
+# the branch name.
+#
+# MEASURED, and recorded at length in plot-dispatch.sh's held_worktree: a
+# hand-made worktree is named for the branch with its TYPE dropped, so a gate
+# that guessed `plot-wt-<flattened>` missed a worktree with six modified files
+# in it. This site had the same shape — it composed `plot-wt-<flattened>` under
+# `repo_root/..` — and this change would make the guess worse, not better: the
+# new `Worktree root:` key introduces a SECOND naming convention, giving a
+# path guess a second way to be wrong. So the read asks git, and only the
+# CREATE-a-fresh-one fallback below composes a name (via dispatch's rule, so the
+# fresh worktree lands where dispatch would have put it).
+#
+# `git worktree list --porcelain` emits `worktree <path>` then `branch
+# refs/heads/<name>` per entry; the branch line is matched and the path taken
+# from the preceding one. A branch already dispatched is thus repaired in the
+# worktree it is already checked out in rather than in a second copy of itself —
+# git refuses a second checkout of one branch, and the two would fight over the
+# same index if it did not.
+wt=$(git worktree list --porcelain </dev/null 2>/dev/null | awk -v want="refs/heads/$branch" '
+  /^worktree /  { path = substr($0, 10) }
+  /^branch /    { if (substr($0, 8) == want) { print path; exit } }')
+
+# No existing worktree holds it — compose the path a fresh one will take, by the
+# same root+prefix rule plot-dispatch.sh uses. Under a `Worktree root:` key the
+# root moves and the `plot-wt-` prefix drops; absent it, today's behaviour.
+if [ -z "$wt" ]; then
+  wt_root=$("$script_dir/plot-config.sh" get "Worktree root" "")
+  if [ -z "$wt_root" ]; then
+    wt_root=$(cd "$repo_root/.." && pwd)
+    wt="$wt_root/plot-wt-$(printf '%s' "$branch" | tr '/' '-')"
+  else
+    case "$wt_root" in
+      /*) : ;;
+      *)  wt_root="$repo_root/$wt_root" ;;
+    esac
+    wt="${wt_root%/}/$(printf '%s' "$branch" | tr '/' '-')"
+  fi
+fi
+
+if [ "$dry_run" = 1 ]; then
+  echo "step: would use worktree $wt"
+  echo "step: would merge origin/$MAIN, take a side of $ARTIFACT_PATH, rebuild, test"
+  echo "step: would push only if pnpm run test:board passes"
+  finish refused dry-run
+fi
+
+git fetch -q origin "$MAIN" "$branch" 2>/dev/null || true
+
+# ONE REPAIR AT A TIME, AND NEVER TWO ON ONE BRANCH.
+#
+# A second run while the first is working would fight over the same worktree:
+# the merge, the rebuild and the five-minute suite all write into it, and two of
+# them interleaved produce an artifact belonging to neither run. The lock is a
+# DIRECTORY rather than a file because `mkdir` is atomic on every filesystem
+# this runs on — two processes racing it, one wins, and the loser learns it lost
+# from the exit code rather than from a check-then-write that both pass.
+#
+# The board guards its own in-flight repairs too, in memory. Both are needed and
+# neither is redundant: the board's registry cannot see a repair started by a
+# second board or by a human at a shell, and this lock cannot stop the board
+# from spawning (it learns only after the spawn). The lock is the authority.
+lock="$repo_root/.plot/state/resolve-$(printf '%s' "$branch" | tr '/' '-').lock"
+mkdir -p "$(dirname "$lock")" 2>/dev/null || true
+if ! mkdir "$lock" 2>/dev/null; then
+  echo "step: a repair is already in flight for $branch ($lock)"
+  finish refused already-in-flight
+fi
+# Released on every exit, including a kill. A lock that outlives its process
+# would make one interrupted repair block the branch forever — and the repair is
+# idempotent, so there is nothing to protect after the process is gone.
+trap 'rmdir "$lock" 2>/dev/null || true' EXIT INT TERM
+
+if [ -d "$wt" ] && git worktree list --porcelain | grep -qx "worktree $wt"; then
+  # A REUSED WORKTREE MAY BELONG TO SOMEONE ELSE, and on 2026-08-17 one did: the
+  # resolver ran `git merge` inside a worktree an agent was actively editing —
+  # zero unmerged paths, three modified files, work in progress. It refused
+  # before writing anything, but that was luck rather than design.
+  #
+  # Reuse is right when the worktree is IDLE; the name alone does not say so. A
+  # worktree with modifications is one whose owner is mid-thought, and merging
+  # into it would either fail on "local changes would be overwritten" or, worse,
+  # succeed and fold a stranger's uncommitted work into a merge commit this
+  # script then pushes.
+  #
+  # The honest minimum is to refuse, and the plan names it acceptable: creating a
+  # scratch worktree is impossible anyway while git holds this branch checked out
+  # here, since git refuses a second checkout of one branch.
+  #
+  # `--porcelain` rather than a parsed `git status`: it is the stable interface,
+  # and an untracked file is deliberately NOT counted — a stray log or an
+  # editor's scratch file is not work in progress, and `merge` does not touch it.
+  echo "step: reusing worktree $wt"
+  busy=$(git -C "$wt" status --porcelain --untracked-files=no 2>/dev/null)
+  if [ -n "$busy" ]; then
+    echo "step: worktree has modifications that are not this repair's — refusing"
+    printf 'step: modified: %s\n' "$(printf '%s' "$busy" | sed 's/^...//' | tr '\n' ' ')"
+    finish refused worktree-busy
+  fi
+else
+  if ! git worktree add -q "$wt" "$branch" 2>/dev/null; then
+    if ! git worktree add -q -b "$branch" "$wt" "origin/$branch" 2>/dev/null; then
+      echo "plot-resolve-artifact: cannot create a worktree for $branch at $wt" >&2
+      finish refused no-worktree
+    fi
+  fi
+  echo "step: worktree $wt"
+fi
+
+# THE FIXED SEQUENCE. Five steps, no decision between them.
+
+# 1. Merge. The conflict is EXPECTED — that is why we are here — so a non-zero
+#    exit is not yet a failure. What decides is which paths came back
+#    unmerged, checked next.
+git -C "$wt" merge --no-edit "origin/$MAIN" >/dev/null 2>&1
+merge_status=$?
+
+if [ "$merge_status" -eq 0 ]; then
+  # Nothing conflicted after all — the prediction was made from refs that have
+  # since moved, which is the direction this repo already knows they move in.
+  # The merge stands; there is nothing to repair and nothing to prove, so this
+  # pushes nothing rather than pushing a merge nobody asked for.
+  git -C "$wt" merge --abort >/dev/null 2>&1 || true
+  git -C "$wt" reset -q --hard "HEAD" >/dev/null 2>&1 || true
+  echo "step: no conflict on merge — nothing to repair"
+  finish refused no-conflict
+fi
+
+# 2. VERIFY THE SET, HERE, AGAINST THE REAL MERGE.
+#
+# The board classified from `merge-tree`, which predicts IN MEMORY from the refs
+# this machine holds. This is the merge itself, and it is the only place the set
+# is a fact rather than a forecast — a stale ref makes the prediction wrong in
+# the reassuring direction, so the entry condition is re-checked against reality
+# before anything is written.
+#
+# The set is read once and asked TWO questions, in order: was anything observed
+# at all, and — only then — was it exactly the artifact.
+unmerged=$(git -C "$wt" diff --name-only --diff-filter=U)
+n_unmerged=$(printf '%s\n' "$unmerged" | grep -c . || true)
+
+# AN EMPTY SET IS NOT A SMALL SET — it is the absence of a reading.
+#
+# The merge exited non-zero, so something went wrong; but a conflict is not the
+# only thing that ends a merge non-zero. A merge that never STARTED — refused
+# because the worktree was dirty, because a merge was already in progress, or
+# because the ref could not be resolved — exits non-zero too and leaves no
+# unmerged paths behind. Zero paths therefore answers a different question than
+# one or three do: those say WHICH files conflicted, zero says NOBODY LOOKED.
+#
+# Measured on 2026-08-17, and the defect this branch exists for: the resolver
+# reused a worktree in which no merge was running, read zero paths, compared
+# zero against one, and reported `not-artifact-only` — a name asserting
+# something about files it had never examined. The refusal was right; its reason
+# was wrong, and the wrong reason sent a reader looking for conflicts that did
+# not exist.
+#
+# So the two refusals are named apart. `not-artifact-only` is a claim about an
+# observed set and may only be said when there was one.
+if [ "$n_unmerged" = "0" ]; then
+  git -C "$wt" merge --abort >/dev/null 2>&1 || true
+  echo "step: the merge reported failure but left no unmerged paths — nothing was observed"
+  finish refused not-observed
+fi
+
+# EXACTLY the artifact: one path, that path, nothing else. Not "the artifact
+# among the conflicts" — an implementation asking that passes every
+# artifact-only case and silently repairs merges that need judgement as a whole.
+if [ "$n_unmerged" != "1" ] || [ "$unmerged" != "$ARTIFACT_PATH" ]; then
+  git -C "$wt" merge --abort >/dev/null 2>&1 || true
+  echo "step: conflict set is not exactly the artifact — refusing"
+  printf 'step: unmerged: %s\n' "$(printf '%s' "$unmerged" | tr '\n' ' ')"
+  finish refused not-artifact-only
+fi
+
+# 3. Take a side. WHICH SIDE CANNOT MATTER — the rebuild overwrites it — and the
+#    diff is never read. `--theirs` because the command needs a word.
+git -C "$wt" checkout --theirs -- "$ARTIFACT_PATH" 2>/dev/null \
+  || git -C "$wt" checkout --ours -- "$ARTIFACT_PATH" 2>/dev/null \
+  || true
+git -C "$wt" add -- "$ARTIFACT_PATH" 2>/dev/null || true
+echo "step: took a side of $ARTIFACT_PATH (either — the rebuild decides)"
+
+# 4. Rebuild, in the branch's OWN worktree. This is what makes the kept side
+#    irrelevant, and it is the property CI's no-diff gate then re-checks.
+if ! (cd "$wt" && pnpm build:board >/dev/null 2>&1); then
+  git -C "$wt" merge --abort >/dev/null 2>&1 || true
+  echo "step: rebuild failed — pushing nothing"
+  finish abandoned build-failed
+fi
+git -C "$wt" add -- "$ARTIFACT_PATH" 2>/dev/null || true
+echo "step: rebuilt $ARTIFACT_PATH"
+
+# The merge commit exists only once the rebuild has produced the artifact it
+# will carry. Committing before the build would leave a commit holding a stale
+# artifact if the build then failed — exactly what CI's no-diff gate catches,
+# arriving as a push instead of as a refusal.
+if ! git -C "$wt" commit -q --no-edit 2>/dev/null; then
+  echo "step: nothing to commit after the rebuild"
+  finish abandoned nothing-to-commit
+fi
+
+# 5. THE GATE. Green in this worktree BEFORE the push, never CI after it.
+#    A resolver that pushed and let CI decide passes every correctness check
+#    above and manufactures a red PR in the queue — the exact stuck state this
+#    plan exists to remove.
+echo "step: running pnpm run test:board"
+if ! (cd "$wt" && pnpm run test:board >/dev/null 2>&1); then
+  # NOTHING IS PUSHED, and the merge is undone so the branch is left exactly as
+  # it was found. A half-repaired branch would be a third state nobody named.
+  git -C "$wt" reset -q --hard "HEAD~1" 2>/dev/null || true
+  echo "step: test:board failed — pushing nothing, this is a conflict a human owns"
+  finish abandoned tests-failed
+fi
+echo "step: test:board passed"
+
+if ! git -C "$wt" push -q origin "HEAD:$branch" 2>/dev/null; then
+  echo "step: push rejected — the branch moved under us; leaving the repair local"
+  finish abandoned push-failed
+fi
+
+echo "step: pushed $branch"
+finish pushed artifact-conflict-resolved