@cohortapp/agent-sdk 2.3.0

package/lib/agent-root.mjs

@@ -0,0 +1,37 @@
+/**
+ * Maestro — Shared Agent Root Resolver
+ *
+ * Single source of truth for "where is this agent's root directory?" so that
+ * every module that needs to locate `state/` (singleton locks, cadence bus,
+ * etc.) agrees on the same path.
+ *
+ * Resolution order (first match wins), absolutized:
+ *   1. AGENT_ROOT  — explicit override (preferred)
+ *   2. AGENT_DIR   — legacy/alternate name used elsewhere in the codebase
+ *   3. process.cwd() — fallback when neither env var is set
+ *
+ * Resolved per call (not memoised at import) so that callers and tests that
+ * mutate the environment before invoking a lock operation see the change.
+ * This deliberately mirrors the resolution used by the cadence bus
+ * (`resolveAgentRoot` in cadence-bus.mjs); both should stay in sync, and the
+ * cadence bus should eventually import from here to remove the duplicate.
+ *
+ * @module agent-root
+ */
+
+import { resolve } from "node:path";
+
+/**
+ * Resolve the agent root directory.
+ *
+ * @param {string} [agentRoot] Optional explicit override (highest precedence).
+ * @returns {string} Absolute path to the agent root.
+ */
+export function resolveAgentRoot(agentRoot) {
+  return resolve(
+    agentRoot ||
+      process.env.AGENT_ROOT ||
+      process.env.AGENT_DIR ||
+      process.cwd()
+  );
+}

package/lib/archetype.mjs

@@ -0,0 +1,236 @@
+/**
+ * archetype.mjs — the function × altitude archetype resolver.
+ *
+ * Maestro's operating model is data, not prose. A chosen archetype is a pair
+ * `{ function, altitude }`. This module composes a fully-resolved operating
+ * profile by deep-merging three versioned YAML overlays:
+ *
+ *     base.yaml  ⊕  functions/<function>.yaml  ⊕  altitudes/<altitude>.yaml
+ *
+ * Function overlays contribute WHAT the agent owns (domain, towers, KPI
+ * categories, stakeholders, backlog streams, tool/skill/template packs, cadence
+ * family). Altitude overlays OVERRIDE how the agent operates (autonomy bands,
+ * decision-rights authority, escalation, KPI altitude, backlog granularity,
+ * delegation breadth, comms formality). The resolved profile is what every
+ * downstream generator reads — charter, backlog, cadences, capabilities, comms.
+ *
+ * Merge semantics (deterministic, see {@link deepMerge}):
+ *   - plain objects        → deep-merge key by key
+ *   - arrays of {id,...}   → upsert by `id` (later layer wins; new ids appended)
+ *   - arrays of scalars    → order-preserving union (deduped)
+ *   - scalars / mismatch   → last layer wins (altitude beats function beats base)
+ *
+ * Validation is dependency-free ({@link validateProfile}); no ajv. The JSON
+ * Schema in archetypes/archetype.schema.json documents the same contract for
+ * editors/tooling.
+ *
+ * @module archetype
+ */
+
+"use strict";
+
+import { readdirSync, readFileSync, existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/** Absolute path to the framework's archetype library (ships in the package). */
+export const ARCHETYPES_DIR = path.resolve(__dirname, "..", "archetypes");
+
+/** Allowed values for the autonomy default posture. @type {string[]} */
+export const AUTONOMY_DEFAULTS = ["observe", "draft", "execute", "escalate-first"];
+/** Allowed decision-right authority levels. @type {string[]} */
+export const AUTHORITIES = ["owns", "recommends", "escalates", "informed"];
+/** Allowed backlog granularities. @type {string[]} */
+export const GRANULARITIES = ["streams", "epics", "tasks"];
+/** Altitude assumed when migrating a legacy single-axis `archetype` value. */
+export const LEGACY_ALTITUDE_DEFAULT = "c-suite";
+
+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;
+}
+
+/** @param {*} v @returns {boolean} true for a non-array, non-null object */
+function isPlainObject(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+/**
+ * Merge two arrays per the documented rules: if every element of the combined
+ * set is an object carrying an `id`, upsert by id (later wins, deep-merging
+ * matching ids); otherwise produce an order-preserving, deduped union.
+ *
+ * @param {any[]} a @param {any[]} b @returns {any[]}
+ */
+function mergeArrays(a, b) {
+  const all = [...a, ...b];
+  const allKeyedObjects = all.length > 0 && all.every((e) => isPlainObject(e) && "id" in e);
+  if (allKeyedObjects) {
+    const byId = new Map();
+    for (const e of a) byId.set(e.id, e);
+    for (const e of b) {
+      byId.set(e.id, byId.has(e.id) && isPlainObject(byId.get(e.id)) ? deepMerge(byId.get(e.id), e) : e);
+    }
+    return [...byId.values()];
+  }
+  const seen = new Set();
+  const out = [];
+  for (const e of all) {
+    const key = isPlainObject(e) ? JSON.stringify(e) : String(e);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(e);
+  }
+  return out;
+}
+
+/**
+ * Deep-merge `b` onto `a` per the module's documented semantics. Pure.
+ *
+ * @param {*} a base value @param {*} b overriding value @returns {*}
+ */
+export function deepMerge(a, b) {
+  if (b === undefined) return a;
+  if (Array.isArray(a) && Array.isArray(b)) return mergeArrays(a, b);
+  if (isPlainObject(a) && isPlainObject(b)) {
+    const out = { ...a };
+    for (const k of Object.keys(b)) out[k] = k in out ? deepMerge(out[k], b[k]) : b[k];
+    return out;
+  }
+  return b;
+}
+
+/** List available function ids (archetypes/functions/*.yaml). @returns {string[]} */
+export function listFunctions() {
+  const dir = path.join(ARCHETYPES_DIR, "functions");
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((f) => f.endsWith(".yaml")).map((f) => f.slice(0, -5)).sort();
+}
+
+/** List available altitude ids (archetypes/altitudes/*.yaml). @returns {string[]} */
+export function listAltitudes() {
+  const dir = path.join(ARCHETYPES_DIR, "altitudes");
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((f) => f.endsWith(".yaml")).map((f) => f.slice(0, -5)).sort();
+}
+
+function loadYamlFile(file, yaml) {
+  if (!existsSync(file)) return {};
+  return yaml.load(readFileSync(file, "utf8")) || {};
+}
+
+/**
+ * Resolve a `{ function, altitude }` pair into a validated operating profile.
+ *
+ * @param {{ function: string, altitude: string }} sel
+ * @returns {Promise<object>} the resolved, validated profile
+ * @throws if the function/altitude is unknown or the resolved profile is invalid
+ */
+export async function resolveArchetype(sel = {}) {
+  const fn = sel.function;
+  const altitude = sel.altitude;
+  if (!fn || !altitude) {
+    throw new Error("resolveArchetype: requires { function, altitude }");
+  }
+  const funcs = listFunctions();
+  const alts = listAltitudes();
+  if (!funcs.includes(fn)) {
+    throw new Error(`resolveArchetype: unknown function "${fn}" (known: ${funcs.join(", ") || "none"})`);
+  }
+  if (!alts.includes(altitude)) {
+    throw new Error(`resolveArchetype: unknown altitude "${altitude}" (known: ${alts.join(", ") || "none"})`);
+  }
+  const yaml = await getYaml();
+  const base = loadYamlFile(path.join(ARCHETYPES_DIR, "base.yaml"), yaml);
+  const fObj = loadYamlFile(path.join(ARCHETYPES_DIR, "functions", `${fn}.yaml`), yaml);
+  const aObj = loadYamlFile(path.join(ARCHETYPES_DIR, "altitudes", `${altitude}.yaml`), yaml);
+
+  const profile = deepMerge(deepMerge(base, fObj), aObj);
+  profile.function = fn;
+  profile.altitude = altitude;
+  if (!profile.label) {
+    const at = profile.altitudeTitle || altitude;
+    const ft = profile.functionTitle || fn;
+    profile.label = `${at}, ${ft}`;
+  }
+  validateProfile(profile);
+  return profile;
+}
+
+/**
+ * Validate a resolved profile against the contract. Fails closed (throws) so an
+ * incomplete overlay can never silently produce a half-formed operating model.
+ *
+ * @param {object} p @returns {true} @throws Error with all violations listed
+ */
+export function validateProfile(p) {
+  const errs = [];
+  if (!isPlainObject(p)) throw new Error("validateProfile: profile must be an object");
+  if (p.schemaVersion !== 1) errs.push("schemaVersion must be 1");
+  for (const k of ["function", "altitude", "label"]) {
+    if (typeof p[k] !== "string" || !p[k]) errs.push(`${k} must be a non-empty string`);
+  }
+  if (!Array.isArray(p.towers) || p.towers.length === 0) errs.push("towers must be a non-empty array");
+  else for (const t of p.towers) if (!isPlainObject(t) || !t.id || !t.name) errs.push("each tower needs id + name");
+
+  if (!isPlainObject(p.autonomy)) errs.push("autonomy must be an object");
+  else {
+    if (!AUTONOMY_DEFAULTS.includes(p.autonomy.default)) errs.push(`autonomy.default must be one of: ${AUTONOMY_DEFAULTS.join(", ")}`);
+    for (const band of ["green", "amber", "red"]) {
+      if (!Array.isArray(p.autonomy[band])) errs.push(`autonomy.${band} must be an array`);
+    }
+  }
+
+  if (!Array.isArray(p.decisionRights) || p.decisionRights.length === 0) errs.push("decisionRights must be a non-empty array");
+  else for (const d of p.decisionRights) {
+    if (!isPlainObject(d) || !d.id || !d.scope) errs.push("each decisionRight needs id + scope");
+    else if (!AUTHORITIES.includes(d.authority)) errs.push(`decisionRight "${d.id}": authority must be one of: ${AUTHORITIES.join(", ")}`);
+  }
+
+  if (!Array.isArray(p.kpiCategories) || p.kpiCategories.length === 0) errs.push("kpiCategories must be a non-empty array");
+  if (!Array.isArray(p.backlogStreams) || p.backlogStreams.length === 0) errs.push("backlogStreams must be a non-empty array");
+  if (!GRANULARITIES.includes(p.backlogGranularity)) errs.push(`backlogGranularity must be one of: ${GRANULARITIES.join(", ")}`);
+  if (!isPlainObject(p.escalation) || !Array.isArray(p.escalation.to)) errs.push("escalation.to must be an array");
+  if (!Array.isArray(p.voiceModes) || p.voiceModes.length === 0) errs.push("voiceModes must be a non-empty array");
+
+  if (errs.length) {
+    throw new Error(`Invalid archetype profile (${p.function || "?"}@${p.altitude || "?"}):\n  - ${errs.join("\n  - ")}`);
+  }
+  return true;
+}
+
+/**
+ * Legacy single-axis `archetype` value for back-compat: the six legacy
+ * archetypes ARE the six functions, so the function id is the legacy value.
+ *
+ * @param {{ function?: string, archetype?: string }} cfg @returns {string|null}
+ */
+export function deriveLegacyArchetype(cfg) {
+  if (!cfg) return null;
+  return cfg.function || cfg.archetype || null;
+}
+
+/**
+ * Migrate a legacy single-axis `archetype` value to a { function, altitude }
+ * pair. Legacy values map to the same function at the default (c-suite) altitude.
+ *
+ * @param {string} oldArchetype @returns {{ function: string, altitude: string } | null}
+ */
+export function migrateLegacyArchetype(oldArchetype) {
+  if (listFunctions().includes(oldArchetype)) {
+    return { function: oldArchetype, altitude: LEGACY_ALTITUDE_DEFAULT };
+  }
+  return null;
+}
+
+/** Every resolvable cell as `{ function, altitude }`. @returns {Array<{function:string,altitude:string}>} */
+export function listCells() {
+  const cells = [];
+  for (const fn of listFunctions()) for (const altitude of listAltitudes()) cells.push({ function: fn, altitude });
+  return cells;
+}

package/lib/archetype.test.mjs

@@ -0,0 +1,132 @@
+/**
+ * archetype.test.mjs — tests for the function × altitude archetype resolver.
+ *
+ * Covers the pure merge engine (deterministic, no I/O) and the live resolution
+ * of the reference cell (technical-leader × vp). A full-matrix "every cell
+ * resolves & validates" test guards the whole library once all overlays exist.
+ *
+ * Run: `node --test lib/archetype.test.mjs`
+ * @module archetype.test
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  deepMerge,
+  resolveArchetype,
+  validateProfile,
+  listFunctions,
+  listAltitudes,
+  listCells,
+  deriveLegacyArchetype,
+  migrateLegacyArchetype,
+  LEGACY_ALTITUDE_DEFAULT,
+} from "./archetype.mjs";
+
+// --- deepMerge: the deterministic merge engine ---
+
+test("deepMerge: scalars — last layer wins", () => {
+  assert.equal(deepMerge("draft", "execute"), "execute");
+  assert.equal(deepMerge(1, 2), 2);
+  assert.equal(deepMerge("x", undefined), "x"); // undefined never overrides
+});
+
+test("deepMerge: plain objects merge key by key", () => {
+  assert.deepEqual(
+    deepMerge({ a: 1, n: { x: 1, y: 1 } }, { b: 2, n: { y: 2, z: 3 } }),
+    { a: 1, b: 2, n: { x: 1, y: 2, z: 3 } }
+  );
+});
+
+test("deepMerge: arrays of {id} upsert by id (later wins, new ids appended)", () => {
+  const a = [{ id: "k", authority: "recommends" }, { id: "m", authority: "owns" }];
+  const b = [{ id: "k", authority: "escalates" }, { id: "n", authority: "owns" }];
+  const merged = deepMerge(a, b);
+  assert.deepEqual(merged.map((e) => e.id), ["k", "m", "n"]);
+  assert.equal(merged.find((e) => e.id === "k").authority, "escalates"); // b wins
+});
+
+test("deepMerge: scalar arrays union (order-preserving, deduped)", () => {
+  assert.deepEqual(deepMerge(["a", "b"], ["b", "c"]), ["a", "b", "c"]);
+});
+
+// --- library is discoverable ---
+
+test("listFunctions/listAltitudes include the reference overlays", () => {
+  assert.ok(listFunctions().includes("technical-leader"));
+  assert.ok(listAltitudes().includes("vp"));
+});
+
+// --- live resolution of the reference cell ---
+
+test("resolveArchetype(technical-leader × vp) composes a valid profile", async () => {
+  const p = await resolveArchetype({ function: "technical-leader", altitude: "vp" });
+  assert.equal(p.schemaVersion, 1);
+  assert.equal(p.function, "technical-leader");
+  assert.equal(p.altitude, "vp");
+  assert.equal(p.label, "VP, Engineering");
+  // function-provided WHAT:
+  assert.ok(p.towers.length >= 5);
+  assert.ok(p.backlogStreams.some((s) => s.id === "roadmap-delivery"));
+  assert.ok(p.kpiCategories.some((k) => k.id === "reliability"));
+  // altitude-provided HOW (overrides base):
+  assert.equal(p.autonomy.default, "execute"); // base 'draft' → altitude 'execute'
+  assert.equal(p.backlogGranularity, "epics");
+  assert.equal(p.kpiAltitude, "operational");
+});
+
+test("decision rights merge: function defaults + altitude overrides coexist", async () => {
+  const p = await resolveArchetype({ function: "technical-leader", altitude: "vp" });
+  const byId = Object.fromEntries(p.decisionRights.map((d) => [d.id, d.authority]));
+  assert.equal(byId.architecture, "owns"); // from function
+  assert.equal(byId["external-commitments"], "escalates"); // from altitude
+  assert.equal(byId.strategy, "recommends"); // altitude-only scope
+});
+
+test("autonomy red band unions base (universal reds) with altitude reds", async () => {
+  const p = await resolveArchetype({ function: "technical-leader", altitude: "vp" });
+  assert.ok(p.autonomy.red.some((r) => /Binding legal or financial/i.test(r))); // base
+  assert.ok(p.autonomy.red.some((r) => /strategy|restructure|headcount/i.test(r))); // altitude
+});
+
+test("operatingPrinciples union base + function + altitude", async () => {
+  const p = await resolveArchetype({ function: "technical-leader", altitude: "vp" });
+  assert.ok(p.operatingPrinciples.includes("Audit everything")); // base
+  assert.ok(p.operatingPrinciples.includes("Technical rigour over speed")); // function
+  assert.ok(p.operatingPrinciples.some((x) => /escalate the tradeoff/i.test(x))); // altitude
+});
+
+// --- failure modes ---
+
+test("resolveArchetype throws on unknown function or altitude", async () => {
+  await assert.rejects(() => resolveArchetype({ function: "nope", altitude: "vp" }), /unknown function/);
+  await assert.rejects(() => resolveArchetype({ function: "technical-leader", altitude: "nope" }), /unknown altitude/);
+  await assert.rejects(() => resolveArchetype({}), /requires \{ function, altitude \}/);
+});
+
+test("validateProfile rejects a malformed profile", () => {
+  assert.throws(() => validateProfile({ schemaVersion: 1, function: "x", altitude: "y", label: "z" }), /towers must be/);
+});
+
+// --- legacy back-compat ---
+
+test("legacy archetype derivation + migration", () => {
+  assert.equal(deriveLegacyArchetype({ function: "technical-leader" }), "technical-leader");
+  assert.deepEqual(migrateLegacyArchetype("technical-leader"), { function: "technical-leader", altitude: LEGACY_ALTITUDE_DEFAULT });
+  assert.equal(migrateLegacyArchetype("not-a-function"), null);
+});
+
+// --- full-matrix guard: every authored cell resolves & validates ---
+
+test("every (function × altitude) cell resolves and validates", async () => {
+  const cells = listCells();
+  assert.ok(cells.length >= 1);
+  for (const cell of cells) {
+    const p = await resolveArchetype(cell); // resolveArchetype validates internally
+    assert.equal(p.function, cell.function);
+    assert.equal(p.altitude, cell.altitude);
+  }
+});

package/lib/autonomy.mjs

@@ -0,0 +1,114 @@
+/**
+ * autonomy.mjs — derive the agent's action-classification policy from its
+ * resolved archetype (function × altitude).
+ *
+ * Autonomy/decision-rights must be a function of the archetype, and must be
+ * ENFORCED, not decorative. This builds an action-classification policy that
+ * carries BOTH shapes:
+ *
+ *   - `action_levels` (human / charter view): observe / draft / execute_autonomous
+ *     (= the profile's green band) / approval_preferred (= amber) / escalate
+ *     (= red), plus decision_rights and the escalation protocol — straight from
+ *     the resolved profile, so a founder's bands differ from a senior-manager's.
+ *
+ *   - `actions` (the per-action map lib/voice/tool-bridge.mjs actually reads:
+ *     `{ actionName: { risk, verbal_confirm, approval } }`). Built from a risk
+ *     baseline, then shifted by the archetype's delegation breadth — broad
+ *     (founder/C-suite) downshifts routine sends toward autonomous; narrow
+ *     (senior-manager) upshifts them toward approval. This is what makes the
+ *     voice/comms gate live instead of defaulting everything to "low".
+ *
+ * Pure (no I/O). ESM. The generator (scripts/setup/generate-autonomy.mjs) writes
+ * the result to the agent's policies/action-classification.yaml.
+ *
+ * @module autonomy
+ */
+
+"use strict";
+
+/** Baseline per-action risk for the actions the comms/voice gate sees. */
+export const ACTION_RISK_BASELINE = {
+  send_email: "high",
+  send_slack_message: "medium",
+  send_whatsapp_message: "medium",
+  send_sms: "medium",
+  place_voice_call: "high",
+  send_voice_message: "high",
+  create_calendar_event: "low",
+  update_calendar_event: "low",
+  search_email: "low",
+  search_calendar: "low",
+  rag_search: "low",
+  generate_report: "low",
+};
+
+const APPROVAL_FOR = { high: "explicit", medium: "preferred", low: "autonomous" };
+
+/**
+ * Build the archetype-derived action-classification policy.
+ * @param {object} profile resolved archetype profile (lib/archetype.mjs)
+ * @param {object} [identity] config/agent.json (optional, for labelling)
+ * @returns {object} the action-classification structure (action_levels + actions + decision_rights)
+ */
+export function buildActionClassification(profile, identity = {}) {
+  if (!profile) throw new Error("buildActionClassification: requires a resolved profile");
+  const a = profile.autonomy || {};
+  const breadth = profile.delegationBreadth || "moderate";
+  const downshift = breadth === "broad"; // more autonomous
+  const upshift = breadth === "narrow" || breadth === "none"; // more approval-gated
+
+  const actions = {};
+  for (const [name, base] of Object.entries(ACTION_RISK_BASELINE)) {
+    let risk = base;
+    if (downshift && risk === "medium") risk = "low";
+    if (upshift && risk === "medium") risk = "high";
+    if (upshift && risk === "low" && /^(send_|place_)/.test(name)) risk = "medium";
+    actions[name] = {
+      risk,
+      verbal_confirm: risk === "high",
+      approval: APPROVAL_FOR[risk] || "autonomous",
+    };
+  }
+
+  const esc = profile.escalation || {};
+
+  // Org source-of-truth override (guarded + minimal): when enrollment persisted
+  // the member's authoritative operating fields (config/agent.json `orgProfile`
+  // from the Cohort MemberProfileDTO), PREFER the org's `autonomyLevel` over the
+  // archetype default and the org's `escalationPath` over the archetype escalation
+  // targets. When the fields are absent the classification is byte-identical to
+  // before — existing behaviour is untouched.
+  const org = (identity && identity.orgProfile) || {};
+  const orgAutonomy = typeof org.autonomyLevel === "string" && org.autonomyLevel.trim() ? org.autonomyLevel.trim() : "";
+  const orgEscalation = typeof org.escalationPath === "string" && org.escalationPath.trim() ? org.escalationPath.trim() : "";
+
+  return {
+    _doc:
+      "Archetype-derived action classification (function × altitude). action_levels is the human/charter view (green/amber/red); `actions` is the per-action map the voice/comms gate enforces. Generated by scripts/setup/generate-autonomy.mjs — regenerate after an archetype change; do not hand-edit. autonomy_default and escalate_to honour the org's authoritative autonomyLevel/escalationPath when present.",
+    archetype: `${profile.function}@${profile.altitude}`,
+    autonomy_default: orgAutonomy || a.default || "draft",
+    ...(orgAutonomy ? { org_autonomy_level: orgAutonomy } : {}),
+    delegation_breadth: breadth,
+    action_levels: {
+      observe: { risk: "low", approval: "none", description: "Read-only: viewing, scanning, searching, monitoring." },
+      draft: { risk: "low", approval: "none", description: "Preparing content without sending or committing." },
+      execute_autonomous: { risk: "low-to-medium", approval: "autonomous", examples: a.green || [] },
+      approval_preferred: { risk: "medium", approval: "principal_preferred", examples: a.amber || [] },
+      escalate: {
+        risk: "high-to-critical",
+        approval: "explicit_required",
+        examples: a.red || [],
+        escalate_to: orgEscalation ? [orgEscalation] : (esc.to || ["principal"]),
+        triggers: esc.triggers || [],
+        ...(orgEscalation ? { escalation_path: orgEscalation } : {}),
+      },
+    },
+    decision_rights: (profile.decisionRights || []).map((d) => ({ id: d.id, scope: d.scope, authority: d.authority })),
+    actions,
+    emergency: {
+      kill_switch: "scripts/emergency-stop.sh",
+      pause_all_sends: true,
+      resume_requires: "scripts/resume-operations.sh",
+    },
+  };
+}

package/lib/autonomy.test.mjs

@@ -0,0 +1,66 @@
+/**
+ * autonomy.test.mjs — tests for the archetype-derived action-classification.
+ * Run: `node --test lib/autonomy.test.mjs`
+ * @module autonomy.test
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { resolveArchetype } from "./archetype.mjs";
+import { buildActionClassification } from "./autonomy.mjs";
+
+test("action_levels bands come straight from the resolved profile", async () => {
+  const profile = await resolveArchetype({ function: "technical-leader", altitude: "vp" });
+  const p = buildActionClassification(profile);
+  assert.deepEqual(p.action_levels.execute_autonomous.examples, profile.autonomy.green);
+  assert.deepEqual(p.action_levels.approval_preferred.examples, profile.autonomy.amber);
+  assert.deepEqual(p.action_levels.escalate.examples, profile.autonomy.red);
+  assert.ok(p.decision_rights.length >= 1 && p.decision_rights[0].authority);
+  assert.deepEqual(p.action_levels.escalate.escalate_to, profile.escalation.to);
+});
+
+test("per-action map is in the shape the voice gate reads (risk + verbal_confirm + approval)", async () => {
+  const p = buildActionClassification(await resolveArchetype({ function: "commercial-leader", altitude: "vp" }));
+  assert.ok(p.actions.send_email && typeof p.actions.send_email.risk === "string");
+  assert.equal(typeof p.actions.send_email.verbal_confirm, "boolean");
+  assert.ok(["explicit", "preferred", "autonomous"].includes(p.actions.send_email.approval));
+  // high-risk actions demand a verbal confirm
+  for (const a of Object.values(p.actions)) if (a.risk === "high") assert.equal(a.verbal_confirm, true);
+});
+
+test("breadth tunes the gate: founder (broad) is more autonomous than senior-manager (narrow)", async () => {
+  const founder = buildActionClassification(await resolveArchetype({ function: "technical-leader", altitude: "founder" }));
+  const srMgr = buildActionClassification(await resolveArchetype({ function: "technical-leader", altitude: "senior-manager" }));
+  // a routine send: broad → low/autonomous; narrow → high/gated
+  assert.equal(founder.actions.send_slack_message.risk, "low");
+  assert.equal(srMgr.actions.send_slack_message.risk, "high");
+  assert.equal(srMgr.actions.send_email.risk, "high");
+  assert.notEqual(founder.delegation_breadth, srMgr.delegation_breadth);
+});
+
+test("buildActionClassification requires a profile", () => {
+  assert.throws(() => buildActionClassification(null), /requires/);
+});
+
+test("org autonomyLevel/escalationPath (identity.orgProfile) override the archetype default", async () => {
+  const profile = await resolveArchetype({ function: "technical-leader", altitude: "vp" });
+  const identity = { orgProfile: { autonomyLevel: "supervised", escalationPath: "CTO then CEO" } };
+  const p = buildActionClassification(profile, identity);
+  assert.equal(p.autonomy_default, "supervised", "org autonomyLevel wins over archetype default");
+  assert.equal(p.org_autonomy_level, "supervised");
+  assert.deepEqual(p.action_levels.escalate.escalate_to, ["CTO then CEO"], "org escalationPath wins");
+  assert.equal(p.action_levels.escalate.escalation_path, "CTO then CEO");
+});
+
+test("absent org fields → classification is unchanged (existing behaviour preserved)", async () => {
+  const profile = await resolveArchetype({ function: "technical-leader", altitude: "vp" });
+  const without = buildActionClassification(profile, {});
+  const baseline = buildActionClassification(profile); // no identity at all
+  assert.equal(without.autonomy_default, profile.autonomy.default || "draft");
+  assert.equal(without.org_autonomy_level, undefined);
+  assert.deepEqual(without.action_levels.escalate.escalate_to, profile.escalation.to);
+  assert.equal(without.action_levels.escalate.escalation_path, undefined);
+  assert.deepEqual(without, baseline);
+});