@cohortapp/agent-sdk 2.3.0

package/scripts/cadence/launchd-cloud-relay-wrapper.sh

@@ -0,0 +1,95 @@
+#!/bin/bash
+# launchd-socket-mode-wrapper.sh — Bootstraps env for slack-cloud-relay-client.mjs
+# under launchd.
+#
+# Mirrors launchd-wrapper.sh exactly: launchd's bare env doesn't include
+# HOME, PATH, or AGENT_ROOT, so we hydrate them before exec'ing the
+# Socket Mode listener. Logs land on the external SSD when available
+# (same fallback semantics as the main daemon wrapper).
+#
+# This wrapper is exec'd by ai.maestro.{firstname}-slack-cloud-relay.plist.
+
+set -e
+
+AGENT_ROOT="$(cd "$(dirname "$0")/../.." && pwd -P)"
+export AGENT_ROOT
+export HOME="${HOME:-/Users/$(whoami)}"
+export USER="${USER:-$(whoami)}"
+export PATH="/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH"
+
+# ── SSD redirect ────────────────────────────────────────────────────────────
+# If an external SSD is mounted at /Volumes/{name}, redirect:
+#   - Claude Code per-cwd temp (CLAUDE_CODE_TMPDIR)
+#   - Listener stdout/stderr (via shell redirection at exec time)
+#
+# Detection mirrors launchd-wrapper.sh — first volume under /Volumes that's
+# not a system mount; MAESTRO_SSD_VOLUME env var overrides if multiple SSDs.
+
+SSD_VOLUME="${MAESTRO_SSD_VOLUME:-}"
+if [ -z "$SSD_VOLUME" ]; then
+  for v in /Volumes/*-SSD /Volumes/*SSD* /Volumes/maestro-data; do
+    if [ -d "$v" ] && [ "$v" != "/Volumes/Macintosh HD" ]; then
+      SSD_VOLUME="$v"
+      break
+    fi
+  done
+fi
+
+AGENT_NAME="$(basename "$AGENT_ROOT" | sed 's/-ai$//')"
+SSD_AGENT_ROOT=""
+SSD_WRITABLE=0
+if [ -n "$SSD_VOLUME" ] && [ -d "$SSD_VOLUME" ]; then
+  SSD_AGENT_ROOT="$SSD_VOLUME/maestro/$AGENT_NAME"
+  if mkdir -p "$SSD_AGENT_ROOT/claude-tmp" "$SSD_AGENT_ROOT/logs/slack-cloud-relay" 2>/dev/null && \
+     touch "$SSD_AGENT_ROOT/.write-test-$$" 2>/dev/null; then
+    rm -f "$SSD_AGENT_ROOT/.write-test-$$"
+    SSD_WRITABLE=1
+    export CLAUDE_CODE_TMPDIR="$SSD_AGENT_ROOT/claude-tmp"
+  fi
+fi
+
+cd "$AGENT_ROOT"
+
+# Resolve node binary — prefer nvm, fall back to homebrew, then system.
+NODE_BIN=""
+for candidate in \
+  "$HOME/.nvm/versions/node/v24.11.1/bin/node" \
+  "$HOME/.nvm/versions/node/v24/bin/node" \
+  "$HOME/.nvm/versions/node/v22/bin/node" \
+  "$HOME/.nvm/versions/node/v20/bin/node" \
+  /opt/homebrew/bin/node \
+  /usr/local/bin/node \
+  /usr/bin/node; do
+  if [ -x "$candidate" ]; then
+    NODE_BIN="$candidate"
+    break
+  fi
+done
+if [ -z "$NODE_BIN" ] && [ -d "$HOME/.nvm/versions/node" ]; then
+  NODE_BIN=$(ls -1d "$HOME/.nvm/versions/node"/v*/bin/node 2>/dev/null | sort -V | tail -1)
+fi
+if [ -z "$NODE_BIN" ] || [ ! -x "$NODE_BIN" ]; then
+  echo "[slack-cloud-relay-wrapper] FATAL: could not find node binary" >&2
+  exit 127
+fi
+
+# Node 22.4+ is required for the global WebSocket. Warn (don't fail) on
+# older versions — the user might have polyfilled via `--experimental-websocket`
+# or installed the `ws` package as a fallback.
+NODE_VERSION="$("$NODE_BIN" --version 2>/dev/null || echo 'v0.0.0')"
+NODE_MAJOR="$(echo "$NODE_VERSION" | sed -E 's/^v([0-9]+).*/\1/')"
+if [ "$NODE_MAJOR" -lt 22 ] 2>/dev/null; then
+  echo "[slack-cloud-relay-wrapper] WARNING: Node $NODE_VERSION is older than v22 — global WebSocket may be missing." >&2
+fi
+
+# Exec the listener. Prefer SSD log path if writable, otherwise fall back
+# to internal disk so the listener stays up even when macOS denies launchd
+# write access to /Volumes/{name}.
+if [ "$SSD_WRITABLE" = "1" ]; then
+  LISTENER_LOG="$SSD_AGENT_ROOT/logs/slack-cloud-relay/listener-$(date +%Y-%m-%d).log"
+  exec "$NODE_BIN" "$AGENT_ROOT/scripts/poller/slack-cloud-relay-client.mjs" >> "$LISTENER_LOG" 2>&1
+else
+  LISTENER_LOG="$AGENT_ROOT/logs/polling/slack-cloud-relay-$(date +%Y-%m-%d).log"
+  mkdir -p "$(dirname "$LISTENER_LOG")" 2>/dev/null || true
+  exec "$NODE_BIN" "$AGENT_ROOT/scripts/poller/slack-cloud-relay-client.mjs" >> "$LISTENER_LOG" 2>&1
+fi

package/scripts/cadence/launchd-socket-mode-wrapper.sh

@@ -0,0 +1,95 @@
+#!/bin/bash
+# launchd-socket-mode-wrapper.sh — Bootstraps env for slack-socket-mode.mjs
+# under launchd.
+#
+# Mirrors launchd-wrapper.sh exactly: launchd's bare env doesn't include
+# HOME, PATH, or AGENT_ROOT, so we hydrate them before exec'ing the
+# Socket Mode listener. Logs land on the external SSD when available
+# (same fallback semantics as the main daemon wrapper).
+#
+# This wrapper is exec'd by ai.maestro.{firstname}-slack-socket.plist.
+
+set -e
+
+AGENT_ROOT="$(cd "$(dirname "$0")/../.." && pwd -P)"
+export AGENT_ROOT
+export HOME="${HOME:-/Users/$(whoami)}"
+export USER="${USER:-$(whoami)}"
+export PATH="/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH"
+
+# ── SSD redirect ────────────────────────────────────────────────────────────
+# If an external SSD is mounted at /Volumes/{name}, redirect:
+#   - Claude Code per-cwd temp (CLAUDE_CODE_TMPDIR)
+#   - Listener stdout/stderr (via shell redirection at exec time)
+#
+# Detection mirrors launchd-wrapper.sh — first volume under /Volumes that's
+# not a system mount; MAESTRO_SSD_VOLUME env var overrides if multiple SSDs.
+
+SSD_VOLUME="${MAESTRO_SSD_VOLUME:-}"
+if [ -z "$SSD_VOLUME" ]; then
+  for v in /Volumes/*-SSD /Volumes/*SSD* /Volumes/maestro-data; do
+    if [ -d "$v" ] && [ "$v" != "/Volumes/Macintosh HD" ]; then
+      SSD_VOLUME="$v"
+      break
+    fi
+  done
+fi
+
+AGENT_NAME="$(basename "$AGENT_ROOT" | sed 's/-ai$//')"
+SSD_AGENT_ROOT=""
+SSD_WRITABLE=0
+if [ -n "$SSD_VOLUME" ] && [ -d "$SSD_VOLUME" ]; then
+  SSD_AGENT_ROOT="$SSD_VOLUME/maestro/$AGENT_NAME"
+  if mkdir -p "$SSD_AGENT_ROOT/claude-tmp" "$SSD_AGENT_ROOT/logs/slack-socket" 2>/dev/null && \
+     touch "$SSD_AGENT_ROOT/.write-test-$$" 2>/dev/null; then
+    rm -f "$SSD_AGENT_ROOT/.write-test-$$"
+    SSD_WRITABLE=1
+    export CLAUDE_CODE_TMPDIR="$SSD_AGENT_ROOT/claude-tmp"
+  fi
+fi
+
+cd "$AGENT_ROOT"
+
+# Resolve node binary — prefer nvm, fall back to homebrew, then system.
+NODE_BIN=""
+for candidate in \
+  "$HOME/.nvm/versions/node/v24.11.1/bin/node" \
+  "$HOME/.nvm/versions/node/v24/bin/node" \
+  "$HOME/.nvm/versions/node/v22/bin/node" \
+  "$HOME/.nvm/versions/node/v20/bin/node" \
+  /opt/homebrew/bin/node \
+  /usr/local/bin/node \
+  /usr/bin/node; do
+  if [ -x "$candidate" ]; then
+    NODE_BIN="$candidate"
+    break
+  fi
+done
+if [ -z "$NODE_BIN" ] && [ -d "$HOME/.nvm/versions/node" ]; then
+  NODE_BIN=$(ls -1d "$HOME/.nvm/versions/node"/v*/bin/node 2>/dev/null | sort -V | tail -1)
+fi
+if [ -z "$NODE_BIN" ] || [ ! -x "$NODE_BIN" ]; then
+  echo "[slack-socket-wrapper] FATAL: could not find node binary" >&2
+  exit 127
+fi
+
+# Node 22.4+ is required for the global WebSocket. Warn (don't fail) on
+# older versions — the user might have polyfilled via `--experimental-websocket`
+# or installed the `ws` package as a fallback.
+NODE_VERSION="$("$NODE_BIN" --version 2>/dev/null || echo 'v0.0.0')"
+NODE_MAJOR="$(echo "$NODE_VERSION" | sed -E 's/^v([0-9]+).*/\1/')"
+if [ "$NODE_MAJOR" -lt 22 ] 2>/dev/null; then
+  echo "[slack-socket-wrapper] WARNING: Node $NODE_VERSION is older than v22 — global WebSocket may be missing." >&2
+fi
+
+# Exec the listener. Prefer SSD log path if writable, otherwise fall back
+# to internal disk so the listener stays up even when macOS denies launchd
+# write access to /Volumes/{name}.
+if [ "$SSD_WRITABLE" = "1" ]; then
+  LISTENER_LOG="$SSD_AGENT_ROOT/logs/slack-socket/listener-$(date +%Y-%m-%d).log"
+  exec "$NODE_BIN" "$AGENT_ROOT/scripts/poller/slack-socket-mode.mjs" >> "$LISTENER_LOG" 2>&1
+else
+  LISTENER_LOG="$AGENT_ROOT/logs/polling/slack-socket-$(date +%Y-%m-%d).log"
+  mkdir -p "$(dirname "$LISTENER_LOG")" 2>/dev/null || true
+  exec "$NODE_BIN" "$AGENT_ROOT/scripts/poller/slack-socket-mode.mjs" >> "$LISTENER_LOG" 2>&1
+fi

package/scripts/ci/check-docs-accuracy.mjs

@@ -0,0 +1,493 @@
+/**
+ * check-docs-accuracy.mjs — docs-accuracy CI guard (gaps-product-quality P1-3).
+ *
+ * Docs drift ships in every created repo: README/CLAUDE.md claim agent/tool
+ * counts that no longer match reality, `teams/`+`workflows/` reference agents
+ * that were deleted, and README relative links rot. For an auditor this is
+ * load-bearing documentation fiction. This guard makes a subset of docs
+ * accuracy a CI-enforced property using only Node builtins.
+ *
+ * What it asserts
+ * --------------
+ *  1. COUNTS — the agent-definition and tool counts asserted in README.md /
+ *     CLAUDE.md prose match reality (count `agents/<id>/` dirs; count tools via
+ *     `getAllToolsByCategory()` in lib/tool-definitions.js).
+ *  2. DANGLING AGENT REFS — every `members:` entry in `teams/*.yaml` and every
+ *     `agent:` step in `workflows/*.yaml` resolves to an `agents/<id>/` dir.
+ *  3. BROKEN LINKS — every relative link in README.md resolves to a real file.
+ *
+ * Severity policy (fail-open per the audit, and scoped to this lane's edits)
+ * ------------------------------------------------------------------------
+ * `run()` returns non-zero ONLY for broken README links — the one invariant
+ * that is clean in the tree today and so can be ratcheted shut without churn.
+ * Count drift and dangling agent refs are surfaced as WARN, not FAIL, because:
+ *   - the count claims live in README.md/CLAUDE.md, pre-scrub prose this guard
+ *     can flag but the count fix is a separate docs edit;
+ *   - workflow `agent:` refs are dispatched via an LLM-mediated trigger prompt
+ *     (not a hard symbol resolution), so a missing dir is a smell, not a build
+ *     break — the spec calls for WARN here explicitly;
+ *   - team `members:` drift is the known "21 deleted agents" backlog item,
+ *     tracked for tokenisation rather than a regression this guard introduces.
+ * The pure analyzers below return ALL drift regardless of severity, so tests
+ * (and a future strict mode) can assert detection of each class directly.
+ *
+ * Pure, dependency-light: Node builtins only. ESM (maestro is "type":"module").
+ *
+ * Usage: `node scripts/ci/check-docs-accuracy.mjs`  (exit 0 ok / 1 broken link)
+ * @module scripts/ci/check-docs-accuracy
+ */
+
+"use strict";
+
+import { readdirSync, readFileSync, existsSync, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Repo root: two levels up from scripts/ci/. @type {string} */
+export const REPO_ROOT = path.resolve(
+  fileURLToPath(new URL(".", import.meta.url)),
+  "..",
+  "..",
+);
+
+// ── Reality: count what actually exists ─────────────────────────────────────
+
+/**
+ * Count agent definitions = immediate subdirectories of `agents/` (each holds an
+ * `agent.md`). Returns 0 if the dir is absent.
+ *
+ * @param {string} [cwd=REPO_ROOT]
+ * @returns {number}
+ */
+export function countAgentDirs(cwd = REPO_ROOT) {
+  const dir = path.join(cwd, "agents");
+  if (!existsSync(dir)) return 0;
+  let n = 0;
+  for (const name of readdirSync(dir)) {
+    if (name.startsWith(".")) continue;
+    let st;
+    try {
+      st = statSync(path.join(dir, name));
+    } catch {
+      continue;
+    }
+    if (st.isDirectory()) n++;
+  }
+  return n;
+}
+
+/**
+ * The set of agent ids (dir names) under `agents/`. Used to resolve refs.
+ *
+ * @param {string} [cwd=REPO_ROOT]
+ * @returns {Set<string>}
+ */
+export function agentIdSet(cwd = REPO_ROOT) {
+  const dir = path.join(cwd, "agents");
+  const out = new Set();
+  if (!existsSync(dir)) return out;
+  for (const name of readdirSync(dir)) {
+    if (name.startsWith(".")) continue;
+    let st;
+    try {
+      st = statSync(path.join(dir, name));
+    } catch {
+      continue;
+    }
+    if (st.isDirectory()) out.add(name);
+  }
+  return out;
+}
+
+/**
+ * Count tool definitions by importing the canonical category map. Falls back to
+ * 0 (and a reason) if the module cannot be loaded, so the guard never crashes a
+ * partial checkout.
+ *
+ * @param {string} [cwd=REPO_ROOT]
+ * @returns {Promise<number>}
+ */
+export async function countTools(cwd = REPO_ROOT) {
+  const modPath = path.join(cwd, "lib", "tool-definitions.js");
+  if (!existsSync(modPath)) return 0;
+  const mod = await import(pathToFileUrl(modPath));
+  if (typeof mod.getAllToolsByCategory !== "function") return 0;
+  const cats = mod.getAllToolsByCategory();
+  let total = 0;
+  for (const k of Object.keys(cats)) {
+    if (Array.isArray(cats[k])) total += cats[k].length;
+  }
+  return total;
+}
+
+/** Build a file:// URL for a dynamic import (avoids Windows-path import bugs). */
+function pathToFileUrl(p) {
+  return new URL(`file://${path.resolve(p)}`).href;
+}
+
+// ── Claims: extract the numbers the docs assert ─────────────────────────────
+
+/**
+ * Extract claimed agent counts from a doc body. Matches phrasings like
+ * "34 agent definitions", "34 sub-agent definitions", "34 specialist agent
+ * definitions". Deliberately narrow so unrelated numbers (ports, versions, the
+ * 40–60 generated sub-agents range) are not misread as the static count.
+ *
+ * @param {string} text
+ * @returns {number[]} every distinct claimed count, in document order
+ */
+export function extractAgentCountClaims(text) {
+  if (typeof text !== "string") return [];
+  const out = [];
+  // "<n> [specialist|sub-]agent definitions" — the static-roster phrasing.
+  const re = /\b(\d{1,4})\s+(?:[a-z-]+\s+){0,2}(?:sub-)?agent\s+definitions\b/gi;
+  let m;
+  while ((m = re.exec(text))) out.push(Number(m[1]));
+  return out;
+}
+
+/**
+ * Extract claimed tool counts from a doc body. Matches "30 tools across",
+ * "30 tools." style total claims; ignores the per-access-level counts
+ * ("29 tools", "(24 tools)") which are a separate, intentionally-different
+ * number.
+ *
+ * @param {string} text
+ * @returns {number[]}
+ */
+export function extractToolCountClaims(text) {
+  if (typeof text !== "string") return [];
+  const out = [];
+  const re = /\b(\d{1,4})\s+tools\s+across\b/gi;
+  let m;
+  while ((m = re.exec(text))) out.push(Number(m[1]));
+  return out;
+}
+
+// ── Dangling agent references in teams/ and workflows/ ──────────────────────
+
+/**
+ * Parse the `members:` block of a team YAML into a list of agent ids. A tiny
+ * structural line-walker (no js-yaml dependency): collects `- <id>` items that
+ * are indented deeper than the `members:` key, stopping at the next key at or
+ * above the members indent. This avoids misreading sibling list blocks
+ * (`responsibilities:`, `principles:`) as agent refs.
+ *
+ * @param {string} yamlText
+ * @returns {string[]}
+ */
+export function parseTeamMembers(yamlText) {
+  if (typeof yamlText !== "string") return [];
+  const lines = yamlText.split(/\r?\n/);
+  const out = [];
+  let inMembers = false;
+  let keyIndent = 0;
+  for (const line of lines) {
+    if (!inMembers) {
+      const k = line.match(/^(\s*)members:\s*(#.*)?$/);
+      if (k) {
+        inMembers = true;
+        keyIndent = k[1].length;
+      }
+      continue;
+    }
+    if (line.trim() === "" || line.trim().startsWith("#")) continue;
+    const item = line.match(/^(\s*)-\s*([A-Za-z0-9][A-Za-z0-9_-]*)\s*(#.*)?$/);
+    if (item && item[1].length > keyIndent) {
+      out.push(item[2]);
+      continue;
+    }
+    // Any non-deeper line (a sibling/parent key, or a non-id list item) ends
+    // the members block.
+    inMembers = false;
+  }
+  return out;
+}
+
+/**
+ * Parse every `agent: <id>` step value from a workflow YAML. These are the
+ * agents a workflow dispatches to. `agent-self` is a sentinel (the executing
+ * agent), not a roster id, and is excluded.
+ *
+ * @param {string} yamlText
+ * @returns {string[]}
+ */
+export function parseWorkflowAgentRefs(yamlText) {
+  if (typeof yamlText !== "string") return [];
+  const out = [];
+  const re = /^\s*-?\s*agent:\s*([A-Za-z0-9][A-Za-z0-9_-]*)\s*(#.*)?$/gm;
+  let m;
+  while ((m = re.exec(yamlText))) {
+    if (m[1] === "agent-self") continue;
+    out.push(m[1]);
+  }
+  return out;
+}
+
+/** Recursively list files matching a suffix under a dir. @returns {string[]} */
+function listYaml(dir) {
+  const out = [];
+  if (!existsSync(dir)) return out;
+  for (const name of readdirSync(dir)) {
+    if (name.startsWith(".") || name === "node_modules") continue;
+    const p = path.join(dir, name);
+    let st;
+    try {
+      st = statSync(p);
+    } catch {
+      continue;
+    }
+    if (st.isDirectory()) out.push(...listYaml(p));
+    else if (name.endsWith(".yaml") || name.endsWith(".yml")) out.push(p);
+  }
+  return out;
+}
+
+/**
+ * Find dangling agent references across teams/ and workflows/.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.cwd=REPO_ROOT]
+ * @param {Set<string>} [opts.ids] - pre-computed agent id set (else read disk)
+ * @returns {{ teamRefs: Array<{file:string, agent:string}>, workflowRefs: Array<{file:string, agent:string}> }}
+ */
+export function findDanglingAgentRefs(opts = {}) {
+  const cwd = opts.cwd || REPO_ROOT;
+  const ids = opts.ids || agentIdSet(cwd);
+  const teamRefs = [];
+  const workflowRefs = [];
+
+  // De-dupe per (file, agent): a workflow can dispatch to the same agent across
+  // many steps, and a team could list it twice — one drift row per pair is the
+  // useful unit.
+  const seen = new Set();
+
+  for (const file of listYaml(path.join(cwd, "teams"))) {
+    let body;
+    try {
+      body = readFileSync(file, "utf8");
+    } catch {
+      continue;
+    }
+    const rel = path.relative(cwd, file);
+    for (const a of parseTeamMembers(body)) {
+      if (ids.has(a)) continue;
+      const key = `t:${rel}:${a}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      teamRefs.push({ file: rel, agent: a });
+    }
+  }
+
+  for (const file of listYaml(path.join(cwd, "workflows"))) {
+    let body;
+    try {
+      body = readFileSync(file, "utf8");
+    } catch {
+      continue;
+    }
+    const rel = path.relative(cwd, file);
+    for (const a of parseWorkflowAgentRefs(body)) {
+      if (ids.has(a)) continue;
+      const key = `w:${rel}:${a}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      workflowRefs.push({ file: rel, agent: a });
+    }
+  }
+
+  return { teamRefs, workflowRefs };
+}
+
+// ── README relative-link resolution ─────────────────────────────────────────
+
+/**
+ * Extract relative (on-disk) link targets from markdown. External (http(s)/
+ * mailto/tel/data), pure-anchor (#…) links are skipped; anchors and query
+ * strings are stripped from the path before resolution.
+ *
+ * @param {string} md
+ * @returns {string[]} distinct relative link paths, in document order
+ */
+export function extractRelativeLinks(md) {
+  if (typeof md !== "string") return [];
+  const out = [];
+  const seen = new Set();
+  const re = /\]\(([^)]+)\)/g;
+  let m;
+  while ((m = re.exec(md))) {
+    let link = m[1].trim();
+    // Markdown link can carry a title: ](path "Title") — drop it.
+    link = link.replace(/\s+["'].*["']$/, "");
+    if (/^(https?:|mailto:|tel:|data:|#)/i.test(link)) continue;
+    link = link.split("#")[0].split("?")[0];
+    if (!link) continue;
+    if (seen.has(link)) continue;
+    seen.add(link);
+    out.push(link);
+  }
+  return out;
+}
+
+/**
+ * Find README relative links that do not resolve to a real path.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.cwd=REPO_ROOT]
+ * @returns {{ checked: number, broken: string[] }}
+ */
+export function findBrokenReadmeLinks(opts = {}) {
+  const cwd = opts.cwd || REPO_ROOT;
+  const readme = path.join(cwd, "README.md");
+  if (!existsSync(readme)) return { checked: 0, broken: [] };
+  const md = readFileSync(readme, "utf8");
+  const links = extractRelativeLinks(md);
+  const broken = [];
+  for (const link of links) {
+    let rel = link;
+    try {
+      rel = decodeURIComponent(link);
+    } catch {
+      /* keep raw if it isn't valid percent-encoding */
+    }
+    const abs = path.resolve(cwd, rel);
+    if (!existsSync(abs)) broken.push(link);
+  }
+  return { checked: links.length, broken };
+}
+
+// ── Top-level analysis (pure-ish: reads disk, no process state) ─────────────
+
+/**
+ * Run every docs-accuracy analysis and return a structured report. Severity is
+ * applied by the caller (`run()`); this returns ALL drift it can see.
+ *
+ * @param {object} [opts] @param {string} [opts.cwd=REPO_ROOT]
+ * @returns {Promise<{
+ *   counts: { agentsActual: number, toolsActual: number,
+ *             agentClaims: Array<{file:string, claimed:number}>,
+ *             toolClaims: Array<{file:string, claimed:number}>,
+ *             agentDrift: Array<{file:string, claimed:number, actual:number}>,
+ *             toolDrift: Array<{file:string, claimed:number, actual:number}> },
+ *   danglingTeamRefs: Array<{file:string, agent:string}>,
+ *   danglingWorkflowRefs: Array<{file:string, agent:string}>,
+ *   links: { checked: number, broken: string[] },
+ * }>}
+ */
+export async function analyzeDocsAccuracy(opts = {}) {
+  const cwd = opts.cwd || REPO_ROOT;
+
+  const agentsActual = countAgentDirs(cwd);
+  const toolsActual = await countTools(cwd);
+
+  const docFiles = ["README.md", "CLAUDE.md"];
+  const agentClaims = [];
+  const toolClaims = [];
+  for (const rel of docFiles) {
+    const abs = path.join(cwd, rel);
+    if (!existsSync(abs)) continue;
+    let body;
+    try {
+      body = readFileSync(abs, "utf8");
+    } catch {
+      continue;
+    }
+    for (const c of extractAgentCountClaims(body)) {
+      agentClaims.push({ file: rel, claimed: c });
+    }
+    for (const c of extractToolCountClaims(body)) {
+      toolClaims.push({ file: rel, claimed: c });
+    }
+  }
+
+  const agentDrift = agentClaims
+    .filter((c) => c.claimed !== agentsActual)
+    .map((c) => ({ ...c, actual: agentsActual }));
+  const toolDrift = toolClaims
+    .filter((c) => c.claimed !== toolsActual)
+    .map((c) => ({ ...c, actual: toolsActual }));
+
+  const ids = agentIdSet(cwd);
+  const { teamRefs, workflowRefs } = findDanglingAgentRefs({ cwd, ids });
+  const links = findBrokenReadmeLinks({ cwd });
+
+  return {
+    counts: {
+      agentsActual,
+      toolsActual,
+      agentClaims,
+      toolClaims,
+      agentDrift,
+      toolDrift,
+    },
+    danglingTeamRefs: teamRefs,
+    danglingWorkflowRefs: workflowRefs,
+    links,
+  };
+}
+
+/**
+ * Run the guard and print a human report.
+ *
+ * Hard-fails (exit 1) ONLY on broken README links — the invariant that is clean
+ * today and so safe to ratchet. Count drift and dangling agent refs print as
+ * WARN (see the module header for the rationale).
+ *
+ * @param {string} [cwd=REPO_ROOT]
+ * @returns {Promise<number>} exit code (0 ok, 1 broken README link)
+ */
+export async function run(cwd = REPO_ROOT) {
+  const r = await analyzeDocsAccuracy({ cwd });
+  const warnings = [];
+
+  for (const d of r.counts.agentDrift) {
+    warnings.push(
+      `${d.file}: claims ${d.claimed} agent definitions, but agents/ has ${d.actual}`,
+    );
+  }
+  for (const d of r.counts.toolDrift) {
+    warnings.push(
+      `${d.file}: claims ${d.claimed} tools, but tool-definitions has ${d.actual}`,
+    );
+  }
+  for (const t of r.danglingTeamRefs) {
+    warnings.push(`${t.file}: team member "${t.agent}" has no agents/${t.agent}/`);
+  }
+  for (const w of r.danglingWorkflowRefs) {
+    warnings.push(
+      `${w.file}: workflow agent "${w.agent}" has no agents/${w.agent}/ (LLM-dispatch ref)`,
+    );
+  }
+
+  if (warnings.length) {
+    console.warn("check-docs-accuracy: WARN — docs drift (non-fatal):");
+    for (const w of warnings) console.warn(`  ${w}`);
+  }
+
+  if (r.links.broken.length) {
+    console.error("check-docs-accuracy: FAIL — README relative links broken:");
+    for (const l of r.links.broken) console.error(`  ${l}`);
+    return 1;
+  }
+
+  console.log(
+    `check-docs-accuracy: OK (${r.links.checked} README link(s) resolve; ` +
+      `${r.counts.agentsActual} agents, ${r.counts.toolsActual} tools` +
+      (warnings.length ? `; ${warnings.length} warning(s)` : "") +
+      ")",
+  );
+  return 0;
+}
+
+// Run when invoked directly (not when imported).
+if (import.meta.url === `file://${process.argv[1]}`) {
+  run()
+    .then((code) => process.exit(code))
+    .catch((err) => {
+      console.error(
+        "check-docs-accuracy: ERROR",
+        err && err.message ? err.message : err,
+      );
+      process.exit(2);
+    });
+}