@workflow-cannon/workspace-kit 0.5.0 → 0.7.0

package/README.md

@@ -63,7 +63,8 @@ This keeps automation adaptive without sacrificing safety, governance, or develo
 
 - **Phase 0** and **Phase 1** (task engine, `v0.3.0`) are complete.
 - **Phase 2** (layered config, policy gates, cutover docs, `v0.4.0`) is complete in-repo; see `docs/maintainers/TASKS.md` and `docs/maintainers/ROADMAP.md`.
-- **Phase 2b** (policy + config UX, `v0.4.1`) and **Phase 3** (enhancement loop MVP, `v0.5.0`) are complete in-repo: evidence-driven **improvement** tasks, **`approvals`** (`review-item`), heuristic confidence, and append-only lineage. **Phase 4** (`v0.6.0`, `T193`+) is next.
+- **Phase 2b** (policy + config UX, `v0.4.1`) and **Phase 3** (enhancement loop MVP, `v0.5.0`) are complete in-repo: evidence-driven **improvement** tasks, **`approvals`** (`review-item`), heuristic confidence, and append-only lineage.
+- **Phase 4** (`v0.6.0`) is complete in-repo: compatibility matrix/gates, diagnostics/SLO baseline evidence, release-channel mapping, and planning-doc consistency checks.
 
 ## Goals
 

package/dist/core/config-metadata.js

@@ -28,6 +28,58 @@ const REGISTRY = {
         requiresApproval: true,
         exposure: "maintainer",
         writableLayers: ["project"]
+    },
+    "improvement.transcripts.sourcePath": {
+        key: "improvement.transcripts.sourcePath",
+        type: "string",
+        description: "Relative path to transcript JSONL source files for sync operations.",
+        default: ".cursor/agent-transcripts",
+        domainScope: "project",
+        owningModule: "improvement",
+        sensitive: false,
+        requiresRestart: false,
+        requiresApproval: false,
+        exposure: "public",
+        writableLayers: ["project", "user"]
+    },
+    "improvement.transcripts.archivePath": {
+        key: "improvement.transcripts.archivePath",
+        type: "string",
+        description: "Relative local archive path where synced transcript JSONL files are copied.",
+        default: "agent-transcripts",
+        domainScope: "project",
+        owningModule: "improvement",
+        sensitive: false,
+        requiresRestart: false,
+        requiresApproval: false,
+        exposure: "public",
+        writableLayers: ["project", "user"]
+    },
+    "improvement.cadence.minIntervalMinutes": {
+        key: "improvement.cadence.minIntervalMinutes",
+        type: "number",
+        description: "Minimum minutes between one-shot ingest recommendation generation runs.",
+        default: 15,
+        domainScope: "project",
+        owningModule: "improvement",
+        sensitive: false,
+        requiresRestart: false,
+        requiresApproval: false,
+        exposure: "maintainer",
+        writableLayers: ["project", "user"]
+    },
+    "improvement.cadence.skipIfNoNewTranscripts": {
+        key: "improvement.cadence.skipIfNoNewTranscripts",
+        type: "boolean",
+        description: "Skip recommendation generation when transcript sync copies no new files.",
+        default: true,
+        domainScope: "project",
+        owningModule: "improvement",
+        sensitive: false,
+        requiresRestart: false,
+        requiresApproval: false,
+        exposure: "maintainer",
+        writableLayers: ["project", "user"]
     }
 };
 export function getConfigKeyMetadata(key) {
@@ -102,7 +154,15 @@ function deepEqualLoose(a, b) {
  * Validate top-level shape of persisted kit config files (strict unknown-key rejection).
  */
 export function validatePersistedConfigDocument(data, label) {
-    const allowed = new Set(["schemaVersion", "core", "tasks", "documentation", "policy", "modules"]);
+    const allowed = new Set([
+        "schemaVersion",
+        "core",
+        "tasks",
+        "documentation",
+        "policy",
+        "improvement",
+        "modules"
+    ]);
     for (const k of Object.keys(data)) {
         if (!allowed.has(k)) {
             throw new Error(`config-invalid(${label}): unknown top-level key '${k}'`);
@@ -156,6 +216,54 @@ export function validatePersistedConfigDocument(data, label) {
             throw new Error(`config-invalid(${label}): modules must be absent or an empty object`);
         }
     }
+    const improvement = data.improvement;
+    if (improvement !== undefined) {
+        if (typeof improvement !== "object" || improvement === null || Array.isArray(improvement)) {
+            throw new Error(`config-invalid(${label}): improvement must be an object`);
+        }
+        const imp = improvement;
+        for (const k of Object.keys(imp)) {
+            if (k !== "transcripts" && k !== "cadence") {
+                throw new Error(`config-invalid(${label}): unknown improvement.${k}`);
+            }
+        }
+        if (imp.transcripts !== undefined) {
+            if (typeof imp.transcripts !== "object" ||
+                imp.transcripts === null ||
+                Array.isArray(imp.transcripts)) {
+                throw new Error(`config-invalid(${label}): improvement.transcripts must be an object`);
+            }
+            const tr = imp.transcripts;
+            for (const k of Object.keys(tr)) {
+                if (k !== "sourcePath" && k !== "archivePath") {
+                    throw new Error(`config-invalid(${label}): unknown improvement.transcripts.${k}`);
+                }
+            }
+            if (tr.sourcePath !== undefined) {
+                validateValueForMetadata(REGISTRY["improvement.transcripts.sourcePath"], tr.sourcePath);
+            }
+            if (tr.archivePath !== undefined) {
+                validateValueForMetadata(REGISTRY["improvement.transcripts.archivePath"], tr.archivePath);
+            }
+        }
+        if (imp.cadence !== undefined) {
+            if (typeof imp.cadence !== "object" || imp.cadence === null || Array.isArray(imp.cadence)) {
+                throw new Error(`config-invalid(${label}): improvement.cadence must be an object`);
+            }
+            const cd = imp.cadence;
+            for (const k of Object.keys(cd)) {
+                if (k !== "minIntervalMinutes" && k !== "skipIfNoNewTranscripts") {
+                    throw new Error(`config-invalid(${label}): unknown improvement.cadence.${k}`);
+                }
+            }
+            if (cd.minIntervalMinutes !== undefined) {
+                validateValueForMetadata(REGISTRY["improvement.cadence.minIntervalMinutes"], cd.minIntervalMinutes);
+            }
+            if (cd.skipIfNoNewTranscripts !== undefined) {
+                validateValueForMetadata(REGISTRY["improvement.cadence.skipIfNoNewTranscripts"], cd.skipIfNoNewTranscripts);
+            }
+        }
+    }
 }
 export function getConfigRegistryExport() {
     return REGISTRY;

package/dist/core/policy.d.ts

@@ -1,5 +1,5 @@
 export declare const POLICY_TRACE_SCHEMA_VERSION: 1;
-export type PolicyOperationId = "cli.upgrade" | "cli.init" | "cli.config-mutate" | "policy.dynamic-sensitive" | "doc.document-project" | "doc.generate-document" | "tasks.import-tasks" | "tasks.generate-tasks-md" | "tasks.run-transition" | "approvals.review-item" | "improvement.generate-recommendations";
+export type PolicyOperationId = "cli.upgrade" | "cli.init" | "cli.config-mutate" | "policy.dynamic-sensitive" | "doc.document-project" | "doc.generate-document" | "tasks.import-tasks" | "tasks.generate-tasks-md" | "tasks.run-transition" | "approvals.review-item" | "improvement.generate-recommendations" | "improvement.ingest-transcripts";
 export declare function getOperationIdForCommand(commandName: string): PolicyOperationId | undefined;
 export declare function getExtraSensitiveModuleCommandsFromEffective(effective: Record<string, unknown>): string[];
 /** Resolve operation id for tracing, including config-declared sensitive module commands. */

package/dist/core/policy.js

@@ -9,7 +9,8 @@ const COMMAND_TO_OPERATION = {
     "generate-tasks-md": "tasks.generate-tasks-md",
     "run-transition": "tasks.run-transition",
     "review-item": "approvals.review-item",
-    "generate-recommendations": "improvement.generate-recommendations"
+    "generate-recommendations": "improvement.generate-recommendations",
+    "ingest-transcripts": "improvement.ingest-transcripts"
 };
 export function getOperationIdForCommand(commandName) {
     return COMMAND_TO_OPERATION[commandName];

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

@@ -13,7 +13,17 @@ export const KIT_CONFIG_DEFAULTS = {
     tasks: {
         storeRelativePath: ".workspace-kit/tasks/state.json"
     },
-    documentation: {}
+    documentation: {},
+    improvement: {
+        transcripts: {
+            sourcePath: ".cursor/agent-transcripts",
+            archivePath: "agent-transcripts"
+        },
+        cadence: {
+            minIntervalMinutes: 15,
+            skipIfNoNewTranscripts: true
+        }
+    }
 };
 /**
  * Static module-level defaults keyed by module id (merged in registry startup order).
@@ -30,7 +40,16 @@ export const MODULE_CONFIG_CONTRIBUTIONS = {
     },
     approvals: {},
     planning: {},
-    improvement: {}
+    improvement: {
+        transcripts: {
+            sourcePath: ".cursor/agent-transcripts",
+            archivePath: "agent-transcripts"
+        },
+        cadence: {
+            minIntervalMinutes: 15,
+            skipIfNoNewTranscripts: true
+        }
+    }
 };
 export function deepMerge(target, source) {
     const out = { ...target };

package/dist/modules/improvement/generate-recommendations-runtime.js

@@ -19,13 +19,24 @@ function hasEvidenceKey(tasks, key) {
         return m.evidenceKey === key;
     });
 }
+function resolveTranscriptArchivePath(ctx, args) {
+    if (typeof args.transcriptsRoot === "string" && args.transcriptsRoot.trim().length > 0) {
+        return args.transcriptsRoot.trim();
+    }
+    const improvement = ctx.effectiveConfig?.improvement && typeof ctx.effectiveConfig.improvement === "object"
+        ? ctx.effectiveConfig.improvement
+        : {};
+    const transcripts = improvement.transcripts && typeof improvement.transcripts === "object"
+        ? improvement.transcripts
+        : {};
+    const archivePath = typeof transcripts.archivePath === "string" ? transcripts.archivePath.trim() : "";
+    return archivePath || "agent-transcripts";
+}
 export async function runGenerateRecommendations(ctx, args) {
     const store = new TaskStore(ctx.workspacePath, taskStoreRelativePath(ctx));
     await store.load();
     const state = await loadImprovementState(ctx.workspacePath);
-    const transcriptsRoot = typeof args.transcriptsRoot === "string" && args.transcriptsRoot.trim()
-        ? args.transcriptsRoot.trim()
-        : "agent-transcripts";
+    const transcriptsRoot = resolveTranscriptArchivePath(ctx, args);
     const fromTag = typeof args.fromTag === "string" ? args.fromTag.trim() : undefined;
     const toTag = typeof args.toTag === "string" ? args.toTag.trim() : undefined;
     const candidates = [];

package/dist/modules/improvement/improvement-state.d.ts

@@ -5,6 +5,8 @@ export type ImprovementStateDocument = {
     mutationLineCursor: number;
     transitionLogLengthCursor: number;
     transcriptLineCursors: Record<string, number>;
+    lastSyncRunAt: string | null;
+    lastIngestRunAt: string | null;
 };
 export declare function emptyImprovementState(): ImprovementStateDocument;
 export declare function loadImprovementState(workspacePath: string): Promise<ImprovementStateDocument>;

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

@@ -11,7 +11,9 @@ export function emptyImprovementState() {
         policyTraceLineCursor: 0,
         mutationLineCursor: 0,
         transitionLogLengthCursor: 0,
-        transcriptLineCursors: {}
+        transcriptLineCursors: {},
+        lastSyncRunAt: null,
+        lastIngestRunAt: null
     };
 }
 export async function loadImprovementState(workspacePath) {

package/dist/modules/improvement/index.js

@@ -1,9 +1,11 @@
 import { queryLineageChain } from "../../core/lineage-store.js";
 import { runGenerateRecommendations } from "./generate-recommendations-runtime.js";
+import { resolveCadenceDecision, runSyncTranscripts } from "./transcript-sync-runtime.js";
+import { loadImprovementState, saveImprovementState } from "./improvement-state.js";
 export const improvementModule = {
     registration: {
         id: "improvement",
-        version: "0.5.0",
+        version: "0.7.0",
         contractVersion: "1",
         capabilities: ["improvement"],
         dependsOn: ["task-engine", "planning"],
@@ -30,6 +32,16 @@ export const improvementModule = {
                     name: "query-lineage",
                     file: "query-lineage.md",
                     description: "Reconstruct lineage chain for a recommendation task id."
+                },
+                {
+                    name: "sync-transcripts",
+                    file: "sync-transcripts.md",
+                    description: "Sync local transcript JSONL files into the archive."
+                },
+                {
+                    name: "ingest-transcripts",
+                    file: "ingest-transcripts.md",
+                    description: "Run transcript sync and recommendation generation in one flow."
                 }
             ]
         }
@@ -54,6 +66,81 @@ export const improvementModule = {
                 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 sync = await runSyncTranscripts(ctx, syncArgs);
+                const state = await loadImprovementState(ctx.workspacePath);
+                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
+                };
+            }
+            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 sync = await runSyncTranscripts(ctx, syncArgs);
+                const state = await loadImprovementState(ctx.workspacePath);
+                const improvement = ctx.effectiveConfig?.improvement && typeof ctx.effectiveConfig.improvement === "object"
+                    ? ctx.effectiveConfig.improvement
+                    : {};
+                const cadence = improvement.cadence && typeof improvement.cadence === "object"
+                    ? improvement.cadence
+                    : {};
+                const minIntervalMinutes = typeof cadence.minIntervalMinutes === "number" && Number.isFinite(cadence.minIntervalMinutes)
+                    ? Math.max(1, Math.floor(cadence.minIntervalMinutes))
+                    : 15;
+                const skipIfNoNewTranscripts = typeof cadence.skipIfNoNewTranscripts === "boolean"
+                    ? cadence.skipIfNoNewTranscripts
+                    : true;
+                const cadenceDecision = resolveCadenceDecision(now, state.lastIngestRunAt, minIntervalMinutes, sync.copied, 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);
+                const status = generate ? "generated" : "skipped";
+                return {
+                    ok: true,
+                    code: "transcripts-ingested",
+                    message: `Ingest ${status}; sync copied ${sync.copied} file(s)`,
+                    data: {
+                        sync,
+                        cadence: {
+                            minIntervalMinutes,
+                            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 };
+            }
+        }
         if (command.name === "query-lineage") {
             const taskId = typeof args.taskId === "string" ? args.taskId.trim() : "";
             if (!taskId) {

package/dist/modules/improvement/transcript-sync-runtime.d.ts

@@ -0,0 +1,24 @@
+import type { ModuleLifecycleContext } from "../../contracts/module-contract.js";
+export type TranscriptSyncArgs = {
+    sourcePath?: string;
+    archivePath?: string;
+};
+export type TranscriptSyncResult = {
+    sourcePath: string;
+    archivePath: string;
+    scanned: number;
+    copied: number;
+    skippedExisting: number;
+    skippedConflict: number;
+    errors: Array<{
+        file: string;
+        code: string;
+        message: string;
+    }>;
+    copiedFiles: string[];
+};
+export declare function runSyncTranscripts(ctx: ModuleLifecycleContext, args: TranscriptSyncArgs): Promise<TranscriptSyncResult>;
+export declare function resolveCadenceDecision(now: Date, previousRunAtIso: string | null, minIntervalMinutes: number, copiedCount: number, skipIfNoNewTranscripts: boolean): {
+    shouldRunGenerate: boolean;
+    reason: string;
+};

package/dist/modules/improvement/transcript-sync-runtime.js

@@ -0,0 +1,131 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createHash } from "node:crypto";
+function resolveImprovementTranscriptConfig(ctx, args) {
+    const improvement = ctx.effectiveConfig?.improvement && typeof ctx.effectiveConfig.improvement === "object"
+        ? ctx.effectiveConfig.improvement
+        : {};
+    const transcripts = improvement.transcripts && typeof improvement.transcripts === "object"
+        ? improvement.transcripts
+        : {};
+    const cadence = improvement.cadence && typeof improvement.cadence === "object"
+        ? improvement.cadence
+        : {};
+    const sourcePathArg = typeof args.sourcePath === "string" ? args.sourcePath.trim() : "";
+    const archivePathArg = typeof args.archivePath === "string" ? args.archivePath.trim() : "";
+    const sourcePathCfg = typeof transcripts.sourcePath === "string" ? transcripts.sourcePath.trim() : "";
+    const archivePathCfg = typeof transcripts.archivePath === "string" ? transcripts.archivePath.trim() : "";
+    const minIntervalCfg = typeof cadence.minIntervalMinutes === "number" && Number.isFinite(cadence.minIntervalMinutes)
+        ? cadence.minIntervalMinutes
+        : 15;
+    const skipIfNoNewCfg = typeof cadence.skipIfNoNewTranscripts === "boolean" ? cadence.skipIfNoNewTranscripts : true;
+    return {
+        sourcePath: sourcePathArg || sourcePathCfg || ".cursor/agent-transcripts",
+        archivePath: archivePathArg || archivePathCfg || "agent-transcripts",
+        minIntervalMinutes: Math.max(1, Math.floor(minIntervalCfg)),
+        skipIfNoNewTranscripts: skipIfNoNewCfg
+    };
+}
+async function listJsonlRelativePaths(root) {
+    const out = [];
+    async function walk(cur) {
+        const ents = await fs.readdir(cur, { withFileTypes: true });
+        for (const ent of ents) {
+            const abs = path.join(cur, ent.name);
+            if (ent.isDirectory()) {
+                await walk(abs);
+            }
+            else if (ent.isFile() && ent.name.endsWith(".jsonl")) {
+                out.push(path.relative(root, abs));
+            }
+        }
+    }
+    await walk(root);
+    return out.sort((a, b) => a.localeCompare(b));
+}
+async function fileSha256(filePath) {
+    const buf = await fs.readFile(filePath);
+    return createHash("sha256").update(buf).digest("hex");
+}
+export async function runSyncTranscripts(ctx, args) {
+    const cfg = resolveImprovementTranscriptConfig(ctx, args);
+    const sourceRoot = path.resolve(ctx.workspacePath, cfg.sourcePath);
+    const archiveRoot = path.resolve(ctx.workspacePath, cfg.archivePath);
+    const result = {
+        sourcePath: path.relative(ctx.workspacePath, sourceRoot) || ".",
+        archivePath: path.relative(ctx.workspacePath, archiveRoot) || ".",
+        scanned: 0,
+        copied: 0,
+        skippedExisting: 0,
+        skippedConflict: 0,
+        errors: [],
+        copiedFiles: []
+    };
+    let files = [];
+    try {
+        files = await listJsonlRelativePaths(sourceRoot);
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        result.errors.push({
+            file: result.sourcePath,
+            code: "source-read-error",
+            message: msg
+        });
+        return result;
+    }
+    result.scanned = files.length;
+    await fs.mkdir(archiveRoot, { recursive: true });
+    for (const rel of files) {
+        const src = path.join(sourceRoot, rel);
+        const dst = path.join(archiveRoot, rel);
+        try {
+            await fs.mkdir(path.dirname(dst), { recursive: true });
+            const srcHash = await fileSha256(src);
+            let dstHash = null;
+            try {
+                dstHash = await fileSha256(dst);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT") {
+                    throw error;
+                }
+            }
+            if (dstHash === srcHash) {
+                result.skippedExisting += 1;
+                continue;
+            }
+            if (dstHash && dstHash !== srcHash) {
+                result.skippedConflict += 1;
+                continue;
+            }
+            await fs.copyFile(src, dst);
+            result.copied += 1;
+            result.copiedFiles.push(rel);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            result.errors.push({ file: rel, code: "copy-error", message: msg });
+        }
+    }
+    result.copiedFiles.sort((a, b) => a.localeCompare(b));
+    return result;
+}
+export function resolveCadenceDecision(now, previousRunAtIso, minIntervalMinutes, copiedCount, skipIfNoNewTranscripts) {
+    if (copiedCount === 0 && skipIfNoNewTranscripts) {
+        return { shouldRunGenerate: false, reason: "skipped-no-new-transcripts" };
+    }
+    if (!previousRunAtIso) {
+        return { shouldRunGenerate: true, reason: "run-first-ingest" };
+    }
+    const prev = new Date(previousRunAtIso);
+    if (!Number.isFinite(prev.getTime())) {
+        return { shouldRunGenerate: true, reason: "run-invalid-last-ingest-at" };
+    }
+    const elapsedMs = now.getTime() - prev.getTime();
+    const requiredMs = minIntervalMinutes * 60 * 1000;
+    if (elapsedMs < requiredMs) {
+        return { shouldRunGenerate: false, reason: "skipped-min-interval" };
+    }
+    return { shouldRunGenerate: true, reason: "run-min-interval-satisfied" };
+}

package/dist/modules/index.d.ts

@@ -5,5 +5,5 @@ export { improvementModule } from "./improvement/index.js";
 export { computeHeuristicConfidence, HEURISTIC_1_ADMISSION_THRESHOLD, shouldAdmitRecommendation, type ConfidenceResult, type ConfidenceSignals, type EvidenceKind } from "./improvement/confidence.js";
 export { workspaceConfigModule } from "./workspace-config/index.js";
 export { planningModule } from "./planning/index.js";
-export { taskEngineModule, TaskStore, TransitionService, TaskEngineError, TransitionValidator, isTransitionAllowed, getTransitionAction, resolveTargetState, getAllowedTransitionsFrom, stateValidityGuard, dependencyCheckGuard, generateTasksMd, importTasksFromMarkdown, getNextActions } from "./task-engine/index.js";
+export { taskEngineModule, TaskStore, TransitionService, TaskEngineError, TransitionValidator, isTransitionAllowed, getTransitionAction, resolveTargetState, getAllowedTransitionsFrom, stateValidityGuard, dependencyCheckGuard, generateTasksMd, syncTaskHeadingsInMarkdown, importTasksFromMarkdown, getNextActions } from "./task-engine/index.js";
 export type { TaskEntity, TaskStatus, TaskPriority, TaskStoreDocument, TransitionEvidence, TransitionGuard, TransitionContext, GuardResult, TaskEngineErrorCode, TaskAdapter, TaskAdapterCapability, NextActionSuggestion, BlockingAnalysisEntry } from "./task-engine/index.js";

package/dist/modules/index.js

@@ -4,4 +4,4 @@ export { improvementModule } from "./improvement/index.js";
 export { computeHeuristicConfidence, HEURISTIC_1_ADMISSION_THRESHOLD, shouldAdmitRecommendation } from "./improvement/confidence.js";
 export { workspaceConfigModule } from "./workspace-config/index.js";
 export { planningModule } from "./planning/index.js";
-export { taskEngineModule, TaskStore, TransitionService, TaskEngineError, TransitionValidator, isTransitionAllowed, getTransitionAction, resolveTargetState, getAllowedTransitionsFrom, stateValidityGuard, dependencyCheckGuard, generateTasksMd, importTasksFromMarkdown, getNextActions } from "./task-engine/index.js";
+export { taskEngineModule, TaskStore, TransitionService, TaskEngineError, TransitionValidator, isTransitionAllowed, getTransitionAction, resolveTargetState, getAllowedTransitionsFrom, stateValidityGuard, dependencyCheckGuard, generateTasksMd, syncTaskHeadingsInMarkdown, importTasksFromMarkdown, getNextActions } from "./task-engine/index.js";

package/dist/modules/task-engine/generator.d.ts

@@ -1,2 +1,3 @@
 import type { TaskEntity } from "./types.js";
 export declare function generateTasksMd(tasks: TaskEntity[]): string;
+export declare function syncTaskHeadingsInMarkdown(markdown: string, tasks: TaskEntity[]): string;

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

@@ -99,3 +99,20 @@ export function generateTasksMd(tasks) {
     }
     return lines.join("\n");
 }
+export function syncTaskHeadingsInMarkdown(markdown, tasks) {
+    const byId = new Map(tasks.map((task) => [task.id, task]));
+    const lines = markdown.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const match = line.match(/^###\s+\[[^\]]*\]\s+(T\d+)\s+(.+)$/);
+        if (!match)
+            continue;
+        const id = match[1];
+        const task = byId.get(id);
+        if (!task)
+            continue;
+        const marker = STATUS_MARKERS[task.status] ?? "[ ]";
+        lines[i] = `### ${marker} ${task.id} ${task.title}`;
+    }
+    return lines.join("\n");
+}

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

@@ -139,8 +139,14 @@ export async function importTasksFromMarkdown(sourcePath) {
         }
         if (line.startsWith("### ")) {
             flushTask();
-            taskStartIdx = i;
-            taskLines = [line];
+            if (parseTaskId(line)) {
+                taskStartIdx = i;
+                taskLines = [line];
+            }
+            else {
+                taskStartIdx = -1;
+                taskLines = [];
+            }
             continue;
         }
         if (taskStartIdx !== -1) {

package/dist/modules/task-engine/index.d.ts

@@ -3,7 +3,7 @@ export type { TaskEntity, TaskStatus, TaskPriority, TaskStoreDocument, Transitio
 export { TaskStore } from "./store.js";
 export { TransitionService } from "./service.js";
 export { TaskEngineError, TransitionValidator, isTransitionAllowed, getTransitionAction, resolveTargetState, getAllowedTransitionsFrom, stateValidityGuard, dependencyCheckGuard } from "./transitions.js";
-export { generateTasksMd } from "./generator.js";
+export { generateTasksMd, syncTaskHeadingsInMarkdown } from "./generator.js";
 export { importTasksFromMarkdown } from "./importer.js";
 export { getNextActions } from "./suggestions.js";
 export declare const taskEngineModule: WorkflowModule;

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

@@ -3,13 +3,13 @@ import fs from "node:fs/promises";
 import { TaskStore } from "./store.js";
 import { TransitionService } from "./service.js";
 import { TaskEngineError } from "./transitions.js";
-import { generateTasksMd } from "./generator.js";
+import { generateTasksMd, syncTaskHeadingsInMarkdown } from "./generator.js";
 import { importTasksFromMarkdown } from "./importer.js";
 import { getNextActions } from "./suggestions.js";
 export { TaskStore } from "./store.js";
 export { TransitionService } from "./service.js";
 export { TaskEngineError, TransitionValidator, isTransitionAllowed, getTransitionAction, resolveTargetState, getAllowedTransitionsFrom, stateValidityGuard, dependencyCheckGuard } from "./transitions.js";
-export { generateTasksMd } from "./generator.js";
+export { generateTasksMd, syncTaskHeadingsInMarkdown } from "./generator.js";
 export { importTasksFromMarkdown } from "./importer.js";
 export { getNextActions } from "./suggestions.js";
 function taskStorePath(ctx) {
@@ -225,8 +225,16 @@ export const taskEngineModule = {
                 ? path.resolve(ctx.workspacePath, args.outputPath)
                 : path.resolve(ctx.workspacePath, "docs/maintainers/TASKS.md");
             const tasks = store.getAllTasks();
-            const markdown = generateTasksMd(tasks);
+            const fallbackMarkdown = generateTasksMd(tasks);
+            let markdown = fallbackMarkdown;
+            const preserveStructure = args.preserveStructure !== false;
             try {
+                if (preserveStructure) {
+                    const existing = await fs.readFile(outputPath, "utf8").catch(() => undefined);
+                    if (typeof existing === "string" && existing.length > 0) {
+                        markdown = syncTaskHeadingsInMarkdown(existing, tasks);
+                    }
+                }
                 await fs.mkdir(path.dirname(outputPath), { recursive: true });
                 await fs.writeFile(outputPath, markdown, "utf8");
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workflow-cannon/workspace-kit",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "private": false,
   "packageManager": "pnpm@10.0.0",
   "license": "MIT",
@@ -24,7 +24,14 @@
     "test": "pnpm run build && node --test test/**/*.test.mjs",
     "pack:dry-run": "pnpm run build && pnpm pack --pack-destination ./artifacts/workspace-kit-pack",
     "check-release-metadata": "node scripts/check-release-metadata.mjs",
-    "parity": "node scripts/run-parity.mjs"
+    "parity": "node scripts/run-parity.mjs",
+    "check-compatibility": "pnpm run build && node scripts/check-compatibility.mjs",
+    "check-planning-consistency": "node scripts/check-planning-doc-consistency.mjs",
+    "check-release-channel": "node scripts/check-release-channel.mjs",
+    "generate-runtime-diagnostics": "node scripts/generate-runtime-diagnostics.mjs",
+    "prune-evidence": "node scripts/prune-evidence.mjs",
+    "phase4-gates": "pnpm run check-compatibility && pnpm run check-planning-consistency && pnpm run check-release-channel",
+    "phase5-gates": "pnpm run phase4-gates && pnpm run test"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",