akm-cli 0.9.17 → 0.9.19-alpha.1

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. */
@@ -222,10 +226,10 @@ function injectRandomClusterMembers(memories, profile, warnings) {
     return out;
 }
 /** Body hashes of pending consolidate proposals, so the prompt can mark memories already queued. */
-function loadPendingConsolidateProposalHashes(stashDir) {
+function loadPendingConsolidateProposalHashes(stashDir, proposalsCtx) {
     const hashes = new Set();
     try {
-        for (const p of listProposalsReadOnly(stashDir, { status: "pending" })) {
+        for (const p of listProposalsReadOnly(stashDir, { status: "pending" }, proposalsCtx)) {
             if (p.source !== "consolidate")
                 continue;
             try {
@@ -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;
@@ -622,7 +640,7 @@ async function planConsolidation(opts, config, stashDir, memories, warnings, sta
         assertRunnerCredentials(llmRunner);
     const { ordered, embedTelemetry } = await clusterMemoriesBySimilarity(budgeted, config, stateDb, opts.signal);
     const chunks = slice(injectRandomClusterMembers(ordered, opts.improveProfile, warnings));
-    const pendingProposalBodyHashes = loadPendingConsolidateProposalHashes(stashDir);
+    const pendingProposalBodyHashes = loadPendingConsolidateProposalHashes(stashDir, opts.proposalsCtx);
     warn(`[consolidate] ${budgeted.length} memories / ${chunks.length} chunk(s) / chunk_size=${chunkSize}` +
         ` / pending-proposal hashes: ${pendingProposalBodyHashes.size}`);
     const planned = await judgeConsolidationChunks({
@@ -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;
@@ -799,7 +803,7 @@ 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);
+    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.
     const cls = getImproveProcessConfig("distill", run.profile)?.cls ?? {};
     let clsContext = "";

package/dist/commands/improve/eligibility.js

@@ -4,6 +4,7 @@
 /** The refs an improve run may consider, read from the index, and the small predicates over them. */
 import fs from "node:fs";
 import path from "node:path";
+import { parseBundleRef } from "../../core/asset/asset-ref.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { conceptIdFromTypeName, parseRefInput, resolveRef, typeNameFromConceptId } from "../../core/asset/resolve-ref.js";
 import { loadConfig } from "../../core/config/config.js";
@@ -109,6 +110,18 @@ export function dedupeRefs(refs) {
         return true;
     });
 }
+/**
+ * The bundle an improve run reads candidates from and files proposals into: its
+ * write target, the source rooted at `stashDir` (else the working bundle).
+ * Reflect reads a candidate from its owning bundle but the proposal lands in
+ * the write target, so a candidate owned by any other bundle would be read from
+ * one bundle and filed in another (#1000).
+ */
+function runBundleIdOf(sources, installations, stashDir) {
+    const root = stashDir === undefined ? undefined : path.resolve(stashDir);
+    const index = sources.findIndex((source) => root === undefined ? source.isDefault === true : path.resolve(source.path) === root);
+    return installations[index]?.id;
+}
 export async function collectEligibleRefs(scope, stashDir, improveProfile, config) {
     return collectEligibleRefsFromIndex(scope, stashDir, improveProfile, false, config);
 }
@@ -135,6 +148,9 @@ async function collectEligibleRefsFromIndex(scope, stashDir, improveProfile, rea
         return empty();
     const installations = deriveInstallations(sources);
     const writableBundleIds = deriveWritableBundleIds(sources);
+    const runBundleId = runBundleIdOf(sources, installations, stashDir);
+    // Candidates come from the write target alone, and only while it is writable.
+    const isCandidateBundle = (bundleId) => bundleId !== undefined && bundleId === runBundleId && writableBundleIds.has(bundleId);
     const ready = {
         status: "ready",
         reason: readOnly ? "loaded a non-mutating point-in-time copy of the existing index" : "loaded the prepared index",
@@ -152,20 +168,34 @@ async function collectEligibleRefsFromIndex(scope, stashDir, improveProfile, rea
             return empty(missing);
         if (scope.mode === "ref" && scope.value) {
             const entriesByItemRef = new Map(getAllEntries(db).map((entry) => [entry.itemRef, entry]));
-            const resolved = resolveRef(scope.value, {
-                defaultBundle: config.defaultBundle,
-                bundles: installations.map((installation) => ({
-                    id: installation.id,
-                    hasConcept: (conceptId) => entriesByItemRef.has(`${installation.id}//${conceptId}`),
-                })),
-            });
+            let resolved;
+            try {
+                resolved = resolveRef(scope.value, {
+                    defaultBundle: config.defaultBundle,
+                    bundles: installations.map((installation) => ({
+                        id: installation.id,
+                        hasConcept: (conceptId) => entriesByItemRef.has(`${installation.id}//${conceptId}`),
+                    })),
+                    ...(runBundleId ? { only: runBundleId } : {}),
+                });
+            }
+            catch (error) {
+                if (!(error instanceof NotFoundError) || !runBundleId)
+                    throw error;
+                // Name the bundle that owns the ref; a typo or an unindexed ref keeps the default advice.
+                const { conceptId } = parseBundleRef(scope.value);
+                const owner = installations.find((installation) => installation.id !== runBundleId && entriesByItemRef.has(`${installation.id}//${conceptId}`))?.id;
+                if (!owner)
+                    throw error;
+                throw new NotFoundError(error.message, error.code, `"${conceptId}" is in bundle "${owner}"; this run improves bundle "${runBundleId}" only. Run \`akm improve ${owner}//${conceptId}\` (or pass \`--bundle ${owner}\`).`);
+            }
             const indexed = entriesByItemRef.get(`${resolved.bundle}//${resolved.conceptId}`);
             if (!indexed?.bundleId || !indexed.conceptId || !fs.existsSync(indexed.filePath)) {
                 if (await findAssetFilePath(scope.value, stashDir))
                     return empty(ready);
                 throw new NotFoundError(`Asset not found in the selected writable source: ${scope.value}`, "ASSET_NOT_FOUND");
             }
-            if (!writableBundleIds.has(indexed.bundleId))
+            if (!isCandidateBundle(indexed.bundleId))
                 return empty(ready);
             const isMemory = indexed.entry.type === "memory";
             return {
@@ -180,7 +210,7 @@ async function collectEligibleRefsFromIndex(scope, stashDir, improveProfile, rea
                 indexSnapshot: ready,
             };
         }
-        const entries = getAllEntries(db, scope.mode === "type" ? scope.value : undefined).filter((indexed) => writableBundleIds.has(indexed.bundleId));
+        const entries = getAllEntries(db, scope.mode === "type" ? scope.value : undefined).filter((indexed) => isCandidateBundle(indexed.bundleId));
         const planned = new Map();
         const strategyFiltered = new Map();
         let memoryEligible = 0;

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

@@ -19,7 +19,7 @@ import { collectEngineCredentialValues } from "../../integrations/agent/engine-r
 import { probeLlmReachable } from "../../llm/client.js";
 import { getOutputMode } from "../../output/context.js";
 import { deliverRendered } from "../../output/html-render.js";
-import { akmImprove, resolveImproveReadSource } from "./improve.js";
+import { akmImprove, IMPROVE_TARGET_FLAG, resolveImproveReadSource } from "./improve.js";
 import { runImproveReportQuery } from "./improve-report.js";
 import { buildImproveRunId, recordImproveRunResult, recordTerminatedImproveRun, } from "./improve-result-file.js";
 import { runImproveSession } from "./improve-session.js";
@@ -209,8 +209,11 @@ export const improveCommand = defineCommand({
             description: "Alias for --dry-run (#947). Sets the exact same internal flag; use it when previewing resolved process -> engine -> model routing (plan.processes) rather than checking what would write.",
             default: false,
         },
-        bundle: { type: "string", description: "Override the write target for accepted proposals" },
-        limit: { type: "string", description: "Maximum number of assets to process (highest utility first)" },
+        bundle: {
+            type: "string",
+            description: "Bundle to improve and write proposals to (default: defaultWriteTarget, else the working bundle); only its assets are planned",
+        },
+        limit: { type: "string", description: "Maximum number of assets to process (highest salience first)" },
         "timeout-ms": {
             type: "string",
             description: "Wall-clock budget for the entire run in milliseconds (default: 7200000 = 2 hours)",
@@ -227,7 +230,7 @@ export const improveCommand = defineCommand({
         },
         "skip-if-locked": {
             type: "boolean",
-            description: "If another improve run already holds the lock, skip gracefully (exit 0) instead of failing with 'already running' (exit 78). Use for high-frequency scheduled runs so they don't pile up failures while a longer run is in progress.",
+            description: "If another improve run already holds the lock, skip gracefully (exit 0) instead of failing with 'already running' (exit 75). Use for high-frequency scheduled runs so they don't pile up failures while a longer run is in progress.",
             default: false,
         },
         "require-engines": {
@@ -286,8 +289,8 @@ export const improveCommand = defineCommand({
             const writeTarget = dryRun
                 ? undefined
                 : scopeRef
-                    ? resolveMutationTarget(effectiveConfig, scopeRef, targetArg).target
-                    : resolveWriteTarget(effectiveConfig, targetArg);
+                    ? resolveMutationTarget(effectiveConfig, scopeRef, targetArg, { flag: IMPROVE_TARGET_FLAG }).target
+                    : resolveWriteTarget(effectiveConfig, targetArg, { flag: IMPROVE_TARGET_FLAG });
             // Every model-backed process resolves before any side effect; a dry run
             // never dispatches, so it tolerates every process being disabled.
             const resolvedPlan = resolveImprovePlan(strategyArg, effectiveConfig, { allowAllDisabled: Boolean(dryRun) });

package/dist/commands/improve/improve.js

@@ -19,7 +19,7 @@ import { redactSensitiveText } from "../../core/redaction.js";
 import { openStateDatabase } from "../../core/state-db.js";
 import { info, warn, warnVerbose } from "../../core/warn.js";
 import { beginWriteProvenance, relativeWrittenPath } from "../../core/write-provenance.js";
-import { resolveWritable, resolveWriteTarget } from "../../core/write-source.js";
+import { resolveWorkingStashTarget, resolveWritable, resolveWriteTarget } from "../../core/write-source.js";
 import { ensureIndex } from "../../indexer/ensure-index.js";
 import { indexWrittenAssets } from "../../indexer/index-written-assets.js";
 import { akmIndex } from "../../indexer/indexer.js";
@@ -268,17 +268,24 @@ function describeRunWrittenPaths(setup, writtenPaths) {
     }
     return [...described].sort();
 }
+/** How `akm improve` spells its destination flag: the shared target resolvers name it in their errors. */
+export const IMPROVE_TARGET_FLAG = "--bundle";
 /**
  * The source a dry run (or `--show-prompt`) inspects, without adapting it into
  * a write target.
  */
 export function resolveImproveReadSource(config, scopedRef, explicitTarget, fallbackStashDir) {
     if (scopedRef?.origin && explicitTarget && scopedRef.origin !== explicitTarget) {
-        throw new UsageError(`Qualified ref bundle "${scopedRef.origin}" conflicts with --target "${explicitTarget}".`, "INVALID_FLAG_VALUE", `Drop --target or use --target ${scopedRef.origin}.`);
+        throw new UsageError(`Qualified ref bundle "${scopedRef.origin}" conflicts with ${IMPROVE_TARGET_FLAG} "${explicitTarget}".`, "INVALID_FLAG_VALUE", `Drop ${IMPROVE_TARGET_FLAG} or use ${IMPROVE_TARGET_FLAG} ${scopedRef.origin}.`);
     }
     const selector = scopedRef?.origin ?? explicitTarget ?? config.defaultWriteTarget;
     if (!selector && fallbackStashDir)
         return { source: { name: "stash", path: fallbackStashDir } };
+    if (!selector && process.env.AKM_BUNDLE_DIR?.trim()) {
+        // A live run's working bundle starts from AKM_BUNDLE_DIR (`resolveWorkingStashTarget`), so its preview does too.
+        const { source } = resolveWorkingStashTarget(config, { requireWritable: false });
+        return { source: { name: source.name, path: source.path } };
+    }
     const configuredSelector = selector ?? config.defaultBundle;
     if (configuredSelector) {
         const entry = bundlesToSourceEntries(config)?.find((source) => source.name === configuredSelector);
@@ -339,10 +346,12 @@ function resolveImproveRunSetup(options) {
     const writeTarget = options.dryRun
         ? undefined
         : scopedRef?.origin
-            ? resolveMutationTarget(config, scopedRef, options.writeTarget?.source.name ?? options.target).target
+            ? resolveMutationTarget(config, scopedRef, options.writeTarget?.source.name ?? options.target, {
+                flag: IMPROVE_TARGET_FLAG,
+            }).target
             : (options.writeTarget ??
                 (options.target || config.defaultWriteTarget || !options.stashDir
-                    ? resolveWriteTarget(config, options.target)
+                    ? resolveWriteTarget(config, options.target, { flag: IMPROVE_TARGET_FLAG })
                     : {
                         source: { kind: "filesystem", name: "stash", path: options.stashDir },
                         config: { type: "filesystem", name: "stash", path: options.stashDir, writable: true },

package/dist/commands/improve/ledger.js

@@ -9,9 +9,9 @@
 import fs from "node:fs";
 import { getStateDbPath, withImmediateTransaction, withStateDb } from "../../core/state-db.js";
 import { warn } from "../../core/warn.js";
-import { isLedgerBlocked, listImproveLedgerRows, PAIR_PASS_LEDGER_SOURCE, recordImproveLedger, } from "../../storage/repositories/improve-ledger-repository.js";
+import { isContentDrivenRow, isLedgerBlocked, listImproveLedgerRows, PAIR_PASS_LEDGER_SOURCE, recordImproveLedger, } from "../../storage/repositories/improve-ledger-repository.js";
 import { openSqliteReadSnapshot } from "../../storage/sqlite-read-snapshot.js";
-export { isLedgerBlocked, PAIR_PASS_LEDGER_SOURCE };
+export { isContentDrivenRow, isLedgerBlocked, PAIR_PASS_LEDGER_SOURCE };
 /** An improve candidate's durable state key: its index item_ref, else its conceptId. */
 export function stateKey(ref, itemRef) {
     return itemRef ?? ref;

package/dist/commands/improve/loop-stages.js

@@ -136,6 +136,8 @@ async function runLoopReflectPass(planned, env, tally) {
     if (reflectErrors.length > 0)
         tally.reflectsWithErrorContext++;
     const budgetMs = env.remainingBudgetMs();
+    // `planned` was selected from the run's write target alone (eligibility.ts), so the
+    // `target` below is the bundle `planned.itemRef` is read from and the proposal is filed in.
     const reflectArgs = {
         ref: planned.ref,
         ...(planned.itemRef ? { itemRef: planned.itemRef } : {}),

package/dist/commands/improve/preparation.js

@@ -209,6 +209,8 @@ async function runConsolidationPass(args) {
             maxChunkSize: processConfig?.maxChunkSize,
             signal: args.budgetSignal,
             p90ChunkSecondsDefault: processConfig?.p90ChunkSecondsDefault,
+            // Its read-only proposal lookups go through the run's own state.db handle.
+            ...(eventsCtx?.db ? { proposalsCtx: { db: eventsCtx.db } } : {}),
         }));
     }
     return { consolidation, plan: planned.plan };
@@ -791,7 +793,7 @@ function fetchRetrievalSignals(options, signalFiltered, noFeedbackCandidates, ev
         // usage_events live in state.db, entries in index.db.
         withRunState(eventsCtx, persist, (stateDb) => {
             if (countUsageEventsByType(stateDb, "show") === 0) {
-                warn("Warning: show events not yet in usage_events — zero-feedback fallback will match only search-retrieved assets.");
+                warn("Warning: show events not yet in usage_events — the retrieval scope will match only search-retrieved assets.");
             }
             const refs = [...new Set([...signalFiltered, ...noFeedbackCandidates].map((r) => r.ref))];
             out.retrievalCounts = getRetrievalCounts(indexDb, stateDb, refs, { sourceName: options.sourceName });

package/dist/commands/improve/reflect.js

@@ -761,7 +761,7 @@ async function gatherReflectPromptSources(options, stash, parsedRef, assetConten
         relatedLessons: options.ref && parsedRef
             ? await readRelatedLessons(stash, options.ref, parsedRef, options.itemRef, options.eventsCtx)
             : [],
-        rejectedProposals: rejectedProposalContext(stash, options.ref, options.ctx),
+        rejectedProposals: rejectedProposalContext(stash, options.ref, options.ctx, options.eventsCtx),
         standardsContext: resolveStandardsContext(options.ref, stash),
     };
 }
@@ -1036,7 +1036,7 @@ async function finalizeReflectProposal(args) {
         payload: { content: payload.content, ...(Object.keys(frontmatter).length > 0 ? { frontmatter } : {}) },
         ...(typeof payload.confidence === "number" ? { confidence: payload.confidence } : {}),
         ...(options.eligibilitySource ? { eligibilitySource: options.eligibilitySource } : {}),
-        ...(options.itemRef ? { attemptedRefs: [options.itemRef] } : {}),
+        ...(options.itemRef ? { itemRef: options.itemRef, attemptedRefs: [options.itemRef] } : {}),
     }, reviewReasons.length > 0
         ? {
             review: {

package/dist/commands/improve/stage.js

@@ -100,12 +100,14 @@ export const MAX_REJECTED_PROPOSALS = 3;
 /**
  * Reflexion context: the newest reviewer rejections for `ref`. Procedural
  * refusals (expiry, stale target, missing asset) are not judgements on the
- * content and are left out. Reads never create state.db.
+ * content and are left out. Reads never create state.db, and an improve run's
+ * live connection (`eventsCtx.db`) is read through, not copied.
  */
-export function rejectedProposalContext(stash, ref, ctx) {
+export function rejectedProposalContext(stash, ref, ctx, eventsCtx) {
     if (!ref)
         return [];
-    return listProposalsReadOnly(stash, { ref, status: "rejected", includeArchive: true }, ctx)
+    const proposalsCtx = eventsCtx?.db ? { ...ctx, db: eventsCtx.db } : ctx;
+    return listProposalsReadOnly(stash, { ref, status: "rejected", includeArchive: true }, proposalsCtx)
         .filter((p) => !isProceduralRejection(p))
         .sort((a, b) => new Date(b.updatedAt ?? 0).getTime() - new Date(a.updatedAt ?? 0).getTime())
         .slice(0, MAX_REJECTED_PROPOSALS)
@@ -156,18 +158,20 @@ export function buildJudgePrompt(lessonContent, sourceContent, similarLessons) {
         "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.",
         "",
         "Source asset content:",
         "```",
-        sourceContent.slice(0, 2000),
+        // 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 lower if the proposed lesson is substantially similar to any of these:");
+        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), "```");
     }
-    lines.push("", "Proposed lesson content:", "```", lessonContent.slice(0, 1000), "```", "", 'Return ONLY valid JSON, no prose: {"scores": {"novelty": <1-5 integer>, "nonRedundancy": <1-5 integer>}, "reason": "<one sentence>"}');
+    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>"}');
     return lines.join("\n");
 }
 function boundedDocument(content, maxChars = 6000) {
@@ -227,12 +231,26 @@ export function buildReflectJudgePrompt(candidateContent, sourceContent, feedbac
         'Return ONLY valid JSON, no prose: {"scores": {"feedbackAlignment": <1-5 integer>, "preservation": <1-5 integer>, "quality": <1-5 integer>}, "reason": "<one sentence>"}',
     ].join("\n");
 }
-const LESSON_JUDGE_CRITERIA = ["novelty", "nonRedundancy"];
+/**
+ * `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 the mean would pass it (or, in the review band, mint it as
+ * a pending proposal). A score of {@link UNGROUNDED_MAX_SCORE} or less is a
+ * rejection whatever the mean says (#999). Only a different subject scores that
+ * low. 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.
+ */
+const GROUNDING_CRITERION = "grounding";
+const UNGROUNDED_MAX_SCORE = 2;
+const LESSON_JUDGE_CRITERIA = ["novelty", "nonRedundancy", GROUNDING_CRITERION];
 const REFLECT_JUDGE_CRITERIA = ["feedbackAlignment", "preservation", "quality"];
 /**
- * Read a judge response: the per-criterion shape (averaged here) or the older
- * `{"score"}` shape. Only the expected criteria are read; any missing or
- * out-of-range (1..5) value is a parse failure, extra keys are ignored.
+ * Read a judge response: the per-criterion shape (averaged here, `grounding`
+ * aside) or the older `{"score"}` shape. Only the expected criteria are read;
+ * any missing or out-of-range (1..5) value is a parse failure, extra keys are
+ * ignored.
  */
 function parseJudgeResponse(raw, keys) {
     const parsed = parseEmbeddedJsonResponse(raw);
@@ -251,7 +269,10 @@ function parseJudgeResponse(raw, keys) {
                 return undefined;
             criteria[key] = value;
         }
-        return { score: Object.values(criteria).reduce((a, b) => a + b, 0) / keys.length, reason, criteria };
+        const averaged = Object.entries(criteria)
+            .filter(([key]) => key !== GROUNDING_CRITERION)
+            .map(([, value]) => value);
+        return { score: averaged.reduce((a, b) => a + b, 0) / averaged.length, reason, criteria };
     }
     return inRange(parsed.score) ? { score: parsed.score, reason } : undefined;
 }
@@ -274,7 +295,8 @@ function judgeResponseSchema(keys) {
 /**
  * The quality judge. Fails closed: no runner, an unparseable verdict or a
  * provider failure never passes content. Bands: >= 3.5 pass, 2.5-3.5 review,
- * < 2.5 reject. Temperature is pinned to 0 so verdicts do not flip.
+ * < 2.5 reject; a `grounding` score of {@link UNGROUNDED_MAX_SCORE} or less
+ * rejects whatever the mean is. Temperature is pinned to 0 so verdicts do not flip.
  */
 async function runQualityJudge(feature, config, prompt, keys, chat, options) {
     const resolved = !options.runnerSelectionFrozen && !options.llmRunner
@@ -307,6 +329,15 @@ 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, 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,
+        };
+    }
     const verdict = score >= 3.5 ? { pass: true } : score >= 2.5 ? { pass: false, reviewNeeded: true } : { pass: false };
     return { ...verdict, score, reason, ...(criteria ? { criteria } : {}) };
 }

package/dist/commands/proposal/diff-format.js

@@ -48,3 +48,24 @@ export function formatNewAssetDiff(ref, content) {
     }
     return lines.join("\n");
 }
+/**
+ * Render the all-removals diff for a retire proposal (#997): the file its
+ * accept archives, line by line, and nothing added. Padding the proposed side
+ * with an empty string, as {@link formatUnifiedDiff} does, reads as "the whole
+ * file replaced by one blank line" — a retirement reviewed as data loss.
+ * `existing` is `null` when the retired file is already gone.
+ */
+export function formatRetireDiff(ref, existing, successorRef) {
+    const destination = `+++ /dev/null (retired: archived${successorRef ? `; successor ${successorRef}` : ""})`;
+    if (existing === null)
+        return [`--- ${ref} (missing)`, destination].join("\n");
+    const removed = existing.split("\n");
+    if (removed[removed.length - 1] === "")
+        removed.pop(); // the newline ending the file is not a line of its own
+    return [
+        `--- ${ref} (existing)`,
+        destination,
+        `@@ 1,${removed.length} 0,0 @@`,
+        ...removed.map((line) => `-${line}`),
+    ].join("\n");
+}