@workflow-cannon/workspace-kit 0.4.0 → 0.4.1

package/README.md

@@ -63,7 +63,7 @@ This keeps automation adaptive without sacrificing safety, governance, or develo
 
 - **Phase 0** and **Phase 1** (task engine, `v0.3.0`) are complete.
 - **Phase 2** (layered config, policy gates, cutover docs, `v0.4.0`) is complete in-repo; see `docs/maintainers/TASKS.md` and `docs/maintainers/ROADMAP.md`.
-- **Phase 3** (enhancement loop MVP, `v0.5.0`) is next (`T190` onward).
+- **Phase 2b** (policy + config UX, `v0.4.1`) is complete in-repo. **Phase 3** (enhancement loop MVP, `v0.5.0`) is next (`T190` onward).
 
 ## Goals
 

package/dist/cli.js

@@ -4,7 +4,8 @@ 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 { appendPolicyTrace, isSensitiveModuleCommandForEffective, parsePolicyApproval, parsePolicyApprovalFromEnv, resolveActor, resolvePolicyOperationIdForCommand } from "./core/policy.js";
+import { runWorkspaceConfigCli } from "./core/config-cli.js";
 import { resolveWorkspaceConfigWithLayers } from "./core/workspace-kit-config.js";
 import { documentationModule } from "./modules/documentation/index.js";
 import { taskEngineModule } from "./modules/task-engine/index.js";
@@ -342,9 +343,12 @@ 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|drift-check|run>");
+        writeError("Usage: workspace-kit <init|doctor|check|upgrade|drift-check|run|config>");
         return EXIT_USAGE_ERROR;
     }
+    if (command === "config") {
+        return runWorkspaceConfigCli(cwd, args.slice(1), { writeLine, writeError });
+    }
     if (command === "init") {
         const approval = await requireCliPolicyApproval(cwd, "cli.init", "init", writeError);
         if (!approval) {
@@ -634,11 +638,11 @@ export async function runCli(args, options = {}) {
             return EXIT_VALIDATION_FAILURE;
         }
         const actor = resolveActor(cwd, commandArgs, process.env);
-        const sensitive = isSensitiveModuleCommand(subcommand, commandArgs);
+        const sensitive = isSensitiveModuleCommandForEffective(subcommand, commandArgs, effective);
         if (sensitive) {
             const approval = parsePolicyApproval(commandArgs);
             if (!approval) {
-                const op = getOperationIdForCommand(subcommand);
+                const op = resolvePolicyOperationIdForCommand(subcommand, effective);
                 if (op) {
                     await appendPolicyTrace(cwd, {
                         timestamp: new Date().toISOString(),
@@ -668,7 +672,7 @@ export async function runCli(args, options = {}) {
             const result = await router.execute(subcommand, commandArgs, ctx);
             if (sensitive) {
                 const approval = parsePolicyApproval(commandArgs);
-                const op = getOperationIdForCommand(subcommand);
+                const op = resolvePolicyOperationIdForCommand(subcommand, effective);
                 if (approval && op) {
                     await appendPolicyTrace(cwd, {
                         timestamp: new Date().toISOString(),
@@ -692,7 +696,7 @@ export async function runCli(args, options = {}) {
         }
     }
     if (command !== "doctor") {
-        writeError(`Unknown command '${command}'. Supported commands: init, doctor, check, upgrade, drift-check, run.`);
+        writeError(`Unknown command '${command}'. Supported commands: init, doctor, check, upgrade, drift-check, run, config.`);
         return EXIT_USAGE_ERROR;
     }
     const issues = [];

package/dist/core/config-cli.d.ts

@@ -0,0 +1,6 @@
+export type ConfigCliIo = {
+    writeLine: (s: string) => void;
+    writeError: (s: string) => void;
+};
+export declare function generateConfigReferenceDocs(workspacePath: string): Promise<void>;
+export declare function runWorkspaceConfigCli(cwd: string, argv: string[], io: ConfigCliIo): Promise<number>;

package/dist/core/config-cli.js

@@ -0,0 +1,479 @@
+import fs from "node:fs/promises";
+import { createInterface } from "node:readline/promises";
+import { stdin as processStdin, stdout as processStdout } from "node:process";
+import path from "node:path";
+import { ModuleRegistry } from "./module-registry.js";
+import { appendPolicyTrace, parsePolicyApprovalFromEnv, resolveActor } from "./policy.js";
+import { appendConfigMutation, summarizeForEvidence } from "./config-mutations.js";
+import { assertWritableKey, getConfigKeyMetadata, listConfigMetadata, validatePersistedConfigDocument, validateValueForMetadata } from "./config-metadata.js";
+import { explainConfigPath, getAtPath, getProjectConfigPath, getUserConfigFilePath, resolveWorkspaceConfigWithLayers, stableStringifyConfig } from "./workspace-kit-config.js";
+import { workspaceConfigModule } from "../modules/workspace-config/index.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";
+const EXIT_SUCCESS = 0;
+const EXIT_VALIDATION_FAILURE = 1;
+const EXIT_USAGE_ERROR = 2;
+const EXIT_INTERNAL_ERROR = 3;
+function cloneCfg(obj) {
+    return JSON.parse(JSON.stringify(obj));
+}
+function setDeep(root, dotted, value) {
+    const out = cloneCfg(root);
+    const parts = dotted.split(".").filter(Boolean);
+    let cur = out;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const p = parts[i];
+        const next = cur[p];
+        if (next === undefined || typeof next !== "object" || Array.isArray(next)) {
+            cur[p] = {};
+        }
+        cur = cur[p];
+    }
+    cur[parts[parts.length - 1]] = value;
+    return out;
+}
+function unsetDeep(root, dotted) {
+    const out = cloneCfg(root);
+    const parts = dotted.split(".").filter(Boolean);
+    if (parts.length === 0)
+        return out;
+    const parents = [out];
+    let cur = out;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const p = parts[i];
+        const next = cur[p];
+        if (next === undefined || typeof next !== "object" || Array.isArray(next)) {
+            return out;
+        }
+        cur = next;
+        parents.push(cur);
+    }
+    const leaf = parts[parts.length - 1];
+    delete cur[leaf];
+    // Prune empty objects bottom-up
+    for (let i = parents.length - 1; i >= 1; i--) {
+        const childKey = parts[i - 1];
+        const parent = parents[i - 1];
+        const child = parent[childKey];
+        if (child &&
+            typeof child === "object" &&
+            !Array.isArray(child) &&
+            Object.keys(child).length === 0) {
+            delete parent[childKey];
+        }
+    }
+    return out;
+}
+async function readJsonFileOrEmpty(fp) {
+    try {
+        const raw = await fs.readFile(fp, "utf8");
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error(`invalid JSON object: ${fp}`);
+        }
+        return parsed;
+    }
+    catch (e) {
+        const err = e;
+        if (err.code === "ENOENT") {
+            return {};
+        }
+        throw e;
+    }
+}
+async function writeConfigFileAtomic(fp, data) {
+    await fs.mkdir(path.dirname(fp), { recursive: true });
+    const tmp = `${fp}.${process.pid}.${Date.now()}.tmp`;
+    await fs.writeFile(tmp, stableStringifyConfig(data), "utf8");
+    await fs.rename(tmp, fp);
+}
+function buildRegistry() {
+    const allModules = [
+        workspaceConfigModule,
+        documentationModule,
+        taskEngineModule,
+        approvalsModule,
+        planningModule,
+        improvementModule
+    ];
+    return new ModuleRegistry(allModules);
+}
+function parseConfigArgs(argv) {
+    const json = argv.includes("--json");
+    const parts = argv.filter((a) => a !== "--json");
+    return { json, parts };
+}
+async function requireConfigApproval(cwd, commandLabel, writeError) {
+    const approval = parsePolicyApprovalFromEnv(process.env);
+    if (!approval) {
+        writeError(`${commandLabel} requires WORKSPACE_KIT_POLICY_APPROVAL with JSON {"confirmed":true,"rationale":"..."}.`);
+        await appendPolicyTrace(cwd, {
+            timestamp: new Date().toISOString(),
+            operationId: "cli.config-mutate",
+            command: commandLabel,
+            actor: resolveActor(cwd, {}, process.env),
+            allowed: false,
+            message: "missing WORKSPACE_KIT_POLICY_APPROVAL"
+        });
+        return null;
+    }
+    return approval;
+}
+export async function generateConfigReferenceDocs(workspacePath) {
+    const meta = listConfigMetadata({ exposure: "maintainer" });
+    const aiPath = path.join(workspacePath, ".ai", "CONFIG.md");
+    const humanPath = path.join(workspacePath, "docs", "maintainers", "CONFIG.md");
+    const lines = (audience) => {
+        const out = [
+            `# Config reference (${audience})`,
+            "",
+            "Generated from `src/core/config-metadata.ts`. Do not edit by hand; run `workspace-kit config generate-docs`.",
+            "",
+            "| Key | Type | Default | Scope | Module | Exposure | Sensitive | Approval |",
+            "| --- | --- | --- | --- | --- | --- | --- | --- |"
+        ];
+        for (const m of meta) {
+            out.push(`| ${m.key} | ${m.type} | ${JSON.stringify(m.default)} | ${m.domainScope} | ${m.owningModule} | ${m.exposure} | ${m.sensitive} | ${m.requiresApproval} |`);
+            out.push("");
+            out.push(`**Description:** ${m.description}`);
+            out.push("");
+        }
+        return out;
+    };
+    await fs.mkdir(path.dirname(aiPath), { recursive: true });
+    await fs.mkdir(path.dirname(humanPath), { recursive: true });
+    await fs.writeFile(aiPath, lines("ai").join("\n") + "\n", "utf8");
+    await fs.writeFile(humanPath, lines("human").join("\n") + "\n", "utf8");
+}
+export async function runWorkspaceConfigCli(cwd, argv, io) {
+    const { writeLine, writeError } = io;
+    const { json, parts } = parseConfigArgs(argv);
+    const sub = parts[0];
+    const tail = parts.slice(1);
+    if (!sub) {
+        writeError("Usage: workspace-kit config <list|get|set|unset|explain|validate|resolve|generate-docs|edit> [--json] ...");
+        return EXIT_USAGE_ERROR;
+    }
+    let registry;
+    try {
+        registry = buildRegistry();
+    }
+    catch (e) {
+        writeError(e instanceof Error ? e.message : String(e));
+        return EXIT_INTERNAL_ERROR;
+    }
+    const emit = (obj) => {
+        writeLine(JSON.stringify(obj, null, json ? 2 : undefined));
+    };
+    try {
+        if (sub === "list") {
+            const all = tail.includes("--all");
+            const exposure = all ? "maintainer" : "public";
+            const rows = listConfigMetadata({ exposure });
+            if (json) {
+                emit({ ok: true, code: "config-list", data: { keys: rows } });
+            }
+            else {
+                writeLine("Known config keys:");
+                for (const r of rows) {
+                    writeLine(`  ${r.key} (${r.type}) — ${r.description}`);
+                }
+            }
+            return EXIT_SUCCESS;
+        }
+        if (sub === "get") {
+            const key = tail[0];
+            if (!key) {
+                writeError("config get <key>");
+                return EXIT_USAGE_ERROR;
+            }
+            const { effective } = await resolveWorkspaceConfigWithLayers({
+                workspacePath: cwd,
+                registry
+            });
+            const val = getAtPath(effective, key);
+            if (json) {
+                emit({ ok: true, code: "config-get", data: { key, value: val } });
+            }
+            else {
+                writeLine(String(JSON.stringify({ key, value: val }, null, 2)));
+            }
+            return EXIT_SUCCESS;
+        }
+        if (sub === "resolve") {
+            const { effective } = await resolveWorkspaceConfigWithLayers({
+                workspacePath: cwd,
+                registry
+            });
+            writeLine(stableStringifyConfig(effective).trimEnd());
+            return EXIT_SUCCESS;
+        }
+        if (sub === "validate") {
+            const projectPath = getProjectConfigPath(cwd);
+            const userPath = getUserConfigFilePath();
+            const p = await readJsonFileOrEmpty(projectPath);
+            const u = await readJsonFileOrEmpty(userPath);
+            validatePersistedConfigDocument(p, ".workspace-kit/config.json");
+            validatePersistedConfigDocument(u, "user config");
+            await resolveWorkspaceConfigWithLayers({ workspacePath: cwd, registry });
+            if (json) {
+                emit({ ok: true, code: "config-validated", data: { projectPath, userPath } });
+            }
+            else {
+                writeLine("Config validate passed (project + user + merged resolution).");
+            }
+            return EXIT_SUCCESS;
+        }
+        if (sub === "explain") {
+            const key = tail[0];
+            if (!key) {
+                writeError("config explain <key>");
+                return EXIT_USAGE_ERROR;
+            }
+            const { layers } = await resolveWorkspaceConfigWithLayers({
+                workspacePath: cwd,
+                registry
+            });
+            const explained = explainConfigPath(key, layers);
+            const meta = getConfigKeyMetadata(key);
+            const data = {
+                ...explained,
+                metadata: meta ?? null
+            };
+            if (json) {
+                emit({ ok: true, code: "config-explained", data });
+            }
+            else {
+                writeLine(JSON.stringify(data, null, 2));
+            }
+            return EXIT_SUCCESS;
+        }
+        if (sub === "generate-docs") {
+            await generateConfigReferenceDocs(cwd);
+            if (json) {
+                emit({ ok: true, code: "config-docs-generated", data: { ai: ".ai/CONFIG.md", human: "docs/maintainers/CONFIG.md" } });
+            }
+            else {
+                writeLine("Wrote .ai/CONFIG.md and docs/maintainers/CONFIG.md");
+            }
+            return EXIT_SUCCESS;
+        }
+        if (sub === "set") {
+            let scope = "project";
+            const args = [...tail];
+            if (args[0] === "--scope" && args[1]) {
+                scope = args[1];
+                if (scope !== "project" && scope !== "user") {
+                    writeError("--scope must be project or user");
+                    return EXIT_USAGE_ERROR;
+                }
+                args.splice(0, 2);
+            }
+            const key = args[0];
+            const jsonLiteral = args[1];
+            if (!key || jsonLiteral === undefined) {
+                writeError('config set [--scope project|user] <key> <jsonValue> e.g. \'".workspace-kit/tasks/state.json"\'');
+                return EXIT_USAGE_ERROR;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(jsonLiteral);
+            }
+            catch {
+                writeError("config set: jsonValue must be valid JSON");
+                return EXIT_USAGE_ERROR;
+            }
+            const meta = assertWritableKey(key);
+            if (!meta.writableLayers.includes(scope)) {
+                writeError(`config set: key '${key}' cannot be written to layer '${scope}'`);
+                return EXIT_VALIDATION_FAILURE;
+            }
+            validateValueForMetadata(meta, parsed);
+            if (meta.requiresApproval || meta.sensitive) {
+                const approval = await requireConfigApproval(cwd, `config set ${key}`, writeError);
+                if (!approval)
+                    return EXIT_VALIDATION_FAILURE;
+            }
+            const fp = scope === "project" ? getProjectConfigPath(cwd) : getUserConfigFilePath();
+            const before = await readJsonFileOrEmpty(fp);
+            validatePersistedConfigDocument(before, scope === "project" ? ".workspace-kit/config.json" : "user config");
+            const prevVal = getAtPath(before, key);
+            const next = setDeep(before, key, parsed);
+            validatePersistedConfigDocument(next, scope === "project" ? ".workspace-kit/config.json" : "user config");
+            const actor = resolveActor(cwd, {}, process.env);
+            try {
+                await writeConfigFileAtomic(fp, next);
+                await appendConfigMutation(cwd, {
+                    timestamp: new Date().toISOString(),
+                    actor,
+                    key,
+                    layer: scope,
+                    operation: "set",
+                    ok: true,
+                    previousSummary: summarizeForEvidence(key, meta.sensitive, prevVal),
+                    nextSummary: summarizeForEvidence(key, meta.sensitive, parsed)
+                });
+                if (meta.requiresApproval || meta.sensitive) {
+                    const appr = parsePolicyApprovalFromEnv(process.env);
+                    await appendPolicyTrace(cwd, {
+                        timestamp: new Date().toISOString(),
+                        operationId: "cli.config-mutate",
+                        command: `config set ${key}`,
+                        actor,
+                        allowed: true,
+                        rationale: appr.rationale,
+                        commandOk: true
+                    });
+                }
+                if (json) {
+                    emit({ ok: true, code: "config-set", data: { key, scope } });
+                }
+                else {
+                    writeLine(`Set ${key} on ${scope} layer.`);
+                }
+                return EXIT_SUCCESS;
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                await appendConfigMutation(cwd, {
+                    timestamp: new Date().toISOString(),
+                    actor,
+                    key,
+                    layer: scope,
+                    operation: "set",
+                    ok: false,
+                    code: "config-set-failed",
+                    message: msg
+                });
+                writeError(msg);
+                return EXIT_VALIDATION_FAILURE;
+            }
+        }
+        if (sub === "unset") {
+            let scope = "project";
+            const args = [...tail];
+            if (args[0] === "--scope" && args[1]) {
+                scope = args[1];
+                args.splice(0, 2);
+            }
+            const key = args[0];
+            if (!key) {
+                writeError("config unset [--scope project|user] <key>");
+                return EXIT_USAGE_ERROR;
+            }
+            const meta = assertWritableKey(key);
+            if (!meta.writableLayers.includes(scope)) {
+                writeError(`config unset: key '${key}' not in layer '${scope}'`);
+                return EXIT_VALIDATION_FAILURE;
+            }
+            if (meta.requiresApproval || meta.sensitive) {
+                const approval = await requireConfigApproval(cwd, `config unset ${key}`, writeError);
+                if (!approval)
+                    return EXIT_VALIDATION_FAILURE;
+            }
+            const fp = scope === "project" ? getProjectConfigPath(cwd) : getUserConfigFilePath();
+            const before = await readJsonFileOrEmpty(fp);
+            validatePersistedConfigDocument(before, scope === "project" ? ".workspace-kit/config.json" : "user config");
+            const prevVal = getAtPath(before, key);
+            const next = unsetDeep(before, key);
+            validatePersistedConfigDocument(next, scope === "project" ? ".workspace-kit/config.json" : "user config");
+            const actor = resolveActor(cwd, {}, process.env);
+            try {
+                if (Object.keys(next).length === 0) {
+                    await fs.rm(fp, { force: true });
+                }
+                else {
+                    await writeConfigFileAtomic(fp, next);
+                }
+                await appendConfigMutation(cwd, {
+                    timestamp: new Date().toISOString(),
+                    actor,
+                    key,
+                    layer: scope,
+                    operation: "unset",
+                    ok: true,
+                    previousSummary: summarizeForEvidence(key, meta.sensitive, prevVal),
+                    nextSummary: summarizeForEvidence(key, meta.sensitive, undefined)
+                });
+                if (meta.requiresApproval || meta.sensitive) {
+                    const appr = parsePolicyApprovalFromEnv(process.env);
+                    await appendPolicyTrace(cwd, {
+                        timestamp: new Date().toISOString(),
+                        operationId: "cli.config-mutate",
+                        command: `config unset ${key}`,
+                        actor,
+                        allowed: true,
+                        rationale: appr.rationale,
+                        commandOk: true
+                    });
+                }
+                if (json) {
+                    emit({ ok: true, code: "config-unset", data: { key, scope } });
+                }
+                else {
+                    writeLine(`Unset ${key} on ${scope} layer.`);
+                }
+                return EXIT_SUCCESS;
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                await appendConfigMutation(cwd, {
+                    timestamp: new Date().toISOString(),
+                    actor,
+                    key,
+                    layer: scope,
+                    operation: "unset",
+                    ok: false,
+                    message: msg
+                });
+                writeError(msg);
+                return EXIT_VALIDATION_FAILURE;
+            }
+        }
+        if (sub === "edit") {
+            if (!processStdin.isTTY) {
+                writeError("config edit requires an interactive TTY");
+                return EXIT_USAGE_ERROR;
+            }
+            const metaList = listConfigMetadata({ exposure: "public" });
+            writeLine("Select a key (number):");
+            metaList.forEach((m, i) => writeLine(`  ${i + 1}. ${m.key} — ${m.description}`));
+            const rl = createInterface({ input: processStdin, output: processStdout });
+            const choice = await rl.question("> ");
+            rl.close();
+            const n = Number.parseInt(choice.trim(), 10);
+            if (!Number.isFinite(n) || n < 1 || n > metaList.length) {
+                writeError("Invalid selection");
+                return EXIT_USAGE_ERROR;
+            }
+            const meta = metaList[n - 1];
+            const { effective } = await resolveWorkspaceConfigWithLayers({ workspacePath: cwd, registry });
+            const current = getAtPath(effective, meta.key);
+            writeLine(`Current: ${JSON.stringify(current)} Default: ${JSON.stringify(meta.default)}`);
+            const rl2 = createInterface({ input: processStdin, output: processStdout });
+            const raw = await rl2.question("New JSON value: ");
+            rl2.close();
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                writeError("Invalid JSON");
+                return EXIT_USAGE_ERROR;
+            }
+            validateValueForMetadata(meta, parsed);
+            const scope = meta.writableLayers.includes("project") ? "project" : "user";
+            return runWorkspaceConfigCli(cwd, ["set", "--scope", scope, meta.key, JSON.stringify(parsed)], io);
+        }
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        writeError(msg);
+        return EXIT_VALIDATION_FAILURE;
+    }
+    writeError(`Unknown config subcommand '${sub}'`);
+    return EXIT_USAGE_ERROR;
+}

package/dist/core/config-metadata.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Canonical metadata for user-facing workspace config keys (Phase 2b).
+ * CLI, explain, and generated docs consume this registry.
+ */
+export type ConfigKeyExposure = "public" | "maintainer" | "internal";
+export type ConfigValueType = "string" | "boolean" | "number" | "object" | "array";
+export type ConfigKeyMetadata = {
+    key: string;
+    type: ConfigValueType;
+    description: string;
+    default: unknown;
+    /** If set, value must equal one of these (after type coercion). */
+    allowedValues?: unknown[];
+    domainScope: "project" | "user" | "runtime" | "internal";
+    owningModule: string;
+    sensitive: boolean;
+    requiresRestart: boolean;
+    requiresApproval: boolean;
+    exposure: ConfigKeyExposure;
+    /** Persisted layers that may store this key */
+    writableLayers: ("project" | "user")[];
+};
+declare const REGISTRY: Record<string, ConfigKeyMetadata>;
+export declare function getConfigKeyMetadata(key: string): ConfigKeyMetadata | undefined;
+export declare function listConfigMetadata(options?: {
+    exposure?: "public" | "maintainer" | "internal" | "all";
+}): ConfigKeyMetadata[];
+export declare function assertWritableKey(key: string): ConfigKeyMetadata;
+export declare function validateValueForMetadata(meta: ConfigKeyMetadata, value: unknown): void;
+/**
+ * Validate top-level shape of persisted kit config files (strict unknown-key rejection).
+ */
+export declare function validatePersistedConfigDocument(data: Record<string, unknown>, label: string): void;
+export declare function getConfigRegistryExport(): typeof REGISTRY;
+export {};

package/dist/core/config-metadata.js

@@ -0,0 +1,162 @@
+/**
+ * Canonical metadata for user-facing workspace config keys (Phase 2b).
+ * CLI, explain, and generated docs consume this registry.
+ */
+const REGISTRY = {
+    "tasks.storeRelativePath": {
+        key: "tasks.storeRelativePath",
+        type: "string",
+        description: "Relative path (from workspace root) to the task engine JSON state file.",
+        default: ".workspace-kit/tasks/state.json",
+        domainScope: "project",
+        owningModule: "task-engine",
+        sensitive: false,
+        requiresRestart: false,
+        requiresApproval: false,
+        exposure: "public",
+        writableLayers: ["project", "user"]
+    },
+    "policy.extraSensitiveModuleCommands": {
+        key: "policy.extraSensitiveModuleCommands",
+        type: "array",
+        description: "Additional module command names (e.g. run subcommands) treated as sensitive for policy approval.",
+        default: [],
+        domainScope: "project",
+        owningModule: "workspace-kit",
+        sensitive: true,
+        requiresRestart: false,
+        requiresApproval: true,
+        exposure: "maintainer",
+        writableLayers: ["project"]
+    }
+};
+export function getConfigKeyMetadata(key) {
+    return REGISTRY[key];
+}
+export function listConfigMetadata(options) {
+    const exposure = options?.exposure ?? "public";
+    const order = ["public", "maintainer", "internal"];
+    const maxIdx = exposure === "all" ? 2 : order.indexOf(exposure);
+    const allowed = maxIdx < 0 ? new Set(["public"]) : new Set(order.slice(0, maxIdx + 1));
+    return Object.values(REGISTRY)
+        .filter((m) => allowed.has(m.exposure))
+        .sort((a, b) => a.key.localeCompare(b.key));
+}
+export function assertWritableKey(key) {
+    const meta = REGISTRY[key];
+    if (!meta) {
+        const err = new Error(`config-unknown-key: '${key}' is not a registered config key`);
+        err.code = "config-unknown-key";
+        throw err;
+    }
+    if (meta.exposure === "internal") {
+        const err = new Error(`config-internal-key: '${key}' is internal and not user-writable`);
+        err.code = "config-internal-key";
+        throw err;
+    }
+    return meta;
+}
+export function validateValueForMetadata(meta, value) {
+    if (meta.type === "array") {
+        if (!Array.isArray(value)) {
+            throw typeError(meta.key, "array", value);
+        }
+        if (meta.key === "policy.extraSensitiveModuleCommands") {
+            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") {
+        throw typeError(meta.key, "string", value);
+    }
+    if (meta.type === "boolean" && typeof value !== "boolean") {
+        throw typeError(meta.key, "boolean", value);
+    }
+    if (meta.type === "number" && typeof value !== "number") {
+        throw typeError(meta.key, "number", value);
+    }
+    if (meta.type === "object") {
+        if (value === null || typeof value !== "object" || Array.isArray(value)) {
+            throw typeError(meta.key, "object", value);
+        }
+    }
+    if (meta.allowedValues && meta.allowedValues.length > 0) {
+        if (!meta.allowedValues.some((v) => deepEqualLoose(v, value))) {
+            throw new Error(`config-constraint(${meta.key}): value not in allowed set: ${JSON.stringify(meta.allowedValues)}`);
+        }
+    }
+}
+function typeError(key, expected, got) {
+    return new Error(`config-type-error(${key}): expected ${expected}, got ${got === null ? "null" : typeof got}`);
+}
+function deepEqualLoose(a, b) {
+    if (a === b)
+        return true;
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+/**
+ * Validate top-level shape of persisted kit config files (strict unknown-key rejection).
+ */
+export function validatePersistedConfigDocument(data, label) {
+    const allowed = new Set(["schemaVersion", "core", "tasks", "documentation", "policy", "modules"]);
+    for (const k of Object.keys(data)) {
+        if (!allowed.has(k)) {
+            throw new Error(`config-invalid(${label}): unknown top-level key '${k}'`);
+        }
+    }
+    if (data.schemaVersion !== undefined && typeof data.schemaVersion !== "number") {
+        throw new Error(`config-invalid(${label}): schemaVersion must be a number`);
+    }
+    const tasks = data.tasks;
+    if (tasks !== undefined) {
+        if (typeof tasks !== "object" || tasks === null || Array.isArray(tasks)) {
+            throw new Error(`config-invalid(${label}): tasks must be an object`);
+        }
+        const t = tasks;
+        for (const k of Object.keys(t)) {
+            if (k !== "storeRelativePath") {
+                throw new Error(`config-invalid(${label}): unknown tasks.${k}`);
+            }
+        }
+    }
+    const policy = data.policy;
+    if (policy !== undefined) {
+        if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
+            throw new Error(`config-invalid(${label}): policy must be an object`);
+        }
+        const p = policy;
+        for (const k of Object.keys(p)) {
+            if (k !== "extraSensitiveModuleCommands") {
+                throw new Error(`config-invalid(${label}): unknown policy.${k}`);
+            }
+        }
+        if (p.extraSensitiveModuleCommands !== undefined) {
+            validateValueForMetadata(REGISTRY["policy.extraSensitiveModuleCommands"], p.extraSensitiveModuleCommands);
+        }
+    }
+    const core = data.core;
+    if (core !== undefined) {
+        if (typeof core !== "object" || core === null || Array.isArray(core) || Object.keys(core).length > 0) {
+            throw new Error(`config-invalid(${label}): core must be an empty object when present`);
+        }
+    }
+    const doc = data.documentation;
+    if (doc !== undefined) {
+        if (typeof doc !== "object" || doc === null || Array.isArray(doc) || Object.keys(doc).length > 0) {
+            throw new Error(`config-invalid(${label}): documentation must be an empty object when present`);
+        }
+    }
+    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`);
+        }
+    }
+}
+export function getConfigRegistryExport() {
+    return REGISTRY;
+}

package/dist/core/config-mutations.d.ts

@@ -0,0 +1,18 @@
+export declare const CONFIG_MUTATIONS_SCHEMA_VERSION: 1;
+export type ConfigMutationRecord = {
+    schemaVersion: typeof CONFIG_MUTATIONS_SCHEMA_VERSION;
+    timestamp: string;
+    actor: string;
+    key: string;
+    layer: "project" | "user";
+    operation: "set" | "unset";
+    ok: boolean;
+    code?: string;
+    message?: string;
+    previousSummary?: string;
+    nextSummary?: string;
+};
+export declare function appendConfigMutation(workspacePath: string, record: Omit<ConfigMutationRecord, "schemaVersion"> & {
+    schemaVersion?: number;
+}): Promise<void>;
+export declare function summarizeForEvidence(key: string, sensitive: boolean, value: unknown): string;

package/dist/core/config-mutations.js

@@ -0,0 +1,32 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+export const CONFIG_MUTATIONS_SCHEMA_VERSION = 1;
+const CONFIG_DIR = ".workspace-kit/config";
+const MUTATIONS_FILE = "mutations.jsonl";
+function summarizeValue(key, value) {
+    if (value === undefined)
+        return "(unset)";
+    if (key === "policy.extraSensitiveModuleCommands" && Array.isArray(value)) {
+        return `array(len=${value.length})`;
+    }
+    if (typeof value === "string") {
+        return `string(len=${value.length})`;
+    }
+    return typeof value;
+}
+export async function appendConfigMutation(workspacePath, record) {
+    const dir = path.join(workspacePath, CONFIG_DIR);
+    const fp = path.join(dir, MUTATIONS_FILE);
+    const line = `${JSON.stringify({
+        schemaVersion: CONFIG_MUTATIONS_SCHEMA_VERSION,
+        ...record
+    })}\n`;
+    await fs.mkdir(dir, { recursive: true });
+    await fs.appendFile(fp, line, "utf8");
+}
+export function summarizeForEvidence(key, sensitive, value) {
+    if (sensitive) {
+        return value === undefined ? "(unset)" : "(redacted)";
+    }
+    return summarizeValue(key, value);
+}

package/dist/core/index.d.ts

@@ -1,5 +1,8 @@
 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 { 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_TRACE_SCHEMA_VERSION, resolveActor, resolvePolicyOperationIdForCommand, type PolicyOperationId, type PolicyTraceRecord, type PolicyTraceRecordInput } from "./policy.js";
+export { assertWritableKey, getConfigKeyMetadata, getConfigRegistryExport, listConfigMetadata, validatePersistedConfigDocument, validateValueForMetadata, type ConfigKeyExposure, type ConfigKeyMetadata, type ConfigValueType } from "./config-metadata.js";
+export { appendConfigMutation, CONFIG_MUTATIONS_SCHEMA_VERSION, summarizeForEvidence, type ConfigMutationRecord } from "./config-mutations.js";
+export { generateConfigReferenceDocs, runWorkspaceConfigCli, type ConfigCliIo } from "./config-cli.js";
 export type CoreRuntimeVersion = "0.1";

package/dist/core/index.js

@@ -1,4 +1,7 @@
 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";
+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_TRACE_SCHEMA_VERSION, resolveActor, resolvePolicyOperationIdForCommand } from "./policy.js";
+export { assertWritableKey, getConfigKeyMetadata, getConfigRegistryExport, listConfigMetadata, validatePersistedConfigDocument, validateValueForMetadata } from "./config-metadata.js";
+export { appendConfigMutation, CONFIG_MUTATIONS_SCHEMA_VERSION, summarizeForEvidence } from "./config-mutations.js";
+export { generateConfigReferenceDocs, runWorkspaceConfigCli } from "./config-cli.js";

package/dist/core/policy.d.ts

@@ -1,5 +1,9 @@
-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 const POLICY_TRACE_SCHEMA_VERSION: 1;
+export type PolicyOperationId = "cli.upgrade" | "cli.init" | "cli.config-mutate" | "policy.dynamic-sensitive" | "doc.document-project" | "doc.generate-document" | "tasks.import-tasks" | "tasks.generate-tasks-md" | "tasks.run-transition";
 export declare function getOperationIdForCommand(commandName: string): PolicyOperationId | undefined;
+export declare function getExtraSensitiveModuleCommandsFromEffective(effective: Record<string, unknown>): string[];
+/** Resolve operation id for tracing, including config-declared sensitive module commands. */
+export declare function resolvePolicyOperationIdForCommand(commandName: string, effective: Record<string, unknown>): PolicyOperationId | undefined;
 /**
  * Sensitive when mutation / write is possible. Documentation commands are exempt when dryRun is true.
  */
@@ -12,6 +16,7 @@ export declare function parsePolicyApprovalFromEnv(env: NodeJS.ProcessEnv): Poli
 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 = {
+    schemaVersion: number;
     timestamp: string;
     operationId: PolicyOperationId;
     command: string;
@@ -21,4 +26,9 @@ export type PolicyTraceRecord = {
     commandOk?: boolean;
     message?: string;
 };
-export declare function appendPolicyTrace(workspacePath: string, record: PolicyTraceRecord): Promise<void>;
+/** Policy sensitivity from built-in map plus `policy.extraSensitiveModuleCommands` on effective config. */
+export declare function isSensitiveModuleCommandForEffective(commandName: string, args: Record<string, unknown>, effective: Record<string, unknown>): boolean;
+export type PolicyTraceRecordInput = Omit<PolicyTraceRecord, "schemaVersion"> & {
+    schemaVersion?: number;
+};
+export declare function appendPolicyTrace(workspacePath: string, record: PolicyTraceRecordInput): Promise<void>;

package/dist/core/policy.js

@@ -1,6 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { execSync } from "node:child_process";
+export const POLICY_TRACE_SCHEMA_VERSION = 1;
 const COMMAND_TO_OPERATION = {
     "document-project": "doc.document-project",
     "generate-document": "doc.generate-document",
@@ -11,6 +12,27 @@ const COMMAND_TO_OPERATION = {
 export function getOperationIdForCommand(commandName) {
     return COMMAND_TO_OPERATION[commandName];
 }
+export function getExtraSensitiveModuleCommandsFromEffective(effective) {
+    const policy = effective.policy;
+    if (!policy || typeof policy !== "object" || Array.isArray(policy)) {
+        return [];
+    }
+    const raw = policy.extraSensitiveModuleCommands;
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    return raw.filter((x) => typeof x === "string" && x.trim().length > 0);
+}
+/** Resolve operation id for tracing, including config-declared sensitive module commands. */
+export function resolvePolicyOperationIdForCommand(commandName, effective) {
+    const builtin = getOperationIdForCommand(commandName);
+    if (builtin)
+        return builtin;
+    if (getExtraSensitiveModuleCommandsFromEffective(effective).includes(commandName)) {
+        return "policy.dynamic-sensitive";
+    }
+    return undefined;
+}
 /**
  * Sensitive when mutation / write is possible. Documentation commands are exempt when dryRun is true.
  */
@@ -91,12 +113,23 @@ export function resolveActor(workspacePath, args, env) {
     }
     return "unknown";
 }
+/** Policy sensitivity from built-in map plus `policy.extraSensitiveModuleCommands` on effective config. */
+export function isSensitiveModuleCommandForEffective(commandName, args, effective) {
+    if (isSensitiveModuleCommand(commandName, args)) {
+        return true;
+    }
+    return getExtraSensitiveModuleCommandsFromEffective(effective).includes(commandName);
+}
 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`;
+    const full = {
+        ...record,
+        schemaVersion: record.schemaVersion ?? POLICY_TRACE_SCHEMA_VERSION
+    };
+    const line = `${JSON.stringify(full)}\n`;
     await fs.mkdir(dir, { recursive: true });
     await fs.appendFile(fp, line, "utf8");
 }

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

@@ -1,11 +1,13 @@
 import type { ConfigRegistryView } from "../contracts/module-contract.js";
-export type ConfigLayerId = "kit-default" | `module:${string}` | "project" | "env" | "invocation";
+export type ConfigLayerId = "kit-default" | `module:${string}` | "user" | "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>;
+export declare const PROJECT_CONFIG_REL = ".workspace-kit/config.json";
+export declare function getProjectConfigPath(workspacePath: string): string;
 /** Built-in defaults (lowest layer). */
 export declare const KIT_CONFIG_DEFAULTS: Record<string, unknown>;
 /**
@@ -16,6 +18,9 @@ export declare const MODULE_CONFIG_CONTRIBUTIONS: Record<string, Record<string,
 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;
+/** Resolved home for user-level config (`~/.workspace-kit/config.json`). Override with `WORKSPACE_KIT_HOME` (tests). */
+export declare function getUserConfigFilePath(): string;
+export declare function loadUserLayer(): Promise<ConfigLayer>;
 /**
  * Parse WORKSPACE_KIT_* env into a nested object (double-underscore → path under domains).
  * Example: WORKSPACE_KIT_TASKS__STORE_PATH -> { tasks: { storeRelativePath: "..." } }
@@ -37,6 +42,9 @@ export declare function resolveWorkspaceConfigWithLayers(options: ResolveWorkspa
     effective: EffectiveWorkspaceConfig;
     layers: ConfigLayer[];
 }>;
+export declare function normalizeConfigForExport(value: unknown): unknown;
+/** Deterministic JSON for agents and tests (sorted keys, trailing newline). */
+export declare function stableStringifyConfig(value: unknown): string;
 export type ExplainConfigResult = {
     path: string;
     effectiveValue: unknown;

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

@@ -1,7 +1,12 @@
 import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
-const PROJECT_CONFIG_REL = ".workspace-kit/config.json";
+import { validatePersistedConfigDocument } from "./config-metadata.js";
+export const PROJECT_CONFIG_REL = ".workspace-kit/config.json";
+export function getProjectConfigPath(workspacePath) {
+    return path.join(workspacePath, PROJECT_CONFIG_REL);
+}
 /** Built-in defaults (lowest layer). */
 export const KIT_CONFIG_DEFAULTS = {
     core: {},
@@ -85,6 +90,25 @@ export function deepEqual(a, b) {
     }
     return true;
 }
+/** Resolved home for user-level config (`~/.workspace-kit/config.json`). Override with `WORKSPACE_KIT_HOME` (tests). */
+export function getUserConfigFilePath() {
+    const home = process.env.WORKSPACE_KIT_HOME?.trim() || os.homedir();
+    return path.join(home, ".workspace-kit", "config.json");
+}
+async function readUserConfigFile() {
+    const fp = getUserConfigFilePath();
+    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(user): ${fp} must be a JSON object`);
+    }
+    const obj = parsed;
+    validatePersistedConfigDocument(obj, "user config");
+    return obj;
+}
 async function readProjectConfigFile(workspacePath) {
     const fp = path.join(workspacePath, PROJECT_CONFIG_REL);
     if (!existsSync(fp)) {
@@ -96,11 +120,13 @@ async function readProjectConfigFile(workspacePath) {
         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");
-    }
+    validatePersistedConfigDocument(obj, ".workspace-kit/config.json");
     return obj;
 }
+export async function loadUserLayer() {
+    const data = await readUserConfigFile();
+    return { id: "user", data };
+}
 /**
  * Parse WORKSPACE_KIT_* env into a nested object (double-underscore → path under domains).
  * Example: WORKSPACE_KIT_TASKS__STORE_PATH -> { tasks: { storeRelativePath: "..." } }
@@ -186,6 +212,7 @@ export function mergeConfigLayers(layers) {
 export async function resolveWorkspaceConfigWithLayers(options) {
     const { workspacePath, registry, env = process.env, invocationConfig } = options;
     const layers = [...buildBaseConfigLayers(registry)];
+    layers.push(await loadUserLayer());
     layers.push(await loadProjectLayer(workspacePath));
     layers.push({ id: "env", data: envToConfigOverlay(env) });
     if (invocationConfig && Object.keys(invocationConfig).length > 0) {
@@ -193,6 +220,27 @@ export async function resolveWorkspaceConfigWithLayers(options) {
     }
     return { effective: mergeConfigLayers(layers), layers };
 }
+export function normalizeConfigForExport(value) {
+    return sortKeysDeep(value);
+}
+function sortKeysDeep(value) {
+    if (value === null || typeof value !== "object") {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map(sortKeysDeep);
+    }
+    const o = value;
+    const out = {};
+    for (const k of Object.keys(o).sort()) {
+        out[k] = sortKeysDeep(o[k]);
+    }
+    return out;
+}
+/** Deterministic JSON for agents and tests (sorted keys, trailing newline). */
+export function stableStringifyConfig(value) {
+    return `${JSON.stringify(sortKeysDeep(value), null, 2)}\n`;
+}
 export function explainConfigPath(dottedPath, layers) {
     const mergedFull = mergeConfigLayers(layers);
     const effectiveValue = getAtPath(mergedFull, dottedPath);

package/dist/modules/workspace-config/index.js

@@ -1,4 +1,4 @@
-import { explainConfigPath, resolveWorkspaceConfigWithLayers } from "../../core/workspace-kit-config.js";
+import { explainConfigPath, normalizeConfigForExport, resolveWorkspaceConfigWithLayers } from "../../core/workspace-kit-config.js";
 async function handleExplainConfig(args, ctx) {
     const pathArg = typeof args.path === "string" ? args.path.trim() : "";
     if (!pathArg) {
@@ -23,6 +23,24 @@ async function handleExplainConfig(args, ctx) {
         data: explained
     };
 }
+async function handleResolveConfig(args, ctx) {
+    const invocationConfig = typeof args.config === "object" && args.config !== null && !Array.isArray(args.config)
+        ? args.config
+        : {};
+    const { effective, layers } = await resolveWorkspaceConfigWithLayers({
+        workspacePath: ctx.workspacePath,
+        registry: ctx.registry,
+        invocationConfig
+    });
+    return {
+        ok: true,
+        code: "config-resolved",
+        data: {
+            effective: normalizeConfigForExport(effective),
+            layers: layers.map((l) => ({ id: l.id }))
+        }
+    };
+}
 export const workspaceConfigModule = {
     registration: {
         id: "workspace-config",
@@ -48,25 +66,35 @@ export const workspaceConfigModule = {
                     name: "explain-config",
                     file: "explain-config.md",
                     description: "Agent-first JSON: effective config value and winning layer for a dotted path."
+                },
+                {
+                    name: "resolve-config",
+                    file: "resolve-config.md",
+                    description: "Agent-first JSON: full effective config (sorted) and merge layer ids."
                 }
             ]
         }
     },
     async onCommand(command, ctx) {
-        if (command.name !== "explain-config") {
-            return { ok: false, code: "unknown-command", message: "workspace-config only implements explain-config" };
-        }
         const reg = ctx.moduleRegistry;
         if (!reg) {
             return {
                 ok: false,
                 code: "internal-error",
-                message: "explain-config requires moduleRegistry on context (CLI wiring)"
+                message: "workspace-config requires moduleRegistry on context (CLI wiring)"
             };
         }
-        return handleExplainConfig(command.args ?? {}, {
-            workspacePath: ctx.workspacePath,
-            registry: reg
-        });
+        const baseCtx = { workspacePath: ctx.workspacePath, registry: reg };
+        if (command.name === "explain-config") {
+            return handleExplainConfig(command.args ?? {}, baseCtx);
+        }
+        if (command.name === "resolve-config") {
+            return handleResolveConfig(command.args ?? {}, baseCtx);
+        }
+        return {
+            ok: false,
+            code: "unknown-command",
+            message: `workspace-config: unknown command '${command.name}'`
+        };
     }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workflow-cannon/workspace-kit",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "private": false,
   "packageManager": "pnpm@10.0.0",
   "license": "MIT",