@workflow-cannon/workspace-kit 0.7.0 → 0.9.0

package/README.md

@@ -62,7 +62,7 @@ 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 `docs/maintainers/TASKS.md` and `docs/maintainers/ROADMAP.md`.
+- **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.
 
@@ -87,7 +87,7 @@ npm install @workflow-cannon/workspace-kit
 - `README.md` - project entry point
 - `.ai/PRINCIPLES.md` - project goals and decision principles (canonical AI)
 - `docs/maintainers/ROADMAP.md` - roadmap and decision log
-- `docs/maintainers/TASKS.md` - execution tracking
+- `.workspace-kit/tasks/state.json` - execution tracking
 - `docs/maintainers/ARCHITECTURE.md` - architecture direction
 - `docs/maintainers/DECISIONS.md` - focused design/decision notes
 - `docs/maintainers/RELEASING.md` - release checklist and validation expectations
@@ -100,12 +100,13 @@ npm install @workflow-cannon/workspace-kit
 
 - Project goals and decision principles: `.ai/PRINCIPLES.md`
 - Strategy and long-range direction: `docs/maintainers/ROADMAP.md`
-- Active execution tasks: `docs/maintainers/TASKS.md`
+- Active execution tasks: `.workspace-kit/tasks/state.json`
 - 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,21 +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 { 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",
@@ -106,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"
         });
@@ -119,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
@@ -273,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;
                     }
@@ -418,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"
@@ -552,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`);
             }
         }
@@ -579,121 +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);
-        if (sensitive) {
-            const approval = parsePolicyApproval(commandArgs);
-            if (!approval) {
-                const op = resolvePolicyOperationIdForCommand(subcommand, effective);
-                if (op) {
-                    await appendPolicyTrace(cwd, {
-                        timestamp: new Date().toISOString(),
-                        operationId: op,
-                        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: {"policyApproval":{"confirmed":true,"rationale":"user approved in chat"}}'
-                }, null, 2));
-                return EXIT_VALIDATION_FAILURE;
-            }
-        }
-        const ctx = {
-            runtimeVersion: "0.1",
-            workspacePath: cwd,
-            effectiveConfig: effective,
-            resolvedActor: actor,
-            moduleRegistry: registry
-        };
-        try {
-            const result = await router.execute(subcommand, commandArgs, ctx);
-            if (sensitive) {
-                const approval = parsePolicyApproval(commandArgs);
-                const op = resolvePolicyOperationIdForCommand(subcommand, effective);
-                if (approval && op) {
-                    await appendPolicyTrace(cwd, {
-                        timestamp: new Date().toISOString(),
-                        operationId: op,
-                        command: `run ${subcommand}`,
-                        actor,
-                        allowed: true,
-                        rationale: approval.rationale,
-                        commandOk: result.ok,
-                        message: result.message
-                    });
-                }
-            }
-            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/contracts/index.d.ts

@@ -1 +1 @@
-export type { ConfigRegistryView, ModuleCommand, ModuleCommandResult, ModuleCapability, ModuleDocumentContract, ModuleEvent, ModuleInstructionContract, ModuleInstructionEntry, ModuleLifecycleContext, ModuleRegistration, WorkflowModule } from "./module-contract.js";
+export type { ConfigRegistryView, ResponseTemplateApplicationMeta, ModuleCommand, ModuleCommandResult, ModuleCapability, ModuleDocumentContract, ModuleEvent, ModuleInstructionContract, ModuleInstructionEntry, ModuleLifecycleContext, ModuleRegistration, WorkflowModule } from "./module-contract.js";

package/dist/contracts/module-contract.d.ts

@@ -30,11 +30,24 @@ export type ModuleCommand = {
     name: string;
     args?: Record<string, unknown>;
 };
+/** Structured response-template application record (Phase 6b); mirrored in core for shaping. */
+export type ResponseTemplateApplicationMeta = {
+    requestedTemplateId: string | null;
+    appliedTemplateId: string | null;
+    enforcementMode: "advisory" | "strict";
+    warnings: string[];
+    telemetry?: {
+        resolveNs: number;
+        warningCount: number;
+    };
+};
 export type ModuleCommandResult = {
     ok: boolean;
     code: string;
     message?: string;
     data?: Record<string, unknown>;
+    /** Advisory response-template shaping metadata; always present for `workspace-kit run` JSON output when enabled. */
+    responseTemplate?: ResponseTemplateApplicationMeta;
 };
 /** Subset of module registry used for config layer ordering (avoids core↔contracts cycles). */
 export type ConfigRegistryView = {

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 });