@workflow-cannon/workspace-kit 0.18.0 → 0.24.0

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

@@ -1,15 +1,3 @@
-import crypto from "node:crypto";
-import { maybeSpawnTranscriptHookAfterCompletion } from "../../core/transcript-completion-hook.js";
-import { TransitionService } from "./service.js";
-import { TaskEngineError, getAllowedTransitionsFrom } from "./transitions.js";
-import { getNextActions } from "./suggestions.js";
-import { readWorkspaceStatusSnapshot } from "./dashboard-status.js";
-import { openPlanningStores } from "./planning-open.js";
-import { runMigrateTaskPersistence } from "./migrate-task-persistence-runtime.js";
-import { planningStrictValidationEnabled } from "./planning-config.js";
-import { validateTaskSetForStrictMode } from "./strict-task-validation.js";
-import { validateKnownTaskTypeRequirements } from "./task-type-validation.js";
-import { buildWishlistItemFromIntake, validateWishlistIntakePayload, validateWishlistUpdatePayload, WISHLIST_ID_RE } from "./wishlist-validation.js";
 export { TaskStore } from "./store.js";
 export { TransitionService } from "./service.js";
 export { TaskEngineError, TransitionValidator, isTransitionAllowed, getTransitionAction, resolveTargetState, getAllowedTransitionsFrom, stateValidityGuard, dependencyCheckGuard } from "./transitions.js";
@@ -19,1134 +7,4 @@ export { WishlistStore } from "./wishlist-store.js";
 export { validateWishlistIntakePayload, validateWishlistUpdatePayload, buildWishlistItemFromIntake, WISHLIST_ID_RE } from "./wishlist-validation.js";
 export { openPlanningStores } from "./planning-open.js";
 export { getTaskPersistenceBackend, planningSqliteDatabaseRelativePath, planningTaskStoreRelativePath, planningWishlistStoreRelativePath } from "./planning-config.js";
-const TASK_ID_RE = /^T\d+$/;
-const SAFE_METADATA_PATH_RE = /^[a-zA-Z0-9_-]+(?:\.[a-zA-Z0-9_-]+)*$/;
-const MUTABLE_TASK_FIELDS = new Set([
-    "title",
-    "type",
-    "priority",
-    "dependsOn",
-    "unblocks",
-    "phase",
-    "metadata",
-    "ownership",
-    "approach",
-    "technicalScope",
-    "acceptanceCriteria"
-]);
-function isRecordLike(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function readMetadataPath(metadata, path) {
-    if (!metadata || !SAFE_METADATA_PATH_RE.test(path)) {
-        return undefined;
-    }
-    const parts = path.split(".");
-    let current = metadata;
-    for (const part of parts) {
-        if (!isRecordLike(current)) {
-            return undefined;
-        }
-        if (!Object.prototype.hasOwnProperty.call(current, part)) {
-            return undefined;
-        }
-        current = current[part];
-    }
-    return current;
-}
-function stableStringify(value) {
-    if (Array.isArray(value)) {
-        return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
-    }
-    if (value && typeof value === "object") {
-        const record = value;
-        const keys = Object.keys(record).sort();
-        return `{${keys.map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`).join(",")}}`;
-    }
-    return JSON.stringify(value);
-}
-function digestPayload(value) {
-    return crypto.createHash("sha256").update(stableStringify(value)).digest("hex");
-}
-function readIdempotencyValue(args) {
-    const raw = args.clientMutationId;
-    if (typeof raw !== "string") {
-        return undefined;
-    }
-    const trimmed = raw.trim();
-    return trimmed.length > 0 ? trimmed : undefined;
-}
-function findIdempotentMutation(store, mutationType, taskId, clientMutationId) {
-    const log = store.getMutationLog();
-    for (let idx = log.length - 1; idx >= 0; idx -= 1) {
-        const entry = log[idx];
-        if (entry.mutationType !== mutationType || entry.taskId !== taskId) {
-            continue;
-        }
-        if (!entry.details || entry.details.clientMutationId !== clientMutationId) {
-            continue;
-        }
-        return {
-            payloadDigest: typeof entry.details.payloadDigest === "string" ? entry.details.payloadDigest : undefined
-        };
-    }
-    return null;
-}
-function strictValidationError(store, effectiveConfig) {
-    if (!planningStrictValidationEnabled({ effectiveConfig })) {
-        return null;
-    }
-    return validateTaskSetForStrictMode(store.getAllTasks());
-}
-function nowIso() {
-    return new Date().toISOString();
-}
-function parseConversionDecomposition(raw) {
-    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
-        return { ok: false, message: "convert-wishlist requires 'decomposition' object" };
-    }
-    const o = raw;
-    const rationale = typeof o.rationale === "string" ? o.rationale.trim() : "";
-    const boundaries = typeof o.boundaries === "string" ? o.boundaries.trim() : "";
-    const dependencyIntent = typeof o.dependencyIntent === "string" ? o.dependencyIntent.trim() : "";
-    if (!rationale || !boundaries || !dependencyIntent) {
-        return {
-            ok: false,
-            message: "decomposition requires non-empty rationale, boundaries, and dependencyIntent"
-        };
-    }
-    return { ok: true, value: { rationale, boundaries, dependencyIntent } };
-}
-function buildTaskFromConversionPayload(row, timestamp) {
-    const id = typeof row.id === "string" ? row.id.trim() : "";
-    if (!TASK_ID_RE.test(id)) {
-        return { ok: false, message: "Each converted task requires 'id' matching T<number>" };
-    }
-    const title = typeof row.title === "string" ? row.title.trim() : "";
-    if (!title) {
-        return { ok: false, message: `Task '${id}' requires non-empty title` };
-    }
-    const phase = typeof row.phase === "string" ? row.phase.trim() : "";
-    if (!phase) {
-        return { ok: false, message: `Task '${id}' requires 'phase' for workable tasks` };
-    }
-    const type = typeof row.type === "string" && row.type.trim() ? row.type.trim() : "workspace-kit";
-    const priority = typeof row.priority === "string" && ["P1", "P2", "P3"].includes(row.priority)
-        ? row.priority
-        : undefined;
-    const approach = typeof row.approach === "string" ? row.approach.trim() : "";
-    if (!approach) {
-        return { ok: false, message: `Task '${id}' requires 'approach'` };
-    }
-    const technicalScope = Array.isArray(row.technicalScope)
-        ? row.technicalScope.filter((x) => typeof x === "string")
-        : [];
-    const acceptanceCriteria = Array.isArray(row.acceptanceCriteria)
-        ? row.acceptanceCriteria.filter((x) => typeof x === "string")
-        : [];
-    if (technicalScope.length === 0) {
-        return { ok: false, message: `Task '${id}' requires non-empty technicalScope array` };
-    }
-    if (acceptanceCriteria.length === 0) {
-        return { ok: false, message: `Task '${id}' requires non-empty acceptanceCriteria array` };
-    }
-    const task = {
-        id,
-        title,
-        type,
-        status: "proposed",
-        createdAt: timestamp,
-        updatedAt: timestamp,
-        priority,
-        dependsOn: Array.isArray(row.dependsOn) ? row.dependsOn.filter((x) => typeof x === "string") : undefined,
-        unblocks: Array.isArray(row.unblocks) ? row.unblocks.filter((x) => typeof x === "string") : undefined,
-        phase,
-        approach,
-        technicalScope,
-        acceptanceCriteria
-    };
-    return { ok: true, task };
-}
-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",
-        version: "0.6.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: "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: "update-wishlist",
-                    file: "update-wishlist.md",
-                    description: "Update mutable fields on an open Wishlist item."
-                },
-                {
-                    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: "convert-wishlist",
-                    file: "convert-wishlist.md",
-                    description: "Convert a Wishlist item into one or more phased tasks and close the wishlist item."
-                },
-                {
-                    name: "create-wishlist",
-                    file: "create-wishlist.md",
-                    description: "Create a Wishlist ideation item with strict required fields (separate namespace from tasks)."
-                },
-                {
-                    name: "get-wishlist",
-                    file: "get-wishlist.md",
-                    description: "Retrieve a single Wishlist item by ID."
-                },
-                {
-                    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: "list-wishlist",
-                    file: "list-wishlist.md",
-                    description: "List Wishlist items (ideation-only; not part of task execution queues)."
-                },
-                {
-                    name: "get-ready-queue",
-                    file: "get-ready-queue.md",
-                    description: "Get ready tasks sorted by priority."
-                },
-                {
-                    name: "get-next-actions",
-                    file: "get-next-actions.md",
-                    description: "Get prioritized next-action suggestions with blocking analysis."
-                },
-                {
-                    name: "migrate-task-persistence",
-                    file: "migrate-task-persistence.md",
-                    description: "Copy task + wishlist state between JSON files and a single SQLite database (offline migration)."
-                },
-                {
-                    name: "dashboard-summary",
-                    file: "dashboard-summary.md",
-                    description: "Stable JSON cockpit summary for UI clients (tasks + maintainer status snapshot)."
-                },
-                {
-                    name: "explain-task-engine-model",
-                    file: "explain-task-engine-model.md",
-                    description: "Explain model variants, planning boundaries, lifecycle transitions, and required fields."
-                }
-            ]
-        }
-    },
-    async onCommand(command, ctx) {
-        const args = command.args ?? {};
-        if (command.name === "migrate-task-persistence") {
-            return runMigrateTaskPersistence(ctx, args);
-        }
-        let planning;
-        try {
-            planning = await openPlanningStores(ctx);
-        }
-        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 open task planning stores: ${err.message}`
-            };
-        }
-        const store = planning.taskStore;
-        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
-                : ctx.resolvedActor !== undefined
-                    ? ctx.resolvedActor
-                    : 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 });
-                if (result.evidence.toState === "completed") {
-                    maybeSpawnTranscriptHookAfterCompletion(ctx.workspacePath, (ctx.effectiveConfig ?? {}));
-                }
-                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 === "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;
-            const clientMutationId = readIdempotencyValue(args);
-            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"
-                };
-            }
-            const evidenceType = command.name === "create-task-from-plan" ? "create-task-from-plan" : "create-task";
-            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
-            };
-            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 };
-            }
-            const createPayloadForDigest = {
-                id: task.id,
-                title: task.title,
-                type: task.type,
-                status: task.status,
-                priority: task.priority,
-                dependsOn: task.dependsOn ?? [],
-                unblocks: task.unblocks ?? [],
-                phase: task.phase ?? null,
-                metadata: task.metadata ?? null,
-                ownership: task.ownership ?? null,
-                approach: task.approach ?? null,
-                technicalScope: task.technicalScope ?? [],
-                acceptanceCriteria: task.acceptanceCriteria ?? []
-            };
-            const payloadDigest = digestPayload(createPayloadForDigest);
-            if (clientMutationId) {
-                const prior = findIdempotentMutation(store, evidenceType, id, clientMutationId);
-                if (prior) {
-                    if (prior.payloadDigest !== payloadDigest) {
-                        return {
-                            ok: false,
-                            code: "idempotency-key-conflict",
-                            message: `clientMutationId '${clientMutationId}' was already used for a different ${evidenceType} payload on ${id}`
-                        };
-                    }
-                    return {
-                        ok: true,
-                        code: "task-create-idempotent-replay",
-                        message: `Idempotent create replay for task '${id}'`,
-                        data: { task: store.getTask(id), replayed: true }
-                    };
-                }
-            }
-            if (store.getTask(id)) {
-                return { ok: false, code: "duplicate-task-id", message: `Task '${id}' already exists` };
-            }
-            const knownTypeValidationError = validateKnownTaskTypeRequirements(task);
-            if (knownTypeValidationError) {
-                return {
-                    ok: false,
-                    code: knownTypeValidationError.code,
-                    message: knownTypeValidationError.message
-                };
-            }
-            store.addTask(task);
-            store.addMutationEvidence(mutationEvidence(evidenceType, id, actor, {
-                initialStatus: task.status,
-                source: command.name,
-                clientMutationId,
-                payloadDigest
-            }));
-            const strictIssue = strictValidationError(store, ctx.effectiveConfig);
-            if (strictIssue) {
-                return { ok: false, code: "strict-task-validation-failed", message: strictIssue };
-            }
-            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 clientMutationId = readIdempotencyValue(args);
-            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() };
-            const payloadDigest = digestPayload({ taskId, updates });
-            if (clientMutationId) {
-                const prior = findIdempotentMutation(store, "update-task", taskId, clientMutationId);
-                if (prior) {
-                    if (prior.payloadDigest !== payloadDigest) {
-                        return {
-                            ok: false,
-                            code: "idempotency-key-conflict",
-                            message: `clientMutationId '${clientMutationId}' was already used for a different update-task payload on ${taskId}`
-                        };
-                    }
-                    return {
-                        ok: true,
-                        code: "task-update-idempotent-replay",
-                        message: `Idempotent update replay for task '${taskId}'`,
-                        data: { task, replayed: true }
-                    };
-                }
-            }
-            const knownTypeValidationError = validateKnownTaskTypeRequirements(updatedTask);
-            if (knownTypeValidationError) {
-                return {
-                    ok: false,
-                    code: knownTypeValidationError.code,
-                    message: knownTypeValidationError.message
-                };
-            }
-            store.updateTask(updatedTask);
-            store.addMutationEvidence(mutationEvidence("update-task", taskId, actor, {
-                updatedFields: Object.keys(updates),
-                clientMutationId,
-                payloadDigest
-            }));
-            const strictIssue = strictValidationError(store, ctx.effectiveConfig);
-            if (strictIssue) {
-                return { ok: false, code: "strict-task-validation-failed", message: strictIssue };
-            }
-            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));
-            const strictIssue = strictValidationError(store, ctx.effectiveConfig);
-            if (strictIssue) {
-                return { ok: false, code: "strict-task-validation-failed", message: strictIssue };
-            }
-            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) {
-                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`
-                };
-            }
-            const historyLimitRaw = args.historyLimit;
-            const historyLimit = typeof historyLimitRaw === "number" && Number.isFinite(historyLimitRaw) && historyLimitRaw > 0
-                ? Math.min(Math.floor(historyLimitRaw), 200)
-                : 50;
-            const log = store.getTransitionLog();
-            const recentTransitions = log
-                .filter((e) => e.taskId === taskId)
-                .sort((a, b) => (a.timestamp < b.timestamp ? 1 : -1))
-                .slice(0, historyLimit);
-            const allowedActions = getAllowedTransitionsFrom(task.status).map(({ to, action }) => ({
-                action,
-                targetStatus: to
-            }));
-            return {
-                ok: true,
-                code: "task-retrieved",
-                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 }));
-            const strictIssue = strictValidationError(store, ctx.effectiveConfig);
-            if (strictIssue) {
-                return { ok: false, code: "strict-task-validation-failed", message: strictIssue };
-            }
-            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.getActiveTasks();
-            const suggestion = getNextActions(tasks);
-            const workspaceStatus = await readWorkspaceStatusSnapshot(ctx.workspacePath);
-            const readyTop = suggestion.readyQueue.slice(0, 15).map((t) => ({
-                id: t.id,
-                title: t.title,
-                priority: t.priority ?? null,
-                phase: t.phase ?? null
-            }));
-            const blockedTop = suggestion.blockingAnalysis.slice(0, 15);
-            let wishlistItems = [];
-            try {
-                const wishlistStore = await planning.openWishlist();
-                wishlistItems = wishlistStore.getAllItems();
-            }
-            catch {
-                /* wishlist store optional */
-            }
-            const wishlistOpenCount = wishlistItems.filter((i) => i.status === "open").length;
-            const data = {
-                schemaVersion: 1,
-                taskStoreLastUpdated: store.getLastUpdated(),
-                workspaceStatus,
-                stateSummary: suggestion.stateSummary,
-                readyQueueTop: readyTop,
-                readyQueueCount: suggestion.readyQueue.length,
-                executionPlanningScope: "tasks-only",
-                wishlist: {
-                    schemaVersion: 1,
-                    openCount: wishlistOpenCount,
-                    totalCount: wishlistItems.length
-                },
-                blockedSummary: {
-                    count: suggestion.blockingAnalysis.length,
-                    top: blockedTop
-                },
-                suggestedNext: suggestion.suggestedNext
-                    ? {
-                        id: suggestion.suggestedNext.id,
-                        title: suggestion.suggestedNext.title,
-                        status: suggestion.suggestedNext.status,
-                        priority: suggestion.suggestedNext.priority ?? null,
-                        phase: suggestion.suggestedNext.phase ?? null
-                    }
-                    : null,
-                blockingAnalysis: suggestion.blockingAnalysis
-            };
-            return {
-                ok: true,
-                code: "dashboard-summary",
-                message: "Dashboard summary built from task store and maintainer status snapshot",
-                data
-            };
-        }
-        if (command.name === "list-tasks") {
-            const statusFilter = typeof args.status === "string" ? args.status : undefined;
-            const phaseFilter = typeof args.phase === "string" ? args.phase : undefined;
-            const typeFilter = typeof args.type === "string" && args.type.trim().length > 0 ? args.type.trim() : undefined;
-            const categoryFilter = typeof args.category === "string" && args.category.trim().length > 0 ? args.category.trim() : undefined;
-            const tagsFilterRaw = args.tags;
-            const tagsFilter = typeof tagsFilterRaw === "string"
-                ? [tagsFilterRaw]
-                : Array.isArray(tagsFilterRaw)
-                    ? tagsFilterRaw.filter((entry) => typeof entry === "string" && entry.trim().length > 0)
-                    : [];
-            const metadataFilters = isRecordLike(args.metadataFilters)
-                ? Object.entries(args.metadataFilters).filter(([path]) => SAFE_METADATA_PATH_RE.test(path))
-                : [];
-            const includeArchived = args.includeArchived === true;
-            let tasks = includeArchived ? store.getAllTasks() : store.getActiveTasks();
-            if (statusFilter) {
-                tasks = tasks.filter((t) => t.status === statusFilter);
-            }
-            if (phaseFilter) {
-                tasks = tasks.filter((t) => t.phase === phaseFilter);
-            }
-            if (typeFilter) {
-                tasks = tasks.filter((t) => t.type === typeFilter);
-            }
-            if (categoryFilter) {
-                tasks = tasks.filter((t) => readMetadataPath(t.metadata, "category") === categoryFilter);
-            }
-            if (tagsFilter.length > 0) {
-                tasks = tasks.filter((t) => {
-                    const tags = readMetadataPath(t.metadata, "tags");
-                    if (!Array.isArray(tags)) {
-                        return false;
-                    }
-                    const normalized = tags.filter((entry) => typeof entry === "string");
-                    return tagsFilter.every((tag) => normalized.includes(tag));
-                });
-            }
-            if (metadataFilters.length > 0) {
-                tasks = tasks.filter((t) => metadataFilters.every(([path, expected]) => readMetadataPath(t.metadata, path) === expected));
-            }
-            return {
-                ok: true,
-                code: "tasks-listed",
-                message: `Found ${tasks.length} tasks`,
-                data: { tasks, count: tasks.length, scope: "tasks-only" }
-            };
-        }
-        if (command.name === "get-ready-queue") {
-            const tasks = store.getActiveTasks();
-            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, scope: "tasks-only" }
-            };
-        }
-        if (command.name === "get-next-actions") {
-            const tasks = store.getActiveTasks();
-            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, scope: "tasks-only" }
-            };
-        }
-        if (command.name === "explain-task-engine-model") {
-            const allStatuses = ["proposed", "ready", "in_progress", "blocked", "completed", "cancelled"];
-            const lifecycle = allStatuses.map((status) => ({
-                status,
-                allowedActions: getAllowedTransitionsFrom(status).map((entry) => ({
-                    action: entry.action,
-                    targetStatus: entry.to
-                }))
-            }));
-            return {
-                ok: true,
-                code: "task-engine-model-explained",
-                message: "Task Engine model variants, planning boundary, and lifecycle transitions.",
-                data: {
-                    modelVersion: 1,
-                    variants: [
-                        {
-                            variant: "execution-task",
-                            idPattern: "^T[0-9]+$",
-                            appearsInExecutionPlanning: true,
-                            requiredFields: ["id", "title", "type", "status", "createdAt", "updatedAt"],
-                            optionalFields: [
-                                "priority",
-                                "dependsOn",
-                                "unblocks",
-                                "phase",
-                                "metadata",
-                                "ownership",
-                                "approach",
-                                "technicalScope",
-                                "acceptanceCriteria"
-                            ]
-                        },
-                        {
-                            variant: "wishlist-item",
-                            idPattern: "^W[0-9]+$",
-                            appearsInExecutionPlanning: false,
-                            requiredFields: [
-                                "id",
-                                "title",
-                                "problemStatement",
-                                "expectedOutcome",
-                                "impact",
-                                "constraints",
-                                "successSignals",
-                                "requestor",
-                                "evidenceRef",
-                                "status",
-                                "createdAt",
-                                "updatedAt"
-                            ],
-                            optionalFields: ["metadata", "convertedTaskIds", "closedAt", "closeReason"],
-                            notes: "Wishlist is ideation-only and excluded from task ready queues."
-                        }
-                    ],
-                    planningBoundary: {
-                        executionQueues: "tasks-only",
-                        wishlistScope: "separate-namespace"
-                    },
-                    executionTaskLifecycle: lifecycle
-                }
-            };
-        }
-        if (command.name === "get-task-summary") {
-            const tasks = store.getActiveTasks();
-            const suggestion = getNextActions(tasks);
-            return {
-                ok: true,
-                code: "task-summary",
-                data: {
-                    scope: "tasks-only",
-                    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,
-                    scope: "tasks-only"
-                }
-            };
-        }
-        if (command.name === "create-wishlist") {
-            const wishlistStore = await planning.openWishlist();
-            const raw = args;
-            const v = validateWishlistIntakePayload(raw);
-            if (!v.ok) {
-                return { ok: false, code: "invalid-task-schema", message: v.errors.join(" ") };
-            }
-            const ts = nowIso();
-            const item = buildWishlistItemFromIntake(raw, ts);
-            try {
-                wishlistStore.addItem(item);
-            }
-            catch (err) {
-                if (err instanceof TaskEngineError) {
-                    return { ok: false, code: err.code, message: err.message };
-                }
-                throw err;
-            }
-            await wishlistStore.save();
-            return {
-                ok: true,
-                code: "wishlist-created",
-                message: `Created wishlist '${item.id}'`,
-                data: { item }
-            };
-        }
-        if (command.name === "list-wishlist") {
-            const wishlistStore = await planning.openWishlist();
-            const statusFilter = typeof args.status === "string" ? args.status : undefined;
-            let items = wishlistStore.getAllItems();
-            if (statusFilter && ["open", "converted", "cancelled"].includes(statusFilter)) {
-                items = items.filter((i) => i.status === statusFilter);
-            }
-            return {
-                ok: true,
-                code: "wishlist-listed",
-                message: `Found ${items.length} wishlist items`,
-                data: { items, count: items.length, scope: "wishlist-only" }
-            };
-        }
-        if (command.name === "get-wishlist") {
-            const wishlistId = typeof args.wishlistId === "string" && args.wishlistId.trim().length > 0
-                ? args.wishlistId.trim()
-                : typeof args.id === "string" && args.id.trim().length > 0
-                    ? args.id.trim()
-                    : "";
-            if (!wishlistId) {
-                return { ok: false, code: "invalid-task-schema", message: "get-wishlist requires 'wishlistId' or 'id'" };
-            }
-            const wishlistStore = await planning.openWishlist();
-            const item = wishlistStore.getItem(wishlistId);
-            if (!item) {
-                return { ok: false, code: "task-not-found", message: `Wishlist item '${wishlistId}' not found` };
-            }
-            return {
-                ok: true,
-                code: "wishlist-retrieved",
-                data: { item }
-            };
-        }
-        if (command.name === "update-wishlist") {
-            const wishlistId = typeof args.wishlistId === "string" ? args.wishlistId.trim() : "";
-            const updates = typeof args.updates === "object" && args.updates !== null ? args.updates : undefined;
-            if (!wishlistId || !updates) {
-                return { ok: false, code: "invalid-task-schema", message: "update-wishlist requires wishlistId and updates" };
-            }
-            const wishlistStore = await planning.openWishlist();
-            const existing = wishlistStore.getItem(wishlistId);
-            if (!existing) {
-                return { ok: false, code: "task-not-found", message: `Wishlist item '${wishlistId}' not found` };
-            }
-            if (existing.status !== "open") {
-                return { ok: false, code: "invalid-transition", message: "Only open wishlist items can be updated" };
-            }
-            const uv = validateWishlistUpdatePayload(updates);
-            if (!uv.ok) {
-                return { ok: false, code: "invalid-task-schema", message: uv.errors.join(" ") };
-            }
-            const merged = { ...existing, updatedAt: nowIso() };
-            const mutable = [
-                "title",
-                "problemStatement",
-                "expectedOutcome",
-                "impact",
-                "constraints",
-                "successSignals",
-                "requestor",
-                "evidenceRef"
-            ];
-            for (const key of mutable) {
-                if (key in updates && typeof updates[key] === "string") {
-                    merged[key] = updates[key].trim();
-                }
-            }
-            wishlistStore.updateItem(merged);
-            await wishlistStore.save();
-            return {
-                ok: true,
-                code: "wishlist-updated",
-                message: `Updated wishlist '${wishlistId}'`,
-                data: { item: merged }
-            };
-        }
-        if (command.name === "convert-wishlist") {
-            const wishlistId = typeof args.wishlistId === "string" ? args.wishlistId.trim() : "";
-            if (!wishlistId || !WISHLIST_ID_RE.test(wishlistId)) {
-                return {
-                    ok: false,
-                    code: "invalid-task-schema",
-                    message: "convert-wishlist requires wishlistId matching W<number>"
-                };
-            }
-            const dec = parseConversionDecomposition(args.decomposition);
-            if (!dec.ok) {
-                return { ok: false, code: "invalid-task-schema", message: dec.message };
-            }
-            const tasksRaw = args.tasks;
-            if (!Array.isArray(tasksRaw) || tasksRaw.length === 0) {
-                return {
-                    ok: false,
-                    code: "invalid-task-schema",
-                    message: "convert-wishlist requires non-empty tasks array"
-                };
-            }
-            const wishlistStore = await planning.openWishlist();
-            const wlItem = wishlistStore.getItem(wishlistId);
-            if (!wlItem) {
-                return { ok: false, code: "task-not-found", message: `Wishlist item '${wishlistId}' not found` };
-            }
-            if (wlItem.status !== "open") {
-                return {
-                    ok: false,
-                    code: "invalid-transition",
-                    message: "Only open wishlist items can be converted"
-                };
-            }
-            const actor = typeof args.actor === "string"
-                ? args.actor
-                : ctx.resolvedActor !== undefined
-                    ? ctx.resolvedActor
-                    : undefined;
-            const timestamp = nowIso();
-            const built = [];
-            for (const row of tasksRaw) {
-                if (!row || typeof row !== "object" || Array.isArray(row)) {
-                    return { ok: false, code: "invalid-task-schema", message: "Each task must be an object" };
-                }
-                const bt = buildTaskFromConversionPayload(row, timestamp);
-                if (!bt.ok) {
-                    return { ok: false, code: "invalid-task-schema", message: bt.message };
-                }
-                if (store.getTask(bt.task.id)) {
-                    return {
-                        ok: false,
-                        code: "duplicate-task-id",
-                        message: `Task '${bt.task.id}' already exists`
-                    };
-                }
-                built.push(bt.task);
-            }
-            const convertedIds = built.map((t) => t.id);
-            const updatedWishlist = {
-                ...wlItem,
-                status: "converted",
-                updatedAt: timestamp,
-                convertedAt: timestamp,
-                convertedToTaskIds: convertedIds,
-                conversionDecomposition: dec.value
-            };
-            const applyConvertMutations = () => {
-                for (const t of built) {
-                    store.addTask(t);
-                    store.addMutationEvidence(mutationEvidence("create-task", t.id, actor, {
-                        initialStatus: t.status,
-                        source: "convert-wishlist",
-                        wishlistId
-                    }));
-                }
-                wishlistStore.updateItem(updatedWishlist);
-            };
-            if (planningStrictValidationEnabled({ effectiveConfig: ctx.effectiveConfig })) {
-                const strictIssue = validateTaskSetForStrictMode([...store.getAllTasks(), ...built]);
-                if (strictIssue) {
-                    return { ok: false, code: "strict-task-validation-failed", message: strictIssue };
-                }
-            }
-            if (planning.kind === "sqlite") {
-                planning.sqliteDual.withTransaction(applyConvertMutations);
-            }
-            else {
-                applyConvertMutations();
-                await store.save();
-                await wishlistStore.save();
-            }
-            return {
-                ok: true,
-                code: "wishlist-converted",
-                message: `Converted wishlist '${wishlistId}' to tasks: ${convertedIds.join(", ")}`,
-                data: { wishlist: updatedWishlist, createdTasks: built }
-            };
-        }
-        return {
-            ok: false,
-            code: "unsupported-command",
-            message: `Task Engine does not support command '${command.name}'`
-        };
-    }
-};
+export { taskEngineModule } from "./task-engine-internal.js";