@plot-pm/board 0.12.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plot-pm/board",
-  "version": "0.12.0",
+  "version": "0.13.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",

package/plot-approve.sh

@@ -116,7 +116,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 +135,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 +167,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 +232,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 +346,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.
@@ -558,13 +569,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 +607,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
       }
-      print line
+      # 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 (tail != "" ? tail : " -->")
     }
   ' "$found")
   if [ "$before" = "$after" ]; then printf 'already'; return 0; fi
@@ -659,7 +686,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 +704,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

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
@@ -66,7 +66,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 +86,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 +109,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 +163,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; }
 
@@ -187,7 +194,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 +228,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")
@@ -412,8 +420,20 @@ write_transition() { # $1=file $2=record $3=recorded(yes|no) → sets phase_repo
   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 +451,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 +515,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 +530,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 +560,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)

package/plot-dispatch.sh

@@ -276,7 +276,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 +1172,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 +1912,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 +1973,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 +1981,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 +1994,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 +2007,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 +2438,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 +2455,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 +2481,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 +2503,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