@cohortapp/agent-sdk 2.3.2 → 2.4.1

package/lib/goals/loop.mjs

@@ -0,0 +1,537 @@
+/**
+ * lib/goals/loop.mjs — the reconciliation loop: a KPI gap becomes real backlog.
+ *
+ * This is the third runtime loop (Loop C in the spec): not reactive, not
+ * scheduled-because-a-plist-fired, but **self-directed** — the agent measures
+ * what it is accountable for, notices where it is short, and produces concrete,
+ * provenance-linked work. It is what separates "an agent with a charter" from
+ * "an agent that pursues its charter".
+ *
+ * The nine steps, each auditable:
+ *
+ *   1. MEASURE    every adopted objective whose measurement window is open,
+ *                 through its manifest-declared sensor (lib/kpi.measureKpi).
+ *   2. GAP        value vs target vs tolerance, plus a real TREND over the
+ *                 series — the thing neither repo could compute before.
+ *   3. DECIDE     the decision table: nothing / create work / ask a question /
+ *                 log and wait / fix the sensor (goals/admission.decideForGap).
+ *   4. PLAN       candidates. Deterministic by default; `deps.proposeCandidates`
+ *                 is the seam where a planning sub-session plugs in, and it is
+ *                 fed the last three interventions WITH their realized deltas so
+ *                 the loop learns instead of repeating itself.
+ *   5. ADMIT      the hard gates (goals/admission.admit). Every rejection is
+ *                 audited with its gate — never silently dropped.
+ *   6. CLASSIFY   SELF / COLLABORATE / HANDOFF / NEEDS_REVIEW (goals/classify).
+ *   7. ROUTE      the execution rung (lib/execution/route.routeRung) and the
+ *                 staffing primitive (goals/collaborate.routeWorkItem).
+ *   8. MIRROR     a local queue item the existing backlog-executor already
+ *                 consumes, carrying `advances` + `expected_delta` + `why`.
+ *   9. AUDIT      one line per decision, with the provenance chain.
+ *
+ * OBSERVE-ONLY is the default posture. For the first period after this ships,
+ * `enforcement:"observe"` records everything and creates ZERO tasks — a human
+ * flips it to `"active"`. An autonomous loop that starts by writing is how you
+ * get a fleet of agents spamming a board on day one.
+ *
+ * Everything is injectable: clock, sensors, org primitives, budget, and the
+ * planner. `runGoalSteward` performs no network I/O of its own.
+ *
+ * @module lib/goals/loop
+ */
+
+"use strict";
+
+import { existsSync, readFileSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+
+import { resolveAgentRoot } from "../agent-root.mjs";
+import { appendJsonl, writeFileAtomic } from "../fs-atomic.mjs";
+import { readCache, stalenessTier, permissionsForTier } from "../mandate/cache.mjs";
+import { adoptedObjectives, validateMandateBody, memberIdOf, provenanceOf, objectivesOf } from "../mandate/model.mjs";
+import { recordDecision } from "../mandate/audit.mjs";
+import {
+  readSeries,
+  recordMeasurement,
+  readInterventions,
+  measureKpi,
+  gapFor,
+  isDue,
+  windowFor,
+} from "../kpi.mjs";
+import { admit, decideForGap } from "./admission.mjs";
+import { classifyWorkItem } from "./classify.mjs";
+import { routeWorkItem, raiseEscalation } from "./collaborate.mjs";
+import { routeRung } from "../execution/route.mjs";
+
+/** The queue the loop writes into. The existing backlog-executor sweeps it. */
+export const GOALS_QUEUE_REL = join("state", "queues", "goals.yaml");
+/** Observe-only output: candidates that WOULD have been created. */
+export const PROPOSED_REL = join("state", "goals", "proposed.jsonl");
+
+/** Default per-candidate cost estimate when the planner supplies none. */
+export const DEFAULT_EST_CENTS = 50;
+
+function logOf(deps) {
+  return deps && typeof deps.log === "function" ? deps.log : () => {};
+}
+function nowMs(deps) {
+  return deps && typeof deps.now === "function" ? deps.now() : Date.now();
+}
+
+// ---------------------------------------------------------------------------
+// Local queue mirror
+// ---------------------------------------------------------------------------
+
+/**
+ * Render queue items in exactly the on-disk shape `lib/backlog.parseQueueItems`
+ * reads. Deterministic, dependency-free (no YAML lib on the hot path — the same
+ * reason the daemon hand-rolls its parser).
+ * @param {object[]} items @returns {string}
+ */
+export function renderQueueItems(items) {
+  const L = [];
+  for (const it of items || []) {
+    L.push(`  - id: ${it.id}`);
+    L.push(`    title: "${String(it.title).replace(/"/g, "'")}"`);
+    L.push(`    status: ${it.status || "open"}`);
+    L.push(`    priority: ${it.priority || "normal"}`);
+    L.push(`    next_action: "${String(it.next_action || it.title).replace(/"/g, "'")}"`);
+    L.push(`    source: goal-steward`);
+    L.push(`    advances: [${(it.advances || []).join(", ")}]`);
+    L.push(`    expected_delta: ${it.expected_delta == null ? "null" : it.expected_delta}`);
+    L.push(`    obligation_key: ${it.obligation_key || "null"}`);
+    L.push(`    disposition: ${it.disposition || "SELF"}`);
+    L.push(`    rung: ${it.rung == null ? "null" : it.rung}`);
+    L.push(`    why: "${String((it.why && it.why.reason) || "kpi-gap").replace(/"/g, "'")}"`);
+    L.push(`    created: ${it.created}`);
+  }
+  return L.join("\n");
+}
+
+/**
+ * Append items to `state/queues/goals.yaml`, creating the file header on first
+ * write. Never throws.
+ * @param {string} agentRoot @param {object[]} items @param {object} [deps]
+ * @returns {{written:number, path:string, ok:boolean}}
+ */
+export function appendBacklogItems(agentRoot, items, deps = {}) {
+  const path = join(resolveAgentRoot(agentRoot), GOALS_QUEUE_REL);
+  if (!items || items.length === 0) return { written: 0, path, ok: true };
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    const header =
+      "queue: goals\n" +
+      "description: Self-directed work created by the goal-steward loop from measured KPI gaps. Every item carries the objective it advances and the expected delta.\n" +
+      "items:\n";
+    const prev = existsSync(path) ? readFileSync(path, "utf-8") : "";
+    const body = prev && prev.includes("items:") ? prev.replace(/\s*$/, "\n") : header;
+    writeFileAtomic(path, `${body}${renderQueueItems(items)}\n`);
+    return { written: items.length, path, ok: true };
+  } catch (err) {
+    logOf(deps)("error", `[goals] could not write the goals queue: ${err && err.message ? err.message : err}`);
+    return { written: 0, path, ok: false };
+  }
+}
+
+/** Open items already on an objective, from the goals queue. Never throws. */
+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 out = [];
+  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;
+    const advances = block.match(/^\s*advances:\s*\[([^\]]*)\]/m);
+    const list = advances ? advances[1].split(",").map((s) => s.trim()).filter(Boolean) : [];
+    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] });
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// The default (deterministic, LLM-free) planner
+// ---------------------------------------------------------------------------
+
+/**
+ * Build one candidate for a lagging objective, with no model in the loop. This
+ * is deliberately conservative: it names the gap, cites the objective, and asks
+ * for the smallest concrete move. `deps.proposeCandidates` replaces it when a
+ * planning sub-session is available.
+ *
+ * @param {object} o - { objective, gap, interventions }
+ * @returns {object[]} candidates
+ */
+export function defaultProposeCandidates(o = {}) {
+  const obj = o.objective || {};
+  const gap = o.gap || {};
+  const metric = obj.metric || obj.key;
+  const dir = obj.direction === "down" ? "reduce" : "raise";
+  // Aim to close half the gap in one period: honest about being an increment,
+  // and it makes `expectedDelta` a number the intervention ledger can score.
+  const expectedDelta = Number.isFinite(gap.gap) ? +(gap.gap / 2).toFixed(6) : null;
+  const priorFailures = (o.interventions || []).filter(
+    (i) => Number.isFinite(i.realizedDelta) && i.realizedDelta <= 0
+  ).length;
+  return [
+    {
+      title: `Close the ${metric} gap: ${dir} from ${gap.value} toward ${gap.target}`,
+      objectiveKey: obj.key,
+      advances: [obj.key],
+      expectedDelta,
+      estCents: DEFAULT_EST_CENTS,
+      collaborators: obj.collaborators || [],
+      actionClasses: obj.actionClasses || [],
+      requiredCapabilities: obj.sensor && obj.sensor.capability ? [obj.sensor.capability] : [],
+      successCriteria: [
+        `${metric} moves ${obj.direction === "down" ? "below" : "above"} ${obj.target} within one ${obj.cadence || "period"}`,
+      ],
+      need: {
+        methods: obj.sensor && obj.sensor.capability ? [obj.sensor.capability] : [],
+        steps: 4,
+        paramsKnown: false,
+        openEnded: priorFailures >= 1,
+      },
+      why: {
+        reason: "kpi-gap",
+        objectiveKey: obj.key,
+        metric,
+        gap: gap.gap,
+        trend: gap.trend,
+        expectedDelta,
+        priorFailedInterventions: priorFailures,
+      },
+    },
+  ];
+}
+
+// ---------------------------------------------------------------------------
+// The loop
+// ---------------------------------------------------------------------------
+
+/**
+ * Run one goal-steward pass.
+ *
+ * @param {object} deps - {
+ *   agentRoot, memberId?, now?, log?,
+ *   cacheRecord?,            // injected mandate cache record (else read from disk)
+ *   sensors?, reachable?,    // capability id → async fn; reachable id set
+ *   peers?,                  // [{memberId, capabilities:[]}] for handoff cover
+ *   proposeCandidates?,      // ({objective,gap,series,interventions}) => candidates[]
+ *   enforcement?,            // "observe" (default) | "active"
+ *   remainingCents?,         // obligation/seat envelope
+ *   budgetStatus?,           // lib/budget-guard.dailyStatus() shape
+ *   maxOpenPerObjective?, maxNewPerRun?,
+ *   …plus every goals/collaborate.mjs primitive seam
+ * }
+ * @returns {Promise<object>} the run report
+ */
+export async function runGoalSteward(deps = {}) {
+  const agentRoot = resolveAgentRoot(deps.agentRoot);
+  const log = logOf(deps);
+  const enforcement = deps.enforcement === "active" ? "active" : "observe";
+  const report = {
+    ok: true,
+    enforcement,
+    at: new Date(nowMs(deps)).toISOString(),
+    staleness: null,
+    validation: null,
+    measured: [],
+    gaps: [],
+    decisions: [],
+    candidates: 0,
+    admitted: [],
+    rejected: [],
+    routed: [],
+    escalations: [],
+    drift: [],
+    created: 0,
+    skipped: null,
+  };
+
+  // --- 0. mandate + staleness ----------------------------------------------
+  const cacheRecord = deps.cacheRecord !== undefined ? deps.cacheRecord : readCache(agentRoot);
+
+  const audit = (rec) =>
+    recordDecision(agentRoot, rec, { now: deps.now, mandate: cacheRecord, log, mirror: deps.auditMirror });
+
+  if (!cacheRecord || cacheRecord.corrupt) {
+    const reason = !cacheRecord
+      ? "no mandate cache — this seat has never fetched an adopted mandate"
+      : `mandate cache is corrupt: ${cacheRecord.reason}`;
+    log("warn", `[goal-steward] ${reason}; nothing to steward`);
+    report.ok = false;
+    report.skipped = reason;
+    audit({ decision: "drift", detail: { kind: "mandate_stale", reason } });
+    report.drift.push({ kind: "mandate_stale", reason });
+    return report;
+  }
+
+  const tier = stalenessTier(cacheRecord, nowMs(deps));
+  const permissions = permissionsForTier(tier);
+  report.staleness = { tier, ...permissions };
+  if (permissions.outcome !== "full") {
+    const reason = `mandate cache is ${tier} — OUTCOME work is ${permissions.outcome}`;
+    log("warn", `[goal-steward] ${reason}; measuring is still allowed, creating work is not`);
+    report.skipped = reason;
+    audit({ decision: "drift", detail: { kind: "mandate_stale", tier, reason } });
+  }
+
+  const memberId = deps.memberId || memberIdOf(cacheRecord) || null;
+  const validation = validateMandateBody(cacheRecord, { ownerMemberId: memberId });
+  report.validation = validation;
+  for (const e of validation.errors) log("warn", `[goal-steward] mandate invalid: ${e}`);
+  for (const w of validation.warnings) log("info", `[goal-steward] mandate warning: ${w}`);
+
+  const objectives = adoptedObjectives(cacheRecord, { ownerMemberId: memberId, badKeys: validation.badKeys });
+  if (objectives.length === 0) {
+    const total = objectivesOf(cacheRecord).length;
+    log(
+      "info",
+      `[goal-steward] no adopted objectives (${total} in the mandate) — proposed objectives drive no work; the agent runs its standard + archetype cadences`
+    );
+    report.skipped = report.skipped || "no adopted objectives";
+    return report;
+  }
+
+  let admittedThisRun = 0;
+  const backlogItems = [];
+  const proposedRows = [];
+
+  for (const objective of objectives) {
+    // --- 1. MEASURE --------------------------------------------------------
+    let series = readSeries(agentRoot, objective.key);
+    const due = isDue(objective, series, deps);
+    if (due.due) {
+      const m = await measureKpi(objective, { sensors: deps.sensors, reachable: deps.reachable, log, now: deps.now });
+      if (m.ok) {
+        const rec = recordMeasurement(
+          agentRoot,
+          { objectiveKey: objective.key, value: m.value, window: due.window, source: m.source, evidence: m.evidence },
+          { now: deps.now, log }
+        );
+        report.measured.push({ objectiveKey: objective.key, value: m.value, window: due.window, source: m.source, recorded: rec.recorded });
+        audit({ decision: "measured", objectiveKey: objective.key, detail: { value: m.value, window: due.window, source: m.source, evidence: m.evidence } });
+        if (typeof deps.mirrorSample === "function") {
+          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}`); }
+        }
+        series = readSeries(agentRoot, objective.key);
+      } 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 });
+        audit({ decision: "measure_failed", objectiveKey: objective.key, detail: { reason: m.reason, capability: objective.sensor && objective.sensor.capability } });
+      }
+    }
+
+    // --- 2. GAP ------------------------------------------------------------
+    const gap = gapFor(objective, series, deps);
+    report.gaps.push(gap);
+    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 });
+
+    if (decision.action === "drift") {
+      report.drift.push({ kind: "stale_sensor", key: objective.key, reason: decision.reason });
+      audit({ decision: "drift", objectiveKey: objective.key, detail: { kind: "stale_sensor", reason: decision.reason } });
+      continue;
+    }
+    if (decision.action === "none" || decision.action === "log") {
+      audit({ decision: "candidate_rejected", objectiveKey: objective.key, detail: { gate: "trend", reason: decision.reason } });
+      continue;
+    }
+    if (decision.action === "escalate") {
+      const question = `${objective.metric || objective.key} is ${gap.trend} at ${gap.value} against a target of ${gap.target}, with ${openItems.length} item(s) already in flight. More tasks will not move it. What should change?`;
+      const options = [
+        { label: "Re-target the objective (the target is not achievable this period)" },
+        { label: "Escalate resourcing — this needs another seat or a budget increase" },
+        { label: "Accept the miss for this period and re-plan next cycle" },
+      ];
+      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);
+        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 {
+        report.escalations.push({ objectiveKey: objective.key, ok: false, reason: "observe-only", question, options });
+        audit({ decision: "observe_only", objectiveKey: objective.key, detail: { wouldEscalate: question } });
+      }
+      continue;
+    }
+
+    // --- 4. PLAN -----------------------------------------------------------
+    const interventions = readInterventions(agentRoot, objective.key, 3);
+    const planner = typeof deps.proposeCandidates === "function" ? deps.proposeCandidates : defaultProposeCandidates;
+    let candidates = [];
+    try {
+      candidates = (await planner({ objective, gap, series, interventions, openItems, agentRoot })) || [];
+    } catch (err) {
+      log("error", `[goal-steward] planner threw for "${objective.key}": ${err && err.message ? err.message : err}`);
+      audit({ decision: "candidate_rejected", objectiveKey: objective.key, detail: { gate: "planner", reason: "planner-threw" } });
+      continue;
+    }
+    report.candidates += candidates.length;
+    const latestSample = series[series.length - 1] || null;
+
+    for (const candidate of candidates) {
+      // --- 5. ADMIT --------------------------------------------------------
+      const verdict = admit(candidate, {
+        objective,
+        gap,
+        latestSample,
+        openItems,
+        admittedThisRun,
+        remainingCents: deps.remainingCents,
+        staleness: permissions,
+        maxOpenPerObjective: deps.maxOpenPerObjective,
+        maxNewPerRun: deps.maxNewPerRun,
+      });
+      if (!verdict.admitted) {
+        report.rejected.push({ title: candidate.title, objectiveKey: objective.key, gate: verdict.gate, reason: verdict.reason });
+        audit({ decision: "candidate_rejected", objectiveKey: objective.key, detail: { title: candidate.title, gate: verdict.gate, reason: verdict.reason, checks: verdict.checks } });
+        log("info", `[goal-steward] rejected "${candidate.title}" at gate ${verdict.gate}: ${verdict.reason}`);
+        continue;
+      }
+
+      // --- 6. CLASSIFY -----------------------------------------------------
+      const classification = classifyWorkItem(candidate, {
+        memberId,
+        objective,
+        reachable: deps.reachable,
+        peers: deps.peers,
+      });
+      audit({ decision: "disposition", objectiveKey: objective.key, detail: { title: candidate.title, disposition: classification.disposition, reason: classification.reason, target: classification.target, why: classification.why } });
+
+      // --- 7. ROUTE (rung) -------------------------------------------------
+      // `routeRung` reads the blast radius off `need.actionClasses`, but a
+      // candidate declares its action classes at the TOP level (that is where
+      // `classifyWorkItem` and `defaultProposeCandidates` both put them). Merge
+      // them in, or the router's "external | irreversible | financial forces an
+      // approval BEFORE any rung executes" gate never fires from this loop —
+      // `route.approval` would be permanently null and the gate dead code.
+      const need = {
+        ...(candidate.need || {}),
+        actionClasses: [
+          ...[].concat(candidate.actionClasses || []),
+          ...[].concat((candidate.need && candidate.need.actionClasses) || []),
+        ],
+      };
+      const route = routeRung(need, {
+        failures: candidate.failures || 0,
+        hasAdoptedObjective: true,
+        estCents: Number.isFinite(candidate.estCents) ? candidate.estCents : DEFAULT_EST_CENTS,
+        remainingCents: deps.remainingCents,
+        maxRung: deps.maxRung,
+      });
+      audit({ decision: "execution_rung", objectiveKey: objective.key, detail: { title: candidate.title, rung: route.rung, mechanism: route.mechanism, why: route.why, gate: route.gate, approval: route.approval } });
+
+      if (route.blocked && route.gate && route.gate.kind === "budget") {
+        report.rejected.push({ title: candidate.title, objectiveKey: objective.key, gate: "budget", reason: `estimate ${route.gate.detail.estCents}c exceeds envelope ${route.gate.detail.remainingCents}c` });
+        audit({ decision: "budget_refused", objectiveKey: objective.key, detail: { title: candidate.title, ...route.gate.detail } });
+        log("warn", `[goal-steward] "${candidate.title}" enqueued rather than run: over the remaining budget envelope`);
+        continue;
+      }
+      if (route.approval) {
+        audit({ decision: "approval_gate", objectiveKey: objective.key, detail: { title: candidate.title, classes: route.approval.classes } });
+      }
+
+      const provenance = provenanceOf(cacheRecord, objective.key);
+      const obligationKey = `outcome.${objective.key}`;
+      const item = {
+        id: `goal-${objective.key}-${windowFor(objective.cadence, nowMs(deps))}-${backlogItems.length + 1}`,
+        title: candidate.title,
+        objectiveKey: objective.key,
+        obligationKey,
+        priority: gap.normalizedGap > 0.25 ? "high" : "normal",
+        expectedDelta: candidate.expectedDelta ?? null,
+        successCriteria: candidate.successCriteria || [],
+        why: { ...(candidate.why || {}), clause: provenance.clause, obligationKey, adoptedBy: provenance.adoptedBy },
+      };
+
+      // --- 8. STAFF + MIRROR -----------------------------------------------
+      if (enforcement !== "active") {
+        proposedRows.push({
+          at: new Date(nowMs(deps)).toISOString(),
+          item,
+          disposition: classification.disposition,
+          rung: route.rung,
+          provenance,
+        });
+        report.admitted.push({ title: candidate.title, objectiveKey: objective.key, disposition: classification.disposition, rung: route.rung, observed: true });
+        audit({ decision: "observe_only", objectiveKey: objective.key, obligationKey, detail: { title: candidate.title, disposition: classification.disposition, rung: route.rung } });
+        admittedThisRun += 1;
+        continue;
+      }
+
+      let routed;
+      try {
+        routed = await routeWorkItem(item, classification, { ...deps, agentRoot, memberId });
+      } catch (err) {
+        log("error", `[goal-steward] routing "${candidate.title}" threw: ${err && err.message ? err.message : err}`);
+        routed = { routed: classification.disposition, ok: false, reason: "route-threw" };
+      }
+      report.routed.push({ title: candidate.title, objectiveKey: objective.key, ...routed });
+      audit({ decision: routed.ok ? "routed" : "route_failed", objectiveKey: objective.key, obligationKey, detail: { title: candidate.title, ...routed } });
+
+      // A lost work-claim lease means a peer owns it — do NOT also queue it.
+      if (routed.routed === "COLLABORATE" && !routed.ok && String(routed.reason || "").startsWith("lease-lost")) {
+        report.rejected.push({ title: candidate.title, objectiveKey: objective.key, gate: "lease", reason: routed.reason });
+        continue;
+      }
+
+      backlogItems.push({
+        id: item.id,
+        title: item.title,
+        status: "open",
+        priority: item.priority,
+        next_action: item.title,
+        advances: [objective.key],
+        expected_delta: item.expectedDelta,
+        obligation_key: obligationKey,
+        disposition: classification.disposition,
+        rung: route.rung,
+        why: item.why,
+        created: new Date(nowMs(deps)).toISOString().slice(0, 10),
+      });
+      report.admitted.push({ title: candidate.title, objectiveKey: objective.key, disposition: classification.disposition, rung: route.rung, itemId: routed.itemId || item.id });
+      audit({ decision: "candidate_admitted", objectiveKey: objective.key, obligationKey, detail: { title: candidate.title, expectedDelta: item.expectedDelta, rung: route.rung, disposition: classification.disposition } });
+      admittedThisRun += 1;
+    }
+  }
+
+  // --- 8b. write ------------------------------------------------------------
+  if (enforcement === "active") {
+    const w = appendBacklogItems(agentRoot, backlogItems, deps);
+    report.created = w.written;
+  } else if (proposedRows.length > 0) {
+    try {
+      const p = join(agentRoot, PROPOSED_REL);
+      mkdirSync(dirname(p), { recursive: true });
+      for (const row of proposedRows) appendJsonl(p, row);
+    } catch (err) {
+      log("error", `[goal-steward] could not write the observe-only proposals: ${err && err.message ? err.message : err}`);
+    }
+    report.created = 0;
+    log("info", `[goal-steward] observe-only: ${proposedRows.length} candidate(s) recorded, 0 tasks created. Set enforcement:"active" to turn the loop on.`);
+  }
+
+  return report;
+}
+
+export default {
+  GOALS_QUEUE_REL,
+  PROPOSED_REL,
+  DEFAULT_EST_CENTS,
+  renderQueueItems,
+  appendBacklogItems,
+  openItemsFor,
+  defaultProposeCandidates,
+  runGoalSteward,
+};