@workflow-cannon/workspace-kit 0.17.0 → 0.24.0

package/dist/modules/documentation/types.d.ts

@@ -44,3 +44,185 @@ export type DocumentationBatchResult = {
         timestamp: string;
     };
 };
+export type NormalizedRecordStatus = "active" | "deprecated" | "draft" | "observed" | "planned";
+export type NormalizedBaseRecord = {
+    id?: string;
+    status?: NormalizedRecordStatus;
+    refs?: string[];
+};
+export type NormalizedMeta = NormalizedBaseRecord & {
+    schema: "base.v2";
+    doc: string;
+    truth: "canonical" | "observed" | "planned";
+    profile?: "core" | "runbook" | "workbook";
+    title?: string;
+    owner?: string;
+    tags?: string[];
+};
+export type NormalizedRef = NormalizedBaseRecord & {
+    id: string;
+    type: "adr" | "file" | "code" | "doc" | "issue" | "pr" | "test" | "external";
+    target: string;
+    anchor?: string;
+    label?: string;
+    note?: string;
+};
+export type NormalizedRule = NormalizedBaseRecord & {
+    id: string;
+    level: "must" | "must_not" | "should" | "may";
+    scope: string;
+    scope_kind?: string;
+    kind?: string;
+    directive: string;
+    why: string;
+    unless?: string;
+    also?: string[];
+    risk?: "low" | "medium" | "high" | "critical";
+    approval?: "none" | "prompt" | "required";
+    override?: "auto" | "warn" | "prompt" | "stop";
+};
+export type NormalizedCheck = NormalizedBaseRecord & {
+    id: string;
+    scope: string;
+    assertion: string;
+    when?: string;
+    onFail?: "auto" | "warn" | "prompt" | "stop";
+};
+export type NormalizedDecision = NormalizedBaseRecord & {
+    id: string;
+    topic: string;
+    choice: string;
+    why: string;
+    consequence?: string;
+};
+export type NormalizedExample = NormalizedBaseRecord & {
+    id: string;
+    for: string;
+    kind: "good" | "bad" | "edge";
+    text: string;
+};
+export type NormalizedTerm = NormalizedBaseRecord & {
+    name: string;
+    definition: string;
+};
+export type NormalizedCommand = NormalizedBaseRecord & {
+    id: string;
+    name: string;
+    use: string;
+    scope: string;
+    expectation: string;
+    risk?: "low" | "medium" | "high" | "critical";
+    sensitivity?: "non_sensitive" | "policy_sensitive";
+};
+export type NormalizedWorkflow = NormalizedBaseRecord & {
+    id: string;
+    name: string;
+    when: string;
+    steps: string[];
+    done: string[];
+    forbid?: string[];
+    askIf?: string;
+    haltIf?: string;
+    approval?: "none" | "prompt" | "required";
+    risk?: "low" | "medium" | "high" | "critical";
+};
+export type NormalizedRunbook = NormalizedBaseRecord & {
+    name: string;
+    scope: string;
+    owner: string;
+};
+export type NormalizedWorkbook = NormalizedBaseRecord & {
+    name: string;
+    phase: string;
+    state: string;
+};
+export type NormalizedChain = NormalizedBaseRecord & {
+    step: string;
+    command: string;
+    expectExit: number;
+};
+export type NormalizedState = NormalizedBaseRecord & {
+    name: string;
+    distTag: string;
+    intent: string;
+};
+export type NormalizedTransition = NormalizedBaseRecord & {
+    from: string;
+    to: string;
+    requires: string[];
+};
+export type NormalizedPromotion = NormalizedBaseRecord & {
+    from: string;
+    to: string;
+    requires: string[];
+};
+export type NormalizedRollback = NormalizedBaseRecord & {
+    strategy: string;
+    note: string;
+};
+export type NormalizedArtifact = NormalizedBaseRecord & {
+    path: string;
+    schema: string;
+};
+export type NormalizedConfig = NormalizedBaseRecord & {
+    key: string;
+    default: string;
+};
+export type NormalizedCadence = NormalizedBaseRecord & {
+    rule: string;
+};
+export type NormalizedGuardrail = NormalizedBaseRecord & {
+    id: string;
+    level: "must" | "must_not" | "should" | "may";
+    directive: string;
+    why: string;
+};
+export type NormalizedDocument = {
+    meta: NormalizedMeta | null;
+    refs: NormalizedRef[];
+    rules: NormalizedRule[];
+    checks: NormalizedCheck[];
+    decisions: NormalizedDecision[];
+    examples: NormalizedExample[];
+    terms: NormalizedTerm[];
+    commands: NormalizedCommand[];
+    workflows: NormalizedWorkflow[];
+    runbooks: NormalizedRunbook[];
+    workbooks: NormalizedWorkbook[];
+    chains: NormalizedChain[];
+    states: NormalizedState[];
+    transitions: NormalizedTransition[];
+    promotions: NormalizedPromotion[];
+    rollbacks: NormalizedRollback[];
+    artifacts: NormalizedArtifact[];
+    configs: NormalizedConfig[];
+    cadences: NormalizedCadence[];
+    guardrails: NormalizedGuardrail[];
+    refsById: Map<string, NormalizedRef>;
+    examplesByParent: Map<string, NormalizedExample[]>;
+    profileRecords: Map<"core" | "runbook" | "workbook", Array<NormalizedBaseRecord>>;
+};
+export type ViewModelSection = {
+    id: string;
+    title?: string;
+    description?: string;
+    renderer: string;
+    source: "meta" | "refs" | "rules" | "checks" | "decisions" | "examples" | "terms" | "commands" | "workflows" | "runbooks" | "workbooks" | "chains" | "states" | "transitions" | "promotions" | "rollbacks" | "artifacts" | "configs" | "cadences" | "guardrails";
+    where?: Record<string, string | number | boolean>;
+    sortBy?: string[];
+    template?: string;
+};
+export type ViewRenderPolicy = {
+    id: string;
+    mode: "append" | "replace" | "fallback";
+    when?: string;
+};
+export type ViewModelDefinition = {
+    id: string;
+    version: number;
+    docType: string;
+    target: string;
+    profile?: "core" | "runbook" | "workbook";
+    sections: ViewModelSection[];
+    renderPolicies?: ViewRenderPolicy[];
+};

package/dist/modules/documentation/validator.d.ts

@@ -0,0 +1,8 @@
+import type { DocumentationValidationIssue } from "./types.js";
+export type AiValidationContext = {
+    strict: boolean;
+    workspacePath: string;
+    expectedDoc?: "rules" | "runbook" | "workbook";
+};
+export declare function validateAiSchema(aiOutput: string, ctx: AiValidationContext): DocumentationValidationIssue[];
+export declare function autoResolveAiSchema(aiOutput: string): string;

package/dist/modules/documentation/validator.js

@@ -0,0 +1,234 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { parseAiDocument } from "./parser.js";
+const REF_TYPES = new Set(["adr", "file", "code", "doc", "issue", "pr", "test", "external"]);
+const REQUIRED_BY_PROFILE = {
+    core: ["meta", "ref", "rule", "check", "decision", "example", "term", "command", "workflow"],
+    runbook: [
+        "meta",
+        "ref",
+        "rule",
+        "check",
+        "decision",
+        "example",
+        "term",
+        "command",
+        "workflow",
+        "runbook",
+        "chain",
+        "artifact",
+        "state",
+        "transition",
+        "promotion",
+        "rollback",
+        "config",
+        "cadence",
+        "guardrail"
+    ],
+    workbook: [
+        "meta",
+        "ref",
+        "rule",
+        "check",
+        "decision",
+        "example",
+        "term",
+        "command",
+        "workflow",
+        "workbook",
+        "state",
+        "transition",
+        "artifact",
+        "guardrail"
+    ]
+};
+function isAllowedMetaDoc(doc) {
+    return (doc === "rules" ||
+        doc === "runbook" ||
+        doc === "workbook" ||
+        doc === "generator" ||
+        doc === "map" ||
+        doc === "workflows" ||
+        doc === "commands" ||
+        doc === "decisions" ||
+        doc === "glossary" ||
+        doc === "observed" ||
+        doc === "planned" ||
+        doc === "checks" ||
+        doc === "manifest");
+}
+function profileForDoc(doc, explicitProfile) {
+    if (explicitProfile === "core" || explicitProfile === "runbook" || explicitProfile === "workbook") {
+        return explicitProfile;
+    }
+    if (doc === "runbook")
+        return "runbook";
+    if (doc === "workbook")
+        return "workbook";
+    return "core";
+}
+export function validateAiSchema(aiOutput, ctx) {
+    const issues = [];
+    const records = parseAiDocument(aiOutput);
+    if (records.length === 0) {
+        return [{ check: "schema", message: "AI output is empty", resolved: false }];
+    }
+    const meta = records[0];
+    if (!meta || meta.type !== "meta") {
+        return [{ check: "schema", message: "AI output must start with a meta record", resolved: false }];
+    }
+    const schema = meta.kv["schema"];
+    const doc = meta.kv["doc"];
+    const truth = meta.kv["truth"];
+    const status = meta.kv["status"] ?? meta.kv["st"];
+    const profile = profileForDoc(doc, meta.kv["profile"]);
+    const isLegacySchema = schema !== "base.v2";
+    if (schema !== "base.v2") {
+        issues.push({
+            check: "schema",
+            message: `AI meta.schema must be 'base.v2' (found '${schema ?? ""}')`,
+            resolved: true
+        });
+    }
+    if (!doc || !isAllowedMetaDoc(doc)) {
+        issues.push({ check: "schema", message: `Unsupported meta.doc '${doc ?? ""}'`, resolved: false });
+    }
+    if (!truth)
+        issues.push({ check: "schema", message: "AI meta.truth is required", resolved: false });
+    if (!status)
+        issues.push({ check: "schema", message: "AI meta.status is required", resolved: false });
+    if (ctx.expectedDoc && doc && ctx.expectedDoc !== doc) {
+        issues.push({
+            check: "schema",
+            message: `meta.doc '${doc}' does not match expected doc family for '${ctx.expectedDoc}'`,
+            resolved: !ctx.strict
+        });
+    }
+    const presentByType = { meta: true };
+    const knownIds = new Set();
+    for (const rec of records.slice(1)) {
+        presentByType[rec.type] = true;
+        const id = rec.kv["id"];
+        if (id)
+            knownIds.add(id);
+        if (rec.kv["name"])
+            knownIds.add(rec.kv["name"]);
+    }
+    for (const rec of records.slice(1)) {
+        if (rec.type === "rule" && !rec.kv["why"]) {
+            issues.push({
+                check: "schema",
+                message: "rule records require why",
+                resolved: isLegacySchema || !ctx.strict
+            });
+        }
+        if (rec.type === "ref") {
+            const type = rec.kv["type"];
+            const target = rec.kv["target"] ?? rec.kv["path"];
+            const legacyPath = rec.kv["path"];
+            if (!rec.kv["id"] || !type || !target) {
+                issues.push({
+                    check: "schema",
+                    message: "ref records require id, type, target",
+                    resolved: isLegacySchema || !ctx.strict
+                });
+                if (legacyPath && !existsSync(resolve(ctx.workspacePath, legacyPath))) {
+                    issues.push({
+                        check: "schema",
+                        message: `ref.path does not exist: '${legacyPath}'`,
+                        resolved: !ctx.strict
+                    });
+                }
+            }
+            else if (!REF_TYPES.has(type)) {
+                issues.push({
+                    check: "schema",
+                    message: `ref.type '${type}' must be one of ${[...REF_TYPES].join(", ")}`,
+                    resolved: isLegacySchema || !ctx.strict
+                });
+            }
+            else if ((type === "file" || type === "code" || type === "doc") && !existsSync(resolve(ctx.workspacePath, target))) {
+                issues.push({
+                    check: "schema",
+                    message: `ref.target does not exist: '${target}'`,
+                    resolved: !ctx.strict
+                });
+            }
+        }
+        if (rec.type === "example") {
+            const parent = rec.kv["for"];
+            const kind = rec.kv["kind"];
+            if (!parent || !knownIds.has(parent)) {
+                issues.push({
+                    check: "schema",
+                    message: `example.for must reference an existing record id/name (found '${parent ?? ""}')`,
+                    resolved: isLegacySchema || !ctx.strict
+                });
+            }
+            if (!kind || !["good", "bad", "edge"].includes(kind)) {
+                issues.push({
+                    check: "schema",
+                    message: "example.kind must be one of good|bad|edge",
+                    resolved: isLegacySchema || !ctx.strict
+                });
+            }
+        }
+    }
+    const isActive = status === "active";
+    if (isActive) {
+        // Preserve strict runbook/workbook/rules baseline behavior during v2 migration.
+        if (doc === "runbook" && !presentByType["rule"] && !presentByType["chain"]) {
+            issues.push({
+                check: "schema",
+                message: "Missing required AI records for doc family 'runbook': at least one rule| or chain| record",
+                resolved: !ctx.strict
+            });
+        }
+        if (doc === "workbook" && !presentByType["command"]) {
+            issues.push({
+                check: "schema",
+                message: "Missing required AI records for doc family 'workbook': at least one command| record",
+                resolved: !ctx.strict
+            });
+        }
+        if (doc === "workbook" && !presentByType["config"]) {
+            issues.push({
+                check: "schema",
+                message: "Missing required AI records for doc family 'workbook': at least one config| record",
+                resolved: !ctx.strict
+            });
+        }
+        if (doc === "rules" && !presentByType["rule"] && !presentByType["check"]) {
+            issues.push({
+                check: "schema",
+                message: "Missing required AI records for doc family 'rules': at least one rule| or check| record",
+                resolved: !ctx.strict
+            });
+        }
+        const missing = REQUIRED_BY_PROFILE[profile]
+            .filter((type) => {
+            if (type === "workflow")
+                return !presentByType["workflow"] && !presentByType["wf"];
+            if (type === "command")
+                return !presentByType["command"] && !presentByType["cmd"];
+            if (type === "example")
+                return !presentByType["example"];
+            return !presentByType[type];
+        })
+            .map((t) => `${t}| record`);
+        if (missing.length > 0) {
+            issues.push({
+                check: "schema",
+                message: `Missing required AI records for profile '${profile}': ${missing.join(", ")}`,
+                resolved: isLegacySchema || !ctx.strict
+            });
+        }
+    }
+    return issues;
+}
+export function autoResolveAiSchema(aiOutput) {
+    if (aiOutput.startsWith("meta|schema=") || aiOutput.startsWith("meta|v=")) {
+        return aiOutput;
+    }
+    return `meta|schema=base.v2|doc=rules|truth=canonical|status=draft|profile=core\n\n${aiOutput}`;
+}

package/dist/modules/documentation/view-models.d.ts

@@ -0,0 +1,3 @@
+import type { ViewModelDefinition } from "./types.js";
+export declare function loadViewModel(workspacePath: string, viewFile: string): Promise<ViewModelDefinition>;
+export declare function listViewModels(workspacePath: string): Promise<string[]>;

package/dist/modules/documentation/view-models.js

@@ -0,0 +1,124 @@
+import { readdir, readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+function parseScalar(raw) {
+    const v = raw.trim();
+    if (v === "true")
+        return true;
+    if (v === "false")
+        return false;
+    if (/^-?\d+$/.test(v))
+        return Number.parseInt(v, 10);
+    return v.replace(/^"(.*)"$/, "$1");
+}
+function parseBlock(lines, start, indent) {
+    const items = [];
+    let idx = start;
+    while (idx < lines.length) {
+        const line = lines[idx];
+        const currentIndent = line.search(/\S|$/);
+        if (currentIndent < indent)
+            break;
+        const trimmed = line.trim();
+        if (!trimmed.startsWith("- ")) {
+            idx += 1;
+            continue;
+        }
+        const item = {};
+        const first = trimmed.slice(2);
+        if (first.includes(":")) {
+            const split = first.indexOf(":");
+            const k = first.slice(0, split).trim();
+            const v = first.slice(split + 1).trim();
+            item[k] = parseScalar(v);
+        }
+        idx += 1;
+        while (idx < lines.length) {
+            const next = lines[idx];
+            const nextIndent = next.search(/\S|$/);
+            if (nextIndent <= currentIndent)
+                break;
+            const t = next.trim();
+            const split = t.indexOf(":");
+            if (split > 0) {
+                const k = t.slice(0, split).trim();
+                const v = t.slice(split + 1).trim();
+                item[k] = parseScalar(v);
+            }
+            idx += 1;
+        }
+        items.push(item);
+    }
+    return { end: idx, items };
+}
+function parseViewModelYaml(text) {
+    const lines = text
+        .split("\n")
+        .map((l) => l.replace(/\t/g, "  "))
+        .filter((l) => l.trim().length > 0 && !l.trim().startsWith("#"));
+    const root = {};
+    let idx = 0;
+    while (idx < lines.length) {
+        const line = lines[idx];
+        const trimmed = line.trim();
+        const split = trimmed.indexOf(":");
+        if (split <= 0) {
+            idx += 1;
+            continue;
+        }
+        const key = trimmed.slice(0, split).trim();
+        const value = trimmed.slice(split + 1).trim();
+        if (!value) {
+            const parsed = parseBlock(lines, idx + 1, line.search(/\S|$/) + 2);
+            root[key] = parsed.items;
+            idx = parsed.end;
+            continue;
+        }
+        root[key] = parseScalar(value);
+        idx += 1;
+    }
+    const sections = root["sections"] ?? [];
+    const renderPolicies = root["render_policies"] ?? [];
+    return {
+        id: String(root["id"] ?? ""),
+        version: Number(root["version"] ?? 1),
+        docType: String(root["doc_type"] ?? ""),
+        target: String(root["target"] ?? ""),
+        profile: root["source_profile"],
+        sections: sections.map((s) => ({
+            id: String(s["id"] ?? ""),
+            title: s["title"] ? String(s["title"]) : undefined,
+            description: s["description"] ? String(s["description"]) : undefined,
+            renderer: String(s["renderer"] ?? ""),
+            source: String(s["source"] ?? "meta"),
+            template: s["template"] ? String(s["template"]) : undefined
+        })),
+        renderPolicies: renderPolicies.map((p) => ({
+            id: String(p["id"] ?? ""),
+            mode: String(p["mode"] ?? "append"),
+            when: p["when"] ? String(p["when"]) : undefined
+        }))
+    };
+}
+export async function loadViewModel(workspacePath, viewFile) {
+    const fullPath = resolve(resolveViewsRoot(workspacePath), viewFile);
+    const content = await readFile(fullPath, "utf8");
+    return parseViewModelYaml(content);
+}
+export async function listViewModels(workspacePath) {
+    const viewsPath = resolveViewsRoot(workspacePath);
+    const entries = await readdir(viewsPath, { withFileTypes: true });
+    return entries
+        .filter((e) => e.isFile() && e.name.endsWith(".view.yaml"))
+        .map((e) => e.name)
+        .sort();
+}
+function resolveViewsRoot(workspacePath) {
+    const local = resolve(workspacePath, "src/modules/documentation/views");
+    if (existsSync(local))
+        return local;
+    const runtimeSourceRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+    return resolve(runtimeSourceRoot, "src/modules/documentation/views");
+}

package/dist/modules/improvement/generate-recommendations-runtime.js

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { openPlanningStores } from "../task-engine/planning-open.js";
+import { openPlanningStores } from "../../core/planning/index.js";
 import { appendLineageEvent } from "../../core/lineage-store.js";
 import { loadImprovementState, saveImprovementState } from "./improvement-state.js";
 import { ingestAgentTranscripts, ingestConfigMutations, ingestGitDiffBetweenTags, ingestPolicyDenials, ingestTaskTransitionFriction, taskIdForEvidenceKey } from "./ingest.js";
@@ -42,7 +42,7 @@ export async function runGenerateRecommendations(ctx, args) {
     const runId = randomUUID();
     const planning = await openPlanningStores(ctx);
     const store = planning.taskStore;
-    const state = await loadImprovementState(ctx.workspacePath);
+    const state = await loadImprovementState(ctx.workspacePath, ctx.effectiveConfig);
     const transcriptsRoot = resolveTranscriptArchivePath(ctx, args);
     const fromTag = typeof args.fromTag === "string" ? args.fromTag.trim() : undefined;
     const toTag = typeof args.toTag === "string" ? args.toTag.trim() : undefined;
@@ -112,7 +112,7 @@ export async function runGenerateRecommendations(ctx, args) {
         });
     }
     await store.save();
-    await saveImprovementState(ctx.workspacePath, state);
+    await saveImprovementState(ctx.workspacePath, state, ctx.effectiveConfig);
     const skipped = skippedDuplicateEvidenceKey + skippedExistingTaskId;
     return {
         runId,

package/dist/modules/improvement/improvement-state.d.ts

@@ -18,5 +18,5 @@ export type ImprovementStateDocument = {
     transcriptRetryQueue: TranscriptRetryEntry[];
 };
 export declare function emptyImprovementState(): ImprovementStateDocument;
-export declare function loadImprovementState(workspacePath: string): Promise<ImprovementStateDocument>;
-export declare function saveImprovementState(workspacePath: string, doc: ImprovementStateDocument): Promise<void>;
+export declare function loadImprovementState(workspacePath: string, effectiveConfig?: Record<string, unknown>): Promise<ImprovementStateDocument>;
+export declare function saveImprovementState(workspacePath: string, doc: ImprovementStateDocument, effectiveConfig?: Record<string, unknown>): Promise<void>;