@mmerterden/multi-agent-pipeline 20.33.0 → 20.35.0

package/pipeline/scripts/triage-memory.mjs

@@ -10,7 +10,9 @@
  * Storage: append-only JSONL, one file per repo:
  *   $HOME/.claude/memory/multi-agent/<repo-slug>/triage-corpus.jsonl
  *
- * Each line conforms to pipeline/schemas/triage-corpus.schema.json.
+ * Each line conforms to pipeline/schemas/triage-corpus.schema.json. Every row
+ * passes the secret scan in _secret-scan.mjs before it is written; one that
+ * fails is counted in `droppedBySecretScan` and left out.
  *
  * Why JSONL not SQLite: zero deps, Node 18+ compatible, easy to grep/diff,
  * easy to delete a single row by line. The cost of a full corpus scan is
@@ -55,6 +57,8 @@ import { readFileSync, existsSync, mkdirSync, appendFileSync, statSync } from "n
 import { homedir } from "node:os";
 import { execFileSync } from "node:child_process";
 import { join, basename, dirname, posix } from "node:path";
+import { checkedSlug, memoryExcluded } from "./_memory-policy.mjs";
+import { openScanner, stripPrivate } from "./_secret-scan.mjs";
 import {
   bm25,
   recencyRank,
@@ -91,6 +95,10 @@ function die(msg, code = 1) {
 // prior-art recall always miss. `--git-common-dir` points at the main
 // repository's .git for every linked worktree.
 function repoSlug() {
+  return checkedSlug(rawRepoSlug());
+}
+
+function rawRepoSlug() {
   if (flags["repo-slug"]) return String(flags["repo-slug"]);
   if (process.env.MULTI_AGENT_REPO_SLUG) return process.env.MULTI_AGENT_REPO_SLUG;
   try {
@@ -249,9 +257,14 @@ function ingest() {
   const fromState = stateDefaults();
   const taskId = flags["task-id"] || fromState.taskId;
   if (!taskId) die("ingest needs --task-id <id> (or --state with a taskId)", 1);
-  const taskTitle = flags["task-title"] || fromState.taskTitle || null;
+  const taskTitle = stripPrivate(flags["task-title"] || fromState.taskTitle || "").trim() || null;
   const stack = flags.stack || fromState.stack || null;
   const slug = repoSlug();
+  if (memoryExcluded(slug)) {
+    process.stdout.write(JSON.stringify({ ok: true, slug, ingested: 0, excluded: true }) + "\n");
+    process.exitCode = 2;
+    return;
+  }
 
   let triage;
   try {
@@ -274,35 +287,51 @@ function ingest() {
   ];
 
   let written = 0;
-  for (const [classification, rows] of buckets) {
-    for (const f of rows) {
-      const issue = (f.issue || "").trim();
-      if (!issue) continue;
-      const file = f.file || "";
-      const key = `${taskId}::${classification}::${file}::${issue}`;
-      if (seen.has(key)) continue;
-      const row = {
-        v: "1.0.0",
-        ts,
-        task_id: taskId,
-        task_title: taskTitle,
-        stack,
-        classification,
-        severity: f.severity || "suggestion",
-        file,
-        line: typeof f.line === "number" ? f.line : null,
-        issue,
-        fix: f.fix || null,
-        reason: f._reason || null,
-        reviewer: f.reviewer || null,
-        file_sha: fileSha(file, top),
-      };
-      writeRow(slug, row);
-      seen.add(key);
-      written++;
+  let droppedBySecretScan = 0;
+  const scan = openScanner();
+  try {
+    for (const [classification, rows] of buckets) {
+      for (const f of rows) {
+        const issue = stripPrivate(f.issue || "").trim();
+        if (!issue) continue;
+        const file = f.file || "";
+        const key = `${taskId}::${classification}::${file}::${issue}`;
+        if (seen.has(key)) continue;
+        const fix = f.fix ? stripPrivate(f.fix).trim() || null : null;
+        const reason = f._reason ? stripPrivate(f._reason).trim() || null : null;
+        const reviewer = f.reviewer || null;
+        const stored = [issue, fix, reason, file, taskTitle, taskId, stack, reviewer, f.severity];
+        if (!scan.isClean(stored.filter(Boolean).join("\n"))) {
+          droppedBySecretScan++;
+          continue;
+        }
+        const row = {
+          v: "1.0.0",
+          ts,
+          task_id: taskId,
+          task_title: taskTitle,
+          stack,
+          classification,
+          severity: f.severity || "suggestion",
+          file,
+          line: typeof f.line === "number" ? f.line : null,
+          issue,
+          fix,
+          reason,
+          reviewer,
+          file_sha: fileSha(file, top),
+        };
+        writeRow(slug, row);
+        seen.add(key);
+        written++;
+      }
     }
+  } finally {
+    scan.close();
   }
-  process.stdout.write(JSON.stringify({ ok: true, slug, ingested: written }) + "\n");
+  process.stdout.write(
+    JSON.stringify({ ok: true, slug, ingested: written, droppedBySecretScan }) + "\n",
+  );
   // exitCode, not exit(): even this one-line write is on the same rule, and a
   // rule with an exception is the one that gets copied into the next branch.
   // 2 = nothing new, which callers treat as an idempotent success.
@@ -313,7 +342,7 @@ function ingest() {
 function query() {
   const cfg = recallConfig();
   const topN = flags.top ? Math.max(1, Number(flags.top)) : cfg.maxResults;
-  const slug = flags["repo-slug"] ? String(flags["repo-slug"]) : repoSlug();
+  const slug = repoSlug();
   const corpus = readCorpus(slug);
   if (corpus.length === 0) {
     process.stdout.write(JSON.stringify({ ok: true, slug, hits: [], total: 0 }) + "\n");
@@ -347,7 +376,7 @@ function priorArt() {
       : [];
   const cfg = recallConfig();
   const topN = flags.top ? Math.max(1, Number(flags.top)) : cfg.maxResults;
-  const slug = flags["repo-slug"] ? String(flags["repo-slug"]) : repoSlug();
+  const slug = repoSlug();
   const corpus = readCorpus(slug);
   const out = list.map((f) => {
     if (corpus.length === 0) return [];
@@ -436,7 +465,7 @@ function rank(corpus, issueText, fileGlob, topN, cfg) {
 function showCmd() {
   const id = flags.id && flags.id !== true ? String(flags.id) : null;
   if (!id) die("show needs --id <id>", 1);
-  const slug = flags["repo-slug"] ? String(flags["repo-slug"]) : repoSlug();
+  const slug = repoSlug();
   const want = id.startsWith("T:") ? id : `T:${id}`;
   const row = readCorpus(slug).find((r) => rowId(r) === want);
   if (!row) {
@@ -465,7 +494,7 @@ function showCmd() {
 function timelineCmd() {
   const id = flags.anchor && flags.anchor !== true ? String(flags.anchor) : null;
   if (!id) die("timeline needs --anchor <id>", 1);
-  const slug = flags["repo-slug"] ? String(flags["repo-slug"]) : repoSlug();
+  const slug = repoSlug();
   const before = flags.before && flags.before !== true ? Math.max(0, Number(flags.before)) : 3;
   const after = flags.after && flags.after !== true ? Math.max(0, Number(flags.after)) : 3;
   const want = id.startsWith("T:") ? id : `T:${id}`;
@@ -495,15 +524,13 @@ function timelineCmd() {
 }
 
 function pathCmd() {
-  process.stdout.write(
-    corpusPath(flags["repo-slug"] ? String(flags["repo-slug"]) : repoSlug()) + "\n",
-  );
+  process.stdout.write(corpusPath(repoSlug()) + "\n");
   process.exitCode = 0;
   return;
 }
 
 function statsCmd() {
-  const slug = flags["repo-slug"] ? String(flags["repo-slug"]) : repoSlug();
+  const slug = repoSlug();
   const corpus = readCorpus(slug);
   const counts = { accepted: 0, deferred: 0, rejected: 0 };
   for (const r of corpus) if (counts[r.classification] !== undefined) counts[r.classification]++;

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

@@ -8,8 +8,12 @@
 // Zero deps. Reads JSON from path arg or STDIN.
 //
 // Usage:
-//   node validate-planning.mjs path/to/plan.json
-//   cat plan.json | node validate-planning.mjs -
+//   node validate-planning.mjs path/to/plan.json [--spec <path>]
+//   cat plan.json | node validate-planning.mjs - [--spec <path>]
+//
+// --spec names the analysis document or task text the plan was written from.
+// A plan more than SPEC_RATIO times its length gets a warning: a plan should
+// record decisions, and one far longer than its spec is usually a transcript.
 //
 // Exit codes:
 //   0  -  valid
@@ -23,15 +27,113 @@
 
 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+$/;
 const NAME_LISTS = ["creates", "removes", "produces", "consumes"];
+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;
+}
+
+/** The plan path: the first argument that is neither a flag nor a flag's value. */
+function inputArg() {
+  const args = process.argv.slice(2);
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--spec") i++;
+    else if (!args[i].startsWith("--")) return args[i];
+  }
+  return undefined;
+}
 
 function readInput() {
-  const arg = process.argv[2];
+  const arg = inputArg();
   if (!arg) {
-    console.error("usage: validate-planning.mjs <path|->");
+    console.error("usage: validate-planning.mjs <path|-> [--spec <path>]");
     process.exit(64);
   }
   if (arg === "-") {
@@ -173,6 +275,33 @@ async function main() {
     }
   }
 
+  if (parsed.reviewFocus !== undefined) {
+    if (!Array.isArray(parsed.reviewFocus)) {
+      errors.push("reviewFocus: must be array if present");
+    } else {
+      if (parsed.reviewFocus.length > REVIEW_FOCUS_MAX) {
+        errors.push(`reviewFocus: at most ${REVIEW_FOCUS_MAX} entries`);
+      }
+      parsed.reviewFocus.forEach((r, i) => {
+        if (typeof r?.input !== "string" || r.input.trim().length < 4) {
+          errors.push(`reviewFocus[${i}].input: must name the input`);
+        }
+        if (!ids.has(r?.ownerTaskId)) {
+          errors.push(`reviewFocus[${i}].ownerTaskId: unknown task "${r?.ownerTaskId}"`);
+        }
+      });
+    }
+  }
+  if (
+    parsed.globalConstraints !== undefined &&
+    !(
+      Array.isArray(parsed.globalConstraints) &&
+      parsed.globalConstraints.every((c) => typeof c === "string" && c.length > 0)
+    )
+  ) {
+    errors.push("globalConstraints: must be an array of non-empty strings if present");
+  }
+
   // approved=false requires userFeedback
   if (errors.length === 0 && parsed.approved === false) {
     if (typeof parsed.userFeedback !== "string" || parsed.userFeedback.length === 0) {
@@ -189,6 +318,45 @@ async function main() {
     errors.push(...found.contradictions);
   }
 
+  const spec = specPath();
+  if (spec) {
+    let specChars = 0;
+    let specText = "";
+    try {
+      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`,
+      );
+    }
+  }
+
   if (errors.length > 0) {
     emit({ ok: false, code: 1, errors, warnings, overlaps });
     process.exitCode = 1;

package/pipeline/scripts/validate-reviewer.mjs

@@ -264,6 +264,26 @@ async function main() {
     errors.push("approved must be boolean");
   }
 
+  // Requirements the diff cannot show: they live in code the change did not touch.
+  if (parsed.cannotVerify !== undefined) {
+    if (!Array.isArray(parsed.cannotVerify)) {
+      errors.push("cannotVerify must be an array when present");
+    } else {
+      parsed.cannotVerify.forEach((row, i) => {
+        const label = `cannotVerify[${i}]`;
+        if (typeof row?.requirement !== "string" || row.requirement.trim().length < 4) {
+          errors.push(`${label}: requirement must name what could not be verified`);
+        }
+        if (typeof row?.where !== "string" || !row.where.trim()) {
+          errors.push(`${label}: where must name the unchanged file or symbol`);
+        }
+        if (typeof row?.why !== "string" || row.why.trim().length < 4) {
+          errors.push(`${label}: why must say what the diff does not show`);
+        }
+      });
+    }
+  }
+
   // Conformance checklist, only when the orchestrator supplied criteria.
   const critIdx = process.argv.indexOf("--criteria");
   if (critIdx !== -1) {