@mmerterden/multi-agent-pipeline 11.4.0 → 11.5.0

package/pipeline/scripts/smoke-plugin-validate.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+#
+# smoke-plugin-validate.sh  -  run `claude plugin validate --strict` against
+# every plugin / marketplace surface committed to this repo.
+#
+# Discovery: any directory containing `.claude-plugin/plugin.json` or
+# `.claude-plugin/marketplace.json` (node_modules excluded). The `claude`
+# CLI validates the containing directory; --strict promotes warnings
+# (unrecognized fields, missing metadata) to failures so CI catches drift
+# the runtime would silently tolerate.
+#
+# Skip semantics (exit 0 with a SKIP line):
+#   - `claude` binary not on PATH (optional tooling; billing-friendly CI
+#     runners don't install it)
+#   - no validatable surface in the repo (the marketplace plugins live in
+#     the separate multi-agent-plugins repo; this repo may carry none)
+#
+# Exit codes: 0=pass or skip, 1=validation failure
+
+set -uo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+
+if ! command -v claude >/dev/null 2>&1; then
+  echo "SKIP smoke-plugin-validate: claude binary not on PATH"
+  exit 0
+fi
+
+# Each hit is a manifest; the validatable surface is its .claude-plugin parent's parent.
+MANIFESTS=$(find "$REPO_ROOT" \
+  -path "$REPO_ROOT/node_modules" -prune -o \
+  -path "$REPO_ROOT/coverage" -prune -o \
+  -type f -path '*/.claude-plugin/*' \( -name plugin.json -o -name marketplace.json \) -print \
+  2>/dev/null | sort)
+
+if [ -z "$MANIFESTS" ]; then
+  echo "SKIP smoke-plugin-validate: no .claude-plugin plugin/marketplace manifest in this repo"
+  exit 0
+fi
+
+PASS=0
+FAIL=0
+pass() { PASS=$((PASS + 1)); echo "  ✓ $1"; }
+fail() { FAIL=$((FAIL + 1)); echo "  ✗ $1"; }
+
+# Validate each surface directory once, even if it carries both manifests.
+SURFACES=$(echo "$MANIFESTS" | sed 's|/\.claude-plugin/[^/]*$||' | sort -u)
+
+for surface in $SURFACES; do
+  rel="${surface#"$REPO_ROOT"/}"
+  [ "$surface" = "$REPO_ROOT" ] && rel="."
+  echo ""
+  echo "→ claude plugin validate --strict $rel"
+  if OUT=$(claude plugin validate --strict "$surface" 2>&1); then
+    pass "$rel validates clean (strict)"
+  else
+    fail "$rel failed strict validation"
+    echo "$OUT" | sed 's/^/    /'
+  fi
+done
+
+echo ""
+echo "══ smoke-plugin-validate: $PASS passed, $FAIL failed ══"
+[ "$FAIL" -gt 0 ] && exit 1 || exit 0

package/pipeline/scripts/smoke-shadow-git.sh

@@ -98,8 +98,22 @@ else
   record_fail "node_modules leaked into shadow tracking"
 fi
 
-# Make a real edit + snapshot
+# 7b. Forced excludes apply even when NOT in the project .gitignore
+# (DerivedData is not in this fixture's .gitignore; it must be excluded via
+# the shadow repo's .git/info/exclude).
+mkdir -p DerivedData && echo "buildjunk" > DerivedData/junk.txt
+bash "$SG" snapshot "$TASK_ID" "$TMP" "derived-data-probe" >/dev/null 2>&1
+if ! git --git-dir="$HOME/.claude/state/shadow-git/$TASK_ID/.git" --work-tree="$TMP" \
+     ls-files 2>/dev/null | grep -q "^DerivedData/"; then
+  record_pass "DerivedData NOT tracked (forced exclude in .git/info/exclude)"
+else
+  record_fail "DerivedData leaked into shadow tracking (forced excludes dead)"
+fi
+rm -rf DerivedData
+
+# Make a real edit + a brand-new file + snapshot
 echo "hello-changed" > a.txt
+echo "post-baseline" > b.txt
 sha_edit=$(bash "$SG" snapshot "$TASK_ID" "$TMP" "edited a.txt" 2>/dev/null | head -1)
 if [ -n "$sha_edit" ] && [ "${#sha_edit}" -ge 7 ]; then
   record_pass "snapshot after edit produced a sha: $sha_edit"
@@ -115,6 +129,7 @@ else
 fi
 
 # 8. Restore the baseline
+echo "never-snapshotted" > c.txt   # created after the last snapshot
 baseline_sha=$(bash "$SG" list "$TASK_ID" 2>/dev/null | tail -1 | awk '{print $1}')
 bash "$SG" restore "$TASK_ID" "$TMP" "$baseline_sha" --files >/dev/null 2>&1
 if [ "$(cat "$TMP/a.txt")" = "hello" ]; then
@@ -123,6 +138,23 @@ else
   record_fail "restore did not revert a.txt (got '$(cat "$TMP/a.txt")')"
 fi
 
+# 8b. Restore removes files that did not exist in the snapshot
+if [ ! -f "$TMP/b.txt" ]; then
+  record_pass "restore removed b.txt (committed after baseline)"
+else
+  record_fail "restore left b.txt in place (created after snapshot must be removed)"
+fi
+if [ ! -f "$TMP/c.txt" ]; then
+  record_pass "restore removed c.txt (never snapshotted)"
+else
+  record_fail "restore left c.txt in place (untracked new file must be removed)"
+fi
+if [ -f "$TMP/node_modules/x.txt" ]; then
+  record_pass "restore left ignored node_modules untouched"
+else
+  record_fail "restore deleted ignored files (node_modules must survive clean)"
+fi
+
 # 9. Prune
 bash "$SG" prune "$TASK_ID" >/dev/null 2>&1
 if [ ! -d "$HOME/.claude/state/shadow-git/$TASK_ID" ]; then
@@ -131,6 +163,21 @@ else
   record_fail "prune did not remove the shadow dir"
 fi
 
+# 9b. Task-id validation: traversal and separator ids are rejected before any
+# rm -rf (a "prune .." must never delete ~/.claude/state).
+for bad_id in ".." "." "a/b" "-x!"; do
+  if bash "$SG" prune "$bad_id" >/dev/null 2>&1; then
+    record_fail "prune accepted unsafe task id '$bad_id'"
+  else
+    record_pass "prune rejects unsafe task id '$bad_id'"
+  fi
+done
+if [ -d "$HOME/.claude/state" ]; then
+  record_pass "~/.claude/state survived unsafe prune attempts"
+else
+  record_fail "~/.claude/state is GONE after unsafe prune attempts"
+fi
+
 cd - >/dev/null
 rm -rf "$TMP"
 

package/pipeline/scripts/smoke-skill-authoring.sh

@@ -51,7 +51,7 @@ TARGETS=(
 
 # Collect the list once.
 SKILLS=$(find "${TARGETS[@]}" -name 'SKILL.md' -type f 2>/dev/null | sort)
-SKILL_COUNT=$(echo "$SKILLS" | grep -c . || echo 0)
+SKILL_COUNT=$(echo "$SKILLS" | grep -c . || true)
 
 echo "→ Scope: $SKILL_COUNT authored SKILL.md files under shared/core/"
 echo "  (external/ intentionally excluded  -  upstream conventions)"

package/pipeline/scripts/smoke-workflow-audit.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+#
+# smoke-workflow-audit.sh  -  security + correctness audit of
+# `.github/workflows/` with the two dedicated external linters:
+#
+#   - zizmor      GitHub Actions security auditor (template injection,
+#                 credential persistence, unpinned actions, ...). Runs in
+#                 offline mode so the smoke never touches the network.
+#   - actionlint  workflow correctness linter (expression syntax, matrix
+#                 typos, shellcheck of run: blocks, ...).
+#
+# Both tools are optional: each is skipped with a SKIP line when its binary
+# is not on PATH (billing-friendly CI runners install neither; run locally
+# via `brew install zizmor actionlint` for full coverage). Structural
+# baseline checks that need no external binary live in
+# smoke-ci-workflows.sh - this smoke is the deeper, tool-backed layer.
+#
+# Any finding from either tool fails the smoke.
+#
+# Exit codes: 0=pass or all tools skipped, 1=findings, 2=workflows missing
+
+set -uo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+WF_DIR="$REPO_ROOT/.github/workflows"
+
+[ -d "$WF_DIR" ] || { echo "FAIL: .github/workflows/ missing"; exit 2; }
+
+PASS=0
+FAIL=0
+SKIPPED=0
+pass() { PASS=$((PASS + 1)); echo "  ✓ $1"; }
+fail() { FAIL=$((FAIL + 1)); echo "  ✗ $1"; }
+skip() { SKIPPED=$((SKIPPED + 1)); echo "  ↷ SKIP: $1"; }
+
+# ──────────────────────────────────────────────────────────────────────────
+echo "→ 1. zizmor (security audit, offline)"
+if command -v zizmor >/dev/null 2>&1; then
+  # Flag names shifted across zizmor releases (--offline vs --no-online-audits);
+  # probe --help so the smoke works with whichever is installed.
+  HELP=$(zizmor --help 2>&1 || true)
+  OFFLINE_FLAG="--offline"
+  echo "$HELP" | grep -q -- '--offline' || OFFLINE_FLAG="--no-online-audits"
+  if OUT=$(zizmor "$WF_DIR" --min-severity medium "$OFFLINE_FLAG" 2>&1); then
+    pass "zizmor: no findings at medium+ severity"
+  else
+    fail "zizmor reported findings (medium+ severity)"
+    echo "$OUT" | sed 's/^/    /'
+  fi
+else
+  skip "zizmor not on PATH (brew install zizmor)"
+fi
+
+# ──────────────────────────────────────────────────────────────────────────
+echo "→ 2. actionlint (workflow correctness)"
+if command -v actionlint >/dev/null 2>&1; then
+  if OUT=$(cd "$REPO_ROOT" && actionlint 2>&1); then
+    pass "actionlint: no findings"
+  else
+    fail "actionlint reported findings"
+    echo "$OUT" | sed 's/^/    /'
+  fi
+else
+  skip "actionlint not on PATH (brew install actionlint)"
+fi
+
+echo ""
+echo "══ smoke-workflow-audit: $PASS passed, $FAIL failed, $SKIPPED skipped ══"
+[ "$FAIL" -gt 0 ] && exit 1 || exit 0

package/pipeline/scripts/test-gap-scan.mjs

@@ -114,7 +114,18 @@ function isExcluded(path) {
     if (pat.endsWith("/")) {
       if (path.includes(pat) || path.startsWith(pat)) return true;
     } else if (pat.includes("**")) {
-      const re = new RegExp("^" + pat.replace(/\./g, "\\.").replace(/\*\*/g, ".*").replace(/\*/g, "[^/]*") + "$");
+      // Tokenize ** before the single-* pass so the * rewrite cannot mangle
+      // the already-translated .* (which broke cross-directory matches).
+      const DOUBLE_STAR = "\u0000";
+      const re = new RegExp(
+        "^" +
+          pat
+            .replace(/\./g, "\\.")
+            .replace(/\*\*/g, DOUBLE_STAR)
+            .replace(/\*/g, "[^/]*")
+            .replace(new RegExp(DOUBLE_STAR, "g"), ".*") +
+          "$",
+      );
       if (re.test(path)) return true;
     } else if (path.endsWith(pat)) return true;
   }

package/pipeline/scripts/triage-memory.mjs

@@ -110,7 +110,16 @@ function score(queryTokens, row) {
 }
 
 function globToRegExp(glob) {
-  const escaped = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, ".*").replace(/\*/g, "[^/]*").replace(/\?/g, ".");
+  // Tokenize ** before the single-* pass: a sequential replace would turn
+  // ** into .* and then the global * pass would rewrite it to .[^/]*,
+  // breaking cross-directory matches (src/**/x vs src/a/b/x).
+  const DOUBLE_STAR = "\u0000";
+  const escaped = glob
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    .replace(/\*\*/g, DOUBLE_STAR)
+    .replace(/\*/g, "[^/]*")
+    .replace(/\?/g, ".")
+    .replace(new RegExp(DOUBLE_STAR, "g"), ".*");
   return new RegExp("^" + escaped + "$", "i");
 }
 

package/pipeline/scripts/uninstall.mjs

@@ -32,10 +32,38 @@
 
 import { existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from "fs";
 import { join } from "path";
+import { pathToFileURL } from "url";
 import { createInterface } from "readline";
 
 const HOME = process.env.HOME || process.env.USERPROFILE;
 
+/**
+ * Agent definition files the pipeline ships (pipeline/agents/). This runs
+ * standalone from ~/.claude/scripts, so the list is static here; a unit test
+ * (test/uninstall.test.mjs) asserts it matches the source tree so it cannot
+ * go stale. Only these file names are removed from the installed agents
+ * dirs - user-authored agent files are never touched.
+ */
+export const PIPELINE_AGENT_FILES = [
+  "android-architect.md",
+  "backend-architect.md",
+  "code-reviewer.md",
+  "dev-critic.md",
+  "explorer.md",
+  "ios-architect.md",
+  "security-auditor.md",
+  "task-clarifier.md",
+];
+
+/**
+ * Non-multi-agent core skills the installer ships from
+ * pipeline/skills/shared/core/ (the multi-agent* dirs are matched by prefix).
+ */
+export const PIPELINE_CORE_SKILL_DIRS = [
+  "apple-archive-compliance",
+  "google-play-compliance",
+];
+
 const flags = process.argv.slice(2).filter((a) => a !== "uninstall");
 
 const TOOL_FLAGS = [
@@ -122,6 +150,33 @@ function rmMatchingFiles(parent, predicate) {
   return count;
 }
 
+// Explicit terminator install/copilot.mjs writes after the pipeline section
+// (v11.4.1+). Must stay in sync with INSTRUCTIONS_END_MARKER there.
+const COPILOT_END_MARKER = "<!-- multi-agent-pipeline:copilot-instructions:end -->";
+
+/**
+ * Legacy copilot-instructions files (written before the end marker existed)
+ * have no explicit terminator. Bound the pipeline span at the next top-level
+ * "# " heading after the start marker when one exists OUTSIDE fenced code
+ * blocks (the pipeline body carries bash comments like "# Bootstrap once ..."
+ * inside fences); otherwise the span runs to EOF (pre-marker behavior).
+ * Mirrors install/copilot.mjs legacyTrailingContent.
+ * @param {string} section - content from the start marker onward
+ * @returns {string} user content trailing the pipeline span ("" if none)
+ */
+function legacyTrailingContent(section) {
+  const lines = section.split("\n");
+  let inFence = false;
+  for (let i = 1; i < lines.length; i++) {
+    if (/^\s*(```|~~~)/.test(lines[i])) {
+      inFence = !inFence;
+      continue;
+    }
+    if (!inFence && /^# /.test(lines[i])) return lines.slice(i).join("\n");
+  }
+  return "";
+}
+
 /**
  * Strip a marker-wrapped `<!-- multi-agent-pipeline:begin/end -->` block from
  * a user-owned file. Preserves everything outside the markers. Deletes the
@@ -135,25 +190,33 @@ function stripManagedBlock(filePath) {
     /\s*<!-- multi-agent-pipeline:begin -->[\s\S]*?<!-- multi-agent-pipeline:end -->\s*/m;
   if (!re.test(content)) {
     // Copilot's install (install/copilot.mjs) does not wrap the block in
-    // begin/end markers; it always writes the pipeline section LAST, from the
-    // `# Multi-Agent Development Pipeline` heading to EOF, keeping any user
-    // content ABOVE it. So slicing from that heading to EOF reliably removes
-    // only our section regardless of file size (no arbitrary size cap - a cap
-    // used to orphan the block in files >50 KB).
+    // begin/end markers. v11.4.1+ writes an explicit end marker after the
+    // pipeline section; strip only the start..end span so user content BELOW
+    // the section survives. Legacy files without the end marker are bounded
+    // at the next top-level heading outside code fences, else EOF.
     if (content.includes("# Multi-Agent Development Pipeline")) {
-      // Heuristic: Copilot's generateCopilotInstructions output. Only strip the
-      // pipeline section, not the whole file.
       const marker = "# Multi-Agent Development Pipeline";
       const idx = content.indexOf(marker);
       if (idx >= 0) {
         const before = content.slice(0, idx).trimEnd();
+        const fromStart = content.slice(idx);
+        const endIdx = fromStart.indexOf(COPILOT_END_MARKER);
+        const rawTrailing =
+          endIdx >= 0
+            ? fromStart.slice(endIdx + COPILOT_END_MARKER.length)
+            : legacyTrailingContent(fromStart);
+        const trailing = rawTrailing.replace(/^[\r\n]+/, "").trimEnd();
+        let remaining = before;
+        if (trailing.length > 0) {
+          remaining = before.length > 0 ? before + "\n\n" + trailing : trailing;
+        }
         if (dryRun) {
           report("would update", filePath);
-        } else if (before.length === 0) {
+        } else if (remaining.length === 0) {
           rmSync(filePath, { force: true });
           console.log(`    removed (was pipeline-only): ${filePath}`);
         } else {
-          writeFileSync(filePath, before + "\n");
+          writeFileSync(filePath, remaining + "\n");
           console.log(`    cleaned pipeline section: ${filePath}`);
         }
         return true;
@@ -200,9 +263,12 @@ function cleanClaudeSettings(settingsPath) {
 
   if (settings.hooks?.PreToolUse?.length) {
     const before = settings.hooks.PreToolUse.length;
+    // Match both the current matcher ("Bash") and the dead pre-v11.4.1 one
+    // ("Bash(git commit:*)"); the pre-commit-check.sh command identifies the
+    // entry as ours either way.
     settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(
       (h) =>
-        !(h.matcher === "Bash(git commit:*)" &&
+        !((h.matcher === "Bash" || h.matcher === "Bash(git commit:*)") &&
           h.hooks?.some((sub) => sub.command?.includes("pre-commit-check.sh"))),
     );
     if (settings.hooks.PreToolUse.length < before) touched = true;
@@ -239,8 +305,8 @@ async function main() {
   if (dryRun) console.log("  [DRY-RUN] Nothing will be modified.");
   console.log("");
   console.log("  Targets:");
-  if (forClaude) console.log("    - Claude Code (~/.claude/{commands,skills,agents,rules,scripts}/multi-agent*)");
-  if (forCopilot) console.log("    - Copilot CLI (~/.copilot/{skills,agents,scripts}/multi-agent* + copilot-instructions.md section)");
+  if (forClaude) console.log("    - Claude Code (~/.claude/{commands/multi-agent, scripts, multi-agent-refs, schemas, lib} + pipeline skills + pipeline agent files)");
+  if (forCopilot) console.log("    - Copilot CLI (~/.copilot/{scripts, schemas, lib} + pipeline skills + pipeline agent files + copilot-instructions.md section)");
   if (forCursor) console.log(`    - Cursor (${adapterTarget}/.cursor/rules/multi-agent-* + .cursorrules)`);
   if (forCopilotChat) console.log(`    - GitHub Copilot Chat (${adapterTarget}/.github/copilot-instructions.md block + .github/instructions/multi-agent-*)`);
   if (forAntigravity) console.log(`    - Antigravity (${adapterTarget}/.agent/rules + .agent/workflows + AGENTS.md block + .agent/mcp_config.json)`);
@@ -265,6 +331,10 @@ async function main() {
     const CLAUDE = join(HOME, ".claude");
     rmIfExists(join(CLAUDE, "commands", "multi-agent"));
     rmIfExists(join(CLAUDE, "scripts"));
+    // Pipeline-managed trees the installer lays down alongside scripts/.
+    rmIfExists(join(CLAUDE, "multi-agent-refs"));
+    rmIfExists(join(CLAUDE, "schemas"));
+    rmIfExists(join(CLAUDE, "lib"));
     // NOTE: ~/.claude/rules/ is USER-OWNED. install lays baseline rules down
     // write-if-missing and NEVER overwrites them (install/claude.mjs
     // installRules, skipExisting) so users can evolve their global rules
@@ -274,20 +344,14 @@ async function main() {
     const skills = join(CLAUDE, "skills");
     let n = rmMatchingDirs(skills, (name) => name === "multi-agent" || name.startsWith("multi-agent-"));
     n += rmMatchingDirs(skills, (name) => name === "figma-ios" || name === "figma-android" || name === "figma-common" || name === "figma-to-component");
+    n += rmMatchingDirs(skills, (name) => PIPELINE_CORE_SKILL_DIRS.includes(name));
     if (n > 0) console.log(`    removed ${n} skill dir(s) under ${skills}`);
     rmIfExists(join(skills, ".skills-index.json"));
     rmIfExists(join(skills, "skills-index.md"));
     rmIfExists(join(skills, "README.md"));
-    rmMatchingDirs(join(CLAUDE, "agents"), (name) =>
-      [
-        "code-reviewer.md",
-        "explorer.md",
-        "ios-architect.md",
-        "android-architect.md",
-        "backend-architect.md",
-        "security-auditor.md",
-      ].includes(name),
-    );
+    // Agent definitions are FILES; remove only the pipeline-shipped names so
+    // user-authored agents survive.
+    rmMatchingFiles(join(CLAUDE, "agents"), (name) => PIPELINE_AGENT_FILES.includes(name));
     cleanClaudeSettings(join(CLAUDE, "settings.json"));
   }
 
@@ -296,21 +360,20 @@ async function main() {
     console.log("  [Copilot CLI] Removing...");
     const COP = join(HOME, ".copilot");
     rmIfExists(join(COP, "scripts"));
+    // Pipeline-managed trees the installer lays down alongside scripts/.
+    rmIfExists(join(COP, "schemas"));
+    rmIfExists(join(COP, "lib"));
     const skills = join(COP, "skills");
     let n = rmMatchingDirs(skills, (name) => name === "multi-agent" || name.startsWith("multi-agent-"));
     n += rmMatchingDirs(skills, (name) => name === "figma-ios" || name === "figma-android" || name === "figma-common" || name === "figma-to-component");
+    n += rmMatchingDirs(skills, (name) => PIPELINE_CORE_SKILL_DIRS.includes(name));
     if (n > 0) console.log(`    removed ${n} skill dir(s) under ${skills}`);
+    rmIfExists(join(skills, ".skills-index.json"));
+    rmIfExists(join(skills, "skills-index.md"));
     rmIfExists(join(skills, "README.md"));
-    rmMatchingDirs(join(COP, "agents"), (name) =>
-      [
-        "code-reviewer.md",
-        "explorer.md",
-        "ios-architect.md",
-        "android-architect.md",
-        "backend-architect.md",
-        "security-auditor.md",
-      ].includes(name),
-    );
+    // Agent definitions are FILES; remove only the pipeline-shipped names so
+    // user-authored agents survive.
+    rmMatchingFiles(join(COP, "agents"), (name) => PIPELINE_AGENT_FILES.includes(name));
     stripManagedBlock(join(COP, "copilot-instructions.md"));
   }
 
@@ -370,7 +433,13 @@ async function main() {
   console.log("");
 }
 
-main().catch((e) => {
-  console.error("uninstall failed:", e.message);
-  process.exit(1);
-});
+// Run only when executed directly (node uninstall.mjs). Guard lets tests
+// import the exported constants without triggering the uninstall.
+const isMainModule =
+  process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isMainModule) {
+  main().catch((e) => {
+    console.error("uninstall failed:", e.message);
+    process.exit(1);
+  });
+}

package/pipeline/scripts/update-issue-progress.sh

@@ -29,12 +29,63 @@
 
 set -euo pipefail
 
+# Rewrite the `### Progress` block of the body file ($2) with $1 and print the
+# result to stdout. The replaced region is bounded at the FIRST of:
+#   - a line starting with `<!--` (the legend comment, printed and kept), or
+#   - the next heading line (^#, printed and kept), or
+#   - EOF.
+# Bounding at the next heading matters: bodies without the legend comment used
+# to have everything from the table to EOF silently dropped and persisted.
+rewrite_progress_body() {
+  # Block passed via environment: BSD awk rejects literal newlines in -v
+  # assignments ("newline in string"), so -v cannot carry the table.
+  NEW_BLOCK_ENV="$1" awk '
+    BEGIN { new_block = ENVIRON["NEW_BLOCK_ENV"] }
+    BEGIN { in_progress = 0 }
+    /^### Progress/ {
+      print
+      print ""
+      print new_block
+      print ""
+      in_progress = 1
+      next
+    }
+    in_progress && /^<!--/ { in_progress = 0; print; next }
+    in_progress && /^#/    { in_progress = 0; print; next }
+    in_progress { next }
+    { print }
+  ' "$2"
+}
+
+build_progress_block() {
+  cat <<EOF
+| Flag | State |
+|---|---|
+| Implementation | ${1} |
+| Testing        | ${2} |
+| Code Connect   | ${3} |
+| Wiki           | ${4} |
+EOF
+}
+
 TASK_ID="${1:-}"
 if [ -z "$TASK_ID" ]; then
   echo "usage: update-issue-progress.sh <task-id>" >&2
   exit 64
 fi
 
+# Internal test seam: `--rewrite <body-file>` runs only the Progress-block
+# rewrite (placeholder glyphs) and prints the result. No state, no gh.
+if [ "$TASK_ID" = "--rewrite" ]; then
+  BODY_IN="${2:-}"
+  if [ -z "$BODY_IN" ] || [ ! -f "$BODY_IN" ]; then
+    echo "usage: update-issue-progress.sh --rewrite <body-file>" >&2
+    exit 64
+  fi
+  rewrite_progress_body "$(build_progress_block "⚪" "⚪" "⚪" "⚪")" "$BODY_IN"
+  exit 0
+fi
+
 # Resolve the project state directory (matches phase-tracker convention).
 STATE_GLOB="$HOME/.claude/projects/*"
 AGENT_STATE=""
@@ -75,9 +126,9 @@ F_WIKI=$(jq -r '.flags.wiki          // false' "$AGENT_STATE")
 # Each flag may be: true | false | "yellow" (validated against older impl).
 glyph_for() {
   case "$1" in
-    true|"true")    echo "🟢" ;;
-    yellow|"yellow") echo "🟡" ;;
-    *)              echo "⚪" ;;
+    true)   echo "🟢" ;;
+    yellow) echo "🟡" ;;
+    *)      echo "⚪" ;;
   esac
 }
 
@@ -87,49 +138,17 @@ G_CC=$(glyph_for "$F_CC")
 G_WIKI=$(glyph_for "$F_WIKI")
 
 # Fetch current body, replace the Progress table, write back.
-TMP_BODY=$(mktemp /tmp/issue-progress-${TASK_ID}-XXXXXX.md)
+TMP_BODY=$(mktemp /tmp/issue-progress-"${TASK_ID}"-XXXXXX.md)
 trap 'rm -f "$TMP_BODY"' EXIT
 
 gh issue view "$ISSUE_NUM" --repo "$ORG_REPO" --json body --jq .body > "$TMP_BODY"
 
 # Build the new Progress block.
-NEW_BLOCK=$(cat <<EOF
-| Flag | State |
-|---|---|
-| Implementation | ${G_IMPL} |
-| Testing        | ${G_TEST} |
-| Code Connect   | ${G_CC} |
-| Wiki           | ${G_WIKI} |
-EOF
-)
-
-# Replace the table between `### Progress` and the next `<!--` HTML comment.
-# Use awk to keep the legend comment in place.
-awk -v new_block="$NEW_BLOCK" '
-  BEGIN { in_progress = 0; replaced = 0 }
-  /^### Progress/ {
-    print
-    print ""
-    print new_block
-    print ""
-    in_progress = 1
-    replaced = 1
-    next
-  }
-  in_progress && /^<!--/ {
-    in_progress = 0
-    print
-    next
-  }
-  in_progress { next }
-  { print }
-  END {
-    if (replaced == 0) {
-      # Body had no Progress section; nothing to replace.
-      exit 0
-    }
-  }
-' "$TMP_BODY" > "${TMP_BODY}.new"
+NEW_BLOCK=$(build_progress_block "$G_IMPL" "$G_TEST" "$G_CC" "$G_WIKI")
+
+# Replace the table between `### Progress` and the first terminator (legend
+# comment, next heading, or EOF)  -  see rewrite_progress_body above.
+rewrite_progress_body "$NEW_BLOCK" "$TMP_BODY" > "${TMP_BODY}.new"
 
 # Check if body actually changed (idempotent no-op).
 if cmp -s "$TMP_BODY" "${TMP_BODY}.new"; then