@cohortapp/agent-sdk 2.3.2 → 2.4.1

package/framework-features.json

@@ -262,6 +262,36 @@
         "command": "true",
         "description": "lib/org/knowledge.mjs — recall()/remember() over the org's shared knowledge plane (backed by the Cohort server). Once the agent is enrolled (org-cohort feature: config/org.yaml enabled with base + token), the daemon's prompt-builder can consult recall() so replies are informed by what the fleet already knows, and finished work can remember() durable facts. Server-side ACL governs visibility. Inert + fail-open until enrollment; no standalone init."
       }
+    },
+    "skill-marketplace": {
+      "version": "1",
+      "since": "2.4.0",
+      "title": "Skill marketplace registration (rung 1 of the execution ladder)",
+      "init": {
+        "auto": true,
+        "command": "node scripts/setup/init-skill-marketplace.mjs",
+        "description": "scripts/setup/init-skill-marketplace.mjs — Claude Code only loads a skill when its plugin is declared by a .claude-plugin/marketplace.json AND listed in ~/.claude/settings.json enabledPlugins. Neither was ever written, so every skill markdown file under plugins/*/skills/ was an orphan: present on disk, dead at runtime, silently. This registers + enables each skill plugin through the SAME lib/capability/probe.probeSkillPlugin({repair}) the inventory section uses, so rung 1 of the execution ladder stops being a lie. Idempotent; an already-registered plugin is untouched. A plugin that cannot be repaired is reported loudly and its skills stay reachable:false, which the plan compiler then refuses to cite."
+      }
+    },
+    "capability-manifest": {
+      "version": "1",
+      "since": "2.4.0",
+      "title": "Capability inventory (probed, durable capability map across four planes)",
+      "init": {
+        "auto": true,
+        "command": "node scripts/setup/init-capability-manifest.mjs",
+        "description": "lib/capability/{inventory,probe}.mjs — exhaustively discover Claude Code built-ins, plugin skills (registering the marketplaces so the skill files are actually invocable), MCP servers (.mcp.json cross-read with config/mcp-servers.yaml), and the Cohort org tools + granted integration tools, PROBE each for reachability, and write config/capability-manifest.json (tracked). The law it establishes: an entry with reachable:false may not be cited by any obligation — the plan compiler enforces it. Idempotent; a no-op re-run yields the same checksum. Degradations are recorded in the manifest AND logged, never swallowed."
+      }
+    },
+    "mandate-spine": {
+      "version": "1",
+      "since": "2.4.0",
+      "title": "Mandate spine + plan compiler (derived, justified per-agent schedule)",
+      "init": {
+        "auto": false,
+        "command": "node scripts/setup/generate-plan.mjs --derive",
+        "description": "lib/mandate/{derive,cache}.mjs + lib/plan/{schema,compile,emit}.mjs — derive a PROPOSED objective tree from the agent's charter pillars, the org's strategy streams, its archetype KPI categories and config/priorities.yaml; bind each metric to a REACHABLE sensor capability; then deterministically compile obligations (SCHEDULE/OUTCOME/REACT) and emit config/plan.yaml + cadences.yaml + .cadence-registry.json (extended shape: allowedTools/guardModule/budgetCents/obligationKey) + .cadence-plists.tsv, which generate-plists.sh turns into real launchd jobs. MANUAL because it proposes objectives to hq: nothing is adopted by the agent, and PROPOSED objectives compile no obligations — until a human adopts, the schedule is exactly today's standard + archetype cadence set."
+      }
     }
   }
 }

package/lib/backlog.mjs

@@ -341,11 +341,147 @@ export function parseQueueItems(content, sourceFile = "") {
     // the claim subsystem keys on a defined id and tolerates undefined.
     const id = idMatch?.[1]?.trim();
     if (id) item.id = id;
+
+    // --- goal-steward provenance (D3) ------------------------------------
+    // `lib/goals/loop.renderQueueItems` writes `advances` / `expected_delta` /
+    // `obligation_key` / `disposition` onto every self-directed item. Without
+    // extracting them here the daemon's sweep could not tell goal-linked work
+    // from seeded work, and the gap-weighted ranking below would be dead code.
+    // All four are OPTIONAL: a legacy or hand-written item simply lacks them
+    // and scores exactly as it does today.
+    const advancesMatch = cleanBlock.match(/^\s*-?\s*"?advances"?:\s*\[([^\]]*)\]/m);
+    if (advancesMatch) {
+      const list = advancesMatch[1].split(",").map((s) => s.trim().replace(/^["']|["']$/g, "")).filter(Boolean);
+      if (list.length) item.advances = list;
+    }
+    const deltaMatch = cleanBlock.match(/^\s*-?\s*"?expected_delta"?:\s*["']?(-?[0-9]*\.?[0-9]+)["']?\s*$/m);
+    if (deltaMatch) {
+      const d = Number(deltaMatch[1]);
+      if (Number.isFinite(d)) item.expected_delta = d;
+    }
+    const obligationMatch = cleanBlock.match(/^\s*-?\s*"?obligation_key"?:\s*["']?([^"'\n]+?)["']?\s*$/m);
+    const ok = obligationMatch?.[1]?.trim();
+    if (ok && ok !== "null") item.obligation_key = ok;
+    const dispMatch = cleanBlock.match(/^\s*-?\s*"?disposition"?:\s*["']?(SELF|COLLABORATE|HANDOFF|NEEDS_REVIEW)["']?/m);
+    if (dispMatch) item.disposition = dispMatch[1];
+
     out.push(item);
   }
   return out;
 }
 
+// ---------------------------------------------------------------------------
+// Gap-weighted backlog ranking (SPEC §6.3 step 6)
+// ---------------------------------------------------------------------------
+
+/** Flat priority ordering — the behaviour the daemon's sweep has always had. */
+export const PRIORITY_ORDER = Object.freeze({ critical: 0, high: 1, normal: 2, low: 3 });
+
+/**
+ * Default ranking weights. `Charter.rewardWeights` overrides these when the
+ * charter carries them — which is the first thing in either repo that actually
+ * CONSUMES that field.
+ *
+ *   priority  how much the declared priority still counts
+ *   gap       how much "this objective is badly missed AND this item claims a
+ *             big delta" counts
+ *   age       how much an item is penalised for sitting (prevents starvation
+ *             of un-linked work by a permanently-lagging KPI)
+ */
+export const DEFAULT_BACKLOG_WEIGHTS = Object.freeze({ priority: 1, gap: 1, age: 0.25 });
+
+/**
+ * Resolve weights from a charter, falling back per-key. Non-finite / negative
+ * values are ignored rather than silently poisoning the ranking.
+ * @param {object} [charter] - { rewardWeights?: {priority?, gap?, age?} }
+ * @returns {{priority:number, gap:number, age:number}}
+ */
+export function resolveBacklogWeights(charter) {
+  const rw = (charter && (charter.rewardWeights || charter.reward_weights)) || {};
+  const pick = (k) => {
+    const v = Number(rw[k]);
+    return Number.isFinite(v) && v >= 0 ? v : DEFAULT_BACKLOG_WEIGHTS[k];
+  };
+  return { priority: pick("priority"), gap: pick("gap"), age: pick("age") };
+}
+
+/**
+ * Score one queue item. HIGHER is more urgent (the sweep sorts descending).
+ *
+ * The flat 4-level priority ordering is preserved exactly as the base term, so
+ * an item with no `advances[]` ranks identically to how it ranks today — the
+ * gap term can only ever *promote* goal-linked work, never demote seeded work
+ * below its priority peers by more than the age penalty already would.
+ *
+ * @param {object} item - parseQueueItems() shape
+ * @param {object} [ctx]
+ * @param {Object<string, {normalizedGap?:number}>} [ctx.gapsByObjective] keyed by objective key
+ * @param {object} [ctx.weights] resolveBacklogWeights() output
+ * @param {number} [ctx.now] epoch ms (injected — never Date.now here)
+ * @returns {{score:number, base:number, gapTerm:number, agePenalty:number, objectiveKey:string|null}}
+ */
+export function scoreQueueItem(item = {}, ctx = {}) {
+  const w = ctx.weights || DEFAULT_BACKLOG_WEIGHTS;
+  const gaps = ctx.gapsByObjective || {};
+
+  // Base: invert the priority ladder so higher == more urgent (critical → 3).
+  const rank = PRIORITY_ORDER[item.priority] ?? PRIORITY_ORDER.normal;
+  const base = (3 - rank) * w.priority;
+
+  // Gap term: normalizedGap × expectedDelta, over every objective the item
+  // claims to advance. An item that advances a badly-missed objective with a
+  // big claimed delta floats. Missing either factor contributes nothing —
+  // an unmeasured objective must not manufacture urgency.
+  let gapTerm = 0;
+  let objectiveKey = null;
+  for (const key of Array.isArray(item.advances) ? item.advances : []) {
+    const g = gaps[key];
+    // BOTH factors are clamped to [0,1] so the gap term is bounded by w_gap.
+    // Unclamped, a 100%-missed target with a big claimed delta would swamp the
+    // priority ladder entirely — a KPI gap must ESCALATE work, not let the
+    // agent redefine what "critical" means.
+    const ng = g && Number.isFinite(g.normalizedGap) ? Math.min(1, Math.max(0, g.normalizedGap)) : 0;
+    const delta = Number.isFinite(item.expected_delta) ? Math.abs(item.expected_delta) : 0;
+    const contribution = ng * (delta > 0 ? Math.min(1, delta) : 0);
+    if (contribution > gapTerm) { gapTerm = contribution; objectiveKey = key; }
+    if (objectiveKey === null) objectiveKey = key;
+  }
+  gapTerm *= w.gap;
+
+  // Age penalty: days since `created`, damped. Bounded so a stale item cannot
+  // dominate; it exists to stop a permanently-lagging KPI starving everything.
+  let agePenalty = 0;
+  if (item.created && Number.isFinite(ctx.now)) {
+    const t = Date.parse(item.created);
+    if (Number.isFinite(t)) {
+      const days = Math.max(0, (ctx.now - t) / 86400000);
+      agePenalty = Math.min(2, days / 14) * w.age;
+    }
+  }
+
+  return { score: base + gapTerm - agePenalty, base, gapTerm, agePenalty, objectiveKey };
+}
+
+/**
+ * Rank a backlog. Stable: ties fall back to the flat priority ordering and then
+ * to the original array order, so a run with no measurements produces byte-for-
+ * byte today's dispatch order.
+ *
+ * @param {object[]} items @param {object} [ctx] see scoreQueueItem
+ * @returns {object[]} a new array, most urgent first, each item carrying `_score`
+ */
+export function rankBacklog(items, ctx = {}) {
+  const scored = (items || []).map((item, i) => ({ item, i, s: scoreQueueItem(item, ctx) }));
+  scored.sort((a, b) => {
+    if (b.s.score !== a.s.score) return b.s.score - a.s.score;
+    const pa = PRIORITY_ORDER[a.item.priority] ?? PRIORITY_ORDER.normal;
+    const pb = PRIORITY_ORDER[b.item.priority] ?? PRIORITY_ORDER.normal;
+    if (pa !== pb) return pa - pb;
+    return a.i - b.i;
+  });
+  return scored.map(({ item, s }) => ({ ...item, _score: s.score, _scoreParts: s }));
+}
+
 /** Count immediately-actionable (d30) tasks in a WBS. @param {object} wbs @returns {number} */
 export function countReadyTasks(wbs) {
   if (!wbs || !Array.isArray(wbs.streams)) return 0;

package/lib/cadences.mjs

@@ -76,6 +76,20 @@ export const STANDARD_CADENCES = [
   // the guard tails the org event chain for branding version.saved and escalates
   // only on a real save. 15min keeps the reaction prompt without polling hard.
   { id: "brand-steward", scope: "standard", mode: "guarded", interval: 900, prompt: "schedules/triggers/brand-steward.md" },
+  // goal-steward (D3, SPEC §6.3): the self-directed loop. Measures every adopted
+  // objective whose window is open, computes the gap, and turns a real gap into
+  // real backlog — classified SELF/COLLABORATE/HANDOFF/NEEDS_REVIEW and routed
+  // through the existing collaboration primitives. GUARDED: the guard runs the
+  // whole measure→decide→admit pass INLINE (it is pure local computation plus
+  // sensor reads) and escalates to a planning sub-session only when a gap
+  // actually needs candidates it cannot generate deterministically. An agent
+  // with no adopted mandate costs one cache read a day and never spawns.
+  //
+  // Defaults to OBSERVE-ONLY (config/plan.yaml: enforcement) — it records what
+  // it would create and creates nothing until a human flips enforcement to
+  // "active". A fleet of agents that starts by writing to a board on day one is
+  // how you lose the fleet.
+  { id: "goal-steward", scope: "standard", mode: "guarded", calendar: { hour: 7, minute: 15 }, prompt: "schedules/triggers/goal-steward.md" },
 ];
 
 /** Altitude-specific cadences (reuse existing triggers where one exists). */
@@ -168,8 +182,42 @@ function normalize(entry, scope) {
 }
 
 /**
- * Resolve the full cadence set for a { function, altitude }.
- * @param {{function:string, altitude:string}} sel
+ * Project a compiled SCHEDULE obligation onto a cadence entry. The obligation
+ * already carries a solved slot and a computed tool scope, so nothing here
+ * re-derives a schedule — `normalize()`'s `scheduleFor()` stagger must NOT be
+ * allowed to overwrite a slot the plan compiler solved against the principal's
+ * calendar.
+ * @param {object} ob @returns {object|null}
+ */
+function fromObligation(ob) {
+  if (!ob || ob.kind !== "SCHEDULE" || !ob.cadence_id) return null;
+  if (ob.status && ob.status !== "active") return null;
+  const entry = { id: ob.cadence_id, 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;
+  return entry;
+}
+
+/**
+ * Resolve the full cadence set for a { function, altitude }, optionally grafted
+ * with the agent's own compiled PLAN.
+ *
+ * Three legs, applied in order, first writer of an id wins:
+ *
+ *   1. STANDARD_CADENCES        — the floor. Every agent, always.
+ *   2. function + altitude      — the archetype's recurring workflows.
+ *   3. `obligations`            — the agent's compiled plan (SPEC §5.6).
+ *
+ * Legs 1 and 2 are retained DELIBERATELY as the fallback: proposed-but-unadopted
+ * objectives compile no obligations, so an agent whose human has not yet adopted
+ * anything keeps running exactly today's archetype cadence set rather than
+ * falling to an empty schedule. The obligations leg only ever ADDS mandate-derived
+ * cadences on top — it can neither delete nor re-slot a standard one, which is
+ * what keeps existing launchd plists from churning.
+ *
+ * @param {{function:string, altitude:string, obligations?:object[]}} sel
  * @returns {Promise<object[]>} ordered, de-duplicated cadence entries
  */
 export async function resolveCadences(sel = {}) {
@@ -196,6 +244,19 @@ export async function resolveCadences(sel = {}) {
 
   for (const c of ALTITUDE_CADENCES[altitude] || []) add(c, "altitude");
 
+  // Plan leg: mandate-derived cadences (measure/review obligations). Carries the
+  // obligation key through so cadence-handlers can meter the tick's budget and
+  // lib/plan/explain.mjs can walk the tick back to the objective that justifies it.
+  for (const ob of Array.isArray(sel.obligations) ? sel.obligations : []) {
+    const entry = fromObligation(ob);
+    if (!entry || seen.has(entry.id)) continue;
+    seen.add(entry.id);
+    const norm = normalize(entry, ob.scope === "mandate" ? "mandate" : (ob.scope || "mandate"));
+    if (ob.key) norm.obligationKey = ob.key;
+    if (ob.objective_id) norm.objectiveId = ob.objective_id;
+    out.push(norm);
+  }
+
   return out;
 }
 

package/lib/cadences.test.mjs

@@ -123,3 +123,108 @@ test("every STANDARD_CADENCES entry that declares a prompt has the file on disk"
     assert.ok(existsSync(join(root, c.prompt)), `cadence ${c.id} prompt missing: ${c.prompt}`);
   }
 });
+
+// ---------------------------------------------------------------------------
+// The PLAN leg (SPEC §4/§5.6): mandate-derived obligations graft onto the
+// standard + archetype floor. This is what makes the schedule per-agent and
+// justified rather than a static default list.
+// ---------------------------------------------------------------------------
+
+/** A compiled SCHEDULE obligation, shaped as lib/plan/compile.mjs emits it. */
+function measureObligation(over = {}) {
+  return {
+    key: "schedule.measure.pipeline-coverage",
+    kind: "SCHEDULE",
+    cadence_id: "measure-pipeline-coverage",
+    scope: "mandate",
+    mode: "guarded",
+    prompt: "schedules/triggers/measure-pipeline-coverage.md",
+    schedule: { calendar: { weekday: 2, hour: 14, minute: 30 } },
+    cadence: "weekly",
+    objective_id: "obj_7Kx",
+    status: "active",
+    ...over,
+  };
+}
+
+test("plan leg: an adopted objective's measure obligation becomes a real cadence", async () => {
+  const cads = await resolveCadences({
+    function: "commercial-leader",
+    altitude: "vp",
+    obligations: [measureObligation()],
+  });
+  const c = cads.find((x) => x.id === "measure-pipeline-coverage");
+  assert.ok(c, "mandate-derived cadence resolves");
+  assert.equal(c.scope, "mandate");
+  assert.equal(c.mode, "guarded");
+  // The compiler solved this slot against the principal's calendar — the
+  // resolver's own scheduleFor() stagger must NOT overwrite it.
+  assert.deepEqual(c.calendar, { weekday: 2, hour: 14, minute: 30 });
+  // Provenance rides along so a tick can be walked back to its objective.
+  assert.equal(c.obligationKey, "schedule.measure.pipeline-coverage");
+  assert.equal(c.objectiveId, "obj_7Kx");
+});
+
+test("plan leg: the standard + archetype floor is RETAINED, never replaced", async () => {
+  // An agent whose human has adopted nothing must keep running today's cadences.
+  const withPlan = await resolveCadences({ function: "commercial-leader", altitude: "vp", obligations: [measureObligation()] });
+  const withoutPlan = await resolveCadences({ function: "commercial-leader", altitude: "vp" });
+  const baseIds = withoutPlan.map((c) => c.id);
+  const planIds = withPlan.map((c) => c.id);
+  for (const id of baseIds) assert.ok(planIds.includes(id), `${id} survives the plan leg`);
+  assert.equal(planIds.length, baseIds.length + 1, "the plan leg only ADDS");
+});
+
+test("plan leg: an empty/absent obligation list is exactly today's behaviour", async () => {
+  const none = await resolveCadences({ function: "technical-leader", altitude: "c-suite" });
+  const empty = await resolveCadences({ function: "technical-leader", altitude: "c-suite", obligations: [] });
+  assert.deepEqual(empty, none);
+});
+
+test("plan leg: a plan obligation cannot re-slot or override a standard cadence", async () => {
+  // First writer wins. A mandate obligation colliding with `inbox-processor`
+  // must not move it — that is what keeps existing launchd plists from churning.
+  const base = await resolveCadences({ function: "technical-leader", altitude: "c-suite" });
+  const original = base.find((c) => c.id === "inbox-processor");
+  const cads = await resolveCadences({
+    function: "technical-leader",
+    altitude: "c-suite",
+    obligations: [measureObligation({ cadence_id: "inbox-processor", schedule: { interval: 99999 }, key: "schedule.hijack" })],
+  });
+  const after = cads.find((c) => c.id === "inbox-processor");
+  assert.deepEqual(after, original, "the standard cadence is untouched");
+  assert.equal(cads.filter((c) => c.id === "inbox-processor").length, 1, "no duplicate entry");
+});
+
+test("plan leg: non-active / non-SCHEDULE obligations emit no cadence", async () => {
+  const cads = await resolveCadences({
+    function: "technical-leader",
+    altitude: "c-suite",
+    obligations: [
+      measureObligation({ cadence_id: "suspended-job", status: "suspended", key: "schedule.suspended" }),
+      { key: "outcome.pipeline-coverage", kind: "OUTCOME", cadence_id: "outcome-job", status: "active" },
+      { key: "react.email.received", kind: "REACT", status: "active", trigger: { topic: "email" } },
+    ],
+  });
+  const ids = cads.map((c) => c.id);
+  assert.ok(!ids.includes("suspended-job"), "a suspended obligation is not scheduled");
+  assert.ok(!ids.includes("outcome-job"), "an OUTCOME is measured, not launchd-scheduled");
+  assert.ok(!ids.includes("react.email.received"), "a REACT is event-driven, not scheduled");
+});
+
+test("plan leg: an interval obligation carries its interval through", async () => {
+  const cads = await resolveCadences({
+    function: "technical-leader",
+    altitude: "c-suite",
+    obligations: [measureObligation({ cadence_id: "fast-sensor", schedule: { interval: 300 }, key: "schedule.fast" })],
+  });
+  const c = cads.find((x) => x.id === "fast-sensor");
+  assert.equal(c.interval, 300);
+  assert.equal(c.calendar, undefined);
+});
+
+test("plan leg: founder altitude resolves its own cadences (was unreachable from the wizard)", async () => {
+  const ids = (await resolveCadences({ function: "finance-leader", altitude: "founder" })).map((c) => c.id);
+  assert.ok(ids.includes("weekly-runway-review"), "founder gets the runway review");
+  assert.ok(ids.includes("monthly-investor-update"), "founder gets the investor update");
+});