@cohortapp/agent-sdk 2.3.2 → 2.4.0

package/lib/setup/sections/mandate.mjs

@@ -0,0 +1,392 @@
+/**
+ * sections/mandate.mjs — the SCHEDULE DERIVATION step.  (order 78)
+ *
+ * Registered by dropping this file into `lib/setup/sections/` — `runner.mjs`
+ * globs the directory and sorts by `order`. No dispatcher edit.
+ *
+ * Order 78 is deliberate: it runs AFTER `org` (75) so `config/org-context.json`
+ * and the Cohort-authored `charter.sections` are on disk, and after `inventory`
+ * (55) so every capability has been probed. This is the step that finally makes
+ * those inert PILLAR sections in `config/agent.json` load-bearing.
+ *
+ * What it does:
+ *   detect  — is there a compiled plan whose lock matches?
+ *   prompt  — the ONLY place an LLM/human touches the mandate spine. Its output
+ *             is persisted and human-confirmed, never re-derived at runtime.
+ *   apply   — (1) try `mandate.get` for an ADOPTED server mandate;
+ *             (2) otherwise derive a PROPOSED tree locally from charter →
+ *                 strategy → KPI categories → priorities, and offer it to hq via
+ *                 `mandate.propose`;
+ *             (3) cache it; (4) COMPILE obligations deterministically;
+ *             (5) EMIT cadences.yaml / .cadence-registry.json / .cadence-plists.tsv
+ *                 / plan.yaml; (6) run generate-plists.sh so real launchd jobs
+ *                 exist.
+ *   verify  — plan compiles, hashes match the lock, no obligation cites an
+ *             unreachable capability, every OUTCOME has a non-LLM sensor, and
+ *             the mandate cache is fresh.
+ *
+ * THE SAFETY PROPERTY: nothing is adopted here. A locally-derived objective is
+ * `state:'proposed'`, and proposed objectives compile NO obligations — so on a
+ * fresh agent this section emits exactly the standard + archetype cadence set
+ * that `resolveCadences()` produces today. The schedule only grows once a human
+ * adopts an objective in hq. That is what makes this shippable incrementally
+ * rather than lockstep, and it is why `generate-cadences.mjs` remains the
+ * fallback producer, untouched.
+ *
+ * Every hook is non-blocking under --headless. apply() is idempotent: identical
+ * inputs re-emit byte-identical files, so no launchd plist churns.
+ *
+ * @module lib/setup/sections/mandate
+ */
+
+"use strict";
+
+import { join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import * as io from "../io.mjs";
+import { readAgentJson } from "../sot.mjs";
+import { runScriptAbs } from "../run-generator.mjs";
+import { readManifest } from "../../capability/inventory.mjs";
+import { deriveMandate, toMandateBody } from "../../mandate/derive.mjs";
+import { readCache, writeCache, stalenessTier, staleSeconds, allObjectives, adoptedObjectives, CACHE_REL } from "../../mandate/cache.mjs";
+import { compilePlan } from "../../plan/compile.mjs";
+import { emitPlan, readLock, PLAN_REL, LOCK_REL } from "../../plan/emit.mjs";
+import { validatePlan } from "../../plan/schema.mjs";
+
+const ORG_CONTEXT_REL = join("config", "org-context.json");
+const PRIORITIES_REL = join("config", "priorities.yaml");
+
+/** Read a JSON file, tolerating absence/corruption (never throws). */
+function readJson(path) {
+  try { return existsSync(path) ? JSON.parse(readFileSync(path, "utf-8")) : null; } catch { return null; }
+}
+
+/** config/priorities.yaml → [{id,title}] (best-effort; never throws). */
+export async function readPriorities(agentRoot) {
+  const p = join(agentRoot, PRIORITIES_REL);
+  if (!existsSync(p)) return [];
+  try {
+    const m = await import("js-yaml");
+    const yaml = m && m.default ? m.default : m;
+    const doc = yaml.load(readFileSync(p, "utf-8"));
+    const list = Array.isArray(doc) ? doc : (doc && (doc.priorities || doc.items)) || [];
+    return (Array.isArray(list) ? list : []).filter(Boolean).map((x) => (typeof x === "string" ? { title: x } : x));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Gather every compiler input from disk. Exported so the standalone
+ * `scripts/setup/generate-plan.mjs` and the tests share one loader.
+ *
+ * @param {object} o - { agentRoot, maestroRoot }
+ * @param {object} [deps] - { resolveCadencesImpl, resolveArchetypeImpl, standardCadences }
+ * @returns {Promise<object>} { agentJson, archetype, profile, manifest, orgContext, priorities, standardCadences, archetypeCadences, degradations }
+ */
+export async function loadCompilerInputs(o = {}, deps = {}) {
+  const { agentRoot, maestroRoot } = o;
+  const degradations = [];
+  const agentJson = readAgentJson(agentRoot) || {};
+  const archetype = agentJson.function && agentJson.altitude ? { function: agentJson.function, altitude: agentJson.altitude } : null;
+  if (!archetype) degradations.push({ kind: "no_archetype", reason: "config/agent.json has no { function, altitude } — archetype cadences will not compile" });
+
+  const manifest = readManifest(agentRoot);
+  if (!manifest) degradations.push({ kind: "no_manifest", reason: "config/capability-manifest.json absent — run `maestro setup --only inventory` first; every sensor will fall back to source:human" });
+
+  const orgContext = readJson(join(agentRoot, ORG_CONTEXT_REL));
+  if (!orgContext) degradations.push({ kind: "no_org_context", reason: `${ORG_CONTEXT_REL} absent — the org's strategy streams will not shape the mandate` });
+
+  const priorities = await readPriorities(agentRoot);
+
+  let profile = null;
+  if (archetype) {
+    try {
+      const resolve = deps.resolveArchetypeImpl || (await import("../../archetype.mjs")).resolveArchetype;
+      profile = await resolve(archetype);
+    } catch (e) {
+      degradations.push({ kind: "archetype_unresolved", reason: `resolveArchetype failed: ${e && e.message ? e.message : e}` });
+    }
+  }
+
+  let standardCadences = deps.standardCadences;
+  let archetypeCadences = [];
+  try {
+    const cad = await import("../../cadences.mjs");
+    if (!standardCadences) standardCadences = cad.STANDARD_CADENCES;
+    if (archetype) {
+      const resolveCadences = deps.resolveCadencesImpl || cad.resolveCadences;
+      archetypeCadences = (await resolveCadences(archetype)).filter((c) => c.scope !== "standard");
+    }
+  } catch (e) {
+    degradations.push({ kind: "cadences_unresolved", reason: `resolveCadences failed: ${e && e.message ? e.message : e}` });
+    standardCadences = standardCadences || [];
+  }
+
+  void maestroRoot;
+  return { agentJson, archetype, profile, manifest, orgContext, priorities, standardCadences: standardCadences || [], archetypeCadences, degradations };
+}
+
+/**
+ * Resolve the org client `call` for this agent, or null when un-enrolled.
+ * Never throws; a missing/broken enrollment is logged, never silent.
+ */
+async function resolveCall(agentRoot, deps, log) {
+  if (deps.callImpl !== undefined) return deps.callImpl;
+  try {
+    const client = await import("../../org/client.mjs");
+    const cfg = client.loadOrgConfig(agentRoot);
+    if (!client.isEnabled(cfg)) {
+      log("[mandate] not enrolled in an org — deriving a LOCAL proposed mandate (nothing will be adopted)");
+      return null;
+    }
+    const cc = client.configFromAgent(cfg);
+    return (m, p) => client.call(m, p, cc);
+  } catch (e) {
+    log(`[mandate] org client unavailable (${e && e.message ? e.message : e}) — deriving a LOCAL proposed mandate`);
+    return null;
+  }
+}
+
+/**
+ * Resolve the mandate: the ADOPTED server snapshot if hq has one, otherwise a
+ * locally-derived PROPOSED tree.
+ *
+ * The server→local resolution itself is NOT reimplemented here — it is
+ * `lib/mandate/refresh.refreshMandate`, which already owns the fetch, the
+ * checksum check, the "a local derivation never supersedes an adopted snapshot"
+ * rule, and the vendored-protocol-gap message. This function adds the one thing
+ * the refresher deliberately does not do: OFFERING the derived tree to hq via
+ * `mandate.propose`.
+ *
+ * @param {object} o - { agentRoot, inputs, memberId?, overrides? }
+ * @param {object} [deps] - { callImpl, now, logImpl }
+ * @returns {Promise<{record:object, derived:object|null, source:string, degraded:boolean, reason:string}>}
+ */
+export async function resolveMandate(o = {}, deps = {}) {
+  const { agentRoot, inputs } = o;
+  const log = deps.logImpl || ((m) => io.note(m, { dim: true }));
+  const call = await resolveCall(agentRoot, deps, log);
+
+  const { refreshMandate } = await import("../../mandate/refresh.mjs");
+  const res = await refreshMandate(agentRoot, {
+    now: deps.now ? () => deps.now() : undefined,
+    log: (level, m) => log(m),
+    memberId: o.memberId || null,
+    callImpl: typeof call === "function" ? call : undefined,
+    offline: typeof call !== "function",
+    derivation: {
+      charterSections: (inputs.agentJson && inputs.agentJson.charter && Array.isArray(inputs.agentJson.charter.sections))
+        ? inputs.agentJson.charter.sections
+        : [],
+      strategy: inputs.orgContext && inputs.orgContext.strategy,
+      kpiCategories: (inputs.profile && inputs.profile.kpiCategories) || [],
+      priorities: inputs.priorities,
+      manifest: inputs.manifest,
+      overrides: o.overrides || {},
+    },
+  });
+
+  const derived = res.source === "server" ? null : { counts: res.counts || {}, degradations: res.degradations || [] };
+
+  // OFFER the proposals to hq. Fail-open + logged: an agent may PROPOSE, only a
+  // human/manager may ADOPT (`mandate.adopt` refuses actor === owner). We never
+  // call adopt, from anywhere, for any reason.
+  const proposals = res.source === "local" ? allObjectives(res.record) : [];
+  if (typeof call === "function" && proposals.length) {
+    let posted = 0;
+    for (const obj of proposals) {
+      try {
+        const r = await call("mandate.propose", {
+          key: obj.key, kind: obj.kind, text: obj.text, metric: obj.metric, unit: obj.unit,
+          direction: obj.direction, target: obj.target, tolerance: obj.tolerance,
+          cadence: obj.cadence, sensor: obj.sensor, parentKey: obj.parentKey,
+        });
+        if (r && r.ok) posted++;
+      } catch { /* a per-objective failure must not abort the rest */ }
+    }
+    if (posted !== proposals.length) {
+      log(`[mandate] proposed ${posted}/${proposals.length} objectives to hq — the rest stayed local (the plan compiles from the cache either way)`);
+    }
+  }
+
+  return { record: res.record, derived, source: res.source, degraded: !!res.degraded, reason: res.reason };
+}
+
+/**
+ * Compile + emit the plan from on-disk inputs. Shared by apply() and
+ * `scripts/setup/generate-plan.mjs`.
+ * @returns {Promise<{ok:boolean, plan:object, emit:object, inputs:object, record:object}>}
+ */
+export async function compileAndEmit(o = {}, deps = {}) {
+  const { agentRoot, maestroRoot } = o;
+  const inputs = o.inputs || (await loadCompilerInputs({ agentRoot, maestroRoot }, deps));
+  const record = o.record || readCache(agentRoot, deps) || { body: {}, version: 0 };
+
+  const plan = compilePlan({
+    mandate: record.body || {},
+    mandateVersion: record.version || 0,
+    manifest: inputs.manifest || { entries: [] },
+    profile: inputs.profile,
+    orgContext: inputs.orgContext,
+    standardCadences: inputs.standardCadences,
+    archetypeCadences: inputs.archetypeCadences,
+    calendarEvents: o.calendarEvents || [],
+    concurrency: o.concurrency,
+  });
+
+  const emit = await emitPlan({
+    agentRoot,
+    plan,
+    manifest: inputs.manifest || { entries: [] },
+    archetype: inputs.archetype ? `${inputs.archetype.function}@${inputs.archetype.altitude}` : null,
+    enforcement: o.enforcement || "observe-only",
+    at: (typeof deps.now === "function" ? deps.now() : new Date().toISOString()),
+  }, deps);
+
+  return { ok: emit.ok, plan, emit, inputs, record };
+}
+
+export default {
+  id: "mandate",
+  label: "Mandate & derived schedule (obligations → launchd jobs)",
+  order: 78,
+
+  async detect(ctx) {
+    const planPath = join(ctx.agentRoot, PLAN_REL);
+    const lock = readLock(ctx.agentRoot);
+    const cache = readCache(ctx.agentRoot);
+    if (existsSync(planPath) && lock && lock.obligationsHash) {
+      const tier = stalenessTier(cache, Date.now());
+      return { status: "complete", summary: `plan ${lock.obligationsHash.slice(0, 12)} · mandate v${lock.mandateVersion ?? 0} (${tier})` };
+    }
+    const agentJson = readAgentJson(ctx.agentRoot) || {};
+    const hasCharter = !!(agentJson.charter && Array.isArray(agentJson.charter.sections) && agentJson.charter.sections.length);
+    if (hasCharter || cache) return { status: "partial", summary: "charter present, no compiled plan", missing: [PLAN_REL, LOCK_REL] };
+    return { status: "unconfigured", missing: [PLAN_REL, CACHE_REL] };
+  },
+
+  async prompt(ctx) {
+    // This is the ONE place prose becomes a structured mandate. It is
+    // interactive, its output is persisted, and it is never re-derived at
+    // runtime (that is what keeps obligationsHash deterministic).
+    const propose = await io.confirm(ctx, {
+      message: "Derive a proposed objective tree from this agent's charter, the org strategy and its KPI categories? (nothing is adopted — a human adopts in Cohort)",
+      key: "mandatePropose",
+      default: true,
+    });
+    ctx.answers.mandatePropose = propose;
+    if (!propose || io.isHeadless(ctx)) return;
+
+    const enforcement = await io.select(ctx, {
+      message: "Plan enforcement mode for the first 14 days",
+      key: "planEnforcement",
+      choices: [
+        { value: "observe-only", label: "observe-only", hint: "record drift, create no tasks (recommended)" },
+        { value: "active", label: "active", hint: "the plan may create work immediately" },
+      ],
+      default: "observe-only",
+    });
+    ctx.answers.planEnforcement = enforcement;
+  },
+
+  async apply(ctx) {
+    const deps = (ctx.mandateDeps && typeof ctx.mandateDeps === "object") ? ctx.mandateDeps : {};
+    const log = deps.logImpl || ((m) => io.note(m, { dim: true }));
+
+    const inputs = await loadCompilerInputs({ agentRoot: ctx.agentRoot, maestroRoot: ctx.maestroRoot }, deps);
+    for (const d of inputs.degradations) log(`[mandate] ${d.kind}: ${d.reason}`);
+
+    const propose = ctx.answers && typeof ctx.answers.mandatePropose === "boolean" ? ctx.answers.mandatePropose : true;
+    let record = readCache(ctx.agentRoot, deps);
+    if (propose || !record) {
+      const res = await resolveMandate({ agentRoot: ctx.agentRoot, inputs, memberId: (inputs.agentJson.orgProfile && inputs.agentJson.orgProfile.memberId) || null, overrides: (ctx.answers && ctx.answers.mandateOverrides) || {} }, deps);
+      record = res.record;
+      if (res.derived) {
+        const c = res.derived.counts;
+        io.note(`[mandate] derived ${c.proposed} PROPOSED objectives (${c.pillars} pillar · ${c.objectives} objective · ${c.goals} goal; ${c.withMethodSensor} with a method sensor). Adopt them in Cohort to activate them.`);
+      }
+    }
+
+    const { ok, plan, emit } = await compileAndEmit({
+      agentRoot: ctx.agentRoot, maestroRoot: ctx.maestroRoot, inputs, record,
+      enforcement: (ctx.answers && ctx.answers.planEnforcement) || "observe-only",
+      calendarEvents: (ctx.answers && ctx.answers.calendarBusy) || [],
+    }, deps);
+
+    if (!ok) {
+      // FAIL-CLOSED and fatal: a plan that does not validate must never be
+      // half-written, because a missing launchd job fails silently forever.
+      throw new Error(`mandate: plan failed validation, nothing written:\n  - ${emit.errors.slice(0, 10).join("\n  - ")}`);
+    }
+
+    io.note(`[mandate] compiled ${plan.counts.total} obligations (${plan.counts.SCHEDULE} SCHEDULE · ${plan.counts.OUTCOME} OUTCOME · ${plan.counts.REACT} REACT) from ${plan.counts.adoptedObjectives} adopted / ${plan.counts.proposedObjectives} proposed objectives`);
+    for (const d of plan.drift) log(`[mandate] drift ${d.kind}${d.key ? ` (${d.key})` : ""}: ${JSON.stringify(d.detail)}`);
+
+    // launchd plists — generate-plists.sh reads config/.cadence-plists.tsv
+    // verbatim, so the derived jobs become REAL launchd jobs with no shell edit.
+    if (deps.skipPlists !== true) {
+      const plistGen = join(ctx.agentRoot, "scripts", "local-triggers", "generate-plists.sh");
+      if (existsSync(plistGen)) {
+        const pr = runScriptAbs(plistGen, ctx.agentRoot, { bash: true, maestroRoot: ctx.maestroRoot });
+        if (!pr.ok) log(`[mandate] generate-plists.sh did not complete: ${(pr.stderr || "").trim().slice(0, 300)}`);
+      } else {
+        log(`[mandate] no scripts/local-triggers/generate-plists.sh in this repo — TSV written, launchd jobs not emitted`);
+      }
+    }
+  },
+
+  async verify(ctx) {
+    const checks = [];
+    const planPath = join(ctx.agentRoot, PLAN_REL);
+    const lock = readLock(ctx.agentRoot);
+    const manifest = readManifest(ctx.agentRoot);
+    const cache = readCache(ctx.agentRoot);
+
+    checks.push({ name: `${PLAN_REL} present`, ok: existsSync(planPath), remedy: existsSync(planPath) ? undefined : "run `maestro setup --only mandate`" });
+    checks.push({ name: `${LOCK_REL} present`, ok: !!lock, remedy: lock ? undefined : "run `maestro setup --only mandate`" });
+    if (!lock || !existsSync(planPath)) return { ok: false, checks };
+
+    // Recompile from the same inputs and compare hashes — this is what catches
+    // "someone hand-edited config/cadences.yaml" and "the manifest moved".
+    // The SAME deps apply() used, or the recompile is comparing two different
+    // worlds and the check is worthless.
+    const deps = (ctx.mandateDeps && typeof ctx.mandateDeps === "object") ? ctx.mandateDeps : {};
+    const inputs = await loadCompilerInputs({ agentRoot: ctx.agentRoot, maestroRoot: ctx.maestroRoot }, deps);
+    const plan = compilePlan({
+      mandate: (cache && cache.body) || {},
+      mandateVersion: (cache && cache.version) || 0,
+      manifest: manifest || { entries: [] },
+      profile: inputs.profile,
+      orgContext: inputs.orgContext,
+      standardCadences: inputs.standardCadences,
+      archetypeCadences: inputs.archetypeCadences,
+    });
+    const hashOk = plan.obligationsHash === lock.obligationsHash;
+    checks.push({ name: "obligationsHash matches compile.lock", ok: hashOk, remedy: hashOk ? undefined : "inputs changed since the last compile — re-run `maestro setup --only mandate`" });
+
+    const v = validatePlan(plan, { manifest: manifest || { entries: [] } });
+    checks.push({ name: "plan validates (no obligation cites an unreachable capability)", ok: v.ok, remedy: v.ok ? undefined : v.errors.slice(0, 3).join("; ") });
+
+    const llmSensors = plan.obligations.filter((ob) => ob.kind === "OUTCOME" && ob.sensor && ob.sensor.source === "llm").length;
+    checks.push({ name: "zero OUTCOME obligations with an llm sensor", ok: llmSensors === 0, remedy: llmSensors === 0 ? undefined : `${llmSensors} OUTCOME obligation(s) are LLM-graded — an llm sample may never close a loop` });
+
+    const secs = staleSeconds(cache, Date.now());
+    const fresh = secs < 24 * 3600;
+    checks.push({
+      name: `mandate cache freshness (${Number.isFinite(secs) ? `${Math.round(secs / 3600)}h` : "never fetched"})`,
+      ok: true,
+      remedy: fresh ? undefined : `cache is ${stalenessTier(cache, Date.now())} — self-directed work is suspended until it refreshes`,
+    });
+
+    const adopted = adoptedObjectives(cache).length;
+    const all = allObjectives(cache).length;
+    checks.push({
+      name: `objectives: ${adopted} adopted / ${all} total`,
+      ok: true,
+      remedy: adopted === 0 && all > 0 ? "no objective is adopted yet — the agent runs standard + archetype cadences only until a human adopts in Cohort" : undefined,
+    });
+
+    return { ok: checks.every((c) => c.ok), checks };
+  },
+};