@workflow-cannon/workspace-kit 0.4.0 → 0.5.0

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,10 @@
 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 { LINEAGE_SCHEMA_VERSION, lineageCorrelationRoot, type LineageAppPayload, type LineageCorrPayload, type LineageDecPayload, type LineageEvent, type LineageEventType, type LineageRecPayload } from "./lineage-contract.js";
+export { appendLineageEvent, newLineageEventId, queryLineageChain, readLineageEvents } from "./lineage-store.js";
 export type CoreRuntimeVersion = "0.1";

package/dist/core/index.js

@@ -1,4 +1,9 @@
 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";
+export { LINEAGE_SCHEMA_VERSION, lineageCorrelationRoot } from "./lineage-contract.js";
+export { appendLineageEvent, newLineageEventId, queryLineageChain, readLineageEvents } from "./lineage-store.js";

package/dist/core/lineage-contract.d.ts

@@ -0,0 +1,59 @@
+/**
+ * T203: Immutable lineage event contract (append-only store, correlation fields).
+ * @see docs/maintainers/TASKS.md T192, T203
+ */
+export declare const LINEAGE_SCHEMA_VERSION: 1;
+export type LineageEventType = "rec" | "dec" | "app" | "corr";
+/** Recommendation enqueued (Task Engine improvement task created). */
+export type LineageRecPayload = {
+    recommendationTaskId: string;
+    evidenceKey: string;
+    title: string;
+    confidence: number;
+    confidenceTier: string;
+    provenanceRefs: Record<string, string>;
+};
+/** Human approval decision recorded (before or alongside task transition). */
+export type LineageDecPayload = {
+    recommendationTaskId: string;
+    evidenceKey: string;
+    decisionVerb: "accept" | "decline" | "accept_edited";
+    actor: string;
+    decisionFingerprint: string;
+    policyTraceRef?: {
+        operationId: string;
+        timestamp: string;
+    };
+    /** Optional link to a config mutation evidence row when the reviewer supplies it. */
+    configMutationRef?: {
+        timestamp: string;
+        key: string;
+    };
+};
+/** Applied change marker (task reached completed via acceptance). */
+export type LineageAppPayload = {
+    recommendationTaskId: string;
+    evidenceKey: string;
+    decisionFingerprint: string;
+    finalTaskStatus: "completed";
+};
+/** Optional correlation enrichment (trace linkage). */
+export type LineageCorrPayload = {
+    recommendationTaskId: string;
+    evidenceKey: string;
+    policySchemaVersion?: number;
+    policyOperationId?: string;
+    policyTimestamp?: string;
+    mutationRecordTimestamp?: string;
+    mutationKey?: string;
+};
+export type LineageEvent = {
+    schemaVersion: typeof LINEAGE_SCHEMA_VERSION;
+    eventId: string;
+    eventType: LineageEventType;
+    timestamp: string;
+    correlationRoot: string;
+    payload: LineageRecPayload | LineageDecPayload | LineageAppPayload | LineageCorrPayload;
+};
+/** Stable correlation root: ties chain to recommendation + evidence identity. */
+export declare function lineageCorrelationRoot(recommendationTaskId: string, evidenceKey: string): string;

package/dist/core/lineage-contract.js

@@ -0,0 +1,9 @@
+/**
+ * T203: Immutable lineage event contract (append-only store, correlation fields).
+ * @see docs/maintainers/TASKS.md T192, T203
+ */
+export const LINEAGE_SCHEMA_VERSION = 1;
+/** Stable correlation root: ties chain to recommendation + evidence identity. */
+export function lineageCorrelationRoot(recommendationTaskId, evidenceKey) {
+    return `${recommendationTaskId}::${evidenceKey}`;
+}

package/dist/core/lineage-store.d.ts

@@ -0,0 +1,16 @@
+import type { LineageEvent, LineageEventType } from "./lineage-contract.js";
+export declare function newLineageEventId(): string;
+export declare function appendLineageEvent(workspacePath: string, input: {
+    eventType: LineageEventType;
+    recommendationTaskId: string;
+    evidenceKey: string;
+    payload: LineageEvent["payload"];
+    eventId?: string;
+    timestamp?: string;
+}): Promise<LineageEvent>;
+export declare function readLineageEvents(workspacePath: string): Promise<LineageEvent[]>;
+/** Reconstruct rec → dec → app chain for a recommendation task id (deterministic sort by timestamp). */
+export declare function queryLineageChain(workspacePath: string, recommendationTaskId: string): Promise<{
+    events: LineageEvent[];
+    byType: Record<LineageEventType, LineageEvent[]>;
+}>;

package/dist/core/lineage-store.js

@@ -0,0 +1,74 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import crypto from "node:crypto";
+import { LINEAGE_SCHEMA_VERSION, lineageCorrelationRoot } from "./lineage-contract.js";
+const LINEAGE_DIR = ".workspace-kit/lineage";
+const EVENTS_FILE = "events.jsonl";
+function eventsPath(workspacePath) {
+    return path.join(workspacePath, LINEAGE_DIR, EVENTS_FILE);
+}
+export function newLineageEventId() {
+    return `lev-${Date.now()}-${crypto.randomUUID().slice(0, 8)}`;
+}
+export async function appendLineageEvent(workspacePath, input) {
+    const timestamp = input.timestamp ?? new Date().toISOString();
+    const correlationRoot = lineageCorrelationRoot(input.recommendationTaskId, input.evidenceKey);
+    const event = {
+        schemaVersion: LINEAGE_SCHEMA_VERSION,
+        eventId: input.eventId ?? newLineageEventId(),
+        eventType: input.eventType,
+        timestamp,
+        correlationRoot,
+        payload: input.payload
+    };
+    const fp = eventsPath(workspacePath);
+    await fs.mkdir(path.dirname(fp), { recursive: true });
+    await fs.appendFile(fp, `${JSON.stringify(event)}\n`, "utf8");
+    return event;
+}
+export async function readLineageEvents(workspacePath) {
+    const fp = eventsPath(workspacePath);
+    let raw;
+    try {
+        raw = await fs.readFile(fp, "utf8");
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return [];
+        throw e;
+    }
+    const out = [];
+    for (const line of raw.split("\n")) {
+        const t = line.trim();
+        if (!t)
+            continue;
+        try {
+            const ev = JSON.parse(t);
+            if (ev.schemaVersion === LINEAGE_SCHEMA_VERSION)
+                out.push(ev);
+        }
+        catch {
+            /* skip corrupt line */
+        }
+    }
+    return out;
+}
+/** Reconstruct rec → dec → app chain for a recommendation task id (deterministic sort by timestamp). */
+export async function queryLineageChain(workspacePath, recommendationTaskId) {
+    const all = await readLineageEvents(workspacePath);
+    const chain = all.filter((e) => {
+        const p = e.payload;
+        return p.recommendationTaskId === recommendationTaskId;
+    });
+    chain.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+    const byType = {
+        rec: [],
+        dec: [],
+        app: [],
+        corr: []
+    };
+    for (const e of chain) {
+        byType[e.eventType].push(e);
+    }
+    return { events: chain, byType };
+}

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" | "approvals.review-item" | "improvement.generate-recommendations";
 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,16 +1,40 @@
 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"
+    "run-transition": "tasks.run-transition",
+    "review-item": "approvals.review-item",
+    "generate-recommendations": "improvement.generate-recommendations"
 };
 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 +115,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/approvals/decisions-store.d.ts

@@ -0,0 +1,20 @@
+export declare const APPROVAL_DECISION_SCHEMA_VERSION: 1;
+export type ApprovalDecisionRecord = {
+    schemaVersion: typeof APPROVAL_DECISION_SCHEMA_VERSION;
+    fingerprint: string;
+    taskId: string;
+    evidenceKey: string;
+    decisionVerb: "accept" | "decline" | "accept_edited";
+    actor: string;
+    timestamp: string;
+    editedSummary?: string;
+    policyTraceRef?: {
+        operationId: string;
+        timestamp: string;
+    };
+};
+export declare function computeDecisionFingerprint(taskId: string, decisionVerb: string, evidenceKey: string, editedSummary?: string): string;
+export declare function readDecisionFingerprints(workspacePath: string): Promise<Set<string>>;
+export declare function appendDecisionRecord(workspacePath: string, record: Omit<ApprovalDecisionRecord, "schemaVersion" | "timestamp"> & {
+    timestamp?: string;
+}): Promise<void>;