@plot-pm/board 0.11.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plot-pm/board",
-  "version": "0.11.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",
@@ -23,14 +23,18 @@
   "files": [
     "dist/board-server.mjs",
     "plot-agent-monitor.sh",
+    "plot-build-monitor.sh",
+    "plot-monitor-subject.sh",
     "plot-approve.sh",
     "plot-budget.sh",
     "plot-config.sh",
+    "plot-default-branch.sh",
     "plot-deliver.sh",
     "plot-dispatch.sh",
     "plot-fleet-scan.sh",
     "plot-host.sh",
     "plot-plan-meta.sh",
+    "plot-pr-merged.sh",
     "plot-reap.sh",
     "plot-release-refs.sh",
     "plot-resolve-artifact.sh",

package/plot-agent-monitor.sh

@@ -227,21 +227,45 @@ publish() { # $1=finding $2=evidence $3=since
 # helpers throw away: `gh` absent, unauthed, or failing is `unaskable`, and an
 # unaskable host produces NO finding rather than a wrong one. A failure to
 # observe is not evidence of something to see.
+#
+# THE HOST IS ASKED THROUGH `plot-host.sh`, never `gh` directly. This port
+# called `gh pr list` until 2026-09-05, so the monitor could see a PR on GitHub
+# and nowhere else: on Bitbucket `command -v gh` failed and every branch on the
+# estate read `unaskable` — the refusal was right about the wrong thing, since
+# the host was reachable and simply not GitHub. `pr-state` answers on both.
+#
+# THE ADAPTER'S TWO OUTCOMES ARE ALREADY THIS PORT'S TWO. `pr-state` exits 0
+# with `state:"NONE"` when the host answered and there is no PR, and non-zero
+# when the call itself failed — which is exactly the line between `no PR` and
+# `unaskable` that the `gh` version drew with `|| return 2`. So the split is
+# read from the exit status and the payload together, and neither answer moved.
 monitor_pr_state() { # → 0 has a PR | 1 no PR | 2 unaskable
   [ -n "$branch" ] || return 2
-  command -v gh >/dev/null 2>&1 || return 2
-  local out
-  # `--state all` and `mergedAt`, never `state`: a merged PR reports CLOSED, and
-  # squash-merge leaves the branch ahead of main forever, so neither the state
-  # word nor ancestry can answer this. The same reading `plot-pr-merged.sh`
-  # makes, and deliberately the same query, so the two never disagree about a
-  # branch.
-  out=$(gh pr list --head "$branch" --state all --limit 100 --json mergedAt,number 2>/dev/null) || return 2
-  # An empty LIST is a real answer — the host was asked and said none. Only a
-  # failed call is unaskable, which is what the `|| return 2` above separates.
-  case "$out" in
-    *'"number"'*) return 0 ;;
-    *) return 1 ;;
+  local host_script out state
+  host_script="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/plot-host.sh"
+  [ -r "$host_script" ] || return 2
+  # `</dev/null` so a host CLI that decides to prompt cannot hang a monitor
+  # whose whole contract is one bounded reading per pass.
+  out=$(bash "$host_script" pr-state "$branch" </dev/null 2>/dev/null) || return 2
+  # THE EXIT STATUS DECIDES WHETHER THE HOST WAS ASKED; the payload only says
+  # what it answered. `pr-state` exits non-zero when the call failed and 0 when
+  # it did not, so anything reaching this line is an answer.
+  #
+  # A MISS IS `NONE`, AND SO IS A NULL. `state:"NONE"` is the adapter's word for
+  # "no PR found", but the same miss reaches here as `state:null` when the host
+  # CLI answers with a payload carrying no PR — measured 2026-09-05 against
+  # `test/e2e/agent-monitor-reads.test.mjs`, where `gh pr view` on a branch with
+  # no PR produced `{"number":null,"state":null,…}` and exit 0.
+  #
+  # Reading that null as `unaskable` is what the first draft of this port did,
+  # and it is wrong in the direction that hides the finding: an agent that
+  # committed and opened nothing produced no `owes a review` at all, because the
+  # monitor believed it had never measured. A failure to observe is not evidence
+  # of something to see — but neither is an observation evidence of a failure.
+  state=$(printf '%s' "$out" | jq -r '.state // "NONE"' 2>/dev/null) || return 2
+  case "$state" in
+    NONE|null|"") return 1 ;;
+    *) return 0 ;;
   esac
 }
 

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,10 +346,14 @@ 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 `**Phase:** Draft` OR `**Phase:** Design` → `Approved` in the `## Status`
-# section only. Both are the pre-Approved phases this script advances from.
+# Flip `**State:** Draft` OR `**State:** Design` → `Approved` in the `## Status`
+# section only. Both are the pre-Approved states this script advances from.
+#
+# 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 approves.
 #
 # Scoped to that section because a plan that QUOTES a status block in its prose
 # (this repo has several, documenting the format) would otherwise have its
@@ -353,7 +367,7 @@ flip_phase() { # $1=in $2=out  → 0 if it changed the file, 1 if there was noth
   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) ~ /draft/) {
         sub(/[Dd]raft/, "Approved")
         done = 1
@@ -555,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; }
@@ -586,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
+      }
+      # 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
@@ -656,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
@@ -672,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