@workflow-cannon/workspace-kit 0.8.0 → 0.10.0

package/dist/core/transcript-completion-hook.js

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, statSync, unlinkSync, writeFileSync } from "node
 import path from "node:path";
 import { spawn } from "node:child_process";
 const LOCK_REL = ".workspace-kit/improvement/transcript-hook.lock";
+const EVENT_LOG_REL = ".workspace-kit/improvement/transcript-hook-events.jsonl";
 const LOCK_STALE_MS = 120_000;
 export function readAfterTaskCompletedHook(effective) {
     const imp = effective.improvement;
@@ -39,31 +40,62 @@ function hookLockBusy(workspacePath) {
         return false;
     }
 }
+function appendHookEvent(workspacePath, event, details) {
+    const fp = path.join(workspacePath, EVENT_LOG_REL);
+    try {
+        mkdirSync(path.dirname(fp), { recursive: true });
+        writeFileSync(fp, `${JSON.stringify({
+            schemaVersion: 1,
+            timestamp: new Date().toISOString(),
+            event,
+            ...details
+        })}\n`, { encoding: "utf8", flag: "a" });
+    }
+    catch {
+        // Observability must never block task transitions.
+    }
+}
 /**
  * After a task reaches `completed`, optionally spawn sync/ingest without blocking the transition (T274).
  * Ingest requires WORKSPACE_KIT_POLICY_APPROVAL in the parent env or falls back to sync.
  */
 export function maybeSpawnTranscriptHookAfterCompletion(workspacePath, effective) {
     const mode = readAfterTaskCompletedHook(effective);
-    if (mode === "off")
+    if (mode === "off") {
+        appendHookEvent(workspacePath, "skipped", { reason: "hook-mode-off" });
         return;
-    if (hookLockBusy(workspacePath))
+    }
+    if (hookLockBusy(workspacePath)) {
+        appendHookEvent(workspacePath, "skipped", { reason: "lock-busy", mode });
         return;
+    }
     let subcommand = "sync-transcripts";
     if (mode === "ingest" && process.env.WORKSPACE_KIT_POLICY_APPROVAL?.trim()) {
         subcommand = "ingest-transcripts";
     }
     const cli = resolveWorkspaceKitCli(workspacePath);
-    if (!cli)
+    if (!cli) {
+        appendHookEvent(workspacePath, "failed", {
+            reason: "cli-not-found",
+            mode,
+            subcommand
+        });
         return;
+    }
     const fp = lockPath(workspacePath);
     try {
         mkdirSync(path.dirname(fp), { recursive: true });
         writeFileSync(fp, `${JSON.stringify({ at: new Date().toISOString(), subcommand })}\n`, "utf8");
     }
     catch {
+        appendHookEvent(workspacePath, "failed", {
+            reason: "lock-write-failed",
+            mode,
+            subcommand
+        });
         return;
     }
+    appendHookEvent(workspacePath, "started", { mode, subcommand });
     const child = spawn(process.execPath, [cli, "run", subcommand, "{}"], {
         cwd: workspacePath,
         detached: true,
@@ -78,6 +110,7 @@ export function maybeSpawnTranscriptHookAfterCompletion(workspacePath, effective
         catch {
             /* ignore */
         }
+        appendHookEvent(workspacePath, "completed", { mode, subcommand });
     });
     child.on("error", () => {
         try {
@@ -86,5 +119,10 @@ export function maybeSpawnTranscriptHookAfterCompletion(workspacePath, effective
         catch {
             /* ignore */
         }
+        appendHookEvent(workspacePath, "failed", {
+            reason: "spawn-error",
+            mode,
+            subcommand
+        });
     });
 }

package/dist/core/workspace-kit-config.d.ts

@@ -12,7 +12,8 @@ export declare function getProjectConfigPath(workspacePath: string): string;
 export declare const KIT_CONFIG_DEFAULTS: Record<string, unknown>;
 /**
  * Static module-level defaults keyed by module id (merged in registry startup order).
- * Each value is deep-merged into the aggregate before project/env/invocation.
+ * Keep true defaults in KIT_CONFIG_DEFAULTS as the canonical source; use this map
+ * only when a module contributes additional non-default config structure.
  */
 export declare const MODULE_CONFIG_CONTRIBUTIONS: Record<string, Record<string, unknown>>;
 export declare function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown>;

package/dist/core/workspace-kit-config.js

@@ -21,7 +21,7 @@ export const KIT_CONFIG_DEFAULTS = {
     },
     improvement: {
         transcripts: {
-            sourcePath: ".cursor/agent-transcripts",
+            sourcePath: "",
             archivePath: "agent-transcripts",
             maxFilesPerSync: 5000,
             maxBytesPerFile: 50_000_000,
@@ -40,37 +40,12 @@ export const KIT_CONFIG_DEFAULTS = {
 };
 /**
  * Static module-level defaults keyed by module id (merged in registry startup order).
- * Each value is deep-merged into the aggregate before project/env/invocation.
+ * Keep true defaults in KIT_CONFIG_DEFAULTS as the canonical source; use this map
+ * only when a module contributes additional non-default config structure.
  */
 export const MODULE_CONFIG_CONTRIBUTIONS = {
-    "task-engine": {
-        tasks: {
-            storeRelativePath: ".workspace-kit/tasks/state.json"
-        }
-    },
-    documentation: {
-        documentation: {}
-    },
     approvals: {},
-    planning: {},
-    improvement: {
-        transcripts: {
-            sourcePath: ".cursor/agent-transcripts",
-            archivePath: "agent-transcripts",
-            maxFilesPerSync: 5000,
-            maxBytesPerFile: 50_000_000,
-            maxTotalScanBytes: 500_000_000,
-            discoveryPaths: []
-        },
-        cadence: {
-            minIntervalMinutes: 15,
-            skipIfNoNewTranscripts: true,
-            maxRecommendationCandidatesPerRun: 500
-        },
-        hooks: {
-            afterTaskCompleted: "off"
-        }
-    }
+    planning: {}
 };
 export function deepMerge(target, source) {
     const out = { ...target };

package/dist/modules/approvals/index.js

@@ -1,4 +1,4 @@
-import { resolveActor } from "../../core/policy.js";
+import { resolveActorWithFallback } from "../../core/policy.js";
 import { runReviewItem } from "./review-runtime.js";
 export const approvalsModule = {
     registration: {
@@ -40,7 +40,7 @@ export const approvalsModule = {
         const args = command.args ?? {};
         const actor = typeof args.actor === "string" && args.actor.trim().length > 0
             ? args.actor.trim()
-            : ctx.resolvedActor ?? resolveActor(ctx.workspacePath, args, process.env);
+            : ctx.resolvedActor ?? (await resolveActorWithFallback(ctx.workspacePath, args, process.env));
         const taskId = typeof args.taskId === "string" ? args.taskId : "";
         const decision = args.decision;
         if (decision !== "accept" && decision !== "decline" && decision !== "accept_edited") {

package/dist/modules/documentation/runtime.js

@@ -2,6 +2,7 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { dirname, resolve, sep } from "node:path";
 import { readdir } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
 function isPathWithinRoot(path, root) {
     return path === root || path.startsWith(`${root}${sep}`);
 }
@@ -12,8 +13,30 @@ function parseDefaultValue(fileContent, key, fallback) {
     return match?.[1] ?? fallback;
 }
 async function loadRuntimeConfig(workspacePath) {
-    const configPath = resolve(workspacePath, "src/modules/documentation/config.md");
-    const configContent = await readFile(configPath, "utf8");
+    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");
@@ -27,7 +50,8 @@ async function loadRuntimeConfig(workspacePath) {
         templatesRoot,
         instructionsRoot,
         schemasRoot,
-        maxValidationAttempts: Number.isFinite(maxValidationAttempts) ? maxValidationAttempts : 3
+        maxValidationAttempts: Number.isFinite(maxValidationAttempts) ? maxValidationAttempts : 3,
+        sourceRoot
     };
 }
 function parseAiRecordLine(line) {
@@ -441,7 +465,7 @@ export async function generateDocument(args, ctx) {
     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 templatePath = resolve(config.sourceRoot, config.templatesRoot, documentType);
     const aiOutputPath = resolve(aiRoot, documentType);
     const humanOutputPath = resolve(humanRoot, documentType);
     if (!isPathWithinRoot(aiOutputPath, aiRoot) || !isPathWithinRoot(humanOutputPath, humanRoot)) {
@@ -493,7 +517,7 @@ export async function generateDocument(args, ctx) {
             };
         }
     }
-    const schemaPath = resolve(ctx.workspacePath, config.schemasRoot, "documentation-schema.md");
+    const schemaPath = resolve(config.sourceRoot, config.schemasRoot, "documentation-schema.md");
     if (existsSync(schemaPath)) {
         filesRead.push(schemaPath);
         await readFile(schemaPath, "utf8");
@@ -663,7 +687,7 @@ export async function generateDocument(args, ctx) {
 }
 export async function generateAllDocuments(args, ctx) {
     const config = await loadRuntimeConfig(ctx.workspacePath);
-    const templatesDir = resolve(ctx.workspacePath, config.templatesRoot);
+    const templatesDir = resolve(config.sourceRoot, config.templatesRoot);
     async function listTemplateFiles(dir, baseDir) {
         const entries = await readdir(dir, { withFileTypes: true });
         const files = [];

package/dist/modules/improvement/index.js

@@ -58,13 +58,25 @@ export const improvementModule = {
             const transcriptsRoot = typeof args.transcriptsRoot === "string" ? args.transcriptsRoot : undefined;
             const fromTag = typeof args.fromTag === "string" ? args.fromTag : undefined;
             const toTag = typeof args.toTag === "string" ? args.toTag : undefined;
+            const syncArgs = {
+                sourcePath: typeof args.sourcePath === "string" ? args.sourcePath : undefined,
+                archivePath: transcriptsRoot
+            };
             try {
-                const result = await runGenerateRecommendations(ctx, { transcriptsRoot, fromTag, toTag });
+                const state = await loadImprovementState(ctx.workspacePath);
+                const sync = await runSyncTranscripts(ctx, syncArgs, state);
+                state.lastSyncRunAt = new Date().toISOString();
+                await saveImprovementState(ctx.workspacePath, state);
+                const result = await runGenerateRecommendations(ctx, {
+                    transcriptsRoot: sync.archivePath,
+                    fromTag,
+                    toTag
+                });
                 return {
                     ok: true,
                     code: "recommendations-generated",
-                    message: `Created ${result.created.length} improvement task(s); skipped ${result.skipped} duplicate(s)`,
-                    data: result
+                    message: `After sync (${sync.copied} copied): created ${result.created.length} improvement task(s); skipped ${result.skipped} duplicate(s)`,
+                    data: { sync, ...result }
                 };
             }
             catch (e) {

package/dist/modules/improvement/transcript-sync-runtime.d.ts

@@ -47,6 +47,11 @@ type ImprovementTranscriptConfig = {
     discoveryPaths: string[];
 };
 export declare function resolveImprovementTranscriptConfig(ctx: ModuleLifecycleContext, args: TranscriptSyncArgs): ImprovementTranscriptConfig;
+/**
+ * Cursor stores agent transcripts under `~/.cursor/projects/<slug>/agent-transcripts`, where `slug`
+ * is the workspace root with path separators replaced by hyphens (drive letter included on Windows).
+ */
+export declare function buildCursorProjectsAgentTranscriptsPath(workspacePath: string): string;
 export declare function resolveTranscriptSourceRoot(workspacePath: string, cfg: ImprovementTranscriptConfig, args: TranscriptSyncArgs): Promise<{
     root: string;
     discoveredFrom: string;

package/dist/modules/improvement/transcript-sync-runtime.js

@@ -1,4 +1,5 @@
 import fs from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 import { createHash, randomUUID } from "node:crypto";
 const DEFAULT_DISCOVERY_PATHS = [".cursor/agent-transcripts", ".vscode/agent-transcripts"];
@@ -58,6 +59,16 @@ async function pathExists(abs) {
         return false;
     }
 }
+/**
+ * Cursor stores agent transcripts under `~/.cursor/projects/<slug>/agent-transcripts`, where `slug`
+ * is the workspace root with path separators replaced by hyphens (drive letter included on Windows).
+ */
+export function buildCursorProjectsAgentTranscriptsPath(workspacePath) {
+    const home = os.homedir();
+    const resolved = path.resolve(workspacePath);
+    const slug = resolved.split(path.sep).filter((s) => s.length > 0).join("-");
+    return path.join(home, ".cursor", "projects", slug, "agent-transcripts");
+}
 export async function resolveTranscriptSourceRoot(workspacePath, cfg, args) {
     const sourcePathArg = typeof args.sourcePath === "string" ? args.sourcePath.trim() : "";
     if (sourcePathArg) {
@@ -76,6 +87,12 @@ export async function resolveTranscriptSourceRoot(workspacePath, cfg, args) {
             return { root: abs, discoveredFrom: rel, tried };
         }
     }
+    const cursorGlobal = buildCursorProjectsAgentTranscriptsPath(workspacePath);
+    const cursorLabel = path.join("~", ".cursor", "projects", path.basename(path.dirname(cursorGlobal)), "agent-transcripts");
+    tried.push(cursorLabel);
+    if (await pathExists(cursorGlobal)) {
+        return { root: cursorGlobal, discoveredFrom: "cursor-global-project-agent-transcripts", tried };
+    }
     const fallback = path.resolve(workspacePath, ".cursor/agent-transcripts");
     return { root: fallback, discoveredFrom: ".cursor/agent-transcripts (fallback)", tried };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workflow-cannon/workspace-kit",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "private": false,
   "packageManager": "pnpm@10.0.0",
   "license": "MIT",
@@ -42,6 +42,7 @@
   },
   "files": [
     "dist",
+    "src/modules/documentation",
     "package.json"
   ]
 }

package/src/modules/documentation/README.md

@@ -0,0 +1,39 @@
+# Documentation Module
+
+Translates between canonical AI-optimized documentation and human-readable maintainership docs.
+
+Primary responsibilities:
+
+- maintain parity between `/.ai` and configured human docs roots (default: `docs/maintainers`)
+- execute instruction-file driven documentation generation
+- record deterministic documentation generation state and evidence
+
+See `src/modules/documentation/RULES.md` for the canonical usage order and validation rules.
+
+## Callable commands
+
+Registered on the documentation module and dispatched through `src/core/module-command-router.ts`:
+
+- `document-project` — batch: generate **all** project docs from the template library. Outputs AI docs to `.ai/` (preserving existing) and human docs to `docs/maintainers/` (overwriting). Continues through failures; reports batch summary. See `instructions/document-project.md`.
+- `generate-document` — single: generate **one** document by `documentType`. See `instructions/generate-document.md`.
+
+## Shipped templates
+
+Files under `templates/`; `documentType` is the filename (basename). Keep this list aligned with `instructions/document-project.md` **Inputs**:
+
+- `AGENTS.md`
+- `ARCHITECTURE.md`
+- `PRINCIPLES.md`
+- `RELEASING.md`
+- `ROADMAP.md`
+- `SECURITY.md`
+- `SUPPORT.md`
+- `TERMS.md`
+- `runbooks/parity-validation-flow.md`
+- `runbooks/consumer-cadence.md`
+- `runbooks/release-channels.md`
+- `workbooks/transcript-automation-baseline.md`
+- `workbooks/phase2-config-policy-workbook.md`
+- `workbooks/task-engine-workbook.md`
+
+Adding a new template: add `templates/<Name>.md`, extend the **Inputs** list in `instructions/document-project.md`, and add the same line here.

package/src/modules/documentation/RULES.md

@@ -0,0 +1,70 @@
+# Documentation Module Rules
+
+Single entrypoint for how to use the documentation module.
+
+## Precedence Order
+
+When guidance conflicts, apply this order:
+
+1. `/.ai/PRINCIPLES.md` (global governance and approval gates)
+2. `/.ai/module-build.md` (module development and validation rules)
+3. `src/modules/documentation/config.md` (module path policy and generation behavior)
+4. `src/modules/documentation/instructions/document-project.md` (document generation workflow)
+5. `src/modules/documentation/instructions/documentation-maintainer.md` (AI-doc generation policy)
+6. `src/modules/documentation/schemas/documentation-schema.md` (record schema contract)
+7. `src/modules/documentation/templates/*.md` (document-type generation templates)
+8. `docs/maintainers/module-build-guide.md` (human-readable companion guidance)
+
+## Usage Model
+
+- Choose an instruction entry from `instructions/` for the operation you want.
+- Discover available callable module operations through `src/core/module-command-router.ts` command listing.
+- Load module config first and restrict writes to configured document paths.
+- If a matching template exists, use it as the structure contract.
+- For templates with `{{{ ... }}}` blocks, treat block content as generation instructions, not output text.
+- Generate AI-surface content first, then generate human-surface content from that result plus project context.
+
+## Command Contracts
+
+### `document-project(options)` — batch
+
+Generates all project docs by iterating every `.md` template in `sources.templatesRoot`.
+
+- Default behavior: **preserve AI docs** (`overwriteAi: false`), **overwrite human docs** (`overwriteHuman: true`), continue on individual failure.
+- Returns batch summary with total/succeeded/failed/skipped counts plus per-document results.
+
+### `generate-document(documentType, options)` — single
+
+Generates one document pair (AI + human) for the given `documentType`.
+
+- `documentType`: required string basename resolving to `<templatesRoot>/<documentType>`.
+- `options`:
+  - `dryRun?: boolean` (default `false`) - compute outputs/validations without writing files
+  - `overwrite?: boolean` (default `true`) - allow replacing existing files (both surfaces)
+  - `overwriteAi?: boolean` - override `overwrite` for AI surface only
+  - `overwriteHuman?: boolean` - override `overwrite` for human surface only
+  - `strict?: boolean` (default `true`) - fail on unresolved warnings (validation/conflict/coverage)
+  - `maxValidationAttempts?: number` (default from config) - override retry limit
+  - `allowWithoutTemplate?: boolean` (default `false`) - continue without template only when explicitly confirmed
+- Shipped template basenames are listed in `instructions/generate-document.md` and `instructions/document-project.md`.
+
+### Shared semantics
+
+- Both commands read paths from module config (`sources.aiRoot`, `sources.humanRoot`, `sources.templatesRoot`, `sources.instructionsRoot`, `sources.schemasRoot`).
+- Both enforce write boundaries to configured output roots only.
+- Both execute AI generation first, then human generation from AI output plus project context.
+- Both return evidence objects containing files read/written, validations, retries, warnings/conflicts, and timestamp.
+
+## Required Validation
+
+- Validate AI output against `schemas/documentation-schema.md`.
+- Verify section coverage for templated documents and ensure no unresolved `{{{` blocks remain.
+- Detect conflicts against higher-precedence sources and stop/prompt when required.
+- Emit run evidence (inputs, outputs, validation results, timestamp).
+
+## Missing Template Behavior
+
+- If a template for the requested document type is missing:
+  - warn the user
+  - ask whether to continue without a template
+  - continue only with explicit confirmation

package/src/modules/documentation/config.md

@@ -0,0 +1,14 @@
+# Documentation Module Config
+
+Defines module-level configuration keys used by the documentation module.
+
+- `sources.aiRoot`: canonical AI docs root (default: `/.ai`)
+- `sources.humanRoot`: human docs root (default: `docs/maintainers`)
+- `sources.templatesRoot`: document template root (default: `src/modules/documentation/templates`)
+- `sources.instructionsRoot`: instruction root (default: `src/modules/documentation/instructions`)
+- `sources.schemasRoot`: schema root (default: `src/modules/documentation/schemas`)
+- `generation.enforceParity`: fail generation when AI and human surfaces diverge
+- `generation.enforceSectionCoverage`: fail when expected template sections are missing in output
+- `generation.resolveOrRetryOnValidationError`: auto-resolve issues or retry generation before returning failure
+- `generation.maxValidationAttempts`: maximum validate/retry attempts (default: `3`)
+- `generation.allowTemplatelessFallback`: when template is missing, require user confirmation before continuing

package/src/modules/documentation/index.ts

@@ -0,0 +1,120 @@
+import type { WorkflowModule } from "../../contracts/module-contract.js";
+import { generateDocument, generateAllDocuments } from "./runtime.js";
+export type {
+  DocumentationBatchResult,
+  DocumentationConflict,
+  DocumentationGenerateOptions,
+  DocumentationGenerateResult,
+  DocumentationGenerationEvidence,
+  DocumentationValidationIssue
+} from "./types.js";
+import type { DocumentationGenerateOptions } from "./types.js";
+
+function parseOptions(raw: Record<string, unknown>): DocumentationGenerateOptions {
+  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: WorkflowModule = {
+  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: Record<string, unknown> =
+      typeof args.options === "object" && args.options !== null
+        ? (args.options as Record<string, unknown>)
+        : {};
+    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/src/modules/documentation/instructions/document-project.md

@@ -0,0 +1,44 @@
+# document-project
+
+Generate all project documentation by running `generate-document` for every template in the template library. Outputs AI-optimized docs to `.ai/` and human-readable docs to `docs/maintainers/`.
+
+## Inputs
+
+- `options` (all optional):
+  - `dryRun?: boolean` — compute outputs/validations without writing files
+  - `overwriteAi?: boolean` — overwrite existing AI docs (default `false`)
+  - `overwriteHuman?: boolean` — overwrite existing human docs (default `true`)
+  - `strict?: boolean` — fail on unresolved warnings (default `false` in batch mode)
+  - `maxValidationAttempts?: number` — override retry limit per document
+
+## Shipped templates
+
+All `.md` files under `sources.templatesRoot` (default `src/modules/documentation/templates`) are processed:
+
+- `AGENTS.md`
+- `ARCHITECTURE.md`
+- `PRINCIPLES.md`
+- `RELEASING.md`
+- `ROADMAP.md`
+- `SECURITY.md`
+- `SUPPORT.md`
+- `TERMS.md`
+- `runbooks/parity-validation-flow.md`
+- `runbooks/consumer-cadence.md`
+- `runbooks/release-channels.md`
+- `workbooks/transcript-automation-baseline.md`
+- `workbooks/phase2-config-policy-workbook.md`
+- `workbooks/task-engine-workbook.md`
+
+## Required behavior
+
+1. Discover all `.md` templates in `sources.templatesRoot`.
+2. For each template, invoke `generate-document` with the template basename as `documentType`.
+3. Default overwrite behavior: **preserve AI docs** (`overwriteAi: false`), **overwrite human docs** (`overwriteHuman: true`).
+4. Continue through all templates on individual failure; do not stop the batch.
+5. Collect per-document results and emit a batch summary with total/succeeded/failed/skipped counts.
+6. Return `ok: true` only when zero documents failed.
+
+## Skipped AI doc handling
+
+When AI docs are skipped because they already exist (`filesSkipped` is non-empty in a document result), the calling agent **must** prompt the user before overwriting. Present the list of skipped AI doc paths and ask for explicit confirmation. If confirmed, re-run with `overwriteAi: true` for those documents.