@mmerterden/multi-agent-pipeline 17.3.0 → 17.5.0

package/pipeline/scripts/verify-citations.mjs

@@ -0,0 +1,428 @@
+#!/usr/bin/env node
+
+/**
+ * @file verify-citations.mjs  -  a `file:line` that nothing resolves is a guess.
+ *
+ * Two surfaces in this pipeline require a citation and neither has ever checked
+ * one. `reviewer-output.schema.json` makes `file` and `line` required on every
+ * finding; `analysis-spec.schema.json` carries `repoEvidence` entries of
+ * `{name, file, line, tag}` and `analysis/locked.md` (Locked 37) asks for
+ * `repo/file:line` on every current-behaviour row. The only check that existed
+ * was `validate-analysis-doc.mjs`'s `/:\d+\b/` - a test that the row LOOKS like
+ * a citation, satisfied by `Foo.swift:9999` in a repo with no Foo.swift.
+ *
+ * The judgement is moved out of the model and into git. A path is resolved at a
+ * commit, not on the working tree, so a run that cites a file deleted three
+ * commits ago fails instead of passing on whatever happens to be checked out.
+ *
+ * Inputs:
+ *   <file>              JSON or markdown to read. `-` reads stdin.
+ *   --repo <path>       Repository root. Default: cwd
+ *   --rev <sha>         Commit to resolve against. Default: HEAD
+ *   --worktree          Resolve against the CHECKOUT instead of a commit. For
+ *                       Phase 4, where a reviewer cites lines the dev has not
+ *                       committed yet and a commit-pinned check would call
+ *                       every one of them invented.
+ *   --json              Machine-readable report
+ *   --quiet             Exit code only
+ *
+ * Accepted shapes, detected rather than declared, so one script serves both
+ * callers and neither has to say which it is:
+ *   - reviewer output   `{findings: [{file, line, ...}]}`
+ *   - triage output     `{accepted|deferred|rejected: [{file, line, ...}]}`
+ *   - analysis spec     `{evidence: {repoEvidence: {<repo>: {buckets: ...}}}}`
+ *   - markdown          every `path/to/file.ext:123` in the prose
+ *
+ * Exit codes:
+ *   0   -  every citation resolved, or there were none to resolve
+ *   1   -  at least one citation did not resolve
+ *   2   -  the input could not be read or is not a repository
+ *   64  -  usage error
+ *
+ * @module pipeline/scripts/verify-citations
+ */
+
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import { resolve as resolvePath, sep } from "node:path";
+import { spawnSync } from "node:child_process";
+
+/**
+ * Reject a path before it reaches git.
+ *
+ * `git show <rev>:<path>` happily resolves `../` out of the tree and an
+ * absolute path against the filesystem, so a citation could name something the
+ * repository does not contain and still "resolve". The guard is here rather
+ * than in the caller because every caller would otherwise need it.
+ *
+ * @param {string} p
+ * @returns {string|null} the reason it is unsafe, or null
+ */
+export function unsafePath(p) {
+  if (!p) return "empty path";
+  if (p.startsWith("/")) return "absolute path";
+  if (p.includes("\\")) return "backslash in path";
+  const parts = p.split("/");
+  if (parts.includes("..")) return "path escapes the repository";
+  if (parts.includes(".git")) return "path reaches into .git";
+  return null;
+}
+
+/**
+ * Extensions a markdown citation may carry.
+ *
+ * A list, not a pattern, and that direction is deliberate: the cost of a
+ * missing extension is one citation going unchecked, while the cost of an open
+ * pattern is the gate failing a correct document over a hostname. Add to it
+ * when a real repository file is missed - never widen it to a wildcard.
+ *
+ * `com`, `net`, `io`, `dev`, `tr` are absent on purpose.
+ */
+export const SOURCE_EXTENSIONS = new Set([
+  "swift",
+  "kt",
+  "kts",
+  "java",
+  "m",
+  "mm",
+  "h",
+  "hpp",
+  "c",
+  "cc",
+  "cpp",
+  "js",
+  "mjs",
+  "cjs",
+  "jsx",
+  "ts",
+  "tsx",
+  "py",
+  "rb",
+  "go",
+  "rs",
+  "php",
+  "sh",
+  "bash",
+  "zsh",
+  "pl",
+  "sql",
+  "json",
+  "yml",
+  "yaml",
+  "toml",
+  "xml",
+  "plist",
+  "xcconfig",
+  "pbxproj",
+  "gradle",
+  "properties",
+  "cfg",
+  "ini",
+  "env",
+  "md",
+  "mdx",
+  "txt",
+  "csv",
+  "tsv",
+  "strings",
+  "stringsdict",
+  "html",
+  "css",
+  "scss",
+  "vue",
+  "svelte",
+  "graphql",
+  "proto",
+  "entitlements",
+  "storyboard",
+  "xib",
+  "lock",
+  "gemspec",
+  "podspec",
+]);
+
+/**
+ * Pull `{file, line}` pairs out of whatever was handed over.
+ *
+ * @param {string} raw
+ * @returns {{file: string, line: number|null, where: string}[]}
+ */
+export function extract(raw) {
+  const out = [];
+  const push = (file, line, where) => {
+    if (typeof file === "string" && file.trim()) {
+      out.push({ file: file.trim(), line: Number.isFinite(line) ? line : null, where });
+    }
+  };
+
+  let doc;
+  try {
+    doc = JSON.parse(raw);
+  } catch {
+    doc = null;
+  }
+
+  if (doc && typeof doc === "object") {
+    for (const key of ["findings", "accepted", "deferred", "rejected"]) {
+      for (const [i, f] of (doc[key] || []).entries()) {
+        if (f && typeof f === "object") push(f.file, Number(f.line), `${key}[${i}]`);
+      }
+    }
+    const repoEvidence = doc?.evidence?.repoEvidence || doc?.analysisSpec?.evidence?.repoEvidence;
+    if (repoEvidence && typeof repoEvidence === "object") {
+      for (const [repo, body] of Object.entries(repoEvidence)) {
+        for (const [bucket, rows] of Object.entries(body?.buckets || {})) {
+          for (const [i, r] of (rows || []).entries()) {
+            if (r && typeof r === "object") {
+              push(r.file, Number(r.line), `repoEvidence.${repo}.${bucket}[${i}]`);
+            }
+          }
+        }
+      }
+    }
+    return out;
+  }
+
+  // Markdown. A citation is a path with an extension followed by a line number.
+  //
+  // Two things that look exactly like one and are not:
+  //
+  //   - a URL with a port. `https://wiki.example.com:8443/x` hands
+  //     `wiki.example.com:8443` to the matcher, and an analysis document is
+  //     full of Confluence, Jira and Figma links. Left in, this gate blocked
+  //     dispatch on every real document and reported "absolute path" as the
+  //     reason, which is not even the right complaint. URLs are removed first.
+  //   - a dotted number. `v1.2:30` has an "extension" of `2`, so the extension
+  //     must START with a letter. No source file is named `.2`.
+  //
+  // Fenced blocks are skipped for the same class of reason: a code sample that
+  // happens to contain `foo.js:12` is an illustration, not a claim about this
+  // repository.
+  //
+  // The URL strip below only removes what carries a scheme. A host written
+  // bare - `wiki.example.com:8443/x`, and an analysis document is full of
+  // them - still looks exactly like a path with an extension and a line
+  // number, and this gate would fail the document over `.com`. So the
+  // extension has to be one a repository actually contains. This is the same
+  // defect that was already fixed once here for scheme-carrying URLs; the bare
+  // form survived it.
+  let fenced = false;
+  raw.split("\n").forEach((line, i) => {
+    if (/^\s*```/.test(line)) {
+      fenced = !fenced;
+      return;
+    }
+    if (fenced) return;
+    const cleaned = line.replace(/\b[a-z][a-z0-9+.-]*:\/\/\S+/gi, " ");
+    for (const m of cleaned.matchAll(/([A-Za-z0-9_./-]+\.([A-Za-z][A-Za-z0-9]*)):(\d+)/g)) {
+      if (!SOURCE_EXTENSIONS.has(m[2].toLowerCase())) continue;
+      push(m[1], Number(m[3]), `line ${i + 1}`);
+    }
+  });
+  return out;
+}
+
+/**
+ * Resolve one citation at a commit, or in the checkout when `rev` is null.
+ *
+ * @param {string} repo
+ * @param {string|null} rev
+ * @param {{file: string, line: number|null}} c
+ * @param {Map<string, number|null>} lineCache
+ * @returns {string|null} the reason it failed, or null
+ */
+export function resolveOne(repo, rev, c, lineCache) {
+  const unsafe = unsafePath(c.file);
+  if (unsafe) return unsafe;
+
+  if (!lineCache.has(c.file)) {
+    lineCache.set(c.file, rev === null ? worktreeLines(repo, c.file) : revLines(repo, rev, c.file));
+  }
+
+  const lines = lineCache.get(c.file);
+  const at = rev === null ? "in the working tree" : `at ${rev.slice(0, 12)}`;
+  if (lines === null) return `no such file ${at}`;
+  if (c.line === null) return null;
+  if (c.line < 1) return `line ${c.line} is not a line number`;
+  if (c.line > lines) return `line ${c.line} is past the end of the file (${lines} lines)`;
+  return null;
+}
+
+/**
+ * Line count of a blob at a commit, or null when the path is not a file there.
+ *
+ * @param {string} repo
+ * @param {string} rev
+ * @param {string} file
+ * @returns {number|null}
+ */
+function revLines(repo, rev, file) {
+  const t = spawnSync("git", ["-C", repo, "cat-file", "-t", `${rev}:${file}`], {
+    encoding: "utf-8",
+  });
+  if (t.status !== 0 || t.stdout.trim() !== "blob") return null;
+  const show = spawnSync("git", ["-C", repo, "show", `${rev}:${file}`], {
+    encoding: "utf-8",
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  return countLines(show.status === 0 ? show.stdout : "");
+}
+
+/**
+ * Line count in the checkout, or null when there is no such file.
+ *
+ * `unsafePath` cannot see a symlink: `docs/out -> /etc` is a relative path with
+ * no `..` in it, and git never followed it because git reads blobs rather than
+ * the filesystem. In worktree mode the filesystem IS the source, so containment
+ * is re-checked after the path is resolved.
+ *
+ * @param {string} repo
+ * @param {string} file
+ * @returns {number|null}
+ */
+function worktreeLines(repo, file) {
+  let real;
+  let root;
+  try {
+    root = realpathSync(repo);
+    real = realpathSync(resolvePath(root, file));
+  } catch {
+    return null;
+  }
+  if (real !== root && !real.startsWith(root + sep)) return null;
+  try {
+    if (!statSync(real).isFile()) return null;
+    return countLines(readFileSync(real, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A file with no trailing newline still has its last line.
+ *
+ * @param {string} text
+ * @returns {number}
+ */
+function countLines(text) {
+  if (text.length === 0) return 0;
+  return text.split("\n").length - (text.endsWith("\n") ? 1 : 0);
+}
+
+/**
+ * @param {object} params
+ * @returns {{checked: number, unresolved: object[], rev: string}}
+ */
+export function verify({ raw, repo, rev }) {
+  const citations = extract(raw);
+  const lineCache = new Map();
+  const unresolved = [];
+  for (const c of citations) {
+    const reason = resolveOne(repo, rev, c, lineCache);
+    if (reason) unresolved.push({ ...c, reason });
+  }
+  return { checked: citations.length, unresolved, rev };
+}
+
+const VALUE_FLAGS = new Set(["--repo", "--rev"]);
+
+/**
+ * One pass, positionally. `argv.indexOf(a)` finds the FIRST occurrence of a
+ * string, so `--repo . file .` would have mis-identified which `.` was the
+ * target; walking the list is both simpler and correct.
+ *
+ * @param {string[]} argv
+ * @returns {{target: string|null, repo: string|null, rev: string|null}}
+ */
+export function parseArgs(argv) {
+  let target = null;
+  let repo = null;
+  let rev = null;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (VALUE_FLAGS.has(a)) {
+      const v = argv[i + 1];
+      if (v !== undefined && !v.startsWith("--")) {
+        if (a === "--repo") repo = v;
+        else rev = v;
+        i++;
+      }
+      continue;
+    }
+    if (a.startsWith("--")) continue;
+    if (target === null) target = a;
+  }
+  return { target, repo, rev };
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const parsed = parseArgs(argv);
+  const target = parsed.target;
+  if (!target) {
+    console.error(
+      "usage: verify-citations.mjs <file|-> [--repo <path>] [--rev <sha>|--worktree] [--json] [--quiet]",
+    );
+    process.exit(64);
+  }
+
+  const repo = parsed.repo || process.cwd();
+  const worktree = argv.includes("--worktree");
+  if (worktree && parsed.rev) {
+    console.error("verify-citations: --worktree and --rev name two different trees; pick one");
+    process.exit(64);
+  }
+  const rev = parsed.rev || "HEAD";
+  const json = argv.includes("--json");
+  const quiet = argv.includes("--quiet");
+
+  let raw;
+  try {
+    raw = target === "-" ? readFileSync(0, "utf-8") : readFileSync(target, "utf-8");
+  } catch (e) {
+    console.error(`verify-citations: cannot read ${target}: ${e.message}`);
+    process.exit(2);
+  }
+
+  const top = spawnSync("git", ["-C", repo, "rev-parse", "--show-toplevel"], { encoding: "utf-8" });
+  if (top.status !== 0) {
+    console.error(`verify-citations: ${repo} is not a git repository`);
+    process.exit(2);
+  }
+  let sha = null;
+  if (!worktree) {
+    const head = spawnSync("git", ["-C", repo, "rev-parse", rev], { encoding: "utf-8" });
+    if (head.status !== 0) {
+      console.error(`verify-citations: ${rev} is not a commit in ${repo}`);
+      process.exit(2);
+    }
+    sha = head.stdout.trim();
+  }
+
+  const report = verify({ raw, repo, rev: sha });
+  const where = sha === null ? "in the working tree" : `at ${sha.slice(0, 12)}`;
+
+  if (json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else if (!quiet) {
+    if (report.unresolved.length === 0) {
+      console.log(`verify-citations: ${report.checked} citation(s) resolve ${where}`);
+    } else {
+      console.log(
+        `verify-citations: ${report.unresolved.length} of ${report.checked} citation(s) do not resolve ${where}:`,
+      );
+      for (const u of report.unresolved) {
+        console.log(`  ${u.where}: ${u.file}${u.line === null ? "" : `:${u.line}`} - ${u.reason}`);
+      }
+      // The cheap way to make this exit 0 is to delete the line number, which
+      // turns a wrong claim into an unfalsifiable one. Said here because this
+      // is the moment someone is deciding what to do about it.
+      console.log("  Re-search and correct the citation; never drop the line number to pass.");
+    }
+  }
+
+  process.exit(report.unresolved.length === 0 ? 0 : 1);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}

package/pipeline/skills/.skill-manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "1.0.0",
-  "generatedAt": "2026-09-14T11:56:29Z",
+  "generatedAt": "2026-09-15T12:49:28Z",
   "skillCount": 212,
   "entries": [
     {
@@ -237,7 +237,7 @@
     },
     {
       "path": "shared/core/multi-agent/SKILL.md",
-      "sha256": "de56a86c64f1e6f56d1d4e5f0e129f04e44c36d930caa3857dd5c46689e8e501"
+      "sha256": "faac7ceb535d18778efe0ea91c19534c8e076bc709e7b1dbc567f5e71692bbbd"
     },
     {
       "path": "shared/external/accessibility-compliance-accessibility-audit/SKILL.md",

package/pipeline/skills/shared/core/multi-agent/SKILL.md

@@ -316,7 +316,7 @@ All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is
 - `multi-agent-local`, `multi-agent-autopilot`, `multi-agent-local-autopilot`: 0 → 1 → 2 → 3 → 4 → 6 → 7 (the interactive Phase 5 gate needs a worktree checkout and an attended run)
 - `multi-agent-analysis`: 0 → 1 → 2 → 4 → 6 → 7 (no code, so no Dev and no Test)
 
-Depth does not change the SET. A Short run (the Phase 0 Step 7.5 answer) registers its command's full set and flips Phases 1 and 2 to `skipped` when the answer lands at Step 7.5 - the tracker boots at Step -1, long before the question can be asked.
+Depth decides WHICH of the command's set is registered. The tracker boots at Step -1, long before the depth question can be asked, so it registers Phase 0 alone and the remaining tiles are created at Step 7.5 once the answer is known - a Short run never draws an Analysis or Planning tile.
 
 Full contract: `refs/tracker-contract.md` section "TaskCreate ordering (strict)".