@workflow-cannon/workspace-kit 0.4.0 → 0.5.0

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;