@cohortapp/agent-sdk 2.3.1 → 2.4.0

package/lib/goals/admission.mjs

@@ -0,0 +1,209 @@
+/**
+ * lib/goals/admission.mjs — the gates a self-directed candidate must clear.
+ *
+ * An agent that turns every gap into tasks is a spam generator. These are the
+ * hard gates between "the number is off" and "work exists", and they are all
+ * pure functions so the decision is reproducible from the audit line alone.
+ *
+ *   honesty     the latest sample's source ∈ {method, human}. An `llm`-sourced
+ *               number is ADVISORY and can never create work. (The Goodhart gate:
+ *               an agent that can invent its own measurement can invent its own
+ *               justification for anything.)
+ *   adoption    the objective is `active` — adopted by somebody who is not its
+ *               owner. A proposed objective admits nothing.
+ *   wip         ≤ MAX_OPEN_PER_OBJECTIVE open items per objective, and
+ *               ≤ MAX_NEW_PER_RUN new items per steward run.
+ *   trend       gap > tolerance AND (nothing already in flight OR the trend has
+ *               been flat for ≥ 2 periods). An improving number needs patience,
+ *               not more tasks.
+ *   budget      estimated cost ≤ the remaining envelope.
+ *   dedupe      not a near-duplicate of an open item on the same objective.
+ *   provenance  non-empty `advances[]` and a populated `why`.
+ *   freshness   the mandate cache is fresh enough for OUTCOME work (§6.4).
+ *
+ * Rejected candidates are RETURNED with their gate and reason, never dropped:
+ * the loop audits every rejection. A silently dropped candidate is
+ * indistinguishable from a bug.
+ *
+ * PURE. No fs, no network, no clock (the clock arrives as `ctx.now`).
+ *
+ * @module lib/goals/admission
+ */
+
+"use strict";
+
+import { WORK_CREATING_SOURCES } from "../kpi.mjs";
+
+/** Ordered gate names — evaluated in this order, first failure wins. */
+export const GATES = Object.freeze([
+  "freshness",
+  "adoption",
+  "honesty",
+  "provenance",
+  "dedupe",
+  "trend",
+  "wip",
+  "budget",
+]);
+
+/** Default caps. Overridable per call so an operator can tune without a fork. */
+export const MAX_OPEN_PER_OBJECTIVE = 3;
+export const MAX_NEW_PER_RUN = 2;
+
+/** Jaccard similarity over word sets — the dedupe heuristic. Pure. */
+export function titleSimilarity(a, b) {
+  const wa = new Set(String(a || "").toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length > 2));
+  const wb = new Set(String(b || "").toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length > 2));
+  if (wa.size === 0 || wb.size === 0) return 0;
+  let inter = 0;
+  for (const w of wa) if (wb.has(w)) inter += 1;
+  return inter / (wa.size + wb.size - inter);
+}
+
+/** Similarity at or above this counts as a duplicate. */
+export const DUPLICATE_THRESHOLD = 0.6;
+
+/**
+ * The decision table (SPEC §6.3). What should a gap PRODUCE, before any
+ * per-candidate gate runs?
+ *
+ *   gap ≤ tolerance                                  → "none"      (leave it alone)
+ *   gap > tolerance, nothing in flight               → "create"    (make work)
+ *   gap > tolerance, work in flight, flat ≥2 periods → "escalate"  (ask, don't pile on)
+ *   gap > tolerance, improving                       → "log"       (patience)
+ *   sensor stale (≥2× cadence)                       → "drift"     (fix the sensor first)
+ *
+ * @param {object} gap - lib/kpi.gapFor() output
+ * @param {object} [o] @param {number} [o.coverage] open items already on this objective
+ * @returns {{action:'none'|'create'|'escalate'|'log'|'drift', reason:string}}
+ */
+export function decideForGap(gap, o = {}) {
+  if (!gap || gap.gap === null) return { action: "drift", reason: "no measurement to decide on" };
+  if (gap.stale) return { action: "drift", reason: `sensor is stale (${(gap.stalenessPeriods || 0).toFixed(1)}× cadence with no sample)` };
+  if (gap.withinTolerance) return { action: "none", reason: "gap is within tolerance" };
+  const coverage = Number.isFinite(o.coverage) ? o.coverage : 0;
+  if (coverage === 0) return { action: "create", reason: "gap exceeds tolerance and nothing is in flight" };
+  if (gap.trend === "improving") return { action: "log", reason: "gap exceeds tolerance but the trend is improving with work in flight" };
+  if (gap.trend === "flat" || gap.trend === "worsening") {
+    return {
+      action: "escalate",
+      reason: `${coverage} item(s) already in flight and the trend is ${gap.trend} — more tasks will not help; ask for a decision`,
+    };
+  }
+  return { action: "log", reason: "work is in flight and the trend is not yet established" };
+}
+
+/**
+ * Run the gates against one candidate.
+ *
+ * @param {object} candidate - { title, advances[], why, estCents?, expectedDelta? }
+ * @param {object} ctx - {
+ *   objective, gap, latestSample, openItems?[], admittedItems?[], admittedThisRun?:number,
+ *   remainingCents?, staleness?:{outcome:string}, maxOpenPerObjective?, maxNewPerRun?
+ * }
+ * @returns {{admitted:boolean, gate:string|null, reason:string, checks:Array<{gate:string, ok:boolean, detail:string}>}}
+ */
+export function admit(candidate = {}, ctx = {}) {
+  const checks = [];
+  const fail = (gate, reason) => {
+    checks.push({ gate, ok: false, detail: reason });
+    return { admitted: false, gate, reason, checks };
+  };
+  const pass = (gate, detail) => checks.push({ gate, ok: true, detail });
+
+  // --- freshness: OUTCOME work is suspended past 24h of mandate staleness ----
+  const outcomeAllowed = !ctx.staleness || ctx.staleness.outcome === "full";
+  if (!outcomeAllowed) {
+    return fail(
+      "freshness",
+      `mandate cache is too stale for self-directed work (outcome=${ctx.staleness && ctx.staleness.outcome})`
+    );
+  }
+  pass("freshness", "mandate cache is fresh");
+
+  // --- adoption -------------------------------------------------------------
+  const obj = ctx.objective || {};
+  if (obj.state !== "active") {
+    return fail("adoption", `objective "${obj.key || "?"}" is ${obj.state || "unknown"}, not active — a proposed objective admits no work`);
+  }
+  pass("adoption", `objective "${obj.key}" is active`);
+
+  // --- honesty --------------------------------------------------------------
+  const source = ctx.latestSample && ctx.latestSample.source;
+  if (!WORK_CREATING_SOURCES.includes(String(source))) {
+    return fail(
+      "honesty",
+      `latest sample source is "${source || "none"}" — only ${WORK_CREATING_SOURCES.join("/")} samples may create work`
+    );
+  }
+  pass("honesty", `latest sample is ${source}-sourced`);
+
+  // --- provenance -----------------------------------------------------------
+  const advances = [].concat(candidate.advances || []).filter(Boolean);
+  if (advances.length === 0) return fail("provenance", "candidate advances no objective");
+  if (!candidate.why || !candidate.why.reason) {
+    return fail("provenance", "candidate carries no `why.reason` — a machine-created task must say why it exists");
+  }
+  pass("provenance", `advances ${advances.join(", ")}`);
+
+  // Shared by dedupe, trend and wip below.
+  const openItems = Array.isArray(ctx.openItems) ? ctx.openItems : [];
+
+  // --- dedupe ---------------------------------------------------------------
+  // BEFORE the trend gate, deliberately. Duplication can only happen when there
+  // ARE open items — and any open item makes `decideForGap` return non-"create",
+  // so with dedupe placed after trend the open-items half of this gate could
+  // never fire at all. (The original comment here rationalised that as "the
+  // reachable case is admittedItems", which conceded the bug rather than fixing
+  // it.) Order also matters for the OPERATOR: "you already have this open" is a
+  // precise, actionable refusal; "work is in flight and the trend is not yet
+  // established" is the vaguer truth that happens to also be true.
+  const against = [...openItems, ...(Array.isArray(ctx.admittedItems) ? ctx.admittedItems : [])];
+  for (const item of against) {
+    const sim = titleSimilarity(candidate.title, item && (item.title || item.text));
+    if (sim >= DUPLICATE_THRESHOLD) {
+      return fail("dedupe", `"${candidate.title}" is ${(sim * 100).toFixed(0)}% similar to "${item.title || item.text}"`);
+    }
+  }
+  pass("dedupe", `no near-duplicate among ${against.length} comparable item(s)`);
+
+  // --- trend ----------------------------------------------------------------
+  const gap = ctx.gap || {};
+  const decision = decideForGap(gap, { coverage: openItems.length });
+  if (decision.action !== "create") {
+    return fail("trend", decision.reason);
+  }
+  pass("trend", decision.reason);
+
+  // --- wip ------------------------------------------------------------------
+  const maxOpen = Number.isFinite(ctx.maxOpenPerObjective) ? ctx.maxOpenPerObjective : MAX_OPEN_PER_OBJECTIVE;
+  if (openItems.length >= maxOpen) {
+    return fail("wip", `${openItems.length} open item(s) on "${obj.key}" ≥ cap ${maxOpen}`);
+  }
+  const maxNew = Number.isFinite(ctx.maxNewPerRun) ? ctx.maxNewPerRun : MAX_NEW_PER_RUN;
+  const admittedThisRun = Number.isFinite(ctx.admittedThisRun) ? ctx.admittedThisRun : 0;
+  if (admittedThisRun >= maxNew) {
+    return fail("wip", `${admittedThisRun} item(s) already admitted this run ≥ cap ${maxNew}`);
+  }
+  pass("wip", `${openItems.length}/${maxOpen} open, ${admittedThisRun}/${maxNew} admitted this run`);
+
+  // --- budget ---------------------------------------------------------------
+  const est = Number(candidate.estCents);
+  const remaining = Number(ctx.remainingCents);
+  if (Number.isFinite(est) && Number.isFinite(remaining) && est > remaining) {
+    return fail("budget", `estimate ${est}c exceeds the remaining envelope ${remaining}c`);
+  }
+  pass("budget", Number.isFinite(est) ? `estimate ${est}c within envelope` : "no cost estimate supplied");
+
+  return { admitted: true, gate: null, reason: "all gates passed", checks };
+}
+
+export default {
+  GATES,
+  MAX_OPEN_PER_OBJECTIVE,
+  MAX_NEW_PER_RUN,
+  DUPLICATE_THRESHOLD,
+  titleSimilarity,
+  decideForGap,
+  admit,
+};

package/lib/goals/admission.test.mjs

@@ -0,0 +1,139 @@
+/**
+ * admission.test.mjs — the gates between "the number is off" and "work exists".
+ * Run: `node --test lib/goals/admission.test.mjs`
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { admit, decideForGap, titleSimilarity, GATES, DUPLICATE_THRESHOLD } from "./admission.mjs";
+
+const OBJ = { key: "pipeline", state: "active", metric: "pipeline_coverage_x", target: 3, cadence: "weekly" };
+const GAP = { gap: 1, target: 3, value: 2, withinTolerance: false, trend: "flat", normalizedGap: 0.33, stale: false };
+const SAMPLE = { source: "method", value: 2, window: "2026-W33" };
+
+function candidate(over = {}) {
+  return {
+    title: "Close the pipeline coverage gap",
+    advances: ["pipeline"],
+    estCents: 40,
+    why: { reason: "kpi-gap", objectiveKey: "pipeline" },
+    ...over,
+  };
+}
+function ctx(over = {}) {
+  return {
+    objective: OBJ,
+    gap: GAP,
+    latestSample: SAMPLE,
+    openItems: [],
+    admittedThisRun: 0,
+    remainingCents: 500,
+    staleness: { outcome: "full" },
+    ...over,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// the decision table
+// ---------------------------------------------------------------------------
+
+test("decision table: within tolerance → nothing; no coverage → create", () => {
+  assert.equal(decideForGap({ ...GAP, withinTolerance: true }).action, "none");
+  assert.equal(decideForGap(GAP, { coverage: 0 }).action, "create");
+});
+
+test("decision table: work in flight + flat/worsening → escalate, NOT more tasks", () => {
+  assert.equal(decideForGap({ ...GAP, trend: "flat" }, { coverage: 2 }).action, "escalate");
+  assert.equal(decideForGap({ ...GAP, trend: "worsening" }, { coverage: 1 }).action, "escalate");
+});
+
+test("decision table: work in flight + improving → log and be patient", () => {
+  assert.equal(decideForGap({ ...GAP, trend: "improving" }, { coverage: 1 }).action, "log");
+});
+
+test("decision table: a stale sensor is a drift to fix, never a gap to work", () => {
+  const d = decideForGap({ ...GAP, stale: true, stalenessPeriods: 3.2 }, { coverage: 0 });
+  assert.equal(d.action, "drift");
+  assert.match(d.reason, /stale/);
+  assert.equal(decideForGap({ gap: null }).action, "drift");
+});
+
+// ---------------------------------------------------------------------------
+// the gates
+// ---------------------------------------------------------------------------
+
+test("a clean candidate passes every gate, in the declared order", () => {
+  const v = admit(candidate(), ctx());
+  assert.equal(v.admitted, true, v.reason);
+  assert.deepEqual(v.checks.map((c) => c.gate), GATES);
+  assert.ok(v.checks.every((c) => c.ok));
+});
+
+test("GATE honesty — an llm-sourced sample is advisory and can NEVER create work", () => {
+  const v = admit(candidate(), ctx({ latestSample: { source: "llm", value: 2 } }));
+  assert.equal(v.admitted, false);
+  assert.equal(v.gate, "honesty");
+  assert.match(v.reason, /only method\/human samples may create work/);
+
+  // human-entered numbers DO count.
+  assert.equal(admit(candidate(), ctx({ latestSample: { source: "human", value: 2 } })).admitted, true);
+});
+
+test("GATE adoption — a proposed objective admits nothing", () => {
+  const v = admit(candidate(), ctx({ objective: { ...OBJ, state: "proposed" } }));
+  assert.equal(v.admitted, false);
+  assert.equal(v.gate, "adoption");
+  assert.match(v.reason, /proposed objective admits no work/);
+});
+
+test("GATE freshness — a stale mandate suspends self-directed work entirely", () => {
+  const v = admit(candidate(), ctx({ staleness: { outcome: "suspended" } }));
+  assert.equal(v.admitted, false);
+  assert.equal(v.gate, "freshness");
+});
+
+test("GATE provenance — no advances[] and no why.reason are both refusals", () => {
+  assert.equal(admit(candidate({ advances: [] }), ctx()).gate, "provenance");
+  assert.equal(admit(candidate({ why: {} }), ctx()).gate, "provenance");
+});
+
+test("GATE wip — the per-objective cap and the per-run cap both bite", () => {
+  const open = [{ title: "a" }, { title: "b" }, { title: "c" }];
+  const capped = admit(candidate(), ctx({ openItems: open, gap: { ...GAP, trend: "improving" } }));
+  assert.equal(capped.gate, "trend", "coverage>0 + improving is caught by the trend gate first");
+
+  const wip = admit(candidate({ title: "totally unrelated new push" }), ctx({ openItems: open, gap: { ...GAP, trend: "unknown" } }));
+  assert.equal(wip.admitted, false);
+
+  const perRun = admit(candidate(), ctx({ admittedThisRun: 2 }));
+  assert.equal(perRun.gate, "wip");
+  assert.match(perRun.reason, /already admitted this run/);
+});
+
+test("GATE dedupe — a near-duplicate of an open item is refused", () => {
+  // coverage>0 would trip the trend gate, so give it an unknown trend to reach dedupe.
+  const v = admit(
+    candidate({ title: "Close the pipeline coverage gap" }),
+    ctx({ openItems: [{ title: "Close the pipeline coverage gap now" }], gap: { ...GAP, trend: "unknown" } })
+  );
+  assert.equal(v.admitted, false);
+  assert.equal(v.gate, "dedupe");
+  assert.ok(titleSimilarity("Close the pipeline coverage gap", "Close the pipeline coverage gap now") >= DUPLICATE_THRESHOLD);
+});
+
+test("NEGATIVE — GATE budget: no budget left means no work, and the reason names both numbers", () => {
+  const v = admit(candidate({ estCents: 900 }), ctx({ remainingCents: 100 }));
+  assert.equal(v.admitted, false);
+  assert.equal(v.gate, "budget");
+  assert.match(v.reason, /900c exceeds the remaining envelope 100c/);
+});
+
+test("every rejection carries its gate and the full check trail — nothing is dropped silently", () => {
+  const v = admit(candidate(), ctx({ latestSample: { source: "llm" } }));
+  assert.ok(v.checks.length > 0);
+  assert.equal(v.checks[v.checks.length - 1].ok, false);
+  assert.equal(v.checks[v.checks.length - 1].gate, v.gate);
+});

package/lib/goals/classify.mjs

@@ -0,0 +1,206 @@
+/**
+ * lib/goals/classify.mjs — SELF / COLLABORATE / HANDOFF / NEEDS_REVIEW.
+ *
+ * A KPI gap produces candidate work. Before any of it is dispatched, each
+ * candidate must answer one question: **whose hands does this need?** That is
+ * this module. It is deliberately a pure classifier — it decides, it does not
+ * act; `goals/collaborate.mjs` does the acting, and it does it exclusively
+ * through primitives that already exist (handoff envelopes, work-claim leases,
+ * board assignment, approvals, escalations). No new collaboration mechanism is
+ * introduced anywhere in this feature.
+ *
+ *   SELF          mine alone. Straight to the backlog at the routed rung.
+ *   COLLABORATE   mine, but a named peer contributes in parallel → work-claim
+ *                 lease so two agents cannot both drive it, + board link.
+ *   HANDOFF       not mine to do: another seat owns it, or only another seat can
+ *                 reach the capability → handoff envelope (handoff.offer).
+ *   NEEDS_REVIEW  mine to do, but the OUTPUT needs someone else's signature —
+ *                 a gated action class (approval.request) or a named reviewer
+ *                 (board review request).
+ *
+ * Note the vocabulary is distinct from `lib/execution/surface-policy.mjs`'s
+ * DISPOSITIONS (`react_now|schedule|delegate|escalate|ignore`). Those classify
+ * an INBOUND EVENT — should I respond at all. These classify OUTBOUND WORK the
+ * agent generated for itself — whose hands does it need. Both exist; conflating
+ * them is what produced "everyone replies at once" the first time.
+ *
+ * PURE. No fs, no network, no clock.
+ *
+ * @module lib/goals/classify
+ */
+
+"use strict";
+
+import { GATED_CLASSES } from "../org/approvals.mjs";
+import { collaboratorsOf } from "../mandate/model.mjs";
+
+/** The four ways a piece of self-directed work can be staffed. */
+export const WORK_DISPOSITIONS = Object.freeze(["SELF", "COLLABORATE", "HANDOFF", "NEEDS_REVIEW"]);
+
+/** True when `d` is one of the four. */
+export function isWorkDisposition(d) {
+  return typeof d === "string" && WORK_DISPOSITIONS.includes(d);
+}
+
+/** Roles that mean "somebody else does the doing". */
+const DOER_ROLES = new Set(["DOER"]);
+/** Roles that mean "somebody else signs it off". */
+const REVIEW_ROLES = new Set(["REVIEWER"]);
+const APPROVE_ROLES = new Set(["APPROVER"]);
+/** Roles that mean "somebody else works alongside me". */
+const CONTRIB_ROLES = new Set(["CONTRIBUTOR"]);
+
+function otherRoles(list, me, roleSet) {
+  return list.filter((c) => roleSet.has(c.role) && c.memberId && c.memberId !== me);
+}
+
+/**
+ * Which of the candidate's required capabilities this seat cannot reach, and
+ * which peer (if any) declares each. Pure.
+ *
+ * @param {string[]} required
+ * @param {Set<string>|string[]} reachable  ids from config/capability-manifest.json
+ * @param {Array<{memberId:string, capabilities?:string[]}>} peers
+ * @returns {{missing:string[], coveredByPeer:Array<{capability:string, memberId:string}>, uncovered:string[]}}
+ */
+export function capabilityGaps(required, reachable, peers) {
+  const need = [].concat(required || []).filter(Boolean).map(String);
+  const have = reachable instanceof Set ? reachable : new Set(reachable || []);
+  const missing = need.filter((c) => !have.has(c));
+  const coveredByPeer = [];
+  const uncovered = [];
+  for (const cap of missing) {
+    // Deterministic: first peer in input order that declares it.
+    const peer = (peers || []).find((p) => p && Array.isArray(p.capabilities) && p.capabilities.includes(cap));
+    if (peer) coveredByPeer.push({ capability: cap, memberId: peer.memberId });
+    else uncovered.push(cap);
+  }
+  return { missing, coveredByPeer, uncovered };
+}
+
+/**
+ * Classify one candidate.
+ *
+ * @param {object} candidate - {
+ *   title, objectiveKey, ownerMemberId?, collaborators?[], requiredCapabilities?[],
+ *   actionClasses?[], reviewBy?
+ * }
+ * @param {object} ctx - {
+ *   memberId, objective?, reachable?:Set<string>|string[], peers?[], gatedClasses?[]
+ * }
+ * @returns {{
+ *   disposition:string, reason:string, target:string|null,
+ *   reviewers:string[], approvers:string[], contributors:string[],
+ *   gatedClasses:string[], capabilityGap:{missing:string[], uncovered:string[]}|null,
+ *   why:string[]
+ * }}
+ */
+export function classifyWorkItem(candidate = {}, ctx = {}) {
+  const me = ctx.memberId || null;
+  const why = [];
+
+  // Collaborators come from the candidate AND from the objective it advances —
+  // an objective-level REVIEWER applies to every task under it.
+  const list = [...collaboratorsOf(candidate), ...collaboratorsOf(ctx.objective)];
+  const seen = new Set();
+  const collaborators = list.filter((c) => {
+    const k = `${c.memberId}:${c.role}`;
+    if (seen.has(k)) return false;
+    seen.add(k);
+    return true;
+  });
+
+  const doers = otherRoles(collaborators, me, DOER_ROLES);
+  const reviewers = otherRoles(collaborators, me, REVIEW_ROLES);
+  const approvers = otherRoles(collaborators, me, APPROVE_ROLES);
+  const contributors = otherRoles(collaborators, me, CONTRIB_ROLES);
+
+  const gatedList = (ctx.gatedClasses || GATED_CLASSES).map((c) => String(c).toLowerCase());
+  const gated = [].concat(candidate.actionClasses || [])
+    .map((c) => String(c).toLowerCase())
+    .filter((c) => gatedList.includes(c));
+
+  const gaps = capabilityGaps(candidate.requiredCapabilities, ctx.reachable, ctx.peers);
+  const capabilityGap = gaps.missing.length ? { missing: gaps.missing, uncovered: gaps.uncovered } : null;
+
+  const base = {
+    disposition: "SELF",
+    reason: "",
+    target: null,
+    reviewers: reviewers.map((c) => c.memberId),
+    approvers: approvers.map((c) => c.memberId),
+    contributors: contributors.map((c) => c.memberId),
+    gatedClasses: gated,
+    capabilityGap,
+    why,
+  };
+
+  // 1 — someone else owns the work outright.
+  if (candidate.ownerMemberId && me && candidate.ownerMemberId !== me) {
+    why.push(`ownerMemberId=${candidate.ownerMemberId} is not this seat`);
+    return { ...base, disposition: "HANDOFF", reason: "owned-by-another-seat", target: candidate.ownerMemberId };
+  }
+
+  // 2 — an explicit DOER collaborator: the mandate says they do it, I steward it.
+  if (doers.length > 0) {
+    why.push(`collaborator ${doers[0].memberId} carries role DOER`);
+    return { ...base, disposition: "HANDOFF", reason: "collaborator-is-doer", target: doers[0].memberId };
+  }
+
+  // 3 — I cannot reach a required capability but a peer declares it. Handing off
+  //     is the ladder's answer, not refusing and not pretending.
+  if (gaps.coveredByPeer.length > 0) {
+    const first = gaps.coveredByPeer[0];
+    why.push(`capability "${first.capability}" is unreachable here but declared by ${first.memberId}`);
+    return {
+      ...base,
+      disposition: "HANDOFF",
+      reason: "capability-only-reachable-by-peer",
+      target: first.memberId,
+    };
+  }
+
+  // 4 — blast radius or a named APPROVER: the output needs a signature BEFORE it
+  //     executes. Approval outranks collaboration; a gated action that is also
+  //     collaborative is still gated.
+  if (gated.length > 0 || approvers.length > 0) {
+    why.push(
+      gated.length
+        ? `action classes ${gated.join("+")} are gated`
+        : `collaborator ${approvers[0].memberId} carries role APPROVER`
+    );
+    return {
+      ...base,
+      disposition: "NEEDS_REVIEW",
+      reason: gated.length ? "gated-action-class" : "collaborator-is-approver",
+      target: approvers.length ? approvers[0].memberId : null,
+    };
+  }
+
+  // 5 — a named reviewer (candidate- or objective-level).
+  const reviewBy = candidate.reviewBy || (ctx.objective && ctx.objective.reviewBy) || null;
+  if (reviewers.length > 0 || (reviewBy && reviewBy !== me)) {
+    const target = reviewers.length ? reviewers[0].memberId : reviewBy;
+    why.push(`review required by ${target}`);
+    return { ...base, disposition: "NEEDS_REVIEW", reason: "review-required", target };
+  }
+
+  // 6 — a peer works alongside me: shared work, so the work-claim lease matters.
+  if (contributors.length > 0) {
+    why.push(`contributor(s) ${contributors.map((c) => c.memberId).join(", ")} work alongside this seat`);
+    return { ...base, disposition: "COLLABORATE", reason: "named-contributors", target: contributors[0].memberId };
+  }
+
+  // 7 — mine alone. If a capability is missing with no peer cover, that is a
+  //     real gap: still SELF (the ladder's rung 2 asks for the integration), but
+  //     the gap travels with the classification so it is never lost.
+  if (capabilityGap && capabilityGap.uncovered.length > 0) {
+    why.push(`capability gap with no peer cover: ${capabilityGap.uncovered.join(", ")}`);
+    return { ...base, disposition: "SELF", reason: "self-with-capability-gap" };
+  }
+
+  why.push("no collaborator, no gate, no capability gap");
+  return { ...base, disposition: "SELF", reason: "self" };
+}
+
+export default { WORK_DISPOSITIONS, isWorkDisposition, capabilityGaps, classifyWorkItem };

package/lib/goals/classify.test.mjs

@@ -0,0 +1,109 @@
+/**
+ * classify.test.mjs — SELF / COLLABORATE / HANDOFF / NEEDS_REVIEW.
+ * Run: `node --test lib/goals/classify.test.mjs`
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { classifyWorkItem, capabilityGaps, WORK_DISPOSITIONS, isWorkDisposition } from "./classify.mjs";
+
+const ME = "mem_self";
+const PEER = "mem_peer";
+const BOSS = "mem_boss";
+
+const OBJ = { key: "pipeline", state: "active", collaborators: [] };
+const REACHABLE = new Set(["crm_list_deals", "task_create"]);
+
+function ctx(over = {}) {
+  return { memberId: ME, objective: OBJ, reachable: REACHABLE, peers: [], ...over };
+}
+
+test("the four dispositions are the vocabulary and nothing else is", () => {
+  assert.deepEqual(WORK_DISPOSITIONS, ["SELF", "COLLABORATE", "HANDOFF", "NEEDS_REVIEW"]);
+  assert.equal(isWorkDisposition("SELF"), true);
+  assert.equal(isWorkDisposition("react_now"), false, "inbound dispositions are a different vocabulary");
+});
+
+test("SELF — mine alone, nothing gated, every capability reachable", () => {
+  const c = classifyWorkItem({ title: "Raise coverage", requiredCapabilities: ["crm_list_deals"] }, ctx());
+  assert.equal(c.disposition, "SELF");
+  assert.equal(c.reason, "self");
+  assert.equal(c.capabilityGap, null);
+});
+
+test("HANDOFF — another seat owns the work outright", () => {
+  const c = classifyWorkItem({ title: "x", ownerMemberId: PEER }, ctx());
+  assert.equal(c.disposition, "HANDOFF");
+  assert.equal(c.target, PEER);
+  assert.equal(c.reason, "owned-by-another-seat");
+});
+
+test("HANDOFF — a collaborator carrying role DOER is the doer, not me", () => {
+  const c = classifyWorkItem({ title: "x", collaborators: [{ memberId: PEER, role: "DOER" }] }, ctx());
+  assert.equal(c.disposition, "HANDOFF");
+  assert.equal(c.target, PEER);
+});
+
+test("HANDOFF — a capability I cannot reach but a peer declares goes to the peer, not to a refusal", () => {
+  const c = classifyWorkItem(
+    { title: "Post to the ledger", requiredCapabilities: ["books_invoices"] },
+    ctx({ peers: [{ memberId: PEER, capabilities: ["books_invoices"] }] })
+  );
+  assert.equal(c.disposition, "HANDOFF");
+  assert.equal(c.target, PEER);
+  assert.equal(c.reason, "capability-only-reachable-by-peer");
+});
+
+test("NEEDS_REVIEW — a gated action class outranks collaboration", () => {
+  const c = classifyWorkItem(
+    { title: "Email the customer base", actionClasses: ["external"], collaborators: [{ memberId: PEER, role: "CONTRIBUTOR" }] },
+    ctx()
+  );
+  assert.equal(c.disposition, "NEEDS_REVIEW");
+  assert.deepEqual(c.gatedClasses, ["external"]);
+  assert.equal(c.reason, "gated-action-class");
+});
+
+test("NEEDS_REVIEW — a named APPROVER, and a named REVIEWER on the OBJECTIVE", () => {
+  const approver = classifyWorkItem({ title: "x", collaborators: [{ memberId: BOSS, role: "APPROVER" }] }, ctx());
+  assert.equal(approver.disposition, "NEEDS_REVIEW");
+  assert.equal(approver.target, BOSS);
+
+  // Objective-level reviewers apply to every task under the objective.
+  const reviewer = classifyWorkItem({ title: "x" }, ctx({ objective: { ...OBJ, collaborators: [{ memberId: PEER, role: "REVIEWER" }] } }));
+  assert.equal(reviewer.disposition, "NEEDS_REVIEW");
+  assert.equal(reviewer.target, PEER);
+  assert.equal(reviewer.reason, "review-required");
+});
+
+test("COLLABORATE — a named contributor works alongside me", () => {
+  const c = classifyWorkItem({ title: "x", collaborators: [{ memberId: PEER, role: "CONTRIBUTOR" }] }, ctx());
+  assert.equal(c.disposition, "COLLABORATE");
+  assert.deepEqual(c.contributors, [PEER]);
+});
+
+test("a collaborator that IS me never turns my own work into a handoff", () => {
+  const c = classifyWorkItem({ title: "x", collaborators: [{ memberId: ME, role: "DOER" }, { memberId: ME, role: "REVIEWER" }] }, ctx());
+  assert.equal(c.disposition, "SELF");
+});
+
+test("NEGATIVE — a missing capability with NO peer cover stays SELF but carries the gap forward", () => {
+  const c = classifyWorkItem({ title: "x", requiredCapabilities: ["stripe_refund"] }, ctx());
+  assert.equal(c.disposition, "SELF");
+  assert.equal(c.reason, "self-with-capability-gap");
+  assert.deepEqual(c.capabilityGap.uncovered, ["stripe_refund"]);
+  assert.match(c.why.join(" "), /capability gap with no peer cover/);
+});
+
+test("capabilityGaps splits missing into peer-covered and uncovered, deterministically", () => {
+  const g = capabilityGaps(["a", "b", "c"], ["a"], [
+    { memberId: "p1", capabilities: ["b"] },
+    { memberId: "p2", capabilities: ["b", "c"] },
+  ]);
+  assert.deepEqual(g.missing, ["b", "c"]);
+  assert.deepEqual(g.coveredByPeer, [{ capability: "b", memberId: "p1" }, { capability: "c", memberId: "p2" }]);
+  assert.deepEqual(g.uncovered, []);
+});