akm-cli 0.9.0-beta.4 → 0.9.0-beta.40

package/dist/commands/improve/procedural.js

@@ -0,0 +1,418 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * #615 — procedural-compilation pass.
+ *
+ * An OPT-IN post-loop improve stage (default disabled via
+ * `IMPROVE_PROCESS_DEFAULTS.procedural`). It reads assets that carry an
+ * `orderedActions` frontmatter list (captured by #619), detects RECURRING
+ * successful action sequences across sessions (the SAME normalized ordered step
+ * list appearing >= `minRecurrence` times with a non-failure `outcomeData`), and
+ * emits ONE normal `type: workflow` proposal per recurring sequence through the
+ * existing proposal queue + quality gate.
+ *
+ * The ordered step list — NOT the LLM — is the source of truth. The bounded LLM
+ * call only NAMES the workflow and per-step titles/instructions; the parser
+ * rejects any output whose step count / order drifts from the deterministic
+ * sequence, and the assembled workflow markdown is re-parsed locally before it
+ * is ever queued. A justified null (the LLM determines the sequence is not a
+ * coherent procedure) is an acceptable outcome and produces no proposal.
+ */
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import proceduralSystemPrompt from "../../assets/prompts/procedural-system.md" with { type: "text" };
+import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { resolveStashDir } from "../../core/common.js";
+import { getDefaultLlmConfig, loadConfig } from "../../core/config/config.js";
+import { appendEvent } from "../../core/events.js";
+import { parseEmbeddedJsonResponse } from "../../core/parse.js";
+import { resolveStashStandards } from "../../core/standards/resolve-stash-standards.js";
+import { warn } from "../../core/warn.js";
+import { closeDatabase, getAllEntries, openExistingDatabase } from "../../indexer/db/db.js";
+import { resolveImproveProcessRunnerFromProfile, runnerIsLlm } from "../../integrations/agent/runner.js";
+import { chatCompletion } from "../../llm/client.js";
+import { parseWorkflow } from "../../workflows/parser.js";
+import { validateProposalFrontmatter } from "../proposal/validators/proposal-quality-validators.js";
+import { createProposal, isProposalSkipped } from "../proposal/validators/proposals.js";
+const PROCEDURAL_SYSTEM_PROMPT = proceduralSystemPrompt;
+const DEFAULT_MIN_RECURRENCE = 3;
+const DEFAULT_MAX_PROPOSALS_PER_RUN = 3;
+/** Failure-signal heuristic: an outcome matching this is NOT counted as success. */
+const FAILURE_SIGNAL = /\b(fail|failed|failure|error|errored|abort|aborted|rollback|reverted)\b/i;
+// ── Normalization + recurrence model (deterministic, no LLM) ────────────────────
+/** Normalize a single action string: trim, lowercase, collapse whitespace, strip trailing punctuation. */
+function normalizeStep(s) {
+    return s
+        .trim()
+        .toLowerCase()
+        .replace(/\s+/g, " ")
+        .replace(/[.;,:]+$/, "")
+        .trim();
+}
+/**
+ * Normalize an ordered action list: each step token-normalized (case /
+ * whitespace / trailing-punctuation insensitive), with empties dropped. The
+ * result is ORDER-SENSITIVE — reordered sequences normalize distinctly.
+ */
+export function normalizeSequence(actions) {
+    return actions.map(normalizeStep).filter((s) => s.length > 0);
+}
+/** A member counts toward recurrence only when its outcome is present, non-empty, and not a failure signal. */
+function isSuccessfulOutcome(outcome) {
+    if (!outcome)
+        return false;
+    const trimmed = outcome.trim();
+    if (!trimmed)
+        return false;
+    return !FAILURE_SIGNAL.test(trimmed);
+}
+/** Recover the ordered-action sequence + outcome from an asset's frontmatter (NOT a DB column). */
+function readOrderedSequence(entry) {
+    let data;
+    try {
+        const raw = fs.readFileSync(entry.filePath, "utf8");
+        data = parseFrontmatter(raw).data;
+    }
+    catch {
+        return null;
+    }
+    const rawActions = data.orderedActions;
+    if (!Array.isArray(rawActions))
+        return null;
+    const actions = rawActions.filter((a) => typeof a === "string");
+    if (actions.length === 0)
+        return null;
+    const outcome = typeof data.outcomeData === "string" ? data.outcomeData : undefined;
+    const ref = `${entry.entry.type}:${entry.entry.name}`;
+    return { actions, ...(outcome !== undefined ? { outcome } : {}), ref, entryKey: entry.entryKey };
+}
+/**
+ * Group entries by their normalized ordered sequence. Only successful members
+ * (non-failure outcome) count toward recurrence. Keep groups whose successful
+ * member count >= `minRecurrence`, sort deterministically (member-count desc
+ * then groupKey asc), and cap to `maxProposalsPerRun`. Exported for unit tests.
+ */
+export function buildSequenceClusters(entries, opts) {
+    const groups = new Map();
+    for (const entry of entries) {
+        const seq = readOrderedSequence(entry);
+        if (!seq)
+            continue;
+        const normalized = normalizeSequence(seq.actions);
+        if (normalized.length === 0)
+            continue;
+        if (!isSuccessfulOutcome(seq.outcome))
+            continue;
+        const groupKey = JSON.stringify(normalized);
+        const existing = groups.get(groupKey);
+        const member = { ref: seq.ref, entryKey: seq.entryKey, outcome: seq.outcome ?? "" };
+        if (existing) {
+            if (!existing.members.some((m) => m.entryKey === member.entryKey))
+                existing.members.push(member);
+        }
+        else {
+            groups.set(groupKey, { groupKey, normalized, members: [member] });
+        }
+    }
+    const clusters = [...groups.values()].filter((c) => c.members.length >= opts.minRecurrence);
+    clusters.sort((a, b) => b.members.length - a.members.length || a.groupKey.localeCompare(b.groupKey));
+    return clusters.slice(0, Math.max(0, opts.maxProposalsPerRun));
+}
+/**
+ * Stable workflow ref for a sequence cluster. The hash of the sorted member keys
+ * + the normalized sequence keeps the ref deterministic across runs, so
+ * re-detection maps to the same ref and the content-hash dedup in createProposal
+ * suppresses queue churn.
+ */
+export function deriveProceduralWorkflowRef(cluster) {
+    const slug = cluster.normalized
+        .slice(0, 3)
+        .join("-")
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+    const memberKey = cluster.members
+        .map((m) => m.entryKey)
+        .sort()
+        .join("|");
+    const hash = createHash("sha256")
+        .update(`${memberKey} ${JSON.stringify(cluster.normalized)}`, "utf8")
+        .digest("hex")
+        .slice(0, 8);
+    return `workflow:compiled/${slug || "sequence"}-${hash}`;
+}
+// ── Prompt + parse ──────────────────────────────────────────────────────────────
+/** Assemble the per-sequence user prompt fed to the procedural LLM. */
+export function buildProceduralPrompt(cluster, standardsContext = "") {
+    const lines = [
+        `A recurring successful action sequence observed across ${cluster.members.length} sessions.`,
+        "",
+    ];
+    if (standardsContext.trim()) {
+        lines.push("Standards to follow (the rulebook for this target):");
+        lines.push(standardsContext.trim());
+        lines.push("");
+    }
+    lines.push("Ordered actions (turn EACH into exactly one step, in this order):");
+    cluster.normalized.forEach((step, i) => {
+        lines.push(`${i + 1}. ${step}`);
+    });
+    lines.push("", "Sample successful outcomes:");
+    for (const m of cluster.members.slice(0, 5)) {
+        if (m.outcome)
+            lines.push(`- ${m.outcome}`);
+    }
+    lines.push("", `Return strict JSON with EXACTLY ${cluster.normalized.length} steps in the same order, or an explicit null.`);
+    return lines.join("\n");
+}
+/** Parse the raw LLM output into a workflow, or `null` for the justified-null path. */
+function parseProceduralWorkflow(raw, expectedSteps) {
+    if (raw === null)
+        return null;
+    const trimmed = raw.trim();
+    if (!trimmed || trimmed.toLowerCase() === "null")
+        return null;
+    const parsed = parseEmbeddedJsonResponse(trimmed);
+    if (parsed === undefined || parsed === null || typeof parsed !== "object")
+        return null;
+    const obj = parsed;
+    const title = typeof obj.title === "string" ? obj.title.trim() : "";
+    const description = typeof obj.description === "string" ? obj.description : "";
+    if (!title && !description)
+        return null;
+    if (!Array.isArray(obj.steps) || obj.steps.length !== expectedSteps)
+        return null;
+    const steps = [];
+    for (const rawStep of obj.steps) {
+        if (typeof rawStep !== "object" || rawStep === null)
+            return null;
+        const s = rawStep;
+        const stepTitle = typeof s.title === "string" ? s.title.trim() : "";
+        const instructions = typeof s.instructions === "string" ? s.instructions.trim() : "";
+        if (!stepTitle || !instructions)
+            return null;
+        const completionCriteria = Array.isArray(s.completionCriteria)
+            ? s.completionCriteria.filter((c) => typeof c === "string" && c.trim().length > 0)
+            : undefined;
+        steps.push({
+            title: stepTitle,
+            instructions,
+            ...(completionCriteria && completionCriteria.length > 0 ? { completionCriteria } : {}),
+        });
+    }
+    return { title: title || "Compiled Workflow", description, steps };
+}
+// ── Workflow markdown assembly ────────────────────────────────────────────────
+/** Convert a step title into a kebab-case step id. */
+function kebab(s) {
+    return (s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "") || "step");
+}
+/** Build the exact workflow markdown the parser accepts. */
+export function assembleWorkflowMarkdown(doc) {
+    const lines = [
+        "---",
+        `description: ${JSON.stringify(doc.description)}`,
+        "---",
+        "",
+        `# Workflow: ${doc.title}`,
+        "",
+    ];
+    const usedIds = new Set();
+    doc.steps.forEach((step, idx) => {
+        let id = kebab(step.title);
+        if (usedIds.has(id))
+            id = `${id}-${idx + 1}`;
+        usedIds.add(id);
+        lines.push(`## Step: ${step.title}`, `Step ID: ${id}`, "", "### Instructions", step.instructions, "");
+        if (step.completionCriteria && step.completionCriteria.length > 0) {
+            lines.push("### Completion Criteria");
+            for (const c of step.completionCriteria)
+                lines.push(`- ${c}`);
+            lines.push("");
+        }
+    });
+    return lines.join("\n");
+}
+// ── Production LLM seam ───────────────────────────────────────────────────────
+/**
+ * Resolve the production LLM seam from the active improve profile. Returns a
+ * `ProceduralLlmFn` that issues one bounded chatCompletion per call, or
+ * `undefined` when no LLM is configured (the pass then makes no calls).
+ */
+function resolveProductionLlmFn(config, signal) {
+    const proceduralProcess = config.profiles?.improve?.default?.processes?.procedural;
+    const runnerSpec = resolveImproveProcessRunnerFromProfile(proceduralProcess, config);
+    const llmConfig = runnerSpec && runnerIsLlm(runnerSpec) ? runnerSpec.connection : getDefaultLlmConfig(config);
+    if (!llmConfig)
+        return undefined;
+    return async (prompt) => {
+        const messages = [
+            { role: "system", content: PROCEDURAL_SYSTEM_PROMPT },
+            { role: "user", content: prompt },
+        ];
+        try {
+            return await chatCompletion(llmConfig, messages, { signal, enableThinking: false });
+        }
+        catch (e) {
+            warn(`[procedural] LLM call failed: ${String(e)}`);
+            return null;
+        }
+    };
+}
+// ── Main entry point ───────────────────────────────────────────────────────────
+export async function akmProcedural(opts) {
+    const startMs = Date.now();
+    const config = opts.config ?? loadConfig();
+    const stashDir = opts.stashDir ?? resolveStashDir();
+    const sourceRun = opts.sourceRun ?? `procedural-${startMs}`;
+    const eligibilitySource = opts.eligibilitySource ?? "procedural";
+    const minRecurrence = opts.minRecurrence ?? DEFAULT_MIN_RECURRENCE;
+    const maxProposalsPerRun = opts.maxProposalsPerRun ?? DEFAULT_MAX_PROPOSALS_PER_RUN;
+    const warnings = [];
+    const finish = (over) => ({
+        schemaVersion: 1,
+        ok: true,
+        sequencesScanned: 0,
+        clustersFormed: 0,
+        proposalsEmitted: 0,
+        nullsReturned: 0,
+        durationMs: Date.now() - startMs,
+        warnings,
+        ...over,
+    });
+    // Budget guard: an already-aborted signal short-circuits before any LLM call.
+    if (opts.signal?.aborted) {
+        return finish({ ok: false, warnings: [...warnings, "aborted-before-start"] });
+    }
+    // Load all entries from the index (orderedActions can ride any asset type).
+    let entries = [];
+    let db;
+    try {
+        db = openExistingDatabase();
+        entries = getAllEntries(db);
+    }
+    catch (e) {
+        warnings.push(`procedural: failed to open index — ${String(e)}`);
+        return finish({ ok: false });
+    }
+    finally {
+        if (db)
+            closeDatabase(db);
+    }
+    const clusters = buildSequenceClusters(entries, { minRecurrence, maxProposalsPerRun });
+    const sequencesScanned = entries.length;
+    let clustersFormed = 0;
+    let proposalsEmitted = 0;
+    let nullsReturned = 0;
+    if (clusters.length === 0) {
+        return finish({ sequencesScanned, clustersFormed: 0 });
+    }
+    const llmFn = opts.proceduralLlmFn ?? resolveProductionLlmFn(config, opts.signal);
+    if (!llmFn) {
+        warnings.push("procedural: no LLM configured — skipping");
+        return finish({ sequencesScanned, clustersFormed: 0 });
+    }
+    // Procedural output is a workflow (non-wiki) → stash authoring standards.
+    // Resolved ONCE per run and passed to each sequence prompt.
+    const standardsContext = resolveStashStandards(stashDir);
+    for (const cluster of clusters) {
+        if (opts.signal?.aborted) {
+            warnings.push("aborted-mid-run");
+            break;
+        }
+        clustersFormed += 1;
+        const workflowRef = deriveProceduralWorkflowRef(cluster);
+        const prompt = buildProceduralPrompt(cluster, standardsContext);
+        const raw = await llmFn(prompt);
+        const doc = parseProceduralWorkflow(raw, cluster.normalized.length);
+        if (!doc) {
+            nullsReturned += 1;
+            appendEvent({
+                eventType: "procedural_compiled",
+                ref: workflowRef,
+                metadata: {
+                    groupKey: cluster.groupKey,
+                    memberCount: cluster.members.length,
+                    outcome: "null_returned",
+                    sourceRun,
+                },
+            }, opts.ctx);
+            continue;
+        }
+        // Quality gate (always-run, never bypassed): the description must be present
+        // and non-truncated. Runs BEFORE createProposal.
+        const fmCheck = validateProposalFrontmatter({ description: doc.description });
+        if (!fmCheck.ok) {
+            appendEvent({
+                eventType: "procedural_compiled",
+                ref: workflowRef,
+                metadata: {
+                    groupKey: cluster.groupKey,
+                    memberCount: cluster.members.length,
+                    outcome: "quality_rejected",
+                    reason: fmCheck.reason,
+                    sourceRun,
+                },
+            }, opts.ctx);
+            continue;
+        }
+        // Assemble + locally validate the workflow markdown. Never queue an
+        // unparseable workflow.
+        const content = assembleWorkflowMarkdown(doc);
+        const parsed = parseWorkflow(content, { path: workflowRef });
+        if (!parsed.ok) {
+            appendEvent({
+                eventType: "procedural_compiled",
+                ref: workflowRef,
+                metadata: {
+                    groupKey: cluster.groupKey,
+                    memberCount: cluster.members.length,
+                    outcome: "invalid_workflow",
+                    reason: parsed.errors[0]?.message,
+                    sourceRun,
+                },
+            }, opts.ctx);
+            continue;
+        }
+        const proposalResult = createProposal(stashDir, {
+            ref: workflowRef,
+            source: "procedural",
+            sourceRun,
+            payload: { content, frontmatter: { description: doc.description } },
+            eligibilitySource,
+        }, opts.ctx);
+        if (isProposalSkipped(proposalResult)) {
+            appendEvent({
+                eventType: "procedural_compiled",
+                ref: workflowRef,
+                metadata: {
+                    groupKey: cluster.groupKey,
+                    memberCount: cluster.members.length,
+                    outcome: "skipped",
+                    skipReason: proposalResult.reason,
+                    sourceRun,
+                },
+            }, opts.ctx);
+            continue;
+        }
+        proposalsEmitted += 1;
+        appendEvent({
+            eventType: "procedural_compiled",
+            ref: workflowRef,
+            metadata: {
+                groupKey: cluster.groupKey,
+                memberCount: cluster.members.length,
+                outcome: "queued",
+                proposalId: proposalResult.id,
+                sourceRun,
+            },
+        }, opts.ctx);
+    }
+    return finish({ sequencesScanned, clustersFormed, proposalsEmitted, nullsReturned });
+}