@specforge/mcp 3.1.2 → 3.2.1

package/dist/tools/index.js

@@ -82,8 +82,6 @@ const READ_TOOL_NAMES = new Set([
     'search_tickets',
     // Working context
     'get_working_context',
-    // Job status
-    'get_job_status',
     // Agent Teams (read operations)
     'get_epic_dependency_graph',
     'get_implementation_plan',
@@ -726,7 +724,7 @@ Examples:
         // ========================================================================
         {
             name: 'start_work_session',
-            description: 'Start working on a ticket. Transitions ready -> active. Returns error with statusReason if ticket is pending (dependencies not met).',
+            description: 'Start working on a ticket. Creates a WorkSession record and transitions ready -> active. Returns the workSessionId along with error with statusReason if ticket is pending (dependencies not met).',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -740,10 +738,9 @@ Examples:
         },
         {
             name: 'complete_work_session',
-            description: 'Mark a ticket as complete. Transitions active -> done.\n\n' +
+            description: 'Mark a ticket as complete and finalize the active WorkSession. Transitions active -> done. Session data (files, test results, time) is stored on the WorkSession record.\n\n' +
+                'All acceptance criteria must be validated and all implementation steps must be completed via action_work_session before calling this. The completion gate enforces this — shortcuts are not available.\n\n' +
                 'Automatically recalculates status for dependent tickets and returns cascade info.\n\n' +
-                'By default, checks if summary addresses acceptance criteria and returns warnings (not errors) for gaps.\n\n' +
-                'Use validated: true as a simple confirmation that the agent has verified all work meets criteria.\n\n' +
                 'Optional validation flags can be provided to report test results inline:\n' +
                 '- tests: Unit/integration test results\n' +
                 '- lint: Linting results\n' +
@@ -770,21 +767,18 @@ Examples:
                         items: { type: 'string' },
                         description: 'List of files created',
                     },
+                    filesDeleted: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'List of files deleted',
+                    },
                     actualHours: {
                         type: 'number',
                         description: 'Actual hours spent on the ticket',
                     },
-                    validated: {
-                        type: 'boolean',
-                        description: 'Simple validation confirmation. When true, indicates:\n' +
-                            '- Agent has verified work meets acceptance criteria\n' +
-                            '- All necessary tests/validations were run and passed\n' +
-                            '- No detailed breakdown needed\n' +
-                            'Trust-based approach for streamlined completion.',
-                    },
                     validation: {
                         type: 'object',
-                        description: 'Detailed validation flags (optional with validated: true)',
+                        description: 'Detailed validation flags for reporting test/lint/build results',
                         properties: {
                             tests: {
                                 type: 'string',
@@ -812,61 +806,175 @@ Examples:
                             },
                         },
                     },
-                    skipCriteriaCheck: {
-                        type: 'boolean',
-                        description: 'Skip acceptance criteria validation. Use for trivial changes or when criteria check is not needed. Default: false',
-                    },
                 },
                 required: ['ticketId', 'summary'],
             },
         },
         {
-            name: 'report_progress',
-            description: 'Report incremental progress on a ticket',
+            name: 'pause_work_session',
+            description: 'Pause work on a ticket, setting it back to ready status. Use this to temporarily pause work on a ticket without completing it.',
             inputSchema: {
                 type: 'object',
                 properties: {
                     ticketId: {
                         type: 'string',
-                        description: 'The ID of the ticket',
-                    },
-                    progress: {
-                        type: 'number',
-                        minimum: 0,
-                        maximum: 100,
-                        description: 'Progress percentage (0-100)',
-                    },
-                    message: {
-                        type: 'string',
-                        description: 'Progress message',
+                        description: 'The ID of the ticket to pause',
                     },
                 },
-                required: ['ticketId', 'progress'],
+                required: ['ticketId'],
             },
         },
         {
-            name: 'pause_work_session',
-            description: 'Pause work on a ticket, setting it back to ready status. Use this to temporarily pause work on a ticket without completing it.',
+            name: 'resume_work_session',
+            description: 'Resume work on a paused ticket, setting it to active status. Use this to continue work on a ticket that was previously paused.',
             inputSchema: {
                 type: 'object',
                 properties: {
                     ticketId: {
                         type: 'string',
-                        description: 'The ID of the ticket to pause',
+                        description: 'The ID of the ticket to resume',
                     },
                 },
                 required: ['ticketId'],
             },
         },
         {
-            name: 'resume_work_session',
-            description: 'Resume work on a paused ticket, setting it to active status. Use this to continue work on a ticket that was previously paused.',
+            name: 'action_work_session',
+            description: `Update checklist state during an active WorkSession. Combines step completion, AC validation, test result reporting, and file tracking into a single atomic operation. All state changes are recorded on the WorkSession and its related validation/completion records.
+
+Use this instead of calling update_ticket for checklist changes. Provides:
+- Step completion (individual or bulk via WorkSessionStepCompletion)
+- Acceptance criteria validation (individual or bulk via WorkSessionACValidation)
+- Test result reporting (merged by test type via WorkSessionTestResult)
+- File tracking (created, modified, deleted on WorkSession)
+- Blocker management (set/clear block reasons)
+- Auto-calculated progress percentage
+- Completion readiness hints
+
+IMPORTANT: All acceptance criteria must be validated and all implementation steps must be completed via this tool before calling complete_work_session. The completion gate enforces this.`,
             inputSchema: {
                 type: 'object',
                 properties: {
                     ticketId: {
                         type: 'string',
-                        description: 'The ID of the ticket to resume',
+                        description: 'The ID of the ticket being worked on (must be in active status)',
+                    },
+                    steps: {
+                        type: 'array',
+                        description: 'Individual step completion updates',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                index: {
+                                    type: 'number',
+                                    description: 'Zero-based index of the step in the implementation.steps array',
+                                },
+                                completed: {
+                                    type: 'boolean',
+                                    description: 'Whether the step is completed',
+                                },
+                                notes: {
+                                    type: 'string',
+                                    description: 'Optional note about this step',
+                                },
+                            },
+                            required: ['index', 'completed'],
+                        },
+                    },
+                    allStepsDone: {
+                        type: 'boolean',
+                        description: 'Shortcut: mark all steps as completed',
+                    },
+                    acceptanceCriteria: {
+                        type: 'array',
+                        description: 'Individual AC validation updates',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                index: {
+                                    type: 'number',
+                                    description: 'Zero-based index of the AC in the acceptanceCriteria array',
+                                },
+                                validated: {
+                                    type: 'boolean',
+                                    description: 'Whether the AC is validated',
+                                },
+                                notes: {
+                                    type: 'string',
+                                    description: 'Optional note about this AC',
+                                },
+                            },
+                            required: ['index', 'validated'],
+                        },
+                    },
+                    allACValidated: {
+                        type: 'boolean',
+                        description: 'Shortcut: mark all acceptance criteria as validated',
+                    },
+                    testResults: {
+                        type: 'array',
+                        description: 'Test result reports to append (merged by testType)',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                testType: {
+                                    type: 'string',
+                                    description: 'Type of test (e.g., "unit", "integration", "e2e", "lint", "typeCheck")',
+                                },
+                                passed: {
+                                    type: 'number',
+                                    description: 'Number of tests that passed',
+                                },
+                                failed: {
+                                    type: 'number',
+                                    description: 'Number of tests that failed',
+                                },
+                                skipped: {
+                                    type: 'number',
+                                    description: 'Number of tests skipped',
+                                },
+                                command: {
+                                    type: 'string',
+                                    description: 'Command used to run the tests',
+                                },
+                                output: {
+                                    type: 'string',
+                                    description: 'Test output (truncated if needed)',
+                                },
+                                duration: {
+                                    type: 'number',
+                                    description: 'Duration in milliseconds',
+                                },
+                            },
+                            required: ['testType', 'passed', 'failed'],
+                        },
+                    },
+                    notes: {
+                        type: 'string',
+                        description: 'Additional notes to append to the ticket',
+                    },
+                    filesCreated: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Files created during this session. Accumulated incrementally.',
+                    },
+                    filesModified: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Files modified during this session. Accumulated incrementally.',
+                    },
+                    filesDeleted: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Files deleted during this session. Accumulated incrementally.',
+                    },
+                    blockReason: {
+                        type: 'string',
+                        description: 'Set a blocker on this ticket. Requires a prior discovery via report_discovery.',
+                    },
+                    clearBlockReason: {
+                        type: 'boolean',
+                        description: 'Clear existing blocker and resume work.',
                     },
                 },
                 required: ['ticketId'],
@@ -883,7 +991,7 @@ Report types:
 - 'implementation': Progress, velocity, completions (replaces get_implementation_summary)
 - 'time': Estimated vs actual hours (replaces get_time_report)
 - 'blockers': Blocked tickets with reasons (replaces get_blockers_report)
-- 'work': Completed work summary (replaces get_work_summary)
+- 'work': Completed work summary from WorkSession records (replaces get_work_summary)
 
 Format options:
 - 'json': Full structured data (default)
@@ -1475,10 +1583,6 @@ At least one scope filter (projectId, specificationId, or epicId) is required.`,
                         items: { type: 'string' },
                         description: 'Array of ticket IDs this ticket depends on',
                     },
-                    skipValidation: {
-                        type: 'boolean',
-                        description: 'Skip validation and completeness scoring. Default: false',
-                    },
                     validationStrictness: {
                         type: 'string',
                         enum: ['lenient', 'normal', 'strict'],
@@ -1587,11 +1691,6 @@ At least one scope filter (projectId, specificationId, or epicId) is required.`,
                         type: 'object',
                         description: 'Technical details like stack, endpoints (JSON) (optional)',
                     },
-                    skipValidation: {
-                        type: 'boolean',
-                        description: 'Skip validation and completeness scoring (default: false)',
-                        default: false,
-                    },
                     validationStrictness: {
                         type: 'string',
                         enum: ['lenient', 'normal', 'strict'],
@@ -2043,119 +2142,6 @@ At least one scope filter (projectId, specificationId, or epicId) is required.`,
         // ========================================================================
         // Bulk Operations
         // ========================================================================
-        {
-            name: 'bulk_create_tickets',
-            description: 'Create multiple tickets in an epic with optional inline dependencies in a single atomic transaction. Reduces 15+ API calls to one.',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    epicId: {
-                        type: 'string',
-                        description: 'The ID of the epic to create tickets in',
-                    },
-                    tickets: {
-                        type: 'array',
-                        description: 'Array of ticket definitions to create',
-                        items: {
-                            type: 'object',
-                            properties: {
-                                title: { type: 'string', description: 'Ticket title (required)' },
-                                description: { type: 'string', description: 'Ticket description' },
-                                estimatedHours: { type: 'number', description: 'Estimated hours' },
-                                complexity: {
-                                    type: 'string',
-                                    enum: ['small', 'medium', 'large', 'xlarge'],
-                                    description: 'Complexity level',
-                                },
-                                priority: {
-                                    type: 'string',
-                                    enum: ['high', 'medium', 'low'],
-                                    description: 'Priority level',
-                                },
-                                acceptanceCriteria: {
-                                    type: 'array',
-                                    items: { type: 'string' },
-                                    description: 'Acceptance criteria',
-                                },
-                                implementation: {
-                                    type: 'object',
-                                    description: 'Implementation details (filesToCreate, filesToModify, steps, etc.)',
-                                },
-                                technicalDetails: {
-                                    type: 'object',
-                                    description: 'Technical details (files, stack, endpoints, etc.)',
-                                },
-                                tags: {
-                                    type: 'array',
-                                    items: { type: 'string' },
-                                    description: 'Tags',
-                                },
-                            },
-                            required: ['title'],
-                        },
-                    },
-                    dependencies: {
-                        type: 'array',
-                        description: 'Optional inline dependencies using array indexes',
-                        items: {
-                            type: 'object',
-                            properties: {
-                                ticket: {
-                                    type: 'number',
-                                    description: 'Index of the ticket in the tickets array',
-                                },
-                                dependsOn: {
-                                    oneOf: [
-                                        { type: 'number', description: 'Index of the ticket it depends on' },
-                                        {
-                                            type: 'array',
-                                            items: { type: 'number' },
-                                            description: 'Indexes of the tickets it depends on',
-                                        },
-                                    ],
-                                    description: 'Index(es) of the ticket(s) it depends on',
-                                },
-                            },
-                            required: ['ticket', 'dependsOn'],
-                        },
-                    },
-                    onError: {
-                        type: 'string',
-                        enum: ['rollback', 'continue'],
-                        description: "Error handling mode: 'rollback' stops and undoes all, 'continue' skips failures (default: 'continue')",
-                    },
-                },
-                required: ['epicId', 'tickets'],
-            },
-        },
-        {
-            name: 'get_job_status',
-            description: 'Get the status of an asynchronous bulk operation job. For batches >= 20 items, bulk operations return a job ID for async processing.',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    jobId: {
-                        type: 'string',
-                        description: 'The job ID returned from a bulk operation',
-                    },
-                },
-                required: ['jobId'],
-            },
-        },
-        {
-            name: 'cancel_job',
-            description: 'Cancel a running async job. Only queued or processing jobs can be cancelled.',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    jobId: {
-                        type: 'string',
-                        description: 'The job ID returned from a bulk operation',
-                    },
-                },
-                required: ['jobId'],
-            },
-        },
         {
             name: 'bulk_add_dependencies',
             description: 'Add multiple dependencies between tickets in a single atomic transaction.',
@@ -3223,19 +3209,9 @@ export function createToolHandlers(apiClient) {
                 summary: args.summary,
                 filesModified: args.filesModified,
                 filesCreated: args.filesCreated,
+                filesDeleted: args.filesDeleted,
                 actualHours: args.actualHours,
-                validated: args.validated, // MCI-066: simple validation flag
-                validation: args.validation, // MCI-064: validation flags
-                skipCriteriaCheck: args.skipCriteriaCheck, // MCI-065: skip criteria check
-            });
-        },
-        report_progress: async (_client, args) => {
-            validateRequired(args, 'ticketId', 'progress');
-            validateRange(args.progress, 'progress', 0, 100);
-            return await apiClient.call('report_progress', {
-                ticketId: args.ticketId,
-                progress: args.progress,
-                message: args.message,
+                validation: args.validation,
             });
         },
         pause_work_session: async (_client, args) => {
@@ -3250,6 +3226,23 @@ export function createToolHandlers(apiClient) {
                 ticketId: args.ticketId,
             });
         },
+        action_work_session: async (_client, args) => {
+            validateRequired(args, 'ticketId');
+            return await apiClient.call('action_work_session', {
+                ticketId: args.ticketId,
+                steps: args.steps,
+                allStepsDone: args.allStepsDone,
+                acceptanceCriteria: args.acceptanceCriteria,
+                allACValidated: args.allACValidated,
+                testResults: args.testResults,
+                notes: args.notes,
+                filesCreated: args.filesCreated,
+                filesModified: args.filesModified,
+                filesDeleted: args.filesDeleted,
+                blockReason: args.blockReason,
+                clearBlockReason: args.clearBlockReason,
+            });
+        },
         // ========================================================================
         // Status & Analytics Tools
         // ========================================================================
@@ -3400,7 +3393,6 @@ export function createToolHandlers(apiClient) {
             validateRequired(args, 'epicId', 'title');
             const responseMode = getResponseModeFromArgs(args);
             // Extract validation options
-            const skipValidation = args.skipValidation === true;
             const validationStrictness = args.validationStrictness === 'lenient' || args.validationStrictness === 'strict'
                 ? args.validationStrictness
                 : 'normal';
@@ -3421,21 +3413,19 @@ export function createToolHandlers(apiClient) {
                 dependsOn: args.dependsOn,
                 notes: args.notes, // F8-001: Add missing notes field
             });
-            // Run validation unless skipped
-            if (!skipValidation) {
-                const validation = validateTicket({
-                    complexity: args.complexity,
-                    implementation: args.implementation,
-                    technicalDetails: args.technicalDetails,
-                    notes: args.notes,
-                    acceptanceCriteria: args.acceptanceCriteria,
-                });
-                // Filter warnings by strictness level
-                const warnings = filterWarningsByStrictness(validation.warnings, validationStrictness);
-                // Add validation results to response
-                result.warnings = warnings;
-                result.completenessScore = validation.completenessScore;
-            }
+            // Run validation
+            const validation = validateTicket({
+                complexity: args.complexity,
+                implementation: args.implementation,
+                technicalDetails: args.technicalDetails,
+                notes: args.notes,
+                acceptanceCriteria: args.acceptanceCriteria,
+            });
+            // Filter warnings by strictness level
+            const warnings = filterWarningsByStrictness(validation.warnings, validationStrictness);
+            // Add validation results to response
+            result.warnings = warnings;
+            result.completenessScore = validation.completenessScore;
             return formatWriteResponse(result, responseMode, 'Ticket created');
         },
         import_specification: async (_client, args) => {
@@ -3454,31 +3444,28 @@ export function createToolHandlers(apiClient) {
             validateRequired(args, 'ticketId');
             const responseMode = getResponseModeFromArgs(args);
             // Extract validation options
-            const skipValidation = args.skipValidation === true;
             const validationStrictness = args.validationStrictness === 'lenient' || args.validationStrictness === 'strict'
                 ? args.validationStrictness
                 : 'normal';
             // Get current ticket to calculate previous completeness score
             let previousCompletenessScore;
-            if (!skipValidation) {
-                try {
-                    const currentTicket = await apiClient.call('get_ticket', {
-                        ticketId: args.ticketId,
-                    });
-                    // Calculate previous completeness score
-                    const prevValidation = validateTicket({
-                        complexity: currentTicket.complexity,
-                        implementation: currentTicket.implementation,
-                        technicalDetails: currentTicket.technicalDetails,
-                        notes: currentTicket.notes,
-                        acceptanceCriteria: currentTicket.acceptanceCriteria,
-                    });
-                    previousCompletenessScore = prevValidation.completenessScore;
-                }
-                catch {
-                    // If we can't get the current ticket, skip previous score tracking
-                    previousCompletenessScore = undefined;
-                }
+            try {
+                const currentTicket = await apiClient.call('get_ticket', {
+                    ticketId: args.ticketId,
+                });
+                // Calculate previous completeness score
+                const prevValidation = validateTicket({
+                    complexity: currentTicket.complexity,
+                    implementation: currentTicket.implementation,
+                    technicalDetails: currentTicket.technicalDetails,
+                    notes: currentTicket.notes,
+                    acceptanceCriteria: currentTicket.acceptanceCriteria,
+                });
+                previousCompletenessScore = prevValidation.completenessScore;
+            }
+            catch {
+                // If we can't get the current ticket, skip previous score tracking
+                previousCompletenessScore = undefined;
             }
             // Update the ticket
             const result = await apiClient.call('update_ticket', {
@@ -3497,25 +3484,23 @@ export function createToolHandlers(apiClient) {
                 technicalDetails: args.technicalDetails,
                 blockReason: args.blockReason,
             });
-            // Run validation on updated ticket unless skipped
-            if (!skipValidation) {
-                // Use the updated values (from args) merged with existing values (from result)
-                // The result should contain the final state after update
-                const validation = validateTicket({
-                    complexity: (args.complexity || result.complexity),
-                    implementation: (args.implementation || result.implementation),
-                    technicalDetails: (args.technicalDetails || result.technicalDetails),
-                    notes: (args.notes || result.notes),
-                    acceptanceCriteria: (args.acceptanceCriteria || result.acceptanceCriteria),
-                });
-                // Filter warnings by strictness level
-                const warnings = filterWarningsByStrictness(validation.warnings, validationStrictness);
-                // Add validation results to response
-                result.warnings = warnings;
-                result.completenessScore = validation.completenessScore;
-                if (previousCompletenessScore !== undefined) {
-                    result.previousCompletenessScore = previousCompletenessScore;
-                }
+            // Run validation on updated ticket
+            // Use the updated values (from args) merged with existing values (from result)
+            // The result should contain the final state after update
+            const validation = validateTicket({
+                complexity: (args.complexity || result.complexity),
+                implementation: (args.implementation || result.implementation),
+                technicalDetails: (args.technicalDetails || result.technicalDetails),
+                notes: (args.notes || result.notes),
+                acceptanceCriteria: (args.acceptanceCriteria || result.acceptanceCriteria),
+            });
+            // Filter warnings by strictness level
+            const warnings = filterWarningsByStrictness(validation.warnings, validationStrictness);
+            // Add validation results to response
+            result.warnings = warnings;
+            result.completenessScore = validation.completenessScore;
+            if (previousCompletenessScore !== undefined) {
+                result.previousCompletenessScore = previousCompletenessScore;
             }
             return formatWriteResponse(result, responseMode, 'Ticket updated');
         },
@@ -3630,56 +3615,6 @@ export function createToolHandlers(apiClient) {
         // ========================================================================
         // Bulk Operations
         // ========================================================================
-        bulk_create_tickets: async (_client, args) => {
-            validateRequired(args, 'epicId', 'tickets');
-            if (!Array.isArray(args.tickets) || args.tickets.length === 0) {
-                throw new Error('tickets array is required and must not be empty');
-            }
-            // Validate each ticket has a title
-            const tickets = args.tickets;
-            for (let i = 0; i < tickets.length; i++) {
-                if (!tickets[i].title || typeof tickets[i].title !== 'string') {
-                    throw new Error(`tickets[${i}].title is required and must be a string`);
-                }
-            }
-            // Validate dependencies if provided
-            if (args.dependencies && Array.isArray(args.dependencies)) {
-                const deps = args.dependencies;
-                for (let i = 0; i < deps.length; i++) {
-                    const dep = deps[i];
-                    if (typeof dep.ticket !== 'number' || dep.ticket < 0 || dep.ticket >= tickets.length) {
-                        throw new Error(`dependencies[${i}].ticket must be a valid index in tickets array (0-${tickets.length - 1})`);
-                    }
-                    const dependsOn = Array.isArray(dep.dependsOn) ? dep.dependsOn : [dep.dependsOn];
-                    for (const idx of dependsOn) {
-                        if (typeof idx !== 'number' || idx < 0 || idx >= tickets.length) {
-                            throw new Error(`dependencies[${i}].dependsOn contains invalid index ${idx} (must be 0-${tickets.length - 1})`);
-                        }
-                        if (idx === dep.ticket) {
-                            throw new Error(`dependencies[${i}]: ticket cannot depend on itself`);
-                        }
-                    }
-                }
-            }
-            return await apiClient.call('bulk_create_tickets', {
-                epicId: args.epicId,
-                tickets: args.tickets,
-                dependencies: args.dependencies,
-                onError: args.onError,
-            });
-        },
-        get_job_status: async (_client, args) => {
-            validateRequired(args, 'jobId');
-            return await apiClient.call('get_job_status', {
-                jobId: args.jobId,
-            });
-        },
-        cancel_job: async (_client, args) => {
-            validateRequired(args, 'jobId');
-            return await apiClient.call('cancel_job', {
-                jobId: args.jobId,
-            });
-        },
         bulk_add_dependencies: async (_client, args) => {
             validateRequired(args, 'dependencies');
             if (!Array.isArray(args.dependencies) || args.dependencies.length === 0) {