@cohortapp/agent-sdk 2.3.2 → 2.4.0

package/lib/plan/emit.test.mjs

@@ -0,0 +1,246 @@
+/**
+ * emit.test.mjs — obligations → the files the runtime already reads (SPEC §5.7).
+ * Run: node --test lib/plan/emit.test.mjs
+ *
+ * The contract under test is compatibility: cadences.yaml, .cadence-registry.json
+ * and .cadence-plists.tsv must keep the EXACT shapes their existing consumers
+ * (cadence-handlers.mjs, session-permissions.mjs, generate-plists.sh) already
+ * parse — new producer, unchanged formats.
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import yaml from "js-yaml";
+
+import { emitPlan, toCadenceEntries, toRegistry, toTsvLines, scheduleXml, readLock, PLAN_REL, CADENCES_REL, REGISTRY_REL, TSV_REL, LOCK_REL } from "./emit.mjs";
+import { compilePlan } from "./compile.mjs";
+
+const AT = "2026-08-11T09:00:00.000Z";
+
+function manifest() {
+  return {
+    schemaVersion: 1,
+    checksum: "fixture",
+    entries: ["board_ready", "task_create", "task_update", "board_claim", "board_complete", "crm_list_deals", "knowledge_search", "email_inbox", "email_triage", "messaging_history", "messaging_send", "email_message", "email_thread", "email_send", "approval_wait", "decision_list"]
+      .map((id) => ({ id, plane: "org", kind: "method_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" },
+];
+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: "Operating review" },
+  { id: "org-cost-sync-fn", scope: "function", mode: "inline", interval: 3600 },
+];
+
+function adoptedObjective() {
+  return {
+    key: "pipeline-coverage", kind: "OBJECTIVE", text: "Pipeline coverage", state: "active", id: "obj_7Kx",
+    metric: "pipeline_coverage_x", direction: "up", target: 3, tolerance: 0.2, weight: 1, cadence: "weekly",
+    sensor: { capability: "crm_list_deals", params: { stage: "open" }, source: "method" }, collaborators: [],
+  };
+}
+
+function planWith(objectives = []) {
+  return compilePlan({ mandate: { objectives }, manifest: manifest(), standardCadences: STANDARD, archetypeCadences: ARCHETYPE });
+}
+
+function tmpRoot() { return mkdtempSync(join(tmpdir(), "maestro-emit-")); }
+
+test("emitPlan writes all five artefacts", async () => {
+  const root = tmpRoot();
+  const r = await emitPlan({ agentRoot: root, plan: planWith([adoptedObjective()]), manifest: manifest(), archetype: "executive-operator@c-suite", at: AT });
+  assert.equal(r.ok, true, r.errors.join("; "));
+  for (const rel of [PLAN_REL, CADENCES_REL, REGISTRY_REL, TSV_REL, LOCK_REL]) {
+    assert.ok(existsSync(join(root, rel)), `${rel} written`);
+  }
+});
+
+test("config/cadences.yaml keeps the shape cadence-handlers already parses", async () => {
+  const root = tmpRoot();
+  await emitPlan({ agentRoot: root, plan: planWith([adoptedObjective()]), manifest: manifest(), archetype: "executive-operator@c-suite", at: AT });
+  const doc = yaml.load(readFileSync(join(root, CADENCES_REL), "utf8"));
+  assert.equal(doc.archetype, "executive-operator@c-suite");
+  const inbox = doc.cadences.find((c) => c.id === "inbox-processor");
+  assert.equal(inbox.interval, 300);
+  assert.equal(inbox.mode, "guarded");
+  assert.equal(inbox.prompt, "schedules/triggers/inbox-processor.md");
+  assert.equal(inbox.scope, "standard");
+  // the plan-derived measure cadence is a first-class cadence id
+  assert.ok(doc.cadences.some((c) => c.id === "measure-pipeline-coverage"));
+});
+
+test(".cadence-registry.json carries the EXTENDED shape session-permissions can scope on", async () => {
+  const root = tmpRoot();
+  await emitPlan({ agentRoot: root, plan: planWith([adoptedObjective()]), manifest: manifest(), at: AT });
+  const reg = JSON.parse(readFileSync(join(root, REGISTRY_REL), "utf8"));
+  const m = reg["measure-pipeline-coverage"];
+  assert.equal(m.mode, "guarded");
+  assert.equal(m.guardModule, "lib/goals/loop.mjs");
+  assert.equal(m.obligationKey, "schedule.measure.pipeline-coverage");
+  assert.ok(Number.isFinite(m.budgetCents));
+  assert.ok(Array.isArray(m.allowedTools) && m.allowedTools.includes("crm_list_deals"));
+  // Back-compat: {mode, prompt} still present for every entry.
+  for (const [id, def] of Object.entries(reg)) {
+    assert.ok(def.mode, `${id} has a mode`);
+    assert.ok(def.prompt, `${id} has a prompt`);
+  }
+});
+
+test(".cadence-plists.tsv is pipe-delimited, EXCLUDES standard cadences, and decodes to launchd XML", async () => {
+  const root = tmpRoot();
+  await emitPlan({ agentRoot: root, plan: planWith([adoptedObjective()]), manifest: manifest(), at: AT });
+  const lines = readFileSync(join(root, TSV_REL), "utf8").trim().split("\n");
+  assert.ok(lines.length > 0);
+  assert.ok(!lines.some((l) => l.startsWith("inbox-processor|")), "generate-plists.sh emits the standard set itself");
+  const interval = lines.find((l) => l.startsWith("org-cost-sync-fn|"));
+  assert.equal(interval, "org-cost-sync-fn|3600|");
+  const cal = lines.find((l) => l.startsWith("weekly-operating-review|"));
+  const [, empty, b64] = cal.split("|");
+  assert.equal(empty, "");
+  const xml = Buffer.from(b64, "base64").toString("utf8");
+  assert.match(xml, /<key>Weekday<\/key>\n\s+<integer>2<\/integer>/);
+  assert.match(xml, /<key>Hour<\/key>\n\s+<integer>10<\/integer>/);
+  // the derived measure cadence becomes a REAL launchd job
+  assert.ok(lines.some((l) => l.startsWith("measure-pipeline-coverage||")));
+});
+
+test("scheduleXml output is byte-identical to the legacy generator's shape", () => {
+  assert.equal(
+    scheduleXml({ weekday: 2, hour: 10, minute: 0 }),
+    "        <key>Weekday</key>\n        <integer>2</integer>\n        <key>Hour</key>\n        <integer>10</integer>\n        <key>Minute</key>\n        <integer>0</integer>",
+  );
+});
+
+test("IDEMPOTENT: re-emitting an unchanged plan produces byte-identical files (no plist churn)", async () => {
+  const root = tmpRoot();
+  const plan = planWith([adoptedObjective()]);
+  await emitPlan({ agentRoot: root, plan, manifest: manifest(), at: AT });
+  const before = [CADENCES_REL, REGISTRY_REL, TSV_REL].map((r) => readFileSync(join(root, r), "utf8"));
+  await emitPlan({ agentRoot: root, plan: planWith([adoptedObjective()]), manifest: manifest(), at: AT });
+  const after = [CADENCES_REL, REGISTRY_REL, TSV_REL].map((r) => readFileSync(join(root, r), "utf8"));
+  assert.deepEqual(after, before);
+});
+
+test("FAIL-CLOSED: an invalid plan writes NOTHING", async () => {
+  const root = tmpRoot();
+  const bad = {
+    compilerVersion: 1, mandateVersion: 0, inputsHash: "x", obligationsHash: "y", counts: {},
+    obligations: [{
+      key: "schedule.ghost", kind: "SCHEDULE", source: { origin: "archetype", ref: "ghost" }, status: "active",
+      mode: "escalate", schedule: { interval: 600 }, cadence_id: "ghost",
+      uses: ["ghost_tool"], allowed_tools: ["Read"], action_classes: [], offline_safe: false,
+    }],
+  };
+  const r = await emitPlan({ agentRoot: root, plan: bad, manifest: manifest(), at: AT });
+  assert.equal(r.ok, false);
+  assert.ok(r.errors.some((e) => /not reachable:true/.test(e)));
+  for (const rel of [PLAN_REL, CADENCES_REL, REGISTRY_REL, TSV_REL, LOCK_REL]) {
+    assert.equal(existsSync(join(root, rel)), false, `${rel} must NOT exist after a failed validation`);
+  }
+});
+
+test("compile.lock carries the hashes verify() checks", async () => {
+  const root = tmpRoot();
+  const plan = planWith([adoptedObjective()]);
+  await emitPlan({ agentRoot: root, plan, manifest: manifest(), at: AT });
+  const lock = readLock(root);
+  assert.equal(lock.obligationsHash, plan.obligationsHash);
+  assert.equal(lock.inputsHash, plan.inputsHash);
+  assert.equal(lock.compilerVersion, plan.compilerVersion);
+  assert.equal(lock.at, AT);
+});
+
+test("config/plan.yaml is the reviewable obligation set (provenance + sensor + tool scope)", async () => {
+  const root = tmpRoot();
+  await emitPlan({ agentRoot: root, plan: planWith([adoptedObjective()]), manifest: manifest(), enforcement: "observe-only", at: AT });
+  const doc = yaml.load(readFileSync(join(root, PLAN_REL), "utf8"));
+  assert.equal(doc.enforcement, "observe-only");
+  const outcome = doc.obligations.find((o) => o.key === "outcome.pipeline-coverage");
+  assert.equal(outcome.objective_id, "obj_7Kx");
+  assert.equal(outcome.sensor.capability, "crm_list_deals");
+  assert.equal(outcome.source.origin, "mandate");
+  assert.ok(Array.isArray(outcome.allowed_tools));
+});
+
+test("SUSPENDED obligations are in plan.yaml but never in the schedule artefacts", () => {
+  const obs = [
+    { key: "schedule.a", kind: "SCHEDULE", cadence_id: "a", scope: "mandate", mode: "guarded", prompt: "p.md", schedule: { interval: 60 }, status: "suspended", uses: [], allowed_tools: ["Read"], action_classes: [], offline_safe: true, source: { origin: "mandate", ref: "a" }, budget_cents_per_period: 100 },
+    { key: "schedule.b", kind: "SCHEDULE", cadence_id: "b", scope: "mandate", mode: "guarded", prompt: "p.md", schedule: { interval: 60 }, status: "active", uses: [], allowed_tools: ["Read"], action_classes: [], offline_safe: true, source: { origin: "mandate", ref: "b" }, budget_cents_per_period: 100 },
+  ];
+  assert.deepEqual(toCadenceEntries(obs).map((c) => c.id), ["b"]);
+  assert.deepEqual(Object.keys(toRegistry(obs)), ["b"]);
+  assert.deepEqual(toTsvLines(obs), ["b|60|"]);
+});
+
+// ---------------------------------------------------------------------------
+// The no-op guard (SPEC §6.4: "if obligationsHash is unchanged, nothing on disk
+// moves"). config/plan.yaml is TRACKED, so a recompile that changes nothing must
+// not rewrite it — otherwise the one artefact meant to make a schedule change
+// legible in a PR diff churns on every org-pulse tick and proves nothing.
+// ---------------------------------------------------------------------------
+
+test("a re-emit with identical inputs moves NOTHING on disk", async () => {
+  const root = tmpRoot();
+  const opts = { agentRoot: root, manifest: manifest(), archetype: "executive-operator@c-suite" };
+
+  const first = await emitPlan({ ...opts, plan: planWith([adoptedObjective()]), at: AT });
+  assert.equal(first.ok, true);
+  assert.equal(first.files.length, 5);
+  const before = [PLAN_REL, CADENCES_REL, REGISTRY_REL, TSV_REL].map((rel) => readFileSync(join(root, rel), "utf-8"));
+
+  // Same inputs, LATER wall clock — the only thing that would otherwise differ.
+  const second = await emitPlan({ ...opts, plan: planWith([adoptedObjective()]), at: "2026-09-01T12:00:00.000Z" });
+  assert.equal(second.ok, true);
+  assert.equal(second.unchanged, true, "the re-emit is reported as a no-op");
+  assert.deepEqual(second.files, [], "no file was rewritten");
+
+  const after = [PLAN_REL, CADENCES_REL, REGISTRY_REL, TSV_REL].map((rel) => readFileSync(join(root, rel), "utf-8"));
+  assert.deepEqual(after, before, "every artefact is byte-identical");
+  // The derived views are still returned, so a caller can report on them.
+  assert.ok(second.cadences.length > 0 && Object.keys(second.registry).length > 0);
+});
+
+test("a CHANGED mandate still re-emits (the guard is not a freeze)", async () => {
+  const root = tmpRoot();
+  const opts = { agentRoot: root, manifest: manifest(), archetype: "executive-operator@c-suite", at: AT };
+
+  await emitPlan({ ...opts, plan: planWith([]) });
+  const beforeTsv = readFileSync(join(root, TSV_REL), "utf-8");
+
+  // Adopting an objective adds measure/outcome obligations → new hashes.
+  const changed = await emitPlan({ ...opts, plan: planWith([adoptedObjective()]) });
+  assert.equal(changed.unchanged, undefined, "a real change is not a no-op");
+  assert.equal(changed.files.length, 5);
+  assert.notEqual(readFileSync(join(root, TSV_REL), "utf-8"), beforeTsv, "the launchd TSV was updated");
+  assert.equal(readLock(root).obligationsHash, planWith([adoptedObjective()]).obligationsHash);
+});
+
+test("the guard re-emits when a tracked artefact was deleted underneath it", async () => {
+  const root = tmpRoot();
+  const opts = { agentRoot: root, manifest: manifest(), at: AT };
+  await emitPlan({ ...opts, plan: planWith([adoptedObjective()]) });
+
+  // Hashes still match, but the file is gone — a missing launchd TSV must be
+  // rebuilt, not skipped because the lock looks satisfied.
+  const { rmSync } = await import("node:fs");
+  rmSync(join(root, TSV_REL));
+  const res = await emitPlan({ ...opts, plan: planWith([adoptedObjective()]) });
+  assert.equal(res.unchanged, undefined);
+  assert.ok(existsSync(join(root, TSV_REL)), "the deleted artefact is restored");
+});
+
+test("force:true overrides the guard", async () => {
+  const root = tmpRoot();
+  const opts = { agentRoot: root, manifest: manifest(), at: AT };
+  await emitPlan({ ...opts, plan: planWith([adoptedObjective()]) });
+  const res = await emitPlan({ ...opts, plan: planWith([adoptedObjective()]), force: true });
+  assert.equal(res.unchanged, undefined);
+  assert.equal(res.files.length, 5);
+});

package/lib/plan/explain.mjs

@@ -0,0 +1,226 @@
+/**
+ * lib/plan/explain.mjs — answer "why does this job exist?" OFFLINE (SPEC §8).
+ *
+ * Every scheduled job this agent runs is supposed to be traceable to an outcome
+ * a human adopted. That claim is worthless unless it can be CHECKED, so this
+ * module walks the chain from a launchd tick all the way back to the clause that
+ * justifies it, using only files already on disk:
+ *
+ *   cadence id / obligation key
+ *     → config/plan.yaml          the obligation (what, when, with which tools)
+ *     → objective_id              the outcome it serves
+ *     → state/mandate/cache.json  the objective: metric, target, state, adopter
+ *     → charterSectionId          the charter clause the objective came from
+ *     → config/agent.json         the clause text
+ *     → adoptedById               WHO adopted it (never the agent itself)
+ *
+ * No network, no LLM, no hq round-trip. A partitioned laptop can still answer
+ * the governance question, which is the entire point of the agent-sovereign
+ * split — hq owns the mandate, the agent owns the plan, and both halves of the
+ * provenance chain are cached locally.
+ *
+ * Nothing here throws on missing inputs: an un-adopted agent legitimately has no
+ * mandate cache. It returns a `provenance` chain that stops early with an
+ * explicit `gap` — a chain that cannot be completed is REPORTED, never faked.
+ *
+ * @module lib/plan/explain
+ */
+
+"use strict";
+
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { PLAN_REL } from "./emit.mjs";
+
+/** Load config/plan.yaml. Returns null when absent/unparseable (with a reason). */
+export function readPlan(agentRoot, deps = {}) {
+  const ex = deps.existsSync || existsSync;
+  const rd = deps.readFileSync || readFileSync;
+  const p = join(agentRoot, PLAN_REL);
+  if (!ex(p)) return null;
+  try {
+    const yaml = deps.yaml;
+    if (!yaml) throw new Error("explain: a yaml loader must be injected (or use explainAsync)");
+    return yaml.load(rd(p, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+/** Load config/agent.json (for charter section text). */
+function readAgentCfg(agentRoot, deps = {}) {
+  const ex = deps.existsSync || existsSync;
+  const rd = deps.readFileSync || readFileSync;
+  const p = join(agentRoot, "config", "agent.json");
+  if (!ex(p)) return null;
+  try { return JSON.parse(rd(p, "utf-8")); } catch { return null; }
+}
+
+/**
+ * Find the obligation a lookup key names. Accepts either the obligation key
+ * (`schedule.measure.pipeline-coverage`) or the cadence id (`measure-pipeline-
+ * coverage`) — a launchd job only knows the latter.
+ * @param {object} plan @param {string} key
+ */
+export function findObligation(plan, key) {
+  const list = (plan && plan.obligations) || [];
+  const k = String(key || "");
+  return list.find((o) => o.key === k) || list.find((o) => o.cadence_id === k) || null;
+}
+
+/** Find an objective in a cached mandate body by id or key. */
+export function findObjective(mandateBody, id) {
+  const list = (mandateBody && mandateBody.objectives) || [];
+  const k = String(id || "");
+  return list.find((o) => o.id === k) || list.find((o) => o.key === k) || null;
+}
+
+/** Find a charter section by id in config/agent.json. */
+export function findCharterSection(agentCfg, sectionId) {
+  const sections = (agentCfg && agentCfg.charter && agentCfg.charter.sections) || [];
+  const k = String(sectionId || "");
+  return sections.find((s) => s && (s.id === k || s.key === k)) || null;
+}
+
+/**
+ * Explain one obligation.
+ *
+ * @param {object} o - { agentRoot, key, plan?, mandate?, agentCfg? }
+ * @param {object} [deps] - { existsSync, readFileSync, yaml }
+ * @returns {{found:boolean, key:string, provenance:object[], gap:string|null, summary:string}}
+ */
+export function explain(o = {}, deps = {}) {
+  const key = String(o.key || "");
+  const plan = o.plan !== undefined ? o.plan : readPlan(o.agentRoot, deps);
+  const provenance = [];
+
+  if (!plan) {
+    return { found: false, key, provenance, gap: "no-plan", summary: `no ${PLAN_REL} on disk — run \`maestro setup --only mandate\`` };
+  }
+
+  const ob = findObligation(plan, key);
+  if (!ob) {
+    return { found: false, key, provenance, gap: "no-obligation", summary: `no obligation named "${key}" in ${PLAN_REL}` };
+  }
+
+  provenance.push({
+    step: "obligation",
+    key: ob.key,
+    kind: ob.kind,
+    status: ob.status,
+    origin: (ob.source && ob.source.origin) || null,
+    when: ob.schedule
+      ? (Number.isFinite(ob.schedule.interval) ? `every ${ob.schedule.interval}s` : JSON.stringify(ob.schedule.calendar))
+      : (ob.trigger ? `on ${ob.trigger.topic}.${ob.trigger.kind || "*"}` : null),
+    uses: ob.uses || [],
+    allowedTools: ob.allowed_tools || [],
+    budgetCents: ob.budget_cents_per_period ?? null,
+  });
+
+  // A standard/archetype obligation is legitimately not mandate-backed: it is
+  // the floor every agent runs. Say so plainly rather than reporting a gap.
+  const origin = (ob.source && ob.source.origin) || "";
+  if (!ob.objective_id) {
+    const floor = origin === "standard" || origin === "archetype" || origin === "react-standard";
+    return {
+      found: true, key: ob.key, provenance,
+      gap: floor ? null : "no-objective",
+      summary: floor
+        ? `"${ob.key}" is a ${origin} obligation — the baseline every ${origin === "archetype" ? "seat of this archetype" : "agent"} runs. It serves no specific adopted objective.`
+        : `"${ob.key}" cites no objective_id, but its origin is "${origin}" — this obligation is unjustified and should be reported as drift.`,
+    };
+  }
+
+  const mandate = o.mandate !== undefined ? o.mandate : null;
+  const body = mandate && (mandate.body || mandate);
+  const objective = findObjective(body, ob.objective_id);
+  if (!objective) {
+    return {
+      found: true, key: ob.key, provenance, gap: "no-mandate-cache",
+      summary: `"${ob.key}" serves objective ${ob.objective_id}, but it is not in the local mandate cache — refresh with \`mandate.get\` (the chain cannot be completed offline).`,
+    };
+  }
+
+  provenance.push({
+    step: "objective",
+    id: objective.id || objective.key,
+    key: objective.key,
+    text: objective.text || null,
+    metric: objective.metric || null,
+    target: objective.target ?? null,
+    direction: objective.direction || "up",
+    cadence: objective.cadence || null,
+    state: objective.state,
+    sensor: objective.sensor || null,
+  });
+
+  // Adoption: the anti-Goodhart law made visible. An objective adopted by its
+  // own owner is a governance violation, and this is where a human sees it.
+  const adoptedBy = objective.adoptedById || null;
+  const owner = objective.memberId || (body && body.memberId) || null;
+  const selfAdopted = !!(adoptedBy && owner && adoptedBy === owner);
+  provenance.push({
+    step: "adoption",
+    state: objective.state,
+    adoptedById: adoptedBy,
+    adoptedAt: objective.adoptedAt || null,
+    ownerId: owner,
+    selfAdopted,
+  });
+
+  if (objective.charterSectionId) {
+    const agentCfg = o.agentCfg !== undefined ? o.agentCfg : readAgentCfg(o.agentRoot, deps);
+    const section = findCharterSection(agentCfg, objective.charterSectionId);
+    provenance.push({
+      step: "charter",
+      sectionId: objective.charterSectionId,
+      kind: section ? section.kind : null,
+      title: section ? (section.title || section.heading || null) : null,
+      text: section ? (section.body || section.text || null) : null,
+      resolved: !!section,
+    });
+  }
+
+  const gap = selfAdopted ? "self-adopted" : (objective.state !== "active" ? "not-adopted" : null);
+  const target = objective.target != null ? ` toward ${objective.metric || objective.key} ${objective.direction === "down" ? "≤" : "≥"} ${objective.target}` : "";
+  const who = adoptedBy ? ` adopted by ${adoptedBy}` : " (not yet adopted)";
+  const summary = selfAdopted
+    ? `GOVERNANCE VIOLATION: "${ob.key}" serves objective "${objective.key}", which was adopted by its own owner (${adoptedBy}). A seat may not define, measure and be graded on the same number.`
+    : `"${ob.key}" exists to serve "${objective.text || objective.key}"${target}${who}.`;
+
+  return { found: true, key: ob.key, provenance, gap, summary };
+}
+
+/**
+ * Convenience wrapper that loads plan.yaml + the mandate cache itself.
+ * @param {object} o - { agentRoot, key }
+ * @returns {Promise<object>}
+ */
+export async function explainAsync(o = {}, deps = {}) {
+  const yaml = deps.yaml || (await import("js-yaml").then((m) => m.default || m));
+  let mandate = o.mandate;
+  if (mandate === undefined) {
+    try {
+      const cache = await import("../mandate/cache.mjs");
+      mandate = cache.readCache(o.agentRoot);
+    } catch {
+      mandate = null;
+    }
+  }
+  return explain({ ...o, mandate }, { ...deps, yaml });
+}
+
+/** Render an explanation as indented text for a CLI / SessionStart banner. */
+export function renderExplanation(res) {
+  const lines = [res.summary];
+  for (const p of res.provenance || []) {
+    if (p.step === "obligation") lines.push(`  obligation  ${p.key} [${p.kind}/${p.status}] ${p.when || ""} — tools: ${(p.allowedTools || []).join(", ") || "none"}`);
+    else if (p.step === "objective") lines.push(`  objective   ${p.key} — ${p.metric || "?"} target ${p.target ?? "?"} (${p.state}), sensor ${p.sensor && p.sensor.capability ? p.sensor.capability : "none"}`);
+    else if (p.step === "adoption") lines.push(`  adoption    ${p.adoptedById ? `by ${p.adoptedById}${p.adoptedAt ? ` at ${p.adoptedAt}` : ""}` : "NOT ADOPTED"}${p.selfAdopted ? "  ← SELF-ADOPTED (invalid)" : ""}`);
+    else if (p.step === "charter") lines.push(`  charter     ${p.sectionId}${p.title ? ` — ${p.title}` : ""}${p.resolved ? "" : "  (clause not found locally)"}`);
+  }
+  if (res.gap) lines.push(`  gap         ${res.gap}`);
+  return lines.join("\n");
+}
+
+export default { explain, explainAsync, findObligation, findObjective, findCharterSection, readPlan, renderExplanation };

package/lib/plan/explain.test.mjs

@@ -0,0 +1,188 @@
+/**
+ * explain.test.mjs — the OFFLINE provenance walk (SPEC §8).
+ * Run: node --test lib/plan/explain.test.mjs
+ *
+ * The claim this module has to defend: every scheduled job an agent runs can be
+ * traced back to an outcome a human adopted, WITHOUT calling hq. These tests
+ * inject the whole world (plan, mandate cache, agent.json) so the walk is proven
+ * to touch no network and to REPORT an incomplete chain rather than fake one.
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { explain, findObligation, findObjective, findCharterSection, renderExplanation } from "./explain.mjs";
+
+const OBLIGATION = {
+  key: "schedule.measure.pipeline-coverage",
+  kind: "SCHEDULE",
+  cadence_id: "measure-pipeline-coverage",
+  status: "active",
+  source: { origin: "mandate", ref: "obj_7Kx", charter_section: "cs_12" },
+  objective_id: "obj_7Kx",
+  schedule: { calendar: { weekday: 2, hour: 14, minute: 30 } },
+  uses: ["crm_list_deals"],
+  allowed_tools: ["Glob", "Grep", "LS", "Read", "crm_list_deals"],
+  budget_cents_per_period: 500,
+};
+
+const STANDARD_OBLIGATION = {
+  key: "schedule.inbox-processor",
+  kind: "SCHEDULE",
+  cadence_id: "inbox-processor",
+  status: "active",
+  source: { origin: "standard", ref: "inbox-processor" },
+  schedule: { interval: 300 },
+  uses: ["email_inbox"],
+  allowed_tools: ["Read", "email_inbox"],
+};
+
+const PLAN = { schemaVersion: 1, obligations: [OBLIGATION, STANDARD_OBLIGATION] };
+
+function mandate(over = {}) {
+  return {
+    version: 3,
+    body: {
+      memberId: "mem_SELF",
+      objectives: [{
+        id: "obj_7Kx",
+        key: "pipeline-coverage",
+        text: "Keep qualified pipeline at 3x the quarterly target",
+        metric: "pipeline_coverage_x",
+        target: 3,
+        direction: "up",
+        cadence: "weekly",
+        state: "active",
+        memberId: "mem_SELF",
+        adoptedById: "mem_HUMAN",
+        adoptedAt: "2026-08-01T10:00:00.000Z",
+        charterSectionId: "cs_12",
+        sensor: { capability: "crm_list_deals", source: "method" },
+        ...over,
+      }],
+    },
+  };
+}
+
+const AGENT_CFG = {
+  charter: {
+    sections: [{ id: "cs_12", kind: "PILLAR", title: "Revenue durability", body: "Sustain a predictable commercial engine." }],
+  },
+};
+
+test("explain walks obligation → objective → adoption → charter clause", () => {
+  const res = explain({ agentRoot: "/agent", key: "schedule.measure.pipeline-coverage", plan: PLAN, mandate: mandate(), agentCfg: AGENT_CFG });
+
+  assert.equal(res.found, true);
+  assert.equal(res.gap, null);
+  const steps = res.provenance.map((p) => p.step);
+  assert.deepEqual(steps, ["obligation", "objective", "adoption", "charter"]);
+
+  const [ob, obj, adopt, charter] = res.provenance;
+  assert.equal(ob.kind, "SCHEDULE");
+  assert.deepEqual(ob.allowedTools, ["Glob", "Grep", "LS", "Read", "crm_list_deals"]);
+  assert.equal(obj.metric, "pipeline_coverage_x");
+  assert.equal(obj.target, 3);
+  assert.equal(adopt.adoptedById, "mem_HUMAN");
+  assert.equal(adopt.selfAdopted, false);
+  assert.equal(charter.resolved, true);
+  assert.equal(charter.title, "Revenue durability");
+  assert.match(res.summary, /Keep qualified pipeline/);
+});
+
+test("explain resolves a launchd CADENCE ID, not just the obligation key", () => {
+  // A launchd job only knows `measure-pipeline-coverage`.
+  const res = explain({ key: "measure-pipeline-coverage", plan: PLAN, mandate: mandate(), agentCfg: AGENT_CFG });
+  assert.equal(res.found, true);
+  assert.equal(res.key, "schedule.measure.pipeline-coverage");
+});
+
+test("a standard cadence is honestly reported as the floor, not as a gap", () => {
+  const res = explain({ key: "inbox-processor", plan: PLAN, mandate: mandate(), agentCfg: AGENT_CFG });
+  assert.equal(res.found, true);
+  assert.equal(res.gap, null, "the baseline set is not drift");
+  assert.match(res.summary, /baseline every agent runs/);
+  assert.equal(res.provenance.length, 1);
+});
+
+test("a mandate-origin obligation with no objective_id is flagged as unjustified", () => {
+  const orphan = { ...OBLIGATION, key: "schedule.orphan", cadence_id: "orphan", objective_id: undefined, source: { origin: "mandate" } };
+  const res = explain({ key: "schedule.orphan", plan: { obligations: [orphan] }, mandate: mandate(), agentCfg: AGENT_CFG });
+  assert.equal(res.gap, "no-objective");
+  assert.match(res.summary, /unjustified/);
+});
+
+test("SELF-ADOPTION is surfaced as a governance violation (the anti-Goodhart law)", () => {
+  // adoptedById === the objective's own owner: a seat defining, measuring and
+  // being graded on the same number.
+  const res = explain({ key: "schedule.measure.pipeline-coverage", plan: PLAN, mandate: mandate({ adoptedById: "mem_SELF" }), agentCfg: AGENT_CFG });
+  assert.equal(res.gap, "self-adopted");
+  assert.match(res.summary, /GOVERNANCE VIOLATION/);
+  assert.equal(res.provenance.find((p) => p.step === "adoption").selfAdopted, true);
+});
+
+test("a proposed (un-adopted) objective reports the not-adopted gap", () => {
+  const res = explain({ key: "schedule.measure.pipeline-coverage", plan: PLAN, mandate: mandate({ state: "proposed", adoptedById: null, adoptedAt: null }), agentCfg: AGENT_CFG });
+  assert.equal(res.gap, "not-adopted");
+  assert.match(res.summary, /not yet adopted/);
+});
+
+test("an incomplete chain is REPORTED, never faked", () => {
+  // No mandate cache at all (an offline agent that never synced).
+  const noCache = explain({ key: "schedule.measure.pipeline-coverage", plan: PLAN, mandate: null, agentCfg: AGENT_CFG });
+  assert.equal(noCache.found, true);
+  assert.equal(noCache.gap, "no-mandate-cache");
+  assert.equal(noCache.provenance.length, 1, "the walk stops where the evidence stops");
+
+  // No plan at all.
+  const noPlan = explain({ key: "whatever", plan: null });
+  assert.equal(noPlan.found, false);
+  assert.equal(noPlan.gap, "no-plan");
+
+  // Plan present, key unknown.
+  const noOb = explain({ key: "schedule.nonexistent", plan: PLAN, mandate: mandate() });
+  assert.equal(noOb.found, false);
+  assert.equal(noOb.gap, "no-obligation");
+});
+
+test("an unresolvable charter clause is marked unresolved rather than dropped", () => {
+  const res = explain({ key: "schedule.measure.pipeline-coverage", plan: PLAN, mandate: mandate(), agentCfg: { charter: { sections: [] } } });
+  const charter = res.provenance.find((p) => p.step === "charter");
+  assert.ok(charter, "the charter step is still emitted");
+  assert.equal(charter.resolved, false);
+  assert.equal(charter.sectionId, "cs_12");
+});
+
+test("lookup helpers match on either id or key", () => {
+  assert.equal(findObligation(PLAN, "measure-pipeline-coverage").key, "schedule.measure.pipeline-coverage");
+  assert.equal(findObligation(PLAN, "nope"), null);
+  const body = mandate().body;
+  assert.equal(findObjective(body, "obj_7Kx").key, "pipeline-coverage");
+  assert.equal(findObjective(body, "pipeline-coverage").id, "obj_7Kx");
+  assert.equal(findObjective(body, "nope"), null);
+  assert.equal(findCharterSection(AGENT_CFG, "cs_12").kind, "PILLAR");
+  assert.equal(findCharterSection(AGENT_CFG, "cs_99"), null);
+});
+
+test("renderExplanation prints every step it walked", () => {
+  const res = explain({ key: "schedule.measure.pipeline-coverage", plan: PLAN, mandate: mandate(), agentCfg: AGENT_CFG });
+  const text = renderExplanation(res);
+  assert.match(text, /obligation {2}schedule\.measure\.pipeline-coverage/);
+  assert.match(text, /objective {3}pipeline-coverage/);
+  assert.match(text, /adoption {4}by mem_HUMAN/);
+  assert.match(text, /charter {5}cs_12 — Revenue durability/);
+});
+
+test("explain touches no network and no clock (pure over injected inputs)", () => {
+  // Same inputs, twice, with fetch sabotaged: identical output.
+  const realFetch = globalThis.fetch;
+  globalThis.fetch = () => { throw new Error("explain must not call the network"); };
+  try {
+    const a = explain({ key: "schedule.measure.pipeline-coverage", plan: PLAN, mandate: mandate(), agentCfg: AGENT_CFG });
+    const b = explain({ key: "schedule.measure.pipeline-coverage", plan: PLAN, mandate: mandate(), agentCfg: AGENT_CFG });
+    assert.deepEqual(a, b);
+  } finally {
+    globalThis.fetch = realFetch;
+  }
+});