@workflow-cannon/workspace-kit 0.2.0 → 0.4.0

package/README.md

@@ -61,9 +61,9 @@ This keeps automation adaptive without sacrificing safety, governance, or develo
 
 ## Current Status
 
-- Project tracking has been reset for split-repo execution.
-- Current execution phase is **Phase 0 (foundation)**.
-- Phase 0 opens with `T178` to `T180` for release hardening and consumer cadence definition.
+- **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 3** (enhancement loop MVP, `v0.5.0`) is next (`T190` onward).
 
 ## Goals
 

package/dist/cli.js

@@ -2,6 +2,16 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
+import { ModuleRegistry } from "./core/module-registry.js";
+import { ModuleCommandRouter } from "./core/module-command-router.js";
+import { appendPolicyTrace, getOperationIdForCommand, isSensitiveModuleCommand, parsePolicyApproval, parsePolicyApprovalFromEnv, resolveActor } from "./core/policy.js";
+import { resolveWorkspaceConfigWithLayers } from "./core/workspace-kit-config.js";
+import { documentationModule } from "./modules/documentation/index.js";
+import { taskEngineModule } from "./modules/task-engine/index.js";
+import { approvalsModule } from "./modules/approvals/index.js";
+import { planningModule } from "./modules/planning/index.js";
+import { improvementModule } from "./modules/improvement/index.js";
+import { workspaceConfigModule } from "./modules/workspace-config/index.js";
 const EXIT_SUCCESS = 0;
 const EXIT_VALIDATION_FAILURE = 1;
 const EXIT_USAGE_ERROR = 2;
@@ -87,6 +97,33 @@ export async function parseJsonFile(filePath) {
     const raw = await fs.readFile(filePath, "utf8");
     return JSON.parse(raw);
 }
+async function requireCliPolicyApproval(cwd, operationId, commandLabel, writeError) {
+    const approval = parsePolicyApprovalFromEnv(process.env);
+    if (!approval) {
+        writeError(`workspace-kit ${commandLabel} requires WORKSPACE_KIT_POLICY_APPROVAL with JSON {"confirmed":true,"rationale":"..."} (agent-mediated).`);
+        await appendPolicyTrace(cwd, {
+            timestamp: new Date().toISOString(),
+            operationId,
+            command: commandLabel,
+            actor: resolveActor(cwd, {}, process.env),
+            allowed: false,
+            message: "missing WORKSPACE_KIT_POLICY_APPROVAL"
+        });
+        return null;
+    }
+    return { rationale: approval.rationale };
+}
+async function recordCliPolicySuccess(cwd, operationId, commandLabel, rationale, commandOk) {
+    await appendPolicyTrace(cwd, {
+        timestamp: new Date().toISOString(),
+        operationId,
+        command: commandLabel,
+        actor: resolveActor(cwd, {}, process.env),
+        allowed: true,
+        rationale,
+        commandOk
+    });
+}
 function readStringField(objectValue, key, errors, fieldPath) {
     const value = objectValue[key];
     if (typeof value !== "string" || value.trim().length === 0) {
@@ -305,12 +342,17 @@ export async function runCli(args, options = {}) {
     const writeError = options.writeError ?? console.error;
     const [command] = args;
     if (!command) {
-        writeError("Usage: workspace-kit <init|doctor|check|upgrade>");
+        writeError("Usage: workspace-kit <init|doctor|check|upgrade|drift-check|run>");
         return EXIT_USAGE_ERROR;
     }
     if (command === "init") {
+        const approval = await requireCliPolicyApproval(cwd, "cli.init", "init", writeError);
+        if (!approval) {
+            return EXIT_VALIDATION_FAILURE;
+        }
         const { errors, profile } = await validateProfile(cwd);
         if (errors.length > 0 || !profile) {
+            await recordCliPolicySuccess(cwd, "cli.init", "init", approval.rationale, false);
             writeError("workspace-kit init failed profile validation.");
             for (const error of errors) {
                 writeError(`- ${error}`);
@@ -321,6 +363,7 @@ export async function runCli(args, options = {}) {
         writeLine("workspace-kit init generated profile-driven project context artifacts.");
         writeLine(`- ${path.relative(cwd, artifacts.generatedJsonPath)}`);
         writeLine(`- ${path.relative(cwd, artifacts.generatedRulePath)}`);
+        await recordCliPolicySuccess(cwd, "cli.init", "init", approval.rationale, true);
         return EXIT_SUCCESS;
     }
     if (command === "check") {
@@ -337,8 +380,13 @@ export async function runCli(args, options = {}) {
         return EXIT_SUCCESS;
     }
     if (command === "upgrade") {
+        const approval = await requireCliPolicyApproval(cwd, "cli.upgrade", "upgrade", writeError);
+        if (!approval) {
+            return EXIT_VALIDATION_FAILURE;
+        }
         const { errors, profile } = await validateProfile(cwd);
         if (errors.length > 0 || !profile) {
+            await recordCliPolicySuccess(cwd, "cli.upgrade", "upgrade", approval.rationale, false);
             writeError("workspace-kit upgrade failed profile validation.");
             for (const error of errors) {
                 writeError(`- ${error}`);
@@ -437,6 +485,7 @@ export async function runCli(args, options = {}) {
             }
         }
         writeLine(`Backups written under: ${path.relative(cwd, backupRoot)}`);
+        await recordCliPolicySuccess(cwd, "cli.upgrade", "upgrade", approval.rationale, true);
         return EXIT_SUCCESS;
     }
     if (command === "drift-check") {
@@ -525,8 +574,125 @@ export async function runCli(args, options = {}) {
         }
         return EXIT_SUCCESS;
     }
+    if (command === "run") {
+        const allModules = [
+            workspaceConfigModule,
+            documentationModule,
+            taskEngineModule,
+            approvalsModule,
+            planningModule,
+            improvementModule
+        ];
+        const registry = new ModuleRegistry(allModules);
+        const router = new ModuleCommandRouter(registry);
+        const subcommand = args[1];
+        if (!subcommand) {
+            const commands = router.listCommands();
+            writeLine("Available module commands:");
+            for (const cmd of commands) {
+                const desc = cmd.description ? ` — ${cmd.description}` : "";
+                writeLine(`  ${cmd.name} (${cmd.moduleId})${desc}`);
+            }
+            writeLine("");
+            writeLine("Usage: workspace-kit run <command> [json-args]");
+            return EXIT_SUCCESS;
+        }
+        let commandArgs = {};
+        if (args[2]) {
+            try {
+                const parsed = JSON.parse(args[2]);
+                if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                    commandArgs = parsed;
+                }
+                else {
+                    writeError("Command args must be a JSON object.");
+                    return EXIT_USAGE_ERROR;
+                }
+            }
+            catch {
+                writeError(`Invalid JSON args: ${args[2]}`);
+                return EXIT_USAGE_ERROR;
+            }
+        }
+        const invocationConfig = typeof commandArgs.config === "object" &&
+            commandArgs.config !== null &&
+            !Array.isArray(commandArgs.config)
+            ? commandArgs.config
+            : {};
+        let effective;
+        try {
+            const resolved = await resolveWorkspaceConfigWithLayers({
+                workspacePath: cwd,
+                registry,
+                invocationConfig
+            });
+            effective = resolved.effective;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            writeError(`Config resolution failed: ${message}`);
+            return EXIT_VALIDATION_FAILURE;
+        }
+        const actor = resolveActor(cwd, commandArgs, process.env);
+        const sensitive = isSensitiveModuleCommand(subcommand, commandArgs);
+        if (sensitive) {
+            const approval = parsePolicyApproval(commandArgs);
+            if (!approval) {
+                const op = getOperationIdForCommand(subcommand);
+                if (op) {
+                    await appendPolicyTrace(cwd, {
+                        timestamp: new Date().toISOString(),
+                        operationId: op,
+                        command: `run ${subcommand}`,
+                        actor,
+                        allowed: false,
+                        message: "missing policyApproval in JSON args"
+                    });
+                }
+                writeLine(JSON.stringify({
+                    ok: false,
+                    code: "policy-denied",
+                    message: 'Sensitive command requires policyApproval in JSON args: {"policyApproval":{"confirmed":true,"rationale":"user approved in chat"}}'
+                }, null, 2));
+                return EXIT_VALIDATION_FAILURE;
+            }
+        }
+        const ctx = {
+            runtimeVersion: "0.1",
+            workspacePath: cwd,
+            effectiveConfig: effective,
+            resolvedActor: actor,
+            moduleRegistry: registry
+        };
+        try {
+            const result = await router.execute(subcommand, commandArgs, ctx);
+            if (sensitive) {
+                const approval = parsePolicyApproval(commandArgs);
+                const op = getOperationIdForCommand(subcommand);
+                if (approval && op) {
+                    await appendPolicyTrace(cwd, {
+                        timestamp: new Date().toISOString(),
+                        operationId: op,
+                        command: `run ${subcommand}`,
+                        actor,
+                        allowed: true,
+                        rationale: approval.rationale,
+                        commandOk: result.ok,
+                        message: result.message
+                    });
+                }
+            }
+            writeLine(JSON.stringify(result, null, 2));
+            return result.ok ? EXIT_SUCCESS : EXIT_VALIDATION_FAILURE;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            writeError(`Module command failed: ${message}`);
+            return EXIT_INTERNAL_ERROR;
+        }
+    }
     if (command !== "doctor") {
-        writeError(`Unknown command '${command}'. Supported commands: init, doctor, check, upgrade, drift-check.`);
+        writeError(`Unknown command '${command}'. Supported commands: init, doctor, check, upgrade, drift-check, run.`);
         return EXIT_USAGE_ERROR;
     }
     const issues = [];

package/dist/contracts/index.d.ts

@@ -1 +1 @@
-export type { ModuleCommand, ModuleCommandResult, ModuleCapability, ModuleDocumentContract, ModuleEvent, ModuleInstructionContract, ModuleInstructionEntry, ModuleLifecycleContext, ModuleRegistration, WorkflowModule } from "./module-contract.js";
+export type { ConfigRegistryView, ModuleCommand, ModuleCommandResult, ModuleCapability, ModuleDocumentContract, ModuleEvent, ModuleInstructionContract, ModuleInstructionEntry, ModuleLifecycleContext, ModuleRegistration, WorkflowModule } from "./module-contract.js";

package/dist/contracts/module-contract.d.ts

@@ -36,9 +36,23 @@ export type ModuleCommandResult = {
     message?: string;
     data?: Record<string, unknown>;
 };
+/** Subset of module registry used for config layer ordering (avoids core↔contracts cycles). */
+export type ConfigRegistryView = {
+    getStartupOrder(): ReadonlyArray<{
+        registration: {
+            id: string;
+        };
+    }>;
+};
 export type ModuleLifecycleContext = {
     runtimeVersion: string;
     workspacePath: string;
+    /** Merged workspace config (kit → modules → project → env → invocation). */
+    effectiveConfig?: Record<string, unknown>;
+    /** Resolved actor for policy traces (see phase2 workbook). */
+    resolvedActor?: string;
+    /** CLI supplies registry for explain-config and config resolution. */
+    moduleRegistry?: ConfigRegistryView;
 };
 export type ModuleRegistration = {
     id: string;

package/dist/core/index.d.ts

@@ -1,3 +1,5 @@
 export { ModuleRegistry, ModuleRegistryError, validateModuleSet, type ModuleRegistryOptions } from "./module-registry.js";
 export { ModuleCommandRouter, ModuleCommandRouterError, type ModuleCommandDescriptor, type ModuleCommandRouterOptions } from "./module-command-router.js";
+export { buildBaseConfigLayers, deepMerge, envToConfigOverlay, explainConfigPath, getAtPath, KIT_CONFIG_DEFAULTS, mergeConfigLayers, MODULE_CONFIG_CONTRIBUTIONS, resolveWorkspaceConfigWithLayers, type ConfigLayer, type ConfigLayerId, type EffectiveWorkspaceConfig, type ExplainConfigResult, type ResolveWorkspaceConfigOptions } from "./workspace-kit-config.js";
+export { appendPolicyTrace, getOperationIdForCommand, isSensitiveModuleCommand, parsePolicyApproval, parsePolicyApprovalFromEnv, resolveActor, type PolicyOperationId, type PolicyTraceRecord } from "./policy.js";
 export type CoreRuntimeVersion = "0.1";

package/dist/core/index.js

@@ -1,2 +1,4 @@
 export { ModuleRegistry, ModuleRegistryError, validateModuleSet } from "./module-registry.js";
 export { ModuleCommandRouter, ModuleCommandRouterError } from "./module-command-router.js";
+export { buildBaseConfigLayers, deepMerge, envToConfigOverlay, explainConfigPath, getAtPath, KIT_CONFIG_DEFAULTS, mergeConfigLayers, MODULE_CONFIG_CONTRIBUTIONS, resolveWorkspaceConfigWithLayers } from "./workspace-kit-config.js";
+export { appendPolicyTrace, getOperationIdForCommand, isSensitiveModuleCommand, parsePolicyApproval, parsePolicyApprovalFromEnv, resolveActor } from "./policy.js";

package/dist/core/policy.d.ts

@@ -0,0 +1,24 @@
+export type PolicyOperationId = "cli.upgrade" | "cli.init" | "doc.document-project" | "doc.generate-document" | "tasks.import-tasks" | "tasks.generate-tasks-md" | "tasks.run-transition";
+export declare function getOperationIdForCommand(commandName: string): PolicyOperationId | undefined;
+/**
+ * Sensitive when mutation / write is possible. Documentation commands are exempt when dryRun is true.
+ */
+export declare function isSensitiveModuleCommand(commandName: string, args: Record<string, unknown>): boolean;
+export type PolicyApprovalPayload = {
+    confirmed: boolean;
+    rationale: string;
+};
+export declare function parsePolicyApprovalFromEnv(env: NodeJS.ProcessEnv): PolicyApprovalPayload | undefined;
+export declare function parsePolicyApproval(args: Record<string, unknown>): PolicyApprovalPayload | undefined;
+export declare function resolveActor(workspacePath: string, args: Record<string, unknown>, env: NodeJS.ProcessEnv): string;
+export type PolicyTraceRecord = {
+    timestamp: string;
+    operationId: PolicyOperationId;
+    command: string;
+    actor: string;
+    allowed: boolean;
+    rationale?: string;
+    commandOk?: boolean;
+    message?: string;
+};
+export declare function appendPolicyTrace(workspacePath: string, record: PolicyTraceRecord): Promise<void>;

package/dist/core/policy.js

@@ -0,0 +1,102 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { execSync } from "node:child_process";
+const COMMAND_TO_OPERATION = {
+    "document-project": "doc.document-project",
+    "generate-document": "doc.generate-document",
+    "import-tasks": "tasks.import-tasks",
+    "generate-tasks-md": "tasks.generate-tasks-md",
+    "run-transition": "tasks.run-transition"
+};
+export function getOperationIdForCommand(commandName) {
+    return COMMAND_TO_OPERATION[commandName];
+}
+/**
+ * Sensitive when mutation / write is possible. Documentation commands are exempt when dryRun is true.
+ */
+export function isSensitiveModuleCommand(commandName, args) {
+    const op = COMMAND_TO_OPERATION[commandName];
+    if (!op)
+        return false;
+    if (op === "doc.document-project" || op === "doc.generate-document") {
+        const options = typeof args.options === "object" && args.options !== null
+            ? args.options
+            : {};
+        if (options.dryRun === true) {
+            return false;
+        }
+    }
+    return true;
+}
+export function parsePolicyApprovalFromEnv(env) {
+    const raw = env.WORKSPACE_KIT_POLICY_APPROVAL?.trim();
+    if (!raw)
+        return undefined;
+    try {
+        const o = JSON.parse(raw);
+        if (o.confirmed !== true)
+            return undefined;
+        const rationale = typeof o.rationale === "string" ? o.rationale.trim() : "";
+        if (!rationale)
+            return undefined;
+        return { confirmed: true, rationale };
+    }
+    catch {
+        return undefined;
+    }
+}
+export function parsePolicyApproval(args) {
+    const raw = args.policyApproval;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        return undefined;
+    }
+    const o = raw;
+    const confirmed = o.confirmed === true;
+    const rationale = typeof o.rationale === "string" ? o.rationale.trim() : "";
+    if (!confirmed || rationale.length === 0) {
+        return undefined;
+    }
+    return { confirmed, rationale };
+}
+export function resolveActor(workspacePath, args, env) {
+    if (typeof args.actor === "string" && args.actor.trim().length > 0) {
+        return args.actor.trim();
+    }
+    const fromEnv = env.WORKSPACE_KIT_ACTOR?.trim();
+    if (fromEnv)
+        return fromEnv;
+    try {
+        const email = execSync("git config user.email", {
+            cwd: workspacePath,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"]
+        }).trim();
+        if (email)
+            return email;
+    }
+    catch {
+        /* ignore */
+    }
+    try {
+        const name = execSync("git config user.name", {
+            cwd: workspacePath,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"]
+        }).trim();
+        if (name)
+            return name;
+    }
+    catch {
+        /* ignore */
+    }
+    return "unknown";
+}
+const POLICY_DIR = ".workspace-kit/policy";
+const TRACE_FILE = "traces.jsonl";
+export async function appendPolicyTrace(workspacePath, record) {
+    const dir = path.join(workspacePath, POLICY_DIR);
+    const fp = path.join(workspacePath, POLICY_DIR, TRACE_FILE);
+    const line = `${JSON.stringify(record)}\n`;
+    await fs.mkdir(dir, { recursive: true });
+    await fs.appendFile(fp, line, "utf8");
+}

package/dist/core/workspace-kit-config.d.ts

@@ -0,0 +1,49 @@
+import type { ConfigRegistryView } from "../contracts/module-contract.js";
+export type ConfigLayerId = "kit-default" | `module:${string}` | "project" | "env" | "invocation";
+export type ConfigLayer = {
+    id: ConfigLayerId;
+    data: Record<string, unknown>;
+};
+/** Effective workspace config: domain keys + optional modules map (project file). */
+export type EffectiveWorkspaceConfig = Record<string, unknown>;
+/** Built-in defaults (lowest layer). */
+export declare const KIT_CONFIG_DEFAULTS: Record<string, unknown>;
+/**
+ * Static module-level defaults keyed by module id (merged in registry startup order).
+ * Each value is deep-merged into the aggregate before project/env/invocation.
+ */
+export declare const MODULE_CONFIG_CONTRIBUTIONS: Record<string, Record<string, unknown>>;
+export declare function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown>;
+export declare function getAtPath(root: Record<string, unknown>, dotted: string): unknown;
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+/**
+ * Parse WORKSPACE_KIT_* env into a nested object (double-underscore → path under domains).
+ * Example: WORKSPACE_KIT_TASKS__STORE_PATH -> { tasks: { storeRelativePath: "..." } }
+ * Uses segment after prefix; known domain prefix sets first key.
+ */
+export declare function envToConfigOverlay(env: NodeJS.ProcessEnv): Record<string, unknown>;
+/** Kit defaults + module contributions (topological order). Project/env/invocation added separately. */
+export declare function buildBaseConfigLayers(registry: ConfigRegistryView): ConfigLayer[];
+export declare function loadProjectLayer(workspacePath: string): Promise<ConfigLayer>;
+export declare function mergeConfigLayers(layers: ConfigLayer[]): Record<string, unknown>;
+export type ResolveWorkspaceConfigOptions = {
+    workspacePath: string;
+    registry: ConfigRegistryView;
+    env?: NodeJS.ProcessEnv;
+    /** Merged last (from `workspace-kit run` top-level `config` key). */
+    invocationConfig?: Record<string, unknown>;
+};
+export declare function resolveWorkspaceConfigWithLayers(options: ResolveWorkspaceConfigOptions): Promise<{
+    effective: EffectiveWorkspaceConfig;
+    layers: ConfigLayer[];
+}>;
+export type ExplainConfigResult = {
+    path: string;
+    effectiveValue: unknown;
+    winningLayer: ConfigLayerId;
+    alternates: {
+        layer: ConfigLayerId;
+        value: unknown;
+    }[];
+};
+export declare function explainConfigPath(dottedPath: string, layers: ConfigLayer[]): ExplainConfigResult;

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

@@ -0,0 +1,218 @@
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+const PROJECT_CONFIG_REL = ".workspace-kit/config.json";
+/** Built-in defaults (lowest layer). */
+export const KIT_CONFIG_DEFAULTS = {
+    core: {},
+    tasks: {
+        storeRelativePath: ".workspace-kit/tasks/state.json"
+    },
+    documentation: {}
+};
+/**
+ * Static module-level defaults keyed by module id (merged in registry startup order).
+ * Each value is deep-merged into the aggregate before project/env/invocation.
+ */
+export const MODULE_CONFIG_CONTRIBUTIONS = {
+    "task-engine": {
+        tasks: {
+            storeRelativePath: ".workspace-kit/tasks/state.json"
+        }
+    },
+    documentation: {
+        documentation: {}
+    },
+    approvals: {},
+    planning: {},
+    improvement: {}
+};
+export function deepMerge(target, source) {
+    const out = { ...target };
+    for (const [k, v] of Object.entries(source)) {
+        if (v !== null && typeof v === "object" && !Array.isArray(v)) {
+            const prev = out[k];
+            const prevObj = prev !== null && typeof prev === "object" && !Array.isArray(prev)
+                ? prev
+                : {};
+            out[k] = deepMerge(prevObj, v);
+        }
+        else {
+            out[k] = v;
+        }
+    }
+    return out;
+}
+function cloneDeep(obj) {
+    return JSON.parse(JSON.stringify(obj));
+}
+export function getAtPath(root, dotted) {
+    const parts = dotted.split(".").filter(Boolean);
+    let cur = root;
+    for (const p of parts) {
+        if (cur === null || cur === undefined || typeof cur !== "object" || Array.isArray(cur)) {
+            return undefined;
+        }
+        cur = cur[p];
+    }
+    return cur;
+}
+export function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null || typeof a !== "object" || typeof b !== "object") {
+        return false;
+    }
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length)
+            return false;
+        return a.every((v, i) => deepEqual(v, b[i]));
+    }
+    const ak = Object.keys(a).sort();
+    const bk = Object.keys(b).sort();
+    if (ak.length !== bk.length)
+        return false;
+    for (let i = 0; i < ak.length; i++) {
+        if (ak[i] !== bk[i])
+            return false;
+    }
+    for (const k of ak) {
+        if (!deepEqual(a[k], b[k])) {
+            return false;
+        }
+    }
+    return true;
+}
+async function readProjectConfigFile(workspacePath) {
+    const fp = path.join(workspacePath, PROJECT_CONFIG_REL);
+    if (!existsSync(fp)) {
+        return {};
+    }
+    const raw = await fs.readFile(fp, "utf8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("config-invalid: .workspace-kit/config.json must be a JSON object");
+    }
+    const obj = parsed;
+    if (obj.schemaVersion !== undefined && typeof obj.schemaVersion !== "number") {
+        throw new Error("config-invalid: schemaVersion must be a number when present");
+    }
+    return obj;
+}
+/**
+ * Parse WORKSPACE_KIT_* env into a nested object (double-underscore → path under domains).
+ * Example: WORKSPACE_KIT_TASKS__STORE_PATH -> { tasks: { storeRelativePath: "..." } }
+ * Uses segment after prefix; known domain prefix sets first key.
+ */
+export function envToConfigOverlay(env) {
+    const prefix = "WORKSPACE_KIT_";
+    const out = {};
+    for (const [key, val] of Object.entries(env)) {
+        if (!key.startsWith(prefix) || val === undefined)
+            continue;
+        const rest = key.slice(prefix.length);
+        if (!rest || rest === "ACTOR")
+            continue;
+        const segments = rest.split("__").map((s) => camelCaseEnvSegment(s));
+        if (segments.length === 0)
+            continue;
+        setDeep(out, segments, coerceEnvValue(val));
+    }
+    return out;
+}
+function camelCaseEnvSegment(s) {
+    const lower = s.toLowerCase().replace(/_/g, "");
+    // tasks -> tasks; STORE_PATH segments already split — first segment may be TASKS
+    if (lower === "tasks")
+        return "tasks";
+    if (lower === "documentation")
+        return "documentation";
+    if (lower === "core")
+        return "core";
+    // e.g. STORE_PATH -> storePath
+    return s
+        .toLowerCase()
+        .split("_")
+        .filter(Boolean)
+        .map((w, i) => (i === 0 ? w : w.charAt(0).toUpperCase() + w.slice(1)))
+        .join("");
+}
+function setDeep(target, segments, value) {
+    let cur = target;
+    for (let i = 0; i < segments.length - 1; i++) {
+        const seg = segments[i];
+        const next = cur[seg];
+        if (next === undefined || typeof next !== "object" || Array.isArray(next)) {
+            cur[seg] = {};
+        }
+        cur = cur[seg];
+    }
+    cur[segments[segments.length - 1]] = value;
+}
+function coerceEnvValue(val) {
+    if (val === "true")
+        return true;
+    if (val === "false")
+        return false;
+    if (/^-?\d+$/.test(val))
+        return Number(val);
+    return val;
+}
+/** Kit defaults + module contributions (topological order). Project/env/invocation added separately. */
+export function buildBaseConfigLayers(registry) {
+    const layers = [];
+    layers.push({ id: "kit-default", data: cloneDeep(KIT_CONFIG_DEFAULTS) });
+    for (const mod of registry.getStartupOrder()) {
+        const contrib = MODULE_CONFIG_CONTRIBUTIONS[mod.registration.id];
+        if (contrib && Object.keys(contrib).length > 0) {
+            layers.push({ id: `module:${mod.registration.id}`, data: cloneDeep(contrib) });
+        }
+    }
+    return layers;
+}
+export async function loadProjectLayer(workspacePath) {
+    const data = await readProjectConfigFile(workspacePath);
+    return { id: "project", data };
+}
+export function mergeConfigLayers(layers) {
+    let acc = {};
+    for (const layer of layers) {
+        acc = deepMerge(acc, layer.data);
+    }
+    return acc;
+}
+export async function resolveWorkspaceConfigWithLayers(options) {
+    const { workspacePath, registry, env = process.env, invocationConfig } = options;
+    const layers = [...buildBaseConfigLayers(registry)];
+    layers.push(await loadProjectLayer(workspacePath));
+    layers.push({ id: "env", data: envToConfigOverlay(env) });
+    if (invocationConfig && Object.keys(invocationConfig).length > 0) {
+        layers.push({ id: "invocation", data: cloneDeep(invocationConfig) });
+    }
+    return { effective: mergeConfigLayers(layers), layers };
+}
+export function explainConfigPath(dottedPath, layers) {
+    const mergedFull = mergeConfigLayers(layers);
+    const effectiveValue = getAtPath(mergedFull, dottedPath);
+    let winningLayer = "kit-default";
+    let prevMerged = {};
+    for (let i = 0; i < layers.length; i++) {
+        const slice = layers.slice(0, i + 1);
+        const nextMerged = mergeConfigLayers(slice);
+        const prevVal = getAtPath(prevMerged, dottedPath);
+        const nextVal = getAtPath(nextMerged, dottedPath);
+        if (!deepEqual(prevVal, nextVal)) {
+            winningLayer = layers[i].id;
+        }
+        prevMerged = nextMerged;
+    }
+    const alternates = [];
+    for (let i = 0; i < layers.length; i++) {
+        const slice = layers.slice(0, i + 1);
+        const m = mergeConfigLayers(slice);
+        alternates.push({ layer: layers[i].id, value: getAtPath(m, dottedPath) });
+    }
+    return { path: dottedPath, effectiveValue, winningLayer, alternates };
+}