@cohortapp/agent-sdk 2.4.0 → 2.5.0

package/lib/goals/loop.mjs

@@ -52,6 +52,7 @@ import { recordDecision } from "../mandate/audit.mjs";
 import {
   readSeries,
   recordMeasurement,
+  recordIntervention,
   readInterventions,
   measureKpi,
   gapFor,
@@ -133,13 +134,56 @@ export function appendBacklogItems(agentRoot, items, deps = {}) {
   }
 }
 
-/** Open items already on an objective, from the goals queue. Never throws. */
+/**
+ * The queue the EXECUTION LADDER writes into when it decides a directed event is
+ * work rather than conversation (`lib/execution/effects.scheduleToQueue`).
+ *
+ * It is read here, and not only in the backlog sweep, because reactive work and
+ * self-directed work advance the SAME objectives and must be scored the same
+ * way. Reading only `goals.yaml` meant a board item the ladder queued could
+ * never be counted as an intervention: `journalRealizedDeltas` iterates
+ * `openItemsFor`, so an item outside that view never reached
+ * `lib/kpi.recordIntervention` and the agent could not learn from anything it
+ * did REACTIVELY — only from what it planned for itself.
+ */
+export const INBOUND_QUEUE_REL = join("state", "queues", "inbound.yaml");
+
+/**
+ * Open items already on an objective, from BOTH work queues (goal-steward and
+ * execution-ladder). Never throws.
+ *
+ * Rows are selected by their `advances: [...]` list, so a queue row that names
+ * no objective is correctly invisible here whichever file it came from.
+ */
 export function openItemsFor(agentRoot, objectiveKey) {
-  const path = join(resolveAgentRoot(agentRoot), GOALS_QUEUE_REL);
-  if (!existsSync(path)) return [];
-  let body;
-  try { body = readFileSync(path, "utf-8"); } catch { return []; }
+  const root = resolveAgentRoot(agentRoot);
   const out = [];
+  for (const rel of [GOALS_QUEUE_REL, INBOUND_QUEUE_REL]) {
+    collectOpenItems(join(root, rel), objectiveKey, out);
+  }
+  return out;
+}
+
+/**
+ * Strip a YAML scalar's surrounding quotes.
+ *
+ * The two writers that now feed this reader disagree: `renderQueueItems` above
+ * emits bare scalars (`id: inb-x`), `lib/execution/effects.scheduleToQueue`
+ * emits quoted ones (`id: "inb-x"`) because its ids contain `#` and `.`. The
+ * `(\S+)` captures include the quotes, and the id is used as the intervention's
+ * `taskId` AND as half of the `${taskId}::${window}` dedupe key — so an unstripped
+ * quote would both corrupt the ledger row and defeat the dedupe.
+ */
+function unquote(v) {
+  const s = String(v == null ? "" : v).trim();
+  return s.replace(/^["']/, "").replace(/["']$/, "");
+}
+
+/** Parse one queue file's open items into `out`. Never throws. */
+function collectOpenItems(path, objectiveKey, out) {
+  if (!existsSync(path)) return;
+  let body;
+  try { body = readFileSync(path, "utf-8"); } catch { return; }
   for (const block of body.split(/^\s*-\s+/m).slice(1)) {
     const status = block.match(/^\s*status:\s*(\S+)/m);
     if (!status || !["open", "in_progress"].includes(status[1])) continue;
@@ -148,9 +192,98 @@ export function openItemsFor(agentRoot, objectiveKey) {
     if (objectiveKey && !list.includes(objectiveKey)) continue;
     const title = block.match(/^\s*title:\s*"?(.+?)"?\s*$/m);
     const id = block.match(/^\s*id:\s*(\S+)/m);
-    out.push({ id: id ? id[1] : null, title: title ? title[1] : "", advances: list, status: status[1] });
+    // `expected_delta` and `obligation_key` are not decoration: they are what
+    // `journalRealizedDeltas` scores the intervention AGAINST. Dropping them here
+    // is why the intervention ledger stayed empty — the loop could see that an
+    // item was open but not what it had promised to move.
+    const expected = block.match(/^\s*expected_delta:\s*(\S+)/m);
+    const obligation = block.match(/^\s*obligation_key:\s*(\S+)/m);
+    out.push({
+      id: id ? unquote(id[1]) : null,
+      title: title ? title[1] : "",
+      advances: list.map(unquote),
+      status: status[1],
+      expectedDelta: expected && expected[1] !== "null" ? Number(expected[1]) : null,
+      obligationKey: obligation && obligation[1] !== "null" ? unquote(obligation[1]) : null,
+    });
   }
-  return out;
+}
+
+// ---------------------------------------------------------------------------
+// The learning signal
+// ---------------------------------------------------------------------------
+
+/**
+ * Score every in-flight intervention against the sample that just landed.
+ *
+ * `lib/kpi.recordIntervention` had ZERO callers, so `readInterventions` (which
+ * step 4 already consults, and which `defaultProposeCandidates` counts prior
+ * failures from) always read an empty file. The loop could plan but never learn:
+ * an intervention that made a number WORSE was proposed again, identically,
+ * forever.
+ *
+ * The delta is measured on the GAP, not the raw value, so `direction` is
+ * honoured: positive `realizedDelta` = the gap closed, whatever way the metric
+ * points. Idempotent on `(taskId, window)` — a second steward pass inside the
+ * same measurement window re-scores nothing.
+ *
+ * @param {object} o - { agentRoot, objective, seriesBefore, seriesAfter, window, openItems }
+ * @param {object} [deps] - { now, log }
+ * @returns {{recorded:number, skipped:number, reason:string, rows:object[]}}
+ */
+export function journalRealizedDeltas(o = {}, deps = {}) {
+  const log = logOf(deps);
+  const { agentRoot, objective, seriesBefore, seriesAfter, window } = o;
+  const openItems = Array.isArray(o.openItems) ? o.openItems : [];
+  if (openItems.length === 0) {
+    return { recorded: 0, skipped: 0, reason: "no in-flight interventions to score", rows: [] };
+  }
+
+  const before = gapFor(objective, seriesBefore || [], deps);
+  const after = gapFor(objective, seriesAfter || [], deps);
+  if (before.gap == null || after.gap == null) {
+    log(
+      "info",
+      `[goals] "${objective.key}": a sample landed for ${window} but there is no PRIOR measured gap — the in-flight work cannot be scored yet (this is the first data point, not a failure)`
+    );
+    return { recorded: 0, skipped: openItems.length, reason: "no prior gap", rows: [] };
+  }
+  if (before.window === after.window) {
+    return { recorded: 0, skipped: openItems.length, reason: "same window — nothing new to score", rows: [] };
+  }
+
+  const realizedDelta = +(before.gap - after.gap).toFixed(6);
+  const priors = readInterventions(agentRoot, objective.key, 0);
+  const already = new Set(priors.map((p) => `${p.taskId}::${p.window}`));
+
+  const rows = [];
+  let skipped = 0;
+  for (const item of openItems) {
+    if (already.has(`${item.id}::${window}`)) { skipped += 1; continue; }
+    const res = recordIntervention(
+      agentRoot,
+      {
+        objectiveKey: objective.key,
+        taskId: item.id,
+        obligationKey: item.obligationKey || `outcome.${objective.key}`,
+        expectedDelta: item.expectedDelta,
+        realizedDelta,
+        measuredAt: after.window,
+        window,
+        basis: `gap ${before.gap} (${before.window}) → ${after.gap} (${after.window})`,
+      },
+      deps
+    );
+    if (res.recorded) rows.push(res.record);
+  }
+  if (rows.length > 0) {
+    const verdict = realizedDelta > 0 ? "closed" : realizedDelta < 0 ? "WIDENED" : "did not move";
+    log(
+      "info",
+      `[goals] "${objective.key}": ${rows.length} in-flight intervention(s) scored — the gap ${verdict} by ${Math.abs(realizedDelta)} between ${before.window} and ${after.window}`
+    );
+  }
+  return { recorded: rows.length, skipped, reason: "scored", rows };
 }
 
 // ---------------------------------------------------------------------------
@@ -241,6 +374,7 @@ export async function runGoalSteward(deps = {}) {
     staleness: null,
     validation: null,
     measured: [],
+    interventions: [],
     gaps: [],
     decisions: [],
     candidates: 0,
@@ -303,6 +437,9 @@ export async function runGoalSteward(deps = {}) {
   const proposedRows = [];
 
   for (const objective of objectives) {
+    // Hoisted above MEASURE: the in-flight items are what a new sample SCORES.
+    const openItems = openItemsFor(agentRoot, objective.key);
+
     // --- 1. MEASURE --------------------------------------------------------
     let series = readSeries(agentRoot, objective.key);
     const due = isDue(objective, series, deps);
@@ -320,7 +457,19 @@ export async function runGoalSteward(deps = {}) {
           try { await deps.mirrorSample({ objective, value: m.value, window: due.window, source: m.source, evidence: m.evidence }); }
           catch (err) { log("warn", `[goal-steward] mandate.sample mirror failed for "${objective.key}": ${err && err.message ? err.message : err}`); }
         }
+        const seriesBefore = series;
         series = readSeries(agentRoot, objective.key);
+        // --- 1b. LEARN: score the in-flight work against the new number ----
+        const scored = journalRealizedDeltas(
+          { agentRoot, objective, seriesBefore, seriesAfter: series, window: due.window, openItems },
+          { now: deps.now, log }
+        );
+        if (scored.recorded > 0) {
+          report.interventions.push({ objectiveKey: objective.key, window: due.window, ...scored, rows: undefined });
+          for (const row of scored.rows) {
+            audit({ decision: "intervention_scored", objectiveKey: objective.key, obligationKey: row.obligationKey, detail: row });
+          }
+        }
       } else {
         report.measured.push({ objectiveKey: objective.key, ok: false, reason: m.reason });
         report.drift.push({ kind: m.reason === "unreachable-capability" ? "unreachable_capability" : "stale_sensor", key: objective.key, reason: m.reason });
@@ -334,7 +483,6 @@ export async function runGoalSteward(deps = {}) {
     audit({ decision: "gap", objectiveKey: objective.key, detail: gap });
 
     // --- 3. DECIDE ---------------------------------------------------------
-    const openItems = openItemsFor(agentRoot, objective.key);
     const decision = decideForGap(gap, { coverage: openItems.length });
     report.decisions.push({ objectiveKey: objective.key, ...decision, coverage: openItems.length });
 
@@ -356,7 +504,9 @@ export async function runGoalSteward(deps = {}) {
       ];
       audit({ decision: "candidate_rejected", objectiveKey: objective.key, detail: { gate: "trend", reason: decision.reason, escalating: true } });
       if (enforcement === "active") {
-        const esc = await raiseEscalation({ objectiveKey: objective.key, question, options, gap }, deps);
+        // `agentRoot` is load-bearing, not decoration: it is how the escalation
+        // primitive resolves this seat's org credential (collaborate.orgConn).
+        const esc = await raiseEscalation({ objectiveKey: objective.key, question, options, gap }, { ...deps, agentRoot, memberId, log });
         report.escalations.push({ objectiveKey: objective.key, ...esc });
         audit({ decision: "routed", objectiveKey: objective.key, detail: { primitive: esc.method || "escalation.create", ok: esc.ok, reason: esc.reason } });
       } else {
@@ -532,6 +682,7 @@ export default {
   renderQueueItems,
   appendBacklogItems,
   openItemsFor,
+  journalRealizedDeltas,
   defaultProposeCandidates,
   runGoalSteward,
 };

package/lib/goals/loop.test.mjs

@@ -29,11 +29,13 @@ import {
   renderQueueItems,
   appendBacklogItems,
   openItemsFor,
+  journalRealizedDeltas,
   defaultProposeCandidates,
   GOALS_QUEUE_REL,
   PROPOSED_REL,
 } from "./loop.mjs";
 import { parseQueueItems } from "../backlog.mjs";
+import { readInterventions } from "../kpi.mjs";
 
 // ---------------------------------------------------------------------------
 // Fixtures
@@ -342,10 +344,14 @@ test("enforcement:active turns a measured gap into a routed, provenance-linked b
     assert.equal(calls.board.length, 1);
     const why = calls.board[0].why;
     assert.equal(why.reason, "kpi-gap");
-    assert.equal(why.objectiveKey, "pipeline-coverage");
     assert.equal(why.clause, "cs_12");
-    assert.equal(why.obligationKey, "outcome.pipeline-coverage");
-    assert.equal(why.adoptedBy, BOSS);
+    // hq's `why` block is CLOSED ({reason, options, clause, wouldChange}); the
+    // keys it has no column for ride in `detail` rather than being sent and
+    // silently dropped — or, as before this fix, rejected BAD_REQUEST wholesale.
+    const detail = calls.board[0].detail;
+    assert.match(detail, /Advances objective: pipeline-coverage/);
+    assert.match(detail, /Obligation: outcome\.pipeline-coverage/);
+    assert.equal(calls.board[0].assigneeId, SELF);
 
     // And the local queue item the backlog-executor will sweep.
     const parsed = parseQueueItems(readFileSync(join(root, GOALS_QUEUE_REL), "utf-8"), "goals.yaml");
@@ -717,3 +723,123 @@ test("WIP cap: a second run does not pile more work onto the same objective", as
     assert.notEqual(second.decisions[0].action, "create");
   } finally { cleanup(root); }
 });
+
+// ---------------------------------------------------------------------------
+// THE LEARNING SIGNAL — recordIntervention had zero callers
+// ---------------------------------------------------------------------------
+
+test("openItemsFor carries the expected delta and obligation an intervention is scored against", () => {
+  const root = makeRoot();
+  try {
+    appendBacklogItems(root, [{
+      id: "goal-1", title: "Close the gap", status: "open", priority: "high",
+      next_action: "Close the gap", advances: ["pipeline-coverage"],
+      expected_delta: 0.75, obligation_key: "outcome.pipeline-coverage",
+      disposition: "SELF", rung: 3, why: { reason: "kpi-gap" }, created: "2026-08-11",
+    }]);
+    const [item] = openItemsFor(root, "pipeline-coverage");
+    assert.equal(item.id, "goal-1");
+    assert.equal(item.expectedDelta, 0.75);
+    assert.equal(item.obligationKey, "outcome.pipeline-coverage");
+  } finally { cleanup(root); }
+});
+
+test("a new sample SCORES the work in flight — the realized delta lands in the ledger", () => {
+  const root = makeRoot();
+  try {
+    const objective = { key: "pipeline-coverage", target: 3, direction: "up", tolerance: 0.2, cadence: "weekly" };
+    const before = [{ window: "2026-W32", value: 1.5, source: "method", at: "2026-08-04T09:00:00.000Z" }];
+    const after = [...before, { window: "2026-W33", value: 2.5, source: "method", at: "2026-08-11T09:00:00.000Z" }];
+    const openItems = [{ id: "goal-1", expectedDelta: 0.75, obligationKey: "outcome.pipeline-coverage" }];
+
+    const r = journalRealizedDeltas(
+      { agentRoot: root, objective, seriesBefore: before, seriesAfter: after, window: "2026-W33", openItems },
+      { now: () => NOW },
+    );
+    assert.equal(r.recorded, 1);
+    // gap 1.5 → 0.5: the gap CLOSED by 1.0, whatever way the metric points.
+    assert.equal(r.rows[0].realizedDelta, 1);
+    assert.equal(r.rows[0].expectedDelta, 0.75);
+    assert.equal(r.rows[0].taskId, "goal-1");
+    assert.equal(r.rows[0].window, "2026-W33");
+
+    // Idempotent on (taskId, window): a second pass in the same window re-scores nothing.
+    const again = journalRealizedDeltas(
+      { agentRoot: root, objective, seriesBefore: before, seriesAfter: after, window: "2026-W33", openItems },
+      { now: () => NOW },
+    );
+    assert.equal(again.recorded, 0);
+    assert.equal(readInterventions(root, "pipeline-coverage", 0).length, 1);
+  } finally { cleanup(root); }
+});
+
+test("an intervention that made the number WORSE is recorded as a negative delta", () => {
+  const root = makeRoot();
+  try {
+    const objective = { key: "pipeline-coverage", target: 3, direction: "up", tolerance: 0.2, cadence: "weekly" };
+    const r = journalRealizedDeltas(
+      {
+        agentRoot: root, objective,
+        seriesBefore: [{ window: "2026-W32", value: 2.5, source: "method", at: "2026-08-04T09:00:00.000Z" }],
+        seriesAfter: [{ window: "2026-W32", value: 2.5, source: "method", at: "2026-08-04T09:00:00.000Z" },
+                      { window: "2026-W33", value: 1.5, source: "method", at: "2026-08-11T09:00:00.000Z" }],
+        window: "2026-W33",
+        openItems: [{ id: "goal-1", expectedDelta: 0.75 }],
+      },
+      { now: () => NOW },
+    );
+    assert.equal(r.rows[0].realizedDelta, -1);
+    // …and the planner sees it, which is the whole point of the ledger.
+    const priors = readInterventions(root, "pipeline-coverage", 3);
+    const candidates = defaultProposeCandidates({ objective, gap: { gap: 1.5, trend: "worsening", value: 1.5, target: 3 }, interventions: priors });
+    assert.equal(candidates[0].why.priorFailedInterventions, 1);
+    assert.equal(candidates[0].need.openEnded, true, "a repeat failure must stop being planned as a one-shot");
+  } finally { cleanup(root); }
+});
+
+test("the FIRST data point scores nothing — there is no prior gap, and that is not a failure", () => {
+  const root = makeRoot();
+  const logs = [];
+  try {
+    const r = journalRealizedDeltas(
+      {
+        agentRoot: root,
+        objective: { key: "pipeline-coverage", target: 3, direction: "up", cadence: "weekly" },
+        seriesBefore: [],
+        seriesAfter: [{ window: "2026-W33", value: 1.5, source: "method", at: "2026-08-11T09:00:00.000Z" }],
+        window: "2026-W33",
+        openItems: [{ id: "goal-1", expectedDelta: 0.75 }],
+      },
+      { now: () => NOW, log: (l, m) => logs.push(`${l}:${m}`) },
+    );
+    assert.equal(r.recorded, 0);
+    assert.equal(r.reason, "no prior gap");
+    assert.ok(logs.some((l) => /first data point, not a failure/.test(l)), "the skip must be logged, not silent");
+    assert.equal(readInterventions(root, "pipeline-coverage", 0).length, 0);
+  } finally { cleanup(root); }
+});
+
+test("the loop journals interventions on its own — end to end through runGoalSteward", async () => {
+  const root = makeRoot();
+  try {
+    seedSeries(root, "pipeline-coverage", [
+      { window: "2026-W32", value: 1.5, source: "method", at: "2026-08-04T09:00:00.000Z" },
+    ]);
+    appendBacklogItems(root, [{
+      id: "goal-prior", title: "A prior intervention", status: "open", priority: "normal",
+      next_action: "…", advances: ["pipeline-coverage"], expected_delta: 0.75,
+      obligation_key: "outcome.pipeline-coverage", disposition: "SELF", rung: 3,
+      why: { reason: "kpi-gap" }, created: "2026-08-04",
+    }]);
+
+    const { deps } = spyDeps({ sensors: sensors(2.5) });
+    const r = await runGoalSteward({ ...deps, agentRoot: root, cacheRecord: mandate(), enforcement: "active" });
+
+    assert.equal(r.interventions.length, 1);
+    assert.equal(r.interventions[0].recorded, 1);
+    const rows = readInterventions(root, "pipeline-coverage", 0);
+    assert.equal(rows.length, 1);
+    assert.equal(rows[0].taskId, "goal-prior");
+    assert.equal(rows[0].realizedDelta, 1);
+  } finally { cleanup(root); }
+});