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

package/CHANGELOG.md

@@ -6,6 +6,118 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.27-alpha.2] - 2026-10-07
+
+### Removed
+
+- **The `scripts/akm-eval` toolkit has moved out of this repository.** The
+  read-only measurement toolkit (the case runner and its suites, the twin
+  experiment, the real-query verdict for the proactive lane, the state
+  analyzers and the curate benchmark) is retired; every live eval is in
+  [itlackey/akm-eval](https://github.com/itlackey/akm-eval). Its code is kept
+  there, to read and not to run, in `retired/akm-scripts-akm-eval/`, copied from
+  commit `f57a7fd44b37`. It imports akm's `src/` by relative path, so it runs
+  only in a checkout at that commit. Removed here with it: `scripts/akm-eval/`,
+  its tests (`tests/integration/akm-eval/`, `tests/akm-eval-*.test.ts`,
+  `tests/curate-metrics.test.ts`) and fixtures (`tests/fixtures/akm-eval/`, and
+  the `curate-golden` stash, which only the curate benchmark read), the
+  `akm-eval determinism` CI job, and `getMeasurementVerdictsDir`, whose only
+  caller was the verdict runner. akm no longer names
+  `$STATE/improve/measurement/verdicts/<stash>/`; a file already there is inert.
+  `docs/maintainers/eval.md` is now a pointer to the new home.
+
+### Fixed
+
+- **The drain's judge no longer sees a note with a code block as truncated.**
+  The judgment prompt fenced the proposed content (and the live asset, sibling
+  proposals and neighbour excerpts) in three backticks, so a note holding its
+  own code block closed the fence early and read as cut off; real rejections said
+  "ends in an empty code block" or "truncated". Each block now uses a fence longer
+  than any backtick run inside it. The judge's reason is also kept on accepts,
+  staged accepts and defers (as the gate decision's `judgeReason`, until now
+  rejections only), and a judge reply that is not a verdict is stamped
+  `judgment-parse-failure`, and a runner failure `judgment-error`, instead of
+  looking like a defer.
+
+- **Distill writes a lesson only when its memory holds one, says only what the
+  memory says, and its judge rejects what a reviewer would.** 2 of the 22 distill
+  proposals since 0.9.26 began were accepted, and 17 of the 19 queued on
+  2026-10-05 were bad (they restated their memory, filed a dated status as a
+  lesson, claimed what the memory does not say, or repeated an asset the library
+  holds). Four causes, found in the code and the rejected proposals, and fixed:
+  (1) the prompt and schema forced a lesson from every memory, and 18 of the 19
+  were records of what was done; the writer now says why a memory holds a
+  lesson or none (`reason`, then `decision: lesson|none`, or the word `NONE`),
+  defined as a cause and what to do about it, or a rule with its reason, and
+  writes only what the memory and its feedback state, in the scope they have; a
+  `NONE` is a `skipped` distill (`skipReason: nothing_reusable`, the writer's
+  reason in the message) with no proposal and no judge call, and the loop keeps
+  its ledger row `unchanged`. (2) The judge asked for "information not already
+  present in the source", so an invented claim scored as novel and a faithful
+  lesson of a lesson-worthy memory as a restatement, and it passed anything that
+  "goes beyond the source" because it "may draw on feedback you are not shown".
+  The rubric is now reusable (a rule with its reason, not a record of what was
+  done), non-redundancy and grounding (every cause, step, number and limit is
+  in the source or its feedback), and the judge is shown the feedback the writer
+  saw. (3) A mean hid a decisive score (4 and 1 average 2.5, a review), and a
+  reviewer read everything the judge did not reject; any criterion at 2 or
+  below, grounding included, is now `quality_rejected`, and the reason names it
+  (`grounding 2/5: …`). The "borderline grounding" routing is gone. (4) Neither
+  the writer nor the judge could see a knowledge note or a skill that already
+  states the rule (the judge saw the 3 lexically nearest lessons, none of them
+  related); both now see the lessons, knowledge notes and skills nearest the
+  memory, which is the existing `processes.distill.cls` context turned on by
+  default (`enabled: false` turns it off). Judge scores are keyed `reusable`
+  where they were `novelty`. Measured on the local qwen3.8-27b with akm-eval's
+  `evals/distill` (30 fictional memories, 5 runs each side): good lessons 7/14 on
+  average (5 to 9) against 3.7/14 (3 to 5), lessons queued for memories that
+  deserve none 0.4/16 against 3.3/16. On 37 real memories with their feedback
+  (34 reviewed bad, 3 good; 3 runs against 2): a lesson was queued for 11% of the
+  bad ones against 44%, and for 6 of 9 good ones against 4 of 6; of the memories
+  that pass 0.9.26's skip of bare positive feedback, 20% of the bad against 50%.
+  No new settings.
+
+- **Reflect no longer plans an asset whose negative feedback is already acted
+  on.** A negative `akm feedback` that came with an exact fix (`--replace` and
+  `--with`, `--outdated` or `--superseded-by`) makes a `feedback` proposal, and
+  once that proposal is accepted the feedback has done its work. Reflect still
+  took the ref as having fresh negative feedback, and on 2026-10-07 44 of its 50
+  refs were of that kind: the judge refused or the model changed nothing for
+  most of them. A negative event with a fix is now left out of the reflect
+  cursor when an accepted `feedback` proposal for the ref was created at or
+  after it. A negative with no fix, one given after the proposal, and one whose
+  proposal is still pending or was rejected plan a reflect as before.
+
+- **Consolidate stops re-offering memories a reviewer already turned down, and
+  the nightly judge sees what a promotion may duplicate.** About 53 promotions a
+  night reached review at ~5% precision, 64-70% of them a memory body already
+  proposed or rejected. Four causes, four changes: a memory whose body equals
+  that of a consolidate promotion rejected on or after 2026-09-29 is held until
+  its body changes, under any name (earlier rejections, the bulk audits of
+  2026-08, do not count); a memory the model judged and left alone is held by its
+  body hash instead of a 7-day clock, so an unchanged memory is no longer judged
+  every week (a row recorded without a hash keeps the 7 days); the coverage gate
+  skips a memory when 30% of its text, not 50%, is in a neighbouring knowledge
+  doc, which catches paraphrases; and the drain's judgment tier, which judged a
+  promotion seeing only the proposal and never `knowledge/`, is now shown the 5
+  nearest knowledge notes (ref, description, excerpt) and told to reject a
+  promotion they already cover. No new settings.
+
+- **A confident `subsumed` or `supersedes` retirement resolves unattended, as a
+  `duplicate` already did.** The pair pass staged a retire proposal for the
+  triage drain only when the judge's label was `duplicate`; every other retirement
+  waited for a person. It now stages any of the three retire labels when the
+  second look (what does the retired note hold that the kept one lacks?) comes
+  back empty and there is no continuity risk; the retired side's claim list is
+  already empty for any proposal, and a `duplicate` must still have an empty list
+  on the kept side too. The staged gate reason is the judge's label, and the drain records it. Replay over 360
+  judged pairs: 336 safe (0.93): `duplicate` 0.98, `subsumed` 0.92, `supersedes`
+  0.875. In production, unstaged `subsumed` retirements were accepted 45 of 54
+  times by hand, and in the latest run 41 of 47 pair proposals would have resolved
+  without a person. `docs/architecture/internals/improve-workflow.md` said triage
+  never auto-accepts a retire proposal, which stopped being true in 0.9.26; it,
+  and the matching lines in `improvement.md`, now describe the staging rule.
+
 ## [0.9.27-alpha.1] - 2026-10-06
 
 ### Fixed

package/LICENSE

@@ -225,10 +225,9 @@ statute, judicial order, or regulation then You must: (a) comply with
 the terms of this License to the maximum extent possible; and (b)
 describe the limitations and the code they affect. Such description must
 be placed in a text file included with all distributions of the Covered
-Software under the name "LEGAL", with additions for new restrictions
-placed at the end of the file. Except to the extent prohibited by
-statute or regulation, such description must be sufficiently detailed
-for a recipient of ordinary skill to be able to understand it.
+Software under this License. Except to the extent prohibited by statute
+or regulation, such description must be sufficiently detailed for a
+recipient of ordinary skill to be able to understand it.
 
 5. Termination
 --------------

package/dist/assets/prompts/distill-lesson-system.md

@@ -1,7 +1,29 @@
 You are the akm `distill` distiller.
-Given an asset and recent feedback events about it, produce a single
-concise *lesson* an agent should remember next time it works on this
-asset's domain.
+You are given a memory and the feedback recorded about it. Decide whether it
+holds a lesson and, if it does, write the lesson.
+
+A memory holds a lesson when it states a cause and what to do about it: a
+failure or surprise with its cause and the fix that worked, or a rule with the
+reason it holds. It holds a lesson even when it is short and names one project,
+tool or incident, if the cause and the fix would help someone in a similar
+situation.
+
+A memory holds NO lesson when all it states is what was done, shipped, released
+or decided, what is pending or planned, how a system is set up now, or the steps
+of a procedure, with no failure and cause behind it, or when its feedback says
+only that it is out of date or superseded. ANSWER NONE then: the single word and
+nothing else. A reply bound to a JSON schema answers NONE by
+setting `decision` to `none` and leaving the other fields empty. Answer NONE too
+when a related asset listed below the memory already states the rule the memory
+would give.
+
+When the memory holds a lesson, write it from what the memory and its feedback
+say, and nothing more:
+- Add no cause, step, rule, number, check or safeguard that neither states.
+- Keep the scope the memory has. A fix verified in one place is a fix for that
+  place, and what was not checked stays unchecked. One case is not "always" or
+  "never".
+- Be shorter than the memory.
 
 YOUR RESPONSE MUST START EXACTLY WITH `---` ON THE VERY FIRST LINE.
 DO NOT output any prose, explanation, or code fences before or after.
@@ -12,7 +34,7 @@ description: <one complete sentence (ending with `.`) summarising what the lesso
 when_to_use: <one complete sentence describing the concrete trigger condition>
 ---
 
-<lesson body — plain markdown, 1–3 short paragraphs of practical guidance>
+<lesson body — plain markdown, as short as the memory allows>
 
 ## description field (MANDATORY)
 - A single complete sentence in present tense, 20–400 chars, NO markdown.
@@ -21,7 +43,7 @@ when_to_use: <one complete sentence describing the concrete trigger condition>
 - DO NOT copy a section heading ("Key takeaways", "For example", "Key pitfalls").
 - DO NOT begin with a numbered list marker, code fence, or markdown heading.
 
-GOOD: "Always validate ref existence before promoting a memory to knowledge; missing refs surface as silent 404s during accept."
+GOOD: "Pin the container image tag, because the `latest` tag moved under the nightly job and its output changed with no code change."
 BAD:  "Key pitfalls"
 BAD:  "When working with the akm CLI"
 BAD:  "For example, you might..."
@@ -32,5 +54,5 @@ RULES:
 - `description` and `when_to_use` MUST differ from each other.
 - The lesson body MUST be non-empty markdown prose. Do NOT restate `description:` or `when_to_use:` inside the body (no `**description:** ...` or `**when_to_use:** ...` lines — the frontmatter is the only place those keys belong).
 - Do NOT emit a second `---` fence after the opening frontmatter — there are exactly two `---` lines in the output, both belonging to the single frontmatter block at the top.
-- Do NOT reproduce the source asset verbatim — distil what a caller needs to know.
-- Output ONLY the lesson file. No preamble, no code fences, no trailing prose.
+- Do NOT reproduce the source asset verbatim.
+- Output ONLY the lesson file. No preamble, no code fences, no trailing prose.

package/dist/commands/improve/consolidate/coverage.js

@@ -6,7 +6,7 @@
  * `knowledge/` proposal, ask whether `knowledge/` already says it.
  *
  * The rule: a memory is covered when at least {@link COVERAGE_MIN_CONTAINMENT}
- * (half) of its distinct {@link COVERAGE_SHINGLE_WORDS}-word shingles appear in
+ * (30%) of its distinct {@link COVERAGE_SHINGLE_WORDS}-word shingles appear in
  * one of the knowledge docs nearest to it. It is a containment of the MEMORY in
  * the doc, not a similarity: a long guide that quotes the memory covers it; a
  * memory that quotes a short doc and adds claims of its own does not.
@@ -25,9 +25,13 @@
  * this gate achieves: it reads only the {@link PAIR_NEIGHBOR_FETCH_K} nearest
  * knowledge docs (below), and a covering doc that ranks lower goes unseen. The
  * recall over that candidate set is unmeasured. The rest of the rejected
- * proposals (paraphrases, partial overlaps) still reach review: the next cut
- * measured, 0.2 (169 of 224 rejected), would also have skipped 2 of the 103
- * accepted ones, and no cosine cut was measured at all. A wrong skip is a
+ * proposals (paraphrases, partial overlaps) still reach review. 0.5 let
+ * paraphrases through: of the 54 promotions minted on 2026-10-07, 18 of the 51
+ * later rejected held 30% or more of their text in a neighbouring doc. The cut is
+ * now 0.3, between the two measured points: 0.2 (169 of 224 rejected) also
+ * skipped 2 of the 103 accepted ones. At 0.3, none of the 5 promotions graded
+ * good in the 2026-10-05 review sample would be skipped (their best doc holds
+ * at most 1% of them) while 5 of its 15 bad ones would. A wrong skip is a
  * promotion nobody gets to review.
  *
  * Candidates are the memory's {@link PAIR_NEIGHBOR_FETCH_K} nearest knowledge
@@ -49,7 +53,7 @@ import { PAIR_NEIGHBOR_FETCH_K } from "./pair-pass.js";
 /** Words per shingle. */
 export const COVERAGE_SHINGLE_WORDS = 5;
 /** Share of a memory's distinct shingles one knowledge doc must hold for the memory to count as covered. */
-export const COVERAGE_MIN_CONTAINMENT = 0.5;
+export const COVERAGE_MIN_CONTAINMENT = 0.3;
 const WORD = /[\p{L}\p{N}]+/gu;
 /** The distinct lower-cased word n-grams of `text`; empty when it has fewer than {@link COVERAGE_SHINGLE_WORDS} words. */
 export function wordShingles(text) {
@@ -72,19 +76,15 @@ export function shingleContainment(memory, doc) {
     return shared / memory.size;
 }
 /**
- * The best-covering knowledge doc among the {@link PAIR_NEIGHBOR_FETCH_K}
- * knowledge docs in `bundleId` nearest to the memory. `filePath` is the
- * memory's indexed file; a memory the index does not know has no stored vector
- * and so no candidates.
+ * The {@link PAIR_NEIGHBOR_FETCH_K} knowledge docs in `bundleId` nearest to the
+ * memory at `filePath`, nearest first. A memory the index does not know has no
+ * stored vector and so no neighbours.
  */
-export function findCoveringKnowledge(db, bundleId, filePath, body) {
-    const shingles = wordShingles(body);
-    if (shingles.size === 0)
-        return undefined;
+function knowledgeNeighbours(db, bundleId, filePath) {
     const entryId = getEntryIdByFilePath(db, filePath);
     if (entryId === undefined)
-        return undefined;
-    let best;
+        return [];
+    const out = [];
     for (const hit of getNeighborsByEntryId(db, entryId, PAIR_NEIGHBOR_FETCH_K, { type: "knowledge", bundleId })) {
         const neighbour = getEntryById(db, hit.id);
         if (!neighbour)
@@ -96,13 +96,67 @@ export function findCoveringKnowledge(db, bundleId, filePath, body) {
         catch {
             continue; // the index outlived the file
         }
-        const containment = shingleContainment(shingles, stripFrontmatterBody(raw));
+        out.push({
+            ref: neighbour.conceptId,
+            description: neighbour.entry.description ?? "",
+            body: stripFrontmatterBody(raw),
+        });
+    }
+    return out;
+}
+/**
+ * The best-covering knowledge doc among the {@link PAIR_NEIGHBOR_FETCH_K}
+ * knowledge docs in `bundleId` nearest to the memory. `filePath` is the
+ * memory's indexed file; a memory the index does not know has no stored
+ * vector and so no candidates.
+ */
+export function findCoveringKnowledge(db, bundleId, filePath, body) {
+    const shingles = wordShingles(body);
+    if (shingles.size === 0)
+        return undefined;
+    let best;
+    for (const neighbour of knowledgeNeighbours(db, bundleId, filePath)) {
+        const containment = shingleContainment(shingles, neighbour.body);
         if (containment >= COVERAGE_MIN_CONTAINMENT && (best === undefined || containment > best.containment)) {
-            best = { ref: neighbour.conceptId, containment };
+            best = { ref: neighbour.ref, containment };
         }
     }
     return best;
 }
+/** Knowledge docs a reviewer is shown for a promotion, nearest first. */
+export const NEIGHBOUR_NOTE_COUNT = 5;
+const NEIGHBOUR_EXCERPT_CHARS = 300;
+/**
+ * The knowledge notes nearest to the memory at `memoryPath`, for the drain's
+ * judge to compare a promotion against: the nearest {@link NEIGHBOUR_NOTE_COUNT}
+ * of the same candidates the coverage gate reads. The memory's bundle is the one
+ * the index recorded for it. Empty when the index has no vector for the memory
+ * or cannot be opened; never throws.
+ */
+export function nearestKnowledgeNotes(memoryPath) {
+    let db;
+    try {
+        db = openExistingDatabase();
+        const entryId = getEntryIdByFilePath(db, memoryPath);
+        const bundleId = entryId === undefined ? undefined : getEntryById(db, entryId)?.bundleId;
+        if (bundleId === undefined)
+            return [];
+        return knowledgeNeighbours(db, bundleId, memoryPath)
+            .slice(0, NEIGHBOUR_NOTE_COUNT)
+            .map((n) => ({
+            ref: n.ref,
+            description: n.description,
+            excerpt: n.body.length > NEIGHBOUR_EXCERPT_CHARS ? `${n.body.slice(0, NEIGHBOUR_EXCERPT_CHARS)}...` : n.body,
+        }));
+    }
+    catch {
+        return [];
+    }
+    finally {
+        if (db)
+            closeDatabase(db);
+    }
+}
 /**
  * The gate for one run, holding its own read handle on `index.db` for the
  * promotions that run emits; `undefined` when there is no bundle or no index

package/dist/commands/improve/consolidate/pair-pass.js

@@ -503,7 +503,7 @@ function checkSection(label, side) {
     ].join("\n");
 }
 /**
- * The second look a duplicate gets before it may retire unattended: one call
+ * The second look a retirement gets before it may retire unattended: one call
  * that asks only what the retired note holds that the kept one lacks. True
  * only on a clean, empty answer (it caught 2 of 4 duplicates the judge got
  * wrong, and held back none of 109 right ones).
@@ -658,17 +658,20 @@ async function judgeOne(ctx, candidate) {
         }, ctx.opts.proposalsCtx);
         ctx.retired.push(proposal.id);
         ctx.perInitiatorProposed.add(candidate.initiator.ref);
-        // A duplicate with nothing unique on either side, confirmed by a second
-        // look, is the one class that retires unattended (109 of 111 safe on the
-        // owner's reviewed pairs, 2026-10-04): the triage drain accepts it under
-        // its usual applyMode. Every other retirement waits for a person.
-        if (verdict.relation === "duplicate" &&
-            verdict.onlyInA.length + verdict.onlyInB.length === 0 &&
+        // A retirement the second look confirms loses nothing retires unattended:
+        // the triage drain accepts it under its usual applyMode. The retired side
+        // holds no claim of its own for any label (`decideRetirement` mints nothing
+        // else); a duplicate must also leave the kept side with none, while a
+        // subsumed or superseding successor holds more by definition. Replay
+        // precision 336/360 (duplicate 0.98, subsumed 0.92, supersedes 0.875,
+        // 2026-10-07); a duplicate alone was 109 of 111 safe on the owner's
+        // reviewed pairs (2026-10-04). Anything else waits for a person.
+        if ((verdict.relation !== "duplicate" || verdict.onlyInA.length + verdict.onlyInB.length === 0) &&
             !continuityRisk &&
             (await confirmNothingLost(ctx, retired, successor))) {
             recordGateDecision(ctx.stashDir, proposal.id, {
                 outcome: "staged",
-                reason: "duplicate",
+                reason: verdict.relation,
                 gate: PAIR_PASS_GATE,
                 contentHash: proposalContentHash(proposal),
             }, ctx.opts.proposalsCtx);

package/dist/commands/improve/consolidate.js

@@ -260,6 +260,39 @@ function loadPendingConsolidateProposalHashes(stashDir, proposalsCtx) {
     }
     return hashes;
 }
+/**
+ * Rejections decided before this are not a verdict on the memory's text: the
+ * 2026-08-02 and 2026-08-18 bulk audits rejected hundreds of promotions
+ * wholesale, and holding their bodies would skip good memories for good.
+ */
+const REJECTED_BODY_HOLD_FROM = "2026-09-29";
+/**
+ * Body hashes of the memories whose promotion was rejected on review. A
+ * proposal minted with `promotionSourceHash` names the memory's raw body; an
+ * older one is hashed from its own body, which is the memory's unless
+ * sanitization changed it.
+ */
+function loadRejectedPromotionBodyHashes(stashDir, proposalsCtx) {
+    const hashes = new Set();
+    try {
+        for (const p of listProposalsReadOnly(stashDir, { status: "rejected", includeArchive: true }, proposalsCtx)) {
+            if (p.source !== "consolidate")
+                continue;
+            if ((p.review?.decidedAt ?? p.updatedAt) < REJECTED_BODY_HOLD_FROM)
+                continue;
+            try {
+                hashes.add(p.promotionSourceHash ?? contentHash(proposalContent(p), "body"));
+            }
+            catch {
+                // A malformed payload cannot hold a memory.
+            }
+        }
+    }
+    catch {
+        // Best-effort: a failed read never blocks judging.
+    }
+    return hashes;
+}
 /**
  * Body hashes of the live knowledge assets, read from disk (the index may lag
  * a just-written asset), so an accepted promotion is not proposed again.
@@ -469,6 +502,18 @@ export function inspectConsolidationPool(opts, stashDir, warnings, existingKnowl
             return !isLedgerBlocked(row, nowIso, changedAt);
         });
     }
+    // A memory whose text a reviewer already rejected as a promotion waits for an edit, whatever it is called.
+    const rejectedBodies = loadRejectedPromotionBodyHashes(stashDir, opts.proposalsCtx);
+    if (rejectedBodies.size > 0) {
+        memories = memories.filter((memory) => {
+            try {
+                return !rejectedBodies.has(contentHash(fs.readFileSync(memory.filePath, "utf8"), "body"));
+            }
+            catch {
+                return true;
+            }
+        });
+    }
     const judgedUnchanged = poolSize - memories.length;
     // Only what retrieval returned or new material improve never processed (#986).
     const retrievalScope = loadRetrievalScope({ proposalsCtx: opts.proposalsCtx, readOnly }, stashDir);
@@ -768,7 +813,13 @@ async function consolidate(opts, config, stashDir, startMs, stateDb) {
     recordLedgerAttempt({ proposalsCtx: opts.proposalsCtx }, [...acc.judgedRefs]
         .filter((ref) => !ctx.promotedSourceRefs.has(ref) &&
         !acc.skipReasonByRef.get(ref)?.skips.some((skip) => skip.reason === "promote_create_failed"))
-        .map((ref) => ({ stashDir, ref, source: "consolidate", outcome: "judged_no_action" })));
+        .map((ref) => ({
+        stashDir,
+        ref,
+        source: "consolidate",
+        outcome: "judged_no_action",
+        ...bodyHashOf(ctx.memoryByRef.get(ref)),
+    })));
     return makeConsolidateResult({
         ...summary(),
         promoted: ctx.promoted,
@@ -783,6 +834,17 @@ async function consolidate(opts, config, stashDir, startMs, stateDb) {
         },
     });
 }
+/** The memory's current body hash as a ledger input field; empty when it cannot be read (the row then keeps its 7-day window). */
+function bodyHashOf(memory) {
+    if (!memory)
+        return {};
+    try {
+        return { contentHash: contentHash(fs.readFileSync(memory.filePath, "utf8"), "body") };
+    }
+    catch {
+        return {};
+    }
+}
 /** The conceptId a ref maps to, or undefined for an invalid ref. */
 function conceptIdForRef(ref) {
     try {

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

@@ -2,25 +2,24 @@
 // 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 guards: related lessons/knowledge shown to the model so it does not
- * overwrite prior generalizations (CLS context), and a cheap check that a
- * proposal does not contradict the memories it came from.
+ * 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.
  */
 export const DEFAULT_CLS_ADJACENT_COUNT = 3;
-/** The CLS prompt section (each entry capped at 400 chars); empty when disabled or nothing is related. */
+/** The CLS prompt section (each entry capped at 600 chars); empty when disabled (on unless `enabled: false`) or nothing is related. */
 export function buildClsContext(adjacentItems, config) {
-    if (!config.enabled || adjacentItems.length === 0)
+    if (config.enabled === false || adjacentItems.length === 0)
         return "";
     const lines = [
         "",
-        "## Existing adjacent lessons / knowledge (CLS context)",
-        "The following are semantically related entries already in the stash.",
-        "Your proposal MUST NOT contradict or silently overwrite these — if you",
-        "disagree with one, flag it as contradicted (do not ignore it).",
+        "## Related assets already in the library",
+        "The library already holds these lessons, knowledge notes and skills near this memory. They may be about another subject.",
+        "If one of them already states the rule the memory would give, answer NONE. Do not contradict or overwrite them.",
         "",
     ];
     for (const item of adjacentItems)
-        lines.push(`### ${item.ref}`, item.content.trim().slice(0, 400), "");
+        lines.push(`### ${item.ref}`, item.content.trim().slice(0, 600), "");
     return lines.join("\n");
 }
 /**

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,7 +129,20 @@ 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) {
     const sections = [
         "You are adjudicating a pending knowledge-base proposal no quality judge has",
@@ -129,12 +153,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,8 +164,15 @@ 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.");
     return sections.join("\n");
@@ -205,7 +234,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 +245,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 +293,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 +307,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 +328,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 +371,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 +381,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 +451,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

package/docs/README.md

@@ -49,7 +49,6 @@ Working on akm itself, not just using it.
 
 - [Maintainer Docs](https://github.com/itlackey/akm/blob/main/docs/maintainers/README.md) -- Start here: local development, measuring improvement, and the curate contract
 - [Local Development](https://github.com/itlackey/akm/blob/main/docs/maintainers/local-development.md) -- Dogfooding akm while editing its own source
-- [akm-eval](https://github.com/itlackey/akm/blob/main/docs/maintainers/eval.md) -- Standalone toolkit for measuring whether `akm improve` is working
 - [Curate Workmap](https://github.com/itlackey/akm/blob/main/docs/maintainers/curate-workmap.md) -- The current `akm curate` contract and the highest-value next fixes
 
 ## Look up details
@@ -100,7 +99,7 @@ Source articles for the dev.to publishing pipeline (historical record). See
 - [itlackey/akm-registry](https://github.com/itlackey/akm-registry) -- the official registry index that powers built-in discovery
 - [itlackey/akm-plugins](https://github.com/itlackey/akm-plugins) -- optional integrations for tools like OpenCode
 - [itlackey/akm-bench](https://github.com/itlackey/akm-bench) -- the standalone benchmark harness for measuring agent performance with akm
-- [itlackey/akm-eval](https://github.com/itlackey/akm-eval) -- the eval framework and tools for akm asset quality (distinct from the in-repo [`scripts/akm-eval/` toolkit](https://github.com/itlackey/akm/blob/main/docs/maintainers/eval.md))
+- [itlackey/akm-eval](https://github.com/itlackey/akm-eval) -- the eval framework and tools for akm asset quality
 
 ---
 

package/docs/integration/bundling-akm.md

@@ -266,7 +266,7 @@ rather than rely on `$HOME`-derived defaults (names verified against
 | `AKM_CONFIG_DIR` | `config.json`'s directory. |
 | `AKM_DATA_DIR` | Durable, non-regenerable data: **`index.db` and `state.db` live here.** This is the directory a migration snapshot's safety copy sits beside. |
 | `AKM_CACHE_DIR` | Regenerable cache: registry downloads, config backups, task logs. Safe to discard between image builds (not between boots of the same running install). |
-| `AKM_STATE_DIR` | **Not** where `state.db` lives, despite the name — this is the XDG "state" directory. Holds scheduled-task invocation context, companion-plugin hook state (Claude Code / OpenCode hook logs), and, per stash, `akm improve`'s machine-local writers (`improve/measurement/verdicts/`) and whole-run lock (`locks/`) — see [Storage locations](https://github.com/itlackey/akm/blob/main/docs/architecture/internals/storage-locations.md). Set it anyway if you schedule akm tasks inside the image, so that context is captured consistently rather than falling back to `$HOME/.local/state/akm`. |
+| `AKM_STATE_DIR` | **Not** where `state.db` lives, despite the name — this is the XDG "state" directory. Holds scheduled-task invocation context, companion-plugin hook state (Claude Code / OpenCode hook logs), and, per stash, `akm improve`'s whole-run lock (`locks/`) — see [Storage locations](https://github.com/itlackey/akm/blob/main/docs/architecture/internals/storage-locations.md). Set it anyway if you schedule akm tasks inside the image, so that context is captured consistently rather than falling back to `$HOME/.local/state/akm`. |
 
 Set all five to paths that persist across container restarts (a mounted
 volume), or `akm migrate apply` will see an empty `state.db` on every boot

package/docs/migration/v0.8-to-v0.9.md

@@ -144,7 +144,9 @@ step is idempotent — a second run reports nothing pending. 0.9.17-alpha.4
 removed that step: `akm migrate` no longer relocates these files, and one left
 at an old path is inert (nothing reads it). Two of the five writers no longer
 exist either — the improve ledger replaced `distill-rejected/`, and the
-write-only `eval-cases/` path was removed.
+write-only `eval-cases/` path was removed. A third, `measurement/verdicts/`, went
+with the `scripts/akm-eval` toolkit that wrote it, which has since left this
+repository ([akm-eval](https://github.com/itlackey/akm/blob/main/docs/maintainers/eval.md)).
 `$STASH/.akm/memory-cleanup/` did not move; it is the one confirmed exception
 to the rule (see Storage locations, above).
 

package/docs/reference/README.md

@@ -17,4 +17,4 @@ Authoritative reference documentation for the akm CLI and its data.
 - [Website Sources](https://github.com/itlackey/akm/blob/main/docs/reference/website-sources.md) -- The pluggable fetcher API behind `akm import <url>` and other URL-based knowledge reads
 - [Data & Telemetry](data-and-telemetry.md) -- Exactly what akm reads and writes on your machine (no remote telemetry)
 
-See also: [akm-eval](https://github.com/itlackey/akm/blob/main/docs/maintainers/eval.md) -- the standalone toolkit for measuring whether `akm improve` is working (maintainer docs), and the repo-root [Roadmap](https://github.com/itlackey/akm/blob/main/ROADMAP.md) -- high-level focus for upcoming releases.
+See also: [akm-eval](https://github.com/itlackey/akm-eval) -- the evals and benchmarks for measuring whether `akm improve` is working, and the repo-root [Roadmap](https://github.com/itlackey/akm/blob/main/ROADMAP.md) -- high-level focus for upcoming releases.

package/docs/reference/cli.md

@@ -2492,16 +2492,19 @@ day; an asset a stage looked at and left unchanged is revisited after 7 days,
 or as soon as new feedback (or, for consolidation, an edit) arrives.
 
 Consolidation's promotion of a memory into `knowledge/` is the exception to the
-7-day rule: once a promotion is accepted or rejected, its memory is not offered
-to the model again until its body changes, however long that takes. The ledger
+7-day rule: once a promotion is accepted or rejected, or the model judged the
+memory and proposed nothing, the memory is not offered to the model again until
+its body changes, however long that takes. The ledger
 records the body hash the promotion was decided against and compares it with
 the memory's current body (frontmatter edits do not count), the same
 content-driven rule the consolidate pair pass uses. A promotion decided by an
-older release, which recorded no hash, keeps the old windows. Consolidation
+older release, which recorded no hash, keeps the old windows. A memory whose
+body equals that of a consolidate promotion rejected on or after 2026-09-29 is
+held the same way, under whatever name it has. Consolidation
 also does not promote a memory that `knowledge/` already covers: before it
 queues a promotion it compares the memory with the 20 `knowledge/` docs in its
 bundle nearest to it by stored vector, and skips the memory when one of them
-holds at least half of its distinct 5-word shingles (skip reason
+holds at least 30% of its distinct 5-word shingles (skip reason
 `dedup_covered_by_knowledge` in the result's `consolidation.skipReasons`). A
 covering doc that ranks lower than the 20th nearest goes unseen. With no stored
 vector (semantic search off, or the memory not indexed yet) that check does

package/docs/reference/data-and-telemetry.md

@@ -195,7 +195,7 @@ the set of types the code actually emits at HEAD (verified against every
 | `reflect_completed` | Reflect phase produced a proposal | `ref` |
 | `improve_reflect_outcome` | Per-asset reflect result | `ref`, `ok`, `durationMs`, `reason` |
 | `propose_invoked` | `akm proposal new` | `ref` |
-| `distill_invoked` | Distill phase inside the `akm improve`/`akm proposal new` pipeline. **`akm distill` is not a CLI command** — there is no standalone verb by that name | `ref`, outcome (`queued`, `skipped` with a `skipReason` such as `lesson_exists` or `conflict_noop`, `llm_failed`, `validation_failed`, `quality_rejected`, `review_needed`) |
+| `distill_invoked` | Distill phase inside the `akm improve`/`akm proposal new` pipeline. **`akm distill` is not a CLI command** — there is no standalone verb by that name | `ref`, outcome (`queued`, `skipped` with a `skipReason` such as `lesson_exists`, `nothing_reusable` or `conflict_noop`, `llm_failed`, `validation_failed`, `quality_rejected`, `review_needed`) |
 | `extract_invoked` | `akm proposal extract --type <harness>` / `--auto`, or improve-stage session extraction | `outcome`, `sessionId`, `harness` |
 | `extract_triaged` | The pre-LLM extract triage gate evaluated at least one session | `evaluated`, `passed`, `triagedOut`, `sourceRun` (aggregated) |
 | `schema_repair_invoked` | The schema-repair pass inside `akm improve` (`runSchemaRepairPass`) attempts to patch missing frontmatter on an asset that failed schema validation. **There is no `akm lint --repair` flag** — `lint` has `--fix`/`--auto-fix`, unrelated to this event | `ref`, outcome |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.27-alpha.1",
+  "version": "0.9.27-alpha.2",
   "type": "module",
   "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
   "keywords": [