@specforge/cli 0.1.0

package/dist/tools/index.js

@@ -0,0 +1,1499 @@
+import {
+  ValidationError,
+  ApiError,
+  validateToolArgs,
+  formatMCPError,
+  transformError
+} from "../validation/index.js";
+import { injectContext, injectContextRequired } from "./core/context-helper.js";
+import { tryLoadProjectConfig, saveProjectConfig } from "../cli/config/index.js";
+import {
+  appendPlanningSessionRegistry,
+  markPlanningSessionRegistryCompleted
+} from "../cli/config/planning-sessions-registry.js";
+function getTools() {
+  const tools = [
+    // ========================================================================
+    // Queries (6)
+    // ========================================================================
+    {
+      name: "get",
+      description: "Get a single entity by type and ID.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          type: {
+            type: "string",
+            enum: ["project", "specification", "epic", "ticket", "implementation_session"],
+            description: "Entity type to retrieve"
+          },
+          id: {
+            type: "string",
+            description: "Entity ID (for project, specification, epic, ticket)"
+          },
+          specificationId: {
+            type: "string",
+            description: "Specification ID (for implementation_session)"
+          }
+        },
+        required: ["type"]
+      }
+    },
+    {
+      name: "list",
+      description: "List entities by type.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          type: {
+            type: "string",
+            enum: ["projects", "specifications", "epics", "tickets"],
+            description: "Entity type to list"
+          },
+          projectId: {
+            type: "string",
+            description: "Filter by project (for specifications)"
+          },
+          specificationId: {
+            type: "string",
+            description: "Filter by specification (for epics, tickets)"
+          },
+          epicId: {
+            type: "string",
+            description: "Filter by epic (for tickets)"
+          }
+        },
+        required: ["type"]
+      }
+    },
+    {
+      name: "search",
+      description: `Unified ticket search with multiple filter options.
+
+Combines:
+- Full-text search (query)
+- File matching (files) - replaces find_tickets_by_file
+- Tag filtering (tags) - replaces find_tickets_by_tag
+- Related tickets (relatedTo) - replaces find_related_tickets
+- Status, complexity, priority filters
+
+At least one of: query, files, tags, or relatedTo is required.
+At least one scope filter (projectId, specificationId, or epicId) is required.`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: {
+            type: "string",
+            description: "Full-text search query"
+          },
+          files: {
+            type: "array",
+            items: { type: "string" },
+            description: 'Glob patterns to match ticket files (e.g., "**/channel/*.ts")'
+          },
+          tags: {
+            type: "array",
+            items: { type: "string" },
+            description: "Tags to filter by"
+          },
+          matchAllTags: {
+            type: "boolean",
+            description: "If true, match all tags (AND). If false, match any (OR). Default: false"
+          },
+          relatedTo: {
+            type: "string",
+            description: "Find tickets related to this ticket ID (by tags, files, tech stack)"
+          },
+          status: {
+            type: "array",
+            items: {
+              type: "string",
+              enum: ["pending", "ready", "active", "done"]
+            },
+            description: "Filter by status"
+          },
+          complexity: {
+            type: "array",
+            items: {
+              type: "string",
+              enum: ["small", "medium", "large", "xlarge"]
+            },
+            description: "Filter by complexity"
+          },
+          priority: {
+            type: "array",
+            items: {
+              type: "string",
+              enum: ["low", "medium", "high", "critical"]
+            },
+            description: "Filter by priority"
+          },
+          projectId: {
+            type: "string",
+            description: "Limit search to project"
+          },
+          specificationId: {
+            type: "string",
+            description: "Limit search to specification"
+          },
+          epicId: {
+            type: "string",
+            description: "Limit search to epic"
+          },
+          limit: {
+            type: "number",
+            description: "Maximum results (default: 20, max: 100)"
+          },
+          offset: {
+            type: "number",
+            description: "Pagination offset (default: 0)"
+          },
+          fields: {
+            type: "array",
+            items: {
+              type: "string",
+              enum: [
+                "id",
+                "epicId",
+                "ticketNumber",
+                "title",
+                "description",
+                "status",
+                "priority",
+                "complexity",
+                "estimatedHours",
+                "actualHours",
+                "acceptanceCriteria",
+                "implementation",
+                "technicalDetails",
+                "notes",
+                "tags",
+                "blockReason",
+                "progress",
+                "testsPassed",
+                "order",
+                "startedAt",
+                "completedAt",
+                "createdAt",
+                "updatedAt"
+              ]
+            },
+            description: "Select specific fields to return. Returns all fields if not specified. id is always included."
+          }
+        }
+      }
+    },
+    {
+      name: "get_next_actionable_tickets",
+      description: 'Get tickets with status "ready" (all dependencies satisfied). Use start_work_session() to begin work on these tickets.',
+      inputSchema: {
+        type: "object",
+        properties: {
+          specificationId: {
+            type: "string",
+            description: "The ID of the specification (optional if projectId provided)"
+          },
+          projectId: {
+            type: "string",
+            description: "The ID of the project to get actionable tickets across all specifications"
+          },
+          limit: {
+            type: "number",
+            description: "Maximum number of tickets to return (default: 5)"
+          }
+        }
+      }
+    },
+    {
+      name: "get_blocked_tickets",
+      description: 'Get tickets with status "pending" and their statusReason explaining why they are blocked (unsatisfied dependencies or external block)',
+      inputSchema: {
+        type: "object",
+        properties: {
+          specificationId: {
+            type: "string",
+            description: "The ID of the specification"
+          }
+        },
+        required: ["specificationId"]
+      }
+    },
+    {
+      name: "get_report",
+      description: `Generate unified reports for implementation, time tracking, blockers, work summary, or active sessions.
+
+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 from WorkSession records (replaces get_work_summary)
+- 'implementation_analysis': Deeper implementation insights
+- 'sessions': Live planning/work/review sessions for a project (requires scope='project')
+
+Format options:
+- 'json': Full structured data (default)
+- 'summary': Condensed text summary`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          type: {
+            type: "string",
+            enum: ["implementation", "time", "blockers", "work", "implementation_analysis", "sessions"],
+            description: "Type of report to generate"
+          },
+          scope: {
+            type: "string",
+            enum: ["project", "specification", "epic"],
+            description: "Scope of the report. 'sessions' requires scope='project'."
+          },
+          scopeId: {
+            type: "string",
+            description: "ID of the scoped entity (projectId, specificationId, or epicId)"
+          },
+          startDate: {
+            type: "string",
+            description: "Start date for work report (ISO 8601)"
+          },
+          endDate: {
+            type: "string",
+            description: "End date for work report (ISO 8601)"
+          }
+        },
+        required: ["type", "scope", "scopeId"]
+      }
+    },
+    // ========================================================================
+    // Lifecycle (10)
+    // ========================================================================
+    {
+      name: "start_planning_session",
+      description: "Start or resume a guided planning session for a specification. Project-scoped lock: only one active planning session per project (the project is derived from the spec \u2014 you do not pass it). Calling with the same spec resumes the existing session (idempotent). Calling with a different spec while one is active returns a rejection with the active session details. Planning is independent of implementation and review \u2014 they can run concurrently.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          specificationId: {
+            type: "string",
+            description: "The specification to plan. Optional \u2014 defaults to the active spec in the local config (.specforge/config.json), so you normally omit it. Do NOT pass projectId; it is derived from the spec."
+          }
+        },
+        // Nothing is required: specificationId falls back to local config, and the
+        // returned sessionId is persisted + injected into subsequent calls.
+        required: []
+      }
+    },
+    {
+      name: "action_planning_session",
+      description: "Execute a planning action within an active session. Wraps all planning operations (create/update epics, tickets, dependencies, blueprints) and read operations (get_ticket for inspecting details, gps for full readiness X-ray worst-first) with automatic status tracking. The spec status advances or regresses automatically based on the action type and gate checks. Returns updated progress, blockers, and next suggested actions after every call. Use responseDetail to control verbosity: 'minimal' (~80 tokens) for rapid iteration, 'standard' (~200 tokens, default) for normal work, 'full' (~500 tokens) for debugging.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          operation: {
+            type: "object",
+            description: 'The operation to perform. Must include a "type" field. Per-op required fields are declared in `oneOf` below \u2014 agents should consult their own tool schema parser for the exact shape per type. Do NOT pass sessionId/projectId/specificationId: the active planning session is injected from local config.',
+            properties: {
+              type: {
+                type: "string",
+                enum: [
+                  "set_metadata",
+                  "create_epic",
+                  "update_epic",
+                  "create_ticket",
+                  "update_ticket",
+                  "delete_epic",
+                  "delete_ticket",
+                  "add_dependencies",
+                  "remove_dependency",
+                  "create_blueprint",
+                  "link_blueprint",
+                  "update_blueprint",
+                  "delete_blueprint",
+                  "unlink_blueprint",
+                  "get_ticket",
+                  "get_status",
+                  "gps"
+                ],
+                description: "The type of planning operation to perform"
+              }
+            },
+            required: ["type"],
+            oneOf: [
+              {
+                properties: { type: { const: "set_metadata" } },
+                required: ["type"]
+              },
+              {
+                properties: {
+                  type: { const: "create_epic" },
+                  title: { type: "string", minLength: 1, description: "Epic title (non-empty)" },
+                  description: { type: "string", minLength: 1, description: "What this epic delivers" },
+                  objective: { type: "string", minLength: 1, description: "Goal achieved for the user" },
+                  goals: { type: "array", items: { type: "string" } },
+                  acceptanceCriteria: { type: "array", items: { type: "string" } },
+                  tickets: { type: "array", description: "Optional bulk-create tickets within the epic" }
+                },
+                required: ["type", "title", "description", "objective"]
+              },
+              {
+                properties: {
+                  type: { const: "update_epic" },
+                  epicId: { type: "string", description: "Epic id; use list_epics or lookup_epic to find" }
+                },
+                required: ["type", "epicId"]
+              },
+              {
+                properties: {
+                  type: { const: "create_ticket" },
+                  epicId: { type: "string", description: "Parent epic id" },
+                  title: { type: "string", minLength: 1, description: "Ticket title (non-empty)" },
+                  description: { type: "string" },
+                  ticketType: { type: "string", enum: ["implementation", "verification"], description: "Ticket type \u2014 implementation (default) or verification (tests/QA). Drives which fields the readiness rubric expects." },
+                  priority: { type: "string", enum: ["high", "medium", "low"] },
+                  complexity: { type: "string", enum: ["small", "medium", "large", "xlarge"] },
+                  acceptanceCriteria: { type: "array", items: { type: "string" } },
+                  implementationSteps: { type: "array", items: { type: "string" }, description: "Implementation steps; persisted as TicketImplementationStep rows" },
+                  dependsOn: { type: "array", items: { type: "string" }, description: "Other ticket ids this depends on; created post-insert" }
+                },
+                required: ["type", "epicId", "title"]
+              },
+              {
+                properties: {
+                  type: { const: "update_ticket" },
+                  ticketId: { type: "string", description: "Ticket id; use list_tickets or lookup_ticket to find" }
+                },
+                required: ["type", "ticketId"]
+              },
+              {
+                properties: {
+                  type: { const: "delete_epic" },
+                  epicId: { type: "string", description: "Epic id; cascades to all tickets in the epic" }
+                },
+                required: ["type", "epicId"]
+              },
+              {
+                properties: {
+                  type: { const: "delete_ticket" },
+                  ticketId: { type: "string" }
+                },
+                required: ["type", "ticketId"]
+              },
+              {
+                properties: {
+                  type: { const: "add_dependencies" },
+                  dependencies: {
+                    type: "array",
+                    minItems: 1,
+                    maxItems: 100,
+                    description: "Up to 100 dependency pairs. Valid pairs commit; malformed pairs come back in failed[] with a per-entry reason.",
+                    items: {
+                      type: "object",
+                      properties: {
+                        ticketId: { type: "string", description: "The dependent ticket" },
+                        dependsOnId: { type: "string", description: "The blocker ticket" },
+                        type: { type: "string", enum: ["requires", "blocks"], description: 'Defaults to "requires"' }
+                      },
+                      required: ["ticketId", "dependsOnId"]
+                    }
+                  }
+                },
+                required: ["type", "dependencies"]
+              },
+              {
+                properties: {
+                  type: { const: "remove_dependency" },
+                  dependencyId: { type: "string" }
+                },
+                required: ["type", "dependencyId"]
+              },
+              {
+                properties: {
+                  type: { const: "remove_dependency" },
+                  ticketId: { type: "string" },
+                  dependsOnId: { type: "string" }
+                },
+                required: ["type", "ticketId", "dependsOnId"]
+              },
+              {
+                properties: {
+                  type: { const: "create_blueprint" },
+                  title: { type: "string", minLength: 1, description: "Blueprint title (non-empty)" },
+                  content: { type: "string", description: "Body. Mermaid format extracts ```mermaid``` fences automatically." },
+                  format: { type: "string", description: 'Defaults to "mermaid"' },
+                  category: { type: "string" },
+                  description: { type: "string" },
+                  tags: { type: "array", items: { type: "string" } }
+                },
+                required: ["type", "title"]
+              },
+              {
+                properties: {
+                  type: { const: "update_blueprint" },
+                  blueprintId: { type: "string" }
+                },
+                required: ["type", "blueprintId"]
+              },
+              {
+                properties: {
+                  type: { const: "delete_blueprint" },
+                  blueprintId: { type: "string" }
+                },
+                required: ["type", "blueprintId"]
+              },
+              {
+                properties: {
+                  type: { const: "link_blueprint" },
+                  ticketId: { type: "string" },
+                  blueprintId: { type: "string" },
+                  context: { type: "string", description: "Optional context annotation" },
+                  section: { type: "string", description: "Optional section reference" }
+                },
+                required: ["type", "ticketId", "blueprintId"]
+              },
+              {
+                properties: {
+                  type: { const: "unlink_blueprint" },
+                  referenceId: { type: "string" }
+                },
+                required: ["type", "referenceId"]
+              },
+              {
+                properties: {
+                  type: { const: "unlink_blueprint" },
+                  ticketId: { type: "string" },
+                  blueprintId: { type: "string" }
+                },
+                required: ["type", "ticketId", "blueprintId"]
+              },
+              {
+                properties: {
+                  type: { const: "get_ticket" },
+                  ticketId: { type: "string" },
+                  include: { type: "array", items: { type: "string", enum: ["dependencies", "testStatus", "statusReason"] } }
+                },
+                required: ["type", "ticketId"]
+              },
+              {
+                properties: { type: { const: "get_status" } },
+                required: ["type"]
+              },
+              {
+                properties: {
+                  type: { const: "gps" },
+                  responseDetail: { type: "string", enum: ["minimal", "standard", "full"] }
+                },
+                required: ["type"]
+              }
+            ]
+          },
+          responseDetail: {
+            type: "string",
+            enum: ["minimal", "standard", "full"],
+            description: "Response detail level: minimal (~80 tokens), standard (~200, default), full (~500)"
+          }
+        },
+        required: ["operation"]
+      }
+    },
+    {
+      name: "complete_planning_session",
+      description: "Complete the planning session and submit the spec for final review. Spec must be in 'planning' status. Runs the planning gate (consistency checks + readinessThreshold from project/spec settings). Transitions the spec directly to 'ready' on pass. Takes no arguments \u2014 the active planning session is injected from local config.",
+      inputSchema: {
+        type: "object",
+        // No inputs: the active planning session (sessionId) is injected from
+        // local config (.specforge/config.json). Do NOT pass sessionId/projectId/specificationId.
+        properties: {},
+        required: []
+      }
+    },
+    {
+      name: "start_work_session",
+      description: "Start working on a ticket. Returns full ticket details (description, implementation steps, AC, technicalDetails, codeReferences, typeReferences, tags, notes, complexity, priority) alongside checklistState and workSessionId. No need to call get_ticket separately. Returns error with statusReason if ticket is pending.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          ticketId: {
+            type: "string",
+            description: "The ID of the ticket to start"
+          }
+        },
+        required: ["ticketId"]
+      }
+    },
+    {
+      name: "action_work_session",
+      description: `Update checklist state during an active WorkSession. Combines step completion, AC validation, test result reporting, file tracking, reference review confirmation, and discovery reporting 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)
+- Discovery reporting (create discoveries for blockers, bugs, tech debt)
+- Blocker management (set block reason; requires existing discovery)
+- Reference review tracking (codeSnippetsReviewed, typeReferencesReviewed)
+- 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.
+
+If the ticket has codeReferences or typeReferences, set codeSnippetsReviewed/typeReferencesReviewed to true after reviewing them \u2014 completion readiness will block until these are confirmed.
+
+Set getTicket: true to fetch full ticket details in the response \u2014 useful for re-reading ticket context mid-implementation. Can be the sole operation or combined with other actions.`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          ticketId: {
+            type: "string",
+            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"
+                },
+                suites: {
+                  type: "array",
+                  description: "Optional suite-level breakdown",
+                  items: {
+                    type: "object",
+                    properties: {
+                      name: { type: "string", description: "Suite name" },
+                      passed: { type: "number", description: "Passed tests in suite" },
+                      failed: { type: "number", description: "Failed tests in suite" },
+                      skipped: { type: "number", description: "Skipped tests in suite" },
+                      duration: { type: "number", description: "Suite duration in ms" }
+                    },
+                    required: ["name", "passed", "failed"]
+                  }
+                },
+                tests: {
+                  type: "array",
+                  description: "Optional individual test breakdown",
+                  items: {
+                    type: "object",
+                    properties: {
+                      name: { type: "string", description: "Test name" },
+                      suite: { type: "string", description: "Parent suite name" },
+                      status: { type: "string", enum: ["passed", "failed", "skipped"], description: "Test result" },
+                      duration: { type: "number", description: "Test duration in ms" }
+                    },
+                    required: ["name", "status"]
+                  }
+                }
+              },
+              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."
+          },
+          discovery: {
+            type: "object",
+            description: "Create a discovery (observation about the implementation). Use this to report blockers, bugs, tech debt, scope changes, etc.",
+            properties: {
+              description: { type: "string", description: "Description of the discovery" },
+              type: { type: "string", description: "Discovery type: bug, tech_debt, blocker, clarification, scope_change, dependency, risk, ticket, epic" },
+              severity: { type: "string", description: "Severity: blocker, critical, major, minor" },
+              suggestedTitle: { type: "string", description: "Suggested title for the new ticket/epic" },
+              suggestedPriority: { type: "string", description: "Suggested priority: high, medium, low" },
+              relatedFiles: { type: "array", items: { type: "string" }, description: "Related file paths" },
+              notes: { type: "string", description: "Additional notes" }
+            },
+            required: ["description"]
+          },
+          blockReason: {
+            type: "string",
+            description: "Set a blocker on this ticket. Requires an existing discovery (create via discovery parameter first)."
+          },
+          getTicket: {
+            type: "boolean",
+            description: "Fetch full ticket details. Can be the sole operation or combined with other actions."
+          },
+          includeFullContext: {
+            type: "boolean",
+            description: "Include full implementation context in response"
+          },
+          codeSnippetsReviewed: {
+            type: "boolean",
+            description: "Confirm that code snippets (codeReferences) on the ticket have been reviewed. Required before completion when the ticket has non-empty codeReferences."
+          },
+          typeReferencesReviewed: {
+            type: "boolean",
+            description: "Confirm that type references (typeReferences) on the ticket have been reviewed. Required before completion when the ticket has non-empty typeReferences."
+          }
+        },
+        required: ["ticketId"]
+      }
+    },
+    {
+      name: "complete_work_session",
+      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\nAll acceptance criteria must be validated and all implementation steps must be completed via action_work_session before calling this. The completion gate enforces this \u2014 shortcuts are not available.\n\nAutomatically recalculates status for dependent tickets and returns cascade info.\n\nOptional validation flags can be provided to report test results inline:\n- tests: Unit/integration test results\n- lint: Linting results\n- typeCheck: TypeScript type checking\n- build: Build/compilation results",
+      inputSchema: {
+        type: "object",
+        properties: {
+          ticketId: {
+            type: "string",
+            description: "The ID of the ticket"
+          },
+          summary: {
+            type: "string",
+            description: "Summary of work completed"
+          },
+          filesModified: {
+            type: "array",
+            items: { type: "string" },
+            description: "List of files modified"
+          },
+          filesCreated: {
+            type: "array",
+            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"
+          },
+          validation: {
+            type: "object",
+            description: "Detailed validation flags for reporting test/lint/build results",
+            properties: {
+              tests: {
+                type: "string",
+                enum: ["passed", "failed", "skipped", "na"],
+                description: "Unit/integration test results"
+              },
+              lint: {
+                type: "string",
+                enum: ["passed", "failed", "skipped", "na"],
+                description: "Linting results"
+              },
+              typeCheck: {
+                type: "string",
+                enum: ["passed", "failed", "skipped", "na"],
+                description: "TypeScript type checking results"
+              },
+              build: {
+                type: "string",
+                enum: ["passed", "failed", "skipped", "na"],
+                description: "Build/compilation results"
+              },
+              notes: {
+                type: "string",
+                description: "Additional validation notes"
+              }
+            }
+          }
+        },
+        required: ["ticketId", "summary"]
+      }
+    },
+    {
+      name: "start_review_session",
+      description: 'Start the implementation review lifecycle. Runs the implementation gate and either auto-transitions to "reviewed" (on pass) or transitions to "in_review" with an active ReviewSession (on fail). Creates correction tickets via action_review_session, then call complete_review_session.',
+      inputSchema: {
+        type: "object",
+        properties: {
+          specificationId: {
+            type: "string",
+            description: "The ID of the specification to review (must be in ready_for_review status)"
+          }
+        },
+        required: ["specificationId"]
+      }
+    },
+    {
+      name: "action_review_session",
+      description: 'Address findings in an active review session. Create correction tickets inline or dismiss findings with justification. Only available when specification is in "in_review" status.',
+      inputSchema: {
+        type: "object",
+        properties: {
+          specificationId: {
+            type: "string",
+            description: "The ID of the specification"
+          },
+          reviewSessionId: {
+            type: "string",
+            description: "The review session ID (auto-detected if omitted)"
+          },
+          findingsAddressed: {
+            type: "array",
+            description: "Findings to address in this action",
+            items: {
+              type: "object",
+              properties: {
+                findingId: {
+                  type: "string",
+                  description: "The finding ID to address"
+                },
+                action: {
+                  type: "string",
+                  enum: ["correction_ticket", "dismissed"],
+                  description: "How to address the finding"
+                },
+                correctionTicket: {
+                  type: "object",
+                  description: "Inline ticket creation params (required for correction_ticket action)",
+                  properties: {
+                    epicId: { type: "string", description: "Epic to add the correction ticket to" },
+                    title: { type: "string", description: "Ticket title" },
+                    description: { type: "string", description: "Ticket description" },
+                    ticketType: { type: "string", enum: ["implementation", "verification"], description: "Ticket type \u2014 defaults to implementation." },
+                    priority: { type: "string", enum: ["low", "medium", "high", "critical"] },
+                    complexity: { type: "string", enum: ["small", "medium", "large", "xlarge"] },
+                    estimatedHours: { type: "number" },
+                    acceptanceCriteria: { type: "array", items: { type: "string" } },
+                    implementationSteps: { type: "array", items: { type: "string" }, description: "Implementation steps; persisted as TicketImplementationStep rows" },
+                    tags: { type: "array", items: { type: "string" } }
+                  },
+                  required: ["epicId", "title"]
+                },
+                justification: {
+                  type: "string",
+                  description: 'Required justification when action is "dismissed"'
+                }
+              },
+              required: ["findingId", "action"]
+            }
+          },
+          notes: {
+            type: "string",
+            description: "Optional notes for this review action"
+          }
+        },
+        required: ["specificationId"]
+      }
+    },
+    {
+      name: "complete_review_session",
+      description: 'Complete an active review session. All error-severity findings must be addressed. If correction tickets exist, transitions to "in_progress". If all findings dismissed, triggers user confirmation flow.',
+      inputSchema: {
+        type: "object",
+        properties: {
+          specificationId: {
+            type: "string",
+            description: "The ID of the specification"
+          },
+          reviewSessionId: {
+            type: "string",
+            description: "The review session ID (auto-detected if omitted)"
+          },
+          summary: {
+            type: "string",
+            description: "Optional completion summary"
+          },
+          confirmAllDismissed: {
+            type: "boolean",
+            description: "Set to true when all findings were dismissed to trigger user confirmation flow"
+          }
+        },
+        required: ["specificationId"]
+      }
+    },
+    {
+      name: "reopen_specification",
+      description: 'Reopen a specification in "ready" status, regressing to "planning". After reopening, call start_planning_session to begin a new planning session.',
+      inputSchema: {
+        type: "object",
+        properties: {
+          specificationId: {
+            type: "string",
+            description: "The ID of the specification to reopen"
+          }
+        },
+        required: ["specificationId"]
+      }
+    },
+    // Spec creation is a HUMAN bootstrap step, NOT an agent MCP tool: specs are
+    // created via `specforge init` (cli-rest surface), which also writes the new
+    // spec id into the local config so the agent's per-call injection finds it.
+    // The agent assumes the spec already exists and starts from
+    // `start_planning_session`. (Backend keeps `create_specification` REST-only;
+    // it was never dispatchable on /local.)
+    // ========================================================================
+    // Utilities (3)
+    // ========================================================================
+    {
+      name: "feedback",
+      description: `Submit and manage feedback about MCP tools. Operations:
+- submit: Submit new feedback (requires category, summary)
+- list: List recent feedback entries
+- get: Get a specific feedback entry by ID`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          operation: {
+            type: "string",
+            enum: ["submit", "list", "get"],
+            description: "The operation to perform"
+          },
+          // For submit operation
+          category: {
+            type: "string",
+            enum: ["bug", "feature_request", "usability", "documentation", "performance"],
+            description: "Feedback category (required for submit)"
+          },
+          summary: {
+            type: "string",
+            description: "Brief summary of the feedback (required for submit)"
+          },
+          severity: {
+            type: "string",
+            enum: ["critical", "high", "medium", "low"],
+            description: "Severity level (default: medium)"
+          },
+          tool: {
+            type: "string",
+            description: "Which MCP tool this relates to"
+          },
+          toolOperation: {
+            type: "string",
+            description: "Specific operation within the tool"
+          },
+          details: {
+            type: "string",
+            description: "Extended description"
+          },
+          expected: {
+            type: "string",
+            description: "Expected behavior"
+          },
+          actual: {
+            type: "string",
+            description: "Actual behavior"
+          },
+          errorMessage: {
+            type: "string",
+            description: "Error message if reporting a bug"
+          },
+          ticketId: {
+            type: "string",
+            description: "Related ticket ID"
+          },
+          // For list operation
+          limit: {
+            type: "number",
+            description: "Maximum entries to return (default: 10)"
+          },
+          categoryFilter: {
+            type: "string",
+            enum: ["bug", "feature_request", "usability", "documentation", "performance"],
+            description: "Filter by category"
+          },
+          // For get operation
+          feedbackId: {
+            type: "string",
+            description: "Feedback ID to retrieve (required for get)"
+          }
+        },
+        required: ["operation"]
+      }
+    },
+    {
+      name: "reset_work_session",
+      description: "Reset tickets to pending/ready status (calculated from dependencies). Returns statusCalculation showing how many became pending vs ready.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          specificationId: {
+            type: "string",
+            description: "The specification containing the tickets"
+          },
+          ticketIds: {
+            type: "array",
+            items: { type: "string" },
+            description: "Specific ticket IDs to reset"
+          },
+          fromTicketId: {
+            type: "string",
+            description: "Reset this ticket and all its dependents"
+          },
+          epicId: {
+            type: "string",
+            description: "Reset all tickets in this epic"
+          },
+          allTickets: {
+            type: "boolean",
+            description: "Reset all tickets in the specification"
+          },
+          resetDependents: {
+            type: "boolean",
+            description: "Also reset tickets that depend on the specified tickets (default: false)"
+          },
+          includeCompleted: {
+            type: "boolean",
+            description: "Include tickets with done status in the reset (default: false)"
+          },
+          preserveNotes: {
+            type: "boolean",
+            description: "Keep existing notes on tickets (default: true)"
+          },
+          clearTestResults: {
+            type: "boolean",
+            description: "Clear test result history (default: false)"
+          }
+        },
+        required: ["specificationId"]
+      }
+    },
+    {
+      name: "link_pull_request",
+      description: "Associate a pull request with a ticket",
+      inputSchema: {
+        type: "object",
+        properties: {
+          ticketId: {
+            type: "string",
+            description: "The ID of the ticket"
+          },
+          prNumber: {
+            type: "number",
+            description: "PR number (provide this or prUrl)"
+          },
+          prUrl: {
+            type: "string",
+            description: "Full PR URL (GitHub, GitLab, or Bitbucket)"
+          },
+          title: {
+            type: "string",
+            description: "PR title"
+          },
+          author: {
+            type: "string",
+            description: "PR author"
+          },
+          repoUrl: {
+            type: "string",
+            description: "Repository URL (required if using prNumber)"
+          }
+        },
+        required: ["ticketId"]
+      }
+    },
+    // ========================================================================
+    // Orchestration (2)
+    // ========================================================================
+    {
+      name: "get_critical_path",
+      description: "Get the critical execution path for a specification.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          specificationId: {
+            type: "string",
+            description: "Specification ID"
+          }
+        },
+        required: ["specificationId"]
+      }
+    },
+    {
+      name: "get_dependency_tree",
+      description: "Get the full dependency tree for a specification.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          specificationId: {
+            type: "string",
+            description: "Specification ID"
+          }
+        },
+        required: ["specificationId"]
+      }
+    }
+  ];
+  return tools;
+}
+const RETRY_CONFIG = {
+  maxRetries: 3,
+  initialDelayMs: 500,
+  maxDelayMs: 5e3,
+  backoffMultiplier: 2
+};
+const TRANSIENT_ERROR_PATTERNS = [
+  /ETIMEDOUT/i,
+  /ECONNRESET/i,
+  /ECONNREFUSED/i,
+  /socket hang up/i,
+  /network error/i,
+  /too many requests/i,
+  /rate limit/i,
+  /5\d{2}/
+  // 5xx status codes
+];
+function isTransientError(error) {
+  return TRANSIENT_ERROR_PATTERNS.some(
+    (pattern) => pattern.test(error.message)
+  );
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function withRetry(fn, toolName, debug) {
+  let lastError = null;
+  let delay = RETRY_CONFIG.initialDelayMs;
+  for (let attempt = 1; attempt <= RETRY_CONFIG.maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+      if (attempt < RETRY_CONFIG.maxRetries && isTransientError(lastError)) {
+        if (debug) {
+          console.error(
+            `[DEBUG] Tool ${toolName} attempt ${attempt} failed with transient error, retrying in ${delay}ms:`,
+            lastError.message
+          );
+        }
+        await sleep(delay);
+        delay = Math.min(delay * RETRY_CONFIG.backoffMultiplier, RETRY_CONFIG.maxDelayMs);
+      } else {
+        break;
+      }
+    }
+  }
+  throw lastError;
+}
+function createToolHandlers(apiClient) {
+  const callLocal = async (op, args) => {
+    const body = await apiClient.getTransport().execute(op, args);
+    if (body && typeof body === "object") {
+      if (body.kind === "standard_error") {
+        const guidance = body.guidance;
+        const prose = guidance && typeof guidance.prose === "string" ? guidance.prose : void 0;
+        throw new Error(
+          prose ?? (typeof body.message === "string" ? body.message : `Operation failed: ${op}`)
+        );
+      }
+      if (body.kind === "lifecycle" && "agentResponse" in body) {
+        return body.agentResponse;
+      }
+    }
+    return body;
+  };
+  return {
+    // ========================================================================
+    // Queries — forward the canonical super-tools straight through (the backend
+    // owns the `type` dispatch; M9 dropped the old granular-op fan-out).
+    // ========================================================================
+    get: async (_client, args) => {
+      if (!args.type) throw new Error("Missing required argument: type");
+      const withCtx = injectContext(args, ["projectId", "specificationId"]);
+      return await callLocal("get", withCtx);
+    },
+    list: async (_client, args) => {
+      if (!args.type) throw new Error("Missing required argument: type");
+      const withCtx = injectContext(args, ["projectId", "specificationId"]);
+      return await callLocal("list", withCtx);
+    },
+    search: async (_client, args) => {
+      if (!args.query && !args.files && !args.tags && !args.relatedTo) {
+        throw new Error("At least one filter is required: query, files, tags, or relatedTo");
+      }
+      const withCtx = injectContext(args, ["projectId", "specificationId"]);
+      if (!withCtx.projectId && !withCtx.specificationId && !withCtx.epicId) {
+        throw new Error('One of projectId, specificationId, or epicId is required. Run "specforge switch" or provide explicitly.');
+      }
+      return await callLocal("search", withCtx);
+    },
+    get_next_actionable_tickets: async (_client, args) => {
+      const argsWithContext = injectContext(args, ["projectId", "specificationId"]);
+      if (!argsWithContext.specificationId && !argsWithContext.projectId) {
+        throw new Error('Either specificationId or projectId is required. Set working context with "specforge switch" or provide explicitly.');
+      }
+      return await callLocal("get_next_actionable_tickets", {
+        specificationId: argsWithContext.specificationId,
+        projectId: argsWithContext.projectId,
+        limit: argsWithContext.limit ?? 5
+      });
+    },
+    get_blocked_tickets: async (_client, args) => {
+      const argsWithContext = injectContext(args, ["specificationId"]);
+      if (!argsWithContext.specificationId) {
+        throw new Error('specificationId is required. Set working context with "specforge switch" or provide explicitly.');
+      }
+      return await callLocal("get_blocked_tickets", {
+        specificationId: argsWithContext.specificationId
+      });
+    },
+    get_report: async (_client, args) => {
+      validateRequired(args, "type", "scope", "scopeId");
+      return await callLocal("get_report", {
+        type: args.type,
+        scope: args.scope,
+        scopeId: args.scopeId,
+        format: args.format ?? "json",
+        startDate: args.startDate,
+        endDate: args.endDate
+      });
+    },
+    // ========================================================================
+    // Lifecycle
+    // ========================================================================
+    // Planning lifecycle (M9.6b) — identity/session injected from the
+    // `.specforge` config; SPS persists the session id, a `closed` status
+    // clears it. Payloads match the post-M8 boundary (SPS {specificationId};
+    // APS {sessionId, operation:{type,...}}; CPS {sessionId}).
+    start_planning_session: async (_client, args) => {
+      const cfg = tryLoadProjectConfig();
+      const specificationId = args.specificationId ?? cfg?.specificationId;
+      if (!specificationId) {
+        throw new Error("No active specification. Run `specforge switch <spec-id>` or pass specificationId.");
+      }
+      const agentResponse = await callLocal(
+        "start_planning_session",
+        { specificationId }
+      );
+      if (agentResponse?.sessionId) {
+        saveProjectConfig({ planningSessionId: agentResponse.sessionId });
+        appendPlanningSessionRegistry({
+          specificationId,
+          planningSessionId: agentResponse.sessionId,
+          startedAt: (/* @__PURE__ */ new Date()).toISOString()
+        });
+      }
+      return agentResponse;
+    },
+    action_planning_session: async (_client, args) => {
+      if (!args.operation || typeof args.operation !== "object") {
+        throw new Error('Missing required argument: operation (e.g. { type: "get_planning_status" })');
+      }
+      const cfg = tryLoadProjectConfig();
+      const sessionId = args.sessionId ?? cfg?.planningSessionId;
+      if (!sessionId) {
+        throw new Error("No active planning session. Call start_planning_session first.");
+      }
+      const agentResponse = await callLocal(
+        "action_planning_session",
+        { sessionId, operation: args.operation }
+      );
+      if (agentResponse?.planningStatus === "closed" && cfg?.specificationId) {
+        saveProjectConfig({ planningSessionId: void 0 });
+        markPlanningSessionRegistryCompleted({
+          specificationId: cfg.specificationId,
+          completedAt: (/* @__PURE__ */ new Date()).toISOString()
+        });
+      }
+      return agentResponse;
+    },
+    complete_planning_session: async (_client, args) => {
+      const cfg = tryLoadProjectConfig();
+      const sessionId = args.sessionId ?? cfg?.planningSessionId;
+      if (!sessionId) {
+        throw new Error("No active planning session. Call start_planning_session first.");
+      }
+      return await callLocal("complete_planning_session", { sessionId });
+    },
+    start_work_session: async (_client, args) => {
+      validateRequired(args, "ticketId");
+      return await callLocal("start_work_session", {
+        ticketId: args.ticketId
+      });
+    },
+    action_work_session: async (_client, args) => {
+      validateRequired(args, "ticketId");
+      return await callLocal("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,
+        discovery: args.discovery,
+        blockReason: args.blockReason,
+        getTicket: args.getTicket,
+        includeFullContext: args.includeFullContext,
+        codeSnippetsReviewed: args.codeSnippetsReviewed,
+        typeReferencesReviewed: args.typeReferencesReviewed
+      });
+    },
+    complete_work_session: async (_client, args) => {
+      validateRequired(args, "ticketId", "summary");
+      return await callLocal("complete_work_session", {
+        ticketId: args.ticketId,
+        summary: args.summary,
+        filesModified: args.filesModified,
+        filesCreated: args.filesCreated,
+        filesDeleted: args.filesDeleted,
+        actualHours: args.actualHours,
+        validation: args.validation
+      });
+    },
+    start_review_session: async (_client, args) => {
+      const argsWithContext = injectContextRequired(args, ["specificationId"]);
+      return await callLocal("start_review_session", {
+        specificationId: argsWithContext.specificationId
+      });
+    },
+    action_review_session: async (_client, args) => {
+      const argsWithContext = injectContextRequired(args, ["specificationId"]);
+      return await callLocal("action_review_session", {
+        specificationId: argsWithContext.specificationId,
+        reviewSessionId: args.reviewSessionId,
+        findingsAddressed: args.findingsAddressed,
+        notes: args.notes
+      });
+    },
+    complete_review_session: async (_client, args) => {
+      const argsWithContext = injectContextRequired(args, ["specificationId"]);
+      return await callLocal("complete_review_session", {
+        specificationId: argsWithContext.specificationId,
+        reviewSessionId: args.reviewSessionId,
+        summary: args.summary,
+        confirmAllDismissed: args.confirmAllDismissed
+      });
+    },
+    reopen_specification: async (_client, args) => {
+      const argsWithContext = injectContextRequired(args, ["specificationId"]);
+      return await callLocal("reopen_specification", {
+        specificationId: argsWithContext.specificationId
+      });
+    },
+    // ========================================================================
+    // Mutation
+    // ========================================================================
+    // ========================================================================
+    // Utilities
+    // ========================================================================
+    feedback: async (_client, args) => {
+      return await callLocal("feedback", args);
+    },
+    reset_work_session: async (_client, args) => {
+      validateRequired(args, "specificationId");
+      return await callLocal("reset_work_session", {
+        specificationId: args.specificationId,
+        ticketIds: args.ticketIds,
+        fromTicketId: args.fromTicketId,
+        epicId: args.epicId,
+        allTickets: args.allTickets,
+        targetStatus: args.targetStatus,
+        resetDependents: args.resetDependents,
+        includeCompleted: args.includeCompleted,
+        preserveNotes: args.preserveNotes,
+        clearTestResults: args.clearTestResults
+      });
+    },
+    link_pull_request: async (_client, args) => {
+      validateRequired(args, "ticketId");
+      if (!args.prNumber && !args.prUrl) {
+        throw new Error("Either prNumber or prUrl must be provided");
+      }
+      return await callLocal("link_pull_request", {
+        ticketId: args.ticketId,
+        prNumber: args.prNumber,
+        prUrl: args.prUrl,
+        title: args.title,
+        author: args.author,
+        repoUrl: args.repoUrl
+      });
+    },
+    // ========================================================================
+    // Orchestration
+    // ========================================================================
+    get_critical_path: async (_client, args) => {
+      const argsWithContext = injectContext(args, ["specificationId"]);
+      if (!argsWithContext.specificationId) {
+        throw new Error("specificationId is required");
+      }
+      return await callLocal("get_critical_path", {
+        specificationId: argsWithContext.specificationId
+      });
+    },
+    get_dependency_tree: async (_client, args) => {
+      const argsWithContext = injectContext(args, ["specificationId"]);
+      if (!argsWithContext.specificationId) {
+        throw new Error("specificationId is required");
+      }
+      return await callLocal("get_dependency_tree", {
+        specificationId: argsWithContext.specificationId
+      });
+    }
+  };
+}
+function validateRequired(args, ...required) {
+  for (const field of required) {
+    if (args[field] === void 0 || args[field] === null || args[field] === "") {
+      throw new Error(`Missing required argument: ${field}`);
+    }
+  }
+}
+let cachedHandlers = null;
+function resetToolHandlers() {
+  cachedHandlers = null;
+}
+async function handleToolCall(apiClient, toolName, args, debug = false) {
+  const startTime = Date.now();
+  if (!cachedHandlers) {
+    cachedHandlers = createToolHandlers(apiClient);
+  }
+  const handler = cachedHandlers[toolName];
+  if (!handler) {
+    throw new Error(`Unknown tool: ${toolName}`);
+  }
+  if (debug) {
+    console.error(`[DEBUG] Calling tool: ${toolName}`, {
+      args: JSON.stringify(args)
+    });
+  }
+  try {
+    validateToolArgs(toolName, args);
+    const result = await withRetry(
+      () => handler(apiClient, args),
+      toolName,
+      debug
+    );
+    const duration = Date.now() - startTime;
+    if (debug) {
+      console.error(`[DEBUG] Tool ${toolName} completed in ${duration}ms`);
+    }
+    return result;
+  } catch (error) {
+    const duration = Date.now() - startTime;
+    const transformedError = transformError(error);
+    const message = transformedError.message;
+    if (debug) {
+      console.error(`[DEBUG] Tool ${toolName} failed after ${duration}ms:`, message);
+      if (transformedError instanceof ValidationError) {
+        console.error(`[DEBUG] Validation field: ${transformedError.field}, code: ${transformedError.code}`);
+      }
+    }
+    if (transformedError instanceof ValidationError) {
+      throw transformedError;
+    }
+    if (transformedError instanceof ApiError) {
+      throw transformedError;
+    }
+    throw new Error(`Tool ${toolName} failed: ${message}`);
+  }
+}
+async function handleToolCallSafe(apiClient, toolName, args, debug = false) {
+  try {
+    return await handleToolCall(apiClient, toolName, args, debug);
+  } catch (error) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    return formatMCPError(err);
+  }
+}
+import {
+  ValidationError as ValidationError2,
+  ApiError as ApiError2,
+  validateToolArgs as validateToolArgs2,
+  formatMCPError as formatMCPError2,
+  transformError as transformError2
+} from "../validation/index.js";
+export {
+  ApiError2 as ApiError,
+  ValidationError2 as ValidationError,
+  createToolHandlers,
+  formatMCPError2 as formatMCPError,
+  getTools,
+  handleToolCall,
+  handleToolCallSafe,
+  resetToolHandlers,
+  transformError2 as transformError,
+  validateToolArgs2 as validateToolArgs
+};
+//# sourceMappingURL=index.js.map