@workflow-cannon/workspace-kit 0.3.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

@@ -4,11 +4,14 @@ 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;
@@ -94,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) {
@@ -316,8 +346,13 @@ export async function runCli(args, options = {}) {
         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}`);
@@ -328,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") {
@@ -344,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}`);
@@ -444,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") {
@@ -534,6 +576,7 @@ export async function runCli(args, options = {}) {
     }
     if (command === "run") {
         const allModules = [
+            workspaceConfigModule,
             documentationModule,
             taskEngineModule,
             approvalsModule,
@@ -571,9 +614,74 @@ export async function runCli(args, options = {}) {
                 return EXIT_USAGE_ERROR;
             }
         }
-        const ctx = { runtimeVersion: "0.1", workspacePath: cwd };
+        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;
         }

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

package/dist/modules/index.d.ts

@@ -2,6 +2,7 @@ export { approvalsModule } from "./approvals/index.js";
 export { documentationModule } from "./documentation/index.js";
 export type { DocumentationConflict, DocumentationGenerateOptions, DocumentationGenerateResult, DocumentationGenerationEvidence, DocumentationValidationIssue } from "./documentation/types.js";
 export { improvementModule } from "./improvement/index.js";
+export { workspaceConfigModule } from "./workspace-config/index.js";
 export { planningModule } from "./planning/index.js";
 export { taskEngineModule, TaskStore, TransitionService, TaskEngineError, TransitionValidator, isTransitionAllowed, getTransitionAction, resolveTargetState, getAllowedTransitionsFrom, stateValidityGuard, dependencyCheckGuard, generateTasksMd, importTasksFromMarkdown, getNextActions } from "./task-engine/index.js";
 export type { TaskEntity, TaskStatus, TaskPriority, TaskStoreDocument, TransitionEvidence, TransitionGuard, TransitionContext, GuardResult, TaskEngineErrorCode, TaskAdapter, TaskAdapterCapability, NextActionSuggestion, BlockingAnalysisEntry } from "./task-engine/index.js";

package/dist/modules/index.js

@@ -1,5 +1,6 @@
 export { approvalsModule } from "./approvals/index.js";
 export { documentationModule } from "./documentation/index.js";
 export { improvementModule } from "./improvement/index.js";
+export { workspaceConfigModule } from "./workspace-config/index.js";
 export { planningModule } from "./planning/index.js";
 export { taskEngineModule, TaskStore, TransitionService, TaskEngineError, TransitionValidator, isTransitionAllowed, getTransitionAction, resolveTargetState, getAllowedTransitionsFrom, stateValidityGuard, dependencyCheckGuard, generateTasksMd, importTasksFromMarkdown, getNextActions } from "./task-engine/index.js";

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

@@ -12,10 +12,18 @@ export { TaskEngineError, TransitionValidator, isTransitionAllowed, getTransitio
 export { generateTasksMd } from "./generator.js";
 export { importTasksFromMarkdown } from "./importer.js";
 export { getNextActions } from "./suggestions.js";
+function taskStorePath(ctx) {
+    const tasks = ctx.effectiveConfig?.tasks;
+    if (!tasks || typeof tasks !== "object" || Array.isArray(tasks)) {
+        return undefined;
+    }
+    const p = tasks.storeRelativePath;
+    return typeof p === "string" && p.trim().length > 0 ? p.trim() : undefined;
+}
 export const taskEngineModule = {
     registration: {
         id: "task-engine",
-        version: "0.3.0",
+        version: "0.4.0",
         contractVersion: "1",
         capabilities: ["task-engine"],
         dependsOn: [],
@@ -73,7 +81,7 @@ export const taskEngineModule = {
     },
     async onCommand(command, ctx) {
         const args = command.args ?? {};
-        const store = new TaskStore(ctx.workspacePath);
+        const store = new TaskStore(ctx.workspacePath, taskStorePath(ctx));
         try {
             await store.load();
         }
@@ -90,7 +98,11 @@ export const taskEngineModule = {
         if (command.name === "run-transition") {
             const taskId = typeof args.taskId === "string" ? args.taskId : undefined;
             const action = typeof args.action === "string" ? args.action : undefined;
-            const actor = typeof args.actor === "string" ? args.actor : undefined;
+            const actor = typeof args.actor === "string"
+                ? args.actor
+                : ctx.resolvedActor !== undefined
+                    ? ctx.resolvedActor
+                    : undefined;
             if (!taskId || !action) {
                 return {
                     ok: false,

package/dist/modules/workspace-config/index.d.ts

@@ -0,0 +1,2 @@
+import type { WorkflowModule } from "../../contracts/module-contract.js";
+export declare const workspaceConfigModule: WorkflowModule;

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

@@ -0,0 +1,72 @@
+import { explainConfigPath, resolveWorkspaceConfigWithLayers } from "../../core/workspace-kit-config.js";
+async function handleExplainConfig(args, ctx) {
+    const pathArg = typeof args.path === "string" ? args.path.trim() : "";
+    if (!pathArg) {
+        return {
+            ok: false,
+            code: "invalid-config-path",
+            message: "explain-config requires string 'path' (dot-separated, e.g. tasks.storeRelativePath)"
+        };
+    }
+    const invocationConfig = typeof args.config === "object" && args.config !== null && !Array.isArray(args.config)
+        ? args.config
+        : {};
+    const { layers } = await resolveWorkspaceConfigWithLayers({
+        workspacePath: ctx.workspacePath,
+        registry: ctx.registry,
+        invocationConfig
+    });
+    const explained = explainConfigPath(pathArg, layers);
+    return {
+        ok: true,
+        code: "config-explained",
+        data: explained
+    };
+}
+export const workspaceConfigModule = {
+    registration: {
+        id: "workspace-config",
+        version: "0.4.0",
+        contractVersion: "1",
+        capabilities: ["diagnostics"],
+        dependsOn: [],
+        enabledByDefault: true,
+        config: {
+            path: "src/modules/workspace-config/config.md",
+            format: "md",
+            description: "Workspace config registry and explain surface."
+        },
+        state: {
+            path: "src/modules/workspace-config/state.md",
+            format: "md",
+            description: "Workspace config module runtime state (none)."
+        },
+        instructions: {
+            directory: "src/modules/workspace-config/instructions",
+            entries: [
+                {
+                    name: "explain-config",
+                    file: "explain-config.md",
+                    description: "Agent-first JSON: effective config value and winning layer for a dotted path."
+                }
+            ]
+        }
+    },
+    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)"
+            };
+        }
+        return handleExplainConfig(command.args ?? {}, {
+            workspacePath: ctx.workspacePath,
+            registry: reg
+        });
+    }
+};

package/package.json

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