@mmerterden/multi-agent-pipeline 14.2.2 → 15.0.0

package/pipeline/scripts/uninstall.mjs

@@ -35,9 +35,20 @@
  * @module pipeline/scripts/runtime/uninstall
  */
 
-import { existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import {
+  chmodSync,
+  existsSync,
+  lstatSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "fs";
 import { execFileSync } from "child_process";
-import { join } from "path";
+import { join, dirname } from "path";
 import { homedir } from "os";
 import { pathToFileURL } from "url";
 import { createInterface } from "readline";
@@ -100,6 +111,43 @@ const adapterTarget = (() => {
   return raw ? raw.slice("--target=".length) : process.cwd();
 })();
 
+/**
+ * tmp + rename, preserving a symlinked target and the existing file mode.
+ *
+ * Duplicated from install/_common.mjs rather than imported: this script runs
+ * standalone from ~/.claude/scripts, where the install tree does not exist.
+ * A plain writeFileSync could leave the host's settings.json truncated on a
+ * crash; a naive rename would replace a dotfiles symlink with a regular file
+ * and reset a 0600 file to 0644.
+ *
+ * @param {string} path
+ * @param {string} content
+ */
+function atomicWrite(path, content) {
+  let target = path;
+  try {
+    if (lstatSync(path).isSymbolicLink()) target = realpathSync(path);
+  } catch {
+    // Missing file: nothing to preserve.
+  }
+  let mode;
+  try {
+    mode = statSync(target).mode & 0o777;
+  } catch {
+    mode = undefined;
+  }
+  const tmp = `${target}.tmp-${process.pid}`;
+  writeFileSync(tmp, content);
+  if (mode !== undefined) {
+    try {
+      chmodSync(tmp, mode);
+    } catch {
+      // Best effort: a failed chmod must not lose the write.
+    }
+  }
+  renameSync(tmp, target);
+}
+
 /**
  * Report a planned action. Always logged; in --dry-run mode, no side effects
  * are performed.
@@ -197,10 +245,7 @@ function deregisterCodexMcpServer() {
  */
 function deregisterClaudeMcpServer() {
   const localBin = join(homedir(), ".local", "bin", "claude");
-  deregisterMcpServer("claude", existsSync(localBin) ? localBin : undefined, [
-    "--scope",
-    "user",
-  ]);
+  deregisterMcpServer("claude", existsSync(localBin) ? localBin : undefined, ["--scope", "user"]);
 }
 
 /**
@@ -220,6 +265,104 @@ function deregisterCopilotMcpServer() {
  * @param {string} parent
  * @param {(name: string) => boolean} predicate
  */
+/**
+ * Remove the pipeline's command namespace while preserving user-authored
+ * local-only alias wrappers (frontmatter `local-only: true`). Those wrappers
+ * exist ONLY under the host dir - install/claude.mjs snapshots them across its
+ * wipe for the same reason - so removing the namespace wholesale would destroy
+ * content a reinstall can never bring back.
+ * @param {string} cmdDir - e.g. ~/.claude/commands/multi-agent
+ * @returns {number} preserved wrapper dirs
+ */
+function rmCommandsPreservingLocalOnly(cmdDir) {
+  // An install interrupted between its wipe and its restore leaves wrappers in
+  // a hidden stash beside the namespace. Adopt them back before deciding what
+  // to preserve, or the "local-only wrappers preserved" promise below strands
+  // them in a dot-directory the user never sees.
+  const stashDir = join(dirname(cmdDir), ".multi-agent-wrapper-stash");
+  if (existsSync(stashDir) && !dryRun) {
+    for (const name of readdirSync(stashDir)) {
+      const to = join(cmdDir, name);
+      if (existsSync(to)) continue;
+      try {
+        renameSync(join(stashDir, name), to);
+        console.log(`    recovered stashed wrapper from an interrupted install: ${name}`);
+      } catch {
+        /* best effort - a failed recovery must not block the uninstall */
+      }
+    }
+    rmIfExists(stashDir);
+  }
+  if (!existsSync(cmdDir)) return 0;
+  const isLocalOnly = (dir) => {
+    const skill = join(dir, "SKILL.md");
+    try {
+      return existsSync(skill) && /^local-only:\s*true\s*$/m.test(readFileSync(skill, "utf-8"));
+    } catch {
+      return false;
+    }
+  };
+  const preserved = readdirSync(cmdDir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && isLocalOnly(join(cmdDir, e.name)))
+    .map((e) => e.name);
+  if (preserved.length === 0) {
+    rmIfExists(cmdDir);
+    return 0;
+  }
+  for (const entry of readdirSync(cmdDir)) {
+    if (preserved.includes(entry)) continue;
+    rmIfExists(join(cmdDir, entry));
+  }
+  console.log(
+    `    preserved ${preserved.length} local-only alias wrapper(s): ${preserved.join(", ")}`,
+  );
+  return preserved.length;
+}
+
+/** Written by install/_platform-filter.mjs beside the skills it delivered. */
+const EXTERNAL_SKILLS_MANIFEST = ".external-skills-manifest.json";
+
+/**
+ * Remove the external skill catalog THIS install delivered, read from the
+ * manifest the installer wrote beside it.
+ *
+ * Deliberately not derived from `.skills-index.json`: that file is the shipped
+ * catalog copied verbatim, so it lists platform-filtered skills that were never
+ * installed, and it says nothing about which package version's tree is on disk.
+ * Either gap would delete a user-authored skill dir that happens to share a
+ * catalog name. Same contract as `.plugin-skills-manifest.json`.
+ *
+ * No manifest (a pre-manifest install) means ours and theirs are
+ * indistinguishable, so nothing is removed and the user is told why.
+ *
+ * @param {string} skillsDir
+ * @returns {number} dirs removed
+ */
+function rmExternalDeliveredSkills(skillsDir) {
+  if (!existsSync(skillsDir)) return 0;
+  const manifestPath = join(skillsDir, EXTERNAL_SKILLS_MANIFEST);
+  let names = null;
+  if (existsSync(manifestPath)) {
+    try {
+      const parsed = JSON.parse(readFileSync(manifestPath, "utf-8"));
+      if (Array.isArray(parsed)) names = new Set(parsed);
+    } catch {
+      names = null;
+    }
+  }
+  if (!names) {
+    console.log(
+      `    note: no ${EXTERNAL_SKILLS_MANIFEST} under ${skillsDir} - external skill dirs left in ` +
+        `place (cannot tell pipeline-delivered from user-authored; re-run install once, then uninstall)`,
+    );
+    return 0;
+  }
+  let n = rmMatchingDirs(skillsDir, (name) => names.has(name));
+  n += rmMatchingFiles(skillsDir, (name) => /^NOTICE-.*\.md$/.test(name));
+  rmIfExists(manifestPath);
+  return n;
+}
+
 function rmMatchingDirs(parent, predicate) {
   if (!existsSync(parent)) return 0;
   let count = 0;
@@ -364,7 +507,7 @@ function stripManagedBlock(filePath) {
           rmSync(filePath, { force: true });
           console.log(`    removed (was pipeline-only): ${filePath}`);
         } else {
-          writeFileSync(filePath, remaining + "\n");
+          atomicWrite(filePath, remaining + "\n");
           console.log(`    cleaned pipeline section: ${filePath}`);
         }
         return true;
@@ -381,7 +524,7 @@ function stripManagedBlock(filePath) {
     rmSync(filePath, { force: true });
     console.log(`    removed (was pipeline-only): ${filePath}`);
   } else {
-    writeFileSync(filePath, cleaned + "\n");
+    atomicWrite(filePath, cleaned + "\n");
     console.log(`    cleaned pipeline block from: ${filePath}`);
   }
   return true;
@@ -424,7 +567,8 @@ function cleanClaudeSettings(settingsPath) {
           (h.matcher === "Bash" || h.matcher === "Bash(git commit:*)") &&
           h.hooks?.some(
             (sub) =>
-              sub.command?.includes("pre-commit-check.sh") || sub.command?.includes("agent-guard.sh"),
+              sub.command?.includes("pre-commit-check.sh") ||
+              sub.command?.includes("agent-guard.sh"),
           )
         ),
     );
@@ -437,7 +581,7 @@ function cleanClaudeSettings(settingsPath) {
     if (dryRun) {
       report("would update", settingsPath);
     } else {
-      writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+      atomicWrite(settingsPath, JSON.stringify(settings, null, 2) + "\n");
       console.log(`    cleaned pipeline hook + env from: ${settingsPath}`);
     }
   }
@@ -497,6 +641,7 @@ export async function main() {
   );
   console.log("    - ~/.claude/CLAUDE.md (your customizations)");
   console.log("    - ~/.claude/rules/ (user-owned; installed write-if-missing, never overwritten)");
+  console.log("    - Local-only alias wrappers under commands/multi-agent/ (user-authored)");
   if (!allData) console.log("    - ~/.claude/multi-agent-preferences.json (your settings)");
   console.log("    - Your own content in copilot-instructions.md above the pipeline section");
   console.log("");
@@ -511,7 +656,7 @@ export async function main() {
     console.log("  [Claude Code] Removing...");
     deregisterClaudeMcpServer();
     const CLAUDE = join(HOME, ".claude");
-    rmIfExists(join(CLAUDE, "commands", "multi-agent"));
+    rmCommandsPreservingLocalOnly(join(CLAUDE, "commands", "multi-agent"));
     rmIfExists(join(CLAUDE, "scripts"));
     // Pipeline-managed trees the installer lays down alongside scripts/.
     rmIfExists(join(CLAUDE, "multi-agent-refs"));
@@ -538,6 +683,7 @@ export async function main() {
         name === "figma-to-component",
     );
     n += rmMatchingDirs(skills, (name) => PIPELINE_CORE_SKILL_DIRS.includes(name));
+    n += rmExternalDeliveredSkills(skills);
     if (n > 0) console.log(`    removed ${n} skill dir(s) under ${skills}`);
     rmIfExists(join(skills, ".skills-index.json"));
     rmIfExists(join(skills, "skills-index.md"));
@@ -573,6 +719,7 @@ export async function main() {
     );
     n += rmMatchingDirs(skills, (name) => PIPELINE_CORE_SKILL_DIRS.includes(name));
     n += rmPluginDeliveredSkills(skills);
+    n += rmExternalDeliveredSkills(skills);
     if (n > 0) console.log(`    removed ${n} skill dir(s) under ${skills}`);
     rmIfExists(join(skills, ".skills-index.json"));
     rmIfExists(join(skills, "skills-index.md"));

package/pipeline/scripts/validate-complaint-doc.mjs

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+// validate-complaint-doc.mjs  -  deterministic validator for an EMITTED
+// /multi-agent:complaint-analysis report (complaints/<run-name>.md).
+//
+// The complaint-analysis SKILL states its "fails the dispatch gate" invariants
+// as prose; this turns the mechanically checkable ones into a real gate so a
+// malformed or PII-leaking report is caught before it reaches Confluence,
+// Jira, or a repo working tree.
+//
+// Zero deps. Reads one markdown file (path arg or STDIN).
+//
+// Checks (ERROR = blocking exit 1; WARN = advisory, still exit 0 unless --strict):
+//   - Front-matter block with required keys (run_name, generated_at, language,
+//     complaint_count, graylog_degraded); language in {tr, en}.
+//   - Required sections present by bilingual title keyword: Summary, Triage,
+//     Complaint Details, Open Questions, Methodology, References.
+//   - Every triage-table row (a table row carrying a C-NN id) has a valid
+//     verdict token: client:<layer> | bff:<layer> | core | insufficient-evidence.
+//     Verdict tokens stay English in both languages (payload vocabulary).
+//   - Every core verdict has a matching entry in the routing section
+//     (Yönlendirme / Routing), and that section exists when any core row does.
+//   - Every client/bff verdict has a fix-plan marker (Fix plan / Geliştirme
+//     planı) in the complaint-details section (development handoff, Locked 13).
+//   - Humanizer punctuation policy: no em-dash / en-dash / ellipsis /
+//     section-sign / curly quotes anywhere.
+//   - Redaction leak scan: an email address or a 13-19 digit card-like run is
+//     an ERROR; a bare 11-digit run is a WARN (could be a numeric trx id).
+//
+// Usage:
+//   node validate-complaint-doc.mjs complaints/complaints-20260810.md
+//   cat report.md | node validate-complaint-doc.mjs -
+//   node validate-complaint-doc.mjs report.md --strict   # WARN also fails
+//
+// Exit: 0 valid, 1 invalid (or WARN under --strict), 64 usage error.
+
+import { readFileSync } from "node:fs";
+
+const REQUIRED_FM = ["run_name", "generated_at", "language", "complaint_count", "graylog_degraded"];
+
+const REQUIRED_SECTIONS = [
+  { key: "summary", any: ["Summary", "Özet", "Ozet"] },
+  { key: "triage table", any: ["Triage"] },
+  { key: "complaint details", any: ["Complaint Details", "Şikayet Detayları", "Sikayet Detaylari", "Detay"] },
+  { key: "open questions", any: ["Open Questions", "Açık Sorular", "Acik Sorular"] },
+  { key: "methodology", any: ["Methodology", "Metodoloji"] },
+  { key: "references", any: ["References", "Referanslar"] },
+];
+
+const ROUTING_KEYWORDS = ["Routing", "Yönlendirme", "Yonlendirme"];
+const FIX_PLAN_RE = /(Fix plan|Fix Plan|Geliştirme planı|Geliştirme Planı|Gelistirme plani|Gelistirme Plani)/;
+
+const VERDICT_RE =
+  /\b(client:(ios|android|web)|bff:(mobile-bff|web-bff)|core|insufficient-evidence)\b/;
+
+const BANNED_PUNCT = [
+  { ch: "—", name: "em-dash" },
+  { ch: "–", name: "en-dash" },
+  { ch: "…", name: "ellipsis" },
+  { ch: "§", name: "section-sign" },
+  { ch: "“", name: "curly-double-open" },
+  { ch: "”", name: "curly-double-close" },
+  { ch: "‘", name: "curly-single-open" },
+  { ch: "’", name: "curly-single-close" },
+];
+
+const EMAIL_RE = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/;
+const CARD_RE = /\b\d(?:[ -]?\d){12,18}\b/;
+const NATIONAL_ID_RE = /\b\d{11}\b/;
+
+function readInput() {
+  const args = process.argv.slice(2).filter((a) => a !== "--strict");
+  const arg = args[0];
+  if (!arg) {
+    console.error("usage: validate-complaint-doc.mjs <path|-> [--strict]");
+    process.exit(64);
+  }
+  if (arg === "-") return readFileSync(0, "utf-8");
+  return readFileSync(arg, "utf-8");
+}
+
+function parseFrontMatter(text) {
+  const lines = text.split("\n");
+  if (lines[0].trim() !== "---") return null;
+  const end = lines.indexOf("---", 1);
+  if (end < 0) return null;
+  const fm = {};
+  for (let i = 1; i < end; i++) {
+    const m = lines[i].match(/^([A-Za-z_][A-Za-z0-9_]*):\s*(.*)$/);
+    if (m) fm[m[1]] = m[2].trim();
+  }
+  return { fm, bodyStart: end + 1 };
+}
+
+// The routing section body: from the heading whose title contains a routing
+// keyword to the next heading of the same or shallower depth.
+function sectionBody(text, keywords) {
+  const lines = text.split("\n");
+  let start = -1;
+  let depth = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^(#{1,3})\s+(.*)$/);
+    if (!m) continue;
+    if (start < 0 && keywords.some((kw) => m[2].includes(kw))) {
+      start = i;
+      depth = m[1].length;
+      continue;
+    }
+    if (start >= 0 && m[1].length <= depth) {
+      return lines.slice(start, i).join("\n");
+    }
+  }
+  return start >= 0 ? lines.slice(start).join("\n") : null;
+}
+
+function main() {
+  const text = readInput();
+  const strict = process.argv.includes("--strict");
+  const errors = [];
+  const warns = [];
+
+  // 1. Front-matter
+  const parsed = parseFrontMatter(text);
+  if (!parsed) {
+    errors.push("missing YAML front-matter block (--- ... ---) at the top");
+  } else {
+    for (const k of REQUIRED_FM) {
+      if (!parsed.fm[k]) errors.push(`front-matter missing required key: ${k}`);
+    }
+    const lang = parsed.fm.language;
+    if (lang && lang !== "tr" && lang !== "en") {
+      errors.push(`front-matter language must be tr|en, got: ${lang}`);
+    }
+  }
+
+  // 2. Required sections (by heading keyword, bilingual)
+  const headings = text
+    .split("\n")
+    .filter((l) => /^#{1,3}\s/.test(l))
+    .map((l) => l.replace(/^#{1,3}\s/, "").trim());
+  const headingBlob = headings.join("\n");
+  for (const sec of REQUIRED_SECTIONS) {
+    if (!sec.any.some((kw) => headingBlob.includes(kw))) {
+      errors.push(`missing required section: ${sec.key}`);
+    }
+  }
+
+  // 3. Triage rows: every table row carrying a complaint id needs a verdict.
+  const rows = text.split("\n").filter((l) => /^\s*\|.*\bC-\d{2,}\b/.test(l));
+  if (rows.length === 0) {
+    errors.push("no triage rows found (expected table rows carrying C-NN complaint ids)");
+  }
+  const coreIds = [];
+  const handoffIds = [];
+  for (const row of rows) {
+    const id = (row.match(/\bC-\d{2,}\b/) || [])[0];
+    const verdict = row.match(VERDICT_RE);
+    if (!verdict) {
+      errors.push(`triage row ${id} has no valid verdict token (client:<layer> | bff:<layer> | core | insufficient-evidence)`);
+    } else if (verdict[0] === "core" && !coreIds.includes(id)) {
+      coreIds.push(id);
+    } else if (/^(client|bff):/.test(verdict[0]) && !handoffIds.includes(id)) {
+      handoffIds.push(id);
+    }
+  }
+
+  // 4. Core verdicts require the routing section, one entry per complaint.
+  if (coreIds.length > 0) {
+    const routing = sectionBody(text, ROUTING_KEYWORDS);
+    if (!routing) {
+      errors.push(`core verdict(s) ${coreIds.join(", ")} but no routing section (Yönlendirme / Routing)`);
+    } else {
+      for (const id of coreIds) {
+        if (!routing.includes(id)) {
+          errors.push(`core verdict ${id} has no entry in the routing section`);
+        }
+      }
+    }
+  }
+
+  // 4b. Client/bff verdicts require a fix-plan block under their C-NN detail
+  // subsection (development handoff, Locked 13).
+  for (const id of handoffIds) {
+    const detail = sectionBody(text, [id]);
+    if (!detail || !FIX_PLAN_RE.test(detail)) {
+      errors.push(`client/bff verdict ${id} has no fix-plan block (Fix plan / Geliştirme planı) in its detail section`);
+    }
+  }
+
+  // 5. Humanizer punctuation
+  const bodyLines = text.split("\n");
+  for (let i = 0; i < bodyLines.length; i++) {
+    for (const b of BANNED_PUNCT) {
+      if (bodyLines[i].includes(b.ch)) {
+        errors.push(`banned punctuation ${b.name} at line ${i + 1} (humanizer policy)`);
+      }
+    }
+  }
+
+  // 6. Redaction leak scan
+  for (let i = 0; i < bodyLines.length; i++) {
+    if (EMAIL_RE.test(bodyLines[i])) {
+      errors.push(`redaction leak: email address at line ${i + 1}`);
+    }
+    if (CARD_RE.test(bodyLines[i])) {
+      errors.push(`redaction leak: card-like digit run at line ${i + 1}`);
+    }
+    if (NATIONAL_ID_RE.test(bodyLines[i]) && !CARD_RE.test(bodyLines[i])) {
+      warns.push(`possible redaction leak: bare 11-digit run at line ${i + 1} (national-id-like; ignore if it is a numeric trx id)`);
+    }
+  }
+
+  // Report
+  for (const w of warns) console.error(`WARN: ${w}`);
+  for (const e of errors) console.error(`ERROR: ${e}`);
+  if (errors.length > 0) {
+    console.error(
+      `validate-complaint-doc: FAIL (${errors.length} error(s), ${warns.length} warning(s))`,
+    );
+    process.exit(1);
+  }
+  if (strict && warns.length > 0) {
+    console.error(`validate-complaint-doc: FAIL under --strict (${warns.length} warning(s))`);
+    process.exit(1);
+  }
+  console.log(`validate-complaint-doc: OK (${warns.length} warning(s))`);
+  process.exit(0);
+}
+
+main();

package/pipeline/scripts/validate-reviewer.mjs

@@ -127,8 +127,13 @@ function validateConformance(parsed, selectedIds, errors) {
         `${label} (${id}): verdict "conformant" needs the file it was checked in  -  a verdict with no evidence is an assertion`,
       );
     }
-    if (row.verdict === "not-applicable" && (typeof row.reason !== "string" || row.reason.length < 4)) {
-      errors.push(`${label} (${id}): verdict "not-applicable" needs a reason naming why the rule cannot bind`);
+    if (
+      row.verdict === "not-applicable" &&
+      (typeof row.reason !== "string" || row.reason.length < 4)
+    ) {
+      errors.push(
+        `${label} (${id}): verdict "not-applicable" needs a reason naming why the rule cannot bind`,
+      );
     }
     if (row.verdict === "violated") {
       const matched = (parsed.findings ?? []).some((f) => f?.ruleId === id);
@@ -141,7 +146,8 @@ function validateConformance(parsed, selectedIds, errors) {
   });
 
   for (const [id, count] of seen) {
-    if (count > 1) errors.push(`conformance: ruleId "${id}" appears ${count} times (expected exactly once)`);
+    if (count > 1)
+      errors.push(`conformance: ruleId "${id}" appears ${count} times (expected exactly once)`);
   }
   const missing = [...selectedIds].filter((id) => !seen.has(id));
   if (missing.length > 0) {