@cohortapp/agent-sdk 2.3.0

package/lib/cadences.mjs

@@ -0,0 +1,205 @@
+/**
+ * cadences.mjs — resolve an archetype's scheduled-task cadence set.
+ *
+ * "Which scheduled tasks run, when" is a function of the archetype, not a fixed
+ * 13-tick rhythm. The resolved cadence list =
+ *   STANDARD_CADENCES (every agent: inbox/backlog/meeting sweeps + daily brief/
+ *     sweep/wrap + quarterly self-assessment)
+ *   ⊕ the function's recurring workflows (from the capability pack — pr-review is
+ *     event-driven so excluded; engineering-health/weekly, release-train/weekly,
+ *     capacity-cost/monthly, … become scheduled cadences)
+ *   ⊕ altitude cadences (a C-suite/SVP gets a weekly strategic memo + board pack;
+ *     a founder gets runway + investor-update; a VP/senior-manager gets a
+ *     priorities/execution review).
+ *
+ * Schedules for function/altitude cadences are assigned deterministically and
+ * staggered (by a stable slot derived from the id) so they don't all fire at
+ * once. The init generator writes the resolved set to config/cadences.yaml;
+ * generate-plists.sh emits launchd plists from it, and cadence-handlers.mjs
+ * consults it (both fall back to the legacy hardcoded set when it's absent).
+ *
+ * Pure-ish (reads the capability pack). Deterministic (no Date/random). ESM.
+ *
+ * @module cadences
+ */
+
+"use strict";
+
+import { loadCapabilityPack, listCapabilityFunctions } from "./capability.mjs";
+
+/** The standard cadences every maestro agent runs, with explicit schedules. */
+export const STANDARD_CADENCES = [
+  { id: "inbox-processor", scope: "standard", mode: "guarded", interval: 300, prompt: "schedules/triggers/inbox-processor.md" },
+  { id: "backlog-executor", scope: "standard", mode: "guarded", interval: 600, prompt: "schedules/triggers/backlog-executor.md" },
+  { id: "meeting-prep", scope: "standard", mode: "guarded", interval: 900, prompt: "schedules/triggers/meeting-prep.md" },
+  { id: "meeting-action-capture", scope: "standard", mode: "escalate", interval: 1800, prompt: "schedules/triggers/meeting-action-capture.md" },
+  { id: "daily-morning-brief", scope: "standard", mode: "escalate", calendar: { hour: 6, minute: 30 }, prompt: "schedules/triggers/daily-morning-brief.md" },
+  { id: "daily-midday-sweep", scope: "standard", mode: "escalate", calendar: { hour: 12, minute: 0 }, prompt: "schedules/triggers/daily-midday-sweep.md" },
+  { id: "daily-evening-wrap", scope: "standard", mode: "escalate", calendar: { hour: 18, minute: 0 }, prompt: "schedules/triggers/daily-evening-wrap.md" },
+  { id: "quarterly-self-assessment", scope: "standard", mode: "escalate", calendar: { day: 1, hour: 9, minute: 0 }, prompt: "schedules/triggers/quarterly-self-assessment.md" },
+  { id: "org-pulse", scope: "standard", mode: "escalate", calendar: { hour: 7, minute: 30 }, prompt: "schedules/triggers/org-pulse.md" },
+  // WS3 self-learning: deterministic skill lifecycle housekeeping. Guarded +
+  // inline (no prompt) — the daemon only runs the pure curator transitions when
+  // a self-authored skill has crossed a 30/90-day staleness boundary.
+  { id: "skill-curator", scope: "standard", mode: "guarded", calendar: { hour: 4, minute: 0 } },
+  // Economics / scheduling cadences (WS-economics). All deterministic, so they
+  // run INLINE in the persistent daemon (no LLM, no sub-session) — except
+  // dynamic-jobs, which is GUARDED: its guard escalates ONLY when an agent-created
+  // job is actually due, so the consumer spawns a session to action it.
+  // nightly-cost-reconcile: three-way spend reconcile vs the Admin Cost API
+  // (fails open with no fetchImpl); flags drift > 10%. Inline, no prompt.
+  { id: "nightly-cost-reconcile", scope: "standard", mode: "inline", calendar: { hour: 3, minute: 30 } },
+  // fleet-cost-digest: build the daily fleet LLM-spend digest. Inline, no prompt.
+  { id: "fleet-cost-digest", scope: "standard", mode: "inline", calendar: { hour: 7, minute: 0 } },
+  // org-cost-sync: push today's router ledger rows to Cohort cost.report
+  // (no-op / fail-open when org.cohort is disabled). Inline, hourly, no prompt.
+  { id: "org-cost-sync", scope: "standard", mode: "inline", interval: 3600 },
+  // monitoring-alerts: evaluate + emit behavioral alerts every 5min. Inline, no prompt.
+  { id: "monitoring-alerts", scope: "standard", mode: "inline", interval: 300 },
+  // dynamic-jobs: action agent-created one-off / recurring reminders. Guarded —
+  // the guard escalates only when dueJobs() returns work; otherwise inline.
+  { id: "dynamic-jobs", scope: "standard", mode: "guarded", interval: 60, prompt: "schedules/triggers/dynamic-jobs.md" },
+  // messaging-inbound (SP10): pull Cohort org messages/@mentions/call-invites
+  // directed at this agent into the inbox pipeline. Guarded — routes inline (the
+  // reactive daemon owns dispatch); escalate-when-items with
+  // MESSAGING_INBOUND_ESCALATE=1. Fail-open / no-op when org messaging disabled.
+  { id: "messaging-inbound", scope: "standard", mode: "guarded", interval: 45, prompt: "schedules/triggers/messaging-inbound.md" },
+  // directory-hygiene (2026-07): keep the Directory clean — propose captures
+  // from signatures/rosters/bank feeds, enrich channels, re-verify anything
+  // unseen for >90d, flag duplicates. Guarded: the cheap pre-check reads the two
+  // review queues and escalates only when one has work, so an idle org costs two
+  // GETs a day and no LLM. PROPOSE-ONLY — merges, awareness changes and archives
+  // are human-gated server-side, so the cadence cannot mutate a record.
+  { id: "directory-hygiene", scope: "standard", mode: "guarded", calendar: { hour: 5, minute: 0 }, prompt: "schedules/triggers/directory-hygiene.md" },
+  // brand-steward (2026-07): a brand foundation save is what makes rendered
+  // imagery and templates stale, so this is EVENT-driven, not report-driven —
+  // the guard tails the org event chain for branding version.saved and escalates
+  // only on a real save. 15min keeps the reaction prompt without polling hard.
+  { id: "brand-steward", scope: "standard", mode: "guarded", interval: 900, prompt: "schedules/triggers/brand-steward.md" },
+];
+
+/** Altitude-specific cadences (reuse existing triggers where one exists). */
+export const ALTITUDE_CADENCES = {
+  founder: [
+    { id: "weekly-runway-review", cadence: "weekly", purpose: "Review runway, burn, and capital position" },
+    { id: "monthly-investor-update", cadence: "monthly", purpose: "Draft the monthly investor update" },
+  ],
+  "c-suite": [
+    { id: "weekly-strategic-memo", cadence: "weekly", purpose: "Weekly strategic memo for the principal/board", prompt: "schedules/triggers/weekly-strategic-memo.md" },
+    { id: "monthly-board-readiness", cadence: "monthly", purpose: "Maintain board-readiness materials" },
+  ],
+  svp: [
+    { id: "weekly-strategic-memo", cadence: "weekly", purpose: "Weekly strategic memo", prompt: "schedules/triggers/weekly-strategic-memo.md" },
+  ],
+  vp: [
+    { id: "weekly-priorities", cadence: "weekly", purpose: "Weekly priorities review", prompt: "schedules/triggers/weekly-priorities.md" },
+  ],
+  "senior-manager": [
+    { id: "weekly-execution", cadence: "weekly", purpose: "Weekly execution review", prompt: "schedules/triggers/weekly-execution.md" },
+  ],
+};
+
+/** Cadence keywords that map to a recurring schedule (event-driven is excluded). */
+export const RECURRING = new Set(["daily", "weekly", "monthly", "quarterly", "continuous"]);
+
+/** Stable non-negative slot from a string id (deterministic stagger). */
+function slotOf(id) {
+  let h = 0;
+  for (let i = 0; i < id.length; i++) h = (h * 31 + id.charCodeAt(i)) >>> 0;
+  return h;
+}
+
+/**
+ * Deterministic, staggered launchd schedule for a cadence keyword.
+ * @param {string} cadence @param {string} id @returns {object} { interval } | { calendar }
+ */
+export function scheduleFor(cadence, id) {
+  const s = slotOf(id);
+  switch (cadence) {
+    case "continuous": return { interval: 600 };
+    case "daily": return { calendar: { hour: 8 + (s % 9), minute: (s % 2) * 30 } };
+    case "weekly": return { calendar: { weekday: 1 + (s % 5), hour: 9 + (s % 7), minute: (s % 2) * 30 } };
+    case "monthly": return { calendar: { day: 1 + (s % 5), hour: 9 + (s % 6), minute: 0 } };
+    case "quarterly": return { calendar: { day: 1, hour: 9 + (s % 6), minute: 0 } }; // handler guards to quarter
+    default: return { interval: 3600 };
+  }
+}
+
+/** Months (1-12) that open a calendar quarter — Jan, Apr, Jul, Oct. */
+const QUARTER_START_MONTHS = new Set([1, 4, 7, 10]);
+
+/**
+ * Quarter guard for a cadence that fires monthly (Day=1) but is logically
+ * quarterly. The `quarterly-self-assessment` plist fires on the 1st of EVERY
+ * month; this returns true only in the first month of each quarter so the
+ * handler/trigger can no-op the other 8 ticks instead of delivering a
+ * "quarterly" report 12×/year. Pure + deterministic (caller supplies the date).
+ *
+ * @param {Date} [now] @returns {boolean}
+ */
+export function isQuarterStartMonth(now = new Date()) {
+  return QUARTER_START_MONTHS.has(now.getMonth() + 1); // getMonth() is 0-based
+}
+
+/**
+ * Eligibility guard for a cadence tick. For the quarterly self-assessment
+ * (which is scheduled monthly so an outage spanning a quarter boundary still
+ * fires) a tick is only due in a quarter-start month. All other cadences are
+ * always due here (their own guard/handler decides finer-grained eligibility).
+ *
+ * @param {string} cadenceId @param {Date} [now] @returns {boolean}
+ */
+export function isCadenceDue(cadenceId, now = new Date()) {
+  if (cadenceId === "quarterly-self-assessment") return isQuarterStartMonth(now);
+  return true;
+}
+
+function normalize(entry, scope) {
+  const out = { id: entry.id, scope, mode: entry.mode || "escalate", prompt: entry.prompt || `schedules/triggers/${entry.id}.md` };
+  if (entry.interval != null) out.interval = entry.interval;
+  else if (entry.calendar) out.calendar = entry.calendar;
+  else {
+    const sch = scheduleFor(entry.cadence, entry.id);
+    Object.assign(out, sch);
+  }
+  if (entry.purpose) out.purpose = entry.purpose;
+  if (entry.cadence) out.cadence = entry.cadence;
+  return out;
+}
+
+/**
+ * Resolve the full cadence set for a { function, altitude }.
+ * @param {{function:string, altitude:string}} sel
+ * @returns {Promise<object[]>} ordered, de-duplicated cadence entries
+ */
+export async function resolveCadences(sel = {}) {
+  const { function: fn, altitude } = sel;
+  if (!fn || !altitude) throw new Error("resolveCadences: requires { function, altitude }");
+
+  const out = [];
+  const seen = new Set();
+  const add = (entry, scope) => {
+    if (!entry || !entry.id || seen.has(entry.id)) return;
+    seen.add(entry.id);
+    out.push(normalize(entry, scope));
+  };
+
+  for (const c of STANDARD_CADENCES) add(c, "standard");
+
+  // Function cadences = the capability pack's recurring workflows.
+  try {
+    const pack = await loadCapabilityPack(fn);
+    for (const wf of pack.workflows || []) {
+      if (RECURRING.has(wf.cadence)) add(wf, "function");
+    }
+  } catch { /* no capability pack for this function — standard + altitude only */ }
+
+  for (const c of ALTITUDE_CADENCES[altitude] || []) add(c, "altitude");
+
+  return out;
+}
+
+/** All function ids that can resolve a cadence set. @returns {string[]} */
+export function listCadenceFunctions() {
+  return listCapabilityFunctions();
+}

package/lib/cadences.test.mjs

@@ -0,0 +1,125 @@
+/**
+ * cadences.test.mjs — tests for the archetype cadence resolver.
+ * Run: `node --test lib/cadences.test.mjs`
+ * @module cadences.test
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { resolveCadences, scheduleFor, STANDARD_CADENCES, RECURRING, isQuarterStartMonth, isCadenceDue } from "./cadences.mjs";
+
+function hasSchedule(c) {
+  return typeof c.interval === "number" || (c.calendar && typeof c.calendar === "object");
+}
+
+test("resolveCadences = standard ⊕ function recurring workflows ⊕ altitude cadences", async () => {
+  const cads = await resolveCadences({ function: "technical-leader", altitude: "c-suite" });
+  const ids = cads.map((c) => c.id);
+  // standard present
+  assert.ok(ids.includes("inbox-processor") && ids.includes("daily-morning-brief"));
+  // a function recurring cadence (from the technical-leader capability workflows)
+  assert.ok(ids.includes("engineering-health"), `expected a function cadence; got ${ids.join(",")}`);
+  // altitude cadence (c-suite → strategic memo)
+  assert.ok(ids.includes("weekly-strategic-memo"));
+  // every entry has a concrete schedule + unique ids
+  assert.ok(cads.every(hasSchedule), "every cadence has interval or calendar");
+  assert.equal(ids.length, new Set(ids).size, "no duplicate cadence ids");
+});
+
+test("event-driven workflows are excluded from cadences (pr-review is not scheduled)", async () => {
+  const cads = await resolveCadences({ function: "technical-leader", altitude: "vp" });
+  assert.ok(!cads.some((c) => c.id === "pr-review"), "event-driven pr-review must not be a scheduled cadence");
+});
+
+test("altitude changes the cadence set (c-suite memo vs senior-manager execution review)", async () => {
+  const cSuite = (await resolveCadences({ function: "operations-leader", altitude: "c-suite" })).map((c) => c.id);
+  const srMgr = (await resolveCadences({ function: "operations-leader", altitude: "senior-manager" })).map((c) => c.id);
+  assert.ok(cSuite.includes("weekly-strategic-memo"));
+  assert.ok(srMgr.includes("weekly-execution"));
+  assert.notDeepEqual(cSuite, srMgr);
+});
+
+test("scheduleFor is deterministic and matches the cadence keyword", () => {
+  assert.deepEqual(scheduleFor("weekly", "x"), scheduleFor("weekly", "x"));
+  assert.ok(scheduleFor("continuous", "x").interval);
+  assert.ok(scheduleFor("weekly", "engineering-health").calendar.weekday >= 1);
+  assert.ok(RECURRING.has("weekly") && !RECURRING.has("event-driven"));
+});
+
+test("resolveCadences requires { function, altitude }", async () => {
+  await assert.rejects(() => resolveCadences({}), /requires/);
+});
+
+test("quarter guard: quarterly cadence is due in Jan/Apr/Jul/Oct, not other months", () => {
+  // The plist fires Day=1 of every month; the guard restricts it to the
+  // quarter-start months so the principal gets 4, not 12, reports/year.
+  const due = [1, 4, 7, 10];
+  for (let month = 1; month <= 12; month++) {
+    // Day 1 of each month, midday local to dodge any TZ/DST edge.
+    const d = new Date(2026, month - 1, 1, 12, 0, 0);
+    const expected = due.includes(month);
+    assert.equal(isQuarterStartMonth(d), expected, `month ${month}: isQuarterStartMonth`);
+    assert.equal(isCadenceDue("quarterly-self-assessment", d), expected, `month ${month}: quarterly due`);
+  }
+});
+
+test("quarter guard does not constrain non-quarterly cadences", () => {
+  // A daily cadence is due every month — the guard is quarterly-only.
+  for (let month = 1; month <= 12; month++) {
+    const d = new Date(2026, month - 1, 1, 12, 0, 0);
+    assert.equal(isCadenceDue("daily-morning-brief", d), true, `month ${month}: daily always due`);
+    assert.equal(isCadenceDue("org-pulse", d), true, `month ${month}: org-pulse always due`);
+  }
+});
+
+test("STANDARD_CADENCES all carry a schedule; escalating ones carry a prompt", () => {
+  assert.ok(STANDARD_CADENCES.length >= 8);
+  // Every standard cadence is scheduled.
+  assert.ok(STANDARD_CADENCES.every((c) => hasSchedule(c)));
+  // Cadences that spawn a sub-session must carry a prompt; a guarded-inline
+  // cadence (e.g. skill-curator) legitimately has none — the daemon handles it
+  // in-process and never escalates.
+  assert.ok(STANDARD_CADENCES.filter((c) => c.mode === "escalate").every((c) => c.prompt));
+});
+
+test("economics/scheduling cadences are wired into STANDARD_CADENCES with the right mode + schedule", () => {
+  const byId = Object.fromEntries(STANDARD_CADENCES.map((c) => [c.id, c]));
+  // Deterministic economics cadences run inline (no LLM).
+  for (const id of ["nightly-cost-reconcile", "fleet-cost-digest", "org-cost-sync"]) {
+    assert.ok(byId[id], `${id} present in STANDARD_CADENCES`);
+    assert.equal(byId[id].mode, "inline", `${id} is inline (deterministic)`);
+    assert.ok(hasSchedule(byId[id]), `${id} has a schedule`);
+  }
+  // Calendar-pinned: nightly-cost-reconcile ~3:30am, fleet-cost-digest ~7am.
+  assert.deepEqual(byId["nightly-cost-reconcile"].calendar, { hour: 3, minute: 30 });
+  assert.deepEqual(byId["fleet-cost-digest"].calendar, { hour: 7, minute: 0 });
+  // org-cost-sync is an hourly interval.
+  assert.equal(byId["org-cost-sync"].interval, 3600);
+  // dynamic-jobs is the only GUARDED economics cadence (escalate-when-due) and a
+  // ~60s interval; because it can escalate it must carry a prompt.
+  assert.ok(byId["dynamic-jobs"], "dynamic-jobs present");
+  assert.equal(byId["dynamic-jobs"].mode, "guarded");
+  assert.equal(byId["dynamic-jobs"].interval, 60);
+  assert.ok(byId["dynamic-jobs"].prompt, "guarded dynamic-jobs carries an escalate prompt");
+});
+
+test("economics/scheduling cadences resolve into every agent's cadence set", async () => {
+  const ids = (await resolveCadences({ function: "operations-leader", altitude: "vp" })).map((c) => c.id);
+  for (const id of ["nightly-cost-reconcile", "fleet-cost-digest", "org-cost-sync", "dynamic-jobs"]) {
+    assert.ok(ids.includes(id), `${id} resolves into the standard cadence set`);
+  }
+});
+
+test("every STANDARD_CADENCES entry that declares a prompt has the file on disk", async () => {
+  // A guarded/escalate cadence whose prompt file is missing would DLQ at escalate
+  // time (regression guard for the dynamic-jobs.md gap).
+  const { existsSync } = await import("node:fs");
+  const { resolve, join } = await import("node:path");
+  const { fileURLToPath } = await import("node:url");
+  const root = resolve(fileURLToPath(new URL(".", import.meta.url)), "..");
+  for (const c of STANDARD_CADENCES.filter((x) => x.prompt)) {
+    assert.ok(existsSync(join(root, c.prompt)), `cadence ${c.id} prompt missing: ${c.prompt}`);
+  }
+});

package/lib/capability.mjs

@@ -0,0 +1,154 @@
+/**
+ * capability.mjs — resolve an archetype's CAPABILITY SURFACE.
+ *
+ * The init wizard generates a deep, ready-to-act agent: not just a charter and a
+ * backlog, but the agent's whole capability surface — the sub-agent org, the
+ * Claude Code skills, the workflows, the MCP servers/plugins, and the
+ * event→capability routing. This module resolves that surface from:
+ *
+ *   STANDARD defaults (every agent gets these generic infrastructure sub-agents)
+ *   ⊕ the function's capability pack (archetypes/capabilities/<function>.yaml:
+ *     agentTeams, skills, workflows, mcpServers)
+ *   ⊕ altitude breadth scaling (profile.delegationBreadth):
+ *       broad    → all teams, all tiers (lead+core+support) — the full 40–60 roster
+ *       moderate → all teams, drop the support tier
+ *       narrow   → core teams only, drop the support tier
+ *       none     → standard defaults only
+ *
+ * Generators (scripts/setup/generate-capability.mjs) render concrete agent.md /
+ * skills / workflows / config/event-routing.yaml from this surface; the wizard
+ * LLM-tailors each to the company context.
+ *
+ * Pure-ish (reads the capability YAML + resolves the profile for breadth). ESM.
+ *
+ * @module capability
+ */
+
+"use strict";
+
+import { readFileSync, existsSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { ARCHETYPES_DIR, resolveArchetype } from "./archetype.mjs";
+
+/** Directory of per-function capability packs. */
+export const CAPABILITIES_DIR = path.join(ARCHETYPES_DIR, "capabilities");
+
+/**
+ * The generic infrastructure sub-agents EVERY maestro agent gets, regardless of
+ * archetype. (Curated from agents/; these are role-agnostic plumbing.)
+ * @type {Array<{ id: string, role: string, purpose: string }>}
+ */
+export const STANDARD_DEFAULT_AGENTS = [
+  { id: "inbound-dispatcher", role: "Inbound Dispatcher", purpose: "Classify and route every inbound event to the right handler." },
+  { id: "inbox-processor", role: "Inbox Processor", purpose: "Triage Slack/email/calendar/SMS inbox items into actions and queues." },
+  { id: "session-spawner", role: "Session Spawner", purpose: "Spawn and supervise managed sub-sessions for delegated work." },
+  { id: "workflow-automation", role: "Workflow Automation", purpose: "Run scheduled and event-driven workflows end-to-end." },
+  { id: "communications", role: "Communications", purpose: "Draft and send messages in the agent's voice across channels." },
+  { id: "calendar-ops", role: "Calendar Ops", purpose: "Manage scheduling, meeting prep, and calendar hygiene." },
+  { id: "decision-log", role: "Decision Log", purpose: "Capture decisions with context, options, and rationale." },
+  { id: "pmo-execution", role: "PMO / Execution", purpose: "Drive the backlog: select, dispatch, and close work items." },
+  { id: "slack-operator", role: "Slack Operator", purpose: "Read/send Slack via the agent's own identity." },
+  { id: "gmail-operator", role: "Gmail Operator", purpose: "Read/send email via IMAP/SMTP under the agent's identity." },
+  { id: "whatsapp-operator", role: "WhatsApp Operator", purpose: "Read/send WhatsApp messages." },
+  { id: "browser-operator", role: "Browser Operator", purpose: "Drive web UIs that lack an API, via the browser." },
+  { id: "desktop-operator", role: "Desktop Operator", purpose: "Drive native macOS apps via accessibility/automation." },
+];
+
+/** Valid breadth values (from altitude profile.delegationBreadth). */
+export const BREADTHS = ["broad", "moderate", "narrow", "none"];
+
+let _yaml = null;
+async function getYaml() {
+  if (_yaml) return _yaml;
+  const mod = await import("js-yaml");
+  _yaml = mod && mod.default ? mod.default : mod;
+  return _yaml;
+}
+
+/** Functions that have a capability pack on disk. @returns {string[]} */
+export function listCapabilityFunctions() {
+  if (!existsSync(CAPABILITIES_DIR)) return [];
+  return readdirSync(CAPABILITIES_DIR).filter((f) => f.endsWith(".yaml")).map((f) => f.slice(0, -5)).sort();
+}
+
+/** Load a function's capability pack. @param {string} fn @returns {Promise<object>} */
+export async function loadCapabilityPack(fn) {
+  const file = path.join(CAPABILITIES_DIR, `${fn}.yaml`);
+  if (!existsSync(file)) throw new Error(`capability pack not found for function "${fn}" (${file})`);
+  const yaml = await getYaml();
+  const pack = yaml.load(readFileSync(file, "utf8")) || {};
+  return {
+    mcpServers: pack.mcpServers || [],
+    skills: pack.skills || [],
+    workflows: pack.workflows || [],
+    agentTeams: pack.agentTeams || [],
+  };
+}
+
+/**
+ * Filter the team/agent catalogue by altitude breadth. Pure.
+ * @param {object[]} teams @param {string} breadth @returns {object[]}
+ */
+export function filterTeamsByBreadth(teams, breadth) {
+  if (breadth === "none") return [];
+  const coreOnly = breadth === "narrow";
+  const dropSupport = breadth === "narrow" || breadth === "moderate";
+  return (teams || [])
+    .filter((t) => (coreOnly ? t.core === true : true))
+    .map((t) => ({
+      ...t,
+      agents: (t.agents || []).filter((a) => (dropSupport ? a.tier !== "support" : true)),
+    }))
+    .filter((t) => t.agents.length > 0);
+}
+
+/**
+ * Resolve the full capability surface for a { function, altitude }.
+ * @param {{function:string, altitude:string}} sel
+ * @returns {Promise<object>} the capability surface
+ */
+export async function resolveCapabilitySurface(sel = {}) {
+  const profile = await resolveArchetype(sel); // validates + gives delegationBreadth
+  const breadth = BREADTHS.includes(profile.delegationBreadth) ? profile.delegationBreadth : "moderate";
+  const pack = await loadCapabilityPack(sel.function);
+  const teams = filterTeamsByBreadth(pack.agentTeams, breadth);
+  const roleAgents = teams.flatMap((t) => (t.agents || []).map((a) => ({ ...a, team: t.id })));
+
+  return {
+    function: sel.function,
+    altitude: sel.altitude,
+    breadth,
+    standardAgents: STANDARD_DEFAULT_AGENTS,
+    teams,
+    roleAgents,
+    skills: pack.skills,
+    workflows: pack.workflows,
+    mcpServers: pack.mcpServers,
+    counts: {
+      standard: STANDARD_DEFAULT_AGENTS.length,
+      role: roleAgents.length,
+      total: STANDARD_DEFAULT_AGENTS.length + roleAgents.length,
+    },
+  };
+}
+
+/**
+ * Build a starter event→capability routing table from a resolved surface.
+ * The wizard enriches it; this gives sensible defaults so the daemon can route.
+ * @param {object} surface @returns {{ routes: Array<{event:string, handler:string, via:string}> }}
+ */
+export function buildEventRouting(surface) {
+  const routes = [
+    { event: "inbound.message", handler: "inbound-dispatcher", via: "standard-agent" },
+    { event: "inbound.email", handler: "inbox-processor", via: "standard-agent" },
+    { event: "decision.made", handler: "decision-log", via: "standard-agent" },
+    { event: "backlog.tick", handler: "pmo-execution", via: "standard-agent" },
+  ];
+  for (const w of surface.workflows || []) {
+    routes.push({ event: w.cadence === "event-driven" ? `event.${w.id}` : `cadence.${w.cadence}.${w.id}`, handler: w.id, via: "workflow" });
+  }
+  for (const s of surface.skills || []) {
+    routes.push({ event: `request.${s.id}`, handler: s.id, via: "skill" });
+  }
+  return { routes };
+}

package/lib/capability.test.mjs

@@ -0,0 +1,78 @@
+/**
+ * capability.test.mjs — tests for the capability-surface resolver.
+ * Run: `node --test lib/capability.test.mjs`
+ * @module capability.test
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  resolveCapabilitySurface,
+  loadCapabilityPack,
+  filterTeamsByBreadth,
+  buildEventRouting,
+  listCapabilityFunctions,
+  STANDARD_DEFAULT_AGENTS,
+} from "./capability.mjs";
+
+const TEAMS = [
+  { id: "a", core: true, agents: [{ id: "a1", tier: "lead" }, { id: "a2", tier: "core" }, { id: "a3", tier: "support" }] },
+  { id: "b", core: false, agents: [{ id: "b1", tier: "lead" }, { id: "b2", tier: "support" }] },
+];
+
+test("filterTeamsByBreadth: breadth scales the roster deterministically", () => {
+  const count = (b) => filterTeamsByBreadth(TEAMS, b).flatMap((t) => t.agents).length;
+  assert.equal(count("broad"), 5); // both teams, all tiers
+  assert.equal(count("moderate"), 3); // both teams, drop support (a: lead+core, b: lead)
+  assert.equal(count("narrow"), 2); // core team only (a), drop support
+  assert.equal(count("none"), 0);
+});
+
+test("technical-leader capability pack loads with mcp/skills/workflows/teams", async () => {
+  assert.ok(listCapabilityFunctions().includes("technical-leader"));
+  const pack = await loadCapabilityPack("technical-leader");
+  assert.ok(pack.mcpServers.length >= 1);
+  assert.ok(pack.skills.length >= 1);
+  assert.ok(pack.workflows.length >= 1);
+  assert.ok(pack.agentTeams.length >= 3);
+});
+
+test("resolveCapabilitySurface composes standard defaults + altitude-scaled role agents", async () => {
+  const s = await resolveCapabilitySurface({ function: "technical-leader", altitude: "c-suite" });
+  assert.equal(s.standardAgents.length, STANDARD_DEFAULT_AGENTS.length);
+  assert.ok(s.roleAgents.length > 0);
+  assert.equal(s.counts.total, s.counts.standard + s.counts.role);
+  assert.ok(s.mcpServers.length >= 1);
+  assert.ok(s.roleAgents.every((a) => a.id && a.role && a.team), "role agents carry id/role/team");
+});
+
+test("altitude scales breadth: c-suite ≥ vp ≥ senior-manager role-agent count", async () => {
+  const c = await resolveCapabilitySurface({ function: "technical-leader", altitude: "c-suite" });
+  const v = await resolveCapabilitySurface({ function: "technical-leader", altitude: "vp" });
+  const m = await resolveCapabilitySurface({ function: "technical-leader", altitude: "senior-manager" });
+  assert.ok(c.counts.role >= v.counts.role, `c-suite(${c.counts.role}) ≥ vp(${v.counts.role})`);
+  assert.ok(v.counts.role >= m.counts.role, `vp(${v.counts.role}) ≥ senior-manager(${m.counts.role})`);
+});
+
+test("buildEventRouting maps standard, workflow, and skill handlers", async () => {
+  const s = await resolveCapabilitySurface({ function: "technical-leader", altitude: "vp" });
+  const { routes } = buildEventRouting(s);
+  assert.ok(routes.some((r) => r.via === "standard-agent"));
+  assert.ok(routes.some((r) => r.via === "workflow"));
+  assert.ok(routes.some((r) => r.via === "skill"));
+});
+
+test("every function pack resolves to a 40–60 role roster at broad altitude, with unique ids + mcp/skills/workflows", async () => {
+  const fns = listCapabilityFunctions();
+  assert.ok(fns.length >= 6, `expected ≥6 capability packs, got ${fns.length}`);
+  for (const fn of fns) {
+    const pack = await loadCapabilityPack(fn);
+    const ids = pack.agentTeams.flatMap((t) => t.agents.map((a) => a.id));
+    assert.equal(ids.length, new Set(ids).size, `${fn}: duplicate agent ids`);
+    assert.ok(pack.mcpServers.length >= 1 && pack.skills.length >= 1 && pack.workflows.length >= 1, `${fn}: missing mcp/skills/workflows`);
+    const broad = await resolveCapabilitySurface({ function: fn, altitude: "founder" }); // founder ⇒ broad
+    assert.ok(broad.counts.role >= 40 && broad.counts.role <= 60, `${fn}: broad role count ${broad.counts.role} not in 40–60`);
+  }
+});