@mmerterden/multi-agent-pipeline 17.6.0 → 19.0.0

package/pipeline/scripts/token-budget-report.mjs

@@ -21,6 +21,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { rowPhase } from "../lib/phase-schema.mjs";
 
 const args = parseArgs(process.argv.slice(2));
 const METRICS =
@@ -64,7 +65,12 @@ for (const e of events) {
       models: new Set(),
     });
   const t = byTask.get(e.task_id);
-  t.phases.add(e.phase);
+  // Normalised to the current vocabulary before it goes in the set. This log
+  // is append-only across the v19.0.0 renumbering, so the raw field carries
+  // two different meanings and a set of raw values cannot be compared to
+  // anything.
+  const cp = rowPhase(e);
+  if (cp !== null) t.phases.add(cp);
   const d = e.details || {};
   if (typeof d.tokens_in === "number") t.tokens_in += d.tokens_in;
   if (typeof d.tokens_out === "number") t.tokens_out += d.tokens_out;
@@ -113,7 +119,12 @@ for (const [taskId, t] of byTask) {
   summary.totalTokensOut += t.tokens_out;
   summary.totalUsd += usd;
   const total = t.tokens_in + t.tokens_out;
-  const isMulti = t.phases.has("4") && t.premium_calls > 5; // heuristic
+  // Heuristic: a task that reached Review with many premium calls is a
+  // multi-repo run. Keyed on Review (3), not on the literal "4" this line used
+  // to carry - under the six-phase contract 4 is Commit, and every run reaches
+  // Commit, so the old literal would have classified nearly everything as
+  // multi-repo and applied the wrong ceiling.
+  const isMulti = t.phases.has(3) && t.premium_calls > 5;
   const tokenLimit = isMulti ? limits.perTaskTokensMultiRepo : limits.perTaskTokens;
   const usdLimit = isMulti ? limits.perTaskUsdMultiRepo : limits.perTaskUsd;
   if (total > tokenLimit)

package/pipeline/scripts/triage-memory.mjs

@@ -3,8 +3,8 @@
 /**
  * @file triage-memory.mjs  -  v8.3.0
  *
- * Lightweight, zero-dep persistence layer for past Phase 4 triage findings.
- * Used by Phase 7 to ingest results, by Phase 1/4 to look up prior art when
+ * Lightweight, zero-dep persistence layer for past Phase 3 triage findings.
+ * Used by Phase 5 to ingest results, by Phase 1/4 to look up prior art when
  * a new task overlaps with a previous one, and by /multi-agent:search.
  *
  * Storage: append-only JSONL, one file per repo:

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

@@ -29,6 +29,54 @@
 
 set -euo pipefail
 
+# jq is not optional on this path. Without the guard below a missing binary
+# renders as EMPTY DATA and the work continues on it; see lib/require-jq.sh.
+for _rq in "$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)/require-jq.sh" \
+           "$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/../lib" 2>/dev/null && pwd)/require-jq.sh" \
+           "$HOME/.claude/lib/require-jq.sh" \
+           "$HOME/.copilot/lib/require-jq.sh" \
+           "$HOME/.codex/lib/require-jq.sh"; do
+  [ -f "$_rq" ] || continue
+  # shellcheck source=/dev/null
+  . "$_rq" && break
+done
+unset _rq
+if ! command -v ma_require_jq >/dev/null 2>&1; then
+  # The helper itself is missing, which is an install problem, not a jq one.
+  ma_require_jq() { command -v jq >/dev/null 2>&1 || { echo "jq not found - cannot ${1:-continue}." >&2; return 1; }; }
+fi
+ma_require_jq "update the issue" || exit 3
+
+# Outbound leak gate. Every byte below is composed at runtime out of command
+# output, error text and file excerpts, any of which can carry a token that was
+# on this machine a second earlier - and once it is in a comment it is in
+# someone else's database. The repo's own leak scanner looks at FILES IN THE
+# REPO and never sees this text. See lib/outbound-gate.mjs.
+ma_outbound_gate() {
+  local body_file="$1" og=""
+  for c in "$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)/outbound-gate.mjs" \
+           "$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/../lib" 2>/dev/null && pwd)/outbound-gate.mjs" \
+           "$HOME/.claude/lib/outbound-gate.mjs" \
+           "$HOME/.copilot/lib/outbound-gate.mjs" \
+           "$HOME/.codex/lib/outbound-gate.mjs"; do
+    [ -f "$c" ] && { og="$c"; break; }
+  done
+  # Missing gate is NOT an open door: refusing to publish beats publishing
+  # unchecked, and the only way this file is absent is a broken install.
+  if [ -z "$og" ]; then
+    echo "outbound-gate.mjs not found - refusing to publish unchecked text." >&2
+    return 7
+  fi
+  node "$og" --file "$body_file"
+}
+
+# Run-state path resolution: pipeline/lib/run-paths.sh owns the two layouts
+# (nested <root>/<project>/<id>/ and flat <root>/<id>/) and every id spelling.
+_MA_RP_HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+. "$_MA_RP_HERE/../lib/run-paths.sh" 2>/dev/null || . "$HOME/.claude/lib/run-paths.sh"
+
+
 # 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
@@ -90,13 +138,10 @@ fi
 # per-project directory ($HOME/.claude/logs/multi-agent/{project}/{taskId}/)
 # - not the ~/.claude/projects/*/state/ path this used to glob, which no
 # writer in the pipeline ever populates.
-AGENT_STATE=""
-for candidate in "$HOME"/.claude/logs/multi-agent/*/"$TASK_ID"/agent-state.json; do
-  if [ -f "$candidate" ]; then
-    AGENT_STATE="$candidate"
-    break
-  fi
-done
+# This globbed ONLY the nested layout. phase-tracker.sh and most Phase 0 paths
+# write flat, so on a real machine the majority of runs resolved to nothing and
+# this script reported "no agent-state.json" for a run whose state existed.
+AGENT_STATE="$(ma_resolve_run_file "$TASK_ID" agent-state.json 2>/dev/null || true)"
 
 if [ -z "$AGENT_STATE" ]; then
   echo "update-issue-progress: no agent-state.json found for task=$TASK_ID" >&2
@@ -154,6 +199,10 @@ if cmp -s "$TMP_BODY" "$TMP_NEW"; then
 fi
 
 # Apply.
+if ! ma_outbound_gate "$TMP_NEW"; then
+  echo "update-issue-progress: outbound gate refused the new body; #$ISSUE_NUM left unchanged" >&2
+  exit 7
+fi
 if ! gh issue edit "$ISSUE_NUM" --repo "$ORG_REPO" --body-file "$TMP_NEW" >/dev/null; then
   echo "update-issue-progress: gh issue edit failed for #$ISSUE_NUM" >&2
   exit 4

package/pipeline/scripts/usage-report.mjs

@@ -609,7 +609,18 @@ async function main() {
 // Windows-safe entry-point check: compare file URLs, never string-split a path.
 const invokedDirectly = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
 if (invokedDirectly) {
-  main().catch(() => process.exit(0));
+  // Exit 0 stays: usage telemetry must never be the reason a run fails, and a
+  // non-zero exit here would propagate into whatever called it.
+  //
+  // But the silence goes. `catch(() => process.exit(0))` reported success for
+  // every failure, so a telemetry path that had been broken for weeks looked
+  // exactly like one that worked - there was no surface on which anyone could
+  // notice. One line on stderr costs nothing and is the difference between a
+  // degraded feature and an invisible one.
+  main().catch((err) => {
+    process.stderr.write(`usage-report: not sent  -  ${err?.message ?? err}\n`);
+    process.exit(0);
+  });
 }
 
 export {

package/pipeline/scripts/validate-analysis-doc.mjs

@@ -11,7 +11,7 @@
 //
 // Checks (ERROR = blocking exit 1; WARN = advisory, still exit 0 unless --strict):
 //   - Front-matter block with required keys (feature, platform, language, mode,
-//     template_version); mode in {full, lite}; platform in the known set.
+//     template_version); mode must be full (lite removed in v19.0.0); platform in the known set.
 //   - Never-omitted sections present by title keyword (Locked 2): Summary,
 //     Goals, User Stories, API Contracts, Architecture, Files to Add, Risks,
 //     References.
@@ -41,6 +41,7 @@
 // Exit: 0 valid, 1 invalid (or WARN under --strict), 64 usage error.
 
 import { readFileSync } from "node:fs";
+import { runMain } from "../lib/fatal.mjs";
 
 // A repo-less run (Locked 35) still splits by channel, derived from the evidence:
 // "mobile" and "web" are its platform values. "none" is the narrower case where the
@@ -244,16 +245,31 @@ function main() {
     for (const k of REQUIRED_FM) {
       if (!parsed.fm[k]) errors.push(`front-matter missing required key: ${k}`);
     }
+    // `mode` is accepted only as "full" now. Lite was removed in v19.0.0: it
+    // picked sections from a fixed list chosen by a three-signal score, which
+    // fought Locked 2 in both directions - a small feature with rich business
+    // rules lost Section 15 because it was not on the list, and a feature with
+    // no API contract kept Section 9 because it was. An older document carrying
+    // `mode: lite` is still readable; it is reported as a legacy value rather
+    // than rejected, because the document was valid when it was written.
     const mode = parsed.fm.mode;
-    if (mode && mode !== "full" && mode !== "lite") {
-      errors.push(`front-matter mode must be full|lite, got: ${mode}`);
+    if (mode === "lite") {
+      warns.push(
+        "front-matter says mode: lite  -  Lite was removed in v19.0.0 and this is a pre-v19 document. Sections are chosen by evidence now (Locked 2).",
+      );
+    } else if (mode && mode !== "full") {
+      errors.push(`front-matter mode must be full, got: ${mode}`);
     }
     const plat = parsed.fm.platform;
     if (plat && !KNOWN_PLATFORMS.has(plat)) {
       errors.push(`front-matter platform not in known set: ${plat}`);
     }
   }
-  const mode = parsed?.fm?.mode || "full";
+  // A pre-v19 `lite` document is validated as Full: the checks it skipped were
+  // skipped because of a mode that no longer exists, and re-skipping them here
+  // would carry that exemption forward forever.
+  const mode = "full";
+  void parsed?.fm?.mode;
   const profile = (parsed?.fm?.profile || "global").toLowerCase();
   if (profile !== "global" && profile !== "corporate") {
     errors.push(`front-matter profile must be global|corporate, got: ${profile}`);
@@ -384,7 +400,7 @@ function main() {
     } else if (rows.some((l) => /\bAS-\d{2,3}\b/.test(l))) {
       // Only when there is something to own. A Section 20 with no stamped row
       // has no owner to check, and warning there would fire on every document
-      // that never needed the column - noise that Phase 4 runs under --strict.
+      // that never needed the column - noise that Phase 3 runs under --strict.
       warns.push(
         "Risks and Open Questions carries AS-NN rows but no owner column; ownership cannot be checked",
       );
@@ -504,7 +520,7 @@ function main() {
       }
       mark("traceability-matrix");
     } else {
-      mark("traceability-matrix", "lite mode");
+      mark("traceability-matrix");
     }
   } else {
     mark("payload-in-table-cell", "global profile");
@@ -579,7 +595,7 @@ function main() {
 
   mark("optin-coverage-sections");
 
-  // 2c. The Test Plan is Phase 3's RED input (phase-3-dev.md step 5b): the tests
+  // 2c. The Test Plan is Phase 3's RED input (phase-2-dev.md step 5b): the tests
   // written first come from it. Full mode without it hands dev an empty matrix.
   // It is Section 15 in the global profile and Section 19 in the corporate one;
   // the check matches on the title, so only the stack-optional case needs an
@@ -593,7 +609,7 @@ function main() {
       // The omission table allows exactly one case: a backend-only run with no
       // contract testing planned. The validator knows the platform, so that case
       // warns instead of blocking; every other platform hands dev an empty matrix.
-      const msg = "no Section 15 Test Plan; Full mode dev reads it as the RED input (Locked 31)";
+      const msg = "no Section 15 Test Plan; dev reads it as the RED input (Locked 30)";
       if (parsed?.fm?.platform === "backend") {
         warns.push(`${msg} - allowed for backend only when no contract testing is planned`);
       } else {
@@ -614,8 +630,7 @@ function main() {
     }
   }
 
-  if (mode !== "full") mark("test-plan", "lite mode");
-  else if (noPlatform) mark("test-plan", "no target platform");
+  if (noPlatform) mark("test-plan", "no target platform");
   else mark("test-plan");
 
   // 2d. Section 3 carries the diagrams. Omission is legitimate under the
@@ -725,7 +740,7 @@ function main() {
 
   mark("concept-table-evidence", conceptBody ? undefined : "no concept table");
 
-  // 2g. Locked 31 main clause: a rule with no test scenario fails the gate.
+  // 2g. Locked 30 main clause: a rule with no test scenario fails the gate.
   // The pre-existing occurrence-count heuristic below stays as the looser net.
   if (mode === "full") {
     const idRx = /BR-[a-z0-9]+(?:-[a-z0-9]+)*-\d+/gi;
@@ -746,7 +761,7 @@ function main() {
     }
   }
 
-  mark("rule-to-test", mode === "full" ? undefined : "lite mode");
+  mark("rule-to-test");
 
   // 2h. Redesign mode (Locked 37). Eight checks, live only when the front-matter
   // opts in. The contract they enforce is analysis/redesign.md, which loads only
@@ -793,7 +808,7 @@ function main() {
         );
       }
       // 3. A rule that lives only in a shared module legitimately reads this way,
-      // so it warns rather than blocks - and Phase 4 runs --strict, so it blocks
+      // so it warns rather than blocks - and Phase 3 runs --strict, so it blocks
       // there, which is where a human is already looking.
       if (/cross-cutting/i.test(evidence) && certainty.includes("confirmed")) {
         warns.push(
@@ -870,7 +885,7 @@ function main() {
     // keyword as a raw substring of the heading line - deliberately, since Locked
     // 2 re-flows section numbers and the corporate profile numbers them
     // differently - so an unrelated `### 4.9 Notes on the old Current Behaviour
-    // audit process` matched, and Phase 4 runs --strict, which turns this warning
+    // audit process` matched, and Phase 3 runs --strict, which turns this warning
     // into a blocked document. The artefact itself is the honest signal: a
     // rendered current-behaviour table always carries `CB-<slug>-NN` ids, and a
     // paragraph that merely uses the words never does.
@@ -920,7 +935,49 @@ function main() {
 
   mark("placeholder-bodies", profile === "global" ? undefined : "corporate profile");
 
-  // 5. Traceability (Full mode only, Locked 31)
+  // 4b. Locked 2's numbering half, which was ungated until v19.0.0.
+  //
+  // It is NOT "numbering re-flows 1..N". That is what the rule used to say and
+  // it could not hold: Locked 30 threads ids across the document by section
+  // NUMBER ("Section 15.1 scenario", "Section 4.4", "Section 3/5 layout cells"),
+  // so a re-flowed document sends every one of those references to the wrong
+  // section. No emitted document ever re-flowed. The rule was the wrong half.
+  //
+  // What holds instead: a rendered section keeps its canonical template number,
+  // so gaps are correct and `1, 2, 4, 9, 13, 14, 21` is a valid document. Two
+  // things are still defects and both are checked here - a number outside the
+  // template's range, and numbers that repeat or go backwards. Either one means
+  // a cross-reference lands somewhere its author did not intend.
+  {
+    const MAX_SECTION = 23;
+    const nums = [];
+    for (const l of text.split("\n")) {
+      const m = /^##\s+(\d+)\.\s/.exec(l);
+      if (m) nums.push(Number(m[1]));
+    }
+    if (nums.length === 0) {
+      mark("section-numbering", "no numbered top-level sections");
+    } else {
+      const outOfRange = nums.filter((n) => n < 1 || n > MAX_SECTION);
+      const notAscending = [];
+      for (let i = 1; i < nums.length; i++) {
+        if (nums[i] <= nums[i - 1]) notAscending.push(`${nums[i - 1]} then ${nums[i]}`);
+      }
+      if (outOfRange.length > 0) {
+        errors.push(
+          `section number outside the 1..${MAX_SECTION} template range (Locked 2): ${outOfRange.join(", ")}`,
+        );
+      }
+      if (notAscending.length > 0) {
+        errors.push(
+          `section numbers repeat or go backwards (Locked 2): ${notAscending.slice(0, 4).join("; ")}`,
+        );
+      }
+      mark("section-numbering");
+    }
+  }
+
+  // 5. Traceability (Locked 30)
   if (mode === "full") {
     const idRe = /BR-[a-z0-9]+(?:-[a-z0-9]+)*-\d+/gi;
     const all = text.match(idRe) || [];
@@ -930,7 +987,7 @@ function main() {
       counts.set(key, (counts.get(key) || 0) + 1);
     }
     if (counts.size === 0 && profile === "global") {
-      warns.push("Full mode but no BR-<slug>-NN business-rule ids found (Section 4.4 / Locked 31)");
+      warns.push("no BR-<slug>-NN business-rule ids found (Section 4.4 / Locked 30)");
     }
     for (const [id, n] of counts) {
       if (n < 2) {
@@ -941,7 +998,7 @@ function main() {
     }
   }
 
-  mark("br-reference-count", mode === "full" ? undefined : "lite mode");
+  mark("br-reference-count");
 
   // 6. Manual test scenarios (Section 15.7): every MT row carries a BR id.
   // A manual scenario nobody can trace back to a rule is a scenario nobody can
@@ -1019,4 +1076,4 @@ function main() {
   console.log(`validate-analysis-doc: OK (mode=${mode}, ${warns.length} warning(s))`);
 }
 
-main();
+runMain("validate-analysis-doc", main);

package/pipeline/scripts/validate-code-graph.mjs

@@ -162,13 +162,16 @@ export function validate(obj) {
     obj = JSON.parse(raw);
   } catch (e) {
     console.log(JSON.stringify({ ok: false, errors: [`JSON parse error: ${e.message}`] }));
-    process.exit(1);
+    process.exitCode = 1;
+    return;
   }
   const errors = validate(obj);
   if (errors.length === 0) {
     console.log(JSON.stringify({ ok: true, errors: [] }));
-    process.exit(0);
+    return;
   }
+  // `errors` is one entry per violation and has no bound, so process.exit(1)
+  // here truncated the report exactly when there was most of it to read.
   console.log(JSON.stringify({ ok: false, errors }));
-  process.exit(1);
+  process.exitCode = 1;
 })();

package/pipeline/scripts/validate-complaint-doc.mjs

@@ -40,6 +40,7 @@
 // Exit: 0 valid, 1 invalid (or WARN under --strict), 64 usage error.
 
 import { readFileSync } from "node:fs";
+import { runMain } from "../lib/fatal.mjs";
 
 const REQUIRED_FM = ["run_name", "generated_at", "language", "complaint_count", "graylog_degraded"];
 
@@ -263,4 +264,4 @@ function main() {
   process.exit(0);
 }
 
-main();
+runMain("validate-complaint-doc", main);

package/pipeline/scripts/validate-diff-risk.mjs

@@ -120,13 +120,16 @@ function validate(obj) {
     obj = JSON.parse(raw);
   } catch (e) {
     console.log(JSON.stringify({ ok: false, errors: [`JSON parse error: ${e.message}`] }));
-    process.exit(1);
+    process.exitCode = 1;
+    return;
   }
   const errors = validate(obj);
   if (errors.length === 0) {
     console.log(JSON.stringify({ ok: true, errors: [] }));
-    process.exit(0);
+    return;
   }
+  // `errors` is one entry per violation and has no bound, so process.exit(1)
+  // here truncated the report exactly when there was most of it to read.
   console.log(JSON.stringify({ ok: false, errors }));
-  process.exit(1);
+  process.exitCode = 1;
 })();

package/pipeline/scripts/validate-planning.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// validate-planning.mjs  -  runtime validator for Phase 2 planning output.
+// validate-planning.mjs  -  runtime validator for Phase 1 planning output.
 //
 // Phase 2 returns a task decomposition conforming to
 // pipeline/schemas/planning-output.schema.json. Phase 3 iterates over `tasks`

package/pipeline/scripts/validate-reviewer.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// validate-reviewer.mjs  -  runtime validator for Phase 4 reviewer subagent output.
+// validate-reviewer.mjs  -  runtime validator for Phase 3 reviewer subagent output.
 //
 // Each of the 3 parallel reviewers (Opus, GPT-5.4, Sonnet) must return an
 // object matching pipeline/schemas/reviewer-output.schema.json. This validator

package/pipeline/scripts/validate-state.mjs

@@ -14,7 +14,7 @@
 // actually make a resume unsafe:
 //   - the file does not parse (truncated / corrupt)
 //   - root is not an object
-//   - currentPhase is missing or out of the 0..7 range (resume keys on it)
+//   - currentPhase is missing or out of the 0..5 range (resume keys on it)
 //   - phases is present but not an object, or an entry is not an object
 // Phase status strings are NOT enum-checked: real writers use "completed"
 // alongside the schema's "done", and an odd status does not make a resume
@@ -66,9 +66,33 @@ async function main() {
     process.exit(1);
   }
 
+  // Which numbering this file was written under. v19.0.0 renumbered eight
+  // phases into six, and a run that finished at `currentPhase: 7` in October
+  // was correct when it was written - calling it invalid now would mark most
+  // of the log directory broken and teach the reader to ignore this validator.
+  // Same decision the metrics file got: label the generation, do not rewrite
+  // history. A file stamped 2.2.0 or later is generation 2 and bounded 0..5;
+  // anything older, including the unstamped files that predate stamping
+  // entirely, is generation 1 and bounded 0..7.
+  const GEN2_FROM = "2.2.0";
+  const cmpVersion = (a, b) => {
+    const pa = String(a).split(".").map(Number);
+    const pb = String(b).split(".").map(Number);
+    for (let i = 0; i < 3; i++) {
+      if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) - (pb[i] || 0);
+    }
+    return 0;
+  };
+  const gen1 = !s.schemaVersion || cmpVersion(s.schemaVersion, GEN2_FROM) < 0;
+  const maxPhase = gen1 ? 7 : 5;
+  const phaseKey = gen1 ? /^[0-7]$/ : /^[0-5]$/;
+
   // currentPhase is the field resume keys on - it must be present and in range.
-  if (!Number.isInteger(s.currentPhase) || s.currentPhase < 0 || s.currentPhase > 7) {
-    errors.push(`currentPhase must be integer 0..7, got ${JSON.stringify(s.currentPhase)}`);
+  if (!Number.isInteger(s.currentPhase) || s.currentPhase < 0 || s.currentPhase > maxPhase) {
+    errors.push(
+      `currentPhase must be integer 0..${maxPhase}, got ${JSON.stringify(s.currentPhase)}` +
+        (gen1 ? " (generation 1 file: unstamped or schemaVersion < 2.2.0)" : ""),
+    );
   }
 
   // phases is optional (some early/aborted states omit it), but if present it
@@ -78,12 +102,28 @@ async function main() {
       errors.push("phases, when present, must be an object keyed by phase number");
     } else {
       for (const [k, v] of Object.entries(s.phases)) {
-        if (!/^[0-7]$/.test(k)) {
-          errors.push(`phases key invalid: "${k}" (expected "0".."7")`);
+        if (!phaseKey.test(k)) {
+          errors.push(`phases key invalid: "${k}" (expected "0".."${maxPhase}")`);
           continue;
         }
         if (typeof v !== "object" || v === null) {
           errors.push(`phases["${k}"] must be an object`);
+          continue;
+        }
+        // The rework cap. Every phase doc says "hard-kill at retryCount === 3"
+        // and the schema writes `maximum: 3`, but nothing read either: a fourth
+        // round produced a state that violates the schema and passed this
+        // validator, which is the one place that could have said so.
+        //
+        // What this does NOT do is stop the loop - that is the orchestrator's
+        // job and it stays prose. What it does is make an over-cap state fail
+        // instead of being carried forward as if it were fine.
+        if (v.retryCount !== undefined) {
+          if (!Number.isInteger(v.retryCount) || v.retryCount < 0 || v.retryCount > 3) {
+            errors.push(
+              `phases["${k}"].retryCount must be integer 0..3 (the rework cap), got ${JSON.stringify(v.retryCount)}`,
+            );
+          }
         }
       }
     }

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

@@ -88,13 +88,16 @@ function validate(obj) {
     obj = JSON.parse(raw);
   } catch (e) {
     console.log(JSON.stringify({ ok: false, errors: [`JSON parse error: ${e.message}`] }));
-    process.exit(1);
+    process.exitCode = 1;
+    return;
   }
   const errors = validate(obj);
   if (errors.length === 0) {
     console.log(JSON.stringify({ ok: true, errors: [] }));
-    process.exit(0);
+    return;
   }
+  // `errors` is one entry per violation and has no bound, so process.exit(1)
+  // here truncated the report exactly when there was most of it to read.
   console.log(JSON.stringify({ ok: false, errors }));
-  process.exit(1);
+  process.exitCode = 1;
 })();

package/pipeline/scripts/validate-triage.mjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
-// validate-triage.mjs  -  behavioral validator for Phase 4 triage output.
+// validate-triage.mjs  -  behavioral validator for Phase 3 triage output.
 //
 // Zero dependencies. Reads a triage JSON from a path arg or STDIN, enforces
 // the contract documented in pipeline/schemas/triage-output.schema.json AND
-// the edge-case rules from phase-4-review.md section3.3.
+// the edge-case rules from phase-3-review.md section3.3.
 //
 // Unlike validate-schemas.mjs (which only checks schema files are well-formed),
 // this validates an ACTUAL triage run's output.
@@ -81,7 +81,7 @@ function validateRawFinding(f, label, errors) {
   }
 }
 
-// v3.2.0 verify-by-test outcome (Phase 4 Step 3.7). Optional; when present:
+// v3.2.0 verify-by-test outcome (Phase 3 Step 3.7). Optional; when present:
 // result is required, and confirmed/not-reproduced additionally require
 // testRef + evidencePath (the empirical claims must be traceable).
 function validateVerification(v, label, errors) {
@@ -292,4 +292,6 @@ function validate(raw) {
 const raw = await readInput();
 const result = validate(raw);
 console.log(JSON.stringify(result, null, 2));
-process.exit(result.ok ? result.code : 1);
+// Assigned rather than called: process.exit() would cut this payload short when
+// stdout is a pipe, which is how every caller reads it.
+process.exitCode = result.ok ? result.code : 1;

package/pipeline/scripts/verify-citations.mjs

@@ -45,6 +45,8 @@
 import { readFileSync, realpathSync, statSync } from "node:fs";
 import { resolve as resolvePath, sep } from "node:path";
 import { spawnSync } from "node:child_process";
+import { runMain } from "../lib/fatal.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
 
 /**
  * Reject a path before it reaches git.
@@ -423,6 +425,6 @@ function main() {
   process.exit(report.unresolved.length === 0 ? 0 : 1);
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
-  main();
+if (invokedDirectly(import.meta.url)) {
+  runMain("verify-citations", main);
 }