akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

package/dist/commands/improve/content-hash.js

@@ -0,0 +1,39 @@
+// 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/.
+/**
+ * Shared memory-content hashing primitives, extracted from the deleted
+ * `dedup.ts` (#617 dedup pre-pass, removed WI-7.3) so `consolidate.ts` /
+ * `consolidate/chunking.ts` / `distill.ts` keep a stable, dependency-free home
+ * for the case-preserving stripped-body hash they use for the body-embedding
+ * cache and (formerly) the fidelity-check body comparison.
+ *
+ * @module content-hash
+ */
+import { createHash } from "node:crypto";
+import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+/**
+ * Strip frontmatter from raw memory content, returning the body text trimmed.
+ * Case and whitespace are preserved. Falls back to `raw.trim()` on
+ * unparseable frontmatter (consistent with the pre-existing load-time hot
+ * guard).
+ */
+export function stripFrontmatterBody(raw) {
+    try {
+        return parseFrontmatter(raw).content.trim();
+    }
+    catch {
+        return raw.trim();
+    }
+}
+/**
+ * Hash used for change-detection and the body-embedding cache: case-/
+ * whitespace-preserving stripped body. Two memories with the same wording
+ * but different casing produce DIFFERENT hashes here, which is intentional —
+ * we embed the exact text and cache by its precise content.
+ *
+ * This is the `content_hash` stored in `body_embeddings`.
+ */
+export function cacheHash(raw) {
+    return createHash("sha256").update(stripFrontmatterBody(raw), "utf8").digest("hex");
+}

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

@@ -11,7 +11,7 @@
  * (`effectiveProposalKind !== "knowledge"`) stays in the caller; these helpers
  * assume the lesson path.
  */
-import { assembleAssetFromString } from "../../../core/asset/asset-serialize.js";
+import { assembleAssetFromString, serializeFrontmatterQuoted } 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";
@@ -82,9 +82,7 @@ export function autoRepairLessonFrontmatter(content, inputRef) {
         ...(missingDesc && descLine ? { description: descLine } : {}),
         ...(missingWtu && wtuLine ? { when_to_use: wtuLine } : {}),
     };
-    const fmLines = Object.entries(repairedFm)
-        .map(([k, v]) => `${k}: ${JSON.stringify(v)}`)
-        .join("\n");
+    const fmLines = serializeFrontmatterQuoted(repairedFm);
     // 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) {
@@ -122,9 +120,7 @@ export function autoSwapDescriptionWhenToUse(content, inputRef) {
                 description: wtuRaw,
                 when_to_use: descRaw,
             };
-            const swappedFmLines = Object.entries(swappedFm)
-                .map(([k, v]) => `${k}: ${JSON.stringify(v)}`)
-                .join("\n");
+            const swappedFmLines = serializeFrontmatterQuoted(swappedFm);
             return { content: assembleAssetFromString(swappedFmLines, parsedSwap.content), swapped: 1 };
         }
     }
@@ -146,9 +142,7 @@ export function repairLessonDescriptionTruncation(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");
+    const repairedFmLines = serializeFrontmatterQuoted({ ...fmRepair, description: repaired });
     return assembleAssetFromString(repairedFmLines, parsedRepair.content);
 }
 /**

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

@@ -18,40 +18,27 @@
  */
 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 { parseEmbeddedJsonResponse } from "../../../core/parse.js";
+import { isProposalSkipped } from "../../proposal/repository.js";
 import { assessMemoryKnowledgePromotionCandidate } from "../distill-promotion-policy.js";
+import { emitProposal } from "../proposal-envelope.js";
+import { durableImproveRef } from "../source-identity.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.
+ * Resolve the knowledge content to propose when a memory promotes to knowledge,
+ * reconciling it with any existing knowledge file at the destination (D-1 / #369).
+ *
+ * When the destination already exists and an LLM is configured, follows the
+ * mem0 ADD/UPDATE/NOOP pattern (arXiv:2504.19413 §3.2): ADD/UPDATE swap in the
+ * merged content, NOOP short-circuits with a terminal "skipped" result. Without
+ * an LLM the existing content is appended as reviewer-reference context so the
+ * merge can be done by hand. Logic is byte-identical to the prior inline block.
  */
-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);
+async function resolveKnowledgePromotionContent(ctx, baseContent, knowledgeRef) {
+    const durableInputRef = ctx.durableInputRef ?? ctx.inputRef;
+    let resolvedPromotionContent = baseContent;
+    const existingKnowledgePath = await ctx.lookup(durableImproveRef(knowledgeRef));
     const existingKnowledgeContent = existingKnowledgePath && fs.existsSync(existingKnowledgePath)
         ? (() => {
             try {
@@ -62,7 +49,7 @@ export async function promoteMemoryToKnowledge(ctx) {
             }
         })()
         : null;
-    if (existingKnowledgeContent && config && getDefaultLlmConfig(config)) {
+    if (existingKnowledgeContent && ctx.llmConfig) {
         // Existing content found: call LLM for contradiction-resolution merge.
         const mergePrompt = [
             "You are merging two versions of a knowledge document.",
@@ -77,38 +64,38 @@ export async function promoteMemoryToKnowledge(ctx) {
             "",
             "## New content from distillation",
             "```",
-            promotion.content.slice(0, 3000),
+            baseContent.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, [
+            const mergeResponse = await ctx.chat(ctx.llmConfig, [
                 { role: "system", content: "Return only valid JSON. No prose." },
                 { role: "user", content: mergePrompt },
-            ]);
+            ], ctx.signal ? { signal: ctx.signal } : undefined);
             const mergeResult = parseEmbeddedJsonResponse(mergeResponse);
             if (mergeResult?.action === "NOOP") {
                 // Existing content is authoritative — no update needed.
                 appendEvent({
                     eventType: "distill_invoked",
-                    ref: inputRef,
+                    // Use item_ref when resolved, otherwise the input conceptId.
+                    ref: ctx.itemRef ?? durableInputRef,
                     metadata: {
                         outcome: "skipped",
-                        lessonRef: promotion.knowledgeRef,
+                        proposalRef: knowledgeRef,
                         message: "D-1: LLM resolved destination conflict as NOOP — existing content kept",
-                        ...eligMeta,
+                        ...ctx.eligMeta,
                     },
-                });
+                }, ctx.eventsCtx);
                 return {
-                    schemaVersion: 1,
-                    ok: true,
-                    outcome: "skipped",
-                    inputRef,
-                    lessonRef: promotion.knowledgeRef,
-                    message: "Existing knowledge content unchanged (contradiction resolution: NOOP)",
+                    earlyResult: {
+                        schemaVersion: 1,
+                        ok: true,
+                        outcome: "skipped",
+                        inputRef: ctx.inputRef,
+                        proposalRef: knowledgeRef,
+                        skipReason: "conflict_noop",
+                        message: "Existing knowledge content unchanged (contradiction resolution: NOOP)",
+                    },
                 };
             }
             if (mergeResult?.action && (mergeResult.action === "ADD" || mergeResult.action === "UPDATE")) {
@@ -122,11 +109,11 @@ export async function promoteMemoryToKnowledge(ctx) {
             // The reviewer will see both versions in the proposal diff.
         }
     }
-    else if (existingKnowledgeContent && config && !getDefaultLlmConfig(config)) {
+    else if (existingKnowledgeContent) {
         // No LLM configured: include existing content as context in the proposal
         // so the reviewer can do the contradiction resolution manually.
         resolvedPromotionContent = [
-            promotion.content,
+            baseContent,
             "",
             "---",
             "<!-- D-1 / #369: Existing knowledge content is shown below for reviewer reference. -->",
@@ -137,20 +124,55 @@ export async function promoteMemoryToKnowledge(ctx) {
             existingKnowledgeContent,
         ].join("\n");
     }
+    return { resolvedContent: resolvedPromotionContent };
+}
+/**
+ * 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, fetchSimilarLessonsFn, existingRefVocabulary, outcomeWeightEnabled, eligMeta, exclusionSetSize, filteredFeedbackCount, feedbackFullyFiltered, } = ctx;
+    const durableInputRef = ctx.durableInputRef ?? inputRef;
+    const promotion = targetKind === "lesson"
+        ? null
+        : assessMemoryKnowledgePromotionCandidate({
+            inputRef: durableInputRef,
+            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).
+    const merged = await resolveKnowledgePromotionContent(ctx, promotion.content, promotion.knowledgeRef);
+    if ("earlyResult" in merged)
+        return merged.earlyResult;
+    const resolvedPromotionContent = merged.resolvedContent;
     // 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")) {
+    if (ctx.strategy?.processes?.distill?.qualityGate?.enabled ?? true) {
         // 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);
+        const judgeResult = await runLessonQualityJudge(config, resolvedPromotionContent, assetContent ?? "", chat, {
+            ...(similarLessons.length > 0 ? { similarLessons } : {}),
+            ...(ctx.llmConfig ? { llmConfig: ctx.llmConfig } : {}),
+            ...(ctx.signal ? { signal: ctx.signal } : {}),
+        });
         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, { reviewNeeded: true }, ctx.eligibilitySource, ctx.eventsCtx);
             }
-            return writeQualityRejection(stash, inputRef, promotion.knowledgeRef, resolvedPromotionContent, judgeResult.score, judgeResult.reason, {}, ctx.eligibilitySource);
+            return writeQualityRejection(stash, inputRef, promotion.knowledgeRef, resolvedPromotionContent, judgeResult.score, judgeResult.reason, {}, ctx.eligibilitySource, ctx.eventsCtx);
         }
         // Normalize 1-5 judge score to [0, 1]. Only a real passing verdict reaches
         // here (07 P0-2: the judge now fails CLOSED on no-LLM / timeout / parse
@@ -160,9 +182,11 @@ export async function promoteMemoryToKnowledge(ctx) {
             knowledgeJudgeConfidence = judgeResult.score / 5;
     }
     const knowledgeParsed = parseFrontmatter(resolvedPromotionContent);
-    const proposalResult = createProposal(stash, {
+    const proposalResult = emitProposal({ stashDir: stash, proposalsCtx: ctx.proposalsCtx }, {
         ref: promotion.knowledgeRef,
         source: "distill",
+        // §23.6 fingerprint model-id term (WI-6.4).
+        ...(ctx.llmConfig?.model ? { modelId: ctx.llmConfig.model } : {}),
         ...(ctx.sourceRun !== undefined ? { sourceRun: ctx.sourceRun } : {}),
         payload: {
             content: resolvedPromotionContent,
@@ -171,38 +195,40 @@ export async function promoteMemoryToKnowledge(ctx) {
         ...(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,
+            // Use item_ref when resolved, otherwise the input conceptId.
+            ref: ctx.itemRef ?? durableInputRef,
             metadata: {
                 outcome: "skipped",
-                lessonRef: promotion.knowledgeRef,
+                proposalRef: promotion.knowledgeRef,
                 message: proposalResult.message,
                 skipReason: proposalResult.reason,
                 ...eligMeta,
             },
-        });
+        }, ctx.eventsCtx);
         return {
             schemaVersion: 1,
             ok: true,
             outcome: "skipped",
             inputRef,
-            lessonRef: promotion.knowledgeRef,
+            proposalRef: promotion.knowledgeRef,
+            skipReason: proposalResult.reason,
             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);
+    persistOutputEncodingSalience(durableImproveRef(promotion.knowledgeRef), resolvedPromotionContent, existingRefVocabulary, outcomeWeightEnabled);
     appendEvent({
         eventType: "distill_invoked",
-        ref: inputRef,
+        // Use item_ref when resolved, otherwise the input conceptId.
+        ref: ctx.itemRef ?? durableInputRef,
         metadata: {
             outcome: "queued",
-            lessonRef: promotion.knowledgeRef,
             proposalRef: promotion.knowledgeRef,
             proposalKind: "knowledge",
             proposalId: proposal.id,
@@ -213,13 +239,12 @@ export async function promoteMemoryToKnowledge(ctx) {
             ...(exclusionSetSize > 0 ? { filteredFeedbackCount } : {}),
             ...eligMeta,
         },
-    });
+    }, ctx.eventsCtx);
     return {
         schemaVersion: 1,
         ok: true,
         outcome: "queued",
         inputRef,
-        lessonRef: promotion.knowledgeRef,
         proposalRef: promotion.knowledgeRef,
         proposalKind: "knowledge",
         proposalId: proposal.id,

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

@@ -10,12 +10,13 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { parseAssetRef } from "../../../core/asset/asset-ref.js";
+import { parseRefInput } from "../../../core/asset/resolve-ref.js";
 import { timestampForFilename } from "../../../core/common.js";
-import { getDefaultLlmConfig } from "../../../core/config/config.js";
 import { appendEvent } from "../../../core/events.js";
+import { parseEmbeddedJsonResponse } from "../../../core/parse.js";
 import { withStateDb } from "../../../core/state-db.js";
-import { parseEmbeddedJsonResponse } from "../../../llm/client.js";
+import { getDefaultLlmConfig } from "../../../integrations/agent/engine-resolution.js";
+import { callStructured } from "../../../llm/structured-call.js";
 import { akmSearch } from "../../read/search.js";
 import { scoreEncodingSalience } from "../encoding-salience.js";
 import { computeSalience, upsertAssetSalience } from "../salience.js";
@@ -98,39 +99,97 @@ export function buildJudgePrompt(lessonContent, sourceContent, similarLessons) {
     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-CLOSED (07 P0-2): returns `pass: false` (score -1) on timeout, parse
- * failure, or missing LLM. Minted content that cannot be judged is rejected,
- * not passed through — an unverifiable judge must never wave content into the
- * stash. The rejection is `quality_rejected`, not `review_needed`.
- */
-export async function runLessonQualityJudge(config, lessonContent, sourceContent, chat, 
-/** D-4 / #390: top-3 similar existing lessons for dedup check. */
-similarLessons) {
-    const llmConfig = getDefaultLlmConfig(config);
+function boundedDocument(content, maxChars = 6000) {
+    if (content.length <= maxChars)
+        return content;
+    const half = Math.floor((maxChars - 80) / 2);
+    return `${content.slice(0, half)}\n\n[... middle omitted for bounded judge context ...]\n\n${content.slice(-half)}`;
+}
+function buildChangedRegion(sourceContent, candidateContent) {
+    const source = sourceContent.split("\n");
+    const candidate = candidateContent.split("\n");
+    let prefix = 0;
+    while (prefix < source.length && prefix < candidate.length && source[prefix] === candidate[prefix])
+        prefix++;
+    let suffix = 0;
+    while (suffix < source.length - prefix &&
+        suffix < candidate.length - prefix &&
+        source[source.length - 1 - suffix] === candidate[candidate.length - 1 - suffix]) {
+        suffix++;
+    }
+    const removed = source.slice(prefix, source.length - suffix).join("\n");
+    const added = candidate.slice(prefix, candidate.length - suffix).join("\n");
+    return boundedDocument(`Removed or replaced:\n${removed || "(none)"}\n\nAdded or replacement:\n${added || "(none)"}`);
+}
+/** Build quality criteria for revising an existing asset in place. */
+export function buildReflectJudgePrompt(candidateContent, sourceContent, feedback) {
+    return [
+        "You are evaluating a proposed revision to an existing akm asset.",
+        "",
+        "Score this revision on each criterion from 1 (poor) to 5 (excellent):",
+        "1. FEEDBACK ALIGNMENT: Does the revision address the supplied feedback or improve retrieval and clarity?",
+        "2. PRESERVATION: Does it retain the source's concrete facts, code, commands, examples, and structure without truncation?",
+        "3. QUALITY: Is the revision coherent, actionable, complete, and free of unsupported claims?",
+        "",
+        "Overlap with the source is expected and must not lower the score by itself; this is an in-place revision, not a new lesson.",
+        "",
+        "Feedback:",
+        "```",
+        (feedback.length > 0 ? feedback.join("\n") : "No explicit feedback supplied.").slice(0, 1000),
+        "```",
+        "",
+        "Source asset content:",
+        "```",
+        boundedDocument(sourceContent),
+        "```",
+        "",
+        "Proposed revision:",
+        "```",
+        boundedDocument(candidateContent),
+        "```",
+        "",
+        "Changed region:",
+        "```",
+        buildChangedRegion(sourceContent, candidateContent),
+        "```",
+        "",
+        'Return ONLY valid JSON, no prose: {"score": <average score 1-5 as float>, "reason": "<one sentence>"}',
+    ].join("\n");
+}
+async function runQualityJudge(feature, config, prompt, chat, options = {}) {
+    const llmConfig = options.llmConfig ?? getDefaultLlmConfig(config);
     if (!llmConfig) {
         return { pass: false, score: -1, reason: "no LLM configured — cannot judge, failing closed" };
     }
-    const judgeLlmConfig = llmConfig.judgeModel ? { ...llmConfig, model: llmConfig.judgeModel } : llmConfig;
-    const JUDGE_TIMEOUT_MS = 8_000;
     try {
-        const raw = await Promise.race([
-            chat(judgeLlmConfig, [
+        // UNGATED at the seam (no akmConfig): the quality gates' enablement is
+        // resolved by the caller before this function runs, and a transport throw
+        // propagates into the fail-closed catch below. `feature` labels the call.
+        const raw = await callStructured({
+            feature,
+            config: llmConfig,
+            messages: [
                 { 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)),
-        ]);
+                { role: "user", content: prompt },
+            ],
+            request: {
+                enableThinking: false,
+                ...(Object.hasOwn(options, "timeoutMs") ? { timeoutMs: options.timeoutMs } : {}),
+                ...(options.signal ? { signal: options.signal } : {}),
+                ...(chat ? { chat } : {}),
+            },
+            parse: (rawResponse) => rawResponse ?? "",
+            // Unreachable on the ungated path (errors propagate); fail closed anyway.
+            onError: () => "",
+            fallback: "",
+        });
         const parsed = parseEmbeddedJsonResponse(raw);
-        if (!parsed || typeof parsed.score !== "number") {
+        if (!parsed ||
+            typeof parsed.score !== "number" ||
+            !Number.isFinite(parsed.score) ||
+            parsed.score < 1 ||
+            parsed.score > 5 ||
+            typeof parsed.reason !== "string") {
             return { pass: false, score: -1, reason: "judge parse failed — cannot judge, failing closed" };
         }
         // D-5 / #388: Three-band system (MT-Bench arXiv:2306.05685 — ~±0.5 judge variance).
@@ -139,19 +198,35 @@ similarLessons) {
         //   < 2.5: auto-reject (pass: false)
         const score = parsed.score;
         const reason = parsed.reason ?? "";
-        if (score >= 3.5) {
+        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.
+        if (score >= 2.5)
             return { pass: false, score, reason, reviewNeeded: true };
-        }
         return { pass: false, score, reason };
     }
     catch {
         return { pass: false, score: -1, reason: "judge timeout/error — cannot judge, failing closed" };
     }
 }
+/**
+ * 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).
+ * The selected strategy's distill/reflect quality-gate setting is resolved by
+ * the caller before this function runs.
+ *
+ * Fail-CLOSED (07 P0-2): returns `pass: false` (score -1) on timeout, parse
+ * failure, or missing LLM. Minted content that cannot be judged is rejected,
+ * not passed through — an unverifiable judge must never wave content into the
+ * stash. The rejection is `quality_rejected`, not `review_needed`.
+ */
+export async function runLessonQualityJudge(config, lessonContent, sourceContent, chat, options = {}) {
+    return runQualityJudge("lesson_quality_gate", config, buildJudgePrompt(lessonContent, sourceContent, options.similarLessons), chat, options);
+}
+/** Judge an in-place reflect revision without applying new-lesson novelty criteria. */
+export async function runReflectQualityJudge(config, candidateContent, sourceContent, feedback, chat, options = {}) {
+    return runQualityJudge("proposal_quality_gate", config, buildReflectJudgePrompt(candidateContent, sourceContent, feedback), chat, options);
+}
 // ── Quality-rejection helper ─────────────────────────────────────────────────
 /**
  * Write a rejected lesson to `.akm/distill-rejected/`, append a `distill_invoked`
@@ -159,25 +234,26 @@ similarLessons) {
  *
  * @param stash     - Root stash directory.
  * @param inputRef  - The original input ref (for the event).
- * @param lessonRef - The proposed lesson/knowledge ref.
+ * @param proposalRef - 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.
+ * @param eventsCtx - Events context so the emit takes appendEvent's fast path (R25).
  */
-export function writeQualityRejection(stash, inputRef, lessonRef, content, score, reason, extraMeta = {}, eligibilitySource) {
+export function writeQualityRejection(stash, inputRef, proposalRef, content, score, reason, extraMeta = {}, eligibilitySource, eventsCtx) {
     // 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");
+    fs.writeFileSync(path.join(rejectDir, `${ts}-${proposalRef.replace(/[:/\\]/g, "-")}.md`), `---\nscore: ${score}\nreason: ${reason}\noutcome: ${outcome}\n---\n\n${content}`, "utf8");
     appendEvent({
         eventType: "distill_invoked",
         ref: inputRef,
         metadata: {
             outcome,
-            lessonRef,
+            proposalRef,
             score,
             reason,
             ...extraMeta,
@@ -185,13 +261,13 @@ export function writeQualityRejection(stash, inputRef, lessonRef, content, score
             // sliced by lane downstream. See EligibilitySource.
             ...(eligibilitySource ? { eligibilitySource } : {}),
         },
-    });
+    }, eventsCtx);
     return {
         schemaVersion: 1,
         ok: true,
         outcome,
         inputRef,
-        lessonRef,
+        proposalRef,
         score,
         reason,
         ...extraMeta,
@@ -212,7 +288,7 @@ export function persistOutputEncodingSalience(ref, body, existingRefVocabulary,
 // preparation uses parity weights — inconsistent salience semantics.
 outcomeWeightEnabled) {
     try {
-        const parsedRef = parseAssetRef(ref);
+        const parsedRef = parseRefInput(ref);
         const salienceResult = scoreEncodingSalience({
             body,
             type: parsedRef.type,

package/dist/commands/improve/distill-guards.js

@@ -96,7 +96,7 @@ export function checkDistillFidelity(proposalBody, sourceBodies, config) {
             }
         }
     }
-    // Also flag proposals whose source_refs are empty (broken provenance).
+    // Also flag proposals whose xrefs are empty (broken provenance).
     // This is a degradation signal, not a contradiction, but worth surfacing.
     return { contradictionDetected: false };
 }