@workflow-cannon/workspace-kit 0.16.1 → 0.18.0

package/dist/core/config-metadata.js

@@ -56,6 +56,59 @@ const REGISTRY = {
         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"]
+    },
+    "planning.defaultQuestionDepth": {
+        key: "planning.defaultQuestionDepth",
+        type: "string",
+        description: "Planning interview depth mode: minimal (critical only), guided (critical + static follow-ups), or adaptive (context-driven follow-ups).",
+        default: "adaptive",
+        allowedValues: ["minimal", "guided", "adaptive"],
+        domainScope: "project",
+        owningModule: "planning",
+        sensitive: false,
+        requiresRestart: false,
+        requiresApproval: false,
+        exposure: "maintainer",
+        writableLayers: ["project", "user"]
+    },
+    "planning.hardBlockCriticalUnknowns": {
+        key: "planning.hardBlockCriticalUnknowns",
+        type: "boolean",
+        description: "When true, planning finalize requests fail until critical unknown questions are answered.",
+        default: true,
+        domainScope: "project",
+        owningModule: "planning",
+        sensitive: false,
+        requiresRestart: false,
+        requiresApproval: false,
+        exposure: "maintainer",
+        writableLayers: ["project", "user"]
+    },
+    "planning.rulePacks": {
+        key: "planning.rulePacks",
+        type: "object",
+        description: "Optional object overrides for planning rule packs by workflow type (`baseQuestions` and `adaptiveQuestions`).",
+        default: {},
+        domainScope: "project",
+        owningModule: "planning",
+        sensitive: false,
+        requiresRestart: false,
+        requiresApproval: false,
+        exposure: "maintainer",
+        writableLayers: ["project", "user"]
+    },
     "policy.extraSensitiveModuleCommands": {
         key: "policy.extraSensitiveModuleCommands",
         type: "array",

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: {
@@ -45,7 +46,11 @@ export const KIT_CONFIG_DEFAULTS = {
  */
 export const MODULE_CONFIG_CONTRIBUTIONS = {
     approvals: {},
-    planning: {}
+    planning: {
+        defaultQuestionDepth: "adaptive",
+        hardBlockCriticalUnknowns: true,
+        rulePacks: {}
+    }
 };
 export function deepMerge(target, source) {
     const out = { ...target };

package/dist/modules/planning/artifact.d.ts

@@ -0,0 +1,19 @@
+import type { PlanningWorkflowType } from "./types.js";
+export type PlanningWishlistArtifact = {
+    schemaVersion: 1;
+    planningType: PlanningWorkflowType;
+    generatedAt: string;
+    goals: string[];
+    approach: string;
+    majorTechnicalDecisions: string[];
+    candidateFeaturesOrChanges: string[];
+    assumptions: string[];
+    openQuestions: string[];
+    risksAndConstraints: string[];
+    sourceAnswers: Record<string, string>;
+};
+export declare function composePlanningWishlistArtifact(args: {
+    planningType: PlanningWorkflowType;
+    answers: Record<string, unknown>;
+    unresolvedCriticalQuestionIds: string[];
+}): PlanningWishlistArtifact;

package/dist/modules/planning/artifact.js

@@ -0,0 +1,72 @@
+function answer(answers, key, fallback) {
+    const value = answers[key];
+    if (typeof value !== "string" || value.trim().length === 0) {
+        return fallback;
+    }
+    return value.trim();
+}
+function list(answers, key) {
+    const value = answers[key];
+    if (Array.isArray(value)) {
+        return value.filter((x) => typeof x === "string" && x.trim().length > 0).map((x) => x.trim());
+    }
+    if (typeof value === "string" && value.trim().length > 0) {
+        return [value.trim()];
+    }
+    return [];
+}
+export function composePlanningWishlistArtifact(args) {
+    const { planningType, answers, unresolvedCriticalQuestionIds } = args;
+    const sourceAnswers = {};
+    for (const [key, value] of Object.entries(answers)) {
+        if (typeof value === "string" && value.trim().length > 0) {
+            sourceAnswers[key] = value.trim();
+        }
+    }
+    const goals = list(answers, "goals");
+    if (goals.length === 0) {
+        const inferredGoal = answer(answers, "goal", "") ||
+            answer(answers, "featureGoal", "") ||
+            answer(answers, "changeGoal", "");
+        if (inferredGoal)
+            goals.push(inferredGoal);
+    }
+    const candidate = list(answers, "candidateFeaturesOrChanges");
+    if (candidate.length === 0) {
+        const inferred = answer(answers, "scope", "");
+        if (inferred)
+            candidate.push(inferred);
+    }
+    const majorTechnicalDecisions = list(answers, "majorTechnicalDecisions");
+    const decisionRationale = answer(answers, "decisionRationale", "");
+    if (decisionRationale && majorTechnicalDecisions.length === 0) {
+        majorTechnicalDecisions.push(decisionRationale);
+    }
+    const assumptions = list(answers, "assumptions");
+    const openQuestions = [
+        ...list(answers, "openQuestions"),
+        ...unresolvedCriticalQuestionIds.map((id) => `Unresolved critical question: ${id}`)
+    ];
+    const risksAndConstraints = list(answers, "risksAndConstraints");
+    const constraints = answer(answers, "constraints", "");
+    if (constraints) {
+        risksAndConstraints.push(`Constraint: ${constraints}`);
+    }
+    const riskPriority = answer(answers, "riskPriority", "");
+    if (riskPriority) {
+        risksAndConstraints.push(`Risk priority: ${riskPriority}`);
+    }
+    return {
+        schemaVersion: 1,
+        planningType,
+        generatedAt: new Date().toISOString(),
+        goals,
+        approach: answer(answers, "approach", "Context-driven workflow guided by planning rules."),
+        majorTechnicalDecisions,
+        candidateFeaturesOrChanges: candidate,
+        assumptions,
+        openQuestions,
+        risksAndConstraints,
+        sourceAnswers
+    };
+}

package/dist/modules/planning/index.js

@@ -1,3 +1,36 @@
+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) {
+    let max = 0;
+    for (const item of items) {
+        const match = /^W(\d+)$/.exec(item.id);
+        if (!match)
+            continue;
+        const parsed = Number(match[1]);
+        if (Number.isFinite(parsed)) {
+            max = Math.max(max, parsed);
+        }
+    }
+    return `W${max + 1}`;
+}
+function toCliGuidance(args) {
+    const { planningType, answers, unresolvedCriticalCount, totalCriticalCount, finalize } = args;
+    const answeredCritical = Math.max(0, totalCriticalCount - unresolvedCriticalCount);
+    const completionPct = totalCriticalCount > 0 ? Math.round((answeredCritical / totalCriticalCount) * 100) : 100;
+    return {
+        answeredCritical,
+        totalCritical: totalCriticalCount,
+        completionPct,
+        suggestedNextCommand: `workspace-kit run build-plan '${JSON.stringify({
+            planningType,
+            answers,
+            finalize: finalize === true
+        })}'`
+    };
+}
 export const planningModule = {
     registration: {
         id: "planning",
@@ -23,8 +56,240 @@ export const planningModule = {
                     name: "build-plan",
                     file: "build-plan.md",
                     description: "Generate a dependency-aware execution plan."
+                },
+                {
+                    name: "list-planning-types",
+                    file: "list-planning-types.md",
+                    description: "List supported planning workflow types and their intent."
+                },
+                {
+                    name: "explain-planning-rules",
+                    file: "explain-planning-rules.md",
+                    description: "Explain effective planning defaults and rule packs for a workflow type."
                 }
             ]
         }
+    },
+    async onCommand(command, ctx) {
+        if (command.name === "list-planning-types") {
+            return {
+                ok: true,
+                code: "planning-types-listed",
+                message: `Found ${PLANNING_WORKFLOW_DESCRIPTORS.length} planning workflow types`,
+                data: {
+                    planningTypes: PLANNING_WORKFLOW_DESCRIPTORS
+                }
+            };
+        }
+        if (command.name === "build-plan") {
+            const args = command.args ?? {};
+            const planningType = typeof args.planningType === "string" ? args.planningType.trim() : "";
+            if (!PLANNING_WORKFLOW_TYPES.includes(planningType)) {
+                return {
+                    ok: false,
+                    code: "invalid-planning-type",
+                    message: "build-plan requires planningType of: task-breakdown, sprint-phase, task-ordering, new-feature, change"
+                };
+            }
+            const descriptor = PLANNING_WORKFLOW_DESCRIPTORS.find((x) => x.type === planningType);
+            const resolvedRulePack = resolvePlanningRulePack(planningType, ctx.effectiveConfig);
+            const totalCriticalCount = resolvedRulePack.baseQuestions.length;
+            const answers = typeof args.answers === "object" && args.answers !== null && !Array.isArray(args.answers)
+                ? args.answers
+                : {};
+            const createWishlist = args.createWishlist !== false;
+            const finalize = args.finalize === true;
+            const { missingCritical, adaptiveFollowups } = nextPlanningQuestions(planningType, answers, ctx.effectiveConfig);
+            const config = resolvePlanningConfig(ctx.effectiveConfig);
+            if (finalize && missingCritical.length > 0) {
+                if (!config.hardBlockCriticalUnknowns) {
+                    return {
+                        ok: true,
+                        code: "planning-ready-with-warnings",
+                        message: `Finalize allowed with unresolved critical questions because planning.hardBlockCriticalUnknowns=false`,
+                        data: {
+                            planningType,
+                            status: "ready-with-warnings",
+                            unresolvedCritical: missingCritical,
+                            nextQuestions: [...missingCritical, ...adaptiveFollowups],
+                            capturedAnswers: answers,
+                            cliGuidance: toCliGuidance({
+                                planningType,
+                                answers,
+                                unresolvedCriticalCount: missingCritical.length,
+                                totalCriticalCount
+                            })
+                        }
+                    };
+                }
+                return {
+                    ok: false,
+                    code: "planning-critical-unknowns",
+                    message: `Cannot finalize ${planningType}: unresolved critical questions (${missingCritical.map((q) => q.id).join(", ")})`,
+                    data: {
+                        planningType,
+                        unresolvedCritical: missingCritical,
+                        nextQuestions: [...missingCritical, ...adaptiveFollowups],
+                        cliGuidance: toCliGuidance({
+                            planningType,
+                            answers,
+                            unresolvedCriticalCount: missingCritical.length,
+                            totalCriticalCount,
+                            finalize: true
+                        })
+                    }
+                };
+            }
+            if (missingCritical.length > 0) {
+                return {
+                    ok: true,
+                    code: "planning-questions",
+                    message: `${missingCritical.length} critical planning questions require answers before finalize`,
+                    data: {
+                        planningType,
+                        status: "needs-input",
+                        unresolvedCritical: missingCritical,
+                        nextQuestions: [...missingCritical, ...adaptiveFollowups],
+                        cliGuidance: toCliGuidance({
+                            planningType,
+                            answers,
+                            unresolvedCriticalCount: missingCritical.length,
+                            totalCriticalCount
+                        })
+                    }
+                };
+            }
+            const unresolvedIds = missingCritical.map((q) => q.id);
+            const artifact = composePlanningWishlistArtifact({
+                planningType: planningType,
+                answers,
+                unresolvedCriticalQuestionIds: unresolvedIds
+            });
+            if (!finalize || !createWishlist) {
+                return {
+                    ok: true,
+                    code: "planning-ready",
+                    message: `Planning interview complete for ${planningType}; artifact ready`,
+                    data: {
+                        planningType,
+                        descriptor,
+                        scaffoldVersion: 3,
+                        status: "ready-for-artifact",
+                        unresolvedCritical: [],
+                        adaptiveFollowups,
+                        capturedAnswers: answers,
+                        artifact,
+                        cliGuidance: toCliGuidance({
+                            planningType,
+                            answers,
+                            unresolvedCriticalCount: 0,
+                            totalCriticalCount,
+                            finalize: createWishlist
+                        })
+                    }
+                };
+            }
+            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`,
+                problemStatement: typeof answers.problemStatement === "string"
+                    ? answers.problemStatement
+                    : typeof answers.featureGoal === "string"
+                        ? answers.featureGoal
+                        : "Planning artifact generated from guided workflow.",
+                expectedOutcome: typeof answers.expectedOutcome === "string"
+                    ? answers.expectedOutcome
+                    : "Clear, reviewable planning artifact for execution decomposition.",
+                impact: typeof answers.impact === "string" ? answers.impact : "Improved planning quality and delivery confidence.",
+                constraints: typeof answers.constraints === "string"
+                    ? answers.constraints
+                    : artifact.risksAndConstraints.join("; ") || "None explicitly provided.",
+                successSignals: typeof answers.successSignals === "string"
+                    ? answers.successSignals
+                    : "Critical questions answered and artifact accepted by operators.",
+                requestor: typeof args.requestor === "string" && args.requestor.trim().length > 0
+                    ? args.requestor.trim()
+                    : ctx.resolvedActor ?? "planning-module",
+                evidenceRef: typeof args.evidenceRef === "string" && args.evidenceRef.trim().length > 0
+                    ? args.evidenceRef.trim()
+                    : `planning:${planningType}:${now}`
+            };
+            const valid = validateWishlistIntakePayload(intake);
+            if (!valid.ok) {
+                return {
+                    ok: false,
+                    code: "invalid-planning-artifact",
+                    message: valid.errors.join("; ")
+                };
+            }
+            const item = buildWishlistItemFromIntake(intake, now);
+            item.updatedAt = now;
+            item.metadata = {
+                planningType,
+                artifactSchemaVersion: artifact.schemaVersion,
+                artifact
+            };
+            wishlist.addItem(item);
+            await wishlist.save();
+            return {
+                ok: true,
+                code: "planning-artifact-created",
+                message: `Planning artifact created as wishlist item ${wishlistId}`,
+                data: {
+                    planningType,
+                    descriptor,
+                    scaffoldVersion: 3,
+                    status: "artifact-created",
+                    wishlistId,
+                    artifact,
+                    unresolvedCritical: [],
+                    adaptiveFollowups,
+                    capturedAnswers: answers,
+                    cliGuidance: toCliGuidance({
+                        planningType,
+                        answers,
+                        unresolvedCriticalCount: 0,
+                        totalCriticalCount,
+                        finalize: true
+                    })
+                }
+            };
+        }
+        if (command.name === "explain-planning-rules") {
+            const args = command.args ?? {};
+            const planningType = typeof args.planningType === "string" ? args.planningType.trim() : "";
+            if (!PLANNING_WORKFLOW_TYPES.includes(planningType)) {
+                return {
+                    ok: false,
+                    code: "invalid-planning-type",
+                    message: "explain-planning-rules requires planningType of: task-breakdown, sprint-phase, task-ordering, new-feature, change"
+                };
+            }
+            const config = resolvePlanningConfig(ctx.effectiveConfig);
+            const rulePack = resolvePlanningRulePack(planningType, ctx.effectiveConfig);
+            return {
+                ok: true,
+                code: "planning-rules-explained",
+                message: `Effective planning rules for ${planningType}`,
+                data: {
+                    planningType,
+                    defaultQuestionDepth: config.depth,
+                    hardBlockCriticalUnknowns: config.hardBlockCriticalUnknowns,
+                    baseQuestions: rulePack.baseQuestions,
+                    adaptiveQuestions: rulePack.adaptiveQuestions
+                }
+            };
+        }
+        return {
+            ok: false,
+            code: "unsupported-command",
+            message: `Planning module does not support command '${command.name}'`
+        };
     }
 };

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

@@ -0,0 +1,23 @@
+import { type PlanningWorkflowType } from "./types.js";
+export type PlanningQuestion = {
+    id: string;
+    prompt: string;
+    examples: string[];
+    whyItMatters: string;
+    critical: boolean;
+};
+export type PlanningQuestionDepth = "minimal" | "guided" | "adaptive";
+export type PlanningRulePack = {
+    baseQuestions: PlanningQuestion[];
+    adaptiveQuestions: PlanningQuestion[];
+};
+export declare function resolvePlanningConfig(config: Record<string, unknown> | undefined): {
+    depth: PlanningQuestionDepth;
+    hardBlockCriticalUnknowns: boolean;
+    rulePacks: Partial<Record<PlanningWorkflowType, PlanningRulePack>>;
+};
+export declare function resolvePlanningRulePack(planningType: PlanningWorkflowType, config: Record<string, unknown> | undefined): PlanningRulePack;
+export declare function nextPlanningQuestions(planningType: PlanningWorkflowType, answers: Record<string, unknown>, config?: Record<string, unknown>): {
+    missingCritical: PlanningQuestion[];
+    adaptiveFollowups: PlanningQuestion[];
+};