@plot-pm/board 0.11.0 → 0.13.0

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,12 +228,15 @@ 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")
 
-# Flip `**Phase:** Approved` → `Delivered` in the `## Status` section only.
+# 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 —
@@ -235,7 +245,7 @@ flip_phase() { # $1=in $2=out  → 0 if it changed the file, 1 if nothing to fli
   awk '
     BEGIN { section = ""; done = 0 }
     /^## / { section = ($0 ~ /^## Status/) ? "status" : ""; print; next }
-    section == "status" && !done && tolower($0) ~ /^[ \t]*[-*]?[ \t]*\**phase[:*]/ {
+    section == "status" && !done && tolower($0) ~ /^[ \t]*[-*]?[ \t]*\**(state|phase)[:*]/ {
       if (tolower($0) ~ /approved/) {
         sub(/[Aa]pproved/, "Delivered")
         done = 1
@@ -410,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#/}"
@@ -429,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")
@@ -500,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
 }
 
@@ -515,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
@@ -542,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)