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

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/loop-stages.js

@@ -475,15 +475,16 @@ export async function runMemoryInferenceMaintenancePass(ctx, dbCell, memoryRefsF
 export async function runGraphExtractionMaintenancePass(ctx, dbCell, args) {
     const { config, sources, primaryStashDir, resolvedPlan } = ctx;
     const settings = ctx.improveProfile?.processes?.graphExtraction;
-    const graphEnabled = resolvedPlan ? true : isProcessEnabled("index", "graph_extraction", config);
     if (settings?.enabled === false) {
         info("[improve] graph extraction skipped (disabled by improve profile)");
         return { durationMs: 0, warnings: [] };
     }
     if (sources.length === 0)
         return { durationMs: 0, warnings: [] };
-    if (!graphEnabled) {
-        info("[improve] graph extraction skipped (features.index.graph_extraction is disabled)");
+    // `index.graph.enabled: false` turns graph extraction off everywhere,
+    // whatever the strategy enables.
+    if (!isProcessEnabled("index", "graph_extraction", config)) {
+        info("[improve] graph extraction skipped (index.graph.enabled is false)");
         return { durationMs: 0, warnings: [] };
     }
     const fullScan = settings?.fullScan === true;

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

package/dist/commands/improve/retrieval-gate.js

@@ -0,0 +1,127 @@
+// 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 retrieval regression gate (#722): a reflect rewrite of an existing asset
+ * must not grade lower on the queries that actually retrieved it.
+ *
+ * Measured before it was built: of 60 accepted reflect rewrites judged against
+ * their own queries, 14 graded lower (23%, 95% CI 14–35%) and 12 higher. The
+ * old and new content are graded one query at a time, blind, with the
+ * retrieval-eval judge's prompt (kappa 0.83 against human grades) and its
+ * document shape: type, ref, name, description and the first 1,500 characters
+ * of the body.
+ */
+import relevanceJudgePrompt from "../../assets/prompts/retrieval-relevance-judge.md" with { type: "text" };
+import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { parseRefInput } from "../../core/asset/resolve-ref.js";
+import { nonTaskInput } from "../../core/non-task-input.js";
+import { parseEmbeddedJsonResponse } from "../../core/parse.js";
+import { listRetrievalQueries } from "../../indexer/usage/usage-events.js";
+import { readLedgerDb, stripBundle } from "./ledger.js";
+import { callStage } from "./stage.js";
+/** Queries graded per rewrite, as measured. */
+const MAX_QUERIES = 5;
+/** The retrieval suite treats a longer input as a paste, not a query; the measurement did the same. */
+const MAX_QUERY_CHARS = 2000;
+/** The judge sees this much of the body, as in the retrieval eval. */
+const MAX_DOC_CHARS = 1500;
+const GRADE_SCHEMA = {
+    type: "object",
+    required: ["grade", "reason"],
+    additionalProperties: false,
+    properties: { grade: { type: "integer", minimum: 0, maximum: 3 }, reason: { type: "string" } },
+};
+/** Up to five distinct task queries, in the given order, whitespace collapsed. */
+export function usableRetrievalQueries(raw) {
+    const out = [];
+    for (const text of raw) {
+        const query = text.replace(/\s+/g, " ").trim();
+        if (!query || query.length > MAX_QUERY_CHARS || nonTaskInput(query) || out.includes(query))
+            continue;
+        out.push(query);
+        if (out.length === MAX_QUERIES)
+            break;
+    }
+    return out;
+}
+/** The asset's own retrieval queries from the usage log (none when state.db cannot be read). */
+export function loadRetrievalQueries(access, ref) {
+    try {
+        return usableRetrievalQueries(readLedgerDb(access, (db) => listRetrievalQueries(db, stripBundle(ref))) ?? []);
+    }
+    catch {
+        return [];
+    }
+}
+function judgeDocument(ref, raw) {
+    const conceptId = stripBundle(ref);
+    const parsed = parseRefInput(conceptId);
+    const { data, content } = parseFrontmatter(raw);
+    const text = content
+        .replace(/\n{3,}/g, "\n\n")
+        .trim()
+        .slice(0, MAX_DOC_CHARS);
+    const name = typeof data.name === "string" && data.name ? data.name : parsed.name;
+    const description = typeof data.description === "string" ? data.description : "";
+    return [
+        "Candidate asset:",
+        `Type: ${parsed.type}`,
+        `Ref: ${conceptId}`,
+        `Name: ${name}`,
+        `Description: ${description}`,
+        "",
+        "Content:",
+        text,
+    ].join("\n");
+}
+/**
+ * Grade `before` and `after` on each query; refuse the rewrite when the new
+ * content's mean grade is lower. Fails closed, like the quality judge: a grade
+ * that cannot be obtained refuses the rewrite.
+ */
+export async function runRetrievalRegressionGate(args) {
+    if (args.queries.length === 0)
+        return { pass: true, queries: 0, reason: "no retrieval queries to compare on" };
+    const documents = { old: judgeDocument(args.ref, args.before), new: judgeDocument(args.ref, args.after) };
+    const totals = { old: 0, new: 0 };
+    for (const query of args.queries) {
+        for (const version of ["old", "new"]) {
+            const outcome = await callStage({
+                feature: "proposal_quality_gate",
+                runner: args.runner,
+                system: relevanceJudgePrompt.trim(),
+                prompt: `Query: ${query}\n\n${documents[version]}`,
+                request: {
+                    enableThinking: false,
+                    temperature: 0,
+                    responseSchema: GRADE_SCHEMA,
+                    ...(args.timeoutMs !== undefined ? { timeoutMs: args.timeoutMs } : {}),
+                    ...(args.signal ? { signal: args.signal } : {}),
+                    ...(args.chat ? { chat: args.chat } : {}),
+                },
+                ...(args.onNotices ? { onNotices: args.onNotices } : {}),
+            });
+            const grade = outcome.ok ? parseEmbeddedJsonResponse(outcome.raw)?.grade : undefined;
+            if (typeof grade !== "number" || !Number.isInteger(grade) || grade < 0 || grade > 3) {
+                return {
+                    pass: false,
+                    queries: args.queries.length,
+                    reason: `retrieval check could not grade the ${version} content${outcome.ok ? "" : ` (${outcome.reason})`}`,
+                };
+            }
+            totals[version] += grade;
+        }
+    }
+    const oldMean = totals.old / args.queries.length;
+    const newMean = totals.new / args.queries.length;
+    const pass = newMean >= oldMean;
+    const grades = `${oldMean.toFixed(2)} -> ${newMean.toFixed(2)} over ${args.queries.length} retrieval ${args.queries.length === 1 ? "query" : "queries"}`;
+    return {
+        pass,
+        queries: args.queries.length,
+        oldMean,
+        newMean,
+        reason: pass ? `retrieval grade ${grades}` : `retrieval regression: grade ${grades}`,
+    };
+}

package/dist/commands/improve/retrieval-scope.js

@@ -0,0 +1,77 @@
+// 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/.
+/**
+ * What improve may rework (#986): an asset that retrieval returned inside the
+ * usage window, or newly captured material no improve stage has processed.
+ *
+ * Fresh feedback and an explicit `--scope <ref>` are usage evidence of their
+ * own, so the signal-delta and scope lanes need no check. The fallback lanes
+ * (proactive maintenance, high salience, forgetting safety) and consolidation
+ * pick assets without such evidence, so they pick only inside this scope.
+ */
+import fs from "node:fs";
+import { daysToMs } from "../../core/common.js";
+import { warn } from "../../core/warn.js";
+import { listUsedEntryRefs, USAGE_EVENT_RETENTION_DAYS } from "../../indexer/usage/usage-events.js";
+import { listImproveLedgerRows } from "../../storage/repositories/improve-ledger-repository.js";
+import { listProposalRefSources } from "../../storage/repositories/proposals-repository.js";
+import { readLedgerDb, stripBundle } from "./ledger.js";
+/**
+ * Ledger and proposal sources that bring material in. Every other source is an
+ * improve stage reworking an asset (reflect, distill, consolidate, schema repair).
+ */
+const CAPTURE_SOURCES = new Set(["extract", "propose", "remember", "import"]);
+/**
+ * Load the scope from state.db. The window is the usage log's retention: the
+ * log keeps nothing older, and anything shorter would drop assets read less
+ * often than the window. A `.derived` hit counts for its parent memory, whose
+ * facts it carries. `undefined` (every asset eligible, as before #986) only
+ * when state.db cannot be read.
+ */
+export function loadRetrievalScope(access, stashDir) {
+    const sinceMs = Date.now() - daysToMs(USAGE_EVENT_RETENTION_DAYS);
+    const used = new Set();
+    const processed = new Set();
+    try {
+        readLedgerDb(access, (db) => {
+            for (const entryRef of listUsedEntryRefs(db, new Date(sinceMs).toISOString())) {
+                const conceptId = stripBundle(entryRef);
+                used.add(conceptId);
+                if (conceptId.endsWith(".derived"))
+                    used.add(conceptId.slice(0, -".derived".length));
+            }
+            if (!stashDir)
+                return;
+            for (const row of [...listImproveLedgerRows(db, stashDir), ...listProposalRefSources(db, stashDir)]) {
+                if (!CAPTURE_SOURCES.has(row.source))
+                    processed.add(stripBundle(row.ref));
+            }
+        });
+    }
+    catch (error) {
+        warn(`[improve] usage history unreadable, so every asset stays eligible: ${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
+    return { used, processed, sinceMs };
+}
+/**
+ * Whether improve may rework `ref` (whose file is `filePath`) under `scope`. An
+ * unprocessed asset whose file cannot be read is left to the disk check that
+ * follows, which reports it as missing.
+ */
+export function isInRetrievalScope(scope, ref, filePath) {
+    if (!scope)
+        return true;
+    const conceptId = stripBundle(ref);
+    if (scope.used.has(conceptId))
+        return true;
+    if (scope.processed.has(conceptId))
+        return false;
+    try {
+        return filePath === undefined || fs.statSync(filePath).mtimeMs >= scope.sinceMs;
+    }
+    catch {
+        return true;
+    }
+}

package/dist/commands/read/curate.js

@@ -9,15 +9,19 @@
  * needed to act (ref, run, parameters, follow-up command).
  *
  * Curation is one search with the fused ranking, the top `limit` hits, and
- * per-hit enrichment (preview, run and parameters, graph support refs). An
- * optional reranker reorders the top fused candidates first.
+ * per-hit enrichment (preview, run and parameters, support refs from the
+ * hit's declared links). An optional reranker reorders the top fused
+ * candidates first.
  *
  * The exported `akmCurate()` API is the single entry point; tests can also
  * drive `curateSearchResults` with a fixture search response.
  */
+import { parseBundleRef } from "../../core/asset/asset-ref.js";
+import { typeNameFromConceptId } from "../../core/asset/resolve-ref.js";
 import { loadConfig } from "../../core/config/config.js";
 import { rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
+import { nonTaskInput } from "../../core/non-task-input.js";
 import { redactCredentialPatterns } from "../../core/redaction.js";
 import { withStateDbTelemetry } from "../../core/state-db.js";
 import { searchHitContent } from "../../indexer/search/db-search.js";
@@ -33,8 +37,6 @@ import { akmSearch, parseSearchSource } from "./search.js";
 import { akmShowUnified } from "./show.js";
 const DEFAULT_CURATE_LIMIT = 4;
 const MAX_CURATE_SUPPORT_REFS = 2;
-/** The line of `src/assets/stash-skeleton/README.md` that reaches curate verbatim as a query. */
-const STASH_README_LINE = "This is an **AKM stash** — a structured knowledge repository that stores reusable";
 /** Fused candidates the reranker reorders when `search.curateRerank.topN` is unset. */
 const DEFAULT_CURATE_RERANK_TOP_N = 30;
 /** Characters of name, description and content sent to the reranker per candidate. */
@@ -131,21 +133,6 @@ export async function akmCurate(options) {
     }
     return result;
 }
-/**
- * What the (trimmed) curate input is when it is not a task, else undefined.
- * Harness and tool envelopes (`<task-notification>…`, `<system-reminder>…`,
- * `<cross-session-message …>…`) start with a tag and close one, and the stash
- * README line arrives verbatim; on the retrieval suite neither shape occurs in
- * a real query. Length is not a signal: prompts over 2,000 characters found
- * relevant assets at about the rate of shorter long prompts.
- */
-function nonTaskInput(query) {
-    if (query.startsWith("<") && query.includes("</"))
-        return "a harness or tool envelope";
-    if (query === STASH_README_LINE)
-        return "the akm stash README boilerplate";
-    return undefined;
-}
 export async function curateSearchResults(query, result, limit, selectedType, eventSource) {
     const allStashHits = result.hits.filter((hit) => hit.type !== "registry");
     const registryHits = result.registryHits ?? [];
@@ -228,7 +215,7 @@ async function enrichCuratedStashHit(query, hit, selectedRefs, eventSource) {
     }
     const description = shown?.description ?? hit.description;
     const preview = buildCuratedPreview(shown, hit);
-    const supportRefs = buildCurateSupportRefs(shown?.related?.hits, selectedRefs, hit.ref);
+    const supportRefs = buildCurateSupportRefs(shown?.links, selectedRefs, hit.ref);
     const item = {
         source: "local",
         type: shown?.type ?? hit.type,
@@ -340,17 +327,41 @@ async function maybeRerankCuratedStashHits(query, hits) {
 function rerankDocumentTexts(hits) {
     return hits.map((hit) => [hit.name, hit.description, searchHitContent(hit)].filter(Boolean).join("\n").slice(0, RERANK_DOCUMENT_CHARS));
 }
-/** Up to {@link MAX_CURATE_SUPPORT_REFS} graph-related assets not already selected. */
-function buildCurateSupportRefs(relatedHits, selectedRefs, ownerRef) {
+/**
+ * Up to {@link MAX_CURATE_SUPPORT_REFS} assets the hit's declared links (#935)
+ * name, not already selected: what the hit links to first, then what links to
+ * it, in the order `akm show` lists them. The LLM entity graph's `related`
+ * list no longer feeds them.
+ */
+function buildCurateSupportRefs(links, selectedRefs, ownerRef) {
     const supportRefs = [];
-    for (const hit of relatedHits ?? []) {
-        if (!hit.ref || hit.ref === ownerRef || selectedRefs.has(hit.ref))
-            continue;
-        if (supportRefs.some((existing) => existing.ref === hit.ref))
-            continue;
-        supportRefs.push({ ref: hit.ref, type: hit.type, reason: "Related asset via shared entities." });
-        if (supportRefs.length >= MAX_CURATE_SUPPORT_REFS)
-            break;
+    for (const [part, direction] of [
+        ["outgoing", "from"],
+        ["incoming", "to"],
+    ]) {
+        for (const [kind, group] of Object.entries(links?.[part] ?? {})) {
+            for (const ref of group.refs) {
+                if (ref === ownerRef || selectedRefs.has(ref) || supportRefs.some((existing) => existing.ref === ref))
+                    continue;
+                const type = supportRefType(ref);
+                supportRefs.push({
+                    ref,
+                    ...(type ? { type } : {}),
+                    reason: `Declared link (${kind}) ${direction} this asset.`,
+                });
+                if (supportRefs.length >= MAX_CURATE_SUPPORT_REFS)
+                    return supportRefs;
+            }
+        }
     }
     return supportRefs;
 }
+/** The asset type a ref's conceptId names (`memories/x` → `memory`), when it names one. */
+function supportRefType(ref) {
+    try {
+        return typeNameFromConceptId(parseBundleRef(ref).conceptId)?.type;
+    }
+    catch {
+        return undefined;
+    }
+}