@workflow-cannon/workspace-kit 0.1.0 → 0.3.0

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 { DocumentationBatchResult, DocumentationConflict, DocumentationGenerateOptions, DocumentationGenerateResult, DocumentationGenerationEvidence, DocumentationValidationIssue } from "./types.js";
+export declare const documentationModule: WorkflowModule;

package/dist/modules/documentation/index.js

@@ -0,0 +1,98 @@
+import { generateDocument, generateAllDocuments } from "./runtime.js";
+function parseOptions(raw) {
+    return {
+        dryRun: typeof raw.dryRun === "boolean" ? raw.dryRun : undefined,
+        overwrite: typeof raw.overwrite === "boolean" ? raw.overwrite : undefined,
+        overwriteAi: typeof raw.overwriteAi === "boolean" ? raw.overwriteAi : undefined,
+        overwriteHuman: typeof raw.overwriteHuman === "boolean" ? raw.overwriteHuman : undefined,
+        strict: typeof raw.strict === "boolean" ? raw.strict : undefined,
+        maxValidationAttempts: typeof raw.maxValidationAttempts === "number" ? raw.maxValidationAttempts : undefined,
+        allowWithoutTemplate: typeof raw.allowWithoutTemplate === "boolean" ? raw.allowWithoutTemplate : undefined,
+    };
+}
+export const documentationModule = {
+    registration: {
+        id: "documentation",
+        version: "0.2.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 all project docs from templates to .ai and docs/maintainers surfaces."
+                },
+                {
+                    name: "generate-document",
+                    file: "generate-document.md",
+                    description: "Generate a single document by type for .ai and docs/maintainers surfaces."
+                }
+            ]
+        }
+    },
+    async onCommand(command, ctx) {
+        const args = command.args ?? {};
+        const rawOptions = typeof args.options === "object" && args.options !== null
+            ? args.options
+            : {};
+        const options = parseOptions(rawOptions);
+        if (command.name === "document-project") {
+            const batchResult = await generateAllDocuments({ options }, ctx);
+            return {
+                ok: batchResult.ok,
+                code: batchResult.ok ? "documented-project" : "documentation-batch-failed",
+                message: batchResult.ok
+                    ? `Generated ${batchResult.summary.succeeded} documents (${batchResult.summary.skipped} skipped)`
+                    : `Batch failed: ${batchResult.summary.failed} of ${batchResult.summary.total} documents failed`,
+                data: {
+                    summary: batchResult.summary,
+                    results: batchResult.results.map((r) => ({
+                        documentType: r.evidence.documentType,
+                        ok: r.ok,
+                        aiOutputPath: r.aiOutputPath,
+                        humanOutputPath: r.humanOutputPath,
+                        filesWritten: r.evidence.filesWritten,
+                        filesSkipped: r.evidence.filesSkipped,
+                    }))
+                }
+            };
+        }
+        if (command.name === "generate-document") {
+            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
+                }
+            };
+        }
+        return {
+            ok: false,
+            code: "unsupported-command",
+            message: `Documentation module does not support command '${command.name}'`
+        };
+    }
+};

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

@@ -0,0 +1,12 @@
+import type { DocumentationBatchResult, 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>;
+type GenerateAllDocumentsArgs = {
+    options?: DocumentationGenerateOptions;
+};
+export declare function generateAllDocuments(args: GenerateAllDocumentsArgs, ctx: ModuleLifecycleContext): Promise<DocumentationBatchResult>;
+export {};

package/dist/modules/documentation/runtime.js

@@ -0,0 +1,368 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { resolve, sep } from "node:path";
+import { readdir } from "node:fs/promises";
+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: [],
+                filesSkipped: [],
+                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 filesSkipped = [];
+    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,
+                filesSkipped,
+                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,
+                    filesSkipped,
+                    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,
+                filesSkipped,
+                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,
+                filesSkipped,
+                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,
+                filesSkipped,
+                validationIssues,
+                conflicts,
+                attemptsUsed,
+                timestamp: new Date().toISOString()
+            }
+        };
+    }
+    if (!options.dryRun) {
+        const canOverwriteAi = options.overwriteAi ?? options.overwrite ?? true;
+        const canOverwriteHuman = options.overwriteHuman ?? options.overwrite ?? true;
+        const aiExists = existsSync(aiOutputPath);
+        const humanExists = existsSync(humanOutputPath);
+        if ((!canOverwriteAi && aiExists) && (!canOverwriteHuman && humanExists)) {
+            return {
+                ok: false,
+                evidence: {
+                    documentType,
+                    filesRead,
+                    filesWritten,
+                    filesSkipped: [aiOutputPath, humanOutputPath],
+                    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 });
+        if (canOverwriteAi || !aiExists) {
+            await writeFile(aiOutputPath, `${aiOutput}\n`, "utf8");
+            filesWritten.push(aiOutputPath);
+        }
+        else {
+            filesSkipped.push(aiOutputPath);
+        }
+        if (canOverwriteHuman || !humanExists) {
+            await writeFile(humanOutputPath, `${humanOutput}\n`, "utf8");
+            filesWritten.push(humanOutputPath);
+        }
+        else {
+            filesSkipped.push(humanOutputPath);
+        }
+    }
+    return {
+        ok: true,
+        aiOutputPath,
+        humanOutputPath,
+        evidence: {
+            documentType,
+            filesRead,
+            filesWritten,
+            filesSkipped,
+            validationIssues,
+            conflicts,
+            attemptsUsed,
+            timestamp: new Date().toISOString()
+        }
+    };
+}
+export async function generateAllDocuments(args, ctx) {
+    const config = await loadRuntimeConfig(ctx.workspacePath);
+    const templatesDir = resolve(ctx.workspacePath, config.templatesRoot);
+    let templateFiles = [];
+    try {
+        const entries = await readdir(templatesDir);
+        templateFiles = entries.filter((f) => f.endsWith(".md")).sort();
+    }
+    catch {
+        return {
+            ok: false,
+            results: [],
+            summary: {
+                total: 0,
+                succeeded: 0,
+                failed: 1,
+                skipped: 0,
+                timestamp: new Date().toISOString()
+            }
+        };
+    }
+    const results = [];
+    let succeeded = 0;
+    let failed = 0;
+    let skipped = 0;
+    const batchOptions = {
+        ...args.options,
+        overwriteAi: args.options?.overwriteAi ?? false,
+        overwriteHuman: args.options?.overwriteHuman ?? true,
+        strict: args.options?.strict ?? false,
+    };
+    for (const templateFile of templateFiles) {
+        const result = await generateDocument({ documentType: templateFile, options: batchOptions }, ctx);
+        results.push(result);
+        if (result.ok) {
+            if (result.evidence.filesWritten.length > 0) {
+                succeeded++;
+            }
+            else {
+                skipped++;
+            }
+        }
+        else {
+            failed++;
+        }
+    }
+    return {
+        ok: failed === 0,
+        results,
+        summary: {
+            total: templateFiles.length,
+            succeeded,
+            failed,
+            skipped,
+            timestamp: new Date().toISOString()
+        }
+    };
+}

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

@@ -0,0 +1,46 @@
+export type DocumentationGenerateOptions = {
+    dryRun?: boolean;
+    overwrite?: boolean;
+    overwriteAi?: boolean;
+    overwriteHuman?: 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[];
+    filesSkipped: string[];
+    validationIssues: DocumentationValidationIssue[];
+    conflicts: DocumentationConflict[];
+    attemptsUsed: number;
+    timestamp: string;
+};
+export type DocumentationGenerateResult = {
+    ok: boolean;
+    aiOutputPath?: string;
+    humanOutputPath?: string;
+    evidence: DocumentationGenerationEvidence;
+};
+export type DocumentationBatchResult = {
+    ok: boolean;
+    results: DocumentationGenerateResult[];
+    summary: {
+        total: number;
+        succeeded: number;
+        failed: number;
+        skipped: number;
+        timestamp: string;
+    };
+};

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,7 @@
+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, TaskStore, TransitionService, TaskEngineError, TransitionValidator, isTransitionAllowed, getTransitionAction, resolveTargetState, getAllowedTransitionsFrom, stateValidityGuard, dependencyCheckGuard, generateTasksMd, importTasksFromMarkdown, getNextActions } from "./task-engine/index.js";
+export type { TaskEntity, TaskStatus, TaskPriority, TaskStoreDocument, TransitionEvidence, TransitionGuard, TransitionContext, GuardResult, TaskEngineErrorCode, TaskAdapter, TaskAdapterCapability, NextActionSuggestion, BlockingAnalysisEntry } 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, TaskStore, TransitionService, TaskEngineError, TransitionValidator, isTransitionAllowed, getTransitionAction, resolveTargetState, getAllowedTransitionsFrom, stateValidityGuard, dependencyCheckGuard, generateTasksMd, importTasksFromMarkdown, getNextActions } 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/generator.d.ts

@@ -0,0 +1,2 @@
+import type { TaskEntity } from "./types.js";
+export declare function generateTasksMd(tasks: TaskEntity[]): string;