@plot-pm/board 0.16.2 → 0.17.0

package/plot-deliver.sh

@@ -1,744 +1,13 @@
 #!/usr/bin/env bash
-# Plot helper: perform the MECHANICAL half of delivering a plan.
-# Usage: plot-deliver.sh [--dry-run] [--who <name>] <slug>
-#   --dry-run   say what would happen; write nothing, push nothing
-#   --who       the name recorded in the `Delivered:` line (default: git user.name)
-#   <slug>      the plan to deliver
-# Output: one `step:` line per step, then a machine-countable summary:
-#             summary: phase=flipped record=written index=moved sprint=updated push=clean tracker=none
-#         `tracker=` is plot-issue-status.sh's outcome (none|written|no-target|
-#         unaskable|failed), or `skipped` when the push was rejected. It never
-#         changes the exit code: a failed status write is reported, not raised.
-#         Exit 0 when the plan is Delivered on the default branch (whether this
-#         run did the work or found it already done); 1 on a refusal or a
-#         failure, with the reason on stderr.
-#
-# WHY THIS EXISTS. The board computes `allSlicesMerged` — exactly the condition
-# that says a plan is ready to deliver — but the transition itself lives only in
-# `/plot-deliver`'s prose. So `Delivered` in the board asked for a caller with
-# nothing safe to call, and an implementer reaching that point would have
-# rebuilt the phase flip, the `Delivered:` record and the symlink move in
-# TypeScript. That is precisely the drift the `plot-approve.sh` split removed.
-#
-# This script is the `plot-approve.sh` of delivery: one implementation, two
-# entrances. `/plot-deliver` keeps the judgement — the completeness check, the
-# partial-deliverable question — and delegates the writes here. The board calls
-# this script directly (or via an agent when a `Deliver command` is set).
-#
-# Manifesto Principle 3 draws the line: SCRIPTS COLLECT AND REPORT; SKILLS
-# INTERPRET AND ADAPT. Flipping a phase and writing a dated record is
-# collecting. Deciding whether PARTIAL work counts as delivered is interpreting,
-# and stays in the skill.
-#
-# IT IS IDEMPOTENT, BECAUSE ONE STEP CANNOT BE UNDONE. The push is irreversible;
-# everything before it is local. A run interrupted between flipping the phase
-# and pushing leaves the plan at `Delivered` in a worktree but still `Approved`
-# on main — so `plot-deliver.sh <slug>` may run any number of times, and RUN IT
-# AGAIN is the repair for every interruption.
-#
-# Each step asks THE SOURCE IT WOULD HAVE WRITTEN whether it is already done:
-# the plan file for the phase and the record, the index directories for the
-# symlink, the sprint file for the tick. Never a progress file of its own.
-#
-# WHAT IT REFUSES, and why refusing beats guessing:
-#   - phase is not `approved` — nothing to deliver. (Already-Delivered is NOT a
-#     refusal: it is the idempotent case, and the run still checks the record
-#     and index.)
-#   - any non-deferred branch is unmerged — work is not done. This is one of
-#     Plot's four phase guardrails, moved from prose into an exit code.
-#
-# macOS bash 3.2 throughout: no associative arrays, no bash-4 line readers.
+# Launcher. The mechanical half of delivering (or releasing) a plan is
+# `board/plot-deliver.mjs`, a JS entry point over the domain — see its header
+# for what it does. This resolves it, passes arguments and the exit code
+# through, and decides nothing.
 set -uo pipefail
-
-script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
-. "$script_dir/plot-tmp.sh"
-
-# The receipt this script leaves for plot-state-gate.sh, which refuses every
-# other writer of a `State:` line. Sourced rather than run: the gate and the
-# three owning scripts must agree on where a receipt lives, and one file is how.
-# shellcheck source=plot-state-receipt.sh
-. "$script_dir/plot-state-receipt.sh"
-
-dry_run=0
-who_override=""
-slug=""
-while [ $# -gt 0 ]; do
-  case "$1" in
-    --dry-run) dry_run=1 ;;
-    --who) who_override="${2:?--who needs a value}"; shift ;;
-    -h|--help) sed -n '2,12p' "$0"; exit 0 ;;
-    -*) echo "plot-deliver: unknown flag '$1'" >&2; exit 1 ;;
-    *) slug="$1" ;;
-  esac
-  shift
-done
-
-die() { echo "plot-deliver: $*" >&2; exit 1; }
-
-[ -n "$slug" ] || die "need a plan slug (usage: plot-deliver.sh [--dry-run] <slug>)"
-git rev-parse --git-dir >/dev/null 2>&1 || die "not a git repository — run this from inside the checkout, or 'git init' one here"
-
-cfg() { bash "$script_dir/plot-config.sh" get "$1" "$2"; }
-
-repo_root=$(git rev-parse --show-toplevel)
-# The booking worktree goes under the desk root of the MAIN checkout, never of
-# this tree: inside a desk `--show-toplevel` answers the desk, and the default
-# `.worktrees` would resolve beneath it. No fallback — `plot-desk-root.sh`.
-# shellcheck source=plot-desk-root.sh
-. "$script_dir/plot-desk-root.sh"
-main_root=$(plot_repo_root)
-wt_root=$(plot_desk_root "$main_root") || die "cannot resolve where the booking worktree goes (see above)"
-
-PLAN_DIR=$(cfg "Plan directory" "docs/plans/")
-ACTIVE_DIR=$(cfg "Active index" "docs/plans/active/")
-DELIVERED_DIR=$(cfg "Delivered index" "docs/plans/delivered/")
-SPRINT_DIR=$(cfg "Sprint directory" "docs/sprints/")
-
-# ---------------------------------------------------------------------------
-# Step 1 — find the plan and read its state
-# ---------------------------------------------------------------------------
-
-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.
-  Check the slug: ls $PLAN_DIR | grep -i '$slug'"
-
-meta=$(bash "$script_dir/plot-plan-meta.sh" "$plan_file" 2>/dev/null) || meta=""
-[ -n "$meta" ] || die "cannot parse '$plan_file' — refusing rather than guessing.
-  See what the parser reads: $script_dir/plot-plan-meta.sh $plan_file
-  A plan needs a '## Status' section with a 'State:' field."
-
-jfield() { printf '%s' "$meta" | jq -r "$1" 2>/dev/null; }
-
-phase=$(jfield '.phase')
-sprint=$(jfield '.sprint')
-delivered_raw=$(jfield '.delivered_raw')
-
-# --- refusal 1: the phase ---------------------------------------------------
-#
-# `approved` and `delivered` both proceed: Delivered is the idempotent case.
-# A run that finds the phase already flipped still has a record to check, an
-# index link to move, and an annotation to update — the very half-states this
-# script exists to repair.
-case "$phase" in
-  approved|delivered) ;;
-  released)
-    die "plan '$slug' is already released — nothing to deliver.
-  Nothing to do here; the work shipped." ;;
-  draft|design)
-    die "plan '$slug' is still '$phase' — approve it first: /plot-approve $slug" ;;
-  NONE|"")
-    die "cannot read the phase of '$slug' ($plan_file) — refusing rather than guessing.
-  Its '## Status' section needs a line reading '- **State:** Approved'." ;;
-  *)
-    die "plan '$slug' is in phase '$phase' — only an Approved plan can be delivered.
-  If that phase is wrong, correct the 'State:' line in $plan_file and push it." ;;
-esac
-
-# ---------------------------------------------------------------------------
-# Step 2 — ask whether every non-deferred branch has merged
-# ---------------------------------------------------------------------------
-#
-# This is one of Plot's four phase guardrails, and it is NO LONGER DECIDED HERE.
-#
-# THE SCRIPT USED TO PARSE THE PLAN ITSELF. Ninety-odd lines of `sed` and `grep`
-# re-derived the branches section, re-derived which lines named a branch, and
-# re-derived which of those were deferred — a second implementation of a job
-# `plot-plan-meta.sh` already owns, with its own bug history. The measured ones:
-# a `## Changelog` bullet read as a branch (four fully-merged plans undeliverable,
-# 2026-08-27), and a `## Slices` section that parsed to ZERO branches so the gate
-# passed having checked nothing (two approved plans, 2026-08-30).
-#
-# A THIRD was measured while this block was being removed, and it is the one
-# that argues hardest for the removal. On
-# `docs/plans/2026-08-21-waves-name-themselves.md` the old range matched a
-# `## Waves` heading that opens DESIGN PROSE — the plan argues for that spelling
-# and illustrates it — and closed at the next `## `, never reaching the real
-# `## Branches` section a hundred lines below. It read three branch names out of
-# the illustration, one of them `bug/one` from inside a code fence, and reported
-# none of the plan's actual work. `plot-plan-meta.sh` reads the same file
-# correctly. That plan was delivered by hand.
-#
-# So the reading stays in the scripts and the DECISION moves inside:
-# `plot-plan-meta.sh` says which branches the plan names and which it gave up,
-# `plot-impl-status.sh` says which the host merged, and the domain's `deliver`
-# rule says whether that makes the plan deliverable. Manifesto Principle 3 —
-# scripts collect and report — with the line drawn where the design plan draws
-# it: parsing a plan is adaptation, "these branches make the plan deliverable"
-# is a decision.
-#
-# THE REFUSAL SENTENCE COMES BACK FROM THE DOMAIN, unchanged in wording, so the
-# two cannot describe one rule differently.
-
-ask_mjs="$script_dir/board/plot-ask.mjs"
-if [ ! -f "$ask_mjs" ]; then
-  die "cannot find $ask_mjs — run 'pnpm build:board' to build it."
-fi
-
-verdict=$(PLOT_REPO_ROOT="$repo_root" PLOT_SCRIPTS_DIR="$script_dir" \
-  node "$ask_mjs" deliverable "$slug" "$plan_file" 2>/dev/null) || verdict=""
-[ -n "$verdict" ] || die "cannot determine deliverability of '$slug' — refusing rather than guessing.
-  See what it said: PLOT_REPO_ROOT=$repo_root PLOT_SCRIPTS_DIR=$script_dir node $ask_mjs deliverable $slug $plan_file"
-
-vfield() { printf '%s' "$verdict" | jq -r "$1" 2>/dev/null; }
-
-if [ "$(vfield '.deliverable')" != "true" ]; then
-  die "$(vfield '.refusal')"
-fi
-
-# THE FINDING — a slice whose merged PR carried no implementation.
-#
-# IT REPORTS AND DOES NOT REFUSE, which is the harder call and the right one.
-# Measured over the last 60 merged PRs on 2026-09-08, seven carried no work and
-# only TWO were this defect: three were claim PRs whose slice finished under a
-# DIFFERENT PR, and a gate refusing on those would have blocked a delivery whose
-# work was complete — right about the PR and wrong about the plan.
-#
-# So it is worded as a QUESTION and names the next move, because a reader told
-# only "this carried nothing" still has the decision to make.
-empty_slices=$(printf '%s' "$verdict" | jq -r '.emptySlices // [] | .[]' 2>/dev/null)
-if [ -n "$empty_slices" ]; then
-  echo "note: this plan's merged PR carried no implementation on:"
-  while IFS= read -r b; do
-    [ -n "$b" ] || continue
-    echo "  - $b"
-  done <<< "$empty_slices"
-  echo "  check whether its work landed under another PR, mark it deferred"
-  echo "  (<!-- deferred: <reason> -->), or re-open it. Delivery continues."
-fi
-
-merged_count=$(vfield '.merged')
-deferred_count=$(vfield '.deferred')
-# Empty rather than `0`, so the suffix below stays absent where the old block
-# left it absent — `${x:+...}` fires on any non-empty value, and "0 deferred"
-# is a line no run has ever printed.
-[ "$deferred_count" = "0" ] && deferred_count=""
-if [ "$merged_count" = "0" ] && [ -z "$deferred_count" ]; then
-  echo "step: no branches found in plan — proceeding (nothing to verify)"
-else
-  echo "step: verified $merged_count branch(es) merged${deferred_count:+, $deferred_count deferred}"
-fi
-
-MAIN=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's#^origin/##')
-[ -n "$MAIN" ] || MAIN=$(bash "$script_dir/plot-host.sh" default-branch 2>/dev/null) || MAIN=""
-[ -n "$MAIN" ] || MAIN="main"
-
-who="${who_override:-${PLOT_DELIVER_WHO:-$(git config user.name 2>/dev/null || echo plot)}}"
-today=$(date +%Y-%m-%d)
-
-if [ "$dry_run" = 1 ]; then
-  echo "step: would flip Phase → Delivered and fill Delivered: $today"
-  echo "step: would move active/ → delivered/ symlink"
-  echo "step: would tick the sprint item${sprint:+ (sprint: $sprint)}"
-  echo "summary: phase=would record=would index=would sprint=would push=would"
-  exit 0
-fi
-
-# ---------------------------------------------------------------------------
-# Steps 3-6 — the local writes, in a booking worktree off origin/<default>
-# ---------------------------------------------------------------------------
-#
-# A SEPARATE WORKTREE, not a checkout here. The caller's working tree may carry
-# uncommitted work, and switching it out from under them is exactly the write
-# this script otherwise refuses.
-
-# The CANONICAL plan file, not the index symlink.
-real_plan_path() { # $1 = plan file as found
-  local p="$1" d b t
-  d=$(cd "$(dirname "$p")" 2>/dev/null && pwd) || return 1
-  b=$(basename "$p")
-  t=$(readlink "$d/$b" 2>/dev/null || true)
-  if [ -n "$t" ]; then
-    case "$t" in
-      /*) d=$(cd "$(dirname "$t")" 2>/dev/null && pwd) || return 1 ;;
-      *)  d=$(cd "$d/$(dirname "$t")" 2>/dev/null && pwd) || return 1 ;;
-    esac
-    b=$(basename "$t")
-  fi
-  case "$d" in
-    "$repo_root")   printf '%s' "$b" ;;
-    "$repo_root"/*) printf '%s/%s' "${d#$repo_root/}" "$b" ;;
-    *) return 1 ;;
-  esac
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+bundle="$script_dir/board/plot-deliver.mjs"
+[ -f "$bundle" ] || {
+  echo "plot-deliver: cannot find $bundle — update the plot plugin in this repository, or — in the plot repository itself — run: pnpm build:board" >&2
+  exit 2
 }
-
-rel=$(cd "$repo_root" && real_plan_path "$plan_file") || rel=""
-[ -n "$rel" ] || die "$plan_file is outside the repository root ($repo_root).
-  Move the plan under $PLAN_DIR inside this checkout and re-run."
-
-# The filename, for symlink creation.
-plan_basename=$(basename "$rel")
-
-# Flip `**State:** Approved` → `Delivered` in the `## Status` section only.
-# Reads `State:` and `Phase:` alike: it changes the VALUE on whichever line
-# carries it, so a plan written before the 2026-09-07 rename still delivers.
-#
-# READS ONE FILE AND WRITES ANOTHER, rather than editing in place. It edited in
-# place until 2026-09-02, which is what let the phase land without its record —
-# see write_transition() below.
-flip_phase() { # $1=in $2=out  → 0 if it changed the file, 1 if nothing to flip
-  awk '
-    BEGIN { section = ""; done = 0 }
-    /^## / { section = ($0 ~ /^## Status/) ? "status" : ""; print; next }
-    section == "status" && !done && tolower($0) ~ /^[ \t]*[-*]?[ \t]*\**(state|phase)[:*]/ {
-      if (tolower($0) ~ /approved/) {
-        sub(/[Aa]pproved/, "Delivered")
-        done = 1
-        changed = 1
-      }
-    }
-    { print }
-    END { exit (changed ? 0 : 1) }
-  ' "$1" > "$2"
-}
-
-# Insert one `- **Delivered:** YYYY-MM-DD` line into the plan's `## Status` section.
-# Fills the placeholder first; falls back to appending after the last list item.
-#
-# IT STOPS AT AN HTML COMMENT, and that is the whole of the fix made 2026-09-01.
-# The plan template ends `## Status` with
-#
-#     <!-- Transition records — written by the workflow commands, not by hand:
-#     - **Started:** <date>, <who>, <branch>
-#     -->
-#
-# and those `- **Started:**` lines ARE list items. The scan tracked the last one
-# it saw, so on any plan whose `Started:` records had been filled in, the record
-# was appended INSIDE the comment — inert, and invisible to
-# `plot-plan-meta.sh`, which reported `delivered_raw: ""` for a plan that had
-# just been delivered. Measured on `a-browser-test-serves-its-own-state`: phase
-# flipped to Delivered, two `Delivered:` lines written into the comment (the
-# script is idempotent on the PHASE, so a second run wrote a second line), and
-# no readable record at all.
-#
-# A comment is where a plan keeps the shape of a record rather than a record, so
-# the insertion point is the last list item BEFORE one — never inside.
-#
-# READS ONE FILE AND WRITES ANOTHER, for the reason flip_phase() gives.
-append_delivered_line() { # $1=in $2=out $3=record
-  local line
-  line="- **Delivered:** $3"
-  awk -v line="$line" '
-    { lines[++n] = $0 }
-    END {
-      for (i = 1; i <= n; i++) {
-        if (lines[i] ~ /^##[ \t]*[Ss]tatus[ \t]*$/) { start = i; break }
-      }
-      if (!start) exit 1
-
-      insert = start
-      for (i = start + 1; i <= n; i++) {
-        if (lines[i] ~ /^##[ \t]/) break
-        # An HTML comment ends the writable region. Checked BEFORE the
-        # placeholder arms so a commented-out `- **Delivered:**` template line
-        # is never mistaken for the slot to fill.
-        if (lines[i] ~ /<!--/) break
-        if (lines[i] ~ /^[ \t]*[-*][ \t]*\*\*Delivered:\*\*[ \t]*$/) { slot = i; break }
-        if (lines[i] ~ /^[ \t]*[-*][ \t]/) insert = i
-      }
-
-      for (i = 1; i <= n; i++) {
-        if (i == slot) { print line; continue }   # replaces the empty placeholder
-        print lines[i]
-        if (!slot && i == insert) print line
-      }
-    }
-  ' "$1" > "$2"
-}
-
-# ---------------------------------------------------------------------------
-# THE TRANSITION — one value, decided in the domain, written whole or not at all
-# ---------------------------------------------------------------------------
-#
-# WHAT THIS CLOSES. The phase and the record were two independent steps until
-# 2026-09-02: `flip_phase` edited the file, and `append_delivered_line` then
-# edited it again. The second could fail — a plan with no `## Status` heading is
-# its documented refusal — and the first had already landed. That is not
-# theoretical: measured 2026-08-20, a plan carrying `Phase: Delivered` with no
-# `Delivered:` line was filtered out of `plot-fleet-scan.sh` ENTIRELY, which
-# reads its delivered window from `delivered_raw` — the record itself. The scan
-# reported zero plans for it. A phase without its record does not make a plan
-# half-delivered; it makes it invisible.
-#
-# SO THE TWO ARE ONE WRITE. The domain says so in a type: `transitions/plan.ts`
-# gives `Decision` a required `phase` AND a required `record`, so a decision
-# missing either does not compile. `plot-transition.mjs` carries that value out
-# to here, and this function is the half that could still have broken it —
-# both edits run against scratch copies, and the plan file is replaced only
-# once both have succeeded.
-#
-# THE DOMAIN DECIDES, THIS PERFORMS. The phase word and the record's text come
-# back from `plot-transition.mjs`; the awk that knows where a `## Status` line
-# lives stays here, because that is adaptation and it carries bug history worth
-# keeping (the HTML-comment fix above, 2026-09-01).
-#
-# IDEMPOTENCE IS UNCHANGED, and it is still the source that answers. The domain
-# reads the phase and the record THIS SCRIPT PARSED FROM THE FILE IT IS ABOUT TO
-# WRITE, and answers `already` when both are present — the same question the two
-# steps asked separately, asked once. No progress file appears here, because a
-# progress file is exactly what would disagree with the repository when somebody
-# intervened by hand between two runs.
-transition_mjs="$script_dir/board/plot-transition.mjs"
-
-# Ask the domain for the transition, and refuse in its words.
-#
-# Called with the file's OWN parse rather than the caller's: on the booking-
-# worktree flow those are different files, and the plan on the default branch is
-# the one that counts.
-decide_transition() { # $1=file  → prints "<Phase>\t<record>\t<write|already>"
-  local f="$1" m answer rc
-  [ -f "$transition_mjs" ] \
-    || { echo "plot-deliver: cannot find $transition_mjs — run 'pnpm build:board'." >&2; return 1; }
-  m=$(bash "$script_dir/plot-plan-meta.sh" "$f" 2>/dev/null) || m=""
-  [ -n "$m" ] || { echo "plot-deliver: cannot parse $f — refusing rather than guessing." >&2; return 1; }
-  answer=$(printf 'deliver\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t\t\t\n' \
-    "$slug" \
-    "$(printf '%s' "$m" | jq -r '.phase // ""')" \
-    "$(printf '%s' "$m" | jq -r '.review // ""')" \
-    "$(printf '%s' "$m" | jq -r '.approved_raw // ""')" \
-    "$(printf '%s' "$m" | jq -r '.delivered_raw // ""')" \
-    "$(printf '%s' "$m" | jq -r '.released_raw // ""')" \
-    "$today" \
-    | node "$transition_mjs" 2>&1)
-  rc=$?
-  # Exit 1 is the domain's refusal and its sentence, tab-separated after the
-  # rule that fired. Exit 2 is this script handing it something unreadable,
-  # which no operator can act on — so it reports as the bug it is.
-  if [ "$rc" != 0 ]; then
-    if [ "$rc" = 1 ]; then
-      echo "plot-deliver: $(printf '%s' "$answer" | cut -f2-)" >&2
-    else
-      echo "plot-deliver: $answer" >&2
-    fi
-    return 1
-  fi
-  printf '%s' "$answer"
-}
-
-# Apply the decided transition: the phase and the record, or neither.
-#
-# BOTH EDITS RUN AGAINST SCRATCH FILES and the plan is replaced by one `mv`.
-# An `## Status` section that cannot take the record leaves the file exactly as
-# it was found — INCLUDING ITS PHASE — so re-running is still the repair, and
-# the half-state that made a plan invisible cannot be reached from here.
-#
-# `$3` says whether the file already carries the record. A plan can carry one
-# while its phase lags — written by hand, or an earlier run cut between the two
-# writes — and appending a second is how one plan came to hold two `Delivered:`
-# lines (2026-09-01). The domain returns the written record unchanged in that
-# case, so the phase still flips and nothing is inserted.
-# Would the PARSER read this phase out of the file we are about to land?
-#
-# THE WRITE SUCCEEDING IS NOT THE OUTCOME HOLDING, and that gap is #924. A plan
-# carrying BOTH front matter and a `## Status` block was delivered in a project
-# repo: `flip_phase` wrote `Delivered` into the block, `mv` landed it, the
-# summary said `phase=flipped`, and `plot-plan-meta.sh` went on answering
-# `approved` — because it preferred front matter wherever it existed. The write
-# took effect on bytes nobody reads.
-#
-# THAT PRECEDENCE INVERTED IN #933, so the two-record plan now delivers rather
-# than refusing here: the parser reads the `## Status` block, which is the field
-# every lifecycle script writes. This gate is unchanged and is not softened —
-# its condition simply stops holding for that shape. It still fires on a scratch
-# copy the parser cannot read, and it still asks the parser rather than trusting
-# that awk changed a line.
-#
-# `flip_phase`'s awk matches only inside `section == "status"`. That one guard
-# IS the defect: on a front-matter plan it edits the block and leaves the front
-# matter untouched, and returns 0 for having changed something.
-#
-# SO THE TEST IS WHAT THE PARSER ANSWERS, NEVER WHETHER AWK CHANGED A LINE.
-# Refusing on `flipped=0` would break every re-run of a correct delivery — a
-# plan already carrying `Delivered` flips nothing and is fine. This asks the one
-# question that distinguishes them: read the scratch copy the way every later
-# consumer will read the plan, and compare.
-#
-# IT RUNS ON THE SCRATCH COPY, BEFORE THE `mv`, and the caller passes whichever
-# file that arm is about to land — `$a` on the `recorded=yes` arm, `$b` on the
-# other. Parsing `$a` on the record arm would check content that never reaches
-# the plan. After the `mv` is too late twice over: the script's own header
-# documents exit 0 as *"the plan is Delivered on the default branch"*, so
-# refusing there would exit 1 on a run meeting the documented success
-# condition — and `runAutoDeliver` spawns this detached, logging a non-zero exit
-# to nobody while the plan sits delivered on main.
-#
-# AN UNREADABLE SCRATCH COPY REFUSES. `decide_transition` already takes that
-# line — *"refusing rather than guessing"* — and a file the parser cannot read
-# is exactly the state this gate exists to keep off the plan.
-phase_would_read() { # $1=scratch file $2=expected phase (lowercase) → 0 agrees, 1 refuses
-  local scratch="$1" want="$2" m got
-  m=$(bash "$script_dir/plot-plan-meta.sh" "$scratch" 2>/dev/null) || m=""
-  if [ -z "$m" ]; then
-    echo "plot-deliver: $rel — the written file does not parse, so the delivery was not landed." >&2
-    echo "  Nothing was written. Re-run after fixing the file." >&2
-    return 1
-  fi
-  got=$(printf '%s' "$m" | jq -r '.phase // ""')
-  [ "$got" = "$want" ] && return 0
-
-  # THE REFUSAL NAMES BOTH VALUES AND THE FILE. A message saying only "delivery
-  # failed" throws away the half a person acts on: which phase was written, and
-  # which one the parser still reads. The cause is named too, because the file
-  # holding two records of one fact is the thing to fix — and which format ought
-  # to win is a decision this gate deliberately leaves to a person.
-  echo "plot-deliver: $rel — wrote phase '$want', but the parser still reads '$got'." >&2
-  echo "  The write landed and the parser reads something else, so the delivery" >&2
-  echo "  would have reported a success it did not achieve." >&2
-  echo "  Nothing was written — the plan is unchanged. Check what the plan says" >&2
-  echo "  its phase is, and where: a plan stating it in two places reports the" >&2
-  echo "  '## Status' block, which is the field every lifecycle script writes." >&2
-  echo "  See what the parser reads: $script_dir/plot-plan-meta.sh $rel" >&2
-  return 1
-}
-
-write_transition() { # $1=file $2=record $3=recorded(yes|no) → sets phase_report record_report
-  local f="$1" record="$2" recorded="$3" a="$1.plot-phase" b="$1.plot-record" flipped=0
-
-  if flip_phase "$f" "$a"; then flipped=1; else flipped=0; fi
-  # awk wrote `$a` either way; where nothing flipped it is a faithful copy, so
-  # the record still has a file to be inserted into.
-  [ -s "$a" ] || { rm -f "$a"; echo "plot-deliver: could not read $rel" >&2; return 1; }
-
-  if [ "$recorded" = "yes" ]; then
-    # THE DRY RUN, on the file this arm is about to land. A refusal discards the
-    # scratch copy and leaves the plan byte-identical — and never reaches
-    # `record_state_receipt`, which would otherwise license a commit of a state
-    # that was refused.
-    phase_would_read "$a" delivered || { rm -f "$a"; return 1; }
-    mv "$a" "$f" || { rm -f "$a"; return 1; }
-    record_report="already"
-  else
-    if ! append_delivered_line "$a" "$b" "$record"; then
-      rm -f "$a" "$b"
-      echo "plot-deliver: $rel has no '## Status' section — nowhere to record the delivery." >&2
-      echo "  Nothing was written: the phase is not flipped either, because a phase" >&2
-      echo "  with no record is invisible to the scan. Fix the section and re-run." >&2
-      return 1
-    fi
-    # `$b` AND NOT `$a`: this arm lands the file carrying the record, so `$a`
-    # is content that never reaches the plan.
-    phase_would_read "$b" delivered || { rm -f "$a" "$b"; return 1; }
-    mv "$b" "$f" || { rm -f "$a" "$b"; return 1; }
-    rm -f "$a"
-    record_report="written"
-  fi
-
-  phase_report=$([ "$flipped" = 1 ] && echo flipped || echo already)
-  # The receipt plot-state-gate.sh clears on. Recorded after the `mv`, so it
-  # names a value the file actually carries — a receipt written before a failed
-  # write would license a commit of the state that was refused.
-  record_state_receipt "$f" "Delivered"
-  return 0
-}
-
-# Tick this plan's sprint item.
-#
-# THE TICK ONLY, since 2026-09-08. This also wrote a `<!-- status: delivered -->`
-# annotation, and `a-withdrawn-item-is-not-open` measured that record dead in
-# both directions: 67 lines carried one, none carried a value any reader acted
-# on, and `plot-sprint-release.sh` read the field nowhere. The plan file carries
-# `State:` and a dated `Delivered:` record, and the estate-outranks-the-checkbox
-# rule points at those — a cache nobody refreshes and nobody reads is a second
-# answer waiting to contradict the first.
-#
-# The box is NOT the same record. `/plot-sprint close` step 2a exists to tick
-# boxes the estate says are done, and ticking here is what keeps that step's
-# work to the items it genuinely cannot resolve.
-update_sprint_item() { # $1=worktree root → prints none|updated|already|missing
-  local root="$1" f found=""
-  [ -n "$sprint" ] || { printf 'none'; return 0; }
-  local dir="$root/${SPRINT_DIR#/}"
-  [ -d "$dir" ] || { printf 'missing'; return 0; }
-  # Find the sprint file by content (the [<slug>] reference), not by filename.
-  for f in "$dir"/*.md; do
-    [ -e "$f" ] || continue
-    grep -q "\[$slug\]" "$f" 2>/dev/null && { found="$f"; break; }
-  done
-  [ -n "$found" ] || { printf 'missing'; return 0; }
-
-  local before after
-  before=$(cat "$found")
-  after=$(awk -v slug="$slug" '
-    index($0, "[" slug "]") == 0 { print; next }
-    {
-      line = $0
-      # Check the box. Nothing else on the line is touched.
-      sub(/\[ \]/, "[x]", line)
-      print line
-    }
-  ' "$found")
-  if [ "$before" = "$after" ]; then printf 'already'; return 0; fi
-  printf '%s\n' "$after" > "$found"
-  printf 'updated'
-}
-
-# Move the active/ symlink to delivered/.
-move_index_symlink() { # $1=worktree root → prints moved|created|already|skipped
-  local root="$1"
-  local active_link="$root/${ACTIVE_DIR#/}$slug.md"
-  local delivered_link="$root/${DELIVERED_DIR#/}$slug.md"
-  local delivered_dir="$root/${DELIVERED_DIR#/}"
-
-  # Ensure delivered/ directory exists (best effort)
-  mkdir -p "$delivered_dir" 2>/dev/null || true
-
-  # Check if already in delivered/
-  if [ -e "$delivered_link" ]; then
-    # Remove from active/ if still there
-    git rm -q --ignore-unmatch "$active_link" 2>/dev/null || true
-    printf 'already'
-    return 0
-  fi
-
-  # Create the delivered/ symlink (relative path to the plan)
-  ln -sfn "../$plan_basename" "$delivered_link" 2>/dev/null || { printf 'skipped'; return 0; }
-
-  # Remove from active/ (best effort, ignore if not there)
-  git rm -q --ignore-unmatch "$active_link" 2>/dev/null || true
-
-  printf 'moved'
-}
-
-# The whole local half, run inside one directory.
-apply_local_writes() { # $1=root  → sets phase_report record_report index_report sprint_report
-  local root="$1" f="$1/$rel"
-  [ -f "$f" ] || { echo "plot-deliver: $rel is not present in $root" >&2; return 1; }
-
-  # Step 3 — THE TRANSITION: the phase and its record, together or not at all.
-  #
-  # ONE STEP WHERE THERE WERE TWO, which is the whole of this change. The domain
-  # decides what the two lines say and whether they are owed at all; this writes
-  # them as one replacement of the file. Already-done test: the domain answers
-  # `already` when the file it is about to write ALREADY carries both, which is
-  # the source asked directly — never a progress file.
-  local decided record action recorded
-  decided=$(decide_transition "$f") || return 1
-  record=$(printf '%s' "$decided" | cut -f2)
-  action=$(printf '%s' "$decided" | cut -f3)
-  recorded=$(printf '%s' "$decided" | cut -f4)
-  if [ "$action" = "already" ]; then
-    phase_report="already"
-    record_report="already"
-  else
-    write_transition "$f" "$record" "$recorded" || return 1
-  fi
-
-  # Step 5 — move the index symlink (best effort).
-  index_report=$(move_index_symlink "$root")
-
-  # Step 6 — tick the sprint item.
-  sprint_report=$(update_sprint_item "$root")
-  return 0
-}
-
-phase_report="" record_report="" index_report="skipped" sprint_report="none"
-push_report="n/a"
-
-# Fetch and create a booking worktree off origin/<default>.
-git fetch -q origin "$MAIN" 2>/dev/null
-
-bookbr="plot/deliver-$slug"
-tmpwt="$wt_root/.plot-deliver-$slug.$$"
-# `git worktree add` creates the desk root when it is missing, so exclude it
-# first: a booking run must not leave `.worktrees/` untracked in `git status`.
-plot_exclude_desk_root "$main_root"
-# -B: a leftover branch from an earlier failed run must not block this one.
-git worktree add -q -B "$bookbr" "$tmpwt" "origin/$MAIN" 2>/dev/null \
-  || die "could not prepare a booking worktree at $tmpwt.
-  Most often origin/$MAIN is not fetched, or '$bookbr' is checked out in
-  another worktree. Check both: git fetch origin $MAIN && git worktree list
-  Nothing has been written locally; the plan is untouched."
-
-cleanup() {
-  git worktree remove --force "$tmpwt" >/dev/null 2>&1 || true
-  git branch -D "$bookbr" >/dev/null 2>&1 || true
-}
-
-if ! apply_local_writes "$tmpwt"; then
-  cleanup
-  exit 1
-fi
-
-# Stage the plan file and index changes.
-git -C "$tmpwt" add -- "$rel" >/dev/null 2>&1 || true
-git -C "$tmpwt" add -- "${ACTIVE_DIR#/}" >/dev/null 2>&1 || true
-git -C "$tmpwt" add -- "${DELIVERED_DIR#/}" >/dev/null 2>&1 || true
-[ "$sprint_report" = "updated" ] && git -C "$tmpwt" add -- "${SPRINT_DIR#/}" >/dev/null 2>&1
-
-# THE BOOKED PLAN, KEPT FOR THE TRACKER. The booking worktree is removed on
-# every exit below, and the working tree may still read `Approved`; the issue
-# status is decided from the file that reached the default branch.
-booked_plan=""
-plot_tmpfile booked_plan deliver-plan
-cp "$tmpwt/$rel" "$booked_plan" 2>/dev/null || : > "$booked_plan"
-
-if git -C "$tmpwt" diff --cached --quiet 2>/dev/null; then
-  # THE IDEMPOTENT EXIT. Everything this run would have written was already
-  # on the default branch, so there is nothing to push and nothing wrong.
-  push_report="nothing-to-commit"
-  echo "step: nothing to commit — the delivery is already recorded on $MAIN"
-  cleanup
-else
-  if ! git -C "$tmpwt" -c "user.name=$who" commit -q -m "plot: deliver $slug"; then
-    cleanup
-    die "could not commit the delivery.
-  See what git refused: git -C $tmpwt status
-  Nothing was pushed; re-run this — it is idempotent."
-  fi
-
-  push_out=$(bash "$script_dir/plot-push-main.sh" "$bookbr" "$MAIN" 2>&1)
-  push_rc=$?
-  printf '%s\n' "$push_out" | sed 's/^/  /'
-  if [ "$push_rc" = 0 ]; then
-    push_report=$(printf '%s' "$push_out" | sed -n 's/^push: \([a-z]*\).*/\1/p' | head -1)
-    [ -n "$push_report" ] || push_report="unknown"
-    cleanup
-  else
-    # BRANCH PROTECTION FALLBACK — open a micro-PR if push is rejected.
-    echo "step: push rejected — opening a micro-PR instead"
-    if git push -q origin "$bookbr" 2>/dev/null \
-      && micro_url=$(bash "$script_dir/plot-host.sh" pr-create \
-           --title "plot: deliver $slug" \
-           --body "Records the delivery of \`$slug\`." \
-           --base "$MAIN" --head "$bookbr" 2>/dev/null) \
-      && micro_num=$(printf '%s' "$micro_url" | sed 's#.*/##') \
-      && bash "$script_dir/plot-host.sh" pr-merge "$micro_num" --delete-branch >/dev/null 2>&1
-    then
-      push_report="micro-pr"
-      echo "step: delivery landed via micro-PR $micro_url"
-      cleanup
-    else
-      push_report="rejected"
-      echo "plot-deliver: the delivery is committed on '$bookbr' but could not reach $MAIN." >&2
-      echo "  Land '$bookbr' by hand, or re-run this command once the push works." >&2
-      git worktree remove --force "$tmpwt" >/dev/null 2>&1 || true
-      rm -f "$booked_plan"
-      # NOTHING REACHED THE DEFAULT BRANCH, so no status is owed yet.
-      echo "summary: phase=$phase_report record=$record_report index=$index_report sprint=$sprint_report push=$push_report tracker=skipped"
-      exit 1
-    fi
-  fi
-fi
-
-# THE TRACKER HEARS AFTER THE DELIVERY LANDED, and never decides it. The plan is
-# delivered; the tracker holds a copy of one fact about it. Every outcome of
-# plot-issue-status.sh, a failed write and an unreadable bundle included, is a
-# report on the summary line and leaves this script's exit code alone.
-tracker_out=$(bash "$script_dir/plot-issue-status.sh" "$booked_plan" 2>&1)
-printf '%s\n' "$tracker_out" | grep -v '^summary: ' | sed '/^$/d; s/^/  tracker: /'
-tracker_report=$(printf '%s' "$tracker_out" | sed -n 's/^summary: tracker=\([a-z-]*\).*/\1/p' | tail -1)
-[ -n "$tracker_report" ] || tracker_report="failed"
-rm -f "$booked_plan"
-
-echo "summary: phase=$phase_report record=$record_report index=$index_report sprint=$sprint_report push=$push_report tracker=$tracker_report"
-# THE RECEIPT IS SPENT HERE, on the action COMPLETING — never at the gate.
-# `plot-controller-gate.sh` clears on a receipt and LEAVES it, so an
-# interrupted run can be repeated on the same licence: this script documents
-# re-running as the repair for any interruption after its irreversible step,
-# and a receipt spent at the gate would refuse that repair in the case it is
-# most needed. One authorisation, one completed action.
-spend_action_receipt "plot-deliver.sh"
-
-exit 0
+exec node "$bundle" "$@"