@mmerterden/multi-agent-pipeline 20.2.1 → 20.3.0

package/pipeline/scripts/capture-resume.sh

@@ -25,7 +25,11 @@ set -uo pipefail
 JSON=0
 [ "${1:-}" = "--json" ] && JSON=1
 
-LOGS="$HOME/.claude/logs/multi-agent"
+_MA_CR_HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+if [ -f "$_MA_CR_HERE/../lib/user-facing.sh" ]; then . "$_MA_CR_HERE/../lib/user-facing.sh"; else . "$HOME/.claude/lib/user-facing.sh"; fi
+
+LOGS="${LOGS_ROOT:-$HOME/.claude/logs/multi-agent}"
 PIPELINE_MEM="$HOME/.claude/memory/multi-agent/_pipeline"
 REVIEW_DAYS=7
 
@@ -131,19 +135,19 @@ fi
 # "13 runs" call for different reactions and the old line could not tell them
 # apart.
 if [ "$AWAITING_N" -gt 0 ]; then
-  printf 'multi-agent: %s run(s) waiting on you, oldest %s at Phase %s - `/multi-agent:resume` to finish.\n' \
-    "$AWAITING_N" "$AWAITING_TASK" "$AWAITING_PHASE"
+  printf 'multi-agent: %s run(s) waiting on you, oldest %s at Phase %s - `%s` to finish.\n' \
+    "$AWAITING_N" "$AWAITING_TASK" "$AWAITING_PHASE" "$(ma_command resume)"
 fi
 if [ "$DIED_N" -gt 0 ]; then
-  printf 'multi-agent: %s run(s) stopped mid-development, oldest %s at Phase %s - `/multi-agent:resume` or `/multi-agent:kill`.\n' \
-    "$DIED_N" "$DIED_TASK" "$DIED_PHASE"
+  printf 'multi-agent: %s run(s) stopped mid-development, oldest %s at Phase %s - `%s` or `%s`.\n' \
+    "$DIED_N" "$DIED_TASK" "$DIED_PHASE" "$(ma_command resume)" "$(ma_command kill)"
 fi
 if [ "$UNSTARTED_N" -gt 0 ]; then
-  printf 'multi-agent: %s run(s) left at a Phase 0 question, nothing built - `/multi-agent:garbage-collect --abandoned` to clear.\n' \
-    "$UNSTARTED_N"
+  printf 'multi-agent: %s run(s) left at a Phase 0 question, nothing built - `%s --abandoned` to clear.\n' \
+    "$UNSTARTED_N" "$(ma_command garbage-collect)"
 fi
 if [ "$REVIEW_DUE" -eq 1 ]; then
-  printf 'multi-agent: %s open pipeline observation(s), last review %s+ days ago - `/multi-agent:refactor backlog` when convenient.\n' \
-    "$OPEN_OBS" "$REVIEW_DAYS"
+  printf 'multi-agent: %s open pipeline observation(s), last review %s+ days ago - `%s backlog` when convenient.\n' \
+    "$OPEN_OBS" "$REVIEW_DAYS" "$(ma_command refactor)"
 fi
 exit 0

package/pipeline/scripts/check-derived-drift.mjs

@@ -69,6 +69,48 @@ function versionFrom(manifest, pluginName) {
   return manifest.version ?? null;
 }
 
+function fetchAge(root) {
+  try {
+    const fetchHead = join(root, ".git", "FETCH_HEAD");
+    return existsSync(fetchHead)
+      ? Math.floor((Date.now() - statSync(fetchHead).mtimeMs) / 86_400_000)
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+// An upstream that ships no manifest (an app repo whose standards live in a
+// few directories) is versioned by commit. The recorded version is the commit
+// the port was taken from; drift is any later commit on the ref that touches
+// one of the named paths, so unrelated app commits never count.
+function fromGitPaths(entry) {
+  if (!entry.upstreamLocalClone || !Array.isArray(entry.upstreamPaths)) return null;
+  const root = expandHome(entry.upstreamLocalClone);
+  const ref = entry.upstreamRef || "origin/main";
+  const git = (...args) =>
+    execFileSync("git", ["-C", root, ...args], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  try {
+    const recorded = git("rev-parse", "--verify", `${entry.derivedFromVersion}^{commit}`);
+    const later = git("rev-list", "--count", `${recorded}..${ref}`, "--", ...entry.upstreamPaths);
+    const version =
+      Number(later) === 0
+        ? entry.derivedFromVersion
+        : git("log", "-1", "--format=%h", ref, "--", ...entry.upstreamPaths);
+    return {
+      version,
+      source: `local clone ${ref}`,
+      authoritative: true,
+      fetchAgeDays: fetchAge(root),
+    };
+  } catch {
+    return null;
+  }
+}
+
 function fromLocalClone(entry) {
   if (!entry.upstreamLocalClone) return null;
   const root = expandHome(entry.upstreamLocalClone);
@@ -89,16 +131,12 @@ function fromLocalClone(entry) {
     if (version) {
       // origin/main is only as fresh as the last fetch. Surface fetch age so a
       // months-old ref is not silently trusted.
-      let fetchAgeDays = null;
-      try {
-        const fetchHead = join(root, ".git", "FETCH_HEAD");
-        if (existsSync(fetchHead)) {
-          fetchAgeDays = Math.floor((Date.now() - statSync(fetchHead).mtimeMs) / 86_400_000);
-        }
-      } catch {
-        fetchAgeDays = null;
-      }
-      return { version, source: "local clone origin/main", authoritative: true, fetchAgeDays };
+      return {
+        version,
+        source: "local clone origin/main",
+        authoritative: true,
+        fetchAgeDays: fetchAge(root),
+      };
     }
   } catch {
     // No origin/main ref (not a git checkout, or unfetched): fall through to
@@ -163,7 +201,10 @@ if (entries.length === 0) {
 
 const rows = [];
 for (const entry of entries) {
-  const resolved = fromLocalClone(entry) || fromRepoApi(entry) || fromCache(entry);
+  const resolved =
+    entry.upstreamVersionSource === "git-paths"
+      ? fromGitPaths(entry)
+      : fromLocalClone(entry) || fromRepoApi(entry) || fromCache(entry);
   if (!resolved) {
     rows.push({
       label: entry.label,

package/pipeline/scripts/commands.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * @file commands.mjs  -  the command catalog a client renders from.
+ *
+ * Prints every /multi-agent:<id> command with its declared parameters, its
+ * surface (button, form, hidden) and whether it needs a confirmation, read from
+ * the SKILL.md frontmatter by the same reader lint-skills.mjs holds to the
+ * contract. Shape: pipeline/schemas/command-parameters.schema.json.
+ *
+ * Nothing in the catalog is machine- or person-specific, so `--redact` is
+ * accepted for symmetry with the other contract outputs and changes nothing.
+ *
+ * Usage:
+ *   node commands.mjs --json [--redact] [--dir <commandsDir>]
+ *
+ * The directory defaults to the source tree beside this script, then to the
+ * installed copy under ~/.claude/commands/multi-agent.
+ *
+ * Exit: 0 printed, 2 usage error or no command tree found.
+ *
+ * @module pipeline/scripts/commands
+ */
+
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CONTRACT_VERSION, loadCatalog } from "./_command-contract.mjs";
+import { runMain } from "../lib/fatal.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+
+export function commandsDir(explicit) {
+  if (explicit) return explicit;
+  const here = fileURLToPath(new URL(".", import.meta.url));
+  for (const cand of [
+    join(here, "..", "commands", "multi-agent"),
+    join(homedir(), ".claude", "commands", "multi-agent"),
+  ]) {
+    if (existsSync(cand)) return cand;
+  }
+  return null;
+}
+
+/**
+ * The catalog as printed, or null when no command tree exists. The CLI and
+ * contract-server.mjs both render this one object.
+ *
+ * @param {string|null} [dir]
+ */
+export function catalog(dir = null) {
+  const root = commandsDir(dir);
+  if (!root || !existsSync(root)) return null;
+  return { contractVersion: CONTRACT_VERSION, commands: loadCatalog(root) };
+}
+
+function main(argv) {
+  let json = false;
+  let dir = null;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--json") json = true;
+    else if (a === "--redact") continue;
+    else if (a === "--dir") dir = argv[++i];
+    else {
+      process.stderr.write(`commands: unknown argument ${a}\n`);
+      return 2;
+    }
+  }
+  const out = catalog(dir);
+  if (!out) {
+    process.stderr.write("commands: no command tree found\n");
+    return 2;
+  }
+  if (json) process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+  else {
+    for (const c of out.commands) {
+      const mark = c.destructive ? " (destructive)" : "";
+      process.stdout.write(`${c.id.padEnd(24)} ${c.gui.padEnd(7)} ${c.argumentHint}${mark}\n`);
+    }
+  }
+  return 0;
+}
+
+if (invokedDirectly(import.meta.url)) {
+  runMain("commands", () => {
+    process.exitCode = main(process.argv.slice(2));
+  });
+}

package/pipeline/scripts/constitution.mjs

@@ -0,0 +1,362 @@
+#!/usr/bin/env node
+/**
+ * constitution.mjs  -  where a project's constitution lives, what makes one
+ * valid, and which repository files it may be derived from.
+ *
+ * A constitution is the short list of rules every requirement and task of one
+ * project is held to: security, accessibility, architecture, licensing. The
+ * analysis flow writes it (multi-agent-refs/features/constitution.md) as
+ * `constitution.md` for people and `constitution.json` for
+ * spec-consistency-gate.mjs, in the project's knowledge store beside
+ * code-graph.json: ~/.claude/knowledge/<project>/. `<project>` is the main
+ * checkout's directory name, resolved through git's common dir so a linked
+ * worktree finds the same file; a run with no repository keys it on the
+ * analysis name.
+ *
+ * Every rule carries one source with the research engine's labels
+ * (multi-agent-refs/research/engine.md): `repo` cites a file in the
+ * repository, `evidence` a fetched document or tracker item, `inference` a
+ * one-line rationale. An inference-sourced rule is proposed and never binding:
+ * reasoning can suggest a rule, only a source or a person can make one.
+ *
+ * Usage:
+ *   constitution.mjs path     [--repo <dir>] [--feature <name>]
+ *   constitution.mjs check    <constitution.json> [--repo <dir>] [--json]
+ *   constitution.mjs evidence --repo <dir> [--json]
+ *
+ * Exit: 0 ok / valid · 1 invalid (check) or no path resolvable (path) · 2 usage · 3 unreadable
+ *
+ * @module pipeline/scripts/constitution
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join } from "node:path";
+
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { resolveStack } from "./_stack-adapter.mjs";
+
+export const CATEGORY_PREFIX = Object.freeze({
+  security: "SEC",
+  accessibility: "A11Y",
+  architecture: "ARCH",
+  licensing: "LIC",
+});
+export const LABELS = ["evidence", "repo", "inference"];
+export const STATUSES = ["binding", "proposed"];
+export const RULE_ID = /^CON-(SEC|A11Y|ARCH|LIC)-\d{2,3}$/;
+export const FILE_NAME = "constitution.json";
+
+/**
+ * The knowledge-store key of the repository at `dir`: the main checkout's
+ * directory name, the same from every linked worktree. Null outside git.
+ *
+ * @param {string} dir
+ * @returns {string|null}
+ */
+export function projectName(dir) {
+  if (!dir || !existsSync(dir)) return null;
+  const r = spawnSync(
+    "git",
+    ["-C", dir, "rev-parse", "--path-format=absolute", "--git-common-dir"],
+    {
+      encoding: "utf8",
+      timeout: 20000,
+    },
+  );
+  if (r.status !== 0) return null;
+  let common = r.stdout.trim();
+  try {
+    common = realpathSync(common);
+  } catch {
+    return null;
+  }
+  return basename(common) === ".git"
+    ? basename(dirname(common))
+    : basename(common).replace(/\.git$/, "");
+}
+
+/** The analysis name as a directory name. */
+export function slug(name) {
+  return String(name)
+    .toLowerCase()
+    .replace(/ı/g, "i")
+    .normalize("NFKD")
+    .replace(/[̀-ͯ]/g, "")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+/**
+ * Where the constitution of a repository, or of a repo-less analysis, lives.
+ *
+ * @param {{repo?: string|null, feature?: string|null, home?: string}} [opts]
+ * @returns {string|null}
+ */
+export function constitutionPath({ repo = null, feature = null, home = homedir() } = {}) {
+  const project = (repo && projectName(repo)) || (feature ? slug(feature) : "") || null;
+  return project ? join(home, ".claude", "knowledge", project, FILE_NAME) : null;
+}
+
+function parseRef(ref) {
+  const m = String(ref).match(/^(.*?)(?::(\d+))?$/);
+  return { file: m[1], line: m[2] ? Number(m[2]) : null };
+}
+
+function checkRepoRef(id, ref, repo, errors) {
+  const { file, line } = parseRef(ref);
+  if (!file || isAbsolute(file) || file.split("/").includes("..")) {
+    errors.push(`${id}: repo ref "${ref}" is not a path inside the repository`);
+    return;
+  }
+  const full = join(repo, file);
+  if (!existsSync(full)) {
+    errors.push(`${id}: repo ref "${ref}" names a file the repository does not have`);
+    return;
+  }
+  if (line !== null) {
+    let count;
+    try {
+      count = readFileSync(full, "utf8").split("\n").length;
+    } catch {
+      errors.push(`${id}: repo ref "${ref}" is not a readable file`);
+      return;
+    }
+    if (line < 1 || line > count)
+      errors.push(`${id}: repo ref "${ref}" is past the end of the file`);
+  }
+}
+
+/**
+ * Structural validity, plus with `repo` that every repo-labelled ref resolves.
+ *
+ * @param {object} doc
+ * @param {{repo?: string|null}} [opts]
+ * @returns {{ok: boolean, errors: string[], rules: object[]}}
+ */
+export function checkConstitution(doc, { repo = null } = {}) {
+  const errors = [];
+  if (!doc || typeof doc !== "object" || Array.isArray(doc)) {
+    return { ok: false, errors: ["the constitution is not a JSON object"], rules: [] };
+  }
+  if (doc.version !== 1) errors.push(`version must be 1, got ${JSON.stringify(doc.version)}`);
+  if (!Array.isArray(doc.rules)) {
+    errors.push("rules must be an array");
+    return { ok: false, errors, rules: [] };
+  }
+  const seen = new Set();
+  doc.rules.forEach((r, i) => {
+    const id = typeof r?.id === "string" ? r.id : `rules[${i}]`;
+    if (!RULE_ID.test(r?.id ?? "")) {
+      errors.push(`${id}: id must match CON-<SEC|A11Y|ARCH|LIC>-NN`);
+    } else if (seen.has(r.id)) {
+      errors.push(`duplicate rule id ${r.id}`);
+    }
+    seen.add(r?.id);
+    const prefix = CATEGORY_PREFIX[r?.category];
+    if (!prefix) {
+      errors.push(`${id}: category must be one of ${Object.keys(CATEGORY_PREFIX).join(", ")}`);
+    } else if (RULE_ID.test(r.id) && r.id.split("-")[1] !== prefix) {
+      errors.push(`${id}: the id prefix does not match category ${r.category} (CON-${prefix}-NN)`);
+    }
+    if (typeof r?.text !== "string" || !r.text.trim()) errors.push(`${id}: text is empty`);
+    const label = r?.source?.label;
+    const ref = r?.source?.ref;
+    if (!LABELS.includes(label))
+      errors.push(`${id}: source.label must be one of ${LABELS.join(", ")}`);
+    if (typeof ref !== "string" || !ref.trim()) errors.push(`${id}: source.ref is empty`);
+    if (!STATUSES.includes(r?.status)) {
+      errors.push(`${id}: status must be one of ${STATUSES.join(", ")}`);
+    } else if (label === "inference" && r.status !== "proposed") {
+      errors.push(`${id}: an inference-sourced rule is proposed, never ${r.status}`);
+    }
+    if (label === "repo" && doc.greenfield === true) {
+      errors.push(`${id}: a greenfield constitution has no repository to cite`);
+    } else if (label === "repo" && repo && typeof ref === "string" && ref.trim()) {
+      checkRepoRef(id, ref.trim(), repo, errors);
+    }
+  });
+  return { ok: errors.length === 0, errors, rules: doc.rules };
+}
+
+/**
+ * The constitution a gate should read. An explicit path must exist; the default
+ * location may be empty, which is a constitution that does not exist yet.
+ *
+ * @param {{explicit?: string|null, repo?: string|null, feature?: string|null, home?: string}} opts
+ * @returns {{path: string|null, doc: object|null, error: string|null}}
+ */
+export function resolveConstitution({ explicit = null, repo = null, feature = null, home } = {}) {
+  const path = explicit || constitutionPath({ repo, feature, home });
+  if (!path || (!explicit && !existsSync(path))) return { path: null, doc: null, error: null };
+  let doc;
+  try {
+    doc = JSON.parse(readFileSync(path, "utf8"));
+  } catch (err) {
+    return { path, doc: null, error: `constitution ${path} is unreadable: ${err.message}` };
+  }
+  const { errors } = checkConstitution(doc);
+  if (errors.length) {
+    return { path, doc: null, error: `constitution ${path} is invalid: ${errors.join("; ")}` };
+  }
+  return { path, doc, error: null };
+}
+
+const LICENSES = [
+  [/GNU AFFERO GENERAL PUBLIC LICENSE/i, "AGPL-3.0"],
+  [/GNU LESSER GENERAL PUBLIC LICENSE/i, "LGPL"],
+  [/GNU GENERAL PUBLIC LICENSE[\s\S]*Version 3/i, "GPL-3.0"],
+  [/GNU GENERAL PUBLIC LICENSE[\s\S]*Version 2/i, "GPL-2.0"],
+  [/Apache License[\s\S]*Version 2\.0/i, "Apache-2.0"],
+  [/Mozilla Public License[\s\S]*2\.0/i, "MPL-2.0"],
+  [/^\s*MIT License/i, "MIT"],
+  [/^\s*ISC License/i, "ISC"],
+  [/BSD \d-Clause|Redistribution and use in source and binary forms/i, "BSD"],
+  [/This is free and unencumbered software released into the public domain/i, "Unlicense"],
+];
+const LICENSE_FILES = ["LICENSE", "LICENSE.md", "LICENSE.txt", "COPYING"];
+const INSTRUCTION_FILES = [
+  "CLAUDE.md",
+  "AGENTS.md",
+  ".github/copilot-instructions.md",
+  "SECURITY.md",
+];
+const LINT_FILES = [
+  ".swiftlint.yml",
+  ".swiftformat",
+  ".eslintrc",
+  ".eslintrc.json",
+  ".eslintrc.js",
+  ".eslintrc.cjs",
+  ".eslintrc.yml",
+  "eslint.config.js",
+  "eslint.config.mjs",
+  "eslint.config.cjs",
+  "eslint.config.ts",
+  "biome.json",
+  ".stylelintrc.json",
+  "detekt.yml",
+  "config/detekt/detekt.yml",
+  ".editorconfig",
+  "ruff.toml",
+  ".ruff.toml",
+  ".flake8",
+  ".golangci.yml",
+  ".golangci.yaml",
+  "clippy.toml",
+  ".rubocop.yml",
+];
+
+function licenseOf(text) {
+  const head = text.slice(0, 4000);
+  return LICENSES.find(([re]) => re.test(head))?.[1] ?? null;
+}
+
+/**
+ * The repository files a rule labelled `repo` may cite, found by name at fixed
+ * places, never by a tree walk: license, agent instructions, lint and format
+ * configs, and the stack manifest the adapter table resolved.
+ *
+ * @param {string} dir
+ * @returns {{kind: "license"|"instructions"|"lint"|"stack", file: string, detail: string|null}[]}
+ */
+export function repoEvidence(dir) {
+  const out = [];
+  for (const f of LICENSE_FILES) {
+    const p = join(dir, f);
+    if (!existsSync(p)) continue;
+    let detail = null;
+    try {
+      detail = licenseOf(readFileSync(p, "utf8"));
+    } catch {
+      /* listed without a detail */
+    }
+    out.push({ kind: "license", file: f, detail });
+  }
+  for (const f of INSTRUCTION_FILES) {
+    if (existsSync(join(dir, f))) out.push({ kind: "instructions", file: f, detail: null });
+  }
+  const rulesDir = join(dir, ".claude", "rules");
+  if (existsSync(rulesDir)) {
+    for (const f of readdirSync(rulesDir)
+      .filter((n) => n.endsWith(".md"))
+      .sort()) {
+      out.push({ kind: "instructions", file: `.claude/rules/${f}`, detail: null });
+    }
+  }
+  for (const f of LINT_FILES) {
+    if (existsSync(join(dir, f))) out.push({ kind: "lint", file: f, detail: null });
+  }
+  const stack = resolveStack(dir);
+  for (const a of stack.adapters) {
+    const why = stack.coarse.why.match(new RegExp(`(?:^|\\s)${a.id}<-(\\S+)`));
+    const plus = a.evidence.split(" + ").find((e) => !e.startsWith("stack-detect:"));
+    out.push({ kind: "stack", file: plus || why?.[1] || "", detail: a.id });
+  }
+  return out;
+}
+
+function main(argv) {
+  const mode = argv[0];
+  const flag = (name) => {
+    const i = argv.indexOf(name);
+    return i === -1 ? undefined : argv[i + 1];
+  };
+  const json = argv.includes("--json");
+  if (mode === "path") {
+    const p = constitutionPath({
+      repo: flag("--repo") ?? null,
+      feature: flag("--feature") ?? null,
+    });
+    if (!p) {
+      process.stderr.write("constitution: no repository and no --feature, so there is no path\n");
+      return 1;
+    }
+    writeFileSync(1, `${p}\n`);
+    return 0;
+  }
+  if (mode === "check") {
+    const file = argv[1];
+    if (!file || file.startsWith("--")) {
+      process.stderr.write("usage: constitution.mjs check <constitution.json> [--repo <dir>]\n");
+      return 2;
+    }
+    let doc;
+    try {
+      doc = JSON.parse(readFileSync(file, "utf8"));
+    } catch (err) {
+      process.stderr.write(`constitution: cannot read ${file}: ${err.message}\n`);
+      return 3;
+    }
+    const r = checkConstitution(doc, { repo: flag("--repo") ?? null });
+    if (json) writeFileSync(1, `${JSON.stringify({ ok: r.ok, errors: r.errors }, null, 2)}\n`);
+    else if (r.ok) writeFileSync(1, `constitution: ${r.rules.length} rule(s), valid\n`);
+    else writeFileSync(2, `${r.errors.map((e) => `constitution: ${e}`).join("\n")}\n`);
+    return r.ok ? 0 : 1;
+  }
+  if (mode === "evidence") {
+    const dir = flag("--repo");
+    if (!dir) {
+      process.stderr.write("usage: constitution.mjs evidence --repo <dir> [--json]\n");
+      return 2;
+    }
+    const ev = repoEvidence(dir);
+    if (json) writeFileSync(1, `${JSON.stringify(ev, null, 2)}\n`);
+    else {
+      writeFileSync(
+        1,
+        `${ev.map((e) => `${e.kind.padEnd(12)} ${e.file}${e.detail ? `  (${e.detail})` : ""}`).join("\n")}\n`,
+      );
+    }
+    return 0;
+  }
+  process.stderr.write(
+    "usage: constitution.mjs path|check|evidence [--repo <dir>] [--feature <name>] [--json]\n",
+  );
+  return 2;
+}
+
+if (invokedDirectly(import.meta.url)) {
+  process.exitCode = main(process.argv.slice(2));
+}