@workflow-cannon/workspace-kit 0.1.0 → 0.3.0

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

@@ -0,0 +1,101 @@
+const STATUS_MARKERS = {
+    proposed: "[p]",
+    ready: "[ ]",
+    in_progress: "[~]",
+    blocked: "[!]",
+    completed: "[x]",
+    cancelled: "[-]"
+};
+function groupByPhase(tasks) {
+    const groups = new Map();
+    for (const task of tasks) {
+        const phase = task.phase ?? "Uncategorized";
+        const group = groups.get(phase) ?? [];
+        group.push(task);
+        groups.set(phase, group);
+    }
+    return groups;
+}
+function buildReadyQueueLine(tasks) {
+    const ready = tasks
+        .filter((t) => t.status === "ready")
+        .sort((a, b) => {
+        const pa = a.priority ?? "P9";
+        const pb = b.priority ?? "P9";
+        return pa.localeCompare(pb);
+    });
+    if (ready.length === 0)
+        return "- Ready queue: _(empty)_";
+    return `- Ready queue: ${ready.map((t) => `\`${t.id}\``).join(", ")}`;
+}
+function buildCurrentPhase(tasks) {
+    const inProgress = tasks.filter((t) => t.status === "in_progress");
+    const ready = tasks.filter((t) => t.status === "ready");
+    const active = [...inProgress, ...ready];
+    if (active.length === 0)
+        return "- Current phase in execution: _(no active tasks)_";
+    const phases = [...new Set(active.map((t) => t.phase).filter(Boolean))];
+    if (phases.length === 0)
+        return "- Current phase in execution: _(unknown)_";
+    return `- Current phase in execution: _${phases[0]}_`;
+}
+function renderTask(task) {
+    const marker = STATUS_MARKERS[task.status] ?? "[ ]";
+    const lines = [];
+    lines.push(`### ${marker} ${task.id} ${task.title}`);
+    if (task.priority) {
+        lines.push(`- Priority: ${task.priority}`);
+    }
+    if (task.approach) {
+        lines.push(`- Approach: ${task.approach}`);
+    }
+    const deps = task.dependsOn ?? [];
+    lines.push(`- Depends on: ${deps.length > 0 ? deps.map((d) => `\`${d}\``).join(", ") : "none"}`);
+    const unblocks = task.unblocks ?? [];
+    if (unblocks.length > 0) {
+        lines.push(`- Unblocks: ${unblocks.map((u) => `\`${u}\``).join(", ")}`);
+    }
+    if (task.technicalScope && task.technicalScope.length > 0) {
+        lines.push("- Technical scope:");
+        for (const item of task.technicalScope) {
+            lines.push(`  - ${item}`);
+        }
+    }
+    if (task.acceptanceCriteria && task.acceptanceCriteria.length > 0) {
+        lines.push("- Acceptance criteria:");
+        for (const item of task.acceptanceCriteria) {
+            lines.push(`  - ${item}`);
+        }
+    }
+    return lines.join("\n");
+}
+export function generateTasksMd(tasks) {
+    const lines = [];
+    lines.push("# Workflow Cannon Tasks");
+    lines.push("");
+    lines.push("> This file is generated by the Task Engine. Do not edit manually.");
+    lines.push("");
+    lines.push("Status markers:");
+    lines.push("- `[p]` proposed");
+    lines.push("- `[ ]` ready");
+    lines.push("- `[~]` in progress");
+    lines.push("- `[!]` blocked");
+    lines.push("- `[x]` completed");
+    lines.push("- `[-]` cancelled");
+    lines.push("");
+    lines.push("## Current execution state");
+    lines.push("");
+    lines.push(buildCurrentPhase(tasks));
+    lines.push(buildReadyQueueLine(tasks));
+    lines.push("");
+    const phaseGroups = groupByPhase(tasks);
+    for (const [phase, phaseTasks] of phaseGroups) {
+        lines.push(`## ${phase}`);
+        lines.push("");
+        for (const task of phaseTasks) {
+            lines.push(renderTask(task));
+            lines.push("");
+        }
+    }
+    return lines.join("\n");
+}

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

@@ -0,0 +1,8 @@
+import type { TaskEntity } from "./types.js";
+export type ImportResult = {
+    imported: number;
+    skipped: number;
+    errors: string[];
+    tasks: TaskEntity[];
+};
+export declare function importTasksFromMarkdown(sourcePath: string): Promise<ImportResult>;

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

@@ -0,0 +1,157 @@
+import fs from "node:fs/promises";
+import { TaskEngineError } from "./transitions.js";
+const STATUS_MAP = {
+    "[p]": "proposed",
+    "[ ]": "ready",
+    "[~]": "in_progress",
+    "[!]": "blocked",
+    "[x]": "completed",
+    "[-]": "cancelled"
+};
+function parseTaskId(heading) {
+    const match = heading.match(/^###\s+\[[^\]]*\]\s+(T\d+)/);
+    return match?.[1] ?? null;
+}
+function parseStatus(heading) {
+    for (const [marker, status] of Object.entries(STATUS_MAP)) {
+        if (heading.includes(marker))
+            return status;
+    }
+    return "ready";
+}
+function parseTitle(heading) {
+    const match = heading.match(/^###\s+\[[^\]]*\]\s+T\d+\s+(.+)/);
+    return match?.[1]?.trim() ?? "Untitled";
+}
+function extractField(lines, prefix) {
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith(prefix)) {
+            return trimmed.slice(prefix.length).trim();
+        }
+    }
+    return undefined;
+}
+function extractListField(lines, fieldPrefix) {
+    const items = [];
+    let capturing = false;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith(fieldPrefix)) {
+            capturing = true;
+            continue;
+        }
+        if (capturing) {
+            if (/^\s{2,}-\s/.test(line)) {
+                items.push(line.replace(/^\s*-\s*/, "").trim());
+                continue;
+            }
+            if (trimmed.startsWith("- ")) {
+                capturing = false;
+                continue;
+            }
+            if (trimmed === "") {
+                continue;
+            }
+        }
+    }
+    return items;
+}
+function parseTaskIds(text) {
+    if (!text || text.trim() === "none")
+        return [];
+    const ids = [];
+    const matches = text.matchAll(/`?(T\d+)`?/g);
+    for (const m of matches) {
+        ids.push(m[1]);
+    }
+    return ids;
+}
+function parsePriority(text) {
+    if (!text)
+        return undefined;
+    const match = text.match(/(P[123])/);
+    return match?.[1];
+}
+function parsePhase(sectionHeading) {
+    const match = sectionHeading.match(/^##\s+(.+)/);
+    return match?.[1]?.trim();
+}
+export async function importTasksFromMarkdown(sourcePath) {
+    let content;
+    try {
+        content = await fs.readFile(sourcePath, "utf8");
+    }
+    catch (err) {
+        throw new TaskEngineError("import-parse-error", `Failed to read TASKS.md: ${err.message}`);
+    }
+    const lines = content.split("\n");
+    const tasks = [];
+    const errors = [];
+    let skipped = 0;
+    let currentPhase;
+    const now = new Date().toISOString();
+    let taskStartIdx = -1;
+    let taskLines = [];
+    function flushTask() {
+        if (taskStartIdx === -1 || taskLines.length === 0)
+            return;
+        const heading = taskLines[0];
+        const id = parseTaskId(heading);
+        if (!id) {
+            errors.push(`Line ${taskStartIdx + 1}: Could not parse task ID from heading`);
+            skipped++;
+            return;
+        }
+        const status = parseStatus(heading);
+        const title = parseTitle(heading);
+        const priorityStr = extractField(taskLines, "- Priority:");
+        const approach = extractField(taskLines, "- Approach:");
+        const dependsOnStr = extractField(taskLines, "- Depends on:");
+        const unblocksStr = extractField(taskLines, "- Unblocks:");
+        const technicalScope = extractListField(taskLines, "- Technical scope:");
+        const acceptanceCriteria = extractListField(taskLines, "- Acceptance criteria:");
+        const task = {
+            id,
+            status,
+            type: "workspace-kit",
+            title,
+            createdAt: now,
+            updatedAt: now,
+            priority: parsePriority(priorityStr),
+            dependsOn: parseTaskIds(dependsOnStr ?? ""),
+            unblocks: parseTaskIds(unblocksStr ?? ""),
+            phase: currentPhase,
+            approach: approach || undefined,
+            technicalScope: technicalScope.length > 0 ? technicalScope : undefined,
+            acceptanceCriteria: acceptanceCriteria.length > 0 ? acceptanceCriteria : undefined
+        };
+        tasks.push(task);
+    }
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.startsWith("## ") && !line.startsWith("### ")) {
+            flushTask();
+            taskStartIdx = -1;
+            taskLines = [];
+            currentPhase = parsePhase(line);
+            continue;
+        }
+        if (line.startsWith("### ")) {
+            flushTask();
+            taskStartIdx = i;
+            taskLines = [line];
+            continue;
+        }
+        if (taskStartIdx !== -1) {
+            taskLines.push(line);
+        }
+    }
+    flushTask();
+    return {
+        imported: tasks.length,
+        skipped,
+        errors,
+        tasks
+    };
+}

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

@@ -0,0 +1,9 @@
+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 { TaskStore } from "./store.js";
+export { TransitionService } from "./service.js";
+export { TaskEngineError, TransitionValidator, isTransitionAllowed, getTransitionAction, resolveTargetState, getAllowedTransitionsFrom, stateValidityGuard, dependencyCheckGuard } from "./transitions.js";
+export { generateTasksMd } from "./generator.js";
+export { importTasksFromMarkdown } from "./importer.js";
+export { getNextActions } from "./suggestions.js";
+export declare const taskEngineModule: WorkflowModule;

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

@@ -0,0 +1,253 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+import { TaskStore } from "./store.js";
+import { TransitionService } from "./service.js";
+import { TaskEngineError } from "./transitions.js";
+import { generateTasksMd } from "./generator.js";
+import { importTasksFromMarkdown } from "./importer.js";
+import { getNextActions } from "./suggestions.js";
+export { TaskStore } from "./store.js";
+export { TransitionService } from "./service.js";
+export { TaskEngineError, TransitionValidator, isTransitionAllowed, getTransitionAction, resolveTargetState, getAllowedTransitionsFrom, stateValidityGuard, dependencyCheckGuard } from "./transitions.js";
+export { generateTasksMd } from "./generator.js";
+export { importTasksFromMarkdown } from "./importer.js";
+export { getNextActions } from "./suggestions.js";
+export const taskEngineModule = {
+    registration: {
+        id: "task-engine",
+        version: "0.3.0",
+        contractVersion: "1",
+        capabilities: ["task-engine"],
+        dependsOn: [],
+        enabledByDefault: true,
+        config: {
+            path: "src/modules/task-engine/config.md",
+            format: "md",
+            description: "Task Engine configuration contract."
+        },
+        state: {
+            path: "src/modules/task-engine/state.md",
+            format: "md",
+            description: "Task Engine runtime state contract."
+        },
+        instructions: {
+            directory: "src/modules/task-engine/instructions",
+            entries: [
+                {
+                    name: "run-transition",
+                    file: "run-transition.md",
+                    description: "Execute a validated task status transition."
+                },
+                {
+                    name: "get-task",
+                    file: "get-task.md",
+                    description: "Retrieve a single task by ID."
+                },
+                {
+                    name: "list-tasks",
+                    file: "list-tasks.md",
+                    description: "List tasks with optional status/phase filters."
+                },
+                {
+                    name: "get-ready-queue",
+                    file: "get-ready-queue.md",
+                    description: "Get ready tasks sorted by priority."
+                },
+                {
+                    name: "import-tasks",
+                    file: "import-tasks.md",
+                    description: "One-time import from TASKS.md into engine state."
+                },
+                {
+                    name: "generate-tasks-md",
+                    file: "generate-tasks-md.md",
+                    description: "Generate read-only TASKS.md from engine state."
+                },
+                {
+                    name: "get-next-actions",
+                    file: "get-next-actions.md",
+                    description: "Get prioritized next-action suggestions with blocking analysis."
+                }
+            ]
+        }
+    },
+    async onCommand(command, ctx) {
+        const args = command.args ?? {};
+        const store = new TaskStore(ctx.workspacePath);
+        try {
+            await store.load();
+        }
+        catch (err) {
+            if (err instanceof TaskEngineError) {
+                return { ok: false, code: err.code, message: err.message };
+            }
+            return {
+                ok: false,
+                code: "storage-read-error",
+                message: `Failed to load task store: ${err.message}`
+            };
+        }
+        if (command.name === "run-transition") {
+            const taskId = typeof args.taskId === "string" ? args.taskId : undefined;
+            const action = typeof args.action === "string" ? args.action : undefined;
+            const actor = typeof args.actor === "string" ? args.actor : undefined;
+            if (!taskId || !action) {
+                return {
+                    ok: false,
+                    code: "invalid-task-schema",
+                    message: "run-transition requires 'taskId' and 'action' arguments"
+                };
+            }
+            try {
+                const service = new TransitionService(store);
+                const result = await service.runTransition({ taskId, action, actor });
+                return {
+                    ok: true,
+                    code: "transition-applied",
+                    message: `${taskId}: ${result.evidence.fromState} → ${result.evidence.toState} (${action})`,
+                    data: {
+                        evidence: result.evidence,
+                        autoUnblocked: result.autoUnblocked
+                    }
+                };
+            }
+            catch (err) {
+                if (err instanceof TaskEngineError) {
+                    return { ok: false, code: err.code, message: err.message };
+                }
+                return {
+                    ok: false,
+                    code: "invalid-transition",
+                    message: err.message
+                };
+            }
+        }
+        if (command.name === "get-task") {
+            const taskId = typeof args.taskId === "string" ? args.taskId : undefined;
+            if (!taskId) {
+                return {
+                    ok: false,
+                    code: "invalid-task-schema",
+                    message: "get-task requires 'taskId' argument"
+                };
+            }
+            const task = store.getTask(taskId);
+            if (!task) {
+                return {
+                    ok: false,
+                    code: "task-not-found",
+                    message: `Task '${taskId}' not found`
+                };
+            }
+            return {
+                ok: true,
+                code: "task-retrieved",
+                data: { task }
+            };
+        }
+        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();
+            if (statusFilter) {
+                tasks = tasks.filter((t) => t.status === statusFilter);
+            }
+            if (phaseFilter) {
+                tasks = tasks.filter((t) => t.phase === phaseFilter);
+            }
+            return {
+                ok: true,
+                code: "tasks-listed",
+                message: `Found ${tasks.length} tasks`,
+                data: { tasks, count: tasks.length }
+            };
+        }
+        if (command.name === "get-ready-queue") {
+            const tasks = store.getAllTasks();
+            const ready = tasks
+                .filter((t) => t.status === "ready")
+                .sort((a, b) => {
+                const pa = a.priority ?? "P9";
+                const pb = b.priority ?? "P9";
+                return pa.localeCompare(pb);
+            });
+            return {
+                ok: true,
+                code: "ready-queue-retrieved",
+                message: `${ready.length} tasks in ready queue`,
+                data: { tasks: ready, count: ready.length }
+            };
+        }
+        if (command.name === "import-tasks") {
+            const sourcePath = typeof args.sourcePath === "string"
+                ? path.resolve(ctx.workspacePath, args.sourcePath)
+                : path.resolve(ctx.workspacePath, "docs/maintainers/TASKS.md");
+            try {
+                const result = await importTasksFromMarkdown(sourcePath);
+                store.replaceAllTasks(result.tasks);
+                await store.save();
+                return {
+                    ok: true,
+                    code: "tasks-imported",
+                    message: `Imported ${result.imported} tasks (${result.skipped} skipped)`,
+                    data: {
+                        imported: result.imported,
+                        skipped: result.skipped,
+                        errors: result.errors
+                    }
+                };
+            }
+            catch (err) {
+                if (err instanceof TaskEngineError) {
+                    return { ok: false, code: err.code, message: err.message };
+                }
+                return {
+                    ok: false,
+                    code: "import-parse-error",
+                    message: err.message
+                };
+            }
+        }
+        if (command.name === "generate-tasks-md") {
+            const outputPath = typeof args.outputPath === "string"
+                ? path.resolve(ctx.workspacePath, args.outputPath)
+                : path.resolve(ctx.workspacePath, "docs/maintainers/TASKS.md");
+            const tasks = store.getAllTasks();
+            const markdown = generateTasksMd(tasks);
+            try {
+                await fs.mkdir(path.dirname(outputPath), { recursive: true });
+                await fs.writeFile(outputPath, markdown, "utf8");
+            }
+            catch (err) {
+                return {
+                    ok: false,
+                    code: "storage-write-error",
+                    message: `Failed to write TASKS.md: ${err.message}`
+                };
+            }
+            return {
+                ok: true,
+                code: "tasks-md-generated",
+                message: `Generated TASKS.md with ${tasks.length} tasks`,
+                data: { outputPath, taskCount: tasks.length }
+            };
+        }
+        if (command.name === "get-next-actions") {
+            const tasks = store.getAllTasks();
+            const suggestion = getNextActions(tasks);
+            return {
+                ok: true,
+                code: "next-actions-retrieved",
+                message: suggestion.suggestedNext
+                    ? `Suggested next: ${suggestion.suggestedNext.id} — ${suggestion.suggestedNext.title}`
+                    : "No tasks in ready queue",
+                data: suggestion
+            };
+        }
+        return {
+            ok: false,
+            code: "unsupported-command",
+            message: `Task Engine does not support command '${command.name}'`
+        };
+    }
+};

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

@@ -0,0 +1,21 @@
+import type { TransitionEvidence, TransitionGuard } from "./types.js";
+import { TransitionValidator } from "./transitions.js";
+import { TaskStore } from "./store.js";
+export type TransitionRequest = {
+    taskId: string;
+    action: string;
+    actor?: string;
+};
+export type TransitionResult = {
+    evidence: TransitionEvidence;
+    autoUnblocked: TransitionEvidence[];
+};
+export declare class TransitionService {
+    private readonly store;
+    private readonly validator;
+    constructor(store: TaskStore, customGuards?: TransitionGuard[]);
+    runTransition(request: TransitionRequest): Promise<TransitionResult>;
+    private autoUnblock;
+    getStore(): TaskStore;
+    getValidator(): TransitionValidator;
+}

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

@@ -0,0 +1,105 @@
+import crypto from "node:crypto";
+import { TaskEngineError, TransitionValidator, getTransitionAction, resolveTargetState } from "./transitions.js";
+export class TransitionService {
+    store;
+    validator;
+    constructor(store, customGuards = []) {
+        this.store = store;
+        this.validator = new TransitionValidator(customGuards);
+    }
+    async runTransition(request) {
+        const task = this.store.getTask(request.taskId);
+        if (!task) {
+            throw new TaskEngineError("task-not-found", `Task '${request.taskId}' not found`);
+        }
+        const targetState = resolveTargetState(task.status, request.action);
+        if (!targetState) {
+            throw new TaskEngineError("invalid-transition", `Action '${request.action}' is not valid from state '${task.status}'`);
+        }
+        const timestamp = new Date().toISOString();
+        const context = {
+            allTasks: this.store.getAllTasks(),
+            timestamp,
+            actor: request.actor
+        };
+        const validation = this.validator.validate(task, targetState, context);
+        if (!validation.allowed) {
+            const rejection = validation.guardResults.find((r) => !r.allowed);
+            if (rejection?.code === "dependency-unsatisfied") {
+                throw new TaskEngineError("dependency-unsatisfied", rejection.message ?? "Dependencies not satisfied");
+            }
+            if (rejection?.code === "invalid-transition") {
+                throw new TaskEngineError("invalid-transition", rejection.message ?? "Invalid transition");
+            }
+            throw new TaskEngineError("guard-rejected", rejection?.message ?? "Transition rejected by guard");
+        }
+        const fromState = task.status;
+        const updatedTask = {
+            ...task,
+            status: targetState,
+            updatedAt: timestamp
+        };
+        this.store.updateTask(updatedTask);
+        const action = getTransitionAction(fromState, targetState) ?? request.action;
+        const autoUnblockResults = targetState === "completed"
+            ? this.autoUnblock(request.taskId, timestamp, request.actor)
+            : [];
+        const evidence = {
+            transitionId: `${request.taskId}-${timestamp}-${crypto.randomUUID().slice(0, 8)}`,
+            taskId: request.taskId,
+            fromState,
+            toState: targetState,
+            action,
+            guardResults: validation.guardResults,
+            dependentsUnblocked: autoUnblockResults.map((r) => r.taskId),
+            timestamp,
+            actor: request.actor
+        };
+        this.store.addEvidence(evidence);
+        for (const unblockEvidence of autoUnblockResults) {
+            this.store.addEvidence(unblockEvidence);
+        }
+        await this.store.save();
+        return { evidence, autoUnblocked: autoUnblockResults };
+    }
+    autoUnblock(completedTaskId, timestamp, actor) {
+        const results = [];
+        const allTasks = this.store.getAllTasks();
+        const dependents = allTasks.filter((t) => t.status === "blocked" && t.dependsOn?.includes(completedTaskId));
+        for (const dependent of dependents) {
+            const deps = dependent.dependsOn ?? [];
+            const allDepsComplete = deps.every((depId) => {
+                if (depId === completedTaskId)
+                    return true;
+                const depTask = this.store.getTask(depId);
+                return depTask?.status === "completed";
+            });
+            if (!allDepsComplete)
+                continue;
+            const updatedDependent = {
+                ...dependent,
+                status: "ready",
+                updatedAt: timestamp
+            };
+            this.store.updateTask(updatedDependent);
+            results.push({
+                transitionId: `${dependent.id}-${timestamp}-${crypto.randomUUID().slice(0, 8)}`,
+                taskId: dependent.id,
+                fromState: "blocked",
+                toState: "ready",
+                action: "unblock",
+                guardResults: [{ allowed: true, guardName: "auto-unblock" }],
+                dependentsUnblocked: [],
+                timestamp,
+                actor
+            });
+        }
+        return results;
+    }
+    getStore() {
+        return this.store;
+    }
+    getValidator() {
+        return this.validator;
+    }
+}

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

@@ -0,0 +1,16 @@
+import type { TaskEntity, TransitionEvidence } from "./types.js";
+export declare class TaskStore {
+    private document;
+    private readonly filePath;
+    constructor(workspacePath: string, storePath?: string);
+    load(): Promise<void>;
+    save(): Promise<void>;
+    getAllTasks(): TaskEntity[];
+    getTask(id: string): TaskEntity | undefined;
+    addTask(task: TaskEntity): void;
+    updateTask(task: TaskEntity): void;
+    addEvidence(evidence: TransitionEvidence): void;
+    getTransitionLog(): TransitionEvidence[];
+    replaceAllTasks(tasks: TaskEntity[]): void;
+    getFilePath(): string;
+}