@wrongstack/tools 0.293.0 → 0.295.1

package/dist/kanban.js

@@ -1,6 +1,7 @@
 // src/kanban.ts
 import { randomUUID } from "node:crypto";
-import { deserializeTaskGraph as deserializeTaskGraph2, loadTasks as loadTasks2, serializeTaskGraph } from "@wrongstack/core";
+import { deserializeTaskGraph as deserializeTaskGraph2, serializeTaskGraph } from "@wrongstack/core/tasking";
+import { loadTasks as loadTasks2 } from "@wrongstack/core/storage";
 import {
   addCheckToTask,
   addColumn,
@@ -47,18 +48,45 @@ import {
   updateColumn,
   updateGoalMetricOnTask,
   updateTask,
-  updateTaskAssignment
+  updateTaskAssignment,
+  verifyTaskCompletion,
+  finalizeTaskCompletion,
+  assessTaskAtomicity,
+  proposeTaskDecomposition
 } from "@wrongstack/kanban";
 
+// src/kanban-evidence-bridge.ts
+import { recordCompletedWorkEvidence } from "@wrongstack/core/utils";
+function kanbanEvidenceKey(boardId, taskId) {
+  return `kanban:${boardId}:${taskId}`;
+}
+function kanbanEvidencePointer(boardId, taskId) {
+  return `kanban://${boardId}/${taskId}#verificationReport`;
+}
+function recordKanbanVerificationEvidence(ctx, report) {
+  try {
+    const passed = report.checks.filter((check) => check.status === "passed").length;
+    const completedAt = Date.parse(report.completedAt);
+    recordCompletedWorkEvidence(ctx, {
+      key: kanbanEvidenceKey(report.boardId, report.taskId),
+      source: "verification",
+      summary: `${report.taskTitle} \u2014 verification ${report.verdict} (${passed}/${report.checks.length} checks)`,
+      ...Number.isFinite(completedAt) ? { completedAt } : {},
+      evidence: kanbanEvidencePointer(report.boardId, report.taskId)
+    });
+  } catch {
+  }
+}
+
 // src/session-kanban.ts
+import { GlobalMailbox } from "@wrongstack/core/coordination";
 import {
-  deserializeTaskGraph,
-  GlobalMailbox,
   loadPlan,
   loadTasks,
   mutatePlan,
   mutateTasks
-} from "@wrongstack/core";
+} from "@wrongstack/core/storage";
+import { deserializeTaskGraph } from "@wrongstack/core/tasking";
 import { resolveWstackPaths } from "@wrongstack/core/utils";
 import {
   createBoard,
@@ -111,8 +139,8 @@ function taskFileToSerializedGraph(tasks, sessionId) {
 var kanbanTool = {
   name: "kanban",
   category: "Project",
-  description: "Manage and audit project-scoped multi-kanban boards stored under .wrongstack/kanbans. Managed cards enforce fully specified details and adjacent Backlog \u2192 Todo \u2192 Running \u2192 Review \u2192 Done transitions with persistent comments and evidence. Successful board access records live agent/session presence.",
-  usageHint: "Use this for durable project kanban state. Reassess with get_board whenever evidence changes; agents may add, update, split, merge, reprioritize, or remove tasks so the board remains a live plan. Presence includes active/last-seen session and agent metadata. For managed boards, fully fill card details, use transition_task after every material step, attach truthful evidence, and never use update_task/move_task to bypass lifecycle guards. Worker completion enters Review; only passed acceptance criteria plus review evidence allow Done.",
+  description: "Manage and audit project-scoped multi-kanban boards stored under .wrongstack/kanbans. Managed cards enforce fully specified details and adjacent Backlog \u2192 Todo \u2192 Running \u2192 Review \u2192 Done transitions with persistent comments and evidence. Successful board access records live agent/session presence. Use verify_completion to validate a task against its success criteria and persist the verification report. Use split_atomic to split a task into child tasks with parent.atomic=true in a single atomic board mutation, enforcing subtree verification before the parent can complete.",
+  usageHint: "Use this for durable project kanban state. Reassess with get_board whenever evidence changes; agents may add, update, split, merge, reprioritize, or remove tasks so the board remains a live plan. Presence includes active/last-seen session and agent metadata. For managed boards, fully fill card details, use transition_task after every material step, attach truthful evidence, and never use update_task/move_task to bypass lifecycle guards. Worker completion enters Review; only passed acceptance criteria plus review evidence allow Done. Use verify_completion to generate a verification report (persisted automatically) and split_atomic to atomically create child subtasks with the atomic flag pre-set.",
   permission: "confirm",
   mutating: true,
   capabilities: ["fs.write"],
@@ -168,7 +196,11 @@ var kanbanTool = {
           "add_check",
           "update_check",
           "add_note",
-          "add_link"
+          "add_link",
+          "verify_completion",
+          "split_atomic",
+          "assess_atomicity",
+          "propose_decomposition"
         ]
       },
       boardId: { type: "string" },
@@ -223,6 +255,7 @@ var kanbanTool = {
       runTaskId: { type: "string" },
       lastResult: { type: "string" },
       error: { type: "string" },
+      expectedLeaseId: { type: "string" },
       assignmentStatus: {
         type: "string",
         enum: ["assigned", "queued", "running", "completed", "failed", "cancelled"]
@@ -257,6 +290,7 @@ var kanbanTool = {
       lastFailureKind: { type: "string" },
       dependsOn: { type: "array", items: { type: "string" } },
       estimatedHours: { type: "number" },
+      actualHours: { type: "number" },
       taskGraph: { type: "object" },
       graphId: { type: "string" },
       specId: { type: "string" },
@@ -302,7 +336,24 @@ var kanbanTool = {
       includeCompletedTasks: { type: "boolean" },
       preserveAssignment: { type: "boolean" },
       preserveDependencies: { type: "boolean" },
-      moveTasksToColumnId: { type: "string" }
+      moveTasksToColumnId: { type: "string" },
+      atomicityMode: { type: "string", enum: ["off", "assess", "enforce"] },
+      atomicityDecomposition: { type: "string", enum: ["auto", "propose"] },
+      gateEnforcement: { type: "string", enum: ["strict", "soft", "off"] },
+      subtasks: {
+        type: "array",
+        minItems: 2,
+        items: {
+          type: "object",
+          properties: {
+            title: { type: "string" },
+            description: { type: "string" },
+            successCriteria: { type: "array", items: { type: "string" } },
+            dependsOnIndex: { type: "array", items: { type: "number" } }
+          },
+          required: ["title"]
+        }
+      }
     },
     required: ["action"]
   },
@@ -342,7 +393,14 @@ var kanbanTool = {
               title: input.title,
               ...input.description !== void 0 ? { description: input.description } : {},
               ...input.tags !== void 0 ? { tags: input.tags } : {},
-              ...input.generatedBy !== void 0 ? { generatedBy: input.generatedBy } : {}
+              ...input.generatedBy !== void 0 ? { generatedBy: input.generatedBy } : {},
+              ...input.atomicityMode !== void 0 ? {
+                atomicity: {
+                  mode: input.atomicityMode,
+                  decomposition: input.atomicityDecomposition ?? "propose"
+                }
+              } : {},
+              ...input.gateEnforcement !== void 0 ? { completionGate: { enforcement: input.gateEnforcement } } : {}
             });
             return { ok: true, message: `Board created: ${board.title}`, board };
           }
@@ -351,7 +409,14 @@ var kanbanTool = {
             const board = await updateBoard2(projectRoot, input.boardId, {
               ...input.title !== void 0 ? { title: input.title } : {},
               ...input.description !== void 0 ? { description: input.description } : {},
-              ...input.tags !== void 0 ? { tags: input.tags } : {}
+              ...input.tags !== void 0 ? { tags: input.tags } : {},
+              ...input.atomicityMode !== void 0 ? {
+                atomicity: {
+                  mode: input.atomicityMode,
+                  decomposition: input.atomicityDecomposition ?? "propose"
+                }
+              } : {},
+              ...input.gateEnforcement !== void 0 ? { completionGate: { enforcement: input.gateEnforcement } } : {}
             });
             return board ? okBoard(board, "Board updated.") : fail("Board not found.");
           }
@@ -559,30 +624,18 @@ var kanbanTool = {
           case "add_task": {
             if (!input.boardId || !input.title) return fail("add_task requires boardId and title.");
             const result2 = await addTask(projectRoot, input.boardId, taskInput(input));
-            return result2 ? okTask(result2.board, result2.task, "Task added.") : fail("Board not found.");
+            if (!result2) return fail("Board not found.");
+            return okTask(
+              result2.board,
+              result2.task,
+              `Task added.${atomicityNudge(result2.task)}`
+            );
           }
           case "split_task": {
             if (!input.boardId || !input.taskId || !input.childTitles?.length) {
               return fail("split_task requires boardId, taskId, and childTitles.");
             }
-            const result2 = await splitTask(projectRoot, input.boardId, input.taskId, {
-              titles: input.childTitles,
-              ...input.targetColumnId !== void 0 ? { columnId: input.targetColumnId } : {},
-              ...input.inheritAssignment !== void 0 ? { inheritAssignment: input.inheritAssignment } : {},
-              ...input.inheritLabels !== void 0 ? { inheritLabels: input.inheritLabels } : {},
-              ...input.inheritSuccessCriteria !== void 0 ? { inheritSuccessCriteria: input.inheritSuccessCriteria } : {},
-              ...input.inheritGoalMetrics !== void 0 ? { inheritGoalMetrics: input.inheritGoalMetrics } : {},
-              ...input.inheritDependencies !== void 0 ? { inheritDependencies: input.inheritDependencies } : {},
-              ...input.chainChildren !== void 0 ? { chainChildren: input.chainChildren } : {},
-              ...input.rewireDependents !== void 0 ? { rewireDependents: input.rewireDependents } : {}
-            });
-            return result2 ? {
-              ok: true,
-              message: `${result2.children.length} child task(s) created.`,
-              board: result2.board,
-              task: result2.parent,
-              children: result2.children
-            } : fail("Task not found.");
+            return handleSplitTask(projectRoot, input, {});
           }
           case "merge_tasks": {
             if (!input.boardId || !input.taskIds?.length || !input.title) {
@@ -656,6 +709,19 @@ var kanbanTool = {
                 "transition_task requires boardId, taskId, lifecycleStage, author, and transitionComment."
               );
             }
+            if (input.lifecycleStage === "done") {
+              const boardBefore = await getBoard2(projectRoot, input.boardId);
+              const taskBefore = boardBefore ? await getTask(projectRoot, input.boardId, input.taskId) : null;
+              if (boardBefore && taskBefore && !taskBefore.verificationReport && (taskBefore.atomic || Boolean(taskBefore.successCriteria?.length))) {
+                const preGate = await verifyTaskCompletion(projectRoot, input.boardId, taskBefore.id, {
+                  persist: false
+                });
+                await updateTask(projectRoot, input.boardId, taskBefore.id, {
+                  verificationReport: preGate.report,
+                  successCriteria: preGate.task.successCriteria
+                });
+              }
+            }
             const result2 = await transitionTask(projectRoot, input.boardId, input.taskId, {
               to: input.lifecycleStage,
               actor: input.author,
@@ -670,6 +736,9 @@ var kanbanTool = {
               } : {},
               patch: taskPatch(input)
             });
+            if (result2 && input.lifecycleStage === "done" && result2.task.verificationReport) {
+              recordKanbanVerificationEvidence(ctx, result2.task.verificationReport);
+            }
             return result2 ? okTask(result2.board, result2.task, `Task advanced to ${result2.transition.to}.`) : fail("Board or task not found.");
           }
           case "move_task": {
@@ -783,7 +852,31 @@ var kanbanTool = {
               // is atomic inside updateTaskAssignment's mutateBoard lock.
               input.expectedLeaseId !== void 0 ? { expectedLeaseId: input.expectedLeaseId } : {}
             );
-            return board ? okBoard(board, "Assignment updated.") : fail("Task not found.");
+            if (!board) return fail("Task not found.");
+            if (assignmentStatus === "completed") {
+              const envGate = readEnvGateEnforcement();
+              const finalized = await finalizeTaskCompletion(projectRoot, board.id, input.taskId, {
+                ...board.completionGate === void 0 && envGate !== void 0 ? { enforcement: envGate } : {},
+                ...ctx.agentId !== void 0 ? { eventContext: { actor: ctx.agentId } } : {}
+              });
+              if (finalized) {
+                if (finalized.gate.report) {
+                  recordKanbanVerificationEvidence(ctx, finalized.gate.report);
+                }
+                const gateSummary = {
+                  enforcement: finalized.gate.enforcement,
+                  allowed: finalized.gate.allowed,
+                  verdict: finalized.gate.verdict,
+                  issues: finalized.gate.issues.map((issue) => issue.message)
+                };
+                const gateMessage = finalized.gate.allowed ? `Completion gate ${finalized.gate.verdict === "skipped" ? "skipped" : "passed"}; task completed.` : finalized.gate.enforcement === "strict" ? `Completion gate BLOCKED (verdict: ${finalized.gate.verdict}); task parked in review. Issues: ${gateSummary.issues.join(" | ")}` : `Completion gate failed softly (verdict: ${finalized.gate.verdict}); task completed with warnings. Issues: ${gateSummary.issues.join(" | ")}`;
+                return {
+                  ...okTask(finalized.board, finalized.task, `Assignment updated. ${gateMessage}`),
+                  gate: gateSummary
+                };
+              }
+            }
+            return okBoard(board, "Assignment updated.");
           }
           case "heartbeat_assignment": {
             if (!input.boardId || !input.taskId) {
@@ -947,6 +1040,83 @@ var kanbanTool = {
             });
             return board ? okBoard(board, "Link added.") : fail("Task not found.");
           }
+          case "assess_atomicity": {
+            if (!input.boardId || !input.taskId) {
+              return fail("assess_atomicity requires boardId and taskId.");
+            }
+            const result2 = await assessTaskAtomicity(projectRoot, input.boardId, input.taskId, {
+              assessedBy: "agent",
+              ...ctx.agentId !== void 0 ? { eventContext: { actor: ctx.agentId } } : {}
+            });
+            if (!result2) return fail("Task not found.");
+            const failing = result2.assessment.criteria.filter((entry) => entry.score < 1).map((entry) => entry.reason);
+            const guidance = result2.assessment.verdict === "needs_decomposition" ? ` This task should be split before dispatch \u2014 call propose_decomposition with 2+ subtasks (each with one verifiable success criterion). Reasons: ${failing.join(" | ")}` : result2.assessment.verdict === "composite" ? " Container task: work happens in its children; it is verified via subtask aggregation." : "";
+            return okTask(
+              result2.board,
+              result2.task,
+              `Atomicity verdict: ${result2.assessment.verdict} (score ${result2.assessment.score}).${guidance}`
+            );
+          }
+          case "propose_decomposition": {
+            if (!input.boardId || !input.taskId || !input.subtasks?.length) {
+              return fail("propose_decomposition requires boardId, taskId, and subtasks (2+).");
+            }
+            if (input.subtasks.length < 2) {
+              return fail("propose_decomposition requires at least two subtasks.");
+            }
+            const invalid = input.subtasks.find(
+              (subtask) => typeof subtask?.title !== "string" || !subtask.title.trim()
+            );
+            if (invalid) return fail("Every proposed subtask needs a non-blank title.");
+            const result2 = await proposeTaskDecomposition(
+              projectRoot,
+              input.boardId,
+              input.taskId,
+              {
+                subtasks: input.subtasks,
+                ...input.note !== void 0 ? { rationale: input.note } : {},
+                ...ctx.agentId !== void 0 ? { proposedBy: ctx.agentId } : {}
+              },
+              ctx.agentId !== void 0 ? { actor: ctx.agentId } : {}
+            );
+            if (!result2) return fail("Task not found.");
+            const message = result2.proposal.status === "applied" ? `Decomposition applied: ${result2.proposal.appliedChildTaskIds?.length ?? 0} child tasks created (parent marked atomic).` : 'Decomposition proposal recorded \u2014 awaiting approval (board policy is "propose"). It can be approved from the WebUI or via update_task.';
+            return okTask(result2.board, result2.task, message);
+          }
+          case "verify_completion": {
+            if (!input.boardId || !input.taskId) {
+              return fail("verify_completion requires boardId and taskId.");
+            }
+            const verResult = await verifyTaskCompletion(projectRoot, input.boardId, input.taskId);
+            const persistedBoard = await updateTask(projectRoot, input.boardId, input.taskId, {
+              verificationReport: verResult.report,
+              successCriteria: verResult.task.successCriteria
+            });
+            if (!persistedBoard) {
+              return {
+                ok: false,
+                verdict: verResult.report.verdict,
+                message: `Verification succeeded but persist failed: ${verResult.report.markdownSummary}. Board may be stale \u2014 re-run verify_completion.`,
+                board: verResult.board
+              };
+            }
+            recordKanbanVerificationEvidence(ctx, verResult.report);
+            const freshTask = persistedBoard.tasks?.find((t) => t.id === input.taskId);
+            const deterministicVerdicts = ["passed", "failed", "needs_human", "incomplete"];
+            return {
+              ok: deterministicVerdicts.includes(verResult.report.verdict),
+              verdict: verResult.report.verdict,
+              message: verResult.report.markdownSummary,
+              board: persistedBoard,
+              task: freshTask ?? verResult.task
+            };
+          }
+          case "split_atomic": {
+            if (!input.boardId || !input.taskId || !input.childTitles?.length) {
+              return fail("split_atomic requires boardId, taskId, and childTitles (at least one).");
+            }
+            return handleSplitTask(projectRoot, input, { atomic: true });
+          }
           default:
             return fail(`Unknown kanban action: ${input.action}`);
         }
@@ -957,6 +1127,15 @@ var kanbanTool = {
     }
   }
 };
+function atomicityNudge(task) {
+  if (task.atomicityAssessment?.verdict !== "needs_decomposition") return "";
+  const reasons = task.atomicityAssessment.criteria.filter((entry) => entry.score < 1).map((entry) => entry.reason).join(" | ");
+  return ` Atomicity: needs_decomposition (score ${task.atomicityAssessment.score}) \u2014 call propose_decomposition with 2+ subtasks before dispatch. Reasons: ${reasons}`;
+}
+function readEnvGateEnforcement() {
+  const raw = process.env["WRONGSTACK_KANBAN_GATE"]?.trim().toLowerCase();
+  return raw === "strict" || raw === "soft" || raw === "off" ? raw : void 0;
+}
 function fail(message) {
   return { ok: false, message };
 }
@@ -966,6 +1145,50 @@ function okBoard(board, message = "Board loaded.") {
 function okTask(board, task, message) {
   return { ok: true, message, board, task };
 }
+async function handleSplitTask(projectRoot, input, extraSplitOptions) {
+  const boardId = input.boardId;
+  const taskId = input.taskId;
+  const childTitles = input.childTitles;
+  if (!boardId || !taskId || !childTitles?.length) {
+    return fail("split requires boardId, taskId, and at least one childTitles.");
+  }
+  const {
+    targetColumnId,
+    inheritAssignment,
+    inheritLabels,
+    inheritSuccessCriteria,
+    inheritGoalMetrics,
+    inheritDependencies,
+    chainChildren,
+    rewireDependents
+  } = input;
+  const result = await splitTask(projectRoot, boardId, taskId, {
+    titles: childTitles,
+    ...extraSplitOptions,
+    ...targetColumnId !== void 0 ? { columnId: targetColumnId } : {},
+    ...inheritAssignment !== void 0 ? { inheritAssignment } : {},
+    ...inheritLabels !== void 0 ? { inheritLabels } : {},
+    ...inheritSuccessCriteria !== void 0 ? { inheritSuccessCriteria } : {},
+    ...inheritGoalMetrics !== void 0 ? { inheritGoalMetrics } : {},
+    ...inheritDependencies !== void 0 ? { inheritDependencies } : {},
+    ...chainChildren !== void 0 ? { chainChildren } : {},
+    ...rewireDependents !== void 0 ? { rewireDependents } : {}
+  });
+  if (!result) return fail("Task not found.");
+  const freshParent = result.board.tasks?.find((t) => t.id === taskId);
+  if (!freshParent) {
+    return fail(
+      `Split succeeded but parent ${taskId} not found in returned board. Children: [${result.children.map((c) => c.id).join(", ")}].`
+    );
+  }
+  return {
+    ok: true,
+    message: `${result.children.length} child task(s) created.`,
+    board: result.board,
+    task: freshParent,
+    children: result.children
+  };
+}
 async function requireBoard(projectRoot, boardId) {
   return boardId ? getBoard2(projectRoot, boardId) : null;
 }
@@ -1067,7 +1290,8 @@ function taskPatch(input) {
     labels: input.labels,
     assignedAgent: input.agentId,
     ...mergedDependsOn(input) ? { dependsOn: mergedDependsOn(input) } : {},
-    ...input.estimatedHours !== void 0 ? { estimatedHours: input.estimatedHours } : {}
+    ...input.estimatedHours !== void 0 ? { estimatedHours: input.estimatedHours } : {},
+    ...input.actualHours !== void 0 ? { actualHours: input.actualHours } : {}
   };
 }
 function assignmentInput(input) {