akm-cli 0.9.0-beta.53 → 0.9.0-beta.55

package/dist/commands/improve/dedup.js

@@ -40,9 +40,9 @@ import path from "node:path";
 import { parseAssetRef } from "../../core/asset/asset-ref.js";
 import { assembleAssetFromString, serializeFrontmatter } from "../../core/asset/asset-serialize.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
-import { getBodyEmbeddings, upsertBodyEmbeddings } from "../../core/state-db.js";
 import { warn } from "../../core/warn.js";
 import { cosineSimilarity, embedBatch, resolveEmbeddingModelId } from "../../llm/embedder.js";
+import { getBodyEmbeddings, upsertBodyEmbeddings } from "../../storage/repositories/embeddings-repository.js";
 /** Default strict cosine floor — high enough to skip distinct-but-related memories. */
 export const DEFAULT_DEDUP_COSINE_THRESHOLD = 0.97;
 /**

package/dist/commands/improve/distill/content-repair.js

@@ -0,0 +1,202 @@
+// 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/.
+/**
+ * Pure content-repair + quality-validation stages for `akm distill`.
+ *
+ * Extracted verbatim from the inline body of `akmDistill` so each normalization
+ * pass is an independently testable unit. Every function is a pure transform of
+ * `(content, inputRef) → content | findings` with no I/O — logic is
+ * byte-identical to the pre-extraction inline code. The lesson-path guard
+ * (`effectiveProposalKind !== "knowledge"`) stays in the caller; these helpers
+ * assume the lesson path.
+ */
+import { assembleAssetFromString } from "../../../core/asset/asset-serialize.js";
+import { parseFrontmatter } from "../../../core/asset/frontmatter.js";
+import { repairTruncatedDescription } from "../../../core/text-truncation.js";
+import { detectDoubleFrontmatter, isValidDescription, isValidWhenToUse, } from "../../proposal/validators/proposal-quality-validators.js";
+/**
+ * Auto-repair missing frontmatter fields before hard-failing. Small models
+ * frequently produce a good lesson body but omit the YAML header entirely.
+ * Rather than discarding valid content, we extract description/when_to_use
+ * from the body and prepend the required frontmatter block.
+ *
+ * IMPORTANT: We do NOT synthesise placeholder strings here. If the body
+ * does not contain text that passes the post-LLM validators
+ * (`isValidDescription` / `isValidWhenToUse`), we leave the field missing
+ * and let the lesson lint reject the proposal as `validation_failed`.
+ * Emitting placeholders like `"Lesson distilled from <ref>"` or
+ * `"When working with <slug>"` is what produced the systematic broken
+ * proposals observed across 323 archived rejections.
+ */
+export function autoRepairLessonFrontmatter(content, inputRef) {
+    const parsed = parseFrontmatter(content);
+    const fm = (parsed.data ?? {});
+    const missingDesc = typeof fm.description !== "string" || !fm.description.trim();
+    const missingWtu = typeof fm.when_to_use !== "string" || !fm.when_to_use.trim();
+    if (!missingDesc && !missingWtu)
+        return content;
+    const body = parsed.content.trim();
+    // Strip markdown formatting tokens from a line so extracted text is clean.
+    const stripMd = (l) => l
+        .replace(/\*\*([^*]+)\*\*/g, "$1")
+        .replace(/\*([^*]+)\*/g, "$1")
+        .replace(/`([^`]+)`/g, "$1")
+        .replace(/^[#*\->_]+\s*/, "")
+        .replace(/:\s*$/, "")
+        .trim();
+    // Skip lines that look like YAML field assignments (key: value) or frontmatter delimiters.
+    // These appear when the LLM leaks frontmatter content into the body, causing
+    // auto-repair to produce description: "description: Key Takeaways".
+    const isYamlLike = (l) => /^---/.test(l) || /^[a-z_]+:\s/i.test(l);
+    const bodyLines = body.split("\n").map(stripMd);
+    // Extract description: first body line that BOTH looks like prose AND
+    // passes isValidDescription. If nothing qualifies, leave the field
+    // missing — the lint pass will reject the proposal cleanly.
+    let descLine;
+    for (const l of bodyLines) {
+        if (isYamlLike(l))
+            continue;
+        if (l.length <= 10 || l.length >= 400)
+            continue;
+        if (isValidDescription(l, inputRef).ok) {
+            descLine = l;
+            break;
+        }
+    }
+    // Extract when_to_use: a line starting with "When" / "Use when" / "Apply when"
+    // that ALSO passes isValidWhenToUse (rejects circular fallbacks).
+    let wtuLine;
+    for (const l of bodyLines) {
+        if (!/^(when |use when|apply when)/i.test(l))
+            continue;
+        if (l.length >= 400)
+            continue;
+        if (isValidWhenToUse(l, inputRef).ok) {
+            wtuLine = l;
+            break;
+        }
+    }
+    const repairedFm = {
+        ...fm,
+        ...(missingDesc && descLine ? { description: descLine } : {}),
+        ...(missingWtu && wtuLine ? { when_to_use: wtuLine } : {}),
+    };
+    const fmLines = Object.entries(repairedFm)
+        .map(([k, v]) => `${k}: ${JSON.stringify(v)}`)
+        .join("\n");
+    // Only rewrite content if we actually have at least one field to write.
+    // Otherwise leave the original content for the lint pass to reject.
+    if (Object.keys(repairedFm).length > 0) {
+        return assembleAssetFromString(fmLines, body);
+    }
+    return content;
+}
+/**
+ * Description ↔ when_to_use auto-swap normalization (recover ~93% of
+ * qwen-9b's `^when\b/i` rejections at zero LLM cost). When the LLM emits
+ * a conditional-framed description ("When X happens, do Y") and the
+ * when_to_use field looks like a declarative description (or is empty),
+ * the two fields are mis-fielded — exactly what `isValidDescription`'s
+ * error message says ("that pattern belongs in when_to_use"). We swap
+ * them and revalidate; the swap is committed only if BOTH fields pass
+ * their respective validators afterwards. If revalidation still fails,
+ * we fall through returning the original content (swapped: 0).
+ */
+export function autoSwapDescriptionWhenToUse(content, inputRef) {
+    const parsedSwap = parseFrontmatter(content);
+    const fmSwap = (parsedSwap.data ?? {});
+    const descRaw = typeof fmSwap.description === "string" ? fmSwap.description.trim() : "";
+    const wtuRaw = typeof fmSwap.when_to_use === "string" ? fmSwap.when_to_use.trim() : "";
+    const descStartsConditional = /^(when|if)\b/i.test(descRaw);
+    const wtuStartsConditional = /^(when|if)\b/i.test(wtuRaw);
+    if (descStartsConditional && !wtuStartsConditional && wtuRaw.length > 0) {
+        // Try the swap and revalidate. The when_to_use validator requires the
+        // value not match `/^when working with\b/i` (the circular fallback) —
+        // a real description rarely does, so this usually passes.
+        const swappedDescCheck = isValidDescription(wtuRaw, inputRef);
+        const swappedWtuCheck = isValidWhenToUse(descRaw, inputRef);
+        if (swappedDescCheck.ok && swappedWtuCheck.ok) {
+            const swappedFm = {
+                ...fmSwap,
+                description: wtuRaw,
+                when_to_use: descRaw,
+            };
+            const swappedFmLines = Object.entries(swappedFm)
+                .map(([k, v]) => `${k}: ${JSON.stringify(v)}`)
+                .join("\n");
+            return { content: assembleAssetFromString(swappedFmLines, parsedSwap.content), swapped: 1 };
+        }
+    }
+    return { content, swapped: 0 };
+}
+/**
+ * Post-generation truncation repair (#556): if the LLM sliced the
+ * description mid-sentence, deterministically complete it from its own text
+ * / the lesson body BEFORE the lint + quality validators run. No-op
+ * (byte-identical) for already-complete descriptions, so this never alters
+ * a valid proposal.
+ */
+export function repairLessonDescriptionTruncation(content) {
+    const parsedRepair = parseFrontmatter(content);
+    const fmRepair = (parsedRepair.data ?? {});
+    const descRepairRaw = typeof fmRepair.description === "string" ? fmRepair.description : "";
+    if (!descRepairRaw)
+        return content;
+    const repaired = repairTruncatedDescription(descRepairRaw, parsedRepair.content);
+    if (repaired === descRepairRaw)
+        return content;
+    const repairedFmLines = Object.entries({ ...fmRepair, description: repaired })
+        .map(([k, v]) => `${k}: ${JSON.stringify(v)}`)
+        .join("\n");
+    return assembleAssetFromString(repairedFmLines, parsedRepair.content);
+}
+/**
+ * Additional quality validators that run only on lessons whose lesson-lint
+ * pass was clean. lesson-lint checks "field is present and non-empty"; these
+ * reject the systematic failure modes observed across 323 archived rejected
+ * proposals:
+ *   - description is a body fragment, section heading, or placeholder
+ *   - when_to_use is the circular "When working with <ref>" fallback
+ *   - description == when_to_use (LLM duplicated a single sentence)
+ *   - body contains a second pseudo-frontmatter block
+ */
+export function collectLessonQualityFindings(content, inputRef) {
+    const findings = [];
+    const parsedQC = parseFrontmatter(content);
+    const fmQC = (parsedQC.data ?? {});
+    const descCheck = isValidDescription(fmQC.description, inputRef);
+    if (!descCheck.ok) {
+        findings.push({
+            kind: "invalid-description",
+            field: "description",
+            message: `Distilled lesson for ${inputRef} has an invalid description: ${descCheck.reason}.`,
+        });
+    }
+    const wtuCheck = isValidWhenToUse(fmQC.when_to_use, inputRef);
+    if (!wtuCheck.ok) {
+        findings.push({
+            kind: "invalid-when_to_use",
+            field: "when_to_use",
+            message: `Distilled lesson for ${inputRef} has an invalid when_to_use: ${wtuCheck.reason}.`,
+        });
+    }
+    // description and when_to_use must say different things.
+    if (descCheck.ok &&
+        wtuCheck.ok &&
+        typeof fmQC.description === "string" &&
+        typeof fmQC.when_to_use === "string" &&
+        fmQC.description.trim().toLowerCase() === fmQC.when_to_use.trim().toLowerCase()) {
+        findings.push({
+            kind: "description-equals-when_to_use",
+            field: "description",
+            message: `Distilled lesson for ${inputRef} has identical description and when_to_use.`,
+        });
+    }
+    // Double-frontmatter / pseudo-frontmatter pollution in the body.
+    const dfm = detectDoubleFrontmatter(content);
+    if (dfm) {
+        findings.push({ kind: dfm.kind, field: "body", message: `Distilled lesson for ${inputRef}: ${dfm.message}` });
+    }
+    return findings;
+}

package/dist/commands/improve/distill/promote-memory.js

@@ -0,0 +1,228 @@
+// 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/.
+/**
+ * Memory→knowledge promotion branch for `akm distill`.
+ *
+ * This is an entire second command that used to be inlined inside `akmDistill`:
+ * when a `memory:*` ref is reinforced enough (per the deterministic stability
+ * heuristic in `distill-promotion-policy`), distill graduates it into a
+ * `knowledge:*` proposal instead of a lesson. The branch owns its own LLM
+ * contradiction-merge (mem0 ADD/UPDATE/NOOP), quality gate, proposal creation,
+ * and `distill_invoked` event emit.
+ *
+ * {@link promoteMemoryToKnowledge} returns the finished {@link AkmDistillResult}
+ * when the branch fired, or `null` when the ref is not a promotion candidate —
+ * in which case the caller falls through to the ordinary lesson/knowledge LLM
+ * path. Logic is byte-identical to the pre-extraction inline code.
+ */
+import fs from "node:fs";
+import { parseFrontmatter } from "../../../core/asset/frontmatter.js";
+import { getDefaultLlmConfig } from "../../../core/config/config.js";
+import { ConfigError } from "../../../core/errors.js";
+import { appendEvent } from "../../../core/events.js";
+import { parseEmbeddedJsonResponse } from "../../../llm/client.js";
+import { isLlmFeatureEnabled } from "../../../llm/feature-gate.js";
+import { createProposal, isProposalSkipped } from "../../proposal/repository.js";
+import { assessMemoryKnowledgePromotionCandidate } from "../distill-promotion-policy.js";
+import { persistOutputEncodingSalience, runLessonQualityJudge, writeQualityRejection } from "./quality-gate.js";
+/**
+ * Run the memory→knowledge promotion branch. Returns the finished distill
+ * result when promotion fired (all paths terminal), or `null` when the ref is
+ * not a promotion candidate and the caller should continue to the ordinary
+ * lesson/knowledge distillation path.
+ */
+export async function promoteMemoryToKnowledge(ctx) {
+    const { targetKind, inputRef, assetContent, config, chat, stash, lookup, fetchSimilarLessonsFn, existingRefVocabulary, outcomeWeightEnabled, eligMeta, exclusionSetSize, filteredFeedbackCount, feedbackFullyFiltered, } = ctx;
+    const promotion = targetKind === "lesson"
+        ? null
+        : assessMemoryKnowledgePromotionCandidate({
+            inputRef,
+            assetContent,
+            feedbackEvents: ctx.filteredEvents.map((event) => ({
+                ...(event.metadata !== undefined ? { metadata: event.metadata } : {}),
+            })),
+        });
+    if (!(promotion?.promote && promotion.content && (targetKind === "knowledge" || targetKind === "auto"))) {
+        return null;
+    }
+    // D-1 / #369: When the destination knowledge file already exists, route
+    // through the LLM for contradiction resolution instead of silently
+    // overwriting. Follows mem0 ADD/UPDATE/DELETE/NOOP pattern (arXiv:2504.19413 §3.2)
+    // and A-MEM dynamic linking (arXiv:2502.12110).
+    let resolvedPromotionContent = promotion.content;
+    const existingKnowledgePath = await lookup(promotion.knowledgeRef);
+    const existingKnowledgeContent = existingKnowledgePath && fs.existsSync(existingKnowledgePath)
+        ? (() => {
+            try {
+                return fs.readFileSync(existingKnowledgePath, "utf8");
+            }
+            catch {
+                return null;
+            }
+        })()
+        : null;
+    if (existingKnowledgeContent && config && getDefaultLlmConfig(config)) {
+        // Existing content found: call LLM for contradiction-resolution merge.
+        const mergePrompt = [
+            "You are merging two versions of a knowledge document.",
+            "Existing content is already committed; new content comes from a memory distillation run.",
+            "Choose one of: ADD (combine both), UPDATE (replace existing with new), NOOP (keep existing unchanged).",
+            'Return ONLY valid JSON: {"action": "ADD"|"UPDATE"|"NOOP", "content": "<merged markdown if ADD/UPDATE, empty string if NOOP>"}',
+            "",
+            "## Existing knowledge content",
+            "```",
+            existingKnowledgeContent.slice(0, 3000),
+            "```",
+            "",
+            "## New content from distillation",
+            "```",
+            promotion.content.slice(0, 3000),
+            "```",
+        ].join("\n");
+        try {
+            const mergeLlm = getDefaultLlmConfig(config);
+            if (!mergeLlm) {
+                throw new ConfigError("LLM is not configured for distillation merge.", "LLM_NOT_CONFIGURED");
+            }
+            const mergeResponse = await chat(mergeLlm, [
+                { role: "system", content: "Return only valid JSON. No prose." },
+                { role: "user", content: mergePrompt },
+            ]);
+            const mergeResult = parseEmbeddedJsonResponse(mergeResponse);
+            if (mergeResult?.action === "NOOP") {
+                // Existing content is authoritative — no update needed.
+                appendEvent({
+                    eventType: "distill_invoked",
+                    ref: inputRef,
+                    metadata: {
+                        outcome: "skipped",
+                        lessonRef: promotion.knowledgeRef,
+                        message: "D-1: LLM resolved destination conflict as NOOP — existing content kept",
+                        ...eligMeta,
+                    },
+                });
+                return {
+                    schemaVersion: 1,
+                    ok: true,
+                    outcome: "skipped",
+                    inputRef,
+                    lessonRef: promotion.knowledgeRef,
+                    message: "Existing knowledge content unchanged (contradiction resolution: NOOP)",
+                };
+            }
+            if (mergeResult?.action && (mergeResult.action === "ADD" || mergeResult.action === "UPDATE")) {
+                if (mergeResult.content?.trim()) {
+                    resolvedPromotionContent = mergeResult.content;
+                }
+            }
+        }
+        catch {
+            // LLM merge failed — fall through with the original promotion content.
+            // The reviewer will see both versions in the proposal diff.
+        }
+    }
+    else if (existingKnowledgeContent && config && !getDefaultLlmConfig(config)) {
+        // No LLM configured: include existing content as context in the proposal
+        // so the reviewer can do the contradiction resolution manually.
+        resolvedPromotionContent = [
+            promotion.content,
+            "",
+            "---",
+            "<!-- D-1 / #369: Existing knowledge content is shown below for reviewer reference. -->",
+            "<!-- Review: decide whether to ADD (merge), UPDATE (replace), or NOOP (keep existing). -->",
+            "",
+            "## Existing content (for reviewer reference)",
+            "",
+            existingKnowledgeContent,
+        ].join("\n");
+    }
+    // Apply quality gate to fast-path knowledge promotion (Risk 4 fix).
+    // D-5 / #388: Three-band system — review_needed band queues to proposal
+    // queue with review_needed outcome rather than auto-rejecting.
+    let knowledgeJudgeConfidence;
+    if (isLlmFeatureEnabled(config, "lesson_quality_gate")) {
+        // D-4 / #390: retrieve top-3 similar lessons for dedup check in judge.
+        const similarLessons = await fetchSimilarLessonsFn(resolvedPromotionContent.slice(0, 500), 3);
+        const judgeResult = await runLessonQualityJudge(config, resolvedPromotionContent, assetContent ?? "", chat, similarLessons.length > 0 ? similarLessons : undefined);
+        if (!judgeResult.pass) {
+            if (judgeResult.reviewNeeded) {
+                // Uncertainty band (2.5–3.5): queue as review_needed instead of rejecting.
+                return writeQualityRejection(stash, inputRef, promotion.knowledgeRef, resolvedPromotionContent, judgeResult.score, judgeResult.reason, { reviewNeeded: true }, ctx.eligibilitySource);
+            }
+            return writeQualityRejection(stash, inputRef, promotion.knowledgeRef, resolvedPromotionContent, judgeResult.score, judgeResult.reason, {}, ctx.eligibilitySource);
+        }
+        // Normalize 1-5 judge score to [0, 1]. Score of -1 means pass-through
+        // (no LLM / timeout / parse failure) — leave confidence undefined so
+        // the auto-accept gate treats the proposal as unscored and skips it.
+        if (judgeResult.score > 0)
+            knowledgeJudgeConfidence = judgeResult.score / 5;
+    }
+    const knowledgeParsed = parseFrontmatter(resolvedPromotionContent);
+    const proposalResult = createProposal(stash, {
+        ref: promotion.knowledgeRef,
+        source: "distill",
+        ...(ctx.sourceRun !== undefined ? { sourceRun: ctx.sourceRun } : {}),
+        payload: {
+            content: resolvedPromotionContent,
+            ...(Object.keys(knowledgeParsed.data).length > 0 ? { frontmatter: knowledgeParsed.data } : {}),
+        },
+        ...(knowledgeJudgeConfidence !== undefined ? { confidence: knowledgeJudgeConfidence } : {}),
+        // Attribution tagging: persist the eligibility lane on the proposal.
+        ...(ctx.eligibilitySource ? { eligibilitySource: ctx.eligibilitySource } : {}),
+    }, ctx.proposalsCtx);
+    if (isProposalSkipped(proposalResult)) {
+        appendEvent({
+            eventType: "distill_invoked",
+            ref: inputRef,
+            metadata: {
+                outcome: "skipped",
+                lessonRef: promotion.knowledgeRef,
+                message: proposalResult.message,
+                skipReason: proposalResult.reason,
+                ...eligMeta,
+            },
+        });
+        return {
+            schemaVersion: 1,
+            ok: true,
+            outcome: "skipped",
+            inputRef,
+            lessonRef: promotion.knowledgeRef,
+            message: proposalResult.message,
+        };
+    }
+    const proposal = proposalResult;
+    // G4: content-score the distilled OUTPUT so it carries a real encoding
+    // salience (encoding_source='content') from creation.
+    persistOutputEncodingSalience(promotion.knowledgeRef, resolvedPromotionContent, existingRefVocabulary, outcomeWeightEnabled);
+    appendEvent({
+        eventType: "distill_invoked",
+        ref: inputRef,
+        metadata: {
+            outcome: "queued",
+            lessonRef: promotion.knowledgeRef,
+            proposalRef: promotion.knowledgeRef,
+            proposalKind: "knowledge",
+            proposalId: proposal.id,
+            // R3: judge verdicts are longitudinally queryable, not just a one-shot
+            // proposal.confidence write (normalized 1–5 score / 5).
+            ...(knowledgeJudgeConfidence !== undefined ? { judgeConfidence: knowledgeJudgeConfidence } : {}),
+            ...(ctx.sourceRun !== undefined ? { sourceRun: ctx.sourceRun } : {}),
+            ...(exclusionSetSize > 0 ? { filteredFeedbackCount } : {}),
+            ...eligMeta,
+        },
+    });
+    return {
+        schemaVersion: 1,
+        ok: true,
+        outcome: "queued",
+        inputRef,
+        lessonRef: promotion.knowledgeRef,
+        proposalRef: promotion.knowledgeRef,
+        proposalKind: "knowledge",
+        proposalId: proposal.id,
+        proposal,
+        ...(exclusionSetSize > 0 ? { filteredFeedbackCount, feedbackFullyFiltered } : {}),
+    };
+}

package/dist/commands/improve/distill/quality-gate.js

@@ -0,0 +1,233 @@
+// 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/.
+/**
+ * Distill quality-gate cluster — LLM-as-judge, quality-rejection envelope
+ * writer, and output-salience persistence. Extracted verbatim from
+ * `distill.ts` so the main `akmDistill` orchestrator and the memory→knowledge
+ * promotion branch (`promote-memory.ts`) can share the same helpers without a
+ * circular import. Logic is byte-identical to the pre-extraction inline code.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { parseAssetRef } from "../../../core/asset/asset-ref.js";
+import { timestampForFilename } from "../../../core/common.js";
+import { getDefaultLlmConfig } from "../../../core/config/config.js";
+import { appendEvent } from "../../../core/events.js";
+import { withStateDb } from "../../../core/state-db.js";
+import { parseEmbeddedJsonResponse } from "../../../llm/client.js";
+import { akmSearch } from "../../read/search.js";
+import { scoreEncodingSalience } from "../encoding-salience.js";
+import { computeSalience, upsertAssetSalience } from "../salience.js";
+// ── D-4 / #390: Top-3 similar lessons retrieval ──────────────────────────────
+/**
+ * Default implementation: use akmSearch to find top-N similar lesson assets.
+ * Returns empty array when search fails or returns no results.
+ * Requires embedding configured for semantic similarity; degrades gracefully.
+ */
+export async function fetchTopSimilarLessons(query, n, _stashDir) {
+    try {
+        const result = await akmSearch({
+            query,
+            type: "lesson",
+            limit: n,
+            skipLogging: true,
+            eventSource: "improve",
+        });
+        const hits = result?.hits ?? [];
+        return hits
+            .filter((h) => "path" in h && typeof h.path === "string")
+            .slice(0, n)
+            .map((h) => {
+            let content = "";
+            try {
+                if (h.path && fs.existsSync(h.path)) {
+                    content = fs.readFileSync(h.path, "utf8");
+                }
+            }
+            catch {
+                /* best-effort */
+            }
+            return { ref: h.ref, content };
+        });
+    }
+    catch {
+        return [];
+    }
+}
+// ── LLM-as-judge quality gate (P2-B) ────────────────────────────────────────
+/**
+ * D-4 / #390: Build the LLM-as-judge prompt.
+ *
+ * When similarLessons are provided (top-3 by embedding similarity), they are
+ * included in the context so the judge can lower the score for near-duplicates.
+ * Voyager arXiv:2305.16291 — skill library admission requires similarity check
+ * against the existing library. A-MEM arXiv:2502.12110 — new notes are checked
+ * against existing notes before linking.
+ */
+export function buildJudgePrompt(lessonContent, sourceContent, similarLessons) {
+    const lines = [
+        "You are evaluating a proposed lesson asset for an akm knowledge base.",
+        "",
+        "Score this lesson on each criterion from 1 (poor) to 5 (excellent):",
+        "1. NOVELTY: Does the lesson add information not already present in the source asset?",
+        "2. ACTIONABILITY: Can an agent follow this lesson without additional context?",
+        "3. NON-REDUNDANCY: Is this lesson meaningfully different from what the source already says?",
+        "",
+        "Source asset content:",
+        "```",
+        sourceContent.slice(0, 2000),
+        "```",
+    ];
+    if (similarLessons && similarLessons.length > 0) {
+        lines.push("");
+        lines.push("Existing similar lessons (top-3 by similarity). Rate lower if the proposed lesson is substantially similar to any of these:");
+        for (const sl of similarLessons) {
+            lines.push(`\nExisting lesson ref: ${sl.ref}`);
+            lines.push("```");
+            lines.push(sl.content.slice(0, 500));
+            lines.push("```");
+        }
+    }
+    lines.push("");
+    lines.push("Proposed lesson content:");
+    lines.push("```");
+    lines.push(lessonContent.slice(0, 1000));
+    lines.push("```");
+    lines.push("");
+    lines.push('Return ONLY valid JSON, no prose: {"score": <average score 1-5 as float>, "reason": "<one sentence>"}');
+    return lines.join("\n");
+}
+/**
+ * Run the LLM-as-judge quality gate on a proposal's content.
+ *
+ * Exported so reflect.ts can apply the same gate to reflect proposals (R-5 / #374).
+ * Gated by the flag name `lesson_quality_gate` (or its alias
+ * `proposal_quality_gate`) via {@link isLlmFeatureEnabled} — which reads
+ * `profiles.improve.default.processes.distill.qualityGate.enabled` (and the
+ * corresponding `.reflect.qualityGate.enabled` for proposals).
+ *
+ * Fail-open: returns `pass: true` on timeout, parse failure, or missing LLM.
+ */
+export async function runLessonQualityJudge(config, lessonContent, sourceContent, chat, 
+/** D-4 / #390: top-3 similar existing lessons for dedup check. */
+similarLessons) {
+    const llmConfig = getDefaultLlmConfig(config);
+    if (!llmConfig) {
+        return { pass: true, score: -1, reason: "no LLM configured — passing through" };
+    }
+    const judgeLlmConfig = llmConfig.judgeModel ? { ...llmConfig, model: llmConfig.judgeModel } : llmConfig;
+    const JUDGE_TIMEOUT_MS = 8_000;
+    try {
+        const raw = await Promise.race([
+            chat(judgeLlmConfig, [
+                { role: "system", content: "Return only valid JSON. No prose." },
+                { role: "user", content: buildJudgePrompt(lessonContent, sourceContent, similarLessons) },
+            ]),
+            new Promise((_, reject) => setTimeout(() => reject(new Error("judge timeout")), JUDGE_TIMEOUT_MS)),
+        ]);
+        const parsed = parseEmbeddedJsonResponse(raw);
+        if (!parsed || typeof parsed.score !== "number") {
+            return { pass: true, score: -1, reason: "judge parse failed — passing through" };
+        }
+        // D-5 / #388: Three-band system (MT-Bench arXiv:2306.05685 — ~±0.5 judge variance).
+        //   >= 3.5: auto-queue as pending (pass: true)
+        //   2.5–3.5: review-needed band — uncertain, escalate to human (reviewNeeded: true)
+        //   < 2.5: auto-reject (pass: false)
+        const score = parsed.score;
+        const reason = parsed.reason ?? "";
+        if (score >= 3.5) {
+            return { pass: true, score, reason };
+        }
+        if (score >= 2.5) {
+            // Uncertainty band: treat as failed for auto-queuing but flag for review.
+            return { pass: false, score, reason, reviewNeeded: true };
+        }
+        return { pass: false, score, reason };
+    }
+    catch {
+        return { pass: true, score: -1, reason: "judge failed — passing through" };
+    }
+}
+// ── Quality-rejection helper ─────────────────────────────────────────────────
+/**
+ * Write a rejected lesson to `.akm/distill-rejected/`, append a `distill_invoked`
+ * quality-rejected event, and return the `quality_rejected` envelope.
+ *
+ * @param stash     - Root stash directory.
+ * @param inputRef  - The original input ref (for the event).
+ * @param lessonRef - The proposed lesson/knowledge ref.
+ * @param content   - The raw content that failed the quality gate.
+ * @param score     - Quality score from the judge.
+ * @param reason    - Human-readable rejection reason.
+ * @param extraMeta - Optional additional metadata for the event.
+ */
+export function writeQualityRejection(stash, inputRef, lessonRef, content, score, reason, extraMeta = {}, eligibilitySource) {
+    // D-5 / #388: reviewNeeded flag selects "review_needed" vs "quality_rejected" outcome.
+    const outcome = extraMeta.reviewNeeded ? "review_needed" : "quality_rejected";
+    const rejectDir = path.join(stash, ".akm", "distill-rejected");
+    fs.mkdirSync(rejectDir, { recursive: true });
+    const ts = timestampForFilename();
+    fs.writeFileSync(path.join(rejectDir, `${ts}-${lessonRef}.md`), `---\nscore: ${score}\nreason: ${reason}\noutcome: ${outcome}\n---\n\n${content}`, "utf8");
+    appendEvent({
+        eventType: "distill_invoked",
+        ref: inputRef,
+        metadata: {
+            outcome,
+            lessonRef,
+            score,
+            reason,
+            ...extraMeta,
+            // Attribution tagging: stamp the eligibility lane so distill_invoked can be
+            // sliced by lane downstream. See EligibilitySource.
+            ...(eligibilitySource ? { eligibilitySource } : {}),
+        },
+    });
+    return {
+        schemaVersion: 1,
+        ok: true,
+        outcome,
+        inputRef,
+        lessonRef,
+        score,
+        reason,
+        ...extraMeta,
+    };
+}
+/**
+ * G4 — content-score a distilled OUTPUT (lesson/knowledge proposal body) and
+ * persist it to state.db :: asset_salience with `encoding_source: "content"`.
+ *
+ * Lessons are refused as distill INPUTS (`DISTILL_REFUSED_INPUT_TYPES`), so
+ * this creation-time write is their only chance to earn a real content-derived
+ * encoding score instead of sitting on the type-weight stub forever. Best-effort:
+ * never blocks or fails the proposal flow.
+ */
+export function persistOutputEncodingSalience(ref, body, existingRefVocabulary, 
+// Operator opt-out (improve.salience.outcomeWeightEnabled: false) must apply
+// here too, or distill-written rank_score rows would use WS-2 weights while
+// preparation uses parity weights — inconsistent salience semantics.
+outcomeWeightEnabled) {
+    try {
+        const parsedRef = parseAssetRef(ref);
+        const salienceResult = scoreEncodingSalience({
+            body,
+            type: parsedRef.type,
+            existingRefVocabulary,
+            revisionCount: 0, // a freshly distilled output IS a first encounter
+        });
+        withStateDb((stateDb) => {
+            const vector = computeSalience({
+                ref,
+                type: parsedRef.type,
+                retrievalFreq: 0,
+                encodingSalience: salienceResult.score,
+                outcomeWeightEnabled,
+            });
+            upsertAssetSalience(stateDb, ref, vector);
+        });
+    }
+    catch {
+        // Best-effort — scoring must never block proposal creation.
+    }
+}