@cohortapp/agent-sdk 2.12.0 → 2.13.0

package/scripts/local-triggers/autoupdate.test.mjs

@@ -26,6 +26,26 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const SCRIPT = join(__dirname, "autoupdate.sh");
 const scriptSrc = readFileSync(SCRIPT, "utf8");
 
+/**
+ * Today, in the SAME basis the code under test uses: `date +%Y-%m-%d`, which is
+ * LOCAL. Both log files this suite fabricates are read back by shell that names
+ * them that way — `autoupdate.sh` for its own log, and for the daemon log the
+ * health gate tails (which `scripts/daemon/launchd-wrapper.sh` also writes with
+ * local `date`).
+ *
+ * This used to be `new Date().toISOString().slice(0, 10)` — UTC — and the two
+ * agree for exactly as long as the machine sits at or west of Greenwich. On a
+ * UTC+4 developer machine they diverge from 20:00 to midnight local, so the
+ * fixture wrote `daemon-<yesterday>.log`, the health gate looked for
+ * `daemon-<today>.log`, found nothing, and all twelve upgrade cases failed with
+ * "UNHEALTHY … ROLLBACK" — a four-hour window each evening in which a green
+ * suite turned red with no code change. Keep the basis matched to the shell.
+ */
+function localDay(d = new Date()) {
+  const p = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+}
+
 function stub(bin, name, body) {
   writeFileSync(join(bin, name), `#!/bin/bash\n${body}\n`);
   chmodSync(join(bin, name), 0o755);
@@ -49,7 +69,7 @@ function fixture({ latest = "2.0.0", healthy = true, supervisorAlive = true, ses
 
   writeFileSync(join(agent, "node_modules", "@cohortapp", "agent-sdk", "package.json"), JSON.stringify({ version: "1.0.0" }));
   writeFileSync(join(agent, "node_modules", "@cohortapp", "agent-sdk", "bin", "maestro.mjs"), "process.exit(0);\n");
-  const day = new Date().toISOString().slice(0, 10);
+  const day = localDay();
   writeFileSync(join(agent, "logs", "daemon", `daemon-${day}.log`), "[daemon] Running\n");
   writeFileSync(join(home, "Library", "LaunchAgents", "ai.maestro.ivy-daemon.plist"), "<plist/>");
   if (installedSessionPlist) writeFileSync(join(home, "Library", "LaunchAgents", "ai.maestro.ivy-session.plist"), "<plist/>");
@@ -108,6 +128,14 @@ function run(fx, extraEnv) {
       // The script prepends the standard tool dirs to PATH; this prefix wins
       // over them so the stubs — never the real npm/launchctl — are reached.
       MAESTRO_AUTOUPDATE_PATH_PREFIX: fx.bin,
+      // The child shell names its log files with `date +%Y-%m-%d` and this
+      // suite fabricates those names with `localDay()`. `env` here is an
+      // explicit whitelist, so without this line the shell inherits NO TZ and
+      // falls back to the system zone while Node honours the ambient one — the
+      // two then disagree whenever a run sets TZ (e.g. `TZ=UTC npm test` on a
+      // UTC+4 machine), and every upgrade case fails on a log file neither
+      // side is wrong about. Pass the zone through so both agree by construction.
+      ...(process.env.TZ ? { TZ: process.env.TZ } : {}),
       MAESTRO_AUTOUPDATE_JITTER_MAX: "0",
       MAESTRO_AUTOUPDATE_HEALTH_WAIT: "0",
       MAESTRO_AUTOUPDATE_RETRY_SLEEP: "0",
@@ -125,7 +153,7 @@ const lastPath = (fx) => join(fx.agent, "state", "autoupdate", "last.json");
 const readLast = (fx) => JSON.parse(readFileSync(lastPath(fx), "utf8"));
 const scriptLog = (fx) => {
   const dir = join(fx.agent, "logs", "autoupdate");
-  try { return readFileSync(join(dir, `${new Date().toISOString().slice(0, 10)}.log`), "utf8"); } catch { return ""; }
+  try { return readFileSync(join(dir, `${localDay()}.log`), "utf8"); } catch { return ""; }
 };
 
 test("a healthy upgrade writes state/session/upgrade-notice.json {from,to,at} and never touches the session job", () => {
@@ -478,7 +506,9 @@ test("the /tmp re-exec copy removes itself on exit (and a run with MAESTRO_AUTOU
     const tmp = join(fx.root, "tmp"); mkdirSync(tmp, { recursive: true });
     const r = spawnSync("/bin/bash", [join(fx.agent, "scripts", "local-triggers", "autoupdate.sh")], {
       encoding: "utf8",
-      env: { HOME: fx.home, AGENT_ROOT: fx.agent, TMPDIR: tmp, PATH: `${fx.bin}:${dirname(process.execPath)}:/usr/bin:/bin`, MAESTRO_AUTOUPDATE_PATH_PREFIX: fx.bin, MAESTRO_AUTOUPDATE_JITTER_MAX: "0", MAESTRO_AUTOUPDATE_HEALTH_WAIT: "0", MAESTRO_AUTOUPDATE_RETRY_SLEEP: "0", MAESTRO_SKIP_GLOBAL_INSTALL: "1" },
+      // This case spawns directly rather than through `run()`, so it needs the
+      // same TZ passthrough for the same reason — see the note in `run()`.
+      env: { HOME: fx.home, AGENT_ROOT: fx.agent, TMPDIR: tmp, PATH: `${fx.bin}:${dirname(process.execPath)}:/usr/bin:/bin`, ...(process.env.TZ ? { TZ: process.env.TZ } : {}), MAESTRO_AUTOUPDATE_PATH_PREFIX: fx.bin, MAESTRO_AUTOUPDATE_JITTER_MAX: "0", MAESTRO_AUTOUPDATE_HEALTH_WAIT: "0", MAESTRO_AUTOUPDATE_RETRY_SLEEP: "0", MAESTRO_SKIP_GLOBAL_INSTALL: "1" },
     });
     assert.equal(r.status, 0, r.stderr);
     assert.match(scriptLog(fx), /up to date \(1\.0\.0\)/, "the re-exec'd copy ran the script");

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,
+};

package/scripts/vendor/sync-skill-packs.mjs

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+/**
+ * sync-skill-packs.mjs — re-vendor a pinned upstream design skill pack.
+ *
+ * Usage:
+ *   node scripts/vendor/sync-skill-packs.mjs <pack>[ <pack> …]   re-fetch and rewrite
+ *   node scripts/vendor/sync-skill-packs.mjs --all
+ *   node scripts/vendor/sync-skill-packs.mjs --list
+ *   node scripts/vendor/sync-skill-packs.mjs <pack> --dry-run    report, write nothing
+ *   node scripts/vendor/sync-skill-packs.mjs --all --dry-run     RE-VERIFY every
+ *       pack against its pinned upstream commit. This is the only thing that
+ *       establishes provenance: `check-skill-packs.mjs` runs offline and can
+ *       only prove the vendored trees have not moved since review, never that
+ *       they came from upstream. Run this when auditing, not on every commit.
+ *
+ * What it does, for each pack in `scripts/vendor/skill-packs.mjs`:
+ *   1. downloads `https://codeload.github.com/<repo>/tar.gz/<sha>` — the PINNED
+ *      commit, never a branch — into a temp dir and extracts it with `tar`;
+ *   2. copies ONLY the paths the pack's allow-list admits into
+ *      `plugins/maestro-skills/vendor/<pack>/`, deleting anything already there
+ *      that the allow-list no longer admits;
+ *   3. rewrites `UPSTREAM.json` with `{repo, sha, date, license, files:[{path,
+ *      sha256}], omitted, notes}`, sorted, so the diff of a re-sync is readable.
+ *
+ * This is a MAINTAINER tool. It is the only place in the SDK that fetches skill
+ * content, it runs on a developer's machine before a commit, and nothing on a
+ * seat ever calls it: seats get the reviewed bytes from the npm tarball. It
+ * never executes anything out of the downloaded tree.
+ *
+ * Node builtins only (plus the system `tar`, which macOS and Linux both ship).
+ *
+ * @module scripts/vendor/sync-skill-packs
+ */
+
+"use strict";
+
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import {
+  mkdtempSync, mkdirSync, rmSync, readdirSync, readFileSync, writeFileSync, statSync, existsSync, copyFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { PACKS, findPack, posix, isAllowedDest, manifestDigest } from "./skill-packs.mjs";
+
+const REPO_ROOT = path.resolve(fileURLToPath(new URL(".", import.meta.url)), "..", "..");
+
+/** Where vendored packs live, relative to the repo root. */
+export const VENDOR_REL = path.join("plugins", "maestro-skills", "vendor");
+
+/** @param {string} p @returns {string} */
+export function sha256File(p) {
+  return createHash("sha256").update(readFileSync(p)).digest("hex");
+}
+
+/** Recursively list files under `dir`, as paths relative to it (POSIX). */
+export function listFiles(dir, prefix = "") {
+  let out = [];
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out; // an absent directory is an empty one for our purposes
+  }
+  for (const e of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
+    const rel = prefix ? `${prefix}/${e.name}` : e.name;
+    if (e.isDirectory()) out = out.concat(listFiles(path.join(dir, e.name), rel));
+    else if (e.isFile()) out.push(rel);
+  }
+  return out;
+}
+
+/**
+ * Expand a pack's rules against a real upstream tree into {from, to} pairs.
+ * Pure over the injected lister so the planner is testable without a download.
+ *
+ * @param {import("./skill-packs.mjs").SkillPack} pack
+ * @param {string} srcRoot
+ * @param {{list?:(dir:string)=>string[], exists?:(p:string)=>boolean}} [deps]
+ * @returns {{ pairs: Array<{from:string,to:string}>, missing: string[] }}
+ */
+export function planPack(pack, srcRoot, deps = {}) {
+  const list = deps.list || ((d) => listFiles(d));
+  const exists = deps.exists || existsSync;
+  const pairs = [];
+  const missing = [];
+  for (const rule of pack.rules) {
+    if (rule.type === "file") {
+      const abs = path.join(srcRoot, rule.from);
+      if (!exists(abs)) { missing.push(rule.from); continue; }
+      pairs.push({ from: rule.from, to: posix(rule.to) });
+      continue;
+    }
+    const absDir = path.join(srcRoot, rule.from);
+    if (!exists(absDir)) { missing.push(`${rule.from}/`); continue; }
+    let taken = 0;
+    for (const rel of list(absDir)) {
+      if (!rule.recursive && rel.includes("/")) continue;
+      const name = rel.slice(rel.lastIndexOf("/") + 1);
+      if (rule.match && !rule.match.test(name)) continue;
+      pairs.push({ from: `${rule.from}/${rel}`, to: posix(rule.to ? `${rule.to}/${rel}` : rel) });
+      taken += 1;
+    }
+    if (taken === 0) missing.push(`${rule.from}/ (matched nothing)`);
+  }
+  // A rule that produced a path the guard would reject is a registry bug, not a
+  // vendoring accident — say so loudly rather than writing an unverifiable tree.
+  for (const p of pairs) {
+    if (!isAllowedDest(pack, p.to)) throw new Error(`rule produced a path its own allow-list rejects: ${p.to}`);
+  }
+  pairs.sort((a, b) => (a.to < b.to ? -1 : a.to > b.to ? 1 : 0));
+  return { pairs, missing };
+}
+
+/** Download the pinned tarball and extract it; returns the extracted repo root. */
+function fetchTree(pack, workDir) {
+  const url = `https://codeload.github.com/${pack.repo}/tar.gz/${pack.sha}`;
+  const tgz = path.join(workDir, "pack.tar.gz");
+  execFileSync("curl", ["-sSLf", "--max-time", "300", "-o", tgz, url], { stdio: ["ignore", "ignore", "pipe"] });
+  const outDir = path.join(workDir, "tree");
+  mkdirSync(outDir, { recursive: true });
+  execFileSync("tar", ["-xzf", tgz, "-C", outDir], { stdio: ["ignore", "ignore", "pipe"] });
+  const roots = readdirSync(outDir, { withFileTypes: true }).filter((e) => e.isDirectory());
+  if (roots.length !== 1) throw new Error(`unexpected tarball layout for ${pack.repo}: ${roots.length} top-level dirs`);
+  return path.join(outDir, roots[0].name);
+}
+
+/** Build the UPSTREAM.json body for a vendored pack. Pure. */
+export function buildManifest(pack, files) {
+  return {
+    repo: pack.repo,
+    sha: pack.sha,
+    date: pack.date,
+    license: pack.license,
+    files: files.slice().sort((a, b) => (a.path < b.path ? -1 : 1)),
+    omitted: pack.omitted.slice(),
+    notes: pack.notes,
+  };
+}
+
+/**
+ * Re-vendor one pack. Returns a summary; throws only on a defect (no network,
+ * a moved upstream path, a rule that contradicts the allow-list).
+ * @param {string} id @param {{repoRoot?:string, dryRun?:boolean, log?:Function}} [o]
+ */
+export function syncPack(id, o = {}) {
+  const pack = findPack(id);
+  if (!pack) throw new Error(`unknown pack "${id}" (known: ${PACKS.map((p) => p.id).join(", ")})`);
+  const repoRoot = o.repoRoot || REPO_ROOT;
+  const log = o.log || (() => {});
+  const destRoot = path.join(repoRoot, VENDOR_REL, pack.id);
+  const work = mkdtempSync(path.join(tmpdir(), `maestro-vendor-${pack.id}-`));
+  try {
+    const srcRoot = fetchTree(pack, work);
+    const { pairs, missing } = planPack(pack, srcRoot);
+    if (missing.length) throw new Error(`${pack.id}: upstream paths absent at ${pack.sha}: ${missing.join(", ")}`);
+    const wanted = new Set(pairs.map((p) => p.to));
+    const existingFiles = listFiles(destRoot);
+    const removed = existingFiles.filter((f) => f !== "UPSTREAM.json" && !wanted.has(f));
+    if (!o.dryRun) {
+      for (const rel of removed) rmSync(path.join(destRoot, rel), { force: true });
+      for (const p of pairs) {
+        const dest = path.join(destRoot, p.to);
+        mkdirSync(path.dirname(dest), { recursive: true });
+        copyFileSync(path.join(srcRoot, p.from), dest);
+        // Vendored content is data. Strip any executable bit the upstream tree
+        // carried unless the pack explicitly allows one there.
+        const mode = statSync(dest).mode & 0o777;
+        const want = 0o644;
+        if (mode !== want) execFileSync("chmod", ["644", dest]);
+      }
+      pruneEmptyDirs(destRoot);
+    }
+    const files = pairs.map((p) => ({
+      path: p.to,
+      sha256: o.dryRun ? sha256File(path.join(srcRoot, p.from)) : sha256File(path.join(destRoot, p.to)),
+    }));
+    const manifest = buildManifest(pack, files);
+    const manifestPath = path.join(destRoot, "UPSTREAM.json");
+    if (!o.dryRun) {
+      mkdirSync(destRoot, { recursive: true });
+      writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+    }
+    // The content pin. `UPSTREAM.json` is written from the bytes it records, so
+    // it can only ever agree with itself; the digest below lives in
+    // skill-packs.mjs, a reviewed source file no vendored tree can reach, and is
+    // what makes a change to the vendored file list show up in a diff as one
+    // line rather than as a data blob nobody reads. A re-sync that shifts it is
+    // a real upstream change and wants a real look — hence the loud line.
+    const contentSha256 = manifestDigest(files);
+    const pinned = pack.contentSha256 || null;
+    if (pinned && pinned !== contentSha256) {
+      log(`${pack.id}: CONTENT CHANGED — review the diff, then set contentSha256: "${contentSha256}" in scripts/vendor/skill-packs.mjs (was ${pinned})`);
+    } else if (!pinned) {
+      log(`${pack.id}: set contentSha256: "${contentSha256}" in scripts/vendor/skill-packs.mjs`);
+    }
+    log(`${pack.id}: ${files.length} file(s) from ${pack.repo}@${pack.sha.slice(0, 12)}${removed.length ? `, ${removed.length} removed` : ""}${o.dryRun ? " (dry-run)" : ""}`);
+    return { pack: pack.id, files, removed, contentSha256, pinned, dryRun: !!o.dryRun };
+  } finally {
+    rmSync(work, { recursive: true, force: true });
+  }
+}
+
+/** Remove directories left empty after a prune. */
+function pruneEmptyDirs(root) {
+  let entries;
+  try { entries = readdirSync(root, { withFileTypes: true }); } catch { return; }
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    const child = path.join(root, e.name);
+    pruneEmptyDirs(child);
+    try { if (readdirSync(child).length === 0) rmSync(child, { recursive: true, force: true }); } catch { /* a racing reader is not our problem */ }
+  }
+}
+
+async function main(argv) {
+  const args = argv.slice(2);
+  if (args.includes("--list") || args.length === 0) {
+    for (const p of PACKS) console.log(`${p.id.padEnd(14)} ${p.repo}@${p.sha.slice(0, 12)}  ${p.license}`);
+    if (args.length === 0) console.log("\nusage: node scripts/vendor/sync-skill-packs.mjs <pack>|--all [--dry-run]");
+    return 0;
+  }
+  const dryRun = args.includes("--dry-run");
+  const ids = args.includes("--all") ? PACKS.map((p) => p.id) : args.filter((a) => !a.startsWith("--"));
+  let code = 0;
+  for (const id of ids) {
+    try {
+      syncPack(id, { dryRun, log: (m) => console.log(`sync-skill-packs: ${m}`) });
+    } catch (err) {
+      console.error(`sync-skill-packs: ${id} FAILED — ${err && err.message ? err.message : err}`);
+      code = 1;
+    }
+  }
+  return code;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main(process.argv).then((c) => process.exit(c)).catch((e) => { console.error("sync-skill-packs: ERROR", e && e.message ? e.message : e); process.exit(2); });
+}
+
+export default { syncPack, planPack, buildManifest, listFiles, sha256File, VENDOR_REL };