@cohortapp/agent-sdk 2.11.15 → 2.13.0

package/scripts/setup/init-agent.test.mjs

@@ -13,7 +13,8 @@
 
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { readFileSync, writeFileSync, mkdtempSync, rmSync } from "node:fs";
+import { readFileSync, writeFileSync, mkdtempSync, mkdirSync, chmodSync, existsSync, rmSync, readdirSync } from "node:fs";
+import { spawnSync } from "node:child_process";
 import { execFileSync } from "node:child_process";
 import { join, dirname } from "node:path";
 import { tmpdir } from "node:os";
@@ -137,6 +138,14 @@ test("init-agent.sh additions contain no allow-all permissions or dangerous-skip
   assert.ok(!m[1].includes("Bash(*)"), "additions must not contain Bash(*) allow-all");
 });
 
+test("init-agent.sh creates the front-door session state and log directories", () => {
+  // launchd creates StandardOutPath's FILE but not its directory; the session
+  // plist logs to logs/session/. The feed/supervisor write under state/session/.
+  for (const d of ["logs/session", "state/session", "state/session/handoffs/done"]) {
+    assert.ok(scriptSrc.includes(`"${d}"`), `DIRS must include ${d}`);
+  }
+});
+
 test("init-agent.sh chmods the .env to 600", () => {
   assert.ok(/chmod 600 "\$ENV_FILE"/.test(scriptSrc),
     "the agent .env must be chmod 600 after writing (no world-readable credentials)");
@@ -149,3 +158,213 @@ test("init-agent.sh deep-merges rather than cat>-overwriting settings.json", ()
   assert.ok(scriptSrc.includes("node -e \"$MAESTRO_MERGE_NODE\""),
     "the merge must run via the embedded node program");
 });
+
+// ---------------------------------------------------------------------------
+// Front-door session prerequisites (design §3.7 / §6 WP-M3): the global SDK
+// install and a terminal multiplexer. The block is embedded in init-agent.sh
+// between BEGIN/END markers; we extract that exact block and run it under
+// bash with stub binaries, so the test pins what the script actually ships.
+// ---------------------------------------------------------------------------
+
+function extractGlobalSdkBlock() {
+  const m = scriptSrc.match(/# --- BEGIN maestro global-sdk check[^\n]*\n([\s\S]*?)# --- END maestro global-sdk check ---/);
+  assert.ok(m, "global-sdk check block (BEGIN/END markers) not found in init-agent.sh");
+  return m[1];
+}
+
+/**
+ * Run the extracted block with a stub `npm` (and optional `tmux`) on PATH.
+ * `npm ls -g` exits per `installed`; `npm view` prints `latest`; every call is
+ * appended to calls.log. Returns {status, stdout, calls}.
+ */
+function runGlobalSdkBlock({ installed, installedVersion = "1.0.0", latest = "1.0.0", tmux = false, screenBin, env = {} }) {
+  const dir = makeTmp();
+  try {
+    const bin = join(dir, "bin");
+    const log = join(dir, "calls.log");
+    mkdirSync(bin, { recursive: true });
+    writeFileSync(join(bin, "npm"), `#!/bin/bash
+echo "npm $*" >> "${log}"
+case "$1" in
+  ls) ${installed ? `echo "/usr/local/lib"; echo "└── @cohortapp/agent-sdk@${installedVersion}"; exit 0` : "exit 1"} ;;
+  view) echo "${latest}"; exit 0 ;;
+  install) exit 0 ;;
+esac
+exit 0
+`);
+    chmodSync(join(bin, "npm"), 0o755);
+    if (tmux) { writeFileSync(join(bin, "tmux"), "#!/bin/bash\necho 'tmux 3.4'\n"); chmodSync(join(bin, "tmux"), 0o755); }
+    const prog = `log(){ echo "[init] $1"; }; ok(){ echo "  ok $1"; }; warn(){ echo "  warn $1"; }; fail(){ echo "  FAIL $1"; exit 1; }\n${extractGlobalSdkBlock()}`;
+    writeFileSync(join(dir, "block.sh"), prog);
+    const r = spawnSync("/bin/bash", [join(dir, "block.sh")], {
+      encoding: "utf8",
+      env: { PATH: `${bin}:${env.MAESTRO_TEST_EXTRA_PATH ? `${env.MAESTRO_TEST_EXTRA_PATH}:` : ""}/usr/bin:/bin`, HOME: dir, MAESTRO_SCREEN_BIN: screenBin || join(dir, "no-such-screen"), ...env },
+    });
+    const calls = existsSync(log) ? readFileSync(log, "utf8") : "";
+    return { status: r.status, stdout: r.stdout + r.stderr, calls };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+test("global SDK present and current: verified, nothing installed", () => {
+  const r = runGlobalSdkBlock({ installed: true, installedVersion: "2.0.0", latest: "2.0.0", tmux: true });
+  assert.equal(r.status, 0, r.stdout);
+  assert.match(r.calls, /^npm ls -g @cohortapp\/agent-sdk/m, `must verify with npm ls -g; calls:\n${r.calls}`);
+  assert.ok(!/npm install -g/.test(r.calls), `must not install; calls:\n${r.calls}`);
+  assert.match(r.stdout, /Global SDK.*2\.0\.0/);
+});
+
+test("global SDK missing: installs @latest", () => {
+  const r = runGlobalSdkBlock({ installed: false, tmux: true });
+  assert.equal(r.status, 0, r.stdout);
+  assert.match(r.calls, /^npm install -g @cohortapp\/agent-sdk@latest/m, `expected a global install; calls:\n${r.calls}`);
+});
+
+test("global SDK outdated: upgrades to @latest", () => {
+  const r = runGlobalSdkBlock({ installed: true, installedVersion: "1.0.0", latest: "2.0.0", tmux: true });
+  assert.equal(r.status, 0, r.stdout);
+  assert.match(r.calls, /^npm install -g @cohortapp\/agent-sdk@latest/m, `expected an upgrade; calls:\n${r.calls}`);
+});
+
+test("MAESTRO_SKIP_GLOBAL_INSTALL=1 verifies but never installs or upgrades", () => {
+  for (const scenario of [{ installed: false }, { installed: true, installedVersion: "1.0.0", latest: "2.0.0" }]) {
+    const r = runGlobalSdkBlock({ ...scenario, tmux: true, env: { MAESTRO_SKIP_GLOBAL_INSTALL: "1" } });
+    assert.equal(r.status, 0, r.stdout);
+    assert.match(r.calls, /^npm ls -g @cohortapp\/agent-sdk/m, "still verifies");
+    assert.ok(!/npm install/.test(r.calls), `must not install under the skip flag; calls:\n${r.calls}`);
+    assert.match(r.stdout, /MAESTRO_SKIP_GLOBAL_INSTALL/, "must say why it skipped");
+  }
+});
+
+test("multiplexer: tmux preferred, /usr/bin/screen accepted, neither → warning naming brew install tmux", () => {
+  const withTmux = runGlobalSdkBlock({ installed: true, tmux: true });
+  assert.match(withTmux.stdout, /tmux/);
+  const dir = makeTmp();
+  try {
+    const screen = join(dir, "screen");
+    writeFileSync(screen, "#!/bin/bash\necho 'Screen version 4.00.03'\n"); chmodSync(screen, 0o755);
+    const withScreen = runGlobalSdkBlock({ installed: true, tmux: false, screenBin: screen });
+    assert.equal(withScreen.status, 0, withScreen.stdout);
+    assert.match(withScreen.stdout, /screen/i);
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+  const neither = runGlobalSdkBlock({ installed: true, tmux: false });
+  assert.equal(neither.status, 0, "a missing multiplexer is a warning, not a fatal (screen ships with macOS)");
+  assert.match(neither.stdout, /brew install tmux/);
+});
+
+// ---------------------------------------------------------------------------
+// Review fixes (2026-09-08): the global-sdk block also verifies PATH and never
+// blocks on the registry; Step 5 never unload/loads a live session or daemon.
+// ---------------------------------------------------------------------------
+
+test("global SDK block: `npm view` carries a fetch timeout so an offline init-agent does not hang for minutes", () => {
+  const r = runGlobalSdkBlock({ installed: true, installedVersion: "2.0.0", latest: "2.0.0", tmux: true });
+  assert.match(r.calls, /^npm view @cohortapp\/agent-sdk version.*--fetch-timeout=\d+/m, `calls:\n${r.calls}`);
+});
+
+test("global SDK block: verifies that maestro and cohort-mcp resolve on PATH (spec §3.7(6))", () => {
+  const missing = runGlobalSdkBlock({ installed: true, installedVersion: "2.0.0", latest: "2.0.0", tmux: true });
+  assert.equal(missing.status, 0, missing.stdout);
+  assert.match(missing.stdout, /warn.*maestro.*not on PATH|warn.*not on PATH.*maestro/i, `must warn when maestro is missing from PATH:\n${missing.stdout}`);
+  assert.match(missing.stdout, /cohort-mcp/, "must name cohort-mcp too");
+  // Present on PATH → ok lines naming both.
+  const dir = makeTmp();
+  try {
+    const extra = join(dir, "gbin");
+    mkdirSync(extra, { recursive: true });
+    for (const b of ["maestro", "cohort-mcp"]) { writeFileSync(join(extra, b), "#!/bin/bash\nexit 0\n"); chmodSync(join(extra, b), 0o755); }
+    const present = runGlobalSdkBlock({ installed: true, installedVersion: "2.0.0", latest: "2.0.0", tmux: true, env: { MAESTRO_TEST_EXTRA_PATH: extra } });
+    assert.equal(present.status, 0, present.stdout);
+    assert.match(present.stdout, /ok.*maestro on PATH/i, present.stdout);
+    assert.match(present.stdout, /ok.*cohort-mcp on PATH/i, present.stdout);
+    assert.ok(!/not on PATH/.test(present.stdout));
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+});
+
+function extractLaunchdBlock() {
+  const m = scriptSrc.match(/# --- BEGIN maestro launchd install[^\n]*\n([\s\S]*?)# --- END maestro launchd install ---/);
+  assert.ok(m, "launchd install block (BEGIN/END markers) not found in init-agent.sh");
+  return m[1];
+}
+
+/**
+ * Run Step 5 with a stub launchctl whose `list <label>` exits 0 for labels in
+ * `loaded`. Generated plists live in scripts/local-triggers/plists/ of a
+ * fixture agent dir. Returns {status, stdout, calls, home}.
+ */
+function runLaunchdBlock({ plists, loaded = [], supervisor = true, migrate = false }) {
+  const dir = makeTmp();
+  const agent = join(dir, "agent");
+  const home = join(dir, "home");
+  const bin = join(dir, "bin");
+  const log = join(dir, "calls.log");
+  mkdirSync(join(agent, "scripts", "local-triggers", "plists"), { recursive: true });
+  mkdirSync(join(agent, "scripts", "session"), { recursive: true });
+  mkdirSync(join(agent, "scripts", "poller-launchd"), { recursive: true });
+  mkdirSync(join(home, "Library", "LaunchAgents"), { recursive: true });
+  mkdirSync(bin, { recursive: true });
+  for (const label of plists) writeFileSync(join(agent, "scripts", "local-triggers", "plists", `${label}.plist`), `<plist>${label}</plist>\n`);
+  if (supervisor) writeFileSync(join(agent, "scripts", "session", "supervisor.sh"), "#!/bin/bash\n");
+  if (migrate) { writeFileSync(join(agent, "scripts", "poller-launchd", "migrate.sh"), `#!/bin/bash\necho "migrate $*" >> "${log}"\n`); chmodSync(join(agent, "scripts", "poller-launchd", "migrate.sh"), 0o755); }
+  writeFileSync(join(bin, "launchctl"), `#!/bin/bash
+echo "launchctl $*" >> "${log}"
+if [ "$1" = "list" ] && [ -n "$2" ]; then case " ${loaded.join(" ")} " in *" $2 "*) exit 0 ;; *) exit 1 ;; esac; fi
+exit 0
+`);
+  chmodSync(join(bin, "launchctl"), 0o755);
+  const prog = `set -u
+log(){ echo "[init] $1"; }; ok(){ echo "  ok $1"; }; warn(){ echo "  warn $1"; }
+AGENT_DIR="${agent}"
+LAUNCH_AGENTS_DIR="$HOME/Library/LaunchAgents"
+PLIST_DIR="$AGENT_DIR/scripts/local-triggers/plists"
+${extractLaunchdBlock()}`;
+  writeFileSync(join(dir, "block.sh"), prog);
+  const r = spawnSync("/bin/bash", [join(dir, "block.sh")], { encoding: "utf8", env: { PATH: `${bin}:/usr/bin:/bin`, HOME: home } });
+  const calls = existsSync(log) ? readFileSync(log, "utf8") : "";
+  const installed = readdirSync(join(home, "Library", "LaunchAgents"));
+  rmSync(dir, { recursive: true, force: true });
+  return { status: r.status, stdout: r.stdout + r.stderr, calls, installed };
+}
+
+test("Step 5: a LOADED session or daemon job is rewritten but never unloaded/loaded on a re-run (WP-M6 'never bootout')", () => {
+  const r = runLaunchdBlock({
+    plists: ["ai.maestro.ivy-session", "ai.maestro.ivy-daemon", "ai.maestro.ivy-daily-brief"],
+    loaded: ["ai.maestro.ivy-session", "ai.maestro.ivy-daemon", "ai.maestro.ivy-daily-brief"],
+  });
+  assert.equal(r.status, 0, r.stdout);
+  assert.ok(!/launchctl (unload|bootout)[^\n]*-session/.test(r.calls), `must not unload the session job; calls:\n${r.calls}`);
+  assert.ok(!/launchctl load[^\n]*-session/.test(r.calls), `must not re-load a loaded session job; calls:\n${r.calls}`);
+  assert.ok(!/launchctl (unload|bootout|load)[^\n]*-daemon/.test(r.calls), `must not unload/load a loaded daemon; calls:\n${r.calls}`);
+  // The trigger job keeps today's unload + load (its script may have changed).
+  assert.match(r.calls, /launchctl unload[^\n]*daily-brief/);
+  assert.match(r.calls, /launchctl load[^\n]*daily-brief/);
+  // Files are still refreshed for all three.
+  assert.deepEqual(r.installed.sort(), ["ai.maestro.ivy-daemon.plist", "ai.maestro.ivy-daily-brief.plist", "ai.maestro.ivy-session.plist"]);
+  assert.match(r.stdout, /kept running/i);
+});
+
+test("Step 5: a NOT-loaded session/daemon job is installed and loaded (first run)", () => {
+  const r = runLaunchdBlock({ plists: ["ai.maestro.ivy-session", "ai.maestro.ivy-daemon"], loaded: [] });
+  assert.equal(r.status, 0, r.stdout);
+  assert.match(r.calls, /launchctl load[^\n]*ai\.maestro\.ivy-session\.plist/);
+  assert.match(r.calls, /launchctl load[^\n]*ai\.maestro\.ivy-daemon\.plist/);
+  assert.ok(!/launchctl unload/.test(r.calls), "nothing to unload on a first run");
+});
+
+test("Step 5: the session plist is skipped when scripts/session/supervisor.sh is absent (launchd would retry every 30 s forever)", () => {
+  const r = runLaunchdBlock({ plists: ["ai.maestro.ivy-session", "ai.maestro.ivy-daemon"], loaded: [], supervisor: false });
+  assert.equal(r.status, 0, r.stdout);
+  assert.ok(!/-session/.test(r.calls), `must not load a session plist with no supervisor; calls:\n${r.calls}`);
+  assert.ok(!r.installed.includes("ai.maestro.ivy-session.plist"));
+  assert.match(r.stdout, /supervisor\.sh/);
+  assert.match(r.calls, /launchctl load[^\n]*-daemon/);
+});
+
+test("Step 5: runs the poller-plist migration (audit F6 follow-through) when it ships", () => {
+  const r = runLaunchdBlock({ plists: ["ai.maestro.ivy-daemon"], migrate: true });
+  assert.equal(r.status, 0, r.stdout);
+  assert.match(r.calls, /^migrate/m, `calls:\n${r.calls}`);
+  const without = runLaunchdBlock({ plists: ["ai.maestro.ivy-daemon"], migrate: false });
+  assert.equal(without.status, 0, "an absent migrate.sh is not an error");
+});

package/scripts/vendor/skill-packs.mjs

@@ -0,0 +1,354 @@
+/**
+ * scripts/vendor/skill-packs.mjs — the pinned registry of vendored design
+ * skill packs, and the pure helpers both the syncer and the CI guard share.
+ *
+ * WP-M7 vendors four upstream Claude Code design skill packs into
+ * `plugins/maestro-skills/vendor/<pack>/` so that every seat gets them from the
+ * npm tarball. Two properties matter more than convenience and are enforced by
+ * `scripts/ci/check-skill-packs.mjs`:
+ *
+ *   1. **Pinned and verifiable.** Each pack is a single upstream commit; every
+ *      vendored byte is recorded in `UPSTREAM.json` as a sha256. The SDK never
+ *      fetches skill content at install or run time on a seat — vendoring is a
+ *      reviewed commit, and the guard is what makes "reviewed" mean something.
+ *   2. **Markdown, not machinery.** The allow-list below takes skill prose and
+ *      its reference files. It deliberately leaves behind every executable
+ *      seam an upstream pack carries: hook manifests, launchers that download a
+ *      binary on first run, browser-automation bundles and font-index data.
+ *      Nothing in a vendored tree is ever executed by maestro.
+ *
+ * The allow-list is expressed as *rules* (one file, or one directory filtered
+ * by a regex) rather than a flat path list, because the syncer must be able to
+ * re-derive the tree from a fresh upstream checkout AND the guard must be able
+ * to decide, with no network, whether a path that exists on disk was allowed.
+ * {@link isAllowedDest} is that second half.
+ *
+ * Pure, dependency-light: Node builtins only, no I/O in this module.
+ *
+ * @module scripts/vendor/skill-packs
+ */
+
+"use strict";
+
+import { createHash } from "node:crypto";
+
+/** @param {string} text */
+function sha256Hex(text) {
+  return createHash("sha256").update(text).digest("hex");
+}
+
+/**
+ * @typedef {object} PackRule
+ * @property {"file"|"dir"} type
+ * @property {string} from       path in the upstream tree (POSIX, repo-relative)
+ * @property {string} to         path in the vendored pack (POSIX, pack-relative); "" = pack root
+ * @property {RegExp} [match]    for `dir`: which basenames to take
+ * @property {boolean} [recursive] for `dir`: descend into subdirectories
+ */
+
+/**
+ * @typedef {object} SkillPack
+ * @property {string} id          directory under plugins/maestro-skills/vendor/
+ * @property {string} repo        "<owner>/<name>" on github.com
+ * @property {string} sha         the pinned commit
+ * @property {string} date        the pinned commit's date (ISO, informational)
+ * @property {string} license     SPDX id
+ * @property {PackRule[]} rules   the allow-list
+ * @property {string[]} omitted   what upstream carries that we deliberately drop
+ * @property {string[]} skillRoots pack-relative dirs that each hold one SKILL.md
+ * @property {string[]} [execAllowed] pack-relative dir prefixes where a file may carry an executable bit
+ * @property {string} notes
+ * @property {string} [contentSha256] {@link manifestDigest} of the vendored file list
+ * @property {Acknowledgement[]} [acknowledged] the supply-chain tokens this pack's prose is known to carry
+ */
+
+/**
+ * One reviewed supply-chain token. Vendored prose is not code we run, but it IS
+ * read as instructions, and "fetch this and run it" is the same capability
+ * whether it arrives as `curl | sh`, `npx some-package`, or a CDN script tag in
+ * markup the reader is told to emit. The guard extracts a token for each such
+ * instruction it finds; a token with no entry here fails the build, which is
+ * how a re-sync that pulls in a NEW one stops rather than shipping.
+ *
+ * `covered` is the literal that must appear in
+ * `plugins/maestro-skills/skills/cohort-design.md`. Acknowledging a capability
+ * without telling a reader what to do instead is not a review, so the guard
+ * checks the prose too.
+ *
+ * @typedef {object} Acknowledgement
+ * @property {string} token
+ * @property {string} why
+ * @property {string} covered
+ */
+
+/** Hosts a vendored file may legitimately point a fetch instruction at. */
+export const FETCH_HOST_ALLOWLIST = Object.freeze([
+  "github.com",
+  "www.github.com",
+  "raw.githubusercontent.com",
+  "objects.githubusercontent.com",
+  "codeload.github.com",
+  "gist.github.com",
+  "api.github.com",
+]);
+
+/**
+ * Basenames that ARE the hook machinery, wherever a pack keeps them. A vendored
+ * tree must never contain one: `install-hooks.mjs` writes a Stop hook into a
+ * settings file (its `--global` flag writes the one every session on the
+ * machine reads), and `stop-hook.mjs` is the body that hook runs. Stripping the
+ * executable bit is cosmetic — `node <file>` does not consult it — so the only
+ * honest neutralisation is absence.
+ */
+export const HOOK_SCRIPT_BASENAMES = Object.freeze([
+  "install-hooks.mjs", "stop-hook.mjs", "install-hook.mjs", "hooks.mjs", "hook.mjs",
+]);
+
+/**
+ * The digest of a manifest's file list — sha256 over `"<path> <sha256>"` lines,
+ * sorted, newline-terminated.
+ *
+ * This is what makes the allow-list a ratchet rather than a description. A
+ * per-file sha256 recorded in `UPSTREAM.json` proves only that the manifest and
+ * the tree agree with each other, so a single commit that adds a file AND its
+ * hash — a poisoned re-sync, a hand-edit with cover — is self-consistent and
+ * passes. Pinning this digest in THIS module, which nothing in a vendored tree
+ * can reach, means such a change must also edit a reviewed source file whose
+ * diff says "the vendored bytes changed" in one line.
+ *
+ * @param {Array<{path:string, sha256:string}>} files
+ * @returns {string}
+ */
+export function manifestDigest(files) {
+  const lines = (files || [])
+    .map((f) => `${posix(f && f.path)} ${String((f && f.sha256) || "")}`)
+    .sort();
+  return sha256Hex(`${lines.join("\n")}\n`);
+}
+
+/** Every pack, in install order. @type {SkillPack[]} */
+export const PACKS = Object.freeze([
+  {
+    id: "impeccable",
+    contentSha256: "0185da328c829c1d2265e3c61c608afc415103e07912a1e09cf05c6825c272f5",
+    repo: "pbakaus/impeccable",
+    sha: "cd12f8660e2dde57b9615c8a6b8ea674101f9cfc",
+    date: "2026-09-09",
+    license: "Apache-2.0",
+    skillRoots: ["."],
+    rules: [
+      { type: "file", from: ".claude/skills/impeccable/SKILL.md", to: "SKILL.md" },
+      { type: "dir", from: ".claude/skills/impeccable/reference", to: "reference", match: /\.md$/, recursive: true },
+      { type: "dir", from: ".claude/agents", to: "agents", match: /^impeccable-[a-z0-9-]+\.md$/, recursive: false },
+      { type: "file", from: "LICENSE", to: "LICENSE" },
+      { type: "file", from: "NOTICE.md", to: "NOTICE.md" },
+    ],
+    omitted: [
+      "hooks (plugin/hooks/hooks.json, .claude/settings.json) — maestro installs no hook from a vendored pack",
+      "skill scripts/ — the `impeccable` launcher downloads and runs a self-contained binary on first use; never run it on a seat",
+      "scripts/data/ (font-index.json, font-index-failures.json) — data for that launcher, ~20 MB",
+      "live-browser*.js, modern-screenshot.umd.js — live browser-automation mode, out of scope on a seat",
+      ".claude-plugin/ and the other per-agent manifest trees (.cursor/, .gemini/, plugin/, …)",
+      "crates/, cli/, extension/, browser-bundle/, tests/, docs/ — the engine repo around the skill",
+    ],
+    acknowledged: [
+      {
+        token: "npx:impeccable",
+        why: "reference/doctor.md and reference/hooks.md offer `npx impeccable update|detect|ignores` as the recovery path when the launcher is missing — which on a seat it always is, because scripts/ is not vendored. That is a registry fetch-and-execute and is exactly what vendoring exists to avoid.",
+        covered: "npx impeccable",
+      },
+      {
+        token: "hook-install-doc",
+        why: "reference/hooks.md is a full guide to writing the impeccable hook into .claude/settings.local.json, .codex/hooks.json, .cursor/hooks.json and .github/hooks/impeccable.json. The file is prose, not a manifest, so the no-manifest rule cannot see it.",
+        covered: "no hook from any of these packs is installed, and none should be",
+      },
+    ],
+    notes: "Skill 4.3.1, Apache-2.0. Markdown only: SKILL.md, reference/**.md and the four impeccable-* subordinate briefs. The SKILL text still describes its launcher; the cohort-design harmoniser overrides that — never run it, and never use live mode on a seat.",
+  },
+  {
+    id: "emilkowalski",
+    contentSha256: "2c8397c22777f6cd71f7ea91e729799ef4128932a39be0f6f8068c8c1dbb5b92",
+    repo: "emilkowalski/skills",
+    sha: "d23d7f88a2e21c9e4b1418c7abe420f5c1052ba7",
+    date: "2026-08-21",
+    license: "MIT",
+    skillRoots: [
+      "skills/emil-design-eng",
+      "skills/animate",
+      "skills/animation-vocabulary",
+      "skills/apple-design",
+      "skills/find-animation-opportunities",
+      "skills/improve-animations",
+      "skills/review-animations",
+      "skills/prototype",
+    ],
+    rules: [
+      { type: "dir", from: "skills/emil-design-eng", to: "skills/emil-design-eng", match: /\.md$/, recursive: false },
+      { type: "dir", from: "skills/animate", to: "skills/animate", match: /\.md$/, recursive: false },
+      { type: "dir", from: "skills/animation-vocabulary", to: "skills/animation-vocabulary", match: /\.md$/, recursive: false },
+      { type: "dir", from: "skills/apple-design", to: "skills/apple-design", match: /\.md$/, recursive: false },
+      { type: "dir", from: "skills/find-animation-opportunities", to: "skills/find-animation-opportunities", match: /\.md$/, recursive: false },
+      { type: "dir", from: "skills/improve-animations", to: "skills/improve-animations", match: /\.md$/, recursive: false },
+      { type: "dir", from: "skills/review-animations", to: "skills/review-animations", match: /\.md$/, recursive: false },
+      { type: "dir", from: "skills/prototype", to: "skills/prototype", match: /\.md$/, recursive: false },
+      { type: "file", from: "LICENSE", to: "LICENSE" },
+    ],
+    omitted: [
+      "skills/pick-ui-library — library choice is Cohort's, settled in the product repo",
+      "skills/ask-sonner — a single third-party toast library's API",
+      "skills/write-swift, skills/animate-expo — native platforms this fleet does not ship",
+    ],
+    acknowledged: [],
+    notes: "MIT. Motion and design-engineering craft. Precedence sits below Cohort's DESIGN.md for tokens and type; these govern easing, duration and restraint.",
+  },
+  {
+    id: "taste-skill",
+    contentSha256: "e63fea105e36e4418bf625cb091bc10a316b35f588ad146a38fce15f4a749c5e",
+    repo: "Leonxlnx/taste-skill",
+    sha: "ccbc15639c97057cbfcf32ecebc38ef716e4bb37",
+    date: "2026-08-24",
+    license: "MIT",
+    skillRoots: [
+      "skills/taste-skill",
+      "skills/redesign-skill",
+      "skills/soft-skill",
+      "skills/minimalist-skill",
+    ],
+    rules: [
+      { type: "dir", from: "skills/taste-skill", to: "skills/taste-skill", match: /\.md$/, recursive: false },
+      { type: "dir", from: "skills/redesign-skill", to: "skills/redesign-skill", match: /\.md$/, recursive: false },
+      { type: "dir", from: "skills/soft-skill", to: "skills/soft-skill", match: /\.md$/, recursive: false },
+      { type: "dir", from: "skills/minimalist-skill", to: "skills/minimalist-skill", match: /\.md$/, recursive: false },
+      { type: "file", from: "LICENSE", to: "LICENSE" },
+    ],
+    omitted: [
+      "skills/imagegen-frontend-web, skills/imagegen-frontend-mobile — image generation belongs to cohort-mcp design_generate_image",
+      "skills/brandkit — brand tokens are DESIGN.md's, never a skill's",
+      "skills/gpt-tasteskill, skills/stitch-skill — other vendors' model/tooling wrappers",
+      "skills/taste-skill-v1 — superseded by skills/taste-skill",
+      "skills/brutalist-skill, skills/output-skill, skills/image-to-code-skill — styles and behaviours outside the four the design ruling admitted",
+      "assets/, examples/, research/, scripts/, skill.sh, .claude-plugin/",
+    ],
+    acknowledged: [
+      {
+        token: "npx:shadcn@latest",
+        why: "skills/taste-skill/SKILL.md tells the reader to run `npx shadcn@latest init|add` to pull components. Registry fetch-and-execute; Cohort's component grammar comes from DESIGN.md.",
+        covered: "npx shadcn",
+      },
+      {
+        token: "pkg-install",
+        why: "skills/taste-skill/SKILL.md carries ~10 `npm install` lines for design-system packages (@material/web, @fluentui/*, @carbon/*, @radix-ui/themes, @primer/*, govuk-frontend, uswds, bootstrap). Adding a dependency is a decision the product repo makes, not a skill.",
+        covered: "Adding a dependency is the product repo's decision",
+      },
+      {
+        token: "remote-asset:cdn.shopify.com",
+        why: "skills/taste-skill/SKILL.md shows a <script src=\"https://cdn.shopify.com/shopifycloud/polaris.js\"> tag as sample markup. A third-party CDN script in shipped output is a supply-chain edge, not a design choice.",
+        covered: "never a remote script tag",
+      },
+      {
+        token: "template-url:picsum.photos",
+        why: "skills/taste-skill, skills/redesign-skill and skills/minimalist-skill all instruct hotlinking https://picsum.photos/seed/{...} placeholder photography into generated markup.",
+        covered: "picsum.photos",
+      },
+      {
+        token: "template-url:cdn.simpleicons.org",
+        why: "skills/taste-skill/SKILL.md instructs hotlinking https://cdn.simpleicons.org/{slug}/ffffff for brand icons. The asset kit is design_export_kit's.",
+        covered: "cdn.simpleicons.org",
+      },
+    ],
+    notes: "MIT. Marketing and site pages ONLY — these skills self-declare out of scope for dashboards, data tables, forms and product UI. Directory names differ from the frontmatter names: taste-skill=design-taste-frontend, redesign-skill=redesign-existing-projects, soft-skill=high-end-visual-design, minimalist-skill=minimalist-ui. Their em-dash ban does NOT apply to Cohort copy.",
+  },
+  {
+    id: "unlazy",
+    contentSha256: "07829533954d1c1aebc318fb8748adb262b4b25c56b9bea76ec1b5bb1b3ddd05",
+    repo: "Leonxlnx/unlazy",
+    sha: "16671491f6679ad9378f52604d3bc2415b4120c7",
+    date: "2026-09-03",
+    license: "MIT",
+    skillRoots: ["."],
+    execAllowed: ["scripts/"],
+    rules: [
+      { type: "file", from: "SKILL.md", to: "SKILL.md" },
+      { type: "file", from: "SECURITY.md", to: "SECURITY.md" },
+      { type: "file", from: "LICENSE", to: "LICENSE" },
+      { type: "dir", from: "references", to: "references", match: /\.md$/, recursive: false },
+      { type: "dir", from: "templates", to: "templates", match: /\.md$/, recursive: false },
+      // The gate checker and its library, and NOT the hook machinery: see
+      // HOOK_SCRIPT_BASENAMES below for why those two names are excluded here
+      // rather than merely discouraged in prose.
+      { type: "dir", from: "scripts", to: "scripts", match: /^(?!install-hooks\.mjs$|stop-hook\.mjs$)[\w.-]+\.mjs$/, recursive: true },
+    ],
+    omitted: [
+      "scripts/install-hooks.mjs and scripts/stop-hook.mjs — the Stop hook MACHINERY is not vendored at all, so it never reaches a seat; `node install-hooks.mjs --global` would have written a Stop hook into ~/.claude/settings.json for every session on the machine, and stripping an executable bit does not stop `node` from running a file",
+      "README.md, CHANGELOG.md, CONTRIBUTING.md, package.json, agents/openai.yaml",
+      "research/, tests/, .github/",
+    ],
+    acknowledged: [
+      {
+        token: "hook-install-doc",
+        why: "SKILL.md and SECURITY.md still describe unlazy's Stop hook and the settings files it would be written into. The two scripts that install and implement it are NOT vendored (see omitted[]), so the instruction has nothing to run — but the prose reaches the seat, and a reader who reconstructs the hook by hand gets the same fleet-wide blast radius.",
+        covered: "Never install unlazy's Stop hook",
+      },
+    ],
+    notes: "MIT. Completion gates for substantial work. scripts/ is vendored so the gate checker can be read and run deliberately by a person who chose to; nothing here is wired into a hook. The two files that INSTALL and IMPLEMENT unlazy's Stop hook (scripts/install-hooks.mjs, scripts/stop-hook.mjs) are deliberately absent from the vendored tree: a prohibition in prose does not survive a reader who takes SKILL.md's own install line at face value, so the machinery is simply not on the seat. SKILL.md still describes it; the cohort-design harmoniser forbids reconstructing it.",
+  },
+]);
+
+/** @param {string} id @returns {SkillPack|null} */
+export function findPack(id) {
+  return PACKS.find((p) => p.id === id) || null;
+}
+
+/** Normalise a path to POSIX separators with no leading "./". @param {string} p */
+export function posix(p) {
+  return String(p == null ? "" : p).split("\\").join("/").replace(/^\.\//, "");
+}
+
+/**
+ * Is `dest` (pack-relative) a path this pack's allow-list admits? This is the
+ * half the CI guard needs: it answers with no upstream tree in hand, so a file
+ * someone dropped into a vendored directory by mistake — or on purpose — fails
+ * the build even though its sha256 would happily be recomputed.
+ *
+ * `UPSTREAM.json` is always allowed: it IS the manifest.
+ *
+ * @param {SkillPack} pack
+ * @param {string} dest
+ * @returns {boolean}
+ */
+export function isAllowedDest(pack, dest) {
+  const d = posix(dest);
+  if (!d || d.startsWith("../") || d.includes("/../")) return false;
+  if (d === "UPSTREAM.json") return true;
+  for (const rule of (pack && pack.rules) || []) {
+    if (rule.type === "file") {
+      if (d === posix(rule.to)) return true;
+      continue;
+    }
+    const prefix = posix(rule.to);
+    const base = prefix ? `${prefix}/` : "";
+    if (!d.startsWith(base)) continue;
+    const rest = d.slice(base.length);
+    if (!rest) continue;
+    if (!rule.recursive && rest.includes("/")) continue;
+    const name = rest.slice(rest.lastIndexOf("/") + 1);
+    if (rule.match && !rule.match.test(name)) continue;
+    return true;
+  }
+  return false;
+}
+
+/**
+ * May `dest` carry an executable bit? Only where a pack declares it (unlazy's
+ * `scripts/`, whose upstream files are 0644 today but need not stay that way).
+ * @param {SkillPack} pack @param {string} dest
+ */
+export function isExecAllowed(pack, dest) {
+  const d = posix(dest);
+  return ((pack && pack.execAllowed) || []).some((p) => d.startsWith(posix(p)));
+}
+
+export default {
+  PACKS, findPack, isAllowedDest, isExecAllowed, posix,
+  FETCH_HOST_ALLOWLIST, HOOK_SCRIPT_BASENAMES, manifestDigest,
+};