@workflow-cannon/workspace-kit 0.7.0 → 0.9.0

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,
@@ -80,6 +80,125 @@ const REGISTRY = {
         requiresApproval: false,
         exposure: "maintainer",
         writableLayers: ["project", "user"]
+    },
+    "improvement.cadence.maxRecommendationCandidatesPerRun": {
+        key: "improvement.cadence.maxRecommendationCandidatesPerRun",
+        type: "number",
+        description: "Upper bound on new improvement tasks created per generate-recommendations run (safety cap; direct runs still respect dedupe).",
+        default: 500,
+        domainScope: "project",
+        owningModule: "improvement",
+        sensitive: false,
+        requiresRestart: false,
+        requiresApproval: false,
+        exposure: "maintainer",
+        writableLayers: ["project", "user"]
+    },
+    "improvement.transcripts.maxFilesPerSync": {
+        key: "improvement.transcripts.maxFilesPerSync",
+        type: "number",
+        description: "Maximum JSONL transcript files processed per sync (deterministic order).",
+        default: 5000,
+        domainScope: "project",
+        owningModule: "improvement",
+        sensitive: false,
+        requiresRestart: false,
+        requiresApproval: false,
+        exposure: "maintainer",
+        writableLayers: ["project", "user"]
+    },
+    "improvement.transcripts.maxBytesPerFile": {
+        key: "improvement.transcripts.maxBytesPerFile",
+        type: "number",
+        description: "Skip transcript files larger than this many bytes during sync.",
+        default: 50_000_000,
+        domainScope: "project",
+        owningModule: "improvement",
+        sensitive: false,
+        requiresRestart: false,
+        requiresApproval: false,
+        exposure: "maintainer",
+        writableLayers: ["project", "user"]
+    },
+    "improvement.transcripts.maxTotalScanBytes": {
+        key: "improvement.transcripts.maxTotalScanBytes",
+        type: "number",
+        description: "Approximate cap on total bytes read for hashing during one sync.",
+        default: 500_000_000,
+        domainScope: "project",
+        owningModule: "improvement",
+        sensitive: false,
+        requiresRestart: false,
+        requiresApproval: false,
+        exposure: "maintainer",
+        writableLayers: ["project", "user"]
+    },
+    "improvement.transcripts.discoveryPaths": {
+        key: "improvement.transcripts.discoveryPaths",
+        type: "array",
+        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",
+        sensitive: false,
+        requiresRestart: false,
+        requiresApproval: false,
+        exposure: "maintainer",
+        writableLayers: ["project", "user"]
+    },
+    "improvement.hooks.afterTaskCompleted": {
+        key: "improvement.hooks.afterTaskCompleted",
+        type: "string",
+        description: "Optional background transcript sync after task-engine transition to completed: off (default), sync, or ingest (ingest requires WORKSPACE_KIT_POLICY_APPROVAL in env).",
+        default: "off",
+        allowedValues: ["off", "sync", "ingest"],
+        domainScope: "project",
+        owningModule: "improvement",
+        sensitive: false,
+        requiresRestart: false,
+        requiresApproval: false,
+        exposure: "maintainer",
+        writableLayers: ["project", "user"]
+    },
+    "responseTemplates.enforcementMode": {
+        key: "responseTemplates.enforcementMode",
+        type: "string",
+        description: "Whether unknown/mismatched response templates fail commands (`strict`) or only emit warnings (`advisory`).",
+        default: "advisory",
+        allowedValues: ["advisory", "strict"],
+        domainScope: "project",
+        owningModule: "workspace-kit",
+        sensitive: false,
+        requiresRestart: false,
+        requiresApproval: false,
+        exposure: "maintainer",
+        writableLayers: ["project", "user"]
+    },
+    "responseTemplates.defaultTemplateId": {
+        key: "responseTemplates.defaultTemplateId",
+        type: "string",
+        description: "Builtin response template id applied when a run does not specify one.",
+        default: "default",
+        domainScope: "project",
+        owningModule: "workspace-kit",
+        sensitive: false,
+        requiresRestart: false,
+        requiresApproval: false,
+        exposure: "maintainer",
+        writableLayers: ["project", "user"]
+    },
+    "responseTemplates.commandOverrides": {
+        key: "responseTemplates.commandOverrides",
+        type: "object",
+        description: "Map of module command name to builtin response template id.",
+        default: {},
+        domainScope: "project",
+        owningModule: "workspace-kit",
+        sensitive: false,
+        requiresRestart: false,
+        requiresApproval: false,
+        exposure: "maintainer",
+        writableLayers: ["project", "user"]
     }
 };
 export function getConfigKeyMetadata(key) {
@@ -120,6 +239,13 @@ export function validateValueForMetadata(meta, value) {
                 }
             }
         }
+        if (meta.key === "improvement.transcripts.discoveryPaths") {
+            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") {
@@ -135,6 +261,16 @@ export function validateValueForMetadata(meta, value) {
         if (value === null || typeof value !== "object" || Array.isArray(value)) {
             throw typeError(meta.key, "object", value);
         }
+        if (meta.key === "responseTemplates.commandOverrides") {
+            for (const [k, v] of Object.entries(value)) {
+                if (typeof k !== "string" || !k.trim()) {
+                    throw new Error(`config-type-error(${meta.key}): keys must be non-empty strings`);
+                }
+                if (typeof v !== "string" || !v.trim()) {
+                    throw new Error(`config-type-error(${meta.key}): values must be non-empty strings`);
+                }
+            }
+        }
     }
     if (meta.allowedValues && meta.allowedValues.length > 0) {
         if (!meta.allowedValues.some((v) => deepEqualLoose(v, value))) {
@@ -161,6 +297,7 @@ export function validatePersistedConfigDocument(data, label) {
         "documentation",
         "policy",
         "improvement",
+        "responseTemplates",
         "modules"
     ]);
     for (const k of Object.keys(data)) {
@@ -223,7 +360,7 @@ export function validatePersistedConfigDocument(data, label) {
         }
         const imp = improvement;
         for (const k of Object.keys(imp)) {
-            if (k !== "transcripts" && k !== "cadence") {
+            if (k !== "transcripts" && k !== "cadence" && k !== "hooks") {
                 throw new Error(`config-invalid(${label}): unknown improvement.${k}`);
             }
         }
@@ -235,7 +372,12 @@ export function validatePersistedConfigDocument(data, label) {
             }
             const tr = imp.transcripts;
             for (const k of Object.keys(tr)) {
-                if (k !== "sourcePath" && k !== "archivePath") {
+                if (k !== "sourcePath" &&
+                    k !== "archivePath" &&
+                    k !== "maxFilesPerSync" &&
+                    k !== "maxBytesPerFile" &&
+                    k !== "maxTotalScanBytes" &&
+                    k !== "discoveryPaths") {
                     throw new Error(`config-invalid(${label}): unknown improvement.transcripts.${k}`);
                 }
             }
@@ -245,6 +387,18 @@ export function validatePersistedConfigDocument(data, label) {
             if (tr.archivePath !== undefined) {
                 validateValueForMetadata(REGISTRY["improvement.transcripts.archivePath"], tr.archivePath);
             }
+            if (tr.maxFilesPerSync !== undefined) {
+                validateValueForMetadata(REGISTRY["improvement.transcripts.maxFilesPerSync"], tr.maxFilesPerSync);
+            }
+            if (tr.maxBytesPerFile !== undefined) {
+                validateValueForMetadata(REGISTRY["improvement.transcripts.maxBytesPerFile"], tr.maxBytesPerFile);
+            }
+            if (tr.maxTotalScanBytes !== undefined) {
+                validateValueForMetadata(REGISTRY["improvement.transcripts.maxTotalScanBytes"], tr.maxTotalScanBytes);
+            }
+            if (tr.discoveryPaths !== undefined) {
+                validateValueForMetadata(REGISTRY["improvement.transcripts.discoveryPaths"], tr.discoveryPaths);
+            }
         }
         if (imp.cadence !== undefined) {
             if (typeof imp.cadence !== "object" || imp.cadence === null || Array.isArray(imp.cadence)) {
@@ -252,7 +406,7 @@ export function validatePersistedConfigDocument(data, label) {
             }
             const cd = imp.cadence;
             for (const k of Object.keys(cd)) {
-                if (k !== "minIntervalMinutes" && k !== "skipIfNoNewTranscripts") {
+                if (k !== "minIntervalMinutes" && k !== "skipIfNoNewTranscripts" && k !== "maxRecommendationCandidatesPerRun") {
                     throw new Error(`config-invalid(${label}): unknown improvement.cadence.${k}`);
                 }
             }
@@ -262,6 +416,46 @@ export function validatePersistedConfigDocument(data, label) {
             if (cd.skipIfNoNewTranscripts !== undefined) {
                 validateValueForMetadata(REGISTRY["improvement.cadence.skipIfNoNewTranscripts"], cd.skipIfNoNewTranscripts);
             }
+            if (cd.maxRecommendationCandidatesPerRun !== undefined) {
+                validateValueForMetadata(REGISTRY["improvement.cadence.maxRecommendationCandidatesPerRun"], cd.maxRecommendationCandidatesPerRun);
+            }
+        }
+        if (imp.hooks !== undefined) {
+            if (typeof imp.hooks !== "object" || imp.hooks === null || Array.isArray(imp.hooks)) {
+                throw new Error(`config-invalid(${label}): improvement.hooks must be an object`);
+            }
+            const hk = imp.hooks;
+            for (const k of Object.keys(hk)) {
+                if (k !== "afterTaskCompleted") {
+                    throw new Error(`config-invalid(${label}): unknown improvement.hooks.${k}`);
+                }
+            }
+            if (hk.afterTaskCompleted !== undefined) {
+                validateValueForMetadata(REGISTRY["improvement.hooks.afterTaskCompleted"], hk.afterTaskCompleted);
+            }
+        }
+    }
+    const responseTemplates = data.responseTemplates;
+    if (responseTemplates !== undefined) {
+        if (typeof responseTemplates !== "object" ||
+            responseTemplates === null ||
+            Array.isArray(responseTemplates)) {
+            throw new Error(`config-invalid(${label}): responseTemplates must be an object`);
+        }
+        const rt = responseTemplates;
+        for (const k of Object.keys(rt)) {
+            if (k !== "enforcementMode" && k !== "defaultTemplateId" && k !== "commandOverrides") {
+                throw new Error(`config-invalid(${label}): unknown responseTemplates.${k}`);
+            }
+        }
+        if (rt.enforcementMode !== undefined) {
+            validateValueForMetadata(REGISTRY["responseTemplates.enforcementMode"], rt.enforcementMode);
+        }
+        if (rt.defaultTemplateId !== undefined) {
+            validateValueForMetadata(REGISTRY["responseTemplates.defaultTemplateId"], rt.defaultTemplateId);
+        }
+        if (rt.commandOverrides !== undefined) {
+            validateValueForMetadata(REGISTRY["responseTemplates.commandOverrides"], rt.commandOverrides);
         }
     }
 }

package/dist/core/index.d.ts

@@ -2,6 +2,12 @@ export { ModuleRegistry, ModuleRegistryError, validateModuleSet, type ModuleRegi
 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 { 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";
+export { allBuiltinDefinitions, getResponseTemplateDefinition, listBuiltinResponseTemplateIds } from "./response-template-registry.js";
+export { applyResponseTemplateApplication } from "./response-template-shaping.js";
+export { maybeSpawnTranscriptHookAfterCompletion, readAfterTaskCompletedHook, resolveWorkspaceKitCli } from "./transcript-completion-hook.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";

package/dist/core/index.js

@@ -2,6 +2,12 @@ export { ModuleRegistry, ModuleRegistryError, validateModuleSet } from "./module
 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 { 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";
+export { allBuiltinDefinitions, getResponseTemplateDefinition, listBuiltinResponseTemplateIds } from "./response-template-registry.js";
+export { applyResponseTemplateApplication } from "./response-template-shaping.js";
+export { maybeSpawnTranscriptHookAfterCompletion, readAfterTaskCompletedHook, resolveWorkspaceKitCli } from "./transcript-completion-hook.js";
 export { assertWritableKey, getConfigKeyMetadata, getConfigRegistryExport, listConfigMetadata, validatePersistedConfigDocument, validateValueForMetadata } from "./config-metadata.js";
 export { appendConfigMutation, CONFIG_MUTATIONS_SCHEMA_VERSION, summarizeForEvidence } from "./config-mutations.js";
 export { generateConfigReferenceDocs, runWorkspaceConfigCli } from "./config-cli.js";

package/dist/core/instruction-template-mapper.d.ts

@@ -0,0 +1,9 @@
+export type TemplateDirectiveParseResult = {
+    templateId: string | null;
+    warnings: string[];
+};
+/**
+ * Resolve a template id from free-form instruction text (T263).
+ * Examples: "Use the COMPLETED_TASK template", "template: compact"
+ */
+export declare function parseTemplateDirectiveFromText(text: string): TemplateDirectiveParseResult;

package/dist/core/instruction-template-mapper.js

@@ -0,0 +1,35 @@
+import { truncateTemplateWarning } from "./response-template-contract.js";
+/**
+ * Resolve a template id from free-form instruction text (T263).
+ * Examples: "Use the COMPLETED_TASK template", "template: compact"
+ */
+export function parseTemplateDirectiveFromText(text) {
+    const warnings = [];
+    if (!text || typeof text !== "string") {
+        return { templateId: null, warnings };
+    }
+    const s = text.trim();
+    if (!s)
+        return { templateId: null, warnings };
+    const ids = new Set();
+    const reUseThe = /\buse\s+the\s+([A-Za-z0-9_-]+)\s+template\b/gi;
+    let m;
+    while ((m = reUseThe.exec(s)) !== null) {
+        ids.add(m[1]);
+    }
+    const reTemplateEq = /\btemplate\s*[:=]\s*([A-Za-z0-9_-]+)\b/gi;
+    while ((m = reTemplateEq.exec(s)) !== null) {
+        ids.add(m[1]);
+    }
+    const reBare = /\b(?:responseTemplateId|templateId)\s+is\s+([A-Za-z0-9_-]+)\b/gi;
+    while ((m = reBare.exec(s)) !== null) {
+        ids.add(m[1]);
+    }
+    if (ids.size === 0) {
+        return { templateId: null, warnings };
+    }
+    if (ids.size > 1) {
+        warnings.push(truncateTemplateWarning("Ambiguous template directive: multiple template ids referenced; using first match."));
+    }
+    return { templateId: [...ids][0], warnings };
+}

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

@@ -1,6 +1,6 @@
 /**
  * T203: Immutable lineage event contract (append-only store, correlation fields).
- * @see docs/maintainers/TASKS.md T192, T203
+ * @see .workspace-kit/tasks/state.json T192, T203
  */
 export declare const LINEAGE_SCHEMA_VERSION: 1;
 export type LineageEventType = "rec" | "dec" | "app" | "corr";

package/dist/core/lineage-contract.js

@@ -1,6 +1,6 @@
 /**
  * T203: Immutable lineage event contract (append-only store, correlation fields).
- * @see docs/maintainers/TASKS.md T192, T203
+ * @see .workspace-kit/tasks/state.json T192, T203
  */
 export const LINEAGE_SCHEMA_VERSION = 1;
 /** Stable correlation root: ties chain to recommendation + evidence identity. */

package/dist/core/policy.d.ts

@@ -1,5 +1,5 @@
 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" | "improvement.ingest-transcripts";
+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[];
 /** Resolve operation id for tracing, including config-declared sensitive module commands. */
@@ -8,13 +8,24 @@ export declare function resolvePolicyOperationIdForCommand(commandName: string,
  * Sensitive when mutation / write is possible. Documentation commands are exempt when dryRun is true.
  */
 export declare function isSensitiveModuleCommand(commandName: string, args: Record<string, unknown>): boolean;
+export type PolicyApprovalScope = "once" | "session";
 export type PolicyApprovalPayload = {
     confirmed: boolean;
     rationale: string;
+    /** When `session`, persist approval for this operation until session id changes or grants file is cleared. */
+    scope?: PolicyApprovalScope;
 };
 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,12 +1,10 @@
 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",
     "generate-document": "doc.generate-document",
-    "import-tasks": "tasks.import-tasks",
-    "generate-tasks-md": "tasks.generate-tasks-md",
     "run-transition": "tasks.run-transition",
     "review-item": "approvals.review-item",
     "generate-recommendations": "improvement.generate-recommendations",
@@ -81,39 +79,58 @@ export function parsePolicyApproval(args) {
     if (!confirmed || rationale.length === 0) {
         return undefined;
     }
-    return { confirmed, rationale };
+    const scopeRaw = o.scope;
+    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/response-template-contract.d.ts

@@ -0,0 +1,15 @@
+/** Contract version for response template definitions and CLI shaping metadata. */
+export declare const RESPONSE_TEMPLATE_CONTRACT_VERSION: 1;
+export type ResponseTemplateEnforcementMode = "advisory" | "strict";
+export type ResponseTemplateDefinition = {
+    id: string;
+    /** Monotonic template definition revision for compatibility notes. */
+    version: number;
+    scope: "global" | "command";
+    description: string;
+    /** Logical section keys expected in shaped command `data` (advisory hints only). */
+    expectedSections: string[];
+};
+/** Max length for a single advisory warning line (T265 / T266). */
+export declare const MAX_TEMPLATE_WARNING_LENGTH = 120;
+export declare function truncateTemplateWarning(message: string): string;

package/dist/core/response-template-contract.js

@@ -0,0 +1,10 @@
+/** Contract version for response template definitions and CLI shaping metadata. */
+export const RESPONSE_TEMPLATE_CONTRACT_VERSION = 1;
+/** Max length for a single advisory warning line (T265 / T266). */
+export const MAX_TEMPLATE_WARNING_LENGTH = 120;
+export function truncateTemplateWarning(message) {
+    const t = message.trim();
+    if (t.length <= MAX_TEMPLATE_WARNING_LENGTH)
+        return t;
+    return `${t.slice(0, MAX_TEMPLATE_WARNING_LENGTH - 1)}…`;
+}

package/dist/core/response-template-registry.d.ts

@@ -0,0 +1,4 @@
+import type { ResponseTemplateDefinition } from "./response-template-contract.js";
+export declare function getResponseTemplateDefinition(id: string | undefined): ResponseTemplateDefinition | undefined;
+export declare function listBuiltinResponseTemplateIds(): string[];
+export declare function allBuiltinDefinitions(): ResponseTemplateDefinition[];

package/dist/core/response-template-registry.js

@@ -0,0 +1,44 @@
+const BUILTIN = {
+    default: {
+        id: "default",
+        version: 1,
+        scope: "global",
+        description: "Passthrough with standard ok/code/message/data fields.",
+        expectedSections: ["ok", "code", "message", "data"]
+    },
+    compact: {
+        id: "compact",
+        version: 1,
+        scope: "global",
+        description: "Emphasizes top-level code and message for quick scanning.",
+        expectedSections: ["ok", "code", "message"]
+    },
+    completed_task: {
+        id: "completed_task",
+        version: 1,
+        scope: "command",
+        description: "Structured completion-style surface for task-style commands.",
+        expectedSections: ["ok", "code", "message", "data"]
+    },
+    COMPLETED_TASK: {
+        id: "COMPLETED_TASK",
+        version: 1,
+        scope: "command",
+        description: "Alias id matching plain-English directive spelling.",
+        expectedSections: ["ok", "code", "message", "data"]
+    }
+};
+export function getResponseTemplateDefinition(id) {
+    if (!id || typeof id !== "string")
+        return undefined;
+    const trimmed = id.trim();
+    if (!trimmed)
+        return undefined;
+    return BUILTIN[trimmed] ?? BUILTIN[trimmed.toLowerCase()] ?? undefined;
+}
+export function listBuiltinResponseTemplateIds() {
+    return Object.keys(BUILTIN).sort((a, b) => a.localeCompare(b));
+}
+export function allBuiltinDefinitions() {
+    return Object.values(BUILTIN);
+}

package/dist/core/response-template-shaping.d.ts

@@ -0,0 +1,6 @@
+import type { ModuleCommandResult } from "../contracts/module-contract.js";
+/**
+ * Apply response template metadata and optional presentation hints (T262, T265).
+ * Advisory mode never flips `ok`. Strict mode fails closed on unknown template ids when a template was explicitly requested or command override is set.
+ */
+export declare function applyResponseTemplateApplication(commandName: string, args: Record<string, unknown>, result: ModuleCommandResult, effective: Record<string, unknown>): ModuleCommandResult;