@mmerterden/multi-agent-pipeline 20.16.0 → 20.17.0

package/pipeline/scripts/explore-findings.mjs

@@ -0,0 +1,410 @@
+#!/usr/bin/env node
+/**
+ * explore-findings.mjs  -  the findings contract, budgets and stop rules of an
+ * exploratory test run, and the packet a fresh judge decides an assertion from.
+ *
+ * The model drives the app and decides what looks wrong; this script holds the
+ * parts that must not be judgement:
+ *
+ *   check --run FILE
+ *       Whether the run must stop now: the step, time or token budget is
+ *       spent, or the last three steps were blocked and reported nothing.
+ *       Prints `{stop, reason, consecutiveBlocked}`.
+ *
+ *   report --run FILE [--json]
+ *       The verdict (passed | failed | blocked), why the run ended, issues
+ *       before warnings with the most severe first, blocked steps grouped by
+ *       cause, and the findings that failed the contract. Markdown, or the
+ *       evaluation as JSON with --json.
+ *
+ *   judge-packet --assertion TEXT --evidence KIND=PATH ... [--vocabulary TEXT]
+ *       The only input a judge subagent receives: the statement, the current
+ *       evidence, and optionally the app's own vocabulary. Run history, step
+ *       summaries and the acting agent's instructions are refused.
+ *
+ *   judge-verdict --packet FILE --verdict FILE
+ *       Holds the judge's answer to the packet: passed and failed must cite
+ *       evidence that was in the packet; anything else, and `inconclusive`,
+ *       fails as ASSERTION_INCONCLUSIVE.
+ *
+ * The run file is described by pipeline/schemas/explore-run.schema.json.
+ * Exit: 0 printed, 2 usage or unreadable input.
+ */
+
+import { readFileSync, realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { runMain } from "../lib/fatal.mjs";
+
+export const BUDGET_DEFAULTS = Object.freeze({ steps: 8, minutes: 10, tokens: 150000 });
+export const BUDGET_LIMITS = Object.freeze({
+  steps: [1, 12],
+  minutes: [3, 15],
+  tokens: [20000, 400000],
+});
+export const STUCK_AFTER = 3;
+
+export const SEVERITY_WORDS = { 5: "critical", 4: "high", 3: "medium", 2: "low", 1: "trivial" };
+
+const BLOCKED_CAUSE = {
+  CREDENTIAL_MISSING: "credentials",
+  ENVIRONMENT_UNAVAILABLE: "environment",
+  SEED_DATA_MISSING: "seed-data",
+  LOCATOR_NOT_FOUND: "automation",
+  LOCATOR_AMBIGUOUS: "automation",
+  REPLAY_DIVERGED: "automation",
+};
+export const BLOCKED_CAUSES = ["environment", "credentials", "seed-data", "automation", "unknown"];
+
+const PRODUCT_FAILURE_CODES = new Set(["ASSERTION_FAILED", "ASSERTION_INCONCLUSIVE"]);
+
+const EVIDENCE_KINDS = new Set(["screenshot", "ui-tree", "video", "trace", "log", "text"]);
+const JUDGE_EVIDENCE_KINDS = new Set(["screenshot", "ui-tree", "text"]);
+const JUDGE_KEYS = new Set(["assertion", "evidence", "vocabulary"]);
+
+const CLEAR_SECRET =
+  /\b(password|passcode|passwd|pin|otp|token|secret|api[-_ ]?key)\s*[:=]\s*(?!secret_ref:)\S+/i;
+
+const JUDGE_INSTRUCTIONS =
+  "Decide whether the assertion holds on the evidence below and nothing else. " +
+  "You have not seen the run that produced it and must not assume anything about it. " +
+  'Answer {"verdict": "passed" | "failed" | "inconclusive", "reason": "<one sentence>", ' +
+  '"cites": ["<evidence path>", ...]}. Cite only paths listed here. ' +
+  "When the evidence does not show enough to decide, answer inconclusive.";
+
+/**
+ * Budget with defaults filled and each value clamped to its range.
+ * @param {{steps?:number, minutes?:number, tokens?:number}} [input]
+ * @returns {{steps:number, minutes:number, tokens:number, clamped:string[]}}
+ */
+export function resolveBudget(input = {}) {
+  const out = { clamped: [] };
+  for (const [key, def] of Object.entries(BUDGET_DEFAULTS)) {
+    const [lo, hi] = BUDGET_LIMITS[key];
+    const raw = Number.isFinite(input?.[key]) ? Number(input[key]) : def;
+    const v = Math.min(hi, Math.max(lo, raw));
+    if (v !== raw) out.clamped.push(key);
+    out[key] = v;
+  }
+  return out;
+}
+
+/**
+ * What a step's status and code mean for the verdict.
+ * @param {{status:string, code?:string}} step
+ * @returns {{outcome:"passed"|"product-failure"|"blocked"|"exhausted", blockedBy?:string}}
+ */
+export function classifyStep(step) {
+  const code = step?.code || "";
+  if (code === "BUDGET_EXCEEDED" || step?.status === "exhausted") return { outcome: "exhausted" };
+  if (step?.status === "passed") return { outcome: "passed" };
+  if (step?.status === "failed" && PRODUCT_FAILURE_CODES.has(code)) {
+    return { outcome: "product-failure" };
+  }
+  return { outcome: "blocked", blockedBy: BLOCKED_CAUSE[code] || "unknown" };
+}
+
+const nonEmpty = (v) => typeof v === "string" && v.trim().length > 0;
+
+/**
+ * Contract errors of one finding; empty when it is complete.
+ * @param {object} f
+ * @returns {string[]}
+ */
+export function validateFinding(f) {
+  const errors = [];
+  if (!f || typeof f !== "object") return ["finding is not an object"];
+  if (!nonEmpty(f.title)) errors.push("title is required");
+  if (f.kind !== "issue" && f.kind !== "warning") errors.push("kind must be issue or warning");
+  if (!Number.isInteger(f.severity) || f.severity < 1 || f.severity > 5) {
+    errors.push("severity must be an integer from 1 (trivial) to 5 (critical)");
+  }
+  if (!nonEmpty(f.expected)) errors.push("expected is required");
+  if (!nonEmpty(f.observed)) errors.push("observed is required");
+  if (!Array.isArray(f.repro) || !f.repro.some(nonEmpty)) {
+    errors.push("repro needs at least one step");
+  }
+  if (
+    !Array.isArray(f.evidence) ||
+    !f.evidence.length ||
+    !f.evidence.every((e) => EVIDENCE_KINDS.has(e?.kind) && nonEmpty(e?.path))
+  ) {
+    errors.push(
+      `evidence needs at least one {kind, path}; kinds: ${[...EVIDENCE_KINDS].join(", ")}`,
+    );
+  }
+  const texts = [f.title, f.expected, f.observed, ...(Array.isArray(f.repro) ? f.repro : [])];
+  if (texts.some((t) => typeof t === "string" && CLEAR_SECRET.test(t))) {
+    errors.push("a secret value is written in clear text; refer to it as secret_ref:<name>");
+  }
+  return errors;
+}
+
+function findingSteps(run) {
+  return new Set((run.findings || []).map((f) => f?.step).filter(Number.isInteger));
+}
+
+function blockedStreak(run) {
+  const reported = findingSteps(run);
+  let streak = 0;
+  for (const step of [...(run.steps || [])].reverse()) {
+    if (classifyStep(step).outcome !== "blocked" || reported.has(step.index)) break;
+    streak++;
+  }
+  return streak;
+}
+
+/**
+ * Whether the run must stop now.
+ * @param {object} run
+ * @returns {{stop:boolean, reason:null|"step-limit"|"time"|"tokens"|"stuck", consecutiveBlocked:number}}
+ */
+export function checkRun(run) {
+  const budget = resolveBudget(run?.budget);
+  const usage = run?.usage || {};
+  const consecutiveBlocked = blockedStreak(run || {});
+  let reason = null;
+  if ((usage.steps ?? (run?.steps || []).length) >= budget.steps) reason = "step-limit";
+  else if ((usage.minutes ?? 0) >= budget.minutes) reason = "time";
+  else if ((usage.tokens ?? 0) >= budget.tokens) reason = "tokens";
+  else if (consecutiveBlocked >= STUCK_AFTER) reason = "stuck";
+  return { stop: reason !== null, reason, consecutiveBlocked };
+}
+
+const bySeverity = (a, b) => b.severity - a.severity || a.index - b.index;
+
+/**
+ * The run's verdict and everything the report lists.
+ * @param {object} run
+ */
+export function evaluateRun(run) {
+  const steps = run?.steps || [];
+  const issues = [];
+  const warnings = [];
+  const invalid = [];
+  (run?.findings || []).forEach((f, index) => {
+    const errors = validateFinding(f);
+    if (errors.length) invalid.push({ index, title: f?.title ?? null, errors });
+    else (f.kind === "issue" ? issues : warnings).push({ ...f, index });
+  });
+  issues.sort(bySeverity);
+  warnings.sort(bySeverity);
+
+  const blocked = Object.fromEntries(BLOCKED_CAUSES.map((c) => [c, []]));
+  const productFailures = [];
+  let exhausted = 0;
+  for (const step of steps) {
+    const c = classifyStep(step);
+    if (c.outcome === "blocked") blocked[c.blockedBy].push(step);
+    else if (c.outcome === "product-failure") productFailures.push(step);
+    else if (c.outcome === "exhausted") exhausted++;
+  }
+  const blockedCount = Object.values(blocked).reduce((n, l) => n + l.length, 0);
+
+  let verdict;
+  if (issues.length) verdict = "failed";
+  else if (!steps.length || blockedCount === steps.length) verdict = "blocked";
+  else verdict = "passed";
+
+  const stop = checkRun(run || {});
+  return {
+    verdict,
+    ended: run?.ended || stop.reason || "finished",
+    budget: resolveBudget(run?.budget),
+    usage: run?.usage || {},
+    issues,
+    warnings,
+    invalid,
+    blocked,
+    productFailures,
+    counts: {
+      steps: steps.length,
+      blocked: blockedCount,
+      exhausted,
+      issues: issues.length,
+      warnings: warnings.length,
+    },
+  };
+}
+
+function findingBlock(f, n) {
+  const ev = f.evidence.map((e) => `${e.kind}=${e.path}`).join(" ");
+  return [
+    `### ${n}. [${SEVERITY_WORDS[f.severity]} ${f.kind}] ${f.title}`,
+    "",
+    `- **Screen**: ${f.screen || "-"}`,
+    `- **Expected**: ${f.expected}`,
+    `- **Observed**: ${f.observed}`,
+    `- **Repro**: ${f.repro.map((s, i) => `${i + 1}. ${s}`).join(" ")}`,
+    `- **Evidence**: ${ev}`,
+    ...(f.spec ? [`- **Spec**: ${f.spec}`] : []),
+    "",
+  ].join("\n");
+}
+
+/**
+ * Markdown report: verdict, issues, warnings, blocked by cause, invalid findings.
+ * @param {ReturnType<typeof evaluateRun>} e
+ * @param {object} run
+ */
+export function renderReport(e, run) {
+  const u = e.usage;
+  const out = [
+    `# Exploratory run: ${run?.goal || "(no goal)"}`,
+    "",
+    `Verdict: ${e.verdict} · ended: ${e.ended} · platform: ${run?.platform || "-"}`,
+    `Budget: ${u.steps ?? e.counts.steps}/${e.budget.steps} steps · ${u.minutes ?? "?"}/${e.budget.minutes} min · ${u.tokens ?? "?"}/${e.budget.tokens} tokens`,
+    "",
+    `## Issues (${e.issues.length})`,
+    "",
+  ];
+  e.issues.forEach((f, i) => out.push(findingBlock(f, i + 1)));
+  if (!e.issues.length) out.push("None.", "");
+  out.push(`## Warnings (${e.warnings.length})`, "");
+  e.warnings.forEach((f, i) => out.push(findingBlock(f, i + 1)));
+  if (!e.warnings.length) out.push("None.", "");
+  out.push(`## Blocked (${e.counts.blocked}) - not product failures`, "");
+  let any = false;
+  for (const cause of BLOCKED_CAUSES) {
+    for (const s of e.blocked[cause]) {
+      any = true;
+      out.push(
+        `- ${cause}: step ${s.index}${s.title ? ` "${s.title}"` : ""} ${s.code || ""}${s.detail ? ` - ${s.detail}` : ""}`.trimEnd(),
+      );
+    }
+  }
+  if (!any) out.push("None.");
+  out.push("");
+  if (e.invalid.length) {
+    out.push(`## Findings that failed the contract (${e.invalid.length})`, "");
+    for (const v of e.invalid)
+      out.push(`- #${v.index} ${v.title ?? "(untitled)"}: ${v.errors.join("; ")}`);
+    out.push("");
+  }
+  return out.join("\n");
+}
+
+/**
+ * The judge's whole input. Anything describing the run is refused.
+ * @param {{assertion:string, evidence:{kind:string,path:string}[], vocabulary?:string}} input
+ */
+export function judgePacket(input) {
+  const extra = Object.keys(input || {}).filter((k) => !JUDGE_KEYS.has(k));
+  if (extra.length) {
+    throw new Error(
+      `a judge sees the assertion and the current evidence only; refused: ${extra.join(", ")}`,
+    );
+  }
+  if (!nonEmpty(input?.assertion)) throw new Error("assertion is required");
+  const evidence = Array.isArray(input.evidence) ? input.evidence : [];
+  if (!evidence.length) throw new Error("a judgement needs evidence: a screenshot or a UI tree");
+  for (const e of evidence) {
+    if (!JUDGE_EVIDENCE_KINDS.has(e?.kind) || !nonEmpty(e?.path)) {
+      throw new Error(
+        `evidence must be {kind, path} with kind ${[...JUDGE_EVIDENCE_KINDS].join(" | ")}`,
+      );
+    }
+  }
+  const packet = {
+    instructions: JUDGE_INSTRUCTIONS,
+    assertion: input.assertion.trim(),
+    evidence: evidence.map((e) => ({ kind: e.kind, path: e.path })),
+  };
+  if (nonEmpty(input.vocabulary)) packet.vocabulary = input.vocabulary.trim();
+  return packet;
+}
+
+/**
+ * The judge's answer held to its packet.
+ * @returns {{verdict:"passed"|"failed", code:null|"ASSERTION_FAILED"|"ASSERTION_INCONCLUSIVE", errors:string[]}}
+ */
+export function checkJudgeVerdict(packet, answer) {
+  const errors = [];
+  const given = new Set((packet?.evidence || []).map((e) => e.path));
+  const cites = Array.isArray(answer?.cites) ? answer.cites : [];
+  if (!["passed", "failed", "inconclusive"].includes(answer?.verdict)) {
+    errors.push("verdict must be passed, failed or inconclusive");
+  }
+  if (!nonEmpty(answer?.reason)) errors.push("reason is required");
+  if (answer?.verdict !== "inconclusive") {
+    if (!cites.length) errors.push("a decided verdict cites at least one evidence path");
+    const foreign = cites.filter((c) => !given.has(c));
+    if (foreign.length)
+      errors.push(`cites evidence the judge was not given: ${foreign.join(", ")}`);
+  }
+  if (errors.length || answer.verdict === "inconclusive") {
+    return { verdict: "failed", code: "ASSERTION_INCONCLUSIVE", errors };
+  }
+  return answer.verdict === "passed"
+    ? { verdict: "passed", code: null, errors }
+    : { verdict: "failed", code: "ASSERTION_FAILED", errors };
+}
+
+function arg(argv, flag) {
+  const i = argv.indexOf(flag);
+  return i >= 0 ? argv[i + 1] : undefined;
+}
+
+function args(argv, flag) {
+  const out = [];
+  argv.forEach((a, i) => {
+    if (a === flag && argv[i + 1] !== undefined) out.push(argv[i + 1]);
+  });
+  return out;
+}
+
+const readJson = (p) => JSON.parse(readFileSync(p, "utf8"));
+
+function main() {
+  const argv = process.argv.slice(2);
+  const mode = argv[0];
+  const usage = () => {
+    process.stderr.write(
+      "usage: explore-findings.mjs check --run FILE\n" +
+        "       explore-findings.mjs report --run FILE [--json]\n" +
+        "       explore-findings.mjs judge-packet --assertion TEXT --evidence KIND=PATH ... [--vocabulary TEXT]\n" +
+        "       explore-findings.mjs judge-verdict --packet FILE --verdict FILE\n",
+    );
+    process.exitCode = 2;
+  };
+  try {
+    if (mode === "check" && arg(argv, "--run")) {
+      process.stdout.write(`${JSON.stringify(checkRun(readJson(arg(argv, "--run"))))}\n`);
+    } else if (mode === "report" && arg(argv, "--run")) {
+      const run = readJson(arg(argv, "--run"));
+      const e = evaluateRun(run);
+      process.stdout.write(
+        argv.includes("--json") ? `${JSON.stringify(e, null, 2)}\n` : `${renderReport(e, run)}\n`,
+      );
+    } else if (mode === "judge-packet" && arg(argv, "--assertion")) {
+      const evidence = args(argv, "--evidence").map((pair) => {
+        const at = pair.indexOf("=");
+        return at > 0 ? { kind: pair.slice(0, at), path: pair.slice(at + 1) } : { path: pair };
+      });
+      const input = { assertion: arg(argv, "--assertion"), evidence };
+      if (arg(argv, "--vocabulary")) input.vocabulary = arg(argv, "--vocabulary");
+      process.stdout.write(`${JSON.stringify(judgePacket(input), null, 2)}\n`);
+    } else if (mode === "judge-verdict" && arg(argv, "--packet") && arg(argv, "--verdict")) {
+      const result = checkJudgeVerdict(
+        readJson(arg(argv, "--packet")),
+        readJson(arg(argv, "--verdict")),
+      );
+      process.stdout.write(`${JSON.stringify(result)}\n`);
+    } else {
+      usage();
+    }
+  } catch (err) {
+    process.stderr.write(`explore-findings: ${err.message}\n`);
+    process.exitCode = 2;
+  }
+}
+
+function invokedDirectly() {
+  if (!process.argv[1]) return false;
+  try {
+    return import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+  } catch {
+    return false;
+  }
+}
+
+if (invokedDirectly()) runMain("explore-findings", main);

package/pipeline/scripts/gen-skills-index.mjs

@@ -31,8 +31,7 @@ function categorize(name) {
   if (
     name.startsWith("multi-agent") ||
     name === "apple-archive-compliance" ||
-    name === "google-play-compliance" ||
-    name === "valven-rules"
+    name === "google-play-compliance"
   )
     return "pipeline";
   if (

package/pipeline/scripts/pr-timeline.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+
+/**
+ * @file pr-timeline.mjs  -  a GitHub pull request's timeline for
+ * `valven-gate.mjs --pr-meta-file`, plus the fields /multi-agent:review reads
+ * from the same file (head and base branch, body, commits).
+ *
+ * Usage:
+ *   pr-timeline.mjs --repo <owner/name> --pr <number> [--out <file>]
+ *
+ * `gh pr view --json` carries no ready-for-review time and names a review's
+ * author by login only, which leaves a bot such as Copilot's reviewer looking
+ * like a person. A GraphQL query fills both: `readyAt` from the last
+ * READY_FOR_REVIEW_EVENT, and the reviews again with each author's type, so the
+ * gate times pickup from ready and leaves bot reviews out. When that query fails
+ * the gh pr view output is written as it is and a warning names what is lost.
+ *
+ * Exit codes:
+ *   0  -  written
+ *   2  -  bad arguments, or gh pr view failed
+ *
+ * @module pipeline/scripts/pr-timeline
+ */
+
+import { execFileSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { runMain } from "../lib/fatal.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+
+const VIEW_FIELDS = [
+  "headRefName",
+  "baseRefName",
+  "body",
+  "commits",
+  "author",
+  "closedAt",
+  "createdAt",
+  "isDraft",
+  "mergedAt",
+  "reviewRequests",
+  "reviews",
+].join(",");
+
+const QUERY = `query($owner:String!,$name:String!,$n:Int!){repository(owner:$owner,name:$name){pullRequest(number:$n){
+timelineItems(last:1,itemTypes:[READY_FOR_REVIEW_EVENT]){nodes{... on ReadyForReviewEvent{createdAt}}}
+reviews(first:100){nodes{author{__typename login} state submittedAt}}}}}`;
+
+function gh(args) {
+  return execFileSync("gh", args, {
+    encoding: "utf-8",
+    maxBuffer: 64 * 1024 * 1024,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+}
+
+/**
+ * Merge the GraphQL timeline into the gh pr view object. Reviews take the
+ * GraphQL shape the gate reads (`author.is_bot`), so a bot is recognised.
+ *
+ * @param {object} view  gh pr view JSON
+ * @param {object} pullRequest  data.repository.pullRequest
+ */
+export function mergeTimeline(view, pullRequest) {
+  const readyAt = pullRequest?.timelineItems?.nodes?.[0]?.createdAt ?? null;
+  const reviews = (pullRequest?.reviews?.nodes ?? []).map((n) => ({
+    author: { login: n?.author?.login ?? null, is_bot: n?.author?.__typename === "Bot" },
+    state: n?.state ?? null,
+    submittedAt: n?.submittedAt ?? null,
+  }));
+  return { ...view, readyAt, reviews };
+}
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i += 2) {
+    const key = argv[i];
+    const val = argv[i + 1];
+    if (!key?.startsWith("--") || val === undefined || val.startsWith("--")) {
+      throw new Error(`${key ?? "argument"} needs a value`);
+    }
+    args[key.slice(2)] = val;
+  }
+  return args;
+}
+
+function fail(msg) {
+  process.stderr.write(`pr-timeline: ${msg}\n`);
+  process.exitCode = 2;
+}
+
+async function main() {
+  let args;
+  try {
+    args = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    return fail(err.message);
+  }
+  const [owner, name, extra] = String(args.repo ?? "").split("/");
+  if (!owner || !name || extra !== undefined) return fail("--repo must be <owner/name>");
+  if (!/^\d+$/.test(String(args.pr ?? ""))) return fail("--pr must be a pull request number");
+
+  let view;
+  try {
+    view = JSON.parse(gh(["pr", "view", args.pr, "--repo", args.repo, "--json", VIEW_FIELDS]));
+  } catch (err) {
+    return fail(`gh pr view failed: ${String(err.stderr || err.message).trim()}`);
+  }
+
+  let merged = view;
+  try {
+    const out = gh([
+      "api",
+      "graphql",
+      "-F",
+      `owner=${owner}`,
+      "-F",
+      `name=${name}`,
+      "-F",
+      `n=${args.pr}`,
+      "-f",
+      `query=${QUERY}`,
+    ]);
+    merged = mergeTimeline(view, JSON.parse(out)?.data?.repository?.pullRequest);
+  } catch (err) {
+    process.stderr.write(
+      `pr-timeline: timeline query failed (${String(err.stderr || err.message).trim()}); pickup counts from the opening and bot reviews are not recognised\n`,
+    );
+  }
+
+  const json = `${JSON.stringify(merged, null, 2)}\n`;
+  if (args.out) writeFileSync(args.out, json);
+  else process.stdout.write(json);
+}
+
+if (invokedDirectly(import.meta.url)) runMain("pr-timeline", main, { code: 2 });

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

@@ -166,8 +166,10 @@ is_binary() {
 scan_file() {
   local file="$1" content="$2" folded="${3:-}"
 
-  # .env files
-  if echo "$file" | grep -qE '\.env($|\.)'; then
+  # .env files. A template (.env.example/.sample/.template) documents names,
+  # not values, so it falls through to the content checks below instead.
+  if echo "$file" | grep -qE '\.env($|\.)' &&
+    ! echo "$file" | grep -qE '\.env\.(example|sample|template)$'; then
     echo "BLOCKED: .env file staged: $file" >&2
     FOUND=1
     return 0

package/pipeline/scripts/skill-conformance.mjs

@@ -44,8 +44,8 @@
 import { existsSync, readFileSync, writeFileSync, readdirSync, statSync } from "node:fs";
 import { dirname, join, resolve, relative, basename, extname, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { homedir } from "node:os";
 import { matchesAnyGlob } from "./glob-match.mjs";
+import { pluginSkillRootCandidates } from "../lib/plugin-skill-roots.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
 
@@ -56,83 +56,29 @@ const here = dirname(fileURLToPath(import.meta.url));
 // checkout, and `~/.claude/scripts`, `~/.copilot/scripts`, `~/.codex/scripts`
 // once installed. install/copilot.mjs copies `scripts/` byte-for-byte with no
 // path rewrite, and Codex puts skills under `multi-agent-refs/skills`, so a
-// hardcoded `~/.claude/skills` is inert on two of the three hosts. That exact
-// bug already shipped once here (see match-skills.mjs header): dynamic skill
-// loading exited 1 on every real install while passing a smoke that ran from
-// the repo. Installed layouts are tried first  -  that is where a run happens.
+// hardcoded `~/.claude/skills` is inert on two of the three hosts. The roots
+// are derived from this script's own location, and installed layouts are tried
+// before the checkout, because an installed tree is where a run happens.
 // ---------------------------------------------------------------------------
 function skillsRootCandidates() {
   const installRoot = resolve(here, ".."); // ~/.claude | ~/.copilot | ~/.codex
   const repoRoot = resolve(here, "..", ".."); // <repo>
-  return [
+  // The first registry found under a name wins. On Claude Code the plugin roots
+  // come first: a registry that ships in a plugin is what the host loads, and a
+  // same-named copy an older install left in ~/.claude/skills must not shadow it.
+  // The gate registries the installer lays down follow, so a registry is still
+  // found while the user's plugin predates it. Copilot and Codex load no plugin;
+  // the copy their installer laid down is the current one and comes first.
+  const plugins = pluginSkillRootCandidates(); // checkout, then every cached version
+  const installed = [
     join(installRoot, "skills"), // ~/.claude/skills, ~/.copilot/skills
     join(installRoot, "multi-agent-refs", "skills"), // ~/.codex/multi-agent-refs/skills
-    ...pluginSkillRoots(), // marketplace stack plugins (Claude Code's only stack-skill source)
-    join(repoRoot, "pipeline", "skills"), // checkout
   ];
-}
-
-// ---------------------------------------------------------------------------
-// Marketplace plugin roots.
-//
-// On Claude Code the stack skills no longer land in ~/.claude/skills - they are
-// loaded from the multi-agent-plugins marketplace. The registries this gate
-// depends on (`ios-coding-standard`, `ios-module-structure`) live in the iOS
-// plugin's knowledge/ tree, so without these roots the registry set silently
-// collapses to the two local compliance catalogs and Phase 4 reads green over
-// criteria that were never loaded. Local checkout is preferred over the plugin
-// cache for the same reason install/_plugin-skills.mjs prefers it: the checkout
-// is what /multi-agent:sync rebuilds, the cache only advances on marketplace
-// refresh. Cache dirs are version-named; newest wins.
-// ---------------------------------------------------------------------------
-const PLUGIN_MARKETPLACE = "multi-agent-plugins";
-const STACK_PLUGIN_NAMES = [
-  "ai-ios-toolkit",
-  "ai-android-toolkit",
-  "ai-frontend-toolkit",
-  "ai-backend-toolkit",
-  "ai-common-toolkit",
-];
-
-function semverCompare(a, b) {
-  const pa = a.split(".").map((n) => parseInt(n, 10) || 0);
-  const pb = b.split(".").map((n) => parseInt(n, 10) || 0);
-  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
-    const d = (pa[i] || 0) - (pb[i] || 0);
-    if (d !== 0) return d;
-  }
-  return a.localeCompare(b);
-}
-
-function pluginSkillRoots() {
-  const home = homedir();
-  const roots = [];
-  for (const name of STACK_PLUGIN_NAMES) {
-    const checkout = join(home, PLUGIN_MARKETPLACE, "plugins", name, "skills");
-    if (existsSync(checkout)) {
-      roots.push(checkout);
-      continue;
-    }
-    const cacheRoot = join(home, ".claude", "plugins", "cache", PLUGIN_MARKETPLACE, name);
-    if (!existsSync(cacheRoot)) continue;
-    const versions = readdirSafe(cacheRoot)
-      .filter((v) => {
-        try {
-          return statSync(join(cacheRoot, v)).isDirectory();
-        } catch {
-          return false;
-        }
-      })
-      .sort(semverCompare);
-    for (const v of versions.reverse()) {
-      const p = join(cacheRoot, v, "skills");
-      if (existsSync(p)) {
-        roots.push(p);
-        break;
-      }
-    }
-  }
-  return roots;
+  const registries = join(installRoot, "multi-agent-refs", "registries"); // ~/.claude
+  const checkout = join(repoRoot, "pipeline", "skills");
+  return basename(installRoot) === ".claude"
+    ? [...plugins, registries, ...installed, checkout]
+    : [...installed, ...plugins, checkout];
 }
 
 /**

package/pipeline/scripts/smoke-cross-cli-behavior.sh

@@ -121,7 +121,7 @@ echo ""
 echo "→ 3. No personal-data hardcodes in generic docs"
 # These are patterns that must be placeholders, never literals
 PERSONAL_HARDCODES=(
-  "${USER:-$(id -un)}_tkgithub"
+  "${USER:-$(id -un)}_"
 )
 for p in "${PERSONAL_HARDCODES[@]}"; do
   FOUND=$(find "$CLAUDE_CMDS" -name SKILL.md -exec grep -l -F -- "$p" {} + 2>/dev/null || true)