@cohortapp/agent-sdk 2.3.0

package/lib/setup/enroll-from-cohort.mjs

@@ -0,0 +1,441 @@
+/**
+ * lib/setup/enroll-from-cohort.mjs — pull-and-map an agent's record from the
+ * Cohort org-data API into the config/agent.json field subset.
+ *
+ * The org single-SoT payoff for ONBOARDING: an admin describes the agent ONCE in
+ * Cohort (its MemberProfileDTO — slug/title/team/role/agentEmail/profileSections/
+ * supervisor/…); when `COHORT_API_KEY` + `COHORT_ORG_ID` are present (optionally
+ * `COHORT_AGENT_ID`), `maestro setup` PULLS that record and auto-populates
+ * config/agent.json instead of prompting the operator field-by-field. The wizard
+ * then CONFIRMS the pulled values; a re-pull (`maestro sync`) keeps the agent in
+ * step with the org over time.
+ *
+ * Two pure, side-effect-free helpers live here so they are trivially testable
+ * (the network call lives in lib/org/client.fetchSelfProfile, injected for tests):
+ *
+ *   mapProfileToAgentConfig(profile)            → the config/agent.json subset the
+ *                                                 profile AUTHORITATIVELY provides
+ *   mergeProfilePatch(current, patch, {force})  → the patch with locally-customised
+ *                                                 leaves dropped (unless force)
+ *
+ * Mapping policy — map ONLY fields the profile authoritatively provides; never
+ * invent a value. Function/altitude are derived from the member's role+team via a
+ * bounded keyword map and ALWAYS fall back to a safe default the wizard can change
+ * (never fail the pull on an unmappable role). Local customisation is sacred: a
+ * value the operator already set in config/agent.json is NOT clobbered by a pull
+ * unless `--force` is passed (the `maestro sync --force` path).
+ *
+ * Fail-open by contract: every helper tolerates a null/partial profile and
+ * returns a (possibly empty) plain object — never throws — so a degraded Cohort
+ * record can never block setup; the wizard simply falls back to manual prompts.
+ *
+ * @module lib/setup/enroll-from-cohort
+ */
+
+"use strict";
+
+import { readAgentJson } from "./sot.mjs";
+import { isPlaceholder } from "./completeness.mjs";
+
+// Archetype axes the identity section also offers. Keep these in sync with
+// lib/setup/sections/identity.mjs FUNCTIONS/ALTITUDES — a derived value MUST be
+// one the wizard's select() can render and the archetype resolver accepts.
+const FUNCTIONS = Object.freeze([
+  "executive-operator",
+  "technical-leader",
+  "commercial-leader",
+  "people-leader",
+  "finance-leader",
+  "compliance-leader",
+]);
+const ALTITUDES = Object.freeze(["c-suite", "svp", "vp", "senior-manager"]);
+
+const DEFAULT_FUNCTION = "executive-operator";
+const DEFAULT_ALTITUDE = "c-suite";
+
+/**
+ * Are the Cohort pull env vars present? The PULL path is gated on an API key +
+ * an org id; the agent id is optional (its absence selects the whoami endpoint).
+ * Pure read of process.env (injectable for tests).
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {{ enabled:boolean, apiKey:string, orgId:string, agentId:string, base:string }}
+ */
+export function cohortPullEnv(env = process.env) {
+  const apiKey = str(env.COHORT_API_KEY) || str(env.COHORT_API_TOKEN) || str(env.COHORT_TOKEN);
+  const orgId = str(env.COHORT_ORG_ID);
+  const agentId = str(env.COHORT_AGENT_ID);
+  const base = str(env.COHORT_BASE) || str(env.COHORT_API_URL);
+  return { enabled: !!(apiKey && orgId), apiKey, orgId, agentId, base };
+}
+
+function str(v) {
+  return v == null ? "" : String(v).trim();
+}
+
+/**
+ * Map a Cohort MemberProfileDTO to the config/agent.json field subset it
+ * authoritatively provides. Only sets a field when the profile carries a real
+ * value (an empty/placeholder profile yields an empty patch). Never throws.
+ *
+ * Authoritatively mapped:
+ *   firstName/lastName/fullName  ← firstName/lastName/displayName
+ *   title                        ← title
+ *   email                        ← agentEmail
+ *   function/altitude            ← derived from role+team (bounded keyword map)
+ *   archetype                    ← `${function} ${altitude}`-derived (left to the
+ *                                  identity generator; we set function/altitude)
+ *   principal                    ← supervisor (fullName/title/email split)
+ *   operatingPrinciples          ← profileSections (operating-principles section)
+ *   communication.defaultTone    ← profileSections (communication/tone section)
+ *   responsibilities             ← profileSections (responsibilities section)
+ *
+ * @param {object|null} profile MemberProfileDTO
+ * @returns {object} the config/agent.json patch (deep-mergeable)
+ */
+export function mapProfileToAgentConfig(profile) {
+  const p = profile && typeof profile === "object" ? profile : {};
+  const patch = {};
+
+  const first = str(p.firstName);
+  const last = str(p.lastName);
+  const display = str(p.displayName);
+  if (first) patch.firstName = first;
+  if (last) patch.lastName = last;
+  const fullName = display || [first, last].filter(Boolean).join(" ").trim();
+  if (fullName) patch.fullName = fullName;
+
+  const title = str(p.title);
+  if (title) patch.title = title;
+
+  const email = str(p.agentEmail) || str(p.email);
+  if (email) patch.email = email;
+
+  // function/altitude — derive from role + team. Only emitted when the profile
+  // carries a role/team/title signal (a genuinely empty profile yields no axis,
+  // leaving the wizard to prompt). When signal IS present, derivation always
+  // resolves to a VALID axis (safe default when unmappable) so the wizard renders
+  // + confirms it rather than failing the pull.
+  const hasAxisSignal = !!(str(p.role) || str(p.team) || str(p.title));
+  if (hasAxisSignal) {
+    patch.function = deriveFunction(p);
+    patch.altitude = deriveAltitude(p);
+  }
+
+  // principal — the supervisor the agent reports to.
+  const principal = mapSupervisor(p.supervisor);
+  if (principal) patch.principal = principal;
+
+  // profileSections — authored prose the org maintains. Mapped conservatively:
+  // only when a recognisable section exists, and only into fields the profile is
+  // the SoT for.
+  const sections = Array.isArray(p.profileSections) ? p.profileSections : [];
+  const principles = sectionLines(sections, ["operating-principles", "operating principles", "principles"]);
+  if (principles.length) patch.operatingPrinciples = principles;
+  const responsibilities = sectionLines(sections, ["responsibilities", "responsibility", "mandate"]);
+  if (responsibilities.length) patch.responsibilities = responsibilities;
+  const tone = sectionText(sections, ["communication", "tone", "communication-style"]);
+  if (tone) patch.communication = { defaultTone: tone };
+
+  // charter — the Cohort-authored operating charter (CharterDTO:
+  // approvedByLine/gatesText/sections). When present this is the SOURCE OF TRUTH
+  // the charter generator renders FROM (scripts/setup/generate-charter.mjs),
+  // overriding the archetype skeleton. We persist it verbatim so the generator
+  // and the doctor read the same authored charter.
+  const charter = mapCharter(p.charter);
+  if (charter) patch.charter = charter;
+
+  // org-authoritative operating fields the enrollment mapper previously DROPPED.
+  // Persisted under `orgProfile` so they are available to autonomy generation
+  // (autonomyLevel/escalationPath) and to any caller that needs the org's view of
+  // this member's reports/governance/skills/operating channel.
+  const orgProfile = mapOrgProfile(p);
+  if (orgProfile) patch.orgProfile = orgProfile;
+
+  return patch;
+}
+
+/**
+ * Map a CharterDTO ({ approvedByLine, gatesText, sections:[{kind,order,title,body}] })
+ * into the persisted charter subset. Returns null when there is no real charter
+ * (no sections AND no approvedBy/gates text) so an empty patch stays empty.
+ * @param {object|null} charter
+ * @returns {object|null}
+ */
+function mapCharter(charter) {
+  if (!charter || typeof charter !== "object") return null;
+  const sectionsIn = Array.isArray(charter.sections) ? charter.sections : [];
+  const sections = sectionsIn
+    .filter((s) => s && typeof s === "object")
+    .map((s) => ({
+      kind: str(s.kind),
+      order: Number.isFinite(s.order) ? s.order : 0,
+      title: str(s.title) || null,
+      body: str(s.body),
+    }))
+    .filter((s) => s.body || s.title);
+  const approvedByLine = str(charter.approvedByLine);
+  const gatesText = str(charter.gatesText);
+  if (!sections.length && !approvedByLine && !gatesText) return null;
+  const out = { sections };
+  if (approvedByLine) out.approvedByLine = approvedByLine;
+  if (gatesText) out.gatesText = gatesText;
+  return out;
+}
+
+/**
+ * Collect the org-authoritative operating fields the wizard should NOT drop:
+ * autonomyLevel, escalationPath, skills, operatingChannel, reports, governance.
+ * Only includes a field when the profile carries a real value. Returns null when
+ * the profile carries none of them (keeps an empty patch empty).
+ * @param {object} p MemberProfileDTO
+ * @returns {object|null}
+ */
+function mapOrgProfile(p) {
+  const out = {};
+  const autonomyLevel = str(p.autonomyLevel);
+  if (autonomyLevel) out.autonomyLevel = autonomyLevel;
+  const escalationPath = str(p.escalationPath);
+  if (escalationPath) out.escalationPath = escalationPath;
+  const operatingChannel = str(p.operatingChannel);
+  if (operatingChannel) out.operatingChannel = operatingChannel;
+  const skills = Array.isArray(p.skills) ? p.skills.map(str).filter(Boolean) : [];
+  if (skills.length) out.skills = skills;
+  const reports = Array.isArray(p.reports) ? p.reports.filter((r) => r && typeof r === "object") : [];
+  if (reports.length) out.reports = reports;
+  const governance = Array.isArray(p.governance) ? p.governance.filter((g) => g && typeof g === "object") : [];
+  if (governance.length) out.governance = governance;
+  return Object.keys(out).length ? out : null;
+}
+
+/** Build the principal sub-object from a supervisor descriptor (string or DTO). */
+function mapSupervisor(sup) {
+  if (!sup) return null;
+  if (typeof sup === "string") {
+    const fullName = str(sup);
+    if (!fullName) return null;
+    const [pf, ...pr] = fullName.split(/\s+/);
+    return { firstName: pf || "", lastName: pr.join(" "), fullName, title: "", email: "" };
+  }
+  if (typeof sup === "object") {
+    const fullName = str(sup.displayName) || str(sup.fullName) || [str(sup.firstName), str(sup.lastName)].filter(Boolean).join(" ").trim();
+    if (!fullName && !str(sup.email) && !str(sup.title)) return null;
+    const [pf, ...pr] = fullName.split(/\s+/);
+    return {
+      firstName: str(sup.firstName) || pf || "",
+      lastName: str(sup.lastName) || pr.join(" "),
+      fullName,
+      title: str(sup.title),
+      email: str(sup.email) || str(sup.agentEmail),
+    };
+  }
+  return null;
+}
+
+/**
+ * Derive the archetype `function` axis from the member's role + team using a
+ * bounded keyword map. Returns DEFAULT_FUNCTION when nothing matches — the pull
+ * never fails on an unmappable role; the wizard confirms/changes it.
+ * @param {object} p
+ * @returns {string} one of FUNCTIONS
+ */
+export function deriveFunction(p) {
+  const hay = `${str(p.role)} ${str(p.team)} ${str(p.title)}`.toLowerCase();
+  const rules = [
+    [/\b(eng|engineer|platform|infra|technical|cto|devops|software|sre)\b/, "technical-leader"],
+    [/\b(sales|revenue|gtm|growth|commercial|marketing|bd|biz dev|partnerships)\b/, "commercial-leader"],
+    [/\b(people|hr|talent|recruit|org design|human resources)\b/, "people-leader"],
+    [/\b(finance|fp&a|accounting|treasury|capital|corp dev|cfo)\b/, "finance-leader"],
+    [/\b(compliance|legal|risk|regulatory|counsel|audit|dfsa)\b/, "compliance-leader"],
+    [/\b(ops|operations|chief of staff|coo|executive|operator)\b/, "executive-operator"],
+  ];
+  for (const [re, fn] of rules) if (re.test(hay)) return fn;
+  return DEFAULT_FUNCTION;
+}
+
+/**
+ * Derive the `altitude` axis from role/title seniority cues. Returns
+ * DEFAULT_ALTITUDE when nothing matches.
+ * @param {object} p
+ * @returns {string} one of ALTITUDES
+ */
+export function deriveAltitude(p) {
+  const hay = `${str(p.role)} ${str(p.title)}`.toLowerCase();
+  // Order matters: most-senior cue wins (check c-suite/SVP before VP/manager).
+  if (/\b(c-?suite|chief|ceo|cto|cfo|coo|cmo|cpo|founder)\b/.test(hay)) return "c-suite";
+  if (/\bsvp\b|senior vice president/.test(hay)) return "svp";
+  if (/\bvp\b|vice president|head of|director/.test(hay)) return "vp";
+  if (/\b(senior manager|sr\.? manager|manager|lead)\b/.test(hay)) return "senior-manager";
+  return DEFAULT_ALTITUDE;
+}
+
+/** Find a profile section by case-insensitive id/title match. */
+function findSection(sections, names) {
+  const wanted = names.map((n) => n.toLowerCase());
+  return (
+    sections.find((s) => {
+      if (!s || typeof s !== "object") return false;
+      const id = str(s.id).toLowerCase();
+      const title = str(s.title).toLowerCase();
+      const heading = str(s.heading).toLowerCase();
+      return wanted.includes(id) || wanted.includes(title) || wanted.includes(heading);
+    }) || null
+  );
+}
+
+/** Pull a section's content as a list of trimmed non-empty lines. */
+function sectionLines(sections, names) {
+  const s = findSection(sections, names);
+  if (!s) return [];
+  if (Array.isArray(s.items)) return s.items.map(str).filter(Boolean);
+  if (Array.isArray(s.lines)) return s.lines.map(str).filter(Boolean);
+  const body = str(s.content) || str(s.body) || str(s.text);
+  if (!body) return [];
+  return body
+    .split(/\r?\n/)
+    .map((l) => l.replace(/^\s*[-*•]\s*/, "").trim())
+    .filter(Boolean);
+}
+
+/** Pull a section's content as a single trimmed string (first non-empty leaf). */
+function sectionText(sections, names) {
+  const s = findSection(sections, names);
+  if (!s) return "";
+  const body = str(s.content) || str(s.body) || str(s.text);
+  if (body) return body.split(/\r?\n/).map((l) => l.trim()).filter(Boolean)[0] || "";
+  if (Array.isArray(s.items) && s.items.length) return str(s.items[0]);
+  return "";
+}
+
+/**
+ * Reduce a pull patch so it never clobbers a locally-customised value. A leaf is
+ * dropped from the patch when the CURRENT config already has a real (non-empty,
+ * non-placeholder) value for it — UNLESS `force` is set. This is the seam that
+ * lets `maestro setup`/`sync` re-pull freely while protecting operator edits.
+ *
+ * Nested objects (principal, communication) are reduced leaf-by-leaf; an entirely
+ * dropped object is omitted. Arrays (responsibilities/operatingPrinciples) are
+ * treated as a single leaf (kept only if the current array is empty or force).
+ *
+ * @param {object|null} current the existing config/agent.json ({} when none)
+ * @param {object} patch the patch from mapProfileToAgentConfig
+ * @param {{force?:boolean}} [opts]
+ * @returns {object} the reduced patch (safe to deep-merge)
+ */
+export function mergeProfilePatch(current, patch, opts = {}) {
+  const force = !!opts.force;
+  const cur = current && typeof current === "object" ? current : {};
+  const out = {};
+  for (const [k, v] of Object.entries(patch || {})) {
+    if (v && typeof v === "object" && !Array.isArray(v)) {
+      const sub = reduceObject((cur[k] && typeof cur[k] === "object" && cur[k]) || {}, v, force);
+      if (sub && Object.keys(sub).length) out[k] = sub;
+      continue;
+    }
+    if (force || isUnset(cur[k])) out[k] = v;
+  }
+  return out;
+}
+
+function reduceObject(curObj, patchObj, force) {
+  const out = {};
+  for (const [k, v] of Object.entries(patchObj)) {
+    if (v && typeof v === "object" && !Array.isArray(v)) {
+      const sub = reduceObject((curObj[k] && typeof curObj[k] === "object" && curObj[k]) || {}, v, force);
+      if (sub && Object.keys(sub).length) out[k] = sub;
+      continue;
+    }
+    if (force || isUnset(curObj[k])) out[k] = v;
+  }
+  return out;
+}
+
+/** A leaf is "unset" when missing, empty, an empty array, or a placeholder. */
+function isUnset(v) {
+  if (v === undefined || v === null) return true;
+  if (typeof v === "string") return v.trim() === "" || isPlaceholder(v);
+  if (Array.isArray(v)) return v.length === 0;
+  return false;
+}
+
+/**
+ * Compute the leaf-level diff between two config subsets — the human-readable
+ * "what changed" report `maestro sync` prints. Returns an array of
+ * `{ path, from, to }`. Pure; only inspects the keys present in `patch`.
+ * @param {object} before
+ * @param {object} patch the reduced patch about to be merged
+ * @returns {Array<{path:string, from:*, to:*}>}
+ */
+export function diffPatch(before, patch) {
+  const b = before && typeof before === "object" ? before : {};
+  const changes = [];
+  walkDiff(b, patch || {}, "", changes);
+  return changes;
+}
+
+function walkDiff(before, patch, prefix, changes) {
+  for (const [k, v] of Object.entries(patch || {})) {
+    const path = prefix ? `${prefix}.${k}` : k;
+    const prev = before ? before[k] : undefined;
+    if (v && typeof v === "object" && !Array.isArray(v)) {
+      walkDiff(prev && typeof prev === "object" ? prev : {}, v, path, changes);
+      continue;
+    }
+    if (!sameLeaf(prev, v)) changes.push({ path, from: prev, to: v });
+  }
+}
+
+function sameLeaf(a, b) {
+  if (Array.isArray(a) && Array.isArray(b)) return JSON.stringify(a) === JSON.stringify(b);
+  return a === b;
+}
+
+/**
+ * High-level orchestration used by both the org/identity sections and
+ * `maestro sync`: pull the self profile, map it, reduce against the current
+ * config, and (optionally) return the diff. Network call is injected via
+ * `fetchSelfProfileImpl` (the lib/org/client export) so this is unit-testable.
+ *
+ * Fail-open: a missing key, an unreachable server, or a profile-less response
+ * yields `{ pulled:false, patch:{}, changes:[] }` — the caller falls back to the
+ * manual prompts exactly as today.
+ *
+ * @param {object} o
+ * @param {string} o.agentRoot
+ * @param {NodeJS.ProcessEnv} [o.env]
+ * @param {boolean} [o.force]
+ * @param {Function} o.fetchSelfProfileImpl  client.fetchSelfProfile (injected)
+ * @returns {Promise<{ pulled:boolean, reason?:string, profile?:object, patch:object, changes:Array }>}
+ */
+export async function pullAndPlan(o = {}) {
+  const env = o.env || process.env;
+  const e = cohortPullEnv(env);
+  if (!e.enabled) return { pulled: false, reason: "cohort-pull env not set", patch: {}, changes: [] };
+  if (typeof o.fetchSelfProfileImpl !== "function") {
+    return { pulled: false, reason: "no fetch impl", patch: {}, changes: [] };
+  }
+
+  let frame;
+  try {
+    frame = await o.fetchSelfProfileImpl({
+      base: e.base,
+      apiKey: e.apiKey,
+      orgId: e.orgId,
+      agentId: e.agentId || undefined,
+      emailHint: str(env.COHORT_AGENT_EMAIL) || undefined,
+    });
+  } catch {
+    return { pulled: false, reason: "fetch threw", patch: {}, changes: [] };
+  }
+  if (!frame || !frame.ok || !frame.result) {
+    return { pulled: false, reason: (frame && frame.error && frame.error.message) || "no profile", patch: {}, changes: [] };
+  }
+
+  const profile = frame.result;
+  const mapped = mapProfileToAgentConfig(profile);
+  const current = readAgentJson(o.agentRoot) || {};
+  const patch = mergeProfilePatch(current, mapped, { force: !!o.force });
+  const changes = diffPatch(current, patch);
+  return { pulled: true, profile, patch, changes };
+}
+
+export { FUNCTIONS, ALTITUDES, DEFAULT_FUNCTION, DEFAULT_ALTITUDE };

package/lib/setup/enroll-from-cohort.test.mjs

@@ -0,0 +1,233 @@
+/**
+ * enroll-from-cohort.test.mjs — pull-and-map a Cohort MemberProfileDTO into
+ * the config/agent.json subset, with local-customisation protection + diff.
+ * Run: node --test lib/setup/enroll-from-cohort.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  mapProfileToAgentConfig,
+  mergeProfilePatch,
+  diffPatch,
+  deriveFunction,
+  deriveAltitude,
+  cohortPullEnv,
+  pullAndPlan,
+  FUNCTIONS,
+  ALTITUDES,
+} from "./enroll-from-cohort.mjs";
+import { readAgentJson } from "./sot.mjs";
+
+function tmpRoot() {
+  const root = mkdtempSync(join(tmpdir(), "maestro-enroll-"));
+  mkdirSync(join(root, "config"), { recursive: true });
+  return root;
+}
+function writeAgent(root, obj) {
+  writeFileSync(join(root, "config", "agent.json"), JSON.stringify(obj, null, 2) + "\n");
+}
+
+// A representative MemberProfileDTO from the org-data API.
+const PROFILE = {
+  slug: "robin",
+  kind: "agent",
+  displayName: "Robin Vega",
+  firstName: "Robin",
+  lastName: "Vega",
+  title: "VP of Engineering",
+  team: "Platform Engineering",
+  role: "engineering-lead",
+  agentEmail: "robin@example.com",
+  supervisor: { displayName: "Layla Al-Masri", title: "CTO", email: "layla@example.com" },
+  profileSections: [
+    { id: "operating-principles", content: "- Ship small\n- Default to autonomy\n- Escalate blockers fast" },
+    { id: "responsibilities", items: ["Own CI/CD", "Run platform on-call"] },
+    { id: "communication", content: "Direct, technical, low-ceremony." },
+  ],
+};
+
+test("mapProfileToAgentConfig maps the authoritative fields", () => {
+  const patch = mapProfileToAgentConfig(PROFILE);
+  assert.equal(patch.firstName, "Robin");
+  assert.equal(patch.lastName, "Vega");
+  assert.equal(patch.fullName, "Robin Vega");
+  assert.equal(patch.title, "VP of Engineering");
+  assert.equal(patch.email, "robin@example.com");
+  assert.equal(patch.function, "technical-leader");
+  assert.equal(patch.altitude, "vp");
+  assert.equal(patch.principal.fullName, "Layla Al-Masri");
+  assert.equal(patch.principal.title, "CTO");
+  assert.equal(patch.principal.email, "layla@example.com");
+  assert.deepEqual(patch.operatingPrinciples, ["Ship small", "Default to autonomy", "Escalate blockers fast"]);
+  assert.deepEqual(patch.responsibilities, ["Own CI/CD", "Run platform on-call"]);
+  assert.equal(patch.communication.defaultTone, "Direct, technical, low-ceremony.");
+});
+
+test("mapProfileToAgentConfig is fail-open on a null/empty profile", () => {
+  assert.deepEqual(mapProfileToAgentConfig(null), {});
+  assert.deepEqual(mapProfileToAgentConfig({}), {});
+  // A bare role signal IS enough to derive an axis.
+  assert.equal(mapProfileToAgentConfig({ role: "engineer" }).function, "technical-leader");
+});
+
+// A MemberProfileDTO carrying the Cohort-authored charter + the authoritative
+// operating fields the mapper previously DROPPED.
+const PROFILE_FULL = {
+  ...PROFILE,
+  autonomyLevel: "high",
+  escalationPath: "CTO, then CEO for irreversible decisions",
+  operatingChannel: "#platform",
+  skills: ["ci-cd", "incident-response"],
+  reports: [{ member: { slug: "kai", displayName: "Kai Tan" }, style: "SOLID" }],
+  governance: [{ type: "ADVISES", direction: "out", counterpart: { slug: "secops" }, theme: "security" }],
+  charter: {
+    approvedByLine: "Approved by Layla Al-Masri, CTO — 2026-06-01",
+    gatesText: "All irreversible spend > $10k escalates.",
+    sections: [
+      { kind: "purpose", order: 1, title: "Purpose & Mandate", body: "Own platform reliability and developer velocity." },
+      { kind: "decision_rights", order: 2, title: null, body: "Owns deploy cadence; recommends headcount." },
+    ],
+  },
+};
+
+test("mapProfileToAgentConfig captures the Cohort-authored charter (SoT)", () => {
+  const patch = mapProfileToAgentConfig(PROFILE_FULL);
+  assert.ok(patch.charter, "charter present in patch");
+  assert.equal(patch.charter.approvedByLine, "Approved by Layla Al-Masri, CTO — 2026-06-01");
+  assert.equal(patch.charter.gatesText, "All irreversible spend > $10k escalates.");
+  assert.equal(patch.charter.sections.length, 2);
+  assert.equal(patch.charter.sections[0].title, "Purpose & Mandate");
+  assert.equal(patch.charter.sections[1].title, null);
+  assert.match(patch.charter.sections[1].body, /Owns deploy cadence/);
+});
+
+test("mapProfileToAgentConfig persists the authoritative org operating fields", () => {
+  const patch = mapProfileToAgentConfig(PROFILE_FULL);
+  assert.ok(patch.orgProfile, "orgProfile present in patch");
+  assert.equal(patch.orgProfile.autonomyLevel, "high");
+  assert.match(patch.orgProfile.escalationPath, /CTO/);
+  assert.equal(patch.orgProfile.operatingChannel, "#platform");
+  assert.deepEqual(patch.orgProfile.skills, ["ci-cd", "incident-response"]);
+  assert.equal(patch.orgProfile.reports[0].member.slug, "kai");
+  assert.equal(patch.orgProfile.governance[0].type, "ADVISES");
+});
+
+test("charter/orgProfile absent → no charter/orgProfile keys (empty patch stays empty)", () => {
+  const patch = mapProfileToAgentConfig(PROFILE); // base fixture has neither
+  assert.equal(patch.charter, undefined);
+  assert.equal(patch.orgProfile, undefined);
+  // A charter with no real content is also dropped.
+  const noContent = mapProfileToAgentConfig({ charter: { approvedByLine: "", gatesText: "", sections: [] } });
+  assert.equal(noContent.charter, undefined);
+});
+
+test("deriveFunction + deriveAltitude resolve to valid axes (safe default)", () => {
+  assert.ok(FUNCTIONS.includes(deriveFunction({ role: "sales lead", team: "Revenue" })));
+  assert.equal(deriveFunction({ role: "sales lead", team: "Revenue" }), "commercial-leader");
+  assert.equal(deriveFunction({ role: "general counsel", team: "Legal" }), "compliance-leader");
+  assert.equal(deriveFunction({ role: "weird-unknown-role" }), "executive-operator");
+  assert.ok(ALTITUDES.includes(deriveAltitude({ title: "Chief Technology Officer" })));
+  assert.equal(deriveAltitude({ title: "Chief Technology Officer" }), "c-suite");
+  assert.equal(deriveAltitude({ title: "Senior Manager, Ops" }), "senior-manager");
+  assert.equal(deriveAltitude({ title: "Mystery" }), "c-suite");
+});
+
+test("mergeProfilePatch protects a locally-customised value unless --force", () => {
+  const current = { firstName: "Robin", title: "Custom Title The Operator Set", email: "" };
+  const patch = mapProfileToAgentConfig(PROFILE);
+  const reduced = mergeProfilePatch(current, patch, { force: false });
+  // title is locally set → dropped; email is empty → kept; firstName equals → still set is fine
+  assert.equal(reduced.title, undefined, "local title is NOT clobbered");
+  assert.equal(reduced.email, "robin@example.com", "empty local value gets filled");
+  // With --force, the org value wins.
+  const forced = mergeProfilePatch(current, patch, { force: true });
+  assert.equal(forced.title, "VP of Engineering");
+});
+
+test("mergeProfilePatch reduces nested objects leaf-by-leaf", () => {
+  const current = { principal: { fullName: "Existing Boss", title: "" } };
+  const patch = mapProfileToAgentConfig(PROFILE);
+  const reduced = mergeProfilePatch(current, patch, { force: false });
+  assert.equal(reduced.principal.fullName, undefined, "local principal.fullName kept");
+  assert.equal(reduced.principal.title, "CTO", "empty principal.title filled");
+});
+
+test("mergeProfilePatch treats a placeholder string as unset", () => {
+  const current = { title: "UNCONFIGURED" };
+  const reduced = mergeProfilePatch(current, { title: "VP of Engineering" }, { force: false });
+  assert.equal(reduced.title, "VP of Engineering");
+});
+
+test("diffPatch reports leaf-level changes including nested + array", () => {
+  const before = { title: "Old", principal: { title: "Old VP" } };
+  const patch = { title: "VP of Engineering", principal: { title: "CTO" }, responsibilities: ["a", "b"] };
+  const diff = diffPatch(before, patch);
+  const byPath = Object.fromEntries(diff.map((d) => [d.path, d]));
+  assert.equal(byPath["title"].from, "Old");
+  assert.equal(byPath["title"].to, "VP of Engineering");
+  assert.equal(byPath["principal.title"].to, "CTO");
+  assert.ok(byPath["responsibilities"], "array change is reported");
+});
+
+test("cohortPullEnv gates on api key + org id; agent id optional", () => {
+  assert.equal(cohortPullEnv({}).enabled, false);
+  assert.equal(cohortPullEnv({ COHORT_API_KEY: "k" }).enabled, false);
+  const e = cohortPullEnv({ COHORT_API_KEY: "k", COHORT_ORG_ID: "acme", COHORT_AGENT_ID: "robin" });
+  assert.equal(e.enabled, true);
+  assert.equal(e.apiKey, "k");
+  assert.equal(e.orgId, "acme");
+  assert.equal(e.agentId, "robin");
+});
+
+test("pullAndPlan: with env + mocked profile, plans a patch and a diff", async () => {
+  const root = tmpRoot();
+  writeAgent(root, { firstName: "UNCONFIGURED" });
+  const plan = await pullAndPlan({
+    agentRoot: root,
+    env: { COHORT_API_KEY: "k", COHORT_ORG_ID: "acme", COHORT_AGENT_ID: "robin" },
+    fetchSelfProfileImpl: async () => ({ ok: true, result: PROFILE }),
+  });
+  assert.equal(plan.pulled, true);
+  assert.equal(plan.patch.firstName, "Robin", "placeholder firstName overwritten");
+  assert.equal(plan.patch.email, "robin@example.com");
+  assert.ok(plan.changes.length > 0);
+});
+
+test("pullAndPlan: absent env → not pulled (manual path stands)", async () => {
+  const root = tmpRoot();
+  const plan = await pullAndPlan({
+    agentRoot: root,
+    env: {},
+    fetchSelfProfileImpl: async () => ({ ok: true, result: PROFILE }),
+  });
+  assert.equal(plan.pulled, false);
+  assert.deepEqual(plan.patch, {});
+  assert.deepEqual(plan.changes, []);
+});
+
+test("pullAndPlan: fetch failure → fail-open, not pulled", async () => {
+  const root = tmpRoot();
+  const plan = await pullAndPlan({
+    agentRoot: root,
+    env: { COHORT_API_KEY: "k", COHORT_ORG_ID: "acme" },
+    fetchSelfProfileImpl: async () => ({ ok: false, error: { code: "INTERNAL", message: "down" } }),
+  });
+  assert.equal(plan.pulled, false);
+  assert.deepEqual(plan.patch, {});
+});
+
+test("pullAndPlan: a local override is NOT clobbered without --force", async () => {
+  const root = tmpRoot();
+  writeAgent(root, { title: "My Custom Title" });
+  const env = { COHORT_API_KEY: "k", COHORT_ORG_ID: "acme", COHORT_AGENT_ID: "robin" };
+  const noForce = await pullAndPlan({ agentRoot: root, env, fetchSelfProfileImpl: async () => ({ ok: true, result: PROFILE }) });
+  assert.equal(noForce.patch.title, undefined, "custom title protected");
+  const forced = await pullAndPlan({ agentRoot: root, env, force: true, fetchSelfProfileImpl: async () => ({ ok: true, result: PROFILE }) });
+  assert.equal(forced.patch.title, "VP of Engineering", "--force overwrites");
+});