@workflow-cannon/workspace-kit 0.4.1 → 0.6.0

package/README.md

@@ -63,7 +63,8 @@ This keeps automation adaptive without sacrificing safety, governance, or develo
 
 - **Phase 0** and **Phase 1** (task engine, `v0.3.0`) are complete.
 - **Phase 2** (layered config, policy gates, cutover docs, `v0.4.0`) is complete in-repo; see `docs/maintainers/TASKS.md` and `docs/maintainers/ROADMAP.md`.
-- **Phase 2b** (policy + config UX, `v0.4.1`) is complete in-repo. **Phase 3** (enhancement loop MVP, `v0.5.0`) is next (`T190` onward).
+- **Phase 2b** (policy + config UX, `v0.4.1`) and **Phase 3** (enhancement loop MVP, `v0.5.0`) are complete in-repo: evidence-driven **improvement** tasks, **`approvals`** (`review-item`), heuristic confidence, and append-only lineage.
+- **Phase 4** (`v0.6.0`) is complete in-repo: compatibility matrix/gates, diagnostics/SLO baseline evidence, release-channel mapping, and planning-doc consistency checks.
 
 ## Goals
 

package/dist/core/index.d.ts

@@ -5,4 +5,6 @@ export { appendPolicyTrace, getExtraSensitiveModuleCommandsFromEffective, getOpe
 export { assertWritableKey, getConfigKeyMetadata, getConfigRegistryExport, listConfigMetadata, validatePersistedConfigDocument, validateValueForMetadata, type ConfigKeyExposure, type ConfigKeyMetadata, type ConfigValueType } from "./config-metadata.js";
 export { appendConfigMutation, CONFIG_MUTATIONS_SCHEMA_VERSION, summarizeForEvidence, type ConfigMutationRecord } from "./config-mutations.js";
 export { generateConfigReferenceDocs, runWorkspaceConfigCli, type ConfigCliIo } from "./config-cli.js";
+export { LINEAGE_SCHEMA_VERSION, lineageCorrelationRoot, type LineageAppPayload, type LineageCorrPayload, type LineageDecPayload, type LineageEvent, type LineageEventType, type LineageRecPayload } from "./lineage-contract.js";
+export { appendLineageEvent, newLineageEventId, queryLineageChain, readLineageEvents } from "./lineage-store.js";
 export type CoreRuntimeVersion = "0.1";

package/dist/core/index.js

@@ -5,3 +5,5 @@ export { appendPolicyTrace, getExtraSensitiveModuleCommandsFromEffective, getOpe
 export { assertWritableKey, getConfigKeyMetadata, getConfigRegistryExport, listConfigMetadata, validatePersistedConfigDocument, validateValueForMetadata } from "./config-metadata.js";
 export { appendConfigMutation, CONFIG_MUTATIONS_SCHEMA_VERSION, summarizeForEvidence } from "./config-mutations.js";
 export { generateConfigReferenceDocs, runWorkspaceConfigCli } from "./config-cli.js";
+export { LINEAGE_SCHEMA_VERSION, lineageCorrelationRoot } from "./lineage-contract.js";
+export { appendLineageEvent, newLineageEventId, queryLineageChain, readLineageEvents } from "./lineage-store.js";

package/dist/core/lineage-contract.d.ts

@@ -0,0 +1,59 @@
+/**
+ * T203: Immutable lineage event contract (append-only store, correlation fields).
+ * @see docs/maintainers/TASKS.md T192, T203
+ */
+export declare const LINEAGE_SCHEMA_VERSION: 1;
+export type LineageEventType = "rec" | "dec" | "app" | "corr";
+/** Recommendation enqueued (Task Engine improvement task created). */
+export type LineageRecPayload = {
+    recommendationTaskId: string;
+    evidenceKey: string;
+    title: string;
+    confidence: number;
+    confidenceTier: string;
+    provenanceRefs: Record<string, string>;
+};
+/** Human approval decision recorded (before or alongside task transition). */
+export type LineageDecPayload = {
+    recommendationTaskId: string;
+    evidenceKey: string;
+    decisionVerb: "accept" | "decline" | "accept_edited";
+    actor: string;
+    decisionFingerprint: string;
+    policyTraceRef?: {
+        operationId: string;
+        timestamp: string;
+    };
+    /** Optional link to a config mutation evidence row when the reviewer supplies it. */
+    configMutationRef?: {
+        timestamp: string;
+        key: string;
+    };
+};
+/** Applied change marker (task reached completed via acceptance). */
+export type LineageAppPayload = {
+    recommendationTaskId: string;
+    evidenceKey: string;
+    decisionFingerprint: string;
+    finalTaskStatus: "completed";
+};
+/** Optional correlation enrichment (trace linkage). */
+export type LineageCorrPayload = {
+    recommendationTaskId: string;
+    evidenceKey: string;
+    policySchemaVersion?: number;
+    policyOperationId?: string;
+    policyTimestamp?: string;
+    mutationRecordTimestamp?: string;
+    mutationKey?: string;
+};
+export type LineageEvent = {
+    schemaVersion: typeof LINEAGE_SCHEMA_VERSION;
+    eventId: string;
+    eventType: LineageEventType;
+    timestamp: string;
+    correlationRoot: string;
+    payload: LineageRecPayload | LineageDecPayload | LineageAppPayload | LineageCorrPayload;
+};
+/** Stable correlation root: ties chain to recommendation + evidence identity. */
+export declare function lineageCorrelationRoot(recommendationTaskId: string, evidenceKey: string): string;

package/dist/core/lineage-contract.js

@@ -0,0 +1,9 @@
+/**
+ * T203: Immutable lineage event contract (append-only store, correlation fields).
+ * @see docs/maintainers/TASKS.md T192, T203
+ */
+export const LINEAGE_SCHEMA_VERSION = 1;
+/** Stable correlation root: ties chain to recommendation + evidence identity. */
+export function lineageCorrelationRoot(recommendationTaskId, evidenceKey) {
+    return `${recommendationTaskId}::${evidenceKey}`;
+}

package/dist/core/lineage-store.d.ts

@@ -0,0 +1,16 @@
+import type { LineageEvent, LineageEventType } from "./lineage-contract.js";
+export declare function newLineageEventId(): string;
+export declare function appendLineageEvent(workspacePath: string, input: {
+    eventType: LineageEventType;
+    recommendationTaskId: string;
+    evidenceKey: string;
+    payload: LineageEvent["payload"];
+    eventId?: string;
+    timestamp?: string;
+}): Promise<LineageEvent>;
+export declare function readLineageEvents(workspacePath: string): Promise<LineageEvent[]>;
+/** Reconstruct rec → dec → app chain for a recommendation task id (deterministic sort by timestamp). */
+export declare function queryLineageChain(workspacePath: string, recommendationTaskId: string): Promise<{
+    events: LineageEvent[];
+    byType: Record<LineageEventType, LineageEvent[]>;
+}>;

package/dist/core/lineage-store.js

@@ -0,0 +1,74 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import crypto from "node:crypto";
+import { LINEAGE_SCHEMA_VERSION, lineageCorrelationRoot } from "./lineage-contract.js";
+const LINEAGE_DIR = ".workspace-kit/lineage";
+const EVENTS_FILE = "events.jsonl";
+function eventsPath(workspacePath) {
+    return path.join(workspacePath, LINEAGE_DIR, EVENTS_FILE);
+}
+export function newLineageEventId() {
+    return `lev-${Date.now()}-${crypto.randomUUID().slice(0, 8)}`;
+}
+export async function appendLineageEvent(workspacePath, input) {
+    const timestamp = input.timestamp ?? new Date().toISOString();
+    const correlationRoot = lineageCorrelationRoot(input.recommendationTaskId, input.evidenceKey);
+    const event = {
+        schemaVersion: LINEAGE_SCHEMA_VERSION,
+        eventId: input.eventId ?? newLineageEventId(),
+        eventType: input.eventType,
+        timestamp,
+        correlationRoot,
+        payload: input.payload
+    };
+    const fp = eventsPath(workspacePath);
+    await fs.mkdir(path.dirname(fp), { recursive: true });
+    await fs.appendFile(fp, `${JSON.stringify(event)}\n`, "utf8");
+    return event;
+}
+export async function readLineageEvents(workspacePath) {
+    const fp = eventsPath(workspacePath);
+    let raw;
+    try {
+        raw = await fs.readFile(fp, "utf8");
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return [];
+        throw e;
+    }
+    const out = [];
+    for (const line of raw.split("\n")) {
+        const t = line.trim();
+        if (!t)
+            continue;
+        try {
+            const ev = JSON.parse(t);
+            if (ev.schemaVersion === LINEAGE_SCHEMA_VERSION)
+                out.push(ev);
+        }
+        catch {
+            /* skip corrupt line */
+        }
+    }
+    return out;
+}
+/** Reconstruct rec → dec → app chain for a recommendation task id (deterministic sort by timestamp). */
+export async function queryLineageChain(workspacePath, recommendationTaskId) {
+    const all = await readLineageEvents(workspacePath);
+    const chain = all.filter((e) => {
+        const p = e.payload;
+        return p.recommendationTaskId === recommendationTaskId;
+    });
+    chain.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+    const byType = {
+        rec: [],
+        dec: [],
+        app: [],
+        corr: []
+    };
+    for (const e of chain) {
+        byType[e.eventType].push(e);
+    }
+    return { events: chain, byType };
+}

package/dist/core/policy.d.ts

@@ -1,5 +1,5 @@
 export declare const POLICY_TRACE_SCHEMA_VERSION: 1;
-export type PolicyOperationId = "cli.upgrade" | "cli.init" | "cli.config-mutate" | "policy.dynamic-sensitive" | "doc.document-project" | "doc.generate-document" | "tasks.import-tasks" | "tasks.generate-tasks-md" | "tasks.run-transition";
+export type PolicyOperationId = "cli.upgrade" | "cli.init" | "cli.config-mutate" | "policy.dynamic-sensitive" | "doc.document-project" | "doc.generate-document" | "tasks.import-tasks" | "tasks.generate-tasks-md" | "tasks.run-transition" | "approvals.review-item" | "improvement.generate-recommendations";
 export declare function getOperationIdForCommand(commandName: string): PolicyOperationId | undefined;
 export declare function getExtraSensitiveModuleCommandsFromEffective(effective: Record<string, unknown>): string[];
 /** Resolve operation id for tracing, including config-declared sensitive module commands. */

package/dist/core/policy.js

@@ -7,7 +7,9 @@ const COMMAND_TO_OPERATION = {
     "generate-document": "doc.generate-document",
     "import-tasks": "tasks.import-tasks",
     "generate-tasks-md": "tasks.generate-tasks-md",
-    "run-transition": "tasks.run-transition"
+    "run-transition": "tasks.run-transition",
+    "review-item": "approvals.review-item",
+    "generate-recommendations": "improvement.generate-recommendations"
 };
 export function getOperationIdForCommand(commandName) {
     return COMMAND_TO_OPERATION[commandName];

package/dist/modules/approvals/decisions-store.d.ts

@@ -0,0 +1,20 @@
+export declare const APPROVAL_DECISION_SCHEMA_VERSION: 1;
+export type ApprovalDecisionRecord = {
+    schemaVersion: typeof APPROVAL_DECISION_SCHEMA_VERSION;
+    fingerprint: string;
+    taskId: string;
+    evidenceKey: string;
+    decisionVerb: "accept" | "decline" | "accept_edited";
+    actor: string;
+    timestamp: string;
+    editedSummary?: string;
+    policyTraceRef?: {
+        operationId: string;
+        timestamp: string;
+    };
+};
+export declare function computeDecisionFingerprint(taskId: string, decisionVerb: string, evidenceKey: string, editedSummary?: string): string;
+export declare function readDecisionFingerprints(workspacePath: string): Promise<Set<string>>;
+export declare function appendDecisionRecord(workspacePath: string, record: Omit<ApprovalDecisionRecord, "schemaVersion" | "timestamp"> & {
+    timestamp?: string;
+}): Promise<void>;

package/dist/modules/approvals/decisions-store.js

@@ -0,0 +1,52 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import crypto from "node:crypto";
+export const APPROVAL_DECISION_SCHEMA_VERSION = 1;
+const DECISIONS_REL = ".workspace-kit/approvals/decisions.jsonl";
+function decisionsPath(workspacePath) {
+    return path.join(workspacePath, DECISIONS_REL);
+}
+export function computeDecisionFingerprint(taskId, decisionVerb, evidenceKey, editedSummary) {
+    const norm = (editedSummary ?? "").trim();
+    return crypto
+        .createHash("sha256")
+        .update([taskId, decisionVerb, evidenceKey, norm].join("\0"), "utf8")
+        .digest("hex");
+}
+export async function readDecisionFingerprints(workspacePath) {
+    const fp = decisionsPath(workspacePath);
+    const set = new Set();
+    let raw;
+    try {
+        raw = await fs.readFile(fp, "utf8");
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return set;
+        throw e;
+    }
+    for (const line of raw.split("\n")) {
+        const t = line.trim();
+        if (!t)
+            continue;
+        try {
+            const rec = JSON.parse(t);
+            if (rec.fingerprint)
+                set.add(rec.fingerprint);
+        }
+        catch {
+            /* skip */
+        }
+    }
+    return set;
+}
+export async function appendDecisionRecord(workspacePath, record) {
+    const fp = decisionsPath(workspacePath);
+    await fs.mkdir(path.dirname(fp), { recursive: true });
+    const full = {
+        schemaVersion: APPROVAL_DECISION_SCHEMA_VERSION,
+        timestamp: record.timestamp ?? new Date().toISOString(),
+        ...record
+    };
+    await fs.appendFile(fp, `${JSON.stringify(full)}\n`, "utf8");
+}

package/dist/modules/approvals/index.js

@@ -1,7 +1,9 @@
+import { resolveActor } from "../../core/policy.js";
+import { runReviewItem } from "./review-runtime.js";
 export const approvalsModule = {
     registration: {
         id: "approvals",
-        version: "0.1.0",
+        version: "0.5.0",
         contractVersion: "1",
         capabilities: ["approvals"],
         dependsOn: ["task-engine"],
@@ -26,5 +28,59 @@ export const approvalsModule = {
                 }
             ]
         }
+    },
+    async onCommand(command, ctx) {
+        if (command.name !== "review-item") {
+            return {
+                ok: false,
+                code: "unsupported-command",
+                message: `Approvals module does not support '${command.name}'`
+            };
+        }
+        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);
+        const taskId = typeof args.taskId === "string" ? args.taskId : "";
+        const decision = args.decision;
+        if (decision !== "accept" && decision !== "decline" && decision !== "accept_edited") {
+            return {
+                ok: false,
+                code: "invalid-args",
+                message: "decision must be accept, decline, or accept_edited"
+            };
+        }
+        const editedSummary = typeof args.editedSummary === "string" ? args.editedSummary : undefined;
+        let policyTraceRef;
+        const ptr = args.policyTraceRef;
+        if (ptr && typeof ptr === "object" && !Array.isArray(ptr)) {
+            const o = ptr;
+            if (typeof o.operationId === "string" && typeof o.timestamp === "string") {
+                policyTraceRef = { operationId: o.operationId, timestamp: o.timestamp };
+            }
+        }
+        let configMutationRef;
+        const cmr = args.configMutationRef;
+        if (cmr && typeof cmr === "object" && !Array.isArray(cmr)) {
+            const o = cmr;
+            if (typeof o.timestamp === "string" && typeof o.key === "string") {
+                configMutationRef = { timestamp: o.timestamp, key: o.key };
+            }
+        }
+        const result = await runReviewItem(ctx, {
+            taskId,
+            decision,
+            editedSummary,
+            policyTraceRef,
+            configMutationRef
+        }, actor);
+        return {
+            ok: result.ok,
+            code: result.code,
+            message: result.message,
+            data: "idempotent" in result && result.idempotent
+                ? { idempotent: true }
+                : undefined
+        };
     }
 };

package/dist/modules/approvals/review-runtime.d.ts

@@ -0,0 +1,24 @@
+import type { ModuleLifecycleContext } from "../../contracts/module-contract.js";
+export type ReviewItemArgs = {
+    taskId: string;
+    decision: "accept" | "decline" | "accept_edited";
+    editedSummary?: string;
+    policyTraceRef?: {
+        operationId: string;
+        timestamp: string;
+    };
+    configMutationRef?: {
+        timestamp: string;
+        key: string;
+    };
+};
+export declare function runReviewItem(ctx: ModuleLifecycleContext, args: ReviewItemArgs, actor: string): Promise<{
+    ok: true;
+    idempotent?: boolean;
+    code: string;
+    message: string;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+}>;

package/dist/modules/approvals/review-runtime.js

@@ -0,0 +1,146 @@
+import { appendLineageEvent } from "../../core/lineage-store.js";
+import { TaskStore } from "../task-engine/store.js";
+import { TransitionService } from "../task-engine/service.js";
+import { appendDecisionRecord, computeDecisionFingerprint, readDecisionFingerprints } from "./decisions-store.js";
+function taskStoreRelativePath(ctx) {
+    const tasks = ctx.effectiveConfig?.tasks;
+    if (!tasks || typeof tasks !== "object" || Array.isArray(tasks)) {
+        return undefined;
+    }
+    const p = tasks.storeRelativePath;
+    return typeof p === "string" && p.trim().length > 0 ? p.trim() : undefined;
+}
+function getEvidenceKey(task) {
+    const m = task.metadata;
+    const k = m && typeof m.evidenceKey === "string" ? m.evidenceKey : "";
+    return k || task.id;
+}
+export async function runReviewItem(ctx, args, actor) {
+    const taskId = typeof args.taskId === "string" ? args.taskId.trim() : "";
+    const decision = args.decision;
+    if (!taskId || !decision) {
+        return { ok: false, code: "invalid-args", message: "taskId and decision are required" };
+    }
+    if (decision === "accept_edited" && !(typeof args.editedSummary === "string" && args.editedSummary.trim())) {
+        return { ok: false, code: "invalid-args", message: "accept_edited requires non-empty editedSummary" };
+    }
+    const store = new TaskStore(ctx.workspacePath, taskStoreRelativePath(ctx));
+    await store.load();
+    const task = store.getTask(taskId);
+    if (!task) {
+        return { ok: false, code: "task-not-found", message: `Task '${taskId}' not found` };
+    }
+    if (task.type !== "improvement") {
+        return { ok: false, code: "invalid-task-type", message: `Task '${taskId}' is not type 'improvement'` };
+    }
+    const evidenceKey = getEvidenceKey(task);
+    const fingerprint = computeDecisionFingerprint(taskId, decision, evidenceKey, args.editedSummary);
+    const existing = await readDecisionFingerprints(ctx.workspacePath);
+    if (existing.has(fingerprint)) {
+        return {
+            ok: true,
+            idempotent: true,
+            code: "decision-idempotent",
+            message: "Decision already recorded (idempotent)"
+        };
+    }
+    const service = new TransitionService(store);
+    const run = async (action) => {
+        await service.runTransition({ taskId, action, actor });
+    };
+    try {
+        if (decision === "decline") {
+            if (task.status === "ready") {
+                await run("cancel");
+            }
+            else if (task.status === "in_progress") {
+                await run("decline");
+            }
+            else {
+                return {
+                    ok: false,
+                    code: "invalid-task-state",
+                    message: `Cannot decline from status '${task.status}'`
+                };
+            }
+        }
+        else {
+            if (task.status === "ready") {
+                await run("start");
+                await run("complete");
+            }
+            else if (task.status === "in_progress") {
+                await run("complete");
+            }
+            else {
+                return {
+                    ok: false,
+                    code: "invalid-task-state",
+                    message: `Cannot accept from status '${task.status}'`
+                };
+            }
+        }
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        return { ok: false, code: "transition-failed", message: msg };
+    }
+    const finalTask = store.getTask(taskId);
+    const finalStatus = finalTask?.status ?? "unknown";
+    await appendDecisionRecord(ctx.workspacePath, {
+        fingerprint,
+        taskId,
+        evidenceKey,
+        decisionVerb: decision,
+        actor,
+        editedSummary: args.editedSummary?.trim() || undefined,
+        policyTraceRef: args.policyTraceRef
+    });
+    await appendLineageEvent(ctx.workspacePath, {
+        eventType: "dec",
+        recommendationTaskId: taskId,
+        evidenceKey,
+        payload: {
+            recommendationTaskId: taskId,
+            evidenceKey,
+            decisionVerb: decision,
+            actor,
+            decisionFingerprint: fingerprint,
+            policyTraceRef: args.policyTraceRef,
+            configMutationRef: args.configMutationRef
+        }
+    });
+    if (decision !== "decline" && finalStatus === "completed") {
+        await appendLineageEvent(ctx.workspacePath, {
+            eventType: "app",
+            recommendationTaskId: taskId,
+            evidenceKey,
+            payload: {
+                recommendationTaskId: taskId,
+                evidenceKey,
+                decisionFingerprint: fingerprint,
+                finalTaskStatus: "completed"
+            }
+        });
+    }
+    if (args.policyTraceRef || args.configMutationRef) {
+        await appendLineageEvent(ctx.workspacePath, {
+            eventType: "corr",
+            recommendationTaskId: taskId,
+            evidenceKey,
+            payload: {
+                recommendationTaskId: taskId,
+                evidenceKey,
+                policyOperationId: args.policyTraceRef?.operationId,
+                policyTimestamp: args.policyTraceRef?.timestamp,
+                mutationRecordTimestamp: args.configMutationRef?.timestamp,
+                mutationKey: args.configMutationRef?.key
+            }
+        });
+    }
+    return {
+        ok: true,
+        code: "decision-recorded",
+        message: `Recorded ${decision} for ${taskId} (${finalStatus})`
+    };
+}

package/dist/modules/improvement/confidence.d.ts

@@ -0,0 +1,23 @@
+/**
+ * T202: Deterministic heuristic confidence (heuristic_1) — no ML.
+ * Callable from ingestion without coupling to file parsers.
+ */
+export type EvidenceKind = "transcript" | "git_diff" | "policy_deny" | "config_mutation" | "task_transition";
+/** Normalized numeric signals in [0,1]; undefined means not applicable. */
+export type ConfidenceSignals = {
+    transcriptFriction?: number;
+    diffImpact?: number;
+    policyDenial?: number;
+    mutationRejection?: number;
+    taskFriction?: number;
+};
+export type ConfidenceResult = {
+    score: number;
+    tier: "high" | "medium" | "low";
+    reasons: string[];
+};
+/** Admission threshold on score; inclusive. */
+export declare const HEURISTIC_1_ADMISSION_THRESHOLD = 0.35;
+export declare function computeHeuristicConfidence(kind: EvidenceKind, signals: ConfidenceSignals): ConfidenceResult;
+export declare function shouldAdmitRecommendation(result: ConfidenceResult): boolean;
+export declare function priorityForTier(tier: ConfidenceResult["tier"]): "P1" | "P2" | "P3";

package/dist/modules/improvement/confidence.js

@@ -0,0 +1,50 @@
+/**
+ * T202: Deterministic heuristic confidence (heuristic_1) — no ML.
+ * Callable from ingestion without coupling to file parsers.
+ */
+/** Admission threshold on score; inclusive. */
+export const HEURISTIC_1_ADMISSION_THRESHOLD = 0.35;
+export function computeHeuristicConfidence(kind, signals) {
+    const reasons = [];
+    const candidates = [];
+    if (signals.transcriptFriction !== undefined) {
+        candidates.push(signals.transcriptFriction);
+        reasons.push(`transcriptFriction=${signals.transcriptFriction.toFixed(3)}`);
+    }
+    if (signals.diffImpact !== undefined) {
+        candidates.push(signals.diffImpact);
+        reasons.push(`diffImpact=${signals.diffImpact.toFixed(3)}`);
+    }
+    if (signals.policyDenial !== undefined) {
+        candidates.push(signals.policyDenial);
+        reasons.push(`policyDenial=${signals.policyDenial.toFixed(3)}`);
+    }
+    if (signals.mutationRejection !== undefined) {
+        candidates.push(signals.mutationRejection);
+        reasons.push(`mutationRejection=${signals.mutationRejection.toFixed(3)}`);
+    }
+    if (signals.taskFriction !== undefined) {
+        candidates.push(signals.taskFriction);
+        reasons.push(`taskFriction=${signals.taskFriction.toFixed(3)}`);
+    }
+    if (candidates.length === 0) {
+        return { score: 0, tier: "low", reasons: [`no-signals:${kind}`] };
+    }
+    const score = Math.max(...candidates);
+    let tier = "low";
+    if (score >= 0.72)
+        tier = "high";
+    else if (score >= 0.5)
+        tier = "medium";
+    return { score, tier, reasons };
+}
+export function shouldAdmitRecommendation(result) {
+    return result.score >= HEURISTIC_1_ADMISSION_THRESHOLD;
+}
+export function priorityForTier(tier) {
+    if (tier === "high")
+        return "P1";
+    if (tier === "medium")
+        return "P2";
+    return "P3";
+}

package/dist/modules/improvement/generate-recommendations-runtime.d.ts

@@ -0,0 +1,13 @@
+import type { ModuleLifecycleContext } from "../../contracts/module-contract.js";
+export type GenerateRecommendationsArgs = {
+    /** Directory relative to workspace containing agent `*.jsonl` transcripts (default: agent-transcripts). */
+    transcriptsRoot?: string;
+    /** When both set with toTag, run git diff evidence between tags. */
+    fromTag?: string;
+    toTag?: string;
+};
+export declare function runGenerateRecommendations(ctx: ModuleLifecycleContext, args: GenerateRecommendationsArgs): Promise<{
+    created: string[];
+    skipped: number;
+    candidates: number;
+}>;

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

@@ -0,0 +1,92 @@
+import { TaskStore } from "../task-engine/store.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";
+import { priorityForTier } from "./confidence.js";
+function taskStoreRelativePath(ctx) {
+    const tasks = ctx.effectiveConfig?.tasks;
+    if (!tasks || typeof tasks !== "object" || Array.isArray(tasks)) {
+        return undefined;
+    }
+    const p = tasks.storeRelativePath;
+    return typeof p === "string" && p.trim().length > 0 ? p.trim() : undefined;
+}
+function hasEvidenceKey(tasks, key) {
+    return tasks.some((t) => {
+        const m = t.metadata;
+        if (!m || typeof m !== "object")
+            return false;
+        return m.evidenceKey === key;
+    });
+}
+export async function runGenerateRecommendations(ctx, args) {
+    const store = new TaskStore(ctx.workspacePath, taskStoreRelativePath(ctx));
+    await store.load();
+    const state = await loadImprovementState(ctx.workspacePath);
+    const transcriptsRoot = typeof args.transcriptsRoot === "string" && args.transcriptsRoot.trim()
+        ? args.transcriptsRoot.trim()
+        : "agent-transcripts";
+    const fromTag = typeof args.fromTag === "string" ? args.fromTag.trim() : undefined;
+    const toTag = typeof args.toTag === "string" ? args.toTag.trim() : undefined;
+    const candidates = [];
+    candidates.push(...(await ingestAgentTranscripts(ctx.workspacePath, transcriptsRoot, state)));
+    candidates.push(...(await ingestPolicyDenials(ctx.workspacePath, state)));
+    candidates.push(...(await ingestConfigMutations(ctx.workspacePath, state)));
+    candidates.push(...ingestTaskTransitionFriction(store.getTransitionLog(), state));
+    if (fromTag && toTag) {
+        const g = ingestGitDiffBetweenTags(ctx.workspacePath, fromTag, toTag);
+        if (g)
+            candidates.push(g);
+    }
+    const allTasks = store.getAllTasks();
+    const created = [];
+    let skipped = 0;
+    const now = new Date().toISOString();
+    for (const c of candidates) {
+        if (hasEvidenceKey(allTasks, c.evidenceKey)) {
+            skipped += 1;
+            continue;
+        }
+        const id = taskIdForEvidenceKey(c.evidenceKey);
+        if (store.getTask(id)) {
+            skipped += 1;
+            continue;
+        }
+        const task = {
+            id,
+            status: "ready",
+            type: "improvement",
+            title: c.title,
+            createdAt: now,
+            updatedAt: now,
+            priority: priorityForTier(c.confidence.tier),
+            metadata: {
+                evidenceKey: c.evidenceKey,
+                evidenceKind: c.evidenceKind,
+                confidence: c.confidence.score,
+                confidenceTier: c.confidence.tier,
+                confidenceReasons: c.confidence.reasons,
+                provenanceRefs: c.provenanceRefs
+            }
+        };
+        store.addTask(task);
+        allTasks.push(task);
+        created.push(id);
+        await appendLineageEvent(ctx.workspacePath, {
+            eventType: "rec",
+            recommendationTaskId: id,
+            evidenceKey: c.evidenceKey,
+            payload: {
+                recommendationTaskId: id,
+                evidenceKey: c.evidenceKey,
+                title: c.title,
+                confidence: c.confidence.score,
+                confidenceTier: c.confidence.tier,
+                provenanceRefs: c.provenanceRefs
+            }
+        });
+    }
+    await store.save();
+    await saveImprovementState(ctx.workspacePath, state);
+    return { created, skipped, candidates: candidates.length };
+}

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

@@ -0,0 +1,11 @@
+export declare const IMPROVEMENT_STATE_SCHEMA_VERSION: 1;
+export type ImprovementStateDocument = {
+    schemaVersion: typeof IMPROVEMENT_STATE_SCHEMA_VERSION;
+    policyTraceLineCursor: number;
+    mutationLineCursor: number;
+    transitionLogLengthCursor: number;
+    transcriptLineCursors: Record<string, number>;
+};
+export declare function emptyImprovementState(): ImprovementStateDocument;
+export declare function loadImprovementState(workspacePath: string): Promise<ImprovementStateDocument>;
+export declare function saveImprovementState(workspacePath: string, doc: ImprovementStateDocument): Promise<void>;

package/dist/modules/improvement/improvement-state.js

@@ -0,0 +1,42 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+export const IMPROVEMENT_STATE_SCHEMA_VERSION = 1;
+const DEFAULT_REL = ".workspace-kit/improvement/state.json";
+function statePath(workspacePath) {
+    return path.join(workspacePath, DEFAULT_REL);
+}
+export function emptyImprovementState() {
+    return {
+        schemaVersion: IMPROVEMENT_STATE_SCHEMA_VERSION,
+        policyTraceLineCursor: 0,
+        mutationLineCursor: 0,
+        transitionLogLengthCursor: 0,
+        transcriptLineCursors: {}
+    };
+}
+export async function loadImprovementState(workspacePath) {
+    const fp = statePath(workspacePath);
+    try {
+        const raw = await fs.readFile(fp, "utf8");
+        const doc = JSON.parse(raw);
+        if (doc.schemaVersion !== IMPROVEMENT_STATE_SCHEMA_VERSION) {
+            return emptyImprovementState();
+        }
+        return {
+            ...emptyImprovementState(),
+            ...doc,
+            transcriptLineCursors: doc.transcriptLineCursors ?? {}
+        };
+    }
+    catch (e) {
+        if (e.code === "ENOENT") {
+            return emptyImprovementState();
+        }
+        throw e;
+    }
+}
+export async function saveImprovementState(workspacePath, doc) {
+    const fp = statePath(workspacePath);
+    await fs.mkdir(path.dirname(fp), { recursive: true });
+    await fs.writeFile(fp, `${JSON.stringify(doc, null, 2)}\n`, "utf8");
+}

package/dist/modules/improvement/index.js

@@ -1,7 +1,9 @@
+import { queryLineageChain } from "../../core/lineage-store.js";
+import { runGenerateRecommendations } from "./generate-recommendations-runtime.js";
 export const improvementModule = {
     registration: {
         id: "improvement",
-        version: "0.1.0",
+        version: "0.5.0",
         contractVersion: "1",
         capabilities: ["improvement"],
         dependsOn: ["task-engine", "planning"],
@@ -23,8 +25,52 @@ export const improvementModule = {
                     name: "generate-recommendations",
                     file: "generate-recommendations.md",
                     description: "Produce evidence-backed workflow recommendations."
+                },
+                {
+                    name: "query-lineage",
+                    file: "query-lineage.md",
+                    description: "Reconstruct lineage chain for a recommendation task id."
                 }
             ]
         }
+    },
+    async onCommand(command, ctx) {
+        const args = command.args ?? {};
+        if (command.name === "generate-recommendations") {
+            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;
+            try {
+                const result = await runGenerateRecommendations(ctx, { transcriptsRoot, fromTag, toTag });
+                return {
+                    ok: true,
+                    code: "recommendations-generated",
+                    message: `Created ${result.created.length} improvement task(s); skipped ${result.skipped} duplicate(s)`,
+                    data: result
+                };
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                return { ok: false, code: "generate-failed", message: msg };
+            }
+        }
+        if (command.name === "query-lineage") {
+            const taskId = typeof args.taskId === "string" ? args.taskId.trim() : "";
+            if (!taskId) {
+                return { ok: false, code: "invalid-args", message: "query-lineage requires taskId" };
+            }
+            const chain = await queryLineageChain(ctx.workspacePath, taskId);
+            return {
+                ok: true,
+                code: "lineage-queried",
+                message: `${chain.events.length} lineage event(s) for ${taskId}`,
+                data: chain
+            };
+        }
+        return {
+            ok: false,
+            code: "unsupported-command",
+            message: `Improvement module does not support '${command.name}'`
+        };
     }
 };

package/dist/modules/improvement/ingest.d.ts

@@ -0,0 +1,18 @@
+import type { TransitionEvidence } from "../task-engine/types.js";
+import type { EvidenceKind, ConfidenceSignals } from "./confidence.js";
+import { computeHeuristicConfidence } from "./confidence.js";
+import type { ImprovementStateDocument } from "./improvement-state.js";
+export type IngestCandidate = {
+    evidenceKind: EvidenceKind;
+    evidenceKey: string;
+    title: string;
+    provenanceRefs: Record<string, string>;
+    signals: ConfidenceSignals;
+    confidence: ReturnType<typeof computeHeuristicConfidence>;
+};
+export declare function ingestAgentTranscripts(workspacePath: string, transcriptsRootRel: string, state: ImprovementStateDocument): Promise<IngestCandidate[]>;
+export declare function ingestGitDiffBetweenTags(workspacePath: string, fromTag: string, toTag: string): IngestCandidate | null;
+export declare function ingestPolicyDenials(workspacePath: string, state: ImprovementStateDocument): Promise<IngestCandidate[]>;
+export declare function ingestConfigMutations(workspacePath: string, state: ImprovementStateDocument): Promise<IngestCandidate[]>;
+export declare function ingestTaskTransitionFriction(transitionLog: TransitionEvidence[], state: ImprovementStateDocument): IngestCandidate[];
+export declare function taskIdForEvidenceKey(evidenceKey: string): string;

package/dist/modules/improvement/ingest.js

@@ -0,0 +1,223 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import crypto from "node:crypto";
+import { computeHeuristicConfidence, shouldAdmitRecommendation } from "./confidence.js";
+function sha256Hex(s) {
+    return crypto.createHash("sha256").update(s, "utf8").digest("hex");
+}
+function stableEvidenceKey(kind, parts) {
+    return `${kind}:${sha256Hex(parts.join("\0")).slice(0, 40)}`;
+}
+async function readJsonlLines(filePath) {
+    try {
+        const raw = await fs.readFile(filePath, "utf8");
+        return raw.split("\n").filter((l) => l.trim().length > 0);
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return [];
+        throw e;
+    }
+}
+async function globJsonlRecursive(dir, acc = []) {
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return acc;
+        throw e;
+    }
+    for (const ent of entries) {
+        const p = path.join(dir, ent.name);
+        if (ent.isDirectory()) {
+            await globJsonlRecursive(p, acc);
+        }
+        else if (ent.isFile() && ent.name.endsWith(".jsonl")) {
+            acc.push(p);
+        }
+    }
+    return acc;
+}
+const FRICTION = /\b(error|fail|broken|hosed|bug|crash|denied|invalid|exception)\b/i;
+function scoreTranscriptLine(line) {
+    if (!FRICTION.test(line))
+        return 0;
+    let s = 0.45;
+    if (/\b(always|again|still|never)\b/i.test(line))
+        s += 0.15;
+    return Math.min(1, s);
+}
+export async function ingestAgentTranscripts(workspacePath, transcriptsRootRel, state) {
+    const root = path.resolve(workspacePath, transcriptsRootRel);
+    const files = await globJsonlRecursive(root);
+    const out = [];
+    for (const abs of files.sort()) {
+        const rel = path.relative(workspacePath, abs);
+        const lines = await readJsonlLines(abs);
+        const start = state.transcriptLineCursors[rel] ?? 0;
+        const slice = lines.slice(start);
+        let maxScore = 0;
+        let sampleLine = "";
+        for (const line of slice) {
+            const sc = scoreTranscriptLine(line);
+            if (sc > maxScore) {
+                maxScore = sc;
+                sampleLine = line.slice(0, 200);
+            }
+        }
+        state.transcriptLineCursors[rel] = lines.length;
+        if (maxScore === 0)
+            continue;
+        const evidenceKey = stableEvidenceKey("transcript", [rel, String(start), String(lines.length)]);
+        const signals = { transcriptFriction: maxScore };
+        const confidence = computeHeuristicConfidence("transcript", signals);
+        if (!shouldAdmitRecommendation(confidence))
+            continue;
+        out.push({
+            evidenceKind: "transcript",
+            evidenceKey,
+            title: `Reduce friction hinted in transcript (${path.basename(rel)})`,
+            provenanceRefs: { transcriptPath: rel, sampleLine },
+            signals,
+            confidence
+        });
+    }
+    return out;
+}
+export function ingestGitDiffBetweenTags(workspacePath, fromTag, toTag) {
+    let names;
+    try {
+        names = execFileSync("git", ["-C", workspacePath, "diff", `${fromTag}..${toTag}`, "--name-only"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    }
+    catch {
+        return null;
+    }
+    const fileList = names.split("\n").filter(Boolean);
+    const churn = Math.min(1, fileList.length / 25);
+    const impact = 0.4 + churn * 0.55;
+    const evidenceKey = stableEvidenceKey("git_diff", [fromTag, toTag, fileList.slice(0, 30).join(",")]);
+    const signals = { diffImpact: impact };
+    const confidence = computeHeuristicConfidence("git_diff", signals);
+    if (!shouldAdmitRecommendation(confidence))
+        return null;
+    return {
+        evidenceKind: "git_diff",
+        evidenceKey,
+        title: `Review workflow impact of changes ${fromTag} → ${toTag} (${fileList.length} paths)`,
+        provenanceRefs: { fromTag, toTag, pathCount: String(fileList.length) },
+        signals,
+        confidence
+    };
+}
+export async function ingestPolicyDenials(workspacePath, state) {
+    const fp = path.join(workspacePath, ".workspace-kit/policy/traces.jsonl");
+    const lines = await readJsonlLines(fp);
+    const start = state.policyTraceLineCursor;
+    const slice = lines.slice(start);
+    state.policyTraceLineCursor = lines.length;
+    const out = [];
+    for (const line of slice) {
+        let rec;
+        try {
+            rec = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (rec.allowed !== false)
+            continue;
+        const op = typeof rec.operationId === "string" ? rec.operationId : "unknown";
+        const ts = typeof rec.timestamp === "string" ? rec.timestamp : "";
+        const evidenceKey = stableEvidenceKey("policy_deny", [op, ts, line.slice(0, 120)]);
+        const hasRationale = typeof rec.rationale === "string" && rec.rationale.length > 0;
+        const policyDenial = hasRationale ? 0.72 : 0.55;
+        const signals = { policyDenial };
+        const confidence = computeHeuristicConfidence("policy_deny", signals);
+        if (!shouldAdmitRecommendation(confidence))
+            continue;
+        out.push({
+            evidenceKind: "policy_deny",
+            evidenceKey,
+            title: `Soften or document policy friction for ${op}`,
+            provenanceRefs: {
+                operationId: op,
+                traceTimestamp: ts,
+                command: typeof rec.command === "string" ? rec.command : ""
+            },
+            signals,
+            confidence
+        });
+    }
+    return out;
+}
+export async function ingestConfigMutations(workspacePath, state) {
+    const fp = path.join(workspacePath, ".workspace-kit/config/mutations.jsonl");
+    const lines = await readJsonlLines(fp);
+    const start = state.mutationLineCursor;
+    const slice = lines.slice(start);
+    state.mutationLineCursor = lines.length;
+    const out = [];
+    for (const line of slice) {
+        let rec;
+        try {
+            rec = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (rec.ok === true)
+            continue;
+        const ts = typeof rec.timestamp === "string" ? rec.timestamp : "";
+        const k = typeof rec.key === "string" ? rec.key : "";
+        const evidenceKey = stableEvidenceKey("config_mutation", ["mutations.jsonl", ts, k, String(rec.code ?? "")]);
+        const mutationRejection = 0.62;
+        const signals = { mutationRejection };
+        const confidence = computeHeuristicConfidence("config_mutation", signals);
+        if (!shouldAdmitRecommendation(confidence))
+            continue;
+        out.push({
+            evidenceKind: "config_mutation",
+            evidenceKey,
+            title: `Improve config UX or validation for key ${k || "(unknown)"}`,
+            provenanceRefs: { mutationsFile: "mutations.jsonl", timestamp: ts, key: k },
+            signals,
+            confidence
+        });
+    }
+    return out;
+}
+export function ingestTaskTransitionFriction(transitionLog, state) {
+    const start = state.transitionLogLengthCursor;
+    const slice = transitionLog.slice(start);
+    state.transitionLogLengthCursor = transitionLog.length;
+    const counts = new Map();
+    for (const ev of slice) {
+        counts.set(ev.taskId, (counts.get(ev.taskId) ?? 0) + 1);
+    }
+    const out = [];
+    for (const [taskId, count] of counts) {
+        if (count < 4)
+            continue;
+        const taskFriction = Math.min(1, 0.38 + count * 0.08);
+        const evidenceKey = stableEvidenceKey("task_transition", [taskId, String(count)]);
+        const signals = { taskFriction };
+        const confidence = computeHeuristicConfidence("task_transition", signals);
+        if (!shouldAdmitRecommendation(confidence))
+            continue;
+        out.push({
+            evidenceKind: "task_transition",
+            evidenceKey,
+            title: `Stabilize transitions for task ${taskId} (high churn: ${count} events)`,
+            provenanceRefs: { taskId, transitionEventCount: String(count) },
+            signals,
+            confidence
+        });
+    }
+    return out;
+}
+export function taskIdForEvidenceKey(evidenceKey) {
+    return `imp-${sha256Hex(evidenceKey).slice(0, 14)}`;
+}

package/dist/modules/index.d.ts

@@ -2,6 +2,7 @@ export { approvalsModule } from "./approvals/index.js";
 export { documentationModule } from "./documentation/index.js";
 export type { DocumentationConflict, DocumentationGenerateOptions, DocumentationGenerateResult, DocumentationGenerationEvidence, DocumentationValidationIssue } from "./documentation/types.js";
 export { improvementModule } from "./improvement/index.js";
+export { computeHeuristicConfidence, HEURISTIC_1_ADMISSION_THRESHOLD, shouldAdmitRecommendation, type ConfidenceResult, type ConfidenceSignals, type EvidenceKind } from "./improvement/confidence.js";
 export { workspaceConfigModule } from "./workspace-config/index.js";
 export { planningModule } from "./planning/index.js";
 export { taskEngineModule, TaskStore, TransitionService, TaskEngineError, TransitionValidator, isTransitionAllowed, getTransitionAction, resolveTargetState, getAllowedTransitionsFrom, stateValidityGuard, dependencyCheckGuard, generateTasksMd, importTasksFromMarkdown, getNextActions } from "./task-engine/index.js";

package/dist/modules/index.js

@@ -1,6 +1,7 @@
 export { approvalsModule } from "./approvals/index.js";
 export { documentationModule } from "./documentation/index.js";
 export { improvementModule } from "./improvement/index.js";
+export { computeHeuristicConfidence, HEURISTIC_1_ADMISSION_THRESHOLD, shouldAdmitRecommendation } from "./improvement/confidence.js";
 export { workspaceConfigModule } from "./workspace-config/index.js";
 export { planningModule } from "./planning/index.js";
 export { taskEngineModule, TaskStore, TransitionService, TaskEngineError, TransitionValidator, isTransitionAllowed, getTransitionAction, resolveTargetState, getAllowedTransitionsFrom, stateValidityGuard, dependencyCheckGuard, generateTasksMd, importTasksFromMarkdown, getNextActions } from "./task-engine/index.js";

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

@@ -23,7 +23,7 @@ function taskStorePath(ctx) {
 export const taskEngineModule = {
     registration: {
         id: "task-engine",
-        version: "0.4.0",
+        version: "0.5.0",
         contractVersion: "1",
         capabilities: ["task-engine"],
         dependsOn: [],

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

@@ -13,6 +13,7 @@ const ALLOWED_TRANSITIONS = {
     "ready->blocked": { action: "block" },
     "ready->cancelled": { action: "cancel" },
     "in_progress->completed": { action: "complete" },
+    "in_progress->cancelled": { action: "decline" },
     "in_progress->blocked": { action: "block" },
     "in_progress->ready": { action: "pause" },
     "blocked->ready": { action: "unblock" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workflow-cannon/workspace-kit",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "private": false,
   "packageManager": "pnpm@10.0.0",
   "license": "MIT",
@@ -24,7 +24,13 @@
     "test": "pnpm run build && node --test test/**/*.test.mjs",
     "pack:dry-run": "pnpm run build && pnpm pack --pack-destination ./artifacts/workspace-kit-pack",
     "check-release-metadata": "node scripts/check-release-metadata.mjs",
-    "parity": "node scripts/run-parity.mjs"
+    "parity": "node scripts/run-parity.mjs",
+    "check-compatibility": "pnpm run build && node scripts/check-compatibility.mjs",
+    "check-planning-consistency": "node scripts/check-planning-doc-consistency.mjs",
+    "check-release-channel": "node scripts/check-release-channel.mjs",
+    "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"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",