@workflow-cannon/workspace-kit 0.16.0 → 0.17.0

package/dist/cli/doctor-planning-issues.d.ts

@@ -0,0 +1,6 @@
+export type DoctorPlanningIssue = {
+    path: string;
+    reason: string;
+};
+/** Resolve layered config and run SQLite planning persistence checks for `workspace-kit doctor`. */
+export declare function collectDoctorPlanningPersistenceIssues(cwd: string): Promise<DoctorPlanningIssue[]>;

package/dist/cli/doctor-planning-issues.js

@@ -0,0 +1,37 @@
+import { ModuleRegistry } from "../core/module-registry.js";
+import { resolveWorkspaceConfigWithLayers } from "../core/workspace-kit-config.js";
+import { validatePlanningPersistenceForDoctor } from "../modules/task-engine/doctor-planning-persistence.js";
+import { documentationModule } from "../modules/documentation/index.js";
+import { taskEngineModule } from "../modules/task-engine/index.js";
+import { approvalsModule } from "../modules/approvals/index.js";
+import { planningModule } from "../modules/planning/index.js";
+import { improvementModule } from "../modules/improvement/index.js";
+import { workspaceConfigModule } from "../modules/workspace-config/index.js";
+const defaultRegistryModules = [
+    workspaceConfigModule,
+    documentationModule,
+    taskEngineModule,
+    approvalsModule,
+    planningModule,
+    improvementModule
+];
+/** Resolve layered config and run SQLite planning persistence checks for `workspace-kit doctor`. */
+export async function collectDoctorPlanningPersistenceIssues(cwd) {
+    try {
+        const registry = new ModuleRegistry(defaultRegistryModules);
+        const { effective } = await resolveWorkspaceConfigWithLayers({
+            workspacePath: cwd,
+            registry,
+            invocationConfig: {}
+        });
+        return validatePlanningPersistenceForDoctor(cwd, effective);
+    }
+    catch (err) {
+        return [
+            {
+                path: "workspace-config",
+                reason: `config-resolution-failed: ${err.message}`
+            }
+        ];
+    }
+}

package/dist/cli.js

@@ -5,6 +5,7 @@ import { pathToFileURL } from "node:url";
 import { AGENT_CLI_MAP_HUMAN_DOC, appendPolicyTrace, parsePolicyApprovalFromEnv, resolveActorWithFallback } from "./core/policy.js";
 import { runWorkspaceConfigCli } from "./core/config-cli.js";
 import { handleRunCommand } from "./cli/run-command.js";
+import { collectDoctorPlanningPersistenceIssues } from "./cli/doctor-planning-issues.js";
 const EXIT_SUCCESS = 0;
 const EXIT_VALIDATION_FAILURE = 1;
 const EXIT_USAGE_ERROR = 2;
@@ -606,6 +607,7 @@ export async function runCli(args, options = {}) {
             });
         }
     }
+    issues.push(...(await collectDoctorPlanningPersistenceIssues(cwd)));
     if (issues.length > 0) {
         writeError("workspace-kit doctor failed validation.");
         for (const issue of issues) {
@@ -615,6 +617,7 @@ export async function runCli(args, options = {}) {
     }
     writeLine("workspace-kit doctor passed.");
     writeLine("All canonical workspace-kit contract files are present and parseable JSON.");
+    writeLine("Effective workspace config resolved; task planning persistence checks passed (including SQLite when configured).");
     writeLine(`Next: workspace-kit run — list module commands; see ${AGENT_CLI_MAP_HUMAN_DOC} for tier/policy copy-paste.`);
     return EXIT_SUCCESS;
 }

package/dist/core/config-metadata.js

@@ -16,6 +16,59 @@ const REGISTRY = {
         exposure: "public",
         writableLayers: ["project", "user"]
     },
+    "tasks.wishlistStoreRelativePath": {
+        key: "tasks.wishlistStoreRelativePath",
+        type: "string",
+        description: "Relative path (from workspace root) to the Wishlist JSON store when persistenceBackend is json.",
+        default: ".workspace-kit/wishlist/state.json",
+        domainScope: "project",
+        owningModule: "task-engine",
+        sensitive: false,
+        requiresRestart: false,
+        requiresApproval: false,
+        exposure: "public",
+        writableLayers: ["project", "user"]
+    },
+    "tasks.persistenceBackend": {
+        key: "tasks.persistenceBackend",
+        type: "string",
+        description: "Task + wishlist persistence: json (default) or sqlite.",
+        default: "json",
+        allowedValues: ["json", "sqlite"],
+        domainScope: "project",
+        owningModule: "task-engine",
+        sensitive: false,
+        requiresRestart: false,
+        requiresApproval: false,
+        exposure: "public",
+        writableLayers: ["project", "user"]
+    },
+    "tasks.sqliteDatabaseRelativePath": {
+        key: "tasks.sqliteDatabaseRelativePath",
+        type: "string",
+        description: "Relative path (from workspace root) to the SQLite file when persistenceBackend is sqlite.",
+        default: ".workspace-kit/tasks/workspace-kit.db",
+        domainScope: "project",
+        owningModule: "task-engine",
+        sensitive: false,
+        requiresRestart: false,
+        requiresApproval: false,
+        exposure: "public",
+        writableLayers: ["project", "user"]
+    },
+    "tasks.strictValidation": {
+        key: "tasks.strictValidation",
+        type: "boolean",
+        description: "When true, task mutations validate the full active task set before persistence and fail on invalid task records.",
+        default: false,
+        domainScope: "project",
+        owningModule: "task-engine",
+        sensitive: false,
+        requiresRestart: false,
+        requiresApproval: false,
+        exposure: "public",
+        writableLayers: ["project", "user"]
+    },
     "policy.extraSensitiveModuleCommands": {
         key: "policy.extraSensitiveModuleCommands",
         type: "array",
@@ -315,10 +368,25 @@ export function validatePersistedConfigDocument(data, label) {
         }
         const t = tasks;
         for (const k of Object.keys(t)) {
-            if (k !== "storeRelativePath") {
+            if (k !== "storeRelativePath" &&
+                k !== "wishlistStoreRelativePath" &&
+                k !== "persistenceBackend" &&
+                k !== "sqliteDatabaseRelativePath") {
                 throw new Error(`config-invalid(${label}): unknown tasks.${k}`);
             }
         }
+        if (t.storeRelativePath !== undefined) {
+            validateValueForMetadata(REGISTRY["tasks.storeRelativePath"], t.storeRelativePath);
+        }
+        if (t.wishlistStoreRelativePath !== undefined) {
+            validateValueForMetadata(REGISTRY["tasks.wishlistStoreRelativePath"], t.wishlistStoreRelativePath);
+        }
+        if (t.persistenceBackend !== undefined) {
+            validateValueForMetadata(REGISTRY["tasks.persistenceBackend"], t.persistenceBackend);
+        }
+        if (t.sqliteDatabaseRelativePath !== undefined) {
+            validateValueForMetadata(REGISTRY["tasks.sqliteDatabaseRelativePath"], t.sqliteDatabaseRelativePath);
+        }
     }
     const policy = data.policy;
     if (policy !== undefined) {

package/dist/core/workspace-kit-config.js

@@ -11,7 +11,8 @@ export function getProjectConfigPath(workspacePath) {
 export const KIT_CONFIG_DEFAULTS = {
     core: {},
     tasks: {
-        storeRelativePath: ".workspace-kit/tasks/state.json"
+        storeRelativePath: ".workspace-kit/tasks/state.json",
+        strictValidation: false
     },
     documentation: {},
     responseTemplates: {

package/dist/modules/task-engine/doctor-planning-persistence.d.ts

@@ -0,0 +1,9 @@
+export type DoctorPlanningIssue = {
+    path: string;
+    reason: string;
+};
+/**
+ * When effective config selects SQLite for task/wishlist persistence, verify the DB file exists
+ * and can be opened read-only; if a planning row is present, validate embedded JSON schemaVersion.
+ */
+export declare function validatePlanningPersistenceForDoctor(workspacePath: string, effectiveConfig: Record<string, unknown>): DoctorPlanningIssue[];

package/dist/modules/task-engine/doctor-planning-persistence.js

@@ -0,0 +1,77 @@
+import fs from "node:fs";
+import path from "node:path";
+import Database from "better-sqlite3";
+import { getTaskPersistenceBackend, planningSqliteDatabaseRelativePath } from "./planning-config.js";
+/**
+ * When effective config selects SQLite for task/wishlist persistence, verify the DB file exists
+ * and can be opened read-only; if a planning row is present, validate embedded JSON schemaVersion.
+ */
+export function validatePlanningPersistenceForDoctor(workspacePath, effectiveConfig) {
+    const issues = [];
+    if (getTaskPersistenceBackend(effectiveConfig) !== "sqlite") {
+        return issues;
+    }
+    const ctx = { workspacePath, effectiveConfig };
+    const dbRel = planningSqliteDatabaseRelativePath(ctx);
+    const dbAbs = path.resolve(workspacePath, dbRel);
+    const relDisplay = path.relative(workspacePath, dbAbs) || dbAbs;
+    if (!fs.existsSync(dbAbs)) {
+        issues.push({
+            path: relDisplay,
+            reason: "sqlite-planning-db-missing (tasks.persistenceBackend is sqlite; run migrate-task-persistence json-to-sqlite or fix tasks.sqliteDatabaseRelativePath)"
+        });
+        return issues;
+    }
+    let db;
+    try {
+        db = new Database(dbAbs, { readonly: true });
+    }
+    catch (err) {
+        issues.push({
+            path: relDisplay,
+            reason: `sqlite-open-failed: ${err.message}`
+        });
+        return issues;
+    }
+    try {
+        const row = db
+            .prepare("SELECT task_store_json, wishlist_store_json FROM workspace_planning_state WHERE id = 1")
+            .get();
+        if (row) {
+            try {
+                const taskDoc = JSON.parse(row.task_store_json);
+                if (taskDoc.schemaVersion !== 1) {
+                    issues.push({
+                        path: relDisplay,
+                        reason: `sqlite-task_store_json: unsupported schemaVersion (expected 1, got ${taskDoc.schemaVersion})`
+                    });
+                }
+            }
+            catch {
+                issues.push({ path: relDisplay, reason: "sqlite-task_store_json: invalid JSON" });
+            }
+            try {
+                const wishDoc = JSON.parse(row.wishlist_store_json);
+                if (wishDoc.schemaVersion !== 1) {
+                    issues.push({
+                        path: relDisplay,
+                        reason: `sqlite-wishlist_store_json: unsupported schemaVersion (expected 1, got ${wishDoc.schemaVersion})`
+                    });
+                }
+            }
+            catch {
+                issues.push({ path: relDisplay, reason: "sqlite-wishlist_store_json: invalid JSON" });
+            }
+        }
+    }
+    catch (err) {
+        issues.push({
+            path: relDisplay,
+            reason: `sqlite-schema-invalid: ${err.message}`
+        });
+    }
+    finally {
+        db.close();
+    }
+    return issues;
+}

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

@@ -6,6 +6,9 @@ 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";
@@ -17,6 +20,7 @@ export { validateWishlistIntakePayload, validateWishlistUpdatePayload, buildWish
 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",
@@ -30,6 +34,70 @@ const MUTABLE_TASK_FIELDS = new Set([
     "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();
 }
@@ -244,6 +312,11 @@ export const taskEngineModule = {
                     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."
                 }
             ]
         }
@@ -323,6 +396,7 @@ export const taskEngineModule = {
             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,
@@ -330,9 +404,7 @@ export const taskEngineModule = {
                     message: "create-task requires id/title, id format T<number>, and status of proposed or ready"
                 };
             }
-            if (store.getTask(id)) {
-                return { ok: false, code: "duplicate-task-id", message: `Task '${id}' already exists` };
-            }
+            const evidenceType = command.name === "create-task-from-plan" ? "create-task-from-plan" : "create-task";
             const timestamp = nowIso();
             const task = {
                 id,
@@ -351,7 +423,6 @@ export const taskEngineModule = {
                 technicalScope: Array.isArray(args.technicalScope) ? args.technicalScope.filter((x) => typeof x === "string") : undefined,
                 acceptanceCriteria: Array.isArray(args.acceptanceCriteria) ? args.acceptanceCriteria.filter((x) => typeof x === "string") : undefined
             };
-            store.addTask(task);
             if (command.name === "create-task-from-plan") {
                 const planRef = typeof args.planRef === "string" && args.planRef.trim().length > 0 ? args.planRef.trim() : undefined;
                 if (!planRef) {
@@ -362,13 +433,63 @@ export const taskEngineModule = {
                     };
                 }
                 task.metadata = { ...(task.metadata ?? {}), planRef };
-                store.updateTask(task);
             }
-            const evidenceType = command.name === "create-task-from-plan" ? "create-task-from-plan" : "create-task";
+            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
+                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,
@@ -388,6 +509,7 @@ export const taskEngineModule = {
             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` };
@@ -401,8 +523,43 @@ export const taskEngineModule = {
                 };
             }
             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) }));
+            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 } };
         }
@@ -424,6 +581,10 @@ export const taskEngineModule = {
             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 } };
         }
@@ -500,6 +661,10 @@ export const taskEngineModule = {
             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,
@@ -608,6 +773,17 @@ export const taskEngineModule = {
         if (command.name === "list-tasks") {
             const statusFilter = typeof args.status === "string" ? args.status : undefined;
             const phaseFilter = typeof args.phase === "string" ? args.phase : undefined;
+            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) {
@@ -616,6 +792,25 @@ export const taskEngineModule = {
             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",
@@ -651,6 +846,69 @@ export const taskEngineModule = {
                 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);
@@ -864,6 +1122,12 @@ export const taskEngineModule = {
                 }
                 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);
             }

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

@@ -8,3 +8,6 @@ export declare function planningWishlistStoreRelativePath(ctx: {
     effectiveConfig?: Record<string, unknown>;
 }): string | undefined;
 export declare function planningSqliteDatabaseRelativePath(ctx: ModuleLifecycleContext): string;
+export declare function planningStrictValidationEnabled(ctx: {
+    effectiveConfig?: Record<string, unknown>;
+}): boolean;

package/dist/modules/task-engine/planning-config.js

@@ -35,3 +35,10 @@ export function planningSqliteDatabaseRelativePath(ctx) {
         ? p.trim()
         : ".workspace-kit/tasks/workspace-kit.db";
 }
+export function planningStrictValidationEnabled(ctx) {
+    const tasks = ctx.effectiveConfig?.tasks;
+    if (!tasks || typeof tasks !== "object" || Array.isArray(tasks)) {
+        return false;
+    }
+    return tasks.strictValidation === true;
+}

package/dist/modules/task-engine/strict-task-validation.d.ts

@@ -0,0 +1,3 @@
+import type { TaskEntity } from "./types.js";
+export declare function validateTaskEntityForStrictMode(task: TaskEntity): string | null;
+export declare function validateTaskSetForStrictMode(tasks: TaskEntity[]): string | null;