@workflow-cannon/workspace-kit 0.18.0 → 0.24.0

package/dist/modules/planning/index.js

@@ -1,12 +1,26 @@
 import { PLANNING_WORKFLOW_DESCRIPTORS, PLANNING_WORKFLOW_TYPES } from "./types.js";
 import { nextPlanningQuestions, resolvePlanningConfig, resolvePlanningRulePack } from "./question-engine.js";
 import { composePlanningWishlistArtifact } from "./artifact.js";
-import { openPlanningStores } from "../task-engine/planning-open.js";
-import { buildWishlistItemFromIntake, validateWishlistIntakePayload } from "../task-engine/wishlist-validation.js";
-function nextWishlistId(items) {
+import { openPlanningStores, validateKnownTaskTypeRequirements, validateWishlistContentFields, allocateNextTaskNumericId, taskEntityFromNewIntake, clearBuildPlanSession, persistBuildPlanSession } from "../../core/planning/index.js";
+import { planningStrictValidationEnabled } from "../task-engine/planning-config.js";
+import { validateTaskSetForStrictMode } from "../task-engine/strict-task-validation.js";
+function resolveOutputMode(args) {
+    const raw = typeof args.outputMode === "string" ? args.outputMode.trim() : "";
+    if (raw === "") {
+        return { ok: true, mode: "wishlist" };
+    }
+    if (raw === "wishlist" || raw === "tasks" || raw === "response") {
+        return { ok: true, mode: raw };
+    }
+    return {
+        ok: false,
+        message: "build-plan outputMode must be one of: wishlist, tasks, response"
+    };
+}
+function nextTaskId(tasks) {
     let max = 0;
-    for (const item of items) {
-        const match = /^W(\d+)$/.exec(item.id);
+    for (const task of tasks) {
+        const match = /^T(\d+)$/.exec(task.id);
         if (!match)
             continue;
         const parsed = Number(match[1]);
@@ -14,10 +28,75 @@ function nextWishlistId(items) {
             max = Math.max(max, parsed);
         }
     }
-    return `W${max + 1}`;
+    return `T${max + 1}`;
+}
+function findMissingAnsweredQuestions(questions, answers) {
+    return questions.filter((q) => {
+        const value = answers[q.id];
+        return !(typeof value === "string" && value.trim().length > 0);
+    });
+}
+function toNormalizedText(value) {
+    return typeof value === "string" ? value.trim().toLowerCase() : "";
+}
+function buildScoringHints(args) {
+    const { planningType, answers, unresolvedCriticalCount, unresolvedAdaptiveCount } = args;
+    const signals = [
+        toNormalizedText(answers.complexity),
+        toNormalizedText(answers.riskPriority),
+        toNormalizedText(answers.timeline),
+        toNormalizedText(answers.compatibilityRisk)
+    ];
+    const hasSignal = signals.some((s) => s.length > 0) || unresolvedCriticalCount > 0 || unresolvedAdaptiveCount > 0;
+    if (!hasSignal) {
+        return null;
+    }
+    let riskScore = Math.min(100, unresolvedCriticalCount * 20 + unresolvedAdaptiveCount * 10);
+    if (signals.some((s) => s.includes("high") || s.includes("critical"))) {
+        riskScore = Math.min(100, riskScore + 20);
+    }
+    const effortScore = Math.min(100, 30 +
+        unresolvedCriticalCount * 10 +
+        unresolvedAdaptiveCount * 5 +
+        (signals.some((s) => s.includes("high")) ? 15 : 0));
+    const orderingScore = Math.min(100, 40 + unresolvedCriticalCount * 8 + (planningType === "task-ordering" ? 15 : 0) + (planningType === "sprint-phase" ? 10 : 0));
+    const classify = (score) => {
+        if (score >= 70)
+            return "high";
+        if (score >= 40)
+            return "medium";
+        return "low";
+    };
+    return {
+        schemaVersion: 1,
+        effort: { score: effortScore, level: classify(effortScore) },
+        risk: { score: riskScore, level: classify(riskScore) },
+        ordering: {
+            score: orderingScore,
+            level: classify(orderingScore),
+            recommendedStrategy: riskScore >= 70 ? "risk-first" : orderingScore >= 60 ? "dependency-first" : "balanced"
+        }
+    };
+}
+async function persistInterviewSnapshot(workspacePath, args) {
+    const cg = args.cliGuidance;
+    const completionPct = typeof cg.completionPct === "number" ? cg.completionPct : 0;
+    const answeredCritical = typeof cg.answeredCritical === "number" ? cg.answeredCritical : 0;
+    const totalCritical = typeof cg.totalCritical === "number" ? cg.totalCritical : 0;
+    const resumeCli = typeof cg.suggestedNextCommand === "string" ? cg.suggestedNextCommand : "";
+    await persistBuildPlanSession(workspacePath, {
+        planningType: args.planningType,
+        outputMode: args.outputMode,
+        status: args.status,
+        completionPct,
+        answeredCritical,
+        totalCritical,
+        answers: args.answers,
+        resumeCli
+    });
 }
 function toCliGuidance(args) {
-    const { planningType, answers, unresolvedCriticalCount, totalCriticalCount, finalize } = args;
+    const { planningType, answers, unresolvedCriticalCount, totalCriticalCount, finalize, outputMode } = args;
     const answeredCritical = Math.max(0, totalCriticalCount - unresolvedCriticalCount);
     const completionPct = totalCriticalCount > 0 ? Math.round((answeredCritical / totalCriticalCount) * 100) : 100;
     return {
@@ -27,28 +106,26 @@ function toCliGuidance(args) {
         suggestedNextCommand: `workspace-kit run build-plan '${JSON.stringify({
             planningType,
             answers,
-            finalize: finalize === true
+            finalize: finalize === true,
+            outputMode: outputMode ?? "wishlist"
         })}'`
     };
 }
 export const planningModule = {
     registration: {
         id: "planning",
-        version: "0.1.0",
+        version: "0.2.0",
         contractVersion: "1",
+        stateSchema: 1,
         capabilities: ["planning"],
         dependsOn: ["task-engine"],
+        optionalPeers: [],
         enabledByDefault: true,
         config: {
             path: "src/modules/planning/config.md",
             format: "md",
             description: "Planning module configuration contract."
         },
-        state: {
-            path: "src/modules/planning/state.md",
-            format: "md",
-            description: "Planning module runtime state contract."
-        },
         instructions: {
             directory: "src/modules/planning/instructions",
             entries: [
@@ -77,12 +154,22 @@ export const planningModule = {
                 code: "planning-types-listed",
                 message: `Found ${PLANNING_WORKFLOW_DESCRIPTORS.length} planning workflow types`,
                 data: {
+                    responseSchemaVersion: 1,
                     planningTypes: PLANNING_WORKFLOW_DESCRIPTORS
                 }
             };
         }
         if (command.name === "build-plan") {
             const args = command.args ?? {};
+            const outputModeResolved = resolveOutputMode(args);
+            if (!outputModeResolved.ok) {
+                return {
+                    ok: false,
+                    code: "invalid-planning-output-mode",
+                    message: outputModeResolved.message
+                };
+            }
+            const outputMode = outputModeResolved.mode;
             const planningType = typeof args.planningType === "string" ? args.planningType.trim() : "";
             if (!PLANNING_WORKFLOW_TYPES.includes(planningType)) {
                 return {
@@ -101,61 +188,141 @@ export const planningModule = {
             const finalize = args.finalize === true;
             const { missingCritical, adaptiveFollowups } = nextPlanningQuestions(planningType, answers, ctx.effectiveConfig);
             const config = resolvePlanningConfig(ctx.effectiveConfig);
+            const unresolvedAdaptive = findMissingAnsweredQuestions(adaptiveFollowups, answers);
+            const scoringHints = buildScoringHints({
+                planningType,
+                answers,
+                unresolvedCriticalCount: missingCritical.length,
+                unresolvedAdaptiveCount: unresolvedAdaptive.length
+            });
             if (finalize && missingCritical.length > 0) {
                 if (!config.hardBlockCriticalUnknowns) {
+                    const cliGuidance = toCliGuidance({
+                        planningType,
+                        answers,
+                        unresolvedCriticalCount: missingCritical.length,
+                        totalCriticalCount,
+                        outputMode
+                    });
+                    await persistInterviewSnapshot(ctx.workspacePath, {
+                        planningType,
+                        outputMode,
+                        status: "ready-with-warnings",
+                        answers,
+                        cliGuidance
+                    });
                     return {
                         ok: true,
                         code: "planning-ready-with-warnings",
                         message: `Finalize allowed with unresolved critical questions because planning.hardBlockCriticalUnknowns=false`,
                         data: {
+                            responseSchemaVersion: 1,
                             planningType,
+                            outputMode,
                             status: "ready-with-warnings",
                             unresolvedCritical: missingCritical,
                             nextQuestions: [...missingCritical, ...adaptiveFollowups],
+                            scoringHints,
                             capturedAnswers: answers,
-                            cliGuidance: toCliGuidance({
-                                planningType,
-                                answers,
-                                unresolvedCriticalCount: missingCritical.length,
-                                totalCriticalCount
-                            })
+                            cliGuidance
                         }
                     };
                 }
+                const cliGuidanceBlocked = toCliGuidance({
+                    planningType,
+                    answers,
+                    unresolvedCriticalCount: missingCritical.length,
+                    totalCriticalCount,
+                    finalize: true,
+                    outputMode
+                });
+                await persistInterviewSnapshot(ctx.workspacePath, {
+                    planningType,
+                    outputMode,
+                    status: "blocked-critical-unknowns",
+                    answers,
+                    cliGuidance: cliGuidanceBlocked
+                });
                 return {
                     ok: false,
                     code: "planning-critical-unknowns",
                     message: `Cannot finalize ${planningType}: unresolved critical questions (${missingCritical.map((q) => q.id).join(", ")})`,
                     data: {
+                        responseSchemaVersion: 1,
                         planningType,
+                        outputMode,
                         unresolvedCritical: missingCritical,
                         nextQuestions: [...missingCritical, ...adaptiveFollowups],
-                        cliGuidance: toCliGuidance({
-                            planningType,
-                            answers,
-                            unresolvedCriticalCount: missingCritical.length,
-                            totalCriticalCount,
-                            finalize: true
-                        })
+                        scoringHints,
+                        cliGuidance: cliGuidanceBlocked
                     }
                 };
             }
+            if (finalize && unresolvedAdaptive.length > 0 && config.adaptiveFinalizePolicy === "block") {
+                const cliGuidanceAdaptive = toCliGuidance({
+                    planningType,
+                    answers,
+                    unresolvedCriticalCount: 0,
+                    totalCriticalCount,
+                    finalize: true,
+                    outputMode
+                });
+                await persistInterviewSnapshot(ctx.workspacePath, {
+                    planningType,
+                    outputMode,
+                    status: "blocked-adaptive-unknowns",
+                    answers,
+                    cliGuidance: cliGuidanceAdaptive
+                });
+                return {
+                    ok: false,
+                    code: "planning-adaptive-unknowns",
+                    message: `Cannot finalize ${planningType}: unresolved adaptive follow-ups (${unresolvedAdaptive
+                        .map((q) => q.id)
+                        .join(", ")})`,
+                    data: {
+                        responseSchemaVersion: 1,
+                        planningType,
+                        outputMode,
+                        unresolvedAdaptive,
+                        unresolvedCritical: [],
+                        nextQuestions: unresolvedAdaptive,
+                        scoringHints,
+                        cliGuidance: cliGuidanceAdaptive
+                    }
+                };
+            }
+            const adaptiveWarnings = finalize && unresolvedAdaptive.length > 0 && config.adaptiveFinalizePolicy === "warn"
+                ? unresolvedAdaptive
+                : [];
             if (missingCritical.length > 0) {
+                const cliGuidanceQuestions = toCliGuidance({
+                    planningType,
+                    answers,
+                    unresolvedCriticalCount: missingCritical.length,
+                    totalCriticalCount,
+                    outputMode
+                });
+                await persistInterviewSnapshot(ctx.workspacePath, {
+                    planningType,
+                    outputMode,
+                    status: "needs-input",
+                    answers,
+                    cliGuidance: cliGuidanceQuestions
+                });
                 return {
                     ok: true,
                     code: "planning-questions",
                     message: `${missingCritical.length} critical planning questions require answers before finalize`,
                     data: {
+                        responseSchemaVersion: 1,
                         planningType,
+                        outputMode,
                         status: "needs-input",
                         unresolvedCritical: missingCritical,
                         nextQuestions: [...missingCritical, ...adaptiveFollowups],
-                        cliGuidance: toCliGuidance({
-                            planningType,
-                            answers,
-                            unresolvedCriticalCount: missingCritical.length,
-                            totalCriticalCount
-                        })
+                        scoringHints,
+                        cliGuidance: cliGuidanceQuestions
                     }
                 };
             }
@@ -165,18 +332,156 @@ export const planningModule = {
                 answers,
                 unresolvedCriticalQuestionIds: unresolvedIds
             });
+            if (outputMode === "response") {
+                await clearBuildPlanSession(ctx.workspacePath);
+                return {
+                    ok: true,
+                    code: "planning-response-ready",
+                    message: `Planning interview complete for ${planningType}; returning response-only artifact`,
+                    data: {
+                        responseSchemaVersion: 1,
+                        planningType,
+                        descriptor,
+                        outputMode,
+                        scaffoldVersion: 3,
+                        status: "ready-for-response",
+                        unresolvedCritical: [],
+                        adaptiveWarnings,
+                        adaptiveFollowups,
+                        scoringHints,
+                        capturedAnswers: answers,
+                        artifact,
+                        cliGuidance: toCliGuidance({
+                            planningType,
+                            answers,
+                            unresolvedCriticalCount: 0,
+                            totalCriticalCount,
+                            finalize,
+                            outputMode
+                        })
+                    }
+                };
+            }
+            if (outputMode === "tasks") {
+                const persistTasks = args.persistTasks === true;
+                const taskType = typeof args.taskType === "string" && args.taskType.trim().length > 0
+                    ? args.taskType.trim()
+                    : "task";
+                const taskPriority = typeof args.taskPriority === "string" && ["P1", "P2", "P3"].includes(args.taskPriority)
+                    ? args.taskPriority
+                    : undefined;
+                const stores = await openPlanningStores(ctx);
+                const store = stores.taskStore;
+                const plannedTaskId = nextTaskId(store.getAllTasks());
+                const planRef = `planning:${planningType}:${new Date().toISOString()}`;
+                const scopeFromArtifact = artifact.candidateFeaturesOrChanges.length > 0
+                    ? artifact.candidateFeaturesOrChanges
+                    : artifact.goals;
+                const criteriaFromSignals = typeof answers.successSignals === "string" && answers.successSignals.trim().length > 0
+                    ? [answers.successSignals.trim()]
+                    : [];
+                const task = {
+                    id: plannedTaskId,
+                    title: artifact.goals[0] && artifact.goals[0].trim().length > 0
+                        ? artifact.goals[0].trim()
+                        : `${descriptor?.title ?? planningType} task output`,
+                    type: taskType,
+                    status: "proposed",
+                    createdAt: new Date().toISOString(),
+                    updatedAt: new Date().toISOString(),
+                    priority: taskPriority,
+                    phase: typeof args.taskPhase === "string" ? args.taskPhase : undefined,
+                    approach: typeof answers.approach === "string" && answers.approach.trim().length > 0
+                        ? answers.approach
+                        : artifact.approach,
+                    technicalScope: scopeFromArtifact.length > 0 ? scopeFromArtifact : undefined,
+                    acceptanceCriteria: criteriaFromSignals.length > 0
+                        ? criteriaFromSignals
+                        : ["Task output reviewed and refined from planning artifact."],
+                    metadata: {
+                        planRef,
+                        planningProvenance: {
+                            planningType,
+                            outputMode,
+                            capturedAnswerKeys: Object.keys(artifact.sourceAnswers).sort()
+                        }
+                    }
+                };
+                const knownTypeValidationError = validateKnownTaskTypeRequirements(task);
+                if (knownTypeValidationError) {
+                    return {
+                        ok: false,
+                        code: knownTypeValidationError.code,
+                        message: knownTypeValidationError.message
+                    };
+                }
+                if (persistTasks) {
+                    if (store.getTask(task.id)) {
+                        return {
+                            ok: false,
+                            code: "duplicate-task-id",
+                            message: `Task '${task.id}' already exists`
+                        };
+                    }
+                    store.addTask(task);
+                    await store.save();
+                }
+                await clearBuildPlanSession(ctx.workspacePath);
+                return {
+                    ok: true,
+                    code: persistTasks ? "planning-task-output-created" : "planning-task-output-preview",
+                    message: persistTasks
+                        ? `Planning task output persisted as '${task.id}'`
+                        : "Planning task output prepared (preview only; set persistTasks=true to write)",
+                    data: {
+                        responseSchemaVersion: 1,
+                        planningType,
+                        descriptor,
+                        outputMode,
+                        persistTasks,
+                        scaffoldVersion: 3,
+                        status: persistTasks ? "task-output-created" : "task-output-preview",
+                        unresolvedCritical: [],
+                        adaptiveWarnings,
+                        adaptiveFollowups,
+                        scoringHints,
+                        capturedAnswers: answers,
+                        artifact,
+                        taskOutputs: [task],
+                        provenance: {
+                            planRef,
+                            outputMode,
+                            persistedTaskIds: persistTasks ? [task.id] : [],
+                            suggestedTaskIds: [task.id]
+                        },
+                        cliGuidance: toCliGuidance({
+                            planningType,
+                            answers,
+                            unresolvedCriticalCount: 0,
+                            totalCriticalCount,
+                            finalize: true,
+                            outputMode
+                        })
+                    }
+                };
+            }
             if (!finalize || !createWishlist) {
+                await clearBuildPlanSession(ctx.workspacePath);
                 return {
                     ok: true,
-                    code: "planning-ready",
-                    message: `Planning interview complete for ${planningType}; artifact ready`,
+                    code: "planning-wishlist-ready",
+                    message: `Planning interview complete for ${planningType}; wishlist artifact ready`,
                     data: {
+                        responseSchemaVersion: 1,
                         planningType,
                         descriptor,
+                        outputMode,
                         scaffoldVersion: 3,
-                        status: "ready-for-artifact",
+                        status: "ready-for-wishlist",
                         unresolvedCritical: [],
+                        adaptiveWarnings,
                         adaptiveFollowups,
+                        scoringHints,
                         capturedAnswers: answers,
                         artifact,
                         cliGuidance: toCliGuidance({
@@ -184,17 +489,15 @@ export const planningModule = {
                             answers,
                             unresolvedCriticalCount: 0,
                             totalCriticalCount,
-                            finalize: createWishlist
+                            finalize: createWishlist,
+                            outputMode
                         })
                     }
                 };
             }
             const stores = await openPlanningStores(ctx);
-            const wishlist = await stores.openWishlist();
-            const wishlistId = nextWishlistId(wishlist.getAllItems());
             const now = new Date().toISOString();
             const intake = {
-                id: wishlistId,
                 title: typeof args.title === "string" && args.title.trim().length > 0
                     ? args.title.trim()
                     : `${descriptor?.title ?? planningType} plan artifact`,
@@ -220,7 +523,7 @@ export const planningModule = {
                     ? args.evidenceRef.trim()
                     : `planning:${planningType}:${now}`
             };
-            const valid = validateWishlistIntakePayload(intake);
+            const valid = validateWishlistContentFields(intake);
             if (!valid.ok) {
                 return {
                     ok: false,
@@ -228,35 +531,64 @@ export const planningModule = {
                     message: valid.errors.join("; ")
                 };
             }
-            const item = buildWishlistItemFromIntake(intake, now);
-            item.updatedAt = now;
-            item.metadata = {
+            const taskId = allocateNextTaskNumericId(stores.taskStore.getAllTasks());
+            const task = taskEntityFromNewIntake(intake, taskId, now, {
                 planningType,
                 artifactSchemaVersion: artifact.schemaVersion,
                 artifact
-            };
-            wishlist.addItem(item);
-            await wishlist.save();
+            });
+            const typeErr = validateKnownTaskTypeRequirements(task);
+            if (typeErr) {
+                return { ok: false, code: typeErr.code, message: typeErr.message };
+            }
+            if (planningStrictValidationEnabled({ effectiveConfig: ctx.effectiveConfig })) {
+                const strictIssue = validateTaskSetForStrictMode([...stores.taskStore.getAllTasks(), task]);
+                if (strictIssue) {
+                    return { ok: false, code: "strict-task-validation-failed", message: strictIssue };
+                }
+            }
+            try {
+                if (stores.kind === "sqlite") {
+                    stores.sqliteDual.withTransaction(() => {
+                        stores.taskStore.addTask(task);
+                    });
+                }
+                else {
+                    stores.taskStore.addTask(task);
+                    await stores.taskStore.save();
+                }
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                return { ok: false, code: "invalid-planning-artifact", message: msg };
+            }
+            await clearBuildPlanSession(ctx.workspacePath);
             return {
                 ok: true,
                 code: "planning-artifact-created",
-                message: `Planning artifact created as wishlist item ${wishlistId}`,
+                message: `Planning artifact created as wishlist intake task ${taskId}`,
                 data: {
+                    responseSchemaVersion: 1,
                     planningType,
                     descriptor,
+                    outputMode,
                     scaffoldVersion: 3,
                     status: "artifact-created",
-                    wishlistId,
+                    wishlistId: taskId,
+                    taskId,
+                    adaptiveWarnings,
                     artifact,
                     unresolvedCritical: [],
                     adaptiveFollowups,
+                    scoringHints,
                     capturedAnswers: answers,
                     cliGuidance: toCliGuidance({
                         planningType,
                         answers,
                         unresolvedCriticalCount: 0,
                         totalCriticalCount,
-                        finalize: true
+                        finalize: true,
+                        outputMode
                     })
                 }
             };
@@ -278,9 +610,11 @@ export const planningModule = {
                 code: "planning-rules-explained",
                 message: `Effective planning rules for ${planningType}`,
                 data: {
+                    responseSchemaVersion: 1,
                     planningType,
                     defaultQuestionDepth: config.depth,
                     hardBlockCriticalUnknowns: config.hardBlockCriticalUnknowns,
+                    adaptiveFinalizePolicy: config.adaptiveFinalizePolicy,
                     baseQuestions: rulePack.baseQuestions,
                     adaptiveQuestions: rulePack.adaptiveQuestions
                 }

package/dist/modules/planning/question-engine.d.ts

@@ -7,6 +7,7 @@ export type PlanningQuestion = {
     critical: boolean;
 };
 export type PlanningQuestionDepth = "minimal" | "guided" | "adaptive";
+export type AdaptiveFinalizePolicy = "off" | "warn" | "block";
 export type PlanningRulePack = {
     baseQuestions: PlanningQuestion[];
     adaptiveQuestions: PlanningQuestion[];
@@ -14,6 +15,7 @@ export type PlanningRulePack = {
 export declare function resolvePlanningConfig(config: Record<string, unknown> | undefined): {
     depth: PlanningQuestionDepth;
     hardBlockCriticalUnknowns: boolean;
+    adaptiveFinalizePolicy: AdaptiveFinalizePolicy;
     rulePacks: Partial<Record<PlanningWorkflowType, PlanningRulePack>>;
 };
 export declare function resolvePlanningRulePack(planningType: PlanningWorkflowType, config: Record<string, unknown> | undefined): PlanningRulePack;

package/dist/modules/planning/question-engine.js

@@ -206,10 +206,17 @@ function parseDepth(value) {
     }
     return "adaptive";
 }
+function parseAdaptiveFinalizePolicy(value) {
+    if (value === "off" || value === "warn" || value === "block") {
+        return value;
+    }
+    return "off";
+}
 export function resolvePlanningConfig(config) {
     const planning = asRecord(config?.planning);
     const depth = parseDepth(planning?.defaultQuestionDepth);
     const hardBlockCriticalUnknowns = planning?.hardBlockCriticalUnknowns !== false;
+    const adaptiveFinalizePolicy = parseAdaptiveFinalizePolicy(planning?.adaptiveFinalizePolicy);
     const rulesRoot = asRecord(planning?.rulePacks);
     const rulePacks = {};
     if (rulesRoot) {
@@ -227,7 +234,7 @@ export function resolvePlanningConfig(config) {
             };
         }
     }
-    return { depth, hardBlockCriticalUnknowns, rulePacks };
+    return { depth, hardBlockCriticalUnknowns, adaptiveFinalizePolicy, rulePacks };
 }
 export function resolvePlanningRulePack(planningType, config) {
     const resolved = resolvePlanningConfig(config);