akm-cli 0.9.27-alpha.1 → 0.9.27-alpha.3

package/dist/commands/improve/distill.js

@@ -78,23 +78,29 @@ export function deriveLessonRef(inputRef) {
 // properties, so every property is required and "none" is an empty array (#1046).
 export const DISTILL_LESSON_JSON_SCHEMA = {
     type: "object",
-    required: ["description", "when_to_use", "body", "tags"],
+    required: ["reason", "decision", "description", "when_to_use", "body", "tags"],
     additionalProperties: false,
     properties: {
+        reason: {
+            type: "string",
+            description: "One sentence, written first: the cause and the fix the memory states, or why it states none.",
+        },
+        decision: {
+            type: "string",
+            enum: ["lesson", "none"],
+            description: "`none` when the memory holds no lesson (it records what was done, a design, or steps already written elsewhere): leave the other fields empty. Otherwise `lesson`.",
+        },
         description: {
             type: "string",
-            minLength: 10,
-            description: "Single complete sentence (80-200 chars) summarising what the lesson teaches. No markdown, no leading 'When'/'If'.",
+            description: "Single complete sentence summarising what the lesson teaches. No markdown, no leading 'When'/'If'. Empty for `none`.",
         },
         when_to_use: {
             type: "string",
-            minLength: 10,
-            description: "Single complete sentence describing the concrete trigger condition for the lesson.",
+            description: "Single complete sentence describing the concrete trigger condition for the lesson. Empty for `none`.",
         },
         body: {
             type: "string",
-            minLength: 1,
-            description: "Lesson body — plain markdown, 1-3 short paragraphs of practical guidance.",
+            description: "Lesson body: plain markdown, shorter than the memory, stating only what it and its feedback say. Empty for `none`.",
         },
         tags: {
             type: "array",
@@ -154,6 +160,19 @@ export function assembleStructuredDistillMarkdown(payload, kind) {
         fm.xrefs = sources;
     return assembleAssetFromString(serializeFrontmatterQuoted(fm), body);
 }
+/**
+ * The writer's answer when it found no lesson: the word NONE, or `decision: "none"` in a reply bound to the schema,
+ * with the reason it gave (`""` for the bare word). `null` for any other reply.
+ */
+function answeredNone(raw) {
+    if (/^[\s"'`*_]*none[\s.!"'`*_]*$/i.test(stripMarkdownFences(raw)))
+        return { reason: "" };
+    const payload = parseEmbeddedJsonResponse(raw);
+    if (payload === null || typeof payload !== "object" || Array.isArray(payload) || payload.decision !== "none") {
+        return null;
+    }
+    return { reason: typeof payload.reason === "string" ? payload.reason.trim() : "" };
+}
 function validateKnowledgeContent(content, inputRef) {
     const findings = [];
     const parsed = parseFrontmatter(content);
@@ -251,7 +270,7 @@ export function buildDistillPrompt(input) {
     }
     lines.push(input.proposalKind === "knowledge"
         ? "Produce the knowledge markdown file now. Start your response with `---` on the first line, followed by a `description:` field whose value is a 1-sentence summary (20–400 chars). Never use placeholder values like `---`, `tbd`, `n/a`, or a single dash. If the source has nothing meaningful to summarize, do NOT produce a proposal — return an empty response instead. The frontmatter block ends with a second `---` line; do not emit any additional `---` fences in the body."
-        : "Produce the lesson markdown file now. Start your response with `---` on the first line, followed by `description:` and `when_to_use:` fields. Both must be real one-sentence summaries (20–400 chars) — never placeholder values like `---`, `tbd`, or `n/a`. The frontmatter block ends with a second `---` line; do not emit any additional `---` fences in the body.");
+        : "Produce the lesson markdown file now. Start your response with `---` on the first line, followed by `description:` and `when_to_use:` fields. Both must be real one-sentence summaries (20–400 chars) — never placeholder values like `---`, `tbd`, or `n/a`. The frontmatter block ends with a second `---` line; do not emit any additional `---` fences in the body. If the memory holds no lesson, answer NONE instead.");
     return lines.join("\n");
 }
 // ── Invocation ───────────────────────────────────────────────────────────────
@@ -343,7 +362,7 @@ export async function akmDistill(options) {
         asset,
         vocabulary: loadRefVocabulary(),
         outcomeWeightEnabled: config.improve?.salience?.outcomeWeightEnabled !== false,
-        similar: options.fetchSimilarLessonsFn ?? fetchTopSimilarLessons,
+        related: options.fetchRelatedFn ?? fetchRelatedAssets,
         lookup,
     };
     const feedbackEvents = readDistillFeedback(run);
@@ -381,6 +400,8 @@ async function distill(run, targetKind, kind, outputRef, feedbackEvents) {
             system,
             prompt,
             gate: { config: run.config, enabled: true },
+            // NONE is an answer: a parser that rejected it would ask for a lesson again.
+            parse: (raw) => (answeredNone(raw) ? raw : parseEmbeddedJsonResponse(raw)),
             // The injected test transport never sees the schema.
             request: {
                 ...(run.options.chat === undefined
@@ -413,6 +434,10 @@ async function distill(run, targetKind, kind, outputRef, feedbackEvents) {
             ...exclusionMeta(run, true),
         };
     }
+    const none = answeredNone(call.raw);
+    if (none) {
+        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);
     if ("rejection" in assembled)
         return assembled.rejection;
@@ -422,8 +447,20 @@ async function distill(run, targetKind, kind, outputRef, feedbackEvents) {
         content: assembled.content,
         source: run.asset.content,
         descriptionSwapped: assembled.descriptionSwapped,
+        feedback: feedbackLines(feedback),
     });
 }
+/** The feedback that says something, one line each, for the judge. A bare signal says nothing the writer could use. */
+function feedbackLines(feedback) {
+    const lines = [];
+    for (const event of feedback) {
+        const meta = event.metadata ?? {};
+        const detail = (typeof meta.reason === "string" ? meta.reason : "") || (typeof meta.note === "string" ? meta.note : "");
+        if (detail.trim())
+            lines.push(`- [${typeof meta.signal === "string" ? meta.signal : event.eventType}] ${detail.trim()}`);
+    }
+    return lines;
+}
 /** Whether a file already holds the lesson `ref` in the stash the proposal would be filed in. */
 function lessonExists(run, ref) {
     const { type, name } = parseRefInput(ref);
@@ -489,11 +526,12 @@ async function judgeAndQueue(run, out) {
     let confidence;
     let judged;
     if (qualityGateEnabled(run)) {
-        const similarLessons = await run.similar(content.slice(0, 500), 3);
+        const related = await run.related(content.slice(0, 500), RELATED_COUNT);
         // The judge reads what the generator read: the source body, without its frontmatter (buildDistillPrompt).
         const source = out.source ? parseFrontmatter(out.source).content.trim() : "";
         const verdict = await runLessonQualityJudge(run.config, content, source, run.options.chat, {
-            ...(similarLessons.length > 0 ? { similarLessons } : {}),
+            ...(related.length > 0 ? { related } : {}),
+            ...(out.feedback && out.feedback.length > 0 ? { feedback: out.feedback } : {}),
             ...((run.judgeRunner ?? run.runner) ? { llmRunner: run.judgeRunner ?? run.runner } : {}),
             ...(run.options.signal ? { signal: run.options.signal } : {}),
             onNotices: run.notices.add,
@@ -873,13 +911,13 @@ function readDistillFeedback(run) {
 /** System + user prompt: rejected-proposal context, optional CLS neighbours, stash standards. */
 async function buildDistillMessages(run, feedback, kind, outputRef) {
     const rejectedProposals = rejectedProposalContext(run.stash, run.inputRef, run.options.ctx, run.options.eventsCtx);
-    // CLS interleaving (default off): show related lessons so the model does not overwrite them.
+    // CLS interleaving (default on): show the related lessons, knowledge notes and skills, so the writer neither repeats nor overwrites them.
     const cls = getImproveProcessConfig("distill", run.profile)?.cls ?? {};
     let clsContext = "";
-    if (cls.enabled) {
+    if (cls.enabled !== false) {
         try {
             const query = run.asset.content ? run.asset.content.slice(0, 500) : run.inputRef;
-            clsContext = buildClsContext(await run.similar(query, cls.adjacentCount ?? DEFAULT_CLS_ADJACENT_COUNT), cls);
+            clsContext = buildClsContext(await run.related(query, cls.adjacentCount ?? DEFAULT_CLS_ADJACENT_COUNT), cls);
         }
         catch {
             // CLS context is supplemental.
@@ -908,12 +946,18 @@ async function defaultLookup(ref, stashDir) {
         honorOrigin: false,
     });
 }
-/** Top-N existing lessons similar to `query` (empty when search is unavailable). */
-async function fetchTopSimilarLessons(query, n) {
+/** What the library already holds on a subject: lessons and knowledge notes say it, a skill is how to do it. */
+const RELATED_TYPES = ["lesson", "knowledge", "skill"];
+const RELATED_COUNT = 3;
+/** The top-N lessons, knowledge notes and skills related to `query`, best first (empty when search is unavailable). */
+async function fetchRelatedAssets(query, n) {
     try {
-        const result = await akmSearch({ query, type: "lesson", limit: n, skipLogging: true, eventSource: "improve" });
-        return (result?.hits ?? [])
+        // One search per type: memories outnumber the rest and would fill an untyped list.
+        const results = await Promise.all(RELATED_TYPES.map((type) => akmSearch({ query, type, limit: n, skipLogging: true, eventSource: "improve" })));
+        return results
+            .flatMap((result) => result?.hits ?? [])
             .filter((h) => "path" in h && typeof h.path === "string")
+            .sort((a, b) => (b.score ?? 0) - (a.score ?? 0))
             .slice(0, n)
             .map((h) => {
             let content = "";

package/dist/commands/improve/preparation.js

@@ -601,6 +601,16 @@ export function buildSnapshotManifest(args) {
     const latestNegativeTs = new Map();
     const feedback = new Map(candidates.map((r) => [r.ref, { hasSignal: false, positive: 0, negative: 0 }]));
     if (candidates.length > 0) {
+        // When each ref's accepted feedback proposals were created: a fix event is acted on once one exists at or after it.
+        const fixedAt = new Map();
+        if (stashDir) {
+            withRunState(eventsCtx, args.readOnly !== true, (db) => {
+                for (const p of listStateProposals(db, { stashDir, status: "accepted" })) {
+                    if (p.source === "feedback")
+                        fixedAt.set(p.ref, [...(fixedAt.get(p.ref) ?? []), p.createdAt]);
+                }
+            });
+        }
         for (const e of readEvents({ type: "feedback" }, eventsCtx).events) {
             const ref = e.ref ? refByKey.get(e.ref) : undefined;
             const entry = ref ? feedback.get(ref) : undefined;
@@ -612,8 +622,11 @@ export function buildSnapshotManifest(args) {
                 entry.hasSignal = true;
                 if (ts > (latestFeedbackTs.get(ref) ?? ""))
                     latestFeedbackTs.set(ref, ts);
-                if (signal === "negative" && ts > (latestNegativeTs.get(ref) ?? ""))
+                const fixApplied = e.metadata?.fix !== undefined &&
+                    (fixedAt.get(e.ref ?? "") ?? []).some((createdAt) => createdAt >= ts);
+                if (signal === "negative" && !fixApplied && ts > (latestNegativeTs.get(ref) ?? "")) {
                     latestNegativeTs.set(ref, ts);
+                }
             }
             if (signal === "positive")
                 entry.positive++;

package/dist/commands/improve/stage.js

@@ -216,28 +216,31 @@ export function resolveQualityGateJudge(config, profile, processName, onNotices)
     onNotices?.(resolved.notices);
     return resolved.runner;
 }
-/** Lesson judge prompt; similar existing lessons let it mark near-duplicates down. */
-export function buildJudgePrompt(lessonContent, sourceContent, similarLessons) {
+/** Lesson judge prompt: what the writer was given (the source and its feedback), the assets nearest the new lesson, the lesson. */
+export function buildJudgePrompt(lessonContent, sourceContent, related, feedback) {
     const lines = [
-        "You are evaluating a proposed lesson asset for an akm knowledge base.",
+        "You are evaluating a lesson an agent wrote from a memory and the feedback about it, 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. NON-REDUNDANCY: Is this lesson meaningfully different from what the source already says?",
-        "3. GROUNDING: Is the lesson about what the source asset is about? Score 1-2 only if it is about a different subject than the source; 3 if it is on the source's subject but goes beyond or corrects what the source says (it may draw on feedback you are not shown); 4-5 if the source supports it. A lesson may generalize the source's point.",
+        "1. REUSABLE: Does the lesson state a rule an agent can use on another occasion, with the reason it holds? Score 1-2 when it only records what was done, shipped, decided, found or is pending, on a date or for one build, machine or project, or how a system is set up now, however it is phrased. Score 4-5 for a rule with its reason.",
+        "2. NON-REDUNDANCY: Is the lesson new next to the existing assets shown below? Score 1-2 only when one of them already states the same rule. Assets on other subjects change nothing: score 4-5 when none is shown or none is on the same subject.",
+        "3. GROUNDING: Is every statement in the lesson stated by the source or its feedback, in any words? Check each cause, step, number, rule and limit in the lesson against them. Score 4-5 when each is stated. Score 3 when one stretches what the source says. Score 1-2 when any is in neither, when the lesson drops a limit the source states (one place checked, not confirmed, a guess) and says more than it, or when it is about another subject than the source.",
         "",
-        "Source asset content:",
+        "Source memory:",
         "```",
         // The window distill generates from (buildDistillPrompt): grounding can reject, so the judge reads all of it.
         sourceContent.slice(0, 3000),
         "```",
     ];
-    if (similarLessons && similarLessons.length > 0) {
-        lines.push("", "Existing similar lessons (top-3 by similarity). Rate NOVELTY and NON-REDUNDANCY lower if the proposed lesson is substantially similar to any of these:");
-        for (const sl of similarLessons)
-            lines.push(`\nExisting lesson ref: ${sl.ref}`, "```", sl.content.slice(0, 500), "```");
+    if (feedback && feedback.length > 0) {
+        lines.push("", "Feedback recorded about the memory (the writer saw it too):", "```", feedback.join("\n").slice(0, 1500), "```");
+    }
+    if (related && related.length > 0) {
+        lines.push("", "Existing assets nearest the new lesson (they may be on another subject):");
+        for (const asset of related)
+            lines.push(`\nExisting asset ref: ${asset.ref}`, "```", asset.content.slice(0, 600), "```");
     }
-    lines.push("", "Proposed lesson content:", "```", lessonContent.slice(0, 1000), "```", "", 'Return ONLY valid JSON, no prose: {"scores": {"novelty": <1-5 integer>, "nonRedundancy": <1-5 integer>, "grounding": <1-5 integer>}, "reason": "<one sentence>"}');
+    lines.push("", "Proposed lesson:", "```", lessonContent.slice(0, 2000), "```", "", 'Return ONLY valid JSON, no prose: {"scores": {"reusable": <1-5 integer>, "nonRedundancy": <1-5 integer>, "grounding": <1-5 integer>}, "reason": "<one sentence naming the weakest criterion>"}');
     return lines.join("\n");
 }
 function boundedDocument(content, maxChars = 6000) {
@@ -317,23 +320,19 @@ export function buildReflectJudgePrompt(candidateContent, sourceContent, feedbac
 }
 /**
  * `grounding` is scored with the other lesson criteria but left out of their
- * mean: a lesson about a different subject than its source reads as novel and
- * non-redundant, so they would pass it (or, in the review band, mint it as
- * a pending proposal). The rubric reserves 1-2 for a different subject. A score
- * of {@link UNGROUNDED_MAX_SCORE} or less is a rejection whatever the mean says
- * (#999). A higher score up to {@link BORDERLINE_GROUNDING_MAX_SCORE} is only
- * borderline: a lesson on its source's subject that advises beyond it has scored
- * 2, and a score can move a point between runs (see `runQualityJudge`), so it
- * goes to a person unless the mean alone already rejects it. A lesson that goes
- * beyond or corrects its source is on its subject: distill folds feedback into
- * the lesson, and the judge is never shown it. A contradiction of the source is
- * the optional fidelity check's to send to a human (`judgeAndQueue` in
- * distill.ts), so the rubric must not pre-empt it.
+ * mean. A lesson criterion scored {@link LESSON_REJECT_MAX_SCORE} or less is a
+ * rejection whatever the mean says: the mean would hide it (4 and 1 average
+ * 2.5, a review), and a reviewer was reading every lesson that was not rejected,
+ * 17 of 19 of them bad on 2026-10-05. The rubric reserves 1-2 for a lesson that
+ * records what was done instead of a rule, repeats an asset the library holds,
+ * or states what neither its source nor its feedback does. The judge is shown
+ * the feedback the writer saw, so a statement it supports is not an invention. A
+ * contradiction of the source is the optional fidelity check's to send to a
+ * human (`judgeAndQueue` in distill.ts).
  */
 const GROUNDING_CRITERION = "grounding";
-const UNGROUNDED_MAX_SCORE = 1;
-const BORDERLINE_GROUNDING_MAX_SCORE = 2;
-const LESSON_JUDGE_CRITERIA = ["novelty", "nonRedundancy", GROUNDING_CRITERION];
+const LESSON_REJECT_MAX_SCORE = 2;
+const LESSON_JUDGE_CRITERIA = ["reusable", "nonRedundancy", GROUNDING_CRITERION];
 const REFLECT_JUDGE_CRITERIA = ["need", "preservation", "quality"];
 /**
  * Read a judge response: the per-criterion shape (averaged here, `grounding`
@@ -390,9 +389,8 @@ export function judgeResponseSchema(keys) {
  * The quality judge. Fails closed: no runner, an unparseable verdict or a
  * provider failure never passes content. Bands: every criterion in the mean
  * >= 4 passes, otherwise a mean >= 2.5 is review and a lower one reject; a
- * `grounding` score of {@link UNGROUNDED_MAX_SCORE} or less rejects whatever
- * the mean is, and one of {@link BORDERLINE_GROUNDING_MAX_SCORE} routes a lesson
- * that would pass to review (a mean that rejects stays a rejection).
+ * lesson criterion (`grounding` included) of {@link LESSON_REJECT_MAX_SCORE}
+ * or less rejects whatever the mean is.
  * Temperature is set to 0, which reduces run-to-run variation but does not
  * remove it: on some servers (llama.cpp batching, for one) the same request can
  * score a point apart, so the routing rules are chosen with that margin in mind.
@@ -430,34 +428,18 @@ async function runQualityJudge(feature, config, prompt, keys, chat, options) {
     if (!parsed)
         return { pass: false, score: -1, reason: "judge parse failed — routed to review", reviewNeeded: true };
     const { score, lowest, reason, criteria } = parsed;
-    const grounding = criteria?.[GROUNDING_CRITERION];
-    if (criteria && grounding !== undefined && grounding <= UNGROUNDED_MAX_SCORE) {
-        return {
-            pass: false,
-            score,
-            reason: `Off-subject for its source (grounding ${grounding}/5): ${reason}`,
-            criteria,
-        };
+    // A lesson criterion at 2 or below is a defect the mean would hide (4 and 1 average 2.5, a review): it rejects.
+    if (criteria && criteria[GROUNDING_CRITERION] !== undefined) {
+        const [weakest, low] = Object.entries(criteria).sort((x, y) => x[1] - y[1])[0];
+        if (low <= LESSON_REJECT_MAX_SCORE)
+            return { pass: false, score, reason: `${weakest} ${low}/5: ${reason}`, criteria };
     }
     const verdict = lowest >= 4 ? { pass: true } : score >= 2.5 ? { pass: false, reviewNeeded: true } : { pass: false };
-    // Borderline grounding is a person's call even when the lesson would pass; a mean that rejects stays rejected.
-    if (criteria &&
-        grounding !== undefined &&
-        grounding <= BORDERLINE_GROUNDING_MAX_SCORE &&
-        (verdict.pass || verdict.reviewNeeded)) {
-        return {
-            pass: false,
-            reviewNeeded: true,
-            score,
-            reason: `Borderline on grounding (${grounding}/5), routed to review: ${reason}`,
-            criteria,
-        };
-    }
     return { ...verdict, score, reason, ...(criteria ? { criteria } : {}) };
 }
 /** Judge a proposed lesson (or knowledge promotion) against its source. */
 export function runLessonQualityJudge(config, lessonContent, sourceContent, chat, options = {}) {
-    const prompt = buildJudgePrompt(lessonContent, sourceContent, options.similarLessons);
+    const prompt = buildJudgePrompt(lessonContent, sourceContent, options.related, options.feedback);
     return runQualityJudge("lesson_quality_gate", config, prompt, LESSON_JUDGE_CRITERIA, chat, options);
 }
 /** Judge an in-place reflect revision without new-lesson novelty criteria. */

package/dist/commands/proposal/drain.js

@@ -28,6 +28,7 @@ import { info, warn } from "../../core/warn.js";
 import { DEFAULT_LLM_TIMEOUT_MS } from "../../integrations/agent/config.js";
 import { buildExecution, resolveExecution } from "../../integrations/agent/execution.js";
 import { assertRunnerCredentials, runExecution, } from "../../integrations/agent/runner-dispatch.js";
+import { nearestKnowledgeNotes } from "../improve/consolidate/coverage.js";
 import { errMessage, noticeSet } from "../improve/stage.js";
 import { akmProposalAccept, akmProposalReject } from "./proposal.js";
 import { isRetireProposal, PAIR_PASS_GATE, STALE_TARGET_GATE_REASON } from "./proposal-types.js";
@@ -57,8 +58,13 @@ function categorizeDrainFailure(message, fallback) {
  * rejection, so instead of failing identically every run it is auto-rejected
  * once; the ledger records `failed`, keeping the ref re-proposable.
  */
-async function acceptProposal(opts, proposal, id, reason, promoteFn, rejectFn) {
-    const gateDecision = { outcome: "auto-accepted", reason, gate: DRAIN_GATE };
+async function acceptProposal(opts, proposal, id, reason, promoteFn, rejectFn, judgeReason) {
+    const gateDecision = {
+        outcome: "auto-accepted",
+        reason,
+        gate: DRAIN_GATE,
+        ...(judgeReason ? { judgeReason } : {}),
+    };
     try {
         if (!opts.dryRun) {
             await promoteFn({
@@ -102,7 +108,7 @@ async function acceptProposal(opts, proposal, id, reason, promoteFn, rejectFn) {
     }
 }
 /** Reject one proposal (nothing in a dry run); the error message on failure. */
-async function rejectProposal(opts, id, reason, gateReason, rejectFn) {
+async function rejectProposal(opts, id, reason, gateReason, rejectFn, judgeReason) {
     if (opts.dryRun)
         return undefined;
     try {
@@ -110,7 +116,12 @@ async function rejectProposal(opts, id, reason, gateReason, rejectFn) {
             stashDir: opts.stashDir,
             id,
             reason,
-            gateDecision: { outcome: "auto-rejected", reason: gateReason, gate: DRAIN_GATE },
+            gateDecision: {
+                outcome: "auto-rejected",
+                reason: gateReason,
+                gate: DRAIN_GATE,
+                ...(judgeReason ? { judgeReason } : {}),
+            },
         });
         return undefined;
     }
@@ -118,8 +129,23 @@ async function rejectProposal(opts, id, reason, gateReason, rejectFn) {
         return errMessage(err);
     }
 }
-/** The judgment prompt: the proposal, the live asset it would overwrite, and same-ref siblings. */
+/**
+ * `text` as a fenced block whose fence is longer than any backtick run inside
+ * it (the CommonMark rule), so a note holding its own code block is not cut
+ * short at the first inner fence.
+ */
+export function fencedBlock(text) {
+    let longest = 2;
+    for (const run of text.match(/`+/g) ?? [])
+        if (run.length > longest)
+            longest = run.length;
+    const fence = "`".repeat(longest + 1);
+    return [fence, text, fence];
+}
+/** The judgment prompt: the proposal, the live asset it would overwrite, same-ref siblings, and for a promotion the nearest knowledge notes. */
 export function buildJudgmentPrompt(proposal, reason, ctx) {
+    // A promotion (a memory proposed as a new knowledge note) must also be durable.
+    const promotion = proposal.source === "consolidate" && ctx.liveAsset === undefined;
     const sections = [
         "You are adjudicating a pending knowledge-base proposal no quality judge has",
         "passed yet. Decide whether to accept, reject, or defer it.",
@@ -129,12 +155,10 @@ export function buildJudgmentPrompt(proposal, reason, ctx) {
         `Left for judgment because: ${reason === "needs-judgment" ? "no quality judge has passed this content yet" : reason}`,
         "",
         "## Proposed content",
-        "```",
-        proposalContent(proposal),
-        "```",
+        ...fencedBlock(proposalContent(proposal)),
     ];
     if (ctx.liveAsset !== undefined) {
-        sections.push("", "## Current live asset (would be overwritten on accept)", "```", ctx.liveAsset, "```");
+        sections.push("", "## Current live asset (would be overwritten on accept)", ...fencedBlock(ctx.liveAsset));
     }
     else {
         sections.push("", "## Current live asset", "(none — this proposal would create a new asset)");
@@ -142,10 +166,19 @@ export function buildJudgmentPrompt(proposal, reason, ctx) {
     if (ctx.siblings.length > 0) {
         sections.push("", "## Other pending proposals for the same ref (dedup context)");
         for (const sib of ctx.siblings) {
-            sections.push("", `### Sibling ${sib.id} (source: ${sib.source})`, "```", proposalContent(sib), "```");
+            sections.push("", `### Sibling ${sib.id} (source: ${sib.source})`, ...fencedBlock(proposalContent(sib)));
+        }
+    }
+    if (ctx.neighbours && ctx.neighbours.length > 0) {
+        sections.push("", "## Existing knowledge notes nearest to this promotion's source memory");
+        for (const note of ctx.neighbours) {
+            sections.push("", `### ${note.ref}`, note.description, ...fencedBlock(note.excerpt));
         }
+        sections.push("", "Reject the promotion if these notes already cover what it says, even in other words.");
     }
-    sections.push("", "## Your task", 'Return ONLY a JSON object: {"decision": "accept" | "reject" | "defer", "reason": "<short reason>"}.', "- accept: the proposed content is a correct, valuable update worth committing.", "- reject: the proposal is wrong, a duplicate, or contradicts the live asset.", "- defer: you cannot decide from the provided context (leave it pending).", "Output the JSON object and nothing else.");
+    sections.push("", "## Your task", 'Return ONLY a JSON object: {"decision": "accept" | "reject" | "defer", "reason": "<short reason>"}.', "- accept: the proposed content is a correct, valuable update worth committing.", promotion
+        ? '- reject: the proposal is wrong, a duplicate, contradicts the live asset, or is not durable: it reports the state of something that changes (a status, rollout, branch, commit, version, test count, "as of <date>"), is a plan not yet carried out, or describes something already retired, replaced or superseded. A lesson drawn from an incident is durable.'
+        : "- reject: the proposal is wrong, a duplicate, or contradicts the live asset.", "- defer: you cannot decide from the provided context (leave it pending).", "Output the JSON object and nothing else.");
     return sections.join("\n");
 }
 /** A verdict from raw runner output (the first JSON object), or null. */
@@ -205,7 +238,7 @@ async function dispatchJudgment(runner, prompt, seams) {
  * (under `applyMode` and the remaining accept budget) or the reject. A defer, an
  * unparseable verdict or a runner error leaves the item undecided.
  */
-async function runJudgmentTier(opts, result, pending, acceptBudget, promoteFn, rejectFn, seams) {
+async function runJudgmentTier(opts, result, pending, acceptBudget, promoteFn, rejectFn, seams, deferNotes) {
     const byId = new Map(pending.map((p) => [p.id, p]));
     const notices = noticeSet();
     const stillDeferred = [];
@@ -216,21 +249,33 @@ async function runJudgmentTier(opts, result, pending, acceptBudget, promoteFn, r
             stillDeferred.push(item);
             continue;
         }
+        const liveAsset = readLiveAssetContent(opts.stashDir, proposal.ref);
         const prompt = buildJudgmentPrompt(proposal, item.reason, {
-            liveAsset: readLiveAssetContent(opts.stashDir, proposal.ref),
+            liveAsset,
             siblings: pending.filter((p) => p.ref === proposal.ref && p.id !== proposal.id),
+            // A create the model otherwise judges blind: the model never sees knowledge/.
+            ...(liveAsset === undefined ? { neighbours: promotionNeighbours(opts.stashDir, proposal) } : {}),
         });
         const dispatch = await dispatchJudgment(opts.judgment, prompt, seams);
         notices.add(dispatch.notices);
         if (dispatch.error)
             warn(`[triage] judgment dispatch failed for ${item.id}: ${dispatch.error}`);
         const verdict = dispatch.error ? null : dispatch.verdict;
-        if (!verdict || verdict.decision === "defer") {
+        if (!verdict) {
+            deferNotes.set(item.id, { reason: dispatch.error ? "judgment-error" : "judgment-parse-failure" });
+            stillDeferred.push(item);
+            continue;
+        }
+        if (verdict.decision === "defer") {
+            deferNotes.set(item.id, {
+                reason: "judgment-deferred",
+                ...(verdict.reason ? { judgeReason: verdict.reason } : {}),
+            });
             stillDeferred.push(item);
             continue;
         }
         if (verdict.decision === "reject") {
-            const failure = await rejectProposal(opts, item.id, verdict.reason || "judgment: reject", "judgment-reject", rejectFn);
+            const failure = await rejectProposal(opts, item.id, verdict.reason || "judgment: reject", "judgment-reject", rejectFn, verdict.reason);
             if (failure === undefined) {
                 result.rejected.push(item.id);
             }
@@ -252,6 +297,7 @@ async function runJudgmentTier(opts, result, pending, acceptBudget, promoteFn, r
                     reason: "judgment-accept",
                     contentHash: proposalContentHash(proposal),
                     gate: DRAIN_GATE,
+                    ...(verdict.reason ? { judgeReason: verdict.reason } : {}),
                 });
                 result.staged.push(item.id);
             }
@@ -265,7 +311,7 @@ async function runJudgmentTier(opts, result, pending, acceptBudget, promoteFn, r
             result.skippedByCap.push(item.id);
             continue;
         }
-        const outcome = await acceptProposal(opts, proposal, item.id, "judgment-accept", promoteFn, rejectFn);
+        const outcome = await acceptProposal(opts, proposal, item.id, "judgment-accept", promoteFn, rejectFn, verdict.reason);
         if (outcome === "promoted") {
             result.promoted.push(item.id);
             acceptBudget -= 1;
@@ -286,6 +332,21 @@ async function runJudgmentTier(opts, result, pending, acceptBudget, promoteFn, r
         result.notices = notices.list();
     result.deferred = stillDeferred;
 }
+/** The knowledge notes nearest to a consolidate promotion's source memory; none for any other proposal. */
+function promotionNeighbours(stashDir, proposal) {
+    if (proposal.source !== "consolidate" || proposal.promotionSource === undefined)
+        return [];
+    try {
+        const parsed = parseRefInput(proposal.promotionSource);
+        const typeDir = stashDirFor(parsed.type);
+        if (!typeDir)
+            return [];
+        return nearestKnowledgeNotes(assetPathForName(parsed.type, path.join(stashDir, typeDir), parsed.name));
+    }
+    catch {
+        return [];
+    }
+}
 /** The live asset a proposal would overwrite, if any. */
 function readLiveAssetContent(stashDir, ref) {
     try {
@@ -314,8 +375,8 @@ export async function drainProposals(opts, promoteFn = akmProposalAccept, reject
     const empties = [];
     for (const proposal of pending) {
         // A consolidate pair-pass `retire` proposal is auto-accepted only when the
-        // pair judge staged it as a duplicate with nothing unique on either side
-        // (spec §25.9, equivalent content); every other one waits for a direct
+        // pair pass staged it: nothing unique on either side, confirmed by a
+        // second look, no continuity risk; every other one waits for a direct
         // `akm proposal accept` (spec §25.6). Checked before isEmptyDiff, which
         // has nothing meaningful to read on a delete-primary change.
         if (isRetireProposal(proposal)) {
@@ -324,7 +385,7 @@ export async function drainProposals(opts, promoteFn = akmProposalAccept, reject
                 staged.gate === PAIR_PASS_GATE &&
                 staged.contentHash === proposalContentHash(proposal) &&
                 !proposal.retirement?.continuityRisk) {
-                accepts.push({ id: proposal.id, reason: "duplicate" });
+                accepts.push({ id: proposal.id, reason: staged.reason });
             }
             continue;
         }
@@ -394,15 +455,22 @@ export async function drainProposals(opts, promoteFn = akmProposalAccept, reject
             }
         }
     }
+    const deferNotes = new Map();
     if (opts.judgment && result.deferred.length > 0) {
-        await runJudgmentTier({ ...opts, judgment: opts.judgment }, result, pending, cap - promotedHere, promoteFn, rejectFn, judgmentSeams);
+        await runJudgmentTier({ ...opts, judgment: opts.judgment }, result, pending, cap - promotedHere, promoteFn, rejectFn, judgmentSeams, deferNotes);
     }
     // #577: whatever stays undecided is left for review (`review_needed` in the ledger).
     if (!opts.dryRun) {
-        const reviewReason = opts.judgment ? "judgment-deferred" : "no-judge-configured";
         for (const item of result.deferred) {
+            const note = deferNotes.get(item.id);
+            const reviewReason = note?.reason ?? (opts.judgment ? "judgment-deferred" : "no-judge-configured");
             try {
-                recordGateDecision(opts.stashDir, item.id, { outcome: "deferred", reason: reviewReason, gate: DRAIN_GATE });
+                recordGateDecision(opts.stashDir, item.id, {
+                    outcome: "deferred",
+                    reason: reviewReason,
+                    gate: DRAIN_GATE,
+                    ...(note?.judgeReason ? { judgeReason: note.judgeReason } : {}),
+                });
             }
             catch (err) {
                 warn(`[triage] failed to record gate decision for ${item.id}: ${errMessage(err)}`);

package/dist/commands/proposal/proposal-types.js

@@ -53,7 +53,7 @@ export function isRetireProposal(proposal) {
 }
 /** A promote refused because the target changed after mint (STALE, R20) — not a merit judgement. */
 export const STALE_TARGET_GATE_REASON = "stale-target";
-/** The gate on a retire proposal the triage drain may accept unattended: a pair-judged duplicate. */
+/** The gate on a retire proposal the triage drain may accept unattended: a staged pair-judged retirement. */
 export const PAIR_PASS_GATE = "consolidate-pair";
 export const EXPIRED_GATE_REASON = "expired";
 export const ASSET_MISSING_GATE_REASON = "asset-missing";

package/dist/core/config/schema/improve-processes.js

@@ -78,9 +78,9 @@ const qualityGateField = z
     .optional();
 /**
  * WS-3b: CLS (Complementary Learning System) interleaving (step 9).
- * distill/memoryInference prompts include embedding-retrieved existing adjacent
- * lessons/knowledge to prevent catastrophic interference with prior generalizations.
- * Default OFF. Only meaningful on `distill` and `memoryInference` processes.
+ * The distill prompt includes the lessons, knowledge notes and skills the library already holds near the
+ * memory, so the writer answers NONE for a rule one of them states and does not overwrite a prior
+ * generalization. Default ON; `enabled: false` turns it off. Only meaningful on the `distill` process.
  */
 const clsField = z
     .object({

package/dist/core/paths.js

@@ -332,15 +332,6 @@ export function getStashStateKey(stashDir) {
 function stashScopedDir(base, stashDir) {
     return path.join(base, getStashStateKey(stashDir));
 }
-/**
- * `$STATE/improve/measurement/verdicts/<stash>/` — `akm-eval-proactive-verdict`
- * reports. Moved out of `$STASH/.akm/measurement/verdicts/` (itlackey/akm#890);
- * the pilot treatment file at `$STASH/.akm/measurement/` is manually-authored
- * measurement input and stays put.
- */
-export function getMeasurementVerdictsDir(stashDir) {
-    return stashScopedDir(path.join(getStateDir(), "improve", "measurement", "verdicts"), stashDir);
-}
 /**
  * `$CACHE/index/unresolved-sources/<stash>/` — synthetic placeholder path for
  * a configured source whose content root did not resolve this run. Never

package/dist/storage/repositories/improve-ledger-repository.js

@@ -50,11 +50,14 @@ export const CONSOLIDATE_LEDGER_SOURCE = "consolidate";
  * promotion is a verdict on that memory's text; asking the model about the
  * same text again can only reproduce the proposal (accepted used to be
  * eligible at once, rejected after 7 days), so the memory waits for an edit.
+ * So does a memory the model judged and left alone (`judged_no_action`):
+ * the same text would be judged weekly with the same answer.
  * The clock stays for a row with no recorded hash — one decided before the
  * hash was recorded — see {@link nextEligibleAt} and {@link isContentDrivenRow}.
  */
 export function isContentDrivenDecision(source, outcome) {
-    return source === CONSOLIDATE_LEDGER_SOURCE && (outcome === "accepted" || outcome === "rejected");
+    return (source === CONSOLIDATE_LEDGER_SOURCE &&
+        (outcome === "accepted" || outcome === "rejected" || outcome === "judged_no_action"));
 }
 /**
  * Whether this row is held by its content hash: a decided consolidate