@workflow-cannon/workspace-kit 0.16.1 → 0.18.0

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

@@ -0,0 +1,277 @@
+const BASE_QUESTIONS = {
+    "task-breakdown": [
+        {
+            id: "goal",
+            prompt: "What is the primary goal of this work?",
+            examples: ["Improve release reliability", "Deliver planning module CLI flow"],
+            whyItMatters: "Clarifies what success looks like before decomposition.",
+            critical: true
+        },
+        {
+            id: "constraints",
+            prompt: "What constraints must we respect?",
+            examples: ["No breaking changes", "Single release", "CLI-first"],
+            whyItMatters: "Prevents planning paths that cannot be delivered safely.",
+            critical: true
+        },
+        {
+            id: "successSignals",
+            prompt: "How will we know the plan worked?",
+            examples: ["All gates pass", "Operators complete flow in under 5 minutes"],
+            whyItMatters: "Anchors acceptance criteria and evidence quality.",
+            critical: true
+        }
+    ],
+    "sprint-phase": [
+        {
+            id: "goal",
+            prompt: "What is the phase objective?",
+            examples: ["Ship planning module v1", "Complete stabilization hardening"],
+            whyItMatters: "Defines what this phase must deliver.",
+            critical: true
+        },
+        {
+            id: "timeline",
+            prompt: "What timeline window should this phase target?",
+            examples: ["Single release train", "Two sprint sequence"],
+            whyItMatters: "Sets ordering and scope pressure explicitly.",
+            critical: true
+        },
+        {
+            id: "criticalPath",
+            prompt: "What dependencies define the critical path?",
+            examples: ["Scaffold before adaptive engine", "Rules before artifact generation"],
+            whyItMatters: "Avoids deadlocks and unrealistic sequencing.",
+            critical: true
+        }
+    ],
+    "task-ordering": [
+        {
+            id: "goal",
+            prompt: "What outcome should ordering optimize for?",
+            examples: ["Risk reduction first", "Fastest path to demo"],
+            whyItMatters: "Provides ranking criteria for sequencing choices.",
+            critical: true
+        },
+        {
+            id: "dependencyIntent",
+            prompt: "What dependency constraints are mandatory?",
+            examples: ["T347 depends on T345", "Validation follows schema contracts"],
+            whyItMatters: "Ensures ordering respects hard blockers.",
+            critical: true
+        },
+        {
+            id: "riskPriority",
+            prompt: "Which risks should be front-loaded?",
+            examples: ["Policy approval edge cases", "Migration complexity"],
+            whyItMatters: "Improves confidence and rollback safety.",
+            critical: true
+        }
+    ],
+    "new-feature": [
+        {
+            id: "featureGoal",
+            prompt: "What user problem should the feature solve?",
+            examples: ["Guide planning interviews", "Improve dashboard visibility"],
+            whyItMatters: "Prevents building features disconnected from need.",
+            critical: true
+        },
+        {
+            id: "placement",
+            prompt: "Where should this feature be surfaced?",
+            examples: ["CLI command", "Extension dashboard panel", "Admin-only view"],
+            whyItMatters: "Drives architecture, permissions, and UX decisions.",
+            critical: true
+        },
+        {
+            id: "technology",
+            prompt: "What technology/runtime constraints apply?",
+            examples: ["TypeScript + CLI runtime", "No new native dependencies"],
+            whyItMatters: "Bounds implementation options early.",
+            critical: true
+        },
+        {
+            id: "targetAudience",
+            prompt: "Who is the target audience?",
+            examples: ["AI Agent Operators", "Developers", "Maintainers"],
+            whyItMatters: "Shapes defaults and interaction style.",
+            critical: true
+        }
+    ],
+    "change": [
+        {
+            id: "changeGoal",
+            prompt: "What behavior or system change is needed?",
+            examples: ["Replace brittle flow", "Refactor planning config handling"],
+            whyItMatters: "Separates desired outcome from implementation details.",
+            critical: true
+        },
+        {
+            id: "compatibilityRisk",
+            prompt: "What compatibility risks exist?",
+            examples: ["CLI contract changes", "state schema shifts"],
+            whyItMatters: "Supports migration-safe release planning.",
+            critical: true
+        },
+        {
+            id: "rollbackPlan",
+            prompt: "What rollback strategy is available?",
+            examples: ["Feature flag off switch", "Revert to prior command behavior"],
+            whyItMatters: "Maintains trustworthiness under failure.",
+            critical: true
+        }
+    ]
+};
+const BASE_ADAPTIVE_QUESTIONS = {
+    "task-breakdown": [
+        {
+            id: "handoffRisk",
+            prompt: "Where is handoff risk highest in this breakdown?",
+            examples: ["Schema-to-runtime boundary", "CLI-to-extension behavior"],
+            whyItMatters: "Highlights where extra tests or review checks are needed.",
+            critical: false
+        }
+    ],
+    "sprint-phase": [
+        {
+            id: "phaseExitSignal",
+            prompt: "What is the explicit exit signal for this phase?",
+            examples: ["All tasks completed and release gates pass", "PR merged with parity evidence"],
+            whyItMatters: "Prevents ambiguous “done” states.",
+            critical: false
+        }
+    ],
+    "task-ordering": [
+        {
+            id: "parallelization",
+            prompt: "Which work items can run in parallel safely?",
+            examples: ["Docs in parallel with runtime hardening", "UI after API contracts are stable"],
+            whyItMatters: "Improves throughput without violating dependencies.",
+            critical: false
+        }
+    ],
+    "new-feature": [
+        {
+            id: "decisionRationale",
+            prompt: "What major technical decision is most likely and why?",
+            examples: ["CLI-first before UI for safer rollout", "Reuse existing module config patterns"],
+            whyItMatters: "Captures rationale for later review and refinement.",
+            critical: false
+        }
+    ],
+    "change": [
+        {
+            id: "migrationNotes",
+            prompt: "What migration or rollout notes should operators receive?",
+            examples: ["No migration required", "Enable setting X before command Y"],
+            whyItMatters: "Protects compatibility and operator trust.",
+            critical: false
+        }
+    ]
+};
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function parseQuestionList(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const parsed = [];
+    for (const entry of value) {
+        const row = asRecord(entry);
+        if (!row)
+            continue;
+        const id = typeof row.id === "string" ? row.id.trim() : "";
+        const prompt = typeof row.prompt === "string" ? row.prompt.trim() : "";
+        const whyItMatters = typeof row.whyItMatters === "string" ? row.whyItMatters.trim() : "";
+        if (!id || !prompt || !whyItMatters)
+            continue;
+        parsed.push({
+            id,
+            prompt,
+            whyItMatters,
+            examples: Array.isArray(row.examples)
+                ? row.examples.filter((x) => typeof x === "string")
+                : [],
+            critical: row.critical === true
+        });
+    }
+    return parsed;
+}
+function parseDepth(value) {
+    if (value === "minimal" || value === "guided" || value === "adaptive") {
+        return value;
+    }
+    return "adaptive";
+}
+export function resolvePlanningConfig(config) {
+    const planning = asRecord(config?.planning);
+    const depth = parseDepth(planning?.defaultQuestionDepth);
+    const hardBlockCriticalUnknowns = planning?.hardBlockCriticalUnknowns !== false;
+    const rulesRoot = asRecord(planning?.rulePacks);
+    const rulePacks = {};
+    if (rulesRoot) {
+        for (const workflowType of Object.keys(BASE_QUESTIONS)) {
+            const pack = asRecord(rulesRoot[workflowType]);
+            if (!pack)
+                continue;
+            const baseQuestions = parseQuestionList(pack.baseQuestions);
+            const adaptiveQuestions = parseQuestionList(pack.adaptiveQuestions);
+            if (baseQuestions.length === 0 && adaptiveQuestions.length === 0)
+                continue;
+            rulePacks[workflowType] = {
+                baseQuestions: baseQuestions.length > 0 ? baseQuestions : BASE_QUESTIONS[workflowType],
+                adaptiveQuestions
+            };
+        }
+    }
+    return { depth, hardBlockCriticalUnknowns, rulePacks };
+}
+export function resolvePlanningRulePack(planningType, config) {
+    const resolved = resolvePlanningConfig(config);
+    const override = resolved.rulePacks[planningType];
+    return {
+        baseQuestions: override?.baseQuestions ?? BASE_QUESTIONS[planningType],
+        adaptiveQuestions: override?.adaptiveQuestions ?? BASE_ADAPTIVE_QUESTIONS[planningType]
+    };
+}
+export function nextPlanningQuestions(planningType, answers, config) {
+    const { depth } = resolvePlanningConfig(config);
+    const rules = resolvePlanningRulePack(planningType, config);
+    const base = rules.baseQuestions;
+    const missingCritical = base.filter((q) => {
+        const value = answers[q.id];
+        return !(typeof value === "string" && value.trim().length > 0);
+    });
+    if (depth === "minimal") {
+        return { missingCritical, adaptiveFollowups: [] };
+    }
+    const adaptiveFollowups = [...rules.adaptiveQuestions];
+    if (depth === "guided") {
+        return { missingCritical, adaptiveFollowups };
+    }
+    const complexity = typeof answers.complexity === "string" ? answers.complexity.toLowerCase() : "";
+    if (complexity === "high") {
+        adaptiveFollowups.push({
+            id: "mitigationPlan",
+            prompt: "What mitigation strategy addresses high complexity risks?",
+            examples: ["Ship in slices", "Add parity checks before release"],
+            whyItMatters: "Reduces probability of destabilizing execution.",
+            critical: false
+        });
+    }
+    if (planningType === "new-feature" && !answers["decisionRationale"]) {
+        if (!adaptiveFollowups.some((q) => q.id === "decisionRationale")) {
+            adaptiveFollowups.push({
+                id: "decisionRationale",
+                prompt: "What major technical decision is most likely and why?",
+                examples: ["CLI-first before UI for safer rollout", "Reuse existing module config patterns"],
+                whyItMatters: "Captures rationale for later review and refinement.",
+                critical: false
+            });
+        }
+    }
+    return { missingCritical, adaptiveFollowups };
+}

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

@@ -0,0 +1,9 @@
+export declare const PLANNING_WORKFLOW_TYPES: readonly ["task-breakdown", "sprint-phase", "task-ordering", "new-feature", "change"];
+export type PlanningWorkflowType = (typeof PLANNING_WORKFLOW_TYPES)[number];
+export type PlanningWorkflowDescriptor = {
+    type: PlanningWorkflowType;
+    title: string;
+    description: string;
+    outcomeFocus: string;
+};
+export declare const PLANNING_WORKFLOW_DESCRIPTORS: PlanningWorkflowDescriptor[];

package/dist/modules/planning/types.js

@@ -0,0 +1,39 @@
+export const PLANNING_WORKFLOW_TYPES = [
+    "task-breakdown",
+    "sprint-phase",
+    "task-ordering",
+    "new-feature",
+    "change"
+];
+export const PLANNING_WORKFLOW_DESCRIPTORS = [
+    {
+        type: "task-breakdown",
+        title: "Task Breakdown",
+        description: "Break work into coherent, reviewable slices with explicit acceptance criteria.",
+        outcomeFocus: "Clear decomposition into actionable units."
+    },
+    {
+        type: "sprint-phase",
+        title: "Sprint / Phase Plan",
+        description: "Define phase goals, sequencing, and completion checkpoints.",
+        outcomeFocus: "Time-ordered delivery framing with clear phase boundaries."
+    },
+    {
+        type: "task-ordering",
+        title: "Task Ordering",
+        description: "Prioritize and sequence tasks with dependency awareness.",
+        outcomeFocus: "Deterministic ordering with explicit dependency intent."
+    },
+    {
+        type: "new-feature",
+        title: "New Feature",
+        description: "Guide discovery for new feature goals, architecture choices, and rollout fit.",
+        outcomeFocus: "High-confidence feature direction and constraints."
+    },
+    {
+        type: "change",
+        title: "Change / Refactor",
+        description: "Assess behavior-impacting changes and migration/compatibility risks.",
+        outcomeFocus: "Safe, justified change plan with risk controls."
+    }
+];