akm-cli 0.9.30 → 0.10.261001-beta

package/dist/commands/improve/consolidate.js

@@ -28,7 +28,7 @@ import { detectAdapterId } from "../../core/adapter/detect-adapter.js";
 import { assembleAssetFromString, serializeFrontmatter } from "../../core/asset/asset-serialize.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { conceptIdFromTypeName, displayRef, parseRefInput } from "../../core/asset/resolve-ref.js";
-import { getImproveProcessConfig, loadConfig } from "../../core/config/config.js";
+import { loadConfig } from "../../core/config/config.js";
 import { parseEmbeddedJsonResponse } from "../../core/parse.js";
 import { openStateDatabase } from "../../core/state-db.js";
 import { warn, warnVerbose } from "../../core/warn.js";
@@ -43,7 +43,7 @@ import { getBodyEmbeddings, upsertBodyEmbeddings } from "../../storage/repositor
 import { closeDatabase, openExistingDatabase, openReadonlyExistingDatabase, } from "../../storage/repositories/index-connection.js";
 import { getAllEntries } from "../../storage/repositories/index-entries-repository.js";
 import { listProposals, listProposalsReadOnly, proposalContent } from "../proposal/repository.js";
-import { hasHotCaptureMode, hasSupersededStatus, validateProposalFrontmatter, } from "../proposal/validators/proposal-quality-validators.js";
+import { hasSupersededStatus, validateProposalFrontmatter } from "../proposal/validators/proposal-quality-validators.js";
 import { buildChunkPrompt, computeSafeChunkSize, DEFAULT_CONTEXT_LENGTH_TOKENS } from "./consolidate/chunking.js";
 import { openKnowledgeCoverage } from "./consolidate/coverage.js";
 import { runConsolidatePairPass } from "./consolidate/pair-pass.js";
@@ -75,21 +75,6 @@ export function mergePlans(chunks) {
 export function isConsolidationEligibleMemoryName(name) {
     return !name.endsWith(".derived");
 }
-/**
- * A `captureMode: hot` memory (written deliberately with `akm remember`). A
- * missing file is not hot; an unreadable one is treated as hot — the check is
- * a protection and must not fail open.
- */
-export function isHotCapturedMemory(filePath) {
-    if (!fs.existsSync(filePath))
-        return false;
-    try {
-        return hasHotCaptureMode(parseFrontmatter(fs.readFileSync(filePath, "utf8")).data);
-    }
-    catch {
-        return true;
-    }
-}
 /**
  * Structured-output schema for a plan. Promote-only: merge/delete/contradict
  * were removed in 0.9.17-alpha.1 (`e82eec811`) after running in production —
@@ -210,36 +195,6 @@ async function clusterMemoriesBySimilarity(memories, config, stateDb, signal) {
     }
     return { ordered, embedTelemetry: telemetry };
 }
-/**
- * Anti-collapse (default on, `antiCollapse.enabled: false` opts out): a small
- * deterministic sample of the pool is spread through the similarity order so
- * consolidation is not purely similarity-driven.
- */
-function injectRandomClusterMembers(memories, profile, warnings) {
-    const config = getImproveProcessConfig("consolidate", profile)?.antiCollapse ?? {};
-    if (config.enabled === false || memories.length <= 2)
-        return memories;
-    const fraction = config.randomClusterFraction ?? 0.05;
-    const randomCount = Math.max(1, Math.floor(memories.length * fraction));
-    const sample = [...memories]
-        .sort((a, b) => contentHash(a.name).localeCompare(contentHash(b.name)))
-        .slice(0, randomCount);
-    const sampled = new Set(sample.map((m) => m.name));
-    const interval = Math.max(2, Math.floor(memories.length / randomCount));
-    const out = [];
-    let next = 0;
-    for (let i = 0; i < memories.length; i++) {
-        const m = memories[i];
-        if (m && !sampled.has(m.name))
-            out.push(m);
-        if (i > 0 && i % interval === 0 && next < sample.length)
-            out.push(sample[next++]);
-    }
-    while (next < sample.length)
-        out.push(sample[next++]);
-    warnings.push(`Anti-collapse: injected ${randomCount} random (non-similarity-driven) cluster member(s) into consolidation pool (fraction=${fraction}).`);
-    return out;
-}
 /** Body hashes of pending consolidate proposals, so the prompt can mark memories already queued. */
 function loadPendingConsolidateProposalHashes(stashDir, proposalsCtx) {
     const hashes = new Set();
@@ -561,9 +516,8 @@ const ABORT_MIN_CHUNKS = 4;
 const ABORT_FAILURE_RATE = 0.5;
 /**
  * The chunk loop: stop cleanly on the budget signal, abort once ≥50% of at
- * least 4 chunks failed (the model is likely down), skip an all-hot chunk
- * without a call (the only thing the model could do with it is refused), and
- * count every memory into exactly one accounting bucket.
+ * least 4 chunks failed (the model is likely down), and count every memory
+ * into exactly one accounting bucket.
  */
 async function judgeConsolidationChunks(args) {
     const { chunks, opts, config, warnings, acc } = args;
@@ -601,15 +555,6 @@ async function judgeConsolidationChunks(args) {
             }
         }
         const chunk = chunks[chunkIdx];
-        if (chunk.length > 0 && chunk.every((m) => isHotCapturedMemory(m.filePath))) {
-            for (const m of chunk) {
-                acc.judgedNoActionRefs.add(memRef(m));
-                acc.judgedRefs.add(memRef(m));
-            }
-            acc.judgedNoAction += chunk.length;
-            warn(`[consolidate] chunk ${chunkIdx + 1}/${chunks.length}: all ${chunk.length} memories are captureMode: hot — skipping LLM (judged no-action).`);
-            continue;
-        }
         warn(`[consolidate] chunk ${chunkIdx + 1}/${chunks.length} (${chunk.length} memories) …`);
         processed++;
         if (!llmRunner) {
@@ -670,11 +615,12 @@ async function judgeConsolidationChunks(args) {
     }
     return planned;
 }
+/** Assumed wall-clock seconds per consolidation chunk for the up-front budget cap. */
+const CHUNK_SECONDS_ESTIMATE = 30;
 /**
  * The model's plan for the narrowed pool: chunk size from the context window,
  * an up-front cap when the remaining budget cannot cover every chunk (oldest
- * first, the rest deferred), similarity clustering, anti-collapse, then the
- * chunk loop.
+ * first, the rest deferred), similarity clustering, then the chunk loop.
  */
 async function planConsolidation(opts, config, stashDir, memories, warnings, stateDb, acc) {
     const llmRunner = opts.llmRunner ?? undefined;
@@ -685,7 +631,7 @@ async function planConsolidation(opts, config, stashDir, memories, warnings, sta
     let budgeted = memories;
     const budgetMs = opts.signal?.remainingBudgetMs;
     if (opts.signal && budgetMs !== undefined) {
-        const safeChunks = Math.max(0, Math.floor((Math.max(0, budgetMs) / 1000 / (opts.p90ChunkSecondsDefault ?? 30)) * 0.6));
+        const safeChunks = Math.max(0, Math.floor((Math.max(0, budgetMs) / 1000 / CHUNK_SECONDS_ESTIMATE) * 0.6));
         if (safeChunks * chunkSize < memories.length) {
             budgeted = [...memories]
                 .sort((a, b) => mtimeMsOf(a) - mtimeMsOf(b) || a.name.localeCompare(b.name))
@@ -696,11 +642,10 @@ async function planConsolidation(opts, config, stashDir, memories, warnings, sta
         }
     }
     const slice = (list) => Array.from({ length: Math.ceil(list.length / chunkSize) }, (_, i) => list.slice(i * chunkSize, (i + 1) * chunkSize));
-    const willDispatch = slice(budgeted).some((chunk) => chunk.length > 0 && !chunk.every((memory) => isHotCapturedMemory(memory.filePath)));
-    if (llmRunner && willDispatch)
+    if (llmRunner && budgeted.length > 0)
         assertRunnerCredentials(llmRunner);
     const { ordered, embedTelemetry } = await clusterMemoriesBySimilarity(budgeted, config, stateDb, opts.signal);
-    const chunks = slice(injectRandomClusterMembers(ordered, opts.improveProfile, warnings));
+    const chunks = slice(ordered);
     const pendingProposalBodyHashes = loadPendingConsolidateProposalHashes(stashDir, opts.proposalsCtx);
     warn(`[consolidate] ${budgeted.length} memories / ${chunks.length} chunk(s) / chunk_size=${chunkSize}` +
         ` / pending-proposal hashes: ${pendingProposalBodyHashes.size}`);

package/dist/commands/improve/distill/lesson-update.js

@@ -0,0 +1,91 @@
+// 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's lesson update (#1090): when a memory's lesson repeats a lesson the library already holds, the writer
+ * is asked to extend that lesson with what the memory adds instead of the duplicate being thrown away. These are
+ * the prompt, the reply schema and the two deterministic checks; the call, the judge and the proposal are in
+ * `../distill`.
+ */
+import { parseEmbeddedJsonResponse } from "../../../core/parse.js";
+export const DISTILL_LESSON_UPDATE_JSON_SCHEMA = {
+    type: "object",
+    required: ["reason", "new_facts", "decision", "ref", "body"],
+    additionalProperties: false,
+    properties: {
+        reason: {
+            type: "string",
+            description: "One sentence: which listed lesson states the rule and what the memory adds to it, or why nothing.",
+        },
+        new_facts: {
+            type: "array",
+            items: { type: "string" },
+            description: "Written before the body: each cause, step, number, limit or consequence the memory states and the lesson lacks, one short phrase each. Empty when there is none.",
+        },
+        decision: {
+            type: "string",
+            enum: ["update", "none"],
+            description: "`none` when no listed lesson states the memory's rule, or `new_facts` is empty: leave `ref` and `body` empty. Otherwise `update`.",
+        },
+        ref: { type: "string", description: "The `Existing lesson ref:` of the lesson to extend. Empty for `none`." },
+        body: {
+            type: "string",
+            description: "That lesson's whole body with the new lines added, every existing line unchanged. No frontmatter. Empty for `none`.",
+        },
+    },
+};
+export function buildLessonUpdatePrompt(memory, feedback, candidates) {
+    const lines = [
+        "A lesson written from the memory below would repeat a lesson the library already holds. Do not write a new lesson. Extend the existing one with what the memory adds.",
+        "",
+        "Memory:",
+        "```",
+        memory.slice(0, 3000),
+        "```",
+    ];
+    if (feedback.length > 0)
+        lines.push("", "Feedback recorded about the memory:", "```", feedback.join("\n").slice(0, 1500), "```");
+    lines.push("", "Existing lessons, nearest first (they may be on another subject):");
+    for (const candidate of candidates) {
+        lines.push(`\nExisting lesson ref: ${candidate.ref}`, "```", candidate.body.slice(0, 3000), "```");
+    }
+    lines.push("", "Pick the one existing lesson that already states the rule the memory gives. Write its whole body again with the new lines added:", "- Copy every existing line unchanged, in its place. Do not reword, shorten, reorder or drop any of them.", "First list in new_facts each cause, step, number, limit or consequence the memory states and the lesson lacks, one short phrase each: check every sentence of the memory against the lesson. The memory's own incident retold (what happened in one test, project or day) is not a new fact unless it carries one of these. Then add one line to the body for each new fact, and say nothing the memory does not say.", "- If the memory contradicts a line of the lesson, answer none.", "- If no listed lesson states the memory's rule, or the memory adds nothing the lesson lacks, answer none.", "", 'Return ONLY valid JSON, no prose: {"reason": "...", "new_facts": ["..."], "decision": "update" | "none", "ref": "<the existing lesson ref>", "body": "<the whole body>"}');
+    return lines.join("\n");
+}
+/** The writer's chosen update, or `null` for `none` and for any reply that names no listed lesson, no new fact or no body. */
+export function parseLessonUpdate(raw, candidates) {
+    const payload = parseEmbeddedJsonResponse(raw);
+    if (!payload || typeof payload !== "object" || Array.isArray(payload) || payload.decision !== "update")
+        return null;
+    const ref = typeof payload.ref === "string" ? payload.ref.trim() : "";
+    const body = typeof payload.body === "string" ? payload.body.trim() : "";
+    const candidate = candidates.find((c) => c.ref === ref);
+    const facts = Array.isArray(payload.new_facts)
+        ? payload.new_facts.filter((f) => typeof f === "string" && f.trim() !== "")
+        : [];
+    if (!candidate || !body || facts.length === 0)
+        return null;
+    return { candidate, body, reason: typeof payload.reason === "string" ? payload.reason.trim() : "" };
+}
+const normalizeLine = (line) => line.trim().replace(/\s+/g, " ").toLowerCase();
+const bodyLines = (body) => body
+    .split("\n")
+    .map(normalizeLine)
+    .filter((line) => line !== "");
+/**
+ * What an update does to a lesson's body: the existing lines it no longer holds (compared by words, in any case
+ * and spacing, anywhere in the new body) and the lines it adds.
+ */
+export function diffLessonBody(existingBody, mergedBody) {
+    const existing = bodyLines(existingBody);
+    const merged = bodyLines(mergedBody);
+    const kept = new Set(merged);
+    const had = new Set(existing);
+    return {
+        dropped: existing.filter((line) => !kept.has(line)),
+        added: mergedBody
+            .split("\n")
+            .filter((line) => line.trim() !== "" && !had.has(normalizeLine(line)))
+            .map((line) => line.trim()),
+    };
+}

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

@@ -3,8 +3,7 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
  * Distill guards: the related lessons, knowledge notes and skills shown to the
- * writer so it does not repeat or overwrite them (CLS context), and a cheap check
- * that a proposal does not contradict the memories it came from.
+ * writer so it does not repeat or overwrite them (CLS context).
  */
 export const DEFAULT_CLS_ADJACENT_COUNT = 3;
 /** The CLS prompt section (each entry capped at 600 chars); empty when disabled (on unless `enabled: false`) or nothing is related. */
@@ -22,44 +21,3 @@ export function buildClsContext(adjacentItems, config) {
         lines.push(`### ${item.ref}`, item.content.trim().slice(0, 600), "");
     return lines.join("\n");
 }
-/**
- * Flag a proposal whose "always/must X" (or "never/must not X") claim meets
- * the opposite claim about X in a source. Deliberately conservative: a flag
- * only costs a human review, while a model call per proposal is expensive.
- */
-export function checkDistillFidelity(proposalBody, sourceBodies, config) {
-    if (!config.enabled || sourceBodies.length === 0)
-        return { contradictionDetected: false };
-    const strongClaims = extractStrongClaims(proposalBody.toLowerCase());
-    for (const sourceBody of sourceBodies) {
-        const sourceLow = sourceBody.toLowerCase();
-        for (const { polarity, term } of strongClaims) {
-            if (hasStrongClaim(sourceLow, term, polarity === "positive" ? "negative" : "positive")) {
-                return {
-                    contradictionDetected: true,
-                    reason: `Proposal makes a ${polarity} strong claim about "${term}" that conflicts with an opposing claim in a cited source. Route to human review.`,
-                };
-            }
-        }
-    }
-    return { contradictionDetected: false };
-}
-const CLAIM_PATTERNS = [
-    { polarity: "positive", re: /\b(?:always|must)\s+(\w+)/g },
-    { polarity: "negative", re: /\b(?:never|must\s+not|should\s+not)\s+(\w+)/g },
-];
-function extractStrongClaims(text) {
-    const claims = [];
-    for (const { polarity, re } of CLAIM_PATTERNS) {
-        for (const m of text.matchAll(re)) {
-            const term = m[1];
-            if (term && term.length > 2)
-                claims.push({ polarity, term });
-        }
-    }
-    return claims;
-}
-function hasStrongClaim(text, term, polarity) {
-    const marker = polarity === "positive" ? /\b(?:always|must)\s/ : /\b(?:never|must\s+not|should\s+not)\s/;
-    return marker.test(text) && text.includes(term);
-}

package/dist/commands/improve/distill.js

@@ -40,15 +40,15 @@ import { getAllEntries } from "../../storage/repositories/index-entries-reposito
 import { listProposals } from "../proposal/repository.js";
 import { detectDoubleFrontmatter, isValidDescription } from "../proposal/validators/proposal-quality-validators.js";
 import { akmSearch } from "../read/search.js";
-import { stripFrontmatterBody } from "./content-hash.js";
 import { autoRepairLessonFrontmatter, autoSwapDescriptionWhenToUse, collectLessonQualityFindings, repairLessonDescriptionTruncation, } from "./distill/content-repair.js";
-import { buildClsContext, checkDistillFidelity, DEFAULT_CLS_ADJACENT_COUNT } from "./distill-guards.js";
+import { buildLessonUpdatePrompt, DISTILL_LESSON_UPDATE_JSON_SCHEMA, diffLessonBody, parseLessonUpdate, } from "./distill/lesson-update.js";
+import { buildClsContext, DEFAULT_CLS_ADJACENT_COUNT } from "./distill-guards.js";
 import { assessMemoryKnowledgePromotionCandidate, deriveKnowledgeRef } from "./distill-promotion-policy.js";
 import { buildRefVocabulary, scoreEncodingSalience } from "./encoding-salience.js";
 import { resolveImproveStrategy, resolveProcessEnabled } from "./improve-strategies.js";
 import { recordLedgerAttempt } from "./ledger.js";
 import { computeSalience, upsertAssetSalience } from "./salience.js";
-import { callStage, mintProposal, noticeSet, rejectedProposalContext, resolveQualityGateJudge, runLessonQualityJudge, stageRunner, } from "./stage.js";
+import { callStage, LESSON_REJECT_MAX_SCORE, mintProposal, noticeSet, rejectedProposalContext, resolveQualityGateJudge, runLessonQualityJudge, stageRunner, } from "./stage.js";
 /**
  * Input types distill structurally refuses: a lesson is the distilled form
  * (distilling one would mint `lessons/lesson-…-lesson`), and env/secret bytes
@@ -361,7 +361,6 @@ export async function akmDistill(options) {
         eligMeta,
         asset,
         vocabulary: loadRefVocabulary(),
-        outcomeWeightEnabled: config.improve?.salience?.outcomeWeightEnabled !== false,
         related: options.fetchRelatedFn ?? fetchRelatedAssets,
         lookup,
     };
@@ -436,6 +435,12 @@ async function distill(run, targetKind, kind, outputRef, feedbackEvents) {
     }
     const none = answeredNone(call.raw);
     if (none) {
+        // The writer may have answered NONE because a lesson already states the rule (the related list says to).
+        if (kind === "lesson") {
+            const update = await proposeLessonUpdate(run, feedbackLines(feedback), none.reason);
+            if (update)
+                return update;
+        }
         return skipDistill(run, outputRef, kind, "nothing_reusable", `The writer found no lesson in ${run.inputRef}${none.reason ? `: ${none.reason}` : "."}`);
     }
     const assembled = assembleDistilledContent(run, call.raw, kind, outputRef);
@@ -537,6 +542,13 @@ async function judgeAndQueue(run, out) {
             onNotices: run.notices.add,
         });
         if (!verdict.pass) {
+            if (out.kind === "lesson" &&
+                !out.promotion &&
+                (verdict.criteria?.nonRedundancy ?? 5) <= LESSON_REJECT_MAX_SCORE) {
+                const update = await proposeLessonUpdate(run, out.feedback ?? [], verdict.reason, related);
+                if (update)
+                    return update;
+            }
             return rejectDistilled(run, out.ref, content, verdict.score, verdict.reason, {
                 ...(verdict.reviewNeeded ? { reviewNeeded: true } : {}),
                 ...(verdict.criteria ? { criteria: verdict.criteria } : {}),
@@ -553,19 +565,6 @@ async function judgeAndQueue(run, out) {
             frontmatter = data;
     }
     else {
-        // Optional check against the cited source; a contradiction goes to a human.
-        const fidelity = getImproveProcessConfig("distill", run.profile)?.fidelityCheck ?? {};
-        if (fidelity.enabled && out.source) {
-            try {
-                const verdict = checkDistillFidelity(stripFrontmatterBody(content), [stripFrontmatterBody(out.source)], fidelity);
-                if (verdict.contradictionDetected) {
-                    return rejectDistilled(run, out.ref, content, 2.0, verdict.reason ?? "Proposal may contradict cited source memories.", { reviewNeeded: true, fidelityContradiction: true });
-                }
-            }
-            catch {
-                // The fidelity check is supplemental.
-            }
-        }
         // Canonical provenance goes into the content promotion writes.
         const parsed = parseFrontmatter(content);
         const xrefs = Array.isArray(parsed.data.xrefs) ? parsed.data.xrefs.map(String) : [];
@@ -622,6 +621,129 @@ async function judgeAndQueue(run, out) {
         ...swapped,
     };
 }
+/**
+ * A memory whose lesson repeats a lesson the library holds extends that lesson instead (#1090): the writer returns
+ * the lesson's body with the memory's new lines added, and the update is proposed on the lesson's own ref, for a
+ * person to review (never staged for the drain). `finding` is what the writer (its NONE reason) or the judge said
+ * about the repeat: the related lessons it names are the candidates, or the only related lesson when it names none,
+ * so a lesson that merely sits among several near the memory costs no call. Nothing is proposed, and `undefined`
+ * returned, when no lesson qualifies, the writer finds the memory adds
+ * nothing or contradicts the lesson, the body drops or rewords a line, the judge does not pass the extended lesson,
+ * or the lesson changed meanwhile. Needs the quality gate: the judge is what holds the added lines to the memory.
+ */
+async function proposeLessonUpdate(run, feedback, finding, related) {
+    const memory = run.asset.content ? parseFrontmatter(run.asset.content).content.trim() : "";
+    const said = finding.toLowerCase();
+    if (!run.runner || !qualityGateEnabled(run) || !memory)
+        return undefined;
+    const lessons = [];
+    for (const asset of related ?? (await run.related(memory.slice(0, 500), RELATED_COUNT))) {
+        const parsed = parseRefInput(asset.ref);
+        if (parsed.type !== "lesson" || !asset.path || !isWithin(asset.path, run.stash))
+            continue;
+        try {
+            const content = fs.readFileSync(asset.path, "utf8");
+            const ref = conceptIdFromTypeName("lesson", parsed.name);
+            lessons.push({ ref, path: asset.path, content, body: parseFrontmatter(content).content.trim() });
+        }
+        catch {
+            // A lesson that cannot be read cannot be extended.
+        }
+    }
+    const named = lessons.filter((l) => said.includes(l.ref.toLowerCase()) || said.includes(l.ref.split("/").slice(1).join("/").toLowerCase()));
+    const candidates = named.length > 0 ? named : lessons.length === 1 ? lessons : [];
+    if (candidates.length === 0)
+        return undefined;
+    const call = await callStage({
+        feature: "distill",
+        runner: run.runner,
+        system: "Return only valid JSON. No prose.",
+        prompt: buildLessonUpdatePrompt(memory, feedback, candidates),
+        gate: { config: run.config, enabled: true },
+        request: {
+            ...(run.options.chat === undefined
+                ? { responseSchema: DISTILL_LESSON_UPDATE_JSON_SCHEMA }
+                : { chat: run.options.chat }),
+            ...(run.options.signal ? { signal: run.options.signal } : {}),
+        },
+        onNotices: run.notices.add,
+    });
+    const update = call.ok ? parseLessonUpdate(call.raw, candidates) : null;
+    if (!update)
+        return undefined;
+    const target = update.candidate;
+    const { dropped, added } = diffLessonBody(target.body, update.body);
+    if (dropped.length > 0) {
+        warnVerbose(`[akm] distill update of ${target.ref} dropped or reworded ${dropped.length} line(s); not proposed`);
+        return undefined;
+    }
+    if (added.length === 0)
+        return undefined;
+    // An edit is judged as the lesson it makes: the existing lesson with the lines added, as one lesson (reusable,
+    // grounded in the memory or the lesson), whose added lines must each say something the lesson did not (one call).
+    const extended = assembleAsset(parseFrontmatter(target.content).data, update.body);
+    const verdict = await runLessonQualityJudge(run.config, extended, memory, run.options.chat, {
+        extending: target.body,
+        ...(feedback.length > 0 ? { feedback } : {}),
+        ...((run.judgeRunner ?? run.runner) ? { llmRunner: run.judgeRunner ?? run.runner } : {}),
+        ...(run.options.signal ? { signal: run.options.signal } : {}),
+        onNotices: run.notices.add,
+    });
+    if (!verdict.pass) {
+        warnVerbose(`[akm] distill update of ${target.ref} not proposed: ${verdict.reason}`);
+        return undefined;
+    }
+    // The proposal's before-hash is taken at mint: a lesson edited since it was read is not what the writer extended.
+    let proposal;
+    try {
+        if (fs.readFileSync(target.path, "utf8") !== target.content)
+            return undefined;
+        const existing = parseFrontmatter(target.content);
+        const xrefs = Array.isArray(existing.data.xrefs) ? existing.data.xrefs.map(String) : [];
+        const frontmatter = { ...existing.data, xrefs: [...new Set([...xrefs, run.inputRef])] };
+        proposal = mintProposal(run.stash, run.options.ctx, {
+            ref: target.ref,
+            source: "distill",
+            ...(run.options.sourceRun !== undefined ? { sourceRun: run.options.sourceRun } : {}),
+            payload: { content: assembleAsset(frontmatter, update.body), frontmatter },
+            ...(verdict.score > 0 ? { confidence: verdict.score / 5 } : {}),
+            ...(run.options.eligibilitySource ? { eligibilitySource: run.options.eligibilitySource } : {}),
+            attemptedRefs: [run.ledgerRef],
+        }, {
+            review: {
+                reason: "distill-update",
+                gate: "quality-gate",
+                ...(verdict.criteria ? { scores: verdict.criteria } : {}),
+                judgeReason: verdict.reason,
+            },
+        });
+    }
+    catch (error) {
+        warnVerbose(`[akm] distill update of ${target.ref} not proposed: ${error instanceof Error ? error.message : error}`);
+        return undefined;
+    }
+    emitDistill(run, {
+        outcome: "queued",
+        proposalRef: target.ref,
+        proposalKind: "lesson",
+        proposalId: proposal.id,
+        updatesExisting: true,
+        ...(run.options.sourceRun !== undefined ? { sourceRun: run.options.sourceRun } : {}),
+        ...exclusionMeta(run, false),
+    });
+    return {
+        schemaVersion: 1,
+        ok: true,
+        outcome: "queued",
+        inputRef: run.inputRef,
+        proposalRef: target.ref,
+        proposalKind: "lesson",
+        proposalId: proposal.id,
+        proposal,
+        updatesExisting: true,
+        ...exclusionMeta(run, true),
+    };
+}
 function rejectDistilled(run, proposalRef, content, score, reason, meta) {
     return writeQualityRejection({
         stash: run.stash,
@@ -667,7 +789,14 @@ export function writeQualityRejection(args) {
                 payload: { content: args.content },
                 attemptedRefs: [ledgerRef],
                 ...(args.eligibilitySource ? { eligibilitySource: args.eligibilitySource } : {}),
-            }, { review: { reason: "quality-review", gate: "quality-gate" } });
+            }, {
+                review: {
+                    reason: "quality-review",
+                    gate: "quality-gate",
+                    judgeReason: args.reason,
+                    ...(meta.criteria ? { scores: meta.criteria } : {}),
+                },
+            });
         }
         catch (error) {
             warn(`[akm] writeQualityRejection: failed to queue ${args.proposalRef} for review: ${error instanceof Error ? error.message : String(error)}`);
@@ -863,7 +992,6 @@ function stampInputSalience(run) {
                 type,
                 retrievalFreq: 0,
                 encodingSalience: scored.score,
-                outcomeWeightEnabled: run.outcomeWeightEnabled,
             })));
         }
         catch {
@@ -887,7 +1015,6 @@ function persistOutputEncodingSalience(run, ref, body) {
             type,
             retrievalFreq: 0,
             encodingSalience: scored.score,
-            outcomeWeightEnabled: run.outcomeWeightEnabled,
         })));
     }
     catch {
@@ -974,7 +1101,7 @@ async function fetchRelatedAssets(query, n) {
             catch {
                 // best-effort
             }
-            return { ref: h.ref, content };
+            return { ref: h.ref, content, ...(h.path ? { path: h.path } : {}) };
         });
     }
     catch {

package/dist/commands/improve/eligibility.js

@@ -4,6 +4,7 @@
 /** The refs an improve run may consider, read from the index, and the small predicates over them. */
 import fs from "node:fs";
 import path from "node:path";
+import { closestMatch } from "../../cli/unknown-flags.js";
 import { parseBundleRef } from "../../core/asset/asset-ref.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { conceptIdFromTypeName, parseRefInput, resolveRef, typeNameFromConceptId } from "../../core/asset/resolve-ref.js";
@@ -11,6 +12,8 @@ import { loadConfig } from "../../core/config/config.js";
 import { ConfigError, NotFoundError, rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
 import { isPathAbsent } from "../../core/path-access.js";
 import { getDbPath } from "../../core/paths.js";
+import { KNOWN_TYPES } from "../../core/recognition-util.js";
+import { warn } from "../../core/warn.js";
 import { deriveInstallations, deriveWritableBundleIds } from "../../indexer/installations.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { resolveAssetPath } from "../../indexer/walk/path-resolver.js";
@@ -210,7 +213,11 @@ async function collectEligibleRefsFromIndex(scope, stashDir, improveProfile, rea
                 indexSnapshot: ready,
             };
         }
-        const entries = getAllEntries(db, scope.mode === "type" ? scope.value : undefined).filter((indexed) => isCandidateBundle(indexed.bundleId));
+        const scoped = getAllEntries(db, scope.mode === "type" ? scope.value : undefined);
+        if (scope.mode === "type" && scope.value && scope.value !== "any" && scoped.length === 0) {
+            warnUnmatchedTypeScope(scope.value, getAllEntries(db));
+        }
+        const entries = scoped.filter((indexed) => isCandidateBundle(indexed.bundleId));
         const planned = new Map();
         const strategyFiltered = new Map();
         let memoryEligible = 0;
@@ -262,6 +269,12 @@ async function collectEligibleRefsFromIndex(scope, stashDir, improveProfile, rea
             closeDatabase(db);
     }
 }
+/** A type scope that matches no indexed asset: warn on stderr, naming the nearest real type. */
+function warnUnmatchedTypeScope(value, indexed) {
+    const types = [...new Set([...KNOWN_TYPES, ...indexed.map((entry) => entry.entry.type)])];
+    const suggestion = closestMatch(value, types, Math.max(1, Math.floor(value.length / 3)));
+    warn(`Scope "${value}" matches no asset in the stash.${suggestion ? ` Did you mean \`${suggestion}\`?` : ""}`);
+}
 /** The parent memory a `--scope <memory ref>` cleanup is restricted to. */
 export function memoryCleanupParentRef(scope, stashDir) {
     if (scope.mode !== "ref" || !scope.value)

package/dist/commands/improve/extract-cli.js

@@ -26,7 +26,7 @@ import { akmExtract, resolveStandaloneExtractPlan } from "./extract.js";
 export const extractCommand = defineJsonCommand({
     meta: {
         name: "extract",
-        description: "Experimental: extract durable insights from native session files (claude, codex, opencode) and queue them as proposals.",
+        description: "Extract durable insights from native session files (claude, codex, opencode) and queue them as proposals.",
     },
     args: {
         type: {

package/dist/commands/improve/extract-prompt.js

@@ -121,26 +121,36 @@ function formatAlreadyPreserved(inlineRefs) {
 export const TRANSCRIPT_FENCE_BEGIN = "=== BEGIN UNTRUSTED SESSION TRANSCRIPT ===";
 export const TRANSCRIPT_FENCE_END = "=== END UNTRUSTED SESSION TRANSCRIPT ===";
 /**
- * Format pre-filtered events as a transcript snippet. Each event becomes:
- *   [<role> @ <iso>] <text>
- * Events are already truncated/cleaned by the pre-filter; this is purely
- * a render step.
+ * Wrap transcript text in the untrusted fence.
  *
  * Anti-spoof: any occurrence of the fence markers inside the transcript text is
  * neutralised so a crafted session cannot forge the boundary and "escape" the
  * fence to inject trusted-looking instructions.
  */
+export function fenceTranscript(text) {
+    const body = text
+        .split(TRANSCRIPT_FENCE_BEGIN)
+        .join("=== (fence) ===")
+        .split(TRANSCRIPT_FENCE_END)
+        .join("=== (fence) ===");
+    return `${TRANSCRIPT_FENCE_BEGIN}\n${body}\n${TRANSCRIPT_FENCE_END}`;
+}
+/**
+ * Format pre-filtered events as a transcript snippet. Each event becomes:
+ *   [<role> @ <iso>] <text>
+ * Events are already truncated/cleaned by the pre-filter; this is purely
+ * a render step.
+ */
 function formatTranscript(events) {
     if (events.length === 0)
         return "(empty — pre-filter removed all events as noise)";
-    const body = events
+    return events
         .map((e) => {
         const tsLabel = e.ts ? new Date(e.ts).toISOString() : "unknown-ts";
         const roleLabel = e.role ?? "unknown";
         return `[${roleLabel} @ ${tsLabel}] ${e.text}`;
     })
         .join("\n\n");
-    return body.split(TRANSCRIPT_FENCE_BEGIN).join("=== (fence) ===").split(TRANSCRIPT_FENCE_END).join("=== (fence) ===");
 }
 /**
  * Build the user-prompt body for the extract LLM call by interpolating
@@ -164,7 +174,7 @@ export function buildExtractPrompt(input) {
         .replace("{{PROJECT_HINT}}", ref.projectHint ?? "(no project hint)")
         .replace("{{ALREADY_PRESERVED}}", formatAlreadyPreserved(input.inlineRefs))
         .replace("{{STANDARDS}}", standards)
-        .replace("{{TRANSCRIPT}}", `${TRANSCRIPT_FENCE_BEGIN}\n${formatTranscript(input.events)}\n${TRANSCRIPT_FENCE_END}`);
+        .replace("{{TRANSCRIPT}}", fenceTranscript(formatTranscript(input.events)));
 }
 function failedExtractPayload(code, message) {
     return { candidates: [], rationale_if_empty: message, parseFailure: { code, message } };