akm-cli 0.9.27 → 0.9.28-alpha.1

package/CHANGELOG.md

@@ -6,6 +6,28 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.28-alpha.1] - 2026-10-08
+
+### Fixed
+
+- **Distill skips a memory marked `beliefState: deprecated` or `superseded`.** Such a note is no longer true and gave
+  no lesson (26 of about 900 memories carry the state; distill ran on 17 of them). The improve loop records a
+  `distill-skipped` action and an `improve_skipped` event (`distill_deprecated_or_superseded`), and the attempt goes
+  in the ledger as `unchanged`; an explicit `--scope` ref still runs. `contradicted` is still distilled.
+- The distill judge scores a lesson 1–2 on non-redundancy when a listed asset
+  states most of what it says, not only when it states the same rule, and is
+  told to compare only with the listed assets, never with the source memory.
+  Before, a lesson that restated a skill the library holds scored 3 ("largely
+  redundant") and went to a reviewer. Judge-only replay of the lessons the
+  writer produced (local qwen3.8-27b, 3 repeats): of 4 public lessons for
+  memories that deserve none, 12 verdicts passed 3 before and 1 after, and of
+  12 such own lessons 33 of 36 passed before and 27 after, while the 31
+  lesson-worthy own lessons lost no verdict (2 of 93 rejected before, 0 after).
+- **The pair judge's reason no longer swaps A and B.** In a replay of 120 recorded pairs, 18 of 90 retirement
+  reasons said the opposite of what the judge's claim lists decided (for example "B contains all claims from A" for a
+  pair where B was retired). The lists were right, so no retirement changed, but the reason a reviewer reads was
+  wrong. The prompt now asks the reason to name the asset that can be deleted; two replays gave 0 and 1 of about 85.
+
 ## [0.9.27] - 2026-10-07
 
 The stable release of the 0.9.27 line: 0.9.27-alpha.1, alpha.2 and alpha.3.

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

@@ -16,4 +16,4 @@ Then classify the relation as exactly one of:
 
 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: {"onlyInA": ["..."], "onlyInB": ["..."], "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: name the asset that can be deleted and what the other asset still holds>"}

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

@@ -28,7 +28,7 @@ import { checkDeadUrls } from "../url-checker.js";
 import { isDistillCandidateRef } from "./eligibility.js";
 import { shouldSkipRef } from "./improve-strategies.js";
 import { recordLedgerAttempt, stateKey, stripBundle } from "./ledger.js";
-import { hasOnlyBarePositiveFeedback, isFlaggedSinceLastEdit, pushRecentError } from "./preparation.js";
+import { hasOnlyBarePositiveFeedback, isDeprecatedOrSuperseded, isFlaggedSinceLastEdit, pushRecentError, } from "./preparation.js";
 import { recordNoOp, resetConsecutiveNoOps } from "./salience.js";
 import { attributeStage, errMessage } from "./stage.js";
 export function prepareImproveLoopEnv(args) {
@@ -198,6 +198,7 @@ async function runLoopReflectPass(planned, env, tally) {
 }
 const FLAGGED_WRONG_REASON = "flagged wrong since its last edit";
 const BARE_POSITIVE_REASON = "only positive feedback, without a reason";
+const DEPRECATED_REASON = "marked deprecated or superseded";
 async function runLoopDistillPass(planned, refType, isDistillOnly, env, tally) {
     const { options, primaryStashDir, improveProfile, resolvedPlan } = env;
     const distillSkip = shouldSkipRef(planned.ref, "distill", improveProfile);
@@ -232,6 +233,12 @@ async function runLoopDistillPass(planned, refType, isDistillOnly, env, tally) {
         recordLoopAttempt(planned, env, "distill", "unchanged", BARE_POSITIVE_REASON);
         return recordSkip(tally, planned.ref, BARE_POSITIVE_REASON, { env, reason: "distill_positive_without_reason" });
     }
+    // A memory marked deprecated or superseded is no longer true, so it gives no lesson. The ledger holds it; an
+    // explicit `--scope` ref still runs.
+    if (!explicitRefScope && isDeprecatedOrSuperseded(planned)) {
+        recordLoopAttempt(planned, env, "distill", "unchanged", DEPRECATED_REASON);
+        return recordSkip(tally, planned.ref, DEPRECATED_REASON, { env, reason: "distill_deprecated_or_superseded" });
+    }
     const result = await attributeStage(resolvedPlan, "distill", () => env.distillFn({
         ref: planned.ref,
         ...(planned.itemRef ? { itemRef: planned.itemRef } : {}),

package/dist/commands/improve/preparation.js

@@ -575,6 +575,22 @@ export function isFlaggedSinceLastEdit(candidate, eventsCtx) {
         return typeof meta.contentHash === "string" ? meta.contentHash === bodyHash : Date.parse(e.ts) > editedAtMs;
     });
 }
+/**
+ * Whether `candidate`'s file declares `beliefState: deprecated` or `superseded`: a note its owner marked no longer
+ * true is no source for a lesson (the 2026-10-08 distill-tune run: 26 of ~900 memories carry the state, none gave
+ * a lesson). `contradicted` is left out: it means a conflict is open, not that the note is retired.
+ */
+export function isDeprecatedOrSuperseded(candidate) {
+    if (!candidate.filePath)
+        return false;
+    try {
+        const state = parseFrontmatter(fs.readFileSync(candidate.filePath, "utf8")).data.beliefState;
+        return state === "deprecated" || state === "superseded";
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Whether the only feedback `candidate` has inside the signal window is positive and says nothing: no reason, no
  * note. A bare `--positive` only records that a note helped, which gives the writer nothing to distil, so it restates

package/dist/commands/improve/stage.js

@@ -223,7 +223,7 @@ export function buildJudgePrompt(lessonContent, sourceContent, related, feedback
         "",
         "Score this lesson on each criterion from 1 (poor) to 5 (excellent):",
         "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.",
+        '2. NON-REDUNDANCY: Compare the lesson only with the assets listed under "Existing assets nearest the new lesson" (each starts with "Existing asset ref:"); never with the source memory. When that list is absent, score 5. Score 1-2 when a listed asset already states the same rule, or states most of what the lesson says in broader words. Score 4-5 when the lesson gives a rule none of the listed assets gives, or when they are on other subjects.',
         "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 memory:",

package/docs/reference/data-and-telemetry.md

@@ -188,7 +188,7 @@ the set of types the code actually emits at HEAD (verified against every
 | `improve_invoked` | Start of an `akm improve` run | `ref` (scope); `strategy`, `scope`, `dryRun`, `eligibleCount` |
 | `improve_completed` | `akm improve` run finished | run stats |
 | `improve_failed` | `akm improve` run errored | error |
-| `improve_skipped` | `akm improve` left a ref, a lane, or a group of refs out | `reason` (`no_new_signal`, `not_retrieved`, `distill_no_new_signal`, `budget_exhausted`, `budget_exhausted_batch`, `asset_missing_on_disk`, `strategy_filtered_all_passes`, `autonomy_gated`, `engine_unavailable`, `pool_below_min_size`, `consolidation_no_memory_updates`, `below_min_new_sessions`, `derived_memory_reflect_skipped`, `memory_distill_requires_feedback`, `distill_flagged_wrong`, `distill_positive_without_reason`); `count`, `remaining`, `strategy`, `lane` or `configKey` where they apply |
+| `improve_skipped` | `akm improve` left a ref, a lane, or a group of refs out | `reason` (`no_new_signal`, `not_retrieved`, `distill_no_new_signal`, `budget_exhausted`, `budget_exhausted_batch`, `asset_missing_on_disk`, `strategy_filtered_all_passes`, `autonomy_gated`, `engine_unavailable`, `pool_below_min_size`, `consolidation_no_memory_updates`, `below_min_new_sessions`, `derived_memory_reflect_skipped`, `memory_distill_requires_feedback`, `distill_flagged_wrong`, `distill_positive_without_reason`, `distill_deprecated_or_superseded`); `count`, `remaining`, `strategy`, `lane` or `configKey` where they apply |
 | `improve_lock_recovered` | Stale improve lock cleared at startup | |
 | `improve_review_needed` | `akm feedback` pushed a high-utility asset's utility below the review threshold — a review-needed escalation is recorded (not a proposal, so it can't accidentally overwrite the asset) | `ref`, `previousUtility`, `nextUtility` |
 | `reflect_invoked` | Start of reflect phase in `akm improve` | `ref`, engine |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.27",
+  "version": "0.9.28-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": [