@mmerterden/multi-agent-pipeline 12.9.0 → 12.11.0

package/CHANGELOG.md

@@ -16,6 +16,118 @@ 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.
+
+### `~/.multi-agent/` is pruned on install
+
+The "shared runtime" the Cursor / Antigravity / VS Code Copilot Chat adapters
+needed, so their emitted agents could reach the gate scripts by absolute path.
+Those adapters were deleted in v10.7.0 along with `installSharedRuntime`,
+`_base.mjs`, `rewriteScriptRefs` and `smoke-shared-runtime.sh` - but not the tree
+they had written. 222 files (174 scripts, 23 lib, 24 schemas) sat frozen at
+whatever the last adapter-era install produced.
+
+It is worse than dead weight because it is indistinguishable from a live install
+when you look at it: same directory names, same file names. Its
+`schemas/migrations/` is missing `prefs-2.3.0-to-2.4.0.mjs`, so reading it gives a
+migration chain three versions short and a reasonable conclusion that the chain
+itself is stale.
+
+`ABANDONED_TREES` now takes `root: "home"` entries for trees beside `~/.claude`
+rather than inside it, and 253 files (this plus the 31 in `~/.claude/eval`) are
+removed on the next install.
+
+### The live-prefs gate was rejecting the only correct state
+
+`smoke-schema-validation.sh` step 7 read:
+
+```bash
+if [ "$LVER" = "2.1.0" ]; then pass "live prefs already v2.1.0"
+elif ... else fail "live prefs has unknown schemaVersion: $LVER"
+```
+
+`migrate-prefs.mjs` `TARGET_VERSION` had since moved to 2.4.0, which inverted the
+gate: a prefs file left behind at 2.1.0 passed as "already current", and a file
+correctly migrated to 2.4.0 fell through to the else arm and FAILED as "unknown".
+The gate rejected the fully-migrated state it exists to encourage.
+
+It now reads the target from `migrate-prefs.mjs` and the accepted set from the
+schema's own `schemaVersion` enum, so it cannot disagree with either again, and a
+known-but-older version reports how far behind it is (`v2.1.0 -> v2.4.0`) instead
+of reading as current. This is a CONSUMER smoke (`/multi-agent:update` runs it), so
+it resolves both paths through `SMOKE_DIR`, which is `pipeline/scripts` in the repo
+and `~/.claude/scripts` in an install.
+
+### Dead-file sweep
+
+Swept refs, schemas, agents, libs and scripts for files nothing references. No
+orphans. The two candidates were both false positives from the sweep's own exclude
+flags: `design-check-config.schema.json` is referenced as the instance filename by
+the design-check command, and `count-lib.sh` is sourced by two siblings inside
+`pipeline/lib/`, which the sweep had excluded. Recorded here so the next sweep does
+not re-flag them.
+
 ## [12.9.0] - 2026-07-26
 
 Context engineering follow-through, and a guard that was blocking safe commands.

package/install/_common.mjs

@@ -252,25 +252,46 @@ export function pruneLegacyMultiAgentSkills(skillsDir) {
  * neither did uninstall - 31 stale files sat there with nothing left that could
  * ever read or remove them.
  *
- * @type {ReadonlyArray<{dir: string, reason: string}>}
+ * `~/.multi-agent/` is the larger case: the "shared runtime" the Cursor /
+ * Antigravity / VS Code Copilot Chat adapters needed, so their emitted agents
+ * could reach the gate scripts by absolute path. Those adapters were deleted in
+ * v10.7.0 along with `installSharedRuntime`, `_base.mjs`, `rewriteScriptRefs` and
+ * `smoke-shared-runtime.sh` - but not the tree they wrote. 221 files (174 scripts,
+ * 23 lib, 24 schemas) frozen at whatever the last adapter-era install produced,
+ * including a migrations directory missing `prefs-2.3.0-to-2.4.0.mjs`. Browsing it
+ * looks exactly like browsing a current install, which is how it comes to be
+ * mistaken for one.
+ *
+ * `root: "home"` entries sit beside `~/.claude`, not inside it.
+ *
+ * @type {ReadonlyArray<{dir: string, root?: "claude"|"home", reason: string}>}
  */
 export const ABANDONED_TREES = Object.freeze([
   {
     dir: "eval",
     reason: "eval corpora; the harnesses that read them are maintainer-only and no longer ship",
   },
+  {
+    dir: ".multi-agent",
+    root: "home",
+    reason:
+      "shared runtime for the Cursor / Antigravity / Copilot Chat adapters, all deleted in v10.7.0",
+  },
 ]);
 
 /**
- * Remove trees an older install left behind under `root`.
+ * Remove trees an older install left behind.
  *
- * @param {string} root e.g. `$HOME/.claude`
+ * @param {string} claudeDir e.g. `$HOME/.claude`
+ * @param {string} [home] `$HOME`, for entries marked `root: "home"`. Defaults to
+ *   the parent of `claudeDir`, which is the layout every installer uses.
  * @returns {number} directories removed
  */
-export function pruneAbandonedTrees(root) {
+export function pruneAbandonedTrees(claudeDir, home = dirname(claudeDir)) {
   let removed = 0;
-  for (const { dir, reason } of ABANDONED_TREES) {
-    const target = join(root, dir);
+  for (const { dir, root, reason } of ABANDONED_TREES) {
+    const base = root === "home" ? home : claudeDir;
+    const target = join(base, dir);
     if (!existsSync(target)) continue;
     if (dryRun) {
       console.log(`    [dry-run] would remove abandoned tree ${target} (${reason})`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "12.9.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

package/pipeline/scripts/smoke-schema-validation.sh

@@ -174,14 +174,40 @@ echo ""
 echo "→ 7. Live preferences (if exists)  -  post-migration check"
 if [ -f "$LIVE_PREFS" ]; then
   LVER=$(node -e "console.log(JSON.parse(require('fs').readFileSync('$LIVE_PREFS','utf8')).schemaVersion || 'none')" 2>/dev/null)
-  if [ "$LVER" = "2.1.0" ]; then
-    pass "live prefs already v2.1.0"
-  elif [ "$LVER" = "2.0.0" ] || [ "$LVER" = "none" ]; then
-    echo "  ⓘ live prefs still $LVER  -  migration pending (Aşama 1.6)"
-    # Not a fail; migration is its own step
-    pass "live prefs present, needs migration (schemaVersion: $LVER)"
+
+  # The target is read from migrate-prefs.mjs, never hardcoded here.
+  #
+  # This block used to say `if [ "$LVER" = "2.1.0" ]; then pass "already v2.1.0"`
+  # with everything else falling through to `fail "unknown schemaVersion"`. The
+  # migration target had since moved to 2.4.0, which inverted the gate: a prefs
+  # file left behind at 2.1.0 reported PASS as "already current", while a file
+  # correctly migrated to 2.4.0 hit the else arm and FAILED as "unknown". The
+  # gate was rejecting the only fully-migrated state it exists to encourage.
+  #
+  # Reading the target from the migrator, and the accepted set from the schema
+  # enum, means this can never disagree with them again.
+  MIGRATOR="$SMOKE_DIR/migrate-prefs.mjs"
+  TARGET=$(grep -oE 'TARGET_VERSION = "[0-9.]+"' "$MIGRATOR" 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+')
+  KNOWN=$(node -e "
+    const s = require('$PREFS_SCHEMA');
+    process.stdout.write((s.properties.schemaVersion.enum || []).join(' '));
+  " 2>/dev/null)
+
+  if [ -z "$TARGET" ]; then
+    fail "cannot read TARGET_VERSION from migrate-prefs.mjs - the check has no reference point"
+  elif [ "$LVER" = "$TARGET" ]; then
+    pass "live prefs at the migration target (v$TARGET)"
+  elif [ "$LVER" = "none" ]; then
+    echo "  ⓘ live prefs carries no schemaVersion  -  migration pending"
+    pass "live prefs present, needs migration (schemaVersion: none)"
+  elif printf '%s\n' $KNOWN | grep -qxF "$LVER"; then
+    # A known-but-older version is legitimately "migration pending", not a
+    # failure: migration is its own install step. Say how far behind it is, so a
+    # file sitting three versions back is visible instead of reading as current.
+    echo "  ⓘ live prefs at v$LVER, target v$TARGET  -  migration pending"
+    pass "live prefs present, needs migration (v$LVER -> v$TARGET)"
   else
-    fail "live prefs has unknown schemaVersion: $LVER"
+    fail "live prefs has a schemaVersion the schema does not know: $LVER (known: $KNOWN)"
   fi
 else
   echo "  ⓘ no live prefs at $LIVE_PREFS  -  ok for fresh install"