@specforge/canary-cli 0.1.3 → 0.1.5

package/dist/tools/index.js

@@ -24,19 +24,15 @@ function getTools() {
         properties: {
           type: {
             type: "string",
-            enum: ["project", "specification", "epic", "ticket", "implementation_session"],
+            enum: ["project", "specification", "epic", "ticket", "blueprint"],
             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)"
+            description: "Entity ID"
           }
         },
-        required: ["type"]
+        required: ["type", "id"]
       }
     },
     {
@@ -47,7 +43,7 @@ function getTools() {
         properties: {
           type: {
             type: "string",
-            enum: ["projects", "specifications", "epics", "tickets"],
+            enum: ["projects", "specifications", "epics", "tickets", "blueprints"],
             description: "Entity type to list"
           },
           projectId: {
@@ -120,14 +116,6 @@ At least one scope filter (projectId, specificationId, or epicId) is required.`,
             },
             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"
@@ -147,38 +135,6 @@ At least one scope filter (projectId, specificationId, or epicId) is required.`,
           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."
           }
         }
       }
@@ -206,7 +162,7 @@ At least one scope filter (projectId, specificationId, or epicId) is required.`,
     },
     {
       name: "get_blocked_tickets",
-      description: 'Get tickets with status "pending" and their statusReason explaining why they are blocked (unsatisfied dependencies or external block)',
+      description: 'Get tickets with status "pending", each with the `blockedBy` list of unsatisfied dependency tickets computed from the dependency tree.',
       inputSchema: {
         type: "object",
         properties: {
@@ -227,7 +183,6 @@ Report types:
 - '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:
@@ -238,7 +193,7 @@ Format options:
         properties: {
           type: {
             type: "string",
-            enum: ["implementation", "time", "blockers", "work", "implementation_analysis", "sessions"],
+            enum: ["implementation", "time", "blockers", "work", "sessions"],
             description: "Type of report to generate"
           },
           scope: {
@@ -257,6 +212,11 @@ Format options:
           endDate: {
             type: "string",
             description: "End date for work report (ISO 8601)"
+          },
+          format: {
+            type: "string",
+            enum: ["json", "summary"],
+            description: "Response format: 'json' (default) or 'summary'."
           }
         },
         required: ["type", "scope", "scopeId"]
@@ -287,7 +247,7 @@ Format options:
     },
     {
       name: "action_planning_session",
-      description: "Execute a planning action within an active session. Wraps all planning operations (create/update/delete epics, tickets, dependencies, blueprints) plus get_planning_status (readiness X-ray, worst-first) with automatic status tracking. The operation.type IS the backend PlanningOperationName. 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. To read a single ticket, use the `get` tool (type:'ticket'). Use responseDetail to control verbosity: 'minimal' (~80 tokens) for rapid iteration, 'standard' (~200 tokens, default) for normal work, 'full' (~500 tokens) for debugging.",
+      description: "Execute a planning action within an active session. Wraps all planning operations (create/update/delete epics, tickets, dependencies, blueprints) plus get_planning_status (readiness X-ray, worst-first) with automatic status tracking. The operation.type IS the backend PlanningOperationName. 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. To read a single ticket, use the `get` tool (type:'ticket').",
       inputSchema: {
         type: "object",
         properties: {
@@ -301,17 +261,17 @@ Format options:
                   "update_spec",
                   "create_epic",
                   "update_epic",
+                  "delete_epic",
                   "create_ticket",
                   "update_ticket",
-                  "delete_epic",
                   "delete_ticket",
-                  "create_dependencies",
-                  "delete_dependencies",
                   "create_blueprint",
                   "update_blueprint",
                   "delete_blueprint",
                   "link_blueprint_to_tickets",
                   "unlink_blueprint_to_tickets",
+                  "create_dependencies",
+                  "delete_dependencies",
                   "get_planning_status"
                 ],
                 description: "The planning operation to perform (lifecycle vocabulary). The type IS the backend PlanningOperationName; remaining fields are the operation payload."
@@ -326,15 +286,15 @@ Format options:
                 },
                 required: ["type", "fields"]
               },
+              // create_epic — SHELL only (epic_decomposition). Body fields are authored
+              // by update_epic in epic_expansion; only title/description/objective are
+              // persisted on create, so only those are advertised.
               {
                 properties: {
                   type: { const: "create_epic" },
                   title: { type: "string", minLength: 1, description: "Epic title (non-empty)" },
                   description: { type: "string", description: "What this epic delivers" },
-                  objective: { type: "string", 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" }
+                  objective: { type: "string", description: "Goal achieved for the user" }
                 },
                 required: ["type", "title"]
               },
@@ -349,26 +309,33 @@ Format options:
                       title: { type: "string" },
                       description: { type: "string" },
                       objective: { type: "string", description: "Goal achieved for the user." },
-                      priority: { type: "string", enum: ["high", "medium", "low"] },
-                      goals: { type: "array", items: { type: "string" } },
-                      acceptanceCriteria: { type: "array", items: { type: "string" } }
+                      architecture: { type: "string", description: "Structural approach specific to this epic." },
+                      scope: { type: "object", description: "Epic scope.", properties: { inScope: { type: "array", items: { type: "string" } }, outOfScope: { type: "array", items: { type: "string" } }, assumptions: { type: "array", items: { type: "string" } }, externalDependencies: { type: "array", items: { type: "string" } } } },
+                      goals: { type: "array", description: "Epic goals as objects (Epic.goals is a json object[], not string[]).", items: { type: "object", properties: { title: { type: "string" }, description: { type: "string" }, type: { type: "string", enum: ["business", "technical", "user", "operational"] }, successCriteria: { type: "array", items: { type: "string" } } }, required: ["title", "description"] } },
+                      acceptanceCriteria: { type: "array", description: "BDD criteria objects (Epic.acceptanceCriteria is a json object[], not string[]).", items: { type: "object", properties: { given: { type: "string" }, when: { type: "string" }, then: { type: "string" } }, required: ["given", "when", "then"] } },
+                      validationCommands: { type: "array", items: { type: "string" }, description: "Commands that verify this epic end-to-end." },
+                      apiContracts: { type: "array", description: "API contracts this epic exposes.", items: { type: "object", properties: { id: { type: "string" }, name: { type: "string" }, type: { type: "string" }, description: { type: "string" } } } },
+                      sharedPatterns: { type: "array", description: "Reusable patterns the epic's tickets should follow.", items: { type: "object" } },
+                      fileStructures: { type: "array", description: "Concrete files this epic creates/modifies.", items: { type: "object", properties: { id: { type: "string" }, scope: { type: "string" }, description: { type: "string" }, content: { type: "string" } } } },
+                      requirementsCovered: { type: "array", items: { type: "string" }, description: "Spec requirement ids this epic covers." },
+                      nfrsCovered: { type: "array", items: { type: "string" }, description: "Spec NFR ids this epic covers." },
+                      goalsCovered: { type: "array", items: { type: "string" }, description: "Spec goal ids this epic advances." }
                     }
                   }
                 },
                 required: ["type", "id", "fields"]
               },
+              // create_ticket — SHELL only (ticket_decomposition). Body fields
+              // (ticketType, complexity, acceptanceCriteria, implementationSteps, …)
+              // are authored by update_ticket in ticket_expansion; dependencies via
+              // create_dependencies in cross_validation. Only epicId/title/description
+              // are persisted on create, so only those are advertised.
               {
                 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" }
+                  description: { type: "string" }
                 },
                 required: ["type", "epicId", "title"]
               },
@@ -392,7 +359,9 @@ Format options:
                       filesToBeDeleted: { type: "array", items: { type: "string" } },
                       filesToBeReferenced: { type: "array", items: { type: "string" } },
                       guardrails: { type: "array", items: { type: "string" } },
-                      testSpecification: { type: "object", properties: { testTypes: { type: "array", items: { type: "string", enum: ["unit", "integration", "e2e", "typecheck", "lint", "build", "contract", "structural", "layout", "a11y", "performance"] } }, qualityGates: { type: "array", items: { type: "string" } }, testCommands: { type: "array", items: { type: "string" } }, coverageTarget: { type: "number", minimum: 0, maximum: 100 } } },
+                      testSpecification: { type: "object", properties: { testTypes: { type: "array", items: { type: "string", enum: ["unit", "integration", "e2e", "typecheck", "lint", "build", "contract", "structural", "layout", "a11y", "performance"] } }, qualityGates: { type: "array", items: { type: "string" } }, testCommands: { type: "array", items: { type: "string" } }, coverageTarget: { type: "integer", minimum: 0, maximum: 100 } } },
+                      codeReferences: { type: "array", description: "Existing code to reuse/anchor on.", items: { type: "object", properties: { filePath: { type: "string" }, symbol: { type: "string" }, description: { type: "string" } }, required: ["filePath"] } },
+                      typeReferences: { type: "array", description: "Existing types to use.", items: { type: "object", properties: { filePath: { type: "string" }, typeName: { type: "string" }, description: { type: "string" } }, required: ["filePath", "typeName"] } },
                       codeSnippets: { type: "array", items: { type: "object", properties: { language: { type: "string" }, content: { type: "string" }, description: { type: "string" } }, required: ["language", "content"] } },
                       typeSnippets: { type: "array", items: { type: "object", properties: { language: { type: "string" }, content: { type: "string" }, description: { type: "string" } }, required: ["language", "content"] } },
                       blueprintReferences: { type: "array", items: { type: "object", properties: { blueprintId: { type: "string" }, context: { type: "string" }, section: { type: "string" } }, required: ["blueprintId"] } },
@@ -405,14 +374,16 @@ Format options:
               {
                 properties: {
                   type: { const: "delete_epic" },
-                  id: { type: "string", description: "Epic id; cascades to all tickets in the epic." }
+                  id: { type: "string", description: "Epic id; cascades to all tickets in the epic." },
+                  cascadeRemoveDependencies: { type: "boolean", description: "Confirm removing dependency edges pointing at this epic's tickets from outside the epic. Required (true) when such referrers exist, else the delete is denied." }
                 },
                 required: ["type", "id"]
               },
               {
                 properties: {
                   type: { const: "delete_ticket" },
-                  id: { type: "string", description: "Ticket id (use list_tickets / lookup_ticket to find)." }
+                  id: { type: "string", description: "Ticket id (use list_tickets / lookup_ticket to find)." },
+                  cascadeRemoveDependencies: { type: "boolean", description: "Confirm removing dependency edges from other tickets that point at this ticket. Required (true) when such referrers exist, else the delete is denied." }
                 },
                 required: ["type", "id"]
               },
@@ -422,14 +393,13 @@ Format options:
                   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.",
+                    maxItems: 5e3,
+                    description: 'Up to 5000 dependency pairs, each a "requires" edge (fromTicketId depends on toTicketId). The batch is validated atomically: a cycle or an all-duplicate batch is rejected with guidance; already-existing edges are skipped.',
                     items: {
                       type: "object",
                       properties: {
                         fromTicketId: { type: "string", description: "The dependent ticket (this one depends on the other)." },
-                        toTicketId: { type: "string", description: "The blocker ticket it depends on." },
-                        type: { type: "string", enum: ["requires", "blocks"], description: 'Defaults to "requires"' }
+                        toTicketId: { type: "string", description: "The blocker ticket it depends on." }
                       },
                       required: ["fromTicketId", "toTicketId"]
                     }
@@ -448,9 +418,9 @@ Format options:
                 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: "Blueprint category (model enum, e.g. flowchart | architecture | sequence | data_model)." },
+                  content: { type: "string", description: "Body \u2014 diagram source or markdown, persisted as-is on create." },
+                  format: { type: "string", enum: ["markdown", "mermaid", "ascii", "mixed", "html", "svg", "image"], description: 'Defaults to "mermaid"' },
+                  category: { type: "string", enum: ["flowchart", "architecture", "state", "sequence", "erd", "mockup", "adr", "component", "deployment", "api", "algorithm", "protocol", "glossary", "design_system"], description: "Blueprint category (SpecificationBlueprint.category model enum)." },
                   description: { type: "string" },
                   tags: { type: "array", items: { type: "string" } }
                 },
@@ -485,9 +455,7 @@ Format options:
                 properties: {
                   type: { const: "link_blueprint_to_tickets" },
                   blueprintId: { type: "string", description: "Blueprint to link." },
-                  ticketIds: { type: "array", minItems: 1, items: { type: "string" }, description: "Tickets to link the blueprint to." },
-                  context: { type: "string", description: "Optional context annotation" },
-                  section: { type: "string", description: "Optional section reference" }
+                  ticketIds: { type: "array", minItems: 1, items: { type: "string" }, description: "Tickets to link the blueprint to." }
                 },
                 required: ["type", "blueprintId", "ticketIds"]
               },
@@ -502,17 +470,11 @@ Format options:
               {
                 // Read-only poll/resume. To read a single ticket, use the `get` tool (type:'ticket').
                 properties: {
-                  type: { const: "get_planning_status" },
-                  responseDetail: { type: "string", enum: ["minimal", "standard", "full"] }
+                  type: { const: "get_planning_status" }
                 },
                 required: ["type"]
               }
             ]
-          },
-          responseDetail: {
-            type: "string",
-            enum: ["minimal", "standard", "full"],
-            description: "Response detail level: minimal (~80 tokens), standard (~200, default), full (~500)"
           }
         },
         required: ["operation"]
@@ -578,7 +540,7 @@ Set getTicket: true to fetch full ticket details in the response \u2014 useful f
               properties: {
                 index: {
                   type: "number",
-                  description: "Zero-based index of the step in the implementation.steps array"
+                  description: "Zero-based index of the step among the ticket's implementation steps (TicketImplementationStep rows, ordered by `order`)"
                 },
                 completed: {
                   type: "boolean",
@@ -785,22 +747,22 @@ Set getTicket: true to fetch full ticket details in the response \u2014 useful f
             properties: {
               tests: {
                 type: "string",
-                enum: ["passed", "failed", "skipped", "na"],
+                enum: ["passed", "failed", "partial", "pending"],
                 description: "Unit/integration test results"
               },
               lint: {
                 type: "string",
-                enum: ["passed", "failed", "skipped", "na"],
+                enum: ["passed", "failed", "partial", "pending"],
                 description: "Linting results"
               },
               typeCheck: {
                 type: "string",
-                enum: ["passed", "failed", "skipped", "na"],
+                enum: ["passed", "failed", "partial", "pending"],
                 description: "TypeScript type checking results"
               },
               build: {
                 type: "string",
-                enum: ["passed", "failed", "skipped", "na"],
+                enum: ["passed", "failed", "partial", "pending"],
                 description: "Build/compilation results"
               },
               notes: {
@@ -864,9 +826,8 @@ Set getTicket: true to fetch full ticket details in the response \u2014 useful f
                     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" },
+                    estimatedMinutes: { type: "integer", minimum: 0 },
                     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" } }
@@ -1127,6 +1088,23 @@ Set getTicket: true to fetch full ticket details in the response \u2014 useful f
       }
     }
   ];
+  const IN_DEVELOPMENT_PLANNED_FOR = {
+    start_work_session: "0.2.0",
+    action_work_session: "0.2.0",
+    complete_work_session: "0.2.0",
+    reset_work_session: "0.2.0",
+    start_review_session: "0.3.0",
+    action_review_session: "0.3.0",
+    complete_review_session: "0.3.0"
+  };
+  for (const t of tools) {
+    const plannedFor = IN_DEVELOPMENT_PLANNED_FOR[t.name];
+    if (plannedFor) {
+      t.description = `**In development \u2014 ships with ${plannedFor}.** Calling returns a typed stub response the client should render as a "coming soon" affordance.
+
+${t.description}`;
+    }
+  }
   return tools;
 }
 const RETRY_CONFIG = {
@@ -1398,7 +1376,6 @@ function createToolHandlers(apiClient) {
         fromTicketId: args.fromTicketId,
         epicId: args.epicId,
         allTickets: args.allTickets,
-        targetStatus: args.targetStatus,
         resetDependents: args.resetDependents,
         includeCompleted: args.includeCompleted,
         preserveNotes: args.preserveNotes,