@plot-pm/board 0.6.0-rc.21 → 0.6.0-rc.210

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plot-pm/board",
-  "version": "0.6.0-rc.21",
+  "version": "0.6.0-rc.210",
   "description": "Local Kanban board for Plot — a glanceable view of plan phases from docs/plans, with sprint and story filters",
   "type": "module",
   "license": "MIT",
@@ -32,7 +32,7 @@
     "build": "pnpm run build:client && pnpm run build:server",
     "prepack": "pnpm run build",
     "typecheck": "tsc --noEmit",
-    "test": "node --test test/*.test.mjs",
+    "test": "node --test --test-concurrency=4 test/*.test.mjs",
     "test:integration": "pnpm build && vitest run"
   },
   "devDependencies": {

package/plot-config.sh

@@ -40,6 +40,17 @@
 #   Approve command     how the board runs `/plot-approve <slug>`; the prompt is
 #                       appended as one argument. Absent = the board's Approve
 #                       button renders disabled, naming this key as the fix.
+#   Idea command        how the board runs `/plot-idea` on a tracker issue; the
+#                       prompt is appended as one argument, and it names a FILE
+#                       the board wrote (an issue body is free text from anyone
+#                       who can file an issue, so no part of it is ever a shell
+#                       word). REQUIRED for the issue row's `Create plan`
+#                       action, unlike `Approve command`: approving has a
+#                       script to fall back to, and creating a plan does not —
+#                       every step of /plot-idea is judgement, and no script
+#                       here can invoke a skill. Absent (or `none`) = the button
+#                       refuses and names this key as the fix, rather than
+#                       accepting the click and doing nothing.
 # Plot 2 posture keys (repo-declared ceremony bounds; all optional):
 #   Plan PRs            required | never | optional   (never = hard gate)
 #   Implementation home this repo | <repo/path list> | none

package/plot-plan-meta.sh

@@ -45,8 +45,14 @@
 #   file           the path given
 #   format         canonical | frontmatter | none
 #   phase_raw      primary phase value as written ("" if absent)
-#   phase          normalized: draft|approved|delivered|released|rejected|
-#                  superseded|UNKNOWN|NONE
+#   phase          normalized: draft|design|approved|delivered|released|
+#                  rejected|superseded|UNKNOWN|NONE
+#                  `design` is a phase of its own, not a synonym for anything:
+#                  a plan in Design cannot yet be handed to development because
+#                  it needs a spec, a spike or a tracer bullet first. That is a
+#                  different statement from "approved and nobody has started",
+#                  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 ""
 #   phase_alt      normalized phase_alt_raw (NONE when absent)
@@ -66,8 +72,26 @@
 #                  `<!-- claimed: ... -->`) bind to the LINE carrying the
 #                  backticked branch name. An annotation on a wrapped
 #                  continuation line is not seen — keep it on the branch line.
+#                  `<!-- deferred -->` (bare, no colon) sets the flag with no
+#                  reason; `waves[].branches[].deferred_reason` carries the
+#                  sentence after the colon, "" where none was written.
 #   prs            PR numbers from `→ #NNN` links in the `## Branches`
 #                  section (sorted, unique)
+#   changelog      the plan's `## Changelog` entries, one string per bullet, in
+#                  document order; [] when the plan has no changelog or an
+#                  unfilled one. This is the one field that says WHAT A PLAN
+#                  CHANGES, which title and story do not.
+#                  ENTRIES, not lines: a bullet wrapped across several lines is
+#                  one entry with the continuation lines joined by a single
+#                  space (9 of the 34 changelogs in the origin repo wrap, so
+#                  line-per-line would have shredded a quarter of them). An
+#                  INDENTED bullet folds into the entry above it the same way:
+#                  a sub-point is not a release note of its own.
+#                  Non-bullet prose in the section is NOT an entry — 8 plans
+#                  close their changelog with a "Board impact:" paragraph, which
+#                  is a note to a reviewer rather than a release note. Comment
+#                  interiors stay non-content, as everywhere else in this parser,
+#                  so the template's guidance block contributes nothing.
 #   issues         tracker issue numbers this plan answers, from the `## Status`
 #                  `Issue:` line or front matter `issue:` (sorted, unique).
 #                  A DEDICATED field, never a scan of the body for `#NNN`: a
@@ -86,6 +110,12 @@
 #                  `Released:` or front matter `released:` — date and version).
 #                  Empty until /plot-release records it; the tag stays the git
 #                  truth and this merely reflects it.
+#   design_raw     the design transition record as written (`## Status`
+#                  `Design:` or front matter `design:` — who/when, and what the
+#                  design work is); "" if absent. Reported for any plan that
+#                  carries the line, whatever its phase: a plan that WENT
+#                  THROUGH design keeps the record after moving on, exactly as
+#                  `approved_raw` outlives the Approved phase.
 #   approved_raw   the approval transition record as written (`## Status`
 #                  `Approved:` or front matter `approved:` — who/when/channel,
 #                  e.g. "2026-07-30, alice, in-session"); "" if absent
@@ -138,7 +168,7 @@ if [ ${#files[@]} -eq 0 ] && [ ${#missing[@]} -eq 0 ]; then
 fi
 
 for f in ${missing[@]+"${missing[@]}"}; do
-  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":[],"issues":[],"review_raw":"","review":"NONE","impl_raw":"","impl":"NONE","approved_raw":"","released_raw":"","delivered_raw":"","started_raw":[]}\n' \
+  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":[],"issues":[],"changelog":[],"review_raw":"","review":"NONE","impl_raw":"","impl":"NONE","design_raw":"","approved_raw":"","released_raw":"","delivered_raw":"","started_raw":[]}\n' \
     "$(printf '%s' "$f" | sed 's/\\/\\\\/g; s/"/\\"/g')"
 done
 
@@ -166,7 +196,7 @@ function norm_phase(raw,   lower, toks, n, i, t) {
   for (i = 1; i <= n; i++) {
     t = toks[i]
     gsub(/^[^a-z]+/, "", t); gsub(/[^a-z-]+$/, "", t)
-    if (t ~ /^(draft|approved|delivered|released|rejected|superseded)$/) return t
+    if (t ~ /^(draft|design|approved|delivered|released|rejected|superseded)$/) return t
     if (t == "ready-for-review" || t == "in-review") return "approved"
   }
   return "UNKNOWN"
@@ -211,11 +241,11 @@ function reset_state() {
   fm_status = ""; fm_phase = ""; fm_type = ""
   fm_title = ""; fm_sprint = ""; fm_story = ""; fm_assignee = ""
   fm_review = ""; fm_impl = ""; fm_approved = ""; fm_started = ""; fm_released = ""
-  fm_delivered = ""
+  fm_delivered = ""; fm_design = ""
   canon_phase = ""; canon_type = ""
   canon_sprint = ""; canon_story = ""; canon_assignee = ""
   canon_review = ""; canon_impl = ""; canon_approved = ""; canon_released = ""
-  canon_delivered = ""
+  canon_delivered = ""; canon_design = ""
   h1_title = ""
   # "" means the plan carries no readable round — NOT zero. Emitted by omitting
   # the field, so a consumer cannot mistake "never interrogated" for "asked
@@ -227,10 +257,12 @@ function reset_state() {
   fm_issue = ""; canon_issue = ""
   delete issues; n_issues = 0
   delete wave_names; delete wave_of; delete wave_seq; delete wave_count
-  delete deferred_of; delete claimed_of; delete ordered_b; n_waves = 0
+  delete deferred_of; delete deferred_why; delete claimed_of; delete ordered_b; n_waves = 0
   delete started; n_started = 0
+  fm_changelog = ""
+  delete changelog; n_changelog = 0; changelog_seen = 0; cl_open = 0
 }
-function emit_record(   fmt, praw, palt_raw, traw, title, sprint, story, assignee, review, impl, approved, delivered, issue, i, j, out, sorted_b, sorted_p, sorted_i, nb, np, ni) {
+function emit_record(   fmt, praw, palt_raw, traw, title, sprint, story, assignee, review, impl, design, approved, delivered, issue, i, j, out, sorted_b, sorted_p, sorted_i, nb, np, ni) {
   if (fm_status != "" || fm_phase != "") {
     fmt = "frontmatter"
     praw = (fm_status != "") ? fm_status : fm_phase
@@ -249,6 +281,7 @@ function emit_record(   fmt, praw, palt_raw, traw, title, sprint, story, assigne
   assignee = strip_placeholder((fm_assignee != "") ? fm_assignee : canon_assignee)
   review   = strip_placeholder((fm_review   != "") ? fm_review   : canon_review)
   impl     = strip_placeholder((fm_impl     != "") ? fm_impl     : canon_impl)
+  design   = strip_placeholder((fm_design   != "") ? fm_design   : canon_design)
   approved = strip_placeholder((fm_approved != "") ? fm_approved : canon_approved)
   released = strip_placeholder((fm_released != "") ? fm_released : canon_released)
   delivered = strip_placeholder((fm_delivered != "") ? fm_delivered : canon_delivered)
@@ -302,6 +335,15 @@ function emit_record(   fmt, praw, palt_raw, traw, title, sprint, story, assigne
   out = out "],\"issues\":["
   for (i = 1; i <= ni; i++) out = out (i > 1 ? "," : "") sorted_i[i]
   out = out "]"
+  # Document order, never sorted: a changelog is a narrative sequence, and the
+  # first entry is the headline. Front matter wins, as it does for every other
+  # field, and contributes exactly one entry.
+  if (fm_changelog != "" && strip_placeholder(fm_changelog) != "") {
+    delete changelog; n_changelog = 1; changelog[1] = strip_placeholder(fm_changelog)
+  }
+  out = out ",\"changelog\":["
+  for (i = 1; i <= n_changelog; i++) out = out (i > 1 ? "," : "") "\"" jesc(changelog[i]) "\""
+  out = out "]"
   # waves[]: branches grouped by `### ` subheading, in document order. A plan
   # with no subheadings yields one wave with an empty name.
   out = out ",\"waves\":["
@@ -311,6 +353,7 @@ function emit_record(   fmt, praw, palt_raw, traw, title, sprint, story, assigne
     for (i = 1; i <= n_branches; i++) {
       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]) "\"}"
       first = 0
     }
@@ -319,6 +362,7 @@ function emit_record(   fmt, praw, palt_raw, traw, title, sprint, story, assigne
   out = out "]"
   out = out ",\"review_raw\":\"" jesc(review) "\",\"review\":\"" norm_review(review) "\""
   out = out ",\"impl_raw\":\"" jesc(impl) "\",\"impl\":\"" norm_impl(impl) "\""
+  out = out ",\"design_raw\":\"" jesc(design) "\""
   out = out ",\"approved_raw\":\"" jesc(approved) "\""
   out = out ",\"released_raw\":\"" jesc(released) "\""
   out = out ",\"delivered_raw\":\"" jesc(delivered) "\""
@@ -350,10 +394,15 @@ in_fm {
   else if (lower ~ /^assignee:/ && fm_assignee == "") fm_assignee = val_after_colon($0)
   else if (lower ~ /^review:/ && fm_review == "") fm_review = val_after_colon($0)
   else if (lower ~ /^impl:/ && fm_impl == "") fm_impl = val_after_colon($0)
+  else if (lower ~ /^design:/ && fm_design == "") fm_design = val_after_colon($0)
   else if (lower ~ /^approved:/ && fm_approved == "") fm_approved = val_after_colon($0)
   else if (lower ~ /^released:/ && fm_released == "") fm_released = val_after_colon($0)
   else if (lower ~ /^delivered:/ && fm_delivered == "") fm_delivered = val_after_colon($0)
   else if (lower ~ /^started:/ && fm_started == "") fm_started = val_after_colon($0)
+  # A scalar `changelog:` in front matter is one entry. A YAML list is NOT read
+  # here: front matter in this repo is a flat key/value surface, and guessing a
+  # list grammar the format never promised would invent a contract.
+  else if (lower ~ /^changelog:/ && fm_changelog == "") fm_changelog = val_after_colon($0)
   next
 }
 # Interior of multi-line HTML comments is non-content (template guidance
@@ -391,6 +440,10 @@ in_comment {
   # section in prose, and those later headings are illustration, not contract.
   else if ($0 ~ /^## Branches/) { section = branches_seen ? "" : "branches"; branches_seen = 1 }
   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
+  # illustration rather than contract.
+  else if ($0 ~ /^## Changelog/) { section = changelog_seen ? "" : "changelog"; changelog_seen = 1 }
   else section = ""
   next
 }
@@ -403,6 +456,7 @@ 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)
   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)
@@ -417,6 +471,47 @@ section == "approval" {
   if (lower ~ /^[ \t]*[-*]?[ \t]*\**assignee[:*]/ && canon_assignee == "") canon_assignee = val_after_colon($0)
   next
 }
+# `## Changelog` — the release-note entries. One entry per bullet, wrapped
+# continuation lines folded into the entry they belong to.
+#
+# A bullet opens an entry. An indented non-bullet line continues the open one.
+# A blank line or a line at column zero closes it: the flush-left prose that 8
+# plans use for a "Board impact:" note is a remark to a reviewer, not a release
+# note, so it ends the entry rather than joining it.
+section == "changelog" {
+  # A line that is nothing but an HTML comment is not content, at any
+  # indentation. Multi-line comments are already swallowed upstream; an INDENTED
+  # single-liner would otherwise land in the continuation branch below and paste
+  # its own markup into the entry above it.
+  if ($0 ~ /^[ \t]*<!--.*-->[ \t]*$/) next
+  # An INDENTED bullet is a sub-point of the entry above, not a release note of
+  # its own, so it continues rather than opens. No changelog in the repo nests
+  # today; the rule is here because the alternative silently promotes a
+  # sub-point to a headline the moment one does.
+  if (cl_open && $0 ~ /^[ \t]+[-*][ \t]/) {
+    _n = $0
+    sub(/^[ \t]*[-*][ \t]+/, "", _n)
+    changelog[n_changelog] = changelog[n_changelog] " " trim(_n)
+    next
+  }
+  if ($0 ~ /^[ \t]*[-*][ \t]/) {
+    _e = $0
+    sub(/^[ \t]*[-*][ \t]+/, "", _e)
+    _e = strip_placeholder(trim(_e))
+    if (_e != "") { changelog[++n_changelog] = _e; cl_open = 1 }
+    else cl_open = 0   # an unfilled bullet opens nothing to continue
+    next
+  }
+  if (cl_open && $0 ~ /^[ \t]+[^ \t]/) {
+    changelog[n_changelog] = changelog[n_changelog] " " trim($0)
+    next
+  }
+  # Blank line, or prose at column zero: whatever entry was open is finished.
+  # The flag matters — without it a continuation-shaped line after a break would
+  # glue itself onto an entry it never belonged to.
+  cl_open = 0
+  next
+}
 section == "branches" {
   # `### <name>` opens a wave. Branches before any subheading belong to an
   # unnamed wave, so a pre-wave plan parses as exactly one wave.
@@ -435,6 +530,30 @@ section == "branches" {
     sub(/[ \t]*-->.*$/, "", _c)
     claim_note = trim(_c)
   }
+  # THE REASON FOR THE DEFERRAL, and not merely the fact of one.
+  #
+  # `<!-- deferred: verified already implemented 2026-08-17 — startRepair() at
+  # fleet.ts:806 -->` was tested for presence and the sentence after the colon
+  # was dropped on the floor. So the board could say `deferred` beside `no
+  # commits` and never say that the first is the REASON for the second — a
+  # reader with no access to the plan file saw a branch nobody started and no
+  # statement that nobody should.
+  #
+  # Extracted the same way and in the same place as the claim note, for the same
+  # reason: `match()` in the branch loop below clobbers RSTART/RLENGTH, so
+  # anything read from the whole line must be read before it runs.
+  #
+  # Newlines are already impossible here — awk hands this rule one line, and the
+  # 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.
+  defer_note = ""
+  if (index($0, "deferred:") > 0) {
+    _d = $0
+    sub(/^.*<!--[ \t]*deferred:[ \t]*/, "", _d)
+    sub(/[ \t]*-->.*$/, "", _d)
+    defer_note = trim(_d)
+  }
   line = $0
   while (match(line, branch_re)) {
     b = substr(line, RSTART + 1, RLENGTH - 2)
@@ -442,7 +561,19 @@ section == "branches" {
     if (n_waves == 0) { wave_names[++n_waves] = "" }
     wave_of[n_branches] = n_waves
     wave_seq[n_branches] = ++wave_count[n_waves]
-    deferred_of[n_branches] = ($0 ~ /<!--[ \t]*deferred:/) ? "true" : "false"
+    # THE FLAG accepts the bare form as well as the annotated one.
+    #
+    # It matched `deferred:` only, so `<!-- deferred -->` — the annotation with
+    # nothing after it — read as NOT deferred at all: the strongest statement a
+    # 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"
+    # 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
+    # of "".
+    deferred_why[n_branches] = defer_note
     # 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