@plot-pm/board 0.10.0 → 0.12.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
@@ -120,6 +129,27 @@
 #                  `<!-- 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.
+#                  `<!-- 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
@@ -291,6 +321,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"
@@ -346,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 = ""
@@ -356,7 +414,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 +422,8 @@ 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 builds_of; delete builds_set
   delete started; n_started = 0
   fm_changelog = ""
   delete changelog; n_changelog = 0; changelog_seen = 0; cl_open = 0
@@ -374,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 = ""
   }
@@ -508,7 +574,17 @@ 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]) "\""
+      # 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
     }
     out = out "]}"
@@ -612,6 +688,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 +711,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 +743,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
@@ -685,18 +781,43 @@ in_fence { next }
 }
 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)
   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 +870,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 +921,97 @@ 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.
+  # 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]*/) {
+    _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 +1036,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 +1045,12 @@ 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
+    builds_of[n_branches] = builds_note
+    builds_set[n_branches] = has_builds
     ordered_b[n_branches] = b
   }
   line = $0
@@ -858,7 +1085,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 +1114,80 @@ 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.
+  # 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]*/) {
+    _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 +1204,13 @@ 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
+    builds_of[n_branches] = builds_note
+    builds_set[n_branches] = has_builds
     ordered_b[n_branches] = b
   }