@mmerterden/multi-agent-pipeline 16.25.0 → 16.27.0

package/pipeline/scripts/observations.mjs

@@ -0,0 +1,347 @@
+#!/usr/bin/env node
+/**
+ * @file observations.mjs  -  the pipeline's own friction log.
+ *
+ * WHY THIS EXISTS
+ *
+ * The learnings ledger records what a run learned about a REPO. Nothing recorded
+ * what a run learned about the PIPELINE. `/multi-agent:refactor` existed, but it
+ * derived every finding from scratch on each invocation, so a friction noticed
+ * on Tuesday was gone by Wednesday unless it was fixed the same hour. Most were
+ * not, because they surface mid-task, when stopping to fix them is the wrong
+ * call.
+ *
+ * So: write it down the moment it is noticed, in the same turn, and let a review
+ * decide later.
+ *
+ * STORAGE
+ *
+ * One markdown file per observation under
+ * `$HOME/.claude/memory/multi-agent/_pipeline/observations/NNNN-slug.md`, with
+ * YAML-ish frontmatter conforming to schemas/skill-observation.schema.json.
+ *
+ * The directory listing IS the index. There is no index file, because an index
+ * is a second copy of the truth and the second copy is the one that goes stale.
+ * `scan` reads frontmatter only and never opens a body, so a queue of several
+ * hundred observations still costs a session almost nothing at startup.
+ *
+ * THE READ IS GUARDED
+ *
+ * A scan that returns nothing reports two different facts with one answer:
+ * there is nothing to find, or the question was never asked. Only the first is
+ * a finding. So `scan` counts the files by a literal path, independently of the
+ * variable the loop walks, and halts with SCAN BROKEN when the two disagree.
+ * This codebase has been bitten by exactly that shape before - a sweep whose
+ * variable expanded to one bogus name, exited non-zero, and reported "0 hits"
+ * as a clean result.
+ *
+ * Subcommands:
+ *   add     --title "..." --target <path> [--target <path>...] --area <a>
+ *             [--session "..."] [--proposes <name>] [--body "..."]
+ *             [--siblings "..."]   (default: filled from skill-siblings.mjs)
+ *   scan    [--status open] [--json]      frontmatter only, guarded
+ *   resolve --id NNNN --status <actioned|declined|superseded|parked>
+ *             [--resolution "..."] [--parked-until "..."] [--reference "..."]
+ *   stats   [--json]
+ *   path
+ *
+ * Exit codes: 0 ok | 1 usage/not-found | 3 SCAN BROKEN (never silent)
+ */
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const STORE = join(homedir(), ".claude", "memory", "multi-agent", "_pipeline");
+const OBS = join(STORE, "observations");
+
+const argv = process.argv.slice(2);
+const SUB = argv[0];
+const flags = {};
+const repeated = { target: [], proposes: [] };
+for (let i = 1; i < argv.length; i++) {
+  const a = argv[i];
+  if (!a.startsWith("--")) continue;
+  const k = a.slice(2);
+  const v = argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[++i] : "true";
+  if (k in repeated) repeated[k].push(v);
+  else flags[k] = v;
+}
+
+const die = (m, c = 1) => {
+  process.stderr.write(`ERR: ${m}\n`);
+  process.exit(c);
+};
+
+const today = () => new Date().toISOString().slice(0, 10);
+
+function slugify(s) {
+  return String(s)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, 60);
+}
+
+/**
+ * Atomically reserve the next id, returned zero-padded.
+ *
+ * A zero-byte marker created with the "wx" flag IS the claim: O_EXCL fails for
+ * the loser of a race, who takes the next number. The marker is kept rather
+ * than deleted, so a crash between reserving and writing loses a number instead
+ * of handing the same one to the next writer. Numbers are cheap; ambiguous ids
+ * are not.
+ */
+function claimId() {
+  const taken = existsSync(OBS)
+    ? readdirSync(OBS)
+        .map((f) => {
+          const m = /^\.?(\d{4})[-.]/.exec(f);
+          return m ? parseInt(m[1], 10) : 0;
+        })
+        .filter((n) => n > 0)
+    : [];
+  let n = taken.length ? Math.max(...taken) + 1 : 1;
+  for (let attempt = 0; attempt < 1000; attempt++, n++) {
+    const pad = String(n).padStart(4, "0");
+    try {
+      writeFileSync(join(OBS, `.${pad}.id`), "", { flag: "wx" });
+      return pad;
+    } catch {
+      /* lost the race for this number; take the next */
+    }
+  }
+  die("could not claim an observation id after 1000 attempts", 1);
+}
+
+/** Files in the store, by a literal path - the independent count the guard needs. */
+function listFiles() {
+  if (!existsSync(OBS)) return [];
+  return readdirSync(OBS)
+    .filter((f) => /^\d{4}-.*\.md$/.test(f))
+    .sort();
+}
+
+/**
+ * Frontmatter only. Bodies are never read: the whole point of one-file-per-
+ * observation is that a scan of hundreds of them stays cheap.
+ */
+function readFrontmatter(file) {
+  const text = readFileSync(join(OBS, file), "utf8");
+  if (!text.startsWith("---")) return null;
+  const end = text.indexOf("\n---", 3);
+  if (end === -1) return null;
+  const head = text.slice(4, end);
+  const fm = {};
+  for (const line of head.split("\n")) {
+    const m = /^([a-z_]+):\s*(.*)$/.exec(line);
+    if (!m) continue;
+    const [, k, raw] = m;
+    let v = raw.trim();
+    if (v.startsWith("[") && v.endsWith("]")) {
+      v = v
+        .slice(1, -1)
+        .split(",")
+        .map((x) => x.trim().replace(/^["']|["']$/g, ""))
+        .filter(Boolean);
+    } else {
+      v = v.replace(/^["']|["']$/g, "");
+    }
+    fm[k] = v;
+  }
+  return fm;
+}
+
+function siblingsFor(targets) {
+  const script = join(HERE, "skill-siblings.mjs");
+  if (!existsSync(script) || targets.length === 0) return "";
+  const notes = [];
+  for (const t of targets) {
+    try {
+      const out = execFileSync("node", [script, t, "--json"], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      });
+      const d = JSON.parse(out);
+      const present = d.surfaces.filter((s) => s.exists).length;
+      notes.push(`${d.name}: ${present}/${d.surfaces.length} surfaces present`);
+    } catch {
+      notes.push(`${t}: not a skill surface`);
+    }
+  }
+  return notes.join("; ");
+}
+
+if (SUB === "path") {
+  // No process.exit() after a write: stdout to a pipe is async and exiting
+  // truncates it at the buffer. Falling out of this block is safe - the blocks
+  // below all test SUB, and none of them can match "path".
+  process.stdout.write(OBS + "\n");
+  process.exitCode = 0;
+}
+
+if (SUB === "add") {
+  const title = flags.title;
+  if (!title || title === "true") die("add needs --title");
+  const targets = repeated.target;
+  if (targets.length === 0) die("add needs at least one --target");
+  const area = flags.area && flags.area !== "true" ? flags.area : "unfiled";
+
+  mkdirSync(OBS, { recursive: true });
+
+  // Claiming the number has to be ATOMIC. Two sessions can notice friction at
+  // the same moment, and this store's premise is that writing is cheap enough
+  // to do mid-task - so concurrent writers are the normal case, not an exotic
+  // one.
+  //
+  // Read-the-max-and-add-one is not atomic: eight simultaneous adds all read
+  // the same max and all wrote id 0001. The FILES did not collide, since their
+  // slugs differ, so nothing looked wrong - but `resolve --id 0001` then picks
+  // whichever the directory listing returns first and silently resolves the
+  // wrong observation.
+  const nextNum = claimId();
+
+  // The sibling answer is computed, never recalled: recollection is the faculty
+  // that produced the drift this field exists to catch.
+  const siblings =
+    flags.siblings && flags.siblings !== "true" ? flags.siblings : siblingsFor(targets);
+  if (!siblings)
+    die(
+      "siblings_checked cannot be empty - pass --siblings when the targets are not skill surfaces",
+    );
+
+  const fm = [
+    "---",
+    `id: ${nextNum}`,
+    `title: ${JSON.stringify(title)}`,
+    "status: open",
+    `target: [${targets.map((t) => JSON.stringify(t)).join(", ")}]`,
+    repeated.proposes.length
+      ? `proposes_skill: [${repeated.proposes.map((p) => JSON.stringify(p)).join(", ")}]`
+      : null,
+    `siblings_checked: ${JSON.stringify(siblings)}`,
+    `area: ${JSON.stringify(area)}`,
+    `date: ${today()}`,
+    flags.session && flags.session !== "true"
+      ? `session_context: ${JSON.stringify(flags.session)}`
+      : null,
+    "---",
+    "",
+    flags.body && flags.body !== "true" ? flags.body : "(no detail recorded)",
+    "",
+  ]
+    .filter((l) => l !== null)
+    .join("\n");
+
+  const file = `${nextNum}-${slugify(title)}.md`;
+  writeFileSync(join(OBS, file), fm);
+  process.stdout.write(JSON.stringify({ ok: true, id: nextNum, file: join(OBS, file) }) + "\n");
+  process.exitCode = 0;
+}
+
+if (SUB === "scan" || SUB === "stats") {
+  const files = listFiles();
+  const parsed = [];
+  for (const f of files) {
+    const fm = readFrontmatter(f);
+    if (fm) parsed.push({ file: f, ...fm });
+  }
+
+  // THE GUARD. Files on disk but nothing parsed means the reader is broken, not
+  // that the queue is empty - and reporting "0 open" for a broken reader is the
+  // failure mode this whole store is meant to avoid.
+  if (files.length > 0 && parsed.length === 0) {
+    process.stderr.write(
+      `SCAN BROKEN: ${files.length} observation file(s) on disk, 0 parsed.\n` +
+        `The frontmatter reader is not matching what is written. This is a defect, not an empty queue.\n`,
+    );
+    process.exit(3);
+  }
+
+  if (SUB === "stats") {
+    const byStatus = {};
+    for (const p of parsed) byStatus[p.status || "?"] = (byStatus[p.status || "?"] || 0) + 1;
+    const out = { total: parsed.length, byStatus, path: OBS };
+    process.stdout.write(
+      flags.json
+        ? JSON.stringify(out, null, 2) + "\n"
+        : `${out.total} observation(s)\n` +
+            Object.entries(byStatus)
+              .map(([k, v]) => `  ${k}: ${v}`)
+              .join("\n") +
+            "\n",
+    );
+    process.exit(0);
+  }
+
+  const want = flags.status && flags.status !== "true" ? flags.status : null;
+  const rows = want ? parsed.filter((p) => p.status === want) : parsed;
+  if (flags.json) {
+    process.stdout.write(
+      JSON.stringify({ count: rows.length, scanned: files.length, observations: rows }, null, 2) +
+        "\n",
+    );
+  } else if (rows.length === 0) {
+    process.stdout.write(
+      `no observations${want ? ` with status ${want}` : ""} (${files.length} scanned)\n`,
+    );
+  } else {
+    for (const r of rows) {
+      process.stdout.write(
+        `${r.id}  ${String(r.status).padEnd(10)} ${r.area ? `[${r.area}] ` : ""}${r.title}\n`,
+      );
+    }
+  }
+  process.exitCode = 0;
+}
+
+if (SUB === "resolve") {
+  const id = flags.id;
+  const status = flags.status;
+  if (!id || id === "true") die("resolve needs --id");
+  const allowed = ["actioned", "declined", "superseded", "parked", "open"];
+  if (!allowed.includes(status)) die(`resolve needs --status one of: ${allowed.join(", ")}`);
+  // A park with no named event is a deferral in disguise: it leaves the queue
+  // and never comes back, which is a silent decline wearing a friendlier word.
+  if (status === "parked" && (!flags["parked-until"] || flags["parked-until"] === "true")) {
+    die("parked needs --parked-until naming the event that unblocks it");
+  }
+
+  const file = listFiles().find((f) => f.startsWith(`${id}-`));
+  if (!file) die(`no observation with id ${id}`);
+  const p = join(OBS, file);
+  let text = readFileSync(p, "utf8");
+
+  const setField = (k, v) => {
+    const re = new RegExp(`^${k}:.*$`, "m");
+    // Dates go in bare, matching how `add` writes `date:`. Quoting one and not
+    // the other is how a store ends up with a reader that handles one form.
+    const bare = typeof v === "string" && /^\d{4}-\d{2}-\d{2}$/.test(v);
+    const line = `${k}: ${bare || typeof v !== "string" ? v : JSON.stringify(v)}`;
+    text = re.test(text)
+      ? text.replace(re, line)
+      : text.replace(/^status:.*$/m, (m) => `${m}\n${line}`);
+  };
+
+  text = text.replace(/^status:.*$/m, `status: ${status}`);
+  if (status !== "open") setField("resolved", today());
+  if (flags.resolution && flags.resolution !== "true") setField("resolution", flags.resolution);
+  if (flags["parked-until"] && flags["parked-until"] !== "true")
+    setField("parked_until", flags["parked-until"]);
+  if (flags.reference && flags.reference !== "true") setField("reference", flags.reference);
+  writeFileSync(p, text);
+  process.stdout.write(JSON.stringify({ ok: true, id, status, file: p }) + "\n");
+  process.exitCode = 0;
+}
+
+// Guarded by an explicit list, not by reachability. The subcommand blocks above
+// no longer exit after writing (stdout to a pipe is async, and exiting
+// truncates it), so control now falls through to here on a HANDLED subcommand
+// too - and an unguarded usage error would fire on every successful run.
+const HANDLED = new Set(["add", "scan", "stats", "resolve", "path"]);
+if (!HANDLED.has(SUB)) {
+  die("usage: observations.mjs <add|scan|resolve|stats|path> [flags]");
+}

package/pipeline/scripts/offload-ref.sh

@@ -190,6 +190,49 @@ FENCE=$(printf '%*s' "$fence_len" '' | tr ' ' '`')
 KB=$(( (BYTES + 1023) / 1024 ))
 printf '[[ref:%s]] %s  -  %s lines, %s KB, full text: %s\n' \
   "$NODE_ID" "$LABEL" "$LINES" "$KB" "${REF_FILE#"$ROOT"/}"
-printf 'Last %s lines follow. Read the file above for the rest.\n' "$TAIL_LINES"
-tail -n "$TAIL_LINES" "$BUF"
+
+# For a log, the tail IS the stub: the failure is at the bottom. For JSON it is
+# close to worthless - the last twenty lines of a 200-element array are the final
+# element and some brackets, which say nothing about the 199 above. So a payload
+# that parses as JSON gets a summary instead: field shape, outliers, and every
+# element carrying an error, with the repetition dropped.
+#
+# Everything about this is fail-open. crush-json.mjs returns its input unchanged
+# on anything that is not JSON, on any internal error, and on any result that is
+# not meaningfully smaller - so the worst case is the tail we would have printed
+# anyway.
+CRUSHER=""
+for c in "$(dirname "${BASH_SOURCE[0]:-$0}")/crush-json.mjs" "$HOME/.claude/scripts/crush-json.mjs"; do
+  [ -f "$c" ] && { CRUSHER="$c"; break; }
+done
+
+# The EXIT CODE decides, not the length. crush-json.mjs exits 0 only when it
+# actually summarised and 3 when it passed the payload through - and length is
+# useless here because command substitution strips trailing newlines, so a
+# passthrough always looks a byte or two "shorter". Reading it that way meant
+# every non-JSON payload was treated as crushed and the stub carried the whole
+# log it existed to replace.
+CRUSHED=""
+CRUSH_RC=1
+if [ -n "$CRUSHER" ] && command -v node >/dev/null 2>&1; then
+  CRUSHED=$(node "$CRUSHER" "$BUF" 2>/dev/null) || CRUSH_RC=$?
+  [ -n "$CRUSHED" ] && [ "$CRUSH_RC" = "1" ] && CRUSH_RC=0
+fi
+
+if [ "$CRUSH_RC" -eq 0 ] && [ -n "$CRUSHED" ]; then
+  printf 'Structural summary follows (errors and outliers kept). Read the file above for the rest.\n'
+  printf '%s\n' "$CRUSHED"
+  # Record what the summary saved, so the value of this path is measurable
+  # rather than asserted. A metric nobody emits is a column that reads "-"
+  # forever and quietly justifies whatever anyone wants to believe.
+  LOGGER="$(dirname "${BASH_SOURCE[0]:-$0}")/log-metric.sh"
+  [ -f "$LOGGER" ] || LOGGER="$HOME/.claude/scripts/log-metric.sh"
+  if [ -f "$LOGGER" ]; then
+    bash "$LOGGER" "${TASK_ID:-unknown}" "${PHASE:-0}" offload.crushed \
+      saved_bytes=$(( BYTES - ${#CRUSHED} )) original_bytes="$BYTES" >/dev/null 2>&1 || true
+  fi
+else
+  printf 'Last %s lines follow. Read the file above for the rest.\n' "$TAIL_LINES"
+  tail -n "$TAIL_LINES" "$BUF"
+fi
 exit 0

package/pipeline/scripts/pre-commit-check.sh

@@ -15,7 +15,26 @@ set -uo pipefail
 # fall through to the full scan. Extraction failure also falls through - the
 # only cost is an unnecessary scan, never a skipped one on a real commit.
 SCAN_UNSTAGED=0
-if [ ! -t 0 ]; then
+# --scan-file <path>: run the detectors over ONE file that git knows nothing
+# about, then exit on the result. It exists so callers outside the commit path
+# can reuse these patterns instead of copying them - learn-from-transcripts.mjs
+# runs every candidate learning through here before it can reach the ledger,
+# because a transcript is the least-redacted artefact on the machine and
+# anything mined from one has to be proven clean first.
+#
+# Copying the regexes into the caller was the alternative, and it is the shape
+# that rots: the copy stops matching a pattern this file later gains, and the
+# gap stays invisible until something leaks.
+#
+# The flag is READ here, before the hook-mode stdin read below (which blocks on
+# a stdin that never closes), and ACTED ON after scan_file is defined.
+SCAN_FILE_TARGET=""
+if [ "${1:-}" = "--scan-file" ]; then
+  SCAN_FILE_TARGET="${2:-}"
+  [ -f "$SCAN_FILE_TARGET" ] || { echo "ERR: --scan-file needs an existing path" >&2; exit 1; }
+fi
+
+if [ -z "$SCAN_FILE_TARGET" ] && [ ! -t 0 ]; then
   HOOK_INPUT="$(cat 2>/dev/null || true)"
   if [ -n "$HOOK_INPUT" ]; then
     HOOK_COMMAND=""
@@ -209,6 +228,17 @@ scan_file() {
   fi
 }
 
+if [ -n "$SCAN_FILE_TARGET" ]; then
+  is_binary "$SCAN_FILE_TARGET" && exit 0
+  scan_file "$SCAN_FILE_TARGET" "$(cat "$SCAN_FILE_TARGET" 2>/dev/null)"
+  if [ "$FOUND" -eq 1 ]; then
+    echo "" >&2
+    echo "Secret check failed on $SCAN_FILE_TARGET." >&2
+    exit 2
+  fi
+  exit 0
+fi
+
 # NUL-delimited so filenames with spaces are scanned (a space-split loop would
 # silently skip them - a secret false-negative).
 

package/pipeline/scripts/scan-agent-config.sh

@@ -85,10 +85,19 @@ for _event, entries in (t.get("hooks") or {}).items():
     for e in entries:
         for h in e.get("hooks", []):
             c = h.get("command", "")
-            # allow only: `bash $HOME/.claude/scripts/<name>` (our vetted scripts)
-            if not re.fullmatch(r'bash \$HOME/\.claude/scripts/[A-Za-z0-9._-]+', c.strip()):
+            # Allow only `bash $HOME/.claude/scripts/<name>` plus plain long
+            # flags. Flags had to be admitted because a hook that cannot take
+            # one cannot be correct: SessionEnd runs capture-flush with
+            # --if-stale, and without it every session end would re-flush a run
+            # that already finished. What stays banned is everything that could
+            # turn a flag into a second command - no spaces inside a token, no
+            # quotes, no metacharacters, and the eval/substitution check below
+            # still runs on the whole string.
+            if not re.fullmatch(
+                r'bash \$HOME/\.claude/scripts/[A-Za-z0-9._-]+(?: --[a-z0-9][a-z0-9-]*)*',
+                c.strip()):
                 bad.append(c)
-            if re.search(r'\beval\b|\$\(|`', c):
+            if re.search(r'\beval\b|\$\(|`|[;&|><]', c):
                 bad.append(c)
 print("\n".join(bad))
 PY

package/pipeline/scripts/skill-siblings.mjs

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+/**
+ * @file skill-siblings.mjs  -  every copy of one skill, resolved mechanically.
+ *
+ * WHY THIS EXISTS
+ *
+ * A command in this tree is never one file. `/multi-agent:refactor` is authored
+ * at `pipeline/commands/multi-agent/refactor/SKILL.md`, mirrored into
+ * `pipeline/skills/shared/core/multi-agent-refactor/SKILL.md`, and installed a
+ * third and fourth time into the Copilot and Codex trees by the sync chain. A
+ * fix applied to the copy that happened to be open drifts from the other three
+ * silently: nothing errors, the gates stay green, and the behaviour differs by
+ * host until someone notices months later.
+ *
+ * So "did you check the siblings?" is a question with a mechanical answer, and
+ * this prints it. observations.mjs fills its `siblings_checked` field from here
+ * rather than from a model's recollection, because recollection is exactly the
+ * faculty that produced the drift.
+ *
+ * Usage:
+ *   ./skill-siblings.mjs <path-or-name>        human-readable
+ *   ./skill-siblings.mjs <path-or-name> --json
+ *   ./skill-siblings.mjs --audit               every command, sibling status
+ *   ./skill-siblings.mjs --audit --json
+ *
+ * `<path-or-name>` takes any of: a repo-relative or absolute path to a SKILL.md,
+ * the directory holding one, a bare command name (`refactor`), or the installed
+ * form (`multi-agent-refactor`).
+ *
+ * Exit codes:
+ *   0  resolved (or: audit found every command's authored sibling present)
+ *   1  bad usage / unresolvable name
+ *   2  audit found at least one command whose in-repo sibling is missing
+ *
+ * The installed trees (Copilot, Codex) are REPORTED but never make the audit
+ * fail: they are generated by `/multi-agent:sync` and their absence means "not
+ * synced yet on this machine", which is a fact about the machine and not a
+ * defect in the repo.
+ */
+
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(HERE, "..", "..");
+const HOME = homedir();
+
+const CMD_DIR = join(ROOT, "pipeline", "commands", "multi-agent");
+const CORE_DIR = join(ROOT, "pipeline", "skills", "shared", "core");
+const COPILOT_DIR = join(HOME, ".copilot", "skills");
+const CODEX_DIR = join(HOME, ".codex", "multi-agent-refs", "commands");
+// The dispatcher is the one skill Codex installs as a SKILL: the 51 sub-commands
+// become refs there, because Codex truncates a large skills block. Resolving it
+// under the refs tree like the others reported a false "absent" - and a sibling
+// check that invents a missing copy is worse than none, since it sends the next
+// change to a path that should not exist.
+const CODEX_ROUTER = join(HOME, ".codex", "skills", "multi-agent", "SKILL.md");
+const CLAUDE_DIR = join(HOME, ".claude", "commands", "multi-agent");
+
+const argv = process.argv.slice(2);
+const JSON_OUT = argv.includes("--json");
+const AUDIT = argv.includes("--audit");
+const TARGET = argv.find((a) => !a.startsWith("--"));
+
+function die(msg, code = 1) {
+  process.stderr.write(`ERR: ${msg}\n`);
+  process.exit(code);
+}
+
+/** Every command that actually ships, read from disk at call time. */
+function commandNames() {
+  if (!existsSync(CMD_DIR)) return [];
+  return readdirSync(CMD_DIR)
+    .filter((d) => {
+      const p = join(CMD_DIR, d);
+      return statSync(p).isDirectory() && existsSync(join(p, "SKILL.md"));
+    })
+    .sort();
+}
+
+/**
+ * Reduce whatever the caller passed to a bare command name.
+ *
+ * A path is the common case (an observation records the file it was about), but
+ * the same skill arrives under four different names depending on which tree the
+ * caller was looking at, so all four forms resolve to the same answer.
+ */
+function toName(input) {
+  let s = String(input).trim();
+  if (s.endsWith("SKILL.md")) s = dirname(s);
+  s = s.replace(/\/+$/, "");
+  let name = basename(s);
+  if (name === "multi-agent" && s.includes("commands")) return "multi-agent";
+  name = name.replace(/^multi-agent-/, "");
+  return name;
+}
+
+function siblingsOf(name) {
+  const authored =
+    name === "multi-agent" ? join(CMD_DIR, "SKILL.md") : join(CMD_DIR, name, "SKILL.md");
+  const shared = join(
+    CORE_DIR,
+    name === "multi-agent" ? "multi-agent" : `multi-agent-${name}`,
+    "SKILL.md",
+  );
+  const installedName = name === "multi-agent" ? "multi-agent" : `multi-agent-${name}`;
+
+  return {
+    name,
+    surfaces: [
+      { tree: "command (authored)", path: authored, exists: existsSync(authored), inRepo: true },
+      { tree: "shared core skill", path: shared, exists: existsSync(shared), inRepo: true },
+      {
+        tree: "claude (installed)",
+        path: join(CLAUDE_DIR, name === "multi-agent" ? "SKILL.md" : join(name, "SKILL.md")),
+        exists: false,
+        inRepo: false,
+      },
+      {
+        tree: "copilot (installed)",
+        path: join(COPILOT_DIR, installedName, "SKILL.md"),
+        exists: false,
+        inRepo: false,
+      },
+      {
+        tree: "codex (installed)",
+        path: name === "multi-agent" ? CODEX_ROUTER : join(CODEX_DIR, name, "SKILL.md"),
+        exists: false,
+        inRepo: false,
+      },
+    ].map((s) => ({ ...s, exists: existsSync(s.path) })),
+  };
+}
+
+if (AUDIT) {
+  const names = commandNames();
+  if (names.length === 0) die("no commands found - the tree layout has changed", 1);
+  const rows = names.map((n) => {
+    const r = siblingsOf(n);
+    const missingRepo = r.surfaces.filter((s) => s.inRepo && !s.exists).map((s) => s.tree);
+    const missingInstalled = r.surfaces.filter((s) => !s.inRepo && !s.exists).map((s) => s.tree);
+    return { name: n, missingRepo, missingInstalled };
+  });
+  const broken = rows.filter((r) => r.missingRepo.length > 0);
+  if (JSON_OUT) {
+    process.stdout.write(JSON.stringify({ commands: names.length, broken, rows }, null, 2) + "\n");
+  } else {
+    process.stdout.write(`${names.length} command(s) checked\n`);
+    if (broken.length === 0) {
+      process.stdout.write("  every command has its authored sibling in the repo\n");
+    }
+    for (const r of broken) {
+      process.stdout.write(`  MISSING  ${r.name}: ${r.missingRepo.join(", ")}\n`);
+    }
+    const unsynced = rows.filter((r) => r.missingInstalled.length > 0).length;
+    if (unsynced > 0) {
+      process.stdout.write(
+        `  ${unsynced} command(s) not present in every installed tree (run /multi-agent:sync)\n`,
+      );
+    }
+  }
+  process.exit(broken.length > 0 ? 2 : 0);
+}
+
+if (!TARGET) die("usage: skill-siblings.mjs <path-or-name> [--json] | --audit [--json]", 1);
+
+const name = toName(TARGET);
+const result = siblingsOf(name);
+if (!result.surfaces.some((s) => s.exists)) {
+  die(`no surface found for "${TARGET}" (resolved to "${name}")`, 1);
+}
+
+if (JSON_OUT) {
+  process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+} else {
+  process.stdout.write(`${name}\n`);
+  for (const s of result.surfaces) {
+    const mark = s.exists ? "found  " : "absent ";
+    const rel = s.path.startsWith(ROOT) ? s.path.slice(ROOT.length + 1) : s.path.replace(HOME, "~");
+    process.stdout.write(`  ${mark} ${s.tree.padEnd(20)} ${rel}\n`);
+  }
+}
+// exitCode rather than process.exit(): the sibling table can be long, and
+// exiting straight after writing it truncates the write on a pipe.
+process.exitCode = 0;