@plot-pm/board 0.19.1 → 0.21.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/plot-plan-meta.sh CHANGED
@@ -166,6 +166,16 @@
166
166
  # charter name is a bare word with no structure to check, so a
167
167
  # template documents the marker inside an outer comment block,
168
168
  # where this pattern cannot see it.
169
+ # `→ commit abc1234` / `→ commit abc1234, def5678` /
170
+ # `→ owner/repo@abc1234` name the COMMITS that completed the
171
+ # slice, reported as `waves[].branches[].commits` in line order.
172
+ # The commit spelling of `→ #N` / `→ owner/repo#N`, for a slice
173
+ # pushed straight to the default branch with no PR. A commit is
174
+ # 7 or more lowercase hex digits; a cross-repository one keeps
175
+ # its `owner/repo@` prefix because a consumer must tell it from
176
+ # one of this repository. ABSENT where none is named, never [];
177
+ # both slice dialects read it from the branch-carrying line.
178
+ # It adds nothing to `prs`: a commit is not a PR.
169
179
  # prs PR numbers, sorted and unique, read from EITHER spelling:
170
180
  # `→ #NNN` / `→ owner/repo#NNN` links in the `## Branches`
171
181
  # section, OR `PR: #NNN` in a `## Waves` `### ` heading. The
@@ -244,11 +254,17 @@
244
254
  # Empty until /plot-release records it; the tag stays the git
245
255
  # truth and this merely reflects it.
246
256
  # design_raw the design transition record as written (`## Status`
247
- # `Design:` or front matter `design:` — who/when, and what the
248
- # design work is); "" if absent. Reported for any plan that
257
+ # `Design:` or front matter `design:` — who/when/channel, e.g.
258
+ # "2026-10-12, alice, cli"); "" if absent. Reported for any plan that
249
259
  # carries the line, whatever its phase: a plan that WENT
250
260
  # THROUGH design keeps the record after moving on, exactly as
251
261
  # `approved_raw` outlives the Approved phase.
262
+ # spike_approved_raw the `Spike approved:` record as written (`## Status`);
263
+ # "" if absent. Read by the spike rules, never decided here.
264
+ # tracer true when `## Status` says `Tracer: yes`; the key is ABSENT
265
+ # otherwise, because no line is no reading
266
+ # waves[].branches[].spike true when the branch line carries a bare
267
+ # `<!-- spike -->`; ABSENT otherwise
252
268
  # approved_raw the approval transition record as written (`## Status`
253
269
  # `Approved:` or front matter `approved:` — who/when/channel,
254
270
  # e.g. "2026-07-30, alice, in-session"); "" if absent
@@ -259,6 +275,8 @@
259
275
  # record left empty (a bookkeeping fault plot-reconcile-scan
260
276
  # reports), and a consumer that needs a DATE must read this
261
277
  # rather than infer one from the phase.
278
+ # verified_raw the `Verified:` record of `## Status`, outside fences; "" if
279
+ # absent or a placeholder. The board passes it to verificationOf.
262
280
  # started_raw implementation-start records, one raw string per
263
281
  # `Started:` line in `## Status` (repeatable; front matter
264
282
  # `started:` contributes one entry); [] if absent.
@@ -311,7 +329,7 @@ if [ ${#files[@]} -eq 0 ] && [ ${#missing[@]} -eq 0 ]; then
311
329
  fi
312
330
 
313
331
  for f in ${missing[@]+"${missing[@]}"}; do
314
- printf '{"file":"%s","format":"none","error":"file not found","phase_raw":"","phase":"NONE","phase_alt_raw":"","phase_alt":"NONE","type":"","title":"","sprint":"","story":"","assignee":"","branches":[],"prs":[],"deferred_prs":[],"issues":[],"malformed_prs":[],"changelog":[],"long_wave_names":[],"unread_branch_headings":[],"unread_waits":[],"review_raw":"","review":"NONE","impl_raw":"","impl":"NONE","design_raw":"","approved_raw":"","released_raw":"","delivered_raw":"","started_raw":[]}\n' \
332
+ printf '{"file":"%s","format":"none","error":"file not found","phase_raw":"","phase":"NONE","phase_alt_raw":"","phase_alt":"NONE","type":"","title":"","sprint":"","story":"","assignee":"","branches":[],"prs":[],"deferred_prs":[],"issues":[],"malformed_prs":[],"changelog":[],"long_wave_names":[],"unread_branch_headings":[],"unread_waits":[],"review_raw":"","review":"NONE","impl_raw":"","impl":"NONE","design_raw":"","spike_approved_raw":"","approved_raw":"","released_raw":"","delivered_raw":"","verified_raw":"","started_raw":[]}\n' \
315
333
  "$(printf '%s' "$f" | sed 's/\\/\\\\/g; s/"/\\"/g')"
316
334
  done
317
335
 
@@ -486,11 +504,11 @@ function reset_state() {
486
504
  fm_title = ""; fm_sprint = ""; fm_story = ""; fm_assignee = ""
487
505
  fm_review = ""; fm_impl = ""; fm_approved = ""; fm_started = ""; fm_released = ""
488
506
  fm_delivered = ""; fm_design = ""
489
- fm_rounds = ""
490
- canon_state = ""; canon_phase = ""; canon_type = ""
507
+ canon_spike_approved = ""; canon_tracer = ""
508
+ fm_rounds = ""; canon_state = ""; canon_phase = ""; canon_type = ""
491
509
  canon_sprint = ""; canon_story = ""; canon_assignee = ""; status_assignee = ""
492
510
  canon_review = ""; canon_impl = ""; canon_approved = ""; canon_released = ""
493
- canon_delivered = ""; canon_design = ""
511
+ canon_delivered = ""; canon_design = ""; canon_verified = ""
494
512
  canon_rounds = ""
495
513
  h1_title = ""
496
514
  # "" means the plan carries no readable round — NOT zero. Emitted by omitting
@@ -504,13 +522,10 @@ function reset_state() {
504
522
  fm_issue = ""; canon_issue = ""
505
523
  delete issues; n_issues = 0
506
524
  delete wave_names; delete wave_of; delete wave_seq; delete wave_count
507
- delete deferred_of; delete deferred_why; delete claimed_of; delete ordered_b; n_waves = 0
508
- delete branch_heading
509
- delete waits_of; delete waits_set; delete waits_n
525
+ delete deferred_of; delete deferred_why; delete claimed_of; delete ordered_b; delete spike_of; n_waves = 0
526
+ delete branch_heading; delete waits_of; delete waits_set; delete waits_n
510
527
  delete unread_waits_branch; delete unread_waits_value; n_unread_waits = 0
511
- delete builds_of; delete builds_set
512
- delete agent_of; delete agent_set
513
- delete started; n_started = 0
528
+ delete builds_of; delete agent_of; delete commits_of; delete started; n_started = 0
514
529
  fm_changelog = ""
515
530
  delete changelog; n_changelog = 0; changelog_seen = 0; cl_open = 0
516
531
  }
@@ -680,6 +695,8 @@ function emit_record( fmt, praw, palt_raw, traw, title, sprint, story, assigne
680
695
  out = out (first ? "" : ",") "{\"branch\":\"" jesc(ordered_b[i]) "\",\"deferred\":" deferred_of[i] \
681
696
  ",\"deferred_reason\":\"" jesc(deferred_why[i]) "\"" \
682
697
  ",\"claimed\":\"" jesc(claimed_of[i]) "\""
698
+ # ABSENT, NOT false, where the branch line carries no `<!-- spike -->`.
699
+ if (spike_of[i] == 1) out = out ",\"spike\":true"
683
700
  # ABSENT, NOT EMPTY ARRAY, where no prerequisite was declared. The key
684
701
  # appears only on a branch whose line carries a `waits:` annotation, so a
685
702
  # consumer reading `waits_on` gets a list of one or more names or no key
@@ -695,14 +712,18 @@ function emit_record( fmt, praw, palt_raw, traw, title, sprint, story, assigne
695
712
  # ABSENT, NOT EMPTY, for the same reason `waits_on` is: a slice that
696
713
  # names no deliverable emits no key, so a consumer reads a name or
697
714
  # nothing. An empty string would read as a deliverable called "".
698
- if (builds_set[i] == 1) out = out ",\"builds\":\"" jesc(builds_of[i]) "\""
715
+ if (builds_of[i] != "") out = out ",\"builds\":\"" jesc(builds_of[i]) "\""
699
716
  # ABSENT, NOT EMPTY, the rule the three annotations above already keep.
700
717
  # Dispatch reads the PRESENCE of this key to decide whether the plan names
701
718
  # a kind at all, so an `"agent":""` would read as a charter called "" and
702
719
  # send it looking for `.plot/charters/.json`.
703
720
  # NOTE: no apostrophe may appear in this awk region — the whole program is
704
721
  # one single-quoted shell string, and one closes it mid-comment.
705
- if (agent_set[i] == 1) out = out ",\"agent\":\"" jesc(agent_of[i]) "\""
722
+ if (agent_of[i] != "") out = out ",\"agent\":\"" jesc(agent_of[i]) "\""
723
+ # ABSENT, NOT EMPTY, as the annotations above: the commits the slice line
724
+ # names as its completion, `abc1234` or `owner/repo@abc1234`, in line order.
725
+ # Hex and owner/repo characters need no escaping.
726
+ if (commits_of[i] != "") { cm = commits_of[i]; gsub(/,/, "\",\"", cm); out = out ",\"commits\":[\"" cm "\"]" }
706
727
  out = out "}"
707
728
  first = 0
708
729
  }
@@ -758,9 +779,12 @@ function emit_record( fmt, praw, palt_raw, traw, title, sprint, story, assigne
758
779
  out = out ",\"review_raw\":\"" jesc(review) "\",\"review\":\"" norm_review(review) "\""
759
780
  out = out ",\"impl_raw\":\"" jesc(impl) "\",\"impl\":\"" norm_impl(impl) "\""
760
781
  out = out ",\"design_raw\":\"" jesc(design) "\""
782
+ out = out ",\"spike_approved_raw\":\"" jesc(canon_spike_approved) "\""
783
+ # ABSENT unless `## Status` says `Tracer: yes`: no line is no reading.
784
+ if (tolower(canon_tracer) ~ /^(yes|true)/) out = out ",\"tracer\":true"
761
785
  out = out ",\"approved_raw\":\"" jesc(approved) "\""
762
786
  out = out ",\"released_raw\":\"" jesc(released) "\""
763
- out = out ",\"delivered_raw\":\"" jesc(delivered) "\""
787
+ out = out ",\"delivered_raw\":\"" jesc(delivered) "\",\"verified_raw\":\"" jesc(canon_verified) "\""
764
788
  out = out ",\"started_raw\":["
765
789
  for (i = 1; i <= n_started; i++) out = out (i > 1 ? "," : "") "\"" jesc(started[i]) "\""
766
790
  out = out "]"
@@ -804,6 +828,174 @@ function store_waits(n, b, k) {
804
828
  }
805
829
  delete pending_unread_value; pending_unread_n = 0
806
830
  }
831
+ # Reads every annotation that binds to the line carrying a branch name, into
832
+ # claim_note, defer_note, line_waits[], builds_note and agent_note. Called by BOTH
833
+ # slice dialects before their branch match, which clobbers RSTART/RLENGTH.
834
+ function read_notes() {
835
+ # Claim reflection, written by the worker after its ref push succeeds. This is
836
+ # a reflection, not the claim: git refs remain authoritative. Computed before
837
+ # the branch loop below — match() clobbers RSTART/RLENGTH, which that loop
838
+ # needs to advance.
839
+ claim_note = (index($0, "claimed:") > 0) ? marker_value($0, "claimed") : ""
840
+ # THE REASON FOR THE DEFERRAL, and not merely the fact of one.
841
+ #
842
+ # `<!-- deferred: verified already implemented 2026-08-17 — startRepair() at
843
+ # fleet.ts:806 -->` was tested for presence and the sentence after the colon
844
+ # was dropped on the floor. So the board could say `deferred` beside `no
845
+ # commits` and never say that the first is the REASON for the second — a
846
+ # reader with no access to the plan file saw a branch nobody started and no
847
+ # statement that nobody should.
848
+ #
849
+ # Extracted the same way and in the same place as the claim note, for the same
850
+ # reason: `match()` in the branch loop below clobbers RSTART/RLENGTH, so
851
+ # anything read from the whole line must be read before it runs.
852
+ #
853
+ # Newlines are already impossible here — awk hands this rule one line, and the
854
+ # documented contract is that an annotation binds to the line carrying the
855
+ # branch name. A deferral whose text is wrapped onto a continuation line is
856
+ # not seen, exactly as `deferred` itself was not.
857
+ # `moved:` IS THE SAME ANSWER AS `deferred:`, and CLAUDE.md has said so since
858
+ # the reconcile scan was written: *"`deferred:`/`moved:` in the plan means
859
+ # reapable"*. `plot-reconcile-scan.sh:504` matches both in one arm; this
860
+ # parser matched only the first, so a slice given up with the other word read
861
+ # as still outstanding — to the board, the delivery gate and the fleet alike.
862
+ # Measured 2026-09-04 on `feature/the-reaper-sweeps-every-kind`: annotated
863
+ # `moved:` into the slice that superseded it, still `deferred:false` here.
864
+ #
865
+ # The two words differ in what they tell a READER — given up, versus taken
866
+ # somewhere else — and the reason is kept verbatim, so the distinction is not
867
+ # lost by being read alike.
868
+ defer_note = (index($0, "deferred:") > 0 || index($0, "moved:") > 0) ? marker_value($0, "deferred|moved") : ""
869
+ # THE PREREQUISITES THIS BRANCH NAMES: `<!-- waits: bug/other-branch -->`.
870
+ #
871
+ # A LIST, not one name. Several `<!-- waits: … -->` comments on a line, or one
872
+ # `<!-- waits: x, y -->`, give the same list in document order, duplicates
873
+ # removed — see parse_waits(). The old greedy `sub()` took only the LAST
874
+ # annotation when a line carried two, which silently dropped every other
875
+ # prerequisite a slice had cleared for merge eligibility by itself (#1153).
876
+ #
877
+ # Each value is a BRANCH NAME, so it stops at the first whitespace or comma
878
+ # rather than running to the closing marker the way a deferral reason does: a
879
+ # reason is a sentence, a branch name is a token, and trailing prose inside
880
+ # the comment would silently become part of a name that then matches nothing.
881
+ #
882
+ # `deferred:` is a judgement and `waits:` is a checkable fact, so the two are
883
+ # separate annotations and both may sit on one line. Read here, beside the
884
+ # other two, for the same reason: `match()` in the branch loop below clobbers
885
+ # RSTART/RLENGTH, so anything read from the whole line must be read first.
886
+ #
887
+ # Presence is separate from the value, because ABSENT and
888
+ # EMPTY are different answers — a branch declaring no prerequisite emits no
889
+ # `waits_on` key at all, never `[]`.
890
+ #
891
+ # A value that does not look like a branch is NOT dropped — parse_waits()
892
+ # queues it in pending_unread_value[], and once the branch this line claims is
893
+ # known (below), it is copied into unread_waits_branch[]/unread_waits_value[].
894
+ # A line with no branch claim never drains the queue, so a `waits:` syntax
895
+ # example in prose — not on a branch line — stays silent, as today.
896
+ delete line_waits
897
+ parse_waits($0, line_waits)
898
+ # WHAT THIS SLICE BUILDS: `<!-- builds: normalizeVersion, a shared helper -->`.
899
+ #
900
+ # AN ANNOTATION, NOT A FIELD LINE, and that is what makes it work in BOTH
901
+ # slice dialects with no dialect-specific code. Annotations bind to the line
902
+ # carrying the branch name — the list item in one spelling, the `### `
903
+ # heading in the other — and both dialects already read `deferred:`,
904
+ # `claimed:` and `waits:` with the identical block. A `Builds:` field line
905
+ # would have had two spellings to parse, and the template writes the LIST
906
+ # dialect, so the heading-only version would be absent from every plan
907
+ # created from it.
908
+ #
909
+ # IT BELONGS TO THE SLICE, NEVER TO THE PLAN. A plan builds several things
910
+ # and each slice builds one; a plan-level list is searched as a whole and
911
+ # reported against the wrong slice.
912
+ #
913
+ # The value runs to the closing marker, the way `deferred:` does and unlike
914
+ # `waits:`. A prerequisite is a branch NAME and stops at whitespace; a
915
+ # deliverable is a name plus enough words to search for — `normalizeVersion,
916
+ # a shared helper` — and cutting it at the first space would leave the half
917
+ # that identifies it.
918
+ #
919
+ # Presence is the value being non-empty, exactly as
920
+ # `waits:` does: a slice declaring nothing emits no key, so a consumer reads
921
+ # a deliverable or nothing and never a blank string that looks like one.
922
+ builds_note = ($0 ~ /<!--[ \t]*builds:[ \t]*/) ? marker_value($0, "builds") : ""
923
+ # WHICH KIND OF AGENT THIS SLICE NEEDS: `<!-- agent: reviewer -->`.
924
+ #
925
+ # `--agent <name>` was the only selector and only an operator could type it.
926
+ # `plot-registryd` hands a queued slice to a free agent with no `--agent`
927
+ # anywhere in the path, so an unattended fleet ran every slice as the same
928
+ # undifferentiated worker. The declaration has to live in the PLAN to reach a
929
+ # dispatch nobody is watching.
930
+ #
931
+ # PER-BRANCH, NEVER A `## Status` FIELD. Every Status field is plan-level, so
932
+ # one there could declare a single kind for a plan with several slices — and a
933
+ # reviewer slice beside an implementer slice is the population this is for.
934
+ #
935
+ # The value runs to the closing marker, the way `builds:` does and unlike
936
+ # `waits:`. A charter name is a bare word today, so both rules agree; this one
937
+ # is chosen because it does not silently truncate if a name grows a space.
938
+ #
939
+ # IT CANNOT VALIDATE ITS VALUE, and that is the difference from `waits:` above.
940
+ # A prerequisite has branch-prefix structure, which is what keeps a SYNTAX
941
+ # EXAMPLE in prose from reading as a declaration; a charter name is a bare word
942
+ # with no structure to check. What protects the templates instead is NESTING:
943
+ # their documentation sits inside an outer `<!-- ... -->` block, so the inner
944
+ # `agent:` carries no `<!--` of its own and this pattern never matches it —
945
+ # the same accident of shape that already keeps `builds:` out of the parse of
946
+ # a template. Documenting it as a bare `<!-- agent: reviewer -->` line would
947
+ # hand a kind to every plan created from that template. A test pins it.
948
+ #
949
+ # Presence is the value being non-empty, as all three
950
+ # annotations before it do: a slice naming no kind emits no key, so dispatch
951
+ # reads a name or nothing and never a blank string that looks like one.
952
+ agent_note = ($0 ~ /<!--[ \t]*agent:[ \t]*/) ? marker_value($0, "agent") : ""
953
+ }
954
+ # The commits a slice line names as its completion: `→ commit abc1234`,
955
+ # `→ commit abc1234, def5678` and `→ owner/repo@abc1234`, the commit spellings of
956
+ # `→ #N` and `→ owner/repo#N`. Returns them comma-joined, a cross-repo one keeping
957
+ # its `owner/repo@` prefix because a reader must tell it apart. A commit is 7 or
958
+ # more lowercase hex digits, so prose after the arrow is never read as one.
959
+ function commit_list(s, out, m, h) {
960
+ h = "[0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]+"
961
+ while (match(s, "→ (commit " h "(, ?" h ")*|[A-Za-z0-9._-]+/[A-Za-z0-9._-]+@" h ")")) {
962
+ m = substr(s, RSTART, RLENGTH); s = substr(s, RSTART + RLENGTH)
963
+ sub(/^→ (commit )?/, "", m); gsub(/, ?/, ",", m)
964
+ out = out (out == "" ? "" : ",") m
965
+ }
966
+ return out
967
+ }
968
+ # Stores the annotations read_notes() found, and the commits the line names,
969
+ # against branch n (named b), at the moment either dialect claims it.
970
+ function keep_branch(n, b) {
971
+ # THE FLAG accepts the bare form as well as the annotated one.
972
+ #
973
+ # It matched `deferred:` only, so `<!-- deferred -->` — the annotation with
974
+ # nothing after it — read as NOT deferred at all: the strongest statement a
975
+ # plan can make about a branch, dropped for want of a colon. A reader
976
+ # writing the shorter form has said the branch will not be built; the
977
+ # parser now hears it.
978
+ deferred_of[n] = ($0 ~ /<!--[ \t]*(deferred|moved)[ \t]*(:|-->)/) ? "true" : "false"
979
+ # The reason travels with the flag. Empty on every non-deferred branch, and
980
+ # empty is also the honest answer for the bare form: the branch IS deferred
981
+ # and no reason was recorded, which is a different statement from a reason
982
+ # of "".
983
+ deferred_why[n] = defer_note
984
+ spike_of[n] = ($0 ~ /<!--[ \t]*spike[ \t]*-->/) ? 1 : 0
985
+ # Claim reflection, written by the worker after its ref push succeeds. This
986
+ # is a reflection, not the claim: git refs remain authoritative.
987
+ claimed_of[n] = claim_note
988
+ # The prerequisites travel with the branch, flattened as waits_of[n,1..k]
989
+ # since this awk has no nested arrays. Presence is tracked separately so a
990
+ # branch that declares none emits no key.
991
+ store_waits(n, b)
992
+ builds_of[n] = builds_note
993
+ # The kind travels with the branch, presence tracked separately so a slice
994
+ # declaring none emits no key.
995
+ agent_of[n] = agent_note
996
+ ordered_b[n] = b
997
+ commits_of[n] = commit_list($0)
998
+ }
807
999
  # The longest wave name that still reads as a label, not prose. A JUDGEMENT, not
808
1000
  # a measurement: the longest legitimate name in the estate is `Offered first`
809
1001
  # (13), and the offender this exists to catch is a 53-character sentence, so the
@@ -989,10 +1181,13 @@ section == "status" {
989
1181
  # capture to avoid storing empties. These four are scalars, and now do the
990
1182
  # same: a placeholder no longer counts as a value, so ORDER STOPS MATTERING.
991
1183
  else if (lower ~ /^[ \t]*[-*]?[ \t]*\**design[:*]/ && canon_design == "") canon_design = strip_placeholder(val_after_colon($0))
1184
+ else if (lower ~ /^[ \t]*[-*]?[ \t]*\**spike approved[:*]/ && canon_spike_approved == "") canon_spike_approved = strip_placeholder(val_after_colon($0))
1185
+ else if (lower ~ /^[ \t]*[-*]?[ \t]*\**tracer[:*]/ && canon_tracer == "") canon_tracer = strip_placeholder(val_after_colon($0))
992
1186
  else if (lower ~ /^[ \t]*[-*]?[ \t]*\**rounds[:*]/ && canon_rounds == "") canon_rounds = val_after_colon($0)
993
1187
  else if (lower ~ /^[ \t]*[-*]?[ \t]*\**approved[:*]/ && canon_approved == "") canon_approved = strip_placeholder(val_after_colon($0))
994
1188
  else if (lower ~ /^[ \t]*[-*]?[ \t]*\**released[:*]/ && canon_released == "") canon_released = strip_placeholder(val_after_colon($0))
995
1189
  else if (lower ~ /^[ \t]*[-*]?[ \t]*\**delivered[:*]/ && canon_delivered == "") canon_delivered = strip_placeholder(val_after_colon($0))
1190
+ else if (lower ~ /^[ \t]*[-*]?[ \t]*\**verified[:*]/ && canon_verified == "") canon_verified = strip_placeholder(val_after_colon($0))
996
1191
  else if (lower ~ /^[ \t]*[-*]?[ \t]*\**started[:*]/) {
997
1192
  _s = strip_placeholder(val_after_colon($0))
998
1193
  if (_s != "") started[++n_started] = _s
@@ -1075,126 +1270,7 @@ section == "slices" && slice_shape != "heading" {
1075
1270
  note_branch_heading()
1076
1271
  next
1077
1272
  }
1078
- # Claim reflection, written by the worker after its ref push succeeds. This is
1079
- # a reflection, not the claim: git refs remain authoritative. Computed before
1080
- # the branch loop below — match() clobbers RSTART/RLENGTH, which that loop
1081
- # needs to advance.
1082
- claim_note = (index($0, "claimed:") > 0) ? marker_value($0, "claimed") : ""
1083
- # THE REASON FOR THE DEFERRAL, and not merely the fact of one.
1084
- #
1085
- # `<!-- deferred: verified already implemented 2026-08-17 — startRepair() at
1086
- # fleet.ts:806 -->` was tested for presence and the sentence after the colon
1087
- # was dropped on the floor. So the board could say `deferred` beside `no
1088
- # commits` and never say that the first is the REASON for the second — a
1089
- # reader with no access to the plan file saw a branch nobody started and no
1090
- # statement that nobody should.
1091
- #
1092
- # Extracted the same way and in the same place as the claim note, for the same
1093
- # reason: `match()` in the branch loop below clobbers RSTART/RLENGTH, so
1094
- # anything read from the whole line must be read before it runs.
1095
- #
1096
- # Newlines are already impossible here — awk hands this rule one line, and the
1097
- # documented contract is that an annotation binds to the line carrying the
1098
- # branch name. A deferral whose text is wrapped onto a continuation line is
1099
- # not seen, exactly as `deferred` itself was not.
1100
- # `moved:` IS THE SAME ANSWER AS `deferred:`, and CLAUDE.md has said so since
1101
- # the reconcile scan was written: *"`deferred:`/`moved:` in the plan means
1102
- # reapable"*. `plot-reconcile-scan.sh:504` matches both in one arm; this
1103
- # parser matched only the first, so a slice given up with the other word read
1104
- # as still outstanding — to the board, the delivery gate and the fleet alike.
1105
- # Measured 2026-09-04 on `feature/the-reaper-sweeps-every-kind`: annotated
1106
- # `moved:` into the slice that superseded it, still `deferred:false` here.
1107
- #
1108
- # The two words differ in what they tell a READER — given up, versus taken
1109
- # somewhere else — and the reason is kept verbatim, so the distinction is not
1110
- # lost by being read alike.
1111
- defer_note = (index($0, "deferred:") > 0 || index($0, "moved:") > 0) ? marker_value($0, "deferred|moved") : ""
1112
- # THE PREREQUISITES THIS BRANCH NAMES: `<!-- waits: bug/other-branch -->`.
1113
- #
1114
- # A LIST, not one name. Several `<!-- waits: … -->` comments on a line, or one
1115
- # `<!-- waits: x, y -->`, give the same list in document order, duplicates
1116
- # removed — see parse_waits(). The old greedy `sub()` took only the LAST
1117
- # annotation when a line carried two, which silently dropped every other
1118
- # prerequisite a slice had cleared for merge eligibility by itself (#1153).
1119
- #
1120
- # Each value is a BRANCH NAME, so it stops at the first whitespace or comma
1121
- # rather than running to the closing marker the way a deferral reason does: a
1122
- # reason is a sentence, a branch name is a token, and trailing prose inside
1123
- # the comment would silently become part of a name that then matches nothing.
1124
- #
1125
- # `deferred:` is a judgement and `waits:` is a checkable fact, so the two are
1126
- # separate annotations and both may sit on one line. Read here, beside the
1127
- # other two, for the same reason: `match()` in the branch loop below clobbers
1128
- # RSTART/RLENGTH, so anything read from the whole line must be read first.
1129
- #
1130
- # `has_waits` carries presence separately from the value, because ABSENT and
1131
- # EMPTY are different answers — a branch declaring no prerequisite emits no
1132
- # `waits_on` key at all, never `[]`.
1133
- #
1134
- # A value that does not look like a branch is NOT dropped — parse_waits()
1135
- # queues it in pending_unread_value[], and once the branch this line claims is
1136
- # known (below), it is copied into unread_waits_branch[]/unread_waits_value[].
1137
- # A line with no branch claim never drains the queue, so a `waits:` syntax
1138
- # example in prose — not on a branch line — stays silent, as today.
1139
- delete line_waits
1140
- has_waits = (parse_waits($0, line_waits) > 0)
1141
- # WHAT THIS SLICE BUILDS: `<!-- builds: normalizeVersion, a shared helper -->`.
1142
- #
1143
- # AN ANNOTATION, NOT A FIELD LINE, and that is what makes it work in BOTH
1144
- # slice dialects with no dialect-specific code. Annotations bind to the line
1145
- # carrying the branch name — the list item in one spelling, the `### `
1146
- # heading in the other — and both dialects already read `deferred:`,
1147
- # `claimed:` and `waits:` with the identical block. A `Builds:` field line
1148
- # would have had two spellings to parse, and the template writes the LIST
1149
- # dialect, so the heading-only version would be absent from every plan
1150
- # created from it.
1151
- #
1152
- # IT BELONGS TO THE SLICE, NEVER TO THE PLAN. A plan builds several things
1153
- # and each slice builds one; a plan-level list is searched as a whole and
1154
- # reported against the wrong slice.
1155
- #
1156
- # The value runs to the closing marker, the way `deferred:` does and unlike
1157
- # `waits:`. A prerequisite is a branch NAME and stops at whitespace; a
1158
- # deliverable is a name plus enough words to search for — `normalizeVersion,
1159
- # a shared helper` — and cutting it at the first space would leave the half
1160
- # that identifies it.
1161
- #
1162
- # `has_builds` carries presence separately from the value, exactly as
1163
- # `waits:` does: a slice declaring nothing emits no key, so a consumer reads
1164
- # a deliverable or nothing and never a blank string that looks like one.
1165
- builds_note = ($0 ~ /<!--[ \t]*builds:[ \t]*/) ? marker_value($0, "builds") : ""
1166
- has_builds = (builds_note != "")
1167
- # WHICH KIND OF AGENT THIS SLICE NEEDS: `<!-- agent: reviewer -->`.
1168
- #
1169
- # `--agent <name>` was the only selector and only an operator could type it.
1170
- # `plot-registryd` hands a queued slice to a free agent with no `--agent`
1171
- # anywhere in the path, so an unattended fleet ran every slice as the same
1172
- # undifferentiated worker. The declaration has to live in the PLAN to reach a
1173
- # dispatch nobody is watching.
1174
- #
1175
- # PER-BRANCH, NEVER A `## Status` FIELD. Every Status field is plan-level, so
1176
- # one there could declare a single kind for a plan with several slices — and a
1177
- # reviewer slice beside an implementer slice is the population this is for.
1178
- #
1179
- # The value runs to the closing marker, the way `builds:` does and unlike
1180
- # `waits:`. A charter name is a bare word today, so both rules agree; this one
1181
- # is chosen because it does not silently truncate if a name grows a space.
1182
- #
1183
- # IT CANNOT VALIDATE ITS VALUE, and that is the difference from `waits:` above.
1184
- # A prerequisite has branch-prefix structure, which is what keeps a SYNTAX
1185
- # EXAMPLE in prose from reading as a declaration; a charter name is a bare word
1186
- # with no structure to check. What protects the templates instead is NESTING:
1187
- # their documentation sits inside an outer `<!-- ... -->` block, so the inner
1188
- # `agent:` carries no `<!--` of its own and this pattern never matches it —
1189
- # the same accident of shape that already keeps `builds:` out of the parse of
1190
- # a template. Documenting it as a bare `<!-- agent: reviewer -->` line would
1191
- # hand a kind to every plan created from that template. A test pins it.
1192
- #
1193
- # `has_agent` carries presence separately from the value, as all three
1194
- # annotations before it do: a slice naming no kind emits no key, so dispatch
1195
- # reads a name or nothing and never a blank string that looks like one.
1196
- agent_note = ($0 ~ /<!--[ \t]*agent:[ \t]*/) ? marker_value($0, "agent") : ""
1197
- has_agent = (agent_note != "")
1273
+ read_notes()
1198
1274
  # ONE LIST ITEM, AT MOST ONE CLAIM — an `if`, not the `while` this was.
1199
1275
  #
1200
1276
  # The old loop walked the line taking every backticked name on it, which is
@@ -1212,33 +1288,7 @@ section == "slices" && slice_shape != "heading" {
1212
1288
  if (n_waves == 0) { wave_names[++n_waves] = "" }
1213
1289
  wave_of[n_branches] = n_waves
1214
1290
  wave_seq[n_branches] = ++wave_count[n_waves]
1215
- # THE FLAG accepts the bare form as well as the annotated one.
1216
- #
1217
- # It matched `deferred:` only, so `<!-- deferred -->` — the annotation with
1218
- # nothing after it — read as NOT deferred at all: the strongest statement a
1219
- # plan can make about a branch, dropped for want of a colon. A reader
1220
- # writing the shorter form has said the branch will not be built; the
1221
- # parser now hears it.
1222
- deferred_of[n_branches] = ($0 ~ /<!--[ \t]*(deferred|moved)[ \t]*(:|-->)/) ? "true" : "false"
1223
- # The reason travels with the flag. Empty on every non-deferred branch, and
1224
- # empty is also the honest answer for the bare form: the branch IS deferred
1225
- # and no reason was recorded, which is a different statement from a reason
1226
- # of "".
1227
- deferred_why[n_branches] = defer_note
1228
- # Claim reflection, written by the worker after its ref push succeeds. This
1229
- # is a reflection, not the claim: git refs remain authoritative.
1230
- claimed_of[n_branches] = claim_note
1231
- # The prerequisites travel with the branch, flattened as waits_of[n,1..k]
1232
- # since this awk has no nested arrays. Presence is tracked separately so a
1233
- # branch that declares none emits no key.
1234
- store_waits(n_branches, b)
1235
- builds_of[n_branches] = builds_note
1236
- builds_set[n_branches] = has_builds
1237
- # The kind travels with the branch, presence tracked separately so a slice
1238
- # declaring none emits no key.
1239
- agent_of[n_branches] = agent_note
1240
- agent_set[n_branches] = has_agent
1241
- ordered_b[n_branches] = b
1291
+ keep_branch(n_branches, b)
1242
1292
  }
1243
1293
  line = $0
1244
1294
  # `→ #N` and `→ owner/repo#N` are both annotations: /plot-deliver instructs
@@ -1293,59 +1343,8 @@ section == "slices" && slice_shape == "heading" {
1293
1343
  wave_names[++n_waves] = wname
1294
1344
  note_branch_heading()
1295
1345
 
1296
- # Claim/deferral annotations bind to the line carrying the branch name, which
1297
- # is the heading. Read before any match() below, which clobbers RSTART/RLENGTH.
1298
- claim_note = (index($0, "claimed:") > 0) ? marker_value($0, "claimed") : ""
1299
- # `moved:` IS THE SAME ANSWER AS `deferred:`, and CLAUDE.md has said so since
1300
- # the reconcile scan was written: *"`deferred:`/`moved:` in the plan means
1301
- # reapable"*. `plot-reconcile-scan.sh:504` matches both in one arm; this
1302
- # parser matched only the first, so a slice given up with the other word read
1303
- # as still outstanding — to the board, the delivery gate and the fleet alike.
1304
- # Measured 2026-09-04 on `feature/the-reaper-sweeps-every-kind`: annotated
1305
- # `moved:` into the slice that superseded it, still `deferred:false` here.
1306
- #
1307
- # The two words differ in what they tell a READER — given up, versus taken
1308
- # somewhere else — and the reason is kept verbatim, so the distinction is not
1309
- # lost by being read alike.
1310
- defer_note = (index($0, "deferred:") > 0 || index($0, "moved:") > 0) ? marker_value($0, "deferred|moved") : ""
1311
- # WHAT THIS SLICE BUILDS: `<!-- builds: normalizeVersion, a shared helper -->`.
1312
- #
1313
- # AN ANNOTATION, NOT A FIELD LINE, and that is what makes it work in BOTH
1314
- # slice dialects with no dialect-specific code. Annotations bind to the line
1315
- # carrying the branch name — the list item in one spelling, the `### `
1316
- # heading in the other — and both dialects already read `deferred:`,
1317
- # `claimed:` and `waits:` with the identical block. A `Builds:` field line
1318
- # would have had two spellings to parse, and the template writes the LIST
1319
- # dialect, so the heading-only version would be absent from every plan
1320
- # created from it.
1321
- #
1322
- # IT BELONGS TO THE SLICE, NEVER TO THE PLAN. A plan builds several things
1323
- # and each slice builds one; a plan-level list is searched as a whole and
1324
- # reported against the wrong slice.
1325
- #
1326
- # The value runs to the closing marker, the way `deferred:` does and unlike
1327
- # `waits:`. A prerequisite is a branch NAME and stops at whitespace; a
1328
- # deliverable is a name plus enough words to search for — `normalizeVersion,
1329
- # a shared helper` — and cutting it at the first space would leave the half
1330
- # that identifies it.
1331
- #
1332
- # `has_builds` carries presence separately from the value, exactly as
1333
- # `waits:` does: a slice declaring nothing emits no key, so a consumer reads
1334
- # a deliverable or nothing and never a blank string that looks like one.
1335
- builds_note = ($0 ~ /<!--[ \t]*builds:[ \t]*/) ? marker_value($0, "builds") : ""
1336
- has_builds = (builds_note != "")
1337
- # The prerequisites, read exactly as the list-item spelling reads them — see
1338
- # parse_waits() and the comment at the list-item block for why the value is a
1339
- # list, why it stops at whitespace/comma, and how an unreadable value reaches
1340
- # unread_waits instead of being dropped.
1341
- delete line_waits
1342
- has_waits = (parse_waits($0, line_waits) > 0)
1343
- # The agent kind, read exactly as the list-item spelling reads it. Both
1344
- # dialects emit the same waves[], so a field added to one only would break that
1345
- # contract the first time a plan migrated. See the list-item block for why the
1346
- # value runs to the closing marker and why this one cannot validate itself.
1347
- agent_note = ($0 ~ /<!--[ \t]*agent:[ \t]*/) ? marker_value($0, "agent") : ""
1348
- has_agent = (agent_note != "")
1346
+ # Annotations bind to the line carrying the branch name, which is the heading.
1347
+ read_notes()
1349
1348
 
1350
1349
  # The branch is the `Branch:` value, matched against the known prefixes exactly
1351
1350
  # as the old shape matched the backticked name. Written unquoted in the heading
@@ -1359,25 +1358,14 @@ section == "slices" && slice_shape == "heading" {
1359
1358
  # the heading opened a wave and yielded nothing. The backticks are optional on
1360
1359
  # both sides and stripped from the name. Measured 2026-09-28 over 357 plans:
1361
1360
  # 2 records change, 355 byte-identical.
1362
- hmeta = $0
1363
- if (match(hmeta, "Branch:[ \t]*`?(" PREFIXES ")/[^ \t,)`]+`?")) {
1364
- b = substr(hmeta, RSTART, RLENGTH)
1361
+ if (match($0, "Branch:[ \t]*`?(" PREFIXES ")/[^ \t,)`]+`?")) {
1362
+ b = substr($0, RSTART, RLENGTH)
1365
1363
  sub(/^Branch:[ \t]*/, "", b)
1366
1364
  gsub(/`/, "", b)
1367
1365
  branches[++n_branches] = b
1368
1366
  wave_of[n_branches] = n_waves
1369
1367
  wave_seq[n_branches] = ++wave_count[n_waves]
1370
- # Bare `<!-- deferred -->` sets the flag with no reason, same as the old
1371
- # shape; `deferred:` carries the reason.
1372
- deferred_of[n_branches] = ($0 ~ /<!--[ \t]*(deferred|moved)[ \t]*(:|-->)/) ? "true" : "false"
1373
- deferred_why[n_branches] = defer_note
1374
- claimed_of[n_branches] = claim_note
1375
- store_waits(n_branches, b)
1376
- builds_of[n_branches] = builds_note
1377
- builds_set[n_branches] = has_builds
1378
- agent_of[n_branches] = agent_note
1379
- agent_set[n_branches] = has_agent
1380
- ordered_b[n_branches] = b
1368
+ keep_branch(n_branches, b)
1381
1369
  }
1382
1370
 
1383
1371
  # The PR is the `PR: #NNN` value in the heading. Absent PR: contributes
@@ -318,7 +318,6 @@ NODE_EOF
318
318
  )
319
319
 
320
320
  refusal=${verdict%%$'\t'*}
321
- detail=${verdict#*$'\t'}
322
321
 
323
322
  if [ "$refusal" != "delete" ]; then
324
323
  # The rule named the refusal; this renders it. A verdict the rule could not
@@ -395,32 +395,6 @@ plot_worker_log() { # $1=worktree → path to the worker log, or "" (non-zero)
395
395
  [ -e "$wt/.plot-worker.log" ] || return 1
396
396
  printf '%s' "$wt/.plot-worker.log"
397
397
  }
398
- # Why did the worker in this worktree end?
399
- #
400
- # A SEPARATE READING FROM `plot_worker_state`, and deliberately so. That function
401
- # answers what the PROCESS did and what the desk holds; this answers why the
402
- # worker stopped, which is a fact only the worker itself could record. The two
403
- # come apart in the case that matters: a worker ended by the floor and one ended
404
- # by a monitor finding both leave `.plot-worker.exit` holding `124`, so the exit
405
- # code cannot tell them apart and the state word does not try to.
406
- #
407
- # IT IS NOT FOLDED INTO THE STATE ROW. `plot_worker_state` prints three
408
- # tab-separated fields that three callers and one domain port parse positionally;
409
- # a fourth field would change a contract this reading does not need to change.
410
- # `plot_worker_log` is the precedent — a standalone reader beside the state
411
- # function, asked by whoever wants it.
412
- #
413
- # ABSENT IS ABSENT, and it is load-bearing. No worktree, or no ending file in
414
- # one, prints nothing and returns non-zero — which is what a SIGKILLed worker
415
- # leaves behind, and what every worker that ran before this record existed
416
- # leaves too. The domain's `readEnding` keeps that apart from a file that exists
417
- # and does not parse; this prints the bytes and decides neither.
418
- plot_worker_ending() { # $1=worktree → the ending record's JSON, or "" (non-zero)
419
- local wt="$1"
420
- [ -n "$wt" ] || return 1
421
- [ -f "$wt/.plot-worker.ending.json" ] || return 1
422
- cat "$wt/.plot-worker.ending.json" 2>/dev/null
423
- }
424
398
 
425
399
  # Is a person being waited on inside this worktree?
426
400
  #
@@ -820,25 +794,6 @@ plot_worker_idle_now() { # $1..$7 as above → idle | silent
820
794
  # `origin/<default>` resolution are copied verbatim, including the comment
821
795
  # that explains why a dispatched branch's own claim commit must not count.
822
796
 
823
- # The reset epoch a desk is waiting out, or nothing.
824
- #
825
- # THE LOOP WRITES THE FILE AND THIS ONLY READS IT. `.plot-worker.limited`
826
- # carries the reset epoch, the same instant as ISO text, and the limit line;
827
- # only the first field is read here, because the caller compares integers and
828
- # never parses a date.
829
- #
830
- # NOTHING IS ANSWERED FOR AN ABSENT, EMPTY OR UNPARSEABLE FILE, and the caller
831
- # reads that as *this desk is not waiting*. A record whose first field is not a
832
- # number is the same answer as no record: a reading that cannot be made must
833
- # not widen into a reason to hold a verdict back.
834
- plot_worker_limited_reset() { # $1=worktree → epoch seconds | ""
835
- local file="$1/.plot-worker.limited" reset
836
- [ -n "$1" ] && [ -r "$file" ] || return 0
837
- reset=$(cut -f1 < "$file" 2>/dev/null | head -n1)
838
- case "$reset" in (''|*[!0-9]*) return 0 ;; esac
839
- printf '%s' "$reset"
840
- }
841
-
842
797
  # Are there commits on this branch yet? → 0 yes | 1 no | 2 unanswerable
843
798
  #
844
799
  # THE THIRD CONDITION ON `idle`, and the one that separates a stall from an