akm-cli 0.9.26 → 0.9.27-alpha.2

package/CHANGELOG.md

@@ -6,6 +6,243 @@ 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
+
+- **A codex dispatch with an output schema no longer leaves a temp folder
+  behind.** Every build of the codex command for a request with a schema made a
+  new `akm-codex-schema-*` folder in the OS temp dir for `--output-schema` and
+  nothing ever removed it (the builder has no post-run hook, and the file is read
+  after it returns), so a machine whose `/tmp` is tmpfs held a folder in RAM per
+  dispatch until reboot. The schema is now written once to akm's cache dir, in a
+  file named by its hash: concurrent units dispatching the same schema share it,
+  a rewrite is an atomic rename of identical bytes, and the only residue is one
+  small file per distinct schema.
+- **An index that has been updated ranks like a fresh index of the same files,
+  and `akm index --full` no longer doubles the full-text totals.** `entries_fts`
+  is contentless, and FTS5 cannot take a deleted row out of a contentless
+  table's BM25 totals (its row count, and the token counts the average document
+  length comes from). Every replaced or removed row left them one row too high:
+  40 notes read 40, then 41 after one edit, then 81 after `--full`, and a delete
+  never lowered them, so scores drifted away from what a fresh index gives.
+  SQLite has no command that recomputes them (`delete` and `rebuild` are refused
+  on a contentless table), so a delete that removes a row now stamps
+  `index_meta.ftsTotalsStale` in its own transaction, whichever process made it,
+  and the next `akm index` rebuilds the table from `entries` before it finishes:
+  about a second at 25,000 entries, and only when rows have left the table. A
+  row the write-path index replaced after an accepted proposal is settled the
+  same way, and an index that has already drifted is corrected by the first run
+  that replaces or removes a row.
+- **`akm improve` runs against an API that rejects `chat_template_kwargs`,
+  OpenAI's among them.** Improve's reflect, consolidate and judge calls always
+  ask for thinking off, and the client sends that as
+  `chat_template_kwargs.enable_thinking` and a top-level `enable_thinking`. A
+  strict API answers 400 `Unknown parameter: 'chat_template_kwargs'`, the retry
+  without the response schema sent both fields again, and `akm improve judge`
+  reported `judge timeout/error — routed to review`. No engine setting could
+  stop it: the call sites override the engine's `enableThinking`, and
+  `extraParams` can only add fields. A 4xx that names either field is now
+  answered by one retry without both (which may in turn fall back without the
+  schema), and akm stops sending them to that endpoint and model for the rest
+  of the process, as it already does for `response_format`.
+- **A lesson the model wrote without a `when_to_use` is no longer thrown away
+  silently by `akm proposal extract`.** The extract schema left `when_to_use`
+  optional while the parser dropped a lesson without one (or with one under 15
+  characters) and said nothing, so a model that followed the schema could
+  write a sound lesson that akm discarded and the session reported no
+  candidates: on akm-eval's extract eval qwen3.8-27b kept 3 of 11 expected
+  insights against 9 for gpt-oss-120b. Every property of the schema is now
+  required, `when_to_use` and `rationale_if_empty` included, with an empty
+  string for none (a memory or knowledge candidate needs no trigger, a
+  non-empty answer no rationale), which is also what a strict structured-output
+  provider needs; the prompt's output contract says the same. Any candidate the
+  contract still refuses, for this reason or another, is named in its session's
+  `warnings` as `<type>:<name> dropped: <reason>`.
+- **Distill's response schemas are valid for a strict structured-output
+  provider.** The client sends a response schema `strict: true`, and OpenAI
+  refuses one whose objects leave a property out of `required`: `400 Invalid
+  schema for response_format 'akm_response': ... Missing 'tags'`. The lesson
+  schema left out `tags`, and the knowledge schema `tags` and `sources`, so
+  the first distill request on such a provider always failed. After a 4xx the
+  client retries once without the schema, but a gateway that answers the same
+  rejection with a 502 is not retried, and every distill call through it
+  failed; the workaround, `supportsJsonSchema: false`, loses the guidance that
+  keeps a model from leaving out `when_to_use`. Every property is now
+  required, and an empty array stands for none (distill already dropped an
+  empty `tags` or `sources`).
+- **`akm improve` no longer reflects on an asset whose file a proposal would not
+  write, so accepting a reflect proposal no longer adds a second file.** A
+  skill's `references/a.md` is indexed as `knowledge/skills/<name>/references/a`,
+  but a proposal writes the path derived from that ref,
+  `knowledge/skills/<name>/references/a.md`. Nothing is there, so the proposal
+  was a `create`, and accepting it wrote a copy beside the skill's own file;
+  later proposals then revised the copy while the skill's file drifted. Reflect
+  now refuses before it calls the model, naming the file and the path a
+  proposal would write, and the loop records it as a skip (`unsupported_type`,
+  `file_outside_layout` in the `reflect_completed` event). This is the rule
+  0.9.26 added to `akm feedback --replace`. An asset that another bundle owns is
+  still refused by `createProposal` (#1000).
+- **An index that 0.9.1 wrote no longer crashes akm.** Every `akm index` on it
+  exited 70 with `null is not an object (evaluating 'doc.xrefs')`, `akm migrate
+  apply` and `akm index --full` did not help, and `akm search` failed with
+  `null is not an object (evaluating 'item.entry.quality')`; the only way out
+  was moving `index.db` aside. That layout (20) keeps the transitional
+  `entry_key`, `dir_path`, `stash_dir`, `entry_json` and `entry_type` columns
+  that layout 21 removed, each NOT NULL, beside the current columns, and leaves
+  `document_json` NULL on every row. The table had every column akm checks for,
+  so it was taken for a current one: the links migration read the NULL
+  documents, and no insert could ever have succeeded (`NOT NULL constraint
+  failed: entries.entry_key`). akm now treats a table that still has a retired
+  column as older than layout 21, as the compat notes already said: the
+  writable opener recreates its entries-keyed tables (the LLM enrichment cache
+  is kept) and the next `akm index` re-walks every source, and a read rebuilds
+  inline. An index that a failed open already half-migrated (layout stamp still
+  20, `search_text` dropped, `asset_links` created) recovers the same way.
+- **Two files that claim one ref no longer trade places in the index, and `akm
+  index` says so.** A skill's `references/a.md` and a note at
+  `knowledge/skills/x/references/a.md` are both the ref
+  `knowledge/skills/x/references/a`, and the index holds one row for it. The
+  first file a run persisted held it, so a full build followed the filesystem's
+  listing order (one bundle indexed on tmpfs and on ext4 held different files),
+  and the first incremental run after a full build handed the row to the other
+  file, because it drains only the directory that lost: with no file touched,
+  the row, its search entry and the text its vector is embedded from changed,
+  and the vector was dropped and recomputed. When a smaller-path file was added
+  later and then deleted, the ref also left the index until `--full`, although
+  its other file was still on disk. The file with the smaller path (code-point
+  order, as `akm show`'s refusal lists them) now holds the ref however the
+  directories are drained and the walk is ordered, a directory that gives a ref
+  up is drained again so the ref passes back when its holder goes, and each
+  pair is reported in the `warnings` of `akm index`, naming the file indexed
+  and the one skipped.
+- **Consolidate's plan schema and the session summary schema are valid for a
+  strict structured-output provider, and a new response schema can no longer
+  skip the rule.** The client sends a response schema `strict: true`, and
+  OpenAI refuses one whose objects leave a property out of `required`. The
+  consolidate plan left out `description` and `confidence`, and the session
+  summary `tags`, so the first request of every plan and every summary to such
+  a provider was refused. The client then retries without the schema and
+  remembers that per connection (endpoint and model), not per schema, so one
+  invalid schema also switched the response schema off for every valid one
+  that followed on that connection. Every property of both is now required: an
+  empty `description` keeps the memory's own, a null `confidence` records none
+  and an empty `tags` array is no tags, which is how all three were already
+  read. A contract test runs every schema akm sends through the rule, so a
+  property added later without being required fails CI.
+
 ## [0.9.26] - 2026-10-05
 
 The stable release of the 0.9.26 line: 0.9.26-alpha.1 and alpha.2, and the

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/consolidate-system.md

@@ -7,10 +7,10 @@ Rules:
 Return ONLY JSON (no prose, no code fences):
 {
   "operations": [
-    { "op": "promote", "ref": "memories/<name>", "knowledgeRef": "knowledge/<suggested-slug>", "reason": "<brief reason>", "description": "<one sentence describing the new knowledge asset>", "confidence": 0.92 }
+    { "op": "promote", "ref": "memories/<name>", "knowledgeRef": "knowledge/<suggested-slug>", "reason": "<brief reason>", "description": "<one sentence describing the new knowledge asset, or an empty string to keep the memory's own>", "confidence": 0.92 }
   ]
 }
 
-For every operation, emit a `confidence` field in [0, 1] expressing your certainty that the operation is correct and safe. Use 0.95+ only when evidence is unambiguous. Omit the field rather than guessing if you are uncertain.
+For every operation, emit a `confidence` field in [0, 1] expressing your certainty that the operation is correct and safe. Use 0.95+ only when evidence is unambiguous. Use `null` rather than guessing if you are uncertain.
 
 When the merged content includes an `updated` frontmatter field, the value MUST be a real ISO date string (e.g. `updated: 2026-05-20`). NEVER emit `updated: today`, `updated: {today}`, `updated: {today: null}`, `updated: now`, or any other literal placeholder/template-variable. If you do not have a real source-of-truth date, OMIT the `updated` field entirely — the post-processor will not invent one for you.

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/assets/prompts/extract-session.md

@@ -48,13 +48,13 @@ Respond with EXACTLY one JSON object matching this shape:
       "type": "memory" | "lesson" | "knowledge",
       "name": "<kebab-case name, e.g. jwt-token; optionally under one kebab-case scope, e.g. auth/jwt-token>",
       "description": "<one sentence 20-400 chars>",
-      "when_to_use": "<one sentence 15-400 chars; REQUIRED only when type=lesson>",
+      "when_to_use": "<one sentence 15-400 chars for a lesson; an empty string for a memory or knowledge candidate>",
       "body": "<markdown body, 200-3000 chars typical>",
       "confidence": <number 0.0-1.0>,
       "evidence": "<one-line pointer to the moment in the session>"
     }
   ],
-  "rationale_if_empty": "<one sentence; REQUIRED when candidates is empty>"
+  "rationale_if_empty": "<one sentence when candidates is empty; an empty string otherwise>"
 }
 ```
 

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

@@ -92,7 +92,7 @@ export const PAIR_JUDGE_JSON_SCHEMA = {
         reason: { type: "string", maxLength: 400 },
     },
 };
-const PAIR_CHECK_JSON_SCHEMA = {
+export const PAIR_CHECK_JSON_SCHEMA = {
     type: "object",
     required: ["missing"],
     additionalProperties: false,
@@ -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);