@plot-pm/board 0.13.0 → 0.14.0

package/package.json

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

@@ -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=""
@@ -172,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
@@ -417,6 +444,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" "Delivered"
   return 0
 }
 
@@ -598,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
@@ -3206,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"