@plot-pm/board 0.14.2 → 0.14.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plot-pm/board",
-  "version": "0.14.2",
+  "version": "0.14.3",
   "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-deliver.sh

@@ -425,9 +425,15 @@ decide_transition() { # $1=file  → prints "<Phase>\t<record>\t<write|already>"
 # 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 prefers front matter wherever it exists and reads the
-# block only in the `else if` below. The write took effect on bytes nobody
-# reads.
+# `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
@@ -468,11 +474,11 @@ phase_would_read() { # $1=scratch file $2=expected phase (lowercase) → 0 agree
   # 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 plan states its phase in TWO places and they disagree: the write" >&2
-  echo "  landed in the '## Status' block while front matter takes precedence," >&2
-  echo "  so the delivery would have reported a success it did not achieve." >&2
-  echo "  Nothing was written — the plan is unchanged. Remove one of the two" >&2
-  echo "  records (front matter, or the '## Status' block) and re-run." >&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
 }

package/plot-dispatch.sh

@@ -1904,62 +1904,70 @@ EOF
     esac
   fi
 
-  # THE COUNT IS THE RULE'S, and the rule is `packages/domain/src/rules/
-  # fleet-size.ts` — imported directly, the same shape `plot-reap.sh` uses for
-  # `reapable.ts`. Node 24 strips the types, so there is no build step between
-  # this script and the decision it asks for, and there is no second copy of the
-  # default, the subtraction or the machine's veto living in shell.
-  #
-  # A RULE THAT CANNOT BE ASKED STARTS NOTHING AND SAYS SO. Missing node, a
-  # failed import, a module that throws all leave the answer empty. The
-  # direction is the reaper's: silence is never permission, and here permission
-  # would spawn detached processes.
+  # THE COUNT IS THE RULE'S, and the rule is asked through its BUNDLE —
+  # `board/plot-fleet-size.mjs`, tracked in git beside the other 24. There is no
+  # second copy of the default, the subtraction or the machine's veto living in
+  # shell.
+  #
+  # A SOURCE IMPORT CANNOT REACH A PLUGIN INSTALL, and this block used to be
+  # one. It imported `rules/fleet-size.ts` and `entities/machine.ts` as `file://`
+  # sources. Node 24 strips types, so the TypeScript was never the obstacle — the
+  # SECOND import is: `machine.ts` opens with `import { z } from 'zod'`, and an
+  # install carrying no `node_modules` cannot resolve it. Measured 2026-09-17
+  # against a copy with no `node_modules` on the path:
+  #
+  #   machine.ts FAILED: Cannot find package 'zod'
+  #   fleet-size.ts: imported
+  #
+  # So the bundle carries BOTH rules with `zod` bundled in. `a-shell-script-asks
+  # -the-domain` settled the shape: a bundle under `skills/plot/scripts/board/`
+  # is how a shell script reaches a rule, and a skill's own script directory is
+  # what a plugin ships.
   #
   # TWO MODULES, BECAUSE THE VERDICT AND THE COUNT ARE TWO RULES. `headroomFor`
   # owns what a fork cost MEANS and `fleetSize` owns what to do about it; the
   # count rule takes the verdict as a reading rather than deriving it, so the
-  # thresholds have exactly one home and this block is the join.
-  #
-  # IMPORTED AS `.ts` WITH NO `.js` REWRITING. Node 24 strips types but does not
-  # remap a relative specifier, so `fleet-size.ts` may only `import type` from
-  # its neighbours — which is why the verdict arrives as a value here rather
-  # than being computed inside the rule.
-  start_domain="$(cd "$script_dir/../../.." 2>/dev/null && pwd)/packages/domain/src"
-  start_rule="file://$start_domain/rules/fleet-size.ts"
-  start_answer=$(PLOT_REQUESTED="$start_count" PLOT_RUNNING="$start_running" \
-                 PLOT_COST="$start_cost" PLOT_RULE="$start_rule" \
-                 PLOT_MACHINE="file://$start_domain/entities/machine.ts" \
-                 node --input-type=module - <<'NODE_EOF' 2>/dev/null
-const { fleetSize, DEFAULT_FLEET_SIZE } = await import(process.env.PLOT_RULE);
-const { headroomFor } = await import(process.env.PLOT_MACHINE);
-
-// AN ABSENT COUNT IS THE RULE'S DEFAULT, resolved here rather than in the
-// shell: the number and the argument for it have one home.
-const requested =
-  process.env.PLOT_REQUESTED === "" ? DEFAULT_FLEET_SIZE : Number(process.env.PLOT_REQUESTED);
-
-// An UNMEASURED cost is null, never zero: zero is the fastest fork there is and
-// would read as the clearest possible machine.
-const spawnCostMs = process.env.PLOT_COST === "" ? null : Number(process.env.PLOT_COST);
-
-const answer = fleetSize({
-  requested,
-  running: Number(process.env.PLOT_RUNNING),
-  spawnCostMs,
-  headroom: headroomFor(spawnCostMs),
-});
-
-process.stdout.write(`${answer.start}\t${answer.headroom}\t${answer.shortfall}`);
-NODE_EOF
-  )
+  # thresholds have exactly one home and the bundle's entry is the join.
+  #
+  # A RULE THAT CANNOT BE ASKED STARTS NOTHING AND SAYS SO. A missing bundle, a
+  # missing node, a module that throws all leave the answer empty. The direction
+  # is the reaper's: silence is never permission, and here permission would spawn
+  # detached processes.
+  start_bundle="$script_dir/board/plot-fleet-size.mjs"
+  start_answer=$(printf '%s\t%s\t%s' "$start_count" "$start_running" "$start_cost" \
+                 | node "$start_bundle" 2>/dev/null)
 
   if [ -z "$start_answer" ]; then
+    # THE REFUSAL NAMES THE CONDITION THAT FAILED, never two that hold. The
+    # message this replaced said *"it needs node 24 and a readable checkout of
+    # packages/domain"* to an operator whose node was 24.4.1 and whose checkout
+    # was readable — the import it could not resolve was named nowhere. A
+    # refusal that names the wrong condition costs more than one that says
+    # nothing, because it looks actionable. So the two causes are separated and
+    # tested in the order that distinguishes them: an absent bundle is a broken
+    # or partial installation, and a present bundle that answered nothing is the
+    # runtime underneath it.
     echo "plot-dispatch: --start could not ask how many agents to start — starting none." >&2
-    echo "  The rule is $start_rule" >&2
-    echo "  It needs node 24 and a readable checkout of packages/domain." >&2
+    if [ ! -f "$start_bundle" ]; then
+      echo "  The rule's bundle is missing: $start_bundle" >&2
+      echo "  Every bundle is tracked in git, so this is a broken or partial installation." >&2
+      echo "  In a development checkout, run 'pnpm build:board'." >&2
+    else
+      start_node_v="$(node --version 2>/dev/null)" || start_node_v=""
+      echo "  The rule's bundle is $start_bundle" >&2
+      if [ -z "$start_node_v" ]; then
+        echo "  No usable 'node' was found on PATH. The bundle needs node 20 or newer." >&2
+      else
+        echo "  The bundle is present but answered nothing under node $start_node_v." >&2
+        echo "  Run it directly to see why: printf '%s\\t%s\\t%s' '$start_count' '$start_running' '$start_cost' | node '$start_bundle'" >&2
+      fi
+    fi
     exit 1
   fi
 
+  # THREE FIELDS, AND THE SENTENCE IS LAST. `start_why` is printed to the
+  # operator below, so it travels; taking it as the whole remainder means a
+  # shortfall can never be truncated by its own punctuation.
   start_n=${start_answer%%$'\t'*}
   start_rest=${start_answer#*$'\t'}
   start_headroom=${start_rest%%$'\t'*}

package/plot-fleet-scan.sh

@@ -89,6 +89,9 @@
 # Output: per-plan wave report on stdout, terminated by a machine-countable
 #         summary line:
 #             summary: plans=1 waves=3 branches=5 claimed=1 eligible=2 blocked=1 deferred=1 waiting=1 prereq_missing=0 merge_detect=pr-merge host=ok main=main
+#         `host` is one of ok, partial, throttled, secondary, failed, unasked —
+#         `partial` means some of the host's states answered and some did not,
+#         so the PR readings below are incomplete rather than absent.
 #         `blocked` counts WAVES an earlier wave holds; `waiting` and
 #         `prereq_missing` count BRANCHES their `waits:` annotation holds.
 #         merge_detect names how merged-and-deleted branches were detected:
@@ -631,6 +634,19 @@ PR_LIST_LIMIT="${PLOT_PR_LIST_LIMIT:-1000}"
 #   secondary  — a burst refusal (`plot-host.sh` exit 6). Nothing is broken
 #                either, and it clears in seconds rather than minutes.
 #   failed     — any other failure (exit 3, or anything unclassified).
+#   partial    — SOME of the host's states answered and some did not
+#                (`plot-host.sh` exit 7). The rows that arrived are real and
+#                are parsed; what is missing is a whole state, so the reading
+#                is incomplete rather than absent. Only Bitbucket can produce
+#                it: `bb pr list` has no `all` state, so the arm asks once per
+#                state, while GitHub takes `--state all` in one call.
+#
+#                IT IS NOT `ok` AND IT IS NOT `failed`. Reporting `ok` would
+#                serve a page missing a state as a complete answer — #912, where
+#                nine branches read `commits, no PR ever opened` and two had
+#                live PRs. Reporting `failed` would throw away rows that
+#                arrived and make every branch `unknown`, which is not
+#                startable — the right refusal about the wrong thing.
 #   unasked    — no host to ask, or --offline WITHOUT `--next`. Not a
 #                degradation: the scan was never going to ask, and saying
 #                `failed` would report a fault where there is a configuration.
@@ -644,6 +660,43 @@ PR_LIST_LIMIT="${PLOT_PR_LIST_LIMIT:-1000}"
 # secondary limit waits minutes for a ceiling that cleared in seconds.
 HOST_VERDICT=unasked
 
+# The remote branches this scan tracks, read once for every question that asks.
+#
+# MOVED UP FROM ITS OLD POSITION (#333) so the host call below can be told which
+# branches to ask about. It is the same single `for-each-ref` it always was —
+# see the commentary at its old site — and the reasons it exists are unchanged:
+# `git show-ref --verify` was asked once per branch from two places, and
+# `%(objectname)` rides along free for the commit walk.
+REMOTE_REFS=$(git for-each-ref --format='%(refname:strip=3)%09%(objectname)' \
+  "refs/remotes/origin" </dev/null 2>/dev/null)
+
+# The branch names alone, space-separated — what the sweep asks the host about.
+#
+# THE JOIN'S OWN KEYS, AND NOTHING WIDER. `prefill_pr_states` indexes the host's
+# reply by branch and every row it cannot key is discarded, so the set this asks
+# about is exactly the set that could ever be used. Measured 2026-09-20 on
+# `quatico/quaweb-website`: 11 remote branches against 902 pull requests, of
+# which a listing hands over 50 — the sweep asks 11 questions and gets 11
+# answers, where the listing asked one and answered for 5%.
+#
+# `HEAD` IS DROPPED. `refs/remotes/origin/HEAD` is a symbolic ref naming the
+# default branch, not a branch of its own; asking the host about a branch called
+# `HEAD` spends a query to learn that nothing is named that.
+#
+# SPACE-SEPARATED, AND GIT IS WHAT MAKES THAT SAFE. Both this list and the
+# adapter's `PR_LIST_BRANCHES` are read by an unquoted `for`, so a name carrying
+# whitespace would split into two branches that do not exist. `git
+# check-ref-format` REFUSES a ref name containing a space or a tab — verified
+# 2026-09-20, both exit non-zero — so no such branch can reach this, and the
+# separator is git's guarantee rather than a hopeful convention.
+#
+# EMPTY IS A REAL ANSWER AND IT DISABLES THE SWEEP. A checkout with no remote
+# refs has no branches to ask about, and a sweep of nothing would state that
+# every tracked branch answered — a completeness claim over an empty set, which
+# would license `NONE` for branches nobody asked about. `prefill_pr_states`
+# falls back to the listing there, which is what it has always done.
+TRACKED_BRANCHES=$(printf '%s\n' "$REMOTE_REFS" | cut -f1 | grep -v '^HEAD$' | grep -v '^$' | tr '\n' ' ')
+
 prefill_pr_states() {
   [ "$HOST_LOOKUP_OK" = 1 ] || return 0
   [ -n "$HOST_STATE_CACHE" ] || return 0
@@ -672,10 +725,34 @@ prefill_pr_states() {
   # and /dev/null keeps the call working with the text simply unavailable.
   host_list_out="${HOST_STATE_CACHE:+$HOST_STATE_CACHE/pr-list.json}"
   host_list_out="${host_list_out:-/dev/null}"
+  # THE BRANCHES THIS SCAN TRACKS, HANDED TO THE HOST (#333). The adapter uses
+  # them only where it can — the Bitbucket arm sweeps its REST endpoint once per
+  # branch per state — and ignores them everywhere else, so the GitHub arm makes
+  # the single call it always made. Passing them unconditionally keeps one call
+  # shape here rather than a backend test this script has no business making.
+  #
+  # AN EMPTY SET PASSES NOTHING and the adapter lists as before. See
+  # `TRACKED_BRANCHES`: a completeness claim over an empty set would license
+  # `NONE` for branches nobody asked about.
+  _branch_args=()
+  for _tb in $TRACKED_BRANCHES; do _branch_args+=(--branch "$_tb"); done
   host_err=$("$script_dir/plot-host.sh" pr-list --state all --limit "$PR_LIST_LIMIT" --rich \
+         ${_branch_args[@]+"${_branch_args[@]}"} \
          </dev/null 2>&1 >"$host_list_out"); rc=$?
   js=$(cat "$host_list_out" 2>/dev/null)
-  if [ "$rc" -ne 0 ]; then
+  # A PARTIAL ANSWER TAKES THE PARSE PATH AND STILL DEGRADES THE VERDICT, which
+  # is a control-flow change rather than another `case` arm below: every other
+  # non-zero rc sets a verdict and returns BEFORE `$js` is read, because there
+  # is nothing to read. Here there is — the rows of the states that answered are
+  # already in `host_list_out`, since stdout is redirected to a file and stderr
+  # captured separately.
+  #
+  # BOTH HALVES ARE REQUIRED. Falling through without setting the verdict would
+  # report `ok` over a page missing a whole state, which is #912; returning
+  # early would throw away rows the host did answer with.
+  if [ "$rc" -eq 7 ]; then
+    HOST_VERDICT=partial
+  elif [ "$rc" -ne 0 ]; then
     # THREE OUTCOMES, NOT TWO. `unasked` already means "the question was
     # never put" (see HOST_VERDICT above: *not a degradation, the scan was
     # never asking*), and a host that cannot be ASKED AT ALL belongs there
@@ -743,7 +820,12 @@ prefill_pr_states() {
     return 0
   fi
   # The list arrived. An empty one arrived too — that is the whole distinction.
-  HOST_VERDICT=ok
+  #
+  # A PARTIAL VERDICT IS NOT OVERWRITTEN HERE. Exit 7 reaches this line
+  # deliberately, because its rows must be parsed; an unguarded `ok` would
+  # undo the one thing that distinguishes an incomplete page from a whole one
+  # and report #912 as a healthy reading.
+  [ "$HOST_VERDICT" = partial ] || HOST_VERDICT=ok
   # `pr-list` emits one compact JSON object per line. PARSED IN ONE PASS, and
   # that is a correctness-of-cost property rather than a style preference:
   # measured 2026-08-18 on this repo's 221 PRs, a `sed` per field per row —
@@ -864,9 +946,39 @@ EOF
   # A repository genuinely holding zero PRs loses nothing by being asked: it has
   # no branches with PRs for the join to serve either, so the cost is zero calls
   # in both readings.
-  if [ "$_pr_rows" -gt 0 ] && [ "$_pr_rows" -lt "$PR_LIST_LIMIT" ] 2>/dev/null; then
-    printf '1' > "$HOST_STATE_CACHE/.list-complete" 2>/dev/null || true
-  fi
+  #
+  # A SWEEP STATES ITS COMPLETENESS; A PAGE ONLY EVER IMPLIED IT (#333). The
+  # test above reads completeness off one page's size, which is the only
+  # evidence a listing offers — and on Bitbucket it is evidence the listing
+  # cannot give at all, since `bb pr list` returns a fixed 50 whether or not
+  # more exist. Where the adapter swept per branch it says so on stderr, naming
+  # both counts, and that sentence is a stronger claim than any row count: every
+  # tracked branch was asked and each one answered.
+  #
+  # THE ROW COUNT IS NOT CONSULTED ON THAT PATH, and it must not be. A sweep
+  # over 11 branches of which 2 have pull requests emits 2 rows — a true and
+  # complete answer that `0 < rows < PR_LIST_LIMIT` would also accept, but for
+  # the wrong reason, and which a sweep of 0 matches would fail outright despite
+  # being equally complete. Reading the claim the adapter made is exact where
+  # re-deriving it from the output is a coincidence.
+  #
+  # THE WORDING IS A CONTRACT between this script and `plot-host.sh`'s
+  # `pr_sweep_report`, pinned on both sides. A partial sweep never prints it, so
+  # a match is licence and a miss is silence — never a guess.
+  #
+  # WHAT IS LOST BY GETTING THIS WRONG IS COST, NOT CORRECTNESS. Without the
+  # marker, `host_pr_state --ask` falls through to one `pr-state` call per
+  # unjoined branch and still answers correctly — the per-branch N+1 that #216
+  # removed. That is why withholding the marker is always the safe direction and
+  # is what every failure path here does.
+  case "$host_err" in
+    *"pr-list sweep complete"*)
+      printf '1' > "$HOST_STATE_CACHE/.list-complete" 2>/dev/null || true ;;
+    *)
+      if [ "$_pr_rows" -gt 0 ] && [ "$_pr_rows" -lt "$PR_LIST_LIMIT" ] 2>/dev/null; then
+        printf '1' > "$HOST_STATE_CACHE/.list-complete" 2>/dev/null || true
+      fi ;;
+  esac
 }
 prefill_pr_states
 
@@ -1487,8 +1599,12 @@ worktree_locked() { # $1=worktree path → 0 when a lock is held there
 # on the population that must stay free. The walk here is a subject/emptiness
 # question rather than a timestamp read, but the guard is deliberately broad and
 # loosening it to fit this change is how a guard rots.
-REMOTE_REFS=$(git for-each-ref --format='%(refname:strip=3)%09%(objectname)' \
-  "refs/remotes/origin" </dev/null 2>/dev/null)
+# READ ABOVE `prefill_pr_states`, not here. The per-branch sweep (#333) hands
+# the host the branches this scan tracks, and that list is exactly what this
+# batch already answers — so the assignment moved up rather than a second
+# `for-each-ref` being added beside it. Everything documented above still
+# describes it; only the line's position changed, and it depends on nothing but
+# git, so nothing between the two points can read a different answer.
 
 # Whether `origin/$1` exists, answered from the batch rather than by spawning.
 #
@@ -4265,6 +4381,17 @@ elif [ "$HOST_VERDICT" = failed ]; then
   echo "        branch below reads from local evidence alone, and a branch whose"
   echo "        PR is unknown reads 'unknown' rather than 'open'. This is not a"
   echo "        rate limit — waiting will not clear it; check the host and auth."
+# THE PAGE IS SHORT, NOT ABSENT, and that is a different instruction to a
+# reader. The three notes above all say *no PR could be read*; here some were,
+# so the branches below are a MIXTURE — a branch shown without a PR may have one
+# in the state that failed. Telling a reader to treat this as an outage would
+# discard the rows that arrived; telling them nothing is #912, where nine
+# branches read as having no PR and two had live ones.
+elif [ "$HOST_VERDICT" = partial ]; then
+  echo "  note: the git host answered for some states and not others, so the PR"
+  echo "        list below is INCOMPLETE. A branch shown without a PR may have one"
+  echo "        in the state that failed — do not read this as evidence that a"
+  echo "        branch is unreviewed. Re-run to get the whole list."
 fi
 # A STALE PULSE SAYS SO. The fetch used to fail silently, which made a scan of
 # hour-old refs read exactly like a scan of current ones — the same