@workflow-cannon/workspace-kit 0.13.0 → 0.14.0

package/dist/modules/task-engine/index.d.ts

@@ -1,5 +1,5 @@
 import type { WorkflowModule } from "../../contracts/module-contract.js";
-export type { TaskEntity, TaskStatus, TaskPriority, TaskStoreDocument, TransitionEvidence, TransitionGuard, TransitionContext, GuardResult, TaskEngineError as TaskEngineErrorType, TaskEngineErrorCode, TaskAdapter, TaskAdapterCapability, NextActionSuggestion, BlockingAnalysisEntry } from "./types.js";
+export type { TaskEntity, TaskStatus, TaskPriority, TaskStoreDocument, TransitionEvidence, TransitionGuard, TransitionContext, GuardResult, TaskEngineError as TaskEngineErrorType, TaskEngineErrorCode, TaskAdapter, TaskAdapterCapability, NextActionSuggestion, BlockingAnalysisEntry, TaskMutationEvidence, TaskMutationType } from "./types.js";
 export { TaskStore } from "./store.js";
 export { TransitionService } from "./service.js";
 export { TaskEngineError, TransitionValidator, isTransitionAllowed, getTransitionAction, resolveTargetState, getAllowedTransitionsFrom, stateValidityGuard, dependencyCheckGuard } from "./transitions.js";

package/dist/modules/task-engine/index.js

@@ -1,3 +1,4 @@
+import crypto from "node:crypto";
 import { maybeSpawnTranscriptHookAfterCompletion } from "../../core/transcript-completion-hook.js";
 import { TaskStore } from "./store.js";
 import { TransitionService } from "./service.js";
@@ -17,6 +18,33 @@ function taskStorePath(ctx) {
     const p = tasks.storeRelativePath;
     return typeof p === "string" && p.trim().length > 0 ? p.trim() : undefined;
 }
+const TASK_ID_RE = /^T\d+$/;
+const MUTABLE_TASK_FIELDS = new Set([
+    "title",
+    "type",
+    "priority",
+    "dependsOn",
+    "unblocks",
+    "phase",
+    "metadata",
+    "ownership",
+    "approach",
+    "technicalScope",
+    "acceptanceCriteria"
+]);
+function nowIso() {
+    return new Date().toISOString();
+}
+function mutationEvidence(mutationType, taskId, actor, details) {
+    return {
+        mutationId: `${mutationType}-${taskId}-${nowIso()}-${crypto.randomUUID().slice(0, 8)}`,
+        mutationType,
+        taskId,
+        timestamp: nowIso(),
+        actor,
+        details
+    };
+}
 export const taskEngineModule = {
     registration: {
         id: "task-engine",
@@ -43,6 +71,61 @@ export const taskEngineModule = {
                     file: "run-transition.md",
                     description: "Execute a validated task status transition."
                 },
+                {
+                    name: "create-task",
+                    file: "create-task.md",
+                    description: "Create a new task through validated task-engine persistence."
+                },
+                {
+                    name: "update-task",
+                    file: "update-task.md",
+                    description: "Update mutable task fields without lifecycle bypass."
+                },
+                {
+                    name: "archive-task",
+                    file: "archive-task.md",
+                    description: "Archive a task without destructive deletion."
+                },
+                {
+                    name: "add-dependency",
+                    file: "add-dependency.md",
+                    description: "Add a dependency edge between tasks with cycle checks."
+                },
+                {
+                    name: "remove-dependency",
+                    file: "remove-dependency.md",
+                    description: "Remove a dependency edge between tasks."
+                },
+                {
+                    name: "get-dependency-graph",
+                    file: "get-dependency-graph.md",
+                    description: "Get dependency graph data for one task or the full store."
+                },
+                {
+                    name: "get-task-history",
+                    file: "get-task-history.md",
+                    description: "Get transition and mutation history for a task."
+                },
+                {
+                    name: "get-recent-task-activity",
+                    file: "get-recent-task-activity.md",
+                    description: "List recent transition and mutation activity across tasks."
+                },
+                {
+                    name: "get-task-summary",
+                    file: "get-task-summary.md",
+                    description: "Get aggregate task-state summary for active tasks."
+                },
+                {
+                    name: "get-blocked-summary",
+                    file: "get-blocked-summary.md",
+                    description: "Get blocked-task dependency summary for active tasks."
+                },
+                {
+                    name: "create-task-from-plan",
+                    file: "create-task-from-plan.md",
+                    description: "Promote planning output into a canonical task."
+                },
                 {
                     name: "get-task",
                     file: "get-task.md",
@@ -129,6 +212,123 @@ export const taskEngineModule = {
                 };
             }
         }
+        if (command.name === "create-task" || command.name === "create-task-from-plan") {
+            const actor = typeof args.actor === "string"
+                ? args.actor
+                : ctx.resolvedActor !== undefined
+                    ? ctx.resolvedActor
+                    : undefined;
+            const id = typeof args.id === "string" && args.id.trim().length > 0 ? args.id.trim() : undefined;
+            const title = typeof args.title === "string" && args.title.trim().length > 0 ? args.title.trim() : undefined;
+            const type = typeof args.type === "string" && args.type.trim().length > 0 ? args.type.trim() : "workspace-kit";
+            const status = typeof args.status === "string" ? args.status : "proposed";
+            const priority = typeof args.priority === "string" && ["P1", "P2", "P3"].includes(args.priority)
+                ? args.priority
+                : undefined;
+            if (!id || !title || !TASK_ID_RE.test(id) || !["proposed", "ready"].includes(status)) {
+                return {
+                    ok: false,
+                    code: "invalid-task-schema",
+                    message: "create-task requires id/title, id format T<number>, and status of proposed or ready"
+                };
+            }
+            if (store.getTask(id)) {
+                return { ok: false, code: "duplicate-task-id", message: `Task '${id}' already exists` };
+            }
+            const timestamp = nowIso();
+            const task = {
+                id,
+                title,
+                type,
+                status: status,
+                createdAt: timestamp,
+                updatedAt: timestamp,
+                priority,
+                dependsOn: Array.isArray(args.dependsOn) ? args.dependsOn.filter((x) => typeof x === "string") : undefined,
+                unblocks: Array.isArray(args.unblocks) ? args.unblocks.filter((x) => typeof x === "string") : undefined,
+                phase: typeof args.phase === "string" ? args.phase : undefined,
+                metadata: typeof args.metadata === "object" && args.metadata !== null ? args.metadata : undefined,
+                ownership: typeof args.ownership === "string" ? args.ownership : undefined,
+                approach: typeof args.approach === "string" ? args.approach : undefined,
+                technicalScope: Array.isArray(args.technicalScope) ? args.technicalScope.filter((x) => typeof x === "string") : undefined,
+                acceptanceCriteria: Array.isArray(args.acceptanceCriteria) ? args.acceptanceCriteria.filter((x) => typeof x === "string") : undefined
+            };
+            store.addTask(task);
+            if (command.name === "create-task-from-plan") {
+                const planRef = typeof args.planRef === "string" && args.planRef.trim().length > 0 ? args.planRef.trim() : undefined;
+                if (!planRef) {
+                    return {
+                        ok: false,
+                        code: "invalid-task-schema",
+                        message: "create-task-from-plan requires 'planRef'"
+                    };
+                }
+                task.metadata = { ...(task.metadata ?? {}), planRef };
+                store.updateTask(task);
+            }
+            const evidenceType = command.name === "create-task-from-plan" ? "create-task-from-plan" : "create-task";
+            store.addMutationEvidence(mutationEvidence(evidenceType, id, actor, {
+                initialStatus: task.status,
+                source: command.name
+            }));
+            await store.save();
+            return {
+                ok: true,
+                code: "task-created",
+                message: `Created task '${id}'`,
+                data: { task }
+            };
+        }
+        if (command.name === "update-task") {
+            const taskId = typeof args.taskId === "string" ? args.taskId : undefined;
+            const updates = typeof args.updates === "object" && args.updates !== null ? args.updates : undefined;
+            const actor = typeof args.actor === "string"
+                ? args.actor
+                : ctx.resolvedActor !== undefined
+                    ? ctx.resolvedActor
+                    : undefined;
+            if (!taskId || !updates) {
+                return { ok: false, code: "invalid-task-schema", message: "update-task requires taskId and updates object" };
+            }
+            const task = store.getTask(taskId);
+            if (!task) {
+                return { ok: false, code: "task-not-found", message: `Task '${taskId}' not found` };
+            }
+            const invalidKeys = Object.keys(updates).filter((key) => !MUTABLE_TASK_FIELDS.has(key));
+            if (invalidKeys.length > 0) {
+                return {
+                    ok: false,
+                    code: "invalid-task-update",
+                    message: `update-task cannot mutate immutable fields: ${invalidKeys.join(", ")}`
+                };
+            }
+            const updatedTask = { ...task, ...updates, updatedAt: nowIso() };
+            store.updateTask(updatedTask);
+            store.addMutationEvidence(mutationEvidence("update-task", taskId, actor, { updatedFields: Object.keys(updates) }));
+            await store.save();
+            return { ok: true, code: "task-updated", message: `Updated task '${taskId}'`, data: { task: updatedTask } };
+        }
+        if (command.name === "archive-task") {
+            const taskId = typeof args.taskId === "string" ? args.taskId : undefined;
+            const actor = typeof args.actor === "string"
+                ? args.actor
+                : ctx.resolvedActor !== undefined
+                    ? ctx.resolvedActor
+                    : undefined;
+            if (!taskId) {
+                return { ok: false, code: "invalid-task-schema", message: "archive-task requires taskId" };
+            }
+            const task = store.getTask(taskId);
+            if (!task) {
+                return { ok: false, code: "task-not-found", message: `Task '${taskId}' not found` };
+            }
+            const archivedAt = nowIso();
+            const updatedTask = { ...task, archived: true, archivedAt, updatedAt: archivedAt };
+            store.updateTask(updatedTask);
+            store.addMutationEvidence(mutationEvidence("archive-task", taskId, actor));
+            await store.save();
+            return { ok: true, code: "task-archived", message: `Archived task '${taskId}'`, data: { task: updatedTask } };
+        }
         if (command.name === "get-task") {
             const taskId = typeof args.taskId === "string" ? args.taskId : undefined;
             if (!taskId) {
@@ -165,8 +365,95 @@ export const taskEngineModule = {
                 data: { task, recentTransitions, allowedActions }
             };
         }
+        if (command.name === "add-dependency" || command.name === "remove-dependency") {
+            const taskId = typeof args.taskId === "string" ? args.taskId : undefined;
+            const dependencyTaskId = typeof args.dependencyTaskId === "string" ? args.dependencyTaskId : undefined;
+            const actor = typeof args.actor === "string"
+                ? args.actor
+                : ctx.resolvedActor !== undefined
+                    ? ctx.resolvedActor
+                    : undefined;
+            if (!taskId || !dependencyTaskId) {
+                return {
+                    ok: false,
+                    code: "invalid-task-schema",
+                    message: `${command.name} requires taskId and dependencyTaskId`
+                };
+            }
+            if (taskId === dependencyTaskId) {
+                return { ok: false, code: "dependency-cycle", message: "Task cannot depend on itself" };
+            }
+            const task = store.getTask(taskId);
+            const dep = store.getTask(dependencyTaskId);
+            if (!task || !dep) {
+                return { ok: false, code: "task-not-found", message: "taskId or dependencyTaskId not found" };
+            }
+            const deps = new Set(task.dependsOn ?? []);
+            if (command.name === "add-dependency") {
+                if (deps.has(dependencyTaskId)) {
+                    return { ok: false, code: "duplicate-dependency", message: "Dependency already exists" };
+                }
+                deps.add(dependencyTaskId);
+            }
+            else {
+                deps.delete(dependencyTaskId);
+            }
+            const updatedTask = { ...task, dependsOn: [...deps], updatedAt: nowIso() };
+            store.updateTask(updatedTask);
+            const mutationType = command.name === "add-dependency" ? "add-dependency" : "remove-dependency";
+            store.addMutationEvidence(mutationEvidence(mutationType, taskId, actor, { dependencyTaskId }));
+            await store.save();
+            return {
+                ok: true,
+                code: command.name === "add-dependency" ? "dependency-added" : "dependency-removed",
+                message: `${command.name} applied for '${taskId}'`,
+                data: { task: updatedTask }
+            };
+        }
+        if (command.name === "get-dependency-graph") {
+            const taskId = typeof args.taskId === "string" ? args.taskId : undefined;
+            const tasks = store.getActiveTasks();
+            const nodes = tasks.map((task) => ({ id: task.id, status: task.status }));
+            const edges = tasks.flatMap((task) => (task.dependsOn ?? []).map((depId) => ({ from: task.id, to: depId })));
+            if (!taskId) {
+                return { ok: true, code: "dependency-graph", data: { nodes, edges } };
+            }
+            const task = tasks.find((candidate) => candidate.id === taskId);
+            if (!task) {
+                return { ok: false, code: "task-not-found", message: `Task '${taskId}' not found` };
+            }
+            return {
+                ok: true,
+                code: "dependency-graph",
+                data: {
+                    taskId,
+                    dependsOn: task.dependsOn ?? [],
+                    directDependents: tasks.filter((candidate) => (candidate.dependsOn ?? []).includes(taskId)).map((x) => x.id),
+                    nodes,
+                    edges
+                }
+            };
+        }
+        if (command.name === "get-task-history" || command.name === "get-recent-task-activity") {
+            const limitRaw = args.limit;
+            const limit = typeof limitRaw === "number" && Number.isFinite(limitRaw) && limitRaw > 0
+                ? Math.min(Math.floor(limitRaw), 500)
+                : 50;
+            const taskId = typeof args.taskId === "string" ? args.taskId : undefined;
+            const transitions = store.getTransitionLog().map((entry) => ({ kind: "transition", ...entry }));
+            const mutations = store.getMutationLog().map((entry) => ({ kind: "mutation", ...entry }));
+            const merged = [...transitions, ...mutations]
+                .filter((entry) => (taskId ? entry.taskId === taskId : true))
+                .sort((a, b) => (a.timestamp < b.timestamp ? 1 : -1))
+                .slice(0, limit);
+            return {
+                ok: true,
+                code: command.name === "get-task-history" ? "task-history" : "recent-task-activity",
+                data: { taskId: taskId ?? null, items: merged, count: merged.length }
+            };
+        }
         if (command.name === "dashboard-summary") {
-            const tasks = store.getAllTasks();
+            const tasks = store.getActiveTasks();
             const suggestion = getNextActions(tasks);
             const workspaceStatus = await readWorkspaceStatusSnapshot(ctx.workspacePath);
             const readyTop = suggestion.readyQueue.slice(0, 15).map((t) => ({
@@ -208,7 +495,8 @@ export const taskEngineModule = {
         if (command.name === "list-tasks") {
             const statusFilter = typeof args.status === "string" ? args.status : undefined;
             const phaseFilter = typeof args.phase === "string" ? args.phase : undefined;
-            let tasks = store.getAllTasks();
+            const includeArchived = args.includeArchived === true;
+            let tasks = includeArchived ? store.getAllTasks() : store.getActiveTasks();
             if (statusFilter) {
                 tasks = tasks.filter((t) => t.status === statusFilter);
             }
@@ -223,7 +511,7 @@ export const taskEngineModule = {
             };
         }
         if (command.name === "get-ready-queue") {
-            const tasks = store.getAllTasks();
+            const tasks = store.getActiveTasks();
             const ready = tasks
                 .filter((t) => t.status === "ready")
                 .sort((a, b) => {
@@ -239,7 +527,7 @@ export const taskEngineModule = {
             };
         }
         if (command.name === "get-next-actions") {
-            const tasks = store.getAllTasks();
+            const tasks = store.getActiveTasks();
             const suggestion = getNextActions(tasks);
             return {
                 ok: true,
@@ -250,6 +538,37 @@ export const taskEngineModule = {
                 data: suggestion
             };
         }
+        if (command.name === "get-task-summary") {
+            const tasks = store.getActiveTasks();
+            const suggestion = getNextActions(tasks);
+            return {
+                ok: true,
+                code: "task-summary",
+                data: {
+                    stateSummary: suggestion.stateSummary,
+                    readyQueueCount: suggestion.readyQueue.length,
+                    suggestedNext: suggestion.suggestedNext
+                        ? {
+                            id: suggestion.suggestedNext.id,
+                            title: suggestion.suggestedNext.title,
+                            priority: suggestion.suggestedNext.priority ?? null
+                        }
+                        : null
+                }
+            };
+        }
+        if (command.name === "get-blocked-summary") {
+            const tasks = store.getActiveTasks();
+            const suggestion = getNextActions(tasks);
+            return {
+                ok: true,
+                code: "blocked-summary",
+                data: {
+                    blockedCount: suggestion.blockingAnalysis.length,
+                    blockedItems: suggestion.blockingAnalysis
+                }
+            };
+        }
         return {
             ok: false,
             code: "unsupported-command",

package/dist/modules/task-engine/store.d.ts

@@ -1,4 +1,4 @@
-import type { TaskEntity, TransitionEvidence } from "./types.js";
+import type { TaskEntity, TaskMutationEvidence, TransitionEvidence } from "./types.js";
 export declare class TaskStore {
     private document;
     private readonly filePath;
@@ -6,11 +6,14 @@ export declare class TaskStore {
     load(): Promise<void>;
     save(): Promise<void>;
     getAllTasks(): TaskEntity[];
+    getActiveTasks(): TaskEntity[];
     getTask(id: string): TaskEntity | undefined;
     addTask(task: TaskEntity): void;
     updateTask(task: TaskEntity): void;
     addEvidence(evidence: TransitionEvidence): void;
+    addMutationEvidence(evidence: TaskMutationEvidence): void;
     getTransitionLog(): TransitionEvidence[];
+    getMutationLog(): TaskMutationEvidence[];
     replaceAllTasks(tasks: TaskEntity[]): void;
     getFilePath(): string;
     getLastUpdated(): string;

package/dist/modules/task-engine/store.js

@@ -8,6 +8,7 @@ function emptyStore() {
         schemaVersion: 1,
         tasks: [],
         transitionLog: [],
+        mutationLog: [],
         lastUpdated: new Date().toISOString()
     };
 }
@@ -26,6 +27,9 @@ export class TaskStore {
                 throw new TaskEngineError("storage-read-error", `Unsupported schema version: ${parsed.schemaVersion}`);
             }
             this.document = parsed;
+            if (!Array.isArray(this.document.mutationLog)) {
+                this.document.mutationLog = [];
+            }
         }
         catch (err) {
             if (err.code === "ENOENT") {
@@ -57,6 +61,9 @@ export class TaskStore {
     getAllTasks() {
         return [...this.document.tasks];
     }
+    getActiveTasks() {
+        return this.document.tasks.filter((task) => !task.archived).map((task) => ({ ...task }));
+    }
     getTask(id) {
         return this.document.tasks.find((t) => t.id === id);
     }
@@ -76,9 +83,18 @@ export class TaskStore {
     addEvidence(evidence) {
         this.document.transitionLog.push(evidence);
     }
+    addMutationEvidence(evidence) {
+        if (!Array.isArray(this.document.mutationLog)) {
+            this.document.mutationLog = [];
+        }
+        this.document.mutationLog.push(evidence);
+    }
     getTransitionLog() {
         return [...this.document.transitionLog];
     }
+    getMutationLog() {
+        return [...(this.document.mutationLog ?? [])];
+    }
     replaceAllTasks(tasks) {
         this.document.tasks = tasks.map((t) => ({ ...t }));
     }

package/dist/modules/task-engine/types.d.ts

@@ -7,6 +7,8 @@ export type TaskEntity = {
     title: string;
     createdAt: string;
     updatedAt: string;
+    archived?: boolean;
+    archivedAt?: string;
     priority?: TaskPriority;
     dependsOn?: string[];
     unblocks?: string[];
@@ -47,13 +49,23 @@ export type TaskStoreDocument = {
     schemaVersion: 1;
     tasks: TaskEntity[];
     transitionLog: TransitionEvidence[];
+    mutationLog?: TaskMutationEvidence[];
     lastUpdated: string;
 };
+export type TaskMutationType = "create-task" | "update-task" | "archive-task" | "add-dependency" | "remove-dependency" | "create-task-from-plan";
+export type TaskMutationEvidence = {
+    mutationId: string;
+    mutationType: TaskMutationType;
+    taskId: string;
+    timestamp: string;
+    actor?: string;
+    details?: Record<string, unknown>;
+};
 export type TaskEngineError = {
     code: TaskEngineErrorCode;
     message: string;
 };
-export type TaskEngineErrorCode = "invalid-transition" | "guard-rejected" | "dependency-unsatisfied" | "task-not-found" | "duplicate-task-id" | "invalid-task-schema" | "storage-read-error" | "storage-write-error" | "invalid-adapter" | "import-parse-error";
+export type TaskEngineErrorCode = "invalid-transition" | "guard-rejected" | "dependency-unsatisfied" | "task-not-found" | "duplicate-task-id" | "invalid-task-schema" | "invalid-task-update" | "invalid-task-id-format" | "task-archived" | "dependency-cycle" | "duplicate-dependency" | "storage-read-error" | "storage-write-error" | "invalid-adapter" | "import-parse-error";
 export type TaskAdapter = {
     name: string;
     supports: () => TaskAdapterCapability[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workflow-cannon/workspace-kit",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "private": false,
   "packageManager": "pnpm@10.0.0",
   "license": "MIT",
@@ -36,7 +36,9 @@
     "pre-release-transcript-hook": "pnpm run build && node scripts/pre-release-transcript-hook.mjs",
     "transcript:sync": "node scripts/run-transcript-cli.mjs sync-transcripts",
     "transcript:ingest": "node scripts/run-transcript-cli.mjs ingest-transcripts",
-    "ext:compile": "cd extensions/cursor-workflow-cannon && npm run compile"
+    "ext:compile": "cd extensions/cursor-workflow-cannon && npm run compile",
+    "ui:prepare": "pnpm run build && pnpm run ext:compile",
+    "ui:watch": "cd extensions/cursor-workflow-cannon && npm run watch"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",