@roadmapperai/mcp 0.9.3 → 0.9.4

package/AGENTS.md

@@ -85,6 +85,13 @@ that's almost always what you actually want.
   CANDIDATE for `propose_capability` (human-confirmed) followed by
   `move_tasks`. Tune `minClusterSize` (default 3) / `fitThreshold`
   (default 0.2) to control sensitivity.
+- `detect_theme_sprawl` — the theme-level companion. Scores every
+  active theme against every other and flags pairs that overlap enough
+  to be consolidation candidates, each with a suggested merge
+  (`move_capabilities` the lighter theme's bets into the heavier, then
+  `archive_theme`). This is how you keep theme count in check now that
+  agents create themes autonomously (see `propose_theme`). Run it at
+  quarterly review. Tune `threshold` (default 0.34).
 - `get_agents_md` — re-read this contract on demand.
 
 **Multi-workspace addressing.** A single MCP install can talk to any
@@ -137,18 +144,37 @@ to "tell the human what I'd do"):
   succeeds (this is a nudge, not a gate — unlike `propose_capability`,
   which hard-blocks until you've done discovery). Surface the warning
   to the user.
+- `propose_tasks` — **bulk** create many tasks under ONE capability in
+  a single call. **This is the token-efficient path: prefer it over N
+  separate `propose_task` calls when filing a plan** — one request, one
+  compact `{id,title}` array back. Each task spec needs `title` +
+  `effort`; intra-batch dependencies work by giving a task a `ref` and
+  listing that ref in a sibling's `dependsOn` (refs are rewritten to
+  real ids after minting). A validation error fails the whole batch
+  before writing; once valid, per-row RPC failures are reported in
+  `tasks[].error` without sinking the rest.
 - `propose_capability` — create a new capability under an **existing**
   theme. Required: `name`, `pillarId`. Sensible defaults are applied
   (`reach: 100`, `impact: 1`, `confidence: 70`). Pass `outcome` and
   `specRef` whenever you have them — capabilities without an outcome
   rarely survive review. Pass `idempotencyKey`.
-- `propose_theme` — create a new theme. **Use sparingly.** Themes are
-  years-stable strategic categories; almost every plan fits under an
-  existing one. Only call this when the human explicitly asks for a
-  new theme or when the work genuinely doesn't fit any of the existing
-  ones from `list_themes`. Default rule: if you're tempted to create
-  a theme, file a capability under the closest existing theme instead
-  and let the human reorganize later.
+- `propose_theme` — create a new theme. **Theme-autonomy is ON by
+  default**, so you MAY create a theme without human confirmation when
+  the work genuinely needs a new years-stable pillar. You don't police
+  sprawl by asking a human every time — the server does it for you:
+  `propose_theme` returns `error: "too_similar"` (naming the match) if
+  your theme overlaps an existing one above the block bar, so you reuse
+  or `update_theme` that one instead. Still prefer the deepest existing
+  parent (new task > new capability > new theme); a theme is the rare
+  case. If a workspace turned autonomy OFF (Settings → Agent
+  automation), `propose_theme` returns `error: "confirmation_required"`
+  until you surface the new theme to the user and retry with
+  `confirm: true`. Use `force: true` only to override a `too_similar`
+  block that's a genuine false positive. Run `detect_theme_sprawl`
+  periodically to catch themes that have drifted into overlap.
+- `submit_acceptance_grades` — stamp `{ status: pass | fail, note? }`
+  per criterion index, after you've actually verified the work. The
+  server stamps `gradedAt` and `gradedBy: "mcp:agent"`.
 - `submit_acceptance_grades` — stamp `{ status: pass | fail, note? }`
   per criterion index, after you've actually verified the work. The
   server stamps `gradedAt` and `gradedBy: "mcp:agent"`.
@@ -223,6 +249,45 @@ disagrees with the cwd snapshot are refused — set
 `ROADMAPPER_ALLOW_CROSS_WORKSPACE=1` in the env to override.
 Reads can target any workspace freely.
 
+**Repo-link gate (write path).** If you're in a git repo that
+isn't mapped to a workspace, a mutator would silently land on the
+install's env-default workspace — almost never what you want. So
+the first such write is **refused** with a structured error:
+
+```json
+{
+  "error": "repo_unmapped",
+  "message": "\"owner/name\" isn't mapped to a workspace ...",
+  "fix": "link_repo()",
+  "alt": "<tool>({ workspaceId: \"<target>\", ... })"
+}
+```
+
+Resolve it one of two ways, then retry:
+- **`link_repo()`** — maps the repo you're in to your key's
+  workspace, so every future session resolves silently. This is
+  the right move when the repo *should* feed this workspace.
+- **Pass `workspaceId` explicitly** on the call — proceeds without
+  mapping the repo. This is the escape hatch when you're working
+  across **several repos in one session** and just want this write
+  to land on a specific existing workspace.
+
+The gate is repo-aware and only fires for a genuinely unmapped
+repo: an explicit `workspaceId`, an already-mapped repo (resolves
+via `repo_workspace_map`), or not being in a git repo at all
+pass straight through — a multi-repo chat is never bricked.
+Operators can disable the gate entirely with
+`ROADMAPPER_ALLOW_UNMAPPED_REPO=1`.
+
+This gate and the **seed-workspace guard** below are complementary,
+not redundant: the repo-link gate covers the *in a git repo but
+unmapped* case (and gives the more actionable `link_repo` fix),
+while the seed-workspace guard still catches a write that fell
+through to the bundled `"default"` workspace when you're **not** in
+any repo (nothing to link). A write can be refused by at most one of
+them; both protect the same env-default footgun from different
+angles.
+
 Authoring discipline:
 - Read first (`list_themes`, `list_capabilities`, `list_tasks`) before
   proposing anything, so you don't invent a new theme/capability that
@@ -402,12 +467,17 @@ Before writing anything:
    - **Top score 0.2–0.4**: weak overlap. The top match is still
      usually the right home; re-using a "close-enough" theme is
      almost always better than creating a duplicate.
-   - **Empty matches or top < 0.2**: no existing theme fits. Stop
-     and ask the user explicitly whether this represents a new
-     strategic direction worth a years-stable theme. Only call
-     `propose_theme` after the user confirms — themes are
-     years-stable, not per-feature.
-   The propose_theme tool enforces this discovery: skipping
+   - **Empty matches or top < 0.2**: no existing theme fits. With
+     theme-autonomy ON (the default), you may call `propose_theme`
+     directly when this is a genuinely new years-stable pillar — you
+     don't need to stop and ask. The server is the sprawl guard: it
+     refuses a near-duplicate (`error: "too_similar"`), so a theme that
+     gets created is one that doesn't already exist. With autonomy OFF,
+     `propose_theme` returns `error: "confirmation_required"` — surface
+     the theme to the user and retry with `confirm: true`. Either way,
+     prefer a capability under the closest theme when one is even
+     plausibly a fit; a new theme is the rare case.
+   The propose_theme tool enforces discovery: skipping
    `suggest_theme_for` (or `list_themes` / `get_roadmap_snapshot`)
    returns a `discovery_missing` error.
 2. **Decompose into Capabilities.** A Capability is "a quarterly
@@ -427,9 +497,18 @@ Before writing anything:
 
 ### What to emit (template)
 
-Return a single JSON block. The user will paste it into Roadmapper's
-import or read it manually; either way the field names must match
-exactly. IDs use the `__NEW__` placeholder prefix when you're
+**If the write tools are live (you can call `propose_capability` /
+`propose_tasks`), FILE DIRECTLY — do not also emit this JSON block.**
+Dumping the full plan as JSON *and* filing it via tools pays for the
+plan twice in tokens, and the tools are the canonical path anyway. Use
+`propose_capability` for the bet, then ONE `propose_tasks` call for all
+its tasks (not N `propose_task` calls), and report back a short summary
+with the returned ids — not the whole record set. The JSON block below
+is only for the **no-write-tools** case (seed/live-read tier), where
+the user pastes it into Roadmapper's import manually.
+
+When you do emit it: return a single JSON block. The field names must
+match exactly. IDs use the `__NEW__` placeholder prefix when you're
 proposing a new record — Roadmapper assigns the real `TH-NNNNNN` /
 `CAP-NNN` / `TK-NNNNNN` ID at import time.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roadmapperai/mcp",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "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

@@ -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;
@@ -853,6 +860,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 +884,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 +911,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,
@@ -1396,6 +1425,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
@@ -1485,6 +1535,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 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.`,
+            repo: slug,
+            envDefaultWorkspace: envWsId,
+            fix: "link_repo()",
+            alt: `${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 +1900,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 +1973,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" },
@@ -2019,6 +2218,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 +2561,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",
@@ -2619,6 +2844,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.
@@ -2836,6 +3082,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 +3147,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}`);
   }
@@ -3087,16 +3340,235 @@ async function proposeTask(args, projected, wsId) {
   );
 }
 
-async function proposeTheme(args, _projected /* unused — themes carry no parent */, wsId) {
+/**
+ * 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;
+}
+
+/** 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,
+    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,
+        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.`,
+      }),
+    );
+  }
+
+  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 (propose_capability with " +
+            `pillarId: "${nearest.id}"), or broaden its scope with update_theme. 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}", ... })`,
+        },
+        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: "propose_theme({ ...same args, confirm: true })",
+        },
+        null,
+        2
+      ),
+      { isError: true }
+    );
+  }
+
   const id = randomThemeId();
   const theme = {
     id,
     name,
-    description: cleanText(args.description),
+    description,
     color: args.color || "#6366f1", // brand-indigo default; user can change
     ...(typeof args.targetRoi === "number" ? { targetRoi: args.targetRoi } : {}),
   };
@@ -3461,18 +3933,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 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 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 +3962,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
@@ -4152,6 +4636,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.`);
@@ -4734,6 +5298,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: {} }),
@@ -6400,6 +7105,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 === "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;