@workflow-cannon/workspace-kit 0.8.0 → 0.10.0

package/src/modules/documentation/templates/TERMS.md

@@ -0,0 +1,61 @@
+{{{AI Documentation Directive}}}
+
+# Workflow Cannon Terms
+
+Project-specific glossary for consistent language across AI-agent guidance, planning, execution, and release workflows.
+
+## How to use this glossary
+
+{{{
+Rules for adopting and extending terms.
+Method:
+1) Read the existing `docs/maintainers/TERMS.md` introduction if present.
+2) Emphasize operational definitions and single primary source per term.
+Output format:
+- 3-5 bullets.
+Validation:
+- Instruct readers to add terms here before broad adoption in other docs.
+}}}
+
+## Definition surfaces
+
+{{{
+List where canonical definitions live vs enforcement surfaces.
+Method:
+1) Reproduce structure from `docs/maintainers/TERMS.md`: glossary, principles, README/ROADMAP/ARCHITECTURE, TASKS, RELEASING, `.cursor/rules`, `tasks/*.md` as applicable.
+2) Verify paths exist before listing.
+Output format:
+- Bullet list; each bullet names a surface and its role with **bold** label.
+Validation:
+- Use consistent path formatting; no broken links.
+}}}
+
+## Terms and definitions
+
+{{{
+Maintain the glossary entries for this project.
+Method:
+1) Read the current `docs/maintainers/TERMS.md` term list and preserve entries unless superseded by `docs/maintainers/DECISIONS.md` or explicit renames.
+2) For each term, keep three sub-bullets aligned under the term:
+   - **Definition**: …
+   - **Defined in**: path(s)
+   - **Enforced in**: path(s) or mechanism
+3) Add new terms when they appear repeatedly in `.workspace-kit/tasks/state.json`, `ROADMAP.md`, or `.cursor/rules` without definitions.
+4) Fix indentation so **Definition** / **Defined in** / **Enforced in** are nested under the term bullet, not orphaned.
+Output format:
+- One top-level bullet per term with nested three-line pattern above.
+Validation:
+- Alphabetize or group by theme consistently with the prior file; do not duplicate term names.
+}}}
+
+## Related docs
+
+{{{
+Cross-link README, principles, roadmap, tasks, releasing.
+Method:
+1) Verify paths exist.
+Output format:
+- Bulleted list.
+Validation:
+- Include at least `README.md`, `.ai/PRINCIPLES.md`, `docs/maintainers/ROADMAP.md`, `.workspace-kit/tasks/state.json`, `docs/maintainers/RELEASING.md` when present.
+}}}

package/src/modules/documentation/templates/runbooks/consumer-cadence.md

@@ -0,0 +1,55 @@
+{{{AI Documentation Directive}}}
+
+# Consumer Update Cadence
+
+Defines update cadence states for `@workflow-cannon/workspace-kit` consumers and transition validation requirements.
+
+## Cadence states
+
+{{{
+Document cadence states and channel intent.
+Method:
+1) Read `docs/maintainers/runbooks/consumer-cadence.md`.
+2) Preserve state names and dist-tags.
+Output format:
+- Markdown table with state, meaning, npm dist-tag, and consumer action.
+Validation:
+- State names and tags must match release-channel policy docs.
+}}}
+
+## State transitions
+
+{{{
+Describe allowed transition paths and recandidate flow.
+Method:
+1) Read maintainer cadence runbook.
+2) Preserve candidate/stable/patch flow semantics.
+Output format:
+- Diagram block or concise bullets.
+Validation:
+- Do not introduce unsupported transition paths.
+}}}
+
+## Required validation per transition
+
+{{{
+Capture required checks for each transition path.
+Method:
+1) Read `docs/maintainers/release-gate-matrix.md` and cadence runbook.
+Output format:
+- Subsections by transition with numbered validation steps.
+Validation:
+- Keep parity and fixture validation requirements explicit.
+}}}
+
+## Related documents
+
+{{{
+List gate/release/task references used for cadence decisions.
+Method:
+1) Use related section from maintainer runbook.
+Output format:
+- Bullets with paths and short purpose.
+Validation:
+- Include only existing files.
+}}}

package/src/modules/documentation/templates/runbooks/parity-validation-flow.md

@@ -0,0 +1,68 @@
+{{{AI Documentation Directive}}}
+
+# Parity Validation Flow
+
+Canonical ordered command chain for validating packaged-artifact parity in `@workflow-cannon/workspace-kit`.
+
+## Purpose
+
+{{{
+State why parity validation exists and when it is required.
+Method:
+1) Read `docs/maintainers/runbooks/parity-validation-flow.md` and `docs/maintainers/RELEASING.md`.
+2) Emphasize packaged-artifact truth and release-gate requirement.
+Output format:
+- One short paragraph.
+Validation:
+- Preserve release-gate intent; do not weaken fail-closed language.
+}}}
+
+## Canonical command chain
+
+{{{
+Produce the ordered parity command sequence and expected outcomes.
+Method:
+1) Read `docs/maintainers/runbooks/parity-validation-flow.md`.
+2) Preserve step ordering and command names exactly.
+Output format:
+- Markdown table: Step | Command | Expected exit | Output artifact | Machine-parseable.
+Validation:
+- Commands must match runnable scripts/paths in repository.
+}}}
+
+## Failure behavior
+
+{{{
+Describe hard-failure handling for any non-zero parity step.
+Method:
+1) Read `scripts/run-parity.mjs` behavior as documented in maintainer runbook.
+Output format:
+- 3-4 bullets.
+Validation:
+- Must indicate stop-on-fail behavior and evidence capture.
+}}}
+
+## Evidence contract
+
+{{{
+Document parity evidence location and key fields.
+Method:
+1) Read `docs/maintainers/runbooks/parity-validation-flow.md`.
+2) Validate schema reference path.
+Output format:
+- Bullets for location, schema, and key fields.
+Validation:
+- Keep artifact path and schema path exact.
+}}}
+
+## Related documents
+
+{{{
+List closely related release and cadence docs.
+Method:
+1) Read links from maintainer parity runbook.
+Output format:
+- Bulleted paths with short purpose notes.
+Validation:
+- Only include files that exist.
+}}}

package/src/modules/documentation/templates/runbooks/release-channels.md

@@ -0,0 +1,30 @@
+{{{AI Documentation Directive}}}
+
+# Release Channels
+
+Operational mapping for `canary`, `stable`, and `lts` channels.
+
+## Channel mapping
+
+{{{
+Produce channel to dist-tag/tag/label/compatibility mapping.
+Method:
+1) Read `docs/maintainers/runbooks/release-channels.md`.
+2) Read `docs/maintainers/data/compatibility-matrix.json`.
+Output format:
+- Markdown table with channel columns used by maintainer doc.
+Validation:
+- Values must match compatibility matrix source.
+}}}
+
+## Promotion and rollback
+
+{{{
+Describe promotion prerequisites and rollback strategy.
+Method:
+1) Read channel runbook and release gate docs.
+Output format:
+- 3 concise bullets.
+Validation:
+- Preserve forward-fix rollback model (no tag mutation).
+}}}

package/src/modules/documentation/templates/workbooks/phase2-config-policy-workbook.md

@@ -0,0 +1,42 @@
+{{{AI Documentation Directive}}}
+
+# Phase 2 workbook — config, policy, local task cutover
+
+Binding design baseline for configuration and policy behavior in `v0.4.0`.
+
+## Scope and non-goals
+
+{{{
+Summarize Phase 2 scope and explicit non-goals.
+Method:
+1) Read `docs/maintainers/workbooks/phase2-config-policy-workbook.md`.
+2) Preserve task coverage and non-goal statements.
+Output format:
+- Short scope line + 3-5 non-goal bullets.
+Validation:
+- Keep references aligned to current task-engine state.
+}}}
+
+## Config precedence and merge semantics
+
+{{{
+Document layered precedence and merge model.
+Method:
+1) Extract precedence stack and merge behavior from maintainer workbook.
+Output format:
+- Numbered precedence list and one merge-semantics note.
+Validation:
+- Order must remain exact and deterministic.
+}}}
+
+## Policy and approvals baseline
+
+{{{
+Capture sensitive operation gating and approval model.
+Method:
+1) Read workbook sections for sensitive operations and approvals.
+Output format:
+- Operation table + approval bullets.
+Validation:
+- Preserve fail-closed policy behavior and actor resolution order.
+}}}

package/src/modules/documentation/templates/workbooks/task-engine-workbook.md

@@ -0,0 +1,42 @@
+{{{AI Documentation Directive}}}
+
+# Task Engine Schema Workbook
+
+Design workbook for Task Engine lifecycle, transitions, persistence, and guard behavior.
+
+## Design decisions
+
+{{{
+Capture resolved design decisions and rationale.
+Method:
+1) Read `docs/maintainers/workbooks/task-engine-workbook.md`.
+2) Preserve canonical choices for lifecycle, persistence, evidence, and command surfaces.
+Output format:
+- Markdown decision table.
+Validation:
+- Keep decisions consistent with current runtime behavior and tests.
+}}}
+
+## State model and transitions
+
+{{{
+Document lifecycle states and transition contract.
+Method:
+1) Use state/transition sections from maintainer workbook.
+Output format:
+- State list and allowed transition table.
+Validation:
+- Transition rules must match runtime guard behavior.
+}}}
+
+## Persistence and evidence contract
+
+{{{
+Describe state store schema and transition evidence requirements.
+Method:
+1) Read persistence/evidence sections from maintainer workbook.
+Output format:
+- Store schema summary and evidence field bullets.
+Validation:
+- Store path and required evidence fields must match implementation.
+}}}

package/src/modules/documentation/templates/workbooks/transcript-automation-baseline.md

@@ -0,0 +1,68 @@
+{{{AI Documentation Directive}}}
+
+# Transcript Automation Baseline (Phase 5)
+
+Canonical design baseline for transcript intelligence automation.
+
+## Scope
+
+{{{
+Capture baseline scope and compatibility expectation for follow-on tasks.
+Method:
+1) Read `docs/maintainers/workbooks/transcript-automation-baseline.md` and `docs/maintainers/ROADMAP.md`.
+2) Preserve task ranges and compatibility constraints.
+Output format:
+- 2 bullets.
+Validation:
+- Task IDs must match task-engine state and roadmap wording.
+}}}
+
+## Command model
+
+{{{
+Describe transcript automation commands and behavioral contract.
+Method:
+1) Read improvement module docs and maintainer workbook.
+2) Preserve command names and policy sensitivity.
+Output format:
+- Bullets grouped by command.
+Validation:
+- Command names must exist in module instruction surfaces.
+}}}
+
+## Config and cadence contract
+
+{{{
+Document config keys and cadence decision rules.
+Method:
+1) Read `src/modules/improvement/config.md` and maintainer workbook.
+2) Preserve default values and skip/generate rules.
+Output format:
+- Key list plus cadence rule bullets.
+Validation:
+- Keys and defaults must match current config metadata.
+}}}
+
+## Safety and observability boundaries
+
+{{{
+Summarize privacy/safety constraints and output diagnostics requirements.
+Method:
+1) Read maintainer workbook and improvement module behavior docs.
+Output format:
+- 4-6 bullets.
+Validation:
+- Keep local-only transcript archive default and policy-gated generation behavior.
+}}}
+
+## Rollout guardrails
+
+{{{
+State constraints for future changes to this baseline.
+Method:
+1) Read roadmap + workbook guardrail language.
+Output format:
+- 2-3 bullets.
+Validation:
+- Require same-change updates for compatibility-impacting baseline changes.
+}}}

package/src/modules/documentation/types.ts

@@ -0,0 +1,51 @@
+export type DocumentationGenerateOptions = {
+  dryRun?: boolean;
+  overwrite?: boolean;
+  overwriteAi?: boolean;
+  overwriteHuman?: boolean;
+  strict?: boolean;
+  maxValidationAttempts?: number;
+  allowWithoutTemplate?: boolean;
+};
+
+export type DocumentationConflict = {
+  source: string;
+  reason: string;
+  severity: "warn" | "stop";
+};
+
+export type DocumentationValidationIssue = {
+  check: "schema" | "section-coverage" | "template-resolution" | "write-boundary" | "conflict";
+  message: string;
+  resolved: boolean;
+};
+
+export type DocumentationGenerationEvidence = {
+  documentType: string;
+  filesRead: string[];
+  filesWritten: string[];
+  filesSkipped: string[];
+  validationIssues: DocumentationValidationIssue[];
+  conflicts: DocumentationConflict[];
+  attemptsUsed: number;
+  timestamp: string;
+};
+
+export type DocumentationGenerateResult = {
+  ok: boolean;
+  aiOutputPath?: string;
+  humanOutputPath?: string;
+  evidence: DocumentationGenerationEvidence;
+};
+
+export type DocumentationBatchResult = {
+  ok: boolean;
+  results: DocumentationGenerateResult[];
+  summary: {
+    total: number;
+    succeeded: number;
+    failed: number;
+    skipped: number;
+    timestamp: string;
+  };
+};