@workflow-cannon/workspace-kit 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Workflow Cannon contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+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.
+
+# Workflow Cannon
+
+Workflow Cannon is the canonical home of `@workflow-cannon/workspace-kit` and the operational docs that drive its evolution.
+
+It is built for developers using VS Code who want safe, reproducible, package-first workflow automation with clear release evidence.
+
+## Table of Contents
+
+- [What This Repository Is](#what-this-repository-is)
+- [Big-Picture Vision](#big-picture-vision)
+- [Current Status](#current-status)
+- [Goals](#goals)
+- [Package](#package)
+- [Repository Map](#repository-map)
+- [Documentation Index](#documentation-index)
+- [License](#license)
+
+## What This Repository Is
+
+Workflow Cannon is the source of truth for:
+
+- The `@workflow-cannon/workspace-kit` package
+- Maintainer planning and execution artifacts
+- Consumer validation and release-readiness evidence
+
+Guiding characteristics:
+
+- Package-first delivery and verification
+- Deterministic, auditable workflows
+- Safe-by-default operations (validation, traceability, rollback-friendly changes)
+
+## Big-Picture Vision
+
+Workflow Cannon is evolving from a package and docs repository into a developer workflow platform that can:
+
+- model planning, tasks, policy, and execution as first-class, versioned contracts
+- run repeatable workflows with deterministic outcomes and evidence capture
+- continuously improve itself based on observed friction and outcome data
+
+The long-term direction in this repository is to close the loop between:
+
+1. **What happened** (transcripts, diffs, run artifacts, diagnostics)
+2. **What should change** (recommendations to templates, rules, process, and config)
+3. **What gets adopted** (human-reviewed approvals, policy checks, safe rollout)
+
+### Enhancement Engine (automatic learning and correction)
+
+The Improvement/Enhancement Engine is intended to detect weak spots in workflows and rules, then generate high-signal fixes with supporting evidence. Instead of hard-coding static process forever, the system should learn from real usage patterns and propose better defaults.
+
+In practice, this means:
+
+- detect recurring failure patterns, manual rework, and template drift
+- emit recommendation items with confidence, deduping, and provenance
+- route recommendations through an approval queue (`accept`, `decline`, `accept edited`)
+- apply approved changes through guarded automation (dry-run, diff, rollback-ready)
+- measure post-change outcomes so future recommendations improve over time
+
+This keeps automation adaptive without sacrificing safety, governance, or developer trust.
+
+## 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.
+
+## Goals
+
+- Keep package implementation and release operations centralized here.
+- Preserve independent consumer validation and update cadence.
+- Grow modular capabilities for planning, tasking, configuration, policy, and improvement.
+- Build a human-governed enhancement loop that learns from usage and recommends better workflows/rules.
+- Maintain deterministic and auditable behavior as system complexity increases.
+
+## Package
+
+Install:
+
+```bash
+npm install @workflow-cannon/workspace-kit
+```
+
+## Repository Map
+
+- `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
+- `docs/maintainers/ARCHITECTURE.md` - architecture direction
+- `docs/maintainers/DECISIONS.md` - focused design/decision notes
+- `docs/maintainers/RELEASING.md` - release checklist and validation expectations
+- `.ai/module-build.md` - canonical AI module build guidance
+- `docs/maintainers/` - maintainer process and boundary docs
+- `docs/maintainers/module-build-guide.md` - human-readable module build guidance
+- `docs/adr/` - ADR templates and records
+
+## Documentation Index
+
+- Project goals and decision principles: `.ai/PRINCIPLES.md`
+- Strategy and long-range direction: `docs/maintainers/ROADMAP.md`
+- Active execution tasks: `docs/maintainers/TASKS.md`
+- 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`
+- Release process and gates: `docs/maintainers/RELEASING.md`
+- 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`
+- AI behavior rules and command wrappers: `.cursor/rules/`, `.cursor/commands/`
+
+## License
+
+Licensed under MIT. See `LICENSE`.

package/dist/adapters/index.d.ts

@@ -0,0 +1 @@
+export type AdapterVersion = "0.1";

package/dist/adapters/index.js

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

package/dist/contracts/index.d.ts

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

package/dist/contracts/index.js

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

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

@@ -0,0 +1,62 @@
+export type ModuleCapability = "documentation" | "task-engine" | "planning" | "improvement" | "approvals" | "diagnostics" | "migration";
+export type ModuleDocumentContract = {
+    path: string;
+    format: "md";
+    description?: string;
+};
+export type ModuleInstructionEntry = {
+    /**
+     * Function-like instruction name, e.g. "document-project".
+     */
+    name: string;
+    /**
+     * Markdown instruction file path under the module instruction directory.
+     */
+    file: string;
+    description?: string;
+};
+export type ModuleInstructionContract = {
+    /**
+     * Directory containing markdown instruction files for this module.
+     */
+    directory: string;
+    entries: ModuleInstructionEntry[];
+};
+export type ModuleEvent = {
+    type: string;
+    payload?: Record<string, unknown>;
+};
+export type ModuleCommand = {
+    name: string;
+    args?: Record<string, unknown>;
+};
+export type ModuleCommandResult = {
+    ok: boolean;
+    code: string;
+    message?: string;
+    data?: Record<string, unknown>;
+};
+export type ModuleLifecycleContext = {
+    runtimeVersion: string;
+    workspacePath: string;
+};
+export type ModuleRegistration = {
+    id: string;
+    version: string;
+    contractVersion: "1";
+    capabilities: ModuleCapability[];
+    dependsOn: 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/contracts/module-contract.js

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

package/dist/core/index.d.ts

@@ -0,0 +1,3 @@
+export { ModuleRegistry, ModuleRegistryError, validateModuleSet, type ModuleRegistryOptions } from "./module-registry.js";
+export { ModuleCommandRouter, ModuleCommandRouterError, type ModuleCommandDescriptor, type ModuleCommandRouterOptions } from "./module-command-router.js";
+export type CoreRuntimeVersion = "0.1";

package/dist/core/index.js

@@ -0,0 +1,2 @@
+export { ModuleRegistry, ModuleRegistryError, validateModuleSet } from "./module-registry.js";
+export { ModuleCommandRouter, ModuleCommandRouterError } from "./module-command-router.js";

package/dist/core/module-command-router.d.ts

@@ -0,0 +1,27 @@
+import type { ModuleCommandResult, ModuleLifecycleContext } from "../contracts/module-contract.js";
+import { ModuleRegistry } from "./module-registry.js";
+export type ModuleCommandDescriptor = {
+    name: string;
+    moduleId: string;
+    instructionFile: string;
+    description?: string;
+};
+export type ModuleCommandRouterOptions = {
+    aliases?: Record<string, string>;
+};
+export declare class ModuleCommandRouterError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare class ModuleCommandRouter {
+    private readonly commands;
+    private readonly aliases;
+    private readonly registry;
+    constructor(registry: ModuleRegistry, options?: ModuleCommandRouterOptions);
+    listCommands(): ModuleCommandDescriptor[];
+    describeCommand(name: string): ModuleCommandDescriptor | undefined;
+    execute(name: string, args: Record<string, unknown> | undefined, ctx: ModuleLifecycleContext): Promise<ModuleCommandResult>;
+    private indexEnabledModuleCommands;
+    private validateAliases;
+    private resolveCommandName;
+}

package/dist/core/module-command-router.js

@@ -0,0 +1,84 @@
+export class ModuleCommandRouterError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "ModuleCommandRouterError";
+        this.code = code;
+    }
+}
+export class ModuleCommandRouter {
+    commands = new Map();
+    aliases;
+    registry;
+    constructor(registry, options) {
+        this.registry = registry;
+        this.aliases = options?.aliases ?? {};
+        this.indexEnabledModuleCommands();
+        this.validateAliases();
+    }
+    listCommands() {
+        return [...this.commands.values()]
+            .map((entry) => entry.descriptor)
+            .sort((a, b) => a.name.localeCompare(b.name));
+    }
+    describeCommand(name) {
+        const commandName = this.resolveCommandName(name);
+        return this.commands.get(commandName)?.descriptor;
+    }
+    async execute(name, args, ctx) {
+        const commandName = this.resolveCommandName(name);
+        const indexed = this.commands.get(commandName);
+        if (!indexed) {
+            const known = this.listCommands()
+                .map((command) => command.name)
+                .join(", ");
+            throw new ModuleCommandRouterError("unknown-command", `Unknown command '${name}'. Known commands: ${known || "none"}`);
+        }
+        if (!this.registry.isModuleEnabled(indexed.descriptor.moduleId)) {
+            throw new ModuleCommandRouterError("disabled-module", `Module '${indexed.descriptor.moduleId}' is disabled for command '${commandName}'`);
+        }
+        if (!indexed.module.onCommand) {
+            throw new ModuleCommandRouterError("command-not-implemented", `Module '${indexed.descriptor.moduleId}' does not implement onCommand for '${commandName}'`);
+        }
+        const command = {
+            name: commandName,
+            args
+        };
+        return indexed.module.onCommand(command, ctx);
+    }
+    indexEnabledModuleCommands() {
+        for (const module of this.registry.getEnabledModules()) {
+            for (const entry of module.registration.instructions.entries) {
+                if (this.commands.has(entry.name)) {
+                    const existing = this.commands.get(entry.name);
+                    throw new ModuleCommandRouterError("duplicate-command", `Command '${entry.name}' is declared by both '${existing?.descriptor.moduleId}' and '${module.registration.id}'`);
+                }
+                this.commands.set(entry.name, {
+                    descriptor: {
+                        name: entry.name,
+                        moduleId: module.registration.id,
+                        instructionFile: `${module.registration.instructions.directory}/${entry.file}`,
+                        description: entry.description
+                    },
+                    module
+                });
+            }
+        }
+    }
+    validateAliases() {
+        for (const [alias, commandName] of Object.entries(this.aliases)) {
+            if (alias === commandName) {
+                throw new ModuleCommandRouterError("invalid-alias", `Alias '${alias}' cannot map to itself`);
+            }
+            if (!this.commands.has(commandName)) {
+                throw new ModuleCommandRouterError("unknown-alias-target", `Alias '${alias}' maps to unknown command '${commandName}'`);
+            }
+            if (this.commands.has(alias)) {
+                throw new ModuleCommandRouterError("alias-conflict", `Alias '${alias}' conflicts with a declared command`);
+            }
+        }
+    }
+    resolveCommandName(name) {
+        return this.aliases[name] ?? name;
+    }
+}

package/dist/core/module-registry.d.ts

@@ -0,0 +1,24 @@
+import type { WorkflowModule } from "../contracts/module-contract.js";
+export declare class ModuleRegistryError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function validateModuleSet(modules: WorkflowModule[]): void;
+export type ModuleRegistryOptions = {
+    enabledModules?: string[];
+    disabledModules?: string[];
+    workspacePath?: string;
+};
+export declare class ModuleRegistry {
+    private readonly modules;
+    private readonly enabledModules;
+    private readonly sortedModules;
+    private readonly moduleMap;
+    private readonly enabledModuleMap;
+    constructor(modules: WorkflowModule[], options?: ModuleRegistryOptions);
+    getAllModules(): WorkflowModule[];
+    getModuleById(id: string): WorkflowModule | undefined;
+    isModuleEnabled(id: string): boolean;
+    getEnabledModules(): WorkflowModule[];
+    getStartupOrder(): WorkflowModule[];
+}

package/dist/core/module-registry.js

@@ -0,0 +1,183 @@
+import { existsSync, statSync } from "node:fs";
+import { resolve, sep } from "node:path";
+export class ModuleRegistryError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "ModuleRegistryError";
+        this.code = code;
+    }
+}
+function buildModuleMap(modules) {
+    const moduleMap = new Map();
+    for (const module of modules) {
+        const id = module.registration.id;
+        if (moduleMap.has(id)) {
+            throw new ModuleRegistryError("duplicate-module-id", `Duplicate module id: '${id}'`);
+        }
+        moduleMap.set(id, module);
+    }
+    return moduleMap;
+}
+function validateDependencies(moduleMap) {
+    for (const module of moduleMap.values()) {
+        const moduleId = module.registration.id;
+        for (const dependency of module.registration.dependsOn) {
+            if (dependency === moduleId) {
+                throw new ModuleRegistryError("self-dependency", `Module '${moduleId}' cannot depend on itself`);
+            }
+            if (!moduleMap.has(dependency)) {
+                throw new ModuleRegistryError("missing-dependency", `Module '${moduleId}' depends on missing module '${dependency}'`);
+            }
+        }
+    }
+}
+function topologicalSort(moduleMap) {
+    const visited = new Set();
+    const inStack = new Set();
+    const sorted = [];
+    const visit = (id) => {
+        if (visited.has(id)) {
+            return;
+        }
+        if (inStack.has(id)) {
+            throw new ModuleRegistryError("dependency-cycle", `Dependency cycle detected at module '${id}'`);
+        }
+        inStack.add(id);
+        const module = moduleMap.get(id);
+        if (!module) {
+            throw new ModuleRegistryError("missing-module", `Module '${id}' not found`);
+        }
+        for (const dependencyId of module.registration.dependsOn) {
+            visit(dependencyId);
+        }
+        inStack.delete(id);
+        visited.add(id);
+        sorted.push(module);
+    };
+    for (const moduleId of moduleMap.keys()) {
+        visit(moduleId);
+    }
+    return sorted;
+}
+function resolveEnabledModuleIds(modules, options) {
+    const explicitEnabled = options?.enabledModules;
+    const explicitDisabled = new Set(options?.disabledModules ?? []);
+    const enabledIds = new Set();
+    for (const module of modules) {
+        if (module.registration.enabledByDefault) {
+            enabledIds.add(module.registration.id);
+        }
+    }
+    if (explicitEnabled && explicitEnabled.length > 0) {
+        enabledIds.clear();
+        for (const moduleId of explicitEnabled) {
+            enabledIds.add(moduleId);
+        }
+    }
+    for (const moduleId of explicitDisabled) {
+        enabledIds.delete(moduleId);
+    }
+    return enabledIds;
+}
+function buildEnabledModuleMap(moduleMap, enabledModuleIds) {
+    const enabledModuleMap = new Map();
+    for (const moduleId of enabledModuleIds) {
+        const module = moduleMap.get(moduleId);
+        if (!module) {
+            throw new ModuleRegistryError("unknown-enabled-module", `Enabled module '${moduleId}' not found`);
+        }
+        enabledModuleMap.set(moduleId, module);
+    }
+    return enabledModuleMap;
+}
+function validateEnabledDependencies(enabledModuleMap) {
+    for (const module of enabledModuleMap.values()) {
+        for (const dependencyId of module.registration.dependsOn) {
+            if (!enabledModuleMap.has(dependencyId)) {
+                throw new ModuleRegistryError("disabled-required-dependency", `Enabled module '${module.registration.id}' requires disabled module '${dependencyId}'`);
+            }
+        }
+    }
+}
+function isInstructionNameValid(name) {
+    return /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name);
+}
+function validateInstructionContracts(moduleMap, workspacePath) {
+    for (const module of moduleMap.values()) {
+        const { id, instructions } = module.registration;
+        const instructionDirectory = resolve(workspacePath, instructions.directory);
+        const seenNames = new Set();
+        const seenFiles = new Set();
+        for (const entry of instructions.entries) {
+            if (!isInstructionNameValid(entry.name)) {
+                throw new ModuleRegistryError("invalid-instruction-name", `Module '${id}' has invalid instruction name '${entry.name}'`);
+            }
+            if (seenNames.has(entry.name)) {
+                throw new ModuleRegistryError("duplicate-instruction-name", `Module '${id}' has duplicate instruction name '${entry.name}'`);
+            }
+            seenNames.add(entry.name);
+            if (!entry.file.endsWith(".md")) {
+                throw new ModuleRegistryError("invalid-instruction-file", `Module '${id}' instruction file '${entry.file}' must end with .md`);
+            }
+            const expectedFileName = `${entry.name}.md`;
+            if (entry.file !== expectedFileName) {
+                throw new ModuleRegistryError("instruction-name-file-mismatch", `Module '${id}' instruction '${entry.name}' must map to '${expectedFileName}'`);
+            }
+            if (seenFiles.has(entry.file)) {
+                throw new ModuleRegistryError("duplicate-instruction-file", `Module '${id}' has duplicate instruction file '${entry.file}'`);
+            }
+            seenFiles.add(entry.file);
+            const instructionFilePath = resolve(instructionDirectory, entry.file);
+            if (instructionFilePath !== instructionDirectory &&
+                !instructionFilePath.startsWith(`${instructionDirectory}${sep}`)) {
+                throw new ModuleRegistryError("instruction-path-escape", `Module '${id}' instruction '${entry.name}' resolves outside instruction directory`);
+            }
+            if (!existsSync(instructionFilePath)) {
+                throw new ModuleRegistryError("missing-instruction-file", `Module '${id}' instruction file '${instructionFilePath}' does not exist`);
+            }
+            if (!statSync(instructionFilePath).isFile()) {
+                throw new ModuleRegistryError("invalid-instruction-file", `Module '${id}' instruction path '${instructionFilePath}' is not a file`);
+            }
+        }
+    }
+}
+export function validateModuleSet(modules) {
+    const moduleMap = buildModuleMap(modules);
+    validateDependencies(moduleMap);
+    validateInstructionContracts(moduleMap, process.cwd());
+    topologicalSort(moduleMap);
+}
+export class ModuleRegistry {
+    modules;
+    enabledModules;
+    sortedModules;
+    moduleMap;
+    enabledModuleMap;
+    constructor(modules, options) {
+        this.moduleMap = buildModuleMap(modules);
+        validateDependencies(this.moduleMap);
+        validateInstructionContracts(this.moduleMap, options?.workspacePath ?? process.cwd());
+        this.modules = [...modules];
+        const enabledModuleIds = resolveEnabledModuleIds(this.modules, options);
+        this.enabledModuleMap = buildEnabledModuleMap(this.moduleMap, enabledModuleIds);
+        validateEnabledDependencies(this.enabledModuleMap);
+        this.sortedModules = topologicalSort(this.enabledModuleMap);
+        this.enabledModules = [...this.sortedModules];
+    }
+    getAllModules() {
+        return [...this.modules];
+    }
+    getModuleById(id) {
+        return this.moduleMap.get(id);
+    }
+    isModuleEnabled(id) {
+        return this.enabledModuleMap.has(id);
+    }
+    getEnabledModules() {
+        return [...this.enabledModules];
+    }
+    getStartupOrder() {
+        return [...this.sortedModules];
+    }
+}

package/dist/index.d.ts

@@ -1 +1,4 @@
 export { defaultWorkspaceKitPaths, parseJsonFile, runCli, type WorkspaceKitCliOptions } from "./cli.js";
+export * from "./core/index.js";
+export * from "./contracts/index.js";
+export * from "./modules/index.js";

package/dist/index.js

@@ -1 +1,4 @@
 export { defaultWorkspaceKitPaths, parseJsonFile, runCli } from "./cli.js";
+export * from "./core/index.js";
+export * from "./contracts/index.js";
+export * from "./modules/index.js";

package/dist/modules/approvals/index.d.ts

@@ -0,0 +1,2 @@
+import type { WorkflowModule } from "../../contracts/module-contract.js";
+export declare const approvalsModule: WorkflowModule;

package/dist/modules/approvals/index.js

@@ -0,0 +1,30 @@
+export const approvalsModule = {
+    registration: {
+        id: "approvals",
+        version: "0.1.0",
+        contractVersion: "1",
+        capabilities: ["approvals"],
+        dependsOn: ["task-engine"],
+        enabledByDefault: true,
+        config: {
+            path: "src/modules/approvals/config.md",
+            format: "md",
+            description: "Approvals module policy and queue configuration contract."
+        },
+        state: {
+            path: "src/modules/approvals/state.md",
+            format: "md",
+            description: "Approvals module decision and queue state contract."
+        },
+        instructions: {
+            directory: "src/modules/approvals/instructions",
+            entries: [
+                {
+                    name: "review-item",
+                    file: "review-item.md",
+                    description: "Review and record an approval decision."
+                }
+            ]
+        }
+    }
+};

package/dist/modules/documentation/index.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowModule } from "../../contracts/module-contract.js";
+export type { DocumentationConflict, DocumentationGenerateOptions, DocumentationGenerateResult, DocumentationGenerationEvidence, DocumentationValidationIssue } from "./types.js";
+export declare const documentationModule: WorkflowModule;

package/dist/modules/documentation/index.js

@@ -0,0 +1,73 @@
+import { generateDocument } from "./runtime.js";
+export const documentationModule = {
+    registration: {
+        id: "documentation",
+        version: "0.1.0",
+        contractVersion: "1",
+        capabilities: ["documentation"],
+        dependsOn: [],
+        enabledByDefault: true,
+        config: {
+            path: "src/modules/documentation/config.md",
+            format: "md",
+            description: "Documentation module configuration contract."
+        },
+        state: {
+            path: "src/modules/documentation/state.md",
+            format: "md",
+            description: "Documentation module generation/runtime state contract."
+        },
+        instructions: {
+            directory: "src/modules/documentation/instructions",
+            entries: [
+                {
+                    name: "document-project",
+                    file: "document-project.md",
+                    description: "Generate aligned project docs for .ai and docs surfaces."
+                }
+            ]
+        }
+    },
+    async onCommand(command, ctx) {
+        if (command.name !== "document-project" && command.name !== "generate-document") {
+            return {
+                ok: false,
+                code: "unsupported-command",
+                message: `Documentation module does not support command '${command.name}'`
+            };
+        }
+        const args = command.args ?? {};
+        const rawOptions = typeof args.options === "object" && args.options !== null
+            ? args.options
+            : undefined;
+        const options = rawOptions
+            ? {
+                dryRun: typeof rawOptions.dryRun === "boolean" ? rawOptions.dryRun : undefined,
+                overwrite: typeof rawOptions.overwrite === "boolean" ? rawOptions.overwrite : undefined,
+                strict: typeof rawOptions.strict === "boolean" ? rawOptions.strict : undefined,
+                maxValidationAttempts: typeof rawOptions.maxValidationAttempts === "number"
+                    ? rawOptions.maxValidationAttempts
+                    : undefined,
+                allowWithoutTemplate: typeof rawOptions.allowWithoutTemplate === "boolean"
+                    ? rawOptions.allowWithoutTemplate
+                    : undefined
+            }
+            : undefined;
+        const result = await generateDocument({
+            documentType: typeof args.documentType === "string" ? args.documentType : undefined,
+            options
+        }, ctx);
+        return {
+            ok: result.ok,
+            code: result.ok ? "generated-document" : "generation-failed",
+            message: result.ok
+                ? `Generated document '${args.documentType ?? "unknown"}'`
+                : `Failed to generate document '${args.documentType ?? "unknown"}'`,
+            data: {
+                aiOutputPath: result.aiOutputPath,
+                humanOutputPath: result.humanOutputPath,
+                evidence: result.evidence
+            }
+        };
+    }
+};

package/dist/modules/documentation/runtime.d.ts

@@ -0,0 +1,8 @@
+import type { DocumentationGenerateOptions, DocumentationGenerateResult } from "./types.js";
+import type { ModuleLifecycleContext } from "../../contracts/module-contract.js";
+type GenerateDocumentArgs = {
+    documentType?: string;
+    options?: DocumentationGenerateOptions;
+};
+export declare function generateDocument(args: GenerateDocumentArgs, ctx: ModuleLifecycleContext): Promise<DocumentationGenerateResult>;
+export {};

package/dist/modules/documentation/runtime.js

@@ -0,0 +1,285 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { resolve, sep } from "node:path";
+function isPathWithinRoot(path, root) {
+    return path === root || path.startsWith(`${root}${sep}`);
+}
+function parseDefaultValue(fileContent, key, fallback) {
+    const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const regex = new RegExp(`\\\`${escaped}\\\`[^\\n]*default:\\s*\\\`([^\\\`]+)\\\``);
+    const match = fileContent.match(regex);
+    return match?.[1] ?? fallback;
+}
+async function loadRuntimeConfig(workspacePath) {
+    const configPath = resolve(workspacePath, "src/modules/documentation/config.md");
+    const configContent = await readFile(configPath, "utf8");
+    const aiRoot = parseDefaultValue(configContent, "sources.aiRoot", "/.ai");
+    const humanRoot = parseDefaultValue(configContent, "sources.humanRoot", "docs/maintainers");
+    const templatesRoot = parseDefaultValue(configContent, "sources.templatesRoot", "src/modules/documentation/templates");
+    const instructionsRoot = parseDefaultValue(configContent, "sources.instructionsRoot", "src/modules/documentation/instructions");
+    const schemasRoot = parseDefaultValue(configContent, "sources.schemasRoot", "src/modules/documentation/schemas");
+    const maxValidationAttemptsRaw = parseDefaultValue(configContent, "generation.maxValidationAttempts", "3");
+    const maxValidationAttempts = Number.parseInt(maxValidationAttemptsRaw, 10);
+    return {
+        aiRoot,
+        humanRoot,
+        templatesRoot,
+        instructionsRoot,
+        schemasRoot,
+        maxValidationAttempts: Number.isFinite(maxValidationAttempts) ? maxValidationAttempts : 3
+    };
+}
+function validateAiSchema(aiOutput) {
+    const issues = [];
+    const lines = aiOutput.split("\n").filter((line) => line.trim().length > 0);
+    if (!lines[0]?.startsWith("meta|v=")) {
+        issues.push({
+            check: "schema",
+            message: "AI output must start with a meta record",
+            resolved: false
+        });
+    }
+    return issues;
+}
+function autoResolveAiSchema(aiOutput) {
+    if (aiOutput.startsWith("meta|v=")) {
+        return aiOutput;
+    }
+    return `meta|v=1|doc=rules|truth=canonical|st=draft\n\n${aiOutput}`;
+}
+function renderTemplate(templateContent) {
+    const output = templateContent.replace(/\{\{\{([\s\S]*?)\}\}\}/g, (_match, instructionText) => {
+        const normalized = instructionText.trim().split("\n")[0] ?? "template instructions";
+        return `Generated content based on instruction: ${normalized}`;
+    });
+    return {
+        output,
+        unresolvedBlocks: output.includes("{{{")
+    };
+}
+function validateSectionCoverage(templateContent, output) {
+    const issues = [];
+    const sectionRegex = /^##\s+(.+)$/gm;
+    const expectedSections = [...templateContent.matchAll(sectionRegex)].map((match) => match[1]);
+    for (const section of expectedSections) {
+        if (!output.includes(`## ${section}`)) {
+            issues.push({
+                check: "section-coverage",
+                message: `Missing required section: ${section}`,
+                resolved: false
+            });
+        }
+    }
+    return issues;
+}
+function detectConflicts(aiOutput, humanOutput) {
+    const conflicts = [];
+    const combined = `${aiOutput}\n${humanOutput}`;
+    if (combined.includes("CONFLICT:")) {
+        conflicts.push({
+            source: "generated-output",
+            reason: "Generated output flagged a conflict marker",
+            severity: "stop"
+        });
+    }
+    return conflicts;
+}
+export async function generateDocument(args, ctx) {
+    const documentType = args.documentType;
+    if (!documentType) {
+        return {
+            ok: false,
+            evidence: {
+                documentType: "unknown",
+                filesRead: [],
+                filesWritten: [],
+                validationIssues: [
+                    {
+                        check: "template-resolution",
+                        message: "Missing required argument 'documentType'",
+                        resolved: false
+                    }
+                ],
+                conflicts: [],
+                attemptsUsed: 0,
+                timestamp: new Date().toISOString()
+            }
+        };
+    }
+    const options = args.options ?? {};
+    const config = await loadRuntimeConfig(ctx.workspacePath);
+    const filesRead = [];
+    const filesWritten = [];
+    const validationIssues = [];
+    const conflicts = [];
+    const aiRoot = resolve(ctx.workspacePath, config.aiRoot.replace(/^\//, ""));
+    const humanRoot = resolve(ctx.workspacePath, config.humanRoot.replace(/^\//, ""));
+    const templatePath = resolve(ctx.workspacePath, config.templatesRoot, documentType);
+    const aiOutputPath = resolve(aiRoot, documentType);
+    const humanOutputPath = resolve(humanRoot, documentType);
+    if (!isPathWithinRoot(aiOutputPath, aiRoot) || !isPathWithinRoot(humanOutputPath, humanRoot)) {
+        return {
+            ok: false,
+            evidence: {
+                documentType,
+                filesRead,
+                filesWritten,
+                validationIssues: [
+                    {
+                        check: "write-boundary",
+                        message: "Resolved output path escapes configured output roots",
+                        resolved: false
+                    }
+                ],
+                conflicts,
+                attemptsUsed: 0,
+                timestamp: new Date().toISOString()
+            }
+        };
+    }
+    let templateContent = "";
+    let templateFound = existsSync(templatePath);
+    if (templateFound) {
+        templateContent = await readFile(templatePath, "utf8");
+        filesRead.push(templatePath);
+    }
+    else {
+        validationIssues.push({
+            check: "template-resolution",
+            message: `Template not found for '${documentType}'`,
+            resolved: Boolean(options.allowWithoutTemplate)
+        });
+        if (!options.allowWithoutTemplate) {
+            return {
+                ok: false,
+                evidence: {
+                    documentType,
+                    filesRead,
+                    filesWritten,
+                    validationIssues,
+                    conflicts,
+                    attemptsUsed: 0,
+                    timestamp: new Date().toISOString()
+                }
+            };
+        }
+    }
+    const schemaPath = resolve(ctx.workspacePath, config.schemasRoot, "documentation-schema.md");
+    if (existsSync(schemaPath)) {
+        filesRead.push(schemaPath);
+        await readFile(schemaPath, "utf8");
+    }
+    let aiOutput = `meta|v=1|doc=rules|truth=canonical|st=draft\nproject|name=workflow-cannon|type=generated_doc|scope=${documentType}`;
+    let attemptsUsed = 0;
+    const maxAttempts = options.maxValidationAttempts ?? config.maxValidationAttempts;
+    while (attemptsUsed < maxAttempts) {
+        attemptsUsed += 1;
+        const schemaIssues = validateAiSchema(aiOutput);
+        if (schemaIssues.length === 0) {
+            break;
+        }
+        validationIssues.push(...schemaIssues);
+        aiOutput = autoResolveAiSchema(aiOutput);
+    }
+    const aiFinalIssues = validateAiSchema(aiOutput);
+    if (aiFinalIssues.length > 0) {
+        validationIssues.push(...aiFinalIssues);
+        return {
+            ok: false,
+            evidence: {
+                documentType,
+                filesRead,
+                filesWritten,
+                validationIssues,
+                conflicts,
+                attemptsUsed,
+                timestamp: new Date().toISOString()
+            }
+        };
+    }
+    let humanOutput = `# ${documentType}\n\nGenerated without template.`;
+    if (templateFound) {
+        const rendered = renderTemplate(templateContent);
+        humanOutput = rendered.output;
+        if (rendered.unresolvedBlocks) {
+            validationIssues.push({
+                check: "section-coverage",
+                message: "Template output still contains unresolved {{{ }}} blocks",
+                resolved: false
+            });
+        }
+        validationIssues.push(...validateSectionCoverage(templateContent, humanOutput));
+    }
+    conflicts.push(...detectConflicts(aiOutput, humanOutput));
+    if (conflicts.some((conflict) => conflict.severity === "stop")) {
+        return {
+            ok: false,
+            evidence: {
+                documentType,
+                filesRead,
+                filesWritten,
+                validationIssues,
+                conflicts,
+                attemptsUsed,
+                timestamp: new Date().toISOString()
+            }
+        };
+    }
+    const hasUnresolvedValidation = validationIssues.some((issue) => !issue.resolved);
+    if (options.strict !== false && hasUnresolvedValidation) {
+        return {
+            ok: false,
+            evidence: {
+                documentType,
+                filesRead,
+                filesWritten,
+                validationIssues,
+                conflicts,
+                attemptsUsed,
+                timestamp: new Date().toISOString()
+            }
+        };
+    }
+    if (!options.dryRun) {
+        if (!options.overwrite && (existsSync(aiOutputPath) || existsSync(humanOutputPath))) {
+            return {
+                ok: false,
+                evidence: {
+                    documentType,
+                    filesRead,
+                    filesWritten,
+                    validationIssues: [
+                        ...validationIssues,
+                        {
+                            check: "write-boundary",
+                            message: "Output exists and overwrite=false",
+                            resolved: false
+                        }
+                    ],
+                    conflicts,
+                    attemptsUsed,
+                    timestamp: new Date().toISOString()
+                }
+            };
+        }
+        await mkdir(aiRoot, { recursive: true });
+        await mkdir(humanRoot, { recursive: true });
+        await writeFile(aiOutputPath, `${aiOutput}\n`, "utf8");
+        await writeFile(humanOutputPath, `${humanOutput}\n`, "utf8");
+        filesWritten.push(aiOutputPath, humanOutputPath);
+    }
+    return {
+        ok: true,
+        aiOutputPath,
+        humanOutputPath,
+        evidence: {
+            documentType,
+            filesRead,
+            filesWritten,
+            validationIssues,
+            conflicts,
+            attemptsUsed,
+            timestamp: new Date().toISOString()
+        }
+    };
+}

package/dist/modules/documentation/types.d.ts

@@ -0,0 +1,32 @@
+export type DocumentationGenerateOptions = {
+    dryRun?: boolean;
+    overwrite?: boolean;
+    strict?: boolean;
+    maxValidationAttempts?: number;
+    allowWithoutTemplate?: boolean;
+};
+export type DocumentationConflict = {
+    source: string;
+    reason: string;
+    severity: "warn" | "stop";
+};
+export type DocumentationValidationIssue = {
+    check: "schema" | "section-coverage" | "template-resolution" | "write-boundary" | "conflict";
+    message: string;
+    resolved: boolean;
+};
+export type DocumentationGenerationEvidence = {
+    documentType: string;
+    filesRead: string[];
+    filesWritten: string[];
+    validationIssues: DocumentationValidationIssue[];
+    conflicts: DocumentationConflict[];
+    attemptsUsed: number;
+    timestamp: string;
+};
+export type DocumentationGenerateResult = {
+    ok: boolean;
+    aiOutputPath?: string;
+    humanOutputPath?: string;
+    evidence: DocumentationGenerationEvidence;
+};

package/dist/modules/documentation/types.js

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

package/dist/modules/improvement/index.d.ts

@@ -0,0 +1,2 @@
+import type { WorkflowModule } from "../../contracts/module-contract.js";
+export declare const improvementModule: WorkflowModule;

package/dist/modules/improvement/index.js

@@ -0,0 +1,30 @@
+export const improvementModule = {
+    registration: {
+        id: "improvement",
+        version: "0.1.0",
+        contractVersion: "1",
+        capabilities: ["improvement"],
+        dependsOn: ["task-engine", "planning"],
+        enabledByDefault: true,
+        config: {
+            path: "src/modules/improvement/config.md",
+            format: "md",
+            description: "Improvement module configuration contract."
+        },
+        state: {
+            path: "src/modules/improvement/state.md",
+            format: "md",
+            description: "Improvement module recommendation state contract."
+        },
+        instructions: {
+            directory: "src/modules/improvement/instructions",
+            entries: [
+                {
+                    name: "generate-recommendations",
+                    file: "generate-recommendations.md",
+                    description: "Produce evidence-backed workflow recommendations."
+                }
+            ]
+        }
+    }
+};

package/dist/modules/index.d.ts

@@ -0,0 +1,6 @@
+export { approvalsModule } from "./approvals/index.js";
+export { documentationModule } from "./documentation/index.js";
+export type { DocumentationConflict, DocumentationGenerateOptions, DocumentationGenerateResult, DocumentationGenerationEvidence, DocumentationValidationIssue } from "./documentation/types.js";
+export { improvementModule } from "./improvement/index.js";
+export { planningModule } from "./planning/index.js";
+export { taskEngineModule } from "./task-engine/index.js";

package/dist/modules/index.js

@@ -0,0 +1,5 @@
+export { approvalsModule } from "./approvals/index.js";
+export { documentationModule } from "./documentation/index.js";
+export { improvementModule } from "./improvement/index.js";
+export { planningModule } from "./planning/index.js";
+export { taskEngineModule } from "./task-engine/index.js";

package/dist/modules/planning/index.d.ts

@@ -0,0 +1,2 @@
+import type { WorkflowModule } from "../../contracts/module-contract.js";
+export declare const planningModule: WorkflowModule;

package/dist/modules/planning/index.js

@@ -0,0 +1,30 @@
+export const planningModule = {
+    registration: {
+        id: "planning",
+        version: "0.1.0",
+        contractVersion: "1",
+        capabilities: ["planning"],
+        dependsOn: ["task-engine"],
+        enabledByDefault: true,
+        config: {
+            path: "src/modules/planning/config.md",
+            format: "md",
+            description: "Planning module configuration contract."
+        },
+        state: {
+            path: "src/modules/planning/state.md",
+            format: "md",
+            description: "Planning module runtime state contract."
+        },
+        instructions: {
+            directory: "src/modules/planning/instructions",
+            entries: [
+                {
+                    name: "build-plan",
+                    file: "build-plan.md",
+                    description: "Generate a dependency-aware execution plan."
+                }
+            ]
+        }
+    }
+};

package/dist/modules/task-engine/index.d.ts

@@ -0,0 +1,2 @@
+import type { WorkflowModule } from "../../contracts/module-contract.js";
+export declare const taskEngineModule: WorkflowModule;

package/dist/modules/task-engine/index.js

@@ -0,0 +1,30 @@
+export const taskEngineModule = {
+    registration: {
+        id: "task-engine",
+        version: "0.1.0",
+        contractVersion: "1",
+        capabilities: ["task-engine"],
+        dependsOn: [],
+        enabledByDefault: true,
+        config: {
+            path: "src/modules/task-engine/config.md",
+            format: "md",
+            description: "Task Engine configuration contract."
+        },
+        state: {
+            path: "src/modules/task-engine/state.md",
+            format: "md",
+            description: "Task Engine runtime state contract."
+        },
+        instructions: {
+            directory: "src/modules/task-engine/instructions",
+            entries: [
+                {
+                    name: "run-transition",
+                    file: "run-transition.md",
+                    description: "Run a validated task status transition."
+                }
+            ]
+        }
+    }
+};

package/dist/ops/index.d.ts

@@ -0,0 +1 @@
+export type OpsVersion = "0.1";

package/dist/ops/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workflow-cannon/workspace-kit",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
   "packageManager": "pnpm@10.0.0",
   "license": "MIT",
@@ -22,7 +22,9 @@
     "check": "tsc -p tsconfig.json --noEmit",
     "clean": "rm -rf dist",
     "test": "pnpm run build && node --test test/**/*.test.mjs",
-    "pack:dry-run": "pnpm run build && pnpm pack --pack-destination ./artifacts/workspace-kit-pack"
+    "pack:dry-run": "pnpm run build && pnpm pack --pack-destination ./artifacts/workspace-kit-pack",
+    "check-release-metadata": "node scripts/check-release-metadata.mjs",
+    "parity": "node scripts/run-parity.mjs"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",