@cohortapp/agent-sdk 2.3.0

package/lib/setup/sections/learning.test.mjs

@@ -0,0 +1,81 @@
+/**
+ * learning.test.mjs — WS3 setup section (order 80) tests.
+ * Run: node --test lib/setup/sections/learning.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, existsSync, readFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import learning from "./learning.mjs";
+import * as io from "../io.mjs";
+
+const MAESTRO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+
+function tmpRoot() {
+  const root = mkdtempSync(join(tmpdir(), "maestro-learnsec-"));
+  mkdirSync(join(root, "config"), { recursive: true });
+  return root;
+}
+function ctxFor(root, answers = {}) {
+  return { agentRoot: root, maestroRoot: MAESTRO_ROOT, flags: { headless: true }, answers, io };
+}
+
+test("section shape: id/order/hooks", () => {
+  assert.equal(learning.id, "learning");
+  assert.equal(learning.order, 80);
+  for (const h of ["detect", "prompt", "apply", "verify"]) assert.equal(typeof learning[h], "function");
+});
+
+test("detect: unconfigured before apply, complete after", async () => {
+  const root = tmpRoot();
+  const before = await learning.detect(ctxFor(root));
+  assert.equal(before.status, "unconfigured");
+
+  await learning.apply(ctxFor(root, { learningEnabled: true }));
+  // config + counters now exist; hook is NOT wired on a CI machine → partial.
+  const after = await learning.detect(ctxFor(root));
+  assert.ok(["complete", "partial"].includes(after.status));
+  assert.ok(existsSync(join(root, "config", "learning.yaml")));
+  assert.ok(existsSync(join(root, "state", "learning", "counters.json")));
+  // Counters seeded to zero state.
+  const c = JSON.parse(readFileSync(join(root, "state", "learning", "counters.json"), "utf8"));
+  assert.equal(c.tool_uses_since_skill, 0);
+});
+
+test("apply: disabled choice writes enabled:false and skips seeding", async () => {
+  const root = tmpRoot();
+  await learning.apply(ctxFor(root, { learningEnabled: false }));
+  const body = readFileSync(join(root, "config", "learning.yaml"), "utf8");
+  assert.match(body, /enabled:\s*false/);
+  assert.ok(!existsSync(join(root, "state", "learning", "counters.json")), "no counters when disabled");
+  const det = await learning.detect(ctxFor(root));
+  assert.equal(det.status, "complete");
+  assert.match(det.summary, /disabled/);
+});
+
+test("verify: config + counters checks; hook is a soft (non-failing) check", async () => {
+  const root = tmpRoot();
+  await learning.apply(ctxFor(root, { learningEnabled: true }));
+  const v = await learning.verify(ctxFor(root));
+  const names = v.checks.map((c) => c.name);
+  assert.ok(names.some((n) => /config\/learning\.yaml/.test(n)));
+  assert.ok(names.some((n) => /counters seeded/.test(n)));
+  // The hook check never hard-fails verify (so CI / fresh repos stay green).
+  const hookCheck = v.checks.find((c) => /Stop-hook/.test(c.name));
+  assert.equal(hookCheck.ok, true);
+  assert.equal(v.ok, true);
+});
+
+test("apply: idempotent — re-apply does not clobber an existing config", async () => {
+  const root = tmpRoot();
+  // Operator hand-customised config.
+  writeFileSync(join(root, "config", "learning.yaml"), "enabled: true\nminTurns: 9\n# custom\n");
+  await learning.apply(ctxFor(root, { learningEnabled: true }));
+  const body = readFileSync(join(root, "config", "learning.yaml"), "utf8");
+  assert.match(body, /minTurns: 9/, "existing customisation preserved");
+});

package/lib/setup/sections/messaging.mjs

@@ -0,0 +1,219 @@
+/**
+ * sections/messaging.mjs — org messaging + calling enablement (order 76).
+ *
+ * SP10 wiring step: makes an agent PARTICIPATE in the org's own human messaging
+ * app (post / @mention / react / call ON Cohort). It is a thin follow-on to the
+ * org-enrollment section (order 75): it does NOT re-capture the server URL or
+ * token (that's org.mjs's job) — it confirms enrollment is present, ensures the
+ * messaging.read / messaging.write / calling.write scopes are recorded in the
+ * agent's GRANTED scope set, and optionally captures the agent's "home" channels
+ * (the channels it watches + posts into by default), writing all of it to
+ * config/org.yaml under `org.cohort.{scopes,messaging.homeChannels}`.
+ *
+ * Order 76 sits immediately after org (75) and before the WS4 recovery/85 +
+ * verify/90 gate, so messaging enablement lands once the org endpoint+token are
+ * known but is still verified before the final gate.
+ *
+ * Non-blocking by contract: detect/apply/verify NEVER read the TTY (so doctor /
+ * CI / --headless call them directly); only prompt() touches the TTY. apply() is
+ * idempotent and ADDITIVE — it merges the messaging scopes into whatever scope
+ * set is already configured (never clobbering operator-set fields) and never
+ * writes anything destructive. verify() best-effort pings messaging.channels and
+ * WARNs (never hard-fails) when the org is disabled / unreachable — messaging is
+ * fail-open at runtime.
+ *
+ * @module lib/setup/sections/messaging
+ */
+
+"use strict";
+
+import { join } from "node:path";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import * as io from "../io.mjs";
+import { isEnabled, configFromAgent } from "../../org/client.mjs";
+import { listChannels } from "../../org/messaging.mjs";
+
+const CONFIG_REL = join("config", "org.yaml");
+
+/** The scopes this section guarantees are present in the granted set. */
+export const MESSAGING_SCOPES = Object.freeze(["messaging.read", "messaging.write", "calling.write"]);
+
+/** Lazily load js-yaml (a maestro dep) the same way the lib/org modules do. */
+async function loadYaml() {
+  const m = await import("js-yaml");
+  return m && m.default ? m.default : m;
+}
+
+/**
+ * Read config/org.yaml into a plain object. Returns {} when absent/unreadable so
+ * callers can null-check uniformly. Never throws.
+ * @param {string} agentRoot
+ * @returns {Promise<object>}
+ */
+export async function readOrgConfig(agentRoot) {
+  const p = join(agentRoot, CONFIG_REL);
+  if (!existsSync(p)) return {};
+  try {
+    const yaml = await loadYaml();
+    const doc = yaml.load(readFileSync(p, "utf8"));
+    return doc && typeof doc === "object" ? doc : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Merge the messaging/calling scopes (and optional home channels) into the
+ * org.cohort block, preserving everything else. ADDITIVE on scopes — the merged
+ * set is the union of any existing `scopes` plus MESSAGING_SCOPES, de-duplicated
+ * and stable-sorted so the write is idempotent. Pure.
+ *
+ * @param {object} existing parsed config/org.yaml ({} when none)
+ * @param {{homeChannels?:string[]}} ans
+ * @returns {object} the merged config object to serialise
+ */
+export function buildMessagingConfig(existing, ans = {}) {
+  const prevOrg = (existing && existing.org) || {};
+  const prev = prevOrg.cohort || {};
+  const cohort = { ...prev };
+
+  // Union the granted scopes with the messaging ones; de-dupe; stable-sort.
+  const prevScopes = Array.isArray(prev.scopes) ? prev.scopes.map(String) : [];
+  const merged = Array.from(new Set([...prevScopes, ...MESSAGING_SCOPES]));
+  merged.sort();
+  cohort.scopes = merged;
+
+  // Optional home channels — merge into the existing messaging block.
+  const home = Array.isArray(ans.homeChannels)
+    ? ans.homeChannels.map((s) => String(s).trim()).filter(Boolean)
+    : [];
+  const prevMsg = (prev.messaging && typeof prev.messaging === "object") ? prev.messaging : {};
+  if (home.length || (Array.isArray(prevMsg.homeChannels) && prevMsg.homeChannels.length)) {
+    const prevHome = Array.isArray(prevMsg.homeChannels) ? prevMsg.homeChannels.map(String) : [];
+    const mergedHome = Array.from(new Set([...prevHome, ...home]));
+    cohort.messaging = { ...prevMsg, homeChannels: mergedHome };
+  } else if (Object.keys(prevMsg).length) {
+    cohort.messaging = prevMsg;
+  }
+
+  return { ...(existing || {}), org: { ...prevOrg, cohort } };
+}
+
+/** Resolve the answers bag (answers → env, via io defaults). */
+function resolvedAnswers(ctx) {
+  const a = (ctx && ctx.answers) || {};
+  let home = a.homeChannels;
+  if (home == null && process.env.COHORT_HOME_CHANNELS) home = process.env.COHORT_HOME_CHANNELS;
+  if (typeof home === "string") {
+    home = home.split(",").map((s) => s.trim()).filter(Boolean);
+  }
+  return { homeChannels: Array.isArray(home) ? home : [] };
+}
+
+/** Do the configured granted scopes already cover all messaging scopes? */
+function hasAllMessagingScopes(cfg) {
+  const scopes = (cfg && cfg.org && cfg.org.cohort && cfg.org.cohort.scopes) || [];
+  if (!Array.isArray(scopes)) return false;
+  const set = new Set(scopes.map(String));
+  return MESSAGING_SCOPES.every((s) => set.has(s));
+}
+
+export default {
+  id: "messaging",
+  label: "Org messaging + calling",
+  order: 76,
+
+  async detect(ctx) {
+    const cfgPath = join(ctx.agentRoot, CONFIG_REL);
+    if (!existsSync(cfgPath)) {
+      // Org section hasn't run yet — messaging can't be enabled without org.
+      return { status: "unconfigured", missing: ["config/org.yaml (run the org section first)"] };
+    }
+    const cfg = await readOrgConfig(ctx.agentRoot);
+    if (!isEnabled(cfg)) {
+      return { status: "partial", summary: "org not enrolled — messaging is dormant", missing: ["org.cohort enabled (base + token)"] };
+    }
+    if (hasAllMessagingScopes(cfg)) {
+      return { status: "complete", summary: "messaging + calling scopes granted" };
+    }
+    return { status: "partial", summary: "org enrolled but messaging scopes not yet recorded", missing: ["org.cohort.scopes: messaging.read/write + calling.write"] };
+  },
+
+  async prompt(ctx) {
+    io.note("Let this agent post / @mention / call ON the org messaging app (Cohort). Requires org enrollment (previous step).", { dim: true });
+    // Home channels are OPTIONAL — comma-separated channel ids the agent watches
+    // and posts into by default. Blank = no default channels (it still receives
+    // @mentions and DMs).
+    const home = await io.text(ctx, {
+      message: "Home channel id(s) the agent watches/posts into (comma-separated, optional)",
+      key: "homeChannels",
+      env: "COHORT_HOME_CHANNELS",
+      default: "",
+    });
+    ctx.answers.homeChannels = home
+      ? String(home).split(",").map((s) => s.trim()).filter(Boolean)
+      : [];
+  },
+
+  async apply(ctx) {
+    const ans = resolvedAnswers(ctx);
+    const existing = await readOrgConfig(ctx.agentRoot);
+
+    // If org.yaml doesn't exist yet, do NOTHING destructive — the org section
+    // owns creating it. We still write the messaging scope set onto whatever is
+    // there so a later org enable inherits it; if there is genuinely no config
+    // we write a minimal stub carrying just the scopes so detect/verify have a
+    // stable artefact (matches the org section's disabled-stub behaviour).
+    const next = buildMessagingConfig(existing, ans);
+
+    mkdirSync(join(ctx.agentRoot, "config"), { recursive: true });
+    const yaml = await loadYaml();
+    const header =
+      "# config/org.yaml — Org enrollment + messaging (Cohort).\n" +
+      "# The `org` setup section owns base/token; the `messaging` section adds the\n" +
+      "# messaging.read/write + calling.write scopes and optional home channels so\n" +
+      "# the agent can post / @mention / call on the org messaging app. The SERVER\n" +
+      "# enforces ACL — these scopes are what the agent REQUESTS at pairing time.\n";
+    writeFileSync(join(ctx.agentRoot, CONFIG_REL), header + yaml.dump(next, { lineWidth: 120, sortKeys: false }));
+  },
+
+  async verify(ctx) {
+    const checks = [];
+    const cfgPresent = existsSync(join(ctx.agentRoot, CONFIG_REL));
+    checks.push({ name: "config/org.yaml present", ok: cfgPresent, remedy: cfgPresent ? undefined : "run `maestro setup --only org` then `--only messaging`" });
+
+    const cfg = await readOrgConfig(ctx.agentRoot);
+    const scopesOk = hasAllMessagingScopes(cfg);
+    checks.push({
+      name: "messaging + calling scopes recorded",
+      ok: scopesOk,
+      remedy: scopesOk ? undefined : "run `maestro setup --only messaging` to add messaging.read/write + calling.write to org.cohort.scopes",
+    });
+
+    if (!isEnabled(cfg)) {
+      // Messaging is OPTIONAL and dormant until the org is enrolled — WARN, do
+      // not hard-fail setup (the agent can run standalone).
+      checks.push({ name: "org messaging (dormant — not enrolled)", ok: true, remedy: "enroll the org (set org.cohort.base + token) to activate messaging" });
+      return { ok: checks.every((c) => c.ok), checks };
+    }
+
+    // Best-effort, NON-BLOCKING reachability probe via messaging.channels. The
+    // client is fail-open (transport error → []), so a timeout/unreachable server
+    // just yields an empty list; we never hard-fail on reachability — the runtime
+    // messaging path is itself fail-open.
+    let reachable = false;
+    try {
+      const channels = await listChannels({ cfg, fetchImpl: ctx.fetchImpl });
+      reachable = Array.isArray(channels);
+    } catch {
+      reachable = false;
+    }
+    checks.push({
+      name: reachable ? "Cohort messaging reachable (channels listed)" : "Cohort messaging reachability (best-effort)",
+      ok: true, // never hard-fail — messaging is fail-open at runtime
+      remedy: reachable ? undefined : "could not list org channels — messaging will fail open until the server is up + scopes are granted",
+    });
+
+    return { ok: checks.every((c) => c.ok), checks };
+  },
+};

package/lib/setup/sections/messaging.test.mjs

@@ -0,0 +1,127 @@
+/**
+ * messaging.test.mjs — org messaging+calling setup section (order 76) tests.
+ * Non-blocking (headless ctx), additive scope merge, no destructive writes,
+ * best-effort verify. Run: node --test lib/setup/sections/messaging.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import yaml from "js-yaml";
+
+import messaging, { buildMessagingConfig, readOrgConfig, MESSAGING_SCOPES } from "./messaging.mjs";
+import * as io from "../io.mjs";
+
+const MAESTRO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+
+function tmpRoot() {
+  const root = mkdtempSync(join(tmpdir(), "maestro-msgsec-"));
+  mkdirSync(join(root, "config"), { recursive: true });
+  return root;
+}
+function ctxFor(root, answers = {}) {
+  return { agentRoot: root, maestroRoot: MAESTRO_ROOT, flags: { headless: true }, answers, io };
+}
+function readCfg(root) {
+  return yaml.load(readFileSync(join(root, "config", "org.yaml"), "utf8"));
+}
+function writeOrg(root, cohort) {
+  writeFileSync(join(root, "config", "org.yaml"), yaml.dump({ org: { cohort } }));
+}
+
+test("section shape: id/order=76/hooks; hooks are functions", () => {
+  assert.equal(messaging.id, "messaging");
+  assert.equal(messaging.order, 76);
+  for (const h of ["detect", "prompt", "apply", "verify"]) assert.equal(typeof messaging[h], "function");
+});
+
+test("buildMessagingConfig: ADDITIVE union of existing scopes + messaging scopes, sorted + de-duped", () => {
+  const existing = { org: { cohort: { enabled: true, base: "b", token: "t", scopes: ["org.read", "messaging.read"] } } };
+  const next = buildMessagingConfig(existing, {});
+  const scopes = next.org.cohort.scopes;
+  for (const s of MESSAGING_SCOPES) assert.ok(scopes.includes(s), `${s} present`);
+  assert.ok(scopes.includes("org.read"), "existing scope preserved");
+  // de-duped (messaging.read appeared in both inputs) + sorted (idempotent write)
+  assert.equal(new Set(scopes).size, scopes.length, "no duplicates");
+  assert.deepEqual(scopes, [...scopes].sort(), "stable-sorted");
+  // never drops base/token
+  assert.equal(next.org.cohort.base, "b");
+  assert.equal(next.org.cohort.token, "t");
+});
+
+test("buildMessagingConfig: home channels merge (union) without clobbering", () => {
+  const existing = { org: { cohort: { enabled: true, base: "b", messaging: { homeChannels: ["C1"] } } } };
+  const next = buildMessagingConfig(existing, { homeChannels: ["C2", "C1"] });
+  assert.deepEqual(next.org.cohort.messaging.homeChannels.sort(), ["C1", "C2"]);
+});
+
+test("detect: unconfigured when there is no org.yaml at all", async () => {
+  const root = tmpRoot();
+  const d = await messaging.detect(ctxFor(root));
+  assert.equal(d.status, "unconfigured");
+});
+
+test("detect: partial when org present but not enrolled", async () => {
+  const root = tmpRoot();
+  writeOrg(root, { enabled: false });
+  const d = await messaging.detect(ctxFor(root));
+  assert.equal(d.status, "partial");
+});
+
+test("detect: complete when enrolled AND messaging scopes recorded", async () => {
+  const root = tmpRoot();
+  writeOrg(root, { enabled: true, base: "https://x", token: "t", scopes: [...MESSAGING_SCOPES] });
+  const d = await messaging.detect(ctxFor(root));
+  assert.equal(d.status, "complete");
+});
+
+test("apply: idempotent + additive — records messaging scopes onto an enrolled org without dropping fields", async () => {
+  const root = tmpRoot();
+  writeOrg(root, { enabled: true, base: "https://cohort.example", token: "tok-1", scopes: ["org.read"] });
+  await messaging.apply(ctxFor(root, { homeChannels: ["C-eng"] }));
+  const cfg = readCfg(root);
+  for (const s of MESSAGING_SCOPES) assert.ok(cfg.org.cohort.scopes.includes(s));
+  assert.ok(cfg.org.cohort.scopes.includes("org.read"), "did not clobber existing scope");
+  assert.equal(cfg.org.cohort.base, "https://cohort.example", "did not clobber base");
+  assert.equal(cfg.org.cohort.token, "tok-1", "did not clobber token");
+  assert.deepEqual(cfg.org.cohort.messaging.homeChannels, ["C-eng"]);
+  assert.equal(cfg.org.cohort.enabled, true, "did not flip enabled");
+
+  // Idempotent: a second apply with no new answers leaves the scope set identical.
+  const before = JSON.stringify(readCfg(root).org.cohort.scopes);
+  await messaging.apply(ctxFor(root, {}));
+  assert.equal(JSON.stringify(readCfg(root).org.cohort.scopes), before, "second apply is a no-op on scopes");
+});
+
+test("apply: never blocks — runs under headless ctx with no answers, writes a non-destructive stub", async () => {
+  const root = tmpRoot();
+  // No org.yaml yet — apply must not throw and must not enable anything.
+  await messaging.apply(ctxFor(root, {}));
+  assert.ok(existsSync(join(root, "config", "org.yaml")));
+  const cfg = readCfg(root);
+  // scopes recorded, but enrollment NOT fabricated (no base/token, enabled falsy).
+  for (const s of MESSAGING_SCOPES) assert.ok(cfg.org.cohort.scopes.includes(s));
+  assert.ok(!cfg.org.cohort.enabled, "apply never enables the org by itself");
+});
+
+test("verify: org not enrolled → ok:true (optional/dormant), with scopes-recorded check", async () => {
+  const root = tmpRoot();
+  await messaging.apply(ctxFor(root, {}));
+  const v = await messaging.verify(ctxFor(root));
+  assert.equal(v.ok, true, "dormant messaging never hard-fails setup");
+  assert.ok(v.checks.some((c) => /scopes recorded/.test(c.name) && c.ok));
+});
+
+test("verify: enrolled → best-effort channels probe, never hard-fails on unreachable", async () => {
+  const root = tmpRoot();
+  writeOrg(root, { enabled: true, base: "https://unreachable.invalid", token: "t", scopes: [...MESSAGING_SCOPES] });
+  // Injected fetch that errors → listChannels fails open to []; verify still ok.
+  const ctx = ctxFor(root);
+  ctx.fetchImpl = async () => { throw new Error("unreachable"); };
+  const v = await messaging.verify(ctx);
+  assert.equal(v.ok, true);
+});

package/lib/setup/sections/model.mjs

@@ -0,0 +1,102 @@
+/**
+ * sections/model.mjs — model / provider selection.  (order 30)
+ *
+ * Records the provider choice: either Anthropic API key (recorded in .env) or
+ * the Claude Code subscription (MAESTRO_PREFER_SUBSCRIPTION_AUTH=1). Optionally
+ * drops a config/model-routing.yaml from the shipped example for cost routing.
+ * Verify probes Claude API reachability (shared with doctor).
+ *
+ * @module lib/setup/sections/model
+ */
+
+"use strict";
+
+import { join } from "node:path";
+import { existsSync, readFileSync, appendFileSync, writeFileSync, copyFileSync } from "node:fs";
+import * as io from "../io.mjs";
+import { probeClaude } from "../claude-probe.mjs";
+
+function readEnv(agentRoot) {
+  const p = join(agentRoot, ".env");
+  return existsSync(p) ? readFileSync(p, "utf-8") : "";
+}
+function hasKey(body, key) { return new RegExp(`^${key}=.+`, "m").test(body); }
+
+function appendEnv(agentRoot, key, value) {
+  const p = join(agentRoot, ".env");
+  if (!existsSync(p)) { writeFileSync(p, `${key}=${value}\n`); return; }
+  const body = readFileSync(p, "utf-8");
+  if (new RegExp(`^${key}=`, "m").test(body)) return; // never clobber an existing value
+  appendFileSync(p, `${body.endsWith("\n") || body === "" ? "" : "\n"}${key}=${value}\n`);
+}
+
+export default {
+  id: "model",
+  label: "Model & provider",
+  order: 30,
+
+  async detect(ctx) {
+    const env = readEnv(ctx.agentRoot);
+    const subs = /^MAESTRO_PREFER_SUBSCRIPTION_AUTH=(1|true|yes)/im.test(env);
+    const apiKey = hasKey(env, "ANTHROPIC_API_KEY");
+    if (subs) return { status: "complete", summary: "Claude Code subscription auth" };
+    if (apiKey) return { status: "complete", summary: "Anthropic API key (.env)" };
+    return { status: "unconfigured", missing: ["provider auth"] };
+  },
+
+  async prompt(ctx) {
+    const provider = await io.select(ctx, {
+      message: "How should the agent authenticate to Claude?",
+      key: "provider",
+      choices: [
+        { label: "Claude Code subscription (keychain OAuth — no API key needed)", value: "subscription" },
+        { label: "Anthropic API key (paste an sk-ant-… key)", value: "api-key" },
+      ],
+      default: "subscription",
+    });
+    let apiKey = "";
+    if (provider === "api-key") {
+      apiKey = await io.secret(ctx, { message: "Paste ANTHROPIC_API_KEY (sk-ant-…)", key: "anthropicApiKey" });
+    }
+    const routing = await io.confirm(ctx, {
+      message: "Enable cost-optimised model routing (writes config/model-routing.yaml)?",
+      key: "modelRouting",
+      default: false,
+    });
+    ctx.answers.model = { provider, apiKey, routing };
+  },
+
+  async apply(ctx) {
+    const a = (ctx.answers && ctx.answers.model) || pull(ctx);
+    if (!a) return;
+    if (a.provider === "subscription") {
+      appendEnv(ctx.agentRoot, "MAESTRO_PREFER_SUBSCRIPTION_AUTH", "1");
+    } else if (a.provider === "api-key" && a.apiKey) {
+      appendEnv(ctx.agentRoot, "ANTHROPIC_API_KEY", a.apiKey);
+    }
+    if (a.routing) {
+      const dst = join(ctx.agentRoot, "config", "model-routing.yaml");
+      const example = join(ctx.maestroRoot, "scaffold", "config", "model-routing.yaml.example");
+      if (!existsSync(dst) && existsSync(example)) {
+        try { copyFileSync(example, dst); } catch { /* fail-open */ }
+      }
+    }
+  },
+
+  async verify(ctx) {
+    const probe = probeClaude(ctx.agentRoot);
+    return {
+      ok: probe.ok,
+      checks: [{ name: probe.name, ok: probe.ok, remedy: probe.remedy }],
+    };
+  },
+};
+
+function pull(ctx) {
+  const ans = ctx.answers || {};
+  if (ans.model) return ans.model;
+  if ("provider" in ans || "anthropicApiKey" in ans) {
+    return { provider: ans.provider || (ans.anthropicApiKey ? "api-key" : "subscription"), apiKey: ans.anthropicApiKey || "", routing: !!ans.modelRouting };
+  }
+  return null;
+}

package/lib/setup/sections/operating-model.mjs

@@ -0,0 +1,78 @@
+/**
+ * sections/operating-model.mjs — generate the full operating model.  (order 60)
+ *
+ * apply() runs the deterministic generators in the design's exact order:
+ *   init-archetype → generate-company → generate-charter → generate-backlog →
+ *   generate-capability → generate-comms → generate-autonomy → generate-cadences
+ *   → generate-plists.sh
+ *
+ * verify() = the shared completeness gate (lib/setup/completeness.assertComplete).
+ * A generator failure is fatal for this section (the operating model is the
+ * "gets straight to work" spine); enrichment of company-slots happens later in
+ * the enrich section.
+ *
+ * @module lib/setup/sections/operating-model
+ */
+
+"use strict";
+
+import { join } from "node:path";
+import { runGenerator, runScriptAbs } from "../run-generator.mjs";
+import { assertComplete } from "../completeness.mjs";
+import * as io from "../io.mjs";
+
+/** Ordered generator pipeline (design §4 "Operating-model apply() order"). */
+const PIPELINE = [
+  "init-archetype.mjs",
+  "generate-company.mjs",
+  "generate-charter.mjs",
+  "generate-backlog.mjs",
+  "generate-capability.mjs",
+  "generate-comms.mjs",
+  "generate-autonomy.mjs",
+  "generate-cadences.mjs",
+];
+
+export default {
+  id: "operating-model",
+  label: "Operating model (charter, backlog, cadences, policies)",
+  order: 60,
+
+  async detect(ctx) {
+    const res = await assertComplete(ctx.agentRoot);
+    if (res.ok) return { status: "complete", summary: "charter + backlog + roster + cadences + policies present" };
+    // Identity/archetype gaps are owned by the identity section, not here.
+    const own = res.missing.filter((m) => !m.artifact.startsWith("identity") && m.artifact !== "config/agent.json");
+    if (own.length === 0) return { status: "complete" };
+    return { status: own.length >= 6 ? "unconfigured" : "partial", missing: own.map((m) => m.artifact) };
+  },
+
+  // No interactive input — the operating model is derived from identity + company.
+  async prompt() { /* none */ },
+
+  async apply(ctx) {
+    for (const script of PIPELINE) {
+      const r = runGenerator(script, ctx.agentRoot, { maestroRoot: ctx.maestroRoot });
+      if (!r.ok) {
+        throw new Error(`operating-model: ${script} failed (exit ${r.code}): ${(r.stderr || r.stdout || "").trim().slice(0, 300)}`);
+      }
+      if (ctx.flags && ctx.flags.verbose) io.note((r.stdout || "").trim(), { dim: true });
+    }
+    // launchd plists (cadence-bus architecture) live under scripts/local-triggers.
+    const plistGen = join(ctx.agentRoot, "scripts", "local-triggers", "generate-plists.sh");
+    const pr = runScriptAbs(plistGen, ctx.agentRoot, { bash: true, maestroRoot: ctx.maestroRoot });
+    // Plist generation can legitimately no-op on non-macOS / missing HOME; don't
+    // hard-fail the operating model on it (the artifacts above are the gate).
+    if (!pr.ok && ctx.flags && ctx.flags.verbose) io.note(`generate-plists.sh: ${(pr.stderr || "").trim()}`, { dim: true });
+  },
+
+  async verify(ctx) {
+    const res = await assertComplete(ctx.agentRoot);
+    const checks = res.ok
+      ? [{ name: "operating model complete", ok: true }]
+      : res.missing
+          .filter((m) => !m.artifact.startsWith("identity") && m.artifact !== "config/agent.json")
+          .map((m) => ({ name: m.artifact, ok: false, remedy: m.reason }));
+    return { ok: checks.every((c) => c.ok), checks: checks.length ? checks : [{ name: "operating model complete", ok: true }] };
+  },
+};