kanbango 3.6.2 → 5.1.0

package/mcp-server.js

@@ -11,13 +11,16 @@ const plan = require('./plan.js');
 const guiRegistry = require('./gui-registry.js');
 const playbook = require('./agent-playbook.js');
 
-const COLS = kanban.COLS;
 const READ_VIEWS = Object.keys(kanban.VIEW_FIELDS);
 const GUI_READY_TIMEOUT_MS = 8000;
 const GUI_READY_POLL_MS = 50;
 let guiProcess = null;
 let guiPort = null;
 
+function activeCols() {
+  return kanban.COLS.slice();
+}
+
 function normalizePort(value) {
   return guiRegistry.normalizeGuiPort(value);
 }
@@ -60,8 +63,37 @@ async function waitForGuiReady(pid, timeoutMs = GUI_READY_TIMEOUT_MS) {
   );
 }
 
+function nextToolCall(error) {
+  const code = error && error.code;
+  const details = (error && error.details) || {};
+
+  if (code === 'TASK_NOT_FOUND') {
+    return {
+      tool: 'kanban_read',
+      arguments: { operation: 'list', col: 'planned' }
+    };
+  }
+
+  if (code === 'INVALID_TRANSITION') {
+    const allowed = details.allowed_columns;
+    if (!Array.isArray(allowed) || allowed.length === 0 || !details.task_id) {
+      return undefined;
+    }
+    return {
+      tool: 'kanban_manage',
+      arguments: {
+        action: 'move',
+        task_id: details.task_id,
+        column: allowed[0]
+      }
+    };
+  }
+
+  return undefined;
+}
+
 function serializeError(error) {
-  return {
+  const payload = {
     error: {
       code: error.code || 'INTERNAL_ERROR',
       message: error.message,
@@ -70,6 +102,9 @@ function serializeError(error) {
       retryable: Boolean(error.retryable)
     }
   };
+  const next = nextToolCall(error);
+  if (next) payload.error.next_tool_call = next;
+  return payload;
 }
 
 function invalidRequest(message, hint, details) {
@@ -79,7 +114,7 @@ function invalidRequest(message, hint, details) {
 function serializeResult(result) {
   if (typeof result === 'string') return result;
 
-  const text = JSON.stringify(result, null, 2);
+  const text = JSON.stringify(result);
   if (typeof text === 'string') return text;
 
   throw kanban.createKanbanError(
@@ -105,7 +140,7 @@ function textResponse(result, isError = false) {
 }
 
 function normalizeReturnShape(returnShape) {
-  if (returnShape === undefined) return 'summary';
+  if (returnShape === undefined) return 'none';
   if (!['none', 'summary', 'full'].includes(returnShape)) {
     throw invalidRequest(
       `Unsupported return value: ${returnShape}`,
@@ -150,13 +185,108 @@ async function buildEpicLookup() {
   return lookup;
 }
 
+function withMissing(payload, missing) {
+  if (!missing || missing.length === 0) return payload;
+  return { ...payload, missing };
+}
+
+function formatCreateAck(id, missing) {
+  return withMissing({ ok: true, id }, missing);
+}
+
+function readFields(readOptions) {
+  if (Array.isArray(readOptions.fields) && readOptions.fields.length > 0) {
+    return readOptions.fields;
+  }
+  return kanban.VIEW_FIELDS[readOptions.view || 'summary'] || kanban.VIEW_FIELDS.summary;
+}
+
+function viewNeedsEpicLookup(readOptions) {
+  return readFields(readOptions).includes('epic_goals');
+}
+
+function viewNeedsAllTasks(readOptions) {
+  const fields = readFields(readOptions);
+  return fields.includes('blocked')
+    || fields.includes('unmet_dependencies')
+    || fields.includes('blocks');
+}
+
+function findTaskOnBoard(taskId, allTasks) {
+  const raw = String(taskId);
+  const exact = allTasks.find((task) => task.id === raw);
+  if (exact) return exact;
+  const num = parseInt(raw, 10);
+  if (!Number.isFinite(num)) return null;
+  return allTasks.find((task) => task.task_number === num) || null;
+}
+
+function omitEmptyPlanFields(payload) {
+  const out = {};
+  for (const [key, value] of Object.entries(payload)) {
+    if (value === undefined || value === null || value === '') continue;
+    if (Array.isArray(value) && value.length === 0) continue;
+    out[key] = value;
+  }
+  return out;
+}
+
+function compactPlanEvidence(evidence) {
+  if (!evidence || typeof evidence !== 'object' || Array.isArray(evidence)) return undefined;
+  return omitEmptyPlanFields({
+    summary: evidence.summary,
+    test_command: evidence.test_command,
+    has_diff: evidence.diff ? true : undefined
+  });
+}
+
+function formatPlanResult(planResult, returnShape) {
+  if (!planResult || typeof planResult !== 'object') return planResult;
+  if (returnShape === 'full') return planResult;
+  const out = { ok: planResult.ok !== false };
+  if (planResult.task_id) out.task_id = planResult.task_id;
+  if (planResult.runner !== undefined) out.runner = planResult.runner;
+  if (planResult.current_step !== undefined && planResult.current_step !== -1) {
+    out.current_step = planResult.current_step;
+  }
+  if (planResult.status) out.status = planResult.status;
+  if (planResult.column) out.column = planResult.column;
+  if (Array.isArray(planResult.unblocked_tasks) && planResult.unblocked_tasks.length > 0) {
+    out.unblocked_tasks = planResult.unblocked_tasks;
+  }
+  if (planResult.warnings) out.warnings = planResult.warnings;
+  if (planResult.missing_recommended) out.missing = planResult.missing_recommended;
+  if (returnShape === 'none') return omitEmptyPlanFields(out);
+  if (Array.isArray(planResult.subtasks)) {
+    out.progress = {
+      done: planResult.subtasks.filter((step) => step.done).length,
+      total: planResult.subtasks.length
+    };
+  }
+  out.evidence = compactPlanEvidence(planResult.evidence);
+  return omitEmptyPlanFields(out);
+}
+
 async function formatTaskResult(task, returnShape) {
-  if (returnShape === 'none') return { ok: true };
-  const epicLookup = await buildEpicLookup();
-  return kanban.shapeTask(task, {
-    view: returnShape === 'full' ? 'full' : 'summary',
-    epicLookup
+  if (returnShape === 'none') {
+    if (Array.isArray(task.unblocked_tasks) && task.unblocked_tasks.length > 0) {
+      return { ok: true, unblocked_tasks: task.unblocked_tasks };
+    }
+    return { ok: true };
+  }
+  const view = returnShape === 'full' ? 'full' : 'summary';
+  const readOptions = { view };
+  const epicLookup = viewNeedsEpicLookup(readOptions) ? await buildEpicLookup() : undefined;
+  const allTasks = viewNeedsAllTasks(readOptions) ? await kanban.allTasks() : undefined;
+  const shaped = kanban.shapeTask(task, {
+    view,
+    epicLookup,
+    allTasks
   });
+  if (Array.isArray(task.unblocked_tasks)) {
+    shaped.unblocked_tasks = task.unblocked_tasks;
+  }
+  return shaped;
 }
 
 function guiIdentity(extra = {}) {
@@ -168,6 +298,21 @@ function guiIdentity(extra = {}) {
   };
 }
 
+function discoveredGuiPayload(discovered, extra = {}) {
+  if (!discovered) return { status: 'not_running' };
+  return guiIdentity({
+    status: extra.status || 'external_running',
+    owned: extra.owned === undefined ? false : extra.owned,
+    port: discovered.port,
+    pid: discovered.pid,
+    url: discovered.url,
+    cwd: discovered.cwd,
+    project: discovered.project,
+    started_at: discovered.started_at,
+    ...extra
+  });
+}
+
 async function startGuiServer(port) {
   if (port !== undefined && port !== null && port !== '' && !normalizePort(port)) {
     throw invalidRequest('Invalid port', 'Use an integer between 1 and 65535', { port });
@@ -254,21 +399,7 @@ async function stopGuiServer() {
 
   guiProcess = null;
   guiPort = null;
-
-  const discovered = await guiRegistry.discoverRunningGui();
-  if (!discovered) {
-    return { status: 'not_running' };
-  }
-
-  return guiIdentity({
-    status: 'external_running',
-    owned: false,
-    port: discovered.port,
-    pid: discovered.pid,
-    url: discovered.url,
-    cwd: discovered.cwd,
-    project: discovered.project,
-    started_at: discovered.started_at,
+  return discoveredGuiPayload(await guiRegistry.discoverRunningGui(), {
     hint: 'GUI was not started by this MCP process; stop refused. Stop it from the owning terminal or kill that PID manually.'
   });
 }
@@ -286,22 +417,7 @@ async function guiStatus() {
 
   guiProcess = null;
   guiPort = null;
-
-  const discovered = await guiRegistry.discoverRunningGui();
-  if (!discovered) {
-    return { status: 'not_running' };
-  }
-
-  return guiIdentity({
-    status: 'external_running',
-    owned: false,
-    port: discovered.port,
-    pid: discovered.pid,
-    url: discovered.url,
-    cwd: discovered.cwd,
-    project: discovered.project,
-    started_at: discovered.started_at
-  });
+  return discoveredGuiPayload(await guiRegistry.discoverRunningGui());
 }
 
 const server = new Server(
@@ -317,6 +433,8 @@ const server = new Server(
 );
 
 server.setRequestHandler(ListToolsRequestSchema, async () => {
+  await require('./workflow.js').ensureBoardConfig();
+  const COLS = activeCols();
   return {
     tools: [
       {
@@ -327,52 +445,36 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           properties: {
             operation: {
               type: 'string',
-              enum: ['list', 'show', 'list_epics', 'show_epic', 'help'],
-              description: 'list/show=tasks; list_epics/show_epic=initiative containers; help=token playbook',
-              default: 'list'
-            },
-            task_id: {
-              type: 'string',
-              description: "Required for show. Numeric id: '014' or '14'."
-            },
-            epic_id: {
-              type: 'string',
-              description: "Required for show_epic. Epic id like 'E001'."
-            },
-            col: {
-              type: 'string',
-              enum: COLS,
-              description: 'Filter list by column (saves tokens — prefer this)'
-            },
-            epic: {
-              type: 'string',
-              description: 'Filter list by epic id or title'
-            },
-            include_archived: {
-              type: 'boolean',
-              description: 'list/list_epics: include archived epics and their tasks (default false)'
-            },
-            include_done: {
-              type: 'boolean',
-              description: 'list_epics: include status=done epics without archived (default false)'
+              enum: ['list', 'show', 'list_epics', 'show_epic', 'context', 'help'],
+              default: 'context'
             },
+            task_id: { type: 'string' },
+            epic_id: { type: 'string' },
+            col: { type: 'string', enum: COLS },
+            epic: { type: 'string' },
+            include_archived: { type: 'boolean' },
+            include_done: { type: 'boolean' },
             status: {
               type: 'string',
-              enum: ['empty', 'planned', 'active', 'done', 'archived'],
-              description: 'list_epics: exact status filter (overrides live-only default)'
-            },
-            view: {
-              type: 'string',
-              enum: READ_VIEWS,
-              description: 'summary=board scan (default); planning=scope/AC; execution=+subtasks; full=everything. Prefer smallest that works.'
+              enum: ['empty', 'planned', 'active', 'done', 'archived']
             },
+            view: { type: 'string', enum: READ_VIEWS },
             fields: {
               type: 'array',
-              description: 'Exact fields only (overrides view). Use when you need 1–2 fields.',
               items: { type: 'string' }
             }
           },
-          additionalProperties: false
+          additionalProperties: false,
+          examples: [
+            { operation: 'context' },
+            { operation: 'show', task_id: '014' },
+            { operation: 'list', col: 'active' }
+          ],
+          if: {
+            properties: { operation: { const: 'show' } },
+            required: ['operation']
+          },
+          then: { required: ['task_id'] }
         }
       },
       {
@@ -398,63 +500,48 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 'plan_evidence',
                 'plan_done',
                 'plan_status'
-              ],
-              description: 'create|move|update|delete daily; epic_create|epic_update|epic_archive|epic_unarchive|epic_delete; plan_* multi-step'
-            },
-            title: {
-              type: 'string',
-              description: 'Required for create, plan_create, epic_create'
+              ]
             },
+            title: { type: 'string' },
             col: {
               type: 'string',
               enum: COLS,
-              default: 'planned',
-              description: 'create column, or update shortcut for column'
+              default: 'planned'
             },
             epic: {
               type: 'string',
-              default: '—',
-              description: 'Epic id or title (create/update/plan_create). Prefer E001.'
-            },
-            epic_id: {
-              type: 'string',
-              description: 'Required for epic_update|epic_archive|epic_unarchive|epic_delete; optional link id'
-            },
-            description: {
-              type: 'string',
-              description: 'Why/context (recommended on create / epic_create)'
-            },
-            goals: {
-              type: 'string',
-              description: 'Epic outcome one-liner (recommended on epic_create)'
-            },
-            specs: {
-              type: 'string',
-              description: 'Technical constraints (recommended on create)'
+              default: '—'
             },
+            epic_id: { type: 'string' },
+            description: { type: 'string' },
+            goals: { type: 'string' },
+            specs: { type: 'string' },
             in_scope: {
               type: 'array',
-              description: 'In-scope bullets (recommended on create)',
               items: { type: 'string' }
             },
             out_of_scope: {
               type: 'array',
-              description: 'Out-of-scope bullets (recommended on create)',
               items: { type: 'string' }
             },
             acceptance_criteria: {
               type: 'array',
-              description: 'Done criteria (recommended on create)',
               items: { type: 'string' }
             },
             test_cases: {
               type: 'array',
-              description: 'Verification scenarios',
+              items: { type: 'string' }
+            },
+            depends_on: {
+              type: 'array',
+              items: { type: 'string' }
+            },
+            files: {
+              type: 'array',
               items: { type: 'string' }
             },
             subtasks: {
               type: 'array',
-              description: 'Full subtask list replace on update (send complete array, not a single toggle)',
               items: {
                 type: 'object',
                 properties: {
@@ -465,13 +552,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 }
               }
             },
-            notes: {
-              type: 'string',
-              description: 'Freeform notes'
-            },
+            notes: { type: 'string' },
             adr: {
-              description:
-                'Append one ADR: { decision, why }. Or replace full array of { id?, decision, why, created? }.',
               oneOf: [
                 {
                   type: 'object',
@@ -495,63 +577,55 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 }
               ]
             },
-            task_id: {
-              type: 'string',
-              description: "Required for move/update/delete/plan_* except plan_create. '014' or '14'."
-            },
-            column: {
-              type: 'string',
-              enum: COLS,
-              description:
-                'Target column for move (not col). Must be a legal transition from the current column. '
-                + 'icebox→planned; planned→active|icebox|testing; active→planned|testing|icebox; '
-                + 'testing→active|review; review→active|done; done→active. Illegal → INVALID_TRANSITION + allowed_columns.'
-            },
-            patch: {
-              type: 'object',
-              description: 'Bulk update object; merged with top-level field shortcuts'
-            },
+            task_id: { type: 'string' },
+            column: { type: 'string', enum: COLS },
+            patch: { type: 'object' },
             return: {
               type: 'string',
               enum: ['none', 'summary', 'full'],
-              description: 'move/update/delete/epic_* response size. Prefer none. Default summary. create/epic_create return full once.'
-            },
-            index: {
-              type: 'integer',
-              description: 'plan_advance: subtask index; omit = first incomplete'
+              default: 'none'
             },
+            index: { type: 'integer' },
             steps: {
               type: 'array',
-              items: { type: 'string' },
-              description: 'plan_create: implementation steps between red/green test steps'
-            },
-            project_root: {
-              type: 'string',
-              description: 'plan_create: root for test-runner detect (default cwd)'
-            },
-            diff: {
-              type: 'string',
-              description: 'plan_evidence: short diff or summary (not whole repo)'
-            },
-            test_command: {
-              type: 'string',
-              description: 'plan_evidence: exact command run'
+              items: { type: 'string' }
             },
-            stdout: {
-              type: 'string',
-              description: 'plan_evidence: test stdout (truncate to last ~2KB if huge)'
+            project_root: { type: 'string' },
+            diff: { type: 'string' },
+            summary: { type: 'string' },
+            test_command: { type: 'string' },
+            stdout: { type: 'string' },
+            stderr: { type: 'string' },
+            exit_code: { type: 'integer' }
+          },
+          required: ['action'],
+          additionalProperties: false,
+          examples: [
+            {
+              action: 'create',
+              title: 'Ship image',
+              epic: 'E001',
+              steps: ['Impl'],
+              col: 'planned'
             },
-            stderr: {
-              type: 'string',
-              description: 'plan_evidence: test stderr (truncate if huge)'
+            { action: 'move', task_id: '014', column: 'testing' }
+          ],
+          allOf: [
+            {
+              if: {
+                properties: { action: { const: 'create' } },
+                required: ['action']
+              },
+              then: { required: ['title'] }
             },
-            exit_code: {
-              type: 'integer',
-              description: 'plan_evidence: process exit code'
+            {
+              if: {
+                properties: { action: { const: 'move' } },
+                required: ['action']
+              },
+              then: { required: ['task_id', 'column'] }
             }
-          },
-          required: ['action'],
-          additionalProperties: false
+          ]
         }
       },
       {
@@ -571,7 +645,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             }
           },
           required: ['action'],
-          additionalProperties: false
+          additionalProperties: false,
+          examples: [
+            { action: 'status' },
+            { action: 'start' }
+          ]
         }
       }
     ]
@@ -586,19 +664,30 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
     switch (name) {
       case 'kanban_read': {
-        const operation = args.operation || 'list';
+        const operation = args.operation || 'context';
 
         if (operation === 'help') {
           result = playbook.playbookHelpPayload();
           break;
         }
 
+        await require('./workflow.js').ensureBoardConfig();
+
+        if (operation === 'context') {
+          result = await kanban.getContextPayload({
+            epic: args.epic,
+            epic_id: args.epic_id
+          });
+          break;
+        }
+
         const readOptions = normalizeReadOptions(args, 'summary');
 
         if (operation === 'list') {
           await kanban.migrateEpicGroups();
           const epics = await kanban.listEpicEntities();
-          let tasks = await kanban.allTasks();
+          const allBoardTasks = await kanban.allTasks();
+          let tasks = allBoardTasks;
           if (args.col) {
             tasks = tasks.filter((task) => task.column === args.col);
           }
@@ -609,12 +698,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           } else {
             tasks = kanban.filterTasksForList(tasks, epics, {
               include_archived: args.include_archived,
-              include_done: args.include_done
+              include_done: args.include_done,
+              col: args.col
             });
           }
 
-          // summary omits epic_goals; no lookup needed for list tokens
-          result = tasks.map((task) => kanban.shapeTask(task, readOptions));
+          result = tasks.map((task) => kanban.shapeTask(task, { ...readOptions, allTasks: allBoardTasks }));
         } else if (operation === 'show') {
           if (!args.task_id) {
             throw invalidRequest(
@@ -625,10 +714,26 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           }
 
           await kanban.migrateEpicGroups();
-          const epicLookup = await buildEpicLookup();
-          result = kanban.shapeTask(await kanban.getTask(args.task_id), {
+          const needBoard = viewNeedsAllTasks(readOptions);
+          const allTasks = needBoard ? await kanban.allTasks() : undefined;
+          const task = allTasks
+            ? findTaskOnBoard(args.task_id, allTasks)
+            : await kanban.getTask(args.task_id);
+          if (!task) {
+            throw kanban.createKanbanError(
+              'TASK_NOT_FOUND',
+              `Task ${args.task_id} was not found`,
+              'Call kanban_read with operation=list to discover valid task ids',
+              { task_id: args.task_id },
+              false,
+              404
+            );
+          }
+          const epicLookup = viewNeedsEpicLookup(readOptions) ? await buildEpicLookup() : undefined;
+          result = kanban.shapeTask(task, {
             ...readOptions,
-            epicLookup
+            epicLookup,
+            allTasks
           });
         } else if (operation === 'list_epics') {
           await kanban.migrateEpicGroups();
@@ -660,13 +765,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           const epic = await kanban.getEpicEntity(link.epic_id);
           const tasks = await kanban.allTasks();
           result = kanban.shapeEpic(epic, tasks, {
-            view: args.view || 'full',
+            view: args.view || 'summary',
             fields: args.fields
           });
         } else {
           throw invalidRequest(
             `Unknown operation: ${operation}`,
-            'Use one of: list, show, list_epics, show_epic, help',
+            'Use one of: list, show, list_epics, show_epic, context, help',
             { operation }
           );
         }
@@ -676,9 +781,19 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case 'kanban_manage': {
         const action = args.action;
         const returnShape = normalizeReturnShape(args.return);
+        await require('./workflow.js').ensureBoardConfig();
 
         switch (action) {
           case 'create': {
+            let subtasks = args.subtasks;
+            if (subtasks === undefined && Array.isArray(args.steps)) {
+              subtasks = args.steps.filter(Boolean).map(String).map((text, index) => ({
+                id: `st-${index + 1}`,
+                text,
+                done: false,
+                description: ''
+              }));
+            }
             const createPayload = {
               description: args.description,
               specs: args.specs,
@@ -686,19 +801,19 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
               out_of_scope: args.out_of_scope,
               acceptance_criteria: args.acceptance_criteria,
               test_cases: args.test_cases,
-              subtasks: args.subtasks,
-              notes: args.notes
+              subtasks,
+              notes: args.notes,
+              depends_on: args.depends_on,
+              files: args.files
             };
             const epicRef = args.epic_id || args.epic || '—';
             const created = await kanban.doCreate(args.title, args.col || 'planned', epicRef, createPayload);
-            const shaped = kanban.shapeTask(created, {
-              view: 'full',
-              epicLookup: await buildEpicLookup()
-            });
-            const warnings = kanban.createFieldWarnings(createPayload);
-            result = warnings.length > 0
-              ? { ...shaped, warnings, missing_recommended: kanban.missingRecommendedCreateFields(createPayload) }
-              : shaped;
+            const missing = kanban.missingRecommendedCreateFields(createPayload);
+            if (returnShape === 'none') {
+              result = formatCreateAck(created.id, missing);
+            } else {
+              result = withMissing(await formatTaskResult(created, returnShape), missing);
+            }
             break;
           }
 
@@ -711,15 +826,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
               notes: args.notes
             };
             const createdEpic = await kanban.doCreateEpic(args.title, epicPayload);
-            const shapedEpic = kanban.shapeEpic(createdEpic, [], { view: 'full' });
-            const epicWarnings = kanban.createEpicFieldWarnings(epicPayload);
-            result = epicWarnings.length > 0
-              ? {
-                ...shapedEpic,
-                warnings: epicWarnings,
-                missing_recommended: kanban.missingRecommendedEpicCreateFields(epicPayload)
-              }
-              : shapedEpic;
+            const missing = kanban.missingRecommendedEpicCreateFields(epicPayload);
+            if (returnShape === 'none') {
+              result = formatCreateAck(createdEpic.id, missing);
+            } else {
+              const view = returnShape === 'full' ? 'full' : 'summary';
+              result = withMissing(
+                kanban.shapeEpic(createdEpic, await kanban.allTasks(), { view }),
+                missing
+              );
+            }
             break;
           }
 
@@ -799,7 +915,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
             const deleted = await kanban.deleteTask(args.task_id);
             result = returnShape === 'none'
-              ? { ok: true, task_id: deleted.task_id }
+              ? { ok: true }
               : deleted;
             break;
           }
@@ -842,6 +958,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             if (args.test_cases !== undefined) patch.test_cases = args.test_cases;
             if (args.subtasks !== undefined) patch.subtasks = args.subtasks;
             if (args.notes !== undefined) patch.notes = args.notes;
+            if (args.depends_on !== undefined) patch.depends_on = args.depends_on;
+            if (args.files !== undefined) patch.files = args.files;
             if (args.adr !== undefined) patch.adr = args.adr;
             if (args.epic_id !== undefined) patch.epic_id = args.epic_id;
             else if (args.epic !== undefined) patch.epic = args.epic;
@@ -861,19 +979,23 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 missing_recommended: kanban.missingRecommendedCreateFields(args)
               };
             }
+            result = formatPlanResult(result, returnShape);
             break;
           }
           case 'plan_advance':
-            result = await plan.advance({ task_id: args.task_id, index: args.index });
+            result = formatPlanResult(
+              await plan.advance({ task_id: args.task_id, index: args.index }),
+              returnShape
+            );
             break;
           case 'plan_evidence':
-            result = await plan.evidence(args);
+            result = formatPlanResult(await plan.evidence(args), returnShape);
             break;
           case 'plan_done':
-            result = await plan.done({ task_id: args.task_id });
+            result = formatPlanResult(await plan.done({ task_id: args.task_id }), returnShape);
             break;
           case 'plan_status':
-            result = await plan.status(args.task_id);
+            result = formatPlanResult(await plan.status(args.task_id), returnShape === 'none' ? 'summary' : returnShape);
             break;
 
           default:
@@ -978,6 +1100,7 @@ async function main() {
 module.exports = {
   serializeError,
   serializeResult,
+  formatPlanResult,
   textResponse,
   startGuiServer,
   stopGuiServer,