@plot-pm/board 0.11.0 → 0.12.0

package/plot-host.sh

@@ -41,6 +41,12 @@
 #   pr-ready <number>              take a PR out of draft
 #                                 merge the PR
 #   pr-list [--state open|merged|closed|all] [--limit N] [--rich]
+#                                 [--repo <owner/repo>] pins the list to ONE
+#                                 repository, exactly as pr-state and pr-merged
+#                                 do. A checkout with remotes on two hosts lets
+#                                 an unpinned list resolve the wrong one, and a
+#                                 caller joining it against `origin/*` refs then
+#                                 reads every branch as having no PR.
 #                                 JSON lines: {"number":N,"title":"...",
 #                                 "state":"...","head":"..."}
 #                                 --rich adds: draft, checks, mergeable, review,
@@ -122,10 +128,12 @@
 #   issue-list [--limit N]        open tracker issues as JSON lines:
 #                                 {"number":N,"title":"…","url":"…",
 #                                  "createdAt":"…"}
-#                                 READ-ONLY, and the only issue op here: Plot
-#                                 never writes to the tracker (no labels, no
-#                                 assignees, no close-on-merge), because a copy
-#                                 of tracker state ages into a lie.
+#                                 READ-ONLY. Plot writes no label, no assignee
+#                                 and no close-on-merge, because a copy of
+#                                 tracker state ages into a lie. The one write
+#                                 that exists is `issue-status`, and it records
+#                                 a status Plot itself just caused rather than
+#                                 mirroring one the tracker holds.
 #                                 `url` is "" when the host omits it, and a
 #                                 consumer renders the number as plain text
 #                                 rather than inventing an address — the rule
@@ -157,8 +165,8 @@
 #                                 tickets*, the failure this story is named for.
 #   issue-view <number>           ONE open issue as a single JSON object:
 #                                 {"number":N,"title":"…","body":"…","url":"…"}
-#                                 STILL READ-ONLY — the second issue op, and it
-#                                 reads. The board's *Create plan* action needs
+#                                 READ-ONLY — the second of the two issue reads.
+#                                 The board's *Create plan* action needs
 #                                 the issue's BODY as the problem statement, and
 #                                 issue-list deliberately omits it: the list is
 #                                 asked on a timer for every open issue, and a
@@ -183,6 +191,28 @@
 #                                 as issue-list. Jira answers 404 for a missing
 #                                 key, which is exit 3 here (the tracker moved),
 #                                 never an empty body.
+#   issue-status <key> <status>   THE ONE WRITE TO A TRACKER: record one status
+#                                 against one issue, and nothing else. No
+#                                 create, no close, no comment, no label — a
+#                                 plan referencing an issue is Plot's record,
+#                                 and the status is the single fact the tracker
+#                                 owns a copy of.
+#                                 JIRA ONLY. Exit 4 where `Tracker` is not jira:
+#                                 this adapter cannot be asked, which is neither
+#                                 a failure nor a silent success. The other
+#                                 vendor's projects surface is written by
+#                                 `plot-update-board.sh`, under its own
+#                                 credentials and through a different API — the
+#                                 reason the tracker port has two connectors.
+#                                 Prints `written` where the transition was
+#                                 performed and `no-target` where the workflow
+#                                 offers no such transition from the issue's
+#                                 current state — which is also what a repeated
+#                                 write reports, because the same status twice
+#                                 is the same status.
+#                                 The transition id is LOOKED UP, never guessed:
+#                                 ids are per workflow and per issue, so a
+#                                 hardcoded one writes to the wrong column.
 #   pr-body <number> --body B     replace the PR description
 #   rate-limit                    both GitHub budgets from `gh api rate_limit`.
 #                                 SUPERSEDED BY `limit`, and kept only because
@@ -556,7 +586,23 @@ jenkins_build_map() {
 # `LC_ALL=C` on the match: the CLI localises its messages, and a matcher that
 # only works in English would silently reclassify every miss as an outage for
 # anyone else.
+#
+# A MISSING CLI IS NOT A MISS, AND THE BARE `not found` ALTERNATIVE COULD NOT
+# TELL THEM APART. Measured 2026-09-06 with `gh` off `PATH`: the shell says
+# `bash: gh: command not found`, which matched — so `pr-merged` answered
+# `not-merged` where `plot-pr-merged.sh` answered `unaskable` about the same
+# branch. `not-merged` reads to `rules/landed.ts` as `none` (the host spoke and
+# said nothing merged), so `mayRemove` may permit a removal; `unaskable`
+# refuses. `plot-release-refs.sh` deletes remote refs on that answer and a
+# deleted ref is not re-creatable, so the two answers differ in the one
+# direction this estate has said it will not fail in.
+#
+# The bare alternative stays — it is what recognises a Bitbucket or Jira miss,
+# whose wording is neither `no pull requests found` nor `could not find`. What
+# it excludes is the shell's own phrasing for an absent binary, which is a
+# transport failure wearing a miss's words.
 is_lookup_miss() {
+  case "$1" in *'command not found'*) return 1 ;; esac
   LC_ALL=C grep -qiE 'no (pull request|pullrequest)s? (found|match)|could not find.*pull request|not found' <<<"$1"
 }
 
@@ -2067,6 +2113,13 @@ case "$op" in
   pr-list)
     state="open"
     rich=0
+    # PIN THE LIST TO ONE REPOSITORY, the same `--repo` `pr-state` and
+    # `pr-merged` already take. A checkout may carry several remotes on several
+    # hosts, and an unpinned `gh pr list` resolves whichever of them it prefers
+    # — so a caller comparing `origin/*` refs would join its refs against
+    # another repository's PRs and report every branch as having none. The
+    # caller knows which remote its refs came from; this op cannot guess it.
+    repo_args=()
     # `gh pr list` and `bb pr list` both cap at 30 by default. That is invisible
     # with --state open (few repos have 30 open PRs) and bites immediately with
     # --state all, where the newest 30 crowd out every older merged PR. A caller
@@ -2078,6 +2131,7 @@ case "$op" in
         --state) state="${2:?}"; shift 2 ;;
         --limit) limit="${2:?}"; shift 2 ;;
         --rich) rich=1; shift ;;
+        --repo) repo_args=(-R "${2:?}"); shift 2 ;;
         *) die "pr-list: unknown arg $1" ;;
       esac
     done
@@ -2196,7 +2250,7 @@ case "$op" in
           #   $jstatus != "ok"  → Jenkins could not answer; every row `unknown`.
           #   $jentry == null   → the branch has no Jenkins job; `none`.
           #   otherwise         → the joined colour's `checks`, job named on fail.
-          _gh_raw="$(pr_list_call gh pr list --state "$state" ${limit_args[@]+"${limit_args[@]}"} \
+          _gh_raw="$(pr_list_call gh ${repo_args[@]+"${repo_args[@]}"} pr list --state "$state" ${limit_args[@]+"${limit_args[@]}"} \
             --json number,title,state,headRefName,isDraft,mergeable,mergeStateStatus,reviewDecision,url)" || exit $?
           pr_list_report_truncation github "$limit" "$state" \
             "$(jq 'length' <<<"$_gh_raw" 2>/dev/null || echo 0)"
@@ -2225,7 +2279,7 @@ case "$op" in
               }'
         else
           # GitHub without Jenkins (or Jenkins not configured): use GitHub rollup
-          _gh_raw="$(pr_list_call gh pr list --state "$state" ${limit_args[@]+"${limit_args[@]}"} \
+          _gh_raw="$(pr_list_call gh ${repo_args[@]+"${repo_args[@]}"} pr list --state "$state" ${limit_args[@]+"${limit_args[@]}"} \
             --json number,title,state,headRefName,isDraft,statusCheckRollup,mergeable,mergeStateStatus,reviewDecision,url)" || exit $?
           pr_list_report_truncation github "$limit" "$state" \
             "$(jq 'length' <<<"$_gh_raw" 2>/dev/null || echo 0)"
@@ -2256,7 +2310,7 @@ case "$op" in
               }'
         fi
       else
-        _gh_raw="$(pr_list_call gh pr list --state "$state" ${limit_args[@]+"${limit_args[@]}"} \
+        _gh_raw="$(pr_list_call gh ${repo_args[@]+"${repo_args[@]}"} pr list --state "$state" ${limit_args[@]+"${limit_args[@]}"} \
           --json number,title,state,headRefName)" || exit $?
         pr_list_report_truncation github "$limit" "$state" \
           "$(jq 'length' <<<"$_gh_raw" 2>/dev/null || echo 0)"
@@ -2296,7 +2350,7 @@ case "$op" in
           # the GitHub arm uses, which is why it lives above the backend branch.
           # `bb`'s standing `unknown` becomes a real value where Jenkins answers.
           for _s in $bb_states; do
-            _bb_raw="$(pr_list_call bb pr list --state "$_s" --json)" || exit $?
+            _bb_raw="$(pr_list_call bb ${repo_args[@]+"${repo_args[@]}"} pr list --state "$_s" --json)" || exit $?
             pr_list_report_truncation bitbucket "$limit" "$_s" \
               "$(jq 'length' <<<"$_bb_raw" 2>/dev/null || echo 0)"
             printf '%s' "$_bb_raw" \
@@ -2325,7 +2379,7 @@ case "$op" in
         else
           # Bitbucket without Jenkins: checks remain unknown
           for _s in $bb_states; do
-            _bb_raw="$(pr_list_call bb pr list --state "$_s" --json)" || exit $?
+            _bb_raw="$(pr_list_call bb ${repo_args[@]+"${repo_args[@]}"} pr list --state "$_s" --json)" || exit $?
             pr_list_report_truncation bitbucket "$limit" "$_s" \
               "$(jq 'length' <<<"$_bb_raw" 2>/dev/null || echo 0)"
             printf '%s' "$_bb_raw" \
@@ -2334,7 +2388,7 @@ case "$op" in
         fi
       else
         for _s in $bb_states; do
-          _bb_raw="$(pr_list_call bb pr list --state "$_s" --json)" || exit $?
+          _bb_raw="$(pr_list_call bb ${repo_args[@]+"${repo_args[@]}"} pr list --state "$_s" --json)" || exit $?
           pr_list_report_truncation bitbucket "$limit" "$_s" \
             "$(jq 'length' <<<"$_bb_raw" 2>/dev/null || echo 0)"
           printf '%s' "$_bb_raw" \
@@ -2690,6 +2744,55 @@ case "$op" in
     fi
     ;;
 
+  issue-status)
+    # THE ONE WRITE TO A TRACKER, and the amendment this op records: Plot writes
+    # a STATUS to the tracker it was told about, and writes nothing else. No
+    # ticket is created, none is closed, no comment, label or assignee is
+    # touched. A plan referencing an issue stays Plot's record; the status is
+    # the one fact the tracker owns a copy of, because it is the one a person
+    # reads in the tracker rather than in Plot.
+    #
+    # JIRA ONLY, and deliberately so rather than by omission. This vendor's
+    # projects surface has a script of its own (`plot-update-board.sh`) reached
+    # by its own connector, and the two write through different APIs under
+    # different credentials — which is why the tracker port has two connectors
+    # rather than one arm with a branch. A repo whose `Tracker` is not jira gets
+    # exit 4 here: this adapter cannot be asked, which is not a failure and not
+    # a silent success.
+    #
+    # IDEMPOTENT BY NATURE. The same status written twice is the same status,
+    # and Jira answers a transition to the state an issue already holds by
+    # naming no such transition — which this reports as `no-target` rather than
+    # as a failure.
+    key="${1:?issue-status needs an issue key}"; shift
+    want="${1:?issue-status needs a status}"; shift
+    [ "$(tracker_scheme)" = "jira" ] || exit 4
+    jira_require_config
+    # THE TRANSITION IS LOOKED UP, NEVER GUESSED. Jira transitions are per
+    # workflow and per issue: the id for "In Progress" differs between projects
+    # and the transition may not be available from the issue's current state at
+    # all. A hardcoded id writes a status to the wrong column silently.
+    raw="$(jira_curl "/rest/api/2/issue/$key/transitions")"; curl_rc=$?
+    body_json="$(jira_check "$raw" "$curl_rc")" || exit $?
+    tid="$(printf '%s' "$body_json" | jq -r --arg want "$want" \
+      '[.transitions[]? | select((.name // "" | ascii_downcase) == ($want | ascii_downcase)
+                                 or ((.to.name // "" | ascii_downcase) == ($want | ascii_downcase)))]
+       | .[0].id // ""')"
+    if [ -z "$tid" ]; then
+      # NO SUCH TRANSITION IS AN ANSWER, not a failure. The tracker was reached
+      # and holds nowhere to put this status — either the workflow has no such
+      # state or the issue is already in it. Reporting it as a failure would
+      # make a repeated write look like an outage.
+      printf '%s\n' 'no-target'
+      exit 0
+    fi
+    raw="$(jira_curl "/rest/api/2/issue/$key/transitions" \
+             -X POST -H 'Content-Type: application/json' \
+             --data "$(jq -cn --arg id "$tid" '{transition:{id:$id}}')")"; curl_rc=$?
+    jira_check "$raw" "$curl_rc" >/dev/null || exit $?
+    printf '%s\n' 'written'
+    ;;
+
   pr-body)
     num="${1:?pr-body needs a PR number}"; shift
     body=""
@@ -2955,6 +3058,6 @@ case "$op" in
     ;;
 
   *)
-    die "unknown op '$op' (backend|default-branch|pr-state|pr-create|pr-merge|pr-list|issue-list|issue-view|pr-body|rate-limit|limit|ci-limit|spend-rate)"
+    die "unknown op '$op' (backend|default-branch|pr-state|pr-create|pr-merge|pr-list|issue-list|issue-view|issue-status|pr-body|rate-limit|limit|ci-limit|spend-rate)"
     ;;
 esac

package/plot-monitor-subject.sh

@@ -0,0 +1,194 @@
+#!/usr/bin/env bash
+# Plot helper: the ONE answer to "is this monitor's subject still there?"
+#
+# SOURCED, NOT RUN, by `plot-worker-monitor.sh` and `plot-agent-monitor.sh`.
+# Both need the same computation and neither renders it the same way, which is
+# the same shape as `plot-worker-state.sh` and `plot-pr-merged.sh` — and the
+# same reason. `plot-worker-state.sh` carried five of its six states in
+# duplicate until 2026-08-18, and the copies had already drifted on the sixth.
+# Two monitors deciding independently when to stop would drift the same way, and
+# the failure would be silent: one monitor left running forever while its twin
+# exits is exactly the leak this file exists to close, half-fixed.
+#
+# ═══════════════════════════════════════════════════════════════════════════
+# WHY A MONITOR NEEDS THIS AT ALL
+# ═══════════════════════════════════════════════════════════════════════════
+#
+# Measured 2026-08-30 and written up in
+# `docs/research/2026-08-30-what-ends-a-monitor.md`: **nothing ended a monitor.**
+# On an ordinary finish and on a `Worker bound` timeout alike, the wrapper's
+# `wait "$agent"` returns, the wrapper writes `.plot-worker.exit` and exits, and
+# both monitors are re-parented to `init` and loop forever. 34 of 40 monitors on
+# the machine were `ppid=1` at the time of measurement, and 100 forks cost
+# 23.3 ms against 4.8 ms on a quiet estate.
+#
+# The one run whose monitors WERE terminated is explained in that document and
+# is not a mechanism: `nohup` does not `setsid`, so an orphan keeps the
+# DISPATCHING SHELL's process group and a group kill sweeps it up collaterally.
+# That fires when a human closes a terminal and never when a worker finishes —
+# the opposite of a lifetime.
+#
+# ═══════════════════════════════════════════════════════════════════════════
+# THE SUBJECT IS THE AGENT, AND THAT IS THE WHOLE DESIGN
+# ═══════════════════════════════════════════════════════════════════════════
+#
+# A monitor exists to watch a dispatched agent. When that agent is gone there is
+# nothing left to measure, so the monitor has finished its job rather than been
+# interrupted — which is why this is a MEASUREMENT and not a timer.
+#
+# The plan forbids a timer explicitly, and the measurement says why: *"a monitor
+# exiting after N seconds regardless would pass the visible assertions and
+# destroy the property the whole plan rests on — a monitor that stops publishing
+# means something."* A monitor that stops because its subject stopped carries
+# information. One that stops because a clock ran out carries none, and is
+# indistinguishable from one that crashed.
+#
+# THE AGENT COVERS ALL THREE ENDINGS. `--stop` kills the agent
+# (`plot-dispatch.sh:752`); the `Worker bound` kills the agent
+# (`plot-worker-loop.sh:172`); an ordinary finish is the agent exiting. In every
+# case the wrapper survives just long enough to write `.plot-worker.exit` and
+# then exits too. So watching the agent is sufficient, and watching the WRAPPER
+# would be wrong: the wrapper outlives the agent by design, and a monitor bound
+# to it would publish about a desk whose agent left.
+#
+# ═══════════════════════════════════════════════════════════════════════════
+# AN ABSENT PID FILE IS `starting`, NEVER `gone`
+# ═══════════════════════════════════════════════════════════════════════════
+#
+# `plot-dispatch.sh:478` records a sub-millisecond gap in which the wrapper has
+# started and `.plot-worker.pid` is not yet written. The monitors start INSIDE
+# that window — they are backgrounded before the agent, deliberately, so they
+# exist before their subject does.
+#
+# So a monitor that read an absent pid file as `gone` would exit immediately on
+# every single dispatch, and the leak would be replaced by a monitor that never
+# runs. That is worse than the bug: an absent monitor is invisible, where an
+# orphaned one at least shows up in `ps`.
+#
+# Three answers, not two:
+#
+#   starting   no pid file yet, or an unreadable one — the wrapper has not
+#              written it. Keep going; say nothing.
+#   alive      the pid file names a process that exists. Keep going.
+#   gone       the pid file names a process that does not exist. Stop.
+#
+# `starting` and `alive` are both "keep going", and they are kept apart anyway
+# because the reason differs and a caller reporting them identically would lose
+# the distinction the startup window depends on.
+#
+# ═══════════════════════════════════════════════════════════════════════════
+# THE LOWER BOUND IS THE CALLER'S, AND IT IS AN ORDERING
+# ═══════════════════════════════════════════════════════════════════════════
+#
+# The plan requires a monitor to outlive its agent long enough to record its
+# finding — the Attaching slice's property, which this slice must not eat. This
+# file does not enforce that, because it cannot: it answers a question and
+# renders nothing.
+#
+# What enforces it is the ORDER in the callers: publish the pass, THEN ask.
+# Every monitor therefore gets one final published pass after its agent has
+# gone, which is the lower bound expressed as sequence rather than as a sleep.
+# A caller that asked first and published second would satisfy the upper bound
+# and silently lose the lower one — so the order is asserted in the tests, not
+# left to a comment.
+
+# `kill -0` is the liveness question, and it is the same one
+# `plot-worker-state.sh` asks. It sends no signal; it only reports whether the
+# pid can be signalled. A pid we do not own answers EPERM rather than ESRCH,
+# which `kill -0` still reports as success — correct here, since a process we
+# cannot signal is nonetheless a process that exists.
+#
+# `$1` = the path to the agent's pid file (`.plot-worker.pid`).
+# Prints exactly one of: starting | alive | gone
+plot_monitor_subject() {
+  local pid_file="${1:-}" pid
+
+  # No path at all: a hand-run monitor with no worktree, which has no subject to
+  # outlive and must not exit on its first pass. `starting` is the honest answer
+  # — there is nothing here that says the subject is gone.
+  [ -n "$pid_file" ] || { printf 'starting'; return 0; }
+
+  # NO PID FILE SPLITS TWO CASES, and reading them as one is what made monitors
+  # immortal. `starting` is right only while the desk is still there and the
+  # wrapper has not yet written the pid. If the DIRECTORY the pid file lives in
+  # is gone, the desk was removed — there is no subject to wait for and none is
+  # coming, so the honest answer is `gone`.
+  #
+  # Measured on CI 2026-08-31: 14 monitors at PPID 1, aged 11-13 minutes, each
+  # holding a `sleep 1`, after every test in the reconcile suite had PASSED.
+  # A test's fixture is removed at teardown, so its pid file vanishes BEFORE the
+  # agent does; `plot_monitor_wait` then never sees `gone` and loops forever,
+  # holding node's event loop open until the job ceiling kills it. That is the
+  # whole of the reconcile-suite hang, and it is why this is a two-case answer
+  # rather than one.
+  #
+  # PRODUCTION IS UNCHANGED: a real worktree outlives its agent, so the
+  # directory is present and this reads `starting` exactly as before.
+  if [ ! -f "$pid_file" ]; then
+    [ -d "$(dirname "$pid_file")" ] && { printf 'starting'; return 0; }
+    printf 'gone'; return 0
+  fi
+
+  pid=$(cat "$pid_file" 2>/dev/null | tr -d ' \n')
+
+  # A file that exists but holds no digits is a half-written pid, which is the
+  # startup window caught mid-`printf`. Not gone.
+  case "$pid" in
+    '' | *[!0-9]*) printf 'starting'; return 0 ;;
+  esac
+
+  if kill -0 "$pid" 2>/dev/null; then
+    printf 'alive'
+  else
+    printf 'gone'
+  fi
+}
+
+# Sleep up to `$1` seconds, but stop early the moment the subject at `$2` is
+# gone. Returns 0 to publish another pass, 1 to leave.
+#
+# ═══════════════════════════════════════════════════════════════════════════
+# WHY THE WAIT IS SPLIT WHEN THE PUBLISHING IS NOT
+# ═══════════════════════════════════════════════════════════════════════════
+#
+# THE TWO CADENCES MUST STAY APART. The plan is explicit: the WorkerMonitor
+# samples the process table every 30 s because a CPU delta is meaningless
+# sampled further apart, and the AgentMonitor asks the host every 300 s because
+# this repo has already measured what host questions on a fast loop cost. *"One
+# subject wants tight sampling of a cheap fact; the other occasional sampling of
+# an expensive one. Merging them would force one of those two to be wrong."*
+#
+# SO ONLY THE WAIT IS SPLIT, NEVER THE PASS. Publishing still happens on the
+# monitor's own interval, unchanged — nothing here makes the AgentMonitor ask
+# the host more often, and its 300 s stays 300 s. What is split is the IDLE TIME
+# between passes, into short naps with a `kill -0` between them.
+#
+# WITHOUT THIS, THE UPPER BOUND IS THE INTERVAL. An AgentMonitor checking only
+# after its full sleep would outlive an agent that finished in ten seconds by
+# nearly five minutes. Bounded, technically — and still an orphan on every
+# dispatch, on an estate where dispatches are frequent. The measurement that
+# opened this slice counted 34 orphans; a five-minute window would have counted
+# plenty too.
+#
+# THE PROBE IS FREE, WHICH IS WHY IT MAY BE FREQUENT. `kill -0` sends no signal
+# and asks no host — it is a single syscall against the process table, the same
+# question `plot-worker-state.sh` asks. The expensive half of an AgentMonitor
+# pass is the host round trip, and that is in the PASS, not here.
+#
+# THE NAP IS THE GRANULARITY, and one second is chosen against the WorkerMonitor
+# rather than in the abstract: a monitor may not outlive its agent by more than
+# the tighter of the two cadences, or the fast monitor's exit would be slower
+# than its own sampling. Any interval SHORTER than one nap sleeps once and is
+# unaffected, which keeps `PLOT_MONITOR_INTERVAL=1` in a test behaving exactly
+# as it reads.
+plot_monitor_wait() { # $1 = seconds to wait, $2 = pid file
+  local remaining="${1:-0}" pid_file="${2:-}" nap
+  while [ "$remaining" -gt 0 ]; do
+    nap=1
+    [ "$remaining" -lt 1 ] && nap="$remaining"
+    sleep "$nap" || return 1
+    remaining=$((remaining - nap))
+    [ "$(plot_monitor_subject "$pid_file")" = gone ] && return 1
+  done
+  return 0
+}

package/plot-plan-meta.sh

@@ -20,9 +20,17 @@
 # Two plan formats are recognized:
 #
 #   canonical    the plan template's `## Status` body section:
-#                    - **Phase:** Approved
+#                    - **State:** Approved
 #                    - **Type:** feature
-#                (bullet, bold, and plain `Phase: ...` variants all accepted)
+#                (bullet, bold, and plain `State: ...` variants all accepted)
+#
+#                `State:` is the field Plot writes. `Phase:` is the name it
+#                carried until 2026-09-07 and is read as the alternate, the
+#                same way front matter reads `status:` over `phase:` below.
+#                THE DUAL READ IS PERMANENT, NOT SCAFFOLDING: a plan file may
+#                have been written a year ago or copied from another project,
+#                and a Plot that refused to read `Phase:` would be worse at its
+#                own job than the one that confused two words.
 #
 #   frontmatter  YAML front matter at the top of the file:
 #                    ---
@@ -88,7 +96,8 @@
 #                  which is a queue. (`ready-for-review`/`in-review` DO
 #                  normalize onto `approved` — those are synonyms; this is not.)
 #   phase_alt_raw  secondary value when the file carries two (front matter
-#                  status: AND phase:), else ""
+#                  status: AND phase:, or a `## Status` body carrying both
+#                  State: AND Phase:), else ""
 #   phase_alt      normalized phase_alt_raw (NONE when absent)
 #   type           normalized plan type (feature|bug|docs|infra or "")
 #   title          plan title: front matter `title:` wins, else the first H1
@@ -128,6 +137,19 @@
 #                  says: a prerequisite no plan declares still parses, and the
 #                  scan is what turns that into a verdict. `waits:` and
 #                  `deferred:` are independent — a branch may carry both.
+#                  `<!-- builds: normalizeVersion, a shared helper -->` names
+#                  what this slice BUILDS, reported as
+#                  `waves[].branches[].builds`. OPTIONAL, like `Sprint:` and
+#                  `Story:` — a docs plan, a rejection or a measurement builds
+#                  nothing nameable, and nothing warns about its absence. The
+#                  key is ABSENT where none was written, never "". The value
+#                  runs to the closing marker rather than stopping at the first
+#                  space the way `waits:` does: a prerequisite is a branch NAME
+#                  and a deliverable is a name plus enough words to search for.
+#                  An annotation rather than a `Builds:` field line precisely
+#                  BECAUSE annotations already work in both slice dialects from
+#                  one block of code — a field line would need two spellings,
+#                  and the template writes the list dialect.
 #   prs            PR numbers, sorted and unique, read from EITHER spelling:
 #                  `→ #NNN` / `→ owner/repo#NNN` links in the `## Branches`
 #                  section, OR `PR: #NNN` in a `## Waves` `### ` heading. The
@@ -382,7 +404,7 @@ function reset_state() {
   fm_review = ""; fm_impl = ""; fm_approved = ""; fm_started = ""; fm_released = ""
   fm_delivered = ""; fm_design = ""
   fm_rounds = ""
-  canon_phase = ""; canon_type = ""
+  canon_state = ""; canon_phase = ""; canon_type = ""
   canon_sprint = ""; canon_story = ""; canon_assignee = ""
   canon_review = ""; canon_impl = ""; canon_approved = ""; canon_released = ""
   canon_delivered = ""; canon_design = ""
@@ -401,6 +423,7 @@ function reset_state() {
   delete wave_names; delete wave_of; delete wave_seq; delete wave_count
   delete deferred_of; delete deferred_why; delete claimed_of; delete ordered_b; n_waves = 0
   delete waits_of; delete waits_set
+  delete builds_of; delete builds_set
   delete started; n_started = 0
   fm_changelog = ""
   delete changelog; n_changelog = 0; changelog_seen = 0; cl_open = 0
@@ -411,8 +434,14 @@ function emit_record(   fmt, praw, palt_raw, traw, title, sprint, story, assigne
     praw = (fm_status != "") ? fm_status : fm_phase
     palt_raw = (fm_status != "" && fm_phase != "") ? fm_phase : ""
     traw = fm_type
-  } else if (canon_phase != "") {
-    fmt = "canonical"; praw = canon_phase; palt_raw = ""; traw = canon_type
+  } else if (canon_state != "" || canon_phase != "") {
+    # `State:` is primary and `Phase:` the alternate, exactly as front matter
+    # reads `status:` over `phase:`. A file carrying both reports the
+    # disagreement rather than hiding it.
+    fmt = "canonical"
+    praw = (canon_state != "") ? canon_state : canon_phase
+    palt_raw = (canon_state != "" && canon_phase != "") ? canon_phase : ""
+    traw = canon_type
   } else {
     fmt = "none"; praw = ""; palt_raw = ""; traw = ""
   }
@@ -551,6 +580,10 @@ function emit_record(   fmt, praw, palt_raw, traw, title, sprint, story, assigne
       # reading `waits_on` gets a branch name or nothing — never a blank string
       # that reads as a prerequisite with no name.
       if (waits_set[i] == 1) out = out ",\"waits_on\":\"" jesc(waits_of[i]) "\""
+      # ABSENT, NOT EMPTY, for the same reason `waits_on` is: a slice that
+      # names no deliverable emits no key, so a consumer reads a name or
+      # nothing. An empty string would read as a deliverable called "".
+      if (builds_set[i] == 1) out = out ",\"builds\":\"" jesc(builds_of[i]) "\""
       out = out "}"
       first = 0
     }
@@ -748,7 +781,8 @@ in_comment {
 }
 section == "status" {
   lower = tolower($0)
-  if (lower ~ /^[ \t]*[-*]?[ \t]*\**phase[:*]/ && canon_phase == "") canon_phase = val_after_colon($0)
+  if (lower ~ /^[ \t]*[-*]?[ \t]*\**state[:*]/ && canon_state == "") canon_state = val_after_colon($0)
+  else if (lower ~ /^[ \t]*[-*]?[ \t]*\**phase[:*]/ && canon_phase == "") canon_phase = val_after_colon($0)
   else if (lower ~ /^[ \t]*[-*]?[ \t]*\**type[:*]/ && canon_type == "") canon_type = val_after_colon($0)
   else if (lower ~ /^[ \t]*[-*]?[ \t]*\**sprint[:*]/ && canon_sprint == "") canon_sprint = val_after_colon($0)
   else if (lower ~ /^[ \t]*[-*]?[ \t]*\**story[:*]/ && canon_story == "") canon_story = val_after_colon($0)
@@ -925,6 +959,39 @@ section == "slices" && slice_shape != "heading" {
   # `has_waits` carries presence separately from the value, because ABSENT and
   # EMPTY are different answers — a branch declaring no prerequisite emits no
   # `waits_on` key at all.
+  # WHAT THIS SLICE BUILDS: `<!-- builds: normalizeVersion, a shared helper -->`.
+  #
+  # AN ANNOTATION, NOT A FIELD LINE, and that is what makes it work in BOTH
+  # slice dialects with no dialect-specific code. Annotations bind to the line
+  # carrying the branch name — the list item in one spelling, the `### `
+  # heading in the other — and both dialects already read `deferred:`,
+  # `claimed:` and `waits:` with the identical block. A `Builds:` field line
+  # would have had two spellings to parse, and the template writes the LIST
+  # dialect, so the heading-only version would be absent from every plan
+  # created from it.
+  #
+  # IT BELONGS TO THE SLICE, NEVER TO THE PLAN. A plan builds several things
+  # and each slice builds one; a plan-level list is searched as a whole and
+  # reported against the wrong slice.
+  #
+  # The value runs to the closing marker, the way `deferred:` does and unlike
+  # `waits:`. A prerequisite is a branch NAME and stops at whitespace; a
+  # deliverable is a name plus enough words to search for — `normalizeVersion,
+  # a shared helper` — and cutting it at the first space would leave the half
+  # that identifies it.
+  #
+  # `has_builds` carries presence separately from the value, exactly as
+  # `waits:` does: a slice declaring nothing emits no key, so a consumer reads
+  # a deliverable or nothing and never a blank string that looks like one.
+  builds_note = ""
+  has_builds = 0
+  if ($0 ~ /<!--[ \t]*builds:[ \t]*/) {
+    _bl = $0
+    sub(/^.*<!--[ \t]*builds:[ \t]*/, "", _bl)
+    sub(/[ \t]*-->.*$/, "", _bl)
+    builds_note = trim(_bl)
+    if (builds_note != "") has_builds = 1
+  }
   waits_note = ""
   has_waits = 0
   if ($0 ~ /<!--[ \t]*waits:[ \t]*/) {
@@ -982,6 +1049,8 @@ section == "slices" && slice_shape != "heading" {
     # so a branch that declares none emits no key.
     waits_of[n_branches] = waits_note
     waits_set[n_branches] = has_waits
+    builds_of[n_branches] = builds_note
+    builds_set[n_branches] = has_builds
     ordered_b[n_branches] = b
   }
   line = $0
@@ -1066,6 +1135,39 @@ section == "slices" && slice_shape == "heading" {
   # The prerequisite, read exactly as the list-item spelling reads it. Both
   # dialects emit the same waves[], so a field added to one only would break
   # that contract the first time a plan migrated.
+  # WHAT THIS SLICE BUILDS: `<!-- builds: normalizeVersion, a shared helper -->`.
+  #
+  # AN ANNOTATION, NOT A FIELD LINE, and that is what makes it work in BOTH
+  # slice dialects with no dialect-specific code. Annotations bind to the line
+  # carrying the branch name — the list item in one spelling, the `### `
+  # heading in the other — and both dialects already read `deferred:`,
+  # `claimed:` and `waits:` with the identical block. A `Builds:` field line
+  # would have had two spellings to parse, and the template writes the LIST
+  # dialect, so the heading-only version would be absent from every plan
+  # created from it.
+  #
+  # IT BELONGS TO THE SLICE, NEVER TO THE PLAN. A plan builds several things
+  # and each slice builds one; a plan-level list is searched as a whole and
+  # reported against the wrong slice.
+  #
+  # The value runs to the closing marker, the way `deferred:` does and unlike
+  # `waits:`. A prerequisite is a branch NAME and stops at whitespace; a
+  # deliverable is a name plus enough words to search for — `normalizeVersion,
+  # a shared helper` — and cutting it at the first space would leave the half
+  # that identifies it.
+  #
+  # `has_builds` carries presence separately from the value, exactly as
+  # `waits:` does: a slice declaring nothing emits no key, so a consumer reads
+  # a deliverable or nothing and never a blank string that looks like one.
+  builds_note = ""
+  has_builds = 0
+  if ($0 ~ /<!--[ \t]*builds:[ \t]*/) {
+    _bl = $0
+    sub(/^.*<!--[ \t]*builds:[ \t]*/, "", _bl)
+    sub(/[ \t]*-->.*$/, "", _bl)
+    builds_note = trim(_bl)
+    if (builds_note != "") has_builds = 1
+  }
   waits_note = ""
   has_waits = 0
   if ($0 ~ /<!--[ \t]*waits:[ \t]*/) {
@@ -1107,6 +1209,8 @@ section == "slices" && slice_shape == "heading" {
     claimed_of[n_branches] = claim_note
     waits_of[n_branches] = waits_note
     waits_set[n_branches] = has_waits
+    builds_of[n_branches] = builds_note
+    builds_set[n_branches] = has_builds
     ordered_b[n_branches] = b
   }