@workflow-cannon/workspace-kit 0.17.0 → 0.24.0

package/dist/core/config-metadata.js

@@ -69,6 +69,86 @@ const REGISTRY = {
         exposure: "public",
         writableLayers: ["project", "user"]
     },
+    "modules.enabled": {
+        key: "modules.enabled",
+        type: "array",
+        description: "When non-empty, only these module ids are enabled (whitelist); then modules.disabled subtracts. When empty, all modules use registration.enabledByDefault.",
+        default: [],
+        domainScope: "project",
+        owningModule: "workspace-kit",
+        sensitive: false,
+        requiresRestart: false,
+        requiresApproval: false,
+        exposure: "maintainer",
+        writableLayers: ["project", "user"]
+    },
+    "modules.disabled": {
+        key: "modules.disabled",
+        type: "array",
+        description: "Module ids to disable after computing the candidate enabled set (default-by-flag or modules.enabled whitelist).",
+        default: [],
+        domainScope: "project",
+        owningModule: "workspace-kit",
+        sensitive: false,
+        requiresRestart: false,
+        requiresApproval: false,
+        exposure: "maintainer",
+        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.adaptiveFinalizePolicy": {
+        key: "planning.adaptiveFinalizePolicy",
+        type: "string",
+        description: "Controls finalize handling for unresolved adaptive follow-up questions: off (ignore), warn (allow finalize with warnings), block (deny finalize).",
+        default: "off",
+        allowedValues: ["off", "warn", "block"],
+        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",
@@ -299,6 +379,13 @@ export function validateValueForMetadata(meta, value) {
                 }
             }
         }
+        if (meta.key === "modules.enabled" || meta.key === "modules.disabled") {
+            for (const item of value) {
+                if (typeof item !== "string" || item.trim().length === 0) {
+                    throw new Error(`config-type-error(${meta.key}): array entries must be non-empty strings`);
+                }
+            }
+        }
         return;
     }
     if (meta.type === "string" && typeof value !== "string") {
@@ -417,8 +504,20 @@ export function validatePersistedConfigDocument(data, label) {
     }
     const mods = data.modules;
     if (mods !== undefined) {
-        if (typeof mods !== "object" || mods === null || Array.isArray(mods) || Object.keys(mods).length > 0) {
-            throw new Error(`config-invalid(${label}): modules must be absent or an empty object`);
+        if (typeof mods !== "object" || mods === null || Array.isArray(mods)) {
+            throw new Error(`config-invalid(${label}): modules must be an object`);
+        }
+        const m = mods;
+        for (const k of Object.keys(m)) {
+            if (k !== "enabled" && k !== "disabled") {
+                throw new Error(`config-invalid(${label}): unknown modules.${k}`);
+            }
+        }
+        if (m.enabled !== undefined) {
+            validateValueForMetadata(REGISTRY["modules.enabled"], m.enabled);
+        }
+        if (m.disabled !== undefined) {
+            validateValueForMetadata(REGISTRY["modules.disabled"], m.disabled);
         }
     }
     const improvement = data.improvement;

package/dist/core/index.d.ts

@@ -1,5 +1,7 @@
-export { ModuleRegistry, ModuleRegistryError, validateModuleSet, type ModuleRegistryOptions } from "./module-registry.js";
+export { ModuleRegistry, ModuleRegistryError, validateModuleSet, type ModuleActivationEntry, type ModuleActivationReport, type ModuleRegistryOptions } from "./module-registry.js";
+export { moduleRegistryOptionsFromEffectiveConfig, pickModuleContractWorkspacePath, resolveRegistryAndConfig } from "./module-registry-resolve.js";
 export { ModuleCommandRouter, ModuleCommandRouterError, type ModuleCommandDescriptor, type ModuleCommandRouterOptions } from "./module-command-router.js";
+export { buildAgentInstructionSurface, classifyInstructionExecution, isInstructionExecutableForRegistry, type AgentInstructionDegradation, type AgentInstructionSurfacePayload, type AgentInstructionSurfaceRow } from "./agent-instruction-surface.js";
 export { buildBaseConfigLayers, deepMerge, envToConfigOverlay, explainConfigPath, getAtPath, getProjectConfigPath, getUserConfigFilePath, KIT_CONFIG_DEFAULTS, loadUserLayer, mergeConfigLayers, MODULE_CONFIG_CONTRIBUTIONS, normalizeConfigForExport, PROJECT_CONFIG_REL, resolveWorkspaceConfigWithLayers, stableStringifyConfig, type ConfigLayer, type ConfigLayerId, type EffectiveWorkspaceConfig, type ExplainConfigResult, type ResolveWorkspaceConfigOptions } from "./workspace-kit-config.js";
 export { appendPolicyTrace, getExtraSensitiveModuleCommandsFromEffective, getOperationIdForCommand, isSensitiveModuleCommand, isSensitiveModuleCommandForEffective, parsePolicyApproval, parsePolicyApprovalFromEnv, POLICY_APPROVAL_HUMAN_DOC, POLICY_TRACE_SCHEMA_VERSION, resolveActor, resolvePolicyOperationIdForCommand, type PolicyOperationId, type PolicyTraceRecord, type PolicyTraceRecordInput } from "./policy.js";
 export { getSessionGrant, loadSessionPolicyDocument, recordSessionGrant, resolveSessionId, SESSION_POLICY_SCHEMA_VERSION, type SessionPolicyDocument, type SessionPolicyGrant } from "./session-policy.js";
@@ -13,4 +15,5 @@ export { appendConfigMutation, CONFIG_MUTATIONS_SCHEMA_VERSION, summarizeForEvid
 export { generateConfigReferenceDocs, runWorkspaceConfigCli, type ConfigCliIo } from "./config-cli.js";
 export { LINEAGE_SCHEMA_VERSION, lineageCorrelationRoot, type LineageAppPayload, type LineageCorrPayload, type LineageDecPayload, type LineageEvent, type LineageEventType, type LineageRecPayload } from "./lineage-contract.js";
 export { appendLineageEvent, newLineageEventId, queryLineageChain, readLineageEvents } from "./lineage-store.js";
+export { UnifiedStateDb, type ModuleStateRow } from "./state/unified-state-db.js";
 export type CoreRuntimeVersion = "0.1";

package/dist/core/index.js

@@ -1,5 +1,7 @@
 export { ModuleRegistry, ModuleRegistryError, validateModuleSet } from "./module-registry.js";
+export { moduleRegistryOptionsFromEffectiveConfig, pickModuleContractWorkspacePath, resolveRegistryAndConfig } from "./module-registry-resolve.js";
 export { ModuleCommandRouter, ModuleCommandRouterError } from "./module-command-router.js";
+export { buildAgentInstructionSurface, classifyInstructionExecution, isInstructionExecutableForRegistry } from "./agent-instruction-surface.js";
 export { buildBaseConfigLayers, deepMerge, envToConfigOverlay, explainConfigPath, getAtPath, getProjectConfigPath, getUserConfigFilePath, KIT_CONFIG_DEFAULTS, loadUserLayer, mergeConfigLayers, MODULE_CONFIG_CONTRIBUTIONS, normalizeConfigForExport, PROJECT_CONFIG_REL, resolveWorkspaceConfigWithLayers, stableStringifyConfig } from "./workspace-kit-config.js";
 export { appendPolicyTrace, getExtraSensitiveModuleCommandsFromEffective, getOperationIdForCommand, isSensitiveModuleCommand, isSensitiveModuleCommandForEffective, parsePolicyApproval, parsePolicyApprovalFromEnv, POLICY_APPROVAL_HUMAN_DOC, POLICY_TRACE_SCHEMA_VERSION, resolveActor, resolvePolicyOperationIdForCommand } from "./policy.js";
 export { getSessionGrant, loadSessionPolicyDocument, recordSessionGrant, resolveSessionId, SESSION_POLICY_SCHEMA_VERSION } from "./session-policy.js";
@@ -13,3 +15,4 @@ export { appendConfigMutation, CONFIG_MUTATIONS_SCHEMA_VERSION, summarizeForEvid
 export { generateConfigReferenceDocs, runWorkspaceConfigCli } from "./config-cli.js";
 export { LINEAGE_SCHEMA_VERSION, lineageCorrelationRoot } from "./lineage-contract.js";
 export { appendLineageEvent, newLineageEventId, queryLineageChain, readLineageEvents } from "./lineage-store.js";
+export { UnifiedStateDb } from "./state/unified-state-db.js";

package/dist/core/module-command-router.js

@@ -1,3 +1,4 @@
+import { classifyInstructionExecution, isInstructionExecutableForRegistry } from "./agent-instruction-surface.js";
 export class ModuleCommandRouterError extends Error {
     code;
     constructor(code, message) {
@@ -40,6 +41,19 @@ export class ModuleCommandRouter {
         if (!indexed.module.onCommand) {
             throw new ModuleCommandRouterError("command-not-implemented", `Module '${indexed.descriptor.moduleId}' does not implement onCommand for '${commandName}'`);
         }
+        if (!isInstructionExecutableForRegistry(indexed.module, indexed.entry, this.registry)) {
+            const deg = classifyInstructionExecution(indexed.module, indexed.entry, this.registry);
+            const detail = deg.kind === "peer_disabled"
+                ? `missing peers: ${deg.missingPeers.join(", ")}`
+                : deg.kind === "module_disabled"
+                    ? "owning module disabled"
+                    : "not executable";
+            return {
+                ok: false,
+                code: "peer-module-disabled",
+                message: `Command '${commandName}' is not executable (${detail}). Enable required modules or follow the instruction markdown for manual guidance. Instruction: ${indexed.descriptor.instructionFile}`
+            };
+        }
         const command = {
             name: commandName,
             args
@@ -49,6 +63,9 @@ export class ModuleCommandRouter {
     indexEnabledModuleCommands() {
         for (const module of this.registry.getEnabledModules()) {
             for (const entry of module.registration.instructions.entries) {
+                if (!isInstructionExecutableForRegistry(module, entry, this.registry)) {
+                    continue;
+                }
                 if (this.commands.has(entry.name)) {
                     const existing = this.commands.get(entry.name);
                     throw new ModuleCommandRouterError("duplicate-command", `Command '${entry.name}' is declared by both '${existing?.descriptor.moduleId}' and '${module.registration.id}'`);
@@ -60,7 +77,8 @@ export class ModuleCommandRouter {
                         instructionFile: `${module.registration.instructions.directory}/${entry.file}`,
                         description: entry.description
                     },
-                    module
+                    module,
+                    entry
                 });
             }
         }

package/dist/core/module-registry-resolve.d.ts

@@ -0,0 +1,27 @@
+import type { WorkflowModule } from "../contracts/module-contract.js";
+import { ModuleRegistry, type ModuleRegistryOptions } from "./module-registry.js";
+import { type ConfigLayer, type EffectiveWorkspaceConfig } from "./workspace-kit-config.js";
+/**
+ * Instruction paths in module registration are repo-relative. Use `workspacePath` when it
+ * contains the kit sources; otherwise fall back to `process.cwd()` (tests / ephemeral cwd).
+ */
+export declare function pickModuleContractWorkspacePath(workspacePath: string): string;
+/**
+ * Reads `modules.enabled` / `modules.disabled` from effective config and maps them
+ * to ModuleRegistryOptions. Unknown module ids throw — fail fast on typos.
+ *
+ * Semantics (matches resolveEnabledModuleIds):
+ * - If `modules.enabled` is non-empty: only those ids are candidates, then `modules.disabled` subtracts.
+ * - If `modules.enabled` is empty/absent: start from each module's enabledByDefault, then subtract disabled.
+ */
+export declare function moduleRegistryOptionsFromEffectiveConfig(effective: Record<string, unknown>, knownModuleIds: Set<string>): Pick<ModuleRegistryOptions, "enabledModules" | "disabledModules">;
+/**
+ * Resolves layered config together with module enablement toggles from that config.
+ * Iterates until the enabled module set stabilizes (module config contributions can
+ * change when modules drop out of startup order).
+ */
+export declare function resolveRegistryAndConfig(workspacePath: string, allModules: WorkflowModule[], invocationConfig?: Record<string, unknown>): Promise<{
+    registry: ModuleRegistry;
+    effective: EffectiveWorkspaceConfig;
+    layers: ConfigLayer[];
+}>;

package/dist/core/module-registry-resolve.js

@@ -0,0 +1,91 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { ModuleRegistry, ModuleRegistryError } from "./module-registry.js";
+import { resolveWorkspaceConfigWithLayers } from "./workspace-kit-config.js";
+/**
+ * Instruction paths in module registration are repo-relative. Use `workspacePath` when it
+ * contains the kit sources; otherwise fall back to `process.cwd()` (tests / ephemeral cwd).
+ */
+export function pickModuleContractWorkspacePath(workspacePath) {
+    const marker = resolve(workspacePath, "src/modules/task-engine/config.md");
+    if (existsSync(marker)) {
+        return workspacePath;
+    }
+    return process.cwd();
+}
+function readNonEmptyStringArray(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const out = value.filter((x) => typeof x === "string" && x.trim().length > 0);
+    return out.length > 0 ? out : undefined;
+}
+/**
+ * Reads `modules.enabled` / `modules.disabled` from effective config and maps them
+ * to ModuleRegistryOptions. Unknown module ids throw — fail fast on typos.
+ *
+ * Semantics (matches resolveEnabledModuleIds):
+ * - If `modules.enabled` is non-empty: only those ids are candidates, then `modules.disabled` subtracts.
+ * - If `modules.enabled` is empty/absent: start from each module's enabledByDefault, then subtract disabled.
+ */
+export function moduleRegistryOptionsFromEffectiveConfig(effective, knownModuleIds) {
+    const root = effective.modules;
+    if (root === undefined || root === null) {
+        return {};
+    }
+    if (typeof root !== "object" || Array.isArray(root)) {
+        throw new ModuleRegistryError("invalid-modules-config", "effectiveConfig.modules must be an object when present");
+    }
+    const mod = root;
+    const enabled = readNonEmptyStringArray(mod.enabled);
+    const disabled = readNonEmptyStringArray(mod.disabled);
+    for (const id of [...(enabled ?? []), ...(disabled ?? [])]) {
+        if (!knownModuleIds.has(id)) {
+            throw new ModuleRegistryError("unknown-module-in-config", `Unknown module id in modules.enabled / modules.disabled: '${id}'`);
+        }
+    }
+    return {
+        enabledModules: enabled,
+        disabledModules: disabled
+    };
+}
+function enabledSignature(registry) {
+    return registry
+        .getEnabledModules()
+        .map((m) => m.registration.id)
+        .sort()
+        .join(",");
+}
+/**
+ * Resolves layered config together with module enablement toggles from that config.
+ * Iterates until the enabled module set stabilizes (module config contributions can
+ * change when modules drop out of startup order).
+ */
+export async function resolveRegistryAndConfig(workspacePath, allModules, invocationConfig) {
+    const knownIds = new Set(allModules.map((m) => m.registration.id));
+    const moduleContractPath = pickModuleContractWorkspacePath(workspacePath);
+    let registry = new ModuleRegistry(allModules, { workspacePath: moduleContractPath });
+    for (let i = 0; i < 8; i++) {
+        const { effective, layers } = await resolveWorkspaceConfigWithLayers({
+            workspacePath,
+            registry,
+            invocationConfig
+        });
+        const extra = moduleRegistryOptionsFromEffectiveConfig(effective, knownIds);
+        const candidate = new ModuleRegistry(allModules, { workspacePath: moduleContractPath, ...extra });
+        if (enabledSignature(registry) === enabledSignature(candidate)) {
+            const fin = await resolveWorkspaceConfigWithLayers({
+                workspacePath,
+                registry: candidate,
+                invocationConfig
+            });
+            return {
+                registry: candidate,
+                effective: fin.effective,
+                layers: fin.layers
+            };
+        }
+        registry = candidate;
+    }
+    throw new ModuleRegistryError("module-enablement-unstable", "modules.enabled / modules.disabled did not stabilize after repeated config resolution; check config layers");
+}

package/dist/core/module-registry.d.ts

@@ -3,6 +3,18 @@ export declare class ModuleRegistryError extends Error {
     readonly code: string;
     constructor(code: string, message: string);
 }
+export type ModuleActivationEntry = {
+    moduleId: string;
+    enabled: boolean;
+    /** dependsOn entries not present in the enabled set (non-empty only if misconfigured). */
+    unsatisfiedHardDependencies: string[];
+    /** optionalPeers not currently enabled (informational). */
+    missingOptionalPeers: string[];
+};
+export type ModuleActivationReport = {
+    schemaVersion: 1;
+    modules: ModuleActivationEntry[];
+};
 export declare function validateModuleSet(modules: WorkflowModule[], workspacePath?: string): void;
 export type ModuleRegistryOptions = {
     enabledModules?: string[];
@@ -21,4 +33,6 @@ export declare class ModuleRegistry {
     isModuleEnabled(id: string): boolean;
     getEnabledModules(): WorkflowModule[];
     getStartupOrder(): WorkflowModule[];
+    /** Snapshot for doctor / tooling: enablement and peer satisfaction. */
+    getActivationReport(): ModuleActivationReport;
 }

package/dist/core/module-registry.js

@@ -32,6 +32,32 @@ function validateDependencies(moduleMap) {
         }
     }
 }
+function validateOptionalPeers(moduleMap) {
+    for (const module of moduleMap.values()) {
+        const moduleId = module.registration.id;
+        const peers = module.registration.optionalPeers ?? [];
+        const hard = new Set(module.registration.dependsOn);
+        for (const peerId of peers) {
+            if (peerId === moduleId) {
+                throw new ModuleRegistryError("self-optional-peer", `Module '${moduleId}' cannot list itself in optionalPeers`);
+            }
+            if (!moduleMap.has(peerId)) {
+                throw new ModuleRegistryError("missing-optional-peer", `Module '${moduleId}' lists unknown optional peer '${peerId}'`);
+            }
+            if (hard.has(peerId)) {
+                throw new ModuleRegistryError("optional-peer-overlap-dependsOn", `Module '${moduleId}' lists '${peerId}' in both dependsOn and optionalPeers`);
+            }
+        }
+    }
+}
+function validateRegistrationSchemas(moduleMap) {
+    for (const module of moduleMap.values()) {
+        const schema = module.registration.stateSchema;
+        if (!Number.isInteger(schema) || schema < 1) {
+            throw new ModuleRegistryError("invalid-state-schema", `Module '${module.registration.id}' must declare integer stateSchema >= 1`);
+        }
+    }
+}
 function topologicalSort(moduleMap) {
     const visited = new Set();
     const inStack = new Set();
@@ -139,12 +165,23 @@ function validateInstructionContracts(moduleMap, workspacePath) {
             if (!statSync(instructionFilePath).isFile()) {
                 throw new ModuleRegistryError("invalid-instruction-file", `Module '${id}' instruction path '${instructionFilePath}' is not a file`);
             }
+            const reqPeers = entry.requiresPeers ?? [];
+            for (const peerId of reqPeers) {
+                if (peerId === id) {
+                    throw new ModuleRegistryError("instruction-requires-self", `Module '${id}' instruction '${entry.name}' cannot list its own module id in requiresPeers`);
+                }
+                if (!moduleMap.has(peerId)) {
+                    throw new ModuleRegistryError("unknown-requires-peer", `Module '${id}' instruction '${entry.name}' lists unknown requiresPeers module '${peerId}'`);
+                }
+            }
         }
     }
 }
 export function validateModuleSet(modules, workspacePath) {
     const moduleMap = buildModuleMap(modules);
     validateDependencies(moduleMap);
+    validateOptionalPeers(moduleMap);
+    validateRegistrationSchemas(moduleMap);
     validateInstructionContracts(moduleMap, workspacePath ?? process.cwd());
     topologicalSort(moduleMap);
 }
@@ -157,6 +194,8 @@ export class ModuleRegistry {
     constructor(modules, options) {
         this.moduleMap = buildModuleMap(modules);
         validateDependencies(this.moduleMap);
+        validateOptionalPeers(this.moduleMap);
+        validateRegistrationSchemas(this.moduleMap);
         validateInstructionContracts(this.moduleMap, options?.workspacePath ?? process.cwd());
         this.modules = [...modules];
         const enabledModuleIds = resolveEnabledModuleIds(this.modules, options);
@@ -180,4 +219,22 @@ export class ModuleRegistry {
     getStartupOrder() {
         return [...this.sortedModules];
     }
+    /** Snapshot for doctor / tooling: enablement and peer satisfaction. */
+    getActivationReport() {
+        const enabledIds = new Set(this.enabledModuleMap.keys());
+        const modules = [];
+        for (const mod of this.modules) {
+            const id = mod.registration.id;
+            const optionalPeers = mod.registration.optionalPeers ?? [];
+            const missingOptionalPeers = optionalPeers.filter((p) => !enabledIds.has(p));
+            const unsatisfiedHardDependencies = mod.registration.dependsOn.filter((d) => !enabledIds.has(d));
+            modules.push({
+                moduleId: id,
+                enabled: enabledIds.has(id),
+                unsatisfiedHardDependencies,
+                missingOptionalPeers
+            });
+        }
+        return { schemaVersion: 1, modules };
+    }
 }

package/dist/core/planning/build-plan-session-file.d.ts

@@ -0,0 +1,29 @@
+/** Local operator snapshot so dashboards and agents can resume `build-plan` without re-entering answers. */
+export type BuildPlanSessionSnapshotV1 = {
+    schemaVersion: 1;
+    updatedAt: string;
+    planningType: string;
+    outputMode: string;
+    status: string;
+    completionPct: number;
+    answeredCritical: number;
+    totalCritical: number;
+    answers: Record<string, unknown>;
+    /** Single-line `workspace-kit run build-plan '…'` hint (shell-escaped JSON inside quotes is caller responsibility). */
+    resumeCli: string;
+};
+export type DashboardPlanningSessionV1 = {
+    schemaVersion: 1;
+    updatedAt: string;
+    planningType: string;
+    outputMode: string;
+    status: string;
+    completionPct: number;
+    answeredCritical: number;
+    totalCritical: number;
+    resumeCli: string;
+};
+export declare function persistBuildPlanSession(workspacePath: string, snapshot: Omit<BuildPlanSessionSnapshotV1, "schemaVersion" | "updatedAt">): Promise<void>;
+export declare function clearBuildPlanSession(workspacePath: string): Promise<void>;
+export declare function readBuildPlanSession(workspacePath: string): Promise<BuildPlanSessionSnapshotV1 | null>;
+export declare function toDashboardPlanningSession(snap: BuildPlanSessionSnapshotV1 | null): DashboardPlanningSessionV1 | null;

package/dist/core/planning/build-plan-session-file.js

@@ -0,0 +1,58 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+const REL_DIR = path.join(".workspace-kit", "planning");
+const FILE_NAME = "build-plan-session.json";
+function sessionPath(workspacePath) {
+    return path.join(workspacePath, REL_DIR, FILE_NAME);
+}
+export async function persistBuildPlanSession(workspacePath, snapshot) {
+    const dir = path.join(workspacePath, REL_DIR);
+    await fs.mkdir(dir, { recursive: true });
+    const full = {
+        schemaVersion: 1,
+        updatedAt: new Date().toISOString(),
+        ...snapshot
+    };
+    await fs.writeFile(sessionPath(workspacePath), `${JSON.stringify(full, null, 2)}\n`, "utf8");
+}
+export async function clearBuildPlanSession(workspacePath) {
+    try {
+        await fs.unlink(sessionPath(workspacePath));
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== "ENOENT")
+            throw err;
+    }
+}
+export async function readBuildPlanSession(workspacePath) {
+    try {
+        const raw = await fs.readFile(sessionPath(workspacePath), "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed?.schemaVersion !== 1 || typeof parsed.planningType !== "string") {
+            return null;
+        }
+        if (typeof parsed.resumeCli !== "string") {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export function toDashboardPlanningSession(snap) {
+    if (!snap)
+        return null;
+    return {
+        schemaVersion: 1,
+        updatedAt: snap.updatedAt,
+        planningType: snap.planningType,
+        outputMode: snap.outputMode,
+        status: snap.status,
+        completionPct: snap.completionPct,
+        answeredCritical: snap.answeredCritical,
+        totalCritical: snap.totalCritical,
+        resumeCli: snap.resumeCli
+    };
+}

package/dist/core/planning/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared planning-domain exports for cross-module consumers.
+ *
+ * **Planning persistence** (task + wishlist stores, SQLite/JSON) lives in `src/modules/task-engine/`.
+ * The **`planning` module** (`src/modules/planning/`) is the CLI interview surface (`build-plan`, …).
+ * This facade keeps non-task-engine modules from importing deep task-engine paths; implementations stay in task-engine.
+ */
+export { openPlanningStores } from "../../modules/task-engine/planning-open.js";
+export { TaskStore } from "../../modules/task-engine/store.js";
+export { WishlistStore } from "../../modules/task-engine/wishlist-store.js";
+export { TransitionService } from "../../modules/task-engine/service.js";
+export { validateKnownTaskTypeRequirements } from "../../modules/task-engine/task-type-validation.js";
+export { buildWishlistItemFromIntake, validateWishlistContentFields, validateWishlistIntakePayload, validateWishlistUpdatePayload, WISHLIST_ID_RE } from "../../modules/task-engine/wishlist-validation.js";
+export { allocateNextTaskNumericId, taskEntityFromNewIntake } from "../../modules/task-engine/wishlist-intake.js";
+export type { TaskEntity, TaskPriority, TaskStatus, TransitionEvidence, TransitionGuard, TransitionContext, GuardResult } from "../../modules/task-engine/types.js";
+export type { WishlistItem, WishlistStatus, WishlistConversionDecomposition } from "../../modules/task-engine/wishlist-types.js";
+export { persistBuildPlanSession, clearBuildPlanSession, readBuildPlanSession, toDashboardPlanningSession, type BuildPlanSessionSnapshotV1, type DashboardPlanningSessionV1 } from "./build-plan-session-file.js";

package/dist/core/planning/index.js

@@ -0,0 +1,15 @@
+/**
+ * Shared planning-domain exports for cross-module consumers.
+ *
+ * **Planning persistence** (task + wishlist stores, SQLite/JSON) lives in `src/modules/task-engine/`.
+ * The **`planning` module** (`src/modules/planning/`) is the CLI interview surface (`build-plan`, …).
+ * This facade keeps non-task-engine modules from importing deep task-engine paths; implementations stay in task-engine.
+ */
+export { openPlanningStores } from "../../modules/task-engine/planning-open.js";
+export { TaskStore } from "../../modules/task-engine/store.js";
+export { WishlistStore } from "../../modules/task-engine/wishlist-store.js";
+export { TransitionService } from "../../modules/task-engine/service.js";
+export { validateKnownTaskTypeRequirements } from "../../modules/task-engine/task-type-validation.js";
+export { buildWishlistItemFromIntake, validateWishlistContentFields, validateWishlistIntakePayload, validateWishlistUpdatePayload, WISHLIST_ID_RE } from "../../modules/task-engine/wishlist-validation.js";
+export { allocateNextTaskNumericId, taskEntityFromNewIntake } from "../../modules/task-engine/wishlist-intake.js";
+export { persistBuildPlanSession, clearBuildPlanSession, readBuildPlanSession, toDashboardPlanningSession } from "./build-plan-session-file.js";

package/dist/core/policy.js

@@ -1,19 +1,29 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { execFile } from "node:child_process";
+import { APPROVALS_POLICY_COMMAND_NAMES } from "../modules/approvals/policy-sensitive-commands.js";
+import { DOCUMENTATION_POLICY_COMMAND_NAMES } from "../modules/documentation/policy-sensitive-commands.js";
+import { IMPROVEMENT_POLICY_COMMAND_NAMES } from "../modules/improvement/policy-sensitive-commands.js";
+import { TASK_ENGINE_POLICY_COMMAND_NAMES } from "../modules/task-engine/policy-sensitive-commands.js";
 export const POLICY_TRACE_SCHEMA_VERSION = 1;
 /** Maintainer doc (repo-relative) linked from policy denial output for `workspace-kit run`. */
 export const POLICY_APPROVAL_HUMAN_DOC = "docs/maintainers/POLICY-APPROVAL.md";
 /** Maintainer doc: tier table + copy-paste patterns for agents (Tier A/B `run` vs CLI env approval). */
 export const AGENT_CLI_MAP_HUMAN_DOC = "docs/maintainers/AGENT-CLI-MAP.md";
-const COMMAND_TO_OPERATION = {
-    "document-project": "doc.document-project",
-    "generate-document": "doc.generate-document",
-    "run-transition": "tasks.run-transition",
-    "review-item": "approvals.review-item",
-    "generate-recommendations": "improvement.generate-recommendations",
-    "ingest-transcripts": "improvement.ingest-transcripts"
-};
+function buildBuiltinCommandToOperation() {
+    const pairs = [
+        ...DOCUMENTATION_POLICY_COMMAND_NAMES,
+        ...TASK_ENGINE_POLICY_COMMAND_NAMES,
+        ...APPROVALS_POLICY_COMMAND_NAMES,
+        ...IMPROVEMENT_POLICY_COMMAND_NAMES
+    ];
+    const out = {};
+    for (const [name, op] of pairs) {
+        out[name] = op;
+    }
+    return out;
+}
+const COMMAND_TO_OPERATION = buildBuiltinCommandToOperation();
 export function getOperationIdForCommand(commandName) {
     return COMMAND_TO_OPERATION[commandName];
 }

package/dist/core/state/unified-state-db.d.ts

@@ -0,0 +1,21 @@
+export type ModuleStateRow = {
+    moduleId: string;
+    stateSchemaVersion: number;
+    state: Record<string, unknown>;
+    updatedAt: string;
+};
+type UnifiedStateDbOptions = {
+    exportSnapshotRelativePath?: string;
+};
+export declare class UnifiedStateDb {
+    private db;
+    readonly dbPath: string;
+    readonly exportSnapshotPath: string | null;
+    constructor(workspacePath: string, databaseRelativePath: string, options?: UnifiedStateDbOptions);
+    private ensureDb;
+    getModuleState(moduleId: string): ModuleStateRow | null;
+    setModuleState(moduleId: string, stateSchemaVersion: number, state: Record<string, unknown>): void;
+    listModuleStates(): ModuleStateRow[];
+    private maybeExportSnapshot;
+}
+export {};