@cohortapp/agent-sdk 2.3.0

package/lib/org/awareness.mjs

@@ -0,0 +1,222 @@
+/**
+ * lib/org/awareness.mjs — situational-awareness SDK over the cached org context.
+ *
+ * PURE read + summarise over the `bootstrapContext` object (or the persisted
+ * `config/org-context.json`). ZERO LLM, ZERO network, ZERO I/O beyond optionally
+ * loading the cache file. Gives a provisioned agent cheap, deterministic answers
+ * to "who owns this?", "who do I escalate to?", "who reports to me?", "who's on
+ * this team?", and "which adopted decisions touch this topic?" — drawn from the
+ * org's authoritative structure rather than guessed from the local archetype.
+ *
+ * Fail-open by contract: every helper tolerates a null/partial context and a
+ * missing part, and returns `null` (single answer) or `[]` (list) when the data
+ * is absent — NEVER throws. The org plane being degraded simply means the agent
+ * gets a null/empty answer and proceeds on its local model.
+ *
+ * Each function accepts either the bootstrapContext object directly, or an
+ * `agentRoot` string (in which case it loads `config/org-context.json`).
+ *
+ * @module lib/org/awareness
+ */
+
+"use strict";
+
+import { loadOrgContext } from "./bootstrap-context.mjs";
+
+/**
+ * Resolve the first arg into a context object. A string is treated as an
+ * agentRoot and loaded from disk; an object is used as-is; anything else → {}.
+ * @param {object|string|null} ctxOrRoot
+ * @returns {object}
+ */
+function resolveCtx(ctxOrRoot) {
+  if (typeof ctxOrRoot === "string") return loadOrgContext(ctxOrRoot) || {};
+  if (ctxOrRoot && typeof ctxOrRoot === "object") return ctxOrRoot;
+  return {};
+}
+
+function lc(v) {
+  return v == null ? "" : String(v).toLowerCase();
+}
+
+/** A node/edge ref → a compact { slug, displayName } summary (or null). */
+function refSummary(ref) {
+  if (!ref || typeof ref !== "object") return null;
+  const slug = ref.slug ? String(ref.slug) : "";
+  if (!slug) return null;
+  return { slug, displayName: ref.displayName != null ? ref.displayName : null };
+}
+
+/**
+ * Who owns a scope? Resolves the accountable owner of a strategy stream matching
+ * `scope` (by stream code/name/mission, case-insensitive substring). Prefers the
+ * RACI "Accountable" assignment, then "Responsible", then the first assigned
+ * member. Returns a summary or null when there is no strategy / no match / no
+ * assigned member.
+ * @param {object|string} ctxOrRoot
+ * @param {string} scope
+ * @returns {{scope:string, stream:{code:string|null,name:string|null}, owner:{slug:string,displayName:string|null}, role:string}|null}
+ */
+export function ownerOf(ctxOrRoot, scope) {
+  const ctx = resolveCtx(ctxOrRoot);
+  const strategy = ctx.strategy;
+  const needle = lc(scope).trim();
+  if (!strategy || !Array.isArray(strategy.streams) || !needle) return null;
+
+  const stream = strategy.streams.find((s) => {
+    if (!s || typeof s !== "object") return false;
+    return lc(s.code).includes(needle) || lc(s.name).includes(needle) || lc(s.mission).includes(needle);
+  });
+  if (!stream || !Array.isArray(stream.raci) || stream.raci.length === 0) return null;
+
+  const byRole = (re) => stream.raci.find((a) => a && a.member && re.test(lc(a.role)));
+  const pick = byRole(/^a\b|accountable/) || byRole(/^r\b|responsible/) || stream.raci.find((a) => a && a.member);
+  const owner = pick && refSummary(pick.member);
+  if (!owner) return null;
+  return {
+    scope: String(scope),
+    stream: { code: stream.code != null ? stream.code : null, name: stream.name != null ? stream.name : null },
+    owner,
+    role: pick.role != null ? String(pick.role) : "",
+  };
+}
+
+/**
+ * Who does THIS agent escalate to? Draws on the self profile's authoritative
+ * `escalationPath` (free text) and supervisor / reporting-line manager. Returns
+ * `{ escalationPath, manager }` (either may be null), or null when neither the
+ * profile nor relationships carry an escalation target.
+ * @param {object|string} ctxOrRoot
+ * @returns {{escalationPath:string|null, manager:{slug:string,displayName:string|null}|null}|null}
+ */
+export function escalateTo(ctxOrRoot) {
+  const ctx = resolveCtx(ctxOrRoot);
+  const profile = ctx.profile || {};
+  const rel = ctx.relationships || {};
+
+  const escalationPath =
+    profile.escalationPath && String(profile.escalationPath).trim() ? String(profile.escalationPath).trim() : null;
+  const manager =
+    refSummary(profile.supervisor) ||
+    refSummary(profile.reportingLine && profile.reportingLine.manager) ||
+    refSummary(rel.reportingLine && rel.reportingLine.manager);
+
+  if (!escalationPath && !manager) return null;
+  return { escalationPath, manager };
+}
+
+/**
+ * Who reports to `selfId`? Prefers the self profile's authoritative `reports`
+ * (when `selfId` is the agent itself or omitted), then the relationships DTO,
+ * then derives from the org chart's reporting edges (manager `from` → report
+ * `to`). Returns `[]` when there are no reports / no data.
+ * @param {object|string} ctxOrRoot
+ * @param {string} [selfId] the manager's member slug
+ * @returns {Array<{slug:string, displayName:string|null, style:string|null}>}
+ */
+export function whoReportsToMe(ctxOrRoot, selfId) {
+  const ctx = resolveCtx(ctxOrRoot);
+  const profile = ctx.profile || {};
+  const rel = ctx.relationships || {};
+  const self = selfId ? String(selfId) : "";
+
+  const fromReportDtos = (arr) =>
+    (Array.isArray(arr) ? arr : [])
+      .map((r) => {
+        const ref = refSummary(r && r.member);
+        if (!ref) return null;
+        return { ...ref, style: r && r.style != null ? String(r.style) : null };
+      })
+      .filter(Boolean);
+
+  // 1) self profile's reports (when it IS the queried member, or no id given).
+  if (Array.isArray(profile.reports) && profile.reports.length && (!self || lc(profile.slug) === lc(self))) {
+    return fromReportDtos(profile.reports);
+  }
+  // 2) relationships DTO for the queried member.
+  if (rel.member && (!self || lc(rel.member.slug) === lc(self)) && Array.isArray(rel.reports) && rel.reports.length) {
+    return fromReportDtos(rel.reports);
+  }
+  // 3) derive from chart reporting edges (from = manager, to = report).
+  const chart = ctx.chart;
+  if (self && chart && Array.isArray(chart.edges)) {
+    const nameBySlug = new Map(
+      (Array.isArray(chart.nodes) ? chart.nodes : []).map((n) => [String(n.slug), n.displayName != null ? n.displayName : null])
+    );
+    const out = [];
+    for (const e of chart.edges) {
+      if (e && e.kind === "reporting" && lc(e.from) === lc(self)) {
+        const slug = String(e.to);
+        out.push({ slug, displayName: nameBySlug.has(slug) ? nameBySlug.get(slug) : null, style: e.type != null ? String(e.type) : null });
+      }
+    }
+    return out;
+  }
+  return [];
+}
+
+/**
+ * Who is on `team`? Filters the org-chart nodes by team (slug / name / shortLabel,
+ * case-insensitive). Falls back to the hierarchy members when no chart is present.
+ * Returns `[]` when there is no data / no match.
+ * @param {object|string} ctxOrRoot
+ * @param {string} team team slug, name, or short label
+ * @returns {Array<{slug:string, displayName:string|null, role:string|null, team:string|null}>}
+ */
+export function colleaguesInTeam(ctxOrRoot, team) {
+  const ctx = resolveCtx(ctxOrRoot);
+  const needle = lc(team).trim();
+  if (!needle) return [];
+
+  const matchTeam = (t) =>
+    !!t && (lc(t.slug) === needle || lc(t.name) === needle || lc(t.shortLabel) === needle || lc(t.name).includes(needle));
+
+  const chart = ctx.chart;
+  if (chart && Array.isArray(chart.nodes)) {
+    return chart.nodes
+      .filter((n) => n && matchTeam(n.team))
+      .map((n) => ({
+        slug: String(n.slug),
+        displayName: n.displayName != null ? n.displayName : null,
+        role: n.role && n.role.title != null ? String(n.role.title) : null,
+        team: n.team && n.team.name != null ? String(n.team.name) : null,
+      }));
+  }
+
+  const hierarchy = ctx.hierarchy;
+  if (hierarchy && Array.isArray(hierarchy.members)) {
+    return hierarchy.members
+      .filter((m) => m && (matchTeam(m.team) || lc(m.team) === needle))
+      .map((m) => ({
+        slug: m.slug != null ? String(m.slug) : "",
+        displayName: m.displayName != null ? m.displayName : null,
+        role: m.role && m.role.title != null ? String(m.role.title) : (m.role != null ? String(m.role) : null),
+        team: m.team && m.team.name != null ? String(m.team.name) : (m.team != null ? String(m.team) : null),
+      }))
+      .filter((m) => m.slug);
+  }
+  return [];
+}
+
+/**
+ * Which adopted decisions touch `topic`? Filters `ctx.decisions` by a
+ * case-insensitive substring across title / rationale / scope / summary / tags.
+ * An empty/blank topic returns ALL cached decisions. Returns `[]` when there are
+ * no decisions / no match.
+ * @param {object|string} ctxOrRoot
+ * @param {string} [topic]
+ * @returns {object[]} the matching decision records (verbatim)
+ */
+export function relevantDecisions(ctxOrRoot, topic) {
+  const ctx = resolveCtx(ctxOrRoot);
+  const decisions = Array.isArray(ctx.decisions) ? ctx.decisions : [];
+  const needle = lc(topic).trim();
+  if (!needle) return decisions.slice();
+
+  return decisions.filter((d) => {
+    if (!d || typeof d !== "object") return false;
+    const tags = Array.isArray(d.tags) ? d.tags.join(" ") : "";
+    const hay = `${lc(d.title)} ${lc(d.rationale)} ${lc(d.scope)} ${lc(d.summary)} ${lc(tags)}`;
+    return hay.includes(needle);
+  });
+}

package/lib/org/awareness.test.mjs

@@ -0,0 +1,159 @@
+/**
+ * awareness.test.mjs — pure situational-awareness helpers over a cached org
+ * context. Fixture-driven; every helper is fail-open (null / [] when data absent).
+ * Run: node --test lib/org/awareness.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { ownerOf, escalateTo, whoReportsToMe, colleaguesInTeam, relevantDecisions } from "./awareness.mjs";
+import { persistOrgContext } from "./bootstrap-context.mjs";
+
+const CTX = {
+  profile: {
+    slug: "robin",
+    displayName: "Robin Vega",
+    escalationPath: "CTO, then CEO for irreversible spend",
+    supervisor: { slug: "layla", displayName: "Layla Al-Masri", role: { title: "CTO" } },
+    reportingLine: { manager: { slug: "layla", displayName: "Layla Al-Masri" } },
+    reports: [
+      { member: { slug: "kai", displayName: "Kai Tan" }, style: "SOLID" },
+      { member: { slug: "noa", displayName: "Noa Levi" }, style: "DOTTED" },
+    ],
+  },
+  chart: {
+    nodes: [
+      { slug: "robin", displayName: "Robin Vega", role: { title: "VP Eng" }, team: { slug: "platform", name: "Platform Engineering", shortLabel: "PLT" } },
+      { slug: "kai", displayName: "Kai Tan", role: { title: "Staff Eng" }, team: { slug: "platform", name: "Platform Engineering", shortLabel: "PLT" } },
+      { slug: "mara", displayName: "Mara Cole", role: { title: "AE" }, team: { slug: "revenue", name: "Revenue", shortLabel: "REV" } },
+    ],
+    edges: [
+      { kind: "reporting", from: "robin", to: "kai", type: "SOLID" },
+      { kind: "reporting", from: "robin", to: "noa", type: "DOTTED" },
+      { kind: "reporting", from: "layla", to: "robin", type: "SOLID" },
+    ],
+  },
+  relationships: {
+    member: { slug: "robin" },
+    reportingLine: { manager: { slug: "layla", displayName: "Layla Al-Masri" } },
+    reports: [{ member: { slug: "kai", displayName: "Kai Tan" }, style: "SOLID" }],
+    governance: [],
+  },
+  strategy: {
+    streams: [
+      { code: "S1", name: "Platform Reliability", mission: "Keep the lights on", raci: [
+        { role: "Accountable", member: { slug: "robin", displayName: "Robin Vega" } },
+        { role: "Responsible", member: { slug: "kai", displayName: "Kai Tan" } },
+      ] },
+      { code: "S2", name: "Revenue Growth", mission: "Grow ARR", raci: [
+        { role: "Accountable", member: { slug: "mara", displayName: "Mara Cole" } },
+      ] },
+    ],
+  },
+  hierarchy: { members: [{ slug: "robin" }, { slug: "kai" }], reporting: [{ from: "layla", to: "robin" }] },
+  decisions: [
+    { id: "D1", title: "Adopt Postgres for the ledger", rationale: "ACID + maturity", scope: "data", status: "adopted" },
+    { id: "D2", title: "Standardise on Slack", rationale: "comms", scope: "ops", tags: ["comms"] },
+  ],
+  policy: { bundleId: "p1" },
+  board: [],
+};
+
+// --- ownerOf ----------------------------------------------------------------
+
+test("ownerOf: matches a strategy stream and returns its Accountable owner", () => {
+  const o = ownerOf(CTX, "reliability");
+  assert.equal(o.owner.slug, "robin");
+  assert.equal(o.role, "Accountable");
+  assert.equal(o.stream.code, "S1");
+  const rev = ownerOf(CTX, "Revenue");
+  assert.equal(rev.owner.slug, "mara");
+});
+
+test("ownerOf: no match / no strategy / blank scope → null", () => {
+  assert.equal(ownerOf(CTX, "nonexistent-scope"), null);
+  assert.equal(ownerOf({}, "reliability"), null);
+  assert.equal(ownerOf(CTX, ""), null);
+  assert.equal(ownerOf(null, "x"), null);
+});
+
+// --- escalateTo -------------------------------------------------------------
+
+test("escalateTo: surfaces escalationPath + supervisor manager", () => {
+  const e = escalateTo(CTX);
+  assert.match(e.escalationPath, /CTO/);
+  assert.equal(e.manager.slug, "layla");
+});
+
+test("escalateTo: falls back to reporting-line manager; null when nothing", () => {
+  const e = escalateTo({ profile: { reportingLine: { manager: { slug: "boss", displayName: "Boss" } } } });
+  assert.equal(e.escalationPath, null);
+  assert.equal(e.manager.slug, "boss");
+  assert.equal(escalateTo({}), null);
+  assert.equal(escalateTo(null), null);
+});
+
+// --- whoReportsToMe ---------------------------------------------------------
+
+test("whoReportsToMe: prefers the self profile's reports", () => {
+  const reports = whoReportsToMe(CTX, "robin");
+  assert.deepEqual(reports.map((r) => r.slug).sort(), ["kai", "noa"]);
+  assert.equal(reports.find((r) => r.slug === "noa").style, "DOTTED");
+});
+
+test("whoReportsToMe: derives from chart edges for a non-self manager", () => {
+  // Querying for "layla" (not the profile member) → derive from chart edges.
+  const reports = whoReportsToMe(CTX, "layla");
+  assert.deepEqual(reports.map((r) => r.slug), ["robin"]);
+});
+
+test("whoReportsToMe: no data → []", () => {
+  assert.deepEqual(whoReportsToMe({}, "x"), []);
+  assert.deepEqual(whoReportsToMe(null), []);
+});
+
+// --- colleaguesInTeam -------------------------------------------------------
+
+test("colleaguesInTeam: filters chart nodes by team slug/name/shortLabel", () => {
+  assert.deepEqual(colleaguesInTeam(CTX, "platform").map((m) => m.slug).sort(), ["kai", "robin"]);
+  assert.deepEqual(colleaguesInTeam(CTX, "Platform Engineering").map((m) => m.slug).sort(), ["kai", "robin"]);
+  assert.deepEqual(colleaguesInTeam(CTX, "REV").map((m) => m.slug), ["mara"]);
+});
+
+test("colleaguesInTeam: falls back to hierarchy members; [] when absent", () => {
+  const ctx = { hierarchy: { members: [{ slug: "x", displayName: "X", team: { slug: "ops", name: "Ops" } }] } };
+  assert.deepEqual(colleaguesInTeam(ctx, "ops").map((m) => m.slug), ["x"]);
+  assert.deepEqual(colleaguesInTeam(CTX, "no-such-team"), []);
+  assert.deepEqual(colleaguesInTeam({}, "platform"), []);
+  assert.deepEqual(colleaguesInTeam(CTX, ""), []);
+});
+
+// --- relevantDecisions ------------------------------------------------------
+
+test("relevantDecisions: filters by topic across title/rationale/scope/tags", () => {
+  assert.deepEqual(relevantDecisions(CTX, "postgres").map((d) => d.id), ["D1"]);
+  assert.deepEqual(relevantDecisions(CTX, "comms").map((d) => d.id), ["D2"]);
+  assert.deepEqual(relevantDecisions(CTX, "data").map((d) => d.id), ["D1"]);
+});
+
+test("relevantDecisions: blank topic returns all; no data → []", () => {
+  assert.equal(relevantDecisions(CTX, "").length, 2);
+  assert.deepEqual(relevantDecisions(CTX, "zzz"), []);
+  assert.deepEqual(relevantDecisions({}, "x"), []);
+});
+
+// --- loads from disk (agentRoot string arg) ---------------------------------
+
+test("awareness helpers accept an agentRoot string (loads config/org-context.json)", () => {
+  const root = mkdtempSync(join(tmpdir(), "maestro-aware-"));
+  mkdirSync(join(root, "config"), { recursive: true });
+  persistOrgContext(root, CTX);
+  assert.equal(ownerOf(root, "reliability").owner.slug, "robin");
+  assert.deepEqual(whoReportsToMe(root, "robin").map((r) => r.slug).sort(), ["kai", "noa"]);
+  assert.equal(escalateTo(root).manager.slug, "layla");
+});

package/lib/org/board.mjs

@@ -0,0 +1,229 @@
+/**
+ * lib/org/board.mjs — agent-side board operations + read-only YAML projection.
+ *
+ * Two layers:
+ *
+ *  1. Board ops — thin, fail-open wrappers over the Cohort board methods via
+ *     lib/org/client.mjs: create / claim / complete / decompose / assign / link /
+ *     ready. The server is the SoT for the board (9-state machine, CAS version,
+ *     DAG links, leases); these helpers just route typed calls and never throw
+ *     (a down server yields an error frame, []/null for reads).
+ *
+ *     decompose/assign are governance-gated server-side (§0.4) — the helpers do
+ *     not pre-check; they forward the call and surface the GOVERNANCE_NOT_READY
+ *     error frame the server returns until governance_ready.
+ *
+ *  2. Projection writer — writes a READ-ONLY YAML view of the board to
+ *     state/org/board/*.yaml so a human (or an offline agent) can see the board
+ *     without the server (§9.1 "read-only YAML projection"). The server is still
+ *     the SoT; these files carry a provenance header marking them derived +
+ *     read-only, written atomically via lib/fs-atomic.mjs. One file per board
+ *     plus a `ready.yaml` for the ready-frontier feed.
+ *
+ * Pure-core + injectable IO: the client is injected as `opts.client` (defaults to
+ * the real client); the projection writer takes an explicit agentRoot. Node
+ * builtins + js-yaml (already a maestro dep, dynamically imported). ESM.
+ *
+ * @module lib/org/board
+ */
+
+"use strict";
+
+import { join } from "node:path";
+
+import { writeFileAtomic } from "../fs-atomic.mjs";
+import * as client from "./client.mjs";
+import { BOARD_STATUS } from "./protocol.mjs";
+
+/** The Cohort client surface this module needs (injectable for tests). */
+function resolveClient(opts) {
+  return (opts && opts.client) || client;
+}
+
+/** Connection options for a client RPC, distilled from opts. */
+function rpcOpts(opts) {
+  return {
+    base: opts && opts.base,
+    token: opts && opts.token,
+    fetchImpl: opts && opts.fetchImpl,
+    idempotencyKey: opts && opts.idempotencyKey,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Board ops (over the Cohort client)
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a board work-item (board.create). Idempotent server-side on the item id.
+ * @param {object} item - { id?, title, status?, priority?, ... }
+ * @param {object} [opts] - { client?, base, token, fetchImpl?, idempotencyKey? }
+ * @returns {Promise<object>} res frame
+ */
+export function createItem(item, opts = {}) {
+  return resolveClient(opts).createItem(item || {}, rpcOpts(opts));
+}
+
+/**
+ * Claim a ready board item (board.claim). The server resolves the race + lease
+ * atomically; the loser gets a LEASE_HELD/CONFLICT error frame.
+ * @param {object} params - { itemId, ... }
+ * @param {object} [opts]
+ * @returns {Promise<object>} res frame
+ */
+export function claimItem(params, opts = {}) {
+  return resolveClient(opts).claimItem(params || {}, rpcOpts(opts));
+}
+
+/**
+ * Complete a board item (board.complete). The server enforces the completion
+ * gate (lease token + expected_run_id CAS + proof).
+ * @param {object} params - { itemId, proof?, ... }
+ * @param {object} [opts]
+ * @returns {Promise<object>} res frame
+ */
+export function completeItem(params, opts = {}) {
+  return resolveClient(opts).completeItem(params || {}, rpcOpts(opts));
+}
+
+/**
+ * Decompose an item into children + blocking links (board.decompose).
+ * GOVERNANCE-GATED server-side.
+ * @param {object} params - { itemId, children:[{title,…}], linkType? }
+ * @param {object} [opts]
+ * @returns {Promise<object>} res frame
+ */
+export function decompose(params, opts = {}) {
+  return resolveClient(opts).boardDecompose(params || {}, rpcOpts(opts));
+}
+
+/**
+ * Assign an owner to an item (board.assign). GOVERNANCE-GATED server-side.
+ * @param {object} params - { itemId, assignee }
+ * @param {object} [opts]
+ * @returns {Promise<object>} res frame
+ */
+export function assign(params, opts = {}) {
+  return resolveClient(opts).boardAssign(params || {}, rpcOpts(opts));
+}
+
+/**
+ * Link two items with a typed DAG edge (board.link). The server runs the DFS
+ * cycle check on insert. NOT governance-gated.
+ * @param {object} params - { fromItem, toItem, linkType? }
+ * @param {object} [opts]
+ * @returns {Promise<object>} res frame
+ */
+export function link(params, opts = {}) {
+  return resolveClient(opts).boardLink(params || {}, rpcOpts(opts));
+}
+
+/**
+ * Read the ready-frontier feed (GET /v1/board.ready). Returns the items array,
+ * or [] on any failure (fail-open).
+ * @param {object} [opts] - { client?, base, token, fetchImpl? }
+ * @returns {Promise<object[]>}
+ */
+export function ready(opts = {}) {
+  return resolveClient(opts).listReady(rpcOpts(opts));
+}
+
+// ---------------------------------------------------------------------------
+// Read-only YAML projection writer
+// ---------------------------------------------------------------------------
+
+/** Header stamped on every projection file: derived, read-only, server is SoT. */
+const PROJECTION_HEADER =
+  "# DERIVED, READ-ONLY board projection written by lib/org/board.mjs.\n" +
+  "# The Cohort org server is the source of truth — DO NOT hand-edit this file;\n" +
+  "# local edits are overwritten on the next sync. For a human/agent to see the\n" +
+  "# board without the server (SPEC-org-server §9.1).\n";
+
+/**
+ * Build the projection document object for a set of board items. Pure: groups by
+ * status (in the canonical BOARD_STATUS order), stamps generatedAt + counts, and
+ * normalises each item to a stable, lease-token-free projection (lease tokens are
+ * never written to any read surface — §8.8). Unknown statuses bucket under
+ * "_other" so a forward-compatible server status can't drop items silently.
+ *
+ * @param {object[]} items
+ * @param {object} [o] - { board?, generatedAt?, cursorHead? }
+ * @returns {{schemaVersion:number, board:string, generatedAt:string, count:number, byStatus:object, items:object[]}}
+ */
+export function buildProjection(items, o = {}) {
+  const list = Array.isArray(items) ? items : [];
+  const projected = list.map(projectItem);
+  const byStatus = {};
+  for (const status of BOARD_STATUS) byStatus[status] = 0;
+  for (const it of projected) {
+    const s = BOARD_STATUS.includes(it.status) ? it.status : "_other";
+    byStatus[s] = (byStatus[s] || 0) + 1;
+  }
+  return {
+    schemaVersion: 1,
+    board: o.board ? String(o.board) : "self",
+    generatedAt: o.generatedAt || new Date().toISOString(),
+    cursorHead: Number.isFinite(o.cursorHead) ? o.cursorHead : undefined,
+    count: projected.length,
+    byStatus,
+    items: projected,
+  };
+}
+
+/** Normalise one server item to the read-only projection shape (token-free). Pure. */
+function projectItem(it) {
+  if (!it || typeof it !== "object") return { id: "", title: "", status: "" };
+  const out = {
+    id: it.id || it.itemId || it.item_id || "",
+    title: it.title || "",
+    status: it.status || "",
+    priority: it.priority || undefined,
+    assignee: it.assignee || it.assignee_agent || it.owner || undefined,
+    blockedBy: Array.isArray(it.blockedBy) ? it.blockedBy.slice() : undefined,
+    updatedAt: it.updatedAt || it.updated_at || undefined,
+  };
+  // Defence-in-depth: never leak a lease/token field to a read surface (§8.8).
+  for (const k of Object.keys(out)) if (out[k] === undefined) delete out[k];
+  return out;
+}
+
+/**
+ * Write a read-only YAML projection of `items` to
+ * state/org/board/<board>.yaml. Atomic (lib/fs-atomic). Returns the path written.
+ * Fail-open: a serialisation/IO error returns null rather than throwing.
+ *
+ * @param {string} agentRoot absolute path to the agent instance root
+ * @param {object[]} items board items (e.g. from board.ready or a snapshot)
+ * @param {object} [o] - { board?, generatedAt?, cursorHead? }
+ * @returns {Promise<string|null>} the file path written, or null on failure
+ */
+export async function writeProjection(agentRoot, items, o = {}) {
+  if (!agentRoot) return null;
+  try {
+    const m = await import("js-yaml");
+    const yaml = m.default || m;
+    const doc = buildProjection(items, o);
+    const body = PROJECTION_HEADER + yaml.dump(doc, { lineWidth: 120, sortKeys: false });
+    const board = doc.board.replace(/[^a-zA-Z0-9_.-]/g, "_") || "self";
+    const path = join(String(agentRoot), "state", "org", "board", `${board}.yaml`);
+    writeFileAtomic(path, body);
+    return path;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Refresh the ready-frontier projection: fetch board.ready from the server and
+ * write it as state/org/board/ready.yaml. Convenience for the org-sync cadence.
+ * Fail-open: a down server writes an EMPTY ready projection (so a stale ready
+ * feed never lingers), and returns the path.
+ *
+ * @param {string} agentRoot
+ * @param {object} [opts] - { client?, base, token, fetchImpl?, generatedAt? }
+ * @returns {Promise<string|null>}
+ */
+export async function writeReadyProjection(agentRoot, opts = {}) {
+  const items = await ready(opts);
+  return writeProjection(agentRoot, items, { board: "ready", generatedAt: opts.generatedAt });
+}