@plot-pm/board 0.10.0 → 0.12.0

package/plot-deliver.sh

@@ -10,7 +10,7 @@
 #         run did the work or found it already done); 1 on a refusal or a
 #         failure, with the reason on stderr.
 #
-# WHY THIS EXISTS. The board computes `allWavesMerged` — exactly the condition
+# WHY THIS EXISTS. The board computes `allSlicesMerged` — exactly the condition
 # that says a plan is ready to deliver — but the transition itself lives only in
 # `/plot-deliver`'s prose. So `Delivered` in the board asked for a caller with
 # nothing safe to call, and an implementer reaching that point would have
@@ -116,105 +116,64 @@ case "$phase" in
 esac
 
 # ---------------------------------------------------------------------------
-# Step 2 — verify all non-deferred branches are merged
+# Step 2 — ask whether every non-deferred branch has merged
 # ---------------------------------------------------------------------------
 #
-# This is one of Plot's four phase guardrails. We call plot-impl-status.sh to
-# check the merge state of all branches. Any branch that is not MERGED and not
-# deferred is a refusal.
-
-# Parse branches from the plan file, respecting deferred annotations.
-# Read the plan's branches section (from EITHER spelling — ## Branches or ## Waves).
-plan_content=$(cat "$plan_file")
-
-# Extract branch lines from ## Branches or ## Waves section
-branches_section=$(printf '%s' "$plan_content" | sed -n '/^## *[Bb]ranches\|^## *[Ww]aves/,/^## /p')
-
-# A BRANCH LINE CARRIES A BRANCH PREFIX, and without that test a changelog
-# bullet is read as a branch. The section range above closes at the next `## `,
-# but a plan whose `## Changelog` bullet mentions a backticked identifier —
-# `impl`, `pr_ready`, `--migrate`, `/api/story` were the four measured on
-# 2026-08-27 — hands one of those to the merge check, which then refuses
-# delivery over a branch that does not exist and never will.
+# This is one of Plot's four phase guardrails, and it is NO LONGER DECIDED HERE.
 #
-# Four fully-merged plans were undeliverable for this reason. The prefixes come
-# from `Branch prefixes` rather than a hardcoded list, the same derivation
-# `plot-fleet-scan.sh:187` uses, so a project with its own prefixes is read
-# correctly and one with none falls back to Plot's defaults.
-prefix_re=$(bash "$script_dir/plot-config.sh" get "Branch prefixes" "idea/, feature/, bug/, docs/, infra/" \
-  | tr -d ' ' | tr ',' '\n' | sed 's#/$##' | grep -v '^$' | paste -sd'|' - )
-[ -n "$prefix_re" ] || prefix_re="idea|feature|bug|docs|infra"
-
-# Parse branches from old-style ## Branches section (backtick-quoted on list lines)
-old_style_branches=$(printf '%s' "$branches_section" \
-  | grep -oE "^- \`($prefix_re)/[A-Za-z0-9_./-]+\`" 2>/dev/null \
-  | sed 's/^- `//; s/`$//' \
-  | sort -u || true)
-
-# Parse branches from new-style ## Waves section (Branch: in ### headings)
-new_style_branches=$(printf '%s' "$branches_section" \
-  | grep -oE "### .*\(Branch: ($prefix_re)/[A-Za-z0-9_./-]+" 2>/dev/null \
-  | sed 's/.*Branch: //' \
-  | sort -u || true)
-
-# Combine both styles
-all_branches=$(printf '%s\n%s' "$old_style_branches" "$new_style_branches" | grep -v '^$' | sort -u || true)
-
-if [ -z "$all_branches" ]; then
-  echo "step: no branches found in plan — proceeding (nothing to verify)"
-else
-  # Check which branches are deferred. A deferred branch has `<!-- deferred:` on its line.
-  deferred_branches=""
-  non_deferred_branches=""
-
-  for br in $all_branches; do
-    # Check both spellings: old style has branch on a `- \`branch\`` line,
-    # new style has branch in a `### ... (Branch: branch ...)` heading.
-    if printf '%s' "$branches_section" | grep -F "\`$br\`" | grep -q '<!-- *deferred' 2>/dev/null; then
-      deferred_branches="${deferred_branches}${br}
-"
-    elif printf '%s' "$branches_section" | grep "Branch: $br" | grep -q '<!-- *deferred' 2>/dev/null; then
-      deferred_branches="${deferred_branches}${br}
-"
-    else
-      non_deferred_branches="${non_deferred_branches}${br}
-"
-    fi
-  done
+# THE SCRIPT USED TO PARSE THE PLAN ITSELF. Ninety-odd lines of `sed` and `grep`
+# re-derived the branches section, re-derived which lines named a branch, and
+# re-derived which of those were deferred — a second implementation of a job
+# `plot-plan-meta.sh` already owns, with its own bug history. The measured ones:
+# a `## Changelog` bullet read as a branch (four fully-merged plans undeliverable,
+# 2026-08-27), and a `## Slices` section that parsed to ZERO branches so the gate
+# passed having checked nothing (two approved plans, 2026-08-30).
+#
+# A THIRD was measured while this block was being removed, and it is the one
+# that argues hardest for the removal. On
+# `docs/plans/2026-08-21-waves-name-themselves.md` the old range matched a
+# `## Waves` heading that opens DESIGN PROSE — the plan argues for that spelling
+# and illustrates it — and closed at the next `## `, never reaching the real
+# `## Branches` section a hundred lines below. It read three branch names out of
+# the illustration, one of them `bug/one` from inside a code fence, and reported
+# none of the plan's actual work. `plot-plan-meta.sh` reads the same file
+# correctly. That plan was delivered by hand.
+#
+# So the reading stays in the scripts and the DECISION moves inside:
+# `plot-plan-meta.sh` says which branches the plan names and which it gave up,
+# `plot-impl-status.sh` says which the host merged, and the domain's `deliver`
+# rule says whether that makes the plan deliverable. Manifesto Principle 3 —
+# scripts collect and report — with the line drawn where the design plan draws
+# it: parsing a plan is adaptation, "these branches make the plan deliverable"
+# is a decision.
+#
+# THE REFUSAL SENTENCE COMES BACK FROM THE DOMAIN, unchanged in wording, so the
+# two cannot describe one rule differently.
 
-  # Trim trailing newlines
-  non_deferred_branches=$(printf '%s' "$non_deferred_branches" | grep -v '^$' || true)
-  deferred_branches=$(printf '%s' "$deferred_branches" | grep -v '^$' || true)
-
-  # Get implementation status for all branches
-  impl_status=$(bash "$script_dir/plot-impl-status.sh" "$slug" 2>/dev/null) || impl_status='{"prs":[]}'
-
-  # Check each non-deferred branch is merged
-  unmerged_branches=""
-  for br in $non_deferred_branches; do
-    [ -z "$br" ] && continue
-    # Look for this branch in the impl status. A branch is merged if its PR state is MERGED.
-    pr_state=$(printf '%s' "$impl_status" | jq -r --arg br "$br" '.prs[] | select(.branch == $br) | .state' 2>/dev/null || true)
-    if [ "$pr_state" != "MERGED" ]; then
-      unmerged_branches="${unmerged_branches}${br}
-"
-    fi
-  done
+ask_mjs="$script_dir/board/plot-ask.mjs"
+if [ ! -f "$ask_mjs" ]; then
+  die "cannot find $ask_mjs — run 'pnpm build:board' to build it."
+fi
 
-  unmerged_branches=$(printf '%s' "$unmerged_branches" | grep -v '^$' || true)
+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."
 
-  if [ -n "$unmerged_branches" ]; then
-    unmerged_count=$(printf '%s\n' "$unmerged_branches" | wc -l | tr -d ' ')
-    unmerged_list=$(printf '%s' "$unmerged_branches" | tr '\n' ', ' | sed 's/, $//')
-    die "cannot deliver: $unmerged_count branch(es) not merged: $unmerged_list
-  Merge them first, or mark them deferred with \`<!-- deferred: <reason> -->\`."
-  fi
+vfield() { printf '%s' "$verdict" | jq -r "$1" 2>/dev/null; }
 
-  deferred_count=0
-  [ -n "$deferred_branches" ] && deferred_count=$(printf '%s\n' "$deferred_branches" | wc -l | tr -d ' ')
-  merged_count=$(printf '%s\n' "$non_deferred_branches" | wc -l | tr -d ' ')
-  [ -z "$non_deferred_branches" ] && merged_count=0
+if [ "$(vfield '.deliverable')" != "true" ]; then
+  die "$(vfield '.refusal')"
+fi
 
+merged_count=$(vfield '.merged')
+deferred_count=$(vfield '.deferred')
+# Empty rather than `0`, so the suffix below stays absent where the old block
+# left it absent — `${x:+...}` fires on any non-empty value, and "0 deferred"
+# is a line no run has ever printed.
+[ "$deferred_count" = "0" ] && deferred_count=""
+if [ "$merged_count" = "0" ] && [ -z "$deferred_count" ]; then
+  echo "step: no branches found in plan — proceeding (nothing to verify)"
+else
   echo "step: verified $merged_count branch(es) merged${deferred_count:+, $deferred_count deferred}"
 fi
 
@@ -267,13 +226,18 @@ rel=$(cd "$repo_root" && real_plan_path "$plan_file") || rel=""
 # The filename, for symlink creation.
 plan_basename=$(basename "$rel")
 
-# Flip `**Phase:** Approved` → `Delivered` in the `## Status` section only.
-flip_phase() { # $1=file  → 0 if it changed the file, 1 if nothing to flip
-  local f="$1"
+# 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 —
+# see write_transition() below.
+flip_phase() { # $1=in $2=out  → 0 if it changed the file, 1 if nothing to flip
   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
@@ -282,17 +246,35 @@ flip_phase() { # $1=file  → 0 if it changed the file, 1 if nothing to flip
     }
     { print }
     END { exit (changed ? 0 : 1) }
-  ' "$f" > "$f.plot-tmp"
-  local rc=$?
-  if [ "$rc" = 0 ]; then mv "$f.plot-tmp" "$f"; else rm -f "$f.plot-tmp"; fi
-  return "$rc"
+  ' "$1" > "$2"
 }
 
 # Insert one `- **Delivered:** YYYY-MM-DD` line into the plan's `## Status` section.
 # Fills the placeholder first; falls back to appending after the last list item.
-append_delivered_line() { # $1=file $2=date
-  local f="$1" line
-  line="- **Delivered:** $2"
+#
+# IT STOPS AT AN HTML COMMENT, and that is the whole of the fix made 2026-09-01.
+# The plan template ends `## Status` with
+#
+#     <!-- Transition records — written by the workflow commands, not by hand:
+#     - **Started:** <date>, <who>, <branch>
+#     -->
+#
+# and those `- **Started:**` lines ARE list items. The scan tracked the last one
+# it saw, so on any plan whose `Started:` records had been filled in, the record
+# was appended INSIDE the comment — inert, and invisible to
+# `plot-plan-meta.sh`, which reported `delivered_raw: ""` for a plan that had
+# just been delivered. Measured on `a-browser-test-serves-its-own-state`: phase
+# flipped to Delivered, two `Delivered:` lines written into the comment (the
+# script is idempotent on the PHASE, so a second run wrote a second line), and
+# no readable record at all.
+#
+# A comment is where a plan keeps the shape of a record rather than a record, so
+# the insertion point is the last list item BEFORE one — never inside.
+#
+# READS ONE FILE AND WRITES ANOTHER, for the reason flip_phase() gives.
+append_delivered_line() { # $1=in $2=out $3=record
+  local line
+  line="- **Delivered:** $3"
   awk -v line="$line" '
     { lines[++n] = $0 }
     END {
@@ -304,8 +286,11 @@ append_delivered_line() { # $1=file $2=date
       insert = start
       for (i = start + 1; i <= n; i++) {
         if (lines[i] ~ /^##[ \t]/) break
+        # An HTML comment ends the writable region. Checked BEFORE the
+        # placeholder arms so a commented-out `- **Delivered:**` template line
+        # is never mistaken for the slot to fill.
+        if (lines[i] ~ /<!--/) break
         if (lines[i] ~ /^[ \t]*[-*][ \t]*\*\*Delivered:\*\*[ \t]*$/) { slot = i; break }
-        if (lines[i] ~ /^[ \t]*[-*][ \t]*\*\*Delivered:\*\*[ \t]*<!--/) { slot = i; break }
         if (lines[i] ~ /^[ \t]*[-*][ \t]/) insert = i
       }
 
@@ -315,8 +300,116 @@ append_delivered_line() { # $1=file $2=date
         if (!slot && i == insert) print line
       }
     }
-  ' "$f" > "$f.plot-tmp" || { rm -f "$f.plot-tmp"; return 1; }
-  mv "$f.plot-tmp" "$f"
+  ' "$1" > "$2"
+}
+
+# ---------------------------------------------------------------------------
+# THE TRANSITION — one value, decided in the domain, written whole or not at all
+# ---------------------------------------------------------------------------
+#
+# WHAT THIS CLOSES. The phase and the record were two independent steps until
+# 2026-09-02: `flip_phase` edited the file, and `append_delivered_line` then
+# edited it again. The second could fail — a plan with no `## Status` heading is
+# its documented refusal — and the first had already landed. That is not
+# theoretical: measured 2026-08-20, a plan carrying `Phase: Delivered` with no
+# `Delivered:` line was filtered out of `plot-fleet-scan.sh` ENTIRELY, which
+# reads its delivered window from `delivered_raw` — the record itself. The scan
+# reported zero plans for it. A phase without its record does not make a plan
+# half-delivered; it makes it invisible.
+#
+# SO THE TWO ARE ONE WRITE. The domain says so in a type: `transitions/plan.ts`
+# gives `Decision` a required `phase` AND a required `record`, so a decision
+# missing either does not compile. `plot-transition.mjs` carries that value out
+# to here, and this function is the half that could still have broken it —
+# both edits run against scratch copies, and the plan file is replaced only
+# once both have succeeded.
+#
+# THE DOMAIN DECIDES, THIS PERFORMS. The phase word and the record's text come
+# back from `plot-transition.mjs`; the awk that knows where a `## Status` line
+# lives stays here, because that is adaptation and it carries bug history worth
+# keeping (the HTML-comment fix above, 2026-09-01).
+#
+# IDEMPOTENCE IS UNCHANGED, and it is still the source that answers. The domain
+# reads the phase and the record THIS SCRIPT PARSED FROM THE FILE IT IS ABOUT TO
+# WRITE, and answers `already` when both are present — the same question the two
+# steps asked separately, asked once. No progress file appears here, because a
+# progress file is exactly what would disagree with the repository when somebody
+# intervened by hand between two runs.
+transition_mjs="$script_dir/board/plot-transition.mjs"
+
+# Ask the domain for the transition, and refuse in its words.
+#
+# Called with the file's OWN parse rather than the caller's: on the booking-
+# worktree flow those are different files, and the plan on the default branch is
+# the one that counts.
+decide_transition() { # $1=file  → prints "<Phase>\t<record>\t<write|already>"
+  local f="$1" m answer rc
+  [ -f "$transition_mjs" ] \
+    || { echo "plot-deliver: cannot find $transition_mjs — run 'pnpm build:board'." >&2; return 1; }
+  m=$(bash "$script_dir/plot-plan-meta.sh" "$f" 2>/dev/null) || m=""
+  [ -n "$m" ] || { echo "plot-deliver: cannot parse $f — refusing rather than guessing." >&2; return 1; }
+  answer=$(printf 'deliver\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t\t\t\n' \
+    "$slug" \
+    "$(printf '%s' "$m" | jq -r '.phase // ""')" \
+    "$(printf '%s' "$m" | jq -r '.review // ""')" \
+    "$(printf '%s' "$m" | jq -r '.approved_raw // ""')" \
+    "$(printf '%s' "$m" | jq -r '.delivered_raw // ""')" \
+    "$(printf '%s' "$m" | jq -r '.released_raw // ""')" \
+    "$today" \
+    | node "$transition_mjs" 2>&1)
+  rc=$?
+  # Exit 1 is the domain's refusal and its sentence, tab-separated after the
+  # rule that fired. Exit 2 is this script handing it something unreadable,
+  # which no operator can act on — so it reports as the bug it is.
+  if [ "$rc" != 0 ]; then
+    if [ "$rc" = 1 ]; then
+      echo "plot-deliver: $(printf '%s' "$answer" | cut -f2-)" >&2
+    else
+      echo "plot-deliver: $answer" >&2
+    fi
+    return 1
+  fi
+  printf '%s' "$answer"
+}
+
+# Apply the decided transition: the phase and the record, or neither.
+#
+# BOTH EDITS RUN AGAINST SCRATCH FILES and the plan is replaced by one `mv`.
+# An `## Status` section that cannot take the record leaves the file exactly as
+# it was found — INCLUDING ITS PHASE — so re-running is still the repair, and
+# the half-state that made a plan invisible cannot be reached from here.
+#
+# `$3` says whether the file already carries the record. A plan can carry one
+# while its phase lags — written by hand, or an earlier run cut between the two
+# writes — and appending a second is how one plan came to hold two `Delivered:`
+# lines (2026-09-01). The domain returns the written record unchanged in that
+# case, so the phase still flips and nothing is inserted.
+write_transition() { # $1=file $2=record $3=recorded(yes|no) → sets phase_report record_report
+  local f="$1" record="$2" recorded="$3" a="$1.plot-phase" b="$1.plot-record" flipped=0
+
+  if flip_phase "$f" "$a"; then flipped=1; else flipped=0; fi
+  # awk wrote `$a` either way; where nothing flipped it is a faithful copy, so
+  # the record still has a file to be inserted into.
+  [ -s "$a" ] || { rm -f "$a"; echo "plot-deliver: could not read $rel" >&2; return 1; }
+
+  if [ "$recorded" = "yes" ]; then
+    mv "$a" "$f" || { rm -f "$a"; return 1; }
+    record_report="already"
+  else
+    if ! append_delivered_line "$a" "$b" "$record"; then
+      rm -f "$a" "$b"
+      echo "plot-deliver: $rel has no '## Status' section — nowhere to record the delivery." >&2
+      echo "  Nothing was written: the phase is not flipped either, because a phase" >&2
+      echo "  with no record is invisible to the scan. Fix the section and re-run." >&2
+      return 1
+    fi
+    mv "$b" "$f" || { rm -f "$a" "$b"; return 1; }
+    rm -f "$a"
+    record_report="written"
+  fi
+
+  phase_report=$([ "$flipped" = 1 ] && echo flipped || echo already)
+  return 0
 }
 
 # Update the sprint item annotation for this plan.
@@ -387,21 +480,23 @@ apply_local_writes() { # $1=root  → sets phase_report record_report index_repo
   local root="$1" f="$1/$rel"
   [ -f "$f" ] || { echo "plot-deliver: $rel is not present in $root" >&2; return 1; }
 
-  # Step 3 — flip the phase. Already-done test: the file no longer says Approved.
-  if flip_phase "$f"; then phase_report="flipped"; else phase_report="already"; fi
-
-  # Step 4 — fill the Delivered: record. Already-done test: it is non-empty.
-  local rec
-  rec=$(bash "$script_dir/plot-plan-meta.sh" "$f" 2>/dev/null | jq -r '.delivered_raw // ""' 2>/dev/null)
-  if [ -n "$rec" ]; then
+  # Step 3 — THE TRANSITION: the phase and its record, together or not at all.
+  #
+  # ONE STEP WHERE THERE WERE TWO, which is the whole of this change. The domain
+  # decides what the two lines say and whether they are owed at all; this writes
+  # them as one replacement of the file. Already-done test: the domain answers
+  # `already` when the file it is about to write ALREADY carries both, which is
+  # the source asked directly — never a progress file.
+  local decided record action recorded
+  decided=$(decide_transition "$f") || return 1
+  record=$(printf '%s' "$decided" | cut -f2)
+  action=$(printf '%s' "$decided" | cut -f3)
+  recorded=$(printf '%s' "$decided" | cut -f4)
+  if [ "$action" = "already" ]; then
+    phase_report="already"
     record_report="already"
   else
-    if append_delivered_line "$f" "$today"; then
-      record_report="written"
-    else
-      echo "plot-deliver: $rel has no '## Status' section — nowhere to record the delivery" >&2
-      return 1
-    fi
+    write_transition "$f" "$record" "$recorded" || return 1
   fi
 
   # Step 5 — move the index symlink (best effort).