@workflow-cannon/workspace-kit 0.17.0 → 0.24.0

package/dist/modules/improvement/improvement-state.js

@@ -1,7 +1,10 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { UnifiedStateDb } from "../../core/state/unified-state-db.js";
+import { getTaskPersistenceBackend, planningSqliteDatabaseRelativePath } from "../task-engine/planning-config.js";
 export const IMPROVEMENT_STATE_SCHEMA_VERSION = 2;
 const DEFAULT_REL = ".workspace-kit/improvement/state.json";
+const IMPROVEMENT_MODULE_STATE_ID = "improvement";
 function statePath(workspacePath) {
     return path.join(workspacePath, DEFAULT_REL);
 }
@@ -31,43 +34,69 @@ function migrateFromV1(raw) {
         lastIngestRunAt: typeof raw.lastIngestRunAt === "string" ? raw.lastIngestRunAt : null
     };
 }
-export async function loadImprovementState(workspacePath) {
+function normalizeLoadedDoc(raw) {
+    const ver = raw.schemaVersion;
+    if (ver === 1) {
+        return migrateFromV1(raw);
+    }
+    if (ver !== IMPROVEMENT_STATE_SCHEMA_VERSION) {
+        return emptyImprovementState();
+    }
+    const doc = raw;
+    return {
+        ...emptyImprovementState(),
+        ...doc,
+        transcriptLineCursors: doc.transcriptLineCursors ?? {},
+        transcriptRetryQueue: Array.isArray(doc.transcriptRetryQueue)
+            ? doc.transcriptRetryQueue.filter((e) => e !== null &&
+                typeof e === "object" &&
+                typeof e.relativePath === "string")
+            : []
+    };
+}
+async function loadImprovementStateFromFile(workspacePath) {
     const fp = statePath(workspacePath);
     try {
         const rawText = await fs.readFile(fp, "utf8");
         const raw = JSON.parse(rawText);
-        const ver = raw.schemaVersion;
-        if (ver === 1) {
-            return migrateFromV1(raw);
-        }
-        if (ver !== IMPROVEMENT_STATE_SCHEMA_VERSION) {
-            return emptyImprovementState();
-        }
-        const doc = raw;
-        return {
-            ...emptyImprovementState(),
-            ...doc,
-            transcriptLineCursors: doc.transcriptLineCursors ?? {},
-            transcriptRetryQueue: Array.isArray(doc.transcriptRetryQueue)
-                ? doc.transcriptRetryQueue.filter((e) => e !== null &&
-                    typeof e === "object" &&
-                    typeof e.relativePath === "string")
-                : []
-        };
+        return normalizeLoadedDoc(raw);
     }
     catch (e) {
         if (e.code === "ENOENT") {
-            return emptyImprovementState();
+            return null;
         }
         throw e;
     }
 }
-export async function saveImprovementState(workspacePath, doc) {
-    const fp = statePath(workspacePath);
-    await fs.mkdir(path.dirname(fp), { recursive: true });
+export async function loadImprovementState(workspacePath, effectiveConfig) {
+    if (getTaskPersistenceBackend(effectiveConfig) === "sqlite") {
+        const ctx = { workspacePath, effectiveConfig };
+        const unified = new UnifiedStateDb(workspacePath, planningSqliteDatabaseRelativePath(ctx));
+        const row = unified.getModuleState(IMPROVEMENT_MODULE_STATE_ID);
+        if (row?.state) {
+            return normalizeLoadedDoc(row.state);
+        }
+        const fromFile = await loadImprovementStateFromFile(workspacePath);
+        if (fromFile) {
+            return fromFile;
+        }
+        return emptyImprovementState();
+    }
+    const fromFile = await loadImprovementStateFromFile(workspacePath);
+    return fromFile ?? emptyImprovementState();
+}
+export async function saveImprovementState(workspacePath, doc, effectiveConfig) {
     const out = {
         ...doc,
         schemaVersion: IMPROVEMENT_STATE_SCHEMA_VERSION
     };
+    if (getTaskPersistenceBackend(effectiveConfig) === "sqlite") {
+        const ctx = { workspacePath, effectiveConfig };
+        const unified = new UnifiedStateDb(workspacePath, planningSqliteDatabaseRelativePath(ctx));
+        unified.setModuleState(IMPROVEMENT_MODULE_STATE_ID, out.schemaVersion, out);
+        return;
+    }
+    const fp = statePath(workspacePath);
+    await fs.mkdir(path.dirname(fp), { recursive: true });
     await fs.writeFile(fp, `${JSON.stringify(out, null, 2)}\n`, "utf8");
 }

package/dist/modules/improvement/index.js

@@ -8,19 +8,16 @@ export const improvementModule = {
         id: "improvement",
         version: "0.8.0",
         contractVersion: "1",
+        stateSchema: 1,
         capabilities: ["improvement"],
         dependsOn: ["task-engine", "planning"],
+        optionalPeers: ["documentation"],
         enabledByDefault: true,
         config: {
             path: "src/modules/improvement/config.md",
             format: "md",
             description: "Improvement module configuration contract."
         },
-        state: {
-            path: "src/modules/improvement/state.md",
-            format: "md",
-            description: "Improvement module recommendation state contract."
-        },
         instructions: {
             directory: "src/modules/improvement/instructions",
             entries: [
@@ -54,153 +51,158 @@ export const improvementModule = {
     },
     async onCommand(command, ctx) {
         const args = command.args ?? {};
-        if (command.name === "generate-recommendations") {
-            const transcriptsRoot = typeof args.transcriptsRoot === "string" ? args.transcriptsRoot : undefined;
-            const fromTag = typeof args.fromTag === "string" ? args.fromTag : undefined;
-            const toTag = typeof args.toTag === "string" ? args.toTag : undefined;
-            const syncArgs = {
-                sourcePath: typeof args.sourcePath === "string" ? args.sourcePath : undefined,
-                archivePath: transcriptsRoot
-            };
-            try {
-                const state = await loadImprovementState(ctx.workspacePath);
-                const sync = await runSyncTranscripts(ctx, syncArgs, state);
-                state.lastSyncRunAt = new Date().toISOString();
-                await saveImprovementState(ctx.workspacePath, state);
-                const result = await runGenerateRecommendations(ctx, {
-                    transcriptsRoot: sync.archivePath,
-                    fromTag,
-                    toTag
-                });
-                return {
-                    ok: true,
-                    code: "recommendations-generated",
-                    message: `After sync (${sync.copied} copied): created ${result.created.length} improvement task(s); skipped ${result.skipped} duplicate(s)`,
-                    data: { sync, ...result }
-                };
-            }
-            catch (e) {
-                const msg = e instanceof Error ? e.message : String(e);
-                return { ok: false, code: "generate-failed", message: msg };
-            }
-        }
-        if (command.name === "sync-transcripts") {
-            const syncArgs = {
-                sourcePath: typeof args.sourcePath === "string" ? args.sourcePath : undefined,
-                archivePath: typeof args.archivePath === "string" ? args.archivePath : undefined
-            };
-            try {
-                const state = await loadImprovementState(ctx.workspacePath);
-                const sync = await runSyncTranscripts(ctx, syncArgs, state);
-                state.lastSyncRunAt = new Date().toISOString();
-                await saveImprovementState(ctx.workspacePath, state);
-                return {
-                    ok: true,
-                    code: "transcripts-synced",
-                    message: `Copied ${sync.copied} transcript file(s); skipped ${sync.skippedExisting} existing`,
-                    data: sync
+        const handlers = {
+            "generate-recommendations": async () => {
+                const transcriptsRoot = typeof args.transcriptsRoot === "string" ? args.transcriptsRoot : undefined;
+                const fromTag = typeof args.fromTag === "string" ? args.fromTag : undefined;
+                const toTag = typeof args.toTag === "string" ? args.toTag : undefined;
+                const syncArgs = {
+                    sourcePath: typeof args.sourcePath === "string" ? args.sourcePath : undefined,
+                    archivePath: transcriptsRoot
                 };
-            }
-            catch (e) {
-                const msg = e instanceof Error ? e.message : String(e);
-                return { ok: false, code: "sync-failed", message: msg };
-            }
-        }
-        if (command.name === "ingest-transcripts") {
-            const syncArgs = {
-                sourcePath: typeof args.sourcePath === "string" ? args.sourcePath : undefined,
-                archivePath: typeof args.archivePath === "string" ? args.archivePath : undefined
-            };
-            const now = new Date();
-            try {
-                const state = await loadImprovementState(ctx.workspacePath);
-                const sync = await runSyncTranscripts(ctx, syncArgs, state);
-                const cfg = resolveImprovementTranscriptConfig(ctx, syncArgs);
-                const cadenceDecision = resolveCadenceDecision(now, state.lastIngestRunAt, cfg.minIntervalMinutes, sync.copied, cfg.skipIfNoNewTranscripts);
-                state.lastSyncRunAt = now.toISOString();
-                const generate = cadenceDecision.shouldRunGenerate || args.forceGenerate === true || args.runGenerate === true;
-                let recommendations = null;
-                if (generate) {
-                    recommendations = await runGenerateRecommendations(ctx, {
-                        transcriptsRoot: sync.archivePath
+                try {
+                    const state = await loadImprovementState(ctx.workspacePath, ctx.effectiveConfig);
+                    const sync = await runSyncTranscripts(ctx, syncArgs, state);
+                    state.lastSyncRunAt = new Date().toISOString();
+                    await saveImprovementState(ctx.workspacePath, state, ctx.effectiveConfig);
+                    const result = await runGenerateRecommendations(ctx, {
+                        transcriptsRoot: sync.archivePath,
+                        fromTag,
+                        toTag
                     });
-                    state.lastIngestRunAt = now.toISOString();
+                    return {
+                        ok: true,
+                        code: "recommendations-generated",
+                        message: `After sync (${sync.copied} copied): created ${result.created.length} improvement task(s); skipped ${result.skipped} duplicate(s)`,
+                        data: { sync, ...result }
+                    };
+                }
+                catch (e) {
+                    const msg = e instanceof Error ? e.message : String(e);
+                    return { ok: false, code: "generate-failed", message: msg };
                 }
-                await saveImprovementState(ctx.workspacePath, state);
-                const status = generate ? "generated" : "skipped";
+            },
+            "sync-transcripts": async () => {
+                const syncArgs = {
+                    sourcePath: typeof args.sourcePath === "string" ? args.sourcePath : undefined,
+                    archivePath: typeof args.archivePath === "string" ? args.archivePath : undefined
+                };
+                try {
+                    const state = await loadImprovementState(ctx.workspacePath, ctx.effectiveConfig);
+                    const sync = await runSyncTranscripts(ctx, syncArgs, state);
+                    state.lastSyncRunAt = new Date().toISOString();
+                    await saveImprovementState(ctx.workspacePath, state, ctx.effectiveConfig);
+                    return {
+                        ok: true,
+                        code: "transcripts-synced",
+                        message: `Copied ${sync.copied} transcript file(s); skipped ${sync.skippedExisting} existing`,
+                        data: sync
+                    };
+                }
+                catch (e) {
+                    const msg = e instanceof Error ? e.message : String(e);
+                    return { ok: false, code: "sync-failed", message: msg };
+                }
+            },
+            "ingest-transcripts": async () => {
+                const syncArgs = {
+                    sourcePath: typeof args.sourcePath === "string" ? args.sourcePath : undefined,
+                    archivePath: typeof args.archivePath === "string" ? args.archivePath : undefined
+                };
+                const now = new Date();
+                try {
+                    const state = await loadImprovementState(ctx.workspacePath, ctx.effectiveConfig);
+                    const sync = await runSyncTranscripts(ctx, syncArgs, state);
+                    const cfg = resolveImprovementTranscriptConfig(ctx, syncArgs);
+                    const cadenceDecision = resolveCadenceDecision(now, state.lastIngestRunAt, cfg.minIntervalMinutes, sync.copied, cfg.skipIfNoNewTranscripts);
+                    state.lastSyncRunAt = now.toISOString();
+                    const generate = cadenceDecision.shouldRunGenerate || args.forceGenerate === true || args.runGenerate === true;
+                    let recommendations = null;
+                    if (generate) {
+                        recommendations = await runGenerateRecommendations(ctx, {
+                            transcriptsRoot: sync.archivePath
+                        });
+                        state.lastIngestRunAt = now.toISOString();
+                    }
+                    await saveImprovementState(ctx.workspacePath, state, ctx.effectiveConfig);
+                    const status = generate ? "generated" : "skipped";
+                    return {
+                        ok: true,
+                        code: "transcripts-ingested",
+                        message: `Ingest ${status}; sync copied ${sync.copied} file(s)`,
+                        data: {
+                            sync,
+                            cadence: {
+                                minIntervalMinutes: cfg.minIntervalMinutes,
+                                skipIfNoNewTranscripts: cfg.skipIfNoNewTranscripts,
+                                decision: cadenceDecision.reason
+                            },
+                            generatedRecommendations: recommendations
+                        }
+                    };
+                }
+                catch (e) {
+                    const msg = e instanceof Error ? e.message : String(e);
+                    return { ok: false, code: "ingest-failed", message: msg };
+                }
+            },
+            "transcript-automation-status": async () => {
+                const syncArgs = {
+                    sourcePath: typeof args.sourcePath === "string" ? args.sourcePath : undefined,
+                    archivePath: typeof args.archivePath === "string" ? args.archivePath : undefined
+                };
+                const state = await loadImprovementState(ctx.workspacePath, ctx.effectiveConfig);
+                const cfg = resolveImprovementTranscriptConfig(ctx, syncArgs);
                 return {
                     ok: true,
-                    code: "transcripts-ingested",
-                    message: `Ingest ${status}; sync copied ${sync.copied} file(s)`,
+                    code: "transcript-automation-status",
+                    message: "Transcript automation status",
                     data: {
-                        sync,
+                        schemaVersion: 1,
+                        lastSyncRunAt: state.lastSyncRunAt,
+                        lastIngestRunAt: state.lastIngestRunAt,
                         cadence: {
                             minIntervalMinutes: cfg.minIntervalMinutes,
                             skipIfNoNewTranscripts: cfg.skipIfNoNewTranscripts,
-                            decision: cadenceDecision.reason
+                            maxRecommendationCandidatesPerRun: getMaxRecommendationCandidatesPerRun(ctx)
                         },
-                        generatedRecommendations: recommendations
-                    }
-                };
-            }
-            catch (e) {
-                const msg = e instanceof Error ? e.message : String(e);
-                return { ok: false, code: "ingest-failed", message: msg };
-            }
-        }
-        if (command.name === "transcript-automation-status") {
-            const syncArgs = {
-                sourcePath: typeof args.sourcePath === "string" ? args.sourcePath : undefined,
-                archivePath: typeof args.archivePath === "string" ? args.archivePath : undefined
-            };
-            const state = await loadImprovementState(ctx.workspacePath);
-            const cfg = resolveImprovementTranscriptConfig(ctx, syncArgs);
-            return {
-                ok: true,
-                code: "transcript-automation-status",
-                message: "Transcript automation status",
-                data: {
-                    schemaVersion: 1,
-                    lastSyncRunAt: state.lastSyncRunAt,
-                    lastIngestRunAt: state.lastIngestRunAt,
-                    cadence: {
-                        minIntervalMinutes: cfg.minIntervalMinutes,
-                        skipIfNoNewTranscripts: cfg.skipIfNoNewTranscripts,
-                        maxRecommendationCandidatesPerRun: getMaxRecommendationCandidatesPerRun(ctx)
-                    },
-                    transcripts: {
-                        sourcePath: cfg.sourcePath || null,
-                        archivePath: cfg.archivePath,
-                        discoveryPaths: cfg.discoveryPaths,
-                        budgets: {
-                            maxFilesPerSync: cfg.maxFilesPerSync,
-                            maxBytesPerFile: cfg.maxBytesPerFile,
-                            maxTotalScanBytes: cfg.maxTotalScanBytes
+                        transcripts: {
+                            sourcePath: cfg.sourcePath || null,
+                            archivePath: cfg.archivePath,
+                            discoveryPaths: cfg.discoveryPaths,
+                            budgets: {
+                                maxFilesPerSync: cfg.maxFilesPerSync,
+                                maxBytesPerFile: cfg.maxBytesPerFile,
+                                maxTotalScanBytes: cfg.maxTotalScanBytes
+                            }
+                        },
+                        retryQueue: {
+                            pending: state.transcriptRetryQueue?.length ?? 0,
+                            entries: state.transcriptRetryQueue ?? []
+                        },
+                        policySession: {
+                            sessionId: resolveSessionId(process.env)
                         }
-                    },
-                    retryQueue: {
-                        pending: state.transcriptRetryQueue?.length ?? 0,
-                        entries: state.transcriptRetryQueue ?? []
-                    },
-                    policySession: {
-                        sessionId: resolveSessionId(process.env)
                     }
+                };
+            },
+            "query-lineage": async () => {
+                const taskId = typeof args.taskId === "string" ? args.taskId.trim() : "";
+                if (!taskId) {
+                    return { ok: false, code: "invalid-args", message: "query-lineage requires taskId" };
                 }
-            };
-        }
-        if (command.name === "query-lineage") {
-            const taskId = typeof args.taskId === "string" ? args.taskId.trim() : "";
-            if (!taskId) {
-                return { ok: false, code: "invalid-args", message: "query-lineage requires taskId" };
+                const chain = await queryLineageChain(ctx.workspacePath, taskId);
+                return {
+                    ok: true,
+                    code: "lineage-queried",
+                    message: `${chain.events.length} lineage event(s) for ${taskId}`,
+                    data: chain
+                };
             }
-            const chain = await queryLineageChain(ctx.workspacePath, taskId);
-            return {
-                ok: true,
-                code: "lineage-queried",
-                message: `${chain.events.length} lineage event(s) for ${taskId}`,
-                data: chain
-            };
-        }
+        };
+        const handler = handlers[command.name];
+        if (handler)
+            return handler();
         return {
             ok: false,
             code: "unsupported-command",

package/dist/modules/improvement/ingest.d.ts

@@ -1,4 +1,4 @@
-import type { TransitionEvidence } from "../task-engine/types.js";
+import type { TransitionEvidence } from "../../core/planning/index.js";
 import type { EvidenceKind, ConfidenceSignals } from "./confidence.js";
 import { computeHeuristicConfidence } from "./confidence.js";
 import type { ImprovementStateDocument } from "./improvement-state.js";

package/dist/modules/improvement/policy-sensitive-commands.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Policy-gated `workspace-kit run` commands owned by the improvement module.
+ */
+export declare const IMPROVEMENT_POLICY_COMMAND_NAMES: readonly [readonly ["generate-recommendations", "improvement.generate-recommendations"], readonly ["ingest-transcripts", "improvement.ingest-transcripts"]];

package/dist/modules/improvement/policy-sensitive-commands.js

@@ -0,0 +1,7 @@
+/**
+ * Policy-gated `workspace-kit run` commands owned by the improvement module.
+ */
+export const IMPROVEMENT_POLICY_COMMAND_NAMES = [
+    ["generate-recommendations", "improvement.generate-recommendations"],
+    ["ingest-transcripts", "improvement.ingest-transcripts"]
+];

package/dist/modules/index.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Default module bundle + selective re-exports. Policy: see `docs/maintainers/module-build-guide.md` (Barrel export policy).
+ */
+import type { WorkflowModule } from "../contracts/module-contract.js";
+export declare const defaultRegistryModules: WorkflowModule[];
+export { agentBehaviorModule, BUILTIN_PROFILES, DEFAULT_BUILTIN_PROFILE_ID, mergeDimensions, validateBehaviorProfile } from "./agent-behavior/index.js";
 export { approvalsModule } from "./approvals/index.js";
 export { documentationModule } from "./documentation/index.js";
 export type { DocumentationConflict, DocumentationGenerateOptions, DocumentationGenerateResult, DocumentationGenerationEvidence, DocumentationValidationIssue } from "./documentation/types.js";

package/dist/modules/index.js

@@ -1,3 +1,20 @@
+import { agentBehaviorModule } from "./agent-behavior/index.js";
+import { approvalsModule } from "./approvals/index.js";
+import { documentationModule } from "./documentation/index.js";
+import { improvementModule } from "./improvement/index.js";
+import { planningModule } from "./planning/index.js";
+import { taskEngineModule } from "./task-engine/index.js";
+import { workspaceConfigModule } from "./workspace-config/index.js";
+export const defaultRegistryModules = [
+    workspaceConfigModule,
+    documentationModule,
+    agentBehaviorModule,
+    taskEngineModule,
+    approvalsModule,
+    planningModule,
+    improvementModule
+];
+export { agentBehaviorModule, BUILTIN_PROFILES, DEFAULT_BUILTIN_PROFILE_ID, mergeDimensions, validateBehaviorProfile } from "./agent-behavior/index.js";
 export { approvalsModule } from "./approvals/index.js";
 export { documentationModule } from "./documentation/index.js";
 export { improvementModule } from "./improvement/index.js";

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