akm-cli 0.9.18 → 0.9.19-alpha.1

package/CHANGELOG.md

@@ -6,6 +6,141 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.19-alpha.1] - 2026-09-30
+
+### Added
+
+- **`akm proposal reopen <id...> [--reason <text>]` (#997).** A rejection was
+  final: nothing undid it, and a rejected `consolidate-pair` retire proposal
+  also kept the pair pass from ever proposing that retirement again while both
+  documents were unchanged. Reopen moves rejected proposals back to `pending`,
+  keeping the rejection (and the gate verdict that came with it) in the
+  proposal's new `reviewHistory`, which `proposal show` prints; the verdict
+  itself is cleared so the drain sees the proposal as undecided, except a
+  `deferred` one (the quality gate's hand-off to a person), which stays. It is
+  refused unless the proposal is `rejected` and `accept` would not refuse it as
+  stale (an update's target unchanged; a create's target still absent; a retire
+  proposal's successor present and both documents' body hashes as recorded),
+  and a retire proposal is refused while another pending retire proposal
+  involves either of its documents. Several ids are all-or-nothing. The pair pass
+  follows the status: a reopened proposal is no longer a settled pair and,
+  pending, is not minted twice. Its `improve_ledger` row is reset (a retire
+  proposal's rejection row is dropped, any other goes back to `proposed`), the
+  age that retention expiry and `--older-than` (bulk accept/reject, `drain`)
+  see restarts at the reopen, so a scheduled sweep does not take a proposal a
+  person just put back, and a `proposal_reopened` event is appended.
+  `akm proposal reject`'s confirmation prompt no longer says a rejection
+  cannot be undone.
+
+### Fixed
+
+- **A tool failure recorded with `akm feedback` no longer becomes a lesson
+  about the error or a `TODO` placeholder in a memory (#999).** Agents
+  recorded `akm show` failing on a memory with a `.derived.md` child (fixed in
+  0.9.17) as negative feedback, and distill and reflect read it as evidence
+  about the memory's content. On one bundle, 9 such events on 8 memories
+  produced 4 distill lessons about "duplicate physical owners" for memories on
+  unrelated subjects (one auto-accepted and live), and a reflect proposal,
+  also auto-accepted, that added a `TODO: verify physical owner` section to a
+  memory, on which a fifth lesson was then built. The shipped hints had told
+  agents to record `--negative` "when it fails"; they, and the help for
+  `akm feedback --reason`, now say a failed akm command is not feedback on the
+  asset. Reflect's feedback caveat no longer offers a `TODO: verify …`
+  placeholder: when feedback asks for information the asset lacks, it says
+  only to leave the section unchanged. The distill quality judge now also
+  scores **grounding**, whether the lesson is about what its source is about
+  (1–2 only for a different subject; a lesson that corrects its source from
+  feedback is not off-subject), and a grounding score of 2 or less is
+  `quality_rejected` (an `improve_ledger` row and a `distill_invoked` event, no
+  proposal) whatever the mean of novelty and non-redundancy is. Such a lesson
+  reads as novel and non-redundant, so it used to pass or, in the review band,
+  be minted as a pending `review_needed` proposal. The judge also reads the
+  same slice of the source the lesson was generated from (its body without
+  frontmatter, first 3000 characters) instead of the raw file's first 2000. A
+  lesson that contradicts its source still reaches a human through the
+  optional fidelity check (`processes.distill.fidelityCheck.enabled`, off by
+  default), and every other `review_needed` reason is unchanged. `TODO:`
+  lines already in a memory are not removed.
+- **Consolidation stops re-proposing memories that `knowledge/` already
+  covers (#998).** The promote pass copied a memory into a new `knowledge/`
+  proposal with no notion of what `knowledge/` already held: the model never
+  sees it, the mint-time checks only caught the same slug or a byte-identical
+  body, and an accepted promotion's memory was eligible again at once (a
+  rejected one after 7 days). On one bundle 88% of a run's proposals came from
+  memories promoted before, one of them 14 times, and 215 of 224 rejections
+  read "covered by an existing knowledge doc". Two changes, no new setting:
+  before queuing a promotion, consolidate now compares the memory with the 20
+  `knowledge/` docs in its bundle nearest to it by stored vector (the lookup
+  the pair pass uses) and skips it, with skip reason
+  `dedup_covered_by_knowledge`, when one of them holds at least half of the
+  memory's distinct 5-word shingles (measured against every knowledge doc,
+  that share was at least 0.5 for 122 of the 224 rejected proposals and for
+  none of the 103 accepted ones; a covering doc past the 20 nearest goes
+  unseen); and a memory whose promotion was accepted or rejected is offered
+  again only when its body changes, the same content-driven rule the pair pass
+  uses, instead of at once or after 7 days. A promotion decided by an older
+  release recorded no body hash and keeps its old windows. With no stored
+  vector (semantic search off) the coverage check does nothing.
+- **`akm improve` no longer files one bundle's assets into another (#1000).**
+  Candidate selection admitted assets from every writable bundle, but every
+  proposal is filed in the run's write target and reflect reads each asset
+  from the bundle that owns it. An asset owned by another bundle therefore
+  came back as a `create` fork in the write target, or as an `update` of the
+  write target's own copy built from the other bundle's copy. A run now plans
+  only the bundle it writes to (`--bundle`, else `defaultWriteTarget`, else
+  the working bundle), and a bare ref scope (`akm improve skills/x`) resolves
+  inside that bundle. Distill's memory-to-knowledge promotion likewise merges
+  only with a doc that already exists in the write target. As a second line of
+  defence, `createProposal` refuses a rewrite whose `itemRef` names an asset
+  owned by a different configured bundle than the queue's. **Narrowed
+  behaviour:** a run no longer picks up assets from your other writable
+  bundles (it used to read them and queue the result in its own write target),
+  so a scheduled `akm improve` now covers only its write target: add one
+  `akm improve --bundle <name>` run per other bundle you want improved.
+  `akm improve <ref>` for an asset that lives only in another bundle now fails
+  with a not-found error whose hint names the remedy (`--bundle team`, or
+  `akm improve team//skills/x`). Proposals the old behaviour already queued
+  stay in the queue; review them with `akm proposal list`. `--bundle`'s help
+  text now says it selects the bundle a run improves and writes to.
+- **`akm improve --dry-run`/`--plan` previews the bundle a live run improves.**
+  With no `--bundle` and no `defaultWriteTarget`, a live run starts from
+  `AKM_BUNDLE_DIR` before `defaultBundle`, but a dry run read `defaultBundle`
+  only, so the two could plan different bundles. The preview now resolves the
+  working bundle the same way.
+- **`akm proposal diff` shows a retire proposal as a retirement (#997).** It
+  rendered the retired file as replaced by one blank line (`----`, a lone `+`,
+  then every other line as a removal, under an `(update: <ref>)` header) and
+  said nothing about the retirement, so one reviewer rejected all 65 of a
+  bundle's `consolidate-pair` proposals as "would destroy content". The diff
+  now lists only the removed lines, under a `(retire: <retired> -> <successor>)`
+  header and `+++ /dev/null (retired: archived; successor <ref>)`, and its JSON
+  result gains `op: "delete"`, a `retirement` block under the keys `proposal
+  show` uses (`retiredRef`, `successorRef`, `judgeLabel`, `judgeReason`,
+  `cosine`, and `continuityRisk` when the pair was flagged, which the text
+  output prints as well) and a `note` that accepting archives the file under
+  `.akm/memory-cleanup/archive/` and `akm proposal revert` restores it
+  byte-exactly. The new fields are additive and appear on retire proposals
+  only. `akm proposal show --detail full` also stops ending a retire proposal
+  with a bare `payload:` heading over nothing.
+- **Errors name the flag the command takes, not the retired `--target`
+  (`improve`, `remember`, `clone`, `task`, `proposal --queue`).** A `--bundle`
+  that names no configured bundle, names a read-only one, or differs from a
+  bundle-qualified ref (`akm improve team//skills/x --bundle stash`) failed with
+  "--target must reference a source name", "or pass --target to a different
+  source" or "conflicts with --target". `akm improve`, `remember`, `clone` and
+  every `task` verb reject `--target` (renamed `--bundle` in 0.9), and
+  `proposal --queue` takes `--queue`, so each message sent the user to a flag
+  that does not work. They now name the flag the command takes, and the
+  remedy in `akm remember --supersedes` says "re-run with --bundle" instead of
+  "--target". A bundle that came from a ref inside a task (`ghost//workflows/x`)
+  is described as such rather than blamed on a flag. The commands that really
+  take `--target` (`import`, `env`, `secret`, `proposal accept`) are unchanged.
+  Separately, the help for `akm improve --skip-if-locked` said a lock collision
+  without the flag exits 78. It exits 75 (`IMPROVE_LOCK_HELD`), as the CLI
+  reference says. The `--limit` help says "highest salience first" (it said
+  utility), and the `task add --command` help example uses
+  `--strategy reflect-distill` (the `frequent` strategy no longer exists).
+
 ## [0.9.18] - 2026-09-29
 
 ### Fixed

package/STABILITY.md

@@ -89,6 +89,7 @@ enumeration of the whole `proposal` noun group.
 | `akm proposal diff` | Evolving | |
 | `akm proposal accept` | Evolving | |
 | `akm proposal reject` | Evolving | |
+| `akm proposal reopen` | Evolving | New in 0.9.19; undoes a rejection. |
 | `akm proposal revert` | Evolving | |
 | `akm proposal drain` | Evolving | |
 | `akm proposal extract` | Evolving | Former top-level `akm extract`. |
@@ -247,7 +248,7 @@ proposal-queue shape may shift. Breaking changes will be flagged in the
 CHANGELOG with a migration note.
 
 - **Improvement loop** — `akm improve` and the proposal noun group
-  `akm proposal {extract,new,list,show,diff,accept,reject,revert,drain}`
+  `akm proposal {extract,new,list,show,diff,accept,reject,reopen,revert,drain}`
   (`extract` and `new` are the former top-level `akm extract`/`akm propose`,
   moved under `proposal` in 0.9.0). Output JSON keys
   are stable; CLI flags (`--strategy`, `--task`, `--generator`) may add

package/dist/assets/hints/cli-hints-full.md

@@ -100,8 +100,9 @@ akm feedback memories/deployment-notes --positive # Works for memories too
 akm feedback env/prod --positive               # Records env feedback without surfacing values
 ```
 
-Use `akm feedback` whenever an asset materially helps or fails so future search
-ranking can learn from actual usage.
+Use `akm feedback` whenever an asset's content materially helps, or proves wrong,
+stale or unhelpful, so future search ranking can learn from actual usage. An akm
+command that fails says nothing about the asset; don't record it as feedback.
 
 ## LLM Wiki bundles
 
@@ -340,6 +341,7 @@ akm proposal accept 7c115132                            # Accept by UUID prefix
 akm proposal accept <id> --target team-bundle            # Accept to a named writable bundle source
 akm proposal reject skills/my-skill --reason "not ready" # Reject by asset ref
 akm proposal reject <id> --reason "..."                 # Archive with a reason
+akm proposal reopen <id> --reason "..."                 # Undo a rejection: back to pending (refused if the target changed)
 akm proposal revert <id>                                # Restore the pre-promotion content
 akm proposal new <type> <name> --task "..."             # Agent-author a NEW asset as a proposal
 akm proposal extract --auto                             # Mine native session files into proposals

package/dist/assets/hints/cli-hints-short.md

@@ -8,7 +8,7 @@ For any task, follow this loop:
 1. `akm curate "<task>"` — find the best matching asset
 2. `akm show <ref>` — read the schema (field names and structure)
 3. Edit the workspace file using schema field names + task-specific values from your README
-4. `akm feedback <ref> --positive` — record success; use `--negative --reason "..."` when it fails
+4. `akm feedback <ref> --positive` — record that the asset helped; use `--negative --reason "..."` when its content was wrong, stale or unhelpful. A failed akm command (e.g. `akm show` erroring) is not feedback on the asset — don't record it.
 
 For workflow tasks:
 1. `akm show workflows/<name>` — inspect the procedure before executing it
@@ -63,8 +63,10 @@ akm search "<query>" --from registry          # Search all registries (registry
 | secret | A single sensitive value for AUTHENTICATION (token, key, cert); name only. Inject with `akm secret run <ref> <VAR> -- <cmd>`. |
 | lesson | A distilled feedback lesson: `content` plus `action` (rendered from the `when_to_use` frontmatter). Read both before applying a related skill. Generated by the improve pipeline and promoted through the proposal queue. |
 
-When an asset meaningfully helps or fails, record that with `akm feedback` so
-future search ranking can learn from real usage.
+When an asset's content meaningfully helps, or proves wrong, stale or unhelpful,
+record that with `akm feedback` so future search ranking can learn from real
+usage. An akm command that fails says nothing about the asset; don't record it
+as feedback.
 
 ## Error Shapes and Exit Codes
 

package/dist/assets/prompts/reflect-feedback-framing.md

@@ -1 +1 @@
-Feedback describes what a reader found missing or wrong. It is a signal to investigate, not a fact to insert. Do not add claims, numbers, dates, paths, ports, or incidents that are not already present in the asset content. If feedback asks for information the asset lacks, add a clearly marked `TODO: verify …` placeholder or leave the section unchanged.
+Feedback describes what a reader found missing or wrong. It is a signal to investigate, not a fact to insert. Do not add claims, numbers, dates, paths, ports, or incidents that are not already present in the asset content. If feedback asks for information the asset lacks, leave the section unchanged.

package/dist/commands/feedback-cli.js

@@ -208,7 +208,7 @@ export const feedbackCommand = defineJsonCommand({
         },
         reason: {
             type: "string",
-            description: "Reason for the feedback (required for negative feedback by default; used by distillation)",
+            description: "What was wrong with (or right about) the asset's content (required for negative feedback by default; used by distillation). Not for akm command errors.",
         },
         "failure-mode": {
             type: "string",

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

@@ -0,0 +1,132 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * The promote pass's coverage gate (#998): before a memory becomes a
+ * `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
+ * 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.
+ *
+ * Why this rule and this cut. The model never sees `knowledge/`, and the
+ * mint-time checks before this one only catch the same slug or the same whole
+ * body, so one edit or paraphrase defeats them. The evidence is #998's, from
+ * the owner's bundle (run `consolidate-1790666282516`: 327 decided proposals,
+ * 103 accepted, 224 rejected, 215 of those as "duplicate of / covered by /
+ * overlaps" an existing knowledge doc): the share of a proposal's distinct
+ * 5-word shingles found in the best OTHER knowledge doc was >= 0.5 for 122 of
+ * the 224 rejected proposals and for none of the 103 accepted ones. 0.5 is the
+ * cut that sample supports: no accepted promotion would have been skipped. That
+ * sample compared each proposal with EVERY other knowledge doc, so 122 of 224
+ * (up to about 54%) is what the rule can take out of review at most, not what
+ * 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
+ * promotion nobody gets to review.
+ *
+ * Candidates are the memory's {@link PAIR_NEIGHBOR_FETCH_K} nearest knowledge
+ * docs in its bundle by stored vector (`getNeighborsByEntryId`, the lookup the
+ * pair pass runs, scoped to the bundle's knowledge entries), never a scan of
+ * `knowledge/`. There is no similarity floor, only a rank: a guide that quotes
+ * the memory is found however far it sits from it by vector, as long as fewer
+ * than that many other knowledge docs in the bundle are nearer. With no stored
+ * vector (semantic search off, the memory not indexed yet, no index at all)
+ * there are no candidates and the gate does nothing: the exact-slug and
+ * whole-body checks still run, and nothing throws.
+ */
+import fs from "node:fs";
+import { closeDatabase, openExistingDatabase } from "../../../storage/repositories/index-connection.js";
+import { getEntryById, getEntryIdByFilePath } from "../../../storage/repositories/index-entries-repository.js";
+import { getNeighborsByEntryId } from "../../../storage/repositories/index-vec-repository.js";
+import { stripFrontmatterBody } from "../content-hash.js";
+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;
+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) {
+    const words = text.toLowerCase().match(WORD) ?? [];
+    const shingles = new Set();
+    for (let i = 0; i + COVERAGE_SHINGLE_WORDS <= words.length; i++) {
+        shingles.add(words.slice(i, i + COVERAGE_SHINGLE_WORDS).join(" "));
+    }
+    return shingles;
+}
+/** The share (0..1) of `memory`'s shingles that also occur in `doc`; 0 when the memory has none. */
+export function shingleContainment(memory, doc) {
+    if (memory.size === 0)
+        return 0;
+    const docShingles = wordShingles(doc);
+    let shared = 0;
+    for (const shingle of memory)
+        if (docShingles.has(shingle))
+            shared++;
+    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.
+ */
+export function findCoveringKnowledge(db, bundleId, filePath, body) {
+    const shingles = wordShingles(body);
+    if (shingles.size === 0)
+        return undefined;
+    const entryId = getEntryIdByFilePath(db, filePath);
+    if (entryId === undefined)
+        return undefined;
+    let best;
+    for (const hit of getNeighborsByEntryId(db, entryId, PAIR_NEIGHBOR_FETCH_K, { type: "knowledge", bundleId })) {
+        const neighbour = getEntryById(db, hit.id);
+        if (!neighbour)
+            continue;
+        let raw;
+        try {
+            raw = fs.readFileSync(neighbour.filePath, "utf8");
+        }
+        catch {
+            continue; // the index outlived the file
+        }
+        const containment = shingleContainment(shingles, stripFrontmatterBody(raw));
+        if (containment >= COVERAGE_MIN_CONTAINMENT && (best === undefined || containment > best.containment)) {
+            best = { ref: neighbour.conceptId, containment };
+        }
+    }
+    return best;
+}
+/**
+ * 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
+ * to look in. A lookup that throws counts as "not known to be covered".
+ */
+export function openKnowledgeCoverage(bundleId) {
+    if (!bundleId)
+        return undefined;
+    let db;
+    try {
+        db = openExistingDatabase();
+    }
+    catch {
+        return undefined;
+    }
+    return {
+        find: (filePath, body) => {
+            try {
+                return findCoveringKnowledge(db, bundleId, filePath, body);
+            }
+            catch {
+                return undefined;
+            }
+        },
+        close: () => closeDatabase(db),
+    };
+}

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

@@ -273,6 +273,35 @@ function pairKey(a, b) {
 function rejectedPairKey(retiredRef, successorRef, retiredHash, successorHash) {
     return [retiredRef, successorRef, retiredHash, successorHash].join("\u0000");
 }
+/**
+ * Item 0 / S1: every rejected OR reverted consolidate-pair retirement on
+ * record, as {@link rejectedPairKey}s — read once per run, the same shape as
+ * `pendingRetireRefs` in {@link runConsolidatePairPass}. `reverted` is
+ * included alongside `rejected`: a person undoing an accept via `akm proposal
+ * revert` is the same "no, not this" signal as a reject — without it, the next
+ * run would re-mint the identical retirement, and a bulk accept could
+ * re-apply a decision the person just undid. The keys follow each proposal's
+ * CURRENT status, so one `akm proposal reopen` put back to `pending` (#997) is
+ * no longer among them — and, pending, blocks its pair from a second mint.
+ *
+ * @internal exported for unit tests.
+ */
+export function loadRejectedPairKeys(stashDir, proposalsCtx) {
+    const keys = new Set();
+    try {
+        for (const status of ["rejected", "reverted"]) {
+            for (const p of listProposalsReadOnly(stashDir, { status, includeArchive: true }, proposalsCtx)) {
+                if (!isRetireProposal(p) || !p.retirement)
+                    continue;
+                keys.add(rejectedPairKey(p.retirement.retiredRef, p.retirement.successorRef, p.retirement.retiredContentHash, p.retirement.successorContentHash));
+            }
+        }
+    }
+    catch {
+        // Best-effort de-dup only; a failed read never blocks judging.
+    }
+    return keys;
+}
 /**
  * Initiators (plan §5.2 step 1, S1 post-review): the pool, in the retrieval
  * scope, and content-eligible — no prior `consolidate-pair` ledger row, or a
@@ -647,26 +676,7 @@ seams = {}) {
         // Best-effort de-dup only; a failed read never blocks judging.
     }
     const isPendingBlocked = (c) => pendingRetireRefs.has(stripBundle(c.initiator.ref)) || pendingRetireRefs.has(stripBundle(c.other.ref));
-    // Item 0 / S1: every rejected OR reverted consolidate-pair retirement on
-    // record, keyed by its exact ref pair and both content hashes — read once
-    // per run, the same shape as pendingRetireRefs above. `reverted` is
-    // included alongside `rejected`: a person undoing an accept via `akm
-    // proposal revert` is the same "no, not this" signal as a reject — without
-    // it, the next run would re-mint the identical retirement, and a bulk
-    // accept could re-apply a decision the person just undid.
-    const rejectedPairKeys = new Set();
-    try {
-        for (const status of ["rejected", "reverted"]) {
-            for (const p of listProposalsReadOnly(stashDir, { status, includeArchive: true }, opts.proposalsCtx)) {
-                if (!isRetireProposal(p) || !p.retirement)
-                    continue;
-                rejectedPairKeys.add(rejectedPairKey(p.retirement.retiredRef, p.retirement.successorRef, p.retirement.retiredContentHash, p.retirement.successorContentHash));
-            }
-        }
-    }
-    catch {
-        // Best-effort de-dup only; a failed read never blocks judging.
-    }
+    const rejectedPairKeys = loadRejectedPairKeys(stashDir, opts.proposalsCtx);
     // Blocker 2: admit WHOLE initiators under MAX_PAIRS_PER_RUN, never
     // individual pairs — the old flat "top 300 candidates by cosine" cap let a
     // pending-blocked pair spend a budget slot doing nothing, and left

package/dist/commands/improve/consolidate.js

@@ -7,7 +7,10 @@
  * promoted. Promotion emits a reviewable proposal and never touches the
  * memory directly; accepting it later retires the source memory (O1, in
  * `proposal/repository.ts`). Memories the improve ledger judged recently and
- * that have not changed since are not judged again.
+ * that have not changed since are not judged again, and a memory whose
+ * promotion was accepted or rejected waits until its body changes. A memory
+ * that a neighbouring knowledge doc already covers is not promoted
+ * (`consolidate/coverage.ts`).
  *
  * Accounting invariant (the promote pass only): `processed == promoted +
  * judgedNoAction + Σ(skipReasons) + failedChunkMemories`.
@@ -41,11 +44,12 @@ import { getAllEntries } from "../../storage/repositories/index-entries-reposito
 import { listProposals, listProposalsReadOnly, proposalContent } from "../proposal/repository.js";
 import { hasHotCaptureMode, hasSupersededStatus, validateProposalFrontmatter, } from "../proposal/validators/proposal-quality-validators.js";
 import { buildChunkPrompt, computeSafeChunkSize, DEFAULT_CONTEXT_LENGTH_TOKENS } from "./consolidate/chunking.js";
+import { openKnowledgeCoverage } from "./consolidate/coverage.js";
 import { runConsolidatePairPass } from "./consolidate/pair-pass.js";
 import { sanitizeMergedContent } from "./consolidate/sanitize.js";
 import { contentHash } from "./content-hash.js";
 import { resolveImproveStrategy, resolveProcessEnabled } from "./improve-strategies.js";
-import { isLedgerBlocked, ledgerKey, loadLedgerSnapshot, recordLedgerAttempt } from "./ledger.js";
+import { isContentDrivenRow, isLedgerBlocked, ledgerKey, loadLedgerSnapshot, recordLedgerAttempt } from "./ledger.js";
 import { isInRetrievalScope, loadRetrievalScope } from "./retrieval-scope.js";
 import { callStage, mintProposal, noticeSet, stageRunner } from "./stage.js";
 /** A plan op worth acting on. Retired advisory ops (merge/delete/contradict) are dropped, never thrown on. */
@@ -420,12 +424,26 @@ export function inspectConsolidationPool(opts, stashDir, warnings, existingKnowl
     }
     memories = memories.filter((memory) => fs.existsSync(memory.filePath));
     const poolSize = memories.length;
-    // A memory judged within its revisit window comes back once it is edited.
+    // A memory judged within its revisit window comes back once it is edited. A
+    // promotion that was accepted or rejected holds its memory until the body
+    // changes, however long that takes (#998).
     const ledger = loadLedgerSnapshot({ proposalsCtx: opts.proposalsCtx, readOnly }, stashDir, ["consolidate"]);
     if (ledger.size > 0) {
         const nowIso = new Date().toISOString();
         memories = memories.filter((memory) => {
             const row = ledger.get(ledgerKey("consolidate", conceptIdFromTypeName("memory", memory.name)));
+            if (!row)
+                return true;
+            if (isContentDrivenRow(row)) {
+                let bodyHash;
+                try {
+                    bodyHash = contentHash(fs.readFileSync(memory.filePath, "utf8"), "body");
+                }
+                catch {
+                    bodyHash = undefined;
+                }
+                return row.contentHash !== bodyHash;
+            }
             let changedAt;
             try {
                 changedAt = fs.statSync(memory.filePath).mtime.toISOString();
@@ -433,7 +451,7 @@ export function inspectConsolidationPool(opts, stashDir, warnings, existingKnowl
             catch {
                 changedAt = undefined;
             }
-            return !row || !isLedgerBlocked(row, nowIso, changedAt);
+            return !isLedgerBlocked(row, nowIso, changedAt);
         });
     }
     const judgedUnchanged = poolSize - memories.length;
@@ -651,7 +669,7 @@ async function consolidate(opts, config, stashDir, startMs, stateDb) {
     const { memories, prefilteredAlreadyPromoted } = pool;
     const plural = (n) => `memor${n === 1 ? "y" : "ies"}`;
     if (pool.judgedUnchanged > 0) {
-        warnings.push(`Consolidation: skipped ${pool.judgedUnchanged} ${plural(pool.judgedUnchanged)} judged within the revisit window and unchanged since.`);
+        warnings.push(`Consolidation: skipped ${pool.judgedUnchanged} ${plural(pool.judgedUnchanged)} judged within the revisit window, or already promoted or rejected, and unchanged since.`);
     }
     if (pool.outsideRetrievalScope > 0) {
         warnings.push(`Consolidation: skipped ${pool.outsideRetrievalScope} ${plural(pool.outsideRetrievalScope)} already judged that retrieval has not returned in the last ${USAGE_EVENT_RETENTION_DAYS} days.`);
@@ -664,8 +682,8 @@ async function consolidate(opts, config, stashDir, startMs, stateDb) {
     // sees .derived memories, flat knowledge and lessons, not just the
     // promote pool above), so it runs regardless of whether the promote pool
     // is empty — every return path below carries its result.
-    const pairPassBundleId = resolveConsolidationSourceOwner(opts, stashDir)?.bundleId;
-    const pairPass = await runConsolidatePairPass(opts, config, stashDir, pairPassBundleId, warnings);
+    const bundleId = resolveConsolidationSourceOwner(opts, stashDir)?.bundleId;
+    const pairPass = await runConsolidatePairPass(opts, config, stashDir, bundleId, warnings);
     if (memories.length === 0) {
         return makeConsolidateResult({
             dryRun: opts.dryRun ?? false,
@@ -719,8 +737,16 @@ async function consolidate(opts, config, stashDir, startMs, stateDb) {
         warnings,
         pushSkipReason: (op, ref, reason) => pushSkipReason(acc, op, ref, reason),
     };
-    for (const op of plan.allOps)
-        await emitPromotionProposal(op, ctx);
+    const coverage = plan.allOps.length > 0 ? openKnowledgeCoverage(bundleId) : undefined;
+    if (coverage)
+        ctx.coveringKnowledge = coverage.find;
+    try {
+        for (const op of plan.allOps)
+            await emitPromotionProposal(op, ctx);
+    }
+    finally {
+        coverage?.close();
+    }
     // Every other judged memory waits out its revisit window (or its next edit);
     // a promotion that failed to persist is retried next run.
     recordLedgerAttempt({ proposalsCtx: opts.proposalsCtx }, [...acc.judgedRefs]
@@ -765,7 +791,8 @@ const PROMOTE_BODY_MIN_CHARS = 100;
 /**
  * Queue one promotion as a proposal. Refused (with a skip reason) when the
  * memory is unknown, already promoted this run, already pending or present
- * as knowledge (by concept, body hash or slug variant), unreadable, fails
+ * as knowledge (by concept, body hash or slug variant), already covered by a
+ * neighbouring knowledge doc (`coverage.ts`), unreadable, fails
  * sanitization, is superseded, has a body too small to be knowledge, or has
  * no valid description.
  * @internal Exported for promotion-path integration tests.
@@ -842,6 +869,12 @@ export async function emitPromotionProposal(op, ctx) {
     if (sameBody) {
         return skip("dedup_pending_proposal", `Skipping promote: identical body already pending as proposal ${sameBody.id} (ref: ${sameBody.ref}); skipping duplicate for ${op.ref} → ${knowledgeRef}`);
     }
+    // #998: the copies the two exact checks above cannot see — an earlier
+    // promotion that was edited or re-slugged, a doc that quotes the memory.
+    const covering = ctx.coveringKnowledge?.(entry.filePath, sourceBody);
+    if (covering) {
+        return skip("dedup_covered_by_knowledge", `Skipping promote: ${op.ref} → ${knowledgeRef} is already covered by ${covering.ref} (${Math.round(covering.containment * 100)}% of its text appears there).`);
+    }
     try {
         const description = (typeof op.description === "string" && op.description.trim()
             ? op.description.trim()

package/dist/commands/improve/distill.js

@@ -20,7 +20,7 @@ import { parseFrontmatter, writeSalienceToFrontmatter } from "../../core/asset/f
 import { stripMarkdownFences } from "../../core/asset/markdown.js";
 import { conceptIdFromTypeName, parseRefInput } from "../../core/asset/resolve-ref.js";
 import { authoringRulesForType } from "../../core/authoring-rules.js";
-import { resolveStashDir } from "../../core/common.js";
+import { isWithin, resolveStashDir } from "../../core/common.js";
 import { getImproveProcessConfig, loadConfig } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
 import { appendEvent, readEvents } from "../../core/events.js";
@@ -436,7 +436,9 @@ async function judgeAndQueue(run, out) {
     let confidence;
     if (qualityGateEnabled(run)) {
         const similarLessons = await run.similar(content.slice(0, 500), 3);
-        const verdict = await runLessonQualityJudge(run.config, content, out.source ?? "", run.options.chat, {
+        // 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 } : {}),
             ...(run.runner ? { llmRunner: run.runner } : {}),
             ...(run.options.signal ? { signal: run.options.signal } : {}),
@@ -599,8 +601,10 @@ async function planPromotion(run, feedbackEvents) {
     const existingPath = await run.lookup(assessment.knowledgeRef);
     let existing = null;
     try {
-        if (existingPath && fs.existsSync(existingPath))
+        // The promotion is filed in run.stash, so only that bundle's doc is its destination (#1000).
+        if (existingPath && fs.existsSync(existingPath) && isWithin(existingPath, run.stash)) {
             existing = fs.readFileSync(existingPath, "utf8");
+        }
     }
     catch {
         existing = null;