@workflow-cannon/workspace-kit 0.3.0 → 0.4.1

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,3 +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, 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,2 +1,7 @@
 export { ModuleRegistry, ModuleRegistryError, validateModuleSet } from "./module-registry.js";
 export { ModuleCommandRouter, ModuleCommandRouterError } from "./module-command-router.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

@@ -0,0 +1,34 @@
+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.
+ */
+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 = {
+    schemaVersion: number;
+    timestamp: string;
+    operationId: PolicyOperationId;
+    command: string;
+    actor: string;
+    allowed: boolean;
+    rationale?: string;
+    commandOk?: boolean;
+    message?: string;
+};
+/** 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

@@ -0,0 +1,135 @@
+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",
+    "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];
+}
+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.
+ */
+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";
+}
+/** 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 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

@@ -0,0 +1,57 @@
+import type { ConfigRegistryView } from "../contracts/module-contract.js";
+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>;
+/**
+ * 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;
+/** 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: "..." } }
+ * 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 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;
+    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,266 @@
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+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: {},
+    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;
+}
+/** 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)) {
+        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;
+    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: "..." } }
+ * 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 loadUserLayer());
+    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 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);
+    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;