@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/lib/mandate/derive.test.mjs

@@ -1,274 +0,0 @@
-/**
- * lib/mandate/derive.test.mjs — the pillars model, derived at init from the
- * charter and the role.
- *
- * This is the step that makes the inert PILLAR sections in an agent's
- * `config/agent.json` load-bearing: charter clause → PILLAR → OBJECTIVE → GOAL,
- * with a sensor bound to a capability the manifest says is actually REACHABLE.
- *
- * The negative cases matter more than the happy path here: an objective whose
- * sensor cannot be reached must be proposed as a HUMAN measurement obligation
- * with a recorded degradation, never bound to a capability that does not exist.
- */
-
-"use strict";
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-
-import { deriveMandate, toMandateBody, pickSensor, slug, firstClause, isAdoptable } from "./derive.mjs";
-import { validateMandateBody, pillars, ancestry, provenanceOf } from "./model.mjs";
-
-// ---------------------------------------------------------------------------
-// Fixtures
-// ---------------------------------------------------------------------------
-
-const CHARTER = [
-  { id: "cs_1", kind: "PILLAR", order: 1, title: "Revenue growth", body: "Own the revenue line end to end." },
-  { id: "cs_2", kind: "PILLAR", order: 2, title: "Customer retention", body: "Keep the customers we win." },
-  { id: "cs_9", kind: "PRINCIPLE", order: 9, title: "Be direct", body: "Say the hard thing early." },
-];
-
-/** A manifest where only the CRM read is actually reachable. */
-const ENTRIES = [
-  { id: "crm_list_deals", plane: "org", reachable: true },
-  { id: "crm_list_contacts", plane: "org", reachable: false },
-];
-/** The shape `lib/capability/inventory.buildInventory` actually returns. */
-const MANIFEST = { version: 1, entries: ENTRIES };
-
-// ---------------------------------------------------------------------------
-// Pure helpers
-// ---------------------------------------------------------------------------
-
-test("slug and firstClause are deterministic and bounded", () => {
-  assert.equal(slug("Revenue Growth!"), "revenue-growth");
-  assert.equal(slug("  Multiple   spaces  "), "multiple-spaces");
-  assert.equal(firstClause("Own the revenue line. And then some more."), "Own the revenue line.");
-  assert.ok(firstClause("x".repeat(500)).length <= 120);
-});
-
-test("pickSensor binds only to a REACHABLE capability", () => {
-  const reachable = new Set(["crm_list_deals"]);
-  const bound = pickSensor("pipeline coverage across open deals", reachable);
-  if (bound.capability) {
-    assert.equal(bound.source, "method");
-    assert.ok(reachable.has(bound.capability), "a bound sensor must name a reachable capability");
-  }
-
-  // Same text, nothing reachable: the family matched but no capability can be
-  // cited — that is a measurement DEBT, and it must be visible.
-  const unbound = pickSensor("pipeline coverage across open deals", new Set());
-  assert.equal(unbound.capability, null);
-  assert.equal(unbound.source, "human");
-});
-
-// ---------------------------------------------------------------------------
-// The derivation
-// ---------------------------------------------------------------------------
-
-test("charter PILLAR sections become PILLAR nodes carrying their charterSectionId", () => {
-  const r = deriveMandate({ charterSections: CHARTER, kpiCategories: [{ id: "pipeline", name: "Pipeline" }] });
-  const ps = pillars(r.objectives);
-  assert.equal(ps.length, 2, "only PILLAR/CAPABILITY sections become pillars — a PRINCIPLE is not an outcome");
-  assert.deepEqual(ps.map((p) => p.charterSectionId), ["cs_1", "cs_2"]);
-  assert.deepEqual(ps.map((p) => p.text), ["Revenue growth", "Customer retention"]);
-  for (const p of ps) {
-    assert.equal(p.parentKey, null);
-    assert.equal(p.state, "proposed", "nothing is adopted by derivation — a human adopts");
-    assert.equal(p.source.origin, "charter");
-  }
-});
-
-test("EVERYTHING derived is proposed — derivation can never adopt", () => {
-  const r = deriveMandate({
-    charterSections: CHARTER,
-    // Both of these overlap a pillar's own words, so both are PLACEABLE — see
-    // the unplaced-node test below for the other half.
-    kpiCategories: [{ id: "revenue-coverage", name: "Revenue pipeline coverage", examples: ["pipeline_coverage_x"] }],
-    priorities: [{ id: "p1", title: "Lift retention among customers we win" }],
-    manifest: MANIFEST,
-  });
-  assert.ok(r.objectives.length >= 4);
-  for (const o of r.objectives) {
-    assert.equal(o.state, "proposed", `"${o.key}" must be proposed, not ${o.state}`);
-    assert.ok(!o.adoptedById, "derivation must never stamp an adopter");
-  }
-  // And therefore nothing here can drive work: adoptedObjectives is empty.
-  const validation = validateMandateBody(r.objectives, { ownerMemberId: "mem_self" });
-  assert.equal(validation.errors.length, 0, `derived tree must be structurally valid: ${validation.errors.join("; ")}`);
-});
-
-test("the derived tree is structurally valid: every objective hangs off a pillar", () => {
-  const r = deriveMandate({
-    charterSections: CHARTER,
-    kpiCategories: [
-      { id: "revenue-coverage", name: "Revenue pipeline coverage", examples: ["pipeline_coverage_x"] },
-      { id: "churn", name: "Customer retention rate", examples: ["logo_retention_pct"] },
-    ],
-    manifest: MANIFEST,
-  });
-  const validation = validateMandateBody(r.objectives);
-  assert.equal(validation.ok, true, validation.errors.join("; "));
-
-  for (const o of r.objectives.filter((x) => x.kind !== "PILLAR")) {
-    assert.ok(o.parentKey, `"${o.key}" must have a parent`);
-    const chain = ancestry(r.objectives, o.key);
-    assert.ok(
-      chain.some((n) => n.kind === "PILLAR"),
-      `"${o.key}" must trace to a PILLAR — provenance is the whole point`
-    );
-  }
-});
-
-test("provenance walks objective → pillar → charter clause, offline", () => {
-  const r = deriveMandate({
-    charterSections: CHARTER,
-    kpiCategories: [{ id: "revenue-coverage", name: "Revenue pipeline coverage", examples: ["pipeline_coverage_x"] }],
-    manifest: MANIFEST,
-  });
-  const obj = r.objectives.find((o) => o.kind === "OBJECTIVE");
-  const prov = provenanceOf(r.objectives, obj.key);
-  assert.ok(prov.pillar, "an objective must resolve to a pillar");
-  assert.match(prov.clause, /^cs_/, "and the pillar must carry the charter clause id");
-  assert.ok(prov.chain.includes(obj.key));
-  // The clause id is also stamped on the OBJECTIVE ITSELF, not only on its
-  // pillar. hq's `mandate.propose` takes `charterSectionId`; it has no idea what
-  // a `parentKey` is, so a node that carried provenance only through its parent
-  // reached the server with BOTH provenance columns null — which is why all 35
-  // of A016's proposals had `charterSectionId: null`.
-  assert.equal(obj.charterSectionId, prov.clause);
-});
-
-test("an objective that overlaps NO pillar is carried UNPLACED, never auto-attached to the first one", () => {
-  // The old fallback parented anything unmatched onto `pillarKeys[0]`. On A016
-  // that put `global-footprint` and `capital-formation-aum-growth` under
-  // `own-the-agent-platform-substrate`: an edge that existed, rendered, and was
-  // fiction.
-  const r = deriveMandate({
-    charterSections: CHARTER,
-    kpiCategories: [{ id: "warehouse-latency", name: "Warehouse latency", examples: ["p95_ms"] }],
-    manifest: MANIFEST,
-  });
-  const orphan = r.objectives.find((o) => o.key === "warehouse-latency");
-  assert.ok(orphan, "the node is KEPT — dropping it would delete work somebody asked for");
-  assert.equal(orphan.parentKey, null, "and it is NOT attached to an unrelated pillar");
-  assert.equal(orphan.charterSectionId, null);
-  assert.ok(
-    r.degradations.some((d) => d.kind === "no_pillar_trace" && d.key === "warehouse-latency"),
-    `expected a no_pillar_trace degradation; got ${JSON.stringify(r.degradations)}`
-  );
-  assert.equal(isAdoptable(orphan), false, "an unplaced objective is not adoptable");
-});
-
-test("a slug collision folds into the existing objective instead of minting an `x-2` mirror", () => {
-  // Ten of A016's 35 proposals were `x` (OBJECTIVE/weekly) + `x-2` (GOAL/monthly)
-  // pairs: one accountability, two rows, two obligations, two gaps.
-  const r = deriveMandate({
-    charterSections: CHARTER,
-    kpiCategories: [{ id: "revenue-coverage", name: "Revenue pipeline coverage", examples: ["pipeline_coverage_x"] }],
-    priorities: [{ id: "p1", title: "Revenue coverage" }],
-    manifest: MANIFEST,
-  });
-  const keys = r.objectives.map((o) => o.key);
-  assert.equal(keys.filter((k) => k === "revenue-coverage").length, 1);
-  assert.ok(!keys.some((k) => /-\d+$/.test(k)), `no mirror key may be minted; got ${keys.join(", ")}`);
-  assert.ok(r.degradations.some((d) => d.kind === "duplicate_key"));
-});
-
-test("an objective with no reachable sensor is a recorded DEGRADATION, not a silent human task", () => {
-  const r = deriveMandate({
-    charterSections: CHARTER,
-    // A KPI category nothing in the manifest can measure.
-    kpiCategories: [{ id: "brand-sentiment", name: "Customer brand sentiment", examples: ["nps_score"] }],
-    manifest: MANIFEST,
-  });
-  const obj = r.objectives.find((o) => o.key === "brand-sentiment");
-  assert.ok(obj);
-  assert.notEqual(obj.sensor && obj.sensor.source, "method");
-  assert.ok(
-    r.degradations.some((d) => d.kind === "no_reachable_sensor" && d.key === "brand-sentiment"),
-    `expected a no_reachable_sensor degradation; got ${JSON.stringify(r.degradations)}`
-  );
-});
-
-test("an empty charter is reported, not silently accepted", () => {
-  const r = deriveMandate({ charterSections: [], kpiCategories: [] });
-  assert.ok(r.degradations.some((d) => d.kind === "no_charter_pillars"));
-  assert.ok(r.degradations.some((d) => d.kind === "no_kpi_categories"));
-  assert.equal(r.objectives.length, 0);
-});
-
-test("derivation is deterministic — same inputs, byte-identical tree", () => {
-  const input = {
-    charterSections: CHARTER,
-    kpiCategories: [{ id: "pipeline", name: "Pipeline coverage", examples: ["pipeline_coverage_x"] }],
-    priorities: [{ id: "p1", title: "Land three lighthouse accounts" }],
-    manifest: MANIFEST,
-  };
-  assert.equal(JSON.stringify(deriveMandate(input)), JSON.stringify(deriveMandate(input)));
-});
-
-test("duplicate titles never collide into one key", () => {
-  const r = deriveMandate({
-    charterSections: [
-      { id: "cs_1", kind: "PILLAR", order: 1, title: "Growth", body: "Growth" },
-      { id: "cs_2", kind: "PILLAR", order: 2, title: "Growth", body: "Growth again" },
-    ],
-  });
-  const keys = r.objectives.map((o) => o.key);
-  assert.equal(new Set(keys).size, keys.length, `keys must be unique; got ${keys.join(",")}`);
-});
-
-test("overrides let a human set the real target without re-deriving", () => {
-  const r = deriveMandate({
-    charterSections: CHARTER,
-    kpiCategories: [{ id: "pipeline", name: "Pipeline coverage", examples: ["pipeline_coverage_x"] }],
-    manifest: MANIFEST,
-    overrides: { pipeline: { target: 3.5, tolerance: 0.2, cadence: "monthly", direction: "up" } },
-  });
-  const obj = r.objectives.find((o) => o.key === "pipeline");
-  assert.equal(obj.target, 3.5);
-  assert.equal(obj.tolerance, 0.2);
-  assert.equal(obj.cadence, "monthly");
-});
-
-test("toMandateBody produces the shape the cache and compiler consume", () => {
-  const r = deriveMandate({ charterSections: CHARTER, kpiCategories: [{ id: "pipeline", name: "Pipeline" }] });
-  const body = toMandateBody({ memberId: "mem_self", objectives: r.objectives });
-  assert.equal(body.memberId, "mem_self");
-  assert.ok(Array.isArray(body.objectives));
-  // NOT a number. A locally-derived body is the OFFLINE fallback, and an offline
-  // agent cannot know what it is funded for. This assertion used to demand a
-  // number and got the hardcoded 500 that made "I never asked" look exactly like
-  // "I asked and was told 500". Null is the true answer, and it must be PRESENT.
-  assert.ok(Object.prototype.hasOwnProperty.call(body, "budgetCentsPerPeriod"));
-  assert.equal(body.budgetCentsPerPeriod, null);
-  assert.ok(body.degradations.some((d) => d.field === "budgetCentsPerPeriod"));
-  assert.ok(Array.isArray(body.reactsTo));
-  // And it must round-trip through the validator the loop uses.
-  assert.equal(validateMandateBody(body).ok, true);
-});
-
-test("a bare ENTRY ARRAY manifest is tolerated, not a crash", () => {
-  // `[].entries` is Array.prototype.entries — a function. Walking it naively
-  // threw "function is not iterable" and took the whole derivation with it.
-  const fromObject = deriveMandate({
-    charterSections: CHARTER,
-    kpiCategories: [{ id: "pipeline", name: "Pipeline coverage", examples: ["pipeline_coverage_x"] }],
-    manifest: MANIFEST,
-  });
-  const fromArray = deriveMandate({
-    charterSections: CHARTER,
-    kpiCategories: [{ id: "pipeline", name: "Pipeline coverage", examples: ["pipeline_coverage_x"] }],
-    manifest: ENTRIES,
-  });
-  assert.deepEqual(fromArray.objectives, fromObject.objectives);
-});
-
-test("toMandateBody tolerates junk without throwing", () => {
-  const body = toMandateBody({});
-  assert.equal(body.memberId, null);
-  assert.deepEqual(body.objectives, []);
-  assert.equal(validateMandateBody(body).ok, true);
-});

package/lib/mandate/model.test.mjs

@@ -1,164 +0,0 @@
-/**
- * model.test.mjs — the pillar spine: validation, provenance, anti-Goodhart.
- * Run: `node --test lib/mandate/model.test.mjs`
- */
-
-"use strict";
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-
-import {
-  objectivesOf,
-  validateMandateBody,
-  buildTree,
-  ancestry,
-  pillarFor,
-  provenanceOf,
-  adoptedObjectives,
-  isSelfAdopted,
-  collaboratorsOf,
-} from "./model.mjs";
-
-const ME = "mem_self";
-const BOSS = "mem_boss";
-
-function tree(over = {}) {
-  return {
-    memberId: ME,
-    objectives: [
-      { key: "growth", kind: "PILLAR", parentKey: null, charterSectionId: "cs_12", state: "active", adoptedById: BOSS, source: { origin: "charter", ref: "cs_12" } },
-      {
-        key: "pipeline",
-        kind: "OBJECTIVE",
-        parentKey: "growth",
-        state: "active",
-        metric: "pipeline_coverage_x",
-        target: 3,
-        tolerance: 0.2,
-        direction: "up",
-        cadence: "weekly",
-        sensor: { capability: "crm_list_deals", params: {}, source: "method" },
-        adoptedById: BOSS,
-        collaborators: [{ memberId: "mem_peer", role: "REVIEWER" }],
-        ...over.pipeline,
-      },
-      { key: "win-rate", kind: "GOAL", parentKey: "pipeline", state: "proposed", metric: "win_rate", target: null, cadence: "monthly" },
-    ],
-  };
-}
-
-test("objectivesOf accepts a cache record, a bare body, or an array", () => {
-  const body = tree();
-  assert.equal(objectivesOf(body).length, 3);
-  assert.equal(objectivesOf({ body }).length, 3);
-  assert.equal(objectivesOf(body.objectives).length, 3);
-  assert.deepEqual(objectivesOf(null), []);
-});
-
-test("a well-formed tree validates and yields exactly the adopted, measurable nodes", () => {
-  const body = tree();
-  const v = validateMandateBody(body, { ownerMemberId: ME });
-  assert.equal(v.ok, true, v.errors.join("; "));
-  const adopted = adoptedObjectives(body, { ownerMemberId: ME, badKeys: v.badKeys });
-  assert.deepEqual(adopted.map((o) => o.key), ["pipeline"], "the PILLAR is not measurable; the GOAL is only proposed");
-});
-
-test("ANTI-GOODHART: a seat that adopted its own objective is an ERROR and drives no work", () => {
-  const body = tree({ pipeline: { adoptedById: ME } });
-  const v = validateMandateBody(body, { ownerMemberId: ME });
-  assert.equal(v.ok, false);
-  assert.match(v.errors.join(" "), /self-adopted/);
-  assert.ok(v.badKeys.includes("pipeline"));
-  assert.deepEqual(adoptedObjectives(body, { ownerMemberId: ME }), [], "a self-adopted objective may never drive work");
-  assert.equal(isSelfAdopted(body.objectives[1], ME), true);
-});
-
-test("an active objective with no target / no metric fails closed", () => {
-  const body = tree({ pipeline: { target: null, metric: null } });
-  const v = validateMandateBody(body, { ownerMemberId: ME });
-  assert.equal(v.ok, false);
-  assert.match(v.errors.join(" "), /no metric/);
-  assert.match(v.errors.join(" "), /no numeric target/);
-  assert.ok(v.badKeys.includes("pipeline"));
-});
-
-test("structural errors: bad kind, missing parent, illegal parentage, duplicate key, cycle", () => {
-  const v = validateMandateBody({
-    memberId: ME,
-    objectives: [
-      { key: "a", kind: "WIDGET", state: "proposed" },
-      { key: "b", kind: "GOAL", parentKey: "nope", state: "proposed" },
-      { key: "c", kind: "PILLAR", parentKey: "d", state: "proposed" },
-      { key: "d", kind: "PILLAR", parentKey: null, state: "proposed" },
-      { key: "d", kind: "PILLAR", parentKey: null, state: "proposed" },
-      { key: "x", kind: "OBJECTIVE", parentKey: "y", state: "proposed" },
-      { key: "y", kind: "OBJECTIVE", parentKey: "x", state: "proposed" },
-    ],
-  });
-  const joined = v.errors.join(" | ");
-  assert.match(joined, /unknown kind "WIDGET"/);
-  assert.match(joined, /parent "nope" not found/);
-  assert.match(joined, /PILLAR may not hang from a PILLAR/);
-  assert.match(joined, /duplicate key "d"/);
-  assert.match(joined, /cycle in the objective tree/);
-});
-
-test("an active objective with no adoptedById WARNS (unverifiable) but is not an error", () => {
-  const body = tree({ pipeline: { adoptedById: null } });
-  const v = validateMandateBody(body, { ownerMemberId: ME });
-  assert.equal(v.ok, true, v.errors.join("; "));
-  assert.match(v.warnings.join(" "), /carries no adoptedById/);
-});
-
-test("provenance walks node → objective → pillar → charter clause, offline", () => {
-  const body = tree();
-  assert.deepEqual(ancestry(body, "win-rate").map((n) => n.key), ["win-rate", "pipeline", "growth"]);
-  assert.equal(pillarFor(body, "win-rate").key, "growth");
-  const p = provenanceOf(body, "pipeline");
-  assert.deepEqual(p.chain, ["pipeline", "growth"]);
-  assert.equal(p.clause, "cs_12");
-  assert.equal(p.adoptedBy, BOSS);
-});
-
-test("buildTree nests children and surfaces orphans as roots rather than dropping them", () => {
-  const roots = buildTree({ objectives: [
-    { key: "p", kind: "PILLAR" },
-    { key: "o", kind: "OBJECTIVE", parentKey: "p" },
-    { key: "orphan", kind: "GOAL", parentKey: "vanished" },
-  ] });
-  assert.deepEqual(roots.map((r) => r.key).sort(), ["orphan", "p"]);
-  assert.equal(roots.find((r) => r.key === "p").children[0].key, "o");
-});
-
-test("collaboratorsOf normalises strings, objects and casing", () => {
-  assert.deepEqual(collaboratorsOf({ collaborators: ["m1", { memberId: "m2", role: "reviewer" }, { id: "m3" }, null] }), [
-    { memberId: "m1", role: "CONTRIBUTOR", source: null },
-    { memberId: "m2", role: "REVIEWER", source: null },
-    { memberId: "m3", role: "CONTRIBUTOR", source: null },
-  ]);
-});
-
-test("collaboratorsOf PRESERVES hq's provenance `source` on the edge", () => {
-  // hq's projectObjective stamps this, and goals/classify.mjs is the consumer:
-  // an APPROVER derived from `objective.adoptedById` is a standing governance
-  // edge, not per-task sign-off. Dropping `source` made every self-directed
-  // candidate classify NEEDS_REVIEW.
-  assert.deepEqual(
-    collaboratorsOf({
-      collaborators: [
-        { memberId: "boss", role: "APPROVER", source: "objective.adoptedById" },
-        { memberId: "peer", role: "REVIEWER" },
-      ],
-    }),
-    [
-      { memberId: "boss", role: "APPROVER", source: "objective.adoptedById" },
-      { memberId: "peer", role: "REVIEWER", source: null },
-    ]
-  );
-});
-
-test("badKeys are excluded from adoptedObjectives so a broken node cannot drive work", () => {
-  const body = tree();
-  assert.deepEqual(adoptedObjectives(body, { ownerMemberId: ME, badKeys: ["pipeline"] }), []);
-});