@workflow-cannon/workspace-kit 0.18.0 → 0.24.0

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

package/dist/core/state/unified-state-db.js

@@ -0,0 +1,80 @@
+import fs from "node:fs";
+import path from "node:path";
+import Database from "better-sqlite3";
+const DDL = `
+CREATE TABLE IF NOT EXISTS workspace_module_state (
+  module_id TEXT PRIMARY KEY,
+  state_schema_version INTEGER NOT NULL,
+  state_json TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+`;
+export class UnifiedStateDb {
+    db = null;
+    dbPath;
+    exportSnapshotPath;
+    constructor(workspacePath, databaseRelativePath, options) {
+        this.dbPath = path.resolve(workspacePath, databaseRelativePath);
+        this.exportSnapshotPath = options?.exportSnapshotRelativePath
+            ? path.resolve(workspacePath, options.exportSnapshotRelativePath)
+            : null;
+    }
+    ensureDb() {
+        if (this.db)
+            return this.db;
+        fs.mkdirSync(path.dirname(this.dbPath), { recursive: true });
+        this.db = new Database(this.dbPath);
+        this.db.pragma("journal_mode = WAL");
+        this.db.exec(DDL);
+        return this.db;
+    }
+    getModuleState(moduleId) {
+        const db = this.ensureDb();
+        const row = db
+            .prepare("SELECT module_id, state_schema_version, state_json, updated_at FROM workspace_module_state WHERE module_id = ?")
+            .get(moduleId);
+        if (!row)
+            return null;
+        return {
+            moduleId: row.module_id,
+            stateSchemaVersion: row.state_schema_version,
+            state: JSON.parse(row.state_json),
+            updatedAt: row.updated_at
+        };
+    }
+    setModuleState(moduleId, stateSchemaVersion, state) {
+        const db = this.ensureDb();
+        const updatedAt = new Date().toISOString();
+        db.prepare(`INSERT INTO workspace_module_state (module_id, state_schema_version, state_json, updated_at)
+       VALUES (?, ?, ?, ?)
+       ON CONFLICT(module_id) DO UPDATE SET
+         state_schema_version=excluded.state_schema_version,
+         state_json=excluded.state_json,
+         updated_at=excluded.updated_at`).run(moduleId, stateSchemaVersion, JSON.stringify(state), updatedAt);
+        this.maybeExportSnapshot();
+    }
+    listModuleStates() {
+        const db = this.ensureDb();
+        const rows = db
+            .prepare("SELECT module_id, state_schema_version, state_json, updated_at FROM workspace_module_state ORDER BY module_id ASC")
+            .all();
+        return rows.map((row) => ({
+            moduleId: row.module_id,
+            stateSchemaVersion: row.state_schema_version,
+            state: JSON.parse(row.state_json),
+            updatedAt: row.updated_at
+        }));
+    }
+    maybeExportSnapshot() {
+        if (!this.exportSnapshotPath)
+            return;
+        const snapshot = {
+            schemaVersion: 1,
+            exportedAt: new Date().toISOString(),
+            dbPath: this.dbPath,
+            modules: this.listModuleStates()
+        };
+        fs.mkdirSync(path.dirname(this.exportSnapshotPath), { recursive: true });
+        fs.writeFileSync(this.exportSnapshotPath, JSON.stringify(snapshot, null, 2) + "\n", "utf8");
+    }
+}

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

@@ -10,6 +10,14 @@ export function getProjectConfigPath(workspacePath) {
 /** Built-in defaults (lowest layer). */
 export const KIT_CONFIG_DEFAULTS = {
     core: {},
+    /**
+     * Module enablement: `enabled` whitelist (non-empty replaces default-by-flag set), then `disabled` subtracts.
+     * Empty arrays = no effect (all modules use registration.enabledByDefault).
+     */
+    modules: {
+        enabled: [],
+        disabled: []
+    },
     tasks: {
         storeRelativePath: ".workspace-kit/tasks/state.json",
         strictValidation: false

package/dist/modules/agent-behavior/builtins.d.ts

@@ -0,0 +1,3 @@
+import { type BehaviorProfile } from "./types.js";
+export declare const DEFAULT_BUILTIN_PROFILE_ID = "builtin:balanced";
+export declare const BUILTIN_PROFILES: Record<string, BehaviorProfile>;

package/dist/modules/agent-behavior/builtins.js

@@ -0,0 +1,71 @@
+import { BEHAVIOR_PROFILE_SCHEMA_VERSION } from "./types.js";
+export const DEFAULT_BUILTIN_PROFILE_ID = "builtin:balanced";
+const nowMeta = () => ({
+    source: "builtin",
+    createdAt: new Date().toISOString()
+});
+export const BUILTIN_PROFILES = {
+    "builtin:cautious": {
+        schemaVersion: BEHAVIOR_PROFILE_SCHEMA_VERSION,
+        id: "builtin:cautious",
+        label: "Cautious",
+        summary: "Prefer small steps, frequent check-ins, and explicit confirmation before larger edits.",
+        dimensions: {
+            deliberationDepth: "high",
+            changeAppetite: "conservative",
+            checkInFrequency: "often",
+            explanationVerbosity: "verbose",
+            explorationStyle: "linear",
+            ambiguityHandling: "ask"
+        },
+        interactionNotes: "Surface risks early; default to the smallest reversible change.",
+        metadata: nowMeta()
+    },
+    "builtin:balanced": {
+        schemaVersion: BEHAVIOR_PROFILE_SCHEMA_VERSION,
+        id: "builtin:balanced",
+        label: "Balanced",
+        summary: "Default collaboration: clear reasoning, normal autonomy when intent is clear.",
+        dimensions: {
+            deliberationDepth: "medium",
+            changeAppetite: "balanced",
+            checkInFrequency: "normal",
+            explanationVerbosity: "normal",
+            explorationStyle: "linear",
+            ambiguityHandling: "ask"
+        },
+        metadata: nowMeta()
+    },
+    "builtin:calculated": {
+        schemaVersion: BEHAVIOR_PROFILE_SCHEMA_VERSION,
+        id: "builtin:calculated",
+        label: "Calculated",
+        summary: "Structured analysis and explicit tradeoffs before acting; still respects governance.",
+        dimensions: {
+            deliberationDepth: "high",
+            changeAppetite: "balanced",
+            checkInFrequency: "normal",
+            explanationVerbosity: "verbose",
+            explorationStyle: "linear",
+            ambiguityHandling: "ask"
+        },
+        interactionNotes: "Lay out options with pros/cons; prefer evidence-backed recommendations.",
+        metadata: nowMeta()
+    },
+    "builtin:experimental": {
+        schemaVersion: BEHAVIOR_PROFILE_SCHEMA_VERSION,
+        id: "builtin:experimental",
+        label: "Experimental",
+        summary: "Try alternatives and parallel approaches in low-risk areas; still obey policy gates.",
+        dimensions: {
+            deliberationDepth: "medium",
+            changeAppetite: "bold",
+            checkInFrequency: "normal",
+            explanationVerbosity: "normal",
+            explorationStyle: "parallel",
+            ambiguityHandling: "decide"
+        },
+        interactionNotes: "Experimental does not mean skipping tests, approvals, or PRINCIPLES—only style of exploration.",
+        metadata: nowMeta()
+    }
+};

package/dist/modules/agent-behavior/explain.d.ts

@@ -0,0 +1,6 @@
+import type { BehaviorProfile } from "./types.js";
+export declare function summarizeProfileMarkdown(profile: BehaviorProfile): string;
+export declare function diffProfiles(a: BehaviorProfile, b: BehaviorProfile): Record<string, {
+    from: string;
+    to: string;
+}>;