@roadmapperai/mcp 0.1.0

package/server.mjs

@@ -0,0 +1,4019 @@
+#!/usr/bin/env node
+/**
+ * Roadmapper MCP server — zero-dependency stdio JSON-RPC.
+ *
+ * Exposes a planning surface so an agent can read the roadmap and
+ * (when authorized) propose tasks or stamp acceptance grades:
+ *
+ *   list_themes              read
+ *   list_capabilities        read   (optionally filtered by themeId)
+ *   list_tasks               read   (optionally filtered by capabilityId / status)
+ *   get_task                 read   (full task detail, including acceptance + deps)
+ *   get_agents_md            read   (the planning contract)
+ *   propose_task             write  (requires SUPABASE_SERVICE_ROLE_KEY)
+ *   submit_acceptance_grades write  (requires SUPABASE_SERVICE_ROLE_KEY)
+ *
+ * Data sources, in order:
+ *   1. Local seed at src/data/roadmap.json (always read).
+ *   2. Workspace edits via Supabase REST, when SUPABASE_URL,
+ *      SUPABASE_WORKSPACE_ID, and either SUPABASE_PUBLISHABLE_KEY or
+ *      the legacy SUPABASE_ANON_KEY are set. Edits override / extend
+ *      the seed exactly like the app does.
+ *   3. Writes require SUPABASE_SERVICE_ROLE_KEY (bypasses RLS). Without
+ *      it the write tools return an error result and the read tools
+ *      still work.
+ *
+ * Wire-up (Claude Code / Claude Desktop / any MCP client):
+ *   {
+ *     "mcpServers": {
+ *       "roadmapper": {
+ *         "command": "node",
+ *         "args": ["/absolute/path/to/roadmap/mcp/server.mjs"],
+ *         "env": {
+ *           "SUPABASE_URL": "...",
+ *           "SUPABASE_PUBLISHABLE_KEY": "sb_publishable_...",
+ *           "SUPABASE_WORKSPACE_ID": "...",
+ *           "SUPABASE_SERVICE_ROLE_KEY": "..."
+ *         }
+ *       }
+ *     }
+ *   }
+ *
+ * Self-test: `node mcp/server.mjs --selftest` exercises every tool
+ * against the local seed and exits 0 on success, 1 on failure. Useful
+ * for verifying the install without an MCP client.
+ *
+ * Speaks the MCP stdio protocol: newline-delimited JSON-RPC 2.0 on
+ * stdin/stdout. Logs go to stderr only.
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REPO = resolve(HERE, "..");
+// Seed JSON: dev environment ships the file at src/data/roadmap.json
+// (used by the SPA). The npm-packaged build has no SPA source tree,
+// so readSeed() falls back to an empty roadmap and the real data
+// loads from Supabase as "edits" on top.
+const SEED_PATH = join(REPO, "src", "data", "roadmap.json");
+// AGENTS.md (planning rubric): prefer the copy bundled inside the
+// npm package (HERE/AGENTS.md) so customers get the right rubric
+// without needing the repo. Fall back to REPO/AGENTS.md for local
+// dev where the canonical file lives at the repo root.
+const BUNDLED_AGENTS_PATH = join(HERE, "AGENTS.md");
+const REPO_AGENTS_PATH = join(REPO, "AGENTS.md");
+
+const PROTOCOL_VERSION = "2024-11-05";
+const SERVER_NAME = "roadmapper";
+const SERVER_VERSION = "0.6.0";
+
+// Must match src/types.ts EFFORT_DAYS — AI-era calibration.
+// Fractional values (XS=0.25, S=0.5) get rounded up when used to
+// project a target date below, since date strings are day-resolution.
+const EFFORT_DAYS = { XS: 0.25, S: 0.5, M: 1, L: 3, XL: 8 };
+const VALID_PRIORITIES = new Set(["P0", "P1", "P2", "P3"]);
+const VALID_EFFORTS = new Set(["XS", "S", "M", "L", "XL"]);
+const VALID_KINDS = new Set(["feature", "bug", "chore", "spike"]);
+const VALID_STATUSES = new Set(["delivered", "in_progress", "planned", "exploring"]);
+
+function log(...args) {
+  console.error("[roadmapper-mcp]", ...args);
+}
+
+function send(message) {
+  process.stdout.write(JSON.stringify(message) + "\n");
+}
+
+function readSeed() {
+  try {
+    return JSON.parse(readFileSync(SEED_PATH, "utf-8"));
+  } catch (e) {
+    log("failed to read seed", e.message);
+    return { product: { themes: [] }, capabilities: [], tasks: [], sprints: [] };
+  }
+}
+
+function readAgentsMd() {
+  // Try the bundled copy first (npm install case), then the repo
+  // root copy (local dev). One of them is always present in a
+  // normal install; both missing means the package was assembled
+  // wrong and the rubric is unavailable.
+  try {
+    return readFileSync(BUNDLED_AGENTS_PATH, "utf-8");
+  } catch {
+    try {
+      return readFileSync(REPO_AGENTS_PATH, "utf-8");
+    } catch {
+      return "AGENTS.md not found — rubric unavailable.";
+    }
+  }
+}
+
+/**
+ * The read key used to fetch the workspace row. Accepts the new
+ * publishable key (`sb_publishable_…`) or the legacy `anon`/JWT key.
+ */
+function readKey() {
+  return (
+    process.env.SUPABASE_PUBLISHABLE_KEY ||
+    process.env.SUPABASE_ANON_KEY ||
+    null
+  );
+}
+
+function supabaseConfig() {
+  return {
+    url: process.env.SUPABASE_URL || null,
+    readKey: readKey(),
+    writeKey: process.env.SUPABASE_SERVICE_ROLE_KEY || null,
+    workspaceId: process.env.SUPABASE_WORKSPACE_ID || null,
+  };
+}
+
+/**
+ * Read `.roadmapper/snapshot.json` from the current working directory
+ * once at first access. Returns the workspaceId it names, or null if
+ * the file is missing/malformed. The snapshot is committed by the
+ * snapshot-roadmaps Edge Function into every connected repo's
+ * roadmapper-snapshot branch — so if an agent is running from a
+ * checkout that has it, the cwd unambiguously names a workspace.
+ *
+ * This is the "if I'm working in repo X right now, I almost certainly
+ * mean to write to repo X's workspace" safety net. It catches the
+ * wrong-workspace-push class of mistake before it lands.
+ */
+const SNAPSHOT_FILE = join(".roadmapper", "snapshot.json");
+let _snapshotWorkspace = undefined; // undefined = unread; null = read & absent/bad
+function snapshotWorkspaceId() {
+  if (_snapshotWorkspace !== undefined) return _snapshotWorkspace;
+  try {
+    const path = join(process.cwd(), SNAPSHOT_FILE);
+    if (!existsSync(path)) {
+      _snapshotWorkspace = null;
+      return null;
+    }
+    const raw = JSON.parse(readFileSync(path, "utf8"));
+    if (typeof raw?.workspaceId === "string" && raw.workspaceId.length > 0) {
+      _snapshotWorkspace = raw.workspaceId;
+      return _snapshotWorkspace;
+    }
+    _snapshotWorkspace = null;
+  } catch {
+    // Unreadable / malformed snapshot is non-fatal — the server keeps
+    // serving with env + per-call defaults. Operators see the warning
+    // when callTool surfaces "no workspace" or via --selftest.
+    _snapshotWorkspace = null;
+  }
+  return _snapshotWorkspace;
+}
+
+// Test hook for selftest. Module-internal; not surfaced via MCP. Pass
+// `undefined` to force snapshotWorkspaceId() to re-read from disk on
+// next call, or a string/null to short-circuit the cache.
+function __setSnapshotWorkspaceForTest(value) {
+  _snapshotWorkspace = value;
+}
+
+/**
+ * Resolve the workspace id for a tool call. Resolution order:
+ *   1. Explicit `workspaceId` arg on the call.
+ *   2. `.roadmapper/snapshot.json` in the cwd (committed by the
+ *      snapshot-roadmaps cron — names the workspace this repo
+ *      belongs to).
+ *   3. Env-driven `SUPABASE_WORKSPACE_ID`.
+ *   4. null.
+ *
+ * Snapshot beats env because the snapshot reflects "where the agent
+ * is right now", while the env reflects "where the operator pointed
+ * the MCP install when they configured it". Cwd-specific wins.
+ *
+ * Mutators with an explicit `workspaceId` arg that conflicts with the
+ * cwd snapshot are refused upstream in `callTool` — see the
+ * cross-workspace guard there.
+ */
+function resolveWorkspaceId(argWorkspaceId) {
+  if (argWorkspaceId) return argWorkspaceId;
+  const snap = snapshotWorkspaceId();
+  if (snap) return snap;
+  return supabaseConfig().workspaceId ?? null;
+}
+
+/**
+ * Read the workspace's current entity state directly from the
+ * normalized tables (Stage 3 Piece 6c — `workspaces.edits` column
+ * was dropped). Returns `{ themes, capabilities, tasks }` in the
+ * legacy camelCase shape the rest of MCP consumes, or `null` if
+ * the read failed (callers fall back to the bundled seed).
+ *
+ * Prefers the service-role key when set so RLS doesn't filter
+ * agent reads down to the caller's visible_pillars allow-list.
+ */
+async function readWorkspaceProjected(wsIdOverride) {
+  const { url, readKey: anonKey, writeKey } = supabaseConfig();
+  const workspaceId = resolveWorkspaceId(wsIdOverride);
+  const key = writeKey || anonKey;
+  if (!url || !key || !workspaceId) return null;
+  const filter = `workspace_id=eq.${encodeURIComponent(workspaceId)}`;
+  const headers = {
+    apikey: key,
+    Authorization: `Bearer ${key}`,
+    Accept: "application/json",
+  };
+  const fetchTable = async (path) => {
+    const res = await fetch(`${url}/rest/v1/${path}&${filter}`, { headers });
+    if (!res.ok) {
+      throw new Error(`${path}: ${res.status} ${await res.text().catch(() => "")}`);
+    }
+    return res.json();
+  };
+  try {
+    const [pillars, caps, tasks] = await Promise.all([
+      fetchTable("pillars?select=*"),
+      fetchTable("capabilities?select=*"),
+      fetchTable("tasks?select=*"),
+    ]);
+    return {
+      themes: pillars.map(rowToThemeProjected),
+      capabilities: caps.map(rowToCapabilityProjected),
+      tasks: tasks.map(rowToTaskProjected),
+    };
+  } catch (e) {
+    log("supabase entity read failed:", e.message);
+    return null;
+  }
+}
+
+/** Row → camelCase projection helpers. Snake-case columns map to
+ *  the same camelCase keys the SPA + agent surfaces have always
+ *  used; the legacy JSONB shape and these table rows agree on
+ *  every field. */
+function rowToThemeProjected(r) {
+  return stripUndefined({
+    id: r.id,
+    name: r.name,
+    description: r.description,
+    color: r.color,
+    targetRoi: r.target_roi,
+    ownerUserId: r.owner_user_id,
+    idempotencyKey: r.idempotency_key,
+    archived: r.archived,
+    archivedAt: r.archived_at,
+    createdAt: r.created_at,
+    updatedAt: r.updated_at,
+  });
+}
+function rowToCapabilityProjected(r) {
+  return stripUndefined({
+    id: r.id,
+    pillarId: r.pillar_id,
+    name: r.name,
+    description: r.description,
+    outcome: r.outcome,
+    reach: r.reach,
+    impact: r.impact,
+    confidence: r.confidence,
+    roi: r.roi,
+    color: r.color,
+    status: r.status,
+    start: r.start_date,
+    target: r.target_date,
+    delivered: r.delivered_date,
+    originalTarget: r.original_target,
+    laneRow: r.lane_row,
+    ownerUserId: r.owner_user_id,
+    specRef: r.spec_ref,
+    outcomeStatus: r.outcome_status,
+    outcomeCheckedAt: r.outcome_checked_at,
+    outcomeReadings: r.outcome_readings,
+    dependsOn: r.depends_on,
+    idempotencyKey: r.idempotency_key,
+    archived: r.archived,
+    archivedAt: r.archived_at,
+    createdAt: r.created_at,
+    updatedAt: r.updated_at,
+  });
+}
+function rowToTaskProjected(r) {
+  return stripUndefined({
+    id: r.id,
+    capabilityId: r.capability_id,
+    pillarId: r.pillar_id,
+    title: r.title,
+    summary: r.summary,
+    status: r.status,
+    priority: r.priority,
+    effort: r.effort,
+    start: r.start_date,
+    target: r.target_date,
+    originalTarget: r.original_target,
+    delivered: r.delivered_date,
+    deliveredAt: r.delivered_at,
+    progress: r.progress,
+    owner: r.owner,
+    ownerGithub: r.owner_github,
+    ownerAvatarUrl: r.owner_avatar_url,
+    ownerUserId: r.owner_user_id,
+    laneRow: r.lane_row,
+    matrixDx: r.matrix_dx,
+    matrixDy: r.matrix_dy,
+    team: r.team,
+    kind: r.kind,
+    authorKind: r.author_kind,
+    expectedPRs: r.expected_prs,
+    expectedScope: r.expected_scope,
+    tags: r.tags,
+    prs: r.prs,
+    links: r.links,
+    acceptance: r.acceptance,
+    acceptanceGrades: r.acceptance_grades,
+    dependsOn: r.depends_on,
+    idempotencyKey: r.idempotency_key,
+    archived: r.archived,
+    archivedAt: r.archived_at,
+    createdAt: r.created_at,
+    updatedAt: r.updated_at,
+  });
+}
+function stripUndefined(o) {
+  for (const k of Object.keys(o)) if (o[k] === undefined || o[k] === null) delete o[k];
+  return o;
+}
+
+/**
+ * Invoke a Postgres function exposed via PostgREST. Used by the
+ * write tools so the read-modify-write happens inside a single
+ * Postgres transaction (with row-level locking on the workspace),
+ * not across two round-trips from the MCP. That's what makes
+ * concurrent agent writes safe — see migration 0006 for the
+ * function bodies.
+ */
+async function rpcCall(fn, body) {
+  const { url, writeKey } = supabaseConfig();
+  // body must already carry p_workspace_id — the per-tool resolver
+  // injects it before calling rpcCall so the override path works.
+  if (!url || !writeKey || !body?.p_workspace_id) {
+    throw new Error(
+      "Write tools require SUPABASE_URL + SUPABASE_SERVICE_ROLE_KEY in env and a resolvable workspaceId (either SUPABASE_WORKSPACE_ID env or workspaceId arg)."
+    );
+  }
+  const res = await fetch(`${url}/rest/v1/rpc/${fn}`, {
+    method: "POST",
+    headers: {
+      apikey: writeKey,
+      Authorization: `Bearer ${writeKey}`,
+      "content-type": "application/json",
+      Accept: "application/json",
+    },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) {
+    const txt = await res.text();
+    throw new Error(
+      `rpc ${fn} failed: ${res.status} ${txt.slice(0, 300)}`
+    );
+  }
+  return res.json();
+}
+
+/**
+ * Project (seed + edits) into a flat view the tools can serve.
+ * Mirrors the lightweight subset of src/lib/store.ts merge logic we
+ * need read-only: replace seed records by id with edited copies,
+ * concat new ones, drop deleted ids.
+ */
+function project(seed, edits) {
+  const e = edits ?? {};
+  const themes = mergeList(
+    seed?.product?.themes ?? [],
+    e.themes ?? {},
+    // The app writes new themes to edits.newPillars and deletes to
+    // edits.deletedPillarIds (Theme is still `Pillar` in the schema
+    // for legacy reasons — see src/types.ts comment). The MCP must
+    // read those same keys so a theme created in the UI shows up in
+    // list_themes — and so propose_theme below doesn't have to fight
+    // the app over which key holds the truth.
+    e.newPillars ?? [],
+    e.deletedPillarIds ?? []
+  );
+  const capabilities = mergeList(
+    seed?.capabilities ?? [],
+    e.capabilities ?? {},
+    e.newCapabilities ?? [],
+    e.deletedCapabilityIds ?? []
+  );
+  const tasks = mergeList(
+    seed?.tasks ?? [],
+    e.tasks ?? {},
+    e.newTasks ?? [],
+    e.deletedTaskIds ?? []
+  );
+  return { themes, capabilities, tasks };
+}
+
+/**
+ * Effective capability status — mirrors
+ * effectiveCapabilityStatus + deriveCapabilityStatus in
+ * src/lib/util.ts. Explicit `cap.status` wins; otherwise derived
+ * from linked tasks. Used here to keep delivered capabilities out
+ * of agent-facing lists so plans target work that's still in flight.
+ */
+function effectiveCapabilityStatus(cap, tasks) {
+  if (cap.status) return cap.status;
+  const own = tasks.filter((t) => t.capabilityId === cap.id);
+  if (own.length === 0) return "exploring";
+  if (own.every((t) => t.status === "delivered")) return "delivered";
+  if (own.some((t) => t.status === "in_progress")) return "in_progress";
+  if (own.every((t) => t.status === "exploring")) return "exploring";
+  return "planned";
+}
+
+function mergeList(seedList, patches, additions, deletedIds) {
+  const del = new Set(deletedIds);
+  const merged = [];
+  for (const row of seedList) {
+    if (del.has(row.id)) continue;
+    merged.push({ ...row, ...(patches[row.id] ?? {}) });
+  }
+  // Patches apply to newly-created records too — matches the app's
+  // store merge. This is what makes grade_acceptance writes visible
+  // on tasks created via propose_task earlier in the same workspace.
+  for (const row of additions) {
+    if (!del.has(row.id)) merged.push({ ...row, ...(patches[row.id] ?? {}) });
+  }
+  return merged;
+}
+
+function todayISO() {
+  return new Date().toISOString().slice(0, 10);
+}
+function addDays(iso, days) {
+  const d = new Date(iso + "T00:00:00Z");
+  d.setUTCDate(d.getUTCDate() + days);
+  return d.toISOString().slice(0, 10);
+}
+
+/**
+ * Decode the five HTML entities agents most often emit when they
+ * think they're rendering into markup. Mirrors src/lib/text.ts.
+ *
+ * Agents sometimes propose names like `Sandbox & Test Mode` —
+ * the storage path stores that verbatim, then React renders it
+ * literally in the UI. Apply this on every propose / update path
+ * so values land in the database in their decoded form.
+ */
+function decodeHtmlEntities(input) {
+  if (!input || typeof input !== "string") return input;
+  return input
+    .replace(/&/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&#x27;/gi, "'");
+}
+/** Convenience: trim AND decode HTML entities on the same value. */
+function cleanText(s) {
+  return decodeHtmlEntities((s ?? "").trim());
+}
+function randomTaskId() {
+  // TK-NNNNNN — 6-digit zero-padded random. Matches the app's format
+  // and stays comfortably under collision risk for any realistic ws.
+  return `TK-${String(Math.floor(Math.random() * 1_000_000)).padStart(6, "0")}`;
+}
+function randomThemeId() {
+  // TH-NNNNNN — 6-digit numeric, same shape store.ts numericId6 emits.
+  return `TH-${String(100000 + Math.floor(Math.random() * 900000))}`;
+}
+function randomCapabilityId() {
+  // CAP-XXXXXX — 6-char uppercase base36, matches store.ts uid("CAP").
+  return `CAP-${Math.random().toString(36).slice(2, 8).toUpperCase()}`;
+}
+
+const VALID_IMPACTS = new Set([3, 2, 1, 0.5, 0.25]);
+
+// ── Validators ────────────────────────────────────────────────────
+// Server-side guardrails for the planning rubric in AGENTS.md.
+// Every propose_* tool runs these before touching Supabase. With
+// dryRun=true the caller sees the validation result without writing.
+
+// Month names must be followed by whitespace + a digit so we don't
+// false-positive on phrases like "may have moved" or "September lifts"
+// where the month token has nothing to do with a date.
+const TEMPORAL_RE =
+  /\b(20\d\d|q[1-4](\s*20\d\d)?|by\s+\d|(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\w*\s+\d)\b/i;
+const NUMBER_RE = /\d/;
+
+/**
+ * An outcome is "falsifiable" when it carries both a number (the
+ * thing you're moving) and a temporal anchor (when you're checking
+ * it). Empty outcomes are also rejected — every capability needs
+ * one. The regex is intentionally loose so reasonable phrasings
+ * pass: "32% to 55% by Q3 2026", "median 3/quarter by 2026-09",
+ * "5x by 2026" all clear.
+ */
+function validateOutcome(outcome) {
+  const o = (outcome ?? "").trim();
+  if (!o) {
+    return "outcome is required. Use the template: <metric> moves from <baseline> to <target> by <date>, measured by <source>.";
+  }
+  const hasNumber = NUMBER_RE.test(o);
+  const hasTemporal = TEMPORAL_RE.test(o);
+  if (!hasNumber || !hasTemporal) {
+    return `outcome must include both a number (the metric) and a date or quarter (when you'll check). Missing: ${[
+      !hasNumber ? "number" : null,
+      !hasTemporal ? "date/quarter" : null,
+    ]
+      .filter(Boolean)
+      .join(" + ")}. See get_agents_md for examples.`;
+  }
+  return null;
+}
+
+function validateName(name, minLen = 8) {
+  const n = (name ?? "").trim();
+  if (!n) return "name is required.";
+  if (n.length < minLen)
+    return `name is too short (${n.length} chars) — aim for ${minLen}+ that describe the bet, not the verb.`;
+  return null;
+}
+
+function validateConfidence(confidence) {
+  if (confidence == null) return null;
+  if (confidence < 0 || confidence > 100)
+    return `confidence must be 0–100, got ${confidence}.`;
+  if (confidence > 95)
+    return `confidence ${confidence} is too high. >95 is reserved for work that's already shipped or behind a flag. Cap at 95 unless you can point to the deployed flag.`;
+  return null;
+}
+
+/**
+ * Warning (not error) when a capability's ROI lands well below the
+ * parent theme's target. Caller can still proceed — but the
+ * warning surfaces in dryRun output so the agent can rethink.
+ */
+function warnRoiVsTheme(roi, theme) {
+  if (roi == null || theme?.targetRoi == null) return null;
+  const floor = theme.targetRoi * 0.7;
+  if (roi < floor) {
+    return `roi $${roi}M is well below 70% of theme "${theme.name}" target ($${theme.targetRoi}M). Justify the gap in your outcome, or rethink the parent theme.`;
+  }
+  return null;
+}
+
+// ── Lightweight Jaccard for suggest_capability_for ────────────────
+//
+// Kept in sync with src/lib/textMatch.ts and api/github-webhook.ts
+// so the three places that score PR-to-capability overlap rank the
+// same matches identically. The "Jaccard" name is a slight misnomer:
+// we normalise by max(|a|,|b|) instead of |a ∪ b| (textbook Jaccard)
+// so a tiny PR title doesn't trivially match a long capability
+// description via two common tokens.
+const STOPWORDS = new Set([
+  "the", "and", "for", "with", "this", "that", "from", "into", "onto", "upon",
+  "fix", "fixes", "fixing", "add", "adds", "adding", "update", "updates", "updating",
+  "remove", "removes", "removing", "refactor", "refactors", "refactoring",
+  "feat", "feature", "bug", "bugfix", "chore", "wip", "draft",
+  "use", "uses", "using", "make", "makes", "making", "support", "supports",
+  "via", "out", "off", "now", "but", "any", "all", "new", "old",
+  "pull", "request", "merge", "branch", "commit", "test", "tests", "testing",
+]);
+function tokenize(s) {
+  const out = new Set();
+  const lower = (s ?? "").toLowerCase().replace(/[^a-z0-9 ]+/g, " ");
+  for (const w of lower.split(/\s+/)) {
+    if (w.length < 3) continue;
+    if (STOPWORDS.has(w)) continue;
+    out.add(w);
+  }
+  return out;
+}
+function jaccardScore(a, b) {
+  if (a.size === 0 || b.size === 0) return 0;
+  let overlap = 0;
+  for (const t of a) if (b.has(t)) overlap += 1;
+  if (overlap === 0) return 0;
+  return overlap / Math.max(a.size, b.size);
+}
+
+// ── Session state + enforcement gates ─────────────────────────────
+//
+// One process serves one MCP client (stdio). State below is the
+// client's session-scoped memory: when get_agents_md was last
+// fetched, how many mutator calls have been attempted without the
+// rubric, etc.
+//
+// The point of this is to stop relying on the agent's discretion to
+// follow the rubric. Tool descriptions catch most cases; the gate
+// here catches the rest with a structured error whose `fix` field
+// names the exact next call.
+const session = {
+  startedAt: Date.now(),
+  rubricFetchedAt: null,
+  // "Discovery" gates — the agent must have looked at the current
+  // catalogue before proposing new theme/cap records. Prevents the
+  // "agent invents Theme X when 'X-ish Theme' already exists"
+  // failure mode that token-overlap alone catches inconsistently.
+  themesListedAt: null,
+  capsDiscoveredAt: null,
+  mutatorAttempts: 0,
+  mutatorBlocks: 0,
+};
+
+function resetSession() {
+  session.startedAt = Date.now();
+  session.rubricFetchedAt = null;
+  session.themesListedAt = null;
+  session.capsDiscoveredAt = null;
+  session.mutatorAttempts = 0;
+  session.mutatorBlocks = 0;
+}
+
+/**
+ * Build the structured "prereq missing" result the mutators return
+ * when the agent hasn't fetched the rubric this session. The shape
+ * matters: LLMs recover well from errors whose `fix` field names
+ * the exact next call, badly from prose. Mirrors the recommendation
+ * in the MCP-effectiveness memo.
+ */
+function rubricMissingResult(toolName) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(
+          {
+            error: "prerequisite_missing",
+            message:
+              `Call get_agents_md first this session, then retry ${toolName}. ` +
+              "The rubric defines acceptance criteria shape and grading dimensions — " +
+              "proposals filed without it will not round-trip.",
+            fix: "get_agents_md()",
+          },
+          null,
+          2
+        ),
+      },
+    ],
+    isError: true,
+  };
+}
+
+/**
+ * Structured error for the per-tool discovery gates. Same shape +
+ * rationale as rubricMissingResult — LLMs follow the `fix` field
+ * reliably when it names the exact next call.
+ */
+function discoveryMissingResult(toolName, fixCall, rationale) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(
+          {
+            error: "discovery_missing",
+            message:
+              `Call ${fixCall} first this session, then retry ${toolName}. ${rationale}`,
+            fix: fixCall,
+          },
+          null,
+          2
+        ),
+      },
+    ],
+    isError: true,
+  };
+}
+
+/**
+ * Telemetry write — fire-and-forget POST to public.mcp_telemetry
+ * via PostgREST when a service-role key is set. Never blocks the
+ * caller; failures are logged to stderr and swallowed.
+ *
+ * The point isn't real-time observability — it's accumulating
+ * signal about *where* the rubric flow breaks so we can tune
+ * descriptions and gates against real failure patterns.
+ */
+function recordTelemetry(event, payload, wsIdOverride) {
+  const { url, writeKey, workspaceId: envWsId } = supabaseConfig();
+  if (!url || !writeKey) return; // self-hosted devs without service key get no-op
+  const body = {
+    event,
+    // Prefer the per-call workspace when one was passed. Mutator
+    // calls resolve this once at the top of callTool so the row
+    // captures the workspace actually being acted on, not just the
+    // env default.
+    workspace_id: wsIdOverride ?? envWsId ?? null,
+    server_version: SERVER_VERSION,
+    session_started_at: new Date(session.startedAt).toISOString(),
+    rubric_fetched_at: session.rubricFetchedAt
+      ? new Date(session.rubricFetchedAt).toISOString()
+      : null,
+    payload: payload ?? null,
+  };
+  fetch(`${url}/rest/v1/mcp_telemetry`, {
+    method: "POST",
+    headers: {
+      apikey: writeKey,
+      Authorization: `Bearer ${writeKey}`,
+      "content-type": "application/json",
+      Prefer: "return=minimal",
+    },
+    body: JSON.stringify(body),
+  }).catch((e) => {
+    log("telemetry write failed (non-fatal)", e.message);
+  });
+}
+
+const TOOLS = [
+  {
+    name: "list_themes",
+    description:
+      "List active themes (strategic pillars). Excludes archived themes by default.\n\n" +
+      "USE WHEN: orienting to the roadmap at session start, scoping which theme a capability belongs under, or answering 'what strategic bets are we tracking'.\n" +
+      "PREREQUISITE: none — read-only.\n" +
+      "ANTI-PATTERN: do not call to look up a single theme by id (use get_roadmap_snapshot or filter the response yourself). Do not call repeatedly in one session — theme catalogue is years-stable. Pass includeArchived=true only when reviewing closed bets — almost never in a planning session.\n" +
+      "EXAMPLE: list_themes()",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspaceId: { type: "string" },
+        includeArchived: { type: "boolean" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "list_capabilities",
+    description:
+      "List active capabilities (quarterly bets). Excludes delivered and archived capabilities by default — agents should target work that's still in flight.\n\n" +
+      "USE WHEN: planning a feature and need to find the right parent capability, reviewing in-flight bets, or scoping what's still on the table this quarter.\n" +
+      "PREREQUISITE: none — read-only. For routing a specific work description, prefer suggest_capability_for which ranks by token overlap.\n" +
+      "ANTI-PATTERN: do not call to find a capability when you already know its id (use get_roadmap_snapshot for richer context). Pass includeDelivered=true or includeArchived=true only when reviewing historical bets — almost never in a planning session.\n" +
+      "EXAMPLE: list_capabilities({ themeId: 'TH-XXX' })",
+    inputSchema: {
+      type: "object",
+      properties: {
+        themeId: { type: "string" },
+        includeDelivered: { type: "boolean" },
+        includeArchived: { type: "boolean" },
+        workspaceId: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "list_tasks",
+    description:
+      "List tasks. Filter by capabilityId or status. Excludes archived tasks by default.\n\n" +
+      "USE WHEN: surveying what already exists under a capability before proposing a new task (avoid duplicates), reviewing a status bucket (e.g. all in_progress), or answering 'what's open right now'.\n" +
+      "PREREQUISITE: none — read-only.\n" +
+      "ANTI-PATTERN: do not call to track in-progress work within a single conversation — use the harness TodoWrite tool. Do not call without a filter when the workspace has many tasks; scope by capabilityId or status. Pass includeArchived=true only when reviewing closed history.\n" +
+      "EXAMPLE: list_tasks({ capabilityId: 'CAP-XXX', status: 'in_progress' })",
+    inputSchema: {
+      type: "object",
+      properties: {
+        capabilityId: { type: "string" },
+        status: {
+          type: "string",
+          enum: ["delivered", "in_progress", "planned", "exploring"],
+        },
+        includeArchived: { type: "boolean" },
+        workspaceId: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_task",
+    description:
+      "Return one task by id with full detail: title, summary, status, owner, acceptance criteria, dependsOn, attached PRs, and acceptance grades.\n\n" +
+      "USE WHEN: about to submit acceptance grades (need the criteria indexes), reviewing a specific task before linking a PR, or answering questions about a particular TK-XXXXXX.\n" +
+      "PREREQUISITE: none — read-only.\n" +
+      "ANTI-PATTERN: do not call to discover that a task exists — use list_tasks for discovery first. Don't loop over many ids; list_tasks returns the same shape in one round trip.\n" +
+      "EXAMPLE: get_task({ id: 'TK-100201' })",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string" },
+        workspaceId: { type: "string" },
+      },
+      required: ["id"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_agents_md",
+    description:
+      "Return the AGENTS.md planning contract — task shape, acceptance criteria format, capability outcome rubric, grading dimensions.\n\n" +
+      "USE WHEN: starting ANY planning session before calling propose_task / propose_capability / propose_theme / submit_acceptance_grades. Call this ONCE per session — the mutator tools refuse without it. Cache the result on your side.\n" +
+      "PREREQUISITE: none.\n" +
+      "ANTI-PATTERN: do not skip when the user says 'just plan some features' — the rubric IS the planning interface; proposals filed without it won't round-trip into the product.\n" +
+      "EXAMPLE: get_agents_md()",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+  {
+    name: "get_roadmap_snapshot",
+    description:
+      "Single-call orient: themes + active capabilities + in-flight tasks for the workspace, plus the resolved workspaceId. Always live. Excludes archived entities by default.\n\n" +
+      "USE WHEN: starting fresh in a workspace and need the whole canonical model in one read, or before opening a PR to confirm which workspace + capability to attach to.\n" +
+      "PREREQUISITE: none — read-only. Often the very first call after get_agents_md.\n" +
+      "ANTI-PATTERN: do not call repeatedly within one planning pass; the data doesn't change inside a single session. Use list_tasks / list_capabilities if you need just one slice. Pass includeArchived=true only when surveying historical state.\n" +
+      "EXAMPLE: get_roadmap_snapshot()",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspaceId: {
+          type: "string",
+          description:
+            "Optional. Override the env-default workspace. Useful when the agent is operating against a .roadmapper/snapshot.json that names its own workspace.",
+        },
+        includeArchived: { type: "boolean" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "propose_task",
+    description:
+      "Propose a new task under an existing roadmapper capability. Server stamps authorKind='agent' + status='planned' + a TK-NNNNNN id.\n\n" +
+      "USE WHEN: the user asks to plan features, design new work, sketch a roadmap, file a TODO that should persist beyond this conversation, or break a capability into deliverables.\n" +
+      "PREREQUISITE: get_agents_md once this session (the server enforces this and returns an error with a `fix` field if missing). Call suggest_capability_for first to find the right parent capability — do not invent a new one.\n" +
+      "ANTI-PATTERN: do not call to track in-progress work within a single conversation — use the harness TodoWrite tool. Do not call to log a bug discovered during implementation — file in the issue tracker, not roadmapper. Do not call when you don't know which capability the task belongs under; resolve that first.\n" +
+      "EXAMPLE: propose_task({ capabilityId: 'CAP-XXX', title: 'Drag-and-drop block reorder', acceptance: ['Block can be dragged with mouse + keyboard', 'Order persists across reloads'], idempotencyKey: 'session-1-task-3' })\n\n" +
+      "Requires SUPABASE_SERVICE_ROLE_KEY. Pass idempotencyKey so retries don't duplicate. Pass dryRun: true to validate without writing. Pass workspaceId to target a workspace other than the env default.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        capabilityId: { type: "string" },
+        title: { type: "string" },
+        summary: { type: "string" },
+        effort: { type: "string", enum: ["XS", "S", "M", "L", "XL"] },
+        priority: { type: "string", enum: ["P0", "P1", "P2", "P3"] },
+        kind: { type: "string", enum: ["feature", "bug", "chore", "spike"] },
+        owner: { type: "string" },
+        acceptance: { type: "array", items: { type: "string" } },
+        dependsOn: { type: "array", items: { type: "string" } },
+        expectedPRs: {
+          type: "number",
+          description:
+            "Advisory cap on merged PRs for this task. Unset by default (no cap). Webhook records a scope_overrun audit row when the actual count exceeds this. Not enforced; this is a hint to track how often tasks blow their envelope.",
+        },
+        expectedScope: {
+          type: "number",
+          description:
+            "Advisory cap on cumulative LoC (additions+deletions) across all PRs linked to this task. Webhook records a scope_overrun audit row when exceeded. Not enforced.",
+        },
+        idempotencyKey: { type: "string" },
+        dryRun: { type: "boolean" },
+        workspaceId: { type: "string" },
+      },
+      required: ["capabilityId", "title"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "propose_theme",
+    description:
+      "Propose a new strategic theme (pillar). Themes are years-stable — only propose one when nothing existing fits.\n\n" +
+      "USE WHEN: the work the user is describing genuinely doesn't fit ANY existing theme, AND the user explicitly says they want a new strategic direction. Almost never the right answer in a planning session.\n" +
+      "PREREQUISITE: get_agents_md once this session (enforced). Theme discovery once this session, satisfied by suggest_theme_for (preferred — returns ranked matches with a fit signal), list_themes, or get_roadmap_snapshot. Enforced — the server returns discovery_missing with a fix field if you skip it. Duplicating a theme is the most common failure mode; the gate stops it.\n" +
+      "ANTI-PATTERN: do not call to organize a quarter of work — that's a capability, not a theme. Do not call because the existing themes feel too coarse — they're SUPPOSED to be coarse. Use propose_capability under an existing theme instead.\n" +
+      "EXAMPLE: propose_theme({ name: 'AI Agent Reliability', description: 'Multi-year bet on making agent workflows reproducible.', targetRoi: 20, idempotencyKey: 'session-1-theme-1' })\n\n" +
+      "Requires SUPABASE_SERVICE_ROLE_KEY. Pass idempotencyKey so retries don't duplicate. Pass dryRun: true to validate without writing. Pass workspaceId to target a workspace other than the env default.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string" },
+        description: { type: "string" },
+        color: { type: "string" },
+        targetRoi: { type: "number" },
+        idempotencyKey: { type: "string" },
+        dryRun: { type: "boolean" },
+        workspaceId: { type: "string" },
+      },
+      required: ["name"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "propose_capability",
+    description:
+      "Propose a new capability under an existing theme — a quarterly bet with a falsifiable outcome.\n\n" +
+      "USE WHEN: planning a multi-task workstream that needs a shared outcome statement; the work is a coherent bet, not a single task; AND suggest_capability_for returned no strong match.\n" +
+      "PREREQUISITE: get_agents_md once this session (enforced). suggest_capability_for (or list_capabilities / get_roadmap_snapshot / the roadmapper://capabilities/active resource) once this session (enforced — server returns discovery_missing with a fix field if you skip it). The server WILL also reject if token overlap with an existing capability is too high; the gate is upstream of that.\n" +
+      "ANTI-PATTERN: do not call for a single deliverable — that's a task. Do not call when the outcome is fuzzy ('improve X') — the server rejects non-falsifiable outcomes. Do not call when an existing capability is close-enough; capabilities cost human attention to maintain.\n" +
+      "EXAMPLE: propose_capability({ pillarId: 'TH-XXX', name: 'Self-serve landing page builder', outcome: 'Customers publish a landing page in under 5 minutes without engineering involvement.', reach: 200, impact: 1, confidence: 70, idempotencyKey: 'session-1-cap-1' })\n\n" +
+      "Server rejects empty / non-falsifiable outcomes, confidence >95, and names <8 chars. Requires SUPABASE_SERVICE_ROLE_KEY. Pass idempotencyKey, dryRun, workspaceId as for propose_task.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string" },
+        pillarId: { type: "string" },
+        description: { type: "string" },
+        outcome: { type: "string" },
+        reach: { type: "number" },
+        impact: { type: "number", enum: [3, 2, 1, 0.5, 0.25] },
+        confidence: { type: "number", minimum: 0, maximum: 100 },
+        roi: { type: "number" },
+        specRef: { type: "string" },
+        idempotencyKey: { type: "string" },
+        dryRun: { type: "boolean" },
+        workspaceId: { type: "string" },
+      },
+      required: ["name", "pillarId", "outcome"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "submit_acceptance_grades",
+    description:
+      "Stamp self-grade results onto a task's acceptanceGrades array. Each entry sets pass/fail on the criterion at the given index.\n\n" +
+      "USE WHEN: you've finished implementing a task and verified its acceptance criteria. Always call before opening a PR — the rubric requires self-grading prior to human review.\n" +
+      "PREREQUISITE: get_agents_md once this session (enforced — defines grading dimensions). Call get_task first to read the acceptance criteria in order — indexes are positional.\n" +
+      "ANTI-PATTERN: do not call before the implementation actually works — fabricated passes destroy the trust this signal carries. Do not call without a note when status='fail' — the reviewer needs the failure mode.\n" +
+      "EXAMPLE: submit_acceptance_grades({ taskId: 'TK-100201', grades: [{ index: 0, status: 'pass' }, { index: 1, status: 'fail', note: 'Reload-persistence is flaky on Firefox; tracked in TK-100202' }] })\n\n" +
+      "Requires SUPABASE_SERVICE_ROLE_KEY. Pass workspaceId to target a workspace other than the env default.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        taskId: { type: "string" },
+        grades: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              index: { type: "integer", minimum: 0 },
+              status: { type: "string", enum: ["pass", "fail"] },
+              note: { type: "string" },
+            },
+            required: ["index", "status"],
+            additionalProperties: false,
+          },
+        },
+        workspaceId: { type: "string" },
+      },
+      required: ["taskId", "grades"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "suggest_capability_for",
+    description:
+      "Given a free-text description of work, return the top existing capabilities ranked by token overlap.\n\n" +
+      "USE WHEN: about to propose tasks or a capability — call this FIRST to find an existing parent. If any returned score > 0.4, strongly prefer attaching tasks there over creating a new capability.\n" +
+      "PREREQUISITE: none — read-only.\n" +
+      "ANTI-PATTERN: do not call after you've already decided to create a new capability — that's the case this tool is meant to prevent. Do not interpret weak matches (<0.2) as fits; if nothing's close, propose_capability is the right next call (after confirming with the user).\n" +
+      "EXAMPLE: suggest_capability_for({ description: 'multi-tenant landing page builder with drag-and-drop blocks' })",
+    inputSchema: {
+      type: "object",
+      properties: {
+        description: { type: "string" },
+        limit: { type: "integer", minimum: 1, maximum: 25 },
+        workspaceId: { type: "string" },
+      },
+      required: ["description"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "suggest_theme_for",
+    description:
+      "Given a free-text description of work, return the top existing themes ranked by token overlap. Mirror of suggest_capability_for but at the theme level — themes are years-stable, so the bar to create a new one is higher.\n\n" +
+      "USE WHEN: about to plan a feature and you've decided you need a Theme/Capability/Task tree. Call this FIRST so you can decide whether to attach a new capability under an existing theme (the usual answer) or whether the work represents a genuinely new strategic direction worth a new theme.\n" +
+      "INTERPRETATION: a top score above ~0.4 = existing theme fits, do NOT create a new one. 0.2-0.4 = weak overlap, almost always still better to use the existing theme. Below 0.2 OR empty matches = ask the user before calling propose_theme — themes are years-stable, not per-feature, and duplicates are the most common failure mode.\n" +
+      "PREREQUISITE: none — read-only. Also satisfies the discovery gate for propose_theme.\n" +
+      "ANTI-PATTERN: do not call after deciding to create a new theme — that's the case this tool is meant to prevent. Do not interpret weak matches as 'must create new' without explicit user confirmation that a new strategic direction is intended.\n" +
+      "EXAMPLE: suggest_theme_for({ description: 'multi-channel marketing analytics dashboard with attribution modeling' })",
+    inputSchema: {
+      type: "object",
+      properties: {
+        description: { type: "string" },
+        limit: { type: "integer", minimum: 1, maximum: 25 },
+        workspaceId: { type: "string" },
+      },
+      required: ["description"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "link_pr",
+    description:
+      "Attach a PR to a task. Closes the deliver-loop gap so an agent that just opened a PR can stamp it onto the parent task without waiting for the next GitHub webhook.\n\n" +
+      "USE WHEN: you just opened a PR for a task and want it visible in roadmapper immediately. Always call alongside submit_acceptance_grades when closing out a task.\n" +
+      "PREREQUISITE: get_agents_md once this session (enforced). The task id must exist (get_task / list_tasks to confirm).\n" +
+      "ANTI-PATTERN: do not call as a substitute for the Roadmapper-Task: PR-body trailer convention — the trailer is the durable contract; link_pr is the instant-feedback shortcut. Do not call for PRs that don't have a parent task in roadmapper.\n" +
+      "EXAMPLE: link_pr({ taskId: 'TK-100201', repo: 'acme/frontend', number: 1234, title: 'Drag block reorder', authorGithub: 'octocat' })\n\n" +
+      "Idempotent by (repo, number) — re-calling with an already-linked PR returns idempotent:true. Requires SUPABASE_SERVICE_ROLE_KEY. Pass workspaceId to target a workspace other than the env default.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        taskId: { type: "string" },
+        repo: { type: "string" },
+        number: { type: "integer", minimum: 1 },
+        title: { type: "string" },
+        merged: { type: "boolean" },
+        mergedAt: { type: "string" },
+        authorGithub: { type: "string" },
+        authorKind: { type: "string", enum: ["human", "agent"] },
+        workspaceId: { type: "string" },
+      },
+      required: ["taskId", "repo", "number"],
+      additionalProperties: false,
+    },
+  },
+  // ── Archive lifecycle (Phase 2 of the upgrade) ──────────────
+  // Soft delete: archived rows stay in the workspace's edits
+  // blob; list views filter them out, by-id lookups still
+  // resolve. Refuses with active children (forces bottom-up
+  // archive). Reason required on every call (audit trail).
+  ...archiveLifecycleTools(),
+  // ── Move lifecycle (Phase 3 of the upgrade) ─────────────────
+  // Re-parent tasks under capabilities and capabilities under
+  // themes. IDs are stable across moves. Target parent must be
+  // active (refuses move into archived parent). Moving an
+  // archived entity into an active parent unarchives in one step.
+  ...moveLifecycleTools(),
+  // ── Update lifecycle (Phase 4 of the upgrade) ───────────────
+  // Patch fields on an entity. Parent fields (capabilityId,
+  // pillarId) and lifecycle flags (archived, archivedAt) are
+  // forbidden — those go through move_/archive_/unarchive_ for
+  // audit clarity. UP5 idempotent on identical input.
+  ...updateLifecycleTools(),
+  // ── Outcome readings ────────────────────────────────────────
+  // Track empirical metric readings against capability outcomes.
+  // Append-only; the RPC takes a row lock so concurrent writes
+  // never clobber. list_stale_outcomes flags capabilities whose
+  // most recent reading is older than N days.
+  {
+    name: "record_outcome_reading",
+    description:
+      "Record a metric reading against a capability's stated outcome. Captures the empirical signal between 'outcome declared' and 'outcome decided.'\n\n" +
+      "USE WHEN: you have a fresh measurement of the metric the capability is moving. A weekly Mixpanel paste, a warehouse extract, a Datadog reading — any source. The reading append-only-ly augments the capability's history; it doesn't replace prior readings.\n" +
+      "PREREQUISITE: get_agents_md once this session (enforced). The capability must exist.\n" +
+      "ANTI-PATTERN: do not use to declare the FINAL outcome (use outcomeStatus via update_capability for that). Readings are observations along the way, not the verdict.\n" +
+      "EXAMPLE: record_outcome_reading({ capabilityId: 'CAP-9F2C7E', value: 0.41, asOf: '2026-05-12', source: 'mixpanel: activated_within_7d weekly', note: 'sample size 4218' })\n\n" +
+      "Requires SUPABASE_SERVICE_ROLE_KEY. Audit log records each reading as 'outcome_reading_recorded'.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        capabilityId: { type: "string", description: "CAP-XXXXXX" },
+        value: { type: "number", description: "The metric reading (cardinality matches the outcome statement)." },
+        asOf: { type: "string", description: "ISO date or timestamp the reading was sampled (not recorded)." },
+        source: { type: "string", description: "Where the reading came from (e.g. 'mixpanel weekly', 'warehouse:fact_orders')." },
+        note: { type: "string" },
+        workspaceId: { type: "string" },
+      },
+      required: ["capabilityId", "value", "asOf", "source"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "list_stale_outcomes",
+    description:
+      "List capabilities whose outcome metric hasn't been measured recently. Default threshold: 14 days. Surfaces bets that have lost the empirical loop — outcome was declared but nobody's checking.\n\n" +
+      "USE WHEN: at quarterly review, weekly outcome check, or any time you want to spot capabilities that are running without a reading.\n" +
+      "Returns each stale capability with its id, name, outcome, days since last reading (or null if never), and most recent reading if present.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        thresholdDays: {
+          type: "number",
+          description: "Days since last reading to count as stale. Default 14.",
+        },
+        includeArchived: { type: "boolean" },
+        workspaceId: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+  },
+];
+
+/**
+ * Six archive/unarchive tools share most of their schema — same
+ * shape per entity kind (task, capability, theme), same required
+ * inputs (entity id + reason), same optional knobs (idempotency,
+ * dryRun, workspaceId). Build them via a factory so the surface
+ * stays in sync if the contract changes.
+ */
+function archiveLifecycleTools() {
+  const kinds = [
+    {
+      kind: "task",
+      idDoc: "TK-NNNNNN",
+      idKey: "taskId",
+      example:
+        "archive_task({ taskId: 'TK-100201', reason: 'cut from this quarter; superseded by TK-100299' })",
+    },
+    {
+      kind: "capability",
+      idDoc: "CAP-XXXXXX",
+      idKey: "capabilityId",
+      example:
+        "archive_capability({ capabilityId: 'CAP-9F2C7E', reason: 'bet was wrong; we're going a different direction' })",
+    },
+    {
+      kind: "theme",
+      idDoc: "TH-XXXXXX",
+      idKey: "themeId",
+      example:
+        "archive_theme({ themeId: 'TH-OLD-AREA', reason: 'theme retired; remaining bets re-parented' })",
+    },
+  ];
+  const out = [];
+  for (const { kind, idDoc, idKey, example } of kinds) {
+    const idSchema = { [idKey]: { type: "string", description: idDoc } };
+    out.push({
+      name: `archive_${kind}`,
+      description:
+        `Archive a ${kind} (soft delete). The row stays in the workspace; list views filter it out, by-id lookups still resolve.\n\n` +
+        `USE WHEN: a ${kind} is no longer relevant — cut from scope, superseded, or retired. Soft delete preserves history without cluttering the active roadmap.\n` +
+        "PREREQUISITE: get_agents_md once this session (enforced). For capabilities/themes, every active child must already be archived — the server refuses with a count of blocking children. For tasks, no child check.\n" +
+        `ANTI-PATTERN: do not archive a ${kind} you might come back to within the same session — prefer moving it (move_${kind === "theme" ? "capability" : kind}) or updating its status. Archive is the right tool for "this is closed out, get it out of the picker."\n` +
+        `EXAMPLE: ${example}\n\n` +
+        "Idempotent: re-archiving an already-archived entity returns { idempotent: true } and emits no audit row. Requires SUPABASE_SERVICE_ROLE_KEY. Pass workspaceId to target a workspace other than the env default.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          ...idSchema,
+          reason: {
+            type: "string",
+            description:
+              "Why this is being archived. Required — landed in the audit log so future readers know the rationale.",
+          },
+          idempotencyKey: { type: "string" },
+          dryRun: { type: "boolean" },
+          workspaceId: { type: "string" },
+        },
+        required: [idKey, "reason"],
+        additionalProperties: false,
+      },
+    });
+    out.push({
+      name: `unarchive_${kind}`,
+      description:
+        `Unarchive a ${kind}. Reverses archive_${kind}.\n\n` +
+        `USE WHEN: an archived ${kind} is being pulled back into scope. To move an archived entity to a different parent, call move_${kind === "theme" ? "capability" : kind} instead — that path unarchives in one step.\n` +
+        "PREREQUISITE: get_agents_md once this session (enforced). The parent (if any) must be active — cannot unarchive a task whose capability is archived, or a capability whose theme is archived. Unarchive the parent first.\n" +
+        "ANTI-PATTERN: do not unarchive en masse without thinking — every unarchive re-floats noise into list views. If you're recovering from an over-aggressive archive sweep, work top-down.\n" +
+        `EXAMPLE: un${example.replace("archive", "archive")}\n\n` +
+        "Idempotent: unarchiving an already-active entity returns { idempotent: true }. Requires SUPABASE_SERVICE_ROLE_KEY.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          ...idSchema,
+          reason: { type: "string" },
+          idempotencyKey: { type: "string" },
+          dryRun: { type: "boolean" },
+          workspaceId: { type: "string" },
+        },
+        required: [idKey, "reason"],
+        additionalProperties: false,
+      },
+    });
+  }
+  return out;
+}
+
+/**
+ * Four move tools: two single (move_task, move_capability) and two
+ * bulk (move_tasks, move_capabilities). Single tools re-parent one
+ * entity; bulk tools accept up to 100 moves and stamp a shared
+ * batchId into each audit row so a reorg shows up in history as one
+ * logical operation. Themes have no parent, so no move_theme.
+ */
+function moveLifecycleTools() {
+  const kinds = [
+    {
+      kind: "task",
+      kindPlural: "tasks",
+      idKey: "taskId",
+      idDoc: "TK-NNNNNN",
+      parentKey: "newCapabilityId",
+      parentDoc: "CAP-XXXXXX",
+      parentKind: "capability",
+      example:
+        "move_task({ taskId: 'TK-100201', newCapabilityId: 'CAP-7A2D9F', reason: 'belongs under the auth capability, not onboarding' })",
+    },
+    {
+      kind: "capability",
+      kindPlural: "capabilities",
+      idKey: "capabilityId",
+      idDoc: "CAP-XXXXXX",
+      parentKey: "newThemeId",
+      parentDoc: "TH-NNNNNN",
+      parentKind: "theme",
+      example:
+        "move_capability({ capabilityId: 'CAP-9F2C7E', newThemeId: 'TH-100042', reason: 'theme reorg — moving under Platform' })",
+    },
+  ];
+  const out = [];
+  for (const { kind, kindPlural, idKey, idDoc, parentKey, parentDoc, parentKind, example } of kinds) {
+    out.push({
+      name: `move_${kind}`,
+      description:
+        `Re-parent a ${kind} under a different ${parentKind}. The ${kind}'s id stays the same (${idDoc} never changes).\n\n` +
+        `USE WHEN: a ${kind} is in the wrong place — wrong ${parentKind} after a reorg, or initially proposed under the wrong parent. To unarchive while moving, pass the archived entity's id with a DIFFERENT active target parent; if the new parent is active the entity unarchives in one step. To unarchive in place (without moving), call unarchive_${kind} directly — move to the SAME parent short-circuits as idempotent and won't unarchive.\n` +
+        "PREREQUISITE: get_agents_md once this session (enforced). Target parent must exist AND be active — refuses move into an archived parent.\n" +
+        `ANTI-PATTERN: do not use move to change anything other than the parent. To rename or rescope, use update_${kind} (coming soon). To delete, use archive_${kind}.\n` +
+        `EXAMPLE: ${example}\n\n` +
+        "Idempotent: moving to the current parent returns { idempotent: true } and emits no audit row. Requires SUPABASE_SERVICE_ROLE_KEY.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          [idKey]: { type: "string", description: idDoc },
+          [parentKey]: { type: "string", description: `Target ${parentKind} id (${parentDoc}).` },
+          reason: {
+            type: "string",
+            description:
+              "Why this is being moved. Required — landed in the audit log so future readers know the rationale.",
+          },
+          dryRun: { type: "boolean" },
+          workspaceId: { type: "string" },
+        },
+        required: [idKey, parentKey, "reason"],
+        additionalProperties: false,
+      },
+    });
+    const bulkExample =
+      kind === "task"
+        ? `move_tasks({ moves: [{ taskId: 'TK-100201', newCapabilityId: 'CAP-7A2D9F' }, { taskId: 'TK-100202', newCapabilityId: 'CAP-7A2D9F' }], reason: 'auth reorg — pulling these under the new auth capability' })`
+        : `move_capabilities({ moves: [{ capabilityId: 'CAP-9F2C7E', newThemeId: 'TH-100042' }, { capabilityId: 'CAP-9F2C7F', newThemeId: 'TH-100042' }], reason: 'theme reorg — moving under Platform' })`;
+    out.push({
+      name: `move_${kindPlural}`,
+      description:
+        `Bulk re-parent up to 100 ${kindPlural} in one call. Each item lists the entity id and its new ${parentKind}; the server stamps a shared batchId so the audit log groups the reorg as one logical operation.\n\n` +
+        `USE WHEN: you have a planned reorg touching many ${kindPlural} at once — splitting a ${parentKind}, merging two, or rebalancing scope. The shared batchId is what makes a 50-row reorg show up as one event in history rather than 50 disconnected moves.\n` +
+        "PREREQUISITE: get_agents_md once this session (enforced). Each move follows the same rules as the single tool — target parent active, reason required. Partial failures: the server processes moves one at a time and returns per-item ok/error; later failures do not roll back earlier successes.\n" +
+        "ANTI-PATTERN: do not loop the single tool when you have a batch — you lose the batchId grouping in audit history. Conversely, do not use bulk for a single move; the single tool has a cleaner response shape.\n" +
+        `EXAMPLE: ${bulkExample}`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          moves: {
+            type: "array",
+            minItems: 1,
+            maxItems: 100,
+            items: {
+              type: "object",
+              properties: {
+                [idKey]: { type: "string", description: idDoc },
+                [parentKey]: { type: "string", description: parentDoc },
+              },
+              required: [idKey, parentKey],
+              additionalProperties: false,
+            },
+            description: "Up to 100 moves to apply with a shared batchId.",
+          },
+          reason: {
+            type: "string",
+            description:
+              "Shared rationale for the reorg — written to every audit row in the batch.",
+          },
+          dryRun: { type: "boolean" },
+          workspaceId: { type: "string" },
+        },
+        required: ["moves", "reason"],
+        additionalProperties: false,
+      },
+    });
+  }
+  return out;
+}
+
+/**
+ * Three update tools: one per kind. Each accepts a `patch` object
+ * whose keys are the fields to mutate. Schemas enumerate the
+ * mutable fields per kind so an agent can introspect what's
+ * settable. Parent fields and lifecycle flags are NOT listed — the
+ * server also rejects them, but advertising them up-front prevents
+ * the round-trip.
+ */
+function updateLifecycleTools() {
+  const kinds = [
+    {
+      kind: "task",
+      idKey: "taskId",
+      idDoc: "TK-NNNNNN",
+      patchProps: {
+        title: { type: "string", description: "Task title. Minimum 5 chars." },
+        summary: { type: "string", description: "Free-form description." },
+        status: {
+          type: "string",
+          enum: ["delivered", "in_progress", "planned", "exploring"],
+        },
+        priority: { type: "string", enum: ["P0", "P1", "P2", "P3"] },
+        effort: { type: "string", enum: ["XS", "S", "M", "L", "XL"] },
+        kind: { type: "string", enum: ["feature", "bug", "chore", "spike"] },
+        start: { type: "string", description: "ISO date YYYY-MM-DD." },
+        target: { type: "string", description: "ISO date YYYY-MM-DD." },
+        progress: { type: "number", description: "0–100." },
+        owner: { type: "string" },
+        team: { type: "string" },
+        tags: { type: "array", items: { type: "string" } },
+        acceptance: { type: "array" },
+        dependsOn: { type: "array", items: { type: "string" } },
+        links: { type: "object", additionalProperties: { type: "string" } },
+        expectedPRs: {
+          type: "number",
+          description: "Advisory: max merged PRs for this task (overrun → audit warning).",
+        },
+        expectedScope: {
+          type: "number",
+          description: "Advisory: cumulative LoC ceiling across linked PRs.",
+        },
+      },
+      example:
+        "update_task({ taskId: 'TK-100201', patch: { status: 'in_progress', progress: 25 }, reason: 'work started — kicking off this week' })",
+    },
+    {
+      kind: "capability",
+      idKey: "capabilityId",
+      idDoc: "CAP-XXXXXX",
+      patchProps: {
+        name: { type: "string", description: "Capability name. Minimum 8 chars." },
+        outcome: { type: "string", description: "Falsifiable outcome statement." },
+        hypothesis: { type: "string" },
+        owner: { type: "string" },
+        team: { type: "string" },
+        confidence: { type: "number", description: "0–95." },
+        impact: { type: "number", description: "One of 0.25, 0.5, 1, 2, 3." },
+        roi: { type: "number" },
+        tags: { type: "array", items: { type: "string" } },
+        links: { type: "object", additionalProperties: { type: "string" } },
+      },
+      example:
+        "update_capability({ capabilityId: 'CAP-9F2C7E', patch: { confidence: 80, outcome: 'Activation moves from 32% to 55% by 2026-09-30, measured by mixpanel_activated_v2.' }, reason: 'sharper outcome after the leadership review' })",
+    },
+    {
+      kind: "theme",
+      idKey: "themeId",
+      idDoc: "TH-XXXXXX",
+      patchProps: {
+        name: { type: "string", description: "Theme name. Minimum 5 chars." },
+        description: { type: "string" },
+        owner: { type: "string" },
+        targetRoi: { type: "number" },
+      },
+      example:
+        "update_theme({ themeId: 'TH-100042', patch: { name: 'Platform Reliability' }, reason: 'sharper name; same scope' })",
+    },
+  ];
+  return kinds.map(({ kind, idKey, idDoc, patchProps, example }) => {
+    // Themes are roots (no parent), so the "use move_*" guidance
+    // doesn't apply to them. Per-kind reparenting hint:
+    const reparentHint =
+      kind === "task"
+        ? "Reparenting must use move_task — passing capabilityId/id/archived in the patch is rejected server-side."
+        : kind === "capability"
+        ? "Reparenting must use move_capability — passing pillarId/id/archived in the patch is rejected server-side."
+        : "Themes are top-level (no parent). Passing id/archived in the patch is rejected server-side; use archive_theme to retire.";
+    return {
+      name: `update_${kind}`,
+      description:
+        `Patch fields on a ${kind}. The patch is a partial object — only the keys you include are touched.\n\n` +
+        `USE WHEN: a ${kind}'s details need to change. Renaming, sharpening outcomes, bumping confidence, fixing typos, advancing status, adding tags — all here.\n` +
+        `PREREQUISITE: get_agents_md once this session (enforced). Reason required (audit trail). ${reparentHint}\n` +
+        `ANTI-PATTERN: do not echo the entity back to the server — pass only the keys that changed. The server diffs against current state and a patch that matches everything returns { idempotent: true }.\n` +
+        `EXAMPLE: ${example}\n\n` +
+        "Idempotent: a patch where every key already matches current state returns { idempotent: true } and emits no audit row. Requires SUPABASE_SERVICE_ROLE_KEY.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        [idKey]: { type: "string", description: idDoc },
+        patch: {
+          type: "object",
+          description: `Partial ${kind} — keys to update. Parent fields and lifecycle flags are rejected.`,
+          properties: patchProps,
+          additionalProperties: false,
+          minProperties: 1,
+        },
+        reason: {
+          type: "string",
+          description: "Why this is being updated. Required — landed in the audit log.",
+        },
+        dryRun: { type: "boolean" },
+        workspaceId: { type: "string" },
+      },
+      required: [idKey, "patch", "reason"],
+      additionalProperties: false,
+    },
+    };
+  });
+}
+
+/** Tools that mutate the workspace — all gated on rubric fetch. */
+const MUTATOR_TOOLS = new Set([
+  "propose_task",
+  "propose_theme",
+  "propose_capability",
+  "submit_acceptance_grades",
+  "link_pr",
+  "archive_task",
+  "archive_capability",
+  "archive_theme",
+  "unarchive_task",
+  "unarchive_capability",
+  "unarchive_theme",
+  "move_task",
+  "move_capability",
+  "move_tasks",
+  "move_capabilities",
+  "update_task",
+  "update_capability",
+  "update_theme",
+  "record_outcome_reading",
+]);
+
+async function callTool(name, args) {
+  // Each tool may override the workspace via args.workspaceId. The
+  // projection is workspace-scoped, so we pass that through to the
+  // read. Tools that need to know the resolved id later (write paths,
+  // snapshot) read it back via resolveWorkspaceId(args?.workspaceId).
+  const wsId = resolveWorkspaceId(args?.workspaceId);
+  // Post-Piece-6c, the entity tables ARE the canonical projection
+  // — no edits blob, no seed-overlay merge. Fall back to the
+  // bundled seed only when the DB is unreachable (offline / dev).
+  const projected =
+    (await readWorkspaceProjected(wsId)) ?? project(readSeed(), {});
+
+  // Rubric gate. The agent must have called get_agents_md this
+  // session before any mutator runs — the rubric defines validation
+  // shapes the mutator enforces, and we'd rather block the call
+  // than let a malformed proposal land in the roadmap. Read-only
+  // tools and get_agents_md itself are always available.
+  if (MUTATOR_TOOLS.has(name)) {
+    session.mutatorAttempts += 1;
+    // Best-effort target attribution for telemetry. Pulled here so
+    // every mutator branch below shares it. The arg names are
+    // inconsistent across tools (id / taskId / capabilityId /
+    // themeId / pillarId), and bulk reorgs (move_tasks /
+    // move_capabilities) nest ids inside args.moves[]. We try the
+    // obvious candidates in a sensible priority order. The first
+    // hit wins. Null when the tool genuinely doesn't carry a
+    // target (e.g. propose_* calls that create a new record where
+    // the id only exists after the server stamps it).
+    const firstMove = Array.isArray(args?.moves) ? args.moves[0] : null;
+    const targetId =
+      (typeof args?.id === "string" && args.id) ||
+      (typeof args?.taskId === "string" && args.taskId) ||
+      (typeof args?.capabilityId === "string" && args.capabilityId) ||
+      (typeof args?.themeId === "string" && args.themeId) ||
+      (typeof args?.pillarId === "string" && args.pillarId) ||
+      (firstMove &&
+        typeof firstMove.taskId === "string" &&
+        firstMove.taskId) ||
+      (firstMove &&
+        typeof firstMove.capabilityId === "string" &&
+        firstMove.capabilityId) ||
+      null;
+    if (session.rubricFetchedAt === null) {
+      session.mutatorBlocks += 1;
+      recordTelemetry(
+        "mutator_blocked_no_rubric",
+        { tool: name, targetId },
+        wsId
+      );
+      return rubricMissingResult(name);
+    }
+    // Per-tool discovery gates. Block propose_theme until the agent
+    // has actually inspected the existing theme catalogue, and
+    // propose_capability until they've ranked existing caps for fit.
+    // Tool descriptions already steer agents this way; this turns
+    // the recommendation into enforcement so the most common
+    // failure mode (creating a duplicate of an existing record) can't
+    // slip through when the LLM skipped the discovery step.
+    if (name === "propose_theme" && session.themesListedAt === null) {
+      session.mutatorBlocks += 1;
+      recordTelemetry(
+        "mutator_blocked_no_discovery",
+        { tool: name, missing: "suggest_theme_for", targetId },
+        wsId
+      );
+      return discoveryMissingResult(
+        name,
+        'suggest_theme_for({ description: "<the work you are about to propose>" })',
+        "Rank existing themes by relevance before proposing a new one — themes are years-stable, duplicates are the most common failure mode. Any returned top score >0.4 means an existing theme is a sensible home; re-use it. list_themes() or get_roadmap_snapshot() also satisfy this gate if you want the full catalogue."
+      );
+    }
+    if (
+      name === "propose_capability" &&
+      session.capsDiscoveredAt === null
+    ) {
+      session.mutatorBlocks += 1;
+      recordTelemetry(
+        "mutator_blocked_no_discovery",
+        {
+          tool: name,
+          missing: "suggest_capability_for",
+          targetId,
+        },
+        wsId
+      );
+      return discoveryMissingResult(
+        name,
+        'suggest_capability_for({ description: "<the work you are about to propose>" })',
+        "Rank existing capabilities by relevance before proposing a new one. If any score is >0.4, attach tasks there instead."
+      );
+    }
+    // Cross-workspace guard. If the cwd has a .roadmapper/snapshot.json
+    // naming a workspace, and the call carries an explicit workspaceId
+    // pointing somewhere else, refuse — almost always a mistake. An
+    // operator who really needs to write across workspaces can set
+    // ROADMAPPER_ALLOW_CROSS_WORKSPACE=1 in env to bypass.
+    const snap = snapshotWorkspaceId();
+    const argWs = args?.workspaceId;
+    if (
+      snap &&
+      typeof argWs === "string" &&
+      argWs.length > 0 &&
+      argWs !== snap &&
+      process.env.ROADMAPPER_ALLOW_CROSS_WORKSPACE !== "1"
+    ) {
+      session.mutatorBlocks += 1;
+      recordTelemetry(
+        "mutator_blocked_cross_workspace",
+        { tool: name, targetId, cwdWorkspace: snap, argWorkspace: argWs },
+        wsId
+      );
+      return errorResult(
+        `Refusing cross-workspace write: cwd's .roadmapper/snapshot.json names workspace "${snap}" but ${name} call targets "${argWs}". Almost always a mistake — drop the workspaceId arg to use the cwd default, or set ROADMAPPER_ALLOW_CROSS_WORKSPACE=1 to override.`
+      );
+    }
+    recordTelemetry("mutator_attempted", { tool: name, targetId }, wsId);
+  }
+
+  switch (name) {
+    case "list_themes": {
+      // Satisfies the propose_theme discovery gate. The agent has
+      // explicitly enumerated the existing theme catalogue.
+      session.themesListedAt = Date.now();
+      let filtered = projected.themes;
+      if (!args?.includeArchived) {
+        filtered = filtered.filter((t) => !t.archived);
+      }
+      return withReminder(
+        "list_themes",
+        projected,
+        textResult(JSON.stringify(filtered, null, 2))
+      );
+    }
+    case "list_capabilities": {
+      // Counts as cap discovery for the propose_capability gate.
+      session.capsDiscoveredAt = Date.now();
+      let filtered = args?.themeId
+        ? projected.capabilities.filter((c) => c.pillarId === args.themeId)
+        : projected.capabilities;
+      if (!args?.includeDelivered) {
+        filtered = filtered.filter(
+          (c) => effectiveCapabilityStatus(c, projected.tasks) !== "delivered"
+        );
+      }
+      if (!args?.includeArchived) {
+        filtered = filtered.filter((c) => !c.archived);
+      }
+      return withReminder(
+        "list_capabilities",
+        projected,
+        textResult(JSON.stringify(filtered, null, 2))
+      );
+    }
+    case "list_tasks": {
+      let filtered = projected.tasks;
+      if (args?.capabilityId)
+        filtered = filtered.filter((t) => t.capabilityId === args.capabilityId);
+      if (args?.status)
+        filtered = filtered.filter((t) => t.status === args.status);
+      if (!args?.includeArchived) {
+        filtered = filtered.filter((t) => !t.archived);
+      }
+      return withReminder(
+        "list_tasks",
+        projected,
+        textResult(JSON.stringify(filtered, null, 2))
+      );
+    }
+    case "get_task": {
+      // S5: direct-by-id lookups always resolve, even for archived
+      // entities. Cross-references (PR links, dependsOn) need this.
+      const t = projected.tasks.find((x) => x.id === args?.id);
+      if (!t) return errorResult(`Task ${args?.id} not found.`);
+      return textResult(JSON.stringify(t, null, 2));
+    }
+    case "get_agents_md": {
+      const fresh = session.rubricFetchedAt === null;
+      session.rubricFetchedAt = Date.now();
+      if (fresh) recordTelemetry("rubric_fetched", { via: "tool" }, wsId);
+      return textResult(readAgentsMd(), {
+        _meta: {
+          roadmapper: {
+            reminder:
+              "Rubric loaded. You can now safely call propose_task, propose_capability, propose_theme, submit_acceptance_grades, link_pr.",
+          },
+        },
+      });
+    }
+    case "get_roadmap_snapshot": {
+      // The snapshot returns themes + active caps + open tasks in a
+      // single response, so the agent has effectively enumerated both
+      // catalogues. Satisfies BOTH discovery gates.
+      const ts = Date.now();
+      session.themesListedAt = ts;
+      session.capsDiscoveredAt = ts;
+      return withReminder(
+        "get_roadmap_snapshot",
+        projected,
+        getRoadmapSnapshot(projected, wsId, args?.includeArchived === true)
+      );
+    }
+    case "propose_task":
+      return proposeTask(args, projected, wsId);
+    case "propose_theme":
+      return proposeTheme(args, projected, wsId);
+    case "propose_capability":
+      return proposeCapability(args, projected, wsId);
+    case "submit_acceptance_grades":
+      return submitAcceptanceGrades(args, projected, wsId);
+    case "suggest_capability_for":
+      // Counts as cap discovery — the agent has explicitly asked
+      // the server to rank existing caps for fit against the work
+      // they're about to propose.
+      session.capsDiscoveredAt = Date.now();
+      return suggestCapabilityFor(args, projected);
+    case "suggest_theme_for":
+      // Mirror of the cap case: satisfies the propose_theme gate,
+      // because the agent has explicitly asked the server to rank
+      // existing themes for fit.
+      session.themesListedAt = Date.now();
+      return suggestThemeFor(args, projected);
+    case "link_pr":
+      return linkPR(args, projected, seed, wsId);
+    case "archive_task":
+      return archiveLifecycle("task", "archive", args, wsId);
+    case "archive_capability":
+      return archiveLifecycle("capability", "archive", args, wsId);
+    case "archive_theme":
+      return archiveLifecycle("theme", "archive", args, wsId);
+    case "unarchive_task":
+      return archiveLifecycle("task", "unarchive", args, wsId);
+    case "unarchive_capability":
+      return archiveLifecycle("capability", "unarchive", args, wsId);
+    case "unarchive_theme":
+      return archiveLifecycle("theme", "unarchive", args, wsId);
+    case "move_task":
+      return moveEntity("task", args, wsId);
+    case "move_capability":
+      return moveEntity("capability", args, wsId);
+    case "move_tasks":
+      return moveBulk("task", args, wsId);
+    case "move_capabilities":
+      return moveBulk("capability", args, wsId);
+    case "update_task":
+      return updateEntity("task", args, wsId, projected);
+    case "update_capability":
+      return updateEntity("capability", args, wsId, projected);
+    case "update_theme":
+      return updateEntity("theme", args, wsId, projected);
+    case "record_outcome_reading":
+      return recordOutcomeReading(args, wsId, projected);
+    case "list_stale_outcomes":
+      return listStaleOutcomes(args, projected);
+    default:
+      return errorResult(`Unknown tool: ${name}`);
+  }
+}
+
+async function proposeTask(args, projected, wsId) {
+  const cap = projected.capabilities.find((c) => c.id === args.capabilityId);
+  if (!cap) return errorResult(`Capability ${args.capabilityId} not found.`);
+  const titleErr = validateName(args.title, 5);
+  if (titleErr) return errorResult(titleErr);
+  if (args.effort && !VALID_EFFORTS.has(args.effort))
+    return errorResult(`Invalid effort ${args.effort}.`);
+  if (args.priority && !VALID_PRIORITIES.has(args.priority))
+    return errorResult(`Invalid priority ${args.priority}.`);
+  if (args.kind && !VALID_KINDS.has(args.kind))
+    return errorResult(`Invalid kind ${args.kind}.`);
+  if (
+    args.expectedPRs !== undefined &&
+    (typeof args.expectedPRs !== "number" || args.expectedPRs <= 0)
+  )
+    return errorResult(`expectedPRs must be a positive number, got ${args.expectedPRs}.`);
+  if (
+    args.expectedScope !== undefined &&
+    (typeof args.expectedScope !== "number" || args.expectedScope <= 0)
+  )
+    return errorResult(`expectedScope must be a positive number, got ${args.expectedScope}.`);
+
+  const effort = args.effort ?? "M";
+  const start = todayISO();
+  // Target dates are day-resolution; round up so sub-day estimates
+  // (XS=0.25, S=0.5) still nudge the target at least one day out.
+  const target = addDays(start, Math.max(1, Math.ceil(EFFORT_DAYS[effort])));
+  const id = randomTaskId();
+  const task = {
+    id,
+    capabilityId: cap.id,
+    title: cleanText(args.title),
+    summary: cleanText(args.summary),
+    status: "planned",
+    priority: args.priority ?? "P2",
+    effort,
+    kind: args.kind ?? "feature",
+    start,
+    target,
+    originalTarget: target,
+    progress: 0,
+    owner: args.owner?.trim() ?? "",
+    team: cap.team ?? "",
+    tags: [],
+    prs: [],
+    links: {},
+    acceptance: args.acceptance ?? [],
+    dependsOn: args.dependsOn ?? [],
+    authorKind: "agent",
+    // Advisory scope ceiling — left unset by default ("default-then-
+    // observe" pattern). Authors who want to declare an envelope can
+    // pass expectedPRs / expectedScope at propose-time, or set them
+    // later via update_task. A future get_size_baseline tool will
+    // suggest sensible defaults from observed history.
+    ...(args.expectedPRs !== undefined ? { expectedPRs: args.expectedPRs } : {}),
+    ...(args.expectedScope !== undefined ? { expectedScope: args.expectedScope } : {}),
+  };
+
+  if (args.dryRun) {
+    return textResult(
+      JSON.stringify(
+        {
+          ok: true,
+          dryRun: true,
+          wouldCreate: task,
+          warnings: [],
+          message: `Would create task ${id} under ${cap.id} (${cap.name}). No record written.`,
+        },
+        null,
+        2
+      )
+    );
+  }
+
+  let rpcResult;
+  try {
+    // RPC does an idempotency check + append inside a row lock.
+    // Concurrent retries with the same key collapse to one task;
+    // concurrent calls without a key both insert distinct tasks.
+    rpcResult = await rpcCall("propose_task", {
+      p_workspace_id: wsId,
+      p_task: task,
+      p_idempotency_key: args.idempotencyKey ?? null,
+    });
+  } catch (e) {
+    return errorResult(e.message);
+  }
+
+  // RPC returns { task, idempotent }. When idempotent=true, an
+  // earlier call with the same idempotencyKey already created the
+  // task — surface that instead of pretending we just made a new one.
+  const stored = rpcResult?.task ?? task;
+  const idempotent = rpcResult?.idempotent === true;
+
+  return textResult(
+    JSON.stringify(
+      {
+        ok: true,
+        id: stored.id,
+        capabilityId: stored.capabilityId,
+        idempotent,
+        message: idempotent
+          ? `Task ${stored.id} already exists with idempotencyKey ${args.idempotencyKey}; returning existing task instead of creating a duplicate.`
+          : `Created ${stored.id} under ${cap.id} (${cap.name}). status=planned, authorKind=agent.`,
+      },
+      null,
+      2
+    )
+  );
+}
+
+async function proposeTheme(args, _projected /* unused — themes carry no parent */, wsId) {
+  const nameErr = validateName(args.name, 6);
+  if (nameErr) return errorResult(nameErr);
+
+  const name = cleanText(args.name);
+  const id = randomThemeId();
+  const theme = {
+    id,
+    name,
+    description: cleanText(args.description),
+    color: args.color || "#6366f1", // brand-indigo default; user can change
+    ...(typeof args.targetRoi === "number" ? { targetRoi: args.targetRoi } : {}),
+  };
+
+  if (args.dryRun) {
+    return textResult(
+      JSON.stringify(
+        {
+          ok: true,
+          dryRun: true,
+          wouldCreate: theme,
+          warnings: [],
+          message: `Would create theme ${id} (${name}). No record written.`,
+        },
+        null,
+        2
+      )
+    );
+  }
+
+  let rpcResult;
+  try {
+    rpcResult = await rpcCall("propose_theme", {
+      p_workspace_id: wsId,
+      p_theme: theme,
+      p_idempotency_key: args.idempotencyKey ?? null,
+    });
+  } catch (e) {
+    return errorResult(e.message);
+  }
+  const stored = rpcResult?.theme ?? theme;
+  const idempotent = rpcResult?.idempotent === true;
+  return textResult(
+    JSON.stringify(
+      {
+        ok: true,
+        id: stored.id,
+        idempotent,
+        message: idempotent
+          ? `Theme ${stored.id} already exists with idempotencyKey ${args.idempotencyKey}; returning existing instead of duplicating.`
+          : `Created theme ${stored.id} (${stored.name}).`,
+      },
+      null,
+      2
+    )
+  );
+}
+
+async function proposeCapability(args, projected, wsId) {
+  const pillarId = (args.pillarId || "").trim();
+
+  // Validation order: cheap structural checks first, then rubric.
+  const nameErr = validateName(args.name, 8);
+  if (nameErr) return errorResult(nameErr);
+  if (!pillarId) return errorResult("pillarId is required.");
+
+  // pillarId must exist in the projected view (seed + newPillars −
+  // deletedPillarIds). The RPC catches the "deleted in this
+  // workspace mid-session" case too.
+  const theme = projected.themes.find((t) => t.id === pillarId);
+  if (!theme) {
+    return errorResult(
+      `pillarId ${pillarId} doesn't match any known theme. Call list_themes first.`
+    );
+  }
+  if (typeof args.impact === "number" && !VALID_IMPACTS.has(args.impact)) {
+    return errorResult(
+      `Invalid impact ${args.impact} — must be one of 3, 2, 1, 0.5, 0.25.`
+    );
+  }
+  const confidenceErr = validateConfidence(args.confidence);
+  if (confidenceErr) return errorResult(confidenceErr);
+  if (typeof args.reach === "number" && args.reach < 0) {
+    return errorResult(`Invalid reach ${args.reach} — must be >= 0.`);
+  }
+  // Outcome is required + must be falsifiable per the AGENTS.md rubric.
+  const outcomeErr = validateOutcome(args.outcome);
+  if (outcomeErr) return errorResult(outcomeErr);
+
+  const id = randomCapabilityId();
+  const capability = {
+    id,
+    name: cleanText(args.name),
+    pillarId,
+    description: cleanText(args.description),
+    outcome: cleanText(args.outcome),
+    reach: typeof args.reach === "number" ? args.reach : 100,
+    impact: typeof args.impact === "number" ? args.impact : 1,
+    confidence: typeof args.confidence === "number" ? args.confidence : 70,
+    ...(typeof args.roi === "number" ? { roi: args.roi } : {}),
+    ...(args.specRef ? { specRef: args.specRef } : {}),
+  };
+
+  // Soft warnings — surface, don't reject.
+  const warnings = [];
+  const roiWarn = warnRoiVsTheme(capability.roi, theme);
+  if (roiWarn) warnings.push(roiWarn);
+
+  if (args.dryRun) {
+    return textResult(
+      JSON.stringify(
+        {
+          ok: true,
+          dryRun: true,
+          wouldCreate: capability,
+          warnings,
+          message: `Would create capability ${id} (${capability.name}) under ${theme.id} (${theme.name}). No record written.`,
+        },
+        null,
+        2
+      )
+    );
+  }
+
+  let rpcResult;
+  try {
+    rpcResult = await rpcCall("propose_capability", {
+      p_workspace_id: wsId,
+      p_capability: capability,
+      p_idempotency_key: args.idempotencyKey ?? null,
+    });
+  } catch (e) {
+    return errorResult(e.message);
+  }
+  const stored = rpcResult?.capability ?? capability;
+  const idempotent = rpcResult?.idempotent === true;
+  return textResult(
+    JSON.stringify(
+      {
+        ok: true,
+        id: stored.id,
+        pillarId: stored.pillarId,
+        idempotent,
+        warnings,
+        message: idempotent
+          ? `Capability ${stored.id} already exists with idempotencyKey ${args.idempotencyKey}; returning existing instead of duplicating.`
+          : `Created capability ${stored.id} (${stored.name}) under ${stored.pillarId}.`,
+      },
+      null,
+      2
+    )
+  );
+}
+
+/**
+ * One-shot snapshot for cold-start agents. Bundles themes, active
+ * capabilities, and in-flight tasks (status=in_progress|planned)
+ * into a single response so the agent doesn't need three round
+ * trips to orient. Always live — never cached.
+ *
+ * The response includes the resolved workspaceId so the agent knows
+ * which id to thread back through subsequent write tools. This is
+ * how a single MCP install operates against multiple workspaces:
+ * the agent reads the workspaceId out of this response (or out of
+ * `.roadmapper/snapshot.json` in the repo it's working in), then
+ * passes that id back on `propose_task` / `propose_capability` /
+ * `propose_theme` calls.
+ */
+function getRoadmapSnapshot(projected, wsId, includeArchived = false) {
+  // Archived entities are filtered out by default — the snapshot
+  // is meant to surface what an agent should plan against, and
+  // archived rows are by definition not in scope. Pass
+  // includeArchived=true to include them (e.g. when reviewing
+  // historical state).
+  const themes = includeArchived
+    ? projected.themes
+    : projected.themes.filter((t) => !t.archived);
+  const activeCapabilities = projected.capabilities.filter((c) => {
+    if (!includeArchived && c.archived) return false;
+    return effectiveCapabilityStatus(c, projected.tasks) !== "delivered";
+  });
+  const inFlightTasks = projected.tasks.filter((t) => {
+    if (!includeArchived && t.archived) return false;
+    return t.status === "in_progress" || t.status === "planned";
+  });
+  return textResult(
+    JSON.stringify(
+      {
+        workspaceId: wsId,
+        generatedAt: new Date().toISOString(),
+        themes,
+        capabilities: activeCapabilities,
+        tasks: inFlightTasks,
+        counts: {
+          themes: themes.length,
+          activeCapabilities: activeCapabilities.length,
+          inFlightTasks: inFlightTasks.length,
+          totalCapabilities: projected.capabilities.length,
+          totalTasks: projected.tasks.length,
+        },
+      },
+      null,
+      2
+    )
+  );
+}
+
+function suggestCapabilityFor(args, projected) {
+  const desc = (args.description || "").trim();
+  if (!desc) return errorResult("description is required.");
+  const limit = Math.min(25, Math.max(1, args.limit ?? 5));
+
+  // Skip delivered capabilities — they're closed bets. A new PR
+  // mapping to a delivered cap would either be wrong (work for a
+  // different bet) or reopen-the-bet (which the user should do
+  // explicitly, not as a side effect of agent triage).
+  const activeCaps = projected.capabilities.filter(
+    (c) => effectiveCapabilityStatus(c, projected.tasks) !== "delivered"
+  );
+  const query = tokenize(desc);
+  const ranked = activeCaps
+    .map((c) => {
+      const hay = tokenize(
+        `${c.name} ${c.description ?? ""} ${c.outcome ?? ""}`
+      );
+      return { capability: c, score: jaccardScore(query, hay) };
+    })
+    .filter((r) => r.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit)
+    .map(({ capability, score }) => ({
+      id: capability.id,
+      name: capability.name,
+      pillarId: capability.pillarId,
+      outcome: capability.outcome,
+      score: Number(score.toFixed(3)),
+    }));
+
+  // Reminder via _meta when nothing strong came back — the model
+  // should pause and ask the user before inventing a new capability.
+  const topScore = ranked[0]?.score ?? 0;
+  const meta =
+    topScore < 0.4
+      ? {
+          _meta: {
+            roadmapper: {
+              reminder:
+                ranked.length === 0
+                  ? "No existing capability is a sensible parent. Before calling propose_capability, verify with the user that a brand-new capability is warranted — capabilities are quarterly bets, not single tasks."
+                  : "No strong match (top score < 0.4). If none of the listed capabilities fit, ask the user before calling propose_capability — the top match is often closer than it scores.",
+            },
+          },
+        }
+      : undefined;
+
+  return textResult(
+    JSON.stringify(
+      {
+        ok: true,
+        query: desc,
+        matches: ranked,
+        hint:
+          ranked.length === 0
+            ? "No existing capabilities overlap your description. propose_capability is likely the right next step."
+            : ranked[0].score > 0.4
+              ? `Strong match: ${ranked[0].id} (${ranked[0].name}). Strongly consider attaching tasks here instead of creating a duplicate capability.`
+              : `Weak overlap. If none of these fit, propose_capability is reasonable — but read the top match first.`,
+      },
+      null,
+      2
+    ),
+    meta
+  );
+}
+
+/**
+ * Theme-level mirror of suggestCapabilityFor — ranks existing
+ * themes by token overlap with the description and signals
+ * whether any existing theme is a sensible home for the work.
+ *
+ * Themes are years-stable so the messaging is more conservative:
+ * even a weak match should usually win over creating a new theme.
+ * Only an empty or very-low-overlap result + explicit user intent
+ * should lead to propose_theme.
+ */
+function suggestThemeFor(args, projected) {
+  const desc = (args.description || "").trim();
+  if (!desc) return errorResult("description is required.");
+  const limit = Math.min(25, Math.max(1, args.limit ?? 5));
+
+  // Skip archived themes — retired strategic bets shouldn't pull
+  // new work into a closed mandate.
+  const activeThemes = projected.themes.filter((t) => !t.archived);
+  const query = tokenize(desc);
+  const ranked = activeThemes
+    .map((t) => {
+      const hay = tokenize(`${t.name} ${t.description ?? ""}`);
+      return { theme: t, score: jaccardScore(query, hay) };
+    })
+    .filter((r) => r.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit)
+    .map(({ theme, score }) => ({
+      id: theme.id,
+      name: theme.name,
+      description: theme.description ?? "",
+      score: Number(score.toFixed(3)),
+    }));
+
+  // Reminder when nothing matches strongly — theme creation is the
+  // years-stable decision, so even a weak match deserves a pause.
+  const topScore = ranked[0]?.score ?? 0;
+  const meta =
+    topScore < 0.4
+      ? {
+          _meta: {
+            roadmapper: {
+              reminder:
+                ranked.length === 0
+                  ? "No existing theme overlaps your description. Themes are years-stable, so creating a new one is a big decision — verify with the user that this represents a genuinely new strategic direction, not a reframing of an existing bet, before calling propose_theme."
+                  : "No strong match (top score < 0.4). Re-using a 'close-enough' theme is almost always the right move; ask the user before calling propose_theme.",
+            },
+          },
+        }
+      : undefined;
+
+  return textResult(
+    JSON.stringify(
+      {
+        ok: true,
+        query: desc,
+        matches: ranked,
+        hint:
+          ranked.length === 0
+            ? "No existing theme overlaps. propose_theme MAY be appropriate, but only with explicit user confirmation that a new strategic direction is intended — themes are years-stable, not per-feature."
+            : ranked[0].score > 0.4
+              ? `Strong match: ${ranked[0].id} (${ranked[0].name}). Attach capabilities under this theme instead of creating a new one.`
+              : `Weak overlap. The top match is often closer than it scores; prefer that over creating a new theme unless the user explicitly asks for a new strategic direction.`,
+      },
+      null,
+      2
+    ),
+    meta
+  );
+}
+
+async function linkPR(args, projected, seed, wsId) {
+  const task = projected.tasks.find((t) => t.id === args.taskId);
+  if (!task) return errorResult(`Task ${args.taskId} not found.`);
+  if (!args.repo || !args.number)
+    return errorResult("repo and number are required.");
+
+  // Build the PR object the way the app expects.
+  const pr = {
+    repo: args.repo,
+    number: args.number,
+    ...(args.title ? { title: args.title } : {}),
+    ...(typeof args.merged === "boolean" ? { merged: args.merged } : {}),
+    ...(args.mergedAt ? { mergedAt: args.mergedAt } : {}),
+    ...(args.authorGithub ? { authorGithub: args.authorGithub } : {}),
+    ...(args.authorKind ? { authorKind: args.authorKind } : {}),
+  };
+
+  // The RPC can't see the seed JSON; if the task is a seed task with
+  // no prior PR patches, we need to pass its seed prs so the RPC can
+  // union our new PR on top rather than clobber.
+  const seedTask = (seed?.tasks ?? []).find((t) => t.id === args.taskId);
+  const seedPrs = seedTask?.prs ?? [];
+
+  let rpcResult;
+  try {
+    rpcResult = await rpcCall("link_pr", {
+      p_workspace_id: wsId,
+      p_task_id: args.taskId,
+      p_pr: pr,
+      p_seed_prs: seedPrs,
+    });
+  } catch (e) {
+    return errorResult(e.message);
+  }
+  const idempotent = rpcResult?.idempotent === true;
+  return textResult(
+    JSON.stringify(
+      {
+        ok: true,
+        taskId: args.taskId,
+        pr: `${pr.repo}#${pr.number}`,
+        idempotent,
+        message: idempotent
+          ? `${pr.repo}#${pr.number} was already linked to ${args.taskId}; no change.`
+          : `Attached ${pr.repo}#${pr.number} to ${args.taskId}.`,
+      },
+      null,
+      2
+    )
+  );
+}
+
+/**
+ * Shared handler for the six archive/unarchive tools. Validates
+ * inputs, calls the SQL RPC (which does the heavy lifting +
+ * audit-log write), and renders the response. The SQL handles
+ * refuse-with-children, idempotency, parent-active checks, and
+ * audit attribution; the JS layer just routes.
+ */
+async function archiveLifecycle(kind, action, args, wsId) {
+  const idArg =
+    kind === "task" ? "taskId" : kind === "capability" ? "capabilityId" : "themeId";
+  const entityId = (args?.[idArg] ?? "").trim();
+  if (!entityId) return errorResult(`${idArg} is required.`);
+  const reason = (args?.reason ?? "").trim();
+  if (!reason) return errorResult("reason is required.");
+  if (!wsId) {
+    return errorResult(
+      "workspaceId could not be resolved (pass workspaceId arg or set SUPABASE_WORKSPACE_ID)."
+    );
+  }
+  try {
+    const result = await rpcCall(
+      action === "archive" ? "archive_entity" : "unarchive_entity",
+      {
+        p_workspace_id: wsId,
+        p_kind: kind,
+        p_entity_id: entityId,
+        p_reason: reason,
+        p_actor_label: "mcp:agent",
+        p_idempotency_key: args?.idempotencyKey ?? null,
+        p_dry_run: args?.dryRun === true,
+      }
+    );
+    return textResult(JSON.stringify(result, null, 2));
+  } catch (e) {
+    return errorResult(e.message);
+  }
+}
+
+/**
+ * Single-entity move. Validates inputs, calls move_entity RPC,
+ * renders the response. SQL handles target-active check, idempotency,
+ * U5 unarchive-on-move, and audit attribution.
+ */
+async function moveEntity(kind, args, wsId) {
+  const idArg = kind === "task" ? "taskId" : "capabilityId";
+  const parentArg = kind === "task" ? "newCapabilityId" : "newThemeId";
+  const entityId = (args?.[idArg] ?? "").trim();
+  if (!entityId) return errorResult(`${idArg} is required.`);
+  const newParentId = (args?.[parentArg] ?? "").trim();
+  if (!newParentId) return errorResult(`${parentArg} is required.`);
+  const reason = (args?.reason ?? "").trim();
+  if (!reason) return errorResult("reason is required.");
+  if (!wsId) {
+    return errorResult(
+      "workspaceId could not be resolved (pass workspaceId arg or set SUPABASE_WORKSPACE_ID)."
+    );
+  }
+  try {
+    const result = await rpcCall("move_entity", {
+      p_workspace_id: wsId,
+      p_kind: kind,
+      p_entity_id: entityId,
+      p_new_parent_id: newParentId,
+      p_reason: reason,
+      p_actor_label: "mcp:agent",
+      p_batch_id: null,
+      p_dry_run: args?.dryRun === true,
+    });
+    return textResult(JSON.stringify(result, null, 2));
+  } catch (e) {
+    return errorResult(e.message);
+  }
+}
+
+/**
+ * Bulk move. Validates the batch (size, shape), generates one
+ * batchId, then issues move_entity calls in sequence stamping each
+ * audit row with the shared id. Per-item failures don't roll back
+ * earlier successes — the response surfaces each move's outcome so
+ * the caller can retry the failures or surface them to the user.
+ */
+async function moveBulk(kind, args, wsId) {
+  const idArg = kind === "task" ? "taskId" : "capabilityId";
+  const parentArg = kind === "task" ? "newCapabilityId" : "newThemeId";
+  const moves = args?.moves;
+  if (!Array.isArray(moves) || moves.length === 0) {
+    return errorResult("moves must be a non-empty array.");
+  }
+  if (moves.length > 100) {
+    return errorResult(`bulk move cap is 100 (got ${moves.length}).`);
+  }
+  const reason = (args?.reason ?? "").trim();
+  if (!reason) return errorResult("reason is required.");
+  if (!wsId) {
+    return errorResult(
+      "workspaceId could not be resolved (pass workspaceId arg or set SUPABASE_WORKSPACE_ID)."
+    );
+  }
+  // Validate every item up-front so we don't half-apply a batch
+  // that's structurally broken — caller probably wants to fix the
+  // payload, not see 7 successes and 3 "missing field" errors.
+  for (let i = 0; i < moves.length; i++) {
+    const m = moves[i];
+    if (!m || typeof m !== "object") {
+      return errorResult(`moves[${i}] must be an object.`);
+    }
+    if (typeof m[idArg] !== "string" || !m[idArg].trim()) {
+      return errorResult(`moves[${i}].${idArg} is required.`);
+    }
+    if (typeof m[parentArg] !== "string" || !m[parentArg].trim()) {
+      return errorResult(`moves[${i}].${parentArg} is required.`);
+    }
+  }
+  const batchId = `batch-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+  const dryRun = args?.dryRun === true;
+  const results = [];
+  for (let i = 0; i < moves.length; i++) {
+    const m = moves[i];
+    try {
+      const out = await rpcCall("move_entity", {
+        p_workspace_id: wsId,
+        p_kind: kind,
+        p_entity_id: m[idArg].trim(),
+        p_new_parent_id: m[parentArg].trim(),
+        p_reason: reason,
+        p_actor_label: "mcp:agent",
+        p_batch_id: batchId,
+        p_dry_run: dryRun,
+      });
+      results.push({ index: i, ...out });
+    } catch (e) {
+      results.push({ index: i, ok: false, error: e.message, entityId: m[idArg] });
+    }
+  }
+  const okCount = results.filter((r) => r.ok).length;
+  const failCount = results.length - okCount;
+  return textResult(
+    JSON.stringify(
+      { ok: failCount === 0, batchId, total: results.length, okCount, failCount, dryRun, results },
+      null,
+      2
+    )
+  );
+}
+
+/**
+ * Per-kind field validators for update_*. Enums and ranges live here
+ * (UP3 in the spec) so the SQL function can stay structural. Returns
+ * an array of error strings; empty array means valid.
+ */
+function validateUpdatePatch(kind, patch) {
+  const errors = [];
+  if (kind === "task") {
+    if (patch.title !== undefined) {
+      const e = validateName(patch.title, 5);
+      if (e) errors.push(e);
+    }
+    if (patch.status !== undefined && !VALID_STATUSES.has(patch.status)) {
+      errors.push(`invalid status: ${patch.status}`);
+    }
+    if (patch.priority !== undefined && !VALID_PRIORITIES.has(patch.priority)) {
+      errors.push(`invalid priority: ${patch.priority}`);
+    }
+    if (patch.effort !== undefined && !VALID_EFFORTS.has(patch.effort)) {
+      errors.push(`invalid effort: ${patch.effort}`);
+    }
+    if (patch.kind !== undefined && !VALID_KINDS.has(patch.kind)) {
+      errors.push(`invalid kind: ${patch.kind}`);
+    }
+    if (
+      patch.progress !== undefined &&
+      (typeof patch.progress !== "number" || patch.progress < 0 || patch.progress > 100)
+    ) {
+      errors.push(`progress must be 0–100, got ${patch.progress}.`);
+    }
+    if (
+      patch.expectedPRs !== undefined &&
+      (typeof patch.expectedPRs !== "number" || patch.expectedPRs <= 0)
+    ) {
+      errors.push(`expectedPRs must be a positive number, got ${patch.expectedPRs}.`);
+    }
+    if (
+      patch.expectedScope !== undefined &&
+      (typeof patch.expectedScope !== "number" || patch.expectedScope <= 0)
+    ) {
+      errors.push(`expectedScope must be a positive number, got ${patch.expectedScope}.`);
+    }
+  } else if (kind === "capability") {
+    if (patch.name !== undefined) {
+      const e = validateName(patch.name, 8);
+      if (e) errors.push(e);
+    }
+    if (patch.outcome !== undefined) {
+      const e = validateOutcome(patch.outcome);
+      if (e) errors.push(e);
+    }
+    if (patch.confidence !== undefined) {
+      const e = validateConfidence(patch.confidence);
+      if (e) errors.push(e);
+    }
+    if (patch.impact !== undefined) {
+      if (typeof patch.impact !== "number" || !VALID_IMPACTS.has(patch.impact)) {
+        errors.push(`invalid impact: ${patch.impact} (must be 0.25, 0.5, 1, 2, or 3).`);
+      }
+    }
+  } else if (kind === "theme") {
+    if (patch.name !== undefined) {
+      const e = validateName(patch.name, 5);
+      if (e) errors.push(e);
+    }
+  }
+  return errors;
+}
+
+/**
+ * Deep JSON equality for patch-vs-current diffing. Handles primitives,
+ * arrays (order-sensitive — tags/dependsOn order is meaningful), and
+ * plain objects. Sufficient for the field shapes update_* accepts.
+ */
+function jsonEqual(a, b) {
+  if (a === b) return true;
+  if (a === null || b === null || a === undefined || b === undefined) {
+    return a == null && b == null;
+  }
+  if (typeof a !== typeof b) return false;
+  if (typeof a !== "object") return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  if (Array.isArray(a)) {
+    if (a.length !== b.length) return false;
+    return a.every((x, i) => jsonEqual(x, b[i]));
+  }
+  const ka = Object.keys(a);
+  const kb = Object.keys(b);
+  if (ka.length !== kb.length) return false;
+  return ka.every((k) => Object.prototype.hasOwnProperty.call(b, k) && jsonEqual(a[k], b[k]));
+}
+
+/**
+ * Single-entity update. Validates the patch against per-kind rules
+ * (UP3), then diffs against the *projected* entity (seed + edits
+ * merged) so seed-resident values participate in idempotency and
+ * audit before-snapshots. Only the truly differing keys are sent
+ * to SQL — the MCP layer is the diff authority because SQL only
+ * sees the sparse patches row, not the seed overlay.
+ */
+async function updateEntity(kind, args, wsId, projected) {
+  const idArg = kind === "task" ? "taskId" : kind === "capability" ? "capabilityId" : "themeId";
+  const entityId = (args?.[idArg] ?? "").trim();
+  if (!entityId) return errorResult(`${idArg} is required.`);
+  const patch = args?.patch;
+  if (!patch || typeof patch !== "object" || Array.isArray(patch)) {
+    return errorResult("patch must be a non-empty object.");
+  }
+  if (Object.keys(patch).length === 0) {
+    return errorResult("patch must include at least one field.");
+  }
+  const reason = (args?.reason ?? "").trim();
+  if (!reason) return errorResult("reason is required.");
+  const validationErrors = validateUpdatePatch(kind, patch);
+  if (validationErrors.length) {
+    return errorResult(`Invalid patch: ${validationErrors.join("; ")}`);
+  }
+  if (!wsId) {
+    return errorResult(
+      "workspaceId could not be resolved (pass workspaceId arg or set SUPABASE_WORKSPACE_ID)."
+    );
+  }
+  if (!projected) {
+    return errorResult("internal: projected view not available.");
+  }
+
+  // Look up the entity in the projected view (seed + edits merged).
+  const collection =
+    kind === "task" ? projected.tasks
+    : kind === "capability" ? projected.capabilities
+    : projected.themes;
+  const current = collection.find((e) => e.id === entityId);
+  if (!current) {
+    return errorResult(`${kind} ${entityId} not found in workspace.`);
+  }
+
+  // Decode HTML entities on user-facing text fields before diffing.
+  // Without this, an agent that re-sends `Sandbox &amp; Test Mode`
+  // to "fix" a previously-encoded value would land another &amp;
+  // and look idempotent against the encoded current value. Decode
+  // first so the comparison and the persisted value are both clean.
+  const TEXT_FIELDS = new Set([
+    "title", "summary", "name", "description", "outcome", "hypothesis",
+    "owner", "team", "note",
+  ]);
+  const cleanedPatch = {};
+  for (const [k, v] of Object.entries(patch)) {
+    cleanedPatch[k] = TEXT_FIELDS.has(k) && typeof v === "string" ? cleanText(v) : v;
+  }
+
+  // Compute the effective patch and its before-snapshot. SQL will
+  // write before_snapshot verbatim into audit.before_json — that's
+  // the whole point of doing the diff up here where the seed is
+  // overlaid.
+  const effectivePatch = {};
+  const beforeSnapshot = {};
+  for (const [k, v] of Object.entries(cleanedPatch)) {
+    if (!jsonEqual(current[k], v)) {
+      effectivePatch[k] = v;
+      beforeSnapshot[k] = current[k] ?? null;
+    }
+  }
+  if (Object.keys(effectivePatch).length === 0) {
+    return textResult(
+      JSON.stringify(
+        {
+          ok: true,
+          entityId,
+          kind,
+          idempotent: true,
+          dryRun: args?.dryRun === true,
+        },
+        null,
+        2
+      )
+    );
+  }
+
+  try {
+    const result = await rpcCall("update_entity", {
+      p_workspace_id: wsId,
+      p_kind: kind,
+      p_entity_id: entityId,
+      p_patch: effectivePatch,
+      p_before: beforeSnapshot,
+      p_reason: reason,
+      p_actor_label: "mcp:agent",
+      p_dry_run: args?.dryRun === true,
+    });
+    return textResult(JSON.stringify(result, null, 2));
+  } catch (e) {
+    return errorResult(e.message);
+  }
+}
+
+/**
+ * Append a metric reading to a capability's outcomeReadings array.
+ * Server takes a row lock so concurrent writers (script + human)
+ * union safely instead of clobbering.
+ */
+async function recordOutcomeReading(args, wsId, projected) {
+  const capabilityId = (args?.capabilityId ?? "").trim();
+  if (!capabilityId) return errorResult("capabilityId is required.");
+  if (typeof args?.value !== "number" || !Number.isFinite(args.value)) {
+    return errorResult("value is required and must be a finite number.");
+  }
+  const asOf = (args?.asOf ?? "").trim();
+  if (!asOf) return errorResult("asOf is required (ISO date or timestamp).");
+  const source = (args?.source ?? "").trim();
+  if (!source) return errorResult("source is required.");
+  if (args?.note !== undefined && args?.note !== null && typeof args.note !== "string") {
+    return errorResult("note must be a string when supplied.");
+  }
+  if (!wsId) {
+    return errorResult(
+      "workspaceId could not be resolved (pass workspaceId arg or set SUPABASE_WORKSPACE_ID)."
+    );
+  }
+  // Existence check — the RPC will happily write a patch entry against
+  // any capabilityId, which would orphan the reading invisibly (the
+  // projector iterates seed + newCapabilities, not the patches dict
+  // alone). Refuse here so phantom readings never land.
+  if (projected) {
+    const exists = projected.capabilities.some((c) => c.id === capabilityId);
+    if (!exists) return errorResult(`capability ${capabilityId} not found in workspace.`);
+  }
+  try {
+    const result = await rpcCall("record_outcome_reading", {
+      p_workspace_id: wsId,
+      p_capability_id: capabilityId,
+      p_value: args.value,
+      p_as_of: asOf,
+      p_source: source,
+      p_note: args.note ?? null,
+      p_actor_label: "mcp:agent",
+    });
+    return textResult(JSON.stringify(result, null, 2));
+  } catch (e) {
+    return errorResult(e.message);
+  }
+}
+
+/**
+ * Read tool — surface capabilities with no recent outcome reading.
+ * Pure projection over the workspace edits; no SQL round-trip needed
+ * since the readings live on each capability already.
+ */
+function listStaleOutcomes(args, projected) {
+  const thresholdDays = typeof args?.thresholdDays === "number" ? args.thresholdDays : 14;
+  const includeArchived = args?.includeArchived === true;
+  const nowMs = Date.now();
+  const thresholdMs = thresholdDays * 24 * 60 * 60 * 1000;
+
+  const stale = [];
+  for (const cap of projected.capabilities) {
+    if (!includeArchived && cap.archived) continue;
+    // Only flag capabilities that declared an outcome — bets without
+    // a falsifiable outcome can't be stale-checked meaningfully.
+    if (!cap.outcome || cap.outcome.trim().length === 0) continue;
+    const rawReadings = Array.isArray(cap.outcomeReadings) ? cap.outcomeReadings : [];
+    // Drop readings whose asOf can't be parsed — they can't anchor a
+    // staleness calculation, and if we let them participate they
+    // could win the "latest" reducer (NaN > X is false) and zero out
+    // staleness for an otherwise-stale capability.
+    const readings = rawReadings.filter(
+      (r) => r && typeof r.asOf === "string" && Number.isFinite(Date.parse(r.asOf))
+    );
+    const latest = readings.length === 0
+      ? null
+      : readings.reduce(
+          (acc, r) => (acc && Date.parse(acc.asOf) >= Date.parse(r.asOf) ? acc : r),
+          null
+        );
+    const daysSince = latest
+      ? Math.floor((nowMs - Date.parse(latest.asOf)) / (24 * 60 * 60 * 1000))
+      : null;
+    const isStale =
+      latest === null ||
+      (typeof daysSince === "number" && daysSince * 24 * 60 * 60 * 1000 > thresholdMs);
+    if (!isStale) continue;
+    stale.push({
+      id: cap.id,
+      name: cap.name,
+      outcome: cap.outcome,
+      daysSinceLastReading: daysSince,
+      latestReading: latest,
+      readingCount: rawReadings.length,
+      malformedReadingCount: rawReadings.length - readings.length || undefined,
+    });
+  }
+  // Sort: never-measured first, then by stalest.
+  stale.sort((a, b) => {
+    if (a.daysSinceLastReading == null && b.daysSinceLastReading != null) return -1;
+    if (b.daysSinceLastReading == null && a.daysSinceLastReading != null) return 1;
+    return (b.daysSinceLastReading ?? 0) - (a.daysSinceLastReading ?? 0);
+  });
+  return textResult(
+    JSON.stringify({ thresholdDays, count: stale.length, stale }, null, 2)
+  );
+}
+
+async function submitAcceptanceGrades(args, projected, wsId) {
+  const task = projected.tasks.find((t) => t.id === args.taskId);
+  if (!task) return errorResult(`Task ${args.taskId} not found.`);
+  const max = (task.acceptance ?? []).length;
+  if (max === 0)
+    return errorResult(
+      `Task ${task.id} has no acceptance criteria to grade. Add some first.`
+    );
+  for (const g of args.grades) {
+    if (g.index >= max)
+      return errorResult(
+        `Grade index ${g.index} is out of range (task has ${max} criteria).`
+      );
+  }
+
+  const today = todayISO();
+  const payload = args.grades.map((g) => ({
+    index: g.index,
+    status: g.status,
+    gradedAt: today,
+    gradedBy: "mcp:agent",
+    ...(g.note ? { note: g.note } : {}),
+  }));
+
+  try {
+    // RPC takes a row lock, re-reads existing grades under the lock,
+    // merges these indices on top, writes back. Concurrent graders
+    // for the same task queue cleanly — no clobber.
+    await rpcCall("grade_acceptance", {
+      p_workspace_id: wsId,
+      p_task_id: task.id,
+      p_grades: payload,
+    });
+  } catch (e) {
+    return errorResult(e.message);
+  }
+
+  return textResult(
+    JSON.stringify(
+      {
+        ok: true,
+        taskId: task.id,
+        graded: args.grades.length,
+        of: max,
+      },
+      null,
+      2
+    )
+  );
+}
+
+/**
+ * Standard MCP tool-result envelope. The optional `extra` object can
+ * carry `_meta` (annotations the client may surface as system
+ * reminders), `structuredContent`, or other MCP-spec fields. We use
+ * _meta for the system-reminder nudges per the effectiveness memo.
+ */
+function textResult(text, extra) {
+  return { content: [{ type: "text", text }], ...(extra ?? {}) };
+}
+function errorResult(message) {
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+
+/**
+ * Build the nudge text we attach via _meta on certain read results.
+ * Returns null when no nudge is warranted — keeps the response
+ * clean for the common case.
+ */
+function buildReminder(toolName, projected) {
+  const reminders = [];
+  // If the rubric hasn't been fetched and the agent's reading list_*
+  // / get_*, they're orienting and about to plan — get the rubric in.
+  if (
+    session.rubricFetchedAt === null &&
+    (toolName === "list_capabilities" ||
+      toolName === "list_tasks" ||
+      toolName === "get_roadmap_snapshot" ||
+      toolName === "list_themes")
+  ) {
+    reminders.push(
+      "Call get_agents_md before any propose_* / submit_acceptance_grades / link_pr call — those tools refuse without it."
+    );
+  }
+  // Tasks with merged PRs but no acceptance grades = ungraded
+  // deliveries. The rubric requires self-grading before reviewer
+  // approval.
+  if (toolName === "list_tasks" || toolName === "get_roadmap_snapshot") {
+    const ungraded = projected.tasks.filter((t) => {
+      if (t.status !== "delivered") return false;
+      const merged = (t.prs ?? []).some((p) => p.merged);
+      if (!merged) return false;
+      return !t.acceptanceGrades || t.acceptanceGrades.length === 0;
+    });
+    if (ungraded.length > 0) {
+      const ids = ungraded.slice(0, 5).map((t) => t.id).join(", ");
+      const more = ungraded.length > 5 ? `, +${ungraded.length - 5} more` : "";
+      reminders.push(
+        `${ungraded.length} delivered task${ungraded.length === 1 ? "" : "s"} ` +
+          `have merged PRs without submitted acceptance grades. ` +
+          `Call submit_acceptance_grades for: ${ids}${more}.`
+      );
+    }
+  }
+  if (reminders.length === 0) return null;
+  return reminders.join(" ");
+}
+
+function withReminder(toolName, projected, payload) {
+  const text = buildReminder(toolName, projected);
+  if (!text) return payload;
+  return {
+    ...payload,
+    _meta: {
+      ...(payload._meta ?? {}),
+      roadmapper: {
+        ...(payload._meta?.roadmapper ?? {}),
+        reminder: text,
+      },
+    },
+  };
+}
+
+// ── MCP resources + prompts ───────────────────────────────────────
+//
+// resources/* — content the client can pull without the model
+// deciding to call a tool. Some clients auto-subscribe on connect,
+// which sidesteps the "agent forgot to fetch the rubric" failure.
+// prompts/*   — parameterized templates the user invokes directly
+// (e.g. "/roadmapper:plan-feature lp v2"). They orchestrate a flow
+// without depending on the model's judgment.
+//
+// Both arrays are intentionally small. Keeping the surface tight
+// is part of the contract — agents read all of this on connect.
+
+const RESOURCES = [
+  {
+    uri: "roadmapper://rubric",
+    name: "Planning rubric (AGENTS.md)",
+    description:
+      "The contract every planner must satisfy: task shape, acceptance criteria format, capability outcome rubric, grading dimensions. Same content as get_agents_md, exposed as a resource so MCP clients that auto-subscribe pull it at connect.",
+    mimeType: "text/markdown",
+  },
+  {
+    uri: "roadmapper://capabilities/active",
+    name: "Active capabilities (snapshot)",
+    description:
+      "Live list of non-delivered capabilities for the env-default workspace. Read this before propose_task or propose_capability to find the right parent. Note: MCP resources don't accept arguments, so this always reads SUPABASE_WORKSPACE_ID's workspace — use list_capabilities({ workspaceId }) for cross-workspace reads.",
+    mimeType: "application/json",
+  },
+  {
+    uri: "roadmapper://tasks/open",
+    name: "Open tasks (snapshot)",
+    description:
+      "Live list of in_progress + planned tasks for the env-default workspace. Same workspaceId caveat as roadmapper://capabilities/active — use list_tasks({ workspaceId }) for cross-workspace reads.",
+    mimeType: "application/json",
+  },
+];
+
+async function readResource(uri) {
+  if (uri === "roadmapper://rubric") {
+    // Side-effect: reading the rubric resource counts as fetching
+    // it. Mutators after this don't get blocked even if the agent
+    // never called the tool — the contract is "the rubric reached
+    // the model," not "this specific call shape ran."
+    if (session.rubricFetchedAt === null) {
+      session.rubricFetchedAt = Date.now();
+      // Pass the cwd snapshot's workspace id so the row is
+      // visible in Settings → MCP activity. Without this the
+      // resource-route fetch lands with workspace_id=NULL and
+      // gets filtered out for non-operator viewers (per migration
+      // 0038's NULL-workspace lock).
+      recordTelemetry(
+        "rubric_fetched",
+        { via: "resource" },
+        snapshotWorkspaceId() ?? undefined
+      );
+    }
+    return {
+      contents: [
+        { uri, mimeType: "text/markdown", text: readAgentsMd() },
+      ],
+    };
+  }
+  // The two snapshot resources project workspace state on each read
+  // so the response is always live; mirrors get_roadmap_snapshot.
+  const projected =
+    (await readWorkspaceProjected()) ?? project(readSeed(), {});
+
+  if (uri === "roadmapper://capabilities/active") {
+    // Counts as cap discovery for the propose_capability gate —
+    // identical intent to suggest_capability_for / list_capabilities,
+    // just delivered as an MCP resource.
+    session.capsDiscoveredAt = Date.now();
+    const active = projected.capabilities.filter(
+      (c) => effectiveCapabilityStatus(c, projected.tasks) !== "delivered"
+    );
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: "application/json",
+          text: JSON.stringify(active, null, 2),
+        },
+      ],
+    };
+  }
+  if (uri === "roadmapper://tasks/open") {
+    const open = projected.tasks.filter(
+      (t) => t.status === "in_progress" || t.status === "planned"
+    );
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: "application/json",
+          text: JSON.stringify(open, null, 2),
+        },
+      ],
+    };
+  }
+  throw new Error(`Unknown resource: ${uri}`);
+}
+
+const PROMPTS = [
+  {
+    name: "plan-feature",
+    description:
+      "Force the full planning flow: rubric → capability resolution → tasks under it. Use when the user says 'design features for X' / 'plan Y' — bypasses model judgment.",
+    arguments: [
+      {
+        name: "description",
+        description: "One-line description of the feature or workstream.",
+        required: true,
+      },
+    ],
+  },
+  {
+    name: "close-task",
+    description:
+      "Force the deliver-flow: load the task → self-grade against its acceptance criteria → link the PR. Use after implementing a TK-NNNNNN.",
+    arguments: [
+      { name: "task_id", description: "TK-NNNNNN", required: true },
+      { name: "pr_url", description: "https://github.com/...", required: false },
+    ],
+  },
+  {
+    name: "weekly-review",
+    description:
+      "Walk through open tasks, stale capabilities, and ungraded deliveries. Use for a structured roadmap review pass.",
+    arguments: [],
+  },
+];
+
+function renderPrompt(name, args) {
+  const text = (() => {
+    switch (name) {
+      case "plan-feature":
+        return (
+          `Plan a feature: "${args.description ?? "(no description provided)"}"\n\n` +
+          "Follow this flow exactly:\n" +
+          "1. Call get_agents_md (or read roadmapper://rubric) to load the rubric for this session.\n" +
+          "2. Call suggest_capability_for with the description above. Read every returned candidate's outcome before deciding.\n" +
+          "3. If a returned candidate scores > 0.4 OR its outcome maps to what we're building, propose tasks under it via propose_task. Each task MUST include acceptance criteria per the rubric.\n" +
+          "4. If nothing fits, STOP and ask the user before calling propose_capability — capabilities are quarterly bets, not single tasks.\n" +
+          "5. After tasks are proposed, summarize: capabilityId chosen, task ids created, anything skipped and why."
+        );
+      case "close-task":
+        return (
+          `Close task ${args.task_id ?? "(missing task_id)"}.\n\n` +
+          "Follow this flow exactly:\n" +
+          "1. Call get_agents_md (or read roadmapper://rubric) to load grading dimensions.\n" +
+          `2. Call get_task({ id: "${args.task_id ?? ""}" }) and read every acceptance criterion.\n` +
+          "3. For each criterion, decide pass/fail. Fabricated passes destroy this signal — only mark pass if you verified.\n" +
+          "4. Call submit_acceptance_grades with the per-index results. Include a note on any fail.\n" +
+          (args.pr_url
+            ? `5. Call link_pr to attach ${args.pr_url} to the task.\n`
+            : "5. If you opened a PR, call link_pr to attach it.\n") +
+          "6. Stamp Roadmapper-Task: " +
+          (args.task_id ?? "TK-NNNNNN") +
+          " in the PR body so the webhook routes future events back here."
+        );
+      case "weekly-review":
+        return (
+          "Run a structured roadmap review.\n\n" +
+          "1. Call get_agents_md to load the rubric (or confirm rubric is current).\n" +
+          "2. Call get_roadmap_snapshot for the canonical model. Note any _meta reminders in the response.\n" +
+          "3. For each active capability, scan: are open tasks aging? Are any without acceptance criteria? Are there delivered tasks without acceptance grades?\n" +
+          "4. List capabilities whose outcomes are no longer falsifiable or whose tasks all delivered (close them or pivot).\n" +
+          "5. Report: ungraded deliveries, stale capabilities, capabilities ready to close, suggested next bets."
+        );
+      default:
+        throw new Error(`Unknown prompt: ${name}`);
+    }
+  })();
+  return {
+    description: PROMPTS.find((p) => p.name === name)?.description ?? "",
+    messages: [
+      { role: "user", content: { type: "text", text } },
+    ],
+  };
+}
+
+async function handle(request) {
+  const { id, method, params } = request;
+  try {
+    if (method === "initialize") {
+      // Snapshot counts so an MCP client showing server info
+      // surfaces actual roadmap shape, not just "connected".
+      const projected =
+        (await readWorkspaceProjected()) ?? project(readSeed(), {});
+      const openTasks = projected.tasks.filter(
+        (t) => t.status !== "delivered"
+      ).length;
+      const stats = {
+        themes: projected.themes.length,
+        capabilities: projected.capabilities.length,
+        openTasks,
+      };
+      // Fresh session — reset rubric-fetched state. The client
+      // re-initializes when it reconnects, which is the right
+      // boundary for "you need to fetch the rubric again."
+      resetSession();
+      recordTelemetry("session_initialized", { stats });
+      return {
+        jsonrpc: "2.0",
+        id,
+        result: {
+          protocolVersion: PROTOCOL_VERSION,
+          // Declare every capability we support. resources +
+          // prompts unlock the auto-pull / slash-command surfaces
+          // some MCP clients expose; tools work for everyone.
+          capabilities: {
+            tools: {},
+            resources: { listChanged: false },
+            prompts: { listChanged: false },
+          },
+          serverInfo: {
+            name: SERVER_NAME,
+            version: SERVER_VERSION,
+            stats,
+            instructions:
+              "Roadmapper online — " +
+              `${stats.themes} theme${stats.themes === 1 ? "" : "s"}, ` +
+              `${stats.capabilities} capabilit${stats.capabilities === 1 ? "y" : "ies"}, ` +
+              `${stats.openTasks} open task${stats.openTasks === 1 ? "" : "s"}. ` +
+              "Call get_agents_md before planning — the propose_* and submit_acceptance_grades tools refuse without it. " +
+              "Use suggest_capability_for before propose_capability. " +
+              "Slash-prompts available: roadmapper:plan-feature, roadmapper:close-task, roadmapper:weekly-review.",
+          },
+        },
+      };
+    }
+    if (method === "tools/list") {
+      return { jsonrpc: "2.0", id, result: { tools: TOOLS } };
+    }
+    if (method === "tools/call") {
+      const result = await callTool(params?.name, params?.arguments ?? {});
+      return { jsonrpc: "2.0", id, result };
+    }
+    if (method === "resources/list") {
+      return { jsonrpc: "2.0", id, result: { resources: RESOURCES } };
+    }
+    if (method === "resources/read") {
+      const result = await readResource(params?.uri);
+      return { jsonrpc: "2.0", id, result };
+    }
+    if (method === "prompts/list") {
+      return { jsonrpc: "2.0", id, result: { prompts: PROMPTS } };
+    }
+    if (method === "prompts/get") {
+      const result = renderPrompt(params?.name, params?.arguments ?? {});
+      return { jsonrpc: "2.0", id, result };
+    }
+    // Notifications (no id) and unknown methods: ignore.
+    if (id === undefined) return null;
+    return {
+      jsonrpc: "2.0",
+      id,
+      error: { code: -32601, message: `Method not found: ${method}` },
+    };
+  } catch (e) {
+    return {
+      jsonrpc: "2.0",
+      id,
+      error: { code: -32603, message: e.message || String(e) },
+    };
+  }
+}
+
+/**
+ * `node mcp/server.mjs --selftest` — invokes each read tool against
+ * the local seed and prints a pass/fail table. Useful for sanity-
+ * checking the install without wiring it into an MCP client.
+ *
+ * Write tools (propose_task, submit_acceptance_grades) are smoke-
+ * tested for argument validation only — they don't touch Supabase.
+ */
+async function runSelftest() {
+  const seed = readSeed();
+  const aTheme = seed?.product?.themes?.[0]?.id;
+  const aCap = seed?.capabilities?.[0]?.id;
+  const aTask = seed?.tasks?.[0]?.id;
+
+  const checks = [
+    {
+      name: "initialize",
+      fn: () => handle({ id: 1, method: "initialize", params: {} }),
+      pass: (r) =>
+        r?.result?.serverInfo?.name === SERVER_NAME &&
+        // New: capabilities advertise resources + prompts too.
+        r?.result?.capabilities?.resources &&
+        r?.result?.capabilities?.prompts,
+    },
+    {
+      // Hitting a mutator with no rubric fetched must return the
+      // structured prerequisite_missing error with a `fix` field,
+      // not a successful write. This is the gate the effectiveness
+      // memo specified. Explicit resetSession() so the check is
+      // order-independent — if a prior check fetched the rubric,
+      // this would otherwise silently pass for the wrong reason.
+      name: "rubric gate blocks mutator before get_agents_md",
+      fn: () => {
+        resetSession();
+        return handle({
+          id: 11,
+          method: "tools/call",
+          params: {
+            name: "propose_task",
+            arguments: { capabilityId: aCap, title: "Should be blocked" },
+          },
+        });
+      },
+      pass: (r) => {
+        if (!r?.result?.isError) return false;
+        const text = r.result.content?.[0]?.text ?? "";
+        return (
+          text.includes("prerequisite_missing") && text.includes("get_agents_md")
+        );
+      },
+    },
+    {
+      // After fetching the rubric, propose_theme should still be
+      // blocked until the agent has actually listed themes. Asserts
+      // the discovery gate fires with the right `fix` field.
+      name: "discovery gate blocks propose_theme before list_themes",
+      fn: () => {
+        resetSession();
+        session.rubricFetchedAt = Date.now(); // rubric satisfied
+        return handle({
+          id: 16,
+          method: "tools/call",
+          params: {
+            name: "propose_theme",
+            arguments: { name: "Some New Theme Idea" },
+          },
+        });
+      },
+      pass: (r) => {
+        if (!r?.result?.isError) return false;
+        const text = r.result.content?.[0]?.text ?? "";
+        return (
+          text.includes("discovery_missing") && text.includes("list_themes")
+        );
+      },
+    },
+    {
+      // Same gate for propose_capability — requires suggest_capability_for
+      // (or list_capabilities / get_roadmap_snapshot) first.
+      name:
+        "discovery gate blocks propose_capability before suggest_capability_for",
+      fn: () => {
+        resetSession();
+        session.rubricFetchedAt = Date.now();
+        return handle({
+          id: 17,
+          method: "tools/call",
+          params: {
+            name: "propose_capability",
+            arguments: {
+              name: "Brand new capability",
+              pillarId: aTheme,
+              outcome: "x",
+            },
+          },
+        });
+      },
+      pass: (r) => {
+        if (!r?.result?.isError) return false;
+        const text = r.result.content?.[0]?.text ?? "";
+        return (
+          text.includes("discovery_missing") &&
+          text.includes("suggest_capability_for")
+        );
+      },
+    },
+    {
+      // get_roadmap_snapshot returns BOTH themes and caps in a single
+      // response, so it satisfies BOTH discovery gates at once.
+      name: "get_roadmap_snapshot satisfies both discovery gates",
+      fn: async () => {
+        resetSession();
+        session.rubricFetchedAt = Date.now();
+        await handle({
+          id: 18,
+          method: "tools/call",
+          params: { name: "get_roadmap_snapshot", arguments: {} },
+        });
+        return {
+          themesListedAt: session.themesListedAt,
+          capsDiscoveredAt: session.capsDiscoveredAt,
+        };
+      },
+      pass: (r) => r?.themesListedAt !== null && r?.capsDiscoveredAt !== null,
+    },
+    {
+      name: "resources/list returns the three resources",
+      fn: () => handle({ id: 12, method: "resources/list", params: {} }),
+      pass: (r) =>
+        Array.isArray(r?.result?.resources) &&
+        r.result.resources.length === RESOURCES.length &&
+        r.result.resources.some((x) => x.uri === "roadmapper://rubric"),
+    },
+    {
+      name: "resources/read rubric counts as a fetched rubric",
+      fn: () =>
+        handle({
+          id: 13,
+          method: "resources/read",
+          params: { uri: "roadmapper://rubric" },
+        }),
+      pass: (r) =>
+        r?.result?.contents?.[0]?.text?.includes("# AGENTS.md") &&
+        session.rubricFetchedAt !== null,
+    },
+    {
+      name: "prompts/list returns the three prompts",
+      fn: () => handle({ id: 14, method: "prompts/list", params: {} }),
+      pass: (r) =>
+        Array.isArray(r?.result?.prompts) &&
+        r.result.prompts.length === PROMPTS.length &&
+        r.result.prompts.some((p) => p.name === "plan-feature"),
+    },
+    {
+      name: "prompts/get plan-feature expands the template",
+      fn: () =>
+        handle({
+          id: 15,
+          method: "prompts/get",
+          params: {
+            name: "plan-feature",
+            arguments: { description: "demo description" },
+          },
+        }),
+      pass: (r) =>
+        r?.result?.messages?.[0]?.content?.text?.includes(
+          "suggest_capability_for"
+        ) &&
+        r.result.messages[0].content.text.includes("demo description"),
+    },
+    {
+      name: "tools/list",
+      fn: () => handle({ id: 2, method: "tools/list", params: {} }),
+      pass: (r) =>
+        Array.isArray(r?.result?.tools) && r.result.tools.length === TOOLS.length,
+    },
+    {
+      name: "list_themes",
+      fn: () =>
+        handle({
+          id: 3,
+          method: "tools/call",
+          params: { name: "list_themes", arguments: {} },
+        }),
+      pass: (r) => !!r?.result?.content?.[0]?.text?.includes(aTheme),
+    },
+    {
+      name: `list_capabilities themeId=${aTheme}`,
+      fn: () =>
+        handle({
+          id: 4,
+          method: "tools/call",
+          params: {
+            name: "list_capabilities",
+            arguments: { themeId: aTheme },
+          },
+        }),
+      pass: (r) => r?.result && !r.result.isError,
+    },
+    {
+      name: "list_tasks status=delivered",
+      fn: () =>
+        handle({
+          id: 5,
+          method: "tools/call",
+          params: {
+            name: "list_tasks",
+            arguments: { status: "delivered" },
+          },
+        }),
+      pass: (r) => r?.result && !r.result.isError,
+    },
+    {
+      // Phase-1 archive smoke: with no archived rows in the seed,
+      // includeArchived: true should still return the full set —
+      // and crucially the code path doesn't throw. Once Phase 2
+      // ships writes, a future check can assert that an archived
+      // task is hidden by default and visible with the flag.
+      name: "list_tasks includeArchived=true (smoke)",
+      fn: () =>
+        handle({
+          id: 51,
+          method: "tools/call",
+          params: {
+            name: "list_tasks",
+            arguments: { includeArchived: true },
+          },
+        }),
+      pass: (r) => r?.result && !r.result.isError,
+    },
+    {
+      name: `get_task id=${aTask}`,
+      fn: () =>
+        handle({
+          id: 6,
+          method: "tools/call",
+          params: { name: "get_task", arguments: { id: aTask } },
+        }),
+      pass: (r) =>
+        !r?.result?.isError &&
+        r?.result?.content?.[0]?.text?.includes(`"id": "${aTask}"`),
+    },
+    {
+      name: "get_task (bogus id returns error result)",
+      fn: () =>
+        handle({
+          id: 7,
+          method: "tools/call",
+          params: {
+            name: "get_task",
+            arguments: { id: "TK-NOPE" },
+          },
+        }),
+      pass: (r) => r?.result?.isError === true,
+    },
+    {
+      name: "get_agents_md",
+      fn: () =>
+        handle({
+          id: 8,
+          method: "tools/call",
+          params: { name: "get_agents_md", arguments: {} },
+        }),
+      pass: (r) => r?.result?.content?.[0]?.text?.includes("# AGENTS.md"),
+    },
+    {
+      name: "propose_task (bad capabilityId returns error result)",
+      fn: () =>
+        handle({
+          id: 9,
+          method: "tools/call",
+          params: {
+            name: "propose_task",
+            arguments: {
+              capabilityId: "CAP-NOPE",
+              title: "Should fail",
+            },
+          },
+        }),
+      pass: (r) => r?.result?.isError === true,
+    },
+    {
+      name: "propose_task (valid args, no service key) errors cleanly",
+      fn: () =>
+        handle({
+          id: 10,
+          method: "tools/call",
+          params: {
+            name: "propose_task",
+            arguments: { capabilityId: aCap, title: "Selftest task" },
+          },
+        }),
+      // Without SUPABASE_SERVICE_ROLE_KEY this must return an error result
+      // (not throw). With the key set, this would actually write — so we
+      // only assert the no-key path here.
+      pass: (r) =>
+        process.env.SUPABASE_SERVICE_ROLE_KEY
+          ? r?.result && !r.result.isError
+          : r?.result?.isError === true,
+    },
+    {
+      name: "propose_theme (missing name returns error result)",
+      fn: () =>
+        handle({
+          id: 11,
+          method: "tools/call",
+          params: { name: "propose_theme", arguments: { name: "" } },
+        }),
+      pass: (r) => r?.result?.isError === true,
+    },
+    {
+      name: "propose_capability (unknown pillarId returns error result)",
+      fn: () =>
+        handle({
+          id: 12,
+          method: "tools/call",
+          params: {
+            name: "propose_capability",
+            arguments: { name: "bogus", pillarId: "TH-DOES-NOT-EXIST" },
+          },
+        }),
+      pass: (r) => r?.result?.isError === true,
+    },
+    {
+      name: "propose_capability (invalid impact returns error result)",
+      fn: () =>
+        handle({
+          id: 13,
+          method: "tools/call",
+          params: {
+            name: "propose_capability",
+            arguments: { name: "bad-impact", pillarId: aTheme, impact: 7 },
+          },
+        }),
+      pass: (r) => r?.result?.isError === true,
+    },
+    {
+      name: "propose_capability (valid args, no service key) errors cleanly",
+      fn: () =>
+        handle({
+          id: 14,
+          method: "tools/call",
+          params: {
+            name: "propose_capability",
+            arguments: {
+              name: "Selftest capability example",
+              pillarId: aTheme,
+              outcome:
+                "Selftest metric moves from 0 to 10 by 2026-12-31, measured by selftest_event.",
+            },
+          },
+        }),
+      pass: (r) =>
+        process.env.SUPABASE_SERVICE_ROLE_KEY
+          ? r?.result && !r.result.isError
+          : r?.result?.isError === true,
+    },
+    {
+      name: "propose_capability (empty outcome rejected by validator)",
+      fn: () =>
+        handle({
+          id: 15,
+          method: "tools/call",
+          params: {
+            name: "propose_capability",
+            arguments: {
+              name: "Selftest capability example",
+              pillarId: aTheme,
+              outcome: "",
+            },
+          },
+        }),
+      pass: (r) => r?.result?.isError === true,
+    },
+    {
+      name: "propose_capability (non-falsifiable outcome rejected)",
+      fn: () =>
+        handle({
+          id: 16,
+          method: "tools/call",
+          params: {
+            name: "propose_capability",
+            arguments: {
+              name: "Selftest capability example",
+              pillarId: aTheme,
+              outcome: "Make the thing better.",
+            },
+          },
+        }),
+      pass: (r) => r?.result?.isError === true,
+    },
+    {
+      // Regression guard for the over-lax month-name match. Outcome
+      // contains a digit ("50%") but no real date — just the verb
+      // "may". Should be rejected, not pass via the month branch.
+      name: "propose_capability (bare month name without a digit-after rejected)",
+      fn: () =>
+        handle({
+          id: 161,
+          method: "tools/call",
+          params: {
+            name: "propose_capability",
+            arguments: {
+              name: "Selftest capability example",
+              pillarId: aTheme,
+              outcome: "We may improve activation from 30% to 50% if all goes well.",
+            },
+          },
+        }),
+      pass: (r) => r?.result?.isError === true,
+    },
+    {
+      name: "propose_capability (confidence 100 rejected by validator)",
+      fn: () =>
+        handle({
+          id: 17,
+          method: "tools/call",
+          params: {
+            name: "propose_capability",
+            arguments: {
+              name: "Selftest capability example",
+              pillarId: aTheme,
+              outcome: "Metric moves from 0 to 5 by 2026-09-30, measured by event.",
+              confidence: 100,
+            },
+          },
+        }),
+      pass: (r) => r?.result?.isError === true,
+    },
+    {
+      name: "propose_capability dryRun returns wouldCreate without writing",
+      fn: () =>
+        handle({
+          id: 18,
+          method: "tools/call",
+          params: {
+            name: "propose_capability",
+            arguments: {
+              name: "Selftest dry run capability",
+              pillarId: aTheme,
+              outcome:
+                "Metric moves from 0 to 5 by 2026-09-30, measured by event.",
+              dryRun: true,
+            },
+          },
+        }),
+      // dryRun: works regardless of whether service key is set
+      pass: (r) =>
+        !r?.result?.isError &&
+        r?.result?.content?.[0]?.text?.includes('"dryRun": true'),
+    },
+    {
+      name: "suggest_capability_for (returns matches sorted by score)",
+      fn: () =>
+        handle({
+          id: 19,
+          method: "tools/call",
+          params: {
+            name: "suggest_capability_for",
+            arguments: { description: "example capability" },
+          },
+        }),
+      pass: (r) =>
+        !r?.result?.isError &&
+        r?.result?.content?.[0]?.text?.includes('"matches"'),
+    },
+    {
+      name: "suggest_capability_for (empty description rejected)",
+      fn: () =>
+        handle({
+          id: 20,
+          method: "tools/call",
+          params: {
+            name: "suggest_capability_for",
+            arguments: { description: "" },
+          },
+        }),
+      pass: (r) => r?.result?.isError === true,
+    },
+    {
+      // suggest_theme_for is the theme-level mirror — same shape,
+      // returns ranked matches against an arbitrary description.
+      name: "suggest_theme_for (returns matches sorted by score)",
+      fn: () =>
+        handle({
+          id: 30,
+          method: "tools/call",
+          params: {
+            name: "suggest_theme_for",
+            arguments: { description: "example theme" },
+          },
+        }),
+      pass: (r) =>
+        !r?.result?.isError &&
+        r?.result?.content?.[0]?.text?.includes('"matches"'),
+    },
+    {
+      name: "suggest_theme_for (empty description rejected)",
+      fn: () =>
+        handle({
+          id: 31,
+          method: "tools/call",
+          params: {
+            name: "suggest_theme_for",
+            arguments: { description: "" },
+          },
+        }),
+      pass: (r) => r?.result?.isError === true,
+    },
+    {
+      // suggest_theme_for satisfies the propose_theme discovery
+      // gate the same way suggest_capability_for satisfies the
+      // propose_capability gate. After the call, themesListedAt
+      // should be populated.
+      name: "suggest_theme_for satisfies propose_theme discovery gate",
+      fn: async () => {
+        resetSession();
+        session.rubricFetchedAt = Date.now();
+        await handle({
+          id: 32,
+          method: "tools/call",
+          params: {
+            name: "suggest_theme_for",
+            arguments: { description: "any" },
+          },
+        });
+        return { themesListedAt: session.themesListedAt };
+      },
+      pass: (r) => r?.themesListedAt !== null,
+    },
+    {
+      name: "link_pr (unknown task rejected)",
+      fn: () =>
+        handle({
+          id: 21,
+          method: "tools/call",
+          params: {
+            name: "link_pr",
+            arguments: { taskId: "TK-NOPE", repo: "x/y", number: 1 },
+          },
+        }),
+      pass: (r) => r?.result?.isError === true,
+    },
+    {
+      name: "link_pr (valid args, no service key errors cleanly)",
+      fn: () =>
+        handle({
+          id: 22,
+          method: "tools/call",
+          params: {
+            name: "link_pr",
+            arguments: { taskId: aTask, repo: "x/y", number: 1 },
+          },
+        }),
+      pass: (r) =>
+        process.env.SUPABASE_SERVICE_ROLE_KEY
+          ? r?.result && !r.result.isError
+          : r?.result?.isError === true,
+    },
+    {
+      // Reason is required on archive/unarchive — empty reason
+      // must return an error result regardless of service-key
+      // availability.
+      name: "archive_task (missing reason returns error result)",
+      fn: () =>
+        handle({
+          id: 23,
+          method: "tools/call",
+          params: {
+            name: "archive_task",
+            arguments: { taskId: aTask, reason: "" },
+          },
+        }),
+      pass: (r) => r?.result?.isError === true,
+    },
+    {
+      name: "archive_capability (missing reason returns error result)",
+      fn: () =>
+        handle({
+          id: 24,
+          method: "tools/call",
+          params: {
+            name: "archive_capability",
+            arguments: { capabilityId: aCap, reason: " " },
+          },
+        }),
+      pass: (r) => r?.result?.isError === true,
+    },
+    {
+      name: "unarchive_theme (missing themeId returns error result)",
+      fn: () =>
+        handle({
+          id: 25,
+          method: "tools/call",
+          params: { name: "unarchive_theme", arguments: { reason: "x" } },
+        }),
+      pass: (r) => r?.result?.isError === true,
+    },
+    {
+      // Move validation: missing newCapabilityId must error out.
+      name: "move_task (missing newCapabilityId returns error result)",
+      fn: () =>
+        handle({
+          id: 26,
+          method: "tools/call",
+          params: {
+            name: "move_task",
+            arguments: { taskId: aTask, reason: "reorg" },
+          },
+        }),
+      pass: (r) => r?.result?.isError === true,
+    },
+    {
+      name: "move_capability (missing reason returns error result)",
+      fn: () =>
+        handle({
+          id: 27,
+          method: "tools/call",
+          params: {
+            name: "move_capability",
+            arguments: { capabilityId: aCap, newThemeId: aTheme, reason: "" },
+          },
+        }),
+      pass: (r) => r?.result?.isError === true,
+    },
+    {
+      // Bulk shape: oversize batch rejected pre-flight, doesn't call SQL.
+      name: "move_tasks (over 100-item cap returns error result)",
+      fn: () => {
+        const moves = Array.from({ length: 101 }, (_, i) => ({
+          taskId: `TK-${String(i).padStart(6, "0")}`,
+          newCapabilityId: aCap,
+        }));
+        return handle({
+          id: 28,
+          method: "tools/call",
+          params: { name: "move_tasks", arguments: { moves, reason: "reorg" } },
+        });
+      },
+      pass: (r) => r?.result?.isError === true,
+    },
+    {
+      name: "move_capabilities (empty moves returns error result)",
+      fn: () =>
+        handle({
+          id: 29,
+          method: "tools/call",
+          params: {
+            name: "move_capabilities",
+            arguments: { moves: [], reason: "reorg" },
+          },
+        }),
+      pass: (r) => r?.result?.isError === true,
+    },
+    {
+      // Schema-level: tools/list must advertise the four move tools.
+      name: "tools/list advertises four move tools",
+      fn: () => handle({ id: 30, method: "tools/list", params: {} }),
+      pass: (r) => {
+        const names = (r?.result?.tools ?? []).map((t) => t.name);
+        return ["move_task", "move_capability", "move_tasks", "move_capabilities"].every((n) =>
+          names.includes(n)
+        );
+      },
+    },
+    {
+      // Update validation: missing patch.
+      name: "update_task (missing patch returns error result)",
+      fn: () =>
+        handle({
+          id: 31,
+          method: "tools/call",
+          params: { name: "update_task", arguments: { taskId: aTask, reason: "r" } },
+        }),
+      pass: (r) => r?.result?.isError === true,
+    },
+    {
+      // Update validation: empty patch.
+      name: "update_capability (empty patch returns error result)",
+      fn: () =>
+        handle({
+          id: 32,
+          method: "tools/call",
+          params: {
+            name: "update_capability",
+            arguments: { capabilityId: aCap, patch: {}, reason: "r" },
+          },
+        }),
+      pass: (r) => r?.result?.isError === true,
+    },
+    {
+      // UP3: invalid status rejected client-side before SQL.
+      name: "update_task (invalid status rejected by validator)",
+      fn: () =>
+        handle({
+          id: 33,
+          method: "tools/call",
+          params: {
+            name: "update_task",
+            arguments: {
+              taskId: aTask,
+              patch: { status: "shipped" },
+              reason: "advance",
+            },
+          },
+        }),
+      pass: (r) => {
+        const txt = r?.result?.content?.[0]?.text ?? "";
+        return r?.result?.isError === true && txt.includes("invalid status");
+      },
+    },
+    {
+      // UP3: invalid confidence (>95) rejected by validator.
+      name: "update_capability (confidence 99 rejected by validator)",
+      fn: () =>
+        handle({
+          id: 34,
+          method: "tools/call",
+          params: {
+            name: "update_capability",
+            arguments: {
+              capabilityId: aCap,
+              patch: { confidence: 99 },
+              reason: "bump",
+            },
+          },
+        }),
+      pass: (r) => r?.result?.isError === true,
+    },
+    {
+      // Schema-level: parent fields are blocked at JSON-schema layer
+      // (additionalProperties:false on patch). Without service key
+      // we won't reach SQL, but the schema rejects it pre-call.
+      name: "tools/list advertises three update tools",
+      fn: () => handle({ id: 35, method: "tools/list", params: {} }),
+      pass: (r) => {
+        const names = (r?.result?.tools ?? []).map((t) => t.name);
+        return ["update_task", "update_capability", "update_theme"].every((n) =>
+          names.includes(n)
+        );
+      },
+    },
+    {
+      // Cross-workspace guard fires when snapshot.json names workspace
+      // A and a mutator call carries workspaceId=B. Cleanup is in
+      // finally so a thrown handle() doesn't leave the cache pinned.
+      name: "cross-workspace write refused when snapshot conflicts with arg",
+      fn: async () => {
+        try {
+          __setSnapshotWorkspaceForTest("ws-cwd");
+          return await handle({
+            id: 36,
+            method: "tools/call",
+            params: {
+              name: "archive_task",
+              arguments: {
+                taskId: aTask,
+                reason: "cross-workspace probe",
+                workspaceId: "ws-other",
+              },
+            },
+          });
+        } finally {
+          __setSnapshotWorkspaceForTest(undefined);
+        }
+      },
+      pass: (r) => {
+        if (!r?.result?.isError) return false;
+        const txt = r.result.content?.[0]?.text ?? "";
+        return (
+          txt.includes("Refusing cross-workspace") &&
+          txt.includes("ws-cwd") &&
+          txt.includes("ws-other")
+        );
+      },
+    },
+    {
+      // Matching workspaceId arg — guard passes, call continues. The
+      // tool reaches archiveLifecycle / rpcCall which fails with the
+      // missing-service-key error (or in selftest mode without env,
+      // some other downstream error). The key assertion: NOT the
+      // cross-workspace refusal — proves guard ran and let through.
+      name: "matching workspaceId arg passes the cross-workspace guard",
+      fn: async () => {
+        try {
+          __setSnapshotWorkspaceForTest("ws-cwd");
+          return await handle({
+            id: 37,
+            method: "tools/call",
+            params: {
+              name: "archive_task",
+              arguments: {
+                taskId: aTask,
+                reason: "same-workspace probe",
+                workspaceId: "ws-cwd",
+              },
+            },
+          });
+        } finally {
+          __setSnapshotWorkspaceForTest(undefined);
+        }
+      },
+      pass: (r) => {
+        // Must be an error result (no service key) but specifically
+        // NOT the cross-workspace refusal. The two non-cross-workspace
+        // errors we can land on are the missing-service-key error or
+        // a workspace-resolution error — both prove the guard
+        // accepted and the request reached downstream code.
+        if (!r?.result?.isError) return false;
+        const txt = r.result.content?.[0]?.text ?? "";
+        if (txt.includes("Refusing cross-workspace")) return false;
+        return (
+          txt.includes("SUPABASE_SERVICE_ROLE_KEY") ||
+          txt.includes("workspaceId could not be resolved") ||
+          txt.includes("Write tools require")
+        );
+      },
+    },
+    {
+      // record_outcome_reading rejects missing value.
+      name: "record_outcome_reading (missing value returns error result)",
+      fn: () =>
+        handle({
+          id: 39,
+          method: "tools/call",
+          params: {
+            name: "record_outcome_reading",
+            arguments: { capabilityId: aCap, asOf: "2026-05-12", source: "test" },
+          },
+        }),
+      pass: (r) => r?.result?.isError === true,
+    },
+    {
+      // record_outcome_reading rejects missing source.
+      name: "record_outcome_reading (missing source returns error result)",
+      fn: () =>
+        handle({
+          id: 40,
+          method: "tools/call",
+          params: {
+            name: "record_outcome_reading",
+            arguments: { capabilityId: aCap, value: 0.5, asOf: "2026-05-12" },
+          },
+        }),
+      pass: (r) => r?.result?.isError === true,
+    },
+    {
+      // list_stale_outcomes is a read tool — should return without
+      // service-role and surface a count field.
+      name: "list_stale_outcomes returns a structured stale list",
+      fn: () =>
+        handle({
+          id: 41,
+          method: "tools/call",
+          params: { name: "list_stale_outcomes", arguments: {} },
+        }),
+      pass: (r) => {
+        if (r?.result?.isError) return false;
+        const txt = r?.result?.content?.[0]?.text ?? "";
+        try {
+          const parsed = JSON.parse(txt);
+          return (
+            typeof parsed.thresholdDays === "number" &&
+            typeof parsed.count === "number" &&
+            Array.isArray(parsed.stale)
+          );
+        } catch {
+          return false;
+        }
+      },
+    },
+    {
+      // ROADMAPPER_ALLOW_CROSS_WORKSPACE=1 disables the guard. Env
+      // cleanup in finally so a thrown handle() doesn't leak the
+      // permissive flag into subsequent tests.
+      name: "ROADMAPPER_ALLOW_CROSS_WORKSPACE=1 disables the cross-workspace guard",
+      fn: async () => {
+        try {
+          __setSnapshotWorkspaceForTest("ws-cwd");
+          process.env.ROADMAPPER_ALLOW_CROSS_WORKSPACE = "1";
+          return await handle({
+            id: 38,
+            method: "tools/call",
+            params: {
+              name: "archive_task",
+              arguments: {
+                taskId: aTask,
+                reason: "override probe",
+                workspaceId: "ws-other",
+              },
+            },
+          });
+        } finally {
+          __setSnapshotWorkspaceForTest(undefined);
+          delete process.env.ROADMAPPER_ALLOW_CROSS_WORKSPACE;
+        }
+      },
+      pass: (r) => {
+        const txt = r?.result?.content?.[0]?.text ?? "";
+        return !txt.includes("Refusing cross-workspace");
+      },
+    },
+  ];
+
+  let passed = 0;
+  for (const c of checks) {
+    let ok = false;
+    let err = null;
+    try {
+      const r = await c.fn();
+      ok = !!c.pass(r);
+    } catch (e) {
+      err = e.message;
+    }
+    const mark = ok ? "PASS" : "FAIL";
+    log(`${mark}  ${c.name}${err ? "  — " + err : ""}`);
+    if (ok) passed++;
+  }
+  log(`---`);
+  log(`${passed}/${checks.length} checks passed.`);
+  if (passed === checks.length) {
+    log("");
+    log("Server is healthy. If your MCP client doesn't see the");
+    log("roadmapper tools after this passes, the client almost");
+    log("certainly needs a full process restart — MCP servers are");
+    log("connected at client startup. For Claude Code:");
+    log("  /exit  → relaunch `claude` → /mcp to verify");
+  }
+  process.exit(passed === checks.length ? 0 : 1);
+}
+
+if (process.argv.includes("--selftest")) {
+  runSelftest();
+} else {
+  let buf = "";
+  process.stdin.setEncoding("utf-8");
+  process.stdin.on("data", async (chunk) => {
+    buf += chunk;
+    let nl;
+    while ((nl = buf.indexOf("\n")) >= 0) {
+      const line = buf.slice(0, nl).trim();
+      buf = buf.slice(nl + 1);
+      if (!line) continue;
+      let msg;
+      try {
+        msg = JSON.parse(line);
+      } catch {
+        log("bad json", line.slice(0, 200));
+        continue;
+      }
+      const response = await handle(msg);
+      if (response) send(response);
+    }
+  });
+
+  process.stdin.on("end", () => process.exit(0));
+  const { url, readKey: rk, writeKey } = supabaseConfig();
+  const mode = url && rk
+    ? writeKey
+      ? "supabase (rw)"
+      : "supabase (ro)"
+    : "seed-only";
+
+  // Boot-time snapshot of the roadmap shape — gives the operator a
+  // fast sanity check that the MCP can read the right workspace.
+  // Errors here are swallowed so a flaky network doesn't keep the
+  // server from booting.
+  (async () => {
+    let stats = null;
+    try {
+      const projected =
+        (await readWorkspaceProjected()) ?? project(readSeed(), {});
+      stats = {
+        themes: projected.themes.length,
+        capabilities: projected.capabilities.length,
+        openTasks: projected.tasks.filter((t) => t.status !== "delivered").length,
+      };
+    } catch (e) {
+      log("ready-snapshot errored:", e.message);
+    }
+    const tail = stats
+      ? `, ${stats.themes} themes, ${stats.capabilities} capabilities, ${stats.openTasks} open tasks`
+      : "";
+    const snap = snapshotWorkspaceId();
+    const snapTail = snap ? `, snapshot-workspace=${snap}` : "";
+    log(`ready (mode=${mode}${tail}${snapTail})`);
+  })();
+}