@taskforcehq/taskforce 0.3.324 → 0.3.327

package/dist/mcp/taskPlanningRegistrar.js

@@ -2,6 +2,15 @@ import { bindDomainTool } from './toolCatalog.js';
 function stringProperty(description, enumValues) {
     return enumValues ? { type: 'string', description, enum: enumValues } : { type: 'string', description };
 }
+function nullableStringProperty(description) {
+    return {
+        description,
+        anyOf: [
+            { type: 'string' },
+            { type: 'null' },
+        ],
+    };
+}
 function numberProperty(description) {
     return { type: 'number', description };
 }
@@ -24,14 +33,86 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
                         type: 'object',
                         properties: descriptor.inputSchema.properties,
                         ...(descriptor.inputSchema.required ? { required: descriptor.inputSchema.required } : {}),
+                        ...(descriptor.inputSchema.additionalProperties !== undefined
+                            ? { additionalProperties: descriptor.inputSchema.additionalProperties }
+                            : {}),
                     },
+                    ...(descriptor.annotations ? { annotations: descriptor.annotations } : {}),
                 };
             },
             handler: bindDomainTool(executeTool, name),
         });
     };
+    register('scaffold_program', (context) => ({
+        description: context.describeTool('Preview or atomically create one bounded Initiative → Workstream → Task program with depends_on edges. Use dryRun=true first; commit requires idempotencyKey and exact retries return the original compact mapping.'),
+        annotations: { idempotentHint: true },
+        inputSchema: {
+            additionalProperties: false,
+            properties: {
+                dryRun: booleanProperty('When true, validate through the real durable application path and roll back every write.'),
+                idempotencyKey: { type: 'string', minLength: 1, maxLength: 128, description: 'Required for commit. Opaque retry key scoped to the current caller and workspace.' },
+                initiative: {
+                    type: 'object', additionalProperties: false,
+                    properties: {
+                        title: stringProperty('Initiative title.'),
+                        description: stringProperty('Optional initiative description.'),
+                        ownerId: stringProperty(`${context.assigneeHint} Call list_assignees to inspect eligible IDs.`),
+                        order: numberProperty('Optional initiative order.'),
+                    },
+                    required: ['title'],
+                },
+                workstreams: {
+                    type: 'array', maxItems: 12,
+                    description: 'Ordered workstreams and their ordered tasks.',
+                    items: {
+                        type: 'object', additionalProperties: false,
+                        properties: {
+                            key: { type: 'string', pattern: '^[a-z][a-z0-9_-]{0,63}$' },
+                            title: stringProperty('Workstream title.'),
+                            description: stringProperty('Optional workstream description.'),
+                            ownerId: stringProperty(`${context.assigneeHint} Call list_assignees to inspect eligible IDs.`),
+                            order: numberProperty('Optional workstream order.'),
+                            tasks: {
+                                type: 'array', maxItems: 50,
+                                items: {
+                                    type: 'object', additionalProperties: false,
+                                    properties: {
+                                        key: { type: 'string', pattern: '^[a-z][a-z0-9_-]{0,63}$' },
+                                        title: stringProperty('Task title.'),
+                                        description: stringProperty('Optional task description.'),
+                                        assignee: stringProperty(`${context.assigneeHint} Call list_assignees to inspect eligible IDs.`),
+                                        category: stringProperty('Task category.', context.categoryEnum),
+                                        type: stringProperty('Task type.', context.typeEnum),
+                                        priority: numberProperty(context.priorityDesc),
+                                        complexity: numberProperty(context.complexityDesc),
+                                        scheduledDate: stringProperty('Optional schedule date (YYYY-MM-DD).'),
+                                        dueDate: stringProperty('Optional due date (YYYY-MM-DD).'),
+                                    },
+                                    required: ['key', 'title'],
+                                },
+                            },
+                        },
+                        required: ['key', 'title', 'tasks'],
+                    },
+                },
+                dependencies: {
+                    type: 'array', maxItems: 100,
+                    description: 'Depends-on edges between task keys.',
+                    items: {
+                        type: 'object', additionalProperties: false,
+                        properties: {
+                            taskKey: { type: 'string', pattern: '^[a-z][a-z0-9_-]{0,63}$' },
+                            dependsOnTaskKey: { type: 'string', pattern: '^[a-z][a-z0-9_-]{0,63}$' },
+                        },
+                        required: ['taskKey', 'dependsOnTaskKey'],
+                    },
+                },
+            },
+            required: ['dryRun', 'initiative', 'workstreams', 'dependencies'],
+        },
+    }));
     register('list_tasks', (context) => ({
-        description: context.describeTool('List active tasks with optional filters. Supports filtering by status, assignee, priority, type, and category. Use openOnly=true to exclude done/cancelled. Use format=json for programmatic use. Default sort is by created date descending. Returns a compact summary of each task — description, comments, and activity are omitted to keep responses concise. Use get_task to retrieve full details for a specific task.'),
+        description: context.describeTool('List active tasks with optional filters, including workstreamId (an ID or WS-123 reference). Use offset and limit for bounded pagination. Use openOnly=true to exclude done/cancelled. Use format=json for programmatic use. Returns compact task summaries without descriptions, comments, activity, attachments, or event streams. When a task URL is provided, preserve it when presenting the task so the user can open it directly. Use get_task for one task’s details.'),
         inputSchema: {
             properties: {
                 format: stringProperty('Toggle output format (default: markdown).', ['markdown', 'json']),
@@ -41,40 +122,76 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
                 assignee: stringProperty(`${context.assigneeHint} Call list_assignees to inspect the current eligible IDs.`),
                 priority: numberProperty('Filter by priority level.'),
                 type: stringProperty('Filter by task type.', context.typeEnum),
+                workstreamId: stringProperty('Filter by workstream ID or workstream reference such as WS-123.'),
                 sort: stringProperty('Sort field (default: created).', ['priority', 'created', 'updated']),
                 order: stringProperty('Sort order (default: desc).', ['asc', 'desc']),
                 limit: numberProperty('Max tasks to return.'),
+                offset: numberProperty('Non-negative result offset for pagination (default: 0).'),
             },
         },
     }));
     register('search_tasks', (context) => ({
-        description: context.describeTool('Search active and archived tasks by keyword. Matches against title, description, and ID. Use scope=\'active\' or scope=\'archive\' to narrow results. Prefer this over list_tasks when looking for a specific task by name.'),
+        description: context.describeTool('Search active and archived tasks by keyword or exact task reference. Matches title, description, internal ID, canonical T-* references, and provisional local LT-* references. Results use linked task references when an application URL is available; preserve those links when presenting tasks. Use scope=\'active\' or scope=\'archive\' to narrow results. Prefer this over list_tasks when looking for a specific task by name.'),
         inputSchema: {
             properties: {
-                query: stringProperty('Search term (matches title, description, internal ID, or task reference such as T-123).'),
+                query: stringProperty('Search term or exact task reference such as T-123 or LT-123.'),
                 scope: stringProperty('Search scope (default: all).', ['all', 'active', 'archive']),
             },
             required: ['query'],
         },
     }));
+    register('list_task_relationships', (context) => ({
+        description: context.describeTool('List structured dependency, related, and supersession relationships for one task. Returns compact task references; use this instead of attachment/document link tools.'),
+        inputSchema: { properties: {
+                taskId: stringProperty('Task ID or reference such as T-123.'),
+                type: stringProperty('Optional relationship type.', ['depends_on', 'blocks', 'related_to', 'supersedes']),
+                direction: stringProperty('Optional stored-edge direction; default both.', ['outgoing', 'incoming', 'both']),
+            }, required: ['taskId'] },
+    }));
+    register('link_task_relationship', (context) => ({
+        description: context.describeTool('Create an idempotent structured relationship between two tasks. blocks(A,B) is the inverse view of depends_on(B,A). Rejects self-links, missing tasks, and dependency/supersession cycles.'),
+        inputSchema: { properties: {
+                sourceTaskId: stringProperty('Source task ID or reference.'),
+                targetTaskId: stringProperty('Target task ID or reference.'),
+                type: stringProperty('Relationship type.', ['depends_on', 'blocks', 'related_to', 'supersedes']),
+                profileToken: stringProperty('Optional profileToken for stateless MCP clients.'),
+            }, required: ['sourceTaskId', 'targetTaskId', 'type'] },
+    }));
+    register('unlink_task_relationship', (context) => ({
+        description: context.describeTool('Idempotently remove a structured task relationship. The relationship is tombstoned so deletion converges across sync.'),
+        inputSchema: { properties: {
+                sourceTaskId: stringProperty('Source task ID or reference.'),
+                targetTaskId: stringProperty('Target task ID or reference.'),
+                type: stringProperty('Relationship type.', ['depends_on', 'blocks', 'related_to', 'supersedes']),
+                profileToken: stringProperty('Optional profileToken for stateless MCP clients.'),
+            }, required: ['sourceTaskId', 'targetTaskId', 'type'] },
+    }));
     register('get_task', (context) => ({
-        description: context.describeTool('Get a single task by ID or task reference. Checks both active and archived tasks. Use this when you have a specific task ID or T-123 reference from a previous list or search result and need full details including comments and attachment metadata. This tool does not return attachment file contents. For task attachments, call get_task_attachments and then read_task_attachment. Do not fetch attachment path URLs directly when MCP attachment-read tools are available. Do not use this for image references like I-123 or document references like D-123.'),
+        description: context.describeTool('Get one task by ID or T-123 reference. The default compact response returns scalar task fields and collection counts without comments, history, checklist items, or attachments. When the response includes url, preserve it in any task reference you present so the user can open the task directly. Pass detail=full for comments and attachment/checklist metadata, or detail=history for one chronological comment/event stream. Use get_task_attachments for attachment bodies; use D-123/I-123 tools for documents/images. When showing this task to the user in a client that supports rich inline rendering, prefer a compact visual summary that retains the task link.'),
         inputSchema: {
             properties: {
                 id: stringProperty('Task ID or task reference such as T-123.'),
+                detail: stringProperty('Response detail level (default: compact). Use full for comments and attachment/checklist metadata, or history for chronological task events.', ['compact', 'full', 'history']),
             },
             required: ['id'],
         },
     }));
     register('list_initiatives', (context) => ({
-        description: context.describeTool('List initiatives for the active workspace. Returns initiative records with attached workstream summaries and task counts so AI agents can reason about the planning model directly.'),
-        inputSchema: { properties: {} },
+        description: context.describeTool('List or search initiatives for the active workspace. Pass query to search by initiative title, description, ID/reference, owner, or linked workstream title. Returns compact initiative summaries with workstream and task counts.'),
+        inputSchema: {
+            properties: {
+                query: stringProperty('Optional search term for initiative title, description, ID/reference such as IN-123, owner, or linked workstream title.'),
+            },
+        },
     }));
     register('get_initiative', (context) => ({
-        description: context.describeTool('Get a single initiative by ID or initiative reference such as IN-123. Returns the initiative plus its workstreams and rolled-up task counts.'),
+        description: context.describeTool('Get one initiative by ID or IN-123 reference. The default compact response returns summary counts. Use detail=planning for current attachments plus paginated active/archived workstream summaries and historical task counts, detail=history for bounded chronological history, or detail=full for the compatible rich response.'),
         inputSchema: {
             properties: {
                 id: stringProperty('Initiative ID or initiative reference such as IN-123.'),
+                detail: stringProperty('Response detail level (default: compact). Planning excludes history; history is chronological and bounded; full preserves the rich response.', ['compact', 'planning', 'history', 'full']),
+                limit: { type: 'integer', minimum: 1, maximum: 100, description: 'Page size for planning workstreams or history entries (default: 25, max: 100).' },
+                offset: { type: 'integer', minimum: 0, description: 'Non-negative page offset for planning workstreams or history entries (default: 0).' },
             },
             required: ['id'],
         },
@@ -128,6 +245,16 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
             required: ['id'],
         },
     }));
+    register('add_initiative_comment', (context) => ({
+        description: context.describeTool('Add a comment to an initiative. Use this for initiative-level progress notes, decisions, coordination context, and audit trails. Comments appear in the initiative activity feed.'),
+        inputSchema: {
+            properties: {
+                id: stringProperty('Initiative ID or initiative reference such as IN-123.'),
+                text: stringProperty('Comment text.'),
+            },
+            required: ['id', 'text'],
+        },
+    }));
     register('archive_initiative', (context) => ({
         description: context.describeTool('Archive an initiative without deleting it. This hides it from open planning views while preserving its workstreams and history.'),
         inputSchema: {
@@ -147,14 +274,21 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
         },
     }));
     register('list_workstreams', (context) => ({
-        description: context.describeTool('List workstreams for the active workspace. Returns workstream records with attached task summaries and linked initiative information when present.'),
-        inputSchema: { properties: {} },
+        description: context.describeTool('List or search workstreams for the active workspace. Pass query to search by workstream title, description, ID/reference, owner, or linked initiative title/reference. Returns compact workstream summaries with task counts.'),
+        inputSchema: {
+            properties: {
+                query: stringProperty('Optional search term for workstream title, description, ID/reference such as WS-123, owner, or linked initiative title/reference.'),
+            },
+        },
     }));
     register('get_workstream', (context) => ({
-        description: context.describeTool('Get a single workstream by ID or workstream reference such as WS-123. Returns the workstream plus its tasks.'),
+        description: context.describeTool('Get one workstream by ID or WS-123 reference. The default compact response returns a summary and task count. Use detail=planning for current attachments and explicit historical task counts without nested tasks, detail=history for bounded chronological history, or detail=full for the compatible rich response. Use list_tasks with workstreamId for bounded active task discovery.'),
         inputSchema: {
             properties: {
                 id: stringProperty('Workstream ID or workstream reference such as WS-123.'),
+                detail: stringProperty('Response detail level (default: compact). Planning excludes history and nested tasks; history is chronological and bounded; full preserves the rich response.', ['compact', 'planning', 'history', 'full']),
+                limit: { type: 'integer', minimum: 1, maximum: 100, description: 'Page size for history entries (default: 25, max: 100).' },
+                offset: { type: 'integer', minimum: 0, description: 'Non-negative history page offset (default: 0).' },
             },
             required: ['id'],
         },
@@ -210,17 +344,18 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
             required: ['id'],
         },
     }));
-    register('archive_workstream', (context) => ({
-        description: context.describeTool('Archive a workstream without deleting it. This hides it from open planning views while preserving its linked tasks.'),
+    register('add_workstream_comment', (context) => ({
+        description: context.describeTool('Add a comment to a workstream. Use this for workstream-level progress notes, decisions, coordination context, and audit trails. Comments appear in the workstream activity feed.'),
         inputSchema: {
             properties: {
                 id: stringProperty('Workstream ID or workstream reference such as WS-123.'),
+                text: stringProperty('Comment text.'),
             },
-            required: ['id'],
+            required: ['id', 'text'],
         },
     }));
-    register('unarchive_workstream', (context) => ({
-        description: context.describeTool('Restore an archived workstream to active planning views.'),
+    register('archive_workstream', (context) => ({
+        description: context.describeTool('Archive a workstream without deleting it. This hides it from open planning views while preserving its linked tasks.'),
         inputSchema: {
             properties: {
                 id: stringProperty('Workstream ID or workstream reference such as WS-123.'),
@@ -228,63 +363,69 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
             required: ['id'],
         },
     }));
-    register('set_task_workstream', (context) => ({
-        description: context.describeTool('Assign an existing task to a workstream. Reassigning a task removes it from any previous workstream.'),
+    register('unarchive_workstream', (context) => ({
+        description: context.describeTool('Restore an archived workstream to active planning views.'),
         inputSchema: {
             properties: {
-                taskId: stringProperty('Task ID or task reference such as T-123.'),
-                workstreamId: stringProperty('Workstream ID or workstream reference such as WS-123.'),
+                id: stringProperty('Workstream ID or workstream reference such as WS-123.'),
             },
-            required: ['taskId', 'workstreamId'],
+            required: ['id'],
         },
     }));
-    register('clear_task_workstream', (context) => ({
-        description: context.describeTool('Remove a task from its current workstream, making it standalone.'),
+    register('update_task_workstream', (context) => ({
+        description: context.describeTool('Set or clear the workstream for one task. Pass workstreamId to assign or reassign; pass an empty string or null to unlink the task from its current workstream.'),
         inputSchema: {
             properties: {
                 taskId: stringProperty('Task ID or task reference such as T-123.'),
+                id: stringProperty('Alias for taskId. Task ID or task reference such as T-123.'),
+                workstreamId: nullableStringProperty('Workstream ID or workstream reference such as WS-123. Pass an empty string or null to unlink.'),
             },
-            required: ['taskId'],
         },
     }));
-    register('set_workstream_initiative', (context) => ({
-        description: context.describeTool('Assign an existing workstream to an initiative. Reassigning a workstream removes it from any previous initiative.'),
+    register('update_workstream_initiative', (context) => ({
+        description: context.describeTool('Set or clear the initiative for one workstream. Pass initiativeId to assign or reassign; pass an empty string or null to unlink the workstream from its current initiative.'),
         inputSchema: {
             properties: {
                 workstreamId: stringProperty('Workstream ID or workstream reference such as WS-123.'),
-                initiativeId: stringProperty('Initiative ID or initiative reference such as IN-123.'),
+                id: stringProperty('Alias for workstreamId. Workstream ID or workstream reference such as WS-123.'),
+                initiativeId: nullableStringProperty('Initiative ID or initiative reference such as IN-123. Pass an empty string or null to unlink.'),
             },
-            required: ['workstreamId', 'initiativeId'],
         },
     }));
-    register('clear_workstream_initiative', (context) => ({
-        description: context.describeTool('Remove a workstream from its current initiative, making it standalone.'),
+    register('get_task_checklist', (context) => ({
+        description: context.describeTool('Read the structured checklist items for one task. Returns stored checklist items, not markdown parsing.'),
         inputSchema: {
             properties: {
-                workstreamId: stringProperty('Workstream ID or workstream reference such as WS-123.'),
+                taskId: stringProperty('Task ID or task reference such as T-123.'),
             },
-            required: ['workstreamId'],
+            required: ['taskId'],
         },
     }));
-    register('get_task_checklist', (context) => ({
-        description: context.describeTool('Read the structured checklist items for one task. Returns stored checklist items, not markdown parsing.'),
+    register('add_task_checklist_item', (context) => ({
+        description: context.describeTool('Append one structured checklist item to a task. Use this when a user asks to add a checklist item without replacing the existing checklist.'),
         inputSchema: {
             properties: {
                 taskId: stringProperty('Task ID or task reference such as T-123.'),
+                text: stringProperty('Checklist item text to append. Must be descriptive, not a placeholder.'),
+                done: { type: 'boolean', description: 'Whether the new checklist item is already complete.' },
             },
-            required: ['taskId'],
+            required: ['taskId', 'text'],
         },
     }));
     register('replace_task_checklist', (context) => ({
-        description: context.describeTool('Replace the structured checklist items for one task with a new ordered list.'),
+        description: context.describeTool('Replace the structured checklist items for one task with a new ordered list. Use this when a user explicitly asks to create, update, or replace a task checklist; do not just draft checklist text.'),
         inputSchema: {
             properties: {
                 taskId: stringProperty('Task ID or task reference such as T-123.'),
                 items: arrayProperty('Ordered checklist items to persist.', {
                     type: 'object',
                     properties: {
+                        id: { type: 'string', description: 'Stable checklist item ID. Reuse it when reordering or updating an existing item.' },
                         text: { type: 'string' },
                         done: { type: 'boolean' },
+                        order: { type: 'number', description: 'Optional zero-based display order.' },
+                        createdAt: { type: 'string', description: 'Optional canonical ISO creation timestamp.' },
+                        updatedAt: { type: 'string', description: 'Optional canonical ISO last-change timestamp.' },
                     },
                     required: ['text'],
                 }),
@@ -293,71 +434,101 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
         },
     }));
     register('get_schedule_board', (context) => ({
-        description: context.describeTool('Read the current schedule board for the active workspace. Use this before scheduling or reordering tasks when you need the existing day layout and order.'),
-        inputSchema: { properties: {} },
-    }));
-    register('schedule_task', (context) => ({
-        description: context.describeTool('Schedule a task on a specific day. Use get_schedule_board first when you need the current order before inserting the task.'),
+        description: context.describeTool('Read the current schedule board for the active workspace. Use this before scheduling tasks when you need the existing day layout and order.'),
         inputSchema: {
             properties: {
-                taskId: stringProperty('Task ID or task reference such as T-123.'),
-                date: stringProperty('Target date in YYYY-MM-DD format.'),
-                order: numberProperty('Optional position within that day.'),
+                week: stringProperty('Optional ISO week key such as 2026-W29. Defaults to the current week.'),
+                showWeekends: booleanProperty('When true, include weekends in the returned board.'),
             },
-            required: ['taskId', 'date'],
         },
     }));
-    register('unschedule_task', (context) => ({
-        description: context.describeTool('Remove a task from the schedule board and return it to the unscheduled pool.'),
+    register('update_schedule', (context) => ({
+        description: context.describeTool('Default schedule write path. Schedule, unschedule, or reorder scheduled tasks. Pass taskId with date to schedule, taskId with date=null or an empty string to unschedule, or pass date plus taskIds to replace one day order. Use get_schedule_board first when you need the current board state.'),
         inputSchema: {
             properties: {
                 taskId: stringProperty('Task ID or task reference such as T-123.'),
+                id: stringProperty('Alias for taskId. Task ID or task reference such as T-123.'),
+                date: nullableStringProperty('Target date in YYYY-MM-DD format. Pass an empty string or null with taskId to unschedule.'),
+                scheduledDate: nullableStringProperty('Alias for date. Target date in YYYY-MM-DD format. Pass an empty string or null with taskId to unschedule.'),
+                order: numberProperty('Optional position within that day.'),
+                orderInDay: numberProperty('Alias for order. Optional position within that day.'),
+                taskIds: arrayProperty('Ordered task IDs or task references for replacing one scheduled day order.', { type: 'string' }),
+                moves: arrayProperty('Advanced reorder moves. Each move may include id or taskId, date or scheduledDate, and order or orderInDay.', {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'string' },
+                        taskId: { type: 'string' },
+                        date: { type: 'string' },
+                        scheduledDate: { type: 'string' },
+                        order: { type: 'number' },
+                        orderInDay: { type: 'number' },
+                    },
+                    anyOf: [
+                        { required: ['id', 'date'] },
+                        { required: ['id', 'scheduledDate'] },
+                        { required: ['taskId', 'date'] },
+                        { required: ['taskId', 'scheduledDate'] },
+                    ],
+                }),
             },
-            required: ['taskId'],
-        },
-    }));
-    register('reorder_scheduled_tasks', (context) => ({
-        description: context.describeTool('Replace the ordered task list for one scheduled day. Use get_schedule_board first to inspect the current day contents.'),
-        inputSchema: {
-            properties: {
-                date: stringProperty('Target date in YYYY-MM-DD format.'),
-                taskIds: arrayProperty('Ordered task IDs or task references for that day.', { type: 'string' }),
-            },
-            required: ['date', 'taskIds'],
         },
     }));
     register('bulk_carryover', (context) => ({
-        description: context.describeTool('Carry unfinished scheduled tasks forward from one day to another in bulk.'),
+        description: context.describeTool('Extended precision tool for carrying unfinished scheduled tasks forward from one day or week to another in bulk. Use get_schedule_board first to inspect the source period.'),
         inputSchema: {
             properties: {
-                fromDate: stringProperty('Source date in YYYY-MM-DD format.'),
-                toDate: stringProperty('Destination date in YYYY-MM-DD format.'),
-                preserveCompleted: booleanProperty('When true, leave completed tasks on the source date.'),
+                fromWeek: stringProperty('Source ISO week key such as 2026-W29.'),
+                toWeek: stringProperty('Destination ISO week key such as 2026-W30.'),
+                mode: stringProperty('Carryover interval.', ['day', 'week']),
+                includeStatuses: arrayProperty('Optional active task statuses to carry over.', {
+                    type: 'string',
+                    enum: ['task', 'in-progress', 'review', 'on-hold'],
+                }),
             },
-            required: ['fromDate', 'toDate'],
+            required: ['fromWeek', 'toWeek', 'mode'],
         },
     }));
     register('set_schedule_preferences', (context) => ({
         description: context.describeTool('Update schedule board display and planning preferences for the current session.'),
         inputSchema: {
             properties: {
-                weekStartsOn: numberProperty('Week start day index, where 0 is Sunday and 1 is Monday.'),
                 showWeekends: booleanProperty('When true, include weekends in schedule views.'),
+                isCalendarSidebarOpen: booleanProperty('Whether the calendar sidebar is open.'),
+                weekStartsOn: stringProperty('First day of the schedule week.', ['sunday', 'monday']),
+                dailyCapacity: {
+                    type: 'object',
+                    description: 'Optional per-day capacity settings.',
+                    properties: {
+                        monday: { type: 'number', minimum: 0 },
+                        tuesday: { type: 'number', minimum: 0 },
+                        wednesday: { type: 'number', minimum: 0 },
+                        thursday: { type: 'number', minimum: 0 },
+                        friday: { type: 'number', minimum: 0 },
+                        saturday: { type: 'number', minimum: 0 },
+                        sunday: { type: 'number', minimum: 0 },
+                    },
+                    additionalProperties: false,
+                },
             },
         },
     }));
     register('create_task', (context) => ({
-        description: context.describeTool('Create a new task. Use get_config first so category, type, priority, approach, status, and complexity values match the active workspace taxonomy.'),
+        description: context.describeTool('Create a new task. Pass idempotencyKey when the call may be retried after a timeout; the same key and payload return the original task, while a changed payload is rejected. Current taxonomy values are included in this schema; call get_config only for richer metadata or after a validation mismatch.'),
         inputSchema: {
             properties: {
                 title: stringProperty('Task title.'),
+                idempotencyKey: {
+                    type: 'string',
+                    minLength: 1,
+                    maxLength: 128,
+                    description: 'Optional opaque retry key scoped to the active workspace and AI profile.',
+                },
                 description: stringProperty('Optional task description.'),
                 assignee: stringProperty(`${context.assigneeHint} Call list_assignees to inspect the current eligible IDs.`),
-                workstreamId: stringProperty('Optional workstream ID or workstream reference such as WS-123. Use this to create the task directly inside a workstream without a separate set_task_workstream call.'),
-                category: stringProperty('Task category value.'),
+                workstreamId: stringProperty('Optional workstream ID or workstream reference such as WS-123. Use this to create the task directly inside a workstream without a separate update_task_workstream call. Call list_workstreams with query first if you only know the workstream name.'),
+                category: stringProperty('Task category value.', context.categoryEnum),
                 type: stringProperty('Task type value.', context.typeEnum),
                 priority: numberProperty(context.priorityDesc),
-                approach: stringProperty('Task approach value.', context.approachEnum),
                 status: stringProperty('Initial task status.', ['task', 'on-hold', 'in-progress', 'review', 'done', 'cancelled']),
                 complexity: numberProperty(context.complexityDesc),
                 scheduledDate: stringProperty('Optional scheduled date in YYYY-MM-DD format.'),
@@ -375,18 +546,27 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
             required: ['id'],
         },
     }));
+    register('reopen_task', (context) => ({
+        description: context.describeTool('Safely resume reviewed work in one call. Reopens archived done tasks or active/archived review tasks to in-progress, preserves an existing assignee, and claims only unassigned work. Cancelled tasks are rejected. Already in-progress tasks are idempotent no-ops.'),
+        inputSchema: {
+            properties: {
+                id: stringProperty('Task ID or task reference such as T-123.'),
+            },
+            required: ['id'],
+        },
+    }));
     register('update_task', (context) => ({
-        description: context.describeTool('Update an existing task. Use get_config first for taxonomy-backed fields. Use start_task when beginning active work on a tracked task, and prefer finish_task for the final completion or review handoff.'),
+        description: context.describeTool('Update an existing task. Current taxonomy values are included in this tool schema; call get_config only for richer metadata or after a validation mismatch. Use start_task when beginning active work on a tracked task, and prefer finish_task for the final completion or review handoff.'),
         inputSchema: {
             properties: {
                 id: stringProperty('Task ID or task reference such as T-123.'),
                 title: stringProperty('Updated task title.'),
                 description: stringProperty('Updated task description.'),
                 assignee: stringProperty(`${context.assigneeHint} Call list_assignees to inspect the current eligible IDs.`),
-                category: stringProperty('Updated category value.'),
+                workstreamId: stringProperty('Updated workstream ID or workstream reference such as WS-123. Pass an empty string to unlink the task. Call list_workstreams with query first if you only know the workstream name.'),
+                category: stringProperty('Updated category value.', context.categoryEnum),
                 type: stringProperty('Updated task type value.', context.typeEnum),
                 priority: numberProperty(context.priorityDesc),
-                approach: stringProperty('Updated task approach value.', context.approachEnum),
                 status: stringProperty('Updated task status.', ['task', 'on-hold', 'in-progress', 'review', 'done', 'cancelled']),
                 complexity: numberProperty(context.complexityDesc),
                 scheduledDate: stringProperty('Updated scheduled date in YYYY-MM-DD format. Pass an empty string to clear.'),
@@ -396,34 +576,14 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
         },
     }));
     register('finish_task', (context) => ({
-        description: context.describeTool('default end-of-task handoff. Use outcome=\'done\' when work is complete and no explicit human action is requested. Use outcome=\'review\' when human validation or approval is needed. If you report completed work on a tracked task, either finish it with this tool or explain why it remains open. This tool never archives automatically.'),
+        description: context.describeTool('default end-of-task handoff for active work. Archived tasks are rejected; call reopen_task first. Use outcome=\'done\' when work is complete and outcome=\'review\' when human validation or approval is needed. If you report completed work on a tracked task, either finish it with this tool or explain why it remains open. Both outcomes remain active and unarchived. This tool never archives automatically; use archive_task separately to move work to history. The response always reports completion.archived from persisted state.'),
         inputSchema: {
             properties: {
                 id: stringProperty('Task ID or task reference such as T-123.'),
                 outcome: stringProperty('Completion outcome.', ['review', 'done']),
-                comment: stringProperty('Optional completion note to add as a task comment.'),
-            },
-            required: ['id'],
-        },
-    }));
-    register('assign_task', (context) => ({
-        description: context.describeTool('Assign a task to one eligible assignee. For assigning 3 or more tasks at once, use bulk_assign_tasks instead.'),
-        inputSchema: {
-            properties: {
-                id: stringProperty('Task ID or task reference such as T-123.'),
-                assignee: stringProperty(`${context.assigneeHint} Call list_assignees to inspect the current eligible IDs.`),
+                comment: stringProperty('Optional completion note returned in the handoff response.'),
             },
-            required: ['id', 'assignee'],
-        },
-    }));
-    register('bulk_assign_tasks', (context) => ({
-        description: context.describeTool('Assign multiple tasks to the same eligible assignee in one request. Preferred over repeated assign_task calls when changing 3 or more tasks at once.'),
-        inputSchema: {
-            properties: {
-                ids: arrayProperty('Task IDs or task references such as T-123.', { type: 'string' }),
-                assignee: stringProperty(`${context.assigneeHint} Call list_assignees to inspect the current eligible IDs.`),
-            },
-            required: ['ids', 'assignee'],
+            required: ['id', 'outcome'],
         },
     }));
     register('archive_task', (context) => ({
@@ -437,14 +597,6 @@ export function registerTaskPlanningTools(registerTool, executeTool) {
             required: ['id', 'status'],
         },
     }));
-    register('list_archive', (context) => ({
-        description: context.describeTool('List archived tasks. Use format=json for programmatic use.'),
-        inputSchema: {
-            properties: {
-                format: stringProperty('Toggle output format (default: markdown).', ['markdown', 'json']),
-            },
-        },
-    }));
     register('unarchive_task', (context) => ({
         description: context.describeTool('Restore an archived task to the active task list.'),
         inputSchema: {

package/dist/mcp/toolCallCompatibility.d.ts

@@ -0,0 +1,6 @@
+export type ResolvedMcpToolCall = {
+    name: string;
+    arguments: Record<string, unknown>;
+};
+export declare function resolveCanonicalMcpToolName(nameRaw: unknown): string;
+export declare function resolveMcpToolCallCompatibility(nameRaw: unknown, argsRaw: unknown): ResolvedMcpToolCall;

package/dist/mcp/toolCallCompatibility.js

@@ -0,0 +1,16 @@
+const LEGACY_TOOL_NAME_ALIASES = Object.freeze({
+    // Kept callable for connector hosts that cached the pre-T-684 contract.
+    // Do not advertise this alias from tools/list; get_task_attachments is canonical.
+    read_task_attachment: 'get_task_attachments',
+});
+export function resolveCanonicalMcpToolName(nameRaw) {
+    const name = String(nameRaw || '').trim();
+    return LEGACY_TOOL_NAME_ALIASES[name] || name;
+}
+export function resolveMcpToolCallCompatibility(nameRaw, argsRaw) {
+    const name = resolveCanonicalMcpToolName(nameRaw);
+    const args = argsRaw && typeof argsRaw === 'object' && !Array.isArray(argsRaw)
+        ? argsRaw
+        : {};
+    return { name, arguments: args };
+}

package/dist/mcp/toolCatalog.d.ts

@@ -3,6 +3,7 @@ export type McpToolInputSchema = {
     type: 'object';
     properties?: Record<string, unknown>;
     required?: string[];
+    additionalProperties?: boolean;
 };
 export type McpToolDescriptor = {
     name: McpToolName;
@@ -17,11 +18,12 @@ export type McpToolDescriptor = {
     };
 };
 export type McpToolDescriptorContext = {
+    runtimeMode: 'local' | 'cloud';
     describeTool: (text: string) => string;
     assigneeHint: string;
+    categoryEnum: string[];
     priorityDesc: string;
     typeEnum: string[];
-    approachEnum: string[];
     complexityDesc: string;
 };
 export type McpToolHandlerResult = {