@mmerterden/multi-agent-pipeline 12.10.0 → 12.11.0

package/CHANGELOG.md

@@ -16,6 +16,65 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ## [Unreleased]
 
+## [12.11.0] - 2026-07-26
+
+### Tracker tile titles rendered HTML entities
+
+A live run showed this in the TaskList widget:
+
+```
+Phase 1: Build & Launch
+Phase 3: Drive & Compare
+```
+
+`rules.md` already forbids entities in "titles, commit messages, task subjects, or
+body text" because nothing downstream decodes them. A tile title IS a task subject,
+so the rule covered this exactly. `output-quality-check.sh` enforced it over the PR
+body and the Jira comment and nowhere else, so the one surface where the rule was
+actually broken was the one surface nothing inspected. The gap was in the check's
+coverage, not in the rule.
+
+`phase-tracker.sh add` is the single funnel for every tile title, so it decodes
+there, and warns on stderr: decoding silently would fix the display and hide the
+bug that produced it.
+
+**All three encodings**, because a title can arrive in any of them:
+
+| | ampersand | less-than | em-dash |
+|---|---|---|---|
+| named | `&` | `<` | `—` |
+| decimal | `&` | `<` | `—` |
+| hex | `&` | `<` | `—` |
+
+The first version of this fix handled only the named column, which is the same bug
+fixed for one spelling out of three.
+
+Two subtleties, each pinned by a test:
+
+- **Nesting.** `&amp;lt;` means the literal text `&lt;`, not `<`. One
+  left-to-right pass gets this right for free, because a global replace never
+  rescans its own output. An ordered-sed version needed `&amp;` decoded last for
+  the same effect, and that ordering was a latent trap.
+- **Fancy punctuation degrades to ASCII.** `&mdash;` becomes `-`, never an
+  em-dash. This repo bans em/en-dash and ellipsis in shipped text and gates it in
+  the scorecard, so decoding them faithfully would make this function INJECT what
+  another gate rejects. Applies to the numeric spellings too, or the named form
+  would be safe while `&#8212;` still injected.
+
+An unknown named entity is left alone, so a title legitimately containing `&foo;`
+survives.
+
+`output-quality-check.sh` gains a tracker-title backstop covering all three
+encodings: an entity reaching the stored state means the funnel was bypassed.
+
+The decoder is fed through a QUOTED HEREDOC rather than `node -e '...'`. Inside a
+single-quoted shell string every apostrophe in the JS terminates the string early -
+including, at one point, the apostrophe in the comment explaining the problem.
+shellcheck flags it (SC2140) and the first version worked only by accident of where
+the quotes fell.
+
+12 tests. 306 unit total.
+
 ## [12.10.0] - 2026-07-26
 
 Two pieces of abandoned residue, and a gate that had inverted.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "12.10.0",
+  "version": "12.11.0",
   "description": "8-phase AI development pipeline with full orchestration on Claude Code and Copilot CLI. Analysis, planning, TDD, CLI-aware parallel review with consensus surfacing + Fable triage, default-FAIL evidence gates, secret + intent guards, per-phase cost ledger, persistent learnings memory, wiki generation, commit automation. Token-preserving uninstall.",
   "type": "module",
   "main": "index.js",

package/pipeline/scripts/output-quality-check.sh

@@ -89,6 +89,40 @@ else
   warn "no .pr-body.md in task dir (skipped PR-body check)"
 fi
 
+# 2b. Tracker tile titles
+#
+# `rules.md` forbids HTML entities in "titles, commit messages, task subjects, or
+# body text", but this check only ever looked at the PR body and the Jira comment.
+# Tile titles are task subjects, and that is where the rule actually broke: a real
+# run rendered `Phase 1: Build & Launch` in the TaskList widget. The rule was
+# right and its enforcement was scoped to the wrong two surfaces.
+#
+# `phase-tracker.sh add` now decodes at the funnel, so this is the backstop that
+# says so: an entity reaching the stored state means the funnel was bypassed.
+TRACKER_STATE="$TASK_DIR/tracker-state.json"
+if [ -f "$TRACKER_STATE" ]; then
+  BAD_TITLES=$(python3 -c "
+import json, re, sys
+try:
+    d = json.load(open('$TRACKER_STATE'))
+except Exception:
+    sys.exit(0)
+# named, decimal and hex - a pattern covering only the named forms would miss
+# exactly the two spellings the first version of the decoder missed.
+pat = re.compile(r'&(amp|lt|gt|quot|apos|nbsp|mdash|ndash|hellip|#[0-9]+|#[xX][0-9a-fA-F]+);')
+for p in d.get('phases', []):
+    n = p.get('name', '')
+    if pat.search(n):
+        print('%s: %s' % (p.get('id'), n))
+" 2>/dev/null)
+  if [ -n "$BAD_TITLES" ]; then
+    bad "tracker tile title(s) carry HTML entities (they render literally):"
+    printf '%s\n' "$BAD_TITLES" | sed 's/^/      /'
+  else
+    ok "tracker tile titles free of HTML entities"
+  fi
+fi
+
 # 3. Jira comment
 JIRA_COMMENT="$TASK_DIR/.jira-comment.txt"
 if [ -f "$JIRA_COMMENT" ]; then

package/pipeline/scripts/phase-tracker.sh

@@ -115,6 +115,84 @@ need_jq() {
   }
 }
 
+# Decode HTML entities in a tile title.
+#
+# `rules.md` forbids entities in "titles, commit messages, task subjects, or body
+# text" because nothing downstream decodes them - they render literally. A tracker
+# tile title IS a task subject, and it rendered exactly that way:
+#
+#   Phase 1: Build & Launch
+#   Phase 3: Drive & Compare
+#
+# The rule existed and `output-quality-check.sh` enforced it, but only over the PR
+# body and the Jira comment, never over a tile title. The one surface where the
+# rule actually broke was the one surface nothing inspected.
+#
+# `add` is the single funnel for every tile title, so fixing it here fixes every
+# caller. Decode rather than reject: the intent behind `&` is unambiguous, and
+# a display path should render correctly now rather than abort a run over
+# punctuation. The stderr warning keeps the caller mistake visible instead of
+# silently papering over it.
+#
+# Handles all three encodings, because a title can arrive in any of them:
+#   named    &  <  "     —
+#   decimal  &  <  "      —
+#   hex      & < "     —
+# A first version handled only the named forms, so the numeric spellings still
+# rendered literally: the same bug fixed for one spelling out of three.
+#
+# ONE left-to-right pass, which also gets nesting right for free: a global replace
+# never rescans its own output, so `<` yields the literal text `<` rather
+# than `<`. An ordered-sed version needed `&amp;` decoded last for the same effect,
+# and that ordering was a latent trap.
+#
+# Fancy punctuation degrades to ASCII instead of decoding faithfully. `&mdash;`
+# becomes `-`, not an em-dash: this repo bans em/en-dash and ellipsis in shipped
+# text and gates it in the scorecard, so decoding them would make this function
+# INJECT what another gate rejects. Same for any numeric entity resolving to one.
+#
+# The program is fed through a QUOTED heredoc, not `node -e '...'`. Inside a
+# single-quoted shell string every apostrophe in the JS (and in its comments)
+# terminates the string early; shellcheck flags it as SC2140 and the first version
+# here worked only by accident of where the quotes happened to fall. A quoted
+# heredoc passes the body through verbatim, so the JS can use any quote it likes.
+decode_entities() {
+  local raw="$1" out
+  out=$(MA_RAW="$raw" node - <<'MA_DECODE_JS'
+const NAMED = {
+  amp: "&", lt: "<", gt: ">", quot: '"', apos: "'",
+  nbsp: " ",
+  // Deliberately ASCII: see the note above this function.
+  ndash: "-", mdash: "-", hellip: "...", laquo: "<<", raquo: ">>",
+};
+// Codepoints that must degrade to ASCII rather than decode faithfully.
+const ASCII_FOR = new Map([
+  [0x00a0, " "], [0x2013, "-"], [0x2014, "-"], [0x2026, "..."],
+  [0x2018, "'"], [0x2019, "'"], [0x201c, '"'], [0x201d, '"'],
+  [0x00a7, ""],
+]);
+const src = process.env.MA_RAW || "";
+process.stdout.write(
+  src.replace(/&(#[xX][0-9a-fA-F]+|#[0-9]+|[a-zA-Z][a-zA-Z0-9]*);/g, (m, body) => {
+    if (body[0] === "#") {
+      const hex = body[1] === "x" || body[1] === "X";
+      const cp = parseInt(hex ? body.slice(2) : body.slice(1), hex ? 16 : 10);
+      if (!Number.isFinite(cp) || cp < 0 || cp > 0x10ffff) return m;
+      if (ASCII_FOR.has(cp)) return ASCII_FOR.get(cp);
+      try { return String.fromCodePoint(cp); } catch { return m; }
+    }
+    const key = body.toLowerCase();
+    // An unknown named entity is left alone: guessing would corrupt a title that
+    // legitimately contains "&foo;".
+    return Object.prototype.hasOwnProperty.call(NAMED, key) ? NAMED[key] : m;
+  }),
+);
+MA_DECODE_JS
+) || out="$raw"
+  [ "$out" != "$raw" ] && echo "phase-tracker: decoded HTML entities in title (rules.md forbids them): '$raw' -> '$out'" >&2
+  printf '%s' "$out"
+}
+
 # OTel-compatible span emission  -  v6.1.0+, opt-in via $MULTI_AGENT_OTEL_SPANS.
 # Appends one JSON line to otel-spans.jsonl. Never fatal on failure.
 #
@@ -575,7 +653,7 @@ case "$ACTION" in
   add)
     need_jq
     [ "$#" -ge 2 ] || { echo "add needs <phase_id> <name>" >&2; exit 64; }
-    PID="$1"; PNAME="$2"
+    PID="$1"; PNAME="$(decode_entities "$2")"
     acquire_state_lock
     state=$(load_state)
     # Idempotent: a phase id that already exists is a no-op (name, status, and