@cohortapp/agent-sdk 2.3.0

package/scripts/setup/generate-agent-package-json.mjs

@@ -0,0 +1,222 @@
+/**
+ * generate-agent-package-json.mjs — the generated-agent package.json builder.
+ *
+ * Why this module exists (gaps-product-quality P0-1)
+ * --------------------------------------------------
+ * `maestro create` scaffolds an agent repo and writes its package.json inline
+ * in bin/maestro.mjs. That generated package.json has two distribution-breaking
+ * holes, both adversarially confirmed in the packaging audit:
+ *
+ *   1. It does NOT depend on `@cohortapp/agent-sdk`. The documented upgrade path —
+ *      `npm update @cohortapp/agent-sdk` (and the generated `upgrade`/`doctor`/`init`
+ *      scripts that shell `npx @cohortapp/agent-sdk …`) — is therefore a no-op: npm
+ *      has nothing to update, and npx re-fetches the latest tarball on every
+ *      call instead of running the pinned version the agent was created against.
+ *   2. It omits `better-sqlite3` and `js-yaml` — the two real runtime deps of
+ *      the framework. They are NOT pulled transitively, so the learning loop
+ *      (sessions.db), RAG (embedding store), and every YAML-gated channel
+ *      adapter reject at runtime on a freshly-created agent.
+ *
+ * This module factors the package.json shape into a pure function so it is
+ * unit-testable and so the create path can adopt it without re-deriving the
+ * dependency set. Pinning `@cohortapp/agent-sdk` to the *framework version that
+ * created the repo* also makes drift measurable (each agent records the version
+ * it was scaffolded from) and lets `npm update` actually move it forward.
+ *
+ * NOTE: wiring this into bin/maestro.mjs's `create()` is a follow-up — bin/ is
+ * out of this change's scope. Until then this is the single source of truth for
+ * the corrected shape, consumed by the writer below and by callers/tests.
+ *
+ * Node builtins only (maestro is "type":"module", near-zero-dep by design).
+ *
+ * @module scripts/setup/generate-agent-package-json
+ */
+
+"use strict";
+
+import { writeJsonAtomic } from "../../lib/fs-atomic.mjs";
+
+/**
+ * The framework's own real runtime dependencies. These MUST be present in a
+ * generated agent's package.json because maestro modules `import` them directly
+ * and they are not guaranteed to be hoisted transitively from the
+ * `@cohortapp/agent-sdk` install. Kept in sync with the framework package.json
+ * "dependencies" block.
+ *
+ * @type {Readonly<Record<string,string>>}
+ */
+export const FRAMEWORK_RUNTIME_DEPS = Object.freeze({
+  "better-sqlite3": "^12.10.0",
+  "js-yaml": "^4.1.1",
+});
+
+/**
+ * Extra runtime deps the scaffolded agent uses directly (email/IMAP, the
+ * Google GenAI + OpenAI SDKs, dotenv, execa). Preserved from the historical
+ * inline create() shape so adopting this builder is behaviour-preserving for
+ * everything except the maestro/core-dep fix.
+ *
+ * @type {Readonly<Record<string,string>>}
+ */
+export const AGENT_EXTRA_DEPS = Object.freeze({
+  "@google/genai": "^1.42.0",
+  dotenv: "^16.4.5",
+  execa: "^9.6.1",
+  imapflow: "^1.2.18",
+  mailparser: "^3.9.6",
+  openai: "^6.33.0",
+});
+
+/** Dev deps preserved from the inline create() shape. @type {Readonly<Record<string,string>>} */
+export const AGENT_DEV_DEPS = Object.freeze({
+  sharp: "^0.34.5",
+  tsx: "^4.20.6",
+});
+
+/** The scripts block preserved from the inline create() shape. @returns {Record<string,string>} */
+function defaultScripts() {
+  return {
+    "init-agent": "./scripts/setup/init-agent.sh",
+    "configure-macos": "sudo ./scripts/setup/configure-macos.sh",
+    "configure-macos:check": "./scripts/setup/configure-macos.sh --check",
+    daemon: "node scripts/daemon/maestro-daemon.mjs",
+    "cadence:enqueue": "node scripts/cadence/enqueue-cadence-tick.mjs",
+    "cadence:consume": "node scripts/daemon/cadence-consumer.mjs",
+    "cadence:status": "node scripts/cadence/cadence-status.mjs",
+    healthcheck: "./scripts/healthcheck.sh",
+    "emergency-stop": "./scripts/emergency-stop.sh",
+    resume: "./scripts/resume-operations.sh",
+    "pdf:memo": "node scripts/pdf-generation/build-document.mjs --template memo",
+    "pdf:board-pack": "node scripts/pdf-generation/build-document.mjs --template board-pack",
+    "pdf:letter": "node scripts/pdf-generation/build-document.mjs --template corporate-letter",
+    "pdf:investor": "node scripts/pdf-generation/build-document.mjs --template investor-letter",
+    "gen:illustration": "node scripts/media-generation/generate-assets.mjs --illustration",
+    "gen:video": "node scripts/media-generation/generate-assets.mjs --video",
+    "gen:all-missing": "node scripts/media-generation/generate-assets.mjs --all-missing",
+    "gen:list": "node scripts/media-generation/generate-assets.mjs --list",
+    "slack:events": "node scripts/slack-events-server.mjs",
+    "slack:events:start": "./scripts/slack-events-ctl.sh start",
+    "slack:events:stop": "./scripts/slack-events-ctl.sh stop",
+    "slack:events:status": "./scripts/slack-events-ctl.sh status",
+    upgrade: "npx @cohortapp/agent-sdk upgrade",
+    init: "npx @cohortapp/agent-sdk init",
+    doctor: "npx @cohortapp/agent-sdk doctor",
+  };
+}
+
+/**
+ * Normalise an arbitrary framework version into a valid npm version range that
+ * pins `@cohortapp/agent-sdk`. A bare semver `1.18.0` is pinned exact-or-newer with
+ * a caret (`^1.18.0`) so `npm update` can advance within the major. A value
+ * that already carries a range operator (`^`, `~`, `>=`, `*`, a dist-tag like
+ * `latest`, or a url/path) is passed through untouched. Empty/invalid input
+ * falls back to `"latest"` so the dep is at least present (npm update can still
+ * resolve it) rather than omitted — which was the original bug.
+ *
+ * @param {string} [frameworkVersion]
+ * @returns {string}
+ */
+export function pinMaestroVersion(frameworkVersion) {
+  const v = typeof frameworkVersion === "string" ? frameworkVersion.trim() : "";
+  if (!v) return "latest";
+  // Already a range / tag / url / path spec — respect it verbatim.
+  if (/^[\^~]|^[<>=]|[*x]|\s-\s|\|\||^[a-z]|[:/]/i.test(v)) return v;
+  // Bare semver (optionally with a prerelease/build) — caret-pin it.
+  if (/^\d+\.\d+\.\d+(?:[-+].*)?$/.test(v)) return `^${v}`;
+  // Partial like "1.18" or "1" — caret-pin as-is (valid npm range).
+  if (/^\d+(?:\.\d+)?$/.test(v)) return `^${v}`;
+  return v;
+}
+
+/**
+ * Build the package.json object for a freshly-created agent repo.
+ *
+ * The returned `dependencies` ALWAYS includes a pinned `@cohortapp/agent-sdk` plus
+ * the framework runtime deps (`better-sqlite3`, `js-yaml`) on top of the agent's
+ * own direct deps — closing P0-1's "npm update is a no-op / core deps missing"
+ * holes.
+ *
+ * Pure: no IO, deterministic for a given input. Sorts dependency keys so the
+ * generated file is stable across runs (avoids churny diffs on regenerate).
+ *
+ * @param {object} opts
+ * @param {string} opts.name - npm package name for the agent repo (the dir name).
+ * @param {string} [opts.frameworkVersion] - the @cohortapp/agent-sdk version the
+ *   repo is created against; pinned via {@link pinMaestroVersion}.
+ * @param {string} [opts.description]
+ * @returns {object} package.json content as a plain object
+ */
+export function buildAgentPackageJson(opts = {}) {
+  const name = typeof opts.name === "string" ? opts.name.trim() : "";
+  if (!name) throw new Error("buildAgentPackageJson: opts.name is required");
+
+  const dependencies = sortKeys({
+    "@cohortapp/agent-sdk": pinMaestroVersion(opts.frameworkVersion),
+    ...FRAMEWORK_RUNTIME_DEPS,
+    ...AGENT_EXTRA_DEPS,
+  });
+
+  return {
+    name,
+    version: "1.0.0",
+    description:
+      typeof opts.description === "string" && opts.description
+        ? opts.description
+        : "Maestro AI agent — configure with: maestro setup",
+    type: "module",
+    private: true,
+    scripts: defaultScripts(),
+    dependencies,
+    devDependencies: sortKeys({ ...AGENT_DEV_DEPS }),
+  };
+}
+
+/** Return a new object with keys sorted ascending (stable serialization). */
+function sortKeys(obj) {
+  const out = {};
+  for (const k of Object.keys(obj).sort()) out[k] = obj[k];
+  return out;
+}
+
+/**
+ * Thin writer: build the package.json and atomically write it to
+ * `<targetDir>/package.json` (durable, crash-safe — uses the shared fs-atomic
+ * primitive so a half-written package.json can never ship).
+ *
+ * @param {string} targetDir - the agent repo root.
+ * @param {object} opts - forwarded to {@link buildAgentPackageJson}.
+ * @returns {object} the package.json object that was written.
+ */
+export function writeAgentPackageJson(targetDir, opts = {}) {
+  if (typeof targetDir !== "string" || !targetDir) {
+    throw new Error("writeAgentPackageJson: targetDir is required");
+  }
+  const pkg = buildAgentPackageJson(opts);
+  // node:path import kept local to the writer so the pure builder stays IO-free.
+  const target = joinPath(targetDir, "package.json");
+  writeJsonAtomic(target, pkg);
+  return pkg;
+}
+
+/** Minimal join that avoids importing node:path at module top (builder stays pure-only at top level). */
+function joinPath(dir, file) {
+  return dir.endsWith("/") ? `${dir}${file}` : `${dir}/${file}`;
+}
+
+// CLI: `node scripts/setup/generate-agent-package-json.mjs <name> [version] [targetDir]`
+// Prints the generated package.json (or writes it if a targetDir is given).
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const [name, version, targetDir] = process.argv.slice(2);
+  if (!name) {
+    console.error(
+      "usage: generate-agent-package-json <name> [frameworkVersion] [targetDir]",
+    );
+    process.exit(2);
+  }
+  if (targetDir) {
+    const pkg = writeAgentPackageJson(targetDir, { name, frameworkVersion: version });
+    console.log(`wrote ${targetDir}/package.json (@cohortapp/agent-sdk ${pkg.dependencies["@cohortapp/agent-sdk"]})`);
+  } else {
+    console.log(JSON.stringify(buildAgentPackageJson({ name, frameworkVersion: version }), null, 2));
+  }
+}

package/scripts/setup/generate-agent-package-json.test.mjs

@@ -0,0 +1,143 @@
+/**
+ * Tests for generate-agent-package-json.mjs — the generated-agent dependency fix
+ * (gaps-product-quality P0-1).
+ *
+ * Asserts the corrected package.json: a pinned `@cohortapp/agent-sdk` plus the real
+ * runtime deps (`better-sqlite3`, `js-yaml`) are always present, the version
+ * pin normaliser behaves, and the writer round-trips to disk.
+ *
+ * @module scripts/setup/generate-agent-package-json.test
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+import {
+  buildAgentPackageJson,
+  writeAgentPackageJson,
+  pinMaestroVersion,
+  FRAMEWORK_RUNTIME_DEPS,
+  AGENT_EXTRA_DEPS,
+} from "./generate-agent-package-json.mjs";
+
+describe("buildAgentPackageJson: the P0-1 dependency fix", () => {
+  it("depends on a PINNED @cohortapp/agent-sdk (the npm update path is no longer a no-op)", () => {
+    const pkg = buildAgentPackageJson({ name: "acme-ai", frameworkVersion: "1.18.0" });
+    assert.equal(pkg.dependencies["@cohortapp/agent-sdk"], "^1.18.0");
+  });
+
+  it("includes the real framework runtime deps (better-sqlite3 + js-yaml)", () => {
+    const pkg = buildAgentPackageJson({ name: "acme-ai", frameworkVersion: "1.18.0" });
+    assert.equal(pkg.dependencies["better-sqlite3"], FRAMEWORK_RUNTIME_DEPS["better-sqlite3"]);
+    assert.equal(pkg.dependencies["js-yaml"], FRAMEWORK_RUNTIME_DEPS["js-yaml"]);
+  });
+
+  it("keeps the agent's own direct deps (email/SDK stack)", () => {
+    const pkg = buildAgentPackageJson({ name: "acme-ai" });
+    for (const dep of Object.keys(AGENT_EXTRA_DEPS)) {
+      assert.equal(pkg.dependencies[dep], AGENT_EXTRA_DEPS[dep], `missing ${dep}`);
+    }
+  });
+
+  it("produces the expected scaffold shape", () => {
+    const pkg = buildAgentPackageJson({ name: "acme-ai" });
+    assert.equal(pkg.name, "acme-ai");
+    assert.equal(pkg.type, "module");
+    assert.equal(pkg.private, true);
+    assert.equal(pkg.version, "1.0.0");
+    assert.ok(pkg.scripts && typeof pkg.scripts === "object");
+    // upgrade/init/doctor scripts shell @cohortapp/agent-sdk — now actually installed.
+    assert.match(pkg.scripts.upgrade, /@cohortapp\/agent-sdk upgrade/);
+    assert.ok(pkg.devDependencies.sharp);
+  });
+
+  it("dependency keys are sorted for stable serialization", () => {
+    const pkg = buildAgentPackageJson({ name: "acme-ai", frameworkVersion: "1.18.0" });
+    const keys = Object.keys(pkg.dependencies);
+    assert.deepEqual(keys, [...keys].sort());
+    // the SDK is pinned and present among the (sorted) dependency keys
+    assert.ok(keys.includes("@cohortapp/agent-sdk"));
+  });
+
+  it("trims the name and honours a custom description", () => {
+    const pkg = buildAgentPackageJson({ name: "  bot-ai  ", description: "Bot." });
+    assert.equal(pkg.name, "bot-ai");
+    assert.equal(pkg.description, "Bot.");
+  });
+
+  it("throws when name is missing", () => {
+    assert.throws(() => buildAgentPackageJson({}), /name is required/);
+    assert.throws(() => buildAgentPackageJson({ name: "   " }), /name is required/);
+  });
+});
+
+describe("pinMaestroVersion", () => {
+  it("caret-pins a bare semver", () => {
+    assert.equal(pinMaestroVersion("1.18.0"), "^1.18.0");
+  });
+
+  it("caret-pins a partial version", () => {
+    assert.equal(pinMaestroVersion("1.18"), "^1.18");
+    assert.equal(pinMaestroVersion("2"), "^2");
+  });
+
+  it("passes through an existing range/tag/operator verbatim", () => {
+    assert.equal(pinMaestroVersion("^1.18.0"), "^1.18.0");
+    assert.equal(pinMaestroVersion("~1.18.0"), "~1.18.0");
+    assert.equal(pinMaestroVersion(">=1.0.0"), ">=1.0.0");
+    assert.equal(pinMaestroVersion("latest"), "latest");
+    assert.equal(pinMaestroVersion("*"), "*");
+  });
+
+  it("handles a prerelease semver", () => {
+    assert.equal(pinMaestroVersion("1.18.0-rc.1"), "^1.18.0-rc.1");
+  });
+
+  it("falls back to 'latest' for empty/invalid input (dep still present)", () => {
+    assert.equal(pinMaestroVersion(""), "latest");
+    assert.equal(pinMaestroVersion(undefined), "latest");
+    assert.equal(pinMaestroVersion(null), "latest");
+  });
+});
+
+describe("writeAgentPackageJson", () => {
+  it("atomically writes a valid, parseable package.json to disk", () => {
+    const dir = mkdtempSync(path.join(os.tmpdir(), "agent-pkg-"));
+    try {
+      const returned = writeAgentPackageJson(dir, {
+        name: "disk-ai",
+        frameworkVersion: "1.18.0",
+      });
+      const onDisk = JSON.parse(readFileSync(path.join(dir, "package.json"), "utf8"));
+      assert.equal(onDisk.name, "disk-ai");
+      assert.equal(onDisk.dependencies["@cohortapp/agent-sdk"], "^1.18.0");
+      assert.equal(onDisk.dependencies["better-sqlite3"], FRAMEWORK_RUNTIME_DEPS["better-sqlite3"]);
+      assert.equal(onDisk.dependencies["js-yaml"], FRAMEWORK_RUNTIME_DEPS["js-yaml"]);
+      assert.deepEqual(onDisk, returned);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("throws when targetDir is missing", () => {
+    assert.throws(() => writeAgentPackageJson("", { name: "x" }), /targetDir is required/);
+  });
+});
+
+describe("parity with the framework's declared runtime deps", () => {
+  it("FRAMEWORK_RUNTIME_DEPS matches the maestro package.json dependencies", () => {
+    const repoRoot = path.resolve(
+      path.dirname(new URL(import.meta.url).pathname),
+      "..",
+      "..",
+    );
+    const pkg = JSON.parse(readFileSync(path.join(repoRoot, "package.json"), "utf8"));
+    // Every framework runtime dep we inject must exist in the framework itself.
+    for (const dep of Object.keys(FRAMEWORK_RUNTIME_DEPS)) {
+      assert.ok(pkg.dependencies[dep], `framework no longer declares ${dep}`);
+    }
+  });
+});

package/scripts/setup/generate-autonomy.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+/**
+ * generate-autonomy.mjs — write the agent's archetype-derived autonomy policy.
+ *
+ * Resolves the archetype (function × altitude) and renders
+ * policies/action-classification.yaml from lib/autonomy.mjs — replacing the
+ * hardcoded one-persona policy with one whose autonomy bands, decision rights,
+ * escalation, and per-action risk map reflect THIS agent's archetype. It lands
+ * at policies/action-classification.yaml, exactly where lib/voice/tool-bridge.mjs
+ * (and the pre-send/outbound checks) read it, so the gate is live.
+ *
+ * Execution contract mirrors the other generators (cwd = agent repo; MAESTRO_ROOT
+ * / AGENT_ROOT in env). Uses js-yaml.
+ *
+ * @module scripts/setup/generate-autonomy
+ */
+
+"use strict";
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const MAESTRO_ROOT =
+  process.env.MAESTRO_ROOT && existsSync(join(process.env.MAESTRO_ROOT, "lib", "autonomy.mjs"))
+    ? process.env.MAESTRO_ROOT
+    : resolve(here, "..", "..");
+const AGENT_ROOT = process.env.AGENT_ROOT || process.cwd();
+
+async function main() {
+  const { resolveArchetype, migrateLegacyArchetype } = await import(pathToFileURL(join(MAESTRO_ROOT, "lib", "archetype.mjs")).href);
+  const { buildActionClassification } = await import(pathToFileURL(join(MAESTRO_ROOT, "lib", "autonomy.mjs")).href);
+  const yamlMod = await import("js-yaml");
+  const yaml = yamlMod && yamlMod.default ? yamlMod.default : yamlMod;
+
+  const cfgPath = join(AGENT_ROOT, "config", "agent.json");
+  if (!existsSync(cfgPath)) { console.error(`[generate-autonomy] no config/agent.json at ${cfgPath}`); return 1; }
+  const identity = JSON.parse(readFileSync(cfgPath, "utf-8"));
+  const sel = identity.function && identity.altitude
+    ? { function: identity.function, altitude: identity.altitude }
+    : migrateLegacyArchetype(identity.archetype);
+  if (!sel) { console.error("[generate-autonomy] config/agent.json has no { function, altitude } archetype."); return 1; }
+
+  const profile = await resolveArchetype(sel);
+  const policy = buildActionClassification(profile, identity);
+
+  const out = join(AGENT_ROOT, "policies", "action-classification.yaml");
+  mkdirSync(dirname(out), { recursive: true });
+  writeFileSync(out, yaml.dump(policy, { lineWidth: 100, noRefs: true }), "utf-8");
+
+  const high = Object.values(policy.actions).filter((x) => x.risk === "high").length;
+  console.log(`[generate-autonomy] ${profile.label} (${profile.function} × ${profile.altitude}), breadth=${policy.delegation_breadth}`);
+  console.log(`[generate-autonomy]   wrote policies/action-classification.yaml — ${policy.action_levels.execute_autonomous.examples.length} green / ${policy.action_levels.approval_preferred.examples.length} amber / ${policy.action_levels.escalate.examples.length} red bands; ${Object.keys(policy.actions).length} gated actions (${high} verbal-confirm).`);
+  return 0;
+}
+
+main()
+  .then((c) => process.exit(c))
+  .catch((e) => { console.error(`[generate-autonomy] FAILED: ${e && e.message ? e.message : e}`); process.exit(1); });

package/scripts/setup/generate-backlog.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * generate-backlog.mjs — seed a proactive WBS backlog from the agent's resolved
+ * archetype profile (lib/archetype.mjs ⊕ lib/backlog.mjs) so the agent gets
+ * straight to work the moment the daemon starts.
+ *
+ * Writes:
+ *   state/backlog/wbs.yaml   — the WBS roll-up (streams → phases → epics → tasks)
+ *   state/queues/backlog.yaml — first-30-day tasks materialised as backlog-executor items
+ *   config/priorities.yaml    — strategic priorities (one per stream)
+ *
+ * Run by the init wizard (and re-runnable via `maestro`). The wizard ENRICHES
+ * the WBS epics/tasks with company-specific content from the gathered context
+ * pack before/after this; even un-enriched the seed is real, actionable work.
+ *
+ * Execution contract mirrors init-archetype.mjs (cwd = agent repo; MAESTRO_ROOT
+ * / AGENT_ROOT in env). Uses js-yaml (a maestro runtime dep).
+ *
+ * @module scripts/setup/generate-backlog
+ */
+
+"use strict";
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const MAESTRO_ROOT =
+  process.env.MAESTRO_ROOT && existsSync(join(process.env.MAESTRO_ROOT, "lib", "backlog.mjs"))
+    ? process.env.MAESTRO_ROOT
+    : resolve(here, "..", "..");
+const AGENT_ROOT = process.env.AGENT_ROOT || process.cwd();
+
+async function main() {
+  const { resolveArchetype, migrateLegacyArchetype } = await import(pathToFileURL(join(MAESTRO_ROOT, "lib", "archetype.mjs")).href);
+  const { buildBacklogSkeleton, materializeReadyTasks, toQueueFile, countReadyTasks } = await import(pathToFileURL(join(MAESTRO_ROOT, "lib", "backlog.mjs")).href);
+  const yamlMod = await import("js-yaml");
+  const yaml = yamlMod && yamlMod.default ? yamlMod.default : yamlMod;
+
+  const cfgPath = join(AGENT_ROOT, "config", "agent.json");
+  if (!existsSync(cfgPath)) {
+    console.error(`[generate-backlog] no config/agent.json at ${cfgPath} — run from an agent repo.`);
+    return 1;
+  }
+  const identity = JSON.parse(readFileSync(cfgPath, "utf-8"));
+  const sel = identity.function && identity.altitude
+    ? { function: identity.function, altitude: identity.altitude }
+    : migrateLegacyArchetype(identity.archetype);
+  if (!sel) {
+    console.error("[generate-backlog] config/agent.json has no { function, altitude } archetype — run init-archetype first.");
+    return 1;
+  }
+  const profile = await resolveArchetype(sel);
+  const date = new Date().toISOString().slice(0, 10);
+  const owner = (identity.firstName || "agent").toLowerCase();
+
+  // The fetched org context (config/org-context.json — written by the Cohort
+  // bootstrap during `maestro setup`/`sync`) SHAPES the backlog: its strategy
+  // streams + ready-board frontier become the leading WBS streams. Fail-open —
+  // a standalone (un-enrolled) agent has no cache and gets the archetype-only
+  // skeleton unchanged. Loaded via the same loader the awareness SDK uses.
+  let orgContext = null;
+  try {
+    const { loadOrgContext } = await import(pathToFileURL(join(MAESTRO_ROOT, "lib", "org", "bootstrap-context.mjs")).href);
+    orgContext = loadOrgContext(AGENT_ROOT);
+  } catch {
+    orgContext = null;
+  }
+
+  const wbs = buildBacklogSkeleton(profile, identity, { date, orgContext });
+  const { queueItems, priorities } = materializeReadyTasks(wbs, { owner, date });
+
+  const dump = (obj) => yaml.dump(obj, { lineWidth: 100, noRefs: true });
+
+  const wbsPath = join(AGENT_ROOT, "state", "backlog", "wbs.yaml");
+  mkdirSync(dirname(wbsPath), { recursive: true });
+  writeFileSync(wbsPath, dump(wbs), "utf-8");
+
+  const queuePath = join(AGENT_ROOT, "state", "queues", "backlog.yaml");
+  mkdirSync(dirname(queuePath), { recursive: true });
+  writeFileSync(queuePath, dump(toQueueFile(queueItems, { queue: "backlog" })), "utf-8");
+
+  const prioPath = join(AGENT_ROOT, "config", "priorities.yaml");
+  mkdirSync(dirname(prioPath), { recursive: true });
+  writeFileSync(prioPath, dump({ priorities }), "utf-8");
+
+  console.log(`[generate-backlog] ${profile.label} (${profile.function} × ${profile.altitude})`);
+  if (wbs.orgContextApplied) {
+    console.log("[generate-backlog]   org context APPLIED — strategy streams + ready-board frontier lead the backlog");
+  }
+  console.log(`[generate-backlog]   state/backlog/wbs.yaml      — ${wbs.streams.length} streams × 30/60/90, ${countReadyTasks(wbs)} ready tasks`);
+  console.log(`[generate-backlog]   state/queues/backlog.yaml   — ${queueItems.length} seeded items (status open)`);
+  console.log(`[generate-backlog]   config/priorities.yaml      — ${priorities.length} strategic priorities`);
+  console.log("[generate-backlog] NEXT: enrich the WBS epics/tasks with company-specific work from the init context pack, then re-run to re-materialise.");
+  return 0;
+}
+
+main()
+  .then((c) => process.exit(c))
+  .catch((e) => { console.error(`[generate-backlog] FAILED: ${e && e.message ? e.message : e}`); process.exit(1); });

package/scripts/setup/generate-cadences.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+/**
+ * generate-cadences.mjs — write the agent's archetype-specific cadence set.
+ *
+ * Resolves the cadence set for the agent's { function, altitude } (lib/cadences.mjs)
+ * and writes:
+ *   config/cadences.yaml        — the full resolved cadence list (human SoT;
+ *                                 read by cadence-handlers.mjs to route ticks)
+ *   config/.cadence-plists.tsv  — machine-readable params for the NON-standard
+ *                                 (function/altitude) cadences, consumed by
+ *                                 generate-plists.sh to emit launchd plists
+ *                                 (id | interval | base64(scheduleXML), pipe-delimited).
+ *
+ * The standard cadences (inbox/backlog/meeting/daily/quarterly) are emitted by
+ * generate-plists.sh directly; this adds the archetype-specific ones on top, so
+ * a compliance officer and a founder get genuinely different schedules.
+ *
+ * Execution contract mirrors the other generators (cwd = agent repo; MAESTRO_ROOT
+ * / AGENT_ROOT in env). Uses js-yaml.
+ *
+ * @module scripts/setup/generate-cadences
+ */
+
+"use strict";
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const MAESTRO_ROOT =
+  process.env.MAESTRO_ROOT && existsSync(join(process.env.MAESTRO_ROOT, "lib", "cadences.mjs"))
+    ? process.env.MAESTRO_ROOT
+    : resolve(here, "..", "..");
+const AGENT_ROOT = process.env.AGENT_ROOT || process.cwd();
+
+/** Build the StartCalendarInterval dict-content XML expected by generate_trigger_plist. */
+function scheduleXml(cal) {
+  let x = "";
+  if (cal.weekday != null) x += `        <key>Weekday</key>\n        <integer>${cal.weekday}</integer>\n`;
+  if (cal.day != null) x += `        <key>Day</key>\n        <integer>${cal.day}</integer>\n`;
+  x += `        <key>Hour</key>\n        <integer>${cal.hour ?? 9}</integer>\n        <key>Minute</key>\n        <integer>${cal.minute ?? 0}</integer>`;
+  return x;
+}
+
+async function main() {
+  const { resolveArchetype, migrateLegacyArchetype } = await import(pathToFileURL(join(MAESTRO_ROOT, "lib", "archetype.mjs")).href);
+  const { resolveCadences } = await import(pathToFileURL(join(MAESTRO_ROOT, "lib", "cadences.mjs")).href);
+  const yamlMod = await import("js-yaml");
+  const yaml = yamlMod && yamlMod.default ? yamlMod.default : yamlMod;
+
+  const cfgPath = join(AGENT_ROOT, "config", "agent.json");
+  if (!existsSync(cfgPath)) { console.error(`[generate-cadences] no config/agent.json at ${cfgPath}`); return 1; }
+  const identity = JSON.parse(readFileSync(cfgPath, "utf-8"));
+  const sel = identity.function && identity.altitude
+    ? { function: identity.function, altitude: identity.altitude }
+    : migrateLegacyArchetype(identity.archetype);
+  if (!sel) { console.error("[generate-cadences] config/agent.json has no { function, altitude } archetype."); return 1; }
+  // resolveArchetype validates the pair; throws if invalid.
+  await resolveArchetype(sel);
+
+  const cadences = await resolveCadences(sel);
+
+  mkdirSync(join(AGENT_ROOT, "config"), { recursive: true });
+  writeFileSync(join(AGENT_ROOT, "config", "cadences.yaml"),
+    yaml.dump({ archetype: `${sel.function}@${sel.altitude}`, cadences }, { lineWidth: 100, noRefs: true }), "utf-8");
+
+  // TSV for the launchd plist generator — non-standard cadences only (standard
+  // ones are emitted by generate-plists.sh directly).
+  const lines = [];
+  for (const c of cadences) {
+    if (c.scope === "standard") continue;
+    if (typeof c.interval === "number") lines.push(`${c.id}|${c.interval}|`);
+    else if (c.calendar) lines.push(`${c.id}||${Buffer.from(scheduleXml(c.calendar), "utf-8").toString("base64")}`);
+  }
+  writeFileSync(join(AGENT_ROOT, "config", ".cadence-plists.tsv"), lines.join("\n") + (lines.length ? "\n" : ""), "utf-8");
+
+  // Routing registry (sync JSON for cadence-handlers.getCadenceDef): id → {mode, prompt}.
+  const registry = {};
+  for (const c of cadences) registry[c.id] = { mode: c.mode, prompt: c.prompt };
+  writeFileSync(join(AGENT_ROOT, "config", ".cadence-registry.json"), JSON.stringify(registry, null, 2) + "\n", "utf-8");
+
+  const std = cadences.filter((c) => c.scope === "standard").length;
+  console.log(`[generate-cadences] ${sel.function} × ${sel.altitude}: ${cadences.length} cadences (${std} standard + ${cadences.length - std} archetype-specific)`);
+  console.log(`[generate-cadences]   wrote config/cadences.yaml + config/.cadence-plists.tsv (${lines.length} archetype plist entries)`);
+  console.log("[generate-cadences]   run generate-plists.sh next to emit launchd plists (standard + archetype).");
+  return 0;
+}
+
+main()
+  .then((c) => process.exit(c))
+  .catch((e) => { console.error(`[generate-cadences] FAILED: ${e && e.message ? e.message : e}`); process.exit(1); });