@workflow-cannon/workspace-kit 0.3.0 → 0.4.1

package/README.md

@@ -61,9 +61,9 @@ This keeps automation adaptive without sacrificing safety, governance, or develo
 
 ## Current Status
 
-- Project tracking has been reset for split-repo execution.
-- Current execution phase is **Phase 0 (foundation)**.
-- Phase 0 opens with `T178` to `T180` for release hardening and consumer cadence definition.
+- **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 2b** (policy + config UX, `v0.4.1`) is complete in-repo. **Phase 3** (enhancement loop MVP, `v0.5.0`) is next (`T190` onward).
 
 ## Goals
 

package/dist/cli.js

@@ -4,11 +4,15 @@ 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 { 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";
 const EXIT_SUCCESS = 0;
 const EXIT_VALIDATION_FAILURE = 1;
 const EXIT_USAGE_ERROR = 2;
@@ -94,6 +98,33 @@ export async function parseJsonFile(filePath) {
     const raw = await fs.readFile(filePath, "utf8");
     return JSON.parse(raw);
 }
+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).`);
+        await appendPolicyTrace(cwd, {
+            timestamp: new Date().toISOString(),
+            operationId,
+            command: commandLabel,
+            actor: resolveActor(cwd, {}, process.env),
+            allowed: false,
+            message: "missing WORKSPACE_KIT_POLICY_APPROVAL"
+        });
+        return null;
+    }
+    return { rationale: approval.rationale };
+}
+async function recordCliPolicySuccess(cwd, operationId, commandLabel, rationale, commandOk) {
+    await appendPolicyTrace(cwd, {
+        timestamp: new Date().toISOString(),
+        operationId,
+        command: commandLabel,
+        actor: resolveActor(cwd, {}, process.env),
+        allowed: true,
+        rationale,
+        commandOk
+    });
+}
 function readStringField(objectValue, key, errors, fieldPath) {
     const value = objectValue[key];
     if (typeof value !== "string" || value.trim().length === 0) {
@@ -312,12 +343,20 @@ export async function runCli(args, options = {}) {
     const writeError = options.writeError ?? console.error;
     const [command] = args;
     if (!command) {
-        writeError("Usage: workspace-kit <init|doctor|check|upgrade|drift-check|run>");
+        writeError("Usage: workspace-kit <init|doctor|check|upgrade|drift-check|run|config>");
         return EXIT_USAGE_ERROR;
     }
+    if (command === "config") {
+        return runWorkspaceConfigCli(cwd, args.slice(1), { writeLine, writeError });
+    }
     if (command === "init") {
+        const approval = await requireCliPolicyApproval(cwd, "cli.init", "init", writeError);
+        if (!approval) {
+            return EXIT_VALIDATION_FAILURE;
+        }
         const { errors, profile } = await validateProfile(cwd);
         if (errors.length > 0 || !profile) {
+            await recordCliPolicySuccess(cwd, "cli.init", "init", approval.rationale, false);
             writeError("workspace-kit init failed profile validation.");
             for (const error of errors) {
                 writeError(`- ${error}`);
@@ -328,6 +367,7 @@ export async function runCli(args, options = {}) {
         writeLine("workspace-kit init generated profile-driven project context artifacts.");
         writeLine(`- ${path.relative(cwd, artifacts.generatedJsonPath)}`);
         writeLine(`- ${path.relative(cwd, artifacts.generatedRulePath)}`);
+        await recordCliPolicySuccess(cwd, "cli.init", "init", approval.rationale, true);
         return EXIT_SUCCESS;
     }
     if (command === "check") {
@@ -344,8 +384,13 @@ export async function runCli(args, options = {}) {
         return EXIT_SUCCESS;
     }
     if (command === "upgrade") {
+        const approval = await requireCliPolicyApproval(cwd, "cli.upgrade", "upgrade", writeError);
+        if (!approval) {
+            return EXIT_VALIDATION_FAILURE;
+        }
         const { errors, profile } = await validateProfile(cwd);
         if (errors.length > 0 || !profile) {
+            await recordCliPolicySuccess(cwd, "cli.upgrade", "upgrade", approval.rationale, false);
             writeError("workspace-kit upgrade failed profile validation.");
             for (const error of errors) {
                 writeError(`- ${error}`);
@@ -444,6 +489,7 @@ export async function runCli(args, options = {}) {
             }
         }
         writeLine(`Backups written under: ${path.relative(cwd, backupRoot)}`);
+        await recordCliPolicySuccess(cwd, "cli.upgrade", "upgrade", approval.rationale, true);
         return EXIT_SUCCESS;
     }
     if (command === "drift-check") {
@@ -534,6 +580,7 @@ export async function runCli(args, options = {}) {
     }
     if (command === "run") {
         const allModules = [
+            workspaceConfigModule,
             documentationModule,
             taskEngineModule,
             approvalsModule,
@@ -571,9 +618,74 @@ export async function runCli(args, options = {}) {
                 return EXIT_USAGE_ERROR;
             }
         }
-        const ctx = { runtimeVersion: "0.1", workspacePath: cwd };
+        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;
         }
@@ -584,7 +696,7 @@ export async function runCli(args, options = {}) {
         }
     }
     if (command !== "doctor") {
-        writeError(`Unknown command '${command}'. Supported commands: init, doctor, check, upgrade, drift-check, run.`);
+        writeError(`Unknown command '${command}'. Supported commands: init, doctor, check, upgrade, drift-check, run, config.`);
         return EXIT_USAGE_ERROR;
     }
     const issues = [];

package/dist/contracts/index.d.ts

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

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

@@ -36,9 +36,23 @@ export type ModuleCommandResult = {
     message?: string;
     data?: Record<string, unknown>;
 };
+/** Subset of module registry used for config layer ordering (avoids core↔contracts cycles). */
+export type ConfigRegistryView = {
+    getStartupOrder(): ReadonlyArray<{
+        registration: {
+            id: string;
+        };
+    }>;
+};
 export type ModuleLifecycleContext = {
     runtimeVersion: string;
     workspacePath: string;
+    /** Merged workspace config (kit → modules → project → env → invocation). */
+    effectiveConfig?: Record<string, unknown>;
+    /** Resolved actor for policy traces (see phase2 workbook). */
+    resolvedActor?: string;
+    /** CLI supplies registry for explain-config and config resolution. */
+    moduleRegistry?: ConfigRegistryView;
 };
 export type ModuleRegistration = {
     id: string;

package/dist/core/config-cli.d.ts

@@ -0,0 +1,6 @@
+export type ConfigCliIo = {
+    writeLine: (s: string) => void;
+    writeError: (s: string) => void;
+};
+export declare function generateConfigReferenceDocs(workspacePath: string): Promise<void>;
+export declare function runWorkspaceConfigCli(cwd: string, argv: string[], io: ConfigCliIo): Promise<number>;