akm-cli 0.9.25-alpha.4 → 0.9.26-alpha.1

package/CHANGELOG.md

@@ -6,6 +6,49 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.26-alpha.1] - 2026-10-05
+
+### Changed
+
+- **Consolidate's pair judge lists what each note alone holds before it
+  classifies the pair, and akm never retires a note the judge listed anything
+  for.** The judge also reads 12,000 characters of each note instead of 2,500.
+  On 650 reviewed pairs from the owner's library, 64% of the old judge's
+  retirements lost nothing; with the lists, 92% do, and it picks the wrong
+  note to keep far less often.
+- **A confirmed duplicate retires unattended.** When the judge finds nothing
+  unique on either side, one more call asks only what the retired note holds
+  that the kept one lacks; an empty answer stages the proposal, and `triage`
+  `applyMode: "promote"` accepts it like a judged revision (it counts against
+  `maxAcceptsPerRun`, and a continuity risk keeps it for review). 109 of the
+  111 duplicates that passed in the reviewed pairs were safe to retire, and an
+  accepted retirement can be undone with `akm proposal revert`. Every other
+  retirement still waits for `akm proposal accept`.
+
+## [0.9.25] - 2026-10-04
+
+The stable release of the 0.9.25 line: 0.9.25-alpha.1 to alpha.4, unchanged. Their
+sections below list every change. When upgrading from 0.9.24:
+
+- **Reflect edits only an asset's `description`, `when_to_use` and title, and
+  keeps the body byte for byte;** it may answer "nothing to change" (alpha.3).
+  Its quality judge has a rubric for these revisions and tells one answering
+  negative feedback from maintenance (alpha.4). A proposal deferred as
+  `body-edit` by 0.9.24 stays deferred.
+- **Reflect refuses defective revisions before the judge runs** (placeholder
+  text, talk about its own edit, frontmatter copied into the body), with the
+  wording lists under `processes.reflect.defectFilter` (alpha.2).
+- **`akm improve judge`** runs reflect's quality judge on one revision, for
+  testing a judge engine (alpha.2).
+- **akm learns from Codex sessions:** `akm proposal extract --type codex`,
+  `--auto` and `akm improve` read `$CODEX_HOME/sessions` (alpha.3).
+- **Engines are interchangeable for model work:** one tool policy, one config
+  rule for which engines model work may use, a 600-second bound on every engine
+  kind, and `reasoningEffort` as the one effort word (alpha.1 and alpha.2).
+- **Removed:** the `--track-usage` / `--no-track-usage` flag on `akm search`,
+  `akm curate` and `akm show` (either spelling now fails as an unknown flag),
+  and opencode model work's step limit (alpha.2).
+
 ## [0.9.25-alpha.4] - 2026-10-04
 
 ### Changed

package/dist/assets/prompts/consolidate-pair-check.md

@@ -0,0 +1,5 @@
+You check whether deleting note X from one person's agent-memory library would lose anything. Note Y stays. List every durable claim of X that Y does not state.
+
+A durable claim is a fact, decision, value, command, flag, path, file name, URL, number, version, name, error message, condition or rule someone would act on. Ignore wording, headings, dates of writing, tags and boilerplate. A claim is stated when Y says it in any wording or format, or replaces it with a newer value. It is not stated when Y is vaguer (a config file instead of the specific path) or drops a number, command, step or condition. Read X's description as part of X. Write each item as a short phrase that quotes its identifier. Use [] when Y states everything.
+
+Answer ONLY with JSON: {"missing": ["..."]}

package/dist/assets/prompts/consolidate-pair.md

@@ -1,20 +1,19 @@
-You compare two assets from one person's agent-memory library (memories and knowledge notes an AI coding agent reads). Asset A is the OLDER one and asset B the NEWER one, by the dates shown.
+You compare two assets from one person's agent-memory library (memories and knowledge notes an AI coding agent reads). Asset A is the OLDER one and asset B the NEWER one, by the dates shown. akm deletes one of them only when the other keeps every claim a reader would need, so your two lists decide what is safe to delete.
 
-Classify the relation between them as exactly one of:
+First list what each asset has that the other lacks:
+- "onlyInA": every durable claim of A that B neither states nor updates.
+- "onlyInB": every durable claim of B that A neither states nor updates.
 
-- "duplicate": they state the same durable facts. Wording, title or formatting may differ, but neither adds a claim a reader would need that the other lacks.
-- "subsumed": one of them contains every durable claim of the other, plus more. The smaller one is redundant.
-- "supersedes": B updates, corrects, reverses or replaces a claim in A (a newer version, a changed decision, a fixed bug, a new value). A is now stale or wrong on that point.
+A durable claim is a fact, decision, value, command, flag, path, file name, URL, number, version, name, error message, condition or rule someone would act on. Ignore wording, headings, dates of writing, tags and boilerplate. A claim is stated when the other asset says it in any wording or format. It is not stated when the other asset is vaguer (a config file instead of the specific path) or drops a number, command, step or condition. Write each item as a short phrase that quotes its identifier. Use [] when there is nothing.
+
+Then classify the relation as exactly one of:
+- "duplicate": both lists are empty.
+- "subsumed": exactly one list is empty. The asset with the empty list is redundant.
+- "supersedes": B updates, corrects, reverses or replaces a claim in A (a newer version, a changed decision, a fixed bug, a new value), and onlyInA is empty.
 - "contradicts": they make logically exclusive claims about the same thing and nothing shows which one is current.
-- "overlap": same subject, but each has durable claims the other lacks. Keeping both loses nothing; merging them would keep both sets of claims.
+- "overlap": same subject, and both lists have items.
 - "unrelated": different subjects or different facts that happen to share words.
 
-Rules:
-- A durable claim is a fact, decision, value, command, path, number or rule someone would act on. Ignore dates, headings, tags and phrasing.
-- Prefer "overlap" over "duplicate" when either asset has a specific detail (a number, command, file, version or condition) that the other lacks.
-- "supersedes" needs a specific claim in A that B changes. Being newer or longer is not enough.
-- "contradicts" needs two claims that cannot both be true. Different scope, project or time is not a contradiction.
-
-Set "redundant" to "A" or "B" when that asset could be removed with no loss (only for "duplicate" or "subsumed"; for "duplicate" name the less complete or older one), else null. Set "stale" to "A" when the relation is "supersedes", else null.
+Set "redundant" to the asset that could be deleted with no loss: "A" for "duplicate", the asset with the empty list for "subsumed", "A" for "supersedes"; else null. Set "stale" to "A" when the relation is "supersedes", else null.
 
-Answer ONLY with JSON: {"relation": "...", "redundant": "A"|"B"|null, "stale": "A"|null, "confidence": 0.0-1.0, "reason": "<at most 25 words>"}
+Answer ONLY with JSON: {"onlyInA": ["..."], "onlyInB": ["..."], "relation": "...", "redundant": "A"|"B"|null, "stale": "A"|null, "confidence": 0.0-1.0, "reason": "<at most 25 words>"}

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

@@ -29,6 +29,7 @@
 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 { parseFrontmatter } from "../../../core/asset/frontmatter.js";
 import { conceptIdFromTypeName } from "../../../core/asset/resolve-ref.js";
 import { asNonEmptyString } from "../../../core/common.js";
@@ -42,8 +43,8 @@ import { runGit } from "../../../sources/providers/git-install.js";
 import { closeDatabase, openExistingDatabase, openReadonlyExistingDatabase, } from "../../../storage/repositories/index-connection.js";
 import { getAllEntries, getEntryById } from "../../../storage/repositories/index-entries-repository.js";
 import { getNeighborsByEntryId } from "../../../storage/repositories/index-vec-repository.js";
-import { isRetireProposal } from "../../proposal/proposal-types.js";
-import { createRetireProposal, listProposalsReadOnly } from "../../proposal/repository.js";
+import { isRetireProposal, PAIR_PASS_GATE, } from "../../proposal/proposal-types.js";
+import { createRetireProposal, listProposalsReadOnly, proposalContentHash, recordGateDecision, } from "../../proposal/repository.js";
 import { isHotCapturedMemory } from "../consolidate.js";
 import { contentHash, stripFrontmatterBody } from "../content-hash.js";
 import { loadLedgerSnapshot, PAIR_PASS_LEDGER_SOURCE, recordLedgerAttempt, stripBundle } from "../ledger.js";
@@ -67,8 +68,8 @@ 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 (plan §4.3: bodies were truncated at this length for calibration). */
-const PAIR_BODY_TRUNCATE_CHARS = 2500;
+/** 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"]);
@@ -76,11 +77,14 @@ const RETIRE_LABELS = new Set(["duplicate", "subsumed", "supersedes"]);
 function isRetireLabel(label) {
     return RETIRE_LABELS.has(label);
 }
-const PAIR_JUDGE_JSON_SCHEMA = {
+/** Exported, with {@link buildPairUserPrompt}, so a replay can drive the exact judge call. */
+export const PAIR_JUDGE_JSON_SCHEMA = {
     type: "object",
-    required: ["relation", "redundant", "stale", "confidence", "reason"],
+    required: ["onlyInA", "onlyInB", "relation", "redundant", "stale", "confidence", "reason"],
     additionalProperties: false,
     properties: {
+        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] },
@@ -88,6 +92,12 @@ const PAIR_JUDGE_JSON_SCHEMA = {
         reason: { type: "string", maxLength: 400 },
     },
 };
+const PAIR_CHECK_JSON_SCHEMA = {
+    type: "object",
+    required: ["missing"],
+    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. */
 export function parsePairJudgeResponse(raw) {
     const parsed = parseEmbeddedJsonResponse(raw);
@@ -103,7 +113,16 @@ export function parsePairJudgeResponse(raw) {
         return undefined;
     const confidence = Math.max(0, Math.min(1, parsed.confidence));
     const reason = typeof parsed.reason === "string" ? parsed.reason : "";
-    return { relation: parsed.relation, redundant, confidence, reason };
+    const onlyInA = claimList(parsed.onlyInA);
+    const onlyInB = claimList(parsed.onlyInB);
+    if (!onlyInA || !onlyInB)
+        return undefined;
+    return { onlyInA, onlyInB, relation: parsed.relation, redundant, confidence, reason };
+}
+function claimList(value) {
+    if (!Array.isArray(value) || !value.every((v) => typeof v === "string"))
+        return undefined;
+    return value.map((v) => v.trim()).filter(Boolean);
 }
 function isFlatName(name) {
     return !name.includes("/");
@@ -445,7 +464,7 @@ function orderByAge(x, y) {
     return xIsOlder ? { older: x, newer: y } : { older: y, newer: x };
 }
 /** The user message: dates decide "A (older)" / "B (newer)" (plan Appendix A), matching the calibration sample's own ordering. */
-function buildPairUserPrompt(older, newer) {
+export function buildPairUserPrompt(older, newer) {
     return [...sideSection("A (older)", older), ...sideSection("B (newer)", newer)].join("\n");
 }
 /** The tombstone-vocabulary reason a judge label maps to (`supersedes` -> `superseded`; the rest unchanged). */
@@ -456,19 +475,59 @@ 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).
+ * if that pointer is missing or invalid). A side is retired only when the
+ * judge listed nothing that it alone holds.
  */
-export function decideRetirement(label, redundant, older, newer) {
+export function decideRetirement(label, redundant, older, newer, only) {
+    let decision;
     if (label === "duplicate" || label === "supersedes")
-        return { retired: older, successor: newer };
-    if (label === "subsumed") {
-        if (redundant === "A")
-            return { retired: older, successor: newer };
-        if (redundant === "B")
-            return { retired: newer, successor: older };
-        return undefined; // the judge's pointer is missing or invalid — no proposal
-    }
-    return undefined;
+        decision = { retired: older, successor: newer };
+    else if (label === "subsumed" && redundant === "A")
+        decision = { retired: older, successor: newer };
+    else if (label === "subsumed" && redundant === "B")
+        decision = { retired: newer, successor: older };
+    if (!decision)
+        return undefined;
+    return (decision.retired === older ? only.onlyInA : only.onlyInB).length === 0 ? decision : undefined;
+}
+function checkSection(label, side) {
+    return [
+        `Note ${label}:`,
+        `Ref: ${side.asset.ref}`,
+        `Description: ${asNonEmptyString(side.frontmatter.description) ?? "(none)"}`,
+        "Content:",
+        "```",
+        stripFrontmatterBody(side.raw).slice(0, PAIR_BODY_TRUNCATE_CHARS),
+        "```",
+        "",
+    ].join("\n");
+}
+/**
+ * The second look a duplicate gets before it may retire unattended: one call
+ * that asks only what the retired note holds that the kept one lacks. True
+ * only on a clean, empty answer (it caught 2 of 4 duplicates the judge got
+ * wrong, and held back none of 109 right ones).
+ */
+async function confirmNothingLost(ctx, retired, successor) {
+    const outcome = await callStage({
+        feature: "memory_consolidation",
+        runner: ctx.llmRunner,
+        system: consolidatePairCheckPrompt,
+        prompt: `${checkSection("X (to delete)", retired)}\n${checkSection("Y (kept)", successor)}`,
+        gate: { config: ctx.config, enabled: true },
+        request: {
+            responseSchema: PAIR_CHECK_JSON_SCHEMA,
+            enableThinking: false,
+            ...(Object.hasOwn(ctx.llmRunner, "timeoutMs") ? { timeoutMs: ctx.llmRunner.timeoutMs } : {}),
+            signal: ctx.opts.signal,
+            ...(ctx.chat ? { chat: ctx.chat } : {}),
+        },
+        parse: (raw) => claimList(parseEmbeddedJsonResponse(raw)?.missing),
+        ...(ctx.opts.onNotices ? { onNotices: ctx.opts.onNotices } : {}),
+    });
+    if (!outcome.ok)
+        return false;
+    return claimList(parseEmbeddedJsonResponse(outcome.raw)?.missing)?.length === 0;
 }
 /**
  * One pair: judge it, then (for a retire class) apply the guards and mint
@@ -519,7 +578,7 @@ async function judgeOne(ctx, candidate) {
         return { failed: false }; // counted; stays human — no proposal, no belief write
     if (!isRetireLabel(verdict.relation))
         return { failed: false }; // overlap / unrelated: judged_no_action
-    const decision = decideRetirement(verdict.relation, verdict.redundant, older, newer);
+    const decision = decideRetirement(verdict.relation, verdict.redundant, older, newer, verdict);
     if (!decision)
         return { failed: false };
     const { retired, successor } = decision;
@@ -599,6 +658,21 @@ async function judgeOne(ctx, candidate) {
         }, ctx.opts.proposalsCtx);
         ctx.retired.push(proposal.id);
         ctx.perInitiatorProposed.add(candidate.initiator.ref);
+        // A duplicate with nothing unique on either side, confirmed by a second
+        // look, is the one class that retires unattended (109 of 111 safe on the
+        // owner's reviewed pairs, 2026-10-04): the triage drain accepts it under
+        // its usual applyMode. Every other retirement waits for a person.
+        if (verdict.relation === "duplicate" &&
+            verdict.onlyInA.length + verdict.onlyInB.length === 0 &&
+            !continuityRisk &&
+            (await confirmNothingLost(ctx, retired, successor))) {
+            recordGateDecision(ctx.stashDir, proposal.id, {
+                outcome: "staged",
+                reason: "duplicate",
+                gate: PAIR_PASS_GATE,
+                contentHash: proposalContentHash(proposal),
+            }, ctx.opts.proposalsCtx);
+        }
         return { failed: false };
     }
     catch (error) {

package/dist/commands/proposal/drain.js

@@ -30,7 +30,7 @@ import { buildExecution, resolveExecution } from "../../integrations/agent/execu
 import { assertRunnerCredentials, runExecution, } from "../../integrations/agent/runner-dispatch.js";
 import { errMessage, noticeSet } from "../improve/stage.js";
 import { akmProposalAccept, akmProposalReject } from "./proposal.js";
-import { isRetireProposal, STALE_TARGET_GATE_REASON } from "./proposal-types.js";
+import { isRetireProposal, PAIR_PASS_GATE, STALE_TARGET_GATE_REASON } from "./proposal-types.js";
 import { listProposals, listProposalsReadOnly, preflightProposalPromotion, proposalContent, proposalContentHash, readFreshProposalTarget, recordGateDecision, } from "./repository.js";
 /** The gate label on every decision the drain records. */
 const DRAIN_GATE = "triage";
@@ -313,13 +313,21 @@ export async function drainProposals(opts, promoteFn = akmProposalAccept, reject
     const accepts = [];
     const empties = [];
     for (const proposal of pending) {
-        // A consolidate pair-pass `retire` proposal is never auto-decided here,
-        // whatever `applyMode` says (alpha.9 brief §A "Review"; spec §25.6):
-        // untouched, still pending, waiting for a direct `akm proposal accept`.
-        // Checked before isEmptyDiff, which reads proposalContent() and has
-        // nothing meaningful to read on a delete-primary change anyway.
-        if (isRetireProposal(proposal))
+        // 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
+        // `akm proposal accept` (spec §25.6). Checked before isEmptyDiff, which
+        // has nothing meaningful to read on a delete-primary change.
+        if (isRetireProposal(proposal)) {
+            const staged = proposal.gateDecision;
+            if (staged?.outcome === "staged" &&
+                staged.gate === PAIR_PASS_GATE &&
+                staged.contentHash === proposalContentHash(proposal) &&
+                !proposal.retirement?.continuityRisk) {
+                accepts.push({ id: proposal.id, reason: "duplicate" });
+            }
             continue;
+        }
         const decision = proposal.gateDecision;
         // Another gate's rejection stands, and another gate's deferral is a
         // generating stage's hand-off to a person: it is left for that person.

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

@@ -53,6 +53,8 @@ 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. */
+export const PAIR_PASS_GATE = "consolidate-pair";
 export const EXPIRED_GATE_REASON = "expired";
 export const ASSET_MISSING_GATE_REASON = "asset-missing";
 const PROCEDURAL_GATE_REASONS = new Set([

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.25-alpha.4",
+  "version": "0.9.26-alpha.1",
   "type": "module",
   "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
   "keywords": [