akm-cli 0.9.17-alpha.6 → 0.9.17-alpha.7

package/CHANGELOG.md

@@ -6,6 +6,152 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.17-alpha.7] - 2026-09-28
+
+A scheduled task is now just a command and a schedule. Each native row
+carries its own `AKM_BUNDLE_DIR` instead of pointing at a descriptor file,
+and the runtime reads only v4 task files; older files convert once with
+`akm migrate apply`. The first `akm task sync` after upgrading rewrites each
+row once, keeping every task and schedule. `akm improve` reworks only assets
+that retrieval returned or that are new, and reflect refuses a rewrite that
+grades worse on the asset's own searches. `--require-engines` no longer
+skips a run because the LLM endpoint is busy.
+
+### Changed
+
+- **akm reads only task source v4.** A `version: 2` or `version: 3` task
+  file, or a `version: 4` file that still carries 0.9.15's retired
+  `schedule[].enabled`, now fails on its own with a message naming
+  `akm migrate apply`, which converts it once, under a backup (`akm upgrade`
+  runs it after an install). Until now every read converted such a file in
+  memory. `akm task sync` reports each one as a failure, leaves its installed
+  row as it is, and keeps reconciling every other task; `akm task run`,
+  `akm lint` and `akm task validate` report it the same way, and
+  `akm task validate`'s `converts` outcome is gone (such a file is
+  `blocked`). `akm migrate apply` now also converts the tasks of the stash
+  `AKM_BUNDLE_DIR` selects when no configured bundle names it, since the
+  runtime reads those too, and a root whose top-level task files are all
+  v2/v3 is still detected as an `akm-task` bundle, so they are found and
+  converted. A host whose task files are all v4 (`akm migrate status`
+  reports `current`) sees no difference.
+  (`src/tasks/source/parse-task-source.ts`, `src/commands/tasks/validate.ts`,
+  `scripts/akm-migrate/task-migrate.ts`,
+  `src/core/adapter/adapters/akm-task-adapter.ts`)
+- **A scheduled row is its command plus its schedule, and carries its own
+  context.** Rows no longer name a `--scheduler-context` descriptor file;
+  they set what it held themselves. Every row sets `AKM_BUNDLE_DIR` to the
+  working stash of the shell that ran `akm task sync`, plus any
+  `AKM_CONFIG_DIR`, `AKM_DATA_DIR`, `AKM_CACHE_DIR` or `AKM_STATE_DIR` that
+  shell set explicitly: a `VAR=value` prefix in the crontab, an
+  `EnvironmentVariables` entry in a launchd plist, a `$env:VAR='value';`
+  assignment ahead of the command in Task Scheduler (its action has no
+  environment of its own). Scheduled runs see the same environment as
+  before, and sync still tells installations sharing a crontab apart by
+  that path (#846).
+  **What hosts see:** the first `akm task sync` after upgrading rewrites
+  every akm row once. `akm task sync --dry-run` lists each one as an update,
+  never an add or a remove; each keeps its launcher and its schedule, and
+  the `--scheduler-context <file>` argument becomes an inline
+  `AKM_BUNDLE_DIR=<working stash>`. On a host whose working stash is
+  `/home/u/akm` a row changes from
+
+  ```text
+  30 8 * * * /home/u/.bun/bin/bun /home/u/.bun/lib/node_modules/akm-cli/dist/akm --scheduler-context /home/u/.local/share/akm/tasks/context/e898….json task run capture --bundle akm --scheduled > /home/u/.cache/akm/tasks/logs/capture.log 2>&1
+  ```
+
+  to
+
+  ```text
+  30 8 * * * AKM_BUNDLE_DIR=/home/u/akm /home/u/.bun/bin/bun /home/u/.bun/lib/node_modules/akm-cli/dist/akm task run capture --bundle akm --scheduled > /home/u/.cache/akm/tasks/logs/capture.log 2>&1
+  ```
+
+  Rows written by 0.9.0 through 0.9.17-alpha.6 keep firing until that sync:
+  the CLI still accepts `--scheduler-context <file>` and applies the file's
+  environment (PATH included, for a 0.9.16 row). The files under
+  `$DATA/tasks/context/` are no longer written, and the uid, mode, symlink
+  and content-hash checks made on every scheduled run are gone. A sync
+  leaves some rows as they are (one whose task file failed to load, one a
+  `--bundle` sync did not cover), and those still name their file: once
+  `akm task doctor` lists no binding with a `contextPath`, nothing reads
+  them and they can be deleted. `akm task prune` now
+  finds rows whose `AKM_BUNDLE_DIR` names a directory that is gone, and older
+  rows whose descriptor cannot be read; `akm task doctor` lists `contextPath`
+  only for an older row. (`src/tasks/scheduler-invocation.ts`,
+  `src/tasks/backends/cron.ts`, `src/tasks/backends/launchd.ts`,
+  `src/tasks/backends/schtasks.ts`, `src/tasks/scheduler-sync.ts`,
+  `src/commands/tasks/tasks.ts`)
+- **`akm improve` reworks only what gets read (#986).** An asset with fresh
+  feedback, or one you name (`akm improve skills/x`), is handled as before.
+  Every other pick must now be in the retrieval scope. That covers the
+  proactive-maintenance, high-salience and forgetting-safety lanes, and the
+  memories consolidation judges. An asset is in scope if a user `search`,
+  `curate` or `show` returned it, or user `feedback` named it, in the last 90
+  days, which is the usage log's retention. A hit on a `.derived` memory counts
+  for its parent. New material that no improve stage has processed yet is also
+  in scope. There is no new config key.
+
+  Measured with `akm improve --dry-run` on a copy of the maintainer's bundle
+  (19,870 assets), against 0.9.17-alpha.6:
+  - The fallback lanes pick from 6,450 assets instead of 15,686, and 9,236
+    refs are left out. No lane setting can reach the unread tail any more. In
+    July the proactive lane rewrote 3,069 assets, and 3,059 of them had not
+    been retrieved since the usage log began on 1 July.
+  - Consolidation judges 59 memories instead of 69.
+  - The high-salience lane no longer admits distill outputs nobody has read (2
+    today).
+  - Under the scheduled caps, today's nightly work is unchanged. The default
+    strategy selects the same 50 feedback-driven refs, and weekly proactive
+    maintenance selects the same 25, because salience ranking already puts
+    retrieved assets first.
+
+  `akm improve --dry-run` and the run result report the left-out refs as a new
+  `retrieval` gate. Health reports them under the skip reason `not_retrieved`.
+  Improve results stored by earlier releases, which have no such gate, still
+  decode. (`src/commands/improve/retrieval-scope.ts`,
+  `src/commands/improve/preparation.ts`, `src/commands/improve/consolidate.ts`)
+
+- **Reflect refuses a rewrite that makes an asset worse for its own searches
+  (#722).** Before reflect proposes a rewrite of an existing asset, it grades
+  the old and the new content on up to five of the queries that actually
+  retrieved the asset (user `search` and `curate`). It uses the retrieval
+  eval's relevance prompt, which agrees with human grades at kappa 0.83. When
+  the new content grades lower on average, the rewrite is refused the same way
+  a quality-judge rejection is: `quality_rejected`, with the 14-day reflect
+  window. An asset without retrieval queries is not graded.
+
+  This was measured before it was built. Of 60 accepted rewrites since July,
+  judged this way, 14 graded lower (23%, 95% CI 14–35%) and 12 graded higher.
+  The gate was built because the lower bound cleared the 10% threshold set
+  before any judging. It costs two judge calls per query on the engine that
+  already runs the quality judge. On the maintainer's 2026-09-28 nightly run,
+  whose 30 rewrites had 102 usable queries, that is 204 calls, about 6 more
+  minutes on a 73-minute run. (`src/commands/improve/retrieval-gate.ts`,
+  `src/commands/improve/reflect.ts`)
+
+### Fixed
+
+- **A cron row too long for one line is seen by `akm task sync` again.** A
+  command over 1,000 bytes runs from a wrapper script, and sync could not
+  read which task such a row ran: every sync, and every `--dry-run`, showed
+  it as an add and wrote it again. Sync now reads the script, so the row is
+  unchanged or an update like any other. (`src/tasks/backends/cron.ts`)
+- **A `$` or a backslash in a scheduled row's value is kept.** launchd and
+  Task Scheduler rows passed their values through a string replacement that
+  read `$'`, `$&` and `$$` as patterns, so a path such as a Windows admin
+  share (`\\nas\share\akm$`) came out corrupted; reading a crontab row
+  back dropped a backslash inside a single-quoted value.
+  (`src/tasks/backends/launchd.ts`, `src/tasks/backends/schtasks.ts`,
+  `src/tasks/backends/cron.ts`)
+- **`akm improve --require-engines` no longer skips a run because the LLM
+  endpoint is busy.** Its reachability probe, one short completion, gave up
+  after 3 seconds, so a local server busy with another job looked
+  unreachable and the whole scheduled run failed (all four scheduled runs on
+  2026-09-27). The probe now waits up to the engine's own `timeoutMs`, at
+  most two minutes, so a busy server can answer while a hung one still fails
+  fast. The error's hint now says to check the endpoint rather than to run
+  `akm setup`.
+  (`src/commands/improve/improve-cli.ts`)
+
 ## [0.9.17-alpha.6] - 2026-09-27
 
 Graph extraction stops losing and wasting work. A timed-out extraction is

package/STABILITY.md

@@ -281,8 +281,8 @@ CHANGELOG with a migration note.
   print unredacted. `akm task validate <path>` (new in 0.9.11) is the same
   kind of zero-write introspection as `explain`, but takes a bare filesystem
   path rather than a bundle-qualified ref — it reports whether that ONE file
-  would parse cleanly (`valid`), auto-convert from task v2/v3 (`converts`),
-  need a human decision the deterministic migrator can't make (`blocked`),
+  would parse cleanly (`valid`), need `akm migrate apply` first (`blocked`:
+  task v2/v3, or a retired `schedule[].enabled`),
   fail schema validation (`invalid`), or isn't a task source at all
   (`not-a-task`) — exactly the diagnostic `akm task sync` would produce for
   it, before the file is ever wired into a bundle or the scheduler.

package/dist/akm

@@ -6,13 +6,13 @@
 import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
-// `--scheduler-context <descriptor>` passes through untouched: the CLI loads
-// and validates it before anything else (`consumeSchedulerContextArg` in
-// src/cli.ts). The scheduler supplies PATH itself (the crontab's `# akm:env`
-// line, a launchd plist's EnvironmentVariables), so runtime selection below
-// needs nothing from the descriptor. This launcher used to re-validate the
-// descriptor with its own copy of the schema, and that copy rejected every
-// descriptor the CLI writes since 0.9.17.
+// A scheduled row sets its environment itself (a cron `VAR=value` prefix, a
+// launchd plist's EnvironmentVariables), and the scheduler supplies PATH, so
+// runtime selection below needs nothing from it. A row written by 0.9.0 –
+// 0.9.17-alpha.6 passes `--scheduler-context <descriptor>` instead; it passes
+// through untouched, and the CLI applies it (`consumeSchedulerContextArg` in
+// src/cli.ts). This launcher used to re-validate the descriptor with its own
+// copy of the schema, and that copy rejected every descriptor 0.9.17 wrote.
 
 process.env.AKM_LAUNCHER_NODE = process.execPath;
 process.env.AKM_LAUNCHER_PATH = fileURLToPath(import.meta.url);

package/dist/assets/prompts/retrieval-relevance-judge.md

@@ -0,0 +1,6 @@
+You are grading search-and-retrieval results for an AI coding agent's knowledge base (the akm tool). For the given query and ONE candidate asset, grade how useful loading this asset would be, on this scale:
+3 = exactly the asset an agent should load for this query or task; it directly answers or performs the request.
+2 = relevant and clearly useful, though not the single best asset for the query.
+1 = same general topic as the query, but would not actually help complete this specific query or task.
+0 = unrelated to the query.
+Reply with ONLY a JSON object: {"grade": <integer 0-3>, "reason": "<=25 words"}.

package/dist/commands/improve/consolidate.js

@@ -26,6 +26,7 @@ import { warn, warnVerbose } from "../../core/warn.js";
 import { resolveWriteTarget } from "../../core/write-source.js";
 import { deriveInstallations } from "../../indexer/installations.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
+import { USAGE_EVENT_RETENTION_DAYS } from "../../indexer/usage/usage-events.js";
 import { assertRunnerCredentials } from "../../integrations/agent/runner-dispatch.js";
 import { cosineSimilarity, embedBatch, resolveEmbeddingModelId } from "../../llm/embedder.js";
 import { getBodyEmbeddings, upsertBodyEmbeddings } from "../../storage/repositories/embeddings-repository.js";
@@ -39,6 +40,7 @@ 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 { 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. */
 export function isValidOp(op) {
@@ -428,6 +430,11 @@ export function inspectConsolidationPool(opts, stashDir, warnings, existingKnowl
         });
     }
     const judgedUnchanged = poolSize - memories.length;
+    // Only what retrieval returned or new material improve never processed (#986).
+    const retrievalScope = loadRetrievalScope({ proposalsCtx: opts.proposalsCtx, readOnly }, stashDir);
+    const beforeScope = memories.length;
+    memories = memories.filter((memory) => isInRetrievalScope(retrievalScope, conceptIdFromTypeName("memory", memory.name), memory.filePath));
+    const outsideRetrievalScope = beforeScope - memories.length;
     if (opts.incrementalSince && memories.length > 0) {
         memories = narrowToIncrementalCandidates(memories, opts.incrementalSince, warnings, opts.neighborsPerChanged, readOnly);
     }
@@ -465,6 +472,7 @@ export function inspectConsolidationPool(opts, stashDir, warnings, existingKnowl
         memories,
         prefilteredAlreadyPromoted,
         judgedUnchanged,
+        outsideRetrievalScope,
     };
 }
 const ABORT_MIN_CHUNKS = 4;
@@ -641,6 +649,9 @@ async function consolidate(opts, config, stashDir, startMs, stateDb) {
     if (pool.judgedUnchanged > 0) {
         warnings.push(`Consolidation: skipped ${pool.judgedUnchanged} ${plural(pool.judgedUnchanged)} judged within the revisit window 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.`);
+    }
     if (prefilteredAlreadyPromoted > 0) {
         warnings.push(`Consolidation: pre-filtered ${prefilteredAlreadyPromoted} ${plural(prefilteredAlreadyPromoted)} whose body already exists verbatim in knowledge/ before chunking.`);
     }

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

@@ -14,6 +14,7 @@ import { getCacheDir } from "../../core/paths.js";
 import { redactSensitiveText } from "../../core/redaction.js";
 import { clearLogFile, setLogFile, warn } from "../../core/warn.js";
 import { resolveWriteTarget } from "../../core/write-source.js";
+import { DEFAULT_LLM_TIMEOUT_MS } from "../../integrations/agent/config.js";
 import { collectEngineCredentialValues } from "../../integrations/agent/engine-resolution.js";
 import { probeLlmReachable } from "../../llm/client.js";
 import { getOutputMode } from "../../output/context.js";
@@ -77,25 +78,44 @@ function collectRequiredEngineTargets(plan) {
     const targets = [];
     for (const [processName, process] of Object.entries(plan.processes)) {
         if (process.runner) {
-            targets.push({ process: processName, engine: process.runner.engine, connection: process.runner.connection });
+            targets.push({
+                process: processName,
+                engine: process.runner.engine,
+                connection: probeConnection(process.runner),
+            });
         }
     }
     if (plan.triageJudgment?.kind === "llm") {
         targets.push({
             process: "triage.judgment",
             engine: plan.triageJudgment.engine,
-            connection: plan.triageJudgment.connection,
+            connection: probeConnection(plan.triageJudgment),
         });
     }
     return targets;
 }
+/** The resolved engine keeps its request timeout beside the connection (the runtime merges it in); the probe needs it on the connection. */
+function probeConnection(runner) {
+    return runner.timeoutMs !== undefined ? { ...runner.connection, timeoutMs: runner.timeoutMs } : runner.connection;
+}
+/**
+ * The bound on `--require-engines`' probe: the connection's own request
+ * timeout, at most two minutes. A local server busy with another job queues
+ * the probe behind that job, and a fixed 3s bound failed every scheduled
+ * improve run on 2026-09-27 against a reachable endpoint; the cap still ends a
+ * hung endpoint (#957) long before a run's own multi-minute calls would.
+ */
+export function requiredEngineProbeTimeoutMs(connection) {
+    return Math.min(connection.timeoutMs ?? DEFAULT_LLM_TIMEOUT_MS, REQUIRED_ENGINE_PROBE_MAX_MS);
+}
+const REQUIRED_ENGINE_PROBE_MAX_MS = 120_000;
 /**
  * `--require-engines`, live: probe each connection's real completion path
- * (a gateway can list a model whose completion route is dead, #980) with a 3s
- * bound, once per endpoint + model. Returns each target's latency for the run
- * result (R17); an unreachable one fails the run.
+ * (a gateway can list a model whose completion route is dead, #980), once per
+ * endpoint + model, within {@link requiredEngineProbeTimeoutMs}. Returns each
+ * target's latency for the run result (R17); an unreachable one fails the run.
  */
-export async function assertRequiredEnginesReachable(plan, probeReachable = (connection) => probeLlmReachable(connection, 3_000)) {
+export async function assertRequiredEnginesReachable(plan, probeReachable = (connection) => probeLlmReachable(connection, requiredEngineProbeTimeoutMs(connection))) {
     const targets = collectRequiredEngineTargets(plan);
     if (targets.length === 0)
         return [];
@@ -117,7 +137,7 @@ export async function assertRequiredEnginesReachable(plan, probeReachable = (con
     const unreachable = probed.filter((item) => !item.reach.reachable);
     if (unreachable.length > 0) {
         const lines = unreachable.map((item) => `  - ${item.process} (engine "${item.engine}", ${item.connection.endpoint}): ${item.reach.error ?? "did not respond"}`);
-        throw new ConfigError(`--require-engines: ${unreachable.length} improve process${unreachable.length === 1 ? "" : "es"} cannot run because ${unreachable.length === 1 ? "its" : "their"} engine completion path is not reachable:\n${lines.join("\n")}`, "LLM_NOT_CONFIGURED");
+        throw new ConfigError(`--require-engines: ${unreachable.length} improve process${unreachable.length === 1 ? "" : "es"} cannot run because ${unreachable.length === 1 ? "its" : "their"} engine completion path is not reachable:\n${lines.join("\n")}`, "LLM_NOT_CONFIGURED", "Check that each listed endpoint is up and serves its model. The probe is one short completion, bounded by the engine's timeoutMs (at most two minutes).");
     }
     return probed.map((item) => ({
         process: item.process,

package/dist/commands/improve/ledger.js

@@ -82,13 +82,17 @@ export function recordLedgerAttempt(access, inputs) {
 export function ledgerKey(source, ref) {
     return `${source}\0${ref}`;
 }
+/** Read state.db through `fn` without creating it: `undefined` when there is none yet. */
+export function readLedgerDb(access, fn) {
+    if (!access?.eventsCtx?.db && !fs.existsSync(ledgerDbPath(access) ?? getStateDbPath()))
+        return undefined;
+    return withLedgerDb(access, fn);
+}
 /** Every ledger row for `sources` in one query; no state.db yet means nothing was attempted. */
 export function loadLedgerSnapshot(access, stashDir, sources) {
     const out = new Map();
-    if (!access?.eventsCtx?.db && !fs.existsSync(ledgerDbPath(access) ?? getStateDbPath()))
-        return out;
     try {
-        withLedgerDb(access, (db) => {
+        readLedgerDb(access, (db) => {
             for (const row of listImproveLedgerRows(db, stashDir, sources))
                 out.set(ledgerKey(row.source, row.ref), row);
         });

package/dist/commands/improve/preparation.js

@@ -23,7 +23,7 @@ import { ConfigError, rethrowIfTestIsolationError } from "../../core/errors.js";
 import { appendEvent, readEvents } from "../../core/events.js";
 import { withStateDb } from "../../core/state-db.js";
 import { info, warn } from "../../core/warn.js";
-import { countUsageEventsByType } from "../../indexer/usage/usage-events.js";
+import { countUsageEventsByType, USAGE_EVENT_RETENTION_DAYS } from "../../indexer/usage/usage-events.js";
 import { getAvailableHarnesses } from "../../integrations/session-logs/index.js";
 import { getZeroResultSearches } from "../../storage/repositories/index-entries-repository.js";
 import { getRetrievalCounts } from "../../storage/repositories/index-utility-repository.js";
@@ -41,6 +41,7 @@ import { applyMemoryCleanup } from "./memory/memory-improve.js";
 import { getAllAssetOutcomes, getAssetOutcome, getOutcomeScoresByRef, OUTCOME_SCORE_MAX, outcomeScoreToSalience, projectAssetOutcome, updateAssetOutcome, } from "./outcome-loop.js";
 import { projectMemoryCleanup, selectEffectiveImproveRefs } from "./planner.js";
 import { DEFAULT_DUE_DAYS, DEFAULT_MAX_PER_RUN, selectProactiveMaintenanceRefs } from "./proactive-maintenance.js";
+import { isInRetrievalScope, loadRetrievalScope } from "./retrieval-scope.js";
 import { buildRankChangeReport, computeSalience, getAllRankScores, getAssetSalience, getLastUseMsByRef, isContentEncodingRow, SALIENCE_NO_OP_DAMPEN_FACTOR, SALIENCE_NO_OP_DAMPEN_THRESHOLD, upsertAssetSalience, } from "./salience.js";
 import { attributeStage, errMessage } from "./stage.js";
 /** The candidate's durable state key (salience, outcome, ledger). */
@@ -663,12 +664,23 @@ async function selectLoopCandidates(args, postCleanupRefs, validationFailureRefs
     const processableRefs = [...partition.eligibleRefs, ...partition.distillOnlyRefs];
     const signalFiltered = processableRefs.filter((c) => snapshot.feedback.get(c.ref)?.hasSignal === true);
     const signalBearingSet = new Set(signalFiltered.map((r) => r.ref));
-    const noFeedbackCandidates = dedupeRefs([
+    // The fallback lanes (proactive, high salience, forgetting safety) have no
+    // usage evidence of their own: they pick only what retrieval returned or new
+    // material improve never processed (#986). Evaluated once per candidate.
+    const fallbackEligible = postCleanupRefs.filter((c) => !validationFailureRefs.has(c.ref));
+    const allowFallbacks = options.requireFeedbackSignal !== true;
+    const retrievalScope = scope.mode === "ref" || !allowFallbacks
+        ? undefined
+        : loadRetrievalScope({ eventsCtx, ...(persist ? {} : { readOnly: true }) }, primaryStashDir ?? options.stashDir);
+    const unscoped = new Set(fallbackEligible.filter((c) => !isInRetrievalScope(retrievalScope, c.ref, c.filePath)).map((c) => c.ref));
+    const noFeedbackPool = dedupeRefs([
         ...processableRefs.filter((r) => !signalBearingSet.has(r.ref)),
         ...partition.noFeedbackPool,
     ]);
+    const noFeedbackCandidates = noFeedbackPool.filter((r) => !unscoped.has(r.ref));
+    // Only a ref no fallback lane may pick anymore is charged to the retrieval gate.
+    const outOfScope = new Set(noFeedbackPool.filter((r) => unscoped.has(r.ref)).map((r) => r.ref));
     const retrieval = fetchRetrievalSignals(options, signalFiltered, noFeedbackCandidates, eventsCtx, persist);
-    const allowFallbacks = options.requireFeedbackSignal !== true;
     const proactive = allowFallbacks
         ? selectProactiveMaintenanceLane(args, noFeedbackCandidates, snapshot, retrieval, persist)
         : { proactiveRefs: [] };
@@ -692,10 +704,10 @@ async function selectLoopCandidates(args, postCleanupRefs, validationFailureRefs
             sourceByRef.set(r.ref, "scope");
     for (const r of mergedRefs)
         r.eligibilitySource = sourceByRef.get(r.ref) ?? "unknown";
-    // Forgetting safety may only reuse this plan's own surviving objects, and
-    // never a ref whose reflect window is still open.
-    const fallbackEligible = postCleanupRefs.filter((c) => !validationFailureRefs.has(c.ref));
-    const forgettingEligible = fallbackEligible.filter((c) => !isLedgerBlocked(ledgerRowFor(snapshot.ledger, "reflect", c.ref, c.itemRef), snapshot.nowIso));
+    // Forgetting safety may only reuse this plan's own surviving objects inside
+    // the retrieval scope, and never a ref whose reflect window is still open.
+    const forgettingEligible = fallbackEligible.filter((c) => !unscoped.has(c.ref) &&
+        !isLedgerBlocked(ledgerRowFor(snapshot.ledger, "reflect", c.ref, c.itemRef), snapshot.nowIso));
     const scored = scoreSalience(args, mergedRefs, snapshot.feedback, retrieval.retrievalCounts, persist);
     mergedRefs = applyForgettingSafety({
         pendingForgettingRefs: scored.pendingForgettingRefs,
@@ -739,28 +751,46 @@ async function selectLoopCandidates(args, postCleanupRefs, validationFailureRefs
     // Skip observability waits until every fallback lane has finalized the
     // survivors, so a rescued ref is never also reported skipped.
     const survivors = new Set(sorted.map((c) => c.ref));
-    const signalSkipped = fallbackEligible.filter((c) => !survivors.has(c.ref));
+    const skipped = fallbackEligible.filter((c) => !survivors.has(c.ref));
+    const retrievalSkipped = skipped.filter((c) => outOfScope.has(c.ref));
+    const signalSkipped = skipped.filter((c) => !outOfScope.has(c.ref));
     for (const ref of partition.distillCooledRefs) {
         actions.push({ ref, mode: "distill-skipped", result: { ok: true, reason: "distill signal-delta" } });
         if (persist)
             recordImproveSkip(eventsCtx, ref, { reason: "distill_no_new_signal" });
     }
-    for (const candidate of signalSkipped) {
+    for (const candidate of skipped) {
         actions.push({
             ref: candidate.ref,
             mode: "distill-skipped",
-            result: { ok: true, reason: "no new signal since last proposal" },
+            result: {
+                ok: true,
+                reason: outOfScope.has(candidate.ref)
+                    ? "not retrieved inside the usage window"
+                    : "no new signal since last proposal",
+            },
         });
     }
     if (persist && signalSkipped.length > 0) {
         recordImproveSkip(eventsCtx, undefined, { reason: "no_new_signal", count: signalSkipped.length });
     }
+    if (persist && retrievalSkipped.length > 0) {
+        recordImproveSkip(eventsCtx, undefined, { reason: "not_retrieved", count: retrievalSkipped.length });
+    }
     const blocked = signalSkipped.length + partition.distillOnlyRefs.length;
     if (blocked > 0) {
         info(`[improve] ${blocked} of ${partition.preCooldownCount} indexed refs blocked by reflect signal-delta ` +
             `(${signalSkipped.length} fully skipped, ${partition.distillOnlyRefs.length} routed to distill-only)`);
     }
+    if (retrievalSkipped.length > 0) {
+        info(`[improve] ${retrievalSkipped.length} refs left out: not retrieved in the last ${USAGE_EVENT_RETENTION_DAYS} days, and not new material`);
+    }
     const gates = [
+        {
+            name: "retrieval",
+            removed: retrievalSkipped.length,
+            reason: `no feedback, and neither returned by search, curate or show in the last ${USAGE_EVENT_RETENTION_DAYS} days nor new material improve never processed`,
+        },
         {
             name: "signal",
             removed: signalSkipped.length,

package/dist/commands/improve/reflect.js

@@ -43,6 +43,7 @@ import { findAssetFilePath } from "./eligibility.js";
 import { resolveImproveLlmExecution } from "./execution.js";
 import { recordLedgerAttempt } from "./ledger.js";
 import { classifyReflectChange, splitFrontmatter } from "./reflect-noise.js";
+import { loadRetrievalQueries, runRetrievalRegressionGate } from "./retrieval-gate.js";
 import { callStage, mintProposal, noticeSet, rejectedProposalContext, runReflectQualityJudge, } from "./stage.js";
 const MAX_FEEDBACK_LINES = 10;
 const MAX_GLOBAL_FEEDBACK_LINES = 20;
@@ -960,6 +961,24 @@ async function finalizeReflectProposal(args) {
     }
     const flagged = Boolean(sanitized.sizeGuardRatio || sanitized.truncationMarkerLeaked);
     const judged = judge.enabled && !flagged;
+    /** A judge refused the revision: record it for the ledger's rejection window and stop. */
+    const refuse = (detail, metadata, message) => {
+        if (options.ref) {
+            recordLedgerAttempt({ proposalsCtx: options.ctx, eventsCtx: options.eventsCtx }, {
+                stashDir: run.stash,
+                ref: options.itemRef ?? options.ref,
+                source: "reflect",
+                outcome: "quality_rejected",
+                detail,
+            });
+        }
+        appendEvent({
+            eventType: "reflect_completed",
+            ref: payload.ref,
+            metadata: { source: "reflect", qualityRejected: true, ...metadata, ...telemetry },
+        }, options.eventsCtx);
+        return reflectFailure(run, result, "quality_rejected", message, false);
+    };
     if (judged) {
         const verdict = await runReflectQualityJudge(run.config, payload.content, assetContent ?? "", feedback, options.chat, {
             runnerSelectionFrozen: true,
@@ -969,28 +988,33 @@ async function finalizeReflectProposal(args) {
             onNotices: run.notices.add,
         });
         if (!verdict.pass) {
-            if (options.ref) {
-                recordLedgerAttempt({ proposalsCtx: options.ctx, eventsCtx: options.eventsCtx }, {
-                    stashDir: run.stash,
-                    ref: options.itemRef ?? options.ref,
-                    source: "reflect",
-                    outcome: "quality_rejected",
-                    detail: verdict.reason,
-                });
-            }
-            appendEvent({
-                eventType: "reflect_completed",
-                ref: payload.ref,
-                metadata: {
-                    source: "reflect",
-                    qualityRejected: true,
-                    qualityScore: verdict.score,
-                    qualityReason: verdict.reason,
-                    ...(verdict.criteria ? { qualityCriteria: verdict.criteria } : {}),
-                    ...telemetry,
-                },
-            }, options.eventsCtx);
-            return reflectFailure(run, result, "quality_rejected", `Reflect proposal quality gate rejected: score=${verdict.score}, reason="${verdict.reason}"`, false);
+            return refuse(verdict.reason, {
+                qualityScore: verdict.score,
+                qualityReason: verdict.reason,
+                ...(verdict.criteria ? { qualityCriteria: verdict.criteria } : {}),
+            }, `Reflect proposal quality gate rejected: score=${verdict.score}, reason="${verdict.reason}"`);
+        }
+    }
+    // #722: a rewrite of an existing asset must not grade lower on its own retrieval queries.
+    if (judged && judge.runner && assetContent !== undefined) {
+        const retrieval = await runRetrievalRegressionGate({
+            ref: payload.ref,
+            before: assetContent,
+            after: payload.content,
+            queries: loadRetrievalQueries({ proposalsCtx: options.ctx, eventsCtx: options.eventsCtx }, payload.ref),
+            runner: judge.runner,
+            ...(options.chat ? { chat: options.chat } : {}),
+            ...(Object.hasOwn(options, "timeoutMs") ? { timeoutMs: options.timeoutMs } : {}),
+            ...(options.signal ? { signal: options.signal } : {}),
+            onNotices: run.notices.add,
+        });
+        if (!retrieval.pass) {
+            return refuse(retrieval.reason, {
+                retrievalRegression: true,
+                retrievalQueries: retrieval.queries,
+                ...(retrieval.oldMean !== undefined ? { retrievalGradeBefore: retrieval.oldMean } : {}),
+                ...(retrieval.newMean !== undefined ? { retrievalGradeAfter: retrieval.newMean } : {}),
+            }, `Reflect proposal refused: ${retrieval.reason}`);
         }
     }
     // A lesson reflect wrote is marked so a later reflect on the same skill does