@workflow-cannon/workspace-kit 0.15.0 → 0.16.0

package/README.md

@@ -1,136 +1,85 @@
 AI agents: `./.ai/` is the authoritative source of truth; read all files there before any analysis, planning, or code changes, and follow `./.ai/` over `README.md`, `./docs/`, and conflicting existing code patterns.
 
-# Workflow Cannon
-
-Workflow Cannon is the canonical home of `@workflow-cannon/workspace-kit` and the operational docs that drive its evolution.
-
-It is built for developers using VS Code who want safe, reproducible, package-first workflow automation with clear release evidence.
-
-## Table of Contents
-
-- [What This Repository Is](#what-this-repository-is)
-- [Big-Picture Vision](#big-picture-vision)
-- [Current Status](#current-status)
-- [Goals](#goals)
-- [Package](#package)
-- [Repository Map](#repository-map)
-- [Documentation Index](#documentation-index)
-- [License](#license)
-
-## What This Repository Is
+<div align="center">
+  <img src="title_image.png" alt="Workflow Cannon" width="720" />
+</div>
 
-Workflow Cannon is the source of truth for:
-
-- The `@workflow-cannon/workspace-kit` package
-- Maintainer planning and execution artifacts
-- Consumer validation and release-readiness evidence
-
-Guiding characteristics:
+# Workflow Cannon
 
-- Package-first delivery and verification
-- Deterministic, auditable workflows
-- Safe-by-default operations (validation, traceability, rollback-friendly changes)
+**[`@workflow-cannon/workspace-kit`](https://www.npmjs.com/package/@workflow-cannon/workspace-kit)** — CLI, task engine, and workflow contracts for repos that want deterministic, policy-governed automation with clear evidence.
 
-## Big-Picture Vision
+## Quick start (clone this repo)
 
-Workflow Cannon is evolving from a package and docs repository into a developer workflow platform that can:
+**Needs:** Node.js **22+** (see CI), **pnpm 10** (see `packageManager` in `package.json`).
 
-- model planning, tasks, policy, and execution as first-class, versioned contracts
-- run repeatable workflows with deterministic outcomes and evidence capture
-- continuously improve itself based on observed friction and outcome data
+```bash
+git clone https://github.com/NJLaPrell/workflow-cannon.git
+cd workflow-cannon
+pnpm install
+pnpm run build
+```
 
-The long-term direction in this repository is to close the loop between:
+Verify the kit sees your workspace:
 
-1. **What happened** (transcripts, diffs, run artifacts, diagnostics)
-2. **What should change** (recommendations to templates, rules, process, and config)
-3. **What gets adopted** (human-reviewed approvals, policy checks, safe rollout)
+```bash
+node dist/cli.js doctor
+node dist/cli.js --help
+```
 
-### Enhancement Engine (automatic learning and correction)
+Try **read-only** task-engine queries:
 
-The Improvement/Enhancement Engine is intended to detect weak spots in workflows and rules, then generate high-signal fixes with supporting evidence. Instead of hard-coding static process forever, the system should learn from real usage patterns and propose better defaults.
+```bash
+node dist/cli.js run list-tasks '{}'
+node dist/cli.js run get-next-actions '{}'
+```
 
-In practice, this means:
+**Developing:** after edits, `pnpm run build` then `pnpm test` (or `pnpm run phase5-gates` before larger changes). If `workspace-kit` is not on your `PATH`, use `node dist/cli.js …` from the repo root (same as above).
 
-- detect recurring failure patterns, manual rework, and template drift
-- emit recommendation items with confidence, deduping, and provenance
-- route recommendations through an approval queue (`accept`, `decline`, `accept edited`)
-- apply approved changes through guarded automation (dry-run, diff, rollback-ready)
-- measure post-change outcomes so future recommendations improve over time
+## Quick start (use the package in another project)
 
-This keeps automation adaptive without sacrificing safety, governance, or developer trust.
+```bash
+npm install @workflow-cannon/workspace-kit
+npx workspace-kit --help
+```
 
-## Current Status
+Or with pnpm: `pnpm add @workflow-cannon/workspace-kit` then `pnpm exec workspace-kit --help`.
 
-**Release and phase truth:** see `docs/maintainers/ROADMAP.md` and `docs/maintainers/data/workspace-kit-status.yaml`. **Task queue:** `.workspace-kit/tasks/state.json` (ids and `status` are authoritative for execution).
+## What this repo contains
 
-- **Phases 0–7** are complete through **`v0.9.0`** (see roadmap for slice ids).
-- **Phase 8** ships maintainer/onboarding hardening (`v0.10.0`): policy denial clarity, runbooks, and doc alignment for CLI vs `run` approval.
-- **Phase 9–10** ship agent/onboarding parity (`v0.11.0`): interactive policy opt-in, strict response-template mode, Agent CLI map (`docs/maintainers/AGENT-CLI-MAP.md`), and CLI-first Cursor guidance.
-- **Phase 11** ships architectural review follow-up hardening (`v0.12.0`): policy/session denial edge tests, persistence concurrency semantics, release doc-sweep checklist, and runtime path audit note.
-- **Phase 12** ships Cursor-native thin-client extension delivery (`v0.13.0`): dashboard/tasks/config UI flows, extension test suite, and operator/security docs.
-- **Phase 13** is the active queue: Task Engine lifecycle tightening (`T311+`).
+| Area | What |
+| --- | --- |
+| **CLI** | `workspace-kit` — `doctor`, `config`, `run <module-command>` (see `workspace-kit run` with no args for the list). |
+| **Task engine** | Canonical queue in `.workspace-kit/tasks/state.json`; lifecycle via `run-transition`. Wishlist ideation uses ids `W###` (see [`docs/maintainers/runbooks/wishlist-workflow.md`](docs/maintainers/runbooks/wishlist-workflow.md)). |
+| **Docs** | Maintainer process, roadmap, and changelog under `docs/maintainers/`. |
+| **Cursor extension** (optional) | Thin UI in `extensions/cursor-workflow-cannon/` — build with `pnpm run ui:prepare`. |
 
-Historical note: this file’s milestone list is not the live queue—always check task state for **`ready`** work.
+There is **no** built-in IDE slash command like `/qt` from this package; editor integrations are **your** config (e.g. `.cursor/commands/`), while **`workspace-kit`** is the supported CLI.
 
-## Goals
+## Policy and approvals (read this before mutating state)
 
-- Keep package implementation and release operations centralized here.
-- Preserve independent consumer validation and update cadence.
-- Grow modular capabilities for planning, tasking, configuration, policy, and improvement.
-- Build a human-governed enhancement loop that learns from usage and recommends better workflows/rules.
-- Maintain deterministic and auditable behavior as system complexity increases.
+Sensitive `workspace-kit run` commands require JSON **`policyApproval`** in the third CLI argument. Chat approval is not enough. Env-based approval applies to `init` / `upgrade` / `config`, not the `run` path.
 
-## Package
+- **Human guide:** [`docs/maintainers/POLICY-APPROVAL.md`](docs/maintainers/POLICY-APPROVAL.md)
+- **Copy-paste table:** [`docs/maintainers/AGENT-CLI-MAP.md`](docs/maintainers/AGENT-CLI-MAP.md)
 
-Install:
+## Project status and roadmap
 
-```bash
-npm install @workflow-cannon/workspace-kit
-```
+Release cadence, phase history, and strategic decisions: [`docs/maintainers/ROADMAP.md`](docs/maintainers/ROADMAP.md). **Live execution queue:** `.workspace-kit/tasks/state.json` (`status` and `id` are authoritative — not this README’s milestone bullets).
 
-### How to run the CLI (this repo and consumers)
+Snapshot: [`docs/maintainers/data/workspace-kit-status.yaml`](docs/maintainers/data/workspace-kit-status.yaml).
 
-There is **no** IDE slash command like `/qt` defined by this package unless your own editor config adds one. Supported entrypoints:
+## Where to go next
 
-| Context | Command |
+| Goal | Start here |
 | --- | --- |
-| **Installed package** | `npx @workflow-cannon/workspace-kit --help` or `pnpm exec workspace-kit --help` when the package is a dependency |
-| **Developing this repo** | `pnpm run build` then `node dist/cli.js --help` or `pnpm exec workspace-kit --help` if linked |
-| **Transcript helpers** | `pnpm run transcript:sync` / `pnpm run transcript:ingest` (see maintainer runbooks) |
-
-Mutating commands require policy approval: **`docs/maintainers/POLICY-APPROVAL.md`** (JSON **`policyApproval`** for `workspace-kit run`, env for `config`/`init`/`upgrade`).
-
-## Repository Map
-
-- `README.md` - project entry point
-- `.ai/PRINCIPLES.md` - project goals and decision principles (canonical AI)
-- `docs/maintainers/ROADMAP.md` - roadmap and decision log
-- `.workspace-kit/tasks/state.json` - execution tracking
-- `docs/maintainers/ARCHITECTURE.md` - architecture direction
-- `docs/maintainers/DECISIONS.md` - focused design/decision notes
-- `docs/maintainers/RELEASING.md` - release checklist and validation expectations
-- `.ai/module-build.md` - canonical AI module build guidance
-- `docs/maintainers/` - maintainer process and boundary docs
-- `docs/maintainers/module-build-guide.md` - human-readable module build guidance
-- `docs/adr/` - ADR templates and records
-
-## Documentation Index
-
-- Project goals and decision principles: `.ai/PRINCIPLES.md`
-- Strategy and long-range direction: `docs/maintainers/ROADMAP.md`
-- Active execution tasks: `.workspace-kit/tasks/state.json`
-- Glossary and agent-guidance terms: `docs/maintainers/TERMS.md`
-- Architecture direction: `docs/maintainers/ARCHITECTURE.md`
-- Project decisions: `docs/maintainers/DECISIONS.md`
-- Governance policy surface: `docs/maintainers/GOVERNANCE.md`
-- Release process and gates: `docs/maintainers/RELEASING.md`
-- Policy / approval surfaces: `docs/maintainers/POLICY-APPROVAL.md`
-- Canonical changelog: `docs/maintainers/CHANGELOG.md` (`CHANGELOG.md` at repo root is pointer-only)
-- Canonical AI module build guidance: `.ai/module-build.md`
-- Human module build guide: `docs/maintainers/module-build-guide.md`
-- Security, support, and governance: `docs/maintainers/SECURITY.md`, `docs/maintainers/SUPPORT.md`, `docs/maintainers/GOVERNANCE.md`
-- AI behavior rules and command wrappers: `.cursor/rules/`, `.cursor/commands/`
+| Goals, trade-offs, gates | [`.ai/PRINCIPLES.md`](.ai/PRINCIPLES.md) |
+| Roadmap & versions | [`docs/maintainers/ROADMAP.md`](docs/maintainers/ROADMAP.md) |
+| Changelog | [`docs/maintainers/CHANGELOG.md`](docs/maintainers/CHANGELOG.md) |
+| Release process | [`docs/maintainers/RELEASING.md`](docs/maintainers/RELEASING.md) |
+| Glossary | [`docs/maintainers/TERMS.md`](docs/maintainers/TERMS.md) |
+| Architecture | [`docs/maintainers/ARCHITECTURE.md`](docs/maintainers/ARCHITECTURE.md) |
+| Agent/CLI execution | [`docs/maintainers/AGENTS.md`](docs/maintainers/AGENTS.md) |
 
 ## License
 
-Licensed under MIT. See `LICENSE`.
+MIT. See [`LICENSE`](LICENSE).

package/dist/modules/approvals/review-runtime.js

@@ -1,15 +1,7 @@
 import { appendLineageEvent } from "../../core/lineage-store.js";
-import { TaskStore } from "../task-engine/store.js";
+import { openPlanningStores } from "../task-engine/planning-open.js";
 import { TransitionService } from "../task-engine/service.js";
 import { appendDecisionRecord, computeDecisionFingerprint, readDecisionFingerprints } from "./decisions-store.js";
-function taskStoreRelativePath(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;
-}
 function getEvidenceKey(task) {
     const m = task.metadata;
     const k = m && typeof m.evidenceKey === "string" ? m.evidenceKey : "";
@@ -24,8 +16,8 @@ export async function runReviewItem(ctx, args, actor) {
     if (decision === "accept_edited" && !(typeof args.editedSummary === "string" && args.editedSummary.trim())) {
         return { ok: false, code: "invalid-args", message: "accept_edited requires non-empty editedSummary" };
     }
-    const store = new TaskStore(ctx.workspacePath, taskStoreRelativePath(ctx));
-    await store.load();
+    const planning = await openPlanningStores(ctx);
+    const store = planning.taskStore;
     const task = store.getTask(taskId);
     if (!task) {
         return { ok: false, code: "task-not-found", message: `Task '${taskId}' not found` };

package/dist/modules/improvement/generate-recommendations-runtime.js

@@ -1,17 +1,9 @@
 import { randomUUID } from "node:crypto";
-import { TaskStore } from "../task-engine/store.js";
+import { openPlanningStores } from "../task-engine/planning-open.js";
 import { appendLineageEvent } from "../../core/lineage-store.js";
 import { loadImprovementState, saveImprovementState } from "./improvement-state.js";
 import { ingestAgentTranscripts, ingestConfigMutations, ingestGitDiffBetweenTags, ingestPolicyDenials, ingestTaskTransitionFriction, taskIdForEvidenceKey } from "./ingest.js";
 import { priorityForTier } from "./confidence.js";
-function taskStoreRelativePath(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;
-}
 function hasEvidenceKey(tasks, key) {
     return tasks.some((t) => {
         const m = t.metadata;
@@ -48,8 +40,8 @@ export function getMaxRecommendationCandidatesPerRun(ctx) {
 }
 export async function runGenerateRecommendations(ctx, args) {
     const runId = randomUUID();
-    const store = new TaskStore(ctx.workspacePath, taskStoreRelativePath(ctx));
-    await store.load();
+    const planning = await openPlanningStores(ctx);
+    const store = planning.taskStore;
     const state = await loadImprovementState(ctx.workspacePath);
     const transcriptsRoot = resolveTranscriptArchivePath(ctx, args);
     const fromTag = typeof args.fromTag === "string" ? args.fromTag.trim() : undefined;

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

@@ -8,4 +8,6 @@ export { readWorkspaceStatusSnapshot } from "./dashboard-status.js";
 export { WishlistStore } from "./wishlist-store.js";
 export type { WishlistItem, WishlistStatus, WishlistStoreDocument } from "./wishlist-types.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";
 export declare const taskEngineModule: WorkflowModule;

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

@@ -1,11 +1,11 @@
 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 { WishlistStore } from "./wishlist-store.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";
@@ -14,22 +14,8 @@ export { getNextActions } from "./suggestions.js";
 export { readWorkspaceStatusSnapshot } from "./dashboard-status.js";
 export { WishlistStore } from "./wishlist-store.js";
 export { validateWishlistIntakePayload, validateWishlistUpdatePayload, buildWishlistItemFromIntake, WISHLIST_ID_RE } from "./wishlist-validation.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;
-}
-function wishlistStorePath(ctx) {
-    const tasks = ctx.effectiveConfig?.tasks;
-    if (!tasks || typeof tasks !== "object" || Array.isArray(tasks)) {
-        return undefined;
-    }
-    const p = tasks.wishlistStoreRelativePath;
-    return typeof p === "string" && p.trim().length > 0 ? p.trim() : undefined;
-}
+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",
@@ -126,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: [],
@@ -249,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",
@@ -259,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) {
@@ -270,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;
@@ -566,14 +561,14 @@ export const taskEngineModule = {
                 phase: t.phase ?? null
             }));
             const blockedTop = suggestion.blockingAnalysis.slice(0, 15);
-            const wishlistStore = new WishlistStore(ctx.workspacePath, wishlistStorePath(ctx));
+            let wishlistItems = [];
             try {
-                await wishlistStore.load();
+                const wishlistStore = await planning.openWishlist();
+                wishlistItems = wishlistStore.getAllItems();
             }
             catch {
                 /* wishlist store optional */
             }
-            const wishlistItems = wishlistStore.getAllItems();
             const wishlistOpenCount = wishlistItems.filter((i) => i.status === "open").length;
             const data = {
                 schemaVersion: 1,
@@ -690,8 +685,7 @@ export const taskEngineModule = {
             };
         }
         if (command.name === "create-wishlist") {
-            const wishlistStore = new WishlistStore(ctx.workspacePath, wishlistStorePath(ctx));
-            await wishlistStore.load();
+            const wishlistStore = await planning.openWishlist();
             const raw = args;
             const v = validateWishlistIntakePayload(raw);
             if (!v.ok) {
@@ -717,8 +711,7 @@ export const taskEngineModule = {
             };
         }
         if (command.name === "list-wishlist") {
-            const wishlistStore = new WishlistStore(ctx.workspacePath, wishlistStorePath(ctx));
-            await wishlistStore.load();
+            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)) {
@@ -740,8 +733,7 @@ export const taskEngineModule = {
             if (!wishlistId) {
                 return { ok: false, code: "invalid-task-schema", message: "get-wishlist requires 'wishlistId' or 'id'" };
             }
-            const wishlistStore = new WishlistStore(ctx.workspacePath, wishlistStorePath(ctx));
-            await wishlistStore.load();
+            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` };
@@ -758,8 +750,7 @@ export const taskEngineModule = {
             if (!wishlistId || !updates) {
                 return { ok: false, code: "invalid-task-schema", message: "update-wishlist requires wishlistId and updates" };
             }
-            const wishlistStore = new WishlistStore(ctx.workspacePath, wishlistStorePath(ctx));
-            await wishlistStore.load();
+            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` };
@@ -817,8 +808,7 @@ export const taskEngineModule = {
                     message: "convert-wishlist requires non-empty tasks array"
                 };
             }
-            const wishlistStore = new WishlistStore(ctx.workspacePath, wishlistStorePath(ctx));
-            await wishlistStore.load();
+            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` };
@@ -854,14 +844,6 @@ export const taskEngineModule = {
                 }
                 built.push(bt.task);
             }
-            for (const t of built) {
-                store.addTask(t);
-                store.addMutationEvidence(mutationEvidence("create-task", t.id, actor, {
-                    initialStatus: t.status,
-                    source: "convert-wishlist",
-                    wishlistId
-                }));
-            }
             const convertedIds = built.map((t) => t.id);
             const updatedWishlist = {
                 ...wlItem,
@@ -871,9 +853,25 @@ export const taskEngineModule = {
                 convertedToTaskIds: convertedIds,
                 conversionDecomposition: dec.value
             };
-            wishlistStore.updateItem(updatedWishlist);
-            await store.save();
-            await wishlistStore.save();
+            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",

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 }
+    };
+}