akm-cli 0.9.26 → 0.9.27-alpha.2

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

@@ -26,7 +26,7 @@ const MAX_QUERIES = 5;
 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 = {
+export const GRADE_SCHEMA = {
     type: "object",
     required: ["grade", "reason"],
     additionalProperties: false,

package/dist/commands/improve/session-asset.js

@@ -14,9 +14,10 @@ import { assembleAsset } from "../../core/asset/asset-serialize.js";
 import { conceptIdFromTypeName } from "../../core/asset/resolve-ref.js";
 import { parseEmbeddedJsonResponse } from "../../core/parse.js";
 import { recordWrittenPath } from "../../core/write-provenance.js";
+// Every property is required, as a strict structured-output provider needs; an empty `tags` array is none.
 export const SESSION_SUMMARY_JSON_SCHEMA = {
     type: "object",
-    required: ["summary", "key_topics"],
+    required: ["summary", "key_topics", "tags"],
     additionalProperties: false,
     properties: {
         summary: { type: "string" },
@@ -61,7 +62,7 @@ export function buildSessionSummaryPrompt(data) {
         "Transcript:",
         renderTranscriptForSummary(data.events),
         "",
-        'Respond as JSON: {"summary": string, "key_topics": string[], "tags"?: string[]}.',
+        'Respond as JSON: {"summary": string, "key_topics": string[], "tags": string[]} (an empty array for no tags).',
     ].join("\n");
 }
 /** The summary JSON, tolerating prose around it; `undefined` when nothing usable parses. */

package/dist/commands/improve/stage.js

@@ -216,28 +216,31 @@ export function resolveQualityGateJudge(config, profile, processName, onNotices)
     onNotices?.(resolved.notices);
     return resolved.runner;
 }
-/** Lesson judge prompt; similar existing lessons let it mark near-duplicates down. */
-export function buildJudgePrompt(lessonContent, sourceContent, similarLessons) {
+/** Lesson judge prompt: what the writer was given (the source and its feedback), the assets nearest the new lesson, the lesson. */
+export function buildJudgePrompt(lessonContent, sourceContent, related, feedback) {
     const lines = [
-        "You are evaluating a proposed lesson asset for an akm knowledge base.",
+        "You are evaluating a lesson an agent wrote from a memory and the feedback about it, for an akm knowledge base.",
         "",
         "Score this lesson on each criterion from 1 (poor) to 5 (excellent):",
-        "1. NOVELTY: Does the lesson add information not already present in the source asset?",
-        "2. NON-REDUNDANCY: Is this lesson meaningfully different from what the source already says?",
-        "3. GROUNDING: Is the lesson about what the source asset is about? Score 1-2 only if it is about a different subject than the source; 3 if it is on the source's subject but goes beyond or corrects what the source says (it may draw on feedback you are not shown); 4-5 if the source supports it. A lesson may generalize the source's point.",
+        "1. REUSABLE: Does the lesson state a rule an agent can use on another occasion, with the reason it holds? Score 1-2 when it only records what was done, shipped, decided, found or is pending, on a date or for one build, machine or project, or how a system is set up now, however it is phrased. Score 4-5 for a rule with its reason.",
+        "2. NON-REDUNDANCY: Is the lesson new next to the existing assets shown below? Score 1-2 only when one of them already states the same rule. Assets on other subjects change nothing: score 4-5 when none is shown or none is on the same subject.",
+        "3. GROUNDING: Is every statement in the lesson stated by the source or its feedback, in any words? Check each cause, step, number, rule and limit in the lesson against them. Score 4-5 when each is stated. Score 3 when one stretches what the source says. Score 1-2 when any is in neither, when the lesson drops a limit the source states (one place checked, not confirmed, a guess) and says more than it, or when it is about another subject than the source.",
         "",
-        "Source asset content:",
+        "Source memory:",
         "```",
         // The window distill generates from (buildDistillPrompt): grounding can reject, so the judge reads all of it.
         sourceContent.slice(0, 3000),
         "```",
     ];
-    if (similarLessons && similarLessons.length > 0) {
-        lines.push("", "Existing similar lessons (top-3 by similarity). Rate NOVELTY and NON-REDUNDANCY lower if the proposed lesson is substantially similar to any of these:");
-        for (const sl of similarLessons)
-            lines.push(`\nExisting lesson ref: ${sl.ref}`, "```", sl.content.slice(0, 500), "```");
+    if (feedback && feedback.length > 0) {
+        lines.push("", "Feedback recorded about the memory (the writer saw it too):", "```", feedback.join("\n").slice(0, 1500), "```");
+    }
+    if (related && related.length > 0) {
+        lines.push("", "Existing assets nearest the new lesson (they may be on another subject):");
+        for (const asset of related)
+            lines.push(`\nExisting asset ref: ${asset.ref}`, "```", asset.content.slice(0, 600), "```");
     }
-    lines.push("", "Proposed lesson content:", "```", lessonContent.slice(0, 1000), "```", "", 'Return ONLY valid JSON, no prose: {"scores": {"novelty": <1-5 integer>, "nonRedundancy": <1-5 integer>, "grounding": <1-5 integer>}, "reason": "<one sentence>"}');
+    lines.push("", "Proposed lesson:", "```", lessonContent.slice(0, 2000), "```", "", 'Return ONLY valid JSON, no prose: {"scores": {"reusable": <1-5 integer>, "nonRedundancy": <1-5 integer>, "grounding": <1-5 integer>}, "reason": "<one sentence naming the weakest criterion>"}');
     return lines.join("\n");
 }
 function boundedDocument(content, maxChars = 6000) {
@@ -317,23 +320,19 @@ export function buildReflectJudgePrompt(candidateContent, sourceContent, feedbac
 }
 /**
  * `grounding` is scored with the other lesson criteria but left out of their
- * mean: a lesson about a different subject than its source reads as novel and
- * non-redundant, so they would pass it (or, in the review band, mint it as
- * a pending proposal). The rubric reserves 1-2 for a different subject. A score
- * of {@link UNGROUNDED_MAX_SCORE} or less is a rejection whatever the mean says
- * (#999). A higher score up to {@link BORDERLINE_GROUNDING_MAX_SCORE} is only
- * borderline: a lesson on its source's subject that advises beyond it has scored
- * 2, and a score can move a point between runs (see `runQualityJudge`), so it
- * goes to a person unless the mean alone already rejects it. A lesson that goes
- * beyond or corrects its source is on its subject: distill folds feedback into
- * the lesson, and the judge is never shown it. A contradiction of the source is
- * the optional fidelity check's to send to a human (`judgeAndQueue` in
- * distill.ts), so the rubric must not pre-empt it.
+ * mean. A lesson criterion scored {@link LESSON_REJECT_MAX_SCORE} or less is a
+ * rejection whatever the mean says: the mean would hide it (4 and 1 average
+ * 2.5, a review), and a reviewer was reading every lesson that was not rejected,
+ * 17 of 19 of them bad on 2026-10-05. The rubric reserves 1-2 for a lesson that
+ * records what was done instead of a rule, repeats an asset the library holds,
+ * or states what neither its source nor its feedback does. The judge is shown
+ * the feedback the writer saw, so a statement it supports is not an invention. A
+ * contradiction of the source is the optional fidelity check's to send to a
+ * human (`judgeAndQueue` in distill.ts).
  */
 const GROUNDING_CRITERION = "grounding";
-const UNGROUNDED_MAX_SCORE = 1;
-const BORDERLINE_GROUNDING_MAX_SCORE = 2;
-const LESSON_JUDGE_CRITERIA = ["novelty", "nonRedundancy", GROUNDING_CRITERION];
+const LESSON_REJECT_MAX_SCORE = 2;
+const LESSON_JUDGE_CRITERIA = ["reusable", "nonRedundancy", GROUNDING_CRITERION];
 const REFLECT_JUDGE_CRITERIA = ["need", "preservation", "quality"];
 /**
  * Read a judge response: the per-criterion shape (averaged here, `grounding`
@@ -370,7 +369,7 @@ function parseJudgeResponse(raw, keys) {
     }
     return inRange(parsed.score) ? { score: parsed.score, lowest: parsed.score, reason } : undefined;
 }
-function judgeResponseSchema(keys) {
+export function judgeResponseSchema(keys) {
     return {
         type: "object",
         required: ["scores", "reason"],
@@ -390,9 +389,8 @@ function judgeResponseSchema(keys) {
  * The quality judge. Fails closed: no runner, an unparseable verdict or a
  * provider failure never passes content. Bands: every criterion in the mean
  * >= 4 passes, otherwise a mean >= 2.5 is review and a lower one reject; a
- * `grounding` score of {@link UNGROUNDED_MAX_SCORE} or less rejects whatever
- * the mean is, and one of {@link BORDERLINE_GROUNDING_MAX_SCORE} routes a lesson
- * that would pass to review (a mean that rejects stays a rejection).
+ * lesson criterion (`grounding` included) of {@link LESSON_REJECT_MAX_SCORE}
+ * or less rejects whatever the mean is.
  * Temperature is set to 0, which reduces run-to-run variation but does not
  * remove it: on some servers (llama.cpp batching, for one) the same request can
  * score a point apart, so the routing rules are chosen with that margin in mind.
@@ -430,34 +428,18 @@ async function runQualityJudge(feature, config, prompt, keys, chat, options) {
     if (!parsed)
         return { pass: false, score: -1, reason: "judge parse failed — routed to review", reviewNeeded: true };
     const { score, lowest, reason, criteria } = parsed;
-    const grounding = criteria?.[GROUNDING_CRITERION];
-    if (criteria && grounding !== undefined && grounding <= UNGROUNDED_MAX_SCORE) {
-        return {
-            pass: false,
-            score,
-            reason: `Off-subject for its source (grounding ${grounding}/5): ${reason}`,
-            criteria,
-        };
+    // A lesson criterion at 2 or below is a defect the mean would hide (4 and 1 average 2.5, a review): it rejects.
+    if (criteria && criteria[GROUNDING_CRITERION] !== undefined) {
+        const [weakest, low] = Object.entries(criteria).sort((x, y) => x[1] - y[1])[0];
+        if (low <= LESSON_REJECT_MAX_SCORE)
+            return { pass: false, score, reason: `${weakest} ${low}/5: ${reason}`, criteria };
     }
     const verdict = lowest >= 4 ? { pass: true } : score >= 2.5 ? { pass: false, reviewNeeded: true } : { pass: false };
-    // Borderline grounding is a person's call even when the lesson would pass; a mean that rejects stays rejected.
-    if (criteria &&
-        grounding !== undefined &&
-        grounding <= BORDERLINE_GROUNDING_MAX_SCORE &&
-        (verdict.pass || verdict.reviewNeeded)) {
-        return {
-            pass: false,
-            reviewNeeded: true,
-            score,
-            reason: `Borderline on grounding (${grounding}/5), routed to review: ${reason}`,
-            criteria,
-        };
-    }
     return { ...verdict, score, reason, ...(criteria ? { criteria } : {}) };
 }
 /** Judge a proposed lesson (or knowledge promotion) against its source. */
 export function runLessonQualityJudge(config, lessonContent, sourceContent, chat, options = {}) {
-    const prompt = buildJudgePrompt(lessonContent, sourceContent, options.similarLessons);
+    const prompt = buildJudgePrompt(lessonContent, sourceContent, options.related, options.feedback);
     return runQualityJudge("lesson_quality_gate", config, prompt, LESSON_JUDGE_CRITERIA, chat, options);
 }
 /** Judge an in-place reflect revision without new-lesson novelty criteria. */

package/dist/commands/proposal/drain.js

@@ -28,6 +28,7 @@ import { info, warn } from "../../core/warn.js";
 import { DEFAULT_LLM_TIMEOUT_MS } from "../../integrations/agent/config.js";
 import { buildExecution, resolveExecution } from "../../integrations/agent/execution.js";
 import { assertRunnerCredentials, runExecution, } from "../../integrations/agent/runner-dispatch.js";
+import { nearestKnowledgeNotes } from "../improve/consolidate/coverage.js";
 import { errMessage, noticeSet } from "../improve/stage.js";
 import { akmProposalAccept, akmProposalReject } from "./proposal.js";
 import { isRetireProposal, PAIR_PASS_GATE, STALE_TARGET_GATE_REASON } from "./proposal-types.js";
@@ -57,8 +58,13 @@ function categorizeDrainFailure(message, fallback) {
  * rejection, so instead of failing identically every run it is auto-rejected
  * once; the ledger records `failed`, keeping the ref re-proposable.
  */
-async function acceptProposal(opts, proposal, id, reason, promoteFn, rejectFn) {
-    const gateDecision = { outcome: "auto-accepted", reason, gate: DRAIN_GATE };
+async function acceptProposal(opts, proposal, id, reason, promoteFn, rejectFn, judgeReason) {
+    const gateDecision = {
+        outcome: "auto-accepted",
+        reason,
+        gate: DRAIN_GATE,
+        ...(judgeReason ? { judgeReason } : {}),
+    };
     try {
         if (!opts.dryRun) {
             await promoteFn({
@@ -102,7 +108,7 @@ async function acceptProposal(opts, proposal, id, reason, promoteFn, rejectFn) {
     }
 }
 /** Reject one proposal (nothing in a dry run); the error message on failure. */
-async function rejectProposal(opts, id, reason, gateReason, rejectFn) {
+async function rejectProposal(opts, id, reason, gateReason, rejectFn, judgeReason) {
     if (opts.dryRun)
         return undefined;
     try {
@@ -110,7 +116,12 @@ async function rejectProposal(opts, id, reason, gateReason, rejectFn) {
             stashDir: opts.stashDir,
             id,
             reason,
-            gateDecision: { outcome: "auto-rejected", reason: gateReason, gate: DRAIN_GATE },
+            gateDecision: {
+                outcome: "auto-rejected",
+                reason: gateReason,
+                gate: DRAIN_GATE,
+                ...(judgeReason ? { judgeReason } : {}),
+            },
         });
         return undefined;
     }
@@ -118,7 +129,20 @@ async function rejectProposal(opts, id, reason, gateReason, rejectFn) {
         return errMessage(err);
     }
 }
-/** The judgment prompt: the proposal, the live asset it would overwrite, and same-ref siblings. */
+/**
+ * `text` as a fenced block whose fence is longer than any backtick run inside
+ * it (the CommonMark rule), so a note holding its own code block is not cut
+ * short at the first inner fence.
+ */
+export function fencedBlock(text) {
+    let longest = 2;
+    for (const run of text.match(/`+/g) ?? [])
+        if (run.length > longest)
+            longest = run.length;
+    const fence = "`".repeat(longest + 1);
+    return [fence, text, fence];
+}
+/** The judgment prompt: the proposal, the live asset it would overwrite, same-ref siblings, and for a promotion the nearest knowledge notes. */
 export function buildJudgmentPrompt(proposal, reason, ctx) {
     const sections = [
         "You are adjudicating a pending knowledge-base proposal no quality judge has",
@@ -129,12 +153,10 @@ export function buildJudgmentPrompt(proposal, reason, ctx) {
         `Left for judgment because: ${reason === "needs-judgment" ? "no quality judge has passed this content yet" : reason}`,
         "",
         "## Proposed content",
-        "```",
-        proposalContent(proposal),
-        "```",
+        ...fencedBlock(proposalContent(proposal)),
     ];
     if (ctx.liveAsset !== undefined) {
-        sections.push("", "## Current live asset (would be overwritten on accept)", "```", ctx.liveAsset, "```");
+        sections.push("", "## Current live asset (would be overwritten on accept)", ...fencedBlock(ctx.liveAsset));
     }
     else {
         sections.push("", "## Current live asset", "(none — this proposal would create a new asset)");
@@ -142,8 +164,15 @@ export function buildJudgmentPrompt(proposal, reason, ctx) {
     if (ctx.siblings.length > 0) {
         sections.push("", "## Other pending proposals for the same ref (dedup context)");
         for (const sib of ctx.siblings) {
-            sections.push("", `### Sibling ${sib.id} (source: ${sib.source})`, "```", proposalContent(sib), "```");
+            sections.push("", `### Sibling ${sib.id} (source: ${sib.source})`, ...fencedBlock(proposalContent(sib)));
+        }
+    }
+    if (ctx.neighbours && ctx.neighbours.length > 0) {
+        sections.push("", "## Existing knowledge notes nearest to this promotion's source memory");
+        for (const note of ctx.neighbours) {
+            sections.push("", `### ${note.ref}`, note.description, ...fencedBlock(note.excerpt));
         }
+        sections.push("", "Reject the promotion if these notes already cover what it says, even in other words.");
     }
     sections.push("", "## Your task", 'Return ONLY a JSON object: {"decision": "accept" | "reject" | "defer", "reason": "<short reason>"}.', "- accept: the proposed content is a correct, valuable update worth committing.", "- reject: the proposal is wrong, a duplicate, or contradicts the live asset.", "- defer: you cannot decide from the provided context (leave it pending).", "Output the JSON object and nothing else.");
     return sections.join("\n");
@@ -205,7 +234,7 @@ async function dispatchJudgment(runner, prompt, seams) {
  * (under `applyMode` and the remaining accept budget) or the reject. A defer, an
  * unparseable verdict or a runner error leaves the item undecided.
  */
-async function runJudgmentTier(opts, result, pending, acceptBudget, promoteFn, rejectFn, seams) {
+async function runJudgmentTier(opts, result, pending, acceptBudget, promoteFn, rejectFn, seams, deferNotes) {
     const byId = new Map(pending.map((p) => [p.id, p]));
     const notices = noticeSet();
     const stillDeferred = [];
@@ -216,21 +245,33 @@ async function runJudgmentTier(opts, result, pending, acceptBudget, promoteFn, r
             stillDeferred.push(item);
             continue;
         }
+        const liveAsset = readLiveAssetContent(opts.stashDir, proposal.ref);
         const prompt = buildJudgmentPrompt(proposal, item.reason, {
-            liveAsset: readLiveAssetContent(opts.stashDir, proposal.ref),
+            liveAsset,
             siblings: pending.filter((p) => p.ref === proposal.ref && p.id !== proposal.id),
+            // A create the model otherwise judges blind: the model never sees knowledge/.
+            ...(liveAsset === undefined ? { neighbours: promotionNeighbours(opts.stashDir, proposal) } : {}),
         });
         const dispatch = await dispatchJudgment(opts.judgment, prompt, seams);
         notices.add(dispatch.notices);
         if (dispatch.error)
             warn(`[triage] judgment dispatch failed for ${item.id}: ${dispatch.error}`);
         const verdict = dispatch.error ? null : dispatch.verdict;
-        if (!verdict || verdict.decision === "defer") {
+        if (!verdict) {
+            deferNotes.set(item.id, { reason: dispatch.error ? "judgment-error" : "judgment-parse-failure" });
+            stillDeferred.push(item);
+            continue;
+        }
+        if (verdict.decision === "defer") {
+            deferNotes.set(item.id, {
+                reason: "judgment-deferred",
+                ...(verdict.reason ? { judgeReason: verdict.reason } : {}),
+            });
             stillDeferred.push(item);
             continue;
         }
         if (verdict.decision === "reject") {
-            const failure = await rejectProposal(opts, item.id, verdict.reason || "judgment: reject", "judgment-reject", rejectFn);
+            const failure = await rejectProposal(opts, item.id, verdict.reason || "judgment: reject", "judgment-reject", rejectFn, verdict.reason);
             if (failure === undefined) {
                 result.rejected.push(item.id);
             }
@@ -252,6 +293,7 @@ async function runJudgmentTier(opts, result, pending, acceptBudget, promoteFn, r
                     reason: "judgment-accept",
                     contentHash: proposalContentHash(proposal),
                     gate: DRAIN_GATE,
+                    ...(verdict.reason ? { judgeReason: verdict.reason } : {}),
                 });
                 result.staged.push(item.id);
             }
@@ -265,7 +307,7 @@ async function runJudgmentTier(opts, result, pending, acceptBudget, promoteFn, r
             result.skippedByCap.push(item.id);
             continue;
         }
-        const outcome = await acceptProposal(opts, proposal, item.id, "judgment-accept", promoteFn, rejectFn);
+        const outcome = await acceptProposal(opts, proposal, item.id, "judgment-accept", promoteFn, rejectFn, verdict.reason);
         if (outcome === "promoted") {
             result.promoted.push(item.id);
             acceptBudget -= 1;
@@ -286,6 +328,21 @@ async function runJudgmentTier(opts, result, pending, acceptBudget, promoteFn, r
         result.notices = notices.list();
     result.deferred = stillDeferred;
 }
+/** The knowledge notes nearest to a consolidate promotion's source memory; none for any other proposal. */
+function promotionNeighbours(stashDir, proposal) {
+    if (proposal.source !== "consolidate" || proposal.promotionSource === undefined)
+        return [];
+    try {
+        const parsed = parseRefInput(proposal.promotionSource);
+        const typeDir = stashDirFor(parsed.type);
+        if (!typeDir)
+            return [];
+        return nearestKnowledgeNotes(assetPathForName(parsed.type, path.join(stashDir, typeDir), parsed.name));
+    }
+    catch {
+        return [];
+    }
+}
 /** The live asset a proposal would overwrite, if any. */
 function readLiveAssetContent(stashDir, ref) {
     try {
@@ -314,8 +371,8 @@ export async function drainProposals(opts, promoteFn = akmProposalAccept, reject
     const empties = [];
     for (const proposal of pending) {
         // A consolidate pair-pass `retire` proposal is auto-accepted only when the
-        // pair judge staged it as a duplicate with nothing unique on either side
-        // (spec §25.9, equivalent content); every other one waits for a direct
+        // pair pass staged it: nothing unique on either side, confirmed by a
+        // second look, no continuity risk; every other one waits for a direct
         // `akm proposal accept` (spec §25.6). Checked before isEmptyDiff, which
         // has nothing meaningful to read on a delete-primary change.
         if (isRetireProposal(proposal)) {
@@ -324,7 +381,7 @@ export async function drainProposals(opts, promoteFn = akmProposalAccept, reject
                 staged.gate === PAIR_PASS_GATE &&
                 staged.contentHash === proposalContentHash(proposal) &&
                 !proposal.retirement?.continuityRisk) {
-                accepts.push({ id: proposal.id, reason: "duplicate" });
+                accepts.push({ id: proposal.id, reason: staged.reason });
             }
             continue;
         }
@@ -394,15 +451,22 @@ export async function drainProposals(opts, promoteFn = akmProposalAccept, reject
             }
         }
     }
+    const deferNotes = new Map();
     if (opts.judgment && result.deferred.length > 0) {
-        await runJudgmentTier({ ...opts, judgment: opts.judgment }, result, pending, cap - promotedHere, promoteFn, rejectFn, judgmentSeams);
+        await runJudgmentTier({ ...opts, judgment: opts.judgment }, result, pending, cap - promotedHere, promoteFn, rejectFn, judgmentSeams, deferNotes);
     }
     // #577: whatever stays undecided is left for review (`review_needed` in the ledger).
     if (!opts.dryRun) {
-        const reviewReason = opts.judgment ? "judgment-deferred" : "no-judge-configured";
         for (const item of result.deferred) {
+            const note = deferNotes.get(item.id);
+            const reviewReason = note?.reason ?? (opts.judgment ? "judgment-deferred" : "no-judge-configured");
             try {
-                recordGateDecision(opts.stashDir, item.id, { outcome: "deferred", reason: reviewReason, gate: DRAIN_GATE });
+                recordGateDecision(opts.stashDir, item.id, {
+                    outcome: "deferred",
+                    reason: reviewReason,
+                    gate: DRAIN_GATE,
+                    ...(note?.judgeReason ? { judgeReason: note.judgeReason } : {}),
+                });
             }
             catch (err) {
                 warn(`[triage] failed to record gate decision for ${item.id}: ${errMessage(err)}`);

package/dist/commands/proposal/proposal-types.js

@@ -53,7 +53,7 @@ export function isRetireProposal(proposal) {
 }
 /** A promote refused because the target changed after mint (STALE, R20) — not a merit judgement. */
 export const STALE_TARGET_GATE_REASON = "stale-target";
-/** The gate on a retire proposal the triage drain may accept unattended: a pair-judged duplicate. */
+/** The gate on a retire proposal the triage drain may accept unattended: a staged pair-judged retirement. */
 export const PAIR_PASS_GATE = "consolidate-pair";
 export const EXPIRED_GATE_REASON = "expired";
 export const ASSET_MISSING_GATE_REASON = "asset-missing";

package/dist/core/config/schema/improve-processes.js

@@ -78,9 +78,9 @@ const qualityGateField = z
     .optional();
 /**
  * WS-3b: CLS (Complementary Learning System) interleaving (step 9).
- * distill/memoryInference prompts include embedding-retrieved existing adjacent
- * lessons/knowledge to prevent catastrophic interference with prior generalizations.
- * Default OFF. Only meaningful on `distill` and `memoryInference` processes.
+ * The distill prompt includes the lessons, knowledge notes and skills the library already holds near the
+ * memory, so the writer answers NONE for a rule one of them states and does not overwrite a prior
+ * generalization. Default ON; `enabled: false` turns it off. Only meaningful on the `distill` process.
  */
 const clsField = z
     .object({

package/dist/core/paths.js

@@ -332,15 +332,6 @@ export function getStashStateKey(stashDir) {
 function stashScopedDir(base, stashDir) {
     return path.join(base, getStashStateKey(stashDir));
 }
-/**
- * `$STATE/improve/measurement/verdicts/<stash>/` — `akm-eval-proactive-verdict`
- * reports. Moved out of `$STASH/.akm/measurement/verdicts/` (itlackey/akm#890);
- * the pilot treatment file at `$STASH/.akm/measurement/` is manually-authored
- * measurement input and stays put.
- */
-export function getMeasurementVerdictsDir(stashDir) {
-    return stashScopedDir(path.join(getStateDir(), "improve", "measurement", "verdicts"), stashDir);
-}
 /**
  * `$CACHE/index/unresolved-sources/<stash>/` — synthetic placeholder path for
  * a configured source whose content root did not resolve this run. Never

package/dist/indexer/indexer.js

@@ -5,7 +5,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { detectAdapterId } from "../core/adapter/detect-adapter.js";
 import { adapterForId } from "../core/adapter/registry.js";
-import { isHttpUrl } from "../core/common.js";
+import { compareCodePoints, isHttpUrl } from "../core/common.js";
 import { classifyPathAccess, describeInaccessiblePath } from "../core/path-access.js";
 import { getDbPath } from "../core/paths.js";
 import { SCRIPT_EXTENSIONS } from "../core/recognition-util.js";
@@ -14,6 +14,7 @@ import { isVerbose, warn, warnOnce, warnVerbose } from "../core/warn.js";
 import { resolveSourcesForOrigin } from "../registry/origin-resolve.js";
 import { closeDatabase, openExistingDatabase, openIndexDatabase, openReadonlyExistingDatabase, } from "../storage/repositories/index-connection.js";
 import { deleteEntriesByBundle, deleteEntriesByDirAndBundle, deleteEntriesByDirExceptRefs, deleteEntriesByIds, deleteUsageEventsByEntryIds, findEntryIdByRef, getAllEntries, getEmbeddableEntryCount, getEntryCount, getIndexedBundleIdsByDir, getIndexedDirPathsByBundleId, relinkUsageEvents, upsertEntry, } from "../storage/repositories/index-entries-repository.js";
+import { rebuildFtsIfTotalsStale } from "../storage/repositories/index-fts-repository.js";
 import { clearStaleCacheEntries } from "../storage/repositories/index-llm-cache-repository.js";
 import { deleteIndexDirState, deleteMeta, getIndexDirState, getMeta, setMeta, upsertIndexDirState, } from "../storage/repositories/index-meta-repository.js";
 import { VACUUM_PENDING_META } from "../storage/repositories/index-schema.js";
@@ -125,7 +126,14 @@ export async function runEmbeddingPass(params) {
  */
 function finalizeIndex(args) {
     const { db, sources, sourceDirs, stashDir, signal, onProgress } = args;
-    onProgress({ phase: "fts", message: "Full-text search index is current." });
+    // Rows replaced or removed since its BM25 totals were taken leave them off; recompute them (#1048).
+    const rebuilt = rebuildFtsIfTotalsStale(db);
+    onProgress({
+        phase: "fts",
+        message: rebuilt
+            ? "Rebuilt the full-text search index to recompute its totals."
+            : "Full-text search index is current.",
+    });
     const tFtsEnd = Date.now();
     // Re-link state.db usage events to the regenerated index and recompute the
     // derived utility cache. Stored refs already use the current item-ref grammar,
@@ -907,11 +915,6 @@ function requiresWorkflowSourcePreflight(ctxs) {
 }
 /** Phase 2 (sync): write all pre-generated scan records inside a single transaction. */
 function persistDirRecords(db, dirRecords, warnings, bundleByRoot) {
-    // Per-source dedup: the same logical asset can appear more than once within
-    // one owning source, where source order still makes the first occurrence win.
-    // The owner is part of the key so identical concepts in different bundles
-    // remain distinct indexed rows.
-    const indexedAssetIdentities = new Set();
     const deletedUsageEntryIds = new Set();
     const findPersisted = db.prepare("SELECT id, content_hash, file_path, adapter_id FROM entries WHERE item_ref = ?");
     const insertTransaction = db.transaction(() => {
@@ -961,7 +964,7 @@ function persistDirRecords(db, dirRecords, warnings, bundleByRoot) {
             let persistedRows = 0;
             let dedupedRows = 0;
             if (stash) {
-                const ownerIdentity = bundle.bundleId;
+                const sourceRoot = `${path.resolve(currentStashDir)}${path.sep}`;
                 for (const entry of stash.entries) {
                     const entryPath = entry.filename ? path.join(dirPath, entry.filename) : null;
                     if (!entryPath) {
@@ -973,23 +976,36 @@ function persistDirRecords(db, dirRecords, warnings, bundleByRoot) {
                         warn(`Skipping entry without adapter-owned concept identity: ${entryPath}`);
                         continue;
                     }
-                    // Adapter-owned concept identity is path-based and cannot be replaced
-                    // by presentation fields such as type/title.
-                    const identityKey = `${ownerIdentity}\0${adapterConceptId}`;
-                    if (indexedAssetIdentities.has(identityKey)) {
-                        dedupedRows++;
-                        continue;
-                    }
-                    indexedAssetIdentities.add(identityKey);
                     // content_hash = doc.hash from the drain, keyed by the recognized
                     // file's path. A missing hash preserves the existing value on upsert.
                     const contentHash = hashByFile?.get(entryPath);
+                    // Adapter-owned concept identity is path-based and cannot be replaced
+                    // by presentation fields such as type/title.
                     const provenance = deriveEntryProvenance(bundle, entry.type, entry.name, adapterConceptId);
+                    // Two files of one source can claim one ref (a skill's references/a.md and
+                    // knowledge/skills/x/references/a.md are both knowledge/skills/x/references/a). The file with
+                    // the smaller path holds it, whichever directories this run drains and in whatever order the
+                    // walk met them (#1050): an entry yields to a row held by a file with a smaller path and
+                    // otherwise takes the ref over. The same concept in another bundle is a different row, and a
+                    // holder whose file is gone is no claim.
+                    const holder = findPersisted.get(provenance.itemRef) ?? undefined;
+                    if (holder &&
+                        holder.file_path !== entryPath &&
+                        holder.file_path.startsWith(sourceRoot) &&
+                        fs.existsSync(holder.file_path)) {
+                        const yields = compareCodePoints(holder.file_path, entryPath) < 0;
+                        const [indexed, skipped] = yields ? [holder.file_path, entryPath] : [entryPath, holder.file_path];
+                        warnings.push(`Two files claim ${provenance.itemRef}: indexed ${indexed}, skipped ${skipped}.`);
+                        if (yields) {
+                            dedupedRows++;
+                            continue;
+                        }
+                        // The directory the ref comes from now has a row fewer than its files: drain it again.
+                        deleteIndexDirState(db, path.dirname(holder.file_path));
+                    }
                     keptItemRefs.add(provenance.itemRef);
                     persistedRows++;
-                    const previous = sameVariant
-                        ? (findPersisted.get(provenance.itemRef) ?? undefined)
-                        : undefined;
+                    const previous = sameVariant ? holder : undefined;
                     const unchanged = previous !== undefined &&
                         contentHash !== undefined &&
                         previous.content_hash === contentHash &&

package/dist/integrations/harnesses/codex/agent-builder.js

@@ -19,12 +19,13 @@
  *     `./result-extractor.ts`. Always emitted, mirroring how the Claude builder
  *     always emits `--print`: dispatch is the captured, non-interactive path.
  *   - Codex is the NATIVE-SCHEMA tier (plan §"Structured-output
- *     normalization"): `req.schema` is written to a temp file and passed via
- *     `--output-schema <file>`. The file is tiny, uniquely named under the OS
- *     temp dir, and intentionally NOT cleaned up here — `BuiltCommand` has no
- *     post-run hook, and the spawned process reads the file after `build()`
- *     returns. OS temp reaping owns the lifecycle. The engine still validates
- *     the output defensively (the constrained output is trusted but verified).
+ *     normalization"): `req.schema` is written to a file and passed via
+ *     `--output-schema <file>`. The file is named by the hash of the schema
+ *     and lives in akm's cache dir, so a schema is written once however many
+ *     units dispatch with it: `BuiltCommand` has no post-run hook, and the
+ *     spawned process reads the file after `build()` returns, so a file per
+ *     dispatch could only leak (#1051). The engine still validates the output
+ *     defensively (the constrained output is trusted but verified).
  *   - `codex exec` has no system-prompt flag; `req.systemPrompt` is folded
  *     into the prompt payload (system text first, blank line, then the task),
  *     after the `--` end-of-options separator so it can never be parsed as a
@@ -52,22 +53,29 @@
  * that registry, so this builder is reachable under the `"codex"` platform
  * name without any further wiring.
  */
-import { mkdtempSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { mkdirSync } from "node:fs";
 import { join } from "node:path";
+import { writeFileAtomic } from "../../../core/common.js";
+import { getCacheDir } from "../../../core/paths.js";
+import { sha256Hex } from "../../../runtime.js";
 import { resolveDispatchModel } from "../../agent/builder-shared.js";
 import { createAgentRequestLowerer } from "../../agent/request-lowering.js";
 /**
- * Write a node's JSON Schema to a fresh temp file for `--output-schema`.
+ * Write a node's JSON Schema to a file for `--output-schema`, named by the hash
+ * of its text, in akm's cache dir. Returns the absolute file path (the value
+ * handed to the flag).
  *
- * A unique `mkdtemp` directory per build avoids collisions between concurrent
- * fan-out units dispatching in the same process. Returns the absolute file
- * path (the value handed to the flag).
+ * The same schema is the same file, so concurrent fan-out units share it, and
+ * the atomic rename makes a write of identical bytes safe under a reader: no
+ * unit can see a half-written schema, and none removes it from another. Nothing
+ * is cleaned up, because nothing accumulates but one file per distinct schema.
  */
 export function writeCodexOutputSchemaFile(schema) {
-    const dir = mkdtempSync(join(tmpdir(), "akm-codex-schema-"));
-    const file = join(dir, "output-schema.json");
-    writeFileSync(file, `${JSON.stringify(schema, null, 2)}\n`, "utf8");
+    const text = `${JSON.stringify(schema, null, 2)}\n`;
+    const dir = join(getCacheDir(), "codex-output-schemas");
+    mkdirSync(dir, { recursive: true });
+    const file = join(dir, `${sha256Hex(text)}.json`);
+    writeFileAtomic(file, text);
     return file;
 }
 /**