@workflow-cannon/workspace-kit 0.8.0 → 0.10.0

package/README.md

@@ -61,10 +61,12 @@ This keeps automation adaptive without sacrificing safety, governance, or develo
 
 ## Current Status
 
-- **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 `.workspace-kit/tasks/state.json` and `docs/maintainers/ROADMAP.md`.
-- **Phase 2b** (policy + config UX, `v0.4.1`) and **Phase 3** (enhancement loop MVP, `v0.5.0`) are complete in-repo: evidence-driven **improvement** tasks, **`approvals`** (`review-item`), heuristic confidence, and append-only lineage.
-- **Phase 4** (`v0.6.0`) is complete in-repo: compatibility matrix/gates, diagnostics/SLO baseline evidence, release-channel mapping, and planning-doc consistency checks.
+**Release and phase truth:** see `docs/maintainers/ROADMAP.md` and `docs/maintainers/data/workspace-kit-status.yaml`. **Task queue:** `.workspace-kit/tasks/state.json` (ids and `status` are authoritative for execution).
+
+- **Phases 0–7** are complete through **`v0.9.0`** (see roadmap for slice ids).
+- **Phase 8** ships maintainer/onboarding hardening (`v0.10.0`): policy denial clarity, runbooks, and doc alignment for CLI vs `run` approval.
+
+Historical note: this file’s milestone list is not the live queue—always check task state for **`ready`** work.
 
 ## Goals
 
@@ -82,6 +84,18 @@ Install:
 npm install @workflow-cannon/workspace-kit
 ```
 
+### How to run the CLI (this repo and consumers)
+
+There is **no** IDE slash command like `/qt` defined by this package unless your own editor config adds one. Supported entrypoints:
+
+| Context | Command |
+| --- | --- |
+| **Installed package** | `npx @workflow-cannon/workspace-kit --help` or `pnpm exec workspace-kit --help` when the package is a dependency |
+| **Developing this repo** | `pnpm run build` then `node dist/cli.js --help` or `pnpm exec workspace-kit --help` if linked |
+| **Transcript helpers** | `pnpm run transcript:sync` / `pnpm run transcript:ingest` (see maintainer runbooks) |
+
+Mutating commands require policy approval: **`docs/maintainers/POLICY-APPROVAL.md`** (JSON **`policyApproval`** for `workspace-kit run`, env for `config`/`init`/`upgrade`).
+
 ## Repository Map
 
 - `README.md` - project entry point
@@ -104,8 +118,10 @@ 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`
+- Policy / approval surfaces: `docs/maintainers/POLICY-APPROVAL.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,143 @@
+import { ModuleRegistry } from "../core/module-registry.js";
+import { ModuleCommandRouter } from "../core/module-command-router.js";
+import { appendPolicyTrace, isSensitiveModuleCommandForEffective, parsePolicyApproval, POLICY_APPROVAL_HUMAN_DOC, 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",
+                operationId: policyOp ?? null,
+                remediationDoc: POLICY_APPROVAL_HUMAN_DOC,
+                message: 'Sensitive command requires policyApproval in JSON args (or an existing session grant for this operation). Example: {"policyApproval":{"confirmed":true,"rationale":"why","scope":"session"}}. See remediationDoc for env vs JSON approval surfaces.',
+                hint: policyOp != null
+                    ? `Operation ${policyOp} requires explicit approval; WORKSPACE_KIT_POLICY_APPROVAL is not read for workspace-kit run.`
+                    : "Operation could not be mapped to policyOperationId; check policy.extraSensitiveModuleCommands and pass policyApproval in JSON args."
+            }, 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",
@@ -103,12 +94,12 @@ export async function parseJsonFile(filePath) {
 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).`);
+        writeError(`workspace-kit ${commandLabel} (${operationId}) requires WORKSPACE_KIT_POLICY_APPROVAL with JSON {"confirmed":true,"rationale":"..."} (agent-mediated). For workspace-kit run sensitive commands, use policyApproval in JSON args instead — see docs/maintainers/POLICY-APPROVAL.md.`);
         await appendPolicyTrace(cwd, {
             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";
@@ -109,12 +109,12 @@ function parseConfigArgs(argv) {
 async function requireConfigApproval(cwd, commandLabel, writeError) {
     const approval = parsePolicyApprovalFromEnv(process.env);
     if (!approval) {
-        writeError(`${commandLabel} requires WORKSPACE_KIT_POLICY_APPROVAL with JSON {"confirmed":true,"rationale":"..."}.`);
+        writeError(`${commandLabel} (cli.config-mutate) requires WORKSPACE_KIT_POLICY_APPROVAL with JSON {"confirmed":true,"rationale":"..."}. See docs/maintainers/POLICY-APPROVAL.md.`);
         await appendPolicyTrace(cwd, {
             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/index.d.ts

@@ -1,7 +1,7 @@
 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 { appendPolicyTrace, getExtraSensitiveModuleCommandsFromEffective, getOperationIdForCommand, isSensitiveModuleCommand, isSensitiveModuleCommandForEffective, parsePolicyApproval, parsePolicyApprovalFromEnv, POLICY_APPROVAL_HUMAN_DOC, POLICY_TRACE_SCHEMA_VERSION, resolveActor, resolvePolicyOperationIdForCommand, type PolicyOperationId, type PolicyTraceRecord, type PolicyTraceRecordInput } from "./policy.js";
 export { getSessionGrant, loadSessionPolicyDocument, recordSessionGrant, resolveSessionId, SESSION_POLICY_SCHEMA_VERSION, type SessionPolicyDocument, type SessionPolicyGrant } from "./session-policy.js";
 export { parseTemplateDirectiveFromText } from "./instruction-template-mapper.js";
 export { RESPONSE_TEMPLATE_CONTRACT_VERSION, MAX_TEMPLATE_WARNING_LENGTH, truncateTemplateWarning, type ResponseTemplateDefinition, type ResponseTemplateEnforcementMode } from "./response-template-contract.js";

package/dist/core/index.js

@@ -1,7 +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 { appendPolicyTrace, getExtraSensitiveModuleCommandsFromEffective, getOperationIdForCommand, isSensitiveModuleCommand, isSensitiveModuleCommandForEffective, parsePolicyApproval, parsePolicyApprovalFromEnv, POLICY_APPROVAL_HUMAN_DOC, POLICY_TRACE_SCHEMA_VERSION, resolveActor, resolvePolicyOperationIdForCommand } from "./policy.js";
 export { getSessionGrant, loadSessionPolicyDocument, recordSessionGrant, resolveSessionId, SESSION_POLICY_SCHEMA_VERSION } from "./session-policy.js";
 export { parseTemplateDirectiveFromText } from "./instruction-template-mapper.js";
 export { RESPONSE_TEMPLATE_CONTRACT_VERSION, MAX_TEMPLATE_WARNING_LENGTH, truncateTemplateWarning } from "./response-template-contract.js";

package/dist/core/policy.d.ts

@@ -1,4 +1,6 @@
 export declare const POLICY_TRACE_SCHEMA_VERSION: 1;
+/** Maintainer doc (repo-relative) linked from policy denial output for `workspace-kit run`. */
+export declare const POLICY_APPROVAL_HUMAN_DOC = "docs/maintainers/POLICY-APPROVAL.md";
 export type PolicyOperationId = "cli.upgrade" | "cli.init" | "cli.config-mutate" | "policy.dynamic-sensitive" | "doc.document-project" | "doc.generate-document" | "tasks.run-transition" | "approvals.review-item" | "improvement.generate-recommendations" | "improvement.ingest-transcripts";
 export declare function getOperationIdForCommand(commandName: string): PolicyOperationId | undefined;
 export declare function getExtraSensitiveModuleCommandsFromEffective(effective: Record<string, unknown>): string[];
@@ -17,7 +19,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,7 +1,9 @@
 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;
+/** Maintainer doc (repo-relative) linked from policy denial output for `workspace-kit run`. */
+export const POLICY_APPROVAL_HUMAN_DOC = "docs/maintainers/POLICY-APPROVAL.md";
 const COMMAND_TO_OPERATION = {
     "document-project": "doc.document-project",
     "generate-document": "doc.generate-document",
@@ -83,37 +85,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. */