@specforge/canary-cli 0.1.17 → 0.2.0

package/dist/tools/index.js

@@ -281,7 +281,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').",
+      description: "Execute a planning action within an active session. Wraps the planning write operations (create/update/delete for epics, tickets and blueprints; plus the dependency, blueprint-link, step-link, justify and creator-election operations) and the read operation get_planning_status. The operation.type IS the backend PlanningOperationName; the remaining fields are the operation payload. To read a single ticket, use the `get` tool (type:'ticket').",
       inputSchema: {
         type: "object",
         properties: {
@@ -297,7 +297,10 @@ Format options:
                   "update_epic",
                   "delete_epic",
                   "create_ticket",
-                  "update_ticket",
+                  "ticket_general_actions",
+                  "ticket_step_actions",
+                  "ticket_criteria_actions",
+                  "ticket_test_actions",
                   "delete_ticket",
                   "create_blueprint",
                   "update_blueprint",
@@ -367,48 +370,78 @@ Format options:
                 required: ["type", "id", "fields"]
               },
               // create_ticket — SHELL (ticket_decomposition): epicId/title/description
-              // + ticketType (the impl/verification decision, set HERE and immutable via
-              // update_ticket). The remaining body fields are authored by update_ticket in
-              // ticket_expansion; dependencies via create_dependencies in cross_validation.
+              // + ticketType (the impl/verification decision, set HERE). The remaining body
+              // fields are authored by the ticket node verbs in ticket_expansion;
+              // dependencies via create_dependencies in cross_validation.
               {
                 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 set here (decomposition); defaults to implementation. Not changeable via update_ticket." }
+                  ticketType: { type: "string", enum: ["implementation", "verification"], description: "Ticket type \u2014 set here (decomposition); defaults to implementation. Editing it later via ticket_general_actions rolls the session back to ticket_decomposition." }
                 },
                 required: ["type", "epicId", "title"]
               },
+              // ME.19.1 (D8/D20) — the four ticket NODE VERBS replace the retired free-form
+              // `update_ticket`. Each targets ONE scope with a TYPED payload (no `fields`
+              // bag); complexity/planningType/ticketType are enums, so an out-of-enum value
+              // is denied at the schema gate before persistence. `status` is NOT settable
+              // (system/event-driven). Blueprint links are NOT settable here — use
+              // link_blueprint_to_tickets.
+              // ticket_general_actions — shell/general fields (partial edit).
               {
+                description: "Edit a ticket's shell/general fields. Only the keys you send are changed. Fields that do not apply are declared with the `justify` op (undo with `unjustify`), never by writing values here.",
                 properties: {
-                  type: { const: "update_ticket" },
-                  id: { type: "string", description: "Ticket id (use list_tickets / lookup_ticket to find)." },
-                  fields: {
-                    type: "object",
-                    description: "Partial ticket update \u2014 only the keys you send are changed. Child-backed arrays (acceptanceCriteria, implementationSteps, filesToBe*, testSpecification.testTypes, codeSnippets, typeSnippets) replace the whole set. Blueprint links are NOT settable here \u2014 use link_blueprint_to_tickets (from ticket_decomposition onward), the sole writer of the blueprint\u2194ticket relation. Fields that do not apply are declared with the `justify` op (undo with `unjustify`), never by writing values here.",
-                    properties: {
-                      title: { type: "string" },
-                      description: { type: "string" },
-                      complexity: { type: "string", enum: ["small", "medium", "large", "xlarge"] },
-                      estimatedMinutes: { type: "integer", minimum: 0 },
-                      acceptanceCriteria: { type: "array", items: { type: "object", properties: { given: { type: "string" }, when: { type: "string" }, then: { type: "string" } }, required: ["given", "when", "then"] } },
-                      implementationSteps: { type: "array", description: "Ordered build steps. Declare the file(s) each step produces INLINE via `producesFiles: [path]` (each path must also appear in filesToBeCreated/filesToBeModified) \u2014 links the step\u2194file in the SAME call so the ticket_expansion gate passes without a second pass. Every step MUST link \u22651 file and every produced file MUST be linked by \u22651 step (hard gates). `link_step_file` remains for post-hoc edits.", items: { type: "object", properties: { text: { type: "string" }, producesFiles: { type: "array", items: { type: "string" }, description: "Paths this step produces \u2014 each must match an entry in filesToBeCreated/filesToBeModified; links the step\u2194file inline (path-based)." } }, required: ["text"] } },
-                      filesToBeCreated: { type: "array", items: { type: "string" } },
-                      filesToBeModified: { type: "array", items: { type: "string" } },
-                      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: "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", description: "Concrete code to write. Attach a snippet to its step INLINE via `stepId` (create-and-link); a snippet linking NO step is dangling and blocks the ticket.", items: { type: "object", properties: { language: { type: "string" }, content: { type: "string" }, description: { type: "string" }, stepId: { type: "string", description: "Implementation step id this snippet follows \u2014 links the snippet\u2194step inline." } }, required: ["language", "content"] } },
-                      typeSnippets: { type: "array", description: "Type/interface definitions to write. Attach to a step INLINE via `stepId` (create-and-link); a snippet linking NO step is dangling and blocks the ticket.", items: { type: "object", properties: { language: { type: "string" }, content: { type: "string" }, description: { type: "string" }, stepId: { type: "string", description: "Implementation step id this snippet follows \u2014 links the snippet\u2194step inline." } }, required: ["language", "content"] } },
-                      tags: { type: "array", items: { type: "string" } }
-                    }
-                  }
+                  type: { const: "ticket_general_actions" },
+                  ticketId: { type: "string", description: "Ticket id (use list_tickets / lookup_ticket to find)." },
+                  title: { type: "string", description: "Concise imperative title." },
+                  description: { type: "string", description: "What this ticket delivers and why." },
+                  complexity: { type: "string", enum: ["small", "medium", "large", "xlarge"] },
+                  planningType: { type: "string", enum: ["planning", "on_flight", "review"], description: "Changing this rolls the session back to ticket_decomposition to re-score." },
+                  ticketType: { type: "string", enum: ["implementation", "verification"], description: "Changing this rolls the session back to ticket_decomposition to re-score." },
+                  epicId: { type: "string", description: "Re-parent the ticket to another epic." },
+                  order: { type: "integer", description: "Rank hint within the epic." },
+                  guardrails: { type: "array", items: { type: "string" }, description: "Per-ticket guardrail ids or descriptions." },
+                  estimatedMinutes: { type: "integer", minimum: 0 }
                 },
-                required: ["type", "id", "fields"]
+                required: ["type", "ticketId"]
+              },
+              // ticket_step_actions — batch add/edit/remove/reorder of implementation steps.
+              {
+                description: "Batch-edit a ticket's implementation steps (add/edit/remove/reorder in one call). A step is a unit of FUNCTIONAL WORK \u2014 describe the functions/components/adjustments it makes AND what each does, never a bare filename. Declare the file(s) each step touches INLINE via `files: [{path, role}]`, role one of creates|modifies|deletes|imports|reads (imports couples to a build/run dependency; reads is a context-only glance). Fields that do not apply are declared with the `justify` op, never by writing empty values here.",
+                properties: {
+                  type: { const: "ticket_step_actions" },
+                  ticketId: { type: "string", description: "Ticket id (use list_tickets / lookup_ticket to find)." },
+                  add: { type: "array", description: "New steps to append.", items: { type: "object", properties: { text: { type: "string" }, files: { type: "array", description: "Files this step touches, by role \u2014 derives the step\u2194file link + the TicketFileChange row.", items: { type: "object", properties: { path: { type: "string" }, role: { type: "string", enum: ["creates", "modifies", "deletes", "imports", "reads"] }, symbol: { type: "string" }, why: { type: "string" } }, required: ["path", "role"] } } }, required: ["text"] } },
+                  edit: { type: "array", description: "Existing steps to edit (by stepId).", items: { type: "object", properties: { stepId: { type: "string" }, text: { type: "string" }, files: { type: "array", items: { type: "object", properties: { path: { type: "string" }, role: { type: "string", enum: ["creates", "modifies", "deletes", "imports", "reads"] }, symbol: { type: "string" }, why: { type: "string" } }, required: ["path", "role"] } } }, required: ["stepId"] } },
+                  remove: { type: "array", items: { type: "string" }, description: "Step ids to remove." },
+                  reorder: { type: "array", items: { type: "string" }, description: "Step ids in the desired order." }
+                },
+                required: ["type", "ticketId"]
+              },
+              // ticket_criteria_actions — batch add/edit/remove/reorder of acceptance criteria.
+              {
+                description: "Batch-edit a ticket's acceptance criteria (given/when/then; add/edit/remove/reorder in one call). Fields that do not apply are declared with the `justify` op, never by writing empty values here.",
+                properties: {
+                  type: { const: "ticket_criteria_actions" },
+                  ticketId: { type: "string", description: "Ticket id (use list_tickets / lookup_ticket to find)." },
+                  add: { type: "array", description: "New acceptance criteria to append.", items: { type: "object", properties: { given: { type: "string" }, when: { type: "string" }, then: { type: "string" } }, required: ["given", "when", "then"] } },
+                  edit: { type: "array", description: "Existing criteria to edit (by criterionId).", items: { type: "object", properties: { criterionId: { type: "string" }, given: { type: "string" }, when: { type: "string" }, then: { type: "string" } }, required: ["criterionId"] } },
+                  remove: { type: "array", items: { type: "string" }, description: "Criterion ids to remove." },
+                  reorder: { type: "array", items: { type: "string" }, description: "Criterion ids in the desired order." }
+                },
+                required: ["type", "ticketId"]
+              },
+              // ticket_test_actions — author the existing single-object testSpecification.
+              {
+                description: "Author a ticket's testSpecification (testTypes, qualityGates, testCommands, coverageTarget). Fields that do not apply are declared with the `justify` op, never by writing empty values here.",
+                properties: {
+                  type: { const: "ticket_test_actions" },
+                  ticketId: { type: "string", description: "Ticket id (use list_tickets / lookup_ticket to find)." },
+                  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 } } }
+                },
+                required: ["type", "ticketId", "testSpecification"]
               },
               {
                 properties: {
@@ -469,7 +502,7 @@ Format options:
                       type: "object",
                       properties: {
                         path: { type: "string", description: "The orphan shared file path to resolve." },
-                        kind: { type: "string", enum: ["toBeCreated", "toBeModified", "toBeDeleted", "toBeReferenced"], description: "The target file-change kind on the elected ticket (normally toBeCreated)." },
+                        kind: { type: "string", enum: ["creates", "modifies", "deletes", "imports", "reads"], description: "The step-file role the elected ticket takes for this path (normally creates)." },
                         creatorTicketId: { type: "string", description: "The elected creator ticket (topologically-earliest toucher)." },
                         producingStep: {
                           type: "object",
@@ -638,7 +671,7 @@ Format options:
     },
     {
       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.",
+      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 the `get` tool (type:'ticket') separately. Returns error with statusReason if ticket is pending.",
       inputSchema: {
         type: "object",
         properties: {
@@ -654,7 +687,7 @@ Format options:
       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:
+Use this instead of reopening the planning session for checklist changes. Provides:
 - Step completion (individual or bulk via WorkSessionImplStepCompletion)
 - Acceptance criteria validation (individual or bulk via WorkSessionAcceptanceCheck)
 - Test result reporting (merged by test type via WorkSessionTestResult)
@@ -1050,7 +1083,7 @@ Set getTicket: true to fetch full ticket details in the response \u2014 useful f
     },
     {
       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.',
+      description: 'Reopen a specification in "ready" status, regressing to "planning". Use when action_planning_session reports the spec is no longer in planning. After reopening, call start_planning_session to begin a new planning session.',
       inputSchema: {
         type: "object",
         properties: {