@roadmapperai/mcp 0.9.4 → 0.9.5

package/AGENTS.md

@@ -7,6 +7,23 @@ The roadmap data model is the source of truth — TypeScript types in
 [`src/types.ts`](https://github.com/vsgro/roadmapper/blob/main/src/types.ts) are the canonical schema. Everything
 in this doc is downstream of that file.
 
+## How to call operations (dispatch surface)
+
+The `roadmapper` MCP server advertises **one** action tool: `roadmap({ op, args })`.
+Every operation named in this document — `get_roadmap_snapshot`, `suggest_capability_for`,
+`propose_task`, `propose_tasks`, `propose_capability`, `get_agents_md`, `link_repo`, etc. — is
+an `op` **value**, not a separately-advertised tool. Invoke it as
+`roadmap({ op: "<name>", args: { ... } })`. Two helpers round out the surface:
+
+- `roadmap_search({ intent })` — list/rank the available operations by what you're trying to do.
+- `roadmap_describe({ op })` — return one operation's exact input schema (its arguments).
+- `roadmap({ op, args })` — execute the operation. `args` may also be passed flat (top-level), but the documented shape is nested under `args`.
+
+So when a section below says "call `propose_tasks`" or shows `suggest_theme_for({ description })`,
+read it as `roadmap({ op: "propose_tasks", args: {...} })` /
+`roadmap({ op: "suggest_theme_for", args: { description } })`. The server enforces the
+rubric/discovery gates and per-op validation identically however you call.
+
 ## TL;DR — what an agent must do
 
 - Reference Themes / Capabilities / Tasks / Sprints by **stable ID**,

package/README.md

@@ -57,7 +57,22 @@ JSON config works, dropped into Cursor's `mcp` field.
 
 ## What this server exposes
 
-Read tools (always available):
+**The wire surface is three dispatch tools.** As of 0.9.5 the server advertises
+only:
+
+- `roadmap_search({ intent })` — list/rank the available operations by intent
+- `roadmap_describe({ op })` — return one operation's exact input schema
+- `roadmap({ op, args })` — execute an operation
+
+Everything below is an **`op` value** passed to `roadmap`, e.g.
+`roadmap({ op: "get_roadmap_snapshot" })` or
+`roadmap({ op: "propose_tasks", args: { capabilityId, tasks: [...] } })`. This
+keeps `tools/list` tiny (one schema instead of ~34) while the per-op schemas
+load on demand via `roadmap_describe`. The full planning contract ships in the
+server's `instructions` (sent at connect) and the `get_agents_md` op /
+`roadmapper://rubric` resource.
+
+### Read operations (always available)
 
 - `list_themes` — top-level strategic themes
 - `list_capabilities` — capabilities (optionally filtered by theme)
@@ -86,7 +101,7 @@ Read tools (always available):
 > for full rows and `limit` (max 200) to raise the cap. This keeps a
 > cold-start read from blowing the token budget on a large workspace.
 
-Write tools (require workspace-scoped write auth — set `ROADMAPPER_API_KEY`
+### Write operations (require workspace-scoped write auth — set `ROADMAPPER_API_KEY`
 to an `rmpr_…` key from the dashboard; writes then route through the
 mcp-broker so the service-role key never lives on your machine):
 
@@ -100,25 +115,26 @@ mcp-broker so the service-role key never lives on your machine):
 
 ## How agents are meant to use this
 
-The intended loop:
+The intended loop (every step is `roadmap({ op, args })`):
 
-1. Agent calls `get_agents_md` to load the rubric.
-2. Agent reads the current roadmap state via `list_themes` /
-   `list_capabilities` / `list_tasks`.
-3. Before proposing anything new, agent calls `suggest_capability_for`
+1. `roadmap({ op: "get_agents_md" })` to load the rubric.
+2. Read the current roadmap state: `roadmap({ op: "get_roadmap_snapshot" })`
+   (or `list_themes` / `list_capabilities` / `list_tasks` ops).
+3. Before proposing anything new, `roadmap({ op: "suggest_capability_for", args: { description } })`
    (or `suggest_theme_for`) to check if a matching parent already exists.
-   Skipping this is allowed for `propose_task` but the response will carry
-   a warn-on-skip nudge; `propose_capability` hard-requires it.
-4. Agent proposes new rows through the `propose_*` tools, including all
-   the rubric-required fields (RICE, acceptance criteria, etc.).
-5. Once a PR is merged, the agent calls `link_pr` to attach it; the
+   Skipping is allowed for `propose_task` but the response carries a
+   warn-on-skip nudge; `propose_capability` hard-requires it.
+4. Propose new rows via `roadmap({ op: "propose_tasks", args })` /
+   `roadmap({ op: "propose_capability", args })`, including all the
+   rubric-required fields (RICE, acceptance criteria, etc.).
+5. Once a PR is merged, `roadmap({ op: "link_pr", args })` to attach it; the
    roadmap delivery stats update automatically.
-6. After delivery, the agent self-grades against the acceptance criteria
-   with `submit_acceptance_grades`.
+6. After delivery, self-grade against the acceptance criteria with
+   `roadmap({ op: "submit_acceptance_grades", args })`.
 
 The server enforces the rubric: proposals filed without first fetching
-`get_agents_md` are rejected with a remediation hint pointing the agent
-back to the rubric.
+`get_agents_md` are rejected with a structured remediation hint whose `fix`
+field names the exact dispatch call to make next.
 
 ## Versioning
 
@@ -134,6 +150,16 @@ the check with `ROADMAPPER_DISABLE_UPDATE_CHECK=1`.
 
 ### Recent changes
 
+- **0.9.5** — **tool-surface collapse for token efficiency.** `tools/list` now
+  advertises three dispatch tools (`roadmap_search` / `roadmap_describe` /
+  `roadmap`) instead of ~34, cutting the always-loaded tool definitions ~97%
+  (~15k → ~0.5k tokens) and the per-session planning footprint ~95%. The ~34
+  operations are unchanged — they're reached as `roadmap({ op, args })`, with
+  schemas served on demand via `roadmap_describe`. Per-tool methodology moved
+  into the server `instructions` (now correctly top-level) plus the
+  `roadmapper://rubric` resource. Already-linked repos should re-run
+  `npm run mcp:setup -- --link <path>` to refresh the permission allow-list and
+  the CLAUDE.md block for the dispatch surface.
 - **0.9.3** — new `link_repo` tool: when `get_active_workspace` reports
   `env_default`/`unresolved` and you're in a git repo, one call persists
   the repo → workspace mapping so future sessions resolve silently (the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roadmapperai/mcp",
-  "version": "0.9.4",
+  "version": "0.9.5",
   "description": "Roadmapper AI MCP server — exposes a planning surface (themes, capabilities, tasks, sprints, PRs) to coding agents via stdio JSON-RPC. Pairs with the Roadmapper AI workspace at dashboard.roadmapperai.com.",
   "keywords": [
     "mcp",

package/server.mjs

@@ -469,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
@@ -1340,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;
 }
@@ -1479,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
@@ -1495,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
@@ -1523,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,
@@ -1566,12 +1649,12 @@ function repoUnmappedResult(toolName, slug, envWsId) {
             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 link_repo (this repo → your key's workspace, resolves silently forever after), then retry ${toolName}. ` +
-              `Or, if you meant a specific existing workspace, pass workspaceId on the call and it proceeds without mapping the repo.`,
+              `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: "link_repo()",
-            alt: `${toolName}({ workspaceId: "<target>", ... })`,
+            fix: opCall("link_repo"),
+            alt: opCall(toolName, '{ workspaceId: "<target>", ... }'),
           },
           null,
           2
@@ -2009,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" },
@@ -2040,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,
@@ -2582,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,
@@ -2881,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 (
@@ -2901,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."
       );
     }
@@ -3055,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.',
           },
         },
       });
@@ -3234,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.`
     );
   }
 
@@ -3523,11 +3809,11 @@ async function proposeTheme(args, projected, wsId) {
             `"${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 (propose_capability with " +
-            `pillarId: "${nearest.id}"), or broaden its scope with update_theme. If this is ` +
+            "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: `propose_capability({ pillarId: "${nearest.id}", ... })`,
+          fix: opCall("propose_capability", `{ pillarId: "${nearest.id}", ... }`),
         },
         null,
         2
@@ -3555,7 +3841,7 @@ async function proposeTheme(args, projected, wsId) {
           ...(nearest
             ? { closestExisting: { id: nearest.id, name: nearest.name, score: Number(nearestScore.toFixed(3)) } }
             : {}),
-          fix: "propose_theme({ ...same args, confirm: true })",
+          fix: opCall("propose_theme", "{ ...same args, confirm: true }"),
         },
         null,
         2
@@ -3631,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)) {
@@ -3871,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.",
             },
           },
@@ -3947,7 +4233,7 @@ function suggestThemeFor(args, projected) {
             roadmapper: {
               reminder: autonomy
                 ? ranked.length === 0
-                  ? "No existing theme overlaps. Theme-autonomy is ON, so you may call 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 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."
@@ -4616,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.`,
             },
           },
         }
@@ -4797,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
@@ -4816,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}.`
       );
     }
   }
@@ -4863,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",
   },
 ];
@@ -5001,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."
@@ -5070,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,
@@ -5083,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."
-              );
-            })(),
           },
         },
       };
@@ -5128,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),
       }));
@@ -5197,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,
@@ -5485,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",
@@ -6477,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.
@@ -6552,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
@@ -7149,7 +7811,7 @@ async function runSelftest() {
           return (
             out.error === "repo_unmapped" &&
             out.repo === "acme/unmapped" &&
-            out.fix === "link_repo()" &&
+            out.fix === 'roadmap({ op: "link_repo" })' &&
             out.envDefaultWorkspace === "ws-envdefault"
           );
         } catch {