akm-cli 0.10.261008-beta → 0.10.261010-beta

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

@@ -5,15 +5,13 @@
  * The consolidate pair pass (0.9.17-alpha.9 plan §5.2, brief §A): runs
  * alongside the existing promote pass inside `akmConsolidate`, over new and
  * changed memory-tier assets. Judges each near-duplicate/superseding pair
- * with the calibrated relation prompt and mints a reviewed `retire` proposal
- * for the `duplicate` / `subsumed` / `supersedes` classes — never merges,
- * never writes belief edges for `contradicts`, and is never auto-accepted by
- * triage (`drain.ts`).
+ * with complete claim comparisons and mints a reviewed `retire` proposal
+ * for derived `duplicate` / `subsumed` outcomes — never merges,
+ * never writes belief edges. A staged retirement can be accepted unattended
+ * by triage (`drain.ts`); an unstaged one stays pending.
  *
- * Calibration (owner grades, 2026-09-28; see the plan's "Human calibration,
- * O5" section): the combined retire class (duplicate ∪ subsumed ∪
- * supersedes) is 20/22 = 0.91 precision against the owner. `T_PAIR` is 0.93,
- * not the initial 0.90, because the 0.90–0.93 band alone graded 3/4 (R1).
+ * Pair-selection calibration (owner grades, 2026-09-28): `T_PAIR` stays
+ * 0.93, not the initial 0.90, because the 0.90–0.93 band alone graded 3/4 (R1).
  *
  * Initiator eligibility and dating (post-review, alpha.9): "created" is the
  * asset's git first-add time (one `git log` per run, {@link loadGitFirstAddedMap}),
@@ -30,6 +28,8 @@ import fs from "node:fs";
 import path from "node:path";
 import consolidatePairPrompt from "../../../assets/prompts/consolidate-pair.md" with { type: "text" };
 import consolidatePairCheckPrompt from "../../../assets/prompts/consolidate-pair-check.md" with { type: "text" };
+import consolidatePairSameAge from "../../../assets/prompts/consolidate-pair-same-age.md" with { type: "text" };
+import consolidatePairTerms from "../../../assets/prompts/consolidate-pair-terms.md" with { type: "text" };
 import { parseFrontmatter } from "../../../core/asset/frontmatter.js";
 import { conceptIdFromTypeName } from "../../../core/asset/resolve-ref.js";
 import { asNonEmptyString } from "../../../core/common.js";
@@ -37,6 +37,7 @@ import { concurrentMap } from "../../../core/concurrent.js";
 import { parseEmbeddedJsonResponse } from "../../../core/parse.js";
 import { DERIVED_SUFFIX } from "../../../core/recognition-util.js";
 import { warnOnce } from "../../../core/warn.js";
+import { sameScope, scopeFromFrontmatter } from "../../../indexer/passes/metadata.js";
 import { runnerLlmConnection } from "../../../integrations/agent/runner.js";
 import { assertRunnerCredentials } from "../../../integrations/agent/runner-dispatch.js";
 import { runGit } from "../../../sources/providers/git-install.js";
@@ -67,28 +68,22 @@ export const BACKFILL_FLOOR = 0.95;
 export const NEW_MATERIAL_DAYS = 7;
 /** Pairs judged per run, highest cosine first (plan §7's nightly cost budget). */
 export const MAX_PAIRS_PER_RUN = 300;
-/** Body characters sent to the judge per side: enough for nearly every note, so a retirement is judged on the whole text. */
-const PAIR_BODY_TRUNCATE_CHARS = 12_000;
 const MS_PER_DAY = 86_400_000;
-const RELATION_LABELS = ["duplicate", "subsumed", "supersedes", "contradicts", "overlap", "unrelated"];
 const RETIRE_LABELS = new Set(["duplicate", "subsumed", "supersedes"]);
-/** The classes that mint a `retire` proposal (the calibrated combined retire class, 20/22 precision). */
+/** The labels represented by the existing retirement metadata. */
 function isRetireLabel(label) {
     return RETIRE_LABELS.has(label);
 }
 /** Exported, with {@link buildPairUserPrompt}, so a replay can drive the exact judge call. */
 export const PAIR_JUDGE_JSON_SCHEMA = {
     type: "object",
-    required: ["onlyInA", "onlyInB", "relation", "redundant", "stale", "confidence", "reason"],
+    required: ["reason", "onlyInA", "onlyInB", "confidence"],
     additionalProperties: false,
     properties: {
+        reason: { type: "string", maxLength: 400 },
         onlyInA: { type: "array", items: { type: "string", maxLength: 200 }, maxItems: 20 },
         onlyInB: { type: "array", items: { type: "string", maxLength: 200 }, maxItems: 20 },
-        relation: { type: "string", enum: [...RELATION_LABELS] },
-        redundant: { type: ["string", "null"], enum: ["A", "B", null] },
-        stale: { type: ["string", "null"], enum: ["A", null] },
         confidence: { type: "number", minimum: 0, maximum: 1 },
-        reason: { type: "string", maxLength: 400 },
     },
 };
 export const PAIR_CHECK_JSON_SCHEMA = {
@@ -97,17 +92,11 @@ export const PAIR_CHECK_JSON_SCHEMA = {
     additionalProperties: false,
     properties: { missing: { type: "array", items: { type: "string", maxLength: 200 }, maxItems: 20 } },
 };
-/** Hand-validates the judge's JSON, independent of whatever the provider's own schema enforcement did. */
+/** Validate both claim lists, then derive the outcome instead of asking the model to duplicate that decision. */
 export function parsePairJudgeResponse(raw) {
     const parsed = parseEmbeddedJsonResponse(raw);
     if (!parsed)
         return undefined;
-    if (typeof parsed.relation !== "string" || !RELATION_LABELS.includes(parsed.relation)) {
-        return undefined;
-    }
-    const redundant = parsed.redundant;
-    if (redundant !== "A" && redundant !== "B" && redundant !== null)
-        return undefined;
     if (typeof parsed.confidence !== "number" || !Number.isFinite(parsed.confidence))
         return undefined;
     const confidence = Math.max(0, Math.min(1, parsed.confidence));
@@ -116,7 +105,13 @@ export function parsePairJudgeResponse(raw) {
     const onlyInB = claimList(parsed.onlyInB);
     if (!onlyInA || !onlyInB)
         return undefined;
-    return { onlyInA, onlyInB, relation: parsed.relation, redundant, confidence, reason };
+    const relation = onlyInA.length === 0 && onlyInB.length === 0
+        ? "duplicate"
+        : onlyInA.length === 0 || onlyInB.length === 0
+            ? "subsumed"
+            : "overlap";
+    const redundant = onlyInA.length === 0 ? "A" : onlyInB.length === 0 ? "B" : null;
+    return { onlyInA, onlyInB, relation, redundant, confidence, reason };
 }
 function claimList(value) {
     if (!Array.isArray(value) || !value.every((v) => typeof v === "string"))
@@ -383,6 +378,10 @@ export function selectCandidates(db, initiators, bundleId, unvectored) {
         // rest of the backlog (no row, not recently git-added) needs the higher
         // BACKFILL_FLOOR.
         const floor = initiator.backlog && !initiator.newMaterial ? BACKFILL_FLOOR : T_PAIR;
+        const initiatorSide = loadSide(initiator, undefined, "");
+        if (!initiatorSide)
+            continue;
+        const scope = scopeFromFrontmatter(initiatorSide.frontmatter);
         let kept = 0;
         for (const hit of getNeighborsByEntryId(db, initiator.entryId, PAIR_NEIGHBOR_FETCH_K)) {
             if (kept >= PAIR_NEIGHBOR_K)
@@ -411,6 +410,9 @@ export function selectCandidates(db, initiators, bundleId, unvectored) {
             const cosine = 1 - (hit.distance * hit.distance) / 2;
             if (cosine < floor)
                 continue;
+            const otherSide = loadSide(other, undefined, "");
+            if (!otherSide || !sameScope(scope, scopeFromFrontmatter(otherSide.frontmatter)))
+                continue;
             const key = pairKey(initiator.ref, other.ref);
             if (seenPairs.has(key))
                 continue;
@@ -460,11 +462,22 @@ function sideSection(label, side) {
         `Description: ${asNonEmptyString(side.frontmatter.description) ?? "(none)"}`,
         "Content:",
         "```",
-        stripFrontmatterBody(side.raw).slice(0, PAIR_BODY_TRUNCATE_CHARS),
+        stripFrontmatterBody(side.raw),
         "```",
         "",
     ];
 }
+/** Lexical attention hints only: equal token sets do not prove equal claims. */
+function exclusiveTerms(side, other) {
+    const tokens = (note) => new Set(`${asNonEmptyString(note.frontmatter.description) ?? ""}\n${stripFrontmatterBody(note.raw)}`
+        .split(/\s+/)
+        .filter(Boolean));
+    const otherTerms = tokens(other);
+    return JSON.stringify([...tokens(side)].filter((term) => !otherTerms.has(term)));
+}
+function termHints(lines) {
+    return consolidatePairTerms.replace("{{DIFFERENCES}}", lines.join("\n"));
+}
 /** Orders two loaded sides by date (older/newer) for the "A (older)"/"B (newer)" labelling the prompt requires. */
 function orderByAge(x, y) {
     const xMs = Date.parse(x.createdIso);
@@ -480,6 +493,11 @@ export function buildPairUserPrompt(older, newer) {
     return [
         ...sideSection(tied ? "A (same age as B)" : "A (older)", older),
         ...sideSection(tied ? "B (same age as A)" : "B (newer)", newer),
+        termHints([
+            `Tokens only in A: ${exclusiveTerms(older, newer)}`,
+            `Tokens only in B: ${exclusiveTerms(newer, older)}`,
+        ]),
+        ...(tied ? [consolidatePairSameAge] : []),
     ].join("\n");
 }
 /** The tombstone-vocabulary reason a judge label maps to (`supersedes` -> `superseded`; the rest unchanged). */
@@ -489,8 +507,7 @@ export function tombstoneReason(label) {
 /**
  * The calibrated outcome table (owner grades, replacing plan §5.2's
  * "shorter body" rule): `duplicate`/`supersedes` keep the newer copy;
- * `subsumed` keeps the side the judge did NOT name `redundant` (no proposal
- * if that pointer is missing or invalid). A side is retired only when the
+ * `subsumed` keeps the side opposite the derived `redundant` pointer. A side is retired only when the
  * judge listed nothing that it alone holds.
  */
 export function decideRetirement(label, redundant, older, newer, only) {
@@ -512,7 +529,7 @@ function checkSection(label, side) {
         `Description: ${asNonEmptyString(side.frontmatter.description) ?? "(none)"}`,
         "Content:",
         "```",
-        stripFrontmatterBody(side.raw).slice(0, PAIR_BODY_TRUNCATE_CHARS),
+        stripFrontmatterBody(side.raw),
         "```",
         "",
     ].join("\n");
@@ -528,7 +545,7 @@ async function confirmNothingLost(ctx, retired, successor) {
         feature: "memory_consolidation",
         runner: ctx.llmRunner,
         system: consolidatePairCheckPrompt,
-        prompt: `${checkSection("X (to delete)", retired)}\n${checkSection("Y (kept)", successor)}`,
+        prompt: `${checkSection("X (to delete)", retired)}\n${checkSection("Y (kept)", successor)}\n${termHints([`Tokens only in X: ${exclusiveTerms(retired, successor)}`])}${Date.parse(retired.createdIso) === Date.parse(successor.createdIso) ? `\n${consolidatePairSameAge}` : ""}`,
         gate: { config: ctx.config, enabled: true },
         request: {
             responseSchema: PAIR_CHECK_JSON_SCHEMA,
@@ -554,6 +571,13 @@ async function judgeOne(ctx, candidate) {
     const otherSide = loadSide(candidate.other, ctx.gitFirstAdded, ctx.stashDir);
     if (!initiatorSide || !otherSide)
         return { failed: false }; // unreadable since selection — skip, not a judge failure
+    const judgedScope = scopeFromFrontmatter(initiatorSide.frontmatter);
+    if (!sameScope(judgedScope, scopeFromFrontmatter(otherSide.frontmatter)))
+        return { failed: false };
+    const scopesStillFresh = () => [initiatorSide, otherSide].every((side) => {
+        const live = loadSide(side.asset, ctx.gitFirstAdded, ctx.stashDir);
+        return live !== undefined && sameScope(judgedScope, scopeFromFrontmatter(live.frontmatter));
+    });
     // Item 0 / S1: this exact pair (same two refs, same two content hashes,
     // EITHER orientation) was already judged and rejected OR reverted. Checked
     // HERE, before the judge call, not after — the judge (not yet run) is what
@@ -651,7 +675,10 @@ async function judgeOne(ctx, candidate) {
         ledgerAccess: { proposalsCtx: ctx.opts.proposalsCtx },
         search: ctx.continuitySearch,
     });
+    if (!scopesStillFresh())
+        return { failed: true };
     const retirement = {
+        judgedScope,
         retiredRef: retired.asset.ref,
         successorRef: successor.asset.ref,
         cosine: candidate.cosine,
@@ -691,7 +718,8 @@ async function judgeOne(ctx, candidate) {
         // reviewed pairs (2026-10-04). Anything else waits for a person.
         if ((verdict.relation !== "duplicate" || verdict.onlyInA.length + verdict.onlyInB.length === 0) &&
             !continuityRisk &&
-            (await confirmNothingLost(ctx, retired, successor))) {
+            (await confirmNothingLost(ctx, retired, successor)) &&
+            scopesStillFresh()) {
             recordGateDecision(ctx.stashDir, proposal.id, {
                 outcome: "staged",
                 reason: verdict.relation,

package/dist/commands/improve/extract.js

@@ -189,17 +189,27 @@ export function parseSinceArg(value, now = Date.now()) {
     throw new UsageError(`--since value "${value}" could not be parsed (expected ISO timestamp or duration like 24h / 7d / 30m)`, "INVALID_FLAG_VALUE");
 }
 /**
- * A candidate's ref and content. `description` (and a lesson's `when_to_use`)
- * go into the body's frontmatter so accept-time validation sees them.
+ * Assemble candidate metadata once in the authoritative Markdown that acceptance
+ * publishes. The payload projection is for proposal readers, not another write path.
  */
 function buildCandidateProposal(candidate, sourceRef, sessionAssetRef) {
     const ref = deriveExtractCandidateRef(candidate, sourceRef);
     // Complete a description the model cut mid-sentence (no-op for valid ones).
     const description = repairTruncatedDescription(candidate.description, candidate.body);
-    const fm = { description, ...(sessionAssetRef ? { xrefs: [sessionAssetRef] } : {}) };
-    if (candidate.type === "lesson" && candidate.when_to_use)
+    const fm = {
+        description,
+        evidence: candidate.evidence,
+        ...(sessionAssetRef ? { xrefs: [sessionAssetRef], evidenceSources: [sessionAssetRef] } : {}),
+    };
+    // With no published session asset, keep the known native session identity in
+    // the existing structured provenance channel, never invent an AKM asset ref.
+    // The identity, not the log's absolute path, so published notes carry no local paths.
+    if (!sessionAssetRef && sourceRef.filePath) {
+        fm.provenance = { sources: [{ resource: `${sourceRef.harness}:${sourceRef.sessionId}` }] };
+    }
+    if (candidate.when_to_use)
         fm.when_to_use = candidate.when_to_use;
-    return { ref, content: assembleAsset(fm, candidate.body), description };
+    return { ref, content: assembleAsset(fm, candidate.body), frontmatter: fm };
 }
 function canonicalSegment(value) {
     return value
@@ -496,13 +506,9 @@ async function processSession(run, sessionRef, gate) {
                     attemptedRefs: [built.ref],
                     payload: {
                         content: built.content,
-                        frontmatter: {
-                            description: built.description,
-                            ...(candidate.when_to_use ? { when_to_use: candidate.when_to_use } : {}),
-                            confidence: candidate.confidence,
-                            ...(sessionAsset.sessionAssetRef ? { xrefs: [sessionAsset.sessionAssetRef] } : {}),
-                            evidence: candidate.evidence,
-                        },
+                        // Model confidence stays on the proposal for reviewers; it is not published,
+                        // where promotion scoring would read it as a signal.
+                        frontmatter: { ...built.frontmatter, confidence: candidate.confidence },
                     },
                 });
                 proposalIds.push(proposal.id);

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

@@ -473,13 +473,13 @@ export async function runMemoryInferenceMaintenancePass(ctx, dbCell, memoryRefsF
         reEnrich: false,
         onProgress: (event) => {
             const current = event.currentRef ? ` ${event.currentRef}` : "";
-            info(`[improve] memory inference ${event.processed}/${event.total}${current} (written ${event.writtenFacts}, skipped ${event.skippedNoFacts})`);
+            info(`[improve] memory inference ${event.processed}/${event.total}${current} (written ${event.writtenFacts}, no change ${event.noChange}, skipped ${event.skippedNoFacts})`);
         },
     })));
     const memoryInference = pass.result;
     if (!memoryInference)
         return { durationMs: pass.durationMs, warnings: pass.warnings };
-    info(`[improve] memory inference complete (${memoryInference.writtenFacts} facts written from ${memoryInference.splitParents} parents)`);
+    info(`[improve] memory inference complete (${memoryInference.writtenFacts} facts written from ${memoryInference.splitParents} parents, ${memoryInference.noChange} no change)`);
     return {
         memoryInference,
         durationMs: pass.durationMs,

package/dist/commands/improve/memory/memory-belief.js

@@ -7,8 +7,8 @@
  * present edge AND demotion is a no-op; an edge without its demotion is
  * repaired) and never weakens a stronger demotion — severity is
  * superseded > contradicted > archived. (alpha.4 removed belief weights from
- * ranking: search no longer reads `beliefState` at all, and `--belief
- * current|historical` is the only reader, opt-in.)
+ * ranking: beliefState never changes rank. Search/curate filter current
+ * by default; --belief all|historical explicitly includes older context.)
  * The SCC resolver in memory-improve.ts is a state-transition writer (it
  * replaces and clears edges) and deliberately does not use this (#885).
  */

package/dist/commands/proposal/repository.js

@@ -33,9 +33,10 @@ import { assertAkmAssetWrite, commitAcceptedPaths, commitWriteTargetBoundary, pr
 import { withAssetMutationLease } from "../../indexer/index-writer-lock.js";
 import { indexWrittenAssets } from "../../indexer/index-written-assets.js";
 import { deriveInstallations } from "../../indexer/installations.js";
+import { sameScope, scopeFromFrontmatter } from "../../indexer/passes/metadata.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { insertEventOnce } from "../../storage/repositories/events-repository.js";
-import { CONSOLIDATE_LEDGER_SOURCE, forgetImproveLedgerDecision, recordImproveLedger, recordImproveLedgerDecision, reopenImproveLedgerDecision, } from "../../storage/repositories/improve-ledger-repository.js";
+import { CONSOLIDATE_LEDGER_SOURCE, forgetImproveLedgerDecision, PAIR_PASS_LEDGER_SOURCE, recordImproveLedger, recordImproveLedgerDecision, reopenImproveLedgerDecision, } from "../../storage/repositories/improve-ledger-repository.js";
 import { getStateProposal, listStateProposalIdsByPrefix, listStateProposals, upsertProposal, } from "../../storage/repositories/proposals-repository.js";
 import { openSqliteReadSnapshot } from "../../storage/sqlite-read-snapshot.js";
 import { pkgVersion } from "../../version.js";
@@ -528,6 +529,14 @@ export function archiveProposal(stashDir, id, status, reason, ctx, gateDecision)
             at: decidedAt,
             ...(reason !== undefined ? { detail: reason } : {}),
         });
+        // The pair pass settles initiators under bare refs, independently of the
+        // proposal's durable ref. A stale decision must release both inputs for
+        // reassessment through that same ledger, rather than hold an old body forever.
+        if (isRetireProposal(updated) && gateDecision?.reason === STALE_TARGET_GATE_REASON) {
+            for (const ref of retireHeldRefs(updated)) {
+                recordImproveLedger(db, { stashDir, ref, source: PAIR_PASS_LEDGER_SOURCE, outcome: "failed", at: decidedAt });
+            }
+        }
         return updated;
     }));
 }
@@ -1007,6 +1016,14 @@ export function preflightProposalPromotion(config, proposal, options = {}, ctx)
             // best-effort; the freshness check is the real staleness gate
         }
     }
+    if (prepared.promotionSource) {
+        const sourcePath = resolveAssetFilePathSafe(target.source, parseRefInput(prepared.promotionSource));
+        if (sourcePath &&
+            fs.existsSync(sourcePath) &&
+            !sameScope(scopeFromFrontmatter(parseFrontmatter(fs.readFileSync(sourcePath, "utf8")).data), scopeFromFrontmatter(parseFrontmatter(stampedContent).data))) {
+            throw new UsageError(`Promotion ${proposal.id} has incompatible source/output scope — reject and reassess.`, "INVALID_FLAG_VALUE");
+        }
+    }
     const lintBlockers = promotionLintBlockers(stampedContent, assetPath, target.source.path, ref.type, config);
     if (lintBlockers.length > 0) {
         const summary = lintBlockers.map((finding) => `[${finding.issue}] ${finding.detail}`).join("; ");
@@ -1127,7 +1144,12 @@ function retirePromotionSource(mutationTarget, accepted, paths) {
             warn(`[proposal] O1: ${accepted.id} has no recorded source hash (minted by an older release) — leaving its source ${accepted.promotionSource} unarchived.`);
             return;
         }
-        const currentHash = contentHash(fs.readFileSync(sourcePath, "utf8"), "body");
+        const sourceContent = fs.readFileSync(sourcePath, "utf8");
+        if (!sameScope(scopeFromFrontmatter(parseFrontmatter(sourceContent).data), scopeFromFrontmatter(parseFrontmatter(proposalContent(accepted)).data))) {
+            warn(`[proposal] source scope changed for ${accepted.id} — leaving ${accepted.promotionSource} unarchived.`);
+            return;
+        }
+        const currentHash = contentHash(sourceContent, "body");
         if (currentHash !== accepted.promotionSourceHash) {
             warn(`[proposal] O1: source ${accepted.promotionSource} for ${accepted.id} changed since the promotion was queued — leaving it unarchived.`);
             return;
@@ -1141,7 +1163,8 @@ function retirePromotionSource(mutationTarget, accepted, paths) {
         const record = archiveCleanupCandidate(mutationTarget.source.path, candidate, sourcePath);
         paths.push(sourcePath, path.join(mutationTarget.source.path, record.archivedPath), path.join(mutationTarget.source.path, record.auditPath));
         const twin = derivedTwinPath(sourcePath, sourceRef.type);
-        if (twin) {
+        if (twin &&
+            sameScope(scopeFromFrontmatter(parseFrontmatter(fs.readFileSync(twin, "utf8")).data), scopeFromFrontmatter(parseFrontmatter(sourceContent).data))) {
             const twinRecord = archiveCleanupCandidate(mutationTarget.source.path, candidate, twin);
             paths.push(twin, path.join(mutationTarget.source.path, twinRecord.archivedPath), path.join(mutationTarget.source.path, twinRecord.auditPath));
         }
@@ -1325,7 +1348,7 @@ function persistRetireAcceptance(stashDir, proposal, info, ctx) {
 }
 /**
  * B2: throws a stale-retire `UsageError` unless the successor still exists
- * and both sides' recorded body hashes still match their current files — the
+ * and both sides' recorded body hashes and judged scopes still match — the
  * durable half of the chain guard. Used for a fresh accept, and (4b, third
  * review round) to re-check a resumed accept whose intent was recorded but
  * nothing has moved yet: a separate proposal accepted in between (e.g. this
@@ -1335,6 +1358,15 @@ function persistRetireAcceptance(stashDir, proposal, info, ctx) {
 function assertRetirementStillFresh(proposalId, proposalRef, retirement, targetSource, retiredCurrentBytes) {
     const successorPath = resolveAssetFilePathSafe(targetSource, parseRefInput(retirement.successorRef));
     const successorBytes = successorPath && fs.existsSync(successorPath) ? fs.readFileSync(successorPath) : undefined;
+    const judgedScope = retirement.judgedScope;
+    if (!judgedScope || typeof judgedScope !== "object" || Array.isArray(judgedScope)) {
+        throw new UsageError(`Retire proposal ${proposalId} is stale — judged scope cannot be established; reject it and reassess the pair before acceptance.`, "INVALID_FLAG_VALUE");
+    }
+    if (!sameScope(scopeFromFrontmatter(parseFrontmatter(retiredCurrentBytes.toString("utf8")).data), judgedScope) ||
+        (successorBytes &&
+            !sameScope(scopeFromFrontmatter(parseFrontmatter(successorBytes.toString("utf8")).data), judgedScope))) {
+        throw new UsageError(`Retire proposal ${proposalId} is stale — scope changed since judging; reject and reassess.`, "INVALID_FLAG_VALUE");
+    }
     const retiredFresh = contentHash(retiredCurrentBytes, "body") === retirement.retiredContentHash;
     const successorFresh = successorBytes !== undefined && contentHash(successorBytes, "body") === retirement.successorContentHash;
     if (!successorBytes || !retiredFresh || !successorFresh) {
@@ -1416,14 +1448,10 @@ async function retireProposalWithLease(stashDir, config, proposal, options, ctx)
     }
     else {
         assertAkmAssetWrite(target.source);
-        // 4b (third review round): intent was recorded but Phase 2 never moved
-        // anything yet — re-run the B2 freshness check before resuming. A
-        // separate proposal accepted in the meantime (this one's successor
-        // itself retired by a B->C accept) can make the decision stale even
-        // though nothing here changed. Once something has moved, it is too late
-        // to cleanly refuse — Phase 2 below already tolerates a partial move.
-        if (working.retirement && fs.existsSync(intent.assetPath)) {
-            assertRetirementStillFresh(proposal.id, proposal.ref, working.retirement, target.source, fs.readFileSync(intent.assetPath));
+        // Revalidate the survivor even after a partial archive. The recorded original
+        // is the judged retired side when its file has already moved.
+        if (working.retirement) {
+            assertRetirementStillFresh(proposal.id, proposal.ref, working.retirement, target.source, fs.existsSync(intent.assetPath) ? fs.readFileSync(intent.assetPath) : Buffer.from(intent.backupContent));
         }
     }
     // Phase 2: move, idempotently — a resumed call skips whichever file a
@@ -1449,7 +1477,10 @@ async function retireProposalWithLease(stashDir, config, proposal, options, ctx)
     // tombstone scan above (`alreadyDone`) already finds one archived earlier,
     // so storing it was redundant persisted state.
     const twinPath = derivedTwinPath(intent.assetPath, ref.type);
-    if (twinPath && !alreadyDone.has(path.resolve(twinPath)) && fs.existsSync(twinPath)) {
+    if (twinPath &&
+        !alreadyDone.has(path.resolve(twinPath)) &&
+        fs.existsSync(twinPath) &&
+        sameScope(scopeFromFrontmatter(parseFrontmatter(fs.readFileSync(twinPath, "utf8")).data), scopeFromFrontmatter(parseFrontmatter(intent.backupContent).data))) {
         const twinRecord = archiveCleanupCandidate(mutationTarget.source.path, candidate, twinPath);
         archiveDirs.push(path.dirname(twinRecord.auditPath));
         paths.push(twinPath, path.join(mutationTarget.source.path, twinRecord.archivedPath), path.join(mutationTarget.source.path, twinRecord.auditPath));

package/dist/commands/read/curate.js

@@ -24,7 +24,7 @@ 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";
+import { matchBeliefFilter, searchHitContent } from "../../indexer/search/db-search.js";
 import { copySearchHitAttribution, getSearchHitAttribution, usageEventAttributionMetadata, } from "../../indexer/search/search-attribution.js";
 import { insertUsageEvent } from "../../indexer/usage/usage-events.js";
 import { estimateTokenCount } from "../../llm/embedders/remote.js";
@@ -32,9 +32,11 @@ import { isLlmFeatureEnabled, tryLlmFeature } from "../../llm/feature-gate.js";
 import { rerankDocuments } from "../../llm/rerank-client.js";
 import { truncateDescription } from "../../output/shapes/helpers.js";
 import { TELEMETRY_BUSY_TIMEOUT_MS, withIndexDb } from "../../storage/repositories/index-db.js";
-import { findEntryIdByRef, getItemRefById } from "../../storage/repositories/index-entries-repository.js";
-import { akmSearch, parseSearchSource } from "./search.js";
+import { findEntryIdByRef, getEntryIdByFilePath, getItemRefById, } from "../../storage/repositories/index-entries-repository.js";
+import { akmSearch, normalizeScopeFilters, parseBeliefFilterMode, parseSearchSource } from "./search.js";
 import { akmShowUnified } from "./show.js";
+// Keep the effective policy with the result through packing without changing JSON.
+const recallPolicies = new WeakMap();
 const DEFAULT_CURATE_LIMIT = 4;
 const MAX_CURATE_SUPPORT_REFS = 2;
 /** Fused candidates the reranker reorders when `search.curateRerank.topN` is unset. */
@@ -103,13 +105,19 @@ export async function akmCurate(options) {
     if (!trimmedQuery) {
         throw new UsageError('A curation query is required. Usage: akm curate "<task or prompt>" [--type <type>] [--limit <n>]', "MISSING_REQUIRED_ARGUMENT");
     }
+    const recall = {
+        type: options.type,
+        source: options.source ?? "local",
+        filters: normalizeScopeFilters(options.filters),
+        belief: parseBeliefFilterMode(options.belief ?? "current"),
+    };
     const nonTask = nonTaskInput(trimmedQuery);
     if (nonTask) {
         const abstained = {
             query: options.query,
             summary: `Curate abstained: the input is ${nonTask}, not a task.`,
             items: [],
-            tip: 'Nothing was selected on purpose. To curate for it, pass the task itself: akm curate "<what you are trying to do>".',
+            tip: 'Nothing was selected on purpose. To curate for it, pass the task itself: akm curate "<what you are trying to do>". For a literal asset or word lookup, use akm search "<literal words>".',
         };
         if (!options.skipLogging) {
             logCurateEvent(options.query, abstained, options.eventSource, options.attributionProjection);
@@ -125,15 +133,18 @@ export async function akmCurate(options) {
             // An enabled reranker reorders the top fused candidates, not just the final `limit`.
             limit: Math.max(limit, rerankTopN(loadConfig())),
             source,
+            filters: recall.filters,
+            belief: recall.belief,
             skipLogging: true,
         }));
-    const result = await curateSearchResults(options.query, searchResponse, limit, options.type, options.eventSource);
+    const result = await curateSearchResults(options.query, searchResponse, limit, options.type, options.eventSource, options.searchResponse ? undefined : recall);
+    recallPolicies.set(result, recall);
     if (!options.skipLogging) {
         logCurateEvent(options.query, result, options.eventSource, options.attributionProjection);
     }
     return result;
 }
-export async function curateSearchResults(query, result, limit, selectedType, eventSource) {
+export async function curateSearchResults(query, result, limit, selectedType, eventSource, recall) {
     const allStashHits = result.hits.filter((hit) => hit.type !== "registry");
     const registryHits = result.registryHits ?? [];
     // F3/R-018: `--type` NARROWS the candidate pool. The caller's search
@@ -145,9 +156,18 @@ export async function curateSearchResults(query, result, limit, selectedType, ev
     // F4/R-019: respect `--limit` for registry fill instead of hard-capping it
     // at a bare literal 2 — the remaining slots after stash hits ARE the cap.
     const selectedRegistryHits = selectedStashHits.length >= limit ? [] : registryHits.slice(0, limit - selectedStashHits.length);
-    const selectedRefs = new Set(selectedStashHits.map((hit) => hit.ref));
+    const selectedRefs = new Set(selectedStashHits.flatMap((hit) => {
+        if (!recall)
+            return [hit.ref];
+        try {
+            return [hit.ref, evidenceRef(hit)];
+        }
+        catch {
+            return [hit.ref]; // no longer indexed: enrichCuratedStashHit drops it
+        }
+    }));
     const items = [
-        ...(await Promise.all(selectedStashHits.map((hit) => enrichCuratedStashHit(query, hit, selectedRefs, eventSource)))),
+        ...(await Promise.all(selectedStashHits.map((hit) => enrichCuratedStashHit(query, hit, selectedRefs, eventSource, recall)))).filter((item) => item !== undefined),
         ...selectedRegistryHits.map((hit) => buildCuratedRegistryItem(query, hit)),
     ].slice(0, limit);
     return {
@@ -181,15 +201,24 @@ export async function packCuratedHits(result, budgetTokens) {
     for (const item of stashItems) {
         let shown;
         try {
-            shown = await akmShowUnified({ ref: item.ref, skipLogging: true });
+            shown = await akmShowUnified({
+                ref: evidenceRef(item),
+                skipLogging: true,
+                recall: recallPolicies.get(result) ?? { belief: "current" },
+            });
         }
         catch {
             continue;
         }
+        const historical = matchBeliefFilter(shown.beliefState, "historical");
+        const context = {
+            ...(shown.beliefState ? { beliefState: shown.beliefState } : {}),
+            ...(historical ? { reason: "Historical context; not current supporting authority." } : {}),
+        };
         const content = shown.content ?? shown.template ?? shown.prompt ?? "";
         const tokens = estimateTokenCount(content);
         if (used + tokens <= budgetTokens) {
-            packed.push({ ref: item.ref, tokens, content });
+            packed.push({ ref: item.ref, tokens, content, ...context });
             used += tokens;
             continue;
         }
@@ -197,7 +226,7 @@ export async function packCuratedHits(result, budgetTokens) {
             const remaining = budgetTokens - used;
             if (remaining > 0) {
                 const truncated = content.slice(0, remaining * 4);
-                packed.push({ ref: item.ref, tokens: estimateTokenCount(truncated), content: truncated });
+                packed.push({ ref: item.ref, tokens: estimateTokenCount(truncated), content: truncated, ...context });
                 used += estimateTokenCount(truncated);
             }
         }
@@ -205,22 +234,38 @@ export async function packCuratedHits(result, budgetTokens) {
     }
     return { query: result.query, budget: budgetTokens, tokens: used, items: packed };
 }
-async function enrichCuratedStashHit(query, hit, selectedRefs, eventSource) {
+function evidenceRef(item) {
+    return withIndexDb((db) => {
+        const id = getEntryIdByFilePath(db, item.path);
+        const ref = id === undefined ? undefined : getItemRefById(db, id);
+        if (!ref) {
+            if (item.path)
+                throw new UsageError(`Indexed asset no longer available: ${item.ref}`);
+            return item.ref;
+        }
+        const fragment = parseBundleRef(item.ref).fragment;
+        return fragment ? `${ref}#${fragment}` : ref;
+    });
+}
+async function enrichCuratedStashHit(query, hit, selectedRefs, eventSource, recall) {
     let shown;
     try {
-        shown = await akmShowUnified({ ref: hit.ref, eventSource, skipLogging: true });
+        shown = await akmShowUnified({ ref: recall ? evidenceRef(hit) : hit.ref, eventSource, skipLogging: true, recall });
     }
     catch {
+        if (recall)
+            return undefined;
         shown = undefined;
     }
+    const ref = shown?.selectedRef ?? shown?.ref ?? hit.ref;
     const description = shown?.description ?? hit.description;
     const preview = buildCuratedPreview(shown, hit);
-    const supportRefs = buildCurateSupportRefs(shown?.links, selectedRefs, hit.ref);
+    const supportRefs = await buildCurateSupportRefs(shown?.links, selectedRefs, ref, recall);
     const item = {
         source: "local",
         type: shown?.type ?? hit.type,
         name: shown?.name ?? hit.name,
-        ref: hit.ref,
+        ref,
         path: shown?.path ?? hit.path,
         editable: shown?.editable ?? hit.editable ?? false,
         ...((shown?.editable ?? hit.editable ?? false) === false
@@ -232,8 +277,9 @@ async function enrichCuratedStashHit(query, hit, selectedRefs, eventSource) {
         ...(shown?.parameters?.length ? { parameters: shown.parameters } : {}),
         ...(shown?.run ? { run: shown.run } : {}),
         ...(supportRefs.length > 0 ? { supportRefs } : {}),
-        followUp: `akm show ${hit.ref}`,
-        reason: buildCuratedReason(query, shown?.type ?? hit.type),
+        followUp: `akm show ${ref}`,
+        ...(shown?.beliefState ? { beliefState: shown.beliefState } : {}),
+        reason: `${matchBeliefFilter(shown?.beliefState, "historical") ? "Historical context. " : ""}${buildCuratedReason(query, shown?.type ?? hit.type)}`,
         ...(hit.score !== undefined ? { score: hit.score } : {}),
     };
     copySearchHitAttribution(hit, item, item.description);
@@ -333,7 +379,7 @@ function rerankDocumentTexts(hits) {
  * it, in the order `akm show` lists them. The LLM entity graph's `related`
  * list no longer feeds them.
  */
-function buildCurateSupportRefs(links, selectedRefs, ownerRef) {
+async function buildCurateSupportRefs(links, selectedRefs, ownerRef, recall) {
     const supportRefs = [];
     for (const [part, direction] of [
         ["outgoing", "from"],
@@ -343,11 +389,24 @@ function buildCurateSupportRefs(links, selectedRefs, ownerRef) {
             for (const ref of group.refs) {
                 if (ref === ownerRef || selectedRefs.has(ref) || supportRefs.some((existing) => existing.ref === ref))
                     continue;
+                let shown;
+                if (recall) {
+                    try {
+                        // A support ref is a link, not a hit: `--type` narrows the hits only.
+                        const { type: _type, ...linkRecall } = recall;
+                        shown = await akmShowUnified({ ref, recall: linkRecall, skipLogging: true });
+                    }
+                    catch {
+                        continue;
+                    }
+                }
+                const historical = matchBeliefFilter(shown?.beliefState, "historical");
                 const type = supportRefType(ref);
                 supportRefs.push({
                     ref,
                     ...(type ? { type } : {}),
-                    reason: `Declared link (${kind}) ${direction} this asset.`,
+                    ...(shown?.beliefState ? { beliefState: shown.beliefState } : {}),
+                    reason: `${historical ? "Historical context; " : ""}Declared link (${kind}) ${direction} this asset.`,
                 });
                 if (supportRefs.length >= MAX_CURATE_SUPPORT_REFS)
                     return supportRefs;