@workflow-cannon/workspace-kit 0.8.0 → 0.9.0

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.9.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.

package/src/modules/documentation/instructions/documentation-maintainer.md

@@ -0,0 +1,81 @@
+meta|v=1|doc=generator|truth=canonical|st=active
+
+goal|produce=canonical_project_docs|opt=max_obedience_per_token|minimize=ambiguity,drift,token_waste
+io|in=repo_files,code_config,existing_docs,core_schema|out=manifest,rules,map,workflows,commands,decisions,glossary,observed,planned,checks
+authority|order=canonical_ai_docs>code_and_config_reality>generated_human_docs>narrative_docs
+
+use|schema=src/modules/documentation/schemas/documentation-schema.md
+create|files=.ai/00-manifest.md,.ai/01-rules.md,.ai/02-map.md,.ai/03-workflows.md,.ai/04-commands.md,.ai/05-decisions.md,.ai/06-glossary.md,.ai/07-observed.md,.ai/08-planned.md,.ai/09-checks.md
+min_set|files=manifest,rules,map,workflows
+
+author|one_record_per_line=true|meta_first_once=true|stable_order=true|omit_empty_optional=true|one_fact_per_record=true|exceptions_inline=true
+author|explicit=level,scope,directive,trigger,done,approval,stop_prompt_behavior
+author|forbid=vague_directives,undefined_shorthand,hidden_exceptions,softened_requirements,duplicate_meaning,manual_reordering_without_reason
+
+classify|rule=intended_policy_for_future_action
+classify|observed=current_reality_or_drift_not_policy
+classify|planned=target_state_not_yet_true
+classify|decision=compact_choice_plus_consequence
+classify|check=validation_assertion
+classify|term=project_specific_term_only
+
+infer|allowed=project_identity,stack,repo_scope,path_roles,module_roles,commands,high_confidence_workflows,observed_facts
+infer|forbid=unstated_policy,hidden_exceptions,preferred_style_without_evidence,intent_from_accidental_code_smells
+infer|policy_from=explicit_docs,repeated_patterns_with_high_confidence,user_stated_preferences,active_decisions
+infer|when_unclear=write_observed_or_draft_not_rule
+
+rule|write=rule|RID|lvl|scope|directive|optional_fields
+rule|good=add_migration,preserve_backward_compatibility,contain_business_logic,commit_secrets,manual_edit,add_or_update_tests
+rule|bad=best_practices,clean_code,good_design,keep_it_simple,do_the_right_thing
+rule|levels=must,must_not,should,may
+rule|scope=concrete_and_stable
+rule|exception=inline_unless
+rule|interaction=ov=auto,warn,prompt,stop_when_needed
+rule|new_id_if=meaning_changes
+rule|keep_id_if=meaning_same_and_fields_refined
+
+map|write=path_and_module_records_only
+map|path_fields=role,has,xhas,deps,xdeps,check,st,refs
+map|module_fields=role,owns,deps,xdeps,entry,tests,st,refs
+map|require=ownership_boundaries_for_major_paths
+map|forbid=generic_roles,misc_buckets
+
+wf|write=wf|WID|name|when|do|done|optional_fields
+wf|require=trigger_and_done_when_tasklike
+wf|use=forbid,ask_if,halt_if,ap,risk_when_relevant
+wf|common_first=true|risky_early=true|clarify_last=true
+wf|stop_if=destructive_unapproved,policy_conflict_unresolved,unsafe_missing_info
+wf|ask_if=multiple_valid_interpretations,required_choice_missing
+
+cmd|write=canonical_commands_only
+cmd|include=install,dev,test,lint,build_when_present
+cmd|forbid=speculative_commands
+
+decision|write=only_active_high_value_choices
+decision|require=topic,choice
+decision|prefer=why,then
+decision|forbid=long_narrative
+
+term|write=only_if_reduces_ambiguity
+term|forbid=common_engineering_terms,indirection_debt
+
+observed|write=for_drift_violations_legacy_patterns_notable_current_facts
+planned|write=for_target_state_not_yet_implemented
+check|write=for_required_validation_gates_and_done_assertions
+
+order|manifest=meta,project,stack,prio,truth,ref
+order|rules=global,risky,scoped,workflow,style
+order|map=roots,major,special,legacy
+order|workflows=common,risky,edge,clarify
+
+validate|struct=allowed_record_types,required_fields,valid_enums,valid_ids,meta_first_once
+validate|semantic=no_duplicate_active_ids,no_conflicting_active_rules_without_exception,no_vague_directives,no_observed_as_rule,no_planned_as_rule,no_unknown_paths_without_reason
+validate|interaction=critical_secret_risk_stop,destructive_unapproved_stop_or_required,ambiguity_prompt_or_observed
+
+stop|if=critical_secret_risk,destructive_change_without_approval,unresolved_policy_conflict,unsafe_missing_info
+prompt|if=multiple_valid_interpretations,required_approval_missing,repo_intent_unclear_but_safe_to_ask
+warn|if=should_violation,low_risk_uncertainty,minor_doc_drift
+auto|if=low_risk_clear_routine_work
+
+output|deterministic=true|preserve_existing_order_when_semantics_same=true|preserve_ids=true
+output|never=soften_must_to_should,drop_unless,merge_distinct_rules_into_fuzzy_prose,invent_rationale

package/src/modules/documentation/instructions/generate-document.md

@@ -0,0 +1,44 @@
+# generate-document
+
+Generate a single document for both canonical AI and human-readable surfaces using module config, schema, and templates.
+
+## Inputs
+
+- `documentType` (required): basename of the doc to generate; must match a file under `sources.templatesRoot` (default `src/modules/documentation/templates`). Known templates:
+  - `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`
+- `options`:
+  - `dryRun?: boolean` — compute outputs/validations without writing files
+  - `overwrite?: boolean` — allow replacing existing files (default `true`)
+  - `overwriteAi?: boolean` — override `overwrite` for AI surface only
+  - `overwriteHuman?: boolean` — override `overwrite` for human surface only
+  - `strict?: boolean` — fail on unresolved warnings (default `true`)
+  - `maxValidationAttempts?: number` — override retry limit
+  - `allowWithoutTemplate?: boolean` — continue without template only when explicitly confirmed
+
+## Required behavior
+
+1. Read `src/modules/documentation/RULES.md` and apply precedence order before generation.
+2. Load module config and resolve output roots from configured paths (`sources.aiRoot`, `sources.humanRoot`).
+3. Restrict writes strictly to configured output roots; reject writes outside those roots.
+4. Resolve template for `documentType` from `sources.templatesRoot`.
+5. If template is missing, warn user and ask whether to continue without a template; continue only on explicit confirmation.
+6. Generate AI output first at `<aiRoot>/<documentType>` using `documentation-maintainer.md` + `documentation-schema.md`.
+7. Validate AI output against schema; on validation failure, auto-resolve/retry up to `generation.maxValidationAttempts` before failing.
+8. Re-read generated AI output with project context, then generate human output at `<humanRoot>/<documentType>`.
+9. For templates containing `{{{ ... }}}`, execute block contents as generation instructions and ensure no unresolved blocks remain in output.
+10. Run section coverage validation (all required sections present, correct headings/order where required); retry/resolve on failure.
+11. Detect conflicts with higher-precedence docs and stop/prompt when policy-sensitive or unresolved.
+12. Emit run evidence: inputs, files read/written, validation results, retries used, conflict outcomes, timestamp.