@cohortapp/agent-sdk 2.3.1 → 2.4.0

package/lib/plan/compile.test.mjs

@@ -0,0 +1,286 @@
+/**
+ * compile.test.mjs — the plan compiler + obligation schema (SPEC §5.6).
+ * Run: node --test lib/plan/compile.test.mjs
+ *
+ * The compiler is PURE, so these tests are pure too: fixture mandate, fixture
+ * manifest, fixture cadence list. No fs, no network, no clock.
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { compilePlan, solveSlot, busyWindows, allowedToolsFor, actionClassesFor, toolNameFor, STANDARD_REACTS, COMPILER_VERSION } from "./compile.mjs";
+import { validatePlan, validateObligation } from "./schema.mjs";
+import { deriveMandate, toMandateBody, pickSensor, slug } from "../mandate/derive.mjs";
+
+/** A small, explicit capability manifest. */
+function manifest(ids = ["board_ready", "task_create", "task_update", "board_claim", "board_complete", "crm_list_deals", "messaging_send", "knowledge_search", "email_inbox", "email_triage", "messaging_history"], unreachable = []) {
+  return {
+    schemaVersion: 1,
+    checksum: "fixture",
+    entries: [
+      ...ids.map((id) => ({ id, plane: "org", kind: "method_tool", reachable: true, blastRadius: id === "messaging_send" ? "external" : id.endsWith("_create") ? "irreversible" : "internal" })),
+      ...unreachable.map((id) => ({ id, plane: "org", kind: "method_tool", reachable: false, blastRadius: "internal" })),
+      { id: "builtin:Read", plane: "builtin", kind: "tool", reachable: true, blastRadius: "internal" },
+    ],
+  };
+}
+
+const STANDARD = [
+  { id: "inbox-processor", scope: "standard", mode: "guarded", interval: 300, prompt: "schedules/triggers/inbox-processor.md" },
+  { id: "daily-morning-brief", scope: "standard", mode: "escalate", calendar: { hour: 6, minute: 30 }, prompt: "schedules/triggers/daily-morning-brief.md" },
+  { id: "nightly-cost-reconcile", scope: "standard", mode: "inline", calendar: { hour: 3, minute: 30 } },
+];
+
+const ARCHETYPE = [
+  { id: "weekly-operating-review", scope: "function", mode: "escalate", cadence: "weekly", calendar: { weekday: 2, hour: 10, minute: 0 }, prompt: "schedules/triggers/weekly-operating-review.md", purpose: "Run the leadership operating review" },
+];
+
+function objective(over = {}) {
+  return {
+    key: "pipeline-coverage", kind: "OBJECTIVE", text: "Pipeline coverage", state: "active",
+    metric: "pipeline_coverage_x", unit: "x", direction: "up", target: 3, tolerance: 0.2,
+    weight: 1, cadence: "weekly", sensor: { capability: "crm_list_deals", params: { stage: "open" }, source: "method" },
+    collaborators: [], id: "obj_7Kx", charterSectionId: "cs_12", ...over,
+  };
+}
+
+test("standard cadences compile to SCHEDULE obligations with VERBATIM triggers", () => {
+  const p = compilePlan({ mandate: {}, manifest: manifest(), standardCadences: STANDARD });
+  const inbox = p.obligations.find((o) => o.key === "schedule.inbox-processor");
+  assert.equal(inbox.kind, "SCHEDULE");
+  assert.deepEqual(inbox.schedule, { interval: 300 });
+  assert.equal(inbox.source.origin, "standard");
+  assert.equal(inbox.scope, "standard");
+  const brief = p.obligations.find((o) => o.key === "schedule.daily-morning-brief");
+  assert.deepEqual(brief.schedule, { calendar: { hour: 6, minute: 30 } }, "trigger copied byte-for-byte so plists do not churn");
+});
+
+test("PROPOSED objectives compile NOTHING — the schedule only grows on human adoption", () => {
+  const proposed = { objectives: [objective({ state: "proposed" })] };
+  const p = compilePlan({ mandate: proposed, manifest: manifest(), standardCadences: STANDARD });
+  assert.equal(p.counts.OUTCOME, 0);
+  assert.equal(p.counts.proposedObjectives, 1);
+  assert.ok(!p.obligations.some((o) => o.key.startsWith("schedule.measure.")));
+});
+
+test("an ADOPTED objective compiles measure + outcome, provenance-linked to the objective and charter clause", () => {
+  const p = compilePlan({ mandate: { objectives: [objective()] }, manifest: manifest(), standardCadences: STANDARD });
+  const measure = p.obligations.find((o) => o.key === "schedule.measure.pipeline-coverage");
+  const outcome = p.obligations.find((o) => o.key === "outcome.pipeline-coverage");
+  assert.ok(measure && outcome);
+  assert.equal(measure.cadence_id, "measure-pipeline-coverage");
+  assert.equal(outcome.objective_id, "obj_7Kx");
+  assert.equal(outcome.source.charter_section, "cs_12");
+  assert.equal(outcome.sensor.capability, "crm_list_deals");
+  assert.equal(outcome.target, 3);
+  // This is what makes it "not a generic cron list":
+  assert.equal(measure.source.origin, "mandate");
+  assert.deepEqual(measure.uses, ["crm_list_deals"]);
+});
+
+test("a REVIEWER collaborator compiles a review cadence", () => {
+  const obj = objective({ collaborators: [{ member_id: "mem_A03", role: "REVIEWER" }] });
+  const p = compilePlan({ mandate: { objectives: [obj] }, manifest: manifest(), standardCadences: [] });
+  const review = p.obligations.find((o) => o.key === "schedule.review.pipeline-coverage");
+  assert.ok(review, "review obligation emitted");
+  assert.equal(review.cadence_id, "review-pipeline-coverage");
+  assert.equal(review.mode, "escalate");
+});
+
+test("an objective whose sensor is UNREACHABLE emits no OUTCOME and opens drift", () => {
+  const p = compilePlan({ mandate: { objectives: [objective()] }, manifest: manifest(["board_ready"], ["crm_list_deals"]), standardCadences: [] });
+  assert.equal(p.counts.OUTCOME, 0);
+  const d = p.drift.find((x) => x.kind === "unreachable_capability");
+  assert.ok(d, `expected unreachable_capability drift, got ${JSON.stringify(p.drift)}`);
+  assert.equal(d.detail.sensor, "crm_list_deals");
+});
+
+test("an objective with a HUMAN sensor emits no OUTCOME and opens stale_sensor drift", () => {
+  const obj = objective({ sensor: { capability: null, params: {}, source: "human" } });
+  const p = compilePlan({ mandate: { objectives: [obj] }, manifest: manifest(), standardCadences: [] });
+  assert.equal(p.counts.OUTCOME, 0);
+  assert.ok(p.drift.some((d) => d.kind === "stale_sensor"));
+});
+
+test("uses[] is filtered against the manifest and every drop is recorded as drift", () => {
+  const p = compilePlan({ mandate: {}, manifest: manifest(["email_inbox"]), standardCadences: STANDARD });
+  const inbox = p.obligations.find((o) => o.key === "schedule.inbox-processor");
+  assert.deepEqual(inbox.uses, ["email_inbox"], "unreachable capabilities are dropped, not cited");
+  assert.ok(p.drift.filter((d) => d.kind === "unreachable_capability" && d.key === "schedule.inbox-processor").length >= 2);
+});
+
+test("allowed_tools is COMPUTED from uses[] — a session-spawning cadence can never be unscoped", () => {
+  const p = compilePlan({ mandate: {}, manifest: manifest(), standardCadences: STANDARD, archetypeCadences: ARCHETYPE });
+  for (const ob of p.obligations.filter((o) => o.kind === "SCHEDULE" && o.mode !== "inline")) {
+    assert.ok(ob.allowed_tools.length > 0, `${ob.key} must carry a tool scope`);
+    assert.ok(ob.allowed_tools.includes("Read"), "baseline read primitives present");
+  }
+  const inline = p.obligations.find((o) => o.key === "schedule.nightly-cost-reconcile");
+  assert.deepEqual(inline.allowed_tools, [], "an inline cadence spawns no session and needs no scope");
+});
+
+test("action_classes are derived from the manifest's blast radii", () => {
+  assert.deepEqual(actionClassesFor(["messaging_send", "board_ready"], manifest()), ["external"]);
+  assert.deepEqual(actionClassesFor(["board_ready"], manifest()), []);
+});
+
+test("toolNameFor maps every plane onto a session tool name", () => {
+  assert.equal(toolNameFor("builtin:Read"), "Read");
+  assert.equal(toolNameFor("skill:agent-skills:morning-brief"), "Skill");
+  assert.equal(toolNameFor("workflow:weekly-operating-review"), "Task");
+  assert.equal(toolNameFor("mcp:notion"), "mcp__notion__*");
+  assert.equal(toolNameFor("board_ready"), "board_ready");
+  assert.deepEqual(allowedToolsFor(["board_ready", "builtin:Read"]), ["Glob", "Grep", "LS", "Read", "board_ready"]);
+});
+
+test("the four standard REACT obligations always compile", () => {
+  const p = compilePlan({ mandate: {}, manifest: manifest(["email_message", "email_thread", "email_send", "board_ready", "board_claim", "task_update", "approval_wait", "decision_list"]), standardCadences: [] });
+  for (const r of STANDARD_REACTS) assert.ok(p.obligations.some((o) => o.key === r.key), `${r.key} missing`);
+  assert.equal(p.counts.REACT, STANDARD_REACTS.length);
+});
+
+test("mandate reactsTo[] adds REACT obligations bound to an objective", () => {
+  const mandate = { objectives: [], reactsTo: [{ key: "react.mandate.deal-stalled", topic: "task", kind: "stalled", uses: ["crm_list_deals"], objectiveId: "obj_7Kx", offlineSafe: true }] };
+  const p = compilePlan({ mandate, manifest: manifest(), standardCadences: [] });
+  const r = p.obligations.find((o) => o.key === "react.mandate.deal-stalled");
+  assert.equal(r.kind, "REACT");
+  assert.equal(r.objective_id, "obj_7Kx");
+  assert.equal(r.offline_safe, true);
+  assert.equal(r.source.origin, "mandate");
+});
+
+test("DETERMINISM: identical inputs → identical obligationsHash; a changed mandate changes it", () => {
+  const a = compilePlan({ mandate: { objectives: [objective()] }, manifest: manifest(), standardCadences: STANDARD, archetypeCadences: ARCHETYPE });
+  const b = compilePlan({ mandate: { objectives: [objective()] }, manifest: manifest(), standardCadences: STANDARD, archetypeCadences: ARCHETYPE });
+  assert.equal(a.obligationsHash, b.obligationsHash);
+  assert.equal(a.inputsHash, b.inputsHash);
+  const c = compilePlan({ mandate: { objectives: [objective({ target: 4 })] }, manifest: manifest(), standardCadences: STANDARD, archetypeCadences: ARCHETYPE });
+  assert.notEqual(a.inputsHash, c.inputsHash, "a different mandate is a different plan input");
+});
+
+test("DETERMINISM: objective input ORDER does not change the emitted schedule", () => {
+  const o1 = objective();
+  const o2 = objective({ key: "decision-latency", id: "obj_2", metric: "decision_days", cadence: "monthly", weight: 1 });
+  const a = compilePlan({ mandate: { objectives: [o1, o2] }, manifest: manifest(), standardCadences: [] });
+  const b = compilePlan({ mandate: { objectives: [o2, o1] }, manifest: manifest(), standardCadences: [] });
+  assert.equal(a.obligationsHash, b.obligationsHash);
+});
+
+test("slot solver: deterministic, avoids the principal's busy hours, respects the concurrency cap", () => {
+  const busy = busyWindows([{ weekday: 1, hour: 9 }, { weekday: 1, hour: 10 }]);
+  const state = { busy, taken: new Map(), concurrency: 1 };
+  const a = solveSlot("schedule.measure.alpha", "weekly", state);
+  const b = solveSlot("schedule.measure.beta", "weekly", state);
+  assert.notDeepEqual(a.calendar, b.calendar, "the cap forces distinct slots");
+  for (const s of [a, b]) assert.ok(!busy.has(`${s.calendar.weekday}:${s.calendar.hour}`), "never lands in a busy window");
+  // Same key, fresh state → same slot, forever.
+  const again = solveSlot("schedule.measure.alpha", "weekly", { busy, taken: new Map(), concurrency: 1 });
+  assert.deepEqual(again.calendar, a.calendar);
+});
+
+test("budget envelope: objectives past the envelope are SUSPENDED with a breach record, never dropped", () => {
+  const objs = [
+    objective({ key: "a", id: "a", weight: 3 }),
+    objective({ key: "b", id: "b", weight: 2 }),
+    objective({ key: "c", id: "c", weight: 1 }),
+  ];
+  const p = compilePlan({ mandate: { objectives: objs, budgetCentsPerPeriod: 500 }, manifest: manifest(), standardCadences: [], seatBudgetCents: 1000 });
+  const suspended = p.obligations.filter((o) => o.status === "suspended");
+  assert.ok(suspended.length > 0, "the third objective exceeds the envelope");
+  assert.ok(p.drift.some((d) => d.kind === "budget_breach"));
+  assert.equal(p.obligations.filter((o) => o.kind === "OUTCOME").length, 3, "all three still exist — suspended, not dropped");
+});
+
+test("validatePlan is FAIL-CLOSED on an unreachable citation and on an llm-sourced OUTCOME", () => {
+  const reachable = new Set(["board_ready"]);
+  const bad = {
+    obligations: [{
+      key: "outcome.x", kind: "OUTCOME", source: { origin: "mandate", ref: "x" }, status: "active",
+      uses: ["ghost_tool"], allowed_tools: ["Read"], action_classes: [], offline_safe: true,
+      objective_id: "obj", sensor: { source: "llm", capability: null },
+    }],
+  };
+  const v = validatePlan(bad, { reachable });
+  assert.equal(v.ok, false);
+  assert.ok(v.errors.some((e) => /not reachable:true/.test(e)));
+  assert.ok(v.errors.some((e) => /"llm" cannot back an OUTCOME/.test(e)));
+});
+
+test("validateObligation rejects a session-spawning SCHEDULE with no tool scope", () => {
+  const errs = validateObligation({
+    key: "schedule.x", kind: "SCHEDULE", source: { origin: "archetype", ref: "x" }, status: "active",
+    mode: "escalate", schedule: { interval: 600 }, uses: [], allowed_tools: [], action_classes: [], offline_safe: false,
+  });
+  assert.ok(errs.some((e) => /non-empty allowed_tools/.test(e)));
+});
+
+test("a full compiled plan validates against the manifest", () => {
+  const m = manifest();
+  const p = compilePlan({ mandate: { objectives: [objective()] }, manifest: m, standardCadences: STANDARD, archetypeCadences: ARCHETYPE });
+  const v = validatePlan(p, { manifest: m });
+  assert.equal(v.ok, true, v.errors.join("; "));
+  assert.equal(p.compilerVersion, COMPILER_VERSION);
+});
+
+// ── derivation (the "per-agent and justified, not a static list" property) ───
+
+test("deriveMandate: charter pillars become PILLARs, KPI categories become OBJECTIVEs parented to them", () => {
+  const d = deriveMandate({
+    charterSections: [
+      { kind: "PILLAR", order: 0, body: "1) Own the agent-platform substrate — runtime, memory, tools." },
+      { kind: "PILLAR", order: 1, body: "2) Make the fleet governable: every capability observable." },
+    ],
+    kpiCategories: [{ id: "execution", name: "Execution & Follow-Through", examples: ["Commitment-closure rate"] }],
+    manifest: manifest(),
+  });
+  assert.equal(d.counts.pillars, 2);
+  assert.equal(d.counts.objectives, 1);
+  const exec = d.objectives.find((o) => o.key === "execution");
+  assert.equal(exec.kind, "OBJECTIVE");
+  assert.ok(exec.parentKey, "every objective hangs off a pillar (provenance)");
+  assert.equal(exec.state, "proposed", "NOTHING is adopted by the agent");
+  assert.equal(exec.sensor.source, "method");
+  assert.equal(exec.sensor.capability, "board_ready", "bound to a REACHABLE capability");
+});
+
+test("deriveMandate: two different agents (different charters/KPIs) get different mandates", () => {
+  const a = deriveMandate({ charterSections: [{ kind: "PILLAR", order: 0, body: "Own revenue growth" }], kpiCategories: [{ id: "pipeline", name: "Pipeline coverage" }], manifest: manifest() });
+  const b = deriveMandate({ charterSections: [{ kind: "PILLAR", order: 0, body: "Own compliance posture" }], kpiCategories: [{ id: "audit", name: "Audit findings closed" }], manifest: manifest() });
+  assert.notDeepEqual(a.objectives.map((o) => o.key), b.objectives.map((o) => o.key));
+});
+
+test("deriveMandate: a metric with no REACHABLE sensor is proposed source:human AND flagged", () => {
+  const d = deriveMandate({ kpiCategories: [{ id: "pipeline", name: "Pipeline coverage", examples: ["Pipeline coverage x"] }], manifest: manifest(["board_ready"]) });
+  const o = d.objectives[0];
+  assert.equal(o.sensor.source, "human");
+  assert.ok(d.degradations.some((x) => x.kind === "no_reachable_sensor"));
+});
+
+test("deriveMandate is deterministic and slug keys are stable", () => {
+  const input = { charterSections: [{ kind: "PILLAR", order: 0, body: "3) Scale the platform with the roster, not after it." }], kpiCategories: [], manifest: manifest() };
+  assert.deepEqual(deriveMandate(input).objectives, deriveMandate(input).objectives);
+  assert.equal(slug("3) Scale the platform with the roster, not after it."), "scale-the-platform-with-the-roster-not-after-it");
+});
+
+test("pickSensor prefers the most specific reachable capability", () => {
+  assert.equal(pickSensor("weekly pipeline coverage", new Set(["crm_list_deals"])).capability, "crm_list_deals");
+  assert.equal(pickSensor("decision cycle time", new Set(["decision_list"])).capability, "decision_list");
+  assert.equal(pickSensor("something unmodelled", new Set(["board_ready"])).source, "human");
+});
+
+test("end to end: derive → compile produces a plan whose obligations trace back to the charter", () => {
+  const d = deriveMandate({
+    charterSections: [{ kind: "PILLAR", order: 0, id: "cs_1", body: "Own execution follow-through" }],
+    kpiCategories: [{ id: "execution", name: "Execution & Follow-Through", examples: ["Commitment-closure rate"] }],
+    manifest: manifest(),
+  });
+  // Simulate the human adoption step in hq.
+  const adopted = d.objectives.map((o) => (o.kind === "OBJECTIVE" ? { ...o, state: "active", target: 0.95, id: `obj_${o.key}` } : o));
+  const p = compilePlan({ mandate: toMandateBody({ objectives: adopted }), manifest: manifest(), standardCadences: STANDARD });
+  const outcome = p.obligations.find((o) => o.kind === "OUTCOME");
+  assert.ok(outcome, "adoption turns the proposal into a real obligation");
+  assert.equal(outcome.target, 0.95);
+  assert.equal(validatePlan(p, { manifest: manifest() }).ok, true);
+});

package/lib/plan/emit.mjs

@@ -0,0 +1,256 @@
+/**
+ * lib/plan/emit.mjs — turn compiled obligations into the files the runtime
+ * already reads (SPEC §5.7).
+ *
+ * The whole point of this design is that it grows NO second scheduling
+ * mechanism. The compiler produces obligations; this module projects them onto
+ * the four artefacts that already exist and are already consumed:
+ *
+ *   config/plan.yaml             ← NEW, and TRACKED: the reviewable obligation
+ *                                  set. A schedule change shows up in a PR diff.
+ *   config/cadences.yaml         ← unchanged format, new producer
+ *                                  (read by cadence-handlers to route ticks)
+ *   config/.cadence-plists.tsv   ← unchanged format, new producer
+ *                                  (read verbatim by generate-plists.sh, which
+ *                                   needs NO edit to emit real launchd jobs)
+ *   config/.cadence-registry.json ← EXTENDED shape
+ *                                  {mode, prompt, allowedTools, guardModule,
+ *                                   budgetCents, obligationKey}
+ *   state/plan/compile.lock      ← the hashes verify() checks
+ *
+ * FAIL-CLOSED: the plan is validated before a single byte is written. A plan
+ * that cites an unreachable capability, or a session-spawning cadence with no
+ * tool scope, is not written at all — a half-written schedule is how a launchd
+ * job silently goes missing.
+ *
+ * NON-DESTRUCTIVE by construction: standard cadences carry their triggers
+ * verbatim from `STANDARD_CADENCES` and are excluded from the TSV exactly as the
+ * old generator excluded them (generate-plists.sh emits the standard set
+ * itself), so re-emitting an unchanged plan produces byte-identical files and no
+ * plist churns.
+ *
+ * @module lib/plan/emit
+ */
+
+"use strict";
+
+import { writeFileSync, mkdirSync, renameSync, existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { validatePlan } from "./schema.mjs";
+
+/** Relative paths this module owns. */
+export const PLAN_REL = join("config", "plan.yaml");
+export const CADENCES_REL = join("config", "cadences.yaml");
+export const REGISTRY_REL = join("config", ".cadence-registry.json");
+export const TSV_REL = join("config", ".cadence-plists.tsv");
+export const LOCK_REL = join("state", "plan", "compile.lock");
+
+/**
+ * Build the StartCalendarInterval dict-content XML `generate_trigger_plist`
+ * expects. Byte-for-byte the same shape generate-cadences.mjs emitted, so an
+ * unchanged cadence yields an unchanged base64 blob and an unchanged plist.
+ */
+export function scheduleXml(cal) {
+  let x = "";
+  if (cal.weekday != null) x += `        <key>Weekday</key>\n        <integer>${cal.weekday}</integer>\n`;
+  if (cal.day != null) x += `        <key>Day</key>\n        <integer>${cal.day}</integer>\n`;
+  x += `        <key>Hour</key>\n        <integer>${cal.hour ?? 9}</integer>\n        <key>Minute</key>\n        <integer>${cal.minute ?? 0}</integer>`;
+  return x;
+}
+
+/** Project SCHEDULE obligations onto the legacy cadences.yaml entry shape. */
+export function toCadenceEntries(obligations) {
+  const out = [];
+  for (const ob of obligations || []) {
+    if (ob.kind !== "SCHEDULE" || ob.status !== "active") continue;
+    const entry = {
+      id: ob.cadence_id,
+      scope: ob.scope || "mandate",
+      mode: ob.mode || "escalate",
+      prompt: ob.prompt || `schedules/triggers/${ob.cadence_id}.md`,
+    };
+    if (ob.schedule && Number.isFinite(ob.schedule.interval)) entry.interval = ob.schedule.interval;
+    else if (ob.schedule && ob.schedule.calendar) entry.calendar = ob.schedule.calendar;
+    if (ob.purpose) entry.purpose = ob.purpose;
+    if (ob.cadence) entry.cadence = ob.cadence;
+    entry.obligationKey = ob.key;
+    out.push(entry);
+  }
+  return out;
+}
+
+/**
+ * The EXTENDED cadence registry (SPEC §4): a plan-derived cadence gets a guard
+ * and a tool scope by construction, so `sessionPermissionArgs()` can scope the
+ * spawn and the consumer can meter its budget.
+ */
+export function toRegistry(obligations) {
+  const reg = {};
+  for (const ob of obligations || []) {
+    if (ob.kind !== "SCHEDULE" || ob.status !== "active") continue;
+    reg[ob.cadence_id] = {
+      mode: ob.mode || "escalate",
+      prompt: ob.prompt || `schedules/triggers/${ob.cadence_id}.md`,
+      allowedTools: Array.isArray(ob.allowed_tools) ? ob.allowed_tools : [],
+      guardModule: ob.guard_module || null,
+      budgetCents: Number.isFinite(ob.budget_cents_per_period) ? ob.budget_cents_per_period : null,
+      obligationKey: ob.key,
+    };
+  }
+  return reg;
+}
+
+/**
+ * The launchd TSV. Standard-scope cadences are EXCLUDED (generate-plists.sh
+ * emits those itself) — identical to the old generator's rule.
+ * Pipe-delimited: `<id>|<interval>|<base64(calendar xml)>`.
+ */
+export function toTsvLines(obligations) {
+  const lines = [];
+  for (const ob of obligations || []) {
+    if (ob.kind !== "SCHEDULE" || ob.status !== "active") continue;
+    if (ob.scope === "standard") continue;
+    if (ob.schedule && Number.isFinite(ob.schedule.interval)) lines.push(`${ob.cadence_id}|${ob.schedule.interval}|`);
+    else if (ob.schedule && ob.schedule.calendar) lines.push(`${ob.cadence_id}||${Buffer.from(scheduleXml(ob.schedule.calendar), "utf-8").toString("base64")}`);
+  }
+  return lines;
+}
+
+/** The obligation projection written to config/plan.yaml (SPEC §5.6 shape). */
+export function toPlanDoc(plan, o = {}) {
+  return {
+    schemaVersion: 1,
+    compilerVersion: plan.compilerVersion,
+    mandateVersion: plan.mandateVersion,
+    enforcement: o.enforcement || "observe-only",
+    archetype: o.archetype || null,
+    generatedAt: o.at || null,
+    inputsHash: plan.inputsHash,
+    obligationsHash: plan.obligationsHash,
+    counts: plan.counts,
+    obligations: (plan.obligations || []).map((ob) => {
+      const y = {
+        key: ob.key,
+        kind: ob.kind,
+        source: ob.source,
+        status: ob.status,
+        uses: ob.uses || [],
+        allowed_tools: ob.allowed_tools || [],
+        action_classes: ob.action_classes || [],
+        budget_cents_per_period: ob.budget_cents_per_period,
+        offline_safe: ob.offline_safe,
+      };
+      if (ob.objective_id) y.objective_id = ob.objective_id;
+      if (ob.cadence_id) y.cadence_id = ob.cadence_id;
+      if (ob.schedule) y.schedule = ob.schedule;
+      if (ob.trigger) y.trigger = ob.trigger;
+      if (ob.sensor) y.sensor = ob.sensor;
+      if (ob.metric) y.metric = ob.metric;
+      if (ob.target != null) y.target = ob.target;
+      if (ob.direction) y.direction = ob.direction;
+      if (ob.tolerance != null) y.tolerance = ob.tolerance;
+      if (ob.cadence) y.cadence = ob.cadence;
+      if (ob.mode) y.mode = ob.mode;
+      if (ob.prompt) y.prompt = ob.prompt;
+      if (ob.guard_module) y.guard_module = ob.guard_module;
+      if (ob.collaborators && ob.collaborators.length) y.collaborators = ob.collaborators;
+      if (ob.purpose) y.purpose = ob.purpose;
+      return y;
+    }),
+  };
+}
+
+/**
+ * Write every artefact. Fail-closed on validation.
+ *
+ * @param {object} o - { agentRoot, plan, manifest, archetype?, enforcement?, at? }
+ * @param {object} [deps] - { writeFileSync, mkdirSync, renameSync, yaml }
+ * @returns {Promise<{ok:boolean, errors:string[], files:string[], cadences:object[], registry:object, tsv:string[]}>}
+ */
+export async function emitPlan(o = {}, deps = {}) {
+  const { agentRoot, plan } = o;
+  if (!agentRoot) throw new Error("emitPlan: agentRoot required");
+
+  const v = validatePlan(plan, { manifest: o.manifest });
+  if (!v.ok) {
+    // FAIL-CLOSED, and loudly: nothing is written, and the caller gets every reason.
+    return { ok: false, errors: v.errors, files: [], cadences: [], registry: {}, tsv: [] };
+  }
+
+  const yaml = deps.yaml || (await loadYaml());
+  const wr = deps.writeFileSync || writeFileSync;
+  const mk = deps.mkdirSync || mkdirSync;
+  const mv = deps.renameSync || renameSync;
+  const atomic = (rel, body) => {
+    const p = join(agentRoot, rel);
+    mk(dirOf(p), { recursive: true });
+    const tmp = `${p}.${process.pid}.tmp`;
+    wr(tmp, body, "utf-8");
+    mv(tmp, p);
+    return p;
+  };
+
+  const cadences = toCadenceEntries(plan.obligations);
+  const registry = toRegistry(plan.obligations);
+  const tsv = toTsvLines(plan.obligations);
+  const files = [];
+
+  // NO-OP GUARD (SPEC §6.4: "if obligationsHash is unchanged, nothing on disk
+  // moves"). config/plan.yaml is TRACKED, and its `generatedAt` is a wall clock:
+  // without this, every recompile — including the ones the org-pulse cadence
+  // fires on an unchanged mandate — rewrites the one artefact whose whole job is
+  // to make a schedule change legible in a PR diff. The result was a file that
+  // churned constantly and therefore proved nothing.
+  //
+  // Identity is the two hashes, not the bytes: inputsHash covers the mandate +
+  // manifest + profile + org strategy + compiler version, obligationsHash covers
+  // the emitted schedule. Equal on both ⇒ genuinely nothing to say.
+  if (!o.force) {
+    const ex = deps.existsSync || existsSync;
+    const prior = readLock(agentRoot, deps);
+    const same = prior
+      && prior.compilerVersion === plan.compilerVersion
+      && prior.inputsHash === plan.inputsHash
+      && prior.obligationsHash === plan.obligationsHash;
+    const allPresent = [PLAN_REL, CADENCES_REL, REGISTRY_REL, TSV_REL].every((rel) => ex(join(agentRoot, rel)));
+    if (same && allPresent) {
+      return { ok: true, unchanged: true, errors: [], files: [], cadences, registry, tsv };
+    }
+  }
+
+  files.push(atomic(PLAN_REL, yaml.dump(toPlanDoc(plan, o), { lineWidth: 100, noRefs: true, sortKeys: false })));
+  files.push(atomic(CADENCES_REL, yaml.dump({ archetype: o.archetype || null, source: "plan-compiler", cadences }, { lineWidth: 100, noRefs: true })));
+  files.push(atomic(REGISTRY_REL, JSON.stringify(registry, null, 2) + "\n"));
+  files.push(atomic(TSV_REL, tsv.join("\n") + (tsv.length ? "\n" : "")));
+  files.push(atomic(LOCK_REL, JSON.stringify({
+    compilerVersion: plan.compilerVersion,
+    inputsHash: plan.inputsHash,
+    obligationsHash: plan.obligationsHash,
+    mandateVersion: plan.mandateVersion,
+    at: o.at || null,
+  }, null, 2) + "\n"));
+
+  return { ok: true, errors: [], files, cadences, registry, tsv };
+}
+
+/** Read state/plan/compile.lock (null when absent/unparseable). */
+export function readLock(agentRoot, deps = {}) {
+  const ex = deps.existsSync || existsSync;
+  const rd = deps.readFileSync || readFileSync;
+  const p = join(agentRoot, LOCK_REL);
+  if (!ex(p)) return null;
+  try { return JSON.parse(rd(p, "utf-8")); } catch { return null; }
+}
+
+/** Directory of a path (avoids importing path.dirname twice over). */
+function dirOf(p) {
+  const i = p.lastIndexOf("/");
+  return i > 0 ? p.slice(0, i) : ".";
+}
+
+async function loadYaml() {
+  const m = await import("js-yaml");
+  return m && m.default ? m.default : m;
+}
+
+export default { emitPlan, toCadenceEntries, toRegistry, toTsvLines, toPlanDoc, scheduleXml, readLock, PLAN_REL, CADENCES_REL, REGISTRY_REL, TSV_REL, LOCK_REL };