@workflow-cannon/workspace-kit 0.7.0 → 0.9.0

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

@@ -1,16 +1,11 @@
-import path from "node:path";
-import fs from "node:fs/promises";
+import { maybeSpawnTranscriptHookAfterCompletion } from "../../core/transcript-completion-hook.js";
 import { TaskStore } from "./store.js";
 import { TransitionService } from "./service.js";
 import { TaskEngineError } from "./transitions.js";
-import { generateTasksMd, syncTaskHeadingsInMarkdown } from "./generator.js";
-import { importTasksFromMarkdown } from "./importer.js";
 import { getNextActions } from "./suggestions.js";
 export { TaskStore } from "./store.js";
 export { TransitionService } from "./service.js";
 export { TaskEngineError, TransitionValidator, isTransitionAllowed, getTransitionAction, resolveTargetState, getAllowedTransitionsFrom, stateValidityGuard, dependencyCheckGuard } from "./transitions.js";
-export { generateTasksMd, syncTaskHeadingsInMarkdown } from "./generator.js";
-export { importTasksFromMarkdown } from "./importer.js";
 export { getNextActions } from "./suggestions.js";
 function taskStorePath(ctx) {
     const tasks = ctx.effectiveConfig?.tasks;
@@ -61,16 +56,6 @@ export const taskEngineModule = {
                     file: "get-ready-queue.md",
                     description: "Get ready tasks sorted by priority."
                 },
-                {
-                    name: "import-tasks",
-                    file: "import-tasks.md",
-                    description: "One-time import from TASKS.md into engine state."
-                },
-                {
-                    name: "generate-tasks-md",
-                    file: "generate-tasks-md.md",
-                    description: "Generate read-only TASKS.md from engine state."
-                },
                 {
                     name: "get-next-actions",
                     file: "get-next-actions.md",
@@ -113,6 +98,9 @@ export const taskEngineModule = {
             try {
                 const service = new TransitionService(store);
                 const result = await service.runTransition({ taskId, action, actor });
+                if (result.evidence.toState === "completed") {
+                    maybeSpawnTranscriptHookAfterCompletion(ctx.workspacePath, (ctx.effectiveConfig ?? {}));
+                }
                 return {
                     ok: true,
                     code: "transition-applied",
@@ -190,68 +178,6 @@ export const taskEngineModule = {
                 data: { tasks: ready, count: ready.length }
             };
         }
-        if (command.name === "import-tasks") {
-            const sourcePath = typeof args.sourcePath === "string"
-                ? path.resolve(ctx.workspacePath, args.sourcePath)
-                : path.resolve(ctx.workspacePath, "docs/maintainers/TASKS.md");
-            try {
-                const result = await importTasksFromMarkdown(sourcePath);
-                store.replaceAllTasks(result.tasks);
-                await store.save();
-                return {
-                    ok: true,
-                    code: "tasks-imported",
-                    message: `Imported ${result.imported} tasks (${result.skipped} skipped)`,
-                    data: {
-                        imported: result.imported,
-                        skipped: result.skipped,
-                        errors: result.errors
-                    }
-                };
-            }
-            catch (err) {
-                if (err instanceof TaskEngineError) {
-                    return { ok: false, code: err.code, message: err.message };
-                }
-                return {
-                    ok: false,
-                    code: "import-parse-error",
-                    message: err.message
-                };
-            }
-        }
-        if (command.name === "generate-tasks-md") {
-            const outputPath = typeof args.outputPath === "string"
-                ? path.resolve(ctx.workspacePath, args.outputPath)
-                : path.resolve(ctx.workspacePath, "docs/maintainers/TASKS.md");
-            const tasks = store.getAllTasks();
-            const fallbackMarkdown = generateTasksMd(tasks);
-            let markdown = fallbackMarkdown;
-            const preserveStructure = args.preserveStructure !== false;
-            try {
-                if (preserveStructure) {
-                    const existing = await fs.readFile(outputPath, "utf8").catch(() => undefined);
-                    if (typeof existing === "string" && existing.length > 0) {
-                        markdown = syncTaskHeadingsInMarkdown(existing, tasks);
-                    }
-                }
-                await fs.mkdir(path.dirname(outputPath), { recursive: true });
-                await fs.writeFile(outputPath, markdown, "utf8");
-            }
-            catch (err) {
-                return {
-                    ok: false,
-                    code: "storage-write-error",
-                    message: `Failed to write TASKS.md: ${err.message}`
-                };
-            }
-            return {
-                ok: true,
-                code: "tasks-md-generated",
-                message: `Generated TASKS.md with ${tasks.length} tasks`,
-                data: { outputPath, taskCount: tasks.length }
-            };
-        }
         if (command.name === "get-next-actions") {
             const tasks = store.getAllTasks();
             const suggestion = getNextActions(tasks);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workflow-cannon/workspace-kit",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "private": false,
   "packageManager": "pnpm@10.0.0",
   "license": "MIT",
@@ -31,7 +31,10 @@
     "generate-runtime-diagnostics": "node scripts/generate-runtime-diagnostics.mjs",
     "prune-evidence": "node scripts/prune-evidence.mjs",
     "phase4-gates": "pnpm run check-compatibility && pnpm run check-planning-consistency && pnpm run check-release-channel",
-    "phase5-gates": "pnpm run phase4-gates && pnpm run test"
+    "phase5-gates": "pnpm run phase4-gates && pnpm run test",
+    "pre-release-transcript-hook": "pnpm run build && node scripts/pre-release-transcript-hook.mjs",
+    "transcript:sync": "node scripts/run-transcript-cli.mjs sync-transcripts",
+    "transcript:ingest": "node scripts/run-transcript-cli.mjs ingest-transcripts"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",
@@ -39,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.