@ezmodo/mcp-server 0.17.1 → 0.18.0

package/config/endpoint-map.js

@@ -29,6 +29,11 @@ export const ENDPOINT_MAP = {
   'mcpSearchEpics': { route: 'mcp/v1/epics/search', method: 'POST' },
   'mcpListEpics': { route: 'mcp/v1/epics', method: 'GET' },
   'mcpGetEpic': { route: 'mcp/v1/epics/by-id', method: 'GET' },
+  // E-259: epic plan with revisions.
+  'mcpGetEpicPlan': { route: 'mcp/v1/epics/plan', method: 'GET' },
+  'mcpUpdateEpicPlan': { route: 'mcp/v1/epics/plan', method: 'PUT' },
+  'mcpListEpicComments': { route: 'mcp/v1/epics/comments', method: 'GET' },
+  'mcpAddEpicComment': { route: 'mcp/v1/epics/comments', method: 'POST' },
   // E-237 #2382: the epic is the fifth consumer of the grounding engine.
   'mcpGenerateEpicHowItWorks': { route: 'mcp/v1/epics/generate-how-it-works', method: 'POST' },
   'mcpApplyEpicHowItWorks': { route: 'mcp/v1/epics/apply-how-it-works', method: 'POST' },
@@ -209,6 +214,11 @@ export const ENDPOINT_MAP = {
   'mcpPromoteDecisionFromKnowledge': { route: 'mcp/v1/decisions/promote-from-knowledge', method: 'POST' },
   'mcpLinkDecisionArtifact': { route: 'mcp/v1/decisions/link', method: 'POST' },
   'mcpUnlinkDecisionArtifact': { route: 'mcp/v1/decisions/link', method: 'DELETE' },
+  // Decisions to make on an epic (E-259).
+  'mcpAddDecisionInput': { route: 'mcp/v1/decisions/inputs', method: 'POST' },
+  'mcpDecideDecision': { route: 'mcp/v1/decisions/decide', method: 'POST' },
+  'mcpHoldTaskForDecision': { route: 'mcp/v1/decisions/holds', method: 'POST' },
+  'mcpReleaseTaskFromDecision': { route: 'mcp/v1/decisions/holds', method: 'DELETE' },
 
   // Recurring task schedules (E-211) — "what task to create, on what cadence".
   'mcpCreateRecurringTask': { route: 'mcp/v1/recurring-tasks', method: 'POST' },
@@ -254,6 +264,10 @@ export const ENDPOINT_MAP = {
   'mcpDiscoverScreens': { route: 'mcp/v1/screens/discover', method: 'GET' },
   'mcpImportScreens': { route: 'mcp/v1/screens/import', method: 'POST' },
   'mcpSyncScreens': { route: 'mcp/v1/screens/sync', method: 'POST' },
+  'mcpListUnmappedPaths': { route: 'mcp/v1/unmapped-paths', method: 'GET' },
+  'mcpAssignUnmappedPath': { route: 'mcp/v1/unmapped-paths/assign', method: 'POST' },
+  'mcpDismissUnmappedPath': { route: 'mcp/v1/unmapped-paths/dismiss', method: 'POST' },
+  'mcpReconcileUnmappedPaths': { route: 'mcp/v1/unmapped-paths/reconcile', method: 'POST' },
   'mcpLinkCatalog': { route: 'mcp/v1/catalogs/link', method: 'POST' },
   'mcpUnlinkCatalog': { route: 'mcp/v1/catalogs/link', method: 'DELETE' },
   // Item-level links (E-218) — attach work or an external URL to one catalog entry

package/handlers/decisions.js

@@ -25,8 +25,13 @@ export async function manageDecision(args) {
   case 'unlink': return unlinkDecisionArtifact(params);
   case 'supersede': return supersedeDecision(params);
   case 'promote_from_knowledge': return promoteFromKnowledge(params);
+  case 'add_input': return addDecisionInput(params);
+  case 'decide': return decideDecision(params);
+  case 'hold_task': return holdTask(params);
+  case 'release_task': return releaseTask(params);
   default:
-    throw new Error(`Unknown action: ${action}. Expected create, update, delete, link, unlink, supersede, or promote_from_knowledge.`);
+    throw new Error(`Unknown action: ${action}. Expected create, update, delete, link, unlink, ` +
+      'supersede, promote_from_knowledge, add_input, decide, hold_task, or release_task.');
   }
 }
 
@@ -48,6 +53,13 @@ export async function getDecision(args) {
     return result;
   }
 
+  // Decisions to make on an epic (E-259).
+  if (filters.epicId) {
+    const params = { epicId: filters.epicId };
+    if (filters.status) params.status = filters.status;
+    return callZephlyAPI('mcpListDecisions', params);
+  }
+
   // List mode
   const params = {};
   if (organizationId) params.organizationId = organizationId;
@@ -66,6 +78,10 @@ export async function getDecision(args) {
 async function createDecision(args) {
   // `links` is applied by the MCP layer after the decision exists (E-225).
   const { links, ...createArgs } = args;
+  // On create the server takes option labels; accept {label} objects too.
+  if (Array.isArray(createArgs.choices)) {
+    createArgs.choices = createArgs.choices.map((c) => (typeof c === 'string' ? c : c?.label));
+  }
   const result = await callZephlyAPI('mcpCreateDecision', createArgs);
 
   // Attach create-time links (E-225) — best effort, never fails the create.
@@ -79,6 +95,11 @@ async function createDecision(args) {
 }
 
 async function updateDecision(args) {
+  // On update the server takes the full list as {id, label}; a bare string is
+  // a new option.
+  if (Array.isArray(args.choices)) {
+    args = { ...args, choices: args.choices.map((c) => (typeof c === 'string' ? { label: c } : c)) };
+  }
   return callZephlyAPI('mcpUpdateDecision', args);
 }
 
@@ -112,3 +133,24 @@ async function promoteFromKnowledge({ organizationId, taskId, knowledgeId, title
     linkToId,
   });
 }
+
+// --- Decisions to make on an epic (E-259) ---
+
+// Record a pick. It counts for the person whose key is used, and replaces
+// their earlier pick; the server records which AI made it.
+async function addDecisionInput({ decisionId, choiceId, reason }) {
+  return callZephlyAPI('mcpAddDecisionInput', { decisionId, choiceId, reason });
+}
+
+// Decide. The server refuses anyone but the epic's owner or an editor.
+async function decideDecision({ decisionId, status, choiceId, decision, rejectedReasons }) {
+  return callZephlyAPI('mcpDecideDecision', { decisionId, status, choiceId, decision, rejectedReasons });
+}
+
+async function holdTask({ decisionId, taskId }) {
+  return callZephlyAPI('mcpHoldTaskForDecision', { decisionId, taskId });
+}
+
+async function releaseTask({ decisionId, taskId }) {
+  return callZephlyAPI('mcpReleaseTaskFromDecision', { decisionId, taskId });
+}

package/handlers/epics.js

@@ -188,3 +188,51 @@ export async function getEpic(args) {
   if (webUrl && result?.epic) result.epic.webUrl = webUrl;
   return result;
 }
+
+/**
+ * Read an epic's plan with its current revision (E-259).
+ */
+export async function getEpicPlan(args) {
+  return callZephlyAPI('mcpGetEpicPlan', args);
+}
+
+/**
+ * Save an epic's plan against the revision it was read at (E-259). A conflict
+ * is returned as a result, not thrown: it is an expected outcome when several
+ * people's AIs share a plan, and the agent needs the current plan and what
+ * changed to redo its edit.
+ */
+export async function updateEpicPlan(args) {
+  try {
+    return await callZephlyAPI('mcpUpdateEpicPlan', args);
+  } catch (err) {
+    if (err?.code === 'PLAN_CONFLICT') {
+      const details = err.details || {};
+      return {
+        saved: false,
+        conflict: true,
+        message: `Someone else changed this plan since revision ${details.baseRevision}. ` +
+          'Nothing was saved. Apply your change to the current plan below and save again with ' +
+          `baseRevision ${details.currentRevision}. Do not resend your old copy.`,
+        currentRevision: details.currentRevision,
+        changesSince: details.changesSince || [],
+        currentPlan: details.current || null,
+      };
+    }
+    throw err;
+  }
+}
+
+/**
+ * Read an epic's discussion (E-259).
+ */
+export async function listEpicComments(args) {
+  return callZephlyAPI('mcpListEpicComments', args);
+}
+
+/**
+ * Post to an epic's discussion, or reply in a thread (E-259).
+ */
+export async function addEpicComment(args) {
+  return callZephlyAPI('mcpAddEpicComment', args);
+}

package/handlers/index.js

@@ -14,6 +14,7 @@ import * as featureHandlers from './features.js';
 import * as decisionHandlers from './decisions.js';
 import * as designHandlers from './designs.js';
 import * as catalogHandlers from './catalogs.js';
+import * as unmappedPathHandlers from './unmapped-paths.js';
 import * as featureFlagHandlers from './feature-flags.js';
 import * as taskHandlers from './tasks.js';
 import * as documentHandlers from './documents.js';
@@ -58,6 +59,10 @@ export const HANDLERS = {
   search_epics: epicHandlers.searchEpics,
   list_epics: epicHandlers.listEpics,
   get_epic: epicHandlers.getEpic,
+  get_epic_plan: epicHandlers.getEpicPlan,
+  update_epic_plan: epicHandlers.updateEpicPlan,
+  list_epic_comments: epicHandlers.listEpicComments,
+  add_epic_comment: epicHandlers.addEpicComment,
 
   // Milestones
   manage_milestone: milestoneHandlers.manageMilestone,
@@ -86,6 +91,8 @@ export const HANDLERS = {
   manage_catalog: catalogHandlers.manageCatalog,
   get_catalog: catalogHandlers.getCatalog,
   list_catalogs: catalogHandlers.listCatalogs,
+  list_unmapped_paths: unmappedPathHandlers.listUnmappedPaths,
+  resolve_unmapped: unmappedPathHandlers.resolveUnmapped,
   list_catalog_items: catalogHandlers.listCatalogItems,
   get_catalog_diff: catalogHandlers.getCatalogDiff,
 

package/handlers/unmapped-paths.js

@@ -0,0 +1,60 @@
+/**
+ * Unmapped code path handlers (E-258 #2756)
+ *
+ * Thin wrappers over /api/mcp/v1/unmapped-paths. Dispatch and validation live
+ * server-side in core/unmappedpaths.Service; these only shape the arguments.
+ */
+
+import { callZephlyAPI } from '../lib/http-client.js';
+
+/**
+ * List a project's unmapped paths, pending by default.
+ */
+export async function listUnmappedPaths({ projectId, status }) {
+  if (!projectId) {
+    throw new Error('projectId is required');
+  }
+  const params = { projectId };
+  if (status) params.status = status;
+  return callZephlyAPI('mcpListUnmappedPaths', params);
+}
+
+/**
+ * Dispatch resolve_unmapped actions.
+ */
+export async function resolveUnmapped(args) {
+  const { action, ...params } = args;
+  switch (action) {
+  case 'reconcile': return reconcileUnmappedPaths(params);
+  case 'assign': return assignUnmappedPath(params);
+  case 'dismiss': return dismissUnmappedPath(params);
+  default:
+    throw new Error(`Unknown action: ${action}. Expected reconcile, assign, or dismiss.`);
+  }
+}
+
+// Close every pending row an existing feature path already covers. Rows several
+// features could claim are left pending on purpose.
+async function reconcileUnmappedPaths({ projectId }) {
+  requireProject(projectId, 'reconcile');
+  return callZephlyAPI('mcpReconcileUnmappedPaths', { projectId });
+}
+
+async function assignUnmappedPath({ projectId, pathId, featureId }) {
+  requireProject(projectId, 'assign');
+  if (!pathId) throw new Error('pathId is required for assign');
+  if (!featureId) throw new Error('featureId is required for assign');
+  return callZephlyAPI('mcpAssignUnmappedPath', { projectId, pathId, featureId });
+}
+
+async function dismissUnmappedPath({ projectId, pathId }) {
+  requireProject(projectId, 'dismiss');
+  if (!pathId) throw new Error('pathId is required for dismiss');
+  return callZephlyAPI('mcpDismissUnmappedPath', { projectId, pathId });
+}
+
+function requireProject(projectId, action) {
+  if (!projectId) {
+    throw new Error(`projectId is required for ${action}`);
+  }
+}

package/lib/http-client.js

@@ -172,6 +172,12 @@ export async function callZephlyAPI(endpoint, data) {
     if (typeof error.retryable === 'boolean') {
       thrown.retryable = error.retryable;
     }
+    // Structured details, when the API sent an object rather than a sentence —
+    // a plan conflict (E-259) carries the current plan and what changed, which
+    // is exactly what the agent needs to redo its edit.
+    if (error.details && typeof error.details === 'object') {
+      thrown.details = error.details;
+    }
     throw thrown;
   }
 

package/lib/remote-tools.js

@@ -58,6 +58,7 @@ export const LOCAL_ONLY_TOOLS = Object.freeze([
 /** Tools safe to serve over the remote transport. */
 export const REMOTE_SAFE_TOOLS = Object.freeze([
   'accept_agent_suggestion',
+  'add_epic_comment',
   'configure_agent',
   'create_tasks',
   'delete_attachment',
@@ -75,6 +76,7 @@ export const REMOTE_SAFE_TOOLS = Object.freeze([
   'get_document',
   'get_document_template',
   'get_epic',
+  'get_epic_plan',
   'get_feature',
   'get_feature_flag',
   'get_goal',
@@ -93,7 +95,9 @@ export const REMOTE_SAFE_TOOLS = Object.freeze([
   'list_attachments',
   'list_catalog_items',
   'list_catalogs',
+  'list_unmapped_paths',
   'list_designs',
+  'list_epic_comments',
   'list_epics',
   'list_facts',
   'list_feature_flags',
@@ -139,10 +143,12 @@ export const REMOTE_SAFE_TOOLS = Object.freeze([
   'resolve_concepts',
   'resolve_link_suggestions',
   'resolve_links',
+  'resolve_unmapped',
   'run_agent_now',
   'search_epics',
   'search_features',
   'search_tasks',
+  'update_epic_plan',
   'update_manifest_entries',
   'validate_manifest',
 ]);

package/lib/version.js

@@ -7,4 +7,4 @@
  *
  * Update this when bumping the version in package.json.
  */
-export const MCP_VERSION = '0.17.1';
+export const MCP_VERSION = '0.18.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ezmodo/mcp-server",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "MCP server for ezmodo - AI-first project management",
   "main": "index.js",
   "type": "module",

package/tools/decisions.js

@@ -11,6 +11,11 @@
  * Decisions capture "why we built it this way" so the rationale survives the work
  * that produced it. A task's decision-type knowledge item can be elevated into a
  * durable Decision via promote_from_knowledge.
+ *
+ * Decisions to make (E-259): a proposed Decision asked on an epic, with a plain
+ * question, options, a recommendation and the people who should weigh in. Each
+ * of them, or their AI, adds a pick (add_input); the epic's owner or an editor
+ * decides (decide). A decision can hold tasks back until it is decided.
  */
 
 import { LINKABLE_TYPES } from './linkable-types.js';
@@ -23,17 +28,81 @@ export const DECISION_TOOLS = [
       'options, decision, consequences, status), link/unlink it to existing artifacts, mark it ' +
       'superseded by another decision, or promote a task\'s decision-type knowledge item into a ' +
       'durable Decision. Decisions are org-level and LINK to features/epics/tasks/milestones/etc., ' +
-      'they do not contain them.',
+      'they do not contain them.\n\n' +
+      'DECISIONS TO MAKE (open choices on an epic that several people weigh in on): create with ' +
+      'epicId + question + choices + recommendation + requestedFrom (the people whose view is ' +
+      'wanted; they are notified). Write the question, options and recommendation in plain ' +
+      'language a non-developer can answer. Then "add_input" records a pick (choiceId + a ' +
+      'one-line reason; your pick counts for the person whose key you use, and replaces their ' +
+      'earlier one). "decide" is for the epic\'s owner or an editor only: pass choiceId, ' +
+      'optionally decision (the answer in plain words) and rejectedReasons {choiceId: why}. ' +
+      '"hold_task" makes a task wait until the decision is made (it is blocked, and released on ' +
+      'decide); "release_task" undoes that. Do not decide on someone\'s behalf unless they asked ' +
+      'you to — add a pick instead.',
     inputSchema: {
       type: 'object',
       properties: {
         action: {
           type: 'string',
-          enum: ['create', 'update', 'delete', 'link', 'unlink', 'supersede', 'promote_from_knowledge'],
+          enum: ['create', 'update', 'delete', 'link', 'unlink', 'supersede', 'promote_from_knowledge',
+            'add_input', 'decide', 'hold_task', 'release_task'],
           description: 'Action to perform. "supersede" marks a decision as superseded by another ' +
             '(pass decisionId + supersededById). "promote_from_knowledge" elevates a task\'s ' +
             'decision-type knowledge item into a durable Decision (pass organizationId + taskId + ' +
-            'knowledgeId, optionally title + linkToType/linkToId to link it on creation).',
+            'knowledgeId, optionally title + linkToType/linkToId to link it on creation). ' +
+            '"add_input" (decisionId + choiceId + reason), "decide" (decisionId + choiceId), ' +
+            '"hold_task" / "release_task" (decisionId + taskId) are for decisions to make on an epic.',
+        },
+        // --- Decisions to make (E-259) ---
+        epicId: {
+          type: 'string',
+          description: 'Ask this decision on an epic (create). Its owner or an editor decides it; the ' +
+            'decision is scoped to the epic\'s project and linked to it.',
+        },
+        question: {
+          type: 'string',
+          description: 'The plain question to answer, e.g. "Who should review changes to the plan?" ' +
+            '(create, update)',
+        },
+        recommendation: {
+          type: 'string',
+          description: 'The recommended answer and why, in a sentence or two (create, update)',
+        },
+        choices: {
+          type: 'array',
+          items: {
+            oneOf: [
+              { type: 'string' },
+              {
+                type: 'object',
+                properties: { id: { type: 'string' }, label: { type: 'string' } },
+                required: ['label'],
+              },
+            ],
+          },
+          description: 'The options to pick from. On create, a list of plain labels. On update, the ' +
+            'full list as {id, label}: keep an option\'s id to keep the picks made for it; leave id ' +
+            'off to add one; omit an option to remove it (create, update)',
+        },
+        requestedFrom: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'User ids of the people whose view is wanted. They are notified (on update, ' +
+            'only the newly added ones) (create, update)',
+        },
+        choiceId: {
+          type: 'string',
+          description: 'An option id from the decision\'s choices, e.g. "c2" (add_input: your pick, ' +
+            'omit for "none of these" and say why in reason; decide: the chosen option)',
+        },
+        reason: {
+          type: 'string',
+          description: 'One line on why you picked it (add_input)',
+        },
+        rejectedReasons: {
+          type: 'object',
+          additionalProperties: { type: 'string' },
+          description: 'Why each option was turned down, as {choiceId: reason} (decide)',
         },
         // --- Identifiers ---
         organizationId: {
@@ -74,7 +143,9 @@ export const DECISION_TOOLS = [
         status: {
           type: 'string',
           enum: ['proposed', 'accepted', 'rejected', 'superseded', 'deprecated'],
-          description: 'Decision lifecycle status (default: "proposed") (create, update)',
+          description: 'Decision lifecycle status (default: "proposed") (create, update). For decide: ' +
+            '"accepted" (default) or "rejected" (none of the options). A decision to make on an epic ' +
+            'cannot change status through update; use decide.',
         },
         projectId: {
           type: 'string',
@@ -95,7 +166,8 @@ export const DECISION_TOOLS = [
         // --- promote_from_knowledge fields ---
         taskId: {
           type: 'string',
-          description: 'Task whose knowledge item to promote (required for promote_from_knowledge)',
+          description: 'Task whose knowledge item to promote (required for promote_from_knowledge), ' +
+            'or the task to hold back / release (hold_task, release_task)',
         },
         knowledgeId: {
           type: 'string',
@@ -121,8 +193,10 @@ export const DECISION_TOOLS = [
     name: 'get_decision',
     description: 'Retrieve a single Decision, list an organization\'s decisions, or list the decisions ' +
       'linked to a given entity (e.g. all decisions on a feature). Provide decisionId for a single ' +
-      'lookup; provide linkedType + linkedId to list decisions linked to that entity; otherwise ' +
-      'provide organizationId to list.',
+      'lookup; provide linkedType + linkedId to list decisions linked to that entity; provide ' +
+      'epicId to list the decisions to make on an epic (open ones first, each with everyone\'s ' +
+      'picks and the tasks it holds back; add status "proposed" for only the open ones); ' +
+      'otherwise provide organizationId to list.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -132,7 +206,11 @@ export const DECISION_TOOLS = [
         },
         organizationId: {
           type: 'string',
-          description: 'Organization ID (required for list, unless using linkedType + linkedId)',
+          description: 'Organization ID (required for list, unless using linkedType + linkedId or epicId)',
+        },
+        epicId: {
+          type: 'string',
+          description: 'List the decisions to make on this epic, with picks and held tasks',
         },
         linkedType: {
           type: 'string',

package/tools/epics.js

@@ -15,6 +15,28 @@
 import { LINKS_ARRAY_SCHEMA, RELATED_ITEM_SCHEMA } from './link-params.js';
 import { TASK_ITEM_PROPERTIES } from './task-item-schema.js';
 
+// A link staged on a plan or planned task before it exists (#2199, #2752).
+// Mirrors the desktop LinkDraft shape so a plan an AI saves back keeps the
+// links the desktop staged.
+const PLAN_LINKS_SCHEMA = {
+  type: 'array',
+  items: {
+    type: 'object',
+    properties: {
+      targetType: { type: 'string' },
+      targetId: { type: 'string' },
+      title: { type: 'string' },
+      source: { type: 'string', enum: ['deterministic', 'suggested', 'manual'] },
+      accepted: { type: 'boolean', description: 'false only for a suggestion that was turned down' },
+      rule: { type: 'string' },
+      confidence: { type: 'number' },
+      suggestionId: { type: 'string' },
+      matchedPaths: { type: 'array', items: { type: 'string' } },
+    },
+    required: ['targetType', 'targetId'],
+  },
+};
+
 export const EPIC_TOOLS = [
   {
     name: 'manage_epic',
@@ -259,4 +281,139 @@ export const EPIC_TOOLS = [
       },
     },
   },
+  {
+    name: 'get_epic_plan',
+    description: 'Read an epic\'s plan (E-259): the planned tasks, notes, status, staged links and any ' +
+      'open planner questions, with ' +
+      '`currentRevision`, the version number you must send back to `update_epic_plan`. ' +
+      'Several people and their AIs can work on one plan, so read it right before you change it. ' +
+      'Pass `includeHistory` to see who changed what, in plain sentences, and `revision` to read an older version.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        epicId: { type: 'string', description: 'The epic ID (required)' },
+        revision: { type: 'number', description: 'Read this saved version instead of the current one' },
+        includeHistory: {
+          type: 'boolean',
+          description: 'Also return recent versions: who saved each, which AI, and what changed',
+        },
+        historyLimit: { type: 'number', description: 'How many versions of history to return (default 20)' },
+      },
+      required: ['epicId'],
+    },
+  },
+  {
+    name: 'update_epic_plan',
+    description: 'Save an epic\'s plan as a new version (E-259). Send the WHOLE plan, changed where you ' +
+      'mean to change it, plus `baseRevision`: the `currentRevision` you read with `get_epic_plan` ' +
+      '(0 when the epic has no plan). Keep each planned task\'s `id` so the change is matched to the right task. ' +
+      'If someone else saved since you read it, nothing is written and you get `PLAN_CONFLICT` with the ' +
+      'current plan and what changed — apply your change to THAT plan and save again with its revision. ' +
+      'Never resend your old copy: that erases their work. ' +
+      'Keep plans simple and readable by anyone: a plain title and one line on why for each task. ' +
+      'Only the epic\'s owner, its creator or an organization admin can save the plan; anyone else ' +
+      'suggests the change with add_epic_comment or asks it as a decision to make (manage_decision).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        epicId: { type: 'string', description: 'The epic ID (required)' },
+        baseRevision: {
+          type: 'number',
+          description: 'The currentRevision you started from (required; 0 for a new plan)',
+        },
+        plan: {
+          type: 'object',
+          description: 'The full plan. Fields not listed here (conversation, targetFeatureId, …) ' +
+            'are kept only if you send them back.',
+          properties: {
+            notes: { type: 'string', description: 'Assumptions, risks and scope notes' },
+            status: { type: 'string', enum: ['draft', 'approved'], description: 'draft (default) or approved' },
+            proposedTasks: {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: {
+                  id: { type: 'string', description: 'Keep the id from get_epic_plan; omit for a new task' },
+                  title: { type: 'string' },
+                  workType: { type: 'string' },
+                  description: { type: 'string' },
+                  steps: { type: 'array', items: { type: 'string' } },
+                  rationale: { type: 'string', description: 'One line on why this task exists' },
+                  dependsOnIndices: { type: 'array', items: { type: 'number' } },
+                  needsHumanGate: { type: 'boolean' },
+                  links: {
+                    ...PLAN_LINKS_SCHEMA,
+                    description: 'Links to create with this task when the plan is approved. Send back ' +
+                      'what get_epic_plan returned',
+                  },
+                },
+                required: ['title'],
+              },
+            },
+            links: {
+              ...PLAN_LINKS_SCHEMA,
+              description: 'Links for the epic, applied when the plan is approved. Send back what ' +
+                'get_epic_plan returned',
+            },
+            questions: {
+              type: 'array',
+              description: 'The planner\'s open clarifying questions, kept as returned by get_epic_plan. ' +
+                'A choice that needs several people\'s view belongs on the epic as a decision to make ' +
+                '(manage_decision with epicId) instead.',
+              items: {
+                type: 'object',
+                properties: {
+                  id: { type: 'string' },
+                  question: { type: 'string' },
+                  header: { type: 'string' },
+                  options: {
+                    type: 'array',
+                    items: {
+                      type: 'object',
+                      properties: { label: { type: 'string' }, description: { type: 'string' } },
+                      required: ['label'],
+                    },
+                  },
+                  multiSelect: { type: 'boolean' },
+                },
+                required: ['question'],
+              },
+            },
+          },
+        },
+      },
+      required: ['epicId', 'baseRevision', 'plan'],
+    },
+  },
+  {
+    name: 'list_epic_comments',
+    description: 'Read an epic\'s discussion (E-259), oldest first. Each comment says who wrote it and, ' +
+      'when an AI wrote it for them, which AI (`agentName`). Replies carry `parentId`. ' +
+      'Read this before planning or changing a shared epic: other people\'s questions and objections live here.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        epicId: { type: 'string', description: 'The epic ID (required)' },
+        limit: { type: 'number', description: 'Maximum comments to return (default 100, max 500)' },
+      },
+      required: ['epicId'],
+    },
+  },
+  {
+    name: 'add_epic_comment',
+    description: 'Post to an epic\'s discussion (E-259), or reply to a comment with `parentId`. ' +
+      'Posted as the person whose key you use, marked as written by you. ' +
+      'Mentioned people, the author you reply to and everyone following the epic are notified, ' +
+      'and posting makes that person follow it. Write plainly: one point per comment, readable by anyone.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        epicId: { type: 'string', description: 'The epic ID (required)' },
+        content: { type: 'string', description: 'The comment (markdown)' },
+        parentId: { type: 'string', description: 'Reply to this comment' },
+        mentions: { type: 'array', items: { type: 'string' }, description: 'User IDs to notify' },
+      },
+      required: ['epicId', 'content'],
+    },
+  },
 ];

package/tools/index.js

@@ -16,6 +16,7 @@ import { FEATURE_TOOLS } from './features.js';
 import { DECISION_TOOLS } from './decisions.js';
 import { DESIGN_TOOLS } from './designs.js';
 import { CATALOG_TOOLS } from './catalogs.js';
+import { UNMAPPED_PATH_TOOLS } from './unmapped-paths.js';
 import { FEATURE_FLAG_TOOLS } from './feature-flags.js';
 import { TASK_TOOLS } from './tasks.js';
 import { DOCUMENT_TOOLS } from './documents.js';
@@ -53,6 +54,7 @@ export const TOOLS = [
   ...DECISION_TOOLS,
   ...DESIGN_TOOLS,
   ...CATALOG_TOOLS,
+  ...UNMAPPED_PATH_TOOLS,
   ...FEATURE_FLAG_TOOLS,
   ...TASK_TOOLS,
   ...RECURRING_TASK_TOOLS,

package/tools/unmapped-paths.js

@@ -0,0 +1,72 @@
+/**
+ * Unmapped code path tools (E-258 #2756)
+ *
+ * When Components were retired, every component source path that belonged to no
+ * feature was recorded for review instead of being dropped. Each row is one
+ * question — "which capability owns this code?" — and until it is answered, work
+ * touching those files auto-links to nothing.
+ *
+ * The list lived only on the project Features page, so an agent asked to tidy it
+ * could set feature paths but never see or close the rows. These two tools make
+ * that loop completable.
+ */
+
+export const UNMAPPED_PATH_TOOLS = [
+  {
+    name: 'list_unmapped_paths',
+    description: 'List a project\'s unmapped code paths — former component paths that no feature owns ' +
+      '(E-258). Each row carries the source path and the component it came from. A pending row means ' +
+      'work touching those files links to no capability, so this is the backlog to work through when ' +
+      'a project\'s features are missing code ownership.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: {
+          type: 'string',
+          description: 'Project ID (required)',
+        },
+        status: {
+          type: 'string',
+          enum: ['pending', 'assigned', 'dismissed', 'all'],
+          description: 'Which rows to return (default "pending")',
+        },
+      },
+      required: ['projectId'],
+    },
+  },
+  {
+    name: 'resolve_unmapped',
+    description: 'Resolve unmapped code paths (E-258). "reconcile" is the one to reach for first: it ' +
+      'closes every pending row a feature has SINCE been given a path for, so the usual flow is to set ' +
+      'ownership with manage_feature action:"paths" and then reconcile, rather than answering rows one ' +
+      'by one. A path several features own stays pending — shared ownership is a judgement, and those ' +
+      'only ever produce link suggestions anyway.\n\n' +
+      '"assign" gives ONE row to a feature (adding that feature path, with the usual scope check), and ' +
+      '"dismiss" records that the path belongs to no capability — the right answer for shared plumbing.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['reconcile', 'assign', 'dismiss'],
+          description: 'reconcile: close every pending row an existing feature path already covers. ' +
+            'assign: give one row (pathId) to featureId. dismiss: mark one row (pathId) as owned by nobody.',
+        },
+        projectId: {
+          type: 'string',
+          description: 'Project ID (required for every action)',
+        },
+        pathId: {
+          type: 'string',
+          description: 'Unmapped path ID, from list_unmapped_paths (required for assign and dismiss)',
+        },
+        featureId: {
+          type: 'string',
+          description: 'Feature to give the path to (required for assign). It must span the project, ' +
+            'or be org-wide.',
+        },
+      },
+      required: ['action', 'projectId'],
+    },
+  },
+];