@plot-pm/board 0.12.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plot-pm/board",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Local Kanban board for Plot — a glanceable view of plan phases from docs/plans, with sprint and story filters",
   "type": "module",
   "license": "MIT",
@@ -38,6 +38,7 @@
     "plot-reap.sh",
     "plot-release-refs.sh",
     "plot-resolve-artifact.sh",
+    "plot-state-receipt.sh",
     "plot-transcript-quiet.sh",
     "plot-worker-monitor.sh",
     "plot-worker-state.sh"

package/plot-approve.sh

@@ -99,6 +99,12 @@ set -uo pipefail
 
 script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
 
+# 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=""
@@ -116,7 +122,7 @@ done
 die() { echo "plot-approve: $*" >&2; exit 1; }
 
 [ -n "$slug" ] || die "need a plan slug (usage: plot-approve.sh [--dry-run] <slug>)"
-git rev-parse --git-dir >/dev/null 2>&1 || die "not a git repository"
+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"; }
 
@@ -135,10 +141,14 @@ plan_file=""
 for cand in "$ACTIVE_DIR$slug.md" "$PLAN_DIR"*"$slug".md; do
   [ -e "$cand" ] && { plan_file="$cand"; break; }
 done
-[ -n "$plan_file" ] || die "no plan found for '$slug' — looked in $ACTIVE_DIR and $PLAN_DIR"
+[ -n "$plan_file" ] || die "no plan found for '$slug' — looked in $ACTIVE_DIR and $PLAN_DIR.
+  Check the slug: ls $PLAN_DIR | grep -i '$slug'
+  Or create the plan first: /plot-idea"
 
 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"
+[ -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; }
 
@@ -163,11 +173,14 @@ plan_branches=$(jfield '.branches[]?')
 case "$phase" in
   draft|design|approved) ;;
   delivered|released)
-    die "plan '$slug' is already $phase — nothing to approve." ;;
+    die "plan '$slug' is already $phase — nothing to approve.
+  Nothing to do here. To take the work further: /plot-release" ;;
   NONE|"")
-    die "cannot read the phase of '$slug' ($plan_file) — refusing rather than guessing." ;;
+    die "cannot read the phase of '$slug' ($plan_file) — refusing rather than guessing.
+  Its '## Status' section needs a line reading '- **State:** Draft'." ;;
   *)
-    die "plan '$slug' is in phase '$phase' — only a Draft or Design plan can be approved." ;;
+    die "plan '$slug' is in phase '$phase' — only a Draft or Design plan can be approved.
+  If that phase is wrong, correct the 'State:' line in $plan_file and push it." ;;
 esac
 
 # --- refusal 2: the review channel ------------------------------------------
@@ -225,9 +238,12 @@ case "$pr_state" in
   MERGED) ;;
   OPEN) ;;
   CLOSED)
-    die "the plan PR for '$slug' (#$pr_number) is closed. Reopen it or create a new one." ;;
+    die "the plan PR for '$slug' (#$pr_number) is closed.
+  Reopen it on the host, or push '$pr_branch' again and open a new one." ;;
   NONE|*)
-    die "no PR found for branch '$pr_branch'. Run /plot-idea first, or push the branch." ;;
+    die "no PR found for branch '$pr_branch'.
+  Push the branch: git push -u origin $pr_branch
+  Then open its PR — or run /plot-idea, which does both." ;;
 esac
 
 echo "step: plan $plan_file — phase=$phase review=${review} impl=${impl} pr=#$pr_number($pr_state)"
@@ -336,7 +352,8 @@ real_plan_path() { # $1 = plan file as found
 }
 
 rel=$(cd "$repo_root" && real_plan_path "$plan_file") || rel=""
-[ -n "$rel" ] || die "$plan_file is outside the repository root"
+[ -n "$rel" ] || die "$plan_file is outside the repository root ($repo_root).
+  Move the plan under $PLAN_DIR inside this checkout and re-run."
 
 # Flip `**State:** Draft` OR `**State:** Design` → `Approved` in the `## Status`
 # section only. Both are the pre-Approved states this script advances from.
@@ -527,6 +544,10 @@ write_transition() { # $1=file $2=record $3=recorded(yes|no) → sets phase_repo
   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" "Approved"
   return 0
 }
 
@@ -558,13 +579,20 @@ clear_holds() { # $1=worktree root; reads $plan_branches
 }
 
 # Update the sprint item annotation this plan appears in:
-#     - [ ] [slug] description <!-- pr: #N, status: draft, branch: feature/slug -->
-# /plot-sprint READS these (`pr`, `status`, `branch`) and /plot-approve writes
-# them, so an approval that skips this makes `/plot-sprint status` wrong rather
-# than merely incomplete.
+#     - [ ] [slug] description <!-- pr: #N, branch: feature/slug -->
+# /plot-sprint READS these (`pr`, `branch`) and /plot-approve writes them, so an
+# approval that skips this makes `/plot-sprint status` wrong rather than merely
+# incomplete.
+#
+# `status:` IS GONE, since 2026-09-08. `a-withdrawn-item-is-not-open` measured
+# it dead in both directions — 67 lines carried one, no reader acted on the
+# value, and `plot-sprint-release.sh` read the field nowhere. The plan file
+# carries `State:` and a dated `Approved:` record; a cache nobody refreshes and
+# nobody reads is a second answer waiting to contradict the first. `pr` and
+# `branch` stay: they name things no plan field holds.
 #
 # A plan in NO sprint is a no-op, never an error — that is the common case.
-# Already-done test: the annotation already carries `status: approved`.
+# Already-done test: the annotation already carries this PR and branch.
 update_sprint_annotation() { # $1=worktree root → prints none|updated|already|missing
   local root="$1" f found=""
   [ -n "$sprint" ] || { printf 'none'; return 0; }
@@ -589,18 +617,27 @@ update_sprint_annotation() { # $1=worktree root → prints none|updated|already|
     {
       line = $0
       if (index(line, "<!--") == 0) {
-        line = line " <!-- pr: #" pr ", status: approved" (br != "" ? ", branch: " br : "") " -->"
-      } else {
-        if (line ~ /status:[ \t]*[a-z-]+/) sub(/status:[ \t]*[a-z-]+/, "status: approved", line)
-        else sub(/-->/, ", status: approved -->", line)
-        if (line ~ /pr:[ \t]*#?[0-9a-z]+/) sub(/pr:[ \t]*#?[0-9a-z]+/, "pr: #" pr, line)
-        else sub(/<!--/, "<!-- pr: #" pr ",", line)
-        if (br != "") {
-          if (line ~ /branch:[ \t]*[^,>]+/) sub(/branch:[ \t]*[^,>]*[^,> \t]/, "branch: " br, line)
-          else sub(/-->/, ", branch: " br " -->", line)
-        }
+        print line " <!-- pr: #" pr (br != "" ? ", branch: " br : "") " -->"
+        next
+      }
+      # THE CLOSING MARKER IS SPLIT OFF BEFORE ANY FIELD IS TOUCHED.
+      # A value pattern that has to avoid `-->` cannot be written safely:
+      # `[^,>]*[^,> \t]` excluded the `>` and still swallowed the `--`, turning
+      # ` -->` into a bare `>` and corrupting the comment — measured 2026-09-08,
+      # `approve: updates the sprint annotation the sprint view reads` failed on
+      # exactly that. Excluding `-` as well is worse: it rewrites `bug/a-b` as
+      # `feature/new-b`, and hyphens are in most branch names here.
+      # With the marker held aside, every field ends at a comma or at
+      # end-of-string, and none can reach it.
+      tail = ""
+      if (match(line, /[ \t]*-->[ \t]*$/)) { tail = substr(line, RSTART); line = substr(line, 1, RSTART - 1) }
+      if (line ~ /pr:[ \t]*#?[0-9a-z]+/) sub(/pr:[ \t]*#?[0-9a-z]+/, "pr: #" pr, line)
+      else sub(/<!--/, "<!-- pr: #" pr ",", line)
+      if (br != "") {
+        if (line ~ /branch:[ \t]*[^,]/) sub(/branch:[ \t]*[^,]*/, "branch: " br, line)
+        else line = line ", branch: " br
       }
-      print line
+      print line (tail != "" ? tail : " -->")
     }
   ' "$found")
   if [ "$before" = "$after" ]; then printf 'already'; return 0; fi
@@ -659,7 +696,9 @@ if [ "$same_branch" = 1 ]; then
     push_report="nothing-to-commit"
     echo "step: nothing to commit — the approval was already recorded"
   else
-    git -C "$repo_root" commit -q -m "plot: approve $slug" || die "could not commit the approval"
+    git -C "$repo_root" commit -q -m "plot: approve $slug" || die "could not commit the approval.
+  The PR is already merged; the local record is what is missing. See what git
+  refused: git -C $repo_root status. Then re-run this — it is idempotent."
     push_report="local"
     echo "step: recorded on $(git -C "$repo_root" branch --show-current) — push it with the implementation"
   fi
@@ -675,7 +714,10 @@ else
   # -B: a leftover branch from an earlier failed run must not block this one.
   # It is disposable by construction — created here, pushed, deleted.
   git worktree add -q -B "$bookbr" "$tmpwt" "origin/$MAIN" 2>/dev/null \
-    || die "could not prepare a booking worktree at $tmpwt"
+    || 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
@@ -744,4 +786,12 @@ else
 fi
 
 echo "summary: merged=$merged_report phase=$phase_report record=$record_report holds=$holds_report sprint=$sprint_report push=$push_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-approve.sh"
+
 exit 0

package/plot-config.sh

@@ -95,6 +95,23 @@
 #   Hosts plans         yes | no                      (no = refuse plan files)
 #   Tracker             plot | jira | github-issues | linear  (+ URL)
 #                       (plot = plans in this repo ARE the tracker; absent = same)
+#   Ticket prefixes     the tracker project keys this repository's work lives
+#                       in, comma-separated (`PROJ-A, PROJ-B`). NOT
+#                       `Branch prefixes`, which sits next to it and holds
+#                       `idea/`, `feature/`, `bug/` — that key is structural and
+#                       names git branches; this one names tracker projects.
+#                       Read by plot-host.sh's `issue-list` to scope the inbox:
+#                       the default JQL scopes by person and state, so on a
+#                       shared instance it is instance-wide and returns other
+#                       customers' tickets. A LIST, because a repository mapping
+#                       to several projects is the normal case; adoption seeds
+#                       ONE prefix and a person adds the rest. Absent = today's
+#                       unscoped query, byte for byte — a default that filtered
+#                       on an undeclared key would empty every existing board's
+#                       inbox on upgrade. `PLOT_JIRA_JQL` overrides both.
+#                       NEVER WRITTEN EMPTY: an empty list reads as *this
+#                       repository has no projects* and changes nothing about
+#                       the query, so adoption omits the key instead.
 #   Git host            github | bitbucket            (resolves gh vs bb)
 #   CI                  jenkins | github-actions | none — which CI system this
 #                       project uses. Recorded by /plot-board-setup; not yet

package/plot-deliver.sh

@@ -35,7 +35,7 @@
 #
 # 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 annotation. Never a progress file of its own.
+# 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
@@ -49,6 +49,12 @@ set -uo pipefail
 
 script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
 
+# 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=""
@@ -66,7 +72,7 @@ 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"
+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"; }
 
@@ -86,10 +92,13 @@ 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"
+[ -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"
+[ -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; }
 
@@ -106,13 +115,16 @@ delivered_raw=$(jfield '.delivered_raw')
 case "$phase" in
   approved|delivered) ;;
   released)
-    die "plan '$slug' is already released — nothing to deliver." ;;
+    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." ;;
+    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." ;;
+    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." ;;
+    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
 
 # ---------------------------------------------------------------------------
@@ -157,7 +169,8 @@ 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."
+[ -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; }
 
@@ -165,6 +178,27 @@ 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
@@ -187,7 +221,7 @@ 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 update the sprint annotation${sprint:+ (sprint: $sprint)}"
+  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
@@ -221,7 +255,8 @@ real_plan_path() { # $1 = plan file as found
 }
 
 rel=$(cd "$repo_root" && real_plan_path "$plan_file") || rel=""
-[ -n "$rel" ] || die "$plan_file is outside the repository root"
+[ -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")
@@ -409,11 +444,27 @@ write_transition() { # $1=file $2=record $3=recorded(yes|no) → sets phase_repo
   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
 }
 
-# Update the sprint item annotation for this plan.
-update_sprint_annotation() { # $1=worktree root → prints none|updated|already|missing
+# 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#/}"
@@ -431,15 +482,8 @@ update_sprint_annotation() { # $1=worktree root → prints none|updated|already|
     index($0, "[" slug "]") == 0 { print; next }
     {
       line = $0
-      # Check the box
+      # Check the box. Nothing else on the line is touched.
       sub(/\[ \]/, "[x]", line)
-      # Update or add status annotation
-      if (index(line, "<!--") == 0) {
-        line = line " <!-- status: delivered -->"
-      } else {
-        if (line ~ /status:[ \t]*[a-z-]+/) sub(/status:[ \t]*[a-z-]+/, "status: delivered", line)
-        else sub(/-->/, ", status: delivered -->", line)
-      }
       print line
     }
   ' "$found")
@@ -502,8 +546,8 @@ apply_local_writes() { # $1=root  → sets phase_report record_report index_repo
   # Step 5 — move the index symlink (best effort).
   index_report=$(move_index_symlink "$root")
 
-  # Step 6 — update the sprint annotation.
-  sprint_report=$(update_sprint_annotation "$root")
+  # Step 6 — tick the sprint item.
+  sprint_report=$(update_sprint_item "$root")
   return 0
 }
 
@@ -517,7 +561,10 @@ bookbr="plot/deliver-$slug"
 tmpwt="$wt_root/.plot-deliver-$slug.$$"
 # -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"
+  || 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
@@ -544,7 +591,9 @@ if git -C "$tmpwt" diff --cached --quiet 2>/dev/null; then
 else
   if ! git -C "$tmpwt" -c "user.name=$who" commit -q -m "plot: deliver $slug"; then
     cleanup
-    die "could not commit the delivery"
+    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)
@@ -580,4 +629,12 @@ else
 fi
 
 echo "summary: phase=$phase_report record=$record_report index=$index_report sprint=$sprint_report push=$push_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

package/plot-dispatch.sh

@@ -150,6 +150,12 @@ script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
 # shellcheck source=plot-worker-state.sh
 . "$script_dir/plot-worker-state.sh"
 
+# The controller receipt, for `spend_action_receipt` below. Sourced from the
+# ONE file that holds both receipt kinds, for the reason that file states: the
+# gate and the owners must agree on where a receipt lives.
+# shellcheck source=plot-state-receipt.sh
+. "$script_dir/plot-state-receipt.sh"
+
 # The ONE answer to "did the host merge ANY PR for this branch?" — `pr_merged`,
 # read by `held_worktree` rather than derived from ancestry. Sourced for the
 # same reason `plot-reap.sh` and `plot-release-refs.sh` source it: three callers
@@ -276,7 +282,11 @@ while [ $# -gt 0 ]; do
 done
 
 git rev-parse --git-dir >/dev/null 2>&1 || { echo "not a git repository" >&2; exit 1; }
-[ -n "$slug" ] || [ "$mode" != dispatch ] || { echo "plot-dispatch: need a plan slug" >&2; exit 1; }
+[ -n "$slug" ] || [ "$mode" != dispatch ] || {
+  echo "plot-dispatch: need a plan slug (usage: plot-dispatch.sh [--dry-run] <slug>)" >&2
+  echo "  Which plans could be dispatched: /plot-pulse" >&2
+  exit 1
+}
 
 # ---------------------------------------------------------------------------
 # Worker launch, and the identity it records
@@ -1168,14 +1178,38 @@ if [ "$mode" = "stop" ]; then
     echo "  Refusing to guess — stopping the wrong worker discards its work." >&2
     exit 1
   fi
-  wt="$wt_root_early/$wt_prefix_early$(printf '%s' "$stop_branch" | tr '/' '-')"
-  [ -d "$wt" ] || { echo "plot-dispatch: no worktree for '$stop_branch' at $wt" >&2; exit 1; }
+  # ASK GIT WHICH WORKTREE HOLDS THE BRANCH, then fall back to the dispatch
+  # path. `--restart` below already asks, and this did not: it rebuilt one path
+  # from the branch name and reported that single path as though it were the
+  # only place a desk could be. On 2026-09-07 the desk existed elsewhere — a
+  # worktree made by hand, which is the population that never follows
+  # dispatch's naming — and the refusal sent a reader to `kill`.
+  #
+  # A refusal that is confidently wrong is worse than one that is terse, so the
+  # path-guess survives only as the LAST candidate and the refusal below says
+  # which places were looked in.
+  wt=$(git worktree list --porcelain </dev/null 2>/dev/null | awk -v want="refs/heads/$stop_branch" '
+    /^worktree /  { path = substr($0, 10) }
+    /^branch /    { if (substr($0, 8) == want) { print path; exit } }')
+  wt_guess="$wt_root_early/$wt_prefix_early$(printf '%s' "$stop_branch" | tr '/' '-')"
+  [ -n "$wt" ] && [ -d "$wt" ] || wt="$wt_guess"
+  if [ ! -d "$wt" ]; then
+    echo "plot-dispatch: no worktree holds '$stop_branch' — nothing to stop." >&2
+    echo "  Asked git for every worktree, and looked at $wt_guess." >&2
+    echo "  If a worker is running somewhere this cannot see, that machine is" >&2
+    echo "  where to stop it: /plot-dispatch --status names the desks here." >&2
+    echo "  Nothing was killed." >&2
+    exit 1
+  fi
   st=$(worker_state "$wt" "$stop_branch")
   case "$st" in
     running*)
       pid=${st#running }
       kill "$pid" 2>/dev/null && echo "stopped $stop_branch (pid $pid)" \
-        || { echo "plot-dispatch: could not stop pid $pid" >&2; exit 1; }
+        || { echo "plot-dispatch: could not stop pid $pid — it may have exited between the read and the signal, or belong to another user." >&2
+             echo "  Check it: ps -p $pid -o pid=,stat=,command=" >&2
+             echo "  Nothing else was written; the worktree and the claim stand." >&2
+             exit 1; }
       # The worktree and its claim are left in place: the branch is still taken,
       # and deleting either would be the kind of write this design avoids.
       echo "  worktree kept at $wt — the claim stands until you release it"
@@ -1884,6 +1918,7 @@ fi
 if [ -z "$plan_path" ]; then
   if [ "$allow_local" = 1 ]; then
     echo "plot-dispatch: no plan found for '$slug' — looked in $ACTIVE_DIR_CFG and $PLAN_DIR_CFG" >&2
+    echo "  Check the slug: ls $PLAN_DIR_CFG | grep -i '$slug'" >&2
   else
     echo "plot-dispatch: no plan for '$slug' on $gate_ref — looked in $ACTIVE_DIR_CFG and $PLAN_DIR_CFG" >&2
     echo "  A plan that exists only in this working tree has not been shared yet: push it first." >&2
@@ -1944,6 +1979,7 @@ case "$gate_phase" in
     exit 1 ;;
   delivered|released)
     echo "plot-dispatch: plan '$slug' is already $gate_phase — its work is done." >&2
+    echo "  Nothing to dispatch. To start new work: /plot-idea" >&2
     exit 1 ;;
   "")
     echo "plot-dispatch: cannot read the phase of '$slug' ($gate_source)." >&2
@@ -1951,6 +1987,8 @@ case "$gate_phase" in
     exit 1 ;;
   *)
     echo "plot-dispatch: plan '$slug' is in phase '$gate_phase', not Approved." >&2
+    echo "  Correct the 'State:' line in the plan and push it, or approve it:" >&2
+    echo "  /plot-approve $slug" >&2
     exit 1 ;;
 esac
 
@@ -1962,6 +2000,7 @@ case "$gate_impl" in
   same-branch)
     echo "plot-dispatch: plan '$slug' records 'Impl: same branch' — plan and code" >&2
     echo "  travel on one branch, so there is nothing to fan out." >&2
+    echo "  Implement on that branch instead: /plot-implement $slug" >&2
     exit 1 ;;
   other-repo)
     echo "plot-dispatch: plan '$slug' records 'Impl: other repo' — implementation" >&2
@@ -1974,6 +2013,8 @@ case "$gate_impl" in
   *)
     echo "plot-dispatch: plan '$slug' records an unrecognised 'Impl:' answer" >&2
     echo "  ('$gate_impl'). Refusing rather than guessing." >&2
+    echo "  Set the plan's 'Impl:' line to one of: own branches, same branch," >&2
+    echo "  other repo, none — then push it." >&2
     exit 1 ;;
 esac
 
@@ -2403,7 +2444,8 @@ write_started_record() { # $@ = branches
   # would carry the symlink and leave the record behind.
   rel=$(cd "$repo_root" && real_plan_path "$plan_file") || rel=""
   if [ -z "$rel" ]; then
-    echo "plot-dispatch: $plan_file is outside the repository root" >&2
+    echo "plot-dispatch: $plan_file is outside the repository root ($repo_root)." >&2
+    echo "  Move the plan under $PLAN_DIR_CFG inside this checkout and re-run." >&2
     return 1
   fi
 
@@ -2419,6 +2461,9 @@ write_started_record() { # $@ = branches
   # one. It is disposable by construction — created here, pushed, deleted.
   if ! git worktree add -q -B "$bookbr" "$tmpwt" "origin/$MAIN" 2>/dev/null; then
     echo "plot-dispatch: could not prepare a booking worktree at $tmpwt" >&2
+    echo "  Most often origin/$MAIN is not fetched, or '$bookbr' is checked out in" >&2
+    echo "  another worktree. Check both: git fetch origin $MAIN && git worktree list" >&2
+    echo "  The branches were dispatched; only the plan's Started record is missing." >&2
     return 1
   fi
 
@@ -2442,6 +2487,7 @@ write_started_record() { # $@ = branches
       fi
       append_started_line "$tmpwt/$rel" "$date" "$who" "$br" || {
         echo "plot-dispatch: $rel has no '## Status' section — nowhere to record" >&2
+        echo "  Add one to the plan (see .plot/templates/plan.md) and push it." >&2
         rc=1
         break
       }
@@ -2463,6 +2509,7 @@ write_started_record() { # $@ = branches
     fi
   else
     echo "plot-dispatch: $rel is not on origin/$MAIN" >&2
+    echo "  Push the plan to $MAIN first; the fleet reads plans from the shared ref." >&2
     rc=1
   fi
 
@@ -3165,3 +3212,13 @@ book_started ${claimed_now[@]+"${claimed_now[@]}"} || true
 check_and_update_cap "$n_started"
 
 print_summary "$n_dispatched" "$n_reused" "$n_skipped" "$n_started"
+
+# THE RECEIPT IS SPENT HERE, on the fan-out COMPLETING — never at the gate.
+# `plot-controller-gate.sh` clears on a receipt and LEAVES it, so a run that
+# died partway can be repeated on the same licence. One authorisation, one
+# completed action.
+#
+# ONLY THE FAN-OUT SPENDS ONE. `--status`, `--dry-run`, `--stop`, `--restart`,
+# `--start` and `--migrate` all return before this line, and the gate exempts
+# each of them: they are reads, or writes no endpoint owns.
+spend_action_receipt "plot-dispatch.sh"