@workflow-cannon/workspace-kit 0.14.0 → 0.16.0

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

@@ -1,23 +1,21 @@
 import crypto from "node:crypto";
 import { maybeSpawnTranscriptHookAfterCompletion } from "../../core/transcript-completion-hook.js";
-import { TaskStore } from "./store.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 { 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";
 export { getNextActions } from "./suggestions.js";
 export { readWorkspaceStatusSnapshot } from "./dashboard-status.js";
-function taskStorePath(ctx) {
-    const tasks = ctx.effectiveConfig?.tasks;
-    if (!tasks || typeof tasks !== "object" || Array.isArray(tasks)) {
-        return undefined;
-    }
-    const p = tasks.storeRelativePath;
-    return typeof p === "string" && p.trim().length > 0 ? p.trim() : undefined;
-}
+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 MUTABLE_TASK_FIELDS = new Set([
     "title",
@@ -35,6 +33,72 @@ const MUTABLE_TASK_FIELDS = new Set([
 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)}`,
@@ -48,7 +112,7 @@ function mutationEvidence(mutationType, taskId, actor, details) {
 export const taskEngineModule = {
     registration: {
         id: "task-engine",
-        version: "0.5.0",
+        version: "0.6.0",
         contractVersion: "1",
         capabilities: ["task-engine"],
         dependsOn: [],
@@ -81,6 +145,11 @@ export const taskEngineModule = {
                     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",
@@ -126,6 +195,21 @@ export const taskEngineModule = {
                     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",
@@ -136,6 +220,11 @@ export const taskEngineModule = {
                     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",
@@ -146,6 +235,11 @@ export const taskEngineModule = {
                     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",
@@ -156,9 +250,12 @@ export const taskEngineModule = {
     },
     async onCommand(command, ctx) {
         const args = command.args ?? {};
-        const store = new TaskStore(ctx.workspacePath, taskStorePath(ctx));
+        if (command.name === "migrate-task-persistence") {
+            return runMigrateTaskPersistence(ctx, args);
+        }
+        let planning;
         try {
-            await store.load();
+            planning = await openPlanningStores(ctx);
         }
         catch (err) {
             if (err instanceof TaskEngineError) {
@@ -167,9 +264,10 @@ export const taskEngineModule = {
             return {
                 ok: false,
                 code: "storage-read-error",
-                message: `Failed to load task store: ${err.message}`
+                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;
@@ -463,6 +561,15 @@ export const taskEngineModule = {
                 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(),
@@ -470,6 +577,12 @@ export const taskEngineModule = {
                 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
@@ -507,7 +620,7 @@ export const taskEngineModule = {
                 ok: true,
                 code: "tasks-listed",
                 message: `Found ${tasks.length} tasks`,
-                data: { tasks, count: tasks.length }
+                data: { tasks, count: tasks.length, scope: "tasks-only" }
             };
         }
         if (command.name === "get-ready-queue") {
@@ -523,7 +636,7 @@ export const taskEngineModule = {
                 ok: true,
                 code: "ready-queue-retrieved",
                 message: `${ready.length} tasks in ready queue`,
-                data: { tasks: ready, count: ready.length }
+                data: { tasks: ready, count: ready.length, scope: "tasks-only" }
             };
         }
         if (command.name === "get-next-actions") {
@@ -535,7 +648,7 @@ export const taskEngineModule = {
                 message: suggestion.suggestedNext
                     ? `Suggested next: ${suggestion.suggestedNext.id} — ${suggestion.suggestedNext.title}`
                     : "No tasks in ready queue",
-                data: suggestion
+                data: { ...suggestion, scope: "tasks-only" }
             };
         }
         if (command.name === "get-task-summary") {
@@ -545,6 +658,7 @@ export const taskEngineModule = {
                 ok: true,
                 code: "task-summary",
                 data: {
+                    scope: "tasks-only",
                     stateSummary: suggestion.stateSummary,
                     readyQueueCount: suggestion.readyQueue.length,
                     suggestedNext: suggestion.suggestedNext
@@ -565,8 +679,204 @@ export const taskEngineModule = {
                 code: "blocked-summary",
                 data: {
                     blockedCount: suggestion.blockingAnalysis.length,
-                    blockedItems: suggestion.blockingAnalysis
+                    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 (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 {

package/dist/modules/task-engine/migrate-task-persistence-runtime.d.ts

@@ -0,0 +1,2 @@
+import type { ModuleCommandResult, ModuleLifecycleContext } from "../../contracts/module-contract.js";
+export declare function runMigrateTaskPersistence(ctx: ModuleLifecycleContext, args: Record<string, unknown>): Promise<ModuleCommandResult>;

package/dist/modules/task-engine/migrate-task-persistence-runtime.js

@@ -0,0 +1,192 @@
+import fs from "node:fs/promises";
+import fsSync from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { TaskEngineError } from "./transitions.js";
+import { SqliteDualPlanningStore } from "./sqlite-dual-planning.js";
+import { planningSqliteDatabaseRelativePath, planningTaskStoreRelativePath, planningWishlistStoreRelativePath } from "./planning-config.js";
+import { DEFAULT_TASK_STORE_PATH } from "./store.js";
+import { DEFAULT_WISHLIST_PATH } from "./wishlist-store.js";
+function emptyTaskDoc() {
+    return {
+        schemaVersion: 1,
+        tasks: [],
+        transitionLog: [],
+        mutationLog: [],
+        lastUpdated: new Date().toISOString()
+    };
+}
+function emptyWishDoc() {
+    return {
+        schemaVersion: 1,
+        items: [],
+        lastUpdated: new Date().toISOString()
+    };
+}
+async function atomicWriteJson(targetPath, body) {
+    const dir = path.dirname(targetPath);
+    const tmpPath = `${targetPath}.${crypto.randomUUID().slice(0, 8)}.tmp`;
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(tmpPath, body, "utf8");
+    await fs.rename(tmpPath, targetPath);
+}
+export async function runMigrateTaskPersistence(ctx, args) {
+    const direction = typeof args.direction === "string" ? args.direction.trim() : "";
+    if (direction !== "json-to-sqlite" && direction !== "sqlite-to-json") {
+        return {
+            ok: false,
+            code: "invalid-task-schema",
+            message: "migrate-task-persistence requires direction: 'json-to-sqlite' | 'sqlite-to-json'"
+        };
+    }
+    const dryRun = args.dryRun === true;
+    const force = args.force === true;
+    const taskRel = planningTaskStoreRelativePath(ctx) ?? DEFAULT_TASK_STORE_PATH;
+    const wishRel = planningWishlistStoreRelativePath(ctx) ?? DEFAULT_WISHLIST_PATH;
+    const taskPath = path.resolve(ctx.workspacePath, taskRel);
+    const wishPath = path.resolve(ctx.workspacePath, wishRel);
+    const dbRel = planningSqliteDatabaseRelativePath(ctx);
+    const dual = new SqliteDualPlanningStore(ctx.workspacePath, dbRel);
+    if (direction === "json-to-sqlite") {
+        if (fsSync.existsSync(dual.dbPath) && !force) {
+            return {
+                ok: false,
+                code: "storage-write-error",
+                message: `SQLite database already exists at ${dual.dbPath} (pass force:true to overwrite)`
+            };
+        }
+        let taskDoc = emptyTaskDoc();
+        try {
+            const raw = await fs.readFile(taskPath, "utf8");
+            const parsed = JSON.parse(raw);
+            if (parsed.schemaVersion !== 1) {
+                throw new TaskEngineError("import-parse-error", `Unsupported task schema ${parsed.schemaVersion}`);
+            }
+            if (!Array.isArray(parsed.mutationLog)) {
+                parsed.mutationLog = [];
+            }
+            taskDoc = parsed;
+        }
+        catch (err) {
+            if (err.code === "ENOENT") {
+                taskDoc = emptyTaskDoc();
+            }
+            else if (err instanceof TaskEngineError) {
+                return { ok: false, code: err.code, message: err.message };
+            }
+            else {
+                return {
+                    ok: false,
+                    code: "import-parse-error",
+                    message: `Failed to read task JSON: ${err.message}`
+                };
+            }
+        }
+        let wishDoc = emptyWishDoc();
+        try {
+            const raw = await fs.readFile(wishPath, "utf8");
+            const parsed = JSON.parse(raw);
+            if (parsed.schemaVersion !== 1) {
+                throw new TaskEngineError("import-parse-error", `Unsupported wishlist schema ${parsed.schemaVersion}`);
+            }
+            if (!Array.isArray(parsed.items)) {
+                throw new TaskEngineError("import-parse-error", "Wishlist items must be an array");
+            }
+            wishDoc = parsed;
+        }
+        catch (err) {
+            if (err.code === "ENOENT") {
+                wishDoc = emptyWishDoc();
+            }
+            else if (err instanceof TaskEngineError) {
+                return { ok: false, code: err.code, message: err.message };
+            }
+            else {
+                return {
+                    ok: false,
+                    code: "import-parse-error",
+                    message: `Failed to read wishlist JSON: ${err.message}`
+                };
+            }
+        }
+        if (dryRun) {
+            return {
+                ok: true,
+                code: "migrate-dry-run",
+                message: "Dry run: would import JSON task/wishlist documents into SQLite",
+                data: {
+                    dbPath: dual.dbPath,
+                    taskPath,
+                    wishPath,
+                    taskCount: taskDoc.tasks.length,
+                    wishlistCount: wishDoc.items.length
+                }
+            };
+        }
+        dual.seedFromDocuments(taskDoc, wishDoc);
+        try {
+            dual.persistSync();
+        }
+        catch (err) {
+            return {
+                ok: false,
+                code: "storage-write-error",
+                message: `Failed to write SQLite database: ${err.message}`
+            };
+        }
+        return {
+            ok: true,
+            code: "migrated-json-to-sqlite",
+            message: `Imported task and wishlist JSON into ${dual.dbPath}`,
+            data: { dbPath: dual.dbPath, taskPath, wishPath }
+        };
+    }
+    // sqlite-to-json
+    if (!fsSync.existsSync(dual.dbPath)) {
+        return {
+            ok: false,
+            code: "storage-read-error",
+            message: `SQLite database not found at ${dual.dbPath}`
+        };
+    }
+    dual.loadFromDisk();
+    if (!force && (fsSync.existsSync(taskPath) || fsSync.existsSync(wishPath))) {
+        return {
+            ok: false,
+            code: "storage-write-error",
+            message: `Target JSON path already exists (task or wishlist); pass force:true to overwrite`,
+            data: { taskPath, wishPath }
+        };
+    }
+    if (dryRun) {
+        return {
+            ok: true,
+            code: "migrate-dry-run",
+            message: "Dry run: would export SQLite documents to JSON files",
+            data: {
+                dbPath: dual.dbPath,
+                taskPath,
+                wishPath,
+                taskCount: dual.taskDocument.tasks.length,
+                wishlistCount: dual.wishlistDocument.items.length
+            }
+        };
+    }
+    try {
+        await atomicWriteJson(taskPath, JSON.stringify(dual.taskDocument, null, 2) + "\n");
+        await atomicWriteJson(wishPath, JSON.stringify(dual.wishlistDocument, null, 2) + "\n");
+    }
+    catch (err) {
+        return {
+            ok: false,
+            code: "storage-write-error",
+            message: `Failed to write JSON export: ${err.message}`
+        };
+    }
+    return {
+        ok: true,
+        code: "migrated-sqlite-to-json",
+        message: `Exported SQLite planning state to ${taskPath} and ${wishPath}`,
+        data: { dbPath: dual.dbPath, taskPath, wishPath }
+    };
+}

package/dist/modules/task-engine/planning-config.d.ts

@@ -0,0 +1,10 @@
+import type { ModuleLifecycleContext } from "../../contracts/module-contract.js";
+export type TaskPersistenceBackend = "json" | "sqlite";
+export declare function getTaskPersistenceBackend(config: Record<string, unknown> | undefined): TaskPersistenceBackend;
+export declare function planningTaskStoreRelativePath(ctx: {
+    effectiveConfig?: Record<string, unknown>;
+}): string | undefined;
+export declare function planningWishlistStoreRelativePath(ctx: {
+    effectiveConfig?: Record<string, unknown>;
+}): string | undefined;
+export declare function planningSqliteDatabaseRelativePath(ctx: ModuleLifecycleContext): string;