@mmerterden/multi-agent-pipeline 20.34.0 → 20.36.0

package/pipeline/scripts/test-stability-gate.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+/**
+ * @file test-stability-gate.mjs  -  the repeated runs of the new and changed
+ * tests agree, or the result is not GREEN.
+ *
+ * Phase 2's stability rule runs each test added or changed in the diff
+ * `testStability.repeatCount` times and keeps every run as
+ * `.pipeline/repeat-<k>.junit.xml`. This gate reads those files and compares
+ * each test case's outcome across the runs: a case that passed in some runs
+ * and failed in others is a flake, however the last run ended.
+ *
+ * A case is keyed by classname and name. Outcomes are pass, fail (a failure
+ * or error element) and skip; a case missing from a run counts as not run.
+ *
+ * Usage:
+ *   test-stability-gate.mjs --dir <dir> --expect <N>
+ *
+ * Output (stdout, JSON): {ok, expected, runs, missingRuns[], cases, flaky[], failedEverywhere[]}
+ *   flaky             [{test, passed, failed, of}]  outcomes disagree across runs
+ *   failedEverywhere  tests that failed in every run (stable, but not GREEN)
+ *
+ * Exit: 0 every case passed in every run; 1 a flake, a run missing, a test
+ * that failed, or no test cases at all; 64 usage.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+
+const attr = (tag, name) => {
+  const m = new RegExp(`\\b${name}="([^"]*)"`).exec(tag);
+  return m ? m[1] : "";
+};
+
+/** Test case key -> outcome for one JUnit XML document. */
+export function outcomes(xml) {
+  const out = new Map();
+  for (const m of String(xml).matchAll(/<testcase\b([^>]*?)(?:\/>|>([\s\S]*?)<\/testcase>)/g)) {
+    const key = `${attr(m[1], "classname")}::${attr(m[1], "name")}`;
+    const body = m[2] ?? "";
+    const outcome = /<(?:failure|error)\b/.test(body)
+      ? "fail"
+      : /<skipped\b/.test(body)
+        ? "skip"
+        : "pass";
+    const prev = out.get(key);
+    out.set(key, prev === "fail" || outcome === "fail" ? "fail" : outcome);
+  }
+  return out;
+}
+
+/** Compare the per-run outcome maps. */
+export function compare(runs) {
+  const keys = new Set();
+  for (const r of runs) for (const k of r.keys()) keys.add(k);
+  const flaky = [];
+  const failedEverywhere = [];
+  for (const k of [...keys].sort()) {
+    const seen = runs.map((r) => r.get(k) ?? "missing");
+    const passed = seen.filter((o) => o === "pass").length;
+    const failed = seen.filter((o) => o === "fail" || o === "missing").length;
+    if (seen.every((o) => o === "skip")) continue;
+    if (passed && failed) flaky.push({ test: k, passed, failed, of: runs.length });
+    else if (!passed && failed) failedEverywhere.push(k);
+  }
+  return { cases: keys.size, flaky, failedEverywhere };
+}
+
+export function evaluate(dir, expected) {
+  const runs = [];
+  const missingRuns = [];
+  for (let k = 1; k <= expected; k++) {
+    const p = join(dir, `repeat-${k}.junit.xml`);
+    if (!existsSync(p)) {
+      missingRuns.push(k);
+      continue;
+    }
+    runs.push(outcomes(readFileSync(p, "utf8")));
+  }
+  const c = compare(runs);
+  return {
+    ok:
+      missingRuns.length === 0 &&
+      c.cases > 0 &&
+      c.flaky.length === 0 &&
+      c.failedEverywhere.length === 0,
+    expected,
+    runs: runs.length,
+    missingRuns,
+    ...c,
+  };
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const get = (f) => {
+    const i = argv.indexOf(f);
+    return i >= 0 ? argv[i + 1] : undefined;
+  };
+  const dir = get("--dir");
+  const expected = Number(get("--expect"));
+  if (argv.length !== 4 || !dir || !Number.isInteger(expected) || expected < 1 || expected > 50) {
+    console.error("usage: test-stability-gate.mjs --dir <dir> --expect <N>");
+    return 64;
+  }
+  const out = evaluate(dir, expected);
+  process.stdout.write(JSON.stringify(out) + "\n");
+  return out.ok ? 0 : 1;
+}
+
+if (invokedDirectly(import.meta.url)) process.exit(main());

package/pipeline/scripts/update-check.sh

@@ -30,6 +30,7 @@
 #                                                         # updateCheck.ttlHours, else 24)
 #   bash pipeline/scripts/update-check.sh --force         # ignore cache
 #   bash pipeline/scripts/update-check.sh --print-required  # emit the floor only
+#   bash pipeline/scripts/update-check.sh --cache-only    # cached answer at any age, never the registry
 #
 # Cache file: ~/.claude/logs/multi-agent/.update-check ("epoch|latest|required").
 # A legacy two-field cache ("epoch|latest") still reads  -  the missing third
@@ -47,6 +48,7 @@ FAIL_TTL_SECONDS=3600
 LOCAL_VERSION=""
 FORCE=0
 PRINT_REQUIRED=0
+CACHE_ONLY=0
 
 while [ $# -gt 0 ]; do
   case "$1" in
@@ -54,6 +56,7 @@ while [ $# -gt 0 ]; do
     --ttl-hours) TTL_HOURS="${2:-}"; shift; [ $# -gt 0 ] && shift ;;
     --force) FORCE=1; shift ;;
     --print-required) PRINT_REQUIRED=1; shift ;;
+    --cache-only) CACHE_ONLY=1; shift ;;
     *) shift ;;
   esac
 done
@@ -124,12 +127,15 @@ if [ "$FORCE" -eq 0 ] && [ -f "$CACHE_FILE" ]; then
   case "$cached_epoch" in (*[!0-9]*|"") cached_epoch=0 ;; esac
   # A stamp in the future is a clock or copy mistake, not a fresh answer.
   [ "$cached_epoch" -gt "$now" ] && cached_epoch=0
-  if [ $((now - cached_epoch)) -lt $((TTL_HOURS * 3600)) ] && [ -n "$cached_latest" ]; then
+  if { [ "$CACHE_ONLY" -eq 1 ] || [ $((now - cached_epoch)) -lt $((TTL_HOURS * 3600)) ]; } && [ -n "$cached_latest" ]; then
     latest="$cached_latest"
     required="$cached_required"
   fi
 fi
 
+# A cache-only caller gets no answer rather than a network wait.
+[ -z "$latest" ] && [ "$CACHE_ONLY" -eq 1 ] && exit 0
+
 # Stale or missing cache -> one bounded registry call (silent on any failure).
 # The abbreviated packument carries dist-tags at a quarter of the full document.
 # A failed read is remembered for FAIL_TTL_SECONDS in "<cache>.fail", so an

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

@@ -11,7 +11,13 @@
 # never hand-edited.
 #
 # Usage:
-#   update-issue-progress.sh <task-id>
+#   update-issue-progress.sh <task-id> [--comment-file <path>]
+#
+#   --comment-file posts that comment on the issue first (through the outbound
+#   gate, with the `Ref: #N` footer appended when missing), then the flags, so
+#   a caller with no separate comment step (the unattended runner) still writes
+#   both. `--body-file` is the same flag under the name the runner's script
+#   runner passes. Without it the flags wait for a comment already on the issue.
 #
 # Inputs:
 #   $HOME/.claude/logs/multi-agent/{project}/{taskId}/agent-state.json
@@ -26,6 +32,9 @@
 #   2 missing agent-state.json
 #   3 missing required flags
 #   4 GitHub edit failed
+#   5 no issue comment from this run yet: the comment is posted first and the
+#     flags follow it, both or neither (channels/issue-comment.md)
+#   6 issue coordinates in the state that are not an owner/repo and a number
 
 set -euo pipefail
 
@@ -118,9 +127,17 @@ EOF
 
 TASK_ID="${1:-}"
 if [ -z "$TASK_ID" ]; then
-  echo "usage: update-issue-progress.sh <task-id>" >&2
+  echo "usage: update-issue-progress.sh <task-id> [--comment-file <path>]" >&2
   exit 64
 fi
+COMMENT_FILE=""
+if [ "$TASK_ID" != "--rewrite" ] && [ "$#" -gt 1 ]; then
+  if [ "$#" -ne 3 ] || { [ "$2" != "--comment-file" ] && [ "$2" != "--body-file" ]; } || [ ! -f "$3" ]; then
+    echo "usage: update-issue-progress.sh <task-id> [--comment-file <path>]" >&2
+    exit 64
+  fi
+  COMMENT_FILE="$3"
+fi
 
 # Internal test seam: `--rewrite <body-file>` runs only the Progress-block
 # rewrite (placeholder glyphs) and prints the result. No state, no gh.
@@ -155,6 +172,11 @@ if [ -z "$ORG_REPO" ] || [ -z "$ISSUE_NUM" ]; then
   echo "update-issue-progress: no githubIssue in state for task=$TASK_ID (Jira-originated task, or issue not yet linked)" >&2
   exit 3
 fi
+if ! printf '%s' "$ISSUE_NUM" | grep -Eq '^[0-9]{1,9}$' ||
+  ! printf '%s' "$ORG_REPO" | grep -Eq '^[A-Za-z0-9][A-Za-z0-9-]{0,38}/[A-Za-z0-9._-]{1,100}$'; then
+  echo "update-issue-progress: githubIssue in state is not an owner/repo and a number; nothing written" >&2
+  exit 6
+fi
 
 # Read the four flags (default false).
 F_IMPL=$(jq -r '.flags.implementation // false' "$AGENT_STATE")
@@ -190,17 +212,60 @@ NEW_BLOCK=$(build_progress_block "$G_IMPL" "$G_TEST" "$G_CC" "$G_WIKI")
 # comment, next heading, or EOF)  -  see rewrite_progress_body above.
 rewrite_progress_body "$NEW_BLOCK" "$TMP_BODY" > "$TMP_NEW"
 
-# Check if body actually changed (idempotent no-op).
-if cmp -s "$TMP_BODY" "$TMP_NEW"; then
+# Whether the body changes (an unchanged body is an idempotent no-op for the
+# flags), and the new body's outbound check before anything is posted, so a
+# refused body never leaves a comment behind without its flags.
+CHANGED=true
+cmp -s "$TMP_BODY" "$TMP_NEW" && CHANGED=false
+if [ "$CHANGED" = true ] && ! ma_outbound_gate "$TMP_NEW"; then
+  echo "update-issue-progress: outbound gate refused the new body; #$ISSUE_NUM left unchanged" >&2
+  exit 7
+fi
+
+# Both or neither: the flags follow this run's issue comment, never stand in
+# for it. With --comment-file the comment is posted here, first, whether or
+# not the flags change. Otherwise it
+# is the one the authenticated account posted on the issue since the run
+# started, carrying the template's `Ref: #N` footer.
+if [ -n "$COMMENT_FILE" ]; then
+  TMP_COMMENT=$(mktemp "/tmp/issue-comment-${TASK_ID}.XXXXXX")
+  trap 'rm -f "$TMP_BODY" "$TMP_NEW" "$TMP_COMMENT"' EXIT
+  cat "$COMMENT_FILE" > "$TMP_COMMENT"
+  grep -qF "Ref: #$ISSUE_NUM" "$TMP_COMMENT" || printf '\n\nRef: #%s\n' "$ISSUE_NUM" >> "$TMP_COMMENT"
+  if ! ma_outbound_gate "$TMP_COMMENT"; then
+    echo "update-issue-progress: outbound gate refused the comment; #$ISSUE_NUM left unchanged" >&2
+    exit 7
+  fi
+  if ! gh issue comment "$ISSUE_NUM" --repo "$ORG_REPO" --body-file "$TMP_COMMENT" >/dev/null; then
+    echo "update-issue-progress: gh issue comment failed for #$ISSUE_NUM; flags left unchanged" >&2
+    exit 4
+  fi
+elif [ "$CHANGED" = true ]; then
+  # The comments API reads `since` as an ISO 8601 instant; an offset's `+`
+  # would arrive as a space, so the start time goes out in UTC.
+  STARTED=$(jq -r '.startedAt // empty' "$AGENT_STATE")
+  STARTED=$(node -e 'const d = new Date(process.argv[1]); if (process.argv[1] && !isNaN(d)) process.stdout.write(d.toISOString().replace(/\.\d{3}Z$/, "Z"));' "$STARTED" 2>/dev/null || true)
+  ME=$(gh api user --jq .login 2>/dev/null || true)
+  if ! printf '%s' "$ME" | grep -Eq '^[A-Za-z0-9][A-Za-z0-9-]{0,38}(\[bot\])?$'; then
+    echo "update-issue-progress: could not read the GitHub account; #$ISSUE_NUM left unchanged" >&2
+    exit 5
+  fi
+  COMMENTS_PATH="repos/$ORG_REPO/issues/$ISSUE_NUM/comments"
+  [ -n "$STARTED" ] && COMMENTS_PATH="$COMMENTS_PATH?since=$STARTED"
+  if ! gh api --paginate "$COMMENTS_PATH" \
+    --jq ".[] | select(.user.login == \"$ME\") | select(.body | contains(\"Ref: #$ISSUE_NUM\")) | .id" 2>/dev/null |
+    grep -q .; then
+    echo "update-issue-progress: no issue comment from this run on #$ISSUE_NUM; post it first (comment and flags go together)" >&2
+    exit 5
+  fi
+fi
+
+if [ "$CHANGED" = false ]; then
   echo "update-issue-progress: no change for #$ISSUE_NUM (idempotent no-op)" >&2
   exit 0
 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/validate-planning.mjs

@@ -27,6 +27,7 @@
 
 import { readFileSync } from "node:fs";
 import { planOverlaps } from "./_plan-overlap.mjs";
+import { sectionBody, tableDataRows } from "../lib/analysis-sections.mjs";
 
 const ALLOWED_TYPES = new Set(["test", "code", "refactor", "docs", "chore"]);
 const TASK_ID_RE = /^T\d+$/;
@@ -35,6 +36,85 @@ const REVIEW_FOCUS_MAX = 5;
 const SPEC_RATIO = 4;
 const SPEC_MIN_CHARS = 400;
 
+const FIGMA_LINK = /\bfigma\.com\/(?:design|file|proto)\//i;
+const DESIGN_VALUE = /\b\d+(?:\.\d+)?\s?(?:px|pt)\b/i;
+const INVENTORY_KEYWORDS = ["Bileşen Envanteri", "Component Inventory"];
+const UI_FILE = /(?:View|Screen|Scene|Content|Cell|Sheet)\.(?:swift|kt)$|\.figma\.(?:swift|kt)$/;
+const MAPPINGS = new Set(["code-connect", "new", "best-fit"]);
+
+/**
+ * The analysis Section 6 rows: the component name (first cell) and whether it
+ * exists already (second cell, yes / no; anything else is unknown).
+ */
+function inventoryComponents(specText) {
+  const body = sectionBody(String(specText).split("\n"), INVENTORY_KEYWORDS, 2);
+  if (!body) return [];
+  return tableDataRows(body)
+    .map((row) => {
+      const cells = row.split("|").map((c) => c.replace(/[`*]/g, "").trim());
+      const existing = (cells[2] || "").toLowerCase();
+      return {
+        name: cells[1] ?? "",
+        existing: /^(yes|evet)\b/.test(existing)
+          ? true
+          : /^(no|hayır|hayir)\b/.test(existing)
+            ? false
+            : null,
+      };
+    })
+    .filter((r) => r.name && !/^<.*>$/.test(r.name));
+}
+
+/**
+ * Errors and warnings for the plan's UI tasks against Section 6: a task that
+ * touches a view file names its component, and the name is a Section 6 row.
+ */
+function designCitations(tasks, components) {
+  const errors = [];
+  const warnings = [];
+  if (!components.length || !Array.isArray(tasks)) return { errors, warnings };
+  const known = new Map(components.map((c) => [c.name, c.existing]));
+  for (const t of tasks) {
+    if (!t || typeof t !== "object") continue;
+    const d = t.design;
+    if (d !== undefined) {
+      if (!d || typeof d.component !== "string" || !MAPPINGS.has(d.mapping)) {
+        errors.push(`tasks ${t.id}.design: needs {component, mapping: code-connect|new|best-fit}`);
+        continue;
+      }
+      const name = d.component.trim();
+      if (!known.has(name)) {
+        errors.push(
+          `tasks ${t.id}.design.component: "${d.component}" is not a Section 6 row; use the inventory's name verbatim, never a sound-alike`,
+        );
+      } else if (d.mapping === "new" && known.get(name) === true) {
+        errors.push(
+          `tasks ${t.id}.design: "${name}" exists already per Section 6; reuse it, do not build it new`,
+        );
+      } else if (d.mapping === "code-connect" && known.get(name) === false) {
+        errors.push(
+          `tasks ${t.id}.design: "${name}" does not exist yet per Section 6, so it has no Code Connect mapping`,
+        );
+      }
+      if (d.mapping === "best-fit") {
+        warnings.push(
+          `tasks ${t.id}: best-fit component needs a Risk row; Phase 3 gates it review_blocking`,
+        );
+      }
+      continue;
+    }
+    const ui = (Array.isArray(t.files) ? t.files : []).some(
+      (f) => typeof f === "string" && UI_FILE.test(f),
+    );
+    if (ui && (t.type === "code" || t.type === "refactor")) {
+      errors.push(
+        `tasks ${t.id}: touches a UI file but cites no Section 6 component (design.component)`,
+      );
+    }
+  }
+  return { errors, warnings };
+}
+
 function specPath() {
   const i = process.argv.indexOf("--spec");
   return i > 0 ? process.argv[i + 1] : null;
@@ -241,11 +321,35 @@ async function main() {
   const spec = specPath();
   if (spec) {
     let specChars = 0;
+    let specText = "";
     try {
-      specChars = readFileSync(spec, "utf-8").length;
+      specText = readFileSync(spec, "utf-8");
+      specChars = specText.length;
     } catch {
       warnings.push(`spec not readable: ${spec}`);
     }
+    // With a design behind the plan, values come from its tokens, never from a
+    // number someone read off a screenshot.
+    if (FIGMA_LINK.test(specText) && Array.isArray(parsed.tasks)) {
+      for (const t of parsed.tasks) {
+        const text = [
+          t?.title,
+          t?.description,
+          ...(Array.isArray(t?.acceptanceCriteria) ? t.acceptanceCriteria : []),
+        ]
+          .filter((v) => typeof v === "string")
+          .join("\n");
+        const m = text.match(DESIGN_VALUE);
+        if (m) {
+          errors.push(
+            `tasks ${t.id}: "${m[0]}" is a raw design value; name the design token (Spacing.*, Radius.*, a type style) the analysis mapped instead`,
+          );
+        }
+      }
+    }
+    const cited = designCitations(parsed.tasks, inventoryComponents(specText));
+    errors.push(...cited.errors);
+    warnings.push(...cited.warnings);
     if (specChars >= SPEC_MIN_CHARS && raw.length > specChars * SPEC_RATIO) {
       warnings.push(
         `plan is ${Math.round(raw.length / specChars)}x the length of its spec; record decisions, not a transcript`,

package/pipeline/scripts/validate-triage.mjs

@@ -13,6 +13,15 @@
 //   cat triage.json | node pipeline/scripts/validate-triage.mjs -
 //     [--reviewers a.json,b.json]   # every reviewer cannotVerify row needs a triage row
 //     [--reviewers-dir <dir>]       # same, for every reviewer-*.json in <dir>
+//     [--anonymized]                # the verdict was judged on anonymized input:
+//                                   # no finding may carry `reviewer`, labels only
+//
+// An accepted finding names its source as `reviewer` (a model family),
+// `foundBy` (an anonymized "Source A" label, or "security-auditor") or `tag`
+// (a deterministic gate finding). Triage judges anonymized findings and
+// carries `foundBy` through; anonymize-findings.mjs --restore writes the
+// family back afterwards, so a `reviewer` in the verdict itself means the
+// judge was told whose findings it graded.
 //
 // Exit codes:
 //   0  -  valid, safe to act on
@@ -27,6 +36,8 @@ import { readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
 const ALLOWED_REVIEWERS = new Set(["fable", "opus", "sonnet", "gpt"]);
+const FOUND_BY_RE = /^(Source [A-Z]|security-auditor)$/;
+const ANONYMIZED = process.argv.includes("--anonymized");
 const ALLOWED_SEVERITIES = new Set(["blocking", "important", "suggestion"]);
 const ALLOWED_CONSENSUS_VERDICTS = new Set([
   "unanimous-pass",
@@ -174,11 +185,33 @@ function validateVerification(v, label, errors) {
   }
 }
 
+/** The finding's source kind, or null when none is valid. */
+function sourceOf(f) {
+  if (f?.foundBy !== undefined) return FOUND_BY_RE.test(String(f.foundBy)) ? "label" : null;
+  if (typeof f?.tag === "string" && f.tag) return "tag";
+  return ALLOWED_REVIEWERS.has(f?.reviewer) ? "reviewer" : null;
+}
+
+/** With --anonymized: every finding that names a reviewer, by list and index. */
+function identityLeaks(parsed) {
+  const out = [];
+  (parsed.accepted || []).forEach((f, i) => {
+    if (f && Object.hasOwn(f, "reviewer")) out.push(`accepted[${i}]`);
+  });
+  for (const key of ["deferred", "rejected"]) {
+    (parsed[key] || []).forEach((e, i) => {
+      if (e?.finding && Object.hasOwn(e.finding, "reviewer")) out.push(`${key}[${i}].finding`);
+    });
+  }
+  return out;
+}
+
 function validateAccepted(f, i, errors) {
   validateRawFinding(f, `accepted[${i}]`, errors);
-  if (!ALLOWED_REVIEWERS.has(f.reviewer)) {
+  const source = sourceOf(f);
+  if (source === null) {
     errors.push(
-      `accepted[${i}]: reviewer must be one of fable|opus|sonnet|gpt (got ${JSON.stringify(f.reviewer)}; haiku was removed in v2.1.0)`,
+      `accepted[${i}]: name the source as foundBy ("Source A".."Source Z" or "security-auditor"), tag, or reviewer fable|opus|sonnet|gpt (got reviewer ${JSON.stringify(f?.reviewer)}, foundBy ${JSON.stringify(f?.foundBy)})`,
     );
   }
   if (typeof f.fix !== "string" || f.fix.length < 4) {
@@ -279,6 +312,13 @@ function validate(raw) {
   parsed.accepted.forEach((f, i) => validateAccepted(f, i, errors));
   parsed.deferred.forEach((f, i) => validateClassified(f, "deferred", i, errors));
   parsed.rejected.forEach((f, i) => validateClassified(f, "rejected", i, errors));
+  if (ANONYMIZED) {
+    for (const at of identityLeaks(parsed)) {
+      errors.push(
+        `${at}: carries reviewer in an anonymized verdict; carry foundBy through, the family is restored after validation`,
+      );
+    }
+  }
 
   // Every requirement a reviewer could not verify from the diff is settled here:
   // checked in the unchanged code (verified), turned into a finding, or ruled

package/pipeline/scripts/work-items.mjs

@@ -7,6 +7,13 @@
  *                    /multi-agent:jira, /multi-agent:issue and Phase 0 run;
  *                    title, type, status, score, blockers, warnings, summary
  *                    and a description excerpt, scrubbed
+ *   reach            how far each open GitHub pull request reaches: its
+ *                    changed files (`gh pr view --json files`) looked up in
+ *                    the repository's own code graph, and the files that
+ *                    depend on them counted (graph-affected, depth 2). A
+ *                    repository without a graph, a Bitbucket pull request or
+ *                    a name that is not owner/repo is listed with its reason
+ *                    and costs no gh call
  *   prs              open pull requests on GitHub where you are asked to
  *                    review or are the author (`gh search prs`, the queries
  *                    /multi-agent:review lists). Bitbucket is reported as a
@@ -34,6 +41,7 @@
  * Usage:
  *   work-items.mjs maturity <key>
  *   work-items.mjs prs
+ *   work-items.mjs reach
  *   work-items.mjs verdict <task-id> [--post]
  *
  * MA_GH_BIN stands in for gh, MA_ISSUE_FETCHER and MA_POST_PR_REVIEW for the
@@ -57,6 +65,8 @@ import { runMain } from "../lib/fatal.mjs";
 import { invokedDirectly } from "../lib/invoked-directly.mjs";
 import { resolveTokenAsync } from "../lib/credential-resolve.mjs";
 import { homedir } from "node:os";
+import { affected } from "./graph-affected.mjs";
+import { loadGraph } from "./graph-query.mjs";
 
 export const CONTRACT_VERSION = "1.1.0";
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -349,6 +359,113 @@ export async function pullRequests({ env = process.env, redact = false } = {}) {
   return { contractVersion: CONTRACT_VERSION, items, sources };
 }
 
+const REACH_MAX = 20;
+const REACH_PARALLEL = 3;
+const REACH_DEPTH = 2;
+const FILES_MAX = 300;
+const NAME_PART = /^(?!\.{1,2}$)[A-Za-z0-9._-]{1,100}$/;
+
+/** owner/repo with two plain parts; anything else never reaches gh. */
+function plainRepo(repo) {
+  const parts = String(repo).split("/");
+  return parts.length === 2 && parts.every((x) => NAME_PART.test(x));
+}
+
+async function inBatches(items, size, fn) {
+  const out = [];
+  for (let i = 0; i < items.length; i += size) {
+    out.push(...(await Promise.all(items.slice(i, i + size).map(fn))));
+  }
+  return out;
+}
+
+/** The changed file paths of one GitHub pull request, or null when gh could not say. */
+async function changedFiles(env, repo, number) {
+  const gh = env.MA_GH_BIN || "gh";
+  const r = await spawnAsync(
+    gh,
+    ["pr", "view", String(number), "--repo", repo, "--json", "files"],
+    {
+      env,
+      timeoutMs: TIMEOUT_MS,
+    },
+  );
+  if (r.error || r.status !== 0) return null;
+  try {
+    const files = JSON.parse(r.stdout)?.files;
+    return (Array.isArray(files) ? files : [])
+      .map((f) => f?.path)
+      .filter((path) => typeof path === "string" && path.length <= 1024)
+      .slice(0, FILES_MAX);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * How far each open pull request reaches, widest first. Changed paths are
+ * used only as keys into the local graph: nothing is read from disk by them
+ * and none is echoed back, only counts.
+ */
+export async function prReach({ env = process.env, list = null } = {}) {
+  const prs = list ?? (await pullRequests({ env }));
+  const envByLogin = new Map();
+  for (const a of await ghAccounts(env)) {
+    const aEnv = await accountEnv(env, a);
+    if (aEnv) envByLogin.set(a.login, aEnv);
+  }
+  const knowledge = join(env.HOME || homedir(), ".claude", "knowledge");
+  const graphs = new Map();
+  const graphFor = (project) => {
+    if (!graphs.has(project)) {
+      const path = join(knowledge, project, "code-graph.json");
+      let graph;
+      try {
+        graph = existsSync(path) ? loadGraph(path) : null;
+      } catch {
+        graph = null;
+      }
+      graphs.set(project, graph);
+    }
+    return graphs.get(project);
+  };
+  const candidates = prs.items
+    .filter((p) => p.source !== "github" || plainRepo(p.repo))
+    .slice(0, REACH_MAX);
+  const rows = await inBatches(candidates, REACH_PARALLEL, async (p) => {
+    const row = { source: p.source, repo: p.repo, number: p.number, project: null };
+    if (p.source !== "github") return { ...row, reach: null, reason: "not measured off GitHub" };
+    const project = p.repo.split("/")[1];
+    const graph = graphFor(project);
+    if (!graph) return { ...row, reach: null, reason: `no code graph for ${project}` };
+    const files = await changedFiles(envByLogin.get(p.account) ?? env, p.repo, p.number);
+    if (!files) return { ...row, project, reach: null, reason: "gh could not list its files" };
+    const ids = new Set(graph.nodes.filter((n) => n.kind === "file").map((n) => n.id));
+    const seeds = files.map((f) => `file:${f}`).filter((id) => ids.has(id));
+    const byId = new Map(graph.nodes.map((n) => [n.id, n]));
+    const dependents = seeds.length
+      ? affected({ graph, seeds: seeds.map((id) => byId.get(id)), depth: REACH_DEPTH })
+      : [];
+    const reachedFiles = new Set(
+      dependents.filter((d) => d.node?.kind === "file").map((d) => d.id),
+    );
+    return {
+      ...row,
+      project,
+      changed: files.length,
+      inGraph: seeds.length,
+      reach: reachedFiles.size,
+    };
+  });
+  const updated = new Map(prs.items.map((p) => [`${p.repo}#${p.number}`, p.updatedAt ?? ""]));
+  rows.sort(
+    (a, b) =>
+      (b.reach ?? -1) - (a.reach ?? -1) ||
+      (updated.get(`${a.repo}#${a.number}`) < updated.get(`${b.repo}#${b.number}`) ? 1 : -1),
+  );
+  return { contractVersion: CONTRACT_VERSION, depth: REACH_DEPTH, items: rows };
+}
+
 function stateOf(taskId) {
   const { found, records } = selectRuns({ taskId });
   if (!found || !records.length) throw new WorkError("no-run", "no such run");
@@ -449,11 +566,12 @@ async function main(argv) {
     let out;
     if (cmd === "maturity" && arg) out = await issueMaturity(arg);
     else if (cmd === "prs" && !arg) out = await pullRequests();
+    else if (cmd === "reach" && !arg) out = await prReach();
     else if (cmd === "verdict" && arg && (flag === undefined || flag === "--post")) {
       out = flag ? await postReviewVerdict(arg) : reviewVerdictPreview(arg);
     } else {
       process.stderr.write(
-        "usage: work-items.mjs maturity <key> | prs | verdict <task-id> [--post]\n",
+        "usage: work-items.mjs maturity <key> | prs | reach | verdict <task-id> [--post]\n",
       );
       return 2;
     }