@workflow-cannon/workspace-kit 0.8.0 → 0.9.0

package/README.md

@@ -104,8 +104,9 @@ npm install @workflow-cannon/workspace-kit
 - Glossary and agent-guidance terms: `docs/maintainers/TERMS.md`
 - Architecture direction: `docs/maintainers/ARCHITECTURE.md`
 - Project decisions: `docs/maintainers/DECISIONS.md`
-- Contribution guidelines: `docs/maintainers/CONTRIBUTING.md`
+- Governance policy surface: `docs/maintainers/GOVERNANCE.md`
 - Release process and gates: `docs/maintainers/RELEASING.md`
+- Canonical changelog: `docs/maintainers/CHANGELOG.md` (`CHANGELOG.md` at repo root is pointer-only)
 - Canonical AI module build guidance: `.ai/module-build.md`
 - Human module build guide: `docs/maintainers/module-build-guide.md`
 - Security, support, and governance: `docs/maintainers/SECURITY.md`, `docs/maintainers/SUPPORT.md`, `docs/maintainers/GOVERNANCE.md`

package/dist/cli/run-command.d.ts

@@ -0,0 +1,11 @@
+export type RunCommandIo = {
+    writeLine: (message: string) => void;
+    writeError: (message: string) => void;
+};
+export type RunCommandExitCodes = {
+    success: number;
+    validationFailure: number;
+    usageError: number;
+    internalError: number;
+};
+export declare function handleRunCommand(cwd: string, args: string[], io: RunCommandIo, codes: RunCommandExitCodes): Promise<number>;

package/dist/cli/run-command.js

@@ -0,0 +1,138 @@
+import { ModuleRegistry } from "../core/module-registry.js";
+import { ModuleCommandRouter } from "../core/module-command-router.js";
+import { appendPolicyTrace, isSensitiveModuleCommandForEffective, parsePolicyApproval, resolveActorWithFallback, resolvePolicyOperationIdForCommand } from "../core/policy.js";
+import { getSessionGrant, recordSessionGrant, resolveSessionId } from "../core/session-policy.js";
+import { applyResponseTemplateApplication } from "../core/response-template-shaping.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";
+export async function handleRunCommand(cwd, args, io, codes) {
+    const { writeLine, writeError } = io;
+    const allModules = [
+        workspaceConfigModule,
+        documentationModule,
+        taskEngineModule,
+        approvalsModule,
+        planningModule,
+        improvementModule
+    ];
+    const registry = new ModuleRegistry(allModules);
+    const router = new ModuleCommandRouter(registry);
+    const subcommand = args[1];
+    if (!subcommand) {
+        const commands = router.listCommands();
+        writeLine("Available module commands:");
+        for (const cmd of commands) {
+            const desc = cmd.description ? ` — ${cmd.description}` : "";
+            writeLine(`  ${cmd.name} (${cmd.moduleId})${desc}`);
+        }
+        writeLine("");
+        writeLine("Usage: workspace-kit run <command> [json-args]");
+        return codes.success;
+    }
+    let commandArgs = {};
+    if (args[2]) {
+        try {
+            const parsed = JSON.parse(args[2]);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                commandArgs = parsed;
+            }
+            else {
+                writeError("Command args must be a JSON object.");
+                return codes.usageError;
+            }
+        }
+        catch {
+            writeError(`Invalid JSON args: ${args[2]}`);
+            return codes.usageError;
+        }
+    }
+    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 codes.validationFailure;
+    }
+    const actor = await resolveActorWithFallback(cwd, commandArgs, process.env);
+    const sensitive = isSensitiveModuleCommandForEffective(subcommand, commandArgs, effective);
+    const sessionId = resolveSessionId(process.env);
+    const policyOp = resolvePolicyOperationIdForCommand(subcommand, effective);
+    const explicitPolicyApproval = parsePolicyApproval(commandArgs);
+    let resolvedSensitiveApproval = explicitPolicyApproval;
+    if (sensitive) {
+        if (!resolvedSensitiveApproval && policyOp) {
+            const grant = await getSessionGrant(cwd, policyOp, sessionId);
+            if (grant) {
+                resolvedSensitiveApproval = { confirmed: true, rationale: grant.rationale };
+            }
+        }
+        if (!resolvedSensitiveApproval) {
+            if (policyOp) {
+                await appendPolicyTrace(cwd, {
+                    timestamp: new Date().toISOString(),
+                    operationId: policyOp,
+                    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 (or an existing session grant for this operation): {"policyApproval":{"confirmed":true,"rationale":"why","scope":"session"}}'
+            }, null, 2));
+            return codes.validationFailure;
+        }
+    }
+    const ctx = {
+        runtimeVersion: "0.1",
+        workspacePath: cwd,
+        effectiveConfig: effective,
+        resolvedActor: actor,
+        moduleRegistry: registry
+    };
+    try {
+        const rawResult = await router.execute(subcommand, commandArgs, ctx);
+        if (sensitive && resolvedSensitiveApproval && policyOp) {
+            await appendPolicyTrace(cwd, {
+                timestamp: new Date().toISOString(),
+                operationId: policyOp,
+                command: `run ${subcommand}`,
+                actor,
+                allowed: true,
+                rationale: resolvedSensitiveApproval.rationale,
+                commandOk: rawResult.ok,
+                message: rawResult.message
+            });
+            if (explicitPolicyApproval?.scope === "session" && rawResult.ok) {
+                await recordSessionGrant(cwd, policyOp, sessionId, explicitPolicyApproval.rationale);
+            }
+        }
+        const result = applyResponseTemplateApplication(subcommand, commandArgs, rawResult, effective);
+        writeLine(JSON.stringify(result, null, 2));
+        return result.ok ? codes.success : codes.validationFailure;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        writeError(`Module command failed: ${message}`);
+        return codes.internalError;
+    }
+}

package/dist/cli.js

@@ -2,23 +2,14 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-import { ModuleRegistry } from "./core/module-registry.js";
-import { ModuleCommandRouter } from "./core/module-command-router.js";
-import { appendPolicyTrace, isSensitiveModuleCommandForEffective, parsePolicyApproval, parsePolicyApprovalFromEnv, resolveActor, resolvePolicyOperationIdForCommand } from "./core/policy.js";
-import { getSessionGrant, recordSessionGrant, resolveSessionId } from "./core/session-policy.js";
-import { applyResponseTemplateApplication } from "./core/response-template-shaping.js";
+import { appendPolicyTrace, parsePolicyApprovalFromEnv, resolveActorWithFallback } from "./core/policy.js";
 import { runWorkspaceConfigCli } from "./core/config-cli.js";
-import { resolveWorkspaceConfigWithLayers } from "./core/workspace-kit-config.js";
-import { documentationModule } from "./modules/documentation/index.js";
-import { taskEngineModule } from "./modules/task-engine/index.js";
-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";
+import { handleRunCommand } from "./cli/run-command.js";
 const EXIT_SUCCESS = 0;
 const EXIT_VALIDATION_FAILURE = 1;
 const EXIT_USAGE_ERROR = 2;
 const EXIT_INTERNAL_ERROR = 3;
+const CANONICAL_KIT_NAME = "@workflow-cannon/workspace-kit";
 export const defaultWorkspaceKitPaths = {
     profile: "workspace-kit.profile.json",
     profileSchema: "schemas/workspace-kit-profile.schema.json",
@@ -108,7 +99,7 @@ async function requireCliPolicyApproval(cwd, operationId, commandLabel, writeErr
             timestamp: new Date().toISOString(),
             operationId,
             command: commandLabel,
-            actor: resolveActor(cwd, {}, process.env),
+            actor: await resolveActorWithFallback(cwd, {}, process.env),
             allowed: false,
             message: "missing WORKSPACE_KIT_POLICY_APPROVAL"
         });
@@ -121,7 +112,7 @@ async function recordCliPolicySuccess(cwd, operationId, commandLabel, rationale,
         timestamp: new Date().toISOString(),
         operationId,
         command: commandLabel,
-        actor: resolveActor(cwd, {}, process.env),
+        actor: await resolveActorWithFallback(cwd, {}, process.env),
         allowed: true,
         rationale,
         commandOk
@@ -275,7 +266,8 @@ async function resolvePackageVersion(cwd) {
                 const version = parsed.version;
                 const name = parsed.name;
                 if (typeof version === "string" && version.length > 0 && typeof name === "string") {
-                    if (name === "quicktask-workspace-kit" ||
+                    if (name === CANONICAL_KIT_NAME ||
+                        name === "quicktask-workspace-kit" ||
                         candidatePath.endsWith("packages/workspace-kit/package.json")) {
                         return version;
                     }
@@ -420,11 +412,7 @@ export async function runCli(args, options = {}) {
         const mergedManifest = {
             schemaVersion: 1,
             kit: {
-                name: typeof existingManifest.kit === "object" &&
-                    existingManifest.kit &&
-                    typeof existingManifest.kit.name === "string"
-                    ? existingManifest.kit.name
-                    : "quicktask-workspace-kit",
+                name: CANONICAL_KIT_NAME,
                 version: typeof existingManifest.kit === "object" &&
                     existingManifest.kit &&
                     typeof existingManifest.kit.version === "string"
@@ -554,12 +542,14 @@ export async function runCli(args, options = {}) {
             if (!manifestKitName || !manifestKitVersion) {
                 driftFindings.push(`${defaultWorkspaceKitPaths.manifest}: kit.name and kit.version are required`);
             }
-            else if (manifestKitName === "quicktask-workspace-kit" && packageVersion) {
+            else if ((manifestKitName === CANONICAL_KIT_NAME || manifestKitName === "quicktask-workspace-kit") &&
+                packageVersion) {
                 if (manifestKitVersion !== packageVersion) {
                     driftFindings.push(`${defaultWorkspaceKitPaths.manifest}: kit.version (${manifestKitVersion}) does not match package version (${packageVersion})`);
                 }
             }
-            else if (manifestKitName !== "quicktask-workspace-kit") {
+            else if (manifestKitName !== CANONICAL_KIT_NAME &&
+                manifestKitName !== "quicktask-workspace-kit") {
                 warnings.push(`${defaultWorkspaceKitPaths.manifest}: kit.name is '${manifestKitName}', skipping package-version drift comparison`);
             }
         }
@@ -581,129 +571,12 @@ export async function runCli(args, options = {}) {
         return EXIT_SUCCESS;
     }
     if (command === "run") {
-        const allModules = [
-            workspaceConfigModule,
-            documentationModule,
-            taskEngineModule,
-            approvalsModule,
-            planningModule,
-            improvementModule
-        ];
-        const registry = new ModuleRegistry(allModules);
-        const router = new ModuleCommandRouter(registry);
-        const subcommand = args[1];
-        if (!subcommand) {
-            const commands = router.listCommands();
-            writeLine("Available module commands:");
-            for (const cmd of commands) {
-                const desc = cmd.description ? ` — ${cmd.description}` : "";
-                writeLine(`  ${cmd.name} (${cmd.moduleId})${desc}`);
-            }
-            writeLine("");
-            writeLine("Usage: workspace-kit run <command> [json-args]");
-            return EXIT_SUCCESS;
-        }
-        let commandArgs = {};
-        if (args[2]) {
-            try {
-                const parsed = JSON.parse(args[2]);
-                if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-                    commandArgs = parsed;
-                }
-                else {
-                    writeError("Command args must be a JSON object.");
-                    return EXIT_USAGE_ERROR;
-                }
-            }
-            catch {
-                writeError(`Invalid JSON args: ${args[2]}`);
-                return EXIT_USAGE_ERROR;
-            }
-        }
-        const invocationConfig = typeof commandArgs.config === "object" &&
-            commandArgs.config !== null &&
-            !Array.isArray(commandArgs.config)
-            ? commandArgs.config
-            : {};
-        let effective;
-        try {
-            const resolved = await resolveWorkspaceConfigWithLayers({
-                workspacePath: cwd,
-                registry,
-                invocationConfig
-            });
-            effective = resolved.effective;
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            writeError(`Config resolution failed: ${message}`);
-            return EXIT_VALIDATION_FAILURE;
-        }
-        const actor = resolveActor(cwd, commandArgs, process.env);
-        const sensitive = isSensitiveModuleCommandForEffective(subcommand, commandArgs, effective);
-        const sessionId = resolveSessionId(process.env);
-        const policyOp = resolvePolicyOperationIdForCommand(subcommand, effective);
-        const explicitPolicyApproval = parsePolicyApproval(commandArgs);
-        let resolvedSensitiveApproval = explicitPolicyApproval;
-        if (sensitive) {
-            if (!resolvedSensitiveApproval && policyOp) {
-                const grant = await getSessionGrant(cwd, policyOp, sessionId);
-                if (grant) {
-                    resolvedSensitiveApproval = { confirmed: true, rationale: grant.rationale };
-                }
-            }
-            if (!resolvedSensitiveApproval) {
-                if (policyOp) {
-                    await appendPolicyTrace(cwd, {
-                        timestamp: new Date().toISOString(),
-                        operationId: policyOp,
-                        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 (or an existing session grant for this operation): {"policyApproval":{"confirmed":true,"rationale":"why","scope":"session"}}'
-                }, null, 2));
-                return EXIT_VALIDATION_FAILURE;
-            }
-        }
-        const ctx = {
-            runtimeVersion: "0.1",
-            workspacePath: cwd,
-            effectiveConfig: effective,
-            resolvedActor: actor,
-            moduleRegistry: registry
-        };
-        try {
-            const rawResult = await router.execute(subcommand, commandArgs, ctx);
-            if (sensitive && resolvedSensitiveApproval && policyOp) {
-                await appendPolicyTrace(cwd, {
-                    timestamp: new Date().toISOString(),
-                    operationId: policyOp,
-                    command: `run ${subcommand}`,
-                    actor,
-                    allowed: true,
-                    rationale: resolvedSensitiveApproval.rationale,
-                    commandOk: rawResult.ok,
-                    message: rawResult.message
-                });
-                if (explicitPolicyApproval?.scope === "session" && rawResult.ok) {
-                    await recordSessionGrant(cwd, policyOp, sessionId, explicitPolicyApproval.rationale);
-                }
-            }
-            const result = applyResponseTemplateApplication(subcommand, commandArgs, rawResult, effective);
-            writeLine(JSON.stringify(result, null, 2));
-            return result.ok ? EXIT_SUCCESS : EXIT_VALIDATION_FAILURE;
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            writeError(`Module command failed: ${message}`);
-            return EXIT_INTERNAL_ERROR;
-        }
+        return handleRunCommand(cwd, args, { writeLine, writeError }, {
+            success: EXIT_SUCCESS,
+            validationFailure: EXIT_VALIDATION_FAILURE,
+            usageError: EXIT_USAGE_ERROR,
+            internalError: EXIT_INTERNAL_ERROR
+        });
     }
     if (command !== "doctor") {
         writeError(`Unknown command '${command}'. Supported commands: init, doctor, check, upgrade, drift-check, run, config.`);

package/dist/core/config-cli.js

@@ -3,7 +3,7 @@ import { createInterface } from "node:readline/promises";
 import { stdin as processStdin, stdout as processStdout } from "node:process";
 import path from "node:path";
 import { ModuleRegistry } from "./module-registry.js";
-import { appendPolicyTrace, parsePolicyApprovalFromEnv, resolveActor } from "./policy.js";
+import { appendPolicyTrace, parsePolicyApprovalFromEnv, resolveActorWithFallback } from "./policy.js";
 import { appendConfigMutation, summarizeForEvidence } from "./config-mutations.js";
 import { assertWritableKey, getConfigKeyMetadata, listConfigMetadata, validatePersistedConfigDocument, validateValueForMetadata } from "./config-metadata.js";
 import { explainConfigPath, getAtPath, getProjectConfigPath, getUserConfigFilePath, resolveWorkspaceConfigWithLayers, stableStringifyConfig } from "./workspace-kit-config.js";
@@ -114,7 +114,7 @@ async function requireConfigApproval(cwd, commandLabel, writeError) {
             timestamp: new Date().toISOString(),
             operationId: "cli.config-mutate",
             command: commandLabel,
-            actor: resolveActor(cwd, {}, process.env),
+            actor: await resolveActorWithFallback(cwd, {}, process.env),
             allowed: false,
             message: "missing WORKSPACE_KIT_POLICY_APPROVAL"
         });
@@ -303,7 +303,7 @@ export async function runWorkspaceConfigCli(cwd, argv, io) {
             const prevVal = getAtPath(before, key);
             const next = setDeep(before, key, parsed);
             validatePersistedConfigDocument(next, scope === "project" ? ".workspace-kit/config.json" : "user config");
-            const actor = resolveActor(cwd, {}, process.env);
+            const actor = await resolveActorWithFallback(cwd, {}, process.env);
             try {
                 await writeConfigFileAtomic(fp, next);
                 await appendConfigMutation(cwd, {
@@ -380,7 +380,7 @@ export async function runWorkspaceConfigCli(cwd, argv, io) {
             const prevVal = getAtPath(before, key);
             const next = unsetDeep(before, key);
             validatePersistedConfigDocument(next, scope === "project" ? ".workspace-kit/config.json" : "user config");
-            const actor = resolveActor(cwd, {}, process.env);
+            const actor = await resolveActorWithFallback(cwd, {}, process.env);
             try {
                 if (Object.keys(next).length === 0) {
                     await fs.rm(fp, { force: true });

package/dist/core/config-metadata.js

@@ -32,8 +32,8 @@ const REGISTRY = {
     "improvement.transcripts.sourcePath": {
         key: "improvement.transcripts.sourcePath",
         type: "string",
-        description: "Relative path to transcript JSONL source files for sync operations.",
-        default: ".cursor/agent-transcripts",
+        description: "Optional relative path to transcript JSONL source. When empty, sync uses discoveryPaths (repo-relative, then Cursor global ~/.cursor/projects/<slug>/agent-transcripts).",
+        default: "",
         domainScope: "project",
         owningModule: "improvement",
         sensitive: false,
@@ -136,7 +136,7 @@ const REGISTRY = {
     "improvement.transcripts.discoveryPaths": {
         key: "improvement.transcripts.discoveryPaths",
         type: "array",
-        description: "Ordered relative paths tried when improvement.transcripts.sourcePath is unset (first existing wins).",
+        description: "Ordered relative paths tried when improvement.transcripts.sourcePath is unset (first existing wins). After these, sync tries Cursor global ~/.cursor/projects/<slug>/agent-transcripts.",
         default: [],
         domainScope: "project",
         owningModule: "improvement",

package/dist/core/policy.d.ts

@@ -17,7 +17,15 @@ export type PolicyApprovalPayload = {
 };
 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 declare function resolveActor(_workspacePath: string, args: Record<string, unknown>, env: NodeJS.ProcessEnv): string;
+/**
+ * Actor precedence:
+ * 1) command args.actor
+ * 2) WORKSPACE_KIT_ACTOR
+ * 3) bounded git user.email/user.name lookup (unless WORKSPACE_KIT_ACTOR_GIT_LOOKUP=off)
+ * 4) "unknown"
+ */
+export declare function resolveActorWithFallback(workspacePath: string, args: Record<string, unknown>, env: NodeJS.ProcessEnv): Promise<string>;
 export type PolicyTraceRecord = {
     schemaVersion: number;
     timestamp: string;

package/dist/core/policy.js

@@ -1,6 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { execSync } from "node:child_process";
+import { execFile } from "node:child_process";
 export const POLICY_TRACE_SCHEMA_VERSION = 1;
 const COMMAND_TO_OPERATION = {
     "document-project": "doc.document-project",
@@ -83,37 +83,54 @@ export function parsePolicyApproval(args) {
     const scope = scopeRaw === "session" || scopeRaw === "once" ? scopeRaw : undefined;
     return { confirmed, rationale, ...(scope ? { scope } : {}) };
 }
-export function resolveActor(workspacePath, args, env) {
+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", {
+    return "unknown";
+}
+function runGitConfigValue(workspacePath, key, timeoutMs) {
+    return new Promise((resolve) => {
+        execFile("git", ["config", key], {
             cwd: workspacePath,
             encoding: "utf8",
-            stdio: ["ignore", "pipe", "ignore"]
-        }).trim();
-        if (name)
-            return name;
+            timeout: timeoutMs,
+            windowsHide: true
+        }, (error, stdout) => {
+            if (error) {
+                resolve(undefined);
+                return;
+            }
+            const trimmed = stdout.trim();
+            resolve(trimmed.length > 0 ? trimmed : undefined);
+        });
+    });
+}
+/**
+ * Actor precedence:
+ * 1) command args.actor
+ * 2) WORKSPACE_KIT_ACTOR
+ * 3) bounded git user.email/user.name lookup (unless WORKSPACE_KIT_ACTOR_GIT_LOOKUP=off)
+ * 4) "unknown"
+ */
+export async function resolveActorWithFallback(workspacePath, args, env) {
+    const explicit = resolveActor(workspacePath, args, env);
+    if (explicit !== "unknown") {
+        return explicit;
     }
-    catch {
-        /* ignore */
+    if (env.WORKSPACE_KIT_ACTOR_GIT_LOOKUP?.trim().toLowerCase() === "off") {
+        return "unknown";
     }
+    const timeoutMs = 300;
+    const email = await runGitConfigValue(workspacePath, "user.email", timeoutMs);
+    if (email)
+        return email;
+    const name = await runGitConfigValue(workspacePath, "user.name", timeoutMs);
+    if (name)
+        return name;
     return "unknown";
 }
 /** Policy sensitivity from built-in map plus `policy.extraSensitiveModuleCommands` on effective config. */

package/dist/core/transcript-completion-hook.js

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, statSync, unlinkSync, writeFileSync } from "node
 import path from "node:path";
 import { spawn } from "node:child_process";
 const LOCK_REL = ".workspace-kit/improvement/transcript-hook.lock";
+const EVENT_LOG_REL = ".workspace-kit/improvement/transcript-hook-events.jsonl";
 const LOCK_STALE_MS = 120_000;
 export function readAfterTaskCompletedHook(effective) {
     const imp = effective.improvement;
@@ -39,31 +40,62 @@ function hookLockBusy(workspacePath) {
         return false;
     }
 }
+function appendHookEvent(workspacePath, event, details) {
+    const fp = path.join(workspacePath, EVENT_LOG_REL);
+    try {
+        mkdirSync(path.dirname(fp), { recursive: true });
+        writeFileSync(fp, `${JSON.stringify({
+            schemaVersion: 1,
+            timestamp: new Date().toISOString(),
+            event,
+            ...details
+        })}\n`, { encoding: "utf8", flag: "a" });
+    }
+    catch {
+        // Observability must never block task transitions.
+    }
+}
 /**
  * After a task reaches `completed`, optionally spawn sync/ingest without blocking the transition (T274).
  * Ingest requires WORKSPACE_KIT_POLICY_APPROVAL in the parent env or falls back to sync.
  */
 export function maybeSpawnTranscriptHookAfterCompletion(workspacePath, effective) {
     const mode = readAfterTaskCompletedHook(effective);
-    if (mode === "off")
+    if (mode === "off") {
+        appendHookEvent(workspacePath, "skipped", { reason: "hook-mode-off" });
         return;
-    if (hookLockBusy(workspacePath))
+    }
+    if (hookLockBusy(workspacePath)) {
+        appendHookEvent(workspacePath, "skipped", { reason: "lock-busy", mode });
         return;
+    }
     let subcommand = "sync-transcripts";
     if (mode === "ingest" && process.env.WORKSPACE_KIT_POLICY_APPROVAL?.trim()) {
         subcommand = "ingest-transcripts";
     }
     const cli = resolveWorkspaceKitCli(workspacePath);
-    if (!cli)
+    if (!cli) {
+        appendHookEvent(workspacePath, "failed", {
+            reason: "cli-not-found",
+            mode,
+            subcommand
+        });
         return;
+    }
     const fp = lockPath(workspacePath);
     try {
         mkdirSync(path.dirname(fp), { recursive: true });
         writeFileSync(fp, `${JSON.stringify({ at: new Date().toISOString(), subcommand })}\n`, "utf8");
     }
     catch {
+        appendHookEvent(workspacePath, "failed", {
+            reason: "lock-write-failed",
+            mode,
+            subcommand
+        });
         return;
     }
+    appendHookEvent(workspacePath, "started", { mode, subcommand });
     const child = spawn(process.execPath, [cli, "run", subcommand, "{}"], {
         cwd: workspacePath,
         detached: true,
@@ -78,6 +110,7 @@ export function maybeSpawnTranscriptHookAfterCompletion(workspacePath, effective
         catch {
             /* ignore */
         }
+        appendHookEvent(workspacePath, "completed", { mode, subcommand });
     });
     child.on("error", () => {
         try {
@@ -86,5 +119,10 @@ export function maybeSpawnTranscriptHookAfterCompletion(workspacePath, effective
         catch {
             /* ignore */
         }
+        appendHookEvent(workspacePath, "failed", {
+            reason: "spawn-error",
+            mode,
+            subcommand
+        });
     });
 }

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

@@ -12,7 +12,8 @@ export declare function getProjectConfigPath(workspacePath: string): string;
 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.
+ * Keep true defaults in KIT_CONFIG_DEFAULTS as the canonical source; use this map
+ * only when a module contributes additional non-default config structure.
  */
 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>;