@mmerterden/multi-agent-pipeline 20.2.1 → 20.3.0

package/pipeline/scripts/scaffold-gate.mjs

@@ -0,0 +1,393 @@
+#!/usr/bin/env node
+/**
+ * scaffold-gate.mjs  -  a new project is proven green by its own commands, and
+ * stays demoable from one story to the next.
+ *
+ * `/multi-agent:scaffold` calls the enabled toolkit's `<toolkit>:scaffold`
+ * skill, which writes a skeleton plus a `.scaffold.json` manifest at its root
+ * and runs `git init`. The pipeline then only verifies, with this script:
+ *
+ *   --phase skeleton   before the first commit. The directory is a git
+ *                      repository with no commit and no remote, and the stack
+ *                      adapter's build, test and lint commands
+ *                      (schemas/stack-adapters.json, _stack-adapter.mjs) pass.
+ *   --phase story      between stories. Build, test and lint pass, and the
+ *                      manifest's demo command exits 0 with output matching
+ *                      its `expect` pattern. A failure here means the next
+ *                      story does not start.
+ *
+ * Build and test logs are judged by evidence-gate.mjs with `--stack`, which
+ * reads the adapter's markers and, for tests, the counts (test-summary.mjs): a
+ * run with no test executed is not a pass. Gradle prints no counts on success,
+ * so for an adapter that reads JUnit XML the project's `test-results`
+ * directories are summed as well (junitCounts). Lint and demo have no markers, so
+ * their exit code and, for the demo, the expected output decide. Every log is
+ * kept under `<dir>/.pipeline/scaffold/<phase>-<check>.log`.
+ *
+ * Manifest (`.scaffold.json`, schemas/scaffold-manifest.schema.json):
+ *   { version: "1.0.0", toolkit, name, stack: <adapter id>, vars?: {slot: value},
+ *     demo?: { command, expect } }
+ * `vars` fills the adapter's `{slot}`s (an iOS scheme, a simulator name). A
+ * `remote` key is refused: the scaffold never creates or names a remote.
+ *
+ * While the quality gates are active (lib/unattended.mjs) the verdict is
+ * recorded as `scaffold/skeleton` or `scaffold/story` through gate-ledger.mjs,
+ * beside the `evidence-gate/*` entries evidence-gate.mjs writes itself. The
+ * check itself runs in every mode: it is the scaffold flow's own proof.
+ *
+ * Usage:
+ *   scaffold-gate.mjs --dir <skeleton> --phase skeleton|story [--story <id>]
+ *                     [--state <agent-state.json>] [--timeout-sec <n>] [--json]
+ *
+ * Exit: 0 pass · 1 a check failed · 2 usage · 3 manifest missing, unreadable or invalid.
+ *
+ * @module pipeline/scripts/scaffold-gate
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { AdapterError, commandFor, getAdapter, loadAdapters, UNKNOWN } from "./_stack-adapter.mjs";
+import { gateContext, recordQuietly } from "./gate-ledger.mjs";
+import { summarizeJunit } from "./test-summary.mjs";
+
+export const MANIFEST = ".scaffold.json";
+export const PHASES = ["skeleton", "story"];
+const EVIDENCE_GATE = fileURLToPath(new URL("./evidence-gate.mjs", import.meta.url));
+const DEFAULT_TIMEOUT_SEC = 900;
+
+/**
+ * Every problem with a manifest, as readable strings. Empty = valid.
+ *
+ * @param {any} m
+ * @param {{phase: "skeleton"|"story", doc?: object}} opts
+ * @returns {string[]}
+ */
+export function validateManifest(m, { phase, doc = loadAdapters() }) {
+  const errors = [];
+  if (!m || typeof m !== "object" || Array.isArray(m)) return ["manifest must be a JSON object"];
+  if (m.version !== "1.0.0") errors.push('version must be "1.0.0"');
+  for (const k of ["toolkit", "name", "stack"]) {
+    if (typeof m[k] !== "string" || !m[k].trim()) errors.push(`${k} is required`);
+  }
+  if (typeof m.stack === "string") {
+    const a = doc.adapters[m.stack];
+    if (!a || m.stack === UNKNOWN || a.applicable === false) {
+      errors.push(`stack "${m.stack}" is not an applicable stack adapter`);
+    }
+  }
+  if (m.vars !== undefined) {
+    const ok =
+      m.vars && typeof m.vars === "object" && !Array.isArray(m.vars)
+        ? Object.values(m.vars).every((v) => typeof v === "string")
+        : false;
+    if (!ok) errors.push("vars must be an object of strings");
+  }
+  if ("remote" in m) errors.push("remote is not allowed: the scaffold never creates or names one");
+  if (m.demo !== undefined) {
+    if (typeof m.demo?.command !== "string" || !m.demo.command.trim()) {
+      errors.push("demo.command is required");
+    }
+    if (typeof m.demo?.expect !== "string" || !m.demo.expect)
+      errors.push("demo.expect is required");
+    else {
+      try {
+        new RegExp(m.demo.expect);
+      } catch {
+        errors.push("demo.expect is not a valid regular expression");
+      }
+    }
+  } else if (phase === "story") {
+    errors.push("demo is required between stories: the app has to be shown working");
+  }
+  return errors;
+}
+
+let runSeq = 0;
+
+/**
+ * Values for the adapter's `{slot}`s. `worktreePath` is always the skeleton;
+ * `resultBundle` is new per run because xcodebuild refuses to overwrite one;
+ * the manifest's `vars` fill the rest and can override neither.
+ *
+ * @param {string} dir
+ * @param {string} phase
+ * @param {Record<string, string>} [manifestVars]
+ */
+export function commandVars(dir, phase, manifestVars = {}) {
+  const stamp = `${Date.now()}-${process.pid}-${++runSeq}`;
+  return {
+    ...(manifestVars || {}),
+    resultBundle: join(dir, ".pipeline", "scaffold", `${phase}-${stamp}.xcresult`),
+    worktreePath: dir,
+  };
+}
+
+const SKIP_DIRS = new Set([
+  ".git",
+  ".gradle",
+  ".pipeline",
+  "node_modules",
+  ".build",
+  ".DerivedData",
+]);
+
+/**
+ * Test counts from the JUnit XML under every `test-results` directory of the
+ * project, for runners whose log carries no counts on success (Gradle).
+ *
+ * @param {string} dir
+ * @returns {{executed: number, passed: number, failed: number, skipped: number,
+ *            status: string, dirs: string[]} | null}  null when no results were found
+ */
+export function junitCounts(dir) {
+  const found = [];
+  const walk = (d, depth) => {
+    if (depth > 4) return;
+    let entries;
+    try {
+      entries = readdirSync(d, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (!e.isDirectory() || SKIP_DIRS.has(e.name)) continue;
+      const full = join(d, e.name);
+      if (e.name === "test-results") found.push(full);
+      else walk(full, depth + 1);
+    }
+  };
+  walk(dir, 0);
+  const total = { executed: 0, passed: 0, failed: 0, skipped: 0, dirs: [] };
+  for (const d of found) {
+    const r = summarizeJunit(d);
+    if (r.executed === null) continue;
+    total.executed += r.executed;
+    total.passed += r.passed;
+    total.failed += r.failed;
+    total.skipped += r.skipped;
+    total.dirs.push(d);
+  }
+  if (total.dirs.length === 0) return null;
+  const status = total.failed > 0 ? "failed" : total.executed === 0 ? "no-tests" : "passed";
+  return { ...total, status };
+}
+
+function git(dir, ...args) {
+  return spawnSync("git", ["-C", dir, ...args], { encoding: "utf8", timeout: 20000 });
+}
+
+function run(command, dir, logPath, timeoutSec) {
+  const r = spawnSync("bash", ["-c", command], {
+    cwd: dir,
+    encoding: "utf8",
+    timeout: timeoutSec * 1000,
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  const out = `${r.stdout || ""}${r.stderr || ""}`;
+  writeFileSync(logPath, `$ ${command}\n${out}`);
+  if (r.error?.code === "ETIMEDOUT" || (r.status === null && r.signal)) {
+    return { status: null, out, reason: `timed out after ${timeoutSec}s` };
+  }
+  return { status: r.status, out, reason: r.status === 0 ? "exit 0" : `exit ${r.status}` };
+}
+
+function evidence(claim, logPath, stack, statePath) {
+  const argv = [EVIDENCE_GATE, "--claim", claim, "--status", "passed"];
+  argv.push("--evidence", logPath, "--stack", stack);
+  if (statePath) argv.push("--state", statePath);
+  const r = spawnSync(process.execPath, argv, { encoding: "utf8", timeout: 60000 });
+  let verdict = null;
+  try {
+    verdict = JSON.parse(r.stdout);
+  } catch {
+    /* reported below */
+  }
+  return {
+    ok: r.status === 0 && verdict?.ok === true,
+    reason: verdict?.reason || `evidence-gate exited ${r.status}: ${(r.stderr || "").trim()}`,
+  };
+}
+
+/**
+ * @param {{dir: string, phase: string, story?: string|null, statePath?: string|null,
+ *          timeoutSec?: number}} opts
+ * @returns {{gate: string, phase: string, story: string|null, verdict: string,
+ *            checks: {name: string, ok: boolean, reason: string, log?: string}[]}}
+ */
+export function verify({ dir, phase, story = null, statePath = null, timeoutSec }) {
+  const gate = `scaffold/${phase}`;
+  const checks = [];
+  const add = (name, ok, reason, log) => checks.push({ name, ok, reason, ...(log ? { log } : {}) });
+  const finish = (verdict) => ({ gate, phase, story, verdict, checks });
+
+  const manifestPath = join(dir, MANIFEST);
+  let m;
+  try {
+    m = JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch (err) {
+    add("manifest", false, `cannot read ${MANIFEST}: ${err.message}`);
+    return finish("invalid");
+  }
+  const errors = validateManifest(m, { phase });
+  if (errors.length) {
+    add("manifest", false, errors.join("; "));
+    return finish("invalid");
+  }
+  add("manifest", true, `${m.toolkit} ${m.name} on the ${m.stack} adapter`);
+
+  if (git(dir, "rev-parse", "--git-dir").status !== 0) {
+    add("git", false, "not a git repository: the scaffold runs git init");
+  } else {
+    const remotes = git(dir, "remote").stdout.trim().split(/\s+/).filter(Boolean);
+    add(
+      "no-remote",
+      remotes.length === 0,
+      remotes.length ? `remote ${remotes.join(", ")} is configured` : "no remote configured",
+    );
+    if (phase === "skeleton") {
+      const head = git(dir, "rev-parse", "--verify", "-q", "HEAD");
+      add(
+        "first-commit",
+        head.status !== 0,
+        head.status === 0
+          ? `the repository already has ${head.stdout.trim().slice(0, 12)}; the proof comes before the first commit`
+          : "no commit yet",
+      );
+    }
+  }
+
+  const logDir = join(dir, ".pipeline", "scaffold");
+  mkdirSync(logDir, { recursive: true });
+  const timeout = timeoutSec || DEFAULT_TIMEOUT_SEC;
+  const vars = commandVars(dir, phase, m.vars);
+
+  for (const kind of ["build", "test", "lint"]) {
+    const log = join(logDir, `${phase}-${kind}.log`);
+    let command;
+    try {
+      command = commandFor(m.stack, kind, { dir, vars }).command;
+    } catch (err) {
+      const why = err instanceof AdapterError ? err.message : String(err);
+      add(kind, false, `no ${kind} command: ${why}`);
+      continue;
+    }
+    const r = run(command, dir, log, timeout);
+    if (kind === "lint") {
+      add(kind, r.status === 0, `${command}: ${r.reason}`, log);
+      continue;
+    }
+    if (r.status !== 0) {
+      add(kind, false, `${command}: ${r.reason}`, log);
+      continue;
+    }
+    const e = evidence(kind, log, m.stack, statePath);
+    if (
+      e.ok &&
+      kind === "test" &&
+      getAdapter(m.stack).testSummary?.parsers?.includes("junit-xml")
+    ) {
+      const counts = junitCounts(dir);
+      if (counts && counts.status !== "passed") {
+        add(kind, false, `JUnit XML: ${counts.executed} executed, ${counts.failed} failed`, log);
+        continue;
+      }
+      if (counts) {
+        add(kind, true, `${e.reason}; JUnit XML: ${counts.executed} executed, 0 failed`, log);
+        continue;
+      }
+    }
+    add(kind, e.ok, e.reason, log);
+  }
+
+  if (m.demo) {
+    const log = join(logDir, `${phase}-demo.log`);
+    const r = run(m.demo.command, dir, log, timeout);
+    const shows = new RegExp(m.demo.expect).test(r.out);
+    add(
+      "demo",
+      r.status === 0 && shows,
+      r.status !== 0
+        ? `${m.demo.command}: ${r.reason}`
+        : shows
+          ? `${m.demo.command}: output matches ${m.demo.expect}`
+          : `${m.demo.command}: output does not match expect ${m.demo.expect}`,
+      log,
+    );
+  }
+
+  return finish(checks.every((c) => c.ok) ? "pass" : "fail");
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+
+function parse(argv) {
+  const opts = { json: false };
+  const single = new Set(["--dir", "--phase", "--story", "--state", "--timeout-sec"]);
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--json") opts.json = true;
+    else if (single.has(a)) {
+      const v = argv[++i];
+      if (v === undefined) throw new Error(`${a} needs a value`);
+      opts[a.slice(2).replace(/-([a-z])/g, (_, c) => c.toUpperCase())] = v;
+    } else throw new Error(`unexpected argument ${a}`);
+  }
+  if (!opts.dir) throw new Error("--dir is required");
+  if (!PHASES.includes(opts.phase)) throw new Error(`--phase must be one of ${PHASES.join(", ")}`);
+  if (opts.timeoutSec !== undefined && !/^[1-9][0-9]*$/.test(opts.timeoutSec)) {
+    throw new Error("--timeout-sec must be a positive integer");
+  }
+  return opts;
+}
+
+async function main(argv) {
+  let opts;
+  try {
+    opts = parse(argv);
+  } catch (err) {
+    process.stderr.write(`scaffold-gate: ${err.message}\n`);
+    return 2;
+  }
+  if (!existsSync(opts.dir)) {
+    process.stderr.write(`scaffold-gate: no directory ${opts.dir}\n`);
+    return 3;
+  }
+  const ctx = gateContext({ statePath: opts.state || null, repo: opts.dir });
+  const result = verify({
+    dir: opts.dir,
+    phase: opts.phase,
+    story: opts.story || null,
+    statePath: ctx.active ? ctx.statePath : null,
+    timeoutSec: opts.timeoutSec ? Number(opts.timeoutSec) : undefined,
+  });
+  if (ctx.active) {
+    await recordQuietly(
+      result.gate,
+      result.verdict === "pass" ? "pass" : "fail",
+      {
+        story: result.story,
+        failed: result.checks.filter((c) => !c.ok).map(({ name, reason }) => ({ name, reason })),
+      },
+      { repo: opts.dir, statePath: ctx.statePath },
+    );
+  }
+  if (opts.json) writeFileSync(1, `${JSON.stringify(result, null, 2)}\n`);
+  else {
+    const lines = [
+      `${result.gate}${result.story ? ` ${result.story}` : ""}: ${result.verdict}`,
+      ...result.checks.map((c) => `  ${c.ok ? "ok  " : "FAIL"} ${c.name}: ${c.reason}`),
+    ];
+    writeFileSync(result.verdict === "pass" ? 1 : 2, `${lines.join("\n")}\n`);
+  }
+  if (result.verdict === "pass") return 0;
+  return result.verdict === "invalid" ? 3 : 1;
+}
+
+if (invokedDirectly(import.meta.url)) {
+  main(process.argv.slice(2)).then((code) => process.exit(code));
+}

package/pipeline/scripts/skill-conformance.mjs

@@ -19,9 +19,10 @@
 //
 // Contract (full spec: multi-agent-refs/features/skill-conformance.md):
 //   1. Registry discovery is DECLARED, never sniffed by name: a skill opts in with
-//      `standards-registry: <relative path>` in its SKILL.md frontmatter. The
-//      pipeline therefore names no stack-specific skill, and a new language's
-//      registry drops in with zero pipeline change.
+//      `standards-registry: <relative path>` in its SKILL.md frontmatter (under
+//      `metadata:`, or at the top level). The pipeline therefore names no
+//      stack-specific skill, and a new language's registry drops in with zero
+//      pipeline change.
 //   2. Every registry declares its own `scope` (languages / paths). Rules outside
 //      the changed files' languages are DROPPED and counted. Without this an
 //      Objective-C or UIKit diff would collect the whole Swift/SwiftUI rule set,
@@ -307,13 +308,28 @@ function readFrontmatter(path) {
   const end = text.indexOf("\n---", 3);
   if (end < 0) return {};
   const out = {};
+  let inMetadata = false;
   for (const line of text.slice(3, end).split("\n")) {
     const m = /^([a-zA-Z0-9_-]+):\s*(.*)$/.exec(line);
-    if (m) out[m[1]] = unquote(m[2].trim());
+    if (m) {
+      out[m[1]] = unquote(m[2].trim());
+      inMetadata = m[1] === "metadata" && m[2].trim() === "";
+      if (inMetadata) out.metadata = {};
+      continue;
+    }
+    const nested = inMetadata && /^\s+([a-zA-Z0-9_-]+):\s*(.*)$/.exec(line);
+    if (nested) out.metadata[nested[1]] = unquote(nested[2].trim());
   }
   return out;
 }
 
+// The host frontmatter schema has no `standards-registry` key, so a skill that
+// ships to a plugin carries it under `metadata:`. The top-level spelling is
+// still read for skills written before that move.
+function declaredRegistry(fm) {
+  return fm.metadata?.["standards-registry"] || fm["standards-registry"] || "";
+}
+
 // ---------------------------------------------------------------------------
 // Language classification from file extension.
 //
@@ -644,7 +660,8 @@ function discoverRegistries(roots) {
     for (const skillDir of findSkillDirs(root, 0, [])) {
       const skillFile = join(skillDir, "SKILL.md");
       const fm = readFrontmatter(skillFile);
-      if (!fm["standards-registry"]) continue;
+      const declared = declaredRegistry(fm);
+      if (!declared) continue;
       const name = fm.name ?? basename(skillDir);
       if (seen.has(name)) continue;
       // `standards-registry` is author-controlled frontmatter, and resolve()
@@ -654,18 +671,18 @@ function discoverRegistries(roots) {
       // would be extracted into the manifest and injected into every reviewer
       // prompt via the shared ${CRITERIA} block. Contain it to the skill's own
       // directory; a declaration that escapes is recorded, not followed.
-      const rulesPath = resolve(skillDir, fm["standards-registry"]);
+      const rulesPath = resolve(skillDir, declared);
       const skillRoot = resolve(skillDir) + sep;
       if (!rulesPath.startsWith(skillRoot)) {
         escaped.push({
           name,
           path: rulesPath,
-          reason: `standards-registry escapes the skill directory (declared: ${fm["standards-registry"]})`,
+          reason: `standards-registry escapes the skill directory (declared: ${declared})`,
         });
         continue;
       }
       seen.add(name);
-      out.push({ name, skillFile, rulesPath, declared: fm["standards-registry"] });
+      out.push({ name, skillFile, rulesPath, declared });
     }
   }
   return { registries: out.sort((a, b) => a.name.localeCompare(b.name)), escaped };

package/pipeline/scripts/skill-siblings.mjs

@@ -42,6 +42,7 @@ 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";
+import { hostCommand } from "../lib/user-facing.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const HOME = homedir();
@@ -190,7 +191,7 @@ if (AUDIT) {
     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`,
+        `  ${unsynced} command(s) not present in every installed tree (run ${hostCommand("sync", HERE)})\n`,
       );
     }
   }

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

@@ -12,17 +12,43 @@
 #   5. Canonical project-name vocabulary in user-facing docs
 #
 # Must pass before any `sync` run that touches shared commands.
+#
+# Which tree it checks:
+#   - CROSS_CLI_HOME set: the install under that home.
+#   - run from a git checkout of the pipeline: that checkout, installed into a
+#     temporary home first, so the verdict is about this tree and never about
+#     whatever version happens to be installed on the machine.
+#   - otherwise (the release tarball `/multi-agent:update` runs it from): the
+#     install under $HOME.
 
 set -uo pipefail
 
-CLAUDE_CMDS="$HOME/.claude/commands/multi-agent"
-COPILOT_SKILLS="$HOME/.copilot/skills"
-
 PASS=0
 FAIL=0
 pass() { PASS=$((PASS + 1)); echo "  ✓ $1"; }
 fail() { FAIL=$((FAIL + 1)); echo "  ✗ $1"; }
 
+CHECKOUT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+INSTALL_HOME=""
+if [ -z "${CROSS_CLI_HOME:-}" ] && [ -e "$CHECKOUT/.git" ] && [ -f "$CHECKOUT/install.js" ]; then
+  INSTALL_HOME=$(mktemp -d "${TMPDIR:-/tmp}/cross-cli-home.XXXXXX")
+  trap 'rm -rf "$INSTALL_HOME"' EXIT
+  if HOME="$INSTALL_HOME" MULTI_AGENT_SKIP_MCP_REGISTER=1 \
+       node "$CHECKOUT/install.js" --claude --copilot >"$INSTALL_HOME/install.log" 2>&1; then
+    pass "installed this checkout into a temporary home"
+  else
+    fail "install of this checkout failed: $(tail -3 "$INSTALL_HOME/install.log" | tr '\n' ' ')"
+    echo ""
+    echo "══ cross-cli-behavior: aborted (setup invalid) ══"
+    exit 2
+  fi
+  CROSS_CLI_HOME="$INSTALL_HOME"
+fi
+H="${CROSS_CLI_HOME:-$HOME}"
+
+CLAUDE_CMDS="$H/.claude/commands/multi-agent"
+COPILOT_SKILLS="$H/.copilot/skills"
+
 # ──────────────────────────────────────────────────────────────────────────
 echo "→ 1. Command-set identity (Claude vs Copilot)"
 if [ ! -d "$CLAUDE_CMDS" ]; then
@@ -137,7 +163,7 @@ done
 # ──────────────────────────────────────────────────────────────────────────
 echo ""
 echo "→ 6. Contract doc exists (required source of truth)"
-CONTRACT="$HOME/.claude/multi-agent-refs/cross-cli-contract.md"
+CONTRACT="$H/.claude/multi-agent-refs/cross-cli-contract.md"
 if [ -f "$CONTRACT" ]; then
   SIZE=$(wc -l < "$CONTRACT" | tr -d ' ')
   if [ "$SIZE" -ge 100 ]; then
@@ -157,8 +183,8 @@ echo ""
 # The pipeline therefore has no figma tree to deploy or parity-check here.
 echo "→ 7. Agent personas deployed to both CLIs"
 
-CLAUDE_AGENTS="$HOME/.claude/agents"
-COPILOT_AGENTS="$HOME/.copilot/agents"
+CLAUDE_AGENTS="$H/.claude/agents"
+COPILOT_AGENTS="$H/.copilot/agents"
 AGENT_FILES=()
 if [ -d "$CLAUDE_AGENTS" ]; then
   for f in "$CLAUDE_AGENTS"/*.md; do

package/pipeline/scripts/smoke-schema-validation.sh

@@ -13,13 +13,17 @@ FAIL=0
 pass() { PASS=$((PASS + 1)); echo "  ✓ $1"; }
 fail() { FAIL=$((FAIL + 1)); echo "  ✗ $1"; }
 
-SCHEMAS_DIR="$HOME/.claude/schemas"
+SMOKE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# The schemas beside this script are the ones under test. The installed copy is
+# only a fallback for a smoke run from an installed tree: validating it from a
+# checkout would grade whatever version was last installed, not the change.
+SCHEMAS_DIR="$SMOKE_DIR/../schemas"
+[ -f "$SCHEMAS_DIR/prefs.schema.json" ] || SCHEMAS_DIR="$HOME/.claude/schemas"
 PREFS_SCHEMA="$SCHEMAS_DIR/prefs.schema.json"
 STATE_SCHEMA="$SCHEMAS_DIR/agent-state.schema.json"
 # Repo checkout first (derived from this script's location), then the
 # maintainer's legacy layout. The template ships only in the repo - when the
 # smoke runs from an installed tree with no checkout, the check is skipped.
-SMOKE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 TEMPLATE="$SMOKE_DIR/../preferences-template.json"
 [ -f "$TEMPLATE" ] || TEMPLATE="$HOME/multi-agent-pipeline/pipeline/preferences-template.json"
 LIVE_PREFS="$HOME/.claude/multi-agent-preferences.json"