@plot-pm/board 0.8.1 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plot-pm/board",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Local Kanban board for Plot — a glanceable view of plan phases from docs/plans, with sprint and story filters",
   "type": "module",
   "license": "MIT",

package/plot-config.sh

@@ -27,6 +27,12 @@
 #   Project board | Branch prefixes | Plan directory | Active index |
 #   Delivered index | Sprint directory | Story directory | Story index |
 #   Plan template | Main branch | Board command
+#   Worktree root       where /plot-dispatch puts its worktrees. Read by
+#                       plot-dispatch.sh; default is the repo's PARENT, which
+#                       scatters `plot-wt-*` beside the checkout. An absolute
+#                       path is taken as given; a relative one resolves against
+#                       the repo root, so `.worktrees` gathers them inside it.
+#                       The default is kept for repos that never set it.
 #   Worker bound        seconds a single prompt run may take in the worker loop
 #                       before it is ended and the worker exits (no hop). Read by
 #                       plot-worker-loop.sh; default 3600 (~1h), `0` disables it.
@@ -42,6 +48,14 @@
 #                       the board finds the registry wherever it was started.
 #                       Absent = the default, so a single-checkout project is
 #                       unaffected.
+#   Worktree root       where /plot-dispatch creates fleet worktrees. A relative
+#                       value resolves against the repo root, an absolute one is
+#                       taken as given. Absent = the default `repo_root/..` with
+#                       the `plot-wt-` prefix — today's behaviour, so no existing
+#                       checkout moves. Under a dedicated root the prefix is
+#                       dropped: the directory already says these are Plot's. Read
+#                       only by the CREATION path; every "which worktree holds this
+#                       branch" read asks `git worktree list` instead.
 # Agent-runner keys (optional; Plot hardcodes no agent tooling, Principle 5):
 #   Worker command      how /plot-dispatch runs an agent headless on a worktree.
 #                       `none` = asked, and this repo starts workers by hand —

package/plot-plan-meta.sh

@@ -57,6 +57,11 @@
 # the old shape invited (a second path-shaped token on a line read as a phantom
 # branch) is structurally impossible.
 #
+# The old shape is now closed against the same defect from the other side: a
+# claim must be a LIST ITEM that starts with the backticked name, so a branch
+# cited in prose, a blockquote or an HTML comment under `## Branches` is read as
+# the citation it is. See the anchor at `branch_claim_re` below.
+#
 # Phase values are normalized by scanning whitespace-separated tokens for the
 # first known phase word — so decorated real-world values like
 # "Delivered (2026-06-29) — split done" normalize to "delivered". A non-empty
@@ -88,9 +93,14 @@
 #   assignee       github handle from the `## Approval` `Assignee:` line or
 #                  front matter `assignee:`; "" if absent
 #   branches       branch names, sorted and unique, read from EITHER spelling:
-#                  the old `## Branches` section (backtick-quoted in the list
-#                  line, matching the known prefixes) OR the new `## Waves`
-#                  section (`Branch:` in a `### ` heading — see below). Both
+#                  the old `## Branches` section (a LIST ITEM whose first token
+#                  is the backtick-quoted name, matching the known prefixes) OR
+#                  the new `## Waves` section (`Branch:` in a `### ` heading —
+#                  see below). A backticked branch name anywhere else under
+#                  `## Branches` — mid-sentence, in a blockquote, in a comment,
+#                  on a wrapped continuation line — is a CITATION and claims
+#                  nothing: plans name each other branches to declare
+#                  dependencies, and doing so must not claim them. Both
 #                  spellings emit the same array; a plan carries one or the
 #                  other, and the parser reads both so a migration that moves
 #                  files one at a time never makes a plan silently empty.
@@ -201,11 +211,18 @@
 set -uo pipefail
 
 prefixes='idea|feature|bug|docs|infra'
+tracker_override=''      # set by --tracker; overrides the config read below
+tracker_override_set=0
 files=()
 missing=()
 while [ $# -gt 0 ]; do
   case "$1" in
     --prefixes) prefixes="${2:?--prefixes needs a value}"; shift 2 ;;
+    # --tracker names the tracker directly, bypassing plot-config.sh. It exists
+    # for the contract tests (which parse fixtures outside any repo whose Plot
+    # Config could name a tracker) and for a caller that has already resolved
+    # the value once. An empty value means "GitHub", the same as no config.
+    --tracker) tracker_override="${2-}"; tracker_override_set=1; shift 2 ;;
     -*) echo "plot-plan-meta: unknown flag: $1" >&2; shift ;;
     *)
       if [ -f "$1" ]; then files+=("$1"); else missing+=("$1"); fi
@@ -225,7 +242,33 @@ done
 
 [ ${#files[@]} -gt 0 ] || exit 0
 
-awk -v PREFIXES="$prefixes" '
+# Read the tracker config to determine whether tracker-key issue references
+# (`PROJ-123`) are parsed in addition to GitHub's `#N`.
+#
+# THIS IS THE FIRST CONFIGURATION DEPENDENCY THIS SCRIPT HAS — keep it narrow:
+# read ONE key, an unreadable or missing config means GitHub (today's
+# behaviour), and NEVER fail a parse for want of configuration. plot-config.sh
+# exits 0 for all cases and prints an empty string when the key is absent, so a
+# repo with no `## Plot Config` at all still parses exactly as it does today.
+if [ "$tracker_override_set" -eq 1 ]; then
+  tracker="$tracker_override"
+else
+  script_dir="$(dirname "${BASH_SOURCE[0]}")"
+  tracker=$("$script_dir/plot-config.sh" get Tracker 2>/dev/null || true)
+fi
+# The value may carry a URL after the scheme (`jira https://…`), so match the
+# FIRST token, lowercased. Only a tracker whose keys are `LETTERS-digits` —
+# jira, linear — enables the key form; github, github-issues, plot, and absent
+# all keep `#N`-only, unchanged. An unrecognized token stays GitHub too: a
+# guess here would let `WONT-FIX` masquerade as an issue reference and hide a
+# real ticket, which the plan interrogation explicitly rejected.
+tracker_scheme=$(printf '%s' "$tracker" | tr '[:upper:]' '[:lower:]' | awk '{print $1}')
+case "$tracker_scheme" in
+  jira|linear) parse_key_issues=1 ;;
+  *) parse_key_issues=0 ;;
+esac
+
+awk -v PREFIXES="$prefixes" -v PARSE_KEY_ISSUES="$parse_key_issues" '
 function jesc(s) {
   gsub(/\\/, "\\\\", s); gsub(/"/, "\\\"", s); gsub(/\t/, "\\t", s)
   return s
@@ -316,7 +359,7 @@ function reset_state() {
   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, design, 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, issue2, i, j, v, is_dup, out, sorted_b, sorted_p, sorted_i, nb, np, ni, num_issues, str_issues, n_num_i, n_str_i, issue_is_str) {
   if (fm_status != "" || fm_phase != "") {
     fmt = "frontmatter"
     praw = (fm_status != "") ? fm_status : fm_phase
@@ -350,10 +393,27 @@ function emit_record(   fmt, praw, palt_raw, traw, title, sprint, story, assigne
   # A LIST, because one plan can answer several signals; the plan that
   # introduced this field subsumes three.
   issue = strip_placeholder((fm_issue != "") ? fm_issue : canon_issue)
+  # GitHub-style `#N` is parsed everywhere, regardless of tracker.
   while (match(issue, /#[0-9]+/)) {
     issues[++n_issues] = substr(issue, RSTART + 1, RLENGTH - 1)
     issue = substr(issue, RSTART + RLENGTH)
   }
+  # Jira-style `PROJ-123` is parsed ONLY when Tracker: names a non-GitHub
+  # tracker (jira, linear). PARSE_KEY_ISSUES is set by the shell before the awk
+  # invocation, based on plot-config.sh reading the Tracker key. Missing config
+  # defaults to 0 (GitHub behaviour), so this never fires in a repo with no
+  # config — the test in this branch proves that (Done-when item 6).
+  #
+  # THE PATTERN is `[A-Z]+-[0-9]+` anchored to word boundaries by iterating
+  # through the string. A greedy match of the whole field would capture only
+  # one; the loop mirrors the `#N` extraction above.
+  if (PARSE_KEY_ISSUES == 1) {
+    issue2 = strip_placeholder((fm_issue != "") ? fm_issue : canon_issue)
+    while (match(issue2, /[A-Z][A-Z0-9]*-[0-9]+/)) {
+      issues[++n_issues] = substr(issue2, RSTART, RLENGTH)
+      issue2 = substr(issue2, RSTART + RLENGTH)
+    }
+  }
   # Insertion sort + dedupe (portable: no gawk asort).
   nb = 0
   for (i = 1; i <= n_branches; i++) {
@@ -369,13 +429,36 @@ function emit_record(   fmt, praw, palt_raw, traw, title, sprint, story, assigne
     for (j = np; j >= 1 && sorted_p[j] > prs[i]+0; j--) sorted_p[j+1] = sorted_p[j]
     sorted_p[j+1] = prs[i]+0; np++
   }
-  ni = 0
+  # Issues: sort numeric (GitHub) issues first, then string (Jira) keys.
+  # Separate into two arrays, sort each, then concatenate.
+  n_num_i = 0; n_str_i = 0
   for (i = 1; i <= n_issues; i++) {
-    for (j = 1; j <= ni && sorted_i[j] != issues[i]+0; j++) ;
-    if (j <= ni) continue
-    for (j = ni; j >= 1 && sorted_i[j] > issues[i]+0; j--) sorted_i[j+1] = sorted_i[j]
-    sorted_i[j+1] = issues[i]+0; ni++
+    v = issues[i]
+    if (v ~ /^[0-9]+$/) {
+      # Numeric: check for duplicate, then insert sorted.
+      is_dup = 0
+      for (j = 1; j <= n_num_i; j++) if (num_issues[j] == v + 0) { is_dup = 1; break }
+      if (!is_dup) {
+        for (j = n_num_i; j >= 1 && num_issues[j] > v + 0; j--) num_issues[j+1] = num_issues[j]
+        num_issues[j+1] = v + 0; n_num_i++
+      }
+    } else {
+      # String (Jira key): check for duplicate, then insert sorted.
+      is_dup = 0
+      for (j = 1; j <= n_str_i; j++) if (str_issues[j] == v) { is_dup = 1; break }
+      if (!is_dup) {
+        for (j = n_str_i; j >= 1 && str_issues[j] > v; j--) str_issues[j+1] = str_issues[j]
+        str_issues[j+1] = v; n_str_i++
+      }
+    }
   }
+  # Concatenate: numeric first, then string (matches the field ordering the
+  # board expects — GitHub issues before Jira keys when both are present).
+  ni = 0
+  for (i = 1; i <= n_num_i; i++) sorted_i[++ni] = num_issues[i]
+  for (i = 1; i <= n_str_i; i++) sorted_i[++ni] = str_issues[i]
+  delete issue_is_str
+  for (i = 1; i <= n_str_i; i++) issue_is_str[str_issues[i]] = 1
   out = "{\"file\":\"" jesc(cur_file) "\",\"format\":\"" fmt "\""
   out = out ",\"phase_raw\":\"" jesc(praw) "\",\"phase\":\"" norm_phase(praw) "\""
   out = out ",\"phase_alt_raw\":\"" jesc(palt_raw) "\",\"phase_alt\":\"" norm_phase(palt_raw) "\""
@@ -387,7 +470,13 @@ function emit_record(   fmt, praw, palt_raw, traw, title, sprint, story, assigne
   out = out "],\"prs\":["
   for (i = 1; i <= np; i++) out = out (i > 1 ? "," : "") sorted_p[i]
   out = out "],\"issues\":["
-  for (i = 1; i <= ni; i++) out = out (i > 1 ? "," : "") sorted_i[i]
+  for (i = 1; i <= ni; i++) {
+    # Numeric issues output as JSON numbers; string issues (Jira keys) as quoted.
+    if (sorted_i[i] in issue_is_str)
+      out = out (i > 1 ? "," : "") "\"" jesc(sorted_i[i]) "\""
+    else
+      out = out (i > 1 ? "," : "") sorted_i[i]
+  }
   out = out "],\"malformed_prs\":["
   for (i = 1; i <= n_malformed_prs; i++) out = out (i > 1 ? "," : "") "\"" jesc(malformed_prs[i]) "\""
   out = out "]"
@@ -463,7 +552,26 @@ function emit_record(   fmt, praw, palt_raw, traw, title, sprint, story, assigne
 # (13), and the offender this exists to catch is a 53-character sentence, so the
 # line sits well clear of both. Reported, never enforced — a name past it makes
 # `long_wave_names`, and nothing refuses the plan.
-BEGIN { branch_re = "`(" PREFIXES ")/[^`]+`"; LONG_WAVE_NAME_MAX = 40 }
+# A CLAIM IS A LIST ITEM, and the anchor is what says so.
+#
+# This matched a backticked branch name ANYWHERE on a line, so a plan that
+# merely CITED another plan branch under `## Branches` claimed it. Measured on
+# the board 2026-08-23: two branches rendered twice, in two sections, wearing
+# `claimed twice` — and /plot-dispatch would have fanned out a branch the plan
+# does not own. Both second claims were dependency citations, written exactly as
+# a `## Branches` section should write them.
+#
+# Rewording the citations was the old repair. That is a rule an author must
+# remember in the one section where writing branch names is the entire point,
+# and it had already been forgotten twice. Gates over rules: anchoring makes the
+# parser UNABLE to read a citation as a claim.
+#
+# Licensed by a MEASUREMENT, not a preference. Swept across docs/plans/ on
+# 2026-08-27: 259 lines under `## Branches` carry a backticked branch name and
+# all 259 are anchored list items, so the stricter rule drops no real claim. The
+# contract test re-runs that sweep differentially rather than pinning a total —
+# the estate moves weekly, and an absolute number would fail a correct parser.
+BEGIN { branch_claim_re = "^[ \t]*-[ \t]+`(" PREFIXES ")/[^`]+`"; LONG_WAVE_NAME_MAX = 40 }
 FNR == 1 {
   if (NR > 1) emit_record()
   reset_state()
@@ -667,9 +775,19 @@ section == "branches" {
     sub(/[ \t]*-->.*$/, "", _d)
     defer_note = trim(_d)
   }
-  line = $0
-  while (match(line, branch_re)) {
-    b = substr(line, RSTART + 1, RLENGTH - 2)
+  # 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
+  # exactly how a citation became a second claim. Anchoring makes a second match
+  # impossible by construction, so the loop is gone rather than left as dead
+  # scaffolding that reads like several claims per item are still expected.
+  #
+  # The match now spans `- ` and the backticks, so the name is cut from the
+  # first backtick rather than from RSTART: RSTART lands on the indent.
+  if (match($0, branch_claim_re)) {
+    claim = substr($0, RSTART, RLENGTH)
+    b = substr(claim, index(claim, "`") + 1)
+    sub(/`$/, "", b)
     branches[++n_branches] = b
     if (n_waves == 0) { wave_names[++n_waves] = "" }
     wave_of[n_branches] = n_waves
@@ -691,7 +809,6 @@ section == "branches" {
     # is a reflection, not the claim: git refs remain authoritative.
     claimed_of[n_branches] = claim_note
     ordered_b[n_branches] = b
-    line = substr(line, RSTART + RLENGTH)
   }
   line = $0
   # `→ #N` and `→ owner/repo#N` are both annotations: /plot-deliver instructs