@workflow-cannon/workspace-kit 0.18.0 → 0.24.0

package/dist/modules/documentation/index.js

@@ -13,21 +13,18 @@ function parseOptions(raw) {
 export const documentationModule = {
     registration: {
         id: "documentation",
-        version: "0.2.0",
+        version: "0.3.0",
         contractVersion: "1",
+        stateSchema: 1,
         capabilities: ["documentation"],
         dependsOn: [],
+        optionalPeers: [],
         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: [
@@ -50,45 +47,50 @@ export const documentationModule = {
             ? 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
-                }
-            };
-        }
+        const handlers = {
+            "document-project": async () => {
+                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
+                        }))
+                    }
+                };
+            },
+            "generate-document": async () => {
+                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
+                    }
+                };
+            }
+        };
+        const handler = handlers[command.name];
+        if (handler)
+            return handler();
         return {
             ok: false,
             code: "unsupported-command",

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

@@ -0,0 +1,3 @@
+import type { AiRecord } from "./parser.js";
+import type { NormalizedDocument } from "./types.js";
+export declare function normalizeDocument(records: AiRecord[]): NormalizedDocument;

package/dist/modules/documentation/normalizer.js

@@ -0,0 +1,171 @@
+function asStatus(v) {
+    if (v === "active" || v === "deprecated" || v === "draft" || v === "observed" || v === "planned")
+        return v;
+    return undefined;
+}
+function asList(v) {
+    if (!v)
+        return [];
+    return v
+        .split(",")
+        .map((x) => x.trim())
+        .filter(Boolean);
+}
+export function normalizeDocument(records) {
+    const refs = [];
+    const rules = [];
+    const checks = [];
+    const decisions = [];
+    const examples = [];
+    const terms = [];
+    const commands = [];
+    const workflows = [];
+    const runbooks = [];
+    const workbooks = [];
+    const chains = [];
+    const states = [];
+    const transitions = [];
+    const promotions = [];
+    const rollbacks = [];
+    const artifacts = [];
+    const configs = [];
+    const cadences = [];
+    const guardrails = [];
+    const refsById = new Map();
+    const examplesByParent = new Map();
+    const profileRecords = new Map([
+        ["core", []],
+        ["runbook", []],
+        ["workbook", []]
+    ]);
+    let meta = null;
+    for (const rec of records) {
+        const status = asStatus(rec.kv["status"] ?? rec.kv["st"]);
+        if (rec.type === "meta") {
+            meta = {
+                schema: "base.v2",
+                doc: rec.kv["doc"] ?? "rules",
+                truth: rec.kv["truth"] ?? "canonical",
+                profile: rec.kv["profile"],
+                status,
+                title: rec.kv["title"],
+                owner: rec.kv["owner"],
+                tags: asList(rec.kv["tags"]),
+                refs: asList(rec.kv["refs"])
+            };
+            continue;
+        }
+        if (rec.type === "ref") {
+            const ref = {
+                id: rec.kv["id"] ?? rec.kv["name"] ?? "",
+                type: rec.kv["type"] ?? "doc",
+                target: rec.kv["target"] ?? rec.kv["path"] ?? "",
+                anchor: rec.kv["anchor"],
+                label: rec.kv["label"] ?? rec.kv["name"],
+                note: rec.kv["note"],
+                status
+            };
+            refs.push(ref);
+            if (ref.id)
+                refsById.set(ref.id, ref);
+            continue;
+        }
+        if (rec.type === "rule") {
+            rules.push({
+                id: rec.kv["id"] ?? rec.kv["slot1"] ?? "",
+                level: rec.kv["level"] ?? "should",
+                scope: rec.kv["scope"] ?? "",
+                scope_kind: rec.kv["scope_kind"],
+                kind: rec.kv["kind"],
+                directive: rec.kv["directive"] ?? rec.kv["slot3"] ?? "",
+                why: rec.kv["why"] ?? "",
+                unless: rec.kv["unless"],
+                also: asList(rec.kv["also"]),
+                risk: rec.kv["risk"],
+                approval: rec.kv["approval"],
+                override: rec.kv["override"],
+                status,
+                refs: asList(rec.kv["refs"])
+            });
+            continue;
+        }
+        if (rec.type === "example") {
+            const ex = {
+                id: rec.kv["id"] ?? "",
+                for: rec.kv["for"] ?? "",
+                kind: rec.kv["kind"] ?? "edge",
+                text: rec.kv["text"] ?? "",
+                status,
+                refs: asList(rec.kv["refs"])
+            };
+            examples.push(ex);
+            const list = examplesByParent.get(ex.for) ?? [];
+            list.push(ex);
+            examplesByParent.set(ex.for, list);
+            continue;
+        }
+        if (rec.type === "check")
+            checks.push({ id: rec.kv["id"] ?? "", scope: rec.kv["scope"] ?? "", assertion: rec.kv["assertion"] ?? rec.kv["assert"] ?? "", when: rec.kv["when"], onFail: rec.kv["onFail"], status, refs: asList(rec.kv["refs"]) });
+        if (rec.type === "decision")
+            decisions.push({ id: rec.kv["id"] ?? "", topic: rec.kv["topic"] ?? "", choice: rec.kv["choice"] ?? "", why: rec.kv["why"] ?? "", consequence: rec.kv["consequence"] ?? rec.kv["then"], status, refs: asList(rec.kv["refs"]) });
+        if (rec.type === "term")
+            terms.push({ name: rec.kv["name"] ?? "", definition: rec.kv["definition"] ?? rec.kv["def"] ?? "", status, refs: asList(rec.kv["refs"]) });
+        if (rec.type === "command" || rec.type === "cmd")
+            commands.push({ id: rec.kv["id"] ?? rec.kv["slot1"] ?? "", name: rec.kv["name"] ?? "", use: rec.kv["use"] ?? "", scope: rec.kv["scope"] ?? "", expectation: rec.kv["expectation"] ?? rec.kv["expect"] ?? "", risk: rec.kv["risk"], sensitivity: rec.kv["sensitivity"], status, refs: asList(rec.kv["refs"]) });
+        if (rec.type === "workflow" || rec.type === "wf")
+            workflows.push({ id: rec.kv["id"] ?? rec.kv["slot1"] ?? "", name: rec.kv["name"] ?? "", when: rec.kv["when"] ?? "", steps: asList(rec.kv["steps"] ?? rec.kv["do"]), done: asList(rec.kv["done"]), forbid: asList(rec.kv["forbid"]), askIf: rec.kv["askIf"] ?? rec.kv["ask_if"], haltIf: rec.kv["haltIf"] ?? rec.kv["halt_if"], approval: rec.kv["approval"], risk: rec.kv["risk"], status, refs: asList(rec.kv["refs"]) });
+        if (rec.type === "runbook")
+            runbooks.push({ name: rec.kv["name"] ?? "", scope: rec.kv["scope"] ?? "", owner: rec.kv["owner"] ?? "", status, refs: asList(rec.kv["refs"]) });
+        if (rec.type === "workbook")
+            workbooks.push({ name: rec.kv["name"] ?? "", phase: rec.kv["phase"] ?? "", state: rec.kv["state"] ?? "", status, refs: asList(rec.kv["refs"]) });
+        if (rec.type === "chain")
+            chains.push({ step: rec.kv["step"] ?? "", command: rec.kv["command"] ?? "", expectExit: Number.parseInt(rec.kv["expectExit"] ?? rec.kv["expect_exit"] ?? "0", 10), status, refs: asList(rec.kv["refs"]) });
+        if (rec.type === "state")
+            states.push({ name: rec.kv["name"] ?? "", distTag: rec.kv["distTag"] ?? rec.kv["dist_tag"] ?? "", intent: rec.kv["intent"] ?? "", status, refs: asList(rec.kv["refs"]) });
+        if (rec.type === "transition")
+            transitions.push({ from: rec.kv["from"] ?? "", to: rec.kv["to"] ?? "", requires: asList(rec.kv["requires"]), status, refs: asList(rec.kv["refs"]) });
+        if (rec.type === "promotion")
+            promotions.push({ from: rec.kv["from"] ?? "", to: rec.kv["to"] ?? "", requires: asList(rec.kv["requires"]), status, refs: asList(rec.kv["refs"]) });
+        if (rec.type === "rollback")
+            rollbacks.push({ strategy: rec.kv["strategy"] ?? "", note: rec.kv["note"] ?? "", status, refs: asList(rec.kv["refs"]) });
+        if (rec.type === "artifact")
+            artifacts.push({ path: rec.kv["path"] ?? "", schema: rec.kv["schema"] ?? "", status, refs: asList(rec.kv["refs"]) });
+        if (rec.type === "config")
+            configs.push({ key: rec.kv["key"] ?? "", default: rec.kv["default"] ?? "", status, refs: asList(rec.kv["refs"]) });
+        if (rec.type === "cadence")
+            cadences.push({ rule: rec.kv["rule"] ?? "", status, refs: asList(rec.kv["refs"]) });
+        if (rec.type === "guardrail")
+            guardrails.push({ id: rec.kv["id"] ?? "", level: rec.kv["level"] ?? "should", directive: rec.kv["directive"] ?? "", why: rec.kv["why"] ?? "", status, refs: asList(rec.kv["refs"]) });
+    }
+    const core = [...refs, ...rules, ...checks, ...decisions, ...examples, ...terms, ...commands, ...workflows];
+    const runbook = [...runbooks, ...chains, ...states, ...transitions, ...promotions, ...rollbacks, ...artifacts, ...configs, ...cadences, ...guardrails];
+    const workbook = [...workbooks, ...states, ...transitions, ...artifacts, ...guardrails];
+    profileRecords.set("core", core);
+    profileRecords.set("runbook", runbook);
+    profileRecords.set("workbook", workbook);
+    return {
+        meta,
+        refs,
+        rules,
+        checks,
+        decisions,
+        examples,
+        terms,
+        commands,
+        workflows,
+        runbooks,
+        workbooks,
+        chains,
+        states,
+        transitions,
+        promotions,
+        rollbacks,
+        artifacts,
+        configs,
+        cadences,
+        guardrails,
+        refsById,
+        examplesByParent,
+        profileRecords
+    };
+}

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

@@ -0,0 +1,7 @@
+export type AiRecord = {
+    type: string;
+    kv: Record<string, string>;
+    raw: string;
+};
+export declare function parseAiRecordLine(line: string): AiRecord | null;
+export declare function parseAiDocument(text: string): AiRecord[];

package/dist/modules/documentation/parser.js

@@ -0,0 +1,39 @@
+export function parseAiRecordLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#"))
+        return null;
+    const parts = trimmed.split("|");
+    if (parts.length < 2)
+        return null;
+    const type = parts[0]?.trim() ?? "";
+    if (!type)
+        return null;
+    const kv = {};
+    let slotIndex = 1;
+    for (const token of parts.slice(1)) {
+        const piece = token.trim();
+        if (!piece)
+            continue;
+        const idx = piece.indexOf("=");
+        if (idx >= 0) {
+            const key = piece.slice(0, idx).trim();
+            const value = piece.slice(idx + 1).trim();
+            if (key)
+                kv[key] = value;
+            continue;
+        }
+        // Transitional support: retain unkeyed tokens as synthetic slots.
+        kv[`slot${slotIndex}`] = piece;
+        slotIndex += 1;
+    }
+    return { type, kv, raw: line };
+}
+export function parseAiDocument(text) {
+    const records = [];
+    for (const line of text.split("\n")) {
+        const rec = parseAiRecordLine(line);
+        if (rec)
+            records.push(rec);
+    }
+    return records;
+}

package/dist/modules/documentation/policy-sensitive-commands.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Policy-gated `workspace-kit run` commands owned by the documentation module.
+ * Keep in sync with instruction names in `documentation/index.ts`.
+ */
+export declare const DOCUMENTATION_POLICY_COMMAND_NAMES: readonly [readonly ["document-project", "doc.document-project"], readonly ["generate-document", "doc.generate-document"]];

package/dist/modules/documentation/policy-sensitive-commands.js

@@ -0,0 +1,8 @@
+/**
+ * Policy-gated `workspace-kit run` commands owned by the documentation module.
+ * Keep in sync with instruction names in `documentation/index.ts`.
+ */
+export const DOCUMENTATION_POLICY_COMMAND_NAMES = [
+    ["document-project", "doc.document-project"],
+    ["generate-document", "doc.generate-document"]
+];

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

@@ -0,0 +1,23 @@
+import type { NormalizedCheck, NormalizedCommand, NormalizedDecision, NormalizedDocument, NormalizedRule, NormalizedTerm, NormalizedWorkflow, ViewModelDefinition } from "./types.js";
+export declare function brief_summary(input: string[]): string;
+export declare function ordered_list(input: string[]): string;
+export declare function rule_table(rules: NormalizedRule[]): string;
+export declare function check_table(checks: NormalizedCheck[]): string;
+export declare function command_reference(commands: NormalizedCommand[]): string;
+export declare function decision_section(decisions: NormalizedDecision[]): string;
+export declare function term_list(terms: NormalizedTerm[]): string;
+export declare function workflow_steps(workflows: NormalizedWorkflow[]): string;
+export declare function chain_steps(chains: Array<{
+    step: string;
+    command: string;
+    expectExit: number;
+}>): string;
+export declare function ref_table(refs: Array<{
+    id: string;
+    type: string;
+    target: string;
+}>): string;
+export declare const renderMetaSection: (doc: NormalizedDocument) => string;
+export declare const renderRuleSection: (doc: NormalizedDocument) => string;
+export declare const renderDecisionSection: (doc: NormalizedDocument) => string;
+export declare function renderDocument(doc: NormalizedDocument, view: ViewModelDefinition): string;

package/dist/modules/documentation/renderer.js

@@ -0,0 +1,105 @@
+function stableSort(values) {
+    return [...values].sort((a, b) => a.localeCompare(b));
+}
+export function brief_summary(input) {
+    if (input.length === 0)
+        return "No summary records.";
+    return input.map((line) => `- ${line}`).join("\n");
+}
+export function ordered_list(input) {
+    if (input.length === 0)
+        return "1. No entries";
+    return input.map((line, idx) => `${idx + 1}. ${line}`).join("\n");
+}
+export function rule_table(rules) {
+    if (rules.length === 0)
+        return "_No rules_";
+    const rows = [...rules].sort((a, b) => a.id.localeCompare(b.id));
+    const body = rows
+        .map((r) => `| ${r.id} | ${r.level} | ${r.scope || "-"} | ${r.directive || "-"} | ${r.why || "-"} |`)
+        .join("\n");
+    return `| ID | Level | Scope | Directive | Why |\n|---|---|---|---|---|\n${body}`;
+}
+export function check_table(checks) {
+    if (checks.length === 0)
+        return "_No checks_";
+    const rows = [...checks].sort((a, b) => a.id.localeCompare(b.id));
+    const body = rows
+        .map((c) => `| ${c.id} | ${c.scope || "-"} | ${c.assertion || "-"} | ${c.onFail || "-"} |`)
+        .join("\n");
+    return `| ID | Scope | Assertion | On Fail |\n|---|---|---|---|\n${body}`;
+}
+export function command_reference(commands) {
+    if (commands.length === 0)
+        return "_No commands_";
+    const rows = [...commands].sort((a, b) => a.name.localeCompare(b.name));
+    return rows.map((c) => `- \`${c.name}\`: ${c.expectation || c.use || "No expectation"}`).join("\n");
+}
+export function decision_section(decisions) {
+    if (decisions.length === 0)
+        return "_No decisions_";
+    const rows = [...decisions].sort((a, b) => a.id.localeCompare(b.id));
+    return rows.map((d) => `### ${d.id}: ${d.topic}\n- Choice: ${d.choice}\n- Why: ${d.why}`).join("\n\n");
+}
+export function term_list(terms) {
+    if (terms.length === 0)
+        return "_No terms_";
+    return [...terms]
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((t) => `- **${t.name}**: ${t.definition}`)
+        .join("\n");
+}
+export function workflow_steps(workflows) {
+    if (workflows.length === 0)
+        return "_No workflows_";
+    return workflows
+        .sort((a, b) => a.id.localeCompare(b.id))
+        .map((wf) => `### ${wf.id}: ${wf.name}\n${ordered_list(stableSort(wf.steps))}`)
+        .join("\n\n");
+}
+export function chain_steps(chains) {
+    if (chains.length === 0)
+        return "_No chain steps_";
+    return chains
+        .map((c, idx) => `${idx + 1}. ${c.step} -> \`${c.command}\` (expect ${c.expectExit})`)
+        .join("\n");
+}
+export function ref_table(refs) {
+    if (refs.length === 0)
+        return "_No refs_";
+    const body = [...refs]
+        .sort((a, b) => a.id.localeCompare(b.id))
+        .map((r) => `| ${r.id} | ${r.type} | ${r.target} |`)
+        .join("\n");
+    return `| ID | Type | Target |\n|---|---|---|\n${body}`;
+}
+export const renderMetaSection = (doc) => brief_summary([
+    `doc=${doc.meta?.doc ?? "unknown"}`,
+    `truth=${doc.meta?.truth ?? "unknown"}`,
+    `profile=${doc.meta?.profile ?? "core"}`
+]);
+export const renderRuleSection = (doc) => rule_table(doc.rules);
+export const renderDecisionSection = (doc) => decision_section(doc.decisions);
+function renderSection(doc, section) {
+    const byName = {
+        renderMetaSection,
+        renderRuleSection,
+        renderDecisionSection,
+        brief_summary: (d) => brief_summary(d.examples.map((e) => e.text)),
+        ordered_list: (d) => ordered_list(d.commands.map((c) => c.name)),
+        rule_table: (d) => rule_table(d.rules),
+        check_table: (d) => check_table(d.checks),
+        command_reference: (d) => command_reference(d.commands),
+        decision_section: (d) => decision_section(d.decisions),
+        term_list: (d) => term_list(d.terms),
+        workflow_steps: (d) => workflow_steps(d.workflows),
+        chain_steps: (d) => chain_steps(d.chains),
+        ref_table: (d) => ref_table(d.refs)
+    };
+    const fn = byName[section.renderer] ?? (() => "_No renderer_");
+    const title = section.title ?? section.id;
+    return `## ${title}\n\n${fn(doc)}`;
+}
+export function renderDocument(doc, view) {
+    return view.sections.map((s) => renderSection(doc, s)).join("\n\n").trim() + "\n";
+}

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

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

package/dist/modules/documentation/runtime-batch.js

@@ -0,0 +1,67 @@
+import { existsSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { resolve } from "node:path";
+import { listViewModels, loadViewModel } from "./view-models.js";
+import { loadRuntimeConfig } from "./runtime-config.js";
+export async function runGenerateAllDocuments(args, ctx, generateOne) {
+    const config = await loadRuntimeConfig(ctx.workspacePath);
+    const workspaceViewsRoot = resolve(ctx.workspacePath, "src/modules/documentation/views");
+    const useWorkspaceViews = existsSync(workspaceViewsRoot);
+    const workItems = [];
+    if (useWorkspaceViews) {
+        const viewFiles = await listViewModels(ctx.workspacePath);
+        for (const viewFile of viewFiles) {
+            const view = await loadViewModel(ctx.workspacePath, viewFile);
+            workItems.push({ documentType: view.target });
+        }
+    }
+    else {
+        const templatesDir = resolve(config.sourceRoot, config.templatesRoot);
+        const listTemplateFiles = async (dir, baseDir) => {
+            const entries = await readdir(dir, { withFileTypes: true });
+            const files = [];
+            for (const entry of entries) {
+                const absPath = resolve(dir, entry.name);
+                if (entry.isDirectory())
+                    files.push(...(await listTemplateFiles(absPath, baseDir)));
+                if (entry.isFile() && entry.name.endsWith(".md"))
+                    files.push(absPath.slice(baseDir.length + 1).split("\\").join("/"));
+            }
+            return files;
+        };
+        for (const templateFile of (await listTemplateFiles(templatesDir, templatesDir)).sort()) {
+            workItems.push({ documentType: templateFile });
+        }
+    }
+    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 item of workItems) {
+        const result = await generateOne({ documentType: item.documentType, options: batchOptions }, ctx);
+        results.push(result);
+        if (!result.ok)
+            failed += 1;
+        else if (result.evidence.filesWritten.length > 0)
+            succeeded += 1;
+        else
+            skipped += 1;
+    }
+    return {
+        ok: failed === 0,
+        results,
+        summary: {
+            total: workItems.length,
+            succeeded,
+            failed,
+            skipped,
+            timestamp: new Date().toISOString()
+        }
+    };
+}

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

@@ -0,0 +1,11 @@
+export type DocumentationRuntimeConfig = {
+    aiRoot: string;
+    humanRoot: string;
+    templatesRoot: string;
+    instructionsRoot: string;
+    schemasRoot: string;
+    maxValidationAttempts: number;
+    sourceRoot: string;
+};
+export declare function isPathWithinRoot(path: string, root: string): boolean;
+export declare function loadRuntimeConfig(workspacePath: string): Promise<DocumentationRuntimeConfig>;

package/dist/modules/documentation/runtime-config.js

@@ -0,0 +1,54 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { dirname, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+export 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;
+}
+export async function loadRuntimeConfig(workspacePath) {
+    const runtimeSourceRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+    const sourceRoots = [workspacePath, runtimeSourceRoot];
+    let sourceRoot = workspacePath;
+    let configContent;
+    for (const candidateRoot of sourceRoots) {
+        const candidate = resolve(candidateRoot, "src/modules/documentation/config.md");
+        if (!existsSync(candidate))
+            continue;
+        configContent = await readFile(candidate, "utf8");
+        sourceRoot = candidateRoot;
+        break;
+    }
+    if (!configContent) {
+        return {
+            aiRoot: "/.ai",
+            humanRoot: "docs/maintainers",
+            templatesRoot: "src/modules/documentation/templates",
+            instructionsRoot: "src/modules/documentation/instructions",
+            schemasRoot: "src/modules/documentation/schemas",
+            maxValidationAttempts: 3,
+            sourceRoot
+        };
+    }
+    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,
+        sourceRoot
+    };
+}

package/dist/modules/documentation/runtime-render-support.d.ts

@@ -0,0 +1,8 @@
+import type { DocumentationConflict, DocumentationValidationIssue } from "./types.js";
+export declare function resolveExpectedDocFamily(docType: string): "rules" | "runbook" | "workbook";
+export declare function renderTemplate(templateContent: string): {
+    output: string;
+    unresolvedBlocks: boolean;
+};
+export declare function validateSectionCoverage(templateContent: string, output: string): DocumentationValidationIssue[];
+export declare function detectConflicts(aiOutput: string, humanOutput: string): DocumentationConflict[];