@roadmapperai/mcp 0.9.3 → 0.9.5

package/server.mjs

@@ -326,6 +326,13 @@ async function fetchWorkspaceEntitiesViaBroker() {
       pillars: Array.isArray(parsed.pillars) ? parsed.pillars : [],
       capabilities: Array.isArray(parsed.capabilities) ? parsed.capabilities : [],
       tasks: Array.isArray(parsed.tasks) ? parsed.tasks : [],
+      // Additive (migration 0108): the workspace_settings row, used to
+      // resolve agent_theme_autonomy. Absent on older backends → null,
+      // which the projection treats as "all defaults" (autonomy on).
+      settings:
+        parsed.settings && typeof parsed.settings === "object"
+          ? parsed.settings
+          : null,
     };
   } catch {
     return null;
@@ -462,6 +469,75 @@ function tplDescription(text, labels) {
   return out;
 }
 
+/**
+ * The full tool descriptions below carry the planning methodology
+ * (USE WHEN / PREREQUISITE / ANTI-PATTERN / EXAMPLE) inline. That prose
+ * is relocated to the server `instructions` field — sent once at connect —
+ * plus the roadmapper://rubric resource, so the per-tool wire payload is
+ * just the one-line summary: the segment before the first blank line.
+ *
+ * Why: the 34 full descriptions cost ~15k tokens in every tools/list, in
+ * every session, used or not. The summaries cost ~3-4k. The methodology
+ * isn't lost — it moves to `instructions` (always sent, deduped) and the
+ * rubric resource (on demand), and the contract is still enforced server
+ * side (rubric/discovery gates + validateOutcome/validateName/etc. return
+ * structured `fix` errors). inputSchema, including every per-field
+ * description, is untouched — callers keep full argument-level guidance.
+ */
+function summaryOf(description) {
+  const i = description.indexOf("\n\n");
+  return i === -1 ? description : description.slice(0, i);
+}
+
+/**
+ * The minimal planning contract an agent needs to file a VALID proposal,
+ * sent once in the initialize `instructions` field. This is the CORE
+ * extract of AGENTS.md (~600 tokens vs the full ~12.5k doc): the gate
+ * sequence, the task/capability shapes, the server-enforced falsifiable
+ * outcome + confidence rules, the enums, IDs, and don'ts. The full doc
+ * (tool catalogue, PR/branch conventions, RICE narrative, GitHub wiring)
+ * stays on demand via get_agents_md / roadmapper://rubric — reading
+ * either also satisfies the rubric gate. Keep this in sync with AGENTS.md
+ * sections: TL;DR, The mental model, Required agent task, Required
+ * capability fields, Outcome statements, Impact/Confidence, ID
+ * conventions, Don'ts.
+ */
+const CORE_CONTRACT = `ROADMAPPER PLANNING CONTRACT (essentials — full version: the get_agents_md op, or read the roadmapper://rubric resource)
+
+ACCESS — every operation runs through ONE tool
+roadmap({ op, args }) executes an operation. roadmap_search(intent) lists/ranks the operations; roadmap_describe(op) returns an op's exact arguments. The op names used below (get_roadmap_snapshot, suggest_capability_for, propose_task, get_agents_md, ...) are values for op — e.g. roadmap({ op: "get_agents_md" }) or roadmap({ op: "propose_task", args: { capabilityId, title, effort } }).
+
+PER-SESSION WORKFLOW
+1. Orient first: get_roadmap_snapshot (or list_themes / list_capabilities). This also satisfies the discovery gates below.
+2. Writing requires the rubric: every workspace-mutating tool (propose_*/update_*/archive_*/unarchive_*/move_*/record_outcome_reading/link_pr/submit_acceptance_grades) refuses until you call get_agents_md once this session (reading roadmapper://rubric also counts).
+3. Reuse before creating: suggest_capability_for({description}) to find an existing home; only propose a new capability if nothing fits. suggest_theme_for / list_themes before proposing a theme.
+4. Before your first write, call get_active_workspace and proceed only if its status is "resolved"; for any other status follow the \`next\` action it returns (e.g. link_repo) so writes don't land in the wrong workspace.
+5. dryRun:true validates any write without committing. Reference everything by stable ID, never by name.
+
+MODEL (don't conflate the layers)
+Theme (TH-NNNNNN · leadership · years) > Capability (CAP-XXXXXX · PM · quarters · a falsifiable bet) > Task (TK-NNNNNN · IC/agent · days) > PR (closes tasks). Sprints (SP-NNN) are 1-2 week buckets.
+
+TASK fields
+Required: capabilityId, title (>=5 chars), effort: XS|S|M|L|XL (XS=2h S=4h M=1d L=3d XL=8d).
+Recommended (not enforced): kind: feature|bug|chore|spike, priority: P0|P1|P2|P3, acceptance: [checkable assertions], dependsOn: [TK-...].
+Give any task an agent will pick up a non-empty acceptance list — an empty list is a stop signal (spike it or ask). Stamp authorKind:agent. Only set dependsOn when one task truly blocks another.
+
+CAPABILITY fields
+Required: name (>=8 chars), pillarId: TH-..., outcome (falsifiable — see below).
+Optional (defaulted): reach: number >=0 (default 100), impact: 3|2|1|0.5|0.25 (default 1), confidence: 0-95 (default 70), specRef (spec link; supply before decomposing a capability into tasks so scope is pinned — convention, not enforced).
+
+FALSIFIABLE OUTCOME (server-enforced — propose_capability rejects otherwise)
+Template: <metric> moves from <baseline> to <target> by <date>, measured by <source>.
+The outcome MUST contain both a number AND a temporal anchor. Use a 20XX year (e.g. 2026-09-30 or "Sep 2026") or a quarter (Q3, q1 2026) — a bare month name or "by <month>" is NOT accepted, so always include the year. Confidence: 100 is never accepted (server caps at 95); reserve 91-95 for work already shipped or behind a flag.
+Good: "Activation rate moves from 32% to 55% by 2026-09-30, measured by the activated_user event."
+Weak: "Improve builder UX" (no metric/baseline/date — rewrite, or file it as a task).
+
+WHEN NOT TO CREATE A CAPABILITY
+A one-off fix, infra under an existing bet, a refactor/rename, or anything that fits in one PR is a TASK under the existing capability — not a new bet. If you can't write a falsifiable outcome, it isn't a capability yet.
+
+DON'TS
+No capability-per-PR. No blank outcomes. Don't game RICE inputs. Don't edit theme IDs after creation. Don't self-promote a task to delivered — wait for the merged PR.`;
+
 /**
  * Resolve a config value from a primary `ROADMAPPER_*` env var,
  * falling back to a legacy `SUPABASE_*` alias when the primary
@@ -853,6 +929,7 @@ async function readWorkspaceProjected(wsIdOverride) {
         themes: ent.pillars.map(rowToThemeProjected),
         capabilities: ent.capabilities.map(rowToCapabilityProjected),
         tasks: ent.tasks.map(rowToTaskProjected),
+        settings: rowToSettingsProjected(ent.settings),
       };
     }
     // Broker failed — fall through to the direct read below. On a pure
@@ -876,15 +953,22 @@ async function readWorkspaceProjected(wsIdOverride) {
     return res.json();
   };
   try {
-    const [pillars, caps, tasks] = await Promise.all([
+    const [pillars, caps, tasks, settingsRows] = await Promise.all([
       fetchTable("pillars?select=*"),
       fetchTable("capabilities?select=*"),
       fetchTable("tasks?select=*"),
+      // Operator path: workspace_settings is one row per workspace.
+      // Tolerate the table not existing on an older DB (404) — fall
+      // back to defaults rather than failing the whole read.
+      fetchTable("workspace_settings?select=*").catch(() => []),
     ]);
     return {
       themes: pillars.map(rowToThemeProjected),
       capabilities: caps.map(rowToCapabilityProjected),
       tasks: tasks.map(rowToTaskProjected),
+      settings: rowToSettingsProjected(
+        Array.isArray(settingsRows) ? settingsRows[0] : settingsRows
+      ),
     };
   } catch (e) {
     log("supabase entity read failed:", e.message);
@@ -896,6 +980,20 @@ async function readWorkspaceProjected(wsIdOverride) {
  *  the same camelCase keys the SPA + agent surfaces have always
  *  used; the legacy JSONB shape and these table rows agree on
  *  every field. */
+/**
+ * Project a workspace_settings row to the camelCase shape the server
+ * reads. Tolerant of null / {} (no row yet, or an older backend that
+ * doesn't return settings): every flag falls back to its product
+ * default. agent_theme_autonomy defaults TRUE — agents create themes
+ * autonomously unless a workspace explicitly turns it off.
+ */
+function rowToSettingsProjected(r) {
+  const row = r && typeof r === "object" ? r : {};
+  return {
+    // Default true: missing column / row / backend all mean "on".
+    agentThemeAutonomy: row.agent_theme_autonomy !== false,
+  };
+}
 function rowToThemeProjected(r) {
   return stripUndefined({
     id: r.id,
@@ -1311,7 +1409,7 @@ function validateOutcome(outcome) {
       !hasTemporal ? "date/quarter" : null,
     ]
       .filter(Boolean)
-      .join(" + ")}. See get_agents_md for examples.`;
+      .join(" + ")}. See ${opCall("get_agents_md")} for examples.`;
   }
   return null;
 }
@@ -1396,6 +1494,27 @@ function jaccardScore(a, b) {
   return overlap / Math.max(a.size, b.size);
 }
 
+// ── Theme sprawl control ──────────────────────────────────────────
+//
+// With agent_theme_autonomy ON (the default), the old "stop and ask a
+// human before any new theme" guard is gone — so the sprawl guard has
+// to live server-side instead. A proposed theme whose name+description
+// overlaps an existing active theme at or above this bar is almost
+// certainly a near-duplicate ("Data Intelligence" vs "Data &
+// Intelligence"); propose_theme refuses it and points at the match so
+// the agent reuses/updates that theme instead of minting a sibling.
+// Set deliberately high: themes are coarse, so only a strong overlap
+// is a real duplicate. 0.6 blocks name-containment dups ("Data
+// Intelligence" ⊂ "Data Intelligence Platform" = 0.67) without
+// false-positiving on two distinct short themes that happen to share
+// ONE word ("Customer Loyalty" vs "Customer Retention" = 0.5 < 0.6).
+// force:true overrides for the rare legitimate case.
+const THEME_SPRAWL_BLOCK = 0.6;
+// Two existing themes overlapping at/above this are flagged as a
+// consolidation candidate by detect_theme_sprawl (lower than the block
+// bar — we want to surface drift before it's an exact dup).
+const THEME_SPRAWL_WARN = 0.34;
+
 // ── Session state + enforcement gates ─────────────────────────────
 //
 // One process serves one MCP client (stdio). State below is the
@@ -1429,6 +1548,20 @@ function resetSession() {
   session.mutatorBlocks = 0;
 }
 
+/**
+ * Format an agent-facing "next call" in the dispatch shape. After the
+ * tool-surface collapse the ONLY callable tool is `roadmap`; the 34 ops are
+ * `op` values, so a fix field of `get_agents_md()` names something a real MCP
+ * client can't invoke (it isn't in tools/list). opCall renders the reachable
+ * form `roadmap({ op: "<op>"[, args: {...}] })`. argsHint is a preformatted
+ * args literal (string) when the call needs arguments.
+ */
+function opCall(op, argsHint) {
+  return argsHint
+    ? `roadmap({ op: "${op}", args: ${argsHint} })`
+    : `roadmap({ op: "${op}" })`;
+}
+
 /**
  * Build the structured "prereq missing" result the mutators return
  * when the agent hasn't fetched the rubric this session. The shape
@@ -1445,10 +1578,10 @@ function rubricMissingResult(toolName) {
           {
             error: "prerequisite_missing",
             message:
-              `Call get_agents_md first this session, then retry ${toolName}. ` +
+              `Call ${opCall("get_agents_md")} first this session, then retry your ${toolName} call. ` +
               "The rubric defines acceptance criteria shape and grading dimensions — " +
               "proposals filed without it will not round-trip.",
-            fix: "get_agents_md()",
+            fix: opCall("get_agents_md"),
           },
           null,
           2
@@ -1473,7 +1606,7 @@ function discoveryMissingResult(toolName, fixCall, rationale) {
           {
             error: "discovery_missing",
             message:
-              `Call ${fixCall} first this session, then retry ${toolName}. ${rationale}`,
+              `Call ${fixCall} first this session, then retry your ${toolName} call. ${rationale}`,
             fix: fixCall,
           },
           null,
@@ -1485,6 +1618,88 @@ function discoveryMissingResult(toolName, fixCall, rationale) {
   };
 }
 
+/**
+ * Block result for a mutator whose target workspace fell through to the
+ * install's env default WHILE the agent is sitting in a git repo that
+ * isn't mapped to any workspace. Same shape + self-heal rationale as the
+ * rubric gate: name the exact fix so the LLM links the repo, then retries.
+ *
+ * Why this is repo-aware, not session-aware — a developer routinely has
+ * SEVERAL repos open in one chat. The gate must only fire for the specific
+ * unmapped repo, and must never brick a legitimate cross-repo write:
+ *   • An explicit `workspaceId` arg → caller is intentionally targeting a
+ *     workspace; never blocked (checked before this is reached).
+ *   • source === "repo"/"snapshot"/"arg" → already resolved to a real
+ *     mapping; this only fires on "env" (the silent install-default
+ *     fall-through), which — because resolveWorkspaceWithSource prefers a
+ *     repo_workspace_map hit — means THIS repo genuinely isn't mapped.
+ *   • No git slug (not in a repo) → nothing to link; fall through to the
+ *     env default rather than deadlock.
+ * The message offers BOTH escape hatches so a multi-repo chat is never
+ * stuck: link_repo (map this repo) OR pass workspaceId (target an existing
+ * workspace without mapping the repo at all).
+ */
+function repoUnmappedResult(toolName, slug, envWsId) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(
+          {
+            error: "repo_unmapped",
+            message:
+              `"${slug}" isn't mapped to a workspace, so ${toolName} would land on the install-default workspace "${envWsId}" — probably not what you want. ` +
+              `Map it once with ${opCall("link_repo")} (this repo → your key's workspace, resolves silently forever after), then retry your ${toolName} call. ` +
+              `Or, if you meant a specific existing workspace, pass workspaceId in the op's args and it proceeds without mapping the repo.`,
+            repo: slug,
+            envDefaultWorkspace: envWsId,
+            fix: opCall("link_repo"),
+            alt: opCall(toolName, '{ workspaceId: "<target>", ... }'),
+          },
+          null,
+          2
+        ),
+      },
+    ],
+    isError: true,
+  };
+}
+
+/**
+ * Decide whether a mutator should be blocked because the agent is in an
+ * unmapped repo and the write would silently hit the env default. Returns
+ * a block result, or null to proceed. Pure + sync (no network) so it's
+ * cheap on every mutator: the per-repo "is it mapped" question was already
+ * answered by resolveWorkspaceWithSource (a mapped repo resolves to
+ * source "repo", never "env"), so we only need the cwd's git slug here.
+ *
+ * Escape hatches, in order:
+ *   1. Explicit workspaceId arg → intentional target, allow.
+ *   2. Writes disabled → not our concern (set_credentials path handles it).
+ *   3. Source isn't "env" → already resolved to a real mapping, allow.
+ *   4. No client roots / no git slug → not in a linkable repo, allow
+ *      (fall through to env default; blocking would deadlock).
+ *   5. Bypass env var set → allow (operator opt-out).
+ */
+async function repoLinkGate(name, args, source, envWsId) {
+  if (args?.workspaceId) return null; // explicit target — never block
+  if (writeMode() === "read-only") return null; // different problem
+  if (source !== "env") return null; // resolved via repo/snapshot/arg
+  if (process.env.ROADMAPPER_ALLOW_UNMAPPED_REPO === "1") return null;
+  if (_clientRoots.length === 0) return null; // not in a repo at all
+
+  // Find the first open root with a resolvable origin slug. If none, the
+  // agent isn't in a linkable git repo — don't block (let env default win).
+  let slug = null;
+  for (const dir of _clientRoots) {
+    slug = await repoSlugForDir(dir);
+    if (slug) break;
+  }
+  if (!slug) return null;
+
+  return repoUnmappedResult(name, slug, envWsId);
+}
+
 /**
  * Telemetry write — fire-and-forget POST to public.mcp_telemetry
  * via PostgREST when a service-role key is set. Never blocks the
@@ -1768,13 +1983,70 @@ const TOOLS = [
       additionalProperties: false,
     },
   },
+  {
+    name: "propose_tasks",
+    description:
+      "Bulk-create MANY tasks under ONE capability in a single call. Token-efficient: prefer this over N separate propose_task calls when filing a plan — one request, one compact {id,title} array back instead of N round trips. When write tools are live, file directly via this tool; do NOT also paste the full JSON plan into chat (that pays for the plan twice).\n\n" +
+      "USE WHEN: decomposing a capability into its 3-8 tasks, or importing a planned backlog. All tasks share the one capabilityId.\n" +
+      "PREREQUISITE: get_agents_md once this session (enforced). The capability must already exist — propose_capability first if needed.\n" +
+      "INTRA-BATCH DEPENDENCIES: give a task a `ref` (any alias string) and reference it in another task's `dependsOn` — refs are rewritten to the real TK ids after minting. dependsOn entries that aren't a sibling ref pass through as literal existing TK ids.\n" +
+      "PARTIAL SUCCESS: a structural/validation error in any row fails the whole call before writing (fix the batch). Once validated, per-row RPC failures are reported in tasks[].error without sinking the rest.\n" +
+      "ANTI-PATTERN: don't use for a single task (use propose_task); don't spread one capability's tasks across multiple capabilities (call once per capability).\n" +
+      "EXAMPLE: propose_tasks({ capabilityId: 'CAP-018', tasks: [{ ref: 'a', title: 'Schema + migration', effort: 'M' }, { title: 'API endpoint', effort: 'M', dependsOn: ['a'] }] })\n\n" +
+      "Requires write auth (set ROADMAPPER_API_KEY). Pass dryRun:true to validate + preview ids without writing. Pass workspaceId to target a workspace other than the env default.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        capabilityId: { type: "string" },
+        tasks: {
+          type: "array",
+          minItems: 1,
+          maxItems: 100,
+          description: "Task specs. Each needs title + effort; everything else is optional.",
+          items: {
+            type: "object",
+            properties: {
+              ref: {
+                type: "string",
+                description:
+                  "Optional caller alias for intra-batch dependsOn references. Not stored.",
+              },
+              title: { type: "string" },
+              summary: { type: "string" },
+              effort: { type: "string", enum: ["XS", "S", "M", "L", "XL"] },
+              kind: { type: "string", enum: ["feature", "bug", "chore", "spike"] },
+              priority: { type: "string", enum: ["P0", "P1", "P2", "P3"] },
+              acceptance: { type: "array", items: { type: "string" } },
+              dependsOn: {
+                type: "array",
+                items: { type: "string" },
+                description:
+                  "Sibling refs (rewritten to real ids) and/or existing TK-NNNNNN ids.",
+              },
+              owner: { type: "string" },
+              expectedPRs: { type: "number" },
+              expectedScope: { type: "number" },
+              idempotencyKey: { type: "string" },
+            },
+            required: ["title", "effort"],
+            additionalProperties: false,
+          },
+        },
+        dryRun: { type: "boolean" },
+        workspaceId: { type: "string" },
+      },
+      required: ["capabilityId", "tasks"],
+      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" +
+      "Propose a new strategic theme (pillar). Themes are years-stable, coarse pillars — the small top tier of the tree.\n\n" +
+      "AUTONOMY: by default (agent_theme_autonomy ON) you may create a theme without human confirmation when the work genuinely needs a new pillar. The server controls sprawl for you — it REFUSES a near-duplicate of an existing theme (returns error:\"too_similar\" naming the match) so you reuse/update that one instead. If a workspace turned autonomy OFF, propose_theme returns error:\"confirmation_required\" until you surface the theme to the user and retry with confirm:true.\n" +
+      "USE WHEN: the work doesn't fit any existing theme AND represents a distinct multi-year strategic direction. Most planning needs a capability under an existing theme, not a new theme.\n" +
+      "PREREQUISITE: get_agents_md once this session (enforced). Theme discovery once this session, satisfied by suggest_theme_for (preferred — returns ranked matches), list_themes, or get_roadmap_snapshot (enforced — discovery_missing with a fix field otherwise).\n" +
+      "ANTI-PATTERN: do not call to organize a quarter of work — that's a capability. Do not retry with force:true to bypass a too_similar block unless the overlap is a genuine false positive — that's the sprawl guard working.\n" +
       "EXAMPLE: propose_theme({ name: 'AI Agent Reliability', description: 'Multi-year bet on making agent workflows reproducible.', targetRoi: 20000000, idempotencyKey: 'session-1-theme-1' })\n\n" +
       "Requires write auth (set ROADMAPPER_API_KEY). targetRoi is RAW ANNUAL DOLLARS (e.g. 20000000 = $20M), not millions. 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: {
@@ -1784,6 +2056,16 @@ const TOOLS = [
         description: { type: "string" },
         color: { type: "string" },
         targetRoi: { type: "number", description: "Annual ROI target in raw dollars (e.g. 20000000 = $20M)." },
+        force: {
+          type: "boolean",
+          description:
+            "Override the too_similar sprawl block. Use ONLY when a flagged overlap with an existing theme is a genuine false positive and this is truly a distinct strategic pillar.",
+        },
+        confirm: {
+          type: "boolean",
+          description:
+            "Set true to proceed when the workspace has agent theme-autonomy turned OFF — your attestation that the user explicitly approved this new theme. Ignored when autonomy is on (the default).",
+        },
         idempotencyKey: { type: "string" },
         dryRun: { type: "boolean" },
         workspaceId: { type: "string" },
@@ -1810,7 +2092,7 @@ const TOOLS = [
         outcome: { type: "string" },
         reach: { type: "number" },
         impact: { type: "number", enum: [3, 2, 1, 0.5, 0.25] },
-        confidence: { type: "number", minimum: 0, maximum: 100 },
+        confidence: { type: "number", minimum: 0, maximum: 95 },
         roi: { type: "number", description: "Estimated annual ROI in raw dollars (e.g. 2500000 = $2.5M)." },
         specRef: { type: "string" },
         idempotencyKey: { type: "string" },
@@ -1841,7 +2123,11 @@ const TOOLS = [
             properties: {
               index: { type: "integer", minimum: 0 },
               status: { type: "string", enum: ["pass", "fail"] },
-              note: { type: "string" },
+              note: {
+                type: "string",
+                description:
+                  "Required when status=fail — the failure mode the reviewer needs. Call this before opening the PR.",
+              },
             },
             required: ["index", "status"],
             additionalProperties: false,
@@ -2019,6 +2305,31 @@ const TOOLS = [
       additionalProperties: false,
     },
   },
+  {
+    name: "detect_theme_sprawl",
+    description:
+      "Find pairs/clusters of EXISTING themes that overlap enough to be candidates for consolidation — the 'we have too many near-duplicate pillars' signal. The companion to agent_theme_autonomy: autonomy lets agents create themes freely, this is how you periodically detect and clean up the drift.\n\n" +
+      "How it works: scores every active theme against every other by name+description token overlap, and reports pairs at or above the warn threshold (default 0.34). Each pair comes with the overlap score and a suggested action (merge via move_capabilities + archive_theme).\n" +
+      "USE WHEN: quarterly review, or any time the theme list feels bloated. With autonomy on, run this occasionally to catch sibling themes that should be one.\n" +
+      "PREREQUISITE: none — read-only. Enumerates every theme, so it satisfies the propose_theme discovery gate.\n" +
+      "ANTI-PATTERN: don't auto-merge on a single weak overlap — a human owns theme structure. Tune threshold rather than acting on noise. Two themes CAN legitimately share vocabulary (e.g. 'Data Ingestion' vs 'Data Governance').\n" +
+      "EXAMPLE: detect_theme_sprawl({ threshold: 0.34 })",
+    inputSchema: {
+      type: "object",
+      properties: {
+        threshold: {
+          type: "number",
+          minimum: 0,
+          maximum: 1,
+          description:
+            "Min name+description Jaccard overlap between two themes to flag as a consolidation candidate. Default 0.34. Raise to surface only the most blatant duplicates.",
+        },
+        includeArchived: { type: "boolean" },
+        workspaceId: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+  },
 ];
 
 /**
@@ -2337,6 +2648,7 @@ function updateLifecycleTools() {
 /** Tools that mutate the workspace — all gated on rubric fetch. */
 const MUTATOR_TOOLS = new Set([
   "propose_task",
+  "propose_tasks",
   "propose_theme",
   "propose_capability",
   "submit_acceptance_grades",
@@ -2357,7 +2669,206 @@ const MUTATOR_TOOLS = new Set([
   "record_outcome_reading",
 ]);
 
+// --- Dispatch surface -------------------------------------------------
+// Token-efficiency collapse: instead of advertising all 34 tools (their
+// inputSchemas alone are ~5k tokens in every tools/list), the wire surface
+// is three dispatch tools. The 34 operations are routed by name through
+// callTool (see the roadmap/roadmap_search/roadmap_describe early returns),
+// and their schemas are served on demand via roadmap_describe. This keeps
+// tools/list tiny while every operation, gate, and validator is unchanged.
+const OP_NAMES = new Set(TOOLS.map((t) => t.name));
+const DISPATCH_TOOLS = new Set(["roadmap", "roadmap_search", "roadmap_describe"]);
+
+const META_TOOLS = [
+  {
+    name: "roadmap_search",
+    description:
+      "Find the right roadmap operation for what you want to do. Returns operation names with one-line summaries, ranked by your intent (or all of them if you omit intent). Then call roadmap_describe(op) for an op's arguments and roadmap({op, args}) to run it.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        intent: {
+          type: "string",
+          description:
+            "Free-text description of the task, e.g. 'file a new bet' or 'mark a task done'. Omit to list every operation.",
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "roadmap_describe",
+    description:
+      "Return the input schema and summary for one roadmap operation (op, e.g. 'propose_task'). Call before roadmap({op, args}) when you need the exact argument shape; this is the same schema the operation validates against.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        op: { type: "string", description: "Operation name to describe, e.g. propose_task." },
+      },
+      required: ["op"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "roadmap",
+    description:
+      "Execute any roadmap operation: roadmap({ op, args }). op is an operation name such as get_roadmap_snapshot, list_capabilities, suggest_capability_for, propose_task, or update_capability — discover them with roadmap_search, get their arguments with roadmap_describe. All reads, planning, and writes go through here; the server enforces the rubric/discovery gates and per-op validation. See the server instructions for the planning contract.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        op: {
+          type: "string",
+          description:
+            "Operation name, e.g. get_roadmap_snapshot, suggest_capability_for, propose_task. Call roadmap_search to discover ops.",
+        },
+        args: {
+          type: "object",
+          description:
+            "Arguments for the op (see roadmap_describe(op)). Omit for ops that take none.",
+          additionalProperties: true,
+        },
+      },
+      required: ["op"],
+      additionalProperties: false,
+    },
+  },
+];
+
+// roadmap_search: rank the 34 ops by token overlap with the intent and
+// return {op, summary} rows. Summaries are the trimmed first line, run
+// through the same label substitution tool descriptions get, so custom
+// workspace labels (theme -> initiative) stay consistent.
+function roadmapSearchResult(intent) {
+  const labels = currentLabels();
+  const ops = TOOLS.map((t) => ({
+    op: t.name,
+    summary: tplDescription(summaryOf(t.description), labels),
+  }));
+  const q = (intent || "").toLowerCase().trim();
+  let operations = ops;
+  if (q) {
+    const terms = q.split(/[^a-z0-9]+/).filter((w) => w.length > 2);
+    if (terms.length) {
+      const score = (o) => {
+        const hay = (o.op + " " + o.summary).toLowerCase();
+        return terms.reduce((n, w) => n + (hay.includes(w) ? 1 : 0), 0);
+      };
+      operations = ops
+        .map((o) => ({ o, s: score(o) }))
+        .sort((a, b) => b.s - a.s)
+        .map((x) => x.o);
+    }
+  }
+  return textResult(
+    JSON.stringify(
+      {
+        intent: intent || null,
+        note: "Call roadmap_describe({ op }) for an op's arguments, then roadmap({ op, args }) to run it.",
+        total: operations.length,
+        operations,
+      },
+      null,
+      2
+    )
+  );
+}
+
+// roadmap_describe: serve one op's inputSchema (the bulk that was evicted
+// from tools/list) plus its trimmed summary, on demand.
+function roadmapDescribeResult(op) {
+  if (typeof op !== "string" || !op) {
+    return errorResult(
+      "roadmap_describe requires an 'op' string, e.g. roadmap_describe({ op: 'propose_task' })."
+    );
+  }
+  const t = TOOLS.find((x) => x.name === op);
+  if (!t) {
+    return errorResult(
+      `Unknown op '${op}'. Call roadmap_search to list operations.`
+    );
+  }
+  return textResult(
+    JSON.stringify(
+      {
+        op: t.name,
+        summary: tplDescription(summaryOf(t.description), currentLabels()),
+        inputSchema: t.inputSchema,
+      },
+      null,
+      2
+    )
+  );
+}
+
 async function callTool(name, args) {
+  // Dispatch surface. roadmap_search / roadmap_describe answer here without
+  // touching the workspace. roadmap({op, args}) re-enters callTool(op, args)
+  // so the operation runs through the IDENTICAL pipeline below — workspace
+  // resolution, the MUTATOR_TOOLS gates, validators, session-flag side
+  // effects — keyed off the real op name, with nothing duplicated. The ops
+  // also stay directly callable (back-compat + what the selftest drives).
+  if (name === "roadmap_search") {
+    return roadmapSearchResult(typeof args?.intent === "string" ? args.intent : "");
+  }
+  if (name === "roadmap_describe") {
+    return roadmapDescribeResult(args?.op);
+  }
+  if (name === "roadmap") {
+    const op = args?.op;
+    if (typeof op !== "string" || !op) {
+      return errorResult(
+        "roadmap requires an 'op', e.g. roadmap({ op: 'get_roadmap_snapshot' }). Call roadmap_search to discover operations."
+      );
+    }
+    if (DISPATCH_TOOLS.has(op)) {
+      return errorResult(
+        `'${op}' is a dispatch tool, not an operation. Pass a real op such as get_roadmap_snapshot — call roadmap_search to list them.`
+      );
+    }
+    if (!OP_NAMES.has(op)) {
+      return errorResult(
+        `Unknown op '${op}'. Call roadmap_search to list operations, or roadmap_describe({ op }) for one.`
+      );
+    }
+    // Accept BOTH the documented nested shape { op, args: {...} } AND the flat
+    // shape { op, ...fields } that LLM clients routinely emit when they hoist
+    // scalar arguments to the top level. Flat siblings fill in keys the nested
+    // object omits; on conflict the nested (documented) shape wins. This means
+    // a top-level workspaceId/dryRun is never silently dropped — which would
+    // mis-target a write or turn a validate-only call into a real one. No op
+    // uses 'op'/'args' as an argument name, so stripping them here is safe.
+    const { op: _op, args: nested, ...flat } = args ?? {};
+    let inner;
+    if (nested == null) {
+      inner = flat; // flat shape (or no args at all)
+    } else if (typeof nested === "object" && !Array.isArray(nested)) {
+      inner = { ...flat, ...nested };
+    } else if (typeof nested === "string") {
+      // Some clients JSON-encode the args object into a string. Parse and
+      // merge when it's an object; otherwise surface the real cause rather
+      // than silently dropping it (which produced a misleading downstream
+      // "X is required" from the inner op).
+      let parsed;
+      try {
+        parsed = JSON.parse(nested);
+      } catch {
+        parsed = undefined;
+      }
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        inner = { ...flat, ...parsed };
+      } else {
+        return errorResult(
+          `roadmap 'args' must be an object — got a string that isn't a JSON object. Call as roadmap({ op: "${op}", args: { ... } }) (or hoist the fields to the top level).`
+        );
+      }
+    } else {
+      return errorResult(
+        `roadmap 'args' must be an object — got ${Array.isArray(nested) ? "an array" : typeof nested}. Call as roadmap({ op: "${op}", args: { ... } }).`
+      );
+    }
+    return callTool(op, inner);
+  }
+
   // 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,
@@ -2619,6 +3130,27 @@ async function callTool(name, args) {
       );
       return rubricMissingResult(name);
     }
+    // Repo-link gate. If the agent is in a git repo that isn't mapped to a
+    // workspace, this write would silently land on the install's env
+    // default. Block once with the link_repo fix (or the workspaceId escape
+    // hatch) so the mapping gets done instead of writes scattering onto the
+    // wrong workspace. Repo-aware so a multi-repo chat is never bricked —
+    // see repoLinkGate / repoUnmappedResult for the full escape-hatch list.
+    {
+      const { source: wsSource } = resolveWorkspaceWithSource(
+        args?.workspaceId
+      );
+      const linkBlock = await repoLinkGate(name, args, wsSource, wsId);
+      if (linkBlock) {
+        session.mutatorBlocks += 1;
+        recordTelemetry(
+          "mutator_blocked_repo_unmapped",
+          { tool: name, targetId },
+          wsId
+        );
+        return linkBlock;
+      }
+    }
     // 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.
@@ -2635,8 +3167,8 @@ async function callTool(name, args) {
       );
       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."
+        opCall("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. The list_themes or get_roadmap_snapshot ops also satisfy this gate if you want the full catalogue."
       );
     }
     if (
@@ -2655,7 +3187,7 @@ async function callTool(name, args) {
       );
       return discoveryMissingResult(
         name,
-        'suggest_capability_for({ description: "<the work you are about to propose>" })',
+        opCall("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."
       );
     }
@@ -2809,7 +3341,7 @@ async function callTool(name, args) {
         _meta: {
           roadmapper: {
             reminder:
-              "Rubric loaded. You can now safely call propose_task, propose_capability, propose_theme, submit_acceptance_grades, link_pr.",
+              'Rubric loaded. You can now safely run the write ops via roadmap({ op, args }) — e.g. roadmap({ op: "propose_task", args: {...} }), propose_capability, propose_theme, submit_acceptance_grades, link_pr.',
           },
         },
       });
@@ -2836,6 +3368,8 @@ async function callTool(name, args) {
     }
     case "propose_task":
       return proposeTask(args, projected, wsId);
+    case "propose_tasks":
+      return proposeTasks(args, projected, wsId);
     case "propose_theme":
       return proposeTheme(args, projected, wsId);
     case "propose_capability":
@@ -2899,6 +3433,11 @@ async function callTool(name, args) {
       // propose_capability gate (the natural next step on a gap).
       session.capsDiscoveredAt = Date.now();
       return detectCapabilityGaps(args, projected);
+    case "detect_theme_sprawl":
+      // Enumerates every active theme, so it satisfies the propose_theme
+      // discovery gate (consolidating or proposing is the natural next step).
+      session.themesListedAt = Date.now();
+      return detectThemeSprawl(args, projected);
     default:
       return errorResult(`Unknown tool: ${name}`);
   }
@@ -2981,12 +3520,12 @@ async function proposeTask(args, projected, wsId) {
     if (best && best.score > 0.2 && best.score > chosenScore + 0.1) {
       return (
         base +
-        `The task text fits ${best.id} (${best.name}) noticeably better (score ${best.score.toFixed(2)}) than the chosen ${cap.id} (${chosenScore.toFixed(2)}). If that's the right home, move_task it there.`
+        `The task text fits ${best.id} (${best.name}) noticeably better (score ${best.score.toFixed(2)}) than the chosen ${cap.id} (${chosenScore.toFixed(2)}). If that's the right home, move it there with ${opCall("move_task")}.`
       );
     }
     return (
       base +
-      "If you're confident in the parent, ignore this; otherwise call suggest_capability_for({ taskId }) to confirm."
+      `If you're confident in the parent, ignore this; otherwise call ${opCall("suggest_capability_for", "{ taskId }")} to confirm.`
     );
   }
 
@@ -3087,44 +3626,263 @@ async function proposeTask(args, projected, wsId) {
   );
 }
 
-async function proposeTheme(args, _projected /* unused — themes carry no parent */, wsId) {
-  const nameErr = validateName(args.name, 6);
-  if (nameErr) return errorResult(nameErr);
+/**
+ * Shared field validation for a single task spec (used by the bulk
+ * propose_tasks path). Returns an error string or null. Mirrors the
+ * inline checks in proposeTask so both paths reject identically.
+ */
+function taskSpecError(t) {
+  const titleErr = validateName(t.title, 5);
+  if (titleErr) return titleErr;
+  if (!t.effort)
+    return "effort is required (one of XS, S, M, L, XL) on every task in the batch.";
+  if (!VALID_EFFORTS.has(t.effort)) return `Invalid effort ${t.effort}.`;
+  if (t.priority && !VALID_PRIORITIES.has(t.priority))
+    return `Invalid priority ${t.priority}.`;
+  if (t.kind && !VALID_KINDS.has(t.kind)) return `Invalid kind ${t.kind}.`;
+  if (t.expectedPRs !== undefined && (typeof t.expectedPRs !== "number" || t.expectedPRs <= 0))
+    return `expectedPRs must be a positive number, got ${t.expectedPRs}.`;
+  if (t.expectedScope !== undefined && (typeof t.expectedScope !== "number" || t.expectedScope <= 0))
+    return `expectedScope must be a positive number, got ${t.expectedScope}.`;
+  return null;
+}
 
-  const name = cleanText(args.name);
-  const id = randomThemeId();
-  const theme = {
+/** Build a task record from a spec + its pre-minted id. Mirrors the
+ *  object proposeTask constructs (minus the per-call skip warning). */
+function buildTaskRecord(t, cap, id) {
+  const start = todayISO();
+  const target = addDays(start, Math.max(1, Math.ceil(EFFORT_DAYS[t.effort])));
+  return {
     id,
-    name,
-    description: cleanText(args.description),
-    color: args.color || "#6366f1", // brand-indigo default; user can change
-    ...(typeof args.targetRoi === "number" ? { targetRoi: args.targetRoi } : {}),
+    capabilityId: cap.id,
+    title: cleanText(t.title),
+    summary: cleanText(t.summary),
+    status: "planned",
+    priority: t.priority ?? "P2",
+    effort: t.effort,
+    kind: t.kind ?? "feature",
+    start,
+    target,
+    originalTarget: target,
+    progress: 0,
+    owner: t.owner?.trim() ?? "",
+    team: cap.team ?? "",
+    tags: [],
+    prs: [],
+    links: {},
+    acceptance: t.acceptance ?? [],
+    dependsOn: t.dependsOn ?? [],
+    authorKind: "agent",
+    ...(t.expectedPRs !== undefined ? { expectedPRs: t.expectedPRs } : {}),
+    ...(t.expectedScope !== undefined ? { expectedScope: t.expectedScope } : {}),
   };
+}
+
+/**
+ * propose_tasks — file MANY tasks under one capability in a single
+ * call. This is the token-efficient path: instead of N round trips
+ * (each with its own tool-call framing + result), the agent sends the
+ * whole batch once and gets back one compact array of {id, title}.
+ *
+ * Intra-batch dependencies: a task may carry a `ref` (a caller-chosen
+ * alias) and other tasks may list that ref in `dependsOn`. We mint all
+ * ids first, then rewrite any dependsOn entry that matches a sibling's
+ * ref to the real TK id. dependsOn entries that aren't a known ref pass
+ * through unchanged (assumed to be existing TK ids).
+ *
+ * Per-item failures don't sink the batch: each result row carries ok
+ * or error, mirroring move_tasks. Validation errors are reported
+ * per-row WITHOUT writing that row; valid rows still get created.
+ */
+async function proposeTasks(args, projected, wsId) {
+  const cap = projected.capabilities.find((c) => c.id === args.capabilityId);
+  if (!cap) return errorResult(`Capability ${args.capabilityId} not found.`);
+  const specs = Array.isArray(args.tasks) ? args.tasks : null;
+  if (!specs || specs.length === 0)
+    return errorResult("tasks must be a non-empty array of task specs.");
+  if (specs.length > 100)
+    return errorResult(`Too many tasks (${specs.length}); cap is 100 per call.`);
+
+  // Mint ids up front so intra-batch dependsOn refs can resolve.
+  const minted = specs.map((t) => ({ spec: t, id: randomTaskId() }));
+  const refToId = new Map();
+  for (const m of minted) {
+    if (typeof m.spec.ref === "string" && m.spec.ref.trim())
+      refToId.set(m.spec.ref.trim(), m.id);
+  }
+  const resolveDeps = (deps) =>
+    Array.isArray(deps) ? deps.map((d) => refToId.get(d) ?? d) : [];
+
+  // Validate everything first; a structural error in any row fails the
+  // whole call (cheaper to fix the batch than to half-apply it). RPC
+  // errors below are the per-row, partial-success case.
+  for (let i = 0; i < minted.length; i++) {
+    const err = taskSpecError(minted[i].spec);
+    if (err) return errorResult(`tasks[${i}]: ${err}`);
+  }
 
   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
-      )
+      JSON.stringify({
+        ok: true,
+        dryRun: true,
+        capabilityId: cap.id,
+        wouldCreate: minted.map(({ spec, id }) => ({
+          id,
+          title: cleanText(spec.title),
+          effort: spec.effort,
+        })),
+        message: `Would create ${minted.length} task(s) under ${cap.id} (${cap.name}). No records written.`,
+      }),
     );
   }
 
-  let rpcResult;
-  try {
-    rpcResult = await rpcCall("propose_theme", {
-      p_workspace_id: wsId,
-      p_theme: theme,
-      p_idempotency_key: args.idempotencyKey ?? null,
-    });
-  } catch (e) {
+  const results = [];
+  let created = 0;
+  for (const { spec, id } of minted) {
+    const record = buildTaskRecord(
+      { ...spec, dependsOn: resolveDeps(spec.dependsOn) },
+      cap,
+      id
+    );
+    try {
+      const rpcResult = await rpcCall("propose_task", {
+        p_workspace_id: wsId,
+        p_task: record,
+        p_idempotency_key: spec.idempotencyKey ?? null,
+      });
+      const stored = rpcResult?.task ?? record;
+      const idempotent = rpcResult?.idempotent === true;
+      if (!idempotent) created += 1;
+      results.push({ ok: true, id: stored.id, title: record.title, idempotent });
+    } catch (e) {
+      results.push({ ok: false, title: record.title, error: e.message });
+    }
+  }
+
+  const failed = results.filter((r) => !r.ok).length;
+  return textResult(
+    JSON.stringify({
+      ok: failed === 0,
+      capabilityId: cap.id,
+      created,
+      idempotent: results.filter((r) => r.ok && r.idempotent).length,
+      failed,
+      tasks: results,
+      message:
+        `Filed ${created} new task(s) under ${cap.id} (${cap.name})` +
+        (failed ? `; ${failed} failed (see tasks[].error).` : "."),
+    })
+  );
+}
+
+async function proposeTheme(args, projected, wsId) {
+  const nameErr = validateName(args.name, 6);
+  if (nameErr) return errorResult(nameErr);
+
+  const name = cleanText(args.name);
+  const description = cleanText(args.description);
+
+  // ── Sprawl control (always on, independent of autonomy) ──────────
+  // Refuse a near-duplicate of an existing active theme. This is the
+  // server-side replacement for the human gate: instead of asking a
+  // person every time, we only stop the agent when it's about to mint
+  // a theme that overlaps one that already exists. Reuse/update beats
+  // a sibling. force:true is the deliberate override.
+  const activeThemes = (projected?.themes ?? []).filter((t) => !t.archived);
+  const proposedTokens = tokenize(`${name} ${description ?? ""}`);
+  let nearest = null;
+  let nearestScore = 0;
+  for (const t of activeThemes) {
+    const s = jaccardScore(proposedTokens, tokenize(`${t.name} ${t.description ?? ""}`));
+    if (s > nearestScore) {
+      nearestScore = s;
+      nearest = t;
+    }
+  }
+  if (nearest && nearestScore >= THEME_SPRAWL_BLOCK && args.force !== true) {
+    return textResult(
+      JSON.stringify(
+        {
+          error: "too_similar",
+          message:
+            `"${name}" overlaps the existing theme ${nearest.id} (${nearest.name}) ` +
+            `at ${nearestScore.toFixed(2)} (block bar ${THEME_SPRAWL_BLOCK}). Themes are the ` +
+            "small, years-stable top tier — a near-duplicate fragments the strategic view. " +
+            "Reuse it: file your work as a capability under it (the propose_capability op with " +
+            `pillarId: "${nearest.id}"), or broaden its scope with the update_theme op. If this is ` +
+            "genuinely a distinct strategic pillar, retry with force:true.",
+          nearestTheme: { id: nearest.id, name: nearest.name, score: Number(nearestScore.toFixed(3)) },
+          fix: opCall("propose_capability", `{ pillarId: "${nearest.id}", ... }`),
+        },
+        null,
+        2
+      ),
+      { isError: true }
+    );
+  }
+
+  // ── Autonomy gate ────────────────────────────────────────────────
+  // Default ON: agents create themes without confirmation. A workspace
+  // that flips agent_theme_autonomy OFF re-imposes a human checkpoint —
+  // propose_theme then refuses until the caller passes confirm:true
+  // (the agent's signal that it surfaced the new theme to the user and
+  // got an explicit yes). The sprawl block above still applies either way.
+  const autonomy = projected?.settings?.agentThemeAutonomy !== false;
+  if (!autonomy && args.confirm !== true && !args.dryRun) {
+    return textResult(
+      JSON.stringify(
+        {
+          error: "confirmation_required",
+          message:
+            `This workspace has agent theme-autonomy turned OFF, so a new theme ("${name}") ` +
+            "needs explicit human sign-off. Surface the proposed theme to the user; if they " +
+            "approve, retry with confirm:true. Otherwise file the work under an existing theme.",
+          ...(nearest
+            ? { closestExisting: { id: nearest.id, name: nearest.name, score: Number(nearestScore.toFixed(3)) } }
+            : {}),
+          fix: opCall("propose_theme", "{ ...same args, confirm: true }"),
+        },
+        null,
+        2
+      ),
+      { isError: true }
+    );
+  }
+
+  const id = randomThemeId();
+  const theme = {
+    id,
+    name,
+    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;
@@ -3159,7 +3917,7 @@ async function proposeCapability(args, projected, wsId) {
   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.`
+      `pillarId ${pillarId} doesn't match any known theme. Run ${opCall("list_themes")} first.`
     );
   }
   if (typeof args.impact === "number" && !VALID_IMPACTS.has(args.impact)) {
@@ -3399,7 +4157,7 @@ function suggestCapabilityFor(args, projected) {
             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 existing capability is a sensible parent. Before ${opCall("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.",
             },
           },
@@ -3461,18 +4219,25 @@ function suggestThemeFor(args, projected) {
       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.
+  // Autonomy-aware guidance. With agent_theme_autonomy ON (default),
+  // the agent may create a theme on a weak/no match WITHOUT asking —
+  // the server's too_similar block in propose_theme is the sprawl
+  // guard, not a human checkpoint. With it OFF, fall back to the old
+  // "confirm with the user first" framing.
+  const autonomy = projected?.settings?.agentThemeAutonomy !== false;
   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.",
+              reminder: autonomy
+                ? ranked.length === 0
+                  ? `No existing theme overlaps. Theme-autonomy is ON, so you may run ${opCall("propose_theme")} directly if this is a genuinely new strategic pillar — the server will refuse it only if it's a near-duplicate of an existing theme.`
+                  : "No strong match (top score < 0.4). Prefer the closest existing theme if it fits; otherwise propose_theme is fine (autonomy is ON, sprawl is guarded server-side)."
+                : ranked.length === 0
+                  ? "No existing theme overlaps. Theme-autonomy is OFF for this workspace — verify with the user that this is a genuinely new strategic direction before propose_theme, and pass confirm:true."
+                  : "No strong match (top score < 0.4). Re-using a 'close-enough' theme is almost always right; theme-autonomy is OFF, so confirm with the user before propose_theme.",
             },
           },
         }
@@ -3483,13 +4248,18 @@ function suggestThemeFor(args, projected) {
       {
         ok: true,
         query: desc,
+        themeAutonomy: autonomy,
         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."
+            ? autonomy
+              ? "No existing theme overlaps. propose_theme is appropriate if this is a distinct strategic pillar — autonomy is on; the server blocks only near-duplicates."
+              : "No existing theme overlaps. propose_theme needs explicit user confirmation (autonomy off): pass confirm:true once the user approves."
             : 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.`,
+              : autonomy
+                ? `Weak overlap. The top match is often closer than it scores — prefer it if it fits; otherwise propose_theme is fine (sprawl guarded server-side).`
+                : `Weak overlap. Prefer the top match over a new theme unless the user explicitly asks for a new strategic direction (autonomy off).`,
       },
       null,
       2
@@ -4132,7 +4902,7 @@ function detectCapabilityGaps(args, projected) {
             roadmapper: {
               reminder:
                 `${shaped.length} capability gap(s) detected — clusters of uncategorized work no existing bet covers. ` +
-                "Each is a CANDIDATE for propose_capability (confirm with the user — capabilities are quarterly bets, not auto-created), then move_tasks the members under it.",
+                `Each is a CANDIDATE for ${opCall("propose_capability")} (confirm with the user — capabilities are quarterly bets, not auto-created), then ${opCall("move_tasks")} the members under it.`,
             },
           },
         }
@@ -4152,6 +4922,86 @@ function detectCapabilityGaps(args, projected) {
   );
 }
 
+/**
+ * detect_theme_sprawl — the consolidation companion to
+ * agent_theme_autonomy. Autonomy lets agents mint themes freely (with
+ * the per-create too_similar block as a guard); over time, two themes
+ * created from different sessions can still drift toward overlap. This
+ * surfaces those pairs so a human can merge them.
+ *
+ * O(n^2) over active themes — fine; themes are the small top tier
+ * (tens, not thousands). Deterministic: stable id sort, never random.
+ */
+function detectThemeSprawl(args, projected) {
+  const threshold =
+    typeof args?.threshold === "number" && Number.isFinite(args.threshold)
+      ? Math.min(1, Math.max(0, args.threshold))
+      : THEME_SPRAWL_WARN;
+  const includeArchived = args?.includeArchived === true;
+
+  const themes = (projected.themes ?? [])
+    .filter((t) => includeArchived || !t.archived)
+    .slice()
+    .sort((a, b) => String(a.id).localeCompare(String(b.id)));
+
+  const capCountByTheme = new Map();
+  for (const c of projected.capabilities ?? []) {
+    if (c.archived) continue;
+    capCountByTheme.set(c.pillarId, (capCountByTheme.get(c.pillarId) ?? 0) + 1);
+  }
+
+  const toks = themes.map((t) => tokenize(`${t.name} ${t.description ?? ""}`));
+  const pairs = [];
+  for (let i = 0; i < themes.length; i++) {
+    for (let j = i + 1; j < themes.length; j++) {
+      const score = jaccardScore(toks[i], toks[j]);
+      if (score < threshold) continue;
+      // Suggest merging the lighter theme (fewer capabilities) INTO the
+      // heavier one — the smaller bet is the cheaper thing to re-parent.
+      const a = themes[i], b = themes[j];
+      const aCaps = capCountByTheme.get(a.id) ?? 0;
+      const bCaps = capCountByTheme.get(b.id) ?? 0;
+      const [keep, fold] = aCaps >= bCaps ? [a, b] : [b, a];
+      const foldCaps = keep === a ? bCaps : aCaps;
+      pairs.push({
+        score: Number(score.toFixed(3)),
+        themes: [
+          { id: a.id, name: a.name, capabilities: aCaps },
+          { id: b.id, name: b.name, capabilities: bCaps },
+        ],
+        suggestion:
+          foldCaps > 0
+            ? `Likely duplicate. To consolidate: move_capabilities the ${foldCaps} capabilit${foldCaps === 1 ? "y" : "ies"} under ${fold.id} (${fold.name}) to ${keep.id} (${keep.name}), then archive_theme ${fold.id}.`
+            : `Likely duplicate. ${fold.id} (${fold.name}) has no capabilities — archive_theme it and keep ${keep.id} (${keep.name}).`,
+      });
+    }
+  }
+  pairs.sort((x, y) => y.score - x.score);
+
+  const meta =
+    pairs.length > 0
+      ? {
+          _meta: {
+            roadmapper: {
+              reminder:
+                `${pairs.length} theme pair(s) overlap at/above ${threshold} — candidate duplicates. ` +
+                "Themes are the years-stable top tier; consolidating keeps the strategic view legible. A human should confirm each merge.",
+            },
+          },
+        }
+      : undefined;
+
+  return textResult(
+    JSON.stringify({
+      themesScanned: themes.length,
+      threshold,
+      sprawlPairCount: pairs.length,
+      pairs,
+    }),
+    meta
+  );
+}
+
 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.`);
@@ -4233,7 +5083,7 @@ function buildReminder(toolName, projected) {
       toolName === "list_themes")
   ) {
     reminders.push(
-      "Call get_agents_md before any propose_* / submit_acceptance_grades / link_pr call — those tools refuse without it."
+      `Call ${opCall("get_agents_md")} before any write op (propose_* / submit_acceptance_grades / link_pr) — they refuse without it.`
     );
   }
   // Tasks with merged PRs but no acceptance grades = ungraded
@@ -4252,7 +5102,7 @@ function buildReminder(toolName, projected) {
       reminders.push(
         `${ungraded.length} delivered task${ungraded.length === 1 ? "" : "s"} ` +
           `have merged PRs without submitted acceptance grades. ` +
-          `Call submit_acceptance_grades for: ${ids}${more}.`
+          `Call ${opCall("submit_acceptance_grades")} for: ${ids}${more}.`
       );
     }
   }
@@ -4299,14 +5149,14 @@ const RESOURCES = [
     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.",
+      `Live list of non-delivered capabilities for the env-default workspace. Read this before proposing tasks or capabilities to find the right parent. Note: MCP resources don't accept arguments, so this always reads SUPABASE_WORKSPACE_ID's workspace — use roadmap({ op: "list_capabilities", args: { 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.",
+      `Live list of in_progress + planned tasks for the env-default workspace. Same workspaceId caveat as roadmapper://capabilities/active — use roadmap({ op: "list_tasks", args: { workspaceId } }) for cross-workspace reads.`,
     mimeType: "application/json",
   },
 ];
@@ -4437,33 +5287,33 @@ function renderPrompt(name, args) {
       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" +
+          "Every operation runs through one tool: roadmap({ op, args }). Follow this flow exactly:\n" +
+          '1. roadmap({ op: "get_agents_md" }) (or read the roadmapper://rubric resource) to load the rubric for this session.\n' +
+          '2. roadmap({ op: "suggest_capability_for", args: { description } }) 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 roadmap({ op: "propose_tasks", args: { capabilityId, tasks: [...] } }). Each task MUST include acceptance criteria per the rubric.\n' +
+          '4. If nothing fits, STOP and ask the user before roadmap({ op: "propose_capability", args }) — 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` +
+          "Every operation runs through one tool: roadmap({ op, args }). Follow this flow exactly:\n" +
+          '1. roadmap({ op: "get_agents_md" }) (or read the roadmapper://rubric resource) to load grading dimensions.\n' +
+          `2. roadmap({ op: "get_task", args: { 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" +
+          '4. roadmap({ op: "submit_acceptance_grades", args: { taskId, 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") +
+            ? `5. roadmap({ op: "link_pr", args: {...} }) to attach ${args.pr_url} to the task.\n`
+            : '5. If you opened a PR, roadmap({ op: "link_pr", args: {...} }) 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" +
+          "Run a structured roadmap review. Every operation runs through one tool: roadmap({ op, args }).\n\n" +
+          '1. roadmap({ op: "get_agents_md" }) to load the rubric (or confirm rubric is current).\n' +
+          '2. roadmap({ op: "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."
@@ -4506,6 +5356,36 @@ async function handle(request) {
       // boundary for "you need to fetch the rubric again."
       resetSession();
       recordTelemetry("session_initialized", { stats });
+      // Build the server instructions once. A dynamic preamble (resolved
+      // workspace + where it came from + live counts, so the agent can
+      // trust where its writes land instead of discovering an empty/wrong
+      // workspace later) followed by the static CORE planning contract.
+      // Surfaced at the TOP LEVEL of the result — the MCP-spec
+      // `instructions` channel that compliant clients (Claude Code,
+      // Cursor) inject into context. It previously lived only inside
+      // serverInfo, where the spec doesn't define it, so spec-reading
+      // clients silently dropped it. The gate/suggest reminders that used
+      // to sit here are now folded into CORE_CONTRACT's workflow section.
+      const instructions = (() => {
+        const { id: ws, source } = resolveWorkspaceWithSource();
+        const wsLine = ws
+          ? `Workspace: ${ws} (resolved from ${source}). `
+          : "No workspace resolved yet. ";
+        const rootsLine = _clientSupportsRoots
+          ? "Detecting the repo you're in to pick its workspace; call get_active_workspace before your first write to confirm. "
+          : ws
+            ? ""
+            : "Set ROADMAPPER_WORKSPACE_ID or open a connected repo. ";
+        const preamble =
+          "Roadmapper online — " +
+          wsLine +
+          `${stats.themes} theme${stats.themes === 1 ? "" : "s"}, ` +
+          `${stats.capabilities} capabilit${stats.capabilities === 1 ? "y" : "ies"}, ` +
+          `${stats.openTasks} open task${stats.openTasks === 1 ? "" : "s"}. ` +
+          rootsLine +
+          "Slash-prompts available: roadmapper:plan-feature, roadmapper:close-task, roadmapper:weekly-review.";
+        return preamble + "\n\n" + CORE_CONTRACT;
+      })();
       return {
         jsonrpc: "2.0",
         id,
@@ -4519,38 +5399,14 @@ async function handle(request) {
             resources: { listChanged: false },
             prompts: { listChanged: false },
           },
+          // Top-level instructions: the spec-defined channel. serverInfo
+          // keeps only name/version/stats (stats is a non-standard extra
+          // some clients surface as "server info").
+          instructions,
           serverInfo: {
             name: SERVER_NAME,
             version: SERVER_VERSION,
             stats,
-            instructions: (() => {
-              // Name the workspace we resolve to RIGHT NOW + where it came
-              // from, so the agent can trust where its writes land instead
-              // of discovering an empty/wrong workspace later. Repo-based
-              // resolution (roots → repo_workspace_map) finishes just after
-              // this handshake, so if the client supports roots we say the
-              // target may refine and to confirm via get_active_workspace.
-              const { id: ws, source } = resolveWorkspaceWithSource();
-              const wsLine = ws
-                ? `Workspace: ${ws} (resolved from ${source}). `
-                : "No workspace resolved yet. ";
-              const rootsLine = _clientSupportsRoots
-                ? "Detecting the repo you're in to pick its workspace; call get_active_workspace before your first write to confirm. "
-                : ws
-                  ? ""
-                  : "Set ROADMAPPER_WORKSPACE_ID or open a connected repo. ";
-              return (
-                "Roadmapper online — " +
-                wsLine +
-                `${stats.themes} theme${stats.themes === 1 ? "" : "s"}, ` +
-                `${stats.capabilities} capabilit${stats.capabilities === 1 ? "y" : "ies"}, ` +
-                `${stats.openTasks} open task${stats.openTasks === 1 ? "" : "s"}. ` +
-                rootsLine +
-                "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."
-              );
-            })(),
           },
         },
       };
@@ -4564,7 +5420,11 @@ async function handle(request) {
       // so the timing usually works out.
       startLabelLoad();
       const labels = currentLabels();
-      const tools = TOOLS.map((t) => ({
+      // Advertise the three dispatch tools, not the 34 operations. The ops
+      // (and their schemas) are reachable via roadmap_search / roadmap_describe
+      // / roadmap — see META_TOOLS and the callTool dispatch. tplDescription
+      // still runs so custom workspace labels apply.
+      const tools = META_TOOLS.map((t) => ({
         ...t,
         description: tplDescription(t.description, labels),
       }));
@@ -4633,6 +5493,23 @@ async function runSelftest() {
         r?.result?.capabilities?.resources &&
         r?.result?.capabilities?.prompts,
     },
+    {
+      // The CORE planning contract must ride on the TOP-LEVEL `instructions`
+      // field (the spec channel clients read), not buried in serverInfo, and
+      // must carry the server-enforced falsifiable-outcome rule so an agent
+      // can file a valid proposal without first fetching the full AGENTS.md.
+      name: "initialize returns top-level instructions with the core contract",
+      fn: () => handle({ id: 2, method: "initialize", params: {} }),
+      pass: (r) => {
+        const instr = r?.result?.instructions;
+        return (
+          typeof instr === "string" &&
+          instr.length > 0 &&
+          instr.includes("FALSIFIABLE OUTCOME") &&
+          instr.includes("get_agents_md")
+        );
+      },
+    },
     {
       // Hitting a mutator with no rubric fetched must return the
       // structured prerequisite_missing error with a `fix` field,
@@ -4734,6 +5611,147 @@ async function runSelftest() {
       },
       pass: (r) => r?.themesListedAt !== null && r?.capsDiscoveredAt !== null,
     },
+    {
+      // Sprawl control: a theme that overlaps an existing one above the
+      // block bar is refused with too_similar, naming the match — even
+      // on dryRun (the guard runs before the write/preview).
+      name: "propose_theme blocks a near-duplicate theme (too_similar)",
+      fn: () =>
+        proposeTheme(
+          { name: "Data Intelligence Platform Core", dryRun: true },
+          {
+            themes: [
+              { id: "TH-DUP", name: "Data Intelligence Platform", description: "" },
+            ],
+            settings: { agentThemeAutonomy: true },
+          },
+          "ws-test"
+        ),
+      pass: (r) => {
+        const t = r?.content?.[0]?.text ?? "";
+        return t.includes("too_similar") && t.includes("TH-DUP");
+      },
+    },
+    {
+      // A distinct theme passes the sprawl guard, and with autonomy ON
+      // (default) sails through to the (dryRun) create — no confirmation.
+      name: "propose_theme allows a distinct theme when autonomy is on",
+      fn: () =>
+        proposeTheme(
+          { name: "Customer Onboarding Automation", dryRun: true },
+          {
+            themes: [
+              { id: "TH-DUP", name: "Data Intelligence Platform", description: "" },
+            ],
+            settings: { agentThemeAutonomy: true },
+          },
+          "ws-test"
+        ),
+      pass: (r) => {
+        const t = r?.content?.[0]?.text ?? "";
+        return t.includes("\"ok\": true") && t.includes("wouldCreate") && !t.includes("too_similar");
+      },
+    },
+    {
+      // force:true overrides a too_similar block for the rare genuine
+      // false positive.
+      name: "propose_theme force:true overrides the sprawl block",
+      fn: () =>
+        proposeTheme(
+          { name: "Data Intelligence Platform Core", force: true, dryRun: true },
+          {
+            themes: [
+              { id: "TH-DUP", name: "Data Intelligence Platform", description: "" },
+            ],
+            settings: { agentThemeAutonomy: true },
+          },
+          "ws-test"
+        ),
+      pass: (r) => {
+        const t = r?.content?.[0]?.text ?? "";
+        return t.includes("wouldCreate") && !t.includes("too_similar");
+      },
+    },
+    {
+      // With autonomy OFF, a brand-new theme needs confirm:true — the
+      // server returns confirmation_required until the human signs off.
+      name: "propose_theme requires confirm when autonomy is off",
+      fn: () =>
+        proposeTheme(
+          { name: "Brand New Distinct Strategic Pillar" },
+          { themes: [], settings: { agentThemeAutonomy: false } },
+          "ws-test"
+        ),
+      pass: (r) => {
+        const t = r?.content?.[0]?.text ?? "";
+        return t.includes("confirmation_required") && t.includes("confirm");
+      },
+    },
+    {
+      // detect_theme_sprawl surfaces overlapping existing themes as
+      // consolidation candidates.
+      name: "detect_theme_sprawl flags overlapping themes",
+      fn: () =>
+        detectThemeSprawl(
+          {},
+          {
+            themes: [
+              { id: "TH-A", name: "Data Intelligence", description: "" },
+              { id: "TH-B", name: "Data Intelligence Platform", description: "" },
+            ],
+            capabilities: [],
+          }
+        ),
+      pass: (r) => {
+        const t = r?.content?.[0]?.text ?? "";
+        return t.includes("\"sprawlPairCount\": 1") || (t.includes("TH-A") && t.includes("TH-B"));
+      },
+    },
+    {
+      // propose_tasks bulk: dryRun previews all rows + mints an id each.
+      name: "propose_tasks bulk previews the whole batch (dryRun)",
+      fn: () =>
+        proposeTasks(
+          {
+            capabilityId: "CAP-1",
+            dryRun: true,
+            tasks: [
+              { ref: "a", title: "First bulk task here", effort: "M" },
+              { title: "Second bulk task here", effort: "S", dependsOn: ["a"] },
+            ],
+          },
+          { capabilities: [{ id: "CAP-1", name: "Test Cap" }], themes: [], tasks: [] },
+          "ws-test"
+        ),
+      pass: (r) => {
+        const t = r?.content?.[0]?.text ?? "";
+        try {
+          const j = JSON.parse(t);
+          return j.dryRun === true && Array.isArray(j.wouldCreate) && j.wouldCreate.length === 2;
+        } catch {
+          return false;
+        }
+      },
+    },
+    {
+      // propose_tasks rejects the whole batch on a per-row validation
+      // error (missing effort), naming the offending index.
+      name: "propose_tasks rejects a batch with a missing-effort row",
+      fn: () =>
+        proposeTasks(
+          {
+            capabilityId: "CAP-1",
+            tasks: [{ title: "No effort on this task" }],
+          },
+          { capabilities: [{ id: "CAP-1", name: "Test Cap" }], themes: [], tasks: [] },
+          "ws-test"
+        ),
+      pass: (r) => {
+        if (!r?.isError) return false;
+        const t = r?.content?.[0]?.text ?? "";
+        return t.includes("tasks[0]") && t.includes("effort");
+      },
+    },
     {
       name: "resources/list returns the three resources",
       fn: () => handle({ id: 12, method: "resources/list", params: {} }),
@@ -4780,10 +5798,317 @@ async function runSelftest() {
         r.result.messages[0].content.text.includes("demo description"),
     },
     {
-      name: "tools/list",
+      // The wire surface is the three dispatch tools, NOT the 34 ops.
+      name: "tools/list advertises exactly the three dispatch tools",
       fn: () => handle({ id: 2, method: "tools/list", params: {} }),
-      pass: (r) =>
-        Array.isArray(r?.result?.tools) && r.result.tools.length === TOOLS.length,
+      pass: (r) => {
+        const names = (r?.result?.tools ?? []).map((t) => t.name).sort();
+        return (
+          names.length === META_TOOLS.length &&
+          ["roadmap", "roadmap_describe", "roadmap_search"].every((n) =>
+            names.includes(n)
+          )
+        );
+      },
+    },
+    {
+      // tools/list must serve TRIMMED descriptions (summary only): every
+      // tool keeps a non-empty one-line summary, and the methodology blocks
+      // (USE WHEN / PREREQUISITE / ANTI-PATTERN / EXAMPLE) must be gone from
+      // the wire payload — they now live in `instructions` + the rubric.
+      // Guards against a regression that re-serves the full descriptions.
+      name: "tools/list serves trimmed one-line descriptions",
+      fn: () => handle({ id: 23, method: "tools/list", params: {} }),
+      pass: (r) => {
+        const tools = r?.result?.tools;
+        if (!Array.isArray(tools) || tools.length === 0) return false;
+        return tools.every(
+          (t) =>
+            typeof t.description === "string" &&
+            t.description.length > 0 &&
+            !t.description.includes("\n\n") &&
+            !t.description.includes("ANTI-PATTERN:") &&
+            !t.description.includes("PREREQUISITE:")
+        );
+      },
+    },
+    {
+      // roadmap_search returns the op catalogue (all 34 when no intent),
+      // each row carrying a trimmed summary (no methodology blocks).
+      name: "roadmap_search lists operations with trimmed summaries",
+      fn: () =>
+        handle({
+          id: 24,
+          method: "tools/call",
+          params: { name: "roadmap_search", arguments: {} },
+        }),
+      pass: (r) => {
+        if (r?.result?.isError) return false;
+        const text = r?.result?.content?.[0]?.text ?? "";
+        let body;
+        try {
+          body = JSON.parse(text);
+        } catch {
+          return false;
+        }
+        const ops = body?.operations ?? [];
+        return (
+          ops.length === TOOLS.length &&
+          ops.some((o) => o.op === "propose_task") &&
+          ops.every(
+            (o) =>
+              typeof o.summary === "string" &&
+              o.summary.length > 0 &&
+              !o.summary.includes("ANTI-PATTERN:")
+          )
+        );
+      },
+    },
+    {
+      // roadmap_describe serves an op's inputSchema on demand (the bulk
+      // evicted from tools/list). move_* / update_* live here now.
+      name: "roadmap_describe returns inputSchema for move/update ops",
+      fn: () =>
+        handle({
+          id: 25,
+          method: "tools/call",
+          params: { name: "roadmap_describe", arguments: { op: "move_task" } },
+        }),
+      pass: (r) => {
+        if (r?.result?.isError) return false;
+        let body;
+        try {
+          body = JSON.parse(r?.result?.content?.[0]?.text ?? "");
+        } catch {
+          return false;
+        }
+        return (
+          body?.op === "move_task" &&
+          body?.inputSchema?.type === "object" &&
+          !!body?.inputSchema?.properties?.newCapabilityId
+        );
+      },
+    },
+    {
+      name: "roadmap_describe rejects an unknown op",
+      fn: () =>
+        handle({
+          id: 26,
+          method: "tools/call",
+          params: { name: "roadmap_describe", arguments: { op: "no_such_op" } },
+        }),
+      pass: (r) => r?.result?.isError === true,
+    },
+    {
+      name: "roadmap rejects a missing op",
+      fn: () =>
+        handle({
+          id: 27,
+          method: "tools/call",
+          params: { name: "roadmap", arguments: {} },
+        }),
+      pass: (r) => r?.result?.isError === true,
+    },
+    {
+      name: "roadmap rejects an unknown op",
+      fn: () =>
+        handle({
+          id: 28,
+          method: "tools/call",
+          params: { name: "roadmap", arguments: { op: "no_such_op" } },
+        }),
+      pass: (r) => r?.result?.isError === true,
+    },
+    {
+      // Dispatch must run the SAME gates as a direct call: hitting a mutator
+      // op through roadmap() before the rubric is fetched returns the
+      // structured prerequisite_missing error, proving gates key off the op.
+      name: "roadmap dispatch enforces the rubric gate on the inner op",
+      fn: () => {
+        resetSession();
+        return handle({
+          id: 29,
+          method: "tools/call",
+          params: {
+            name: "roadmap",
+            arguments: {
+              op: "propose_task",
+              args: { capabilityId: aCap, title: "Should be blocked via dispatch" },
+            },
+          },
+        });
+      },
+      pass: (r) => {
+        if (!r?.result?.isError) return false;
+        try {
+          // Parse and assert the fix FIELD directly (not the whole blob) so a
+          // regression reverting fix to a bare uncallable get_agents_md() —
+          // which still appears in the message — can't pass on substring luck.
+          const out = JSON.parse(r.result.content?.[0]?.text ?? "");
+          return (
+            out.error === "prerequisite_missing" &&
+            out.fix === 'roadmap({ op: "get_agents_md" })'
+          );
+        } catch {
+          return false;
+        }
+      },
+    },
+    {
+      // Dispatch reaches the inner op's argument validation identically to a
+      // direct call. Tightened: assert the message is move_task's OWN
+      // validator (newCapabilityId), so a regression that swallowed args.args
+      // (yielding a generic 'taskId is required') can't pass this.
+      name: "roadmap dispatch reaches inner-op validation",
+      fn: () => {
+        resetSession();
+        return handle({
+          id: 30,
+          method: "tools/call",
+          params: { name: "get_agents_md", arguments: {} },
+        }).then(() =>
+          handle({
+            id: 31,
+            method: "tools/call",
+            params: {
+              name: "roadmap",
+              arguments: { op: "move_task", args: { taskId: "TK-1" } },
+            },
+          })
+        );
+      },
+      pass: (r) => {
+        if (!r?.result?.isError) return false;
+        const text = r.result.content?.[0]?.text ?? "";
+        return text.includes("newCapabilityId") && text.includes("required");
+      },
+    },
+    {
+      // POSITIVE path: a successful read THROUGH roadmap returns the inner
+      // op's real data verbatim (proves the unwrap + passthrough, which the
+      // error-path checks above never exercise).
+      name: "roadmap dispatch returns real data on the happy path",
+      fn: () =>
+        handle({
+          id: 32,
+          method: "tools/call",
+          params: { name: "roadmap", arguments: { op: "get_roadmap_snapshot" } },
+        }),
+      pass: (r) => {
+        if (r?.result?.isError) return false;
+        try {
+          const body = JSON.parse(r.result.content?.[0]?.text ?? "");
+          // Real snapshot shape (workspaceId may be null in seed-only mode).
+          return (
+            Array.isArray(body?.themes) &&
+            Array.isArray(body?.capabilities) &&
+            typeof body?.counts === "object"
+          );
+        } catch {
+          return false;
+        }
+      },
+    },
+    {
+      // Discovery/rubric session flags must be SET through dispatch, not just
+      // blocked when unset — satisfy both gates purely via roadmap({op}) and
+      // confirm the flags flipped (guards a regression where dispatch stopped
+      // re-entering the switch that writes them).
+      name: "roadmap dispatch sets the rubric + discovery session flags",
+      fn: async () => {
+        resetSession();
+        await handle({
+          id: 33,
+          method: "tools/call",
+          params: { name: "roadmap", arguments: { op: "get_agents_md" } },
+        });
+        await handle({
+          id: 34,
+          method: "tools/call",
+          params: { name: "roadmap", arguments: { op: "get_roadmap_snapshot" } },
+        });
+        return {
+          rubric: session.rubricFetchedAt,
+          themes: session.themesListedAt,
+          caps: session.capsDiscoveredAt,
+        };
+      },
+      pass: (r) => r?.rubric !== null && r?.themes !== null && r?.caps !== null,
+    },
+    {
+      // Flat (un-nested) args must NOT be silently dropped — the dangerous
+      // case being a dropped workspaceId/dryRun. Use a gate-free read: a flat
+      // get_task carrying the id at the TOP level (not under args) must reach
+      // the op and resolve the real task. If the flat id were dropped, it
+      // would 404 instead. Proves the flat-merge in the roadmap dispatch.
+      name: "roadmap tolerates flat (un-nested) args",
+      fn: () =>
+        handle({
+          id: 36,
+          method: "tools/call",
+          params: { name: "roadmap", arguments: { op: "get_task", id: aTask } },
+        }),
+      pass: (r) => {
+        if (r?.result?.isError) return false;
+        const text = r.result.content?.[0]?.text ?? "";
+        return typeof aTask === "string" && text.includes(aTask);
+      },
+    },
+    {
+      // When both a flat sibling and a nested args carry the same key, the
+      // nested (documented) value must win. Flat id is a bogus task; nested
+      // id is the real one — resolving the real task proves nested precedence.
+      name: "roadmap merge: nested args win over flat siblings on conflict",
+      fn: () =>
+        handle({
+          id: 37,
+          method: "tools/call",
+          params: {
+            name: "roadmap",
+            arguments: { op: "get_task", id: "TK-DOES-NOT-EXIST", args: { id: aTask } },
+          },
+        }),
+      pass: (r) => {
+        if (r?.result?.isError) return false;
+        const text = r.result.content?.[0]?.text ?? "";
+        return text.includes(aTask) && !text.includes("TK-DOES-NOT-EXIST");
+      },
+    },
+    {
+      // args passed as a JSON STRING (a real LLM failure mode) must be parsed
+      // and honored, not silently dropped — a flat get_task with stringified
+      // args resolves the real task.
+      name: "roadmap parses JSON-string args",
+      fn: () =>
+        handle({
+          id: 38,
+          method: "tools/call",
+          params: {
+            name: "roadmap",
+            arguments: { op: "get_task", args: JSON.stringify({ id: aTask }) },
+          },
+        }),
+      pass: (r) => {
+        if (r?.result?.isError) return false;
+        const text = r.result.content?.[0]?.text ?? "";
+        return typeof aTask === "string" && text.includes(aTask);
+      },
+    },
+    {
+      // A non-object, non-parseable args must produce a clear boundary error
+      // naming the cause — not a misleading downstream 'X is required'.
+      name: "roadmap rejects non-object args with a clear error",
+      fn: () =>
+        handle({
+          id: 39,
+          method: "tools/call",
+          params: { name: "roadmap", arguments: { op: "get_task", args: "not json at all" } },
+        }),
+      pass: (r) => {
+        if (!r?.result?.isError) return false;
+        const text = r.result.content?.[0]?.text ?? "";
+        return text.includes("args") && text.includes("must be an object");
+      },
     },
     {
       name: "get_active_workspace reports a resolution source",
@@ -5772,15 +7097,37 @@ async function runSelftest() {
       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)
-        );
+      // The four move ops are no longer advertised by name (the surface is
+      // the three dispatch tools) but must remain reachable + describable.
+      name: "roadmap_describe resolves all four move ops",
+      fn: async () => {
+        const ops = ["move_task", "move_capability", "move_tasks", "move_capabilities"];
+        const out = [];
+        for (const op of ops) {
+          out.push(
+            await handle({
+              id: 30,
+              method: "tools/call",
+              params: { name: "roadmap_describe", arguments: { op } },
+            })
+          );
+        }
+        return out;
       },
+      pass: (results) =>
+        Array.isArray(results) &&
+        results.length === 4 &&
+        results.every((r) => {
+          if (r?.result?.isError) return false;
+          try {
+            return (
+              JSON.parse(r.result.content?.[0]?.text ?? "")?.inputSchema?.type ===
+              "object"
+            );
+          } catch {
+            return false;
+          }
+        }),
     },
     {
       // Update validation: missing patch.
@@ -5847,17 +7194,37 @@ async function runSelftest() {
       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)
-        );
+      // The three update ops are reachable + describable via the dispatch
+      // surface (not advertised by name in tools/list anymore).
+      name: "roadmap_describe resolves all three update ops",
+      fn: async () => {
+        const ops = ["update_task", "update_capability", "update_theme"];
+        const out = [];
+        for (const op of ops) {
+          out.push(
+            await handle({
+              id: 35,
+              method: "tools/call",
+              params: { name: "roadmap_describe", arguments: { op } },
+            })
+          );
+        }
+        return out;
       },
+      pass: (results) =>
+        Array.isArray(results) &&
+        results.length === 3 &&
+        results.every((r) => {
+          if (r?.result?.isError) return false;
+          try {
+            return (
+              JSON.parse(r.result.content?.[0]?.text ?? "")?.inputSchema?.type ===
+              "object"
+            );
+          } catch {
+            return false;
+          }
+        }),
     },
     {
       // Cross-workspace guard fires when snapshot.json names workspace
@@ -6400,6 +7767,161 @@ async function runSelftest() {
         }
       },
     },
+    {
+      // Repo-link gate: a mutator in an UNMAPPED git repo (slug resolves
+      // but no repo_workspace_map row, so resolution falls to env source)
+      // is blocked with repo_unmapped naming the slug + the link_repo fix.
+      name: "mutator blocked when in an unmapped repo (would hit env default)",
+      fn: async () => {
+        const savedWs = process.env.ROADMAPPER_WORKSPACE_ID;
+        const savedKey = process.env.ROADMAPPER_API_KEY;
+        const savedUrl = process.env.ROADMAPPER_BACKEND_URL;
+        try {
+          // Writes must be enabled or the gate defers to set_credentials.
+          process.env.ROADMAPPER_API_KEY = "rmpr_selftest";
+          process.env.ROADMAPPER_BACKEND_URL = "https://selftest.local";
+          process.env.ROADMAPPER_WORKSPACE_ID = "ws-envdefault";
+          session.rubricFetchedAt = Date.now(); // past the rubric gate
+          _clientRoots = ["/tmp/unmapped"];
+          __setRepoSlugForTest("acme/unmapped");
+          __setRootWorkspaceForTest(null); // no repo_workspace_map hit → env source
+          return await handle({
+            id: 94,
+            method: "tools/call",
+            params: {
+              name: "archive_task",
+              arguments: { taskId: aTask, reason: "unmapped-repo probe" },
+            },
+          });
+        } finally {
+          __setRepoSlugForTest(undefined);
+          __setRootWorkspaceForTest(undefined);
+          _clientRoots = [];
+          if (savedWs === undefined) delete process.env.ROADMAPPER_WORKSPACE_ID;
+          else process.env.ROADMAPPER_WORKSPACE_ID = savedWs;
+          if (savedKey === undefined) delete process.env.ROADMAPPER_API_KEY;
+          else process.env.ROADMAPPER_API_KEY = savedKey;
+          if (savedUrl === undefined) delete process.env.ROADMAPPER_BACKEND_URL;
+          else process.env.ROADMAPPER_BACKEND_URL = savedUrl;
+        }
+      },
+      pass: (r) => {
+        try {
+          const out = JSON.parse(r?.result?.content?.[0]?.text ?? "{}");
+          return (
+            out.error === "repo_unmapped" &&
+            out.repo === "acme/unmapped" &&
+            out.fix === 'roadmap({ op: "link_repo" })' &&
+            out.envDefaultWorkspace === "ws-envdefault"
+          );
+        } catch {
+          return false;
+        }
+      },
+    },
+    {
+      // ESCAPE HATCH 1 (the multi-repo case): an explicit workspaceId arg
+      // means the caller is intentionally targeting a workspace — the gate
+      // must NOT fire even in an unmapped repo. Proves a developer juggling
+      // several repos in one chat is never bricked: pass workspaceId and the
+      // write proceeds (lands downstream on the missing-service-key error in
+      // selftest, NOT the repo_unmapped block — that's the assertion).
+      name: "repo-link gate skipped when workspaceId passed explicitly",
+      fn: async () => {
+        try {
+          session.rubricFetchedAt = Date.now();
+          _clientRoots = ["/tmp/unmapped"];
+          __setRepoSlugForTest("acme/unmapped");
+          __setRootWorkspaceForTest(null);
+          return await handle({
+            id: 95,
+            method: "tools/call",
+            params: {
+              name: "archive_task",
+              arguments: {
+                taskId: aTask,
+                reason: "explicit-ws probe",
+                workspaceId: "ws-explicit",
+              },
+            },
+          });
+        } finally {
+          __setRepoSlugForTest(undefined);
+          __setRootWorkspaceForTest(undefined);
+          _clientRoots = [];
+        }
+      },
+      pass: (r) => {
+        // Must be an error result (no service key downstream) but NOT the
+        // repo_unmapped block — proves the gate let the explicit target through.
+        if (!r?.result?.isError) return false;
+        const txt = r.result.content?.[0]?.text ?? "";
+        return !txt.includes("repo_unmapped");
+      },
+    },
+    {
+      // ESCAPE HATCH 2: a MAPPED repo (resolution returns source "repo")
+      // never trips the gate — the whole point. Seeding a root workspace
+      // makes resolveWorkspaceWithSource return source:"repo", not "env".
+      name: "repo-link gate skipped when repo IS mapped (source=repo)",
+      fn: async () => {
+        try {
+          session.rubricFetchedAt = Date.now();
+          _clientRoots = ["/tmp/mapped"];
+          __setRepoSlugForTest("acme/mapped");
+          __setRootWorkspaceForTest("ws-mapped", "acme/mapped"); // mapped → source "repo"
+          return await handle({
+            id: 96,
+            method: "tools/call",
+            params: {
+              name: "archive_task",
+              arguments: { taskId: aTask, reason: "mapped-repo probe" },
+            },
+          });
+        } finally {
+          __setRepoSlugForTest(undefined);
+          __setRootWorkspaceForTest(undefined);
+          _clientRoots = [];
+        }
+      },
+      pass: (r) => {
+        if (!r?.result?.isError) return false;
+        const txt = r.result.content?.[0]?.text ?? "";
+        return !txt.includes("repo_unmapped");
+      },
+    },
+    {
+      // ESCAPE HATCH 3: not in a git repo at all (no client roots) — nothing
+      // to link, so the gate must fall through to the env default rather than
+      // deadlock. Asserts NOT repo_unmapped.
+      name: "repo-link gate skipped when not in a git repo (no deadlock)",
+      fn: async () => {
+        const savedWs = process.env.ROADMAPPER_WORKSPACE_ID;
+        try {
+          process.env.ROADMAPPER_WORKSPACE_ID = "ws-envdefault";
+          session.rubricFetchedAt = Date.now();
+          _clientRoots = []; // not in a repo
+          __setRootWorkspaceForTest(null);
+          return await handle({
+            id: 97,
+            method: "tools/call",
+            params: {
+              name: "archive_task",
+              arguments: { taskId: aTask, reason: "no-repo probe" },
+            },
+          });
+        } finally {
+          __setRootWorkspaceForTest(undefined);
+          if (savedWs === undefined) delete process.env.ROADMAPPER_WORKSPACE_ID;
+          else process.env.ROADMAPPER_WORKSPACE_ID = savedWs;
+        }
+      },
+      pass: (r) => {
+        if (!r?.result?.isError) return false;
+        const txt = r.result.content?.[0]?.text ?? "";
+        return !txt.includes("repo_unmapped");
+      },
+    },
   ];
 
   let passed = 0;