@workflow-cannon/workspace-kit 0.18.0 → 0.24.0

package/README.md

@@ -1,4 +1,4 @@
-AI agents: `./.ai/` is the authoritative source of truth; read all files there before any analysis, planning, or code changes, and follow `./.ai/` over `README.md`, `./docs/`, and conflicting existing code patterns.
+AI agents: read **`./.ai/`** first for machine-oriented contracts (module build rules, principles). For **conflicts between** `.ai/`, `docs/maintainers/`, `.cursor/rules/`, and code, use the ordered **Source-of-truth** list in [`docs/maintainers/AGENTS.md`](docs/maintainers/AGENTS.md) and the precedence note in [`docs/maintainers/ARCHITECTURE.md`](docs/maintainers/ARCHITECTURE.md) — do not rely on this README alone for governance precedence.
 
 <div align="center">
   <img src="title_image.png" alt="Workflow Cannon" width="720" />
@@ -19,12 +19,24 @@ pnpm install
 pnpm run build
 ```
 
-Verify the kit sees your workspace:
+### Where to start after build
 
-```bash
-node dist/cli.js doctor
-node dist/cli.js --help
-```
+| Step | Command | What you get |
+| --- | --- | --- |
+| 1 | `node dist/cli.js --help` | Orientation: top-level commands, first-run path, doc pointers |
+| 2 | `node dist/cli.js doctor` | Confirms kit contract files and config resolve |
+| 3 | `node dist/cli.js run` | **Command menu** — every runnable `workspace-kit run <cmd>` |
+| 4 | `node dist/cli.js run get-next-actions '{}'` | Read-only suggestion for what to do next |
+
+**Developing:** after edits, `pnpm run build` then `pnpm test` (or `pnpm run phase5-gates` before larger changes). **`workspace-kit` is not on your PATH by default** — invoke it in one of these ways:
+
+| Situation | Example |
+| --- | --- |
+| This repo, after `pnpm run build` | `node dist/cli.js --help` (same subcommands as `workspace-kit`) |
+| This repo, dev dependency on PATH via pnpm | `pnpm exec workspace-kit --help` |
+| Another project with the package installed | `npx workspace-kit --help` or `pnpm exec workspace-kit --help` |
+
+**`workspace-kit run` with no subcommand is the full module command list** — that is the usual “what can I run?” answer.
 
 Try **read-only** task-engine queries:
 
@@ -33,16 +45,17 @@ node dist/cli.js run list-tasks '{}'
 node dist/cli.js run get-next-actions '{}'
 ```
 
-**Developing:** after edits, `pnpm run build` then `pnpm test` (or `pnpm run phase5-gates` before larger changes). If `workspace-kit` is not on your `PATH`, use `node dist/cli.js …` from the repo root (same as above).
-
 ## Quick start (use the package in another project)
 
 ```bash
 npm install @workflow-cannon/workspace-kit
 npx workspace-kit --help
+npx workspace-kit run
 ```
 
-Or with pnpm: `pnpm add @workflow-cannon/workspace-kit` then `pnpm exec workspace-kit --help`.
+`--help` prints the top-level guide; `run` with no subcommand lists every module command. In a repo that already contains maintainer docs, paths like `docs/maintainers/AGENT-CLI-MAP.md` match this repository; in a consumer project, use the copy shipped under `node_modules/@workflow-cannon/workspace-kit/` or your own docs link.
+
+Or with pnpm: `pnpm add @workflow-cannon/workspace-kit` then `pnpm exec workspace-kit --help` and `pnpm exec workspace-kit run`.
 
 ## What this repo contains
 
@@ -79,6 +92,7 @@ Snapshot: [`docs/maintainers/data/workspace-kit-status.yaml`](docs/maintainers/d
 | Glossary | [`docs/maintainers/TERMS.md`](docs/maintainers/TERMS.md) |
 | Architecture | [`docs/maintainers/ARCHITECTURE.md`](docs/maintainers/ARCHITECTURE.md) |
 | Agent/CLI execution | [`docs/maintainers/AGENTS.md`](docs/maintainers/AGENTS.md) |
+| CLI visual map (diagrams) | [`docs/maintainers/CLI-VISUAL-GUIDE.md`](docs/maintainers/CLI-VISUAL-GUIDE.md) |
 
 ## License
 

package/dist/cli/doctor-planning-issues.js

@@ -1,29 +1,10 @@
-import { ModuleRegistry } from "../core/module-registry.js";
-import { resolveWorkspaceConfigWithLayers } from "../core/workspace-kit-config.js";
+import { resolveRegistryAndConfig } from "../core/module-registry-resolve.js";
 import { validatePlanningPersistenceForDoctor } from "../modules/task-engine/doctor-planning-persistence.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 defaultRegistryModules = [
-    workspaceConfigModule,
-    documentationModule,
-    taskEngineModule,
-    approvalsModule,
-    planningModule,
-    improvementModule
-];
+import { defaultRegistryModules } from "../modules/index.js";
 /** Resolve layered config and run SQLite planning persistence checks for `workspace-kit doctor`. */
 export async function collectDoctorPlanningPersistenceIssues(cwd) {
     try {
-        const registry = new ModuleRegistry(defaultRegistryModules);
-        const { effective } = await resolveWorkspaceConfigWithLayers({
-            workspacePath: cwd,
-            registry,
-            invocationConfig: {}
-        });
+        const { effective } = await resolveRegistryAndConfig(cwd, defaultRegistryModules, {});
         return validatePlanningPersistenceForDoctor(cwd, effective);
     }
     catch (err) {

package/dist/cli/run-command.js

@@ -1,44 +1,15 @@
-import { ModuleRegistry } from "../core/module-registry.js";
 import { ModuleCommandRouter } from "../core/module-command-router.js";
+import { resolveRegistryAndConfig } from "../core/module-registry-resolve.js";
 import { appendPolicyTrace, isSensitiveModuleCommandForEffective, parsePolicyApproval, AGENT_CLI_MAP_HUMAN_DOC, 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";
+import { defaultRegistryModules } from "../modules/index.js";
 import { promptSensitiveRunApproval } from "./interactive-policy.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]`);
-        writeLine(`Instruction files: src/modules/<module>/instructions/<command>.md — policy-sensitive runs need JSON policyApproval (${POLICY_APPROVAL_HUMAN_DOC}).`);
-        writeLine(`Agent-oriented tier table + copy-paste patterns: ${AGENT_CLI_MAP_HUMAN_DOC}.`);
-        return codes.success;
-    }
     let commandArgs = {};
-    if (args[2]) {
+    if (subcommand && args[2]) {
         try {
             const parsed = JSON.parse(args[2]);
             if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
@@ -59,20 +30,33 @@ export async function handleRunCommand(cwd, args, io, codes) {
         !Array.isArray(commandArgs.config)
         ? commandArgs.config
         : {};
+    let registry;
+    let router;
     let effective;
     try {
-        const resolved = await resolveWorkspaceConfigWithLayers({
-            workspacePath: cwd,
-            registry,
-            invocationConfig
-        });
+        const resolved = await resolveRegistryAndConfig(cwd, defaultRegistryModules, invocationConfig);
+        registry = resolved.registry;
         effective = resolved.effective;
+        router = new ModuleCommandRouter(registry);
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        writeError(`Config resolution failed: ${message}`);
+        writeError(`Module registry / config resolution failed: ${message}`);
         return codes.validationFailure;
     }
+    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]`);
+        writeLine(`Instruction files: src/modules/<module>/instructions/<command>.md — policy-sensitive runs need JSON policyApproval (${POLICY_APPROVAL_HUMAN_DOC}).`);
+        writeLine(`Agent-oriented tier table + copy-paste patterns: ${AGENT_CLI_MAP_HUMAN_DOC}.`);
+        return codes.success;
+    }
     const actor = await resolveActorWithFallback(cwd, commandArgs, process.env);
     const sensitive = isSensitiveModuleCommandForEffective(subcommand, commandArgs, effective);
     const sessionId = resolveSessionId(process.env);

package/dist/cli.js

@@ -1,11 +1,15 @@
 #!/usr/bin/env node
 import fs from "node:fs/promises";
 import path from "node:path";
-import { pathToFileURL } from "node:url";
-import { AGENT_CLI_MAP_HUMAN_DOC, appendPolicyTrace, parsePolicyApprovalFromEnv, resolveActorWithFallback } from "./core/policy.js";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { AGENT_CLI_MAP_HUMAN_DOC, POLICY_APPROVAL_HUMAN_DOC, appendPolicyTrace, parsePolicyApprovalFromEnv, resolveActorWithFallback } from "./core/policy.js";
+import { buildAgentInstructionSurface } from "./core/agent-instruction-surface.js";
 import { runWorkspaceConfigCli } from "./core/config-cli.js";
 import { handleRunCommand } from "./cli/run-command.js";
 import { collectDoctorPlanningPersistenceIssues } from "./cli/doctor-planning-issues.js";
+import { ModuleRegistryError } from "./core/module-registry.js";
+import { resolveRegistryAndConfig } from "./core/module-registry-resolve.js";
+import { defaultRegistryModules } from "./modules/index.js";
 const EXIT_SUCCESS = 0;
 const EXIT_VALIDATION_FAILURE = 1;
 const EXIT_USAGE_ERROR = 2;
@@ -281,6 +285,62 @@ async function resolvePackageVersion(cwd) {
     }
     return undefined;
 }
+/** Version from the installed kit package (works from repo `dist/` or `node_modules`). */
+async function readCliBundledPackageVersion() {
+    try {
+        const pkgPath = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+        const parsed = await parseJsonFile(pkgPath);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            const v = parsed.version;
+            return typeof v === "string" && v.length > 0 ? v : undefined;
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    return undefined;
+}
+function writeDoctorFailureRemediation(writeError, issues) {
+    writeError("");
+    writeError("Next steps:");
+    const hasMissing = issues.some((issue) => issue.reason === "missing");
+    if (hasMissing) {
+        writeError("  - Kit files missing: run workspace-kit upgrade from the repo root (set WORKSPACE_KIT_POLICY_APPROVAL — see docs/maintainers/POLICY-APPROVAL.md).");
+    }
+    writeError("  - workspace-kit --help — orientation and top-level commands");
+    writeError("  - workspace-kit run — list module commands (after doctor passes)");
+}
+async function printWorkspaceKitTopLevelHelp(writeLine) {
+    const version = await readCliBundledPackageVersion();
+    const versionSuffix = version ? ` v${version}` : "";
+    writeLine(`Workflow Cannon — workspace-kit${versionSuffix} (${CANONICAL_KIT_NAME})`);
+    writeLine("");
+    writeLine("CLI for deterministic, policy-governed task workflows. Module commands are listed separately.");
+    writeLine("");
+    writeLine("Start here (first time in a kit-enabled repo)");
+    writeLine("  1) workspace-kit doctor");
+    writeLine("  2) workspace-kit run              ← lists every module command (your command menu)");
+    writeLine("  3) workspace-kit run get-next-actions '{}'   ← safe read: suggested next work");
+    writeLine("");
+    writeLine("Top-level commands");
+    writeLine("  doctor          Validate kit contract files, config, and persistence checks");
+    writeLine("  doctor --agent-instruction-surface   JSON catalog of all declared instructions");
+    writeLine("  run <cmd> [json]  Run a module command; omit <cmd> to list runnable commands");
+    writeLine("  config          Show or change kit config (mutations need env approval — see below)");
+    writeLine("  check           Validate workspace-kit.profile.json");
+    writeLine("  init            Regenerate profile-driven artifacts (needs env approval)");
+    writeLine("  upgrade         Refresh kit-managed baseline files (needs env approval)");
+    writeLine("  drift-check     Fail if managed kit assets differ from expected content");
+    writeLine("");
+    writeLine("Policy & docs (paths are relative to a clone of this repo; npm consumers: open the package or docs site)");
+    writeLine(`  ${AGENT_CLI_MAP_HUMAN_DOC} — tier table, copy-paste JSON for agents`);
+    writeLine(`  ${POLICY_APPROVAL_HUMAN_DOC} — when policyApproval JSON vs env approval applies`);
+    writeLine("");
+    writeLine("Global options");
+    writeLine("  -h, --help      Show this message");
+    writeLine("  -V, --version   Print CLI version");
+    writeLine("  help            Same as --help");
+}
 async function readOwnedPathsDocument(cwd) {
     const ownedPathsPath = path.join(cwd, defaultWorkspaceKitPaths.ownedPaths);
     let parsed;
@@ -338,8 +398,18 @@ export async function runCli(args, options = {}) {
     const writeError = options.writeError ?? console.error;
     const readStdinLine = options.readStdinLine;
     const [command] = args;
+    if (command === "--version" || command === "-V") {
+        const v = await readCliBundledPackageVersion();
+        writeLine(v ?? "workspace-kit (version unknown)");
+        return EXIT_SUCCESS;
+    }
+    if (command === "--help" || command === "-h" || command === "help") {
+        await printWorkspaceKitTopLevelHelp(writeLine);
+        return EXIT_SUCCESS;
+    }
     if (!command) {
-        writeError("Usage: workspace-kit <init|doctor|check|upgrade|drift-check|run|config>");
+        await printWorkspaceKitTopLevelHelp(writeLine);
+        writeError("Missing command. Re-run with a top-level command, or pass --help for the same guide.");
         return EXIT_USAGE_ERROR;
     }
     if (command === "config") {
@@ -581,9 +651,12 @@ export async function runCli(args, options = {}) {
         });
     }
     if (command !== "doctor") {
-        writeError(`Unknown command '${command}'. Supported commands: init, doctor, check, upgrade, drift-check, run, config.`);
+        writeError(`Unknown command '${command}'. Supported: init, doctor, check, upgrade, drift-check, run, config. Run workspace-kit --help for a guided overview.`);
         return EXIT_USAGE_ERROR;
     }
+    const doctorRest = args.slice(1);
+    const wantAgentInstructionSurface = doctorRest.includes("--agent-instruction-surface") ||
+        doctorRest.includes("agent-instruction-surface");
     const issues = [];
     const requiredPaths = Object.values(defaultWorkspaceKitPaths).map((relativePath) => path.join(cwd, relativePath));
     for (const requiredPath of requiredPaths) {
@@ -613,8 +686,26 @@ export async function runCli(args, options = {}) {
         for (const issue of issues) {
             writeError(`- ${issue.path}: ${issue.reason}`);
         }
+        writeDoctorFailureRemediation(writeError, issues);
         return EXIT_VALIDATION_FAILURE;
     }
+    if (wantAgentInstructionSurface) {
+        try {
+            const { registry } = await resolveRegistryAndConfig(cwd, defaultRegistryModules);
+            const surface = buildAgentInstructionSurface(registry.getAllModules(), registry);
+            writeLine(JSON.stringify({ ok: true, code: "agent-instruction-surface", data: surface }, null, 2));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            writeError(`workspace-kit doctor: could not build agent instruction surface: ${message}`);
+            writeError("  Hint: workspace-kit --help; fix config/module issues, then retry.");
+            if (error instanceof ModuleRegistryError) {
+                return EXIT_VALIDATION_FAILURE;
+            }
+            return EXIT_INTERNAL_ERROR;
+        }
+        return EXIT_SUCCESS;
+    }
     writeLine("workspace-kit doctor passed.");
     writeLine("All canonical workspace-kit contract files are present and parseable JSON.");
     writeLine("Effective workspace config resolved; task planning persistence checks passed (including SQLite when configured).");

package/dist/contracts/command-manifest.d.ts

@@ -0,0 +1,17 @@
+import type { ModuleInstructionEntry } from "./module-contract.js";
+/**
+ * Single-row command declaration for a module: instruction catalog metadata plus optional
+ * policy binding for Tier A/B `workspace-kit run` sensitivity (see `docs/maintainers/POLICY-APPROVAL.md`).
+ *
+ * Phase 20: policy bindings are assembled in `src/core/policy.ts` from per-module `policy-sensitive-commands.ts`
+ * files so operation ids are not duplicated alongside `COMMAND_TO_OPERATION`.
+ *
+ * Future: merge `ModuleInstructionEntry` generation from the same manifest rows (see `docs/maintainers/module-build-guide.md`).
+ */
+export type ModuleCommandManifestRow = ModuleInstructionEntry & {
+    /**
+     * When set, this command requires JSON `policyApproval` (or session grant) for `workspace-kit run`
+     * when sensitive per `isSensitiveModuleCommand` rules in `src/core/policy.ts`.
+     */
+    policyOperationId?: string;
+};

package/dist/contracts/command-manifest.js

@@ -0,0 +1 @@
+export {};

package/dist/contracts/index.d.ts

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

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

@@ -1,4 +1,4 @@
-export type ModuleCapability = "documentation" | "task-engine" | "planning" | "improvement" | "approvals" | "diagnostics" | "migration";
+export type ModuleCapability = "documentation" | "task-engine" | "planning" | "improvement" | "approvals" | "diagnostics" | "migration" | "agent-behavior";
 export type ModuleDocumentContract = {
     path: string;
     format: "md";
@@ -14,6 +14,11 @@ export type ModuleInstructionEntry = {
      */
     file: string;
     description?: string;
+    /**
+     * Other module ids that must be enabled for this command to be registered in the
+     * command router (in addition to the owning module). Empty/omitted = no extra peers.
+     */
+    requiresPeers?: string[];
 };
 export type ModuleInstructionContract = {
     /**
@@ -22,10 +27,6 @@ export type ModuleInstructionContract = {
     directory: string;
     entries: ModuleInstructionEntry[];
 };
-export type ModuleEvent = {
-    type: string;
-    payload?: Record<string, unknown>;
-};
 export type ModuleCommand = {
     name: string;
     args?: Record<string, unknown>;
@@ -71,19 +72,19 @@ export type ModuleRegistration = {
     id: string;
     version: string;
     contractVersion: "1";
+    stateSchema: number;
     capabilities: ModuleCapability[];
     dependsOn: string[];
+    /**
+     * Other modules this module integrates with when present; unlike dependsOn,
+     * missing optional peers do not block registry construction or enablement.
+     */
+    optionalPeers?: string[];
     enabledByDefault: boolean;
     config: ModuleDocumentContract;
-    state: ModuleDocumentContract;
     instructions: ModuleInstructionContract;
 };
 export interface WorkflowModule {
     registration: ModuleRegistration;
-    onInstall?(ctx: ModuleLifecycleContext): Promise<void>;
-    onConfigChange?(ctx: ModuleLifecycleContext): Promise<void>;
-    onStart?(ctx: ModuleLifecycleContext): Promise<void>;
-    onStop?(ctx: ModuleLifecycleContext): Promise<void>;
-    onEvent?(event: ModuleEvent, ctx: ModuleLifecycleContext): Promise<void>;
     onCommand?(command: ModuleCommand, ctx: ModuleLifecycleContext): Promise<ModuleCommandResult>;
 }

package/dist/core/agent-instruction-surface.d.ts

@@ -0,0 +1,33 @@
+import type { ModuleInstructionEntry, WorkflowModule } from "../contracts/module-contract.js";
+import type { ModuleActivationReport, ModuleRegistry } from "./module-registry.js";
+export type AgentInstructionDegradation = {
+    kind: "executable";
+} | {
+    kind: "module_disabled";
+} | {
+    kind: "peer_disabled";
+    missingPeers: string[];
+};
+export type AgentInstructionSurfaceRow = {
+    commandName: string;
+    moduleId: string;
+    /** Repo-relative path to the instruction markdown file. */
+    instructionPath: string;
+    executable: boolean;
+    degradation: AgentInstructionDegradation;
+};
+export type AgentInstructionSurfacePayload = {
+    schemaVersion: 1;
+    commands: AgentInstructionSurfaceRow[];
+    activationReport: ModuleActivationReport;
+};
+/**
+ * Classifies whether an instruction can be executed via the command router for the
+ * current enabled module set (owning module enabled + all requiresPeers enabled).
+ */
+export declare function classifyInstructionExecution(mod: WorkflowModule, entry: ModuleInstructionEntry, registry: ModuleRegistry): AgentInstructionDegradation;
+export declare function isInstructionExecutableForRegistry(mod: WorkflowModule, entry: ModuleInstructionEntry, registry: ModuleRegistry): boolean;
+/**
+ * Full catalog for agents: every declared instruction, with executable vs documentation-only.
+ */
+export declare function buildAgentInstructionSurface(allModules: WorkflowModule[], registry: ModuleRegistry): AgentInstructionSurfacePayload;

package/dist/core/agent-instruction-surface.js

@@ -0,0 +1,46 @@
+/**
+ * Classifies whether an instruction can be executed via the command router for the
+ * current enabled module set (owning module enabled + all requiresPeers enabled).
+ */
+export function classifyInstructionExecution(mod, entry, registry) {
+    const moduleId = mod.registration.id;
+    if (!registry.isModuleEnabled(moduleId)) {
+        return { kind: "module_disabled" };
+    }
+    const requires = entry.requiresPeers ?? [];
+    const missing = requires.filter((peerId) => !registry.isModuleEnabled(peerId));
+    if (missing.length > 0) {
+        return { kind: "peer_disabled", missingPeers: missing };
+    }
+    return { kind: "executable" };
+}
+export function isInstructionExecutableForRegistry(mod, entry, registry) {
+    return classifyInstructionExecution(mod, entry, registry).kind === "executable";
+}
+/**
+ * Full catalog for agents: every declared instruction, with executable vs documentation-only.
+ */
+export function buildAgentInstructionSurface(allModules, registry) {
+    const commands = [];
+    for (const mod of allModules) {
+        const moduleId = mod.registration.id;
+        const { directory, entries } = mod.registration.instructions;
+        for (const entry of entries) {
+            const degradation = classifyInstructionExecution(mod, entry, registry);
+            const instructionPath = `${directory}/${entry.file}`.replace(/\\/g, "/");
+            commands.push({
+                commandName: entry.name,
+                moduleId,
+                instructionPath,
+                executable: degradation.kind === "executable",
+                degradation
+            });
+        }
+    }
+    commands.sort((a, b) => a.commandName.localeCompare(b.commandName));
+    return {
+        schemaVersion: 1,
+        commands,
+        activationReport: registry.getActivationReport()
+    };
+}

package/dist/core/config-cli.js

@@ -3,16 +3,12 @@ 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 { pickModuleContractWorkspacePath, resolveRegistryAndConfig } from "./module-registry-resolve.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";
-import { workspaceConfigModule } from "../modules/workspace-config/index.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 { defaultRegistryModules } from "../modules/index.js";
 const EXIT_SUCCESS = 0;
 const EXIT_VALIDATION_FAILURE = 1;
 const EXIT_USAGE_ERROR = 2;
@@ -90,16 +86,10 @@ async function writeConfigFileAtomic(fp, data) {
     await fs.writeFile(tmp, stableStringifyConfig(data), "utf8");
     await fs.rename(tmp, fp);
 }
-function buildRegistry() {
-    const allModules = [
-        workspaceConfigModule,
-        documentationModule,
-        taskEngineModule,
-        approvalsModule,
-        planningModule,
-        improvementModule
-    ];
-    return new ModuleRegistry(allModules);
+function buildRegistry(workspacePath) {
+    return new ModuleRegistry(defaultRegistryModules, {
+        workspacePath: pickModuleContractWorkspacePath(workspacePath)
+    });
 }
 function parseConfigArgs(argv) {
     const json = argv.includes("--json");
@@ -159,7 +149,13 @@ export async function runWorkspaceConfigCli(cwd, argv, io) {
     }
     let registry;
     try {
-        registry = buildRegistry();
+        if (sub === "list") {
+            registry = buildRegistry(cwd);
+        }
+        else {
+            const resolved = await resolveRegistryAndConfig(cwd, defaultRegistryModules);
+            registry = resolved.registry;
+        }
     }
     catch (e) {
         writeError(e instanceof Error ? e.message : String(e));

package/dist/core/config-metadata.js

@@ -69,6 +69,32 @@ const REGISTRY = {
         exposure: "public",
         writableLayers: ["project", "user"]
     },
+    "modules.enabled": {
+        key: "modules.enabled",
+        type: "array",
+        description: "When non-empty, only these module ids are enabled (whitelist); then modules.disabled subtracts. When empty, all modules use registration.enabledByDefault.",
+        default: [],
+        domainScope: "project",
+        owningModule: "workspace-kit",
+        sensitive: false,
+        requiresRestart: false,
+        requiresApproval: false,
+        exposure: "maintainer",
+        writableLayers: ["project", "user"]
+    },
+    "modules.disabled": {
+        key: "modules.disabled",
+        type: "array",
+        description: "Module ids to disable after computing the candidate enabled set (default-by-flag or modules.enabled whitelist).",
+        default: [],
+        domainScope: "project",
+        owningModule: "workspace-kit",
+        sensitive: false,
+        requiresRestart: false,
+        requiresApproval: false,
+        exposure: "maintainer",
+        writableLayers: ["project", "user"]
+    },
     "planning.defaultQuestionDepth": {
         key: "planning.defaultQuestionDepth",
         type: "string",
@@ -96,6 +122,20 @@ const REGISTRY = {
         exposure: "maintainer",
         writableLayers: ["project", "user"]
     },
+    "planning.adaptiveFinalizePolicy": {
+        key: "planning.adaptiveFinalizePolicy",
+        type: "string",
+        description: "Controls finalize handling for unresolved adaptive follow-up questions: off (ignore), warn (allow finalize with warnings), block (deny finalize).",
+        default: "off",
+        allowedValues: ["off", "warn", "block"],
+        domainScope: "project",
+        owningModule: "planning",
+        sensitive: false,
+        requiresRestart: false,
+        requiresApproval: false,
+        exposure: "maintainer",
+        writableLayers: ["project", "user"]
+    },
     "planning.rulePacks": {
         key: "planning.rulePacks",
         type: "object",
@@ -339,6 +379,13 @@ export function validateValueForMetadata(meta, value) {
                 }
             }
         }
+        if (meta.key === "modules.enabled" || meta.key === "modules.disabled") {
+            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") {
@@ -457,8 +504,20 @@ export function validatePersistedConfigDocument(data, label) {
     }
     const mods = data.modules;
     if (mods !== undefined) {
-        if (typeof mods !== "object" || mods === null || Array.isArray(mods) || Object.keys(mods).length > 0) {
-            throw new Error(`config-invalid(${label}): modules must be absent or an empty object`);
+        if (typeof mods !== "object" || mods === null || Array.isArray(mods)) {
+            throw new Error(`config-invalid(${label}): modules must be an object`);
+        }
+        const m = mods;
+        for (const k of Object.keys(m)) {
+            if (k !== "enabled" && k !== "disabled") {
+                throw new Error(`config-invalid(${label}): unknown modules.${k}`);
+            }
+        }
+        if (m.enabled !== undefined) {
+            validateValueForMetadata(REGISTRY["modules.enabled"], m.enabled);
+        }
+        if (m.disabled !== undefined) {
+            validateValueForMetadata(REGISTRY["modules.disabled"], m.disabled);
         }
     }
     const improvement = data.improvement;

package/dist/core/index.d.ts

@@ -1,5 +1,7 @@
-export { ModuleRegistry, ModuleRegistryError, validateModuleSet, type ModuleRegistryOptions } from "./module-registry.js";
+export { ModuleRegistry, ModuleRegistryError, validateModuleSet, type ModuleActivationEntry, type ModuleActivationReport, type ModuleRegistryOptions } from "./module-registry.js";
+export { moduleRegistryOptionsFromEffectiveConfig, pickModuleContractWorkspacePath, resolveRegistryAndConfig } from "./module-registry-resolve.js";
 export { ModuleCommandRouter, ModuleCommandRouterError, type ModuleCommandDescriptor, type ModuleCommandRouterOptions } from "./module-command-router.js";
+export { buildAgentInstructionSurface, classifyInstructionExecution, isInstructionExecutableForRegistry, type AgentInstructionDegradation, type AgentInstructionSurfacePayload, type AgentInstructionSurfaceRow } from "./agent-instruction-surface.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_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";
@@ -13,4 +15,5 @@ export { appendConfigMutation, CONFIG_MUTATIONS_SCHEMA_VERSION, summarizeForEvid
 export { generateConfigReferenceDocs, runWorkspaceConfigCli, type ConfigCliIo } from "./config-cli.js";
 export { LINEAGE_SCHEMA_VERSION, lineageCorrelationRoot, type LineageAppPayload, type LineageCorrPayload, type LineageDecPayload, type LineageEvent, type LineageEventType, type LineageRecPayload } from "./lineage-contract.js";
 export { appendLineageEvent, newLineageEventId, queryLineageChain, readLineageEvents } from "./lineage-store.js";
+export { UnifiedStateDb, type ModuleStateRow } from "./state/unified-state-db.js";
 export type CoreRuntimeVersion = "0.1";