@plot-pm/board 0.10.0 → 0.11.0

package/plot-plan-meta.sh

@@ -120,6 +120,14 @@
 #                  `<!-- deferred -->` (bare, no colon) sets the flag with no
 #                  reason; `waves[].branches[].deferred_reason` carries the
 #                  sentence after the colon, "" where none was written.
+#                  `<!-- waits: bug/other -->` names ONE branch this branch
+#                  waits on, reported as `waves[].branches[].waits_on`. The key
+#                  is ABSENT where no annotation was written — never "" — and
+#                  the value is a branch name in this repo, not a plan slug and
+#                  not a cross-repo reference. The parser reports what the file
+#                  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.
 #   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
@@ -291,6 +299,34 @@ function val_after_colon(s) {
 }
 # Template placeholders like "<!-- optional -->" mean "field absent".
 function strip_placeholder(s) { return (s ~ /^<!--/) ? "" : s }
+# Blank out backtick-delimited inline code, so a marker PRINTED as a literal is
+# not read as syntax. Markdown renders `<!--` between backticks as the four
+# characters; this parser used to read it as a comment-open, and because such a
+# line carries no closing marker it swallowed the rest of the file — one
+# backticked marker in a summary line cost a plan its phase, type and branches.
+#
+# Only the comment rules consult this. The line itself is untouched everywhere
+# else, because branch names live in backticks too and stripping them for real
+# would empty every `## Branches` entry.
+#
+# Runs of backticks are matched longest-first so a ``code`` span closes against
+# its own delimiter. An UNPAIRED backtick leaves its tail as-is: that is prose
+# with a stray tick, and prose is exactly where a real comment may open.
+# NOTE: the closing-run index is named `shut` because `close` is an awk builtin
+# and cannot be a parameter name — it fails as a syntax error on the function
+# signature, pointing nowhere near the cause.
+function mask_code(s,   out, n, tick, shut) {
+  out = ""
+  while ((n = index(s, "`")) > 0) {
+    out = out substr(s, 1, n - 1)
+    s = substr(s, n)
+    tick = ""
+    while (substr(s, 1, 1) == "`") { tick = tick "`"; s = substr(s, 2) }
+    if ((shut = index(s, tick)) == 0) return out tick s
+    s = substr(s, shut + length(tick))
+  }
+  return out s
+}
 # First known phase token wins; NONE if empty; UNKNOWN otherwise.
 function norm_phase(raw,   lower, toks, n, i, t) {
   if (raw == "") return "NONE"
@@ -356,7 +392,7 @@ function reset_state() {
   # the field, so a consumer cannot mistake "never interrogated" for "asked
   # nothing".
   block_rounds = ""
-  in_fm = 0; section = ""; in_comment = 0; in_challenge = 0; in_fence = 0; branches_seen = 0; waves_seen = 0
+  in_fm = 0; section = ""; in_comment = 0; in_challenge = 0; in_fence = 0; slices_seen = 0; slice_shape = ""
   delete branches; n_branches = 0
   delete prs; n_prs = 0
   delete malformed_prs; n_malformed_prs = 0
@@ -364,6 +400,7 @@ function reset_state() {
   delete issues; n_issues = 0
   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 started; n_started = 0
   fm_changelog = ""
   delete changelog; n_changelog = 0; changelog_seen = 0; cl_open = 0
@@ -508,7 +545,13 @@ function emit_record(   fmt, praw, palt_raw, traw, title, sprint, story, assigne
       if (wave_of[i] != w) continue
       out = out (first ? "" : ",") "{\"branch\":\"" jesc(ordered_b[i]) "\",\"deferred\":" deferred_of[i] \
             ",\"deferred_reason\":\"" jesc(deferred_why[i]) "\"" \
-            ",\"claimed\":\"" jesc(claimed_of[i]) "\"}"
+            ",\"claimed\":\"" jesc(claimed_of[i]) "\""
+      # ABSENT, NOT EMPTY, where no prerequisite was declared. The key appears
+      # only on a branch whose line carries a `waits:` annotation, so a consumer
+      # 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]) "\""
+      out = out "}"
       first = 0
     }
     out = out "]}"
@@ -612,6 +655,10 @@ in_fm {
   else if (lower ~ /^rounds:/ && fm_rounds == "") fm_rounds = val_after_colon($0)
   next
 }
+# A fence marker is a line whose first non-space run is ``` or ~~~ (an info
+# string like ```markdown may follow). The marker line itself is never content.
+/^[ \t]*(```|~~~)/ { in_fence = !in_fence; next }
+in_fence { next }
 # Interior of multi-line HTML comments is non-content (template guidance
 # blocks); single-line "<!-- ... -->" placeholders are unaffected.
 #
@@ -631,13 +678,25 @@ in_comment {
   if ($0 ~ /-->/) { in_comment = 0; in_challenge = 0 }
   next
 }
-/<!--/ && $0 !~ /-->/ {
-  in_comment = 1
-  # A truncated block never closes; it simply runs to EOF as a comment, and the
-  # round stays whatever was read before the truncation — absent if the "round"
-  # line was itself lost. Nothing else in the record is affected either way.
-  in_challenge = ($0 ~ /CHALLENGE-THE-PLAN-METADATA/) ? 1 : 0
-  next
+# A comment opens only where the marker is SYNTAX. Inside inline code it is a
+# literal being quoted, and the fence rules above have already consumed code
+# blocks — so what reaches here is prose, minus its backticked spans.
+#
+# The cheap test guards the expensive one: /<!--/ on the raw line rejects the
+# overwhelming majority, so mask_code runs once per line that actually carries a
+# marker rather than twice per line of every plan. The masked verdict is decided
+# INSIDE the rule so a line that turns out to be inline code simply falls
+# through to the ordinary content rules below, carrying no state with it.
+/<!--/ {
+  _masked = mask_code($0)
+  if (_masked ~ /<!--/ && _masked !~ /-->/) {
+    in_comment = 1
+    # A truncated block never closes; it simply runs to EOF as a comment, and
+    # the round stays whatever was read before the truncation — absent if the
+    # "round" line was itself lost. Nothing else in the record is affected.
+    in_challenge = ($0 ~ /CHALLENGE-THE-PLAN-METADATA/) ? 1 : 0
+    next
+  }
 }
 # A fenced code block is illustration, never contract — the same standing rule
 # comment interiors and repeated headings already follow. A plan that documents
@@ -651,30 +710,34 @@ in_comment {
 # example won its first-heading-wins guard and hid the real section). Toggling on
 # a fence fence-marker line closes both.
 #
-# A fence marker is a line whose first non-space run is ``` or ~~~ (an info
-# string like ```markdown may follow). The marker line itself is never content.
-/^[ \t]*(```|~~~)/ { in_fence = !in_fence; next }
-in_fence { next }
 # First H1 is the title fallback (front matter title: still wins in emit).
 /^#[ \t]/ && h1_title == "" { h1_title = trim(substr($0, 2)) }
 /^## / {
   if ($0 ~ /^## Status/) section = "status"
-  # First `## Branches` wins: a plan documenting the plan format quotes the
+  # THE HEADING WORD NO LONGER PICKS THE LAYOUT. `## Branches`, `## Waves` and
+  # `## Slices` open ONE section, and which shape it holds is decided by the
+  # first `### ` heading in it — see `slice_shape` below.
+  #
+  # THEY USED TO SELECT IT, AND THAT MADE THE RENAME UNSAFE. The two layouts are
+  # genuinely different: the old one carries the branch on a LIST ITEM
+  # (`- ` + backtick + `feature/x` + backtick + ` -> #72`), the new one carries it in the
+  # heading (`### Name (Branch: feature/x, PR: #577)`). With the word choosing
+  # the consumer, renaming a heading silently changed which grammar was applied.
+  # Measured 2026-09-04 on `2026-08-14-parallel-agent-fleet.md`: renaming its
+  # `## Branches` to `## Slices` took it from **6 branches to 0**, with no error
+  # anywhere — the file still parsed, and simply held nothing.
+  #
+  # Deciding by shape makes the heading a NAME again. All three spellings read
+  # either layout, so a plan can be renamed without being rewritten, and the 48
+  # files still saying `## Branches` are safe to migrate a word at a time.
+  #
+  # First one wins, as before: a plan documenting the plan format quotes the
   # section in prose, and those later headings are illustration, not contract.
-  else if ($0 ~ /^## Branches/) { section = branches_seen ? "" : "branches"; branches_seen = 1 }
-  # `## Waves` is the new spelling: the branch and PR live in the `### ` heading,
-  # the line below is prose. First one wins, for the same reason `## Branches`
-  # does. A plan carries one or the other — but the parser reads both while the
-  # migration moves 85 files, so a file moved one commit early never reads
-  # as silently empty.
-  # `## Slices` is the spelling the design spec uses, and `## Waves` is what 132
-  # plans already say. They are ONE section here, sharing waves_seen, because the
-  # shape is identical: the branch and PR ride the `### ` heading either way. A
-  # third arm would be a second implementation of a re-spelling, and the two
-  # would drift. No existing plan is rewritten to say Slices — a delivered plan
-  # describes what was built in the vocabulary of its day, and churning 132
-  # files git blame for a word buys nothing. New plans may use either.
-  else if ($0 ~ /^## Waves/ || $0 ~ /^## Slices/) { section = waves_seen ? "" : "waves"; waves_seen = 1 }
+  else if ($0 ~ /^## Branches/ || $0 ~ /^## Waves/ || $0 ~ /^## Slices/) {
+    section = slices_seen ? "" : "slices"
+    slices_seen = 1
+    slice_shape = ""
+  }
   else if ($0 ~ /^## Approval/) section = "approval"
   # First `## Changelog` wins, for the same reason `## Branches` does: a plan
   # about the plan format quotes the section in prose, and the later heading is
@@ -692,11 +755,35 @@ section == "status" {
   else if (lower ~ /^[ \t]*[-*]?[ \t]*\**issue[:*]/ && canon_issue == "") canon_issue = val_after_colon($0)
   else if (lower ~ /^[ \t]*[-*]?[ \t]*\**review[:*]/ && canon_review == "") canon_review = val_after_colon($0)
   else if (lower ~ /^[ \t]*[-*]?[ \t]*\**impl[:*]/ && canon_impl == "") canon_impl = val_after_colon($0)
-  else if (lower ~ /^[ \t]*[-*]?[ \t]*\**design[:*]/ && canon_design == "") canon_design = val_after_colon($0)
+  # EACH TAKES THE FIRST LINE THAT CARRIES A VALUE, NOT THE FIRST LINE.
+  #
+  # A plan may hold both a record and an unfilled placeholder for the same
+  # field, on either side of each other. Seven plans here write the placeholder
+  # as a per-line comment —
+  #
+  #     - **Delivered:** <!-- YYYY-MM-DD -->
+  #
+  # — beside a real `- **Delivered:** 2026-09-01`. `strip_placeholder` used to
+  # run in `emit_record`, AFTER first-wins had already chosen: the placeholder
+  # claimed the slot, was emptied a moment later, and the record it beat was
+  # gone. Whether a plan parsed correctly then depended on which line came
+  # first, and `append_delivered_line` decides that by where a `<!--` happens
+  # to stop its scan.
+  #
+  # A DELIVERED PLAN THAT READS `delivered_raw: ""` IS INVISIBLE TO THE SCAN,
+  # which reads its rolling window from that field — the same failure the
+  # comment-block fix addressed, reached by a different road. Measured
+  # 2026-09-01 on `a-machine-is-an-instance`: parsed correctly, but only
+  # because its record sat two lines above its placeholder.
+  #
+  # `started` never had this bug because it is a list and had to filter at
+  # capture to avoid storing empties. These four are scalars, and now do the
+  # same: a placeholder no longer counts as a value, so ORDER STOPS MATTERING.
+  else if (lower ~ /^[ \t]*[-*]?[ \t]*\**design[:*]/ && canon_design == "") canon_design = strip_placeholder(val_after_colon($0))
   else if (lower ~ /^[ \t]*[-*]?[ \t]*\**rounds[:*]/ && canon_rounds == "") canon_rounds = val_after_colon($0)
-  else if (lower ~ /^[ \t]*[-*]?[ \t]*\**approved[:*]/ && canon_approved == "") canon_approved = val_after_colon($0)
-  else if (lower ~ /^[ \t]*[-*]?[ \t]*\**released[:*]/ && canon_released == "") canon_released = val_after_colon($0)
-  else if (lower ~ /^[ \t]*[-*]?[ \t]*\**delivered[:*]/ && canon_delivered == "") canon_delivered = val_after_colon($0)
+  else if (lower ~ /^[ \t]*[-*]?[ \t]*\**approved[:*]/ && canon_approved == "") canon_approved = strip_placeholder(val_after_colon($0))
+  else if (lower ~ /^[ \t]*[-*]?[ \t]*\**released[:*]/ && canon_released == "") canon_released = strip_placeholder(val_after_colon($0))
+  else if (lower ~ /^[ \t]*[-*]?[ \t]*\**delivered[:*]/ && canon_delivered == "") canon_delivered = strip_placeholder(val_after_colon($0))
   else if (lower ~ /^[ \t]*[-*]?[ \t]*\**started[:*]/) {
     _s = strip_placeholder(val_after_colon($0))
     if (_s != "") started[++n_started] = _s
@@ -749,7 +836,23 @@ section == "changelog" {
   cl_open = 0
   next
 }
-section == "branches" {
+# WHICH SHAPE THIS SECTION HOLDS, decided once from its first `### ` heading and
+# then fixed for the rest of the section.
+#
+# `(Branch:` IS THE MARKER, and it is the only reliable one. A heading carrying
+# it is the new shape by construction — that parenthetical is where the new
+# layout puts the branch. A heading without it is the old shape, whose headings
+# are bare names (`### Tracer`) and whose branches ride list items below.
+#
+# A SECTION WITH NO `### ` AT ALL is the old shape, and must be: a plan written
+# before subheadings existed is one unnamed wave of list items, which is exactly
+# what the old consumer produces. `slice_shape` therefore stays `""` until a
+# heading is seen, and `""` routes to the old consumer.
+section == "slices" && $0 ~ /^###[ \t]/ && slice_shape == "" {
+  slice_shape = (index($0, "(Branch:") > 0) ? "heading" : "list"
+}
+
+section == "slices" && slice_shape != "heading" {
   # `### <name>` opens a wave. Branches before any subheading belong to an
   # unnamed wave, so a pre-wave plan parses as exactly one wave.
   if ($0 ~ /^###[ \t]/) {
@@ -784,13 +887,64 @@ section == "branches" {
   # documented contract is that an annotation binds to the line carrying the
   # branch name. A deferral whose text is wrapped onto a continuation line is
   # not seen, exactly as `deferred` itself was not.
+  # `moved:` IS THE SAME ANSWER AS `deferred:`, and CLAUDE.md has said so since
+  # the reconcile scan was written: *"`deferred:`/`moved:` in the plan means
+  # reapable"*. `plot-reconcile-scan.sh:504` matches both in one arm; this
+  # parser matched only the first, so a slice given up with the other word read
+  # as still outstanding — to the board, the delivery gate and the fleet alike.
+  # Measured 2026-09-04 on `feature/the-reaper-sweeps-every-kind`: annotated
+  # `moved:` into the slice that superseded it, still `deferred:false` here.
+  #
+  # The two words differ in what they tell a READER — given up, versus taken
+  # somewhere else — and the reason is kept verbatim, so the distinction is not
+  # lost by being read alike.
   defer_note = ""
-  if (index($0, "deferred:") > 0) {
+  if (index($0, "deferred:") > 0 || index($0, "moved:") > 0) {
     _d = $0
-    sub(/^.*<!--[ \t]*deferred:[ \t]*/, "", _d)
+    sub(/^.*<!--[ \t]*(deferred|moved):[ \t]*/, "", _d)
     sub(/[ \t]*-->.*$/, "", _d)
     defer_note = trim(_d)
   }
+  # THE PREREQUISITE THIS BRANCH NAMES: `<!-- waits: bug/other-branch -->`.
+  #
+  # ONE branch, never a list. A slice needing two prerequisites has not been cut
+  # finely enough, and a list invites a dependency graph nobody wants to debug.
+  # The greedy `.*` takes the LAST annotation when a line carries two, which is
+  # the same rule `deferred:` and `claimed:` already follow.
+  #
+  # The value is a BRANCH NAME, so it stops at the first whitespace rather than
+  # running to the closing marker the way a deferral reason does: a reason is a
+  # sentence, a branch name is a token, and trailing prose inside the comment
+  # would silently become part of a name that then matches nothing.
+  #
+  # `deferred:` is a judgement and `waits:` is a checkable fact, so the two are
+  # separate annotations and both may sit on one line. Read here, beside the
+  # other two, for the same reason: `match()` in the branch loop below clobbers
+  # RSTART/RLENGTH, so anything read from the whole line must be read first.
+  #
+  # `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.
+  waits_note = ""
+  has_waits = 0
+  if ($0 ~ /<!--[ \t]*waits:[ \t]*/) {
+    _w = $0
+    sub(/^.*<!--[ \t]*waits:[ \t]*/, "", _w)
+    sub(/[ \t].*$/, "", _w)
+    sub(/-->.*$/, "", _w)
+    waits_note = trim(_w)
+    # THE VALUE MUST LOOK LIKE A BRANCH, and that check is what keeps a
+    # SYNTAX EXAMPLE from becoming a declaration. A plan that documents the
+    # annotation writes the literal marker in prose, and no comment-aware
+    # reading can tell that apart from the real thing on the same line — the
+    # branch prefixes can. `<branch>` is not a branch name; `bug/x` is.
+    #
+    # Reusing the branch prefixes rather than a new pattern: the prerequisite
+    # IS a branch in this repo, so the two must never disagree about what a
+    # branch name looks like.
+    if (waits_note ~ "^(" PREFIXES ")/[^ \t]+$") has_waits = 1
+    else waits_note = ""
+  }
   # ONE LIST ITEM, AT MOST ONE CLAIM — an `if`, not the `while` this was.
   #
   # The old loop walked the line taking every backticked name on it, which is
@@ -815,7 +969,7 @@ section == "branches" {
     # plan can make about a branch, dropped for want of a colon. A reader
     # writing the shorter form has said the branch will not be built; the
     # parser now hears it.
-    deferred_of[n_branches] = ($0 ~ /<!--[ \t]*deferred[ \t]*(:|-->)/) ? "true" : "false"
+    deferred_of[n_branches] = ($0 ~ /<!--[ \t]*(deferred|moved)[ \t]*(:|-->)/) ? "true" : "false"
     # The reason travels with the flag. Empty on every non-deferred branch, and
     # empty is also the honest answer for the bare form: the branch IS deferred
     # and no reason was recorded, which is a different statement from a reason
@@ -824,6 +978,10 @@ section == "branches" {
     # Claim reflection, written by the worker after its ref push succeeds. This
     # is a reflection, not the claim: git refs remain authoritative.
     claimed_of[n_branches] = claim_note
+    # The prerequisite travels with the branch. Presence is tracked separately
+    # so a branch that declares none emits no key.
+    waits_of[n_branches] = waits_note
+    waits_set[n_branches] = has_waits
     ordered_b[n_branches] = b
   }
   line = $0
@@ -858,7 +1016,7 @@ section == "branches" {
 # The emitted arrays (branches, prs, waves) must be byte-identical to what the
 # old shape produces for the same plan. So this shares every accumulation
 # variable with the branches handler above; only the EXTRACTION differs.
-section == "waves" {
+section == "slices" && slice_shape == "heading" {
   # Only the `### ` heading carries meta. Body lines are prose — never scanned
   # for a branch or a PR, which is the whole point of the new shape.
   if ($0 !~ /^###[ \t]/) next
@@ -887,13 +1045,47 @@ section == "waves" {
     sub(/[ \t]*-->.*$/, "", _c)
     claim_note = trim(_c)
   }
+  # `moved:` IS THE SAME ANSWER AS `deferred:`, and CLAUDE.md has said so since
+  # the reconcile scan was written: *"`deferred:`/`moved:` in the plan means
+  # reapable"*. `plot-reconcile-scan.sh:504` matches both in one arm; this
+  # parser matched only the first, so a slice given up with the other word read
+  # as still outstanding — to the board, the delivery gate and the fleet alike.
+  # Measured 2026-09-04 on `feature/the-reaper-sweeps-every-kind`: annotated
+  # `moved:` into the slice that superseded it, still `deferred:false` here.
+  #
+  # The two words differ in what they tell a READER — given up, versus taken
+  # somewhere else — and the reason is kept verbatim, so the distinction is not
+  # lost by being read alike.
   defer_note = ""
-  if (index($0, "deferred:") > 0) {
+  if (index($0, "deferred:") > 0 || index($0, "moved:") > 0) {
     _d = $0
-    sub(/^.*<!--[ \t]*deferred:[ \t]*/, "", _d)
+    sub(/^.*<!--[ \t]*(deferred|moved):[ \t]*/, "", _d)
     sub(/[ \t]*-->.*$/, "", _d)
     defer_note = trim(_d)
   }
+  # 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.
+  waits_note = ""
+  has_waits = 0
+  if ($0 ~ /<!--[ \t]*waits:[ \t]*/) {
+    _w = $0
+    sub(/^.*<!--[ \t]*waits:[ \t]*/, "", _w)
+    sub(/[ \t].*$/, "", _w)
+    sub(/-->.*$/, "", _w)
+    waits_note = trim(_w)
+    # THE VALUE MUST LOOK LIKE A BRANCH, and that check is what keeps a
+    # SYNTAX EXAMPLE from becoming a declaration. A plan that documents the
+    # annotation writes the literal marker in prose, and no comment-aware
+    # reading can tell that apart from the real thing on the same line — the
+    # branch prefixes can. `<branch>` is not a branch name; `bug/x` is.
+    #
+    # Reusing the branch prefixes rather than a new pattern: the prerequisite
+    # IS a branch in this repo, so the two must never disagree about what a
+    # branch name looks like.
+    if (waits_note ~ "^(" PREFIXES ")/[^ \t]+$") has_waits = 1
+    else waits_note = ""
+  }
 
   # The branch is the `Branch:` value, matched against the known prefixes exactly
   # as the old shape matched the backticked name. Written unquoted in the heading
@@ -910,9 +1102,11 @@ section == "waves" {
     wave_seq[n_branches] = ++wave_count[n_waves]
     # Bare `<!-- deferred -->` sets the flag with no reason, same as the old
     # shape; `deferred:` carries the reason.
-    deferred_of[n_branches] = ($0 ~ /<!--[ \t]*deferred[ \t]*(:|-->)/) ? "true" : "false"
+    deferred_of[n_branches] = ($0 ~ /<!--[ \t]*(deferred|moved)[ \t]*(:|-->)/) ? "true" : "false"
     deferred_why[n_branches] = defer_note
     claimed_of[n_branches] = claim_note
+    waits_of[n_branches] = waits_note
+    waits_set[n_branches] = has_waits
     ordered_b[n_branches] = b
   }