@cohortapp/agent-sdk 2.3.0

package/scripts/ci/check-no-residual-identity.mjs

@@ -0,0 +1,163 @@
+/**
+ * check-no-residual-identity.mjs — de-identification ratchet.
+ *
+ * The framework is white-label: it must carry NO trace of its first instance's
+ * real identity (the Sophie / Mehran / Adaptic deployment). Once a path has been
+ * de-identified (tokenised with {{agent.*}}/{{company.*}} or rewritten
+ * persona-agnostic), it must STAY clean. This guard scans a curated list of
+ * already-de-identified paths for the original instance identity and fails on any
+ * regression. EXPAND `DE_IDENTIFIED_PATHS` as each increment de-identifies more of
+ * the corpus (triggers → agents → lib → templates → docs).
+ *
+ * These markers are the ORIGINAL client identity (NOT confidential data — that is
+ * the job of check-no-confidential.mjs), so they are safe to hardcode here. The
+ * generic placeholders the framework now ships (Northwind / Alex / Jordan etc.)
+ * are intentional examples and are NOT flagged.
+ *
+ * Pure, dependency-light: Node builtins only. ESM.
+ *
+ * Usage: `node scripts/ci/check-no-residual-identity.mjs`  (exit 0 ok / 1 found)
+ * @module scripts/ci/check-no-residual-identity
+ */
+
+"use strict";
+
+import { readdirSync, readFileSync, existsSync, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const REPO_ROOT = path.resolve(fileURLToPath(new URL(".", import.meta.url)), "..", "..");
+
+/**
+ * Paths confirmed de-identified that must remain free of the original instance
+ * identity. Grow this list as increments land. 2.0 grew it with bin/, scripts/,
+ * scaffold/, and services/ (the §4.5 rebrand sweep cleaned their offenders).
+ * @type {string[]}
+ */
+export const DE_IDENTIFIED_PATHS = [
+  "schedules/triggers",
+  "agents",
+  "lib",
+  "teams",
+  "bin",
+  "scripts",
+  "scaffold",
+  "services",
+];
+/** @deprecated retained for back-compat with callers/tests referencing the old name. */
+export const DE_SOPHIED_PATHS = DE_IDENTIFIED_PATHS;
+
+/**
+ * SELF-EXEMPTION (the guard-of-the-guard). These two files carry identity
+ * tokens BY DESIGN — this guard's own IDENTITY_PATTERNS literals/labels/header
+ * doctrine, and check-no-confidential.mjs's scope-note naming what this guard
+ * covers — so scanning them can never come clean. They are skipped by exact
+ * repo-relative path. The policy assert below keeps this list from ever
+ * growing into a general escape hatch: every entry MUST be a scripts/ci/
+ * check-no-* guard, or the module throws at import.
+ * @type {string[]}
+ */
+export const EXEMPT_FILES = [
+  "scripts/ci/check-no-residual-identity.mjs",
+  "scripts/ci/check-no-residual-identity.test.mjs", // seeds/asserts the markers by design
+  "scripts/ci/check-no-confidential.mjs",
+];
+
+/**
+ * Enforce the exemption policy. Exported so the test can drive the throwing
+ * branch directly; invoked at module load over the real EXEMPT_FILES.
+ * @param {string[]} files
+ */
+export function assertExemptPolicy(files) {
+  for (const f of files) {
+    if (!String(f).startsWith("scripts/ci/check-no-")) {
+      throw new Error(
+        `check-no-residual-identity: EXEMPT_FILES entry "${f}" is out of policy — ` +
+          "only scripts/ci/check-no-* guards may self-exempt (the list is not a general escape hatch)",
+      );
+    }
+  }
+}
+assertExemptPolicy(EXEMPT_FILES);
+
+/** Original-instance identity markers the framework must not reintroduce. @type {Array<{label:string, re:RegExp}>} */
+export const IDENTITY_PATTERNS = [
+  { label: "agent name (Sophie)", re: /\bSophie\b/i },
+  { label: "principal name (Mehran)", re: /\bMehran\b/i },
+  { label: "company (Adaptic)", re: /\bAdaptic\b/ },
+  { label: "surname (Granfar)", re: /\bGranfar\b/i },
+  { label: "surname (Nguyen)", re: /\bNguyen\b/i },
+  { label: "principal first name (Hootan)", re: /\bHootan\b/i },
+  { label: "colleague (Nima)", re: /\bNima\b/ },
+  { label: "instance regulator (DFSA)", re: /\bDFSA\b/ },
+  { label: "instance email (@adaptic.ai)", re: /@adaptic\.ai/i },
+  { label: "instance repo slug (sophie-ai)", re: /\bsophie-ai\b/i },
+  { label: "instance home path (/Users/sophie)", re: /\/Users\/sophie/i },
+  { label: "old package scope (@adaptic/)", re: /@adaptic\// },
+];
+
+/** Scan a text blob for identity markers. Pure. @returns {Array<{label:string, match:string}>} */
+export function scanIdentity(text) {
+  if (typeof text !== "string" || text.length === 0) return [];
+  const hits = [];
+  for (const p of IDENTITY_PATTERNS) {
+    const m = text.match(p.re);
+    if (m) hits.push({ label: p.label, match: m[0] });
+  }
+  return hits;
+}
+
+function walkFiles(dir) {
+  const out = [];
+  for (const name of readdirSync(dir)) {
+    if (name === "node_modules" || name === ".git") continue;
+    const p = path.join(dir, name);
+    let st;
+    try { st = statSync(p); } catch { continue; }
+    if (st.isDirectory()) out.push(...walkFiles(p));
+    else out.push(p);
+  }
+  return out;
+}
+
+/**
+ * @param {object} [opts] @param {string} [opts.cwd=REPO_ROOT] @param {string[]} [opts.dirs=DE_IDENTIFIED_PATHS]
+ * @returns {Array<{ file: string, hits: Array<{label:string, match:string}> }>}
+ */
+export function findResidualIdentity(opts = {}) {
+  const cwd = opts.cwd || REPO_ROOT;
+  const dirs = opts.dirs || DE_IDENTIFIED_PATHS;
+  const exempt = new Set(opts.exemptFiles || EXEMPT_FILES);
+  const offenders = [];
+  for (const d of dirs) {
+    const abs = path.join(cwd, d);
+    if (!existsSync(abs)) continue;
+    for (const file of walkFiles(abs)) {
+      const rel = path.relative(cwd, file);
+      if (exempt.has(rel)) continue; // self-exemption (policy-asserted above)
+      let body;
+      try { body = readFileSync(file, "utf8"); } catch { continue; }
+      const hits = scanIdentity(body);
+      if (hits.length) offenders.push({ file: rel, hits });
+    }
+  }
+  return offenders;
+}
+
+/** @param {string} [cwd=REPO_ROOT] @returns {Promise<number>} */
+export async function run(cwd = REPO_ROOT) {
+  const offenders = findResidualIdentity({ cwd });
+  if (offenders.length === 0) {
+    console.log(`check-no-residual-identity: OK (${DE_IDENTIFIED_PATHS.length} de-identified path(s) clean)`);
+    return 0;
+  }
+  console.error("check-no-residual-identity: FAIL — original instance identity reintroduced into de-identified paths:");
+  for (const o of offenders) {
+    for (const h of o.hits) console.error(`  ${o.file} :: ${h.label} ("${h.match}")`);
+  }
+  return 1;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  run().then((c) => process.exit(c)).catch((e) => { console.error("check-no-residual-identity: ERROR", e && e.message ? e.message : e); process.exit(2); });
+}

package/scripts/ci/check-no-residual-identity.test.mjs

@@ -0,0 +1,89 @@
+/**
+ * check-no-residual-identity.test.mjs — the de-identification ratchet's own
+ * guard-of-the-guard (2.0 §4.5(8)):
+ *   (i)   exempt files are skipped by the scan,
+ *   (ii)  an out-of-policy exemption entry throws (the list can never grow
+ *         into a general escape hatch),
+ *   (iii) a seeded marker in a tmp corpus still fails — the exemption did not
+ *         blunt the ratchet.
+ * Run: node --test scripts/ci/check-no-residual-identity.test.mjs
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  DE_IDENTIFIED_PATHS,
+  EXEMPT_FILES,
+  IDENTITY_PATTERNS,
+  assertExemptPolicy,
+  findResidualIdentity,
+  scanIdentity,
+  run,
+} from "./check-no-residual-identity.mjs";
+
+test("ratchet coverage: 2.0 grew the de-identified paths with bin/scripts/scaffold/services", () => {
+  for (const d of ["bin", "scripts", "scaffold", "services", "lib"]) {
+    assert.ok(DE_IDENTIFIED_PATHS.includes(d), `${d} ratcheted`);
+  }
+  assert.ok(
+    IDENTITY_PATTERNS.some((p) => p.label.includes("@adaptic/")),
+    "old package scope pattern present",
+  );
+});
+
+test("(i) exempt files are skipped: a marker inside an exempt path never offends", () => {
+  const cwd = mkdtempSync(join(tmpdir(), "ratchet-"));
+  mkdirSync(join(cwd, "scripts", "ci"), { recursive: true });
+  // The exempt guard file carries identity tokens BY DESIGN.
+  writeFileSync(join(cwd, "scripts", "ci", "check-no-residual-identity.mjs"), "// patterns: Sophie Mehran Adaptic\n");
+  writeFileSync(join(cwd, "scripts", "ci", "check-no-confidential.mjs"), "// scope note naming Sophie\n");
+  const offenders = findResidualIdentity({ cwd });
+  assert.deepEqual(offenders, [], "both exempt files skipped");
+  rmSync(cwd, { recursive: true, force: true });
+});
+
+test("(ii) an out-of-policy exemption entry throws at policy assert", () => {
+  assert.doesNotThrow(() => assertExemptPolicy(EXEMPT_FILES), "the real list is in policy");
+  assert.throws(
+    () => assertExemptPolicy(["lib/org/client.mjs"]),
+    /out of policy/,
+    "a non-guard path can never self-exempt",
+  );
+  assert.throws(() => assertExemptPolicy(["scripts/ci/run-tests.mjs"]), /out of policy/, "even scripts/ci files must be check-no-* guards");
+  for (const f of EXEMPT_FILES) {
+    assert.match(f, /^scripts\/ci\/check-no-/, `${f} matches the policy prefix`);
+  }
+});
+
+test("(iii) a seeded marker in a NON-exempt file still fails the ratchet", async () => {
+  const cwd = mkdtempSync(join(tmpdir(), "ratchet-"));
+  mkdirSync(join(cwd, "scripts", "daemon"), { recursive: true });
+  mkdirSync(join(cwd, "services", "x"), { recursive: true });
+  writeFileSync(join(cwd, "scripts", "daemon", "sneaky.mjs"), 'const who = "Sophie";\n');
+  writeFileSync(join(cwd, "services", "x", "pkg.json"), '{"name": "@adaptic/oops"}\n');
+  const offenders = findResidualIdentity({ cwd });
+  assert.equal(offenders.length, 2, "both seeded markers caught");
+  const labels = offenders.flatMap((o) => o.hits.map((h) => h.label)).join("|");
+  assert.match(labels, /Sophie/);
+  assert.match(labels, /@adaptic\//);
+  const code = await run(cwd);
+  assert.equal(code, 1, "run() exits non-zero on offenders");
+  rmSync(cwd, { recursive: true, force: true });
+});
+
+test("scanIdentity flags every 2.0 pattern incl. the package scope; placeholders stay clean", () => {
+  assert.ok(scanIdentity("npm i @adaptic/maestro").some((h) => /@adaptic\//.test(h.match)));
+  assert.equal(scanIdentity("Northwind's Alex and Jordan shipped it").length, 0, "generic placeholders are intentional");
+  assert.equal(scanIdentity("").length, 0);
+});
+
+test("the LIVE repo is clean under the expanded ratchet (the commit that lands it is green)", async () => {
+  const code = await run();
+  assert.equal(code, 0, "expanded ratchet must be green in-tree");
+});

package/scripts/ci/check-tarball-fidelity.mjs

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+/**
+ * check-tarball-fidelity.mjs — packaging fidelity guard (Phase 0 item 0.13c).
+ *
+ * `npm publish` ships whatever `npm pack` produces. The cheaper static guard
+ * `check-no-build-artifacts.mjs` inspects the git index; this one inspects the
+ * *actual tarball* — the bytes that reach the fleet via `npm update`. It runs a
+ * real `npm pack` into a tmp dir, extracts it, and asserts:
+ *
+ *   1. Completeness — every package.json `files[]` entry is represented in the
+ *      tarball (a missing entry means agents install a broken tree, e.g. the
+ *      relative `../../lib/...` imports the daemon depends on would 404).
+ *   2. Hygiene — the extracted tree contains no `node_modules/`, no Python
+ *      bytecode (`*.pyc`/`*.pyo`/`__pycache__/`), and no symlinks (a tracked
+ *      symlink resolves only on the author's machine and cannot survive
+ *      pack/install; cf. the broken `validate_outbound.py` cross-tenant link).
+ *   3. Requireability — the package main (exports["."], default lib/index.js)
+ *      is present in the extracted tree, so a consumer's `import` resolves.
+ *
+ * This is a SLOW check (it shells out to `npm pack` and `tar`), so it is wired
+ * as its own opt-in npm script (`npm run test:pack`) and is NOT part of the
+ * default fast `check`/`test` path. CI runs it best-effort.
+ *
+ * Node builtins + child_process only (maestro is "type":"module", near-zero-dep).
+ *
+ * Usage: `node scripts/ci/check-tarball-fidelity.mjs`  (exit 0 ok / 1 found / 2 error)
+ * @module scripts/ci/check-tarball-fidelity
+ */
+
+"use strict";
+
+import { execFileSync } from "node:child_process";
+import {
+  mkdtempSync,
+  rmSync,
+  readFileSync,
+  readdirSync,
+  lstatSync,
+  existsSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const REPO_ROOT = path.resolve(fileURLToPath(new URL(".", import.meta.url)), "..", "..");
+
+/** Patterns that must never appear in the packaged tree. @type {Array<{label:string, re:RegExp}>} */
+export const FORBIDDEN_PATTERNS = [
+  { label: "bundled node_modules", re: /(^|\/)node_modules(\/|$)/ },
+  { label: "python bytecode (*.pyc)", re: /\.pyc$/ },
+  { label: "python bytecode (*.pyo)", re: /\.pyo$/ },
+  { label: "bytecode cache dir (__pycache__)", re: /(^|\/)__pycache__(\/|$)/ },
+];
+
+/**
+ * The "main" file a consumer's bare `import "@cohortapp/agent-sdk"` resolves to.
+ * Falls back to lib/index.js (the documented default) when exports["."] is odd.
+ * @param {object} pkg
+ * @returns {string|null} repo-relative path or null
+ */
+export function resolveMainEntry(pkg) {
+  const dot = pkg && pkg.exports && pkg.exports["."];
+  let rel = null;
+  if (typeof dot === "string") rel = dot;
+  else if (dot && typeof dot === "object") rel = dot.default || dot.import || dot.require || null;
+  rel = rel || pkg.main || "lib/index.js";
+  return rel.replace(/^\.\//, "");
+}
+
+/**
+ * Recursively walk `dir`, returning every entry as
+ *   { rel, isSymlink, isDir } with rel relative to `dir` (posix-style).
+ * Symlinks are reported but NOT followed.
+ * @param {string} dir
+ * @returns {Array<{ rel: string, isSymlink: boolean, isDir: boolean }>}
+ */
+export function walkTree(dir) {
+  const out = [];
+  const stack = [dir];
+  while (stack.length) {
+    const cur = stack.pop();
+    let entries;
+    try { entries = readdirSync(cur, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      const full = path.join(cur, e.name);
+      const rel = path.relative(dir, full).split(path.sep).join("/");
+      // Use lstat so we classify the link itself, never its target.
+      let st;
+      try { st = lstatSync(full); } catch { continue; }
+      const isSymlink = st.isSymbolicLink();
+      const isDir = !isSymlink && st.isDirectory();
+      out.push({ rel, isSymlink, isDir });
+      if (isDir) stack.push(full);
+    }
+  }
+  return out;
+}
+
+/**
+ * Run npm pack + extraction and assess the tarball. Pure-ish: takes no globals
+ * beyond REPO_ROOT and the filesystem, cleans up its own tmp dir.
+ *
+ * @param {object} [opts] @param {string} [opts.cwd=REPO_ROOT]
+ * @returns {{ ok: boolean, offenders: Array<{file:string,reason:string}>, missing: string[], tarballFiles: number, mainEntry: string }}
+ */
+export function checkTarball(opts = {}) {
+  const cwd = opts.cwd || REPO_ROOT;
+  const pkg = JSON.parse(readFileSync(path.join(cwd, "package.json"), "utf8"));
+  const filesAllowlist = Array.isArray(pkg.files) ? pkg.files : [];
+  const mainEntry = resolveMainEntry(pkg);
+
+  const work = mkdtempSync(path.join(tmpdir(), "maestro-pack-"));
+  try {
+    // 1) Real pack into the tmp dir. --json gives the manifest; the .tgz lands
+    //    in --pack-destination. Suppress npm's own stdout noise via --silent.
+    const raw = execFileSync(
+      "npm",
+      ["pack", "--json", "--silent", "--pack-destination", work],
+      { cwd, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 },
+    );
+    const manifest = JSON.parse(raw);
+    const entry = Array.isArray(manifest) ? manifest[0] : manifest;
+    const tarballPath = path.join(work, entry.filename);
+
+    // 2) Extract the tarball (npm tarballs root everything under "package/").
+    execFileSync("tar", ["-xzf", tarballPath, "-C", work]);
+    const pkgRoot = path.join(work, "package");
+    if (!existsSync(pkgRoot)) {
+      throw new Error(`extracted tarball has no package/ root (${tarballPath})`);
+    }
+
+    const tree = walkTree(pkgRoot);
+    const filePaths = tree.filter((t) => !t.isDir).map((t) => t.rel);
+
+    // 3) Hygiene — forbidden artifacts + symlinks in the EXTRACTED tree.
+    const offenders = [];
+    for (const t of tree) {
+      if (t.isSymlink) {
+        offenders.push({ file: t.rel, reason: "symlink in tarball (does not survive install; may point cross-tenant)" });
+        continue;
+      }
+      for (const p of FORBIDDEN_PATTERNS) {
+        if (p.re.test(t.rel)) { offenders.push({ file: t.rel, reason: p.label }); break; }
+      }
+    }
+
+    // 4) Completeness — every files[] entry must be represented. A directory
+    //    entry (e.g. "lib/") is satisfied by any packaged path beneath it; a
+    //    file entry must appear verbatim.
+    const missing = [];
+    for (const decl of filesAllowlist) {
+      const norm = decl.replace(/^\.\//, "").replace(/\/+$/, "");
+      const asDirPrefix = norm + "/";
+      const present = filePaths.some(
+        (f) => f === norm || f.startsWith(asDirPrefix),
+      );
+      if (!present) missing.push(decl);
+    }
+
+    // 5) Requireability — the package main must be in the tree.
+    if (!filePaths.includes(mainEntry)) {
+      missing.push(`${mainEntry} (package main / exports["."])`);
+    }
+
+    return {
+      ok: offenders.length === 0 && missing.length === 0,
+      offenders,
+      missing,
+      tarballFiles: filePaths.length,
+      mainEntry,
+    };
+  } finally {
+    try { rmSync(work, { recursive: true, force: true }); } catch { /* */ }
+  }
+}
+
+/** @param {string} [cwd=REPO_ROOT] @returns {Promise<number>} */
+export async function run(cwd = REPO_ROOT) {
+  let res;
+  try {
+    res = checkTarball({ cwd });
+  } catch (err) {
+    console.error(`check-tarball-fidelity: ERROR — ${err && err.message ? err.message : err}`);
+    return 2;
+  }
+  if (res.ok) {
+    console.log(`check-tarball-fidelity: OK (${res.tarballFiles} files; main "${res.mainEntry}" present; no node_modules/.pyc/symlinks)`);
+    return 0;
+  }
+  if (res.missing.length) {
+    console.error("check-tarball-fidelity: FAIL — declared files[] / main missing from the tarball:");
+    for (const m of res.missing) console.error(`  ${m}`);
+  }
+  if (res.offenders.length) {
+    console.error("check-tarball-fidelity: FAIL — forbidden artifacts in the tarball:");
+    for (const o of res.offenders) console.error(`  ${o.file} :: ${o.reason}`);
+  }
+  return 1;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  run()
+    .then((c) => process.exit(c))
+    .catch((e) => { console.error("check-tarball-fidelity: ERROR", e && e.message ? e.message : e); process.exit(2); });
+}

package/scripts/ci/check-unresolved-tokens.mjs

@@ -0,0 +1,83 @@
+/**
+ * check-unresolved-tokens.mjs — CI guard that fails if a framework prompt file
+ * contains a `{{token}}` outside the known render vocabulary.
+ *
+ * Framework operational prompts (triggers, agent definitions, skills, prompt
+ * templates) carry {{agent.*}} identity tokens that lib/render.mjs resolves at
+ * load time. A typo ({{agent.firstname}}) or stray braces would render to
+ * nothing and ship a broken prompt to a model. This guard scans those files and
+ * fails on any token not in lib/render.mjs KNOWN_TOKENS.
+ *
+ * Pure, dependency-light: Node builtins + lib/render.mjs. ESM.
+ *
+ * Usage: `node scripts/ci/check-unresolved-tokens.mjs`  (exit 0 ok / 1 found)
+ * @module scripts/ci/check-unresolved-tokens
+ */
+
+"use strict";
+
+import { readdirSync, readFileSync, existsSync, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { unknownTokens } from "../../lib/render.mjs";
+
+const REPO_ROOT = path.resolve(fileURLToPath(new URL(".", import.meta.url)), "..", "..");
+
+/** Directories whose .md prompt files carry render tokens. @type {string[]} */
+export const SCAN_DIRS = [
+  "schedules/triggers",
+  "agents",
+  "plugins/maestro-skills/skills",
+  "docs/prompts",
+];
+
+/** Recursively collect *.md files under a directory. */
+function walkMd(dir) {
+  const out = [];
+  for (const name of readdirSync(dir)) {
+    const p = path.join(dir, name);
+    let st;
+    try { st = statSync(p); } catch { continue; }
+    if (st.isDirectory()) out.push(...walkMd(p));
+    else if (name.endsWith(".md")) out.push(p);
+  }
+  return out;
+}
+
+/**
+ * Find prompt files containing unknown tokens.
+ * @param {object} [opts] @param {string} [opts.cwd=REPO_ROOT] @param {string[]} [opts.dirs=SCAN_DIRS]
+ * @returns {Array<{ file: string, tokens: string[] }>}
+ */
+export function findUnresolvedTokens(opts = {}) {
+  const cwd = opts.cwd || REPO_ROOT;
+  const dirs = opts.dirs || SCAN_DIRS;
+  const offenders = [];
+  for (const d of dirs) {
+    const abs = path.join(cwd, d);
+    if (!existsSync(abs)) continue;
+    for (const file of walkMd(abs)) {
+      let body;
+      try { body = readFileSync(file, "utf8"); } catch { continue; }
+      const bad = unknownTokens(body);
+      if (bad.length) offenders.push({ file: path.relative(cwd, file), tokens: bad });
+    }
+  }
+  return offenders;
+}
+
+/** @param {string} [cwd=REPO_ROOT] @returns {Promise<number>} */
+export async function run(cwd = REPO_ROOT) {
+  const offenders = findUnresolvedTokens({ cwd });
+  if (offenders.length === 0) {
+    console.log("check-unresolved-tokens: OK (no unknown {{tokens}} in prompt files)");
+    return 0;
+  }
+  console.error("check-unresolved-tokens: FAIL — unknown/typo tokens that will not render:");
+  for (const o of offenders) console.error(`  ${o.file}: ${o.tokens.map((t) => `{{${t}}}`).join(", ")}`);
+  return 1;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  run().then((c) => process.exit(c)).catch((e) => { console.error("check-unresolved-tokens: ERROR", e && e.message ? e.message : e); process.exit(2); });
+}

package/scripts/ci/check.mjs

@@ -0,0 +1,109 @@
+/**
+ * check.mjs — CI guard aggregator. Runs every individual maestro CI guard and
+ * exits non-zero if any of them fail, printing a one-line-per-check summary.
+ *
+ * Adapted from OpenClaw's scripts/check.mjs runner. Pure, dependency-light:
+ * Node builtins only. ESM module (maestro is "type":"module").
+ *
+ * Each guard is imported as a module and its `run()` is awaited, so a single
+ * Node process executes the whole suite (no per-check subprocess spawn). A
+ * guard that throws is treated as a failure rather than crashing the suite, so
+ * the summary still lists every check's outcome.
+ *
+ * Currently aggregates:
+ *   - check-no-conflict-markers : no git conflict markers in tracked files
+ *   - check-exports-exist       : every package.json exports[] target exists
+ *   - check-files-exist         : every package.json files[] entry exists
+ *   - check-no-confidential     : no confidential instance data in the tarball
+ *   - check-unresolved-tokens   : no unknown {{tokens}} in framework prompt files
+ *   - check-no-residual-identity: de-Robin'd paths stay persona-agnostic
+ *   - check-no-build-artifacts  : no tracked .pyc/symlinks reach the tarball
+ *   - check-docs-accuracy       : README links resolve; counts/agent-refs WARN
+ *
+ * Usage: `node scripts/ci/check.mjs`
+ *   exit 0 → all checks passed; exit 1 → one or more failed.
+ *
+ * @module scripts/ci/check
+ */
+
+"use strict";
+
+import { run as runConflictMarkers } from "./check-no-conflict-markers.mjs";
+import { run as runExportsExist } from "./check-exports-exist.mjs";
+import { run as runFilesExist } from "./check-files-exist.mjs";
+import { run as runNoConfidential } from "./check-no-confidential.mjs";
+import { run as runUnresolvedTokens } from "./check-unresolved-tokens.mjs";
+import { run as runNoResidualIdentity } from "./check-no-residual-identity.mjs";
+import { run as runNoBuildArtifacts } from "./check-no-build-artifacts.mjs";
+import { run as runDocsAccuracy } from "./check-docs-accuracy.mjs";
+
+/**
+ * The ordered list of guards this aggregator runs.
+ * Each entry's `run` returns a Promise<number> exit code (0 = pass).
+ * @type {Array<{ name: string, run: () => Promise<number> }>}
+ */
+export const CHECKS = [
+  { name: "check-no-conflict-markers", run: runConflictMarkers },
+  { name: "check-exports-exist", run: runExportsExist },
+  { name: "check-files-exist", run: runFilesExist },
+  { name: "check-no-confidential", run: runNoConfidential },
+  { name: "check-unresolved-tokens", run: runUnresolvedTokens },
+  { name: "check-no-residual-identity", run: runNoResidualIdentity },
+  { name: "check-no-build-artifacts", run: runNoBuildArtifacts },
+  { name: "check-docs-accuracy", run: runDocsAccuracy },
+];
+
+/**
+ * Run every guard in {@link CHECKS}, capturing pass/fail without letting one
+ * throw abort the rest.
+ *
+ * @param {Array<{ name: string, run: () => Promise<number> }>} [checks=CHECKS]
+ * @returns {Promise<{ ok: boolean, results: Array<{ name: string, passed: boolean, code: number, error?: string }> }>}
+ */
+export async function runAll(checks = CHECKS) {
+  const results = [];
+  for (const check of checks) {
+    try {
+      const code = await check.run();
+      results.push({ name: check.name, passed: code === 0, code });
+    } catch (err) {
+      results.push({
+        name: check.name,
+        passed: false,
+        code: 2,
+        error: err && err.message ? err.message : String(err),
+      });
+    }
+  }
+  const ok = results.every((r) => r.passed);
+  return { ok, results };
+}
+
+/**
+ * Run all checks and print a summary block.
+ *
+ * @returns {Promise<number>} Process exit code (0 = all passed, 1 = any failed).
+ */
+export async function run() {
+  const { ok, results } = await runAll();
+  console.log("");
+  console.log("=== maestro CI guards summary ===");
+  for (const r of results) {
+    const mark = r.passed ? "PASS" : "FAIL";
+    const extra = r.error ? `  (error: ${r.error})` : "";
+    console.log(`  [${mark}] ${r.name}${extra}`);
+  }
+  const passedCount = results.filter((r) => r.passed).length;
+  console.log(`=== ${passedCount}/${results.length} checks passed ===`);
+  return ok ? 0 : 1;
+}
+
+// Run when invoked directly (not when imported).
+if (import.meta.url === `file://${process.argv[1]}`) {
+  run()
+    .then((code) => process.exit(code))
+    .catch((err) => {
+      console.error("check (aggregator): ERROR", err && err.message ? err.message : err);
+      process.exit(2);
+    });
+}