@workflow-cannon/workspace-kit 0.7.0 → 0.9.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;
+  };
+};

package/dist/modules/task-engine/generator.d.ts

@@ -1,3 +0,0 @@
-import type { TaskEntity } from "./types.js";
-export declare function generateTasksMd(tasks: TaskEntity[]): string;
-export declare function syncTaskHeadingsInMarkdown(markdown: string, tasks: TaskEntity[]): string;

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

@@ -1,118 +0,0 @@
-const STATUS_MARKERS = {
-    proposed: "[p]",
-    ready: "[ ]",
-    in_progress: "[~]",
-    blocked: "[!]",
-    completed: "[x]",
-    cancelled: "[-]"
-};
-function groupByPhase(tasks) {
-    const groups = new Map();
-    for (const task of tasks) {
-        const phase = task.phase ?? "Uncategorized";
-        const group = groups.get(phase) ?? [];
-        group.push(task);
-        groups.set(phase, group);
-    }
-    return groups;
-}
-function buildReadyQueueLine(tasks) {
-    const ready = tasks
-        .filter((t) => t.status === "ready")
-        .sort((a, b) => {
-        const pa = a.priority ?? "P9";
-        const pb = b.priority ?? "P9";
-        return pa.localeCompare(pb);
-    });
-    if (ready.length === 0)
-        return "- Ready queue: _(empty)_";
-    return `- Ready queue: ${ready.map((t) => `\`${t.id}\``).join(", ")}`;
-}
-function buildCurrentPhase(tasks) {
-    const inProgress = tasks.filter((t) => t.status === "in_progress");
-    const ready = tasks.filter((t) => t.status === "ready");
-    const active = [...inProgress, ...ready];
-    if (active.length === 0)
-        return "- Current phase in execution: _(no active tasks)_";
-    const phases = [...new Set(active.map((t) => t.phase).filter(Boolean))];
-    if (phases.length === 0)
-        return "- Current phase in execution: _(unknown)_";
-    return `- Current phase in execution: _${phases[0]}_`;
-}
-function renderTask(task) {
-    const marker = STATUS_MARKERS[task.status] ?? "[ ]";
-    const lines = [];
-    lines.push(`### ${marker} ${task.id} ${task.title}`);
-    if (task.priority) {
-        lines.push(`- Priority: ${task.priority}`);
-    }
-    if (task.approach) {
-        lines.push(`- Approach: ${task.approach}`);
-    }
-    const deps = task.dependsOn ?? [];
-    lines.push(`- Depends on: ${deps.length > 0 ? deps.map((d) => `\`${d}\``).join(", ") : "none"}`);
-    const unblocks = task.unblocks ?? [];
-    if (unblocks.length > 0) {
-        lines.push(`- Unblocks: ${unblocks.map((u) => `\`${u}\``).join(", ")}`);
-    }
-    if (task.technicalScope && task.technicalScope.length > 0) {
-        lines.push("- Technical scope:");
-        for (const item of task.technicalScope) {
-            lines.push(`  - ${item}`);
-        }
-    }
-    if (task.acceptanceCriteria && task.acceptanceCriteria.length > 0) {
-        lines.push("- Acceptance criteria:");
-        for (const item of task.acceptanceCriteria) {
-            lines.push(`  - ${item}`);
-        }
-    }
-    return lines.join("\n");
-}
-export function generateTasksMd(tasks) {
-    const lines = [];
-    lines.push("# Workflow Cannon Tasks");
-    lines.push("");
-    lines.push("> This file is generated by the Task Engine. Do not edit manually.");
-    lines.push("");
-    lines.push("Status markers:");
-    lines.push("- `[p]` proposed");
-    lines.push("- `[ ]` ready");
-    lines.push("- `[~]` in progress");
-    lines.push("- `[!]` blocked");
-    lines.push("- `[x]` completed");
-    lines.push("- `[-]` cancelled");
-    lines.push("");
-    lines.push("## Current execution state");
-    lines.push("");
-    lines.push(buildCurrentPhase(tasks));
-    lines.push(buildReadyQueueLine(tasks));
-    lines.push("");
-    const phaseGroups = groupByPhase(tasks);
-    for (const [phase, phaseTasks] of phaseGroups) {
-        lines.push(`## ${phase}`);
-        lines.push("");
-        for (const task of phaseTasks) {
-            lines.push(renderTask(task));
-            lines.push("");
-        }
-    }
-    return lines.join("\n");
-}
-export function syncTaskHeadingsInMarkdown(markdown, tasks) {
-    const byId = new Map(tasks.map((task) => [task.id, task]));
-    const lines = markdown.split("\n");
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i];
-        const match = line.match(/^###\s+\[[^\]]*\]\s+(T\d+)\s+(.+)$/);
-        if (!match)
-            continue;
-        const id = match[1];
-        const task = byId.get(id);
-        if (!task)
-            continue;
-        const marker = STATUS_MARKERS[task.status] ?? "[ ]";
-        lines[i] = `### ${marker} ${task.id} ${task.title}`;
-    }
-    return lines.join("\n");
-}

package/dist/modules/task-engine/importer.d.ts

@@ -1,8 +0,0 @@
-import type { TaskEntity } from "./types.js";
-export type ImportResult = {
-    imported: number;
-    skipped: number;
-    errors: string[];
-    tasks: TaskEntity[];
-};
-export declare function importTasksFromMarkdown(sourcePath: string): Promise<ImportResult>;