@cohortapp/agent-sdk 2.12.0 → 2.14.0

package/bin/maestro.mjs

@@ -1181,7 +1181,8 @@ and in .maestro/upgrade-result.json {from,to,at,steps}):
   launchd        install / replace / load every generated plist under
                  ~/Library/LaunchAgents (mode 600, launchctl bootstrap);
                  -daemon and -session are rewritten, never restarted
-  globalSetup    maestro global-setup (identity block, cohort MCP, settings, skills)
+  globalSetup    maestro global-setup (identity block, cohort MCP, settings, skills,
+                 vendored design skill packs)
   globalInstall  npm i -g @cohortapp/agent-sdk@<this version>
                  (MAESTRO_SKIP_GLOBAL_INSTALL=1 skips)
   verify         the --verify report
@@ -3356,7 +3357,8 @@ async function globalSetup(args = []) {
   ok(`${dryRun ? "[dry-run] " : ""}machine pointer → ${pointerFile}`);
 
   // 4) Front-door session (2026-09 §3.7): identity block, cohort MCP server,
-  //    settings additions, global skills — lib/cli/global-setup-extras.mjs.
+  //    settings additions, global skills and the vendored design skill packs
+  //    (WP-M7) — lib/cli/global-setup-extras.mjs.
   try {
     const extras = await import("../lib/cli/global-setup-extras.mjs");
     await extras.applyFrontDoorSetup({ agentRoot: cwd, claudeDir, dryRun, log, ok, warn });
@@ -3806,6 +3808,7 @@ switch (command) {
   case "session-ack": process.exitCode = await (await import("../lib/cli/session-ack.mjs")).runSessionAck(args); break;
   case "session": { const r = await (await import("../lib/cli/session.mjs")).run(args); process.exitCode = r.code; break; }
   case "board": await (await import("../lib/cli/board.mjs")).boardCmd(args); break;
+  case "design": await (await import("../lib/cli/design.mjs")).designCmd(args); break;
   case "init":
   case "update-init":
   case "init-update":
@@ -3835,6 +3838,7 @@ Usage:
   npx @cohortapp/agent-sdk session-ack <tickId>       Ack a cadence tick handed to the main session
   npx @cohortapp/agent-sdk session <cmd>              Front-door session: status|attach|start|stop|restart|spawn|peers|handoffs|ack
   npx @cohortapp/agent-sdk board mine|track|claim|complete   Your work across every board (maestro board --help)
+  npx @cohortapp/agent-sdk design sync [--out <dir>]  Pull the brand foundation → DESIGN.md + PRODUCT.md
 
 Upgrade flags:
   --dry-run, -n          Preview changes without writing

package/docs/guides/front-door-session.md

@@ -47,6 +47,43 @@ direction. The beat reports which lane is active: `machine.frontDoor`
 open record — rather than `session`, which hq validates strictly and which
 stays `null` while no work session runs.
 
+**And WHY it is not live.** `sessionLive: false` on its own is a symptom with
+several cures, and no seat in the fleet accepts SSH, so the beat has to carry
+the cause too. When (and only when) the front door is down, the beat adds
+`machine.sessionNote` — `{reason, since?, detail?}`:
+
+| `reason` | what happened | what to do |
+| --- | --- | --- |
+| `job-absent` | no `ai.maestro.<first>-session` plist in `~/Library/LaunchAgents`. A statement of configuration, not necessarily a fault — a seat whose front door is deliberately the daemon lane reports this on every beat | nothing, if that is the intent; else `maestro session install` |
+| `awaiting-input` | `state/session/attention.json` exists and no later heartbeat has superseded it: the session is up but has never beaten, so it is sitting on a first-run trust/permission dialog | attach with the command in `detail` and answer it |
+| `heartbeat-stale` | a heartbeat exists but has aged out — supervisor died, or the mux session ended; `since` is the last beat | `maestro session restart` |
+| `heartbeat-unreadable` | `heartbeat.json` is there and will not parse. The job may well have beaten — this is NOT "never beaten" | delete the file and let the feed rewrite it |
+| `never-beaten` | no heartbeat file at all and no watchdog record yet (the supervisor's watchdog fires 120 s in) | wait a minute, then `maestro session status` |
+
+`detail` is capped at 200 characters and scrubbed of home paths, session ids
+and token-shaped words before it leaves the machine
+(`lib/telemetry/collect.mjs#sanitizeNoteDetail`); the attach command survives,
+because that is the actionable part. `since` is never passed through from the
+file either — it is parsed and re-emitted as canonical ISO 8601, so nothing can
+ride it that the `detail` scrubber would have caught.
+
+Two rules the reasons obey, because a note that misleads is worse than no note:
+
+- **An unknown is reported as neither an absence nor a presence.** `job-absent`
+  comes only from a directory that was read and genuinely did not hold the
+  label; an unreadable `~/Library/LaunchAgents` (or a non-Mac seat) yields
+  `never-beaten` with a `detail` that says the job's presence could not be
+  checked, rather than claiming an installation nobody verified.
+- **Every reason is PRESENT-TENSE and expires with the snapshot**, like
+  `frontDoor` and `sessionLive` and unlike `machine.upgrade`. `job-absent` and
+  `never-beaten` carry no `since`, so a consumer dates them from the snapshot's
+  own `ts` — printing "attach and answer the dialog" off a week-old snapshot is
+  the mistake this note exists to prevent, not to cause.
+
+The decision itself is the pure `sessionNote(...)` over injected inputs — the
+reads that feed it are fail-open, so a throw anywhere in them drops the field
+rather than the beat.
+
 **Exactly one.** The supervisor takes an O_EXCL lock (`lib/singleton.js`,
 name `session`); a second supervisor exits 0 so launchd does not thrash. An
 orphaned mux session with no lock holder is adopted, not duplicated.
@@ -245,6 +282,53 @@ To the humans it talks to, the agent is one persona. Peer sessions and
 sub-agents are "my team" / "a colleague"; the persona audit hook blocks any
 outbound text that says otherwise.
 
+## 6a. DESIGN.md and the parallelism directive
+
+Two things reach every prompt a seat runs, and neither is left to a session to
+remember.
+
+**DESIGN.md and PRODUCT.md.** `maestro design sync` reads the workspace's SAVED
+brand foundation (`branding.getFoundation` — never a draft) and renders it into
+`DESIGN.md` (colour, type, radius, spacing and component tokens, in the
+google-labs-code/design.md frontmatter shape, with `{colors.primary}`-style
+refs) and `PRODUCT.md` (positioning, voice, tone, lexicon) in the agent dir,
+plus the raw snapshot at `state/design/foundation.json`. The daemon re-runs the
+same code path every 15 minutes and rewrites the files when the foundation's
+version has moved, so a seat's design files follow the humans editing the
+foundation without anyone re-running a command.
+
+Both files are GENERATED. An edit to them is overwritten on the next sync;
+foundation changes are human-gated and go through the `design_propose_change`
+tool. The write is byte-idempotent — an unchanged foundation touches no mtime,
+so the poll never churns the tree, and the render stamp is kept per output
+directory so a `--out` run and the daemon's poll of the agent dir cannot
+invalidate each other's files. Every posture here is fail-open: an un-enrolled
+seat writes nothing, and a failed read keeps the last-good files rather than
+blanking them. Design skills are told to read `$AGENT_ROOT/DESIGN.md` when the
+working directory is not the agent dir.
+
+A workspace that has never SAVED a foundation writes nothing at all, and the
+CLI says why. hq answers such a read with its own product defaults and
+`unversioned: true` — a complete, plausible palette that is nobody's brand — and
+a DESIGN.md rendered from it would ground every design skill on the seat in the
+wrong palette with a generated file's authority behind it.
+
+    maestro design sync                # into the agent dir
+    maestro design sync --out docs/brand --json
+
+**The parallelism directive.** `lib/prompts/parallelism.mjs` holds one constant,
+prepended exactly once (it is idempotent, and the seams compose) to every
+peer-session prompt by `maestro session spawn`, to every sub-session prompt
+built by the daemon's prompt-builder, and to every cadence trigger prompt on the
+escalate/guarded lane — both when a sub-session is spawned for it and when a
+live main session is handed it (`renderCadencePromptBody`, one seam for both, so
+the two lanes send the same bytes). It grants the standing permission to
+dispatch independent tasks as one parallel batch, and carries the safety rule
+that makes that safe on a shared checkout: check the planned file scope first,
+and never assign two agents to edit the same file — sequence or re-scope
+instead. Sessions ran plans strictly serially before it existed, because
+nothing in the prompt had ever said they need not.
+
 ## 7. Files
 
 | Path | What |
@@ -258,6 +342,8 @@ outbound text that says otherwise.
 | `state/session/upgrade-notice.json` | written by autoupdate; the session restarts itself when idle |
 | `state/session.lock` | the singleton lock |
 | `state/inbox/cohort/*.yaml` | inbound items (`.dispatched` = claimed, `.processed` = done, `.deferred`) |
+| `DESIGN.md`, `PRODUCT.md` | generated from the workspace brand foundation by `maestro design sync` and the daemon's 15-minute poll; edits are overwritten |
+| `state/design/foundation.json` | `{fetchedAt, renderedAt, version, versionLabel, foundation}` — the last synced foundation; the refresh gate reads it back |
 | `state/org/board-mine.json` | `{ts, items}` — the daemon's 5-minute cache of hq `board.mine` (this agent's items across every board); read by the SessionStart primer, the `session_status` MCP tool and `maestro board mine` |
 | `.maestro/upgrade-result.json` | `{from, to, at, steps:{plists, launchd, globalSetup, globalInstall, verify}}` — what the last `maestro upgrade` did to the seat |
 | `state/autoupdate/last.json` | `{from, to, at, ok, healthy, reason}` — the last autoupdate attempt; the beat's `machine.upgrade` |

package/lib/cli/design.mjs

@@ -0,0 +1,185 @@
+/**
+ * lib/cli/design.mjs — `maestro design sync`.
+ *
+ *   maestro design sync [--out <dir>] [--json]
+ *
+ * Pulls the workspace's SAVED brand foundation from hq (`branding.getFoundation`
+ * — the same read the `design_foundation` tool makes; drafts are never visible
+ * to a seat) and lands it as `DESIGN.md` + `PRODUCT.md` in the agent dir, plus
+ * the raw snapshot at `state/design/foundation.json`. Design skills read those
+ * files; this command is how they stop being fiction.
+ *
+ * FAIL POSTURE. A fetch that fails writes NOTHING and exits non-zero with the
+ * server's own message. That is deliberate and is the opposite of the daemon's
+ * posture: a human who typed `design sync` is owed the error, whereas a
+ * background poll must never overwrite a good DESIGN.md with a half-answer from
+ * an hq that was briefly down. Nothing here throws — expected failures are
+ * printed and become exit 1.
+ *
+ * IDEMPOTENT. Re-running against an unchanged foundation rewrites no file (the
+ * comparison is on rendered bytes — `lib/design/write.mjs#syncDesign`), so a
+ * cron-y re-sync leaves mtimes and the git tree alone.
+ *
+ * `runDesign(argv, deps)` is the testable core (every I/O injectable);
+ * `designCmd(argv)` is the bin entry.
+ *
+ * @module lib/cli/design
+ */
+
+"use strict";
+
+import { loadOrgConfig, configFromAgent, isEnabled, brandingGetFoundation } from "../org/client.mjs";
+import { syncDesign, workspaceName } from "../design/write.mjs";
+import { DESIGN_FILES, DESIGN_STATE_REL, isUnversionedFoundation } from "../design/refresh-gate.mjs";
+
+export function usage() {
+  return [
+    "Usage:",
+    "  maestro design sync [--out <dir>] [--json]   Pull the brand foundation and write DESIGN.md + PRODUCT.md",
+    "",
+    `Writes ${DESIGN_FILES.join(" + ")} into the agent dir (or --out) and the raw`,
+    `snapshot to ${DESIGN_STATE_REL}. Unchanged files are left untouched.`,
+    "Foundation changes are human-gated: propose one with the design_propose_change tool.",
+  ].join("\n");
+}
+
+/**
+ * Parse argv → {sub, out, json, help, error}. Pure.
+ * @param {string[]} argv
+ */
+export function parseDesignArgs(argv) {
+  const args = Array.isArray(argv) ? argv.map(String) : [];
+  const out = { sub: null, out: null, json: false, help: false, error: null };
+  if (args.length === 0 || args.includes("--help") || args.includes("-h")) { out.help = true; return out; }
+  out.sub = args[0];
+  const rest = args.slice(1);
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    const eq = a.indexOf("=");
+    const key = a.startsWith("--") && eq > 0 ? a.slice(0, eq) : a;
+    const inline = a.startsWith("--") && eq > 0 ? a.slice(eq + 1) : undefined;
+    const take = () => (inline !== undefined ? inline : rest[++i]);
+    if (key === "--json") out.json = true;
+    else if (key === "--out") {
+      // A MISSING value is an error, never a silent fallback. `--out` with the
+      // path forgotten (or eaten by the shell) used to leave `out` null and
+      // write DESIGN.md into the agent dir — exactly where the operator was
+      // trying not to write — and `--out --json` used to create a directory
+      // called "--json". Both exit 1 now and write nothing.
+      const v = take();
+      if (v === undefined) { out.error = "--out needs a directory"; return out; }
+      if (typeof v === "string" && v.startsWith("--")) { out.error = `--out needs a directory, not ${v}`; return out; }
+      out.out = v;
+    }
+    else { out.error = `unknown argument ${a}`; return out; }
+  }
+  if (out.sub !== "sync") out.error = `unknown design command: ${out.sub}`;
+  else if (out.out !== null && !String(out.out).trim()) out.error = "--out needs a directory";
+  return out;
+}
+
+/** A protocol error frame → one readable line. */
+export function describeFrame(frame) {
+  const e = frame && frame.error ? frame.error : null;
+  if (e) return `${e.code || "error"}: ${e.message || ""}`.trim();
+  return "no response";
+}
+
+/**
+ * Re-exported so `maestro design sync` and the daemon's poller name the
+ * workspace identically — the heading is part of the rendered bytes, so two
+ * definitions would make the two lanes rewrite each other's files forever.
+ * The definition lives in `lib/design/write.mjs`.
+ */
+export { workspaceName };
+
+/**
+ * The testable core. deps: {agentRoot, cfg, now, write, fetchImpl,
+ * getFoundationImpl, syncImpl, io}.
+ * @param {string[]} argv
+ * @param {object} [deps]
+ * @returns {Promise<{code:number, data?:object}>}
+ */
+export async function runDesign(argv, deps = {}) {
+  const write = typeof deps.write === "function" ? deps.write : (s) => process.stdout.write(`${s}\n`);
+  const p = parseDesignArgs(argv);
+  if (p.help) { write(usage()); return { code: 0 }; }
+  if (p.error) { write(`error: ${p.error}\n\n${usage()}`); return { code: 1 }; }
+
+  const agentRoot = deps.agentRoot || process.cwd();
+  const cfg = deps.cfg || loadOrgConfig(agentRoot);
+  if (!isEnabled(cfg)) {
+    write("error: the org (Cohort) is not enabled for this agent — run `maestro setup --only org`.");
+    return { code: 1 };
+  }
+  const conn = configFromAgent(cfg) || {};
+  const now = Number.isFinite(deps.now) ? deps.now : Date.now();
+  const outDir = p.out ? String(p.out) : agentRoot;
+
+  let frame;
+  try {
+    frame = await (deps.getFoundationImpl || brandingGetFoundation)(
+      { historyLimit: 0 },
+      { base: conn.base, token: conn.token, orgId: conn.orgId, fetchImpl: deps.fetchImpl },
+    );
+  } catch (err) {
+    // A transport throw is the same class of failure as an error frame: say so
+    // and write nothing. The last-good DESIGN.md on disk stays authoritative.
+    write(`error: could not read the brand foundation — ${err && err.message ? err.message : String(err)}. Nothing was written.`);
+    return { code: 1 };
+  }
+  if (!frame || !frame.ok || !frame.result || typeof frame.result !== "object") {
+    write(`error: could not read the brand foundation — ${describeFrame(frame)}. Nothing was written.`);
+    return { code: 1 };
+  }
+  if (!frame.result.foundation || typeof frame.result.foundation !== "object") {
+    write("error: the workspace has no brand foundation yet — set one up in Design first. Nothing was written.");
+    return { code: 1 };
+  }
+  // AN UNVERSIONED WORKSPACE IS NOT A BRAND. hq answers a workspace that has
+  // never saved a foundation with its own product defaults and `unversioned:
+  // true` — a complete, plausible palette that is nobody's brand. Writing it
+  // would hand every design skill on the seat a wrong palette wearing the
+  // authority of a generated file. See refresh-gate.mjs#isUnversionedFoundation.
+  if (isUnversionedFoundation(frame.result)) {
+    write("error: this workspace has never saved a brand foundation — hq answered with stock defaults, which are not your brand. Set one up in Design (or propose one with design_propose_change) and re-run. Nothing was written.");
+    return { code: 1 };
+  }
+
+  let result;
+  try {
+    result = (deps.syncImpl || syncDesign)(
+      { agentRoot, outDir, result: frame.result, now, name: deps.name || workspaceName(cfg), source: "cohort · branding.getFoundation" },
+      deps.io || {},
+    );
+  } catch (err) {
+    write(`error: could not write the design files — ${err && err.message ? err.message : String(err)}`);
+    return { code: 1 };
+  }
+
+  if (p.json) {
+    write(JSON.stringify(result, null, 2));
+    return { code: 0, data: result };
+  }
+  const wrote = result.written.length
+    ? `wrote ${result.written.join(", ")}`
+    : `unchanged (${result.unchanged.join(", ")})`;
+  write(`design sync: ${wrote} in ${result.outDir}${result.version ? ` — foundation ${result.version}` : ""}`);
+  return { code: 0, data: result };
+}
+
+/** bin entry: resolve the agent root (env → walk → machine pointer) and run. */
+export async function designCmd(argv) {
+  let agentRoot = null;
+  try {
+    const { resolveAgentRoot } = await import("../collective/config.mjs");
+    agentRoot = resolveAgentRoot(process.cwd());
+  } catch {
+    agentRoot = null; // fall through to cwd
+  }
+  const r = await runDesign(argv, { agentRoot: agentRoot || process.cwd() });
+  process.exitCode = r.code;
+  return r;
+}
+
+export default { runDesign, designCmd, parseDesignArgs, workspaceName, describeFrame, usage };

package/lib/cli/design.test.mjs

@@ -0,0 +1,270 @@
+/**
+ * design.test.mjs — `maestro design sync` (WP-M7 mechanic 4).
+ *
+ * Drives the REAL `runDesign` against a temp agent dir with an injected
+ * `branding.getFoundation`. Two claims carry the command and both are load
+ * bearing:
+ *
+ *   · FAIL-OPEN MEANS "WRITE NOTHING". A seat's DESIGN.md is what every design
+ *     skill grounds on. A failed read must leave the last-good file exactly
+ *     where it is and exit non-zero — the opposite of half-writing a file that
+ *     then looks authoritative.
+ *   · IDEMPOTENT BY BYTES. A second run against an unchanged foundation must
+ *     not touch a single mtime, so the 15-minute daemon poll never churns the
+ *     tree or wakes an editor's file watcher.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, writeFileSync, statSync, utimesSync, existsSync, rmSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+import { runDesign, parseDesignArgs, describeFrame, workspaceName, usage } from "./design.mjs";
+
+const NOW = Date.parse("2026-09-08T12:00:00Z");
+const FIXTURE = JSON.parse(readFileSync(new URL("../design/fixtures/foundation.json", import.meta.url), "utf8"));
+const CFG = { org: { cohort: { enabled: true, base: "https://os.example.test", token: "nlk_t", orgId: "org_1", orgName: "Northwind" } } };
+
+const okFrame = (over = {}) => ({
+  ok: true,
+  result: {
+    foundation: FIXTURE,
+    version: { id: "bv_01HQZ", seq: 7, label: "V2.7" },
+    headVersionId: "bv_01HQZ",
+    isHead: true,
+    unversioned: false,
+    history: [],
+    ...over,
+  },
+});
+
+function harness(t, opts = {}) {
+  const root = mkdtempSync(join(tmpdir(), "maestro-design-cli-"));
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  const lines = [];
+  const calls = [];
+  const deps = {
+    agentRoot: root,
+    cfg: opts.cfg === undefined ? CFG : opts.cfg,
+    now: opts.now === undefined ? NOW : opts.now,
+    write: (s) => lines.push(s),
+    getFoundationImpl: opts.getFoundationImpl || (async (params, o) => { calls.push({ params, o }); return okFrame(); }),
+  };
+  return { root, lines, calls, deps, out: () => lines.join("\n") };
+}
+
+// ── argument parsing ────────────────────────────────────────────────────────
+
+test("parseDesignArgs handles the flags, both spellings, and rejects the rest", () => {
+  assert.deepEqual(parseDesignArgs(["sync"]), { sub: "sync", out: null, json: false, help: false, error: null });
+  assert.equal(parseDesignArgs(["sync", "--json"]).json, true);
+  assert.equal(parseDesignArgs(["sync", "--out", "docs"]).out, "docs");
+  assert.equal(parseDesignArgs(["sync", "--out=docs"]).out, "docs");
+  assert.equal(parseDesignArgs([]).help, true);
+  assert.equal(parseDesignArgs(["--help"]).help, true);
+  assert.equal(parseDesignArgs(["-h"]).help, true);
+  assert.match(parseDesignArgs(["shove"]).error, /unknown design command: shove/);
+  assert.match(parseDesignArgs(["sync", "--wat"]).error, /unknown argument --wat/);
+  assert.match(parseDesignArgs(["sync", "--out", ""]).error, /--out needs a directory/);
+
+  // A MISSING value is an error, not a silent fallback to the agent dir —
+  // which is precisely the directory the operator was trying not to write to.
+  assert.match(parseDesignArgs(["sync", "--out"]).error, /--out needs a directory/);
+  assert.equal(parseDesignArgs(["sync", "--out"]).out, null);
+  assert.match(parseDesignArgs(["sync", "--out", "--json"]).error, /--out needs a directory, not --json/);
+  assert.equal(parseDesignArgs(["sync", "--out", "--json"]).json, false, "and --json was not eaten as a path");
+});
+
+test("`--out` with no path exits 1 and writes nothing at all", async (t) => {
+  const h = harness(t);
+  const r = await runDesign(["sync", "--out"], h.deps);
+  assert.equal(r.code, 1);
+  assert.match(h.out(), /--out needs a directory/);
+  assert.equal(h.calls.length, 0, "not even a read is spent");
+  assert.deepEqual(readdirSync(h.root), [], "and no DESIGN.md lands in the agent dir by accident");
+});
+
+test("--help and a bad argument both print the usage; only the bad argument is an error", async (t) => {
+  const h = harness(t);
+  assert.deepEqual(await runDesign(["--help"], h.deps), { code: 0 });
+  assert.match(h.out(), /maestro design sync/);
+
+  const h2 = harness(t);
+  const r = await runDesign(["sync", "--nope"], h2.deps);
+  assert.equal(r.code, 1);
+  assert.match(h2.out(), /error: unknown argument --nope/);
+  assert.match(h2.out(), /maestro design sync/, "the usage follows the error");
+  assert.ok(usage().includes("design_propose_change"), "the usage says how a change is actually made");
+});
+
+// ── the happy path ──────────────────────────────────────────────────────────
+
+test("sync writes DESIGN.md, PRODUCT.md and the snapshot, and reads the SAVED foundation", async (t) => {
+  const h = harness(t);
+  const r = await runDesign(["sync"], h.deps);
+
+  assert.equal(r.code, 0);
+  assert.deepEqual(r.data.written, ["DESIGN.md", "PRODUCT.md"]);
+  assert.ok(existsSync(join(h.root, "DESIGN.md")));
+  assert.ok(existsSync(join(h.root, "PRODUCT.md")));
+  assert.ok(existsSync(join(h.root, "state", "design", "foundation.json")));
+  assert.match(h.out(), /design sync: wrote DESIGN\.md, PRODUCT\.md/);
+  assert.match(h.out(), /foundation bv_01HQZ/);
+
+  assert.equal(h.calls.length, 1);
+  assert.deepEqual(h.calls[0].params, { historyLimit: 0 }, "no history is fetched — the seat only needs the head");
+  assert.equal(h.calls[0].o.base, "https://os.example.test", "the agent's own connection is used");
+  assert.equal(h.calls[0].o.orgId, "org_1");
+
+  const design = readFileSync(join(h.root, "DESIGN.md"), "utf8");
+  assert.match(design, /^---\nname: "Northwind"\n/, "the heading comes from the org config, not the foundation prose");
+  assert.match(design, /\{colors\.primary\}/);
+  assert.equal(statSync(join(h.root, "DESIGN.md")).mode & 0o777, 0o644);
+  assert.equal(statSync(join(h.root, "PRODUCT.md")).mode & 0o777, 0o644);
+});
+
+test("--json prints the machine result and still writes the files", async (t) => {
+  const h = harness(t);
+  const r = await runDesign(["sync", "--json"], h.deps);
+  assert.equal(r.code, 0);
+  const doc = JSON.parse(h.out());
+  assert.deepEqual(doc.written, ["DESIGN.md", "PRODUCT.md"]);
+  assert.equal(doc.version, "bv_01HQZ");
+  assert.equal(doc.outDir, h.root);
+});
+
+test("--out puts the docs elsewhere and keeps the snapshot under the agent root", async (t) => {
+  const h = harness(t);
+  const outDir = join(h.root, "brand");
+  const r = await runDesign(["sync", "--out", outDir], h.deps);
+  assert.equal(r.code, 0);
+  assert.ok(existsSync(join(outDir, "DESIGN.md")));
+  assert.ok(!existsSync(join(h.root, "DESIGN.md")));
+  assert.ok(existsSync(join(h.root, "state", "design", "foundation.json")));
+});
+
+test("re-running against an unchanged foundation rewrites nothing", async (t) => {
+  const h = harness(t);
+  await runDesign(["sync"], h.deps);
+  const old = new Date(NOW - 86_400_000);
+  for (const rel of ["DESIGN.md", "PRODUCT.md"]) utimesSync(join(h.root, rel), old, old);
+  const before = ["DESIGN.md", "PRODUCT.md"].map((rel) => statSync(join(h.root, rel)).mtimeMs);
+
+  const r = await runDesign(["sync"], { ...h.deps, now: NOW + 3_600_000 });
+  assert.equal(r.code, 0);
+  assert.deepEqual(r.data.written, []);
+  assert.deepEqual(r.data.unchanged, ["DESIGN.md", "PRODUCT.md"]);
+  assert.match(h.out(), /design sync: unchanged \(DESIGN\.md, PRODUCT\.md\)/);
+  assert.deepEqual(["DESIGN.md", "PRODUCT.md"].map((rel) => statSync(join(h.root, rel)).mtimeMs), before);
+});
+
+// ── the failure postures ────────────────────────────────────────────────────
+
+test("an error frame exits 1 and writes NOTHING", async (t) => {
+  const h = harness(t, { getFoundationImpl: async () => ({ ok: false, error: { code: "FORBIDDEN", message: "design.read is not granted to this seat." } }) });
+  const r = await runDesign(["sync"], h.deps);
+  assert.equal(r.code, 1);
+  assert.match(h.out(), /FORBIDDEN: design\.read is not granted to this seat\./);
+  assert.match(h.out(), /Nothing was written\./);
+  assert.deepEqual(readdirSync(h.root), [], "not one file, not even the state dir");
+});
+
+test("a transport throw exits 1, says so, and leaves the last-good files exactly as they were", async (t) => {
+  const h = harness(t);
+  await runDesign(["sync"], h.deps); // establish a good DESIGN.md first
+  const good = readFileSync(join(h.root, "DESIGN.md"), "utf8");
+  const old = new Date(NOW - 86_400_000);
+  utimesSync(join(h.root, "DESIGN.md"), old, old);
+  const mtime = statSync(join(h.root, "DESIGN.md")).mtimeMs;
+
+  const r = await runDesign(["sync"], { ...h.deps, getFoundationImpl: async () => { throw new Error("fetch failed: ECONNREFUSED"); } });
+  assert.equal(r.code, 1);
+  assert.match(h.out(), /could not read the brand foundation — fetch failed: ECONNREFUSED/);
+  assert.match(h.out(), /Nothing was written\./);
+  assert.equal(readFileSync(join(h.root, "DESIGN.md"), "utf8"), good, "the last-good file is untouched");
+  assert.equal(statSync(join(h.root, "DESIGN.md")).mtimeMs, mtime);
+});
+
+test("a workspace with no foundation yet is named as such, not rendered as an empty brand", async (t) => {
+  const h = harness(t, { getFoundationImpl: async () => ({ ok: true, result: { foundation: null, headVersionId: null, unversioned: true, history: [] } }) });
+  const r = await runDesign(["sync"], h.deps);
+  assert.equal(r.code, 1);
+  assert.match(h.out(), /no brand foundation yet — set one up in Design first/);
+  assert.deepEqual(readdirSync(h.root), []);
+});
+
+test("hq's stock defaults are refused: an unversioned workspace writes nothing and is told why", async (t) => {
+  // The FRAME HQ ACTUALLY SENDS for a workspace that never saved a foundation:
+  // a complete `dsDefaults()` palette, `unversioned: true`, `headVersionId:
+  // null`. The `foundation: null` case above cannot occur in production, so
+  // this is the guard that has to hold.
+  const h = harness(t, {
+    getFoundationImpl: async () => ({
+      ok: true,
+      result: {
+        foundation: { ...FIXTURE, colors: [{ name: "Ink", value: "#0d0d0d" }] },
+        version: null,
+        headVersionId: null,
+        isHead: false,
+        unversioned: true,
+        history: [],
+      },
+    }),
+  });
+  const r = await runDesign(["sync"], h.deps);
+  assert.equal(r.code, 1);
+  assert.match(h.out(), /never saved a brand foundation/);
+  assert.match(h.out(), /stock defaults, which are not your brand/);
+  assert.match(h.out(), /Nothing was written\./);
+  assert.deepEqual(readdirSync(h.root), [], "no DESIGN.md wearing another product's palette");
+});
+
+test("an older hq that omits `unversioned` is judged by the version identity instead", async (t) => {
+  const h = harness(t, {
+    getFoundationImpl: async () => ({ ok: true, result: { foundation: FIXTURE, version: null, headVersionId: null, history: [] } }),
+  });
+  const r = await runDesign(["sync"], h.deps);
+  assert.equal(r.code, 1);
+  assert.match(h.out(), /never saved a brand foundation/);
+  assert.deepEqual(readdirSync(h.root), []);
+});
+
+test("a seat that is not enrolled in the org exits 1 and points at setup", async (t) => {
+  const h = harness(t, { cfg: { org: { cohort: { enabled: false } } } });
+  const r = await runDesign(["sync"], h.deps);
+  assert.equal(r.code, 1);
+  assert.match(h.out(), /not enabled for this agent — run `maestro setup --only org`/);
+  assert.equal(h.calls.length, 0, "no hq call is attempted");
+  assert.deepEqual(readdirSync(h.root), []);
+});
+
+test("a write failure is reported, not thrown", async (t) => {
+  const h = harness(t);
+  const r = await runDesign(["sync"], { ...h.deps, syncImpl: () => { throw new Error("EROFS: read-only file system"); } });
+  assert.equal(r.code, 1);
+  assert.match(h.out(), /could not write the design files — EROFS/);
+});
+
+test("describeFrame turns any frame into one readable line", () => {
+  assert.equal(describeFrame({ ok: false, error: { code: "RATE_LIMITED", message: "Slow down." } }), "RATE_LIMITED: Slow down.");
+  assert.equal(describeFrame({ ok: false, error: { message: "no code" } }), "error: no code");
+  assert.equal(describeFrame(null), "no response");
+  assert.equal(describeFrame({ ok: true }), "no response");
+});
+
+test("workspaceName is the one shared with the daemon", async () => {
+  const { workspaceName: fromWriter } = await import("../design/write.mjs");
+  assert.equal(workspaceName, fromWriter, "one definition, so the CLI and the daemon cannot render different headings");
+});
+
+// ── the bin seam ────────────────────────────────────────────────────────────
+
+test("`maestro design` is wired into bin/maestro.mjs", () => {
+  const bin = fileURLToPath(new URL("../../bin/maestro.mjs", import.meta.url));
+  const out = execFileSync(process.execPath, [bin, "design", "--help"], { encoding: "utf8" });
+  assert.match(out, /maestro design sync \[--out <dir>\] \[--json\]/);
+  assert.match(execFileSync(process.execPath, [bin, "--help"], { encoding: "utf8" }), /design sync/, "and listed in the top-level help");
+});

package/lib/cli/global-setup-extras.mjs

@@ -15,6 +15,12 @@
  *                                   persona/audit hook
  *   4. ~/.claude/skills/maestro-<name>/  every shipped skill (symlink for a global
  *                                   install, copy otherwise)
+ *   5. ~/.claude/skills/<pack skill>/    the vendored design skill packs (WP-M7),
+ *                                   copied under their own frontmatter names;
+ *                                   a directory that is not ours is never touched,
+ *                                   local edits inside one that IS ours are
+ *                                   copied aside first, and the whole step is
+ *                                   opt-out via MAESTRO_SKIP_VENDOR_SKILLS=1
  *
  * Additive, idempotent, backed up: JSON files are copied to
  * `<file>.backup.<stamp>` before the first write of a run, and a re-run that
@@ -232,6 +238,7 @@ export async function applyFrontDoorSetup(o = {}) {
     mcp: { changed: false, via: null, skipped: null },
     settings: { changes: [], skipped: null, hookScript: null },
     skills: { mode: null, installed: [], unchanged: [] },
+    vendorSkills: { installed: [], unchanged: [], skipped: [], errors: [] },
   };
   let agentJson = null; // config/agent.json, shared by the identity block and the skill renderer
 
@@ -404,6 +411,43 @@ export async function applyFrontDoorSetup(o = {}) {
     warn(`skills install failed: ${err && err.message}`);
   }
 
+  // 5) Vendored design skill packs (WP-M7) — impeccable, emilkowalski, taste-skill,
+  //    unlazy, installed under their OWN frontmatter names because that is what
+  //    their prose and the cohort-design harmoniser refer to. Copies, never
+  //    links: the point of vendoring is that the seat holds reviewed bytes. A
+  //    directory that is not ours (the human installed the upstream pack
+  //    themselves, launcher and hooks and all) is left exactly as it is.
+  try {
+    // An opt-out, because this step writes into the GLOBAL ~/.claude/skills and
+    // so reaches every piece of work done on the machine, including repos that
+    // have nothing to do with Cohort design. A seat that does not want the
+    // packs sets MAESTRO_SKIP_VENDOR_SKILLS=1 and keeps every other step.
+    const skip = String(process.env.MAESTRO_SKIP_VENDOR_SKILLS || "").trim();
+    if (skip && skip !== "0" && skip.toLowerCase() !== "false") {
+      summary.vendorSkills = { skippedByEnv: true };
+      ok("vendored design skills skipped (MAESTRO_SKIP_VENDOR_SKILLS)");
+      return summary;
+    }
+    const [{ PACKS }, vendor] = await Promise.all([
+      import("../../scripts/vendor/skill-packs.mjs"),
+      import("../collective/vendor-skills.mjs"),
+    ]);
+    const r = vendor.installVendorSkills({ sdkRoot, skillsDir: join(claudeDir, "skills"), packs: PACKS, dryRun });
+    summary.vendorSkills = { installed: r.installed, unchanged: r.unchanged, skipped: r.skipped, backups: r.backups || [], errors: r.errors };
+    if (r.installed.length === 0 && r.skipped.length === 0 && r.errors.length === 0) {
+      ok(`vendored design skills up to date (${r.unchanged.length} pack skill(s))`);
+    } else if (r.installed.length) {
+      ok(`${pre}vendored design skills copied: ${r.installed.join(", ")}${r.unchanged.length ? ` (+${r.unchanged.length} unchanged)` : ""}`);
+    }
+    for (const b of r.backups || []) warn(`design skill ${b.name}: local edits found (${b.files.join(", ")}) — copied to ${b.path} before rewriting`);
+    for (const sk of r.skipped) warn(`design skill ${sk.name} left alone: ${sk.reason}`);
+    for (const e of r.errors || []) warn(`design pack ${e.pack}: ${e.error}`);
+  } catch (err) {
+    // Fail-open: an SDK copy that predates WP-M7 has no vendor tree, and a seat
+    // that cannot install design skills must still get its identity and tools.
+    warn(`vendored design skills not installed: ${err && err.message}`);
+  }
+
   return summary;
 }