akm-cli 0.9.26-alpha.2 → 0.9.27-alpha.1

package/dist/scripts/akm-migrate.js

@@ -24967,6 +24967,7 @@ var $visitAsync = visit.visitAsync;
 import path7 from "path";
 // src/runtime.ts
 import { spawn as nodeSpawn, spawnSync as nodeSpawnSync } from "child_process";
+import { createHash } from "crypto";
 import { createWriteStream, statfsSync } from "fs";
 import { createRequire } from "module";
 import path6 from "path";
@@ -26131,6 +26132,9 @@ async function writeResponseToFileCapped(filePath, res, options) {
     reader.releaseLock?.();
   }
 }
+function sha256Hex(data) {
+  return createHash("sha256").update(data).digest("hex");
+}
 function getDirname(importMetaUrl) {
   return path6.dirname(fileURLToPath(importMetaUrl));
 }
@@ -35173,8 +35177,7 @@ var ExperimentalConfigSchema = exports_external.object({
 
 // src/core/config/schema/feedback.ts
 var FeedbackConfigSchema = exports_external.object({
-  requireReason: exports_external.boolean().optional(),
-  allowedFailureModes: exports_external.array(nonEmptyString).optional()
+  requireReason: exports_external.boolean().optional()
 }).passthrough();
 
 // src/core/config/schema/improve-processes.ts
@@ -36178,7 +36181,7 @@ function withConfigLock(fn) {
 }
 
 // src/core/config/config-sources.ts
-import { createHash } from "crypto";
+import { createHash as createHash2 } from "crypto";
 import fs9 from "fs";
 import path13 from "path";
 function bundleComponentConfig(bundle) {
@@ -36241,7 +36244,7 @@ function filesystemBundleSourceId(contentRoot) {
   });
 }
 function hashBundleSourceIdentity(identity3) {
-  return `sha256:${createHash("sha256").update("akm.bundle-source\x00v1\x00").update(JSON.stringify(identity3)).digest("hex")}`;
+  return `sha256:${createHash2("sha256").update("akm.bundle-source\x00v1\x00").update(JSON.stringify(identity3)).digest("hex")}`;
 }
 function bundleContentRoots(config) {
   const bundles = config.bundles ?? {};
@@ -37703,7 +37706,7 @@ async function tryFetchJson(url, headers) {
 }
 
 // src/sources/providers/provider-utils.ts
-import { createHash as createHash4, randomUUID as randomUUID2 } from "crypto";
+import { createHash as createHash5, randomUUID as randomUUID2 } from "crypto";
 import fs27 from "fs";
 import path34 from "path";
 
@@ -37798,7 +37801,7 @@ function countLines(text) {
 }
 
 // src/core/adapter/adapters/shared.ts
-import { createHash as createHash2 } from "crypto";
+import { createHash as createHash3 } from "crypto";
 
 // src/core/asset/frontmatter-lint.ts
 function checkUnquotedDescriptionColon(frontmatterText) {
@@ -37820,7 +37823,7 @@ function checkUnquotedDescriptionColon(frontmatterText) {
 
 // src/core/adapter/adapters/shared.ts
 function hashContent(content) {
-  return createHash2("sha256").update(content, "utf8").digest("hex");
+  return createHash3("sha256").update(content, "utf8").digest("hex");
 }
 function nonEmptyString2(value) {
   if (typeof value !== "string")
@@ -39003,7 +39006,7 @@ function extractDirTagsFromName(name) {
 }
 
 // src/core/adapter/execution-source.ts
-import { createHash as createHash3 } from "crypto";
+import { createHash as createHash4 } from "crypto";
 
 // src/execution/source.ts
 var EXECUTION_SOURCE_SCHEMA_VERSION = 1;
@@ -39341,7 +39344,7 @@ function renderMarkdownExecutionSource(input) {
       bundle: identity3.bundle,
       adapter: identity3.adapter,
       file: identity3.file,
-      hash: createHash3("sha256").update(raw, "utf8").digest("hex")
+      hash: createHash4("sha256").update(raw, "utf8").digest("hex")
     },
     ...hasDefaults ? { defaults } : {},
     ...extensions === undefined ? {} : { extensions }
@@ -45896,7 +45899,7 @@ function uniqueSlug() {
 }
 function buildInstallCacheDir(cacheRootDir, source, id, version) {
   const safeId = id.replace(/[^a-zA-Z0-9_.-]+/g, "-").replace(/^-+|-+$/g, "");
-  const identitySuffix = version === "writable" ? `-${createHash4("sha256").update(`${source}:${id}`).digest("hex").slice(0, 12)}` : "";
+  const identitySuffix = version === "writable" ? `-${createHash5("sha256").update(`${source}:${id}`).digest("hex").slice(0, 12)}` : "";
   const slug = `${source}-${safeId}${identitySuffix}`;
   const versionSlug = source === "local" ? uniqueSlug() : version?.replace(/[^a-zA-Z0-9_.-]+/g, "-") ?? uniqueSlug();
   return path34.join(cacheRootDir, slug || source, versionSlug);
@@ -45917,7 +45920,7 @@ async function downloadArchive(url, destination) {
 }
 async function computeFileHash(filePath) {
   const data = fs27.readFileSync(filePath);
-  const hash = createHash4("sha256").update(data).digest("hex");
+  const hash = createHash5("sha256").update(data).digest("hex");
   return `sha256:${hash}`;
 }
 function isDirectory(target) {
@@ -46092,7 +46095,7 @@ function redactUrlUserinfo(text) {
   return text.replace(/\b([A-Za-z][A-Za-z0-9+.-]*:\/\/)([^\s/@]+)@/g, "$1[REDACTED]@");
 }
 // src/sources/providers/git-provider.ts
-import { createHash as createHash5 } from "crypto";
+import { createHash as createHash6 } from "crypto";
 import fs30 from "fs";
 import path36 from "path";
 
@@ -46153,7 +46156,7 @@ function resolveGitContentDir(config) {
   throw new ConfigError("git source entry must have either `path` or `url`");
 }
 function getCachePaths(repoUrl, cacheRootOverride) {
-  const key = createHash5("sha256").update(repoUrl).digest("hex").slice(0, 16);
+  const key = createHash6("sha256").update(repoUrl).digest("hex").slice(0, 16);
   const cacheRoot = cacheRootOverride ?? getRegistryIndexCacheDir();
   const rootDir = path36.join(cacheRoot, `git-${key}`);
   return {
@@ -46374,7 +46377,7 @@ import fs33 from "fs";
 import path39 from "path";
 
 // src/sources/providers/tar-utils.ts
-import { createHash as createHash6 } from "crypto";
+import { createHash as createHash7 } from "crypto";
 import fs32 from "fs";
 import path38 from "path";
 function verifyArchiveIntegrity(archivePath, expected, source) {
@@ -46387,7 +46390,7 @@ function verifyArchiveIntegrity(archivePath, expected, source) {
     const dashIndex = expected.indexOf("-");
     const algorithm = expected.slice(0, dashIndex);
     const expectedBase64 = expected.slice(dashIndex + 1);
-    const actualBase64 = createHash6(algorithm).update(fileBuffer).digest("base64");
+    const actualBase64 = createHash7(algorithm).update(fileBuffer).digest("base64");
     if (actualBase64 !== expectedBase64) {
       fs32.unlinkSync(archivePath);
       throw new Error(`Integrity check failed for ${archivePath}: expected ${algorithm} digest ${expectedBase64}, got ${actualBase64}`);
@@ -46395,7 +46398,7 @@ function verifyArchiveIntegrity(archivePath, expected, source) {
     return;
   }
   if (/^[0-9a-f]{40}$/i.test(expected)) {
-    const actualHex = createHash6("sha1").update(fileBuffer).digest("hex");
+    const actualHex = createHash7("sha1").update(fileBuffer).digest("hex");
     if (actualHex.toLowerCase() !== expected.toLowerCase()) {
       fs32.unlinkSync(archivePath);
       throw new Error(`Integrity check failed for ${archivePath}: expected sha1 ${expected}, got ${actualHex}`);
@@ -51665,14 +51668,15 @@ class ClaudeHarness extends BaseHarness {
 }
 
 // src/integrations/harnesses/codex/agent-builder.ts
-import { mkdtempSync, writeFileSync } from "fs";
-import { tmpdir } from "os";
+import { mkdirSync } from "fs";
 import { join as join2 } from "path";
 function writeCodexOutputSchemaFile(schema) {
-  const dir = mkdtempSync(join2(tmpdir(), "akm-codex-schema-"));
-  const file = join2(dir, "output-schema.json");
-  writeFileSync(file, `${JSON.stringify(schema, null, 2)}
-`, "utf8");
+  const text = `${JSON.stringify(schema, null, 2)}
+`;
+  const dir = join2(getCacheDir(), "codex-output-schemas");
+  mkdirSync(dir, { recursive: true });
+  const file = join2(dir, `${sha256Hex(text)}.json`);
+  writeFileAtomic(file, text);
   return file;
 }
 function ensureSandboxFlags(base) {

package/dist/storage/repositories/index-entry-schema.js

@@ -120,20 +120,36 @@ const REQUIRED_ENTRY_COLUMNS = [
     "document_json",
     "derived_from",
 ];
+/**
+ * The transitional columns layout 20 and earlier kept beside the current ones
+ * and layout 21 removed (`entry_key` was the key). They are NOT NULL, so a
+ * table that still has one takes none of this release's inserts, and its
+ * `document_json` is empty (the entry sat in `entry_json`), so none of its rows
+ * can be read either. A 0.9.1 index is such a table.
+ */
+const RETIRED_ENTRY_COLUMNS = ["entry_key", "dir_path", "stash_dir", "entry_json", "entry_type"];
+function entryColumnNames(db) {
+    return new Set(db.prepare("PRAGMA table_info(entries)").all().map((c) => c.name));
+}
 /** Required `entries` columns the table lacks; every column when there is no `entries` table. */
 export function missingEntryColumns(db) {
-    const present = new Set(db.prepare("PRAGMA table_info(entries)").all().map((c) => c.name));
+    const present = entryColumnNames(db);
     return REQUIRED_ENTRY_COLUMNS.filter((column) => !present.has(column));
 }
+/** Retired `entries` columns the table still has: it was written by layout 20 or earlier. */
+export function retiredEntryColumns(db) {
+    const present = entryColumnNames(db);
+    return RETIRED_ENTRY_COLUMNS.filter((column) => present.has(column));
+}
 /**
  * Whether an index database has an `entries` table this release can read. A
  * fresh or empty file has none; an index older than layout 21 has one keyed
- * by columns this release no longer reads, and serves nothing until the next
- * `akm index` recreates it.
+ * by columns this release no longer reads (or lacks the ones it does), and
+ * serves nothing until the next `akm index` recreates it.
  */
 export function hasCurrentEntriesTable(db) {
     try {
-        return missingEntryColumns(db).length === 0;
+        return missingEntryColumns(db).length === 0 && retiredEntryColumns(db).length === 0;
     }
     catch {
         return false;

package/dist/storage/repositories/index-fts-repository.js

@@ -19,9 +19,27 @@ import { splitMarkdownFragments } from "../../core/asset/markdown-fragments.js";
 import { warn } from "../../core/warn.js";
 import { ftsOrMatch, ftsQueryTokens } from "../../indexer/search/fts-query.js";
 import { buildSearchFields } from "../../indexer/search/search-fields.js";
+import { isContentlessFtsDdl, readTableSql } from "./index-entry-schema.js";
+import { deleteMeta, getMeta } from "./index-meta-repository.js";
 import { SQLITE_CHUNK_SIZE } from "./index-sql.js";
 // `entries_fts.rowid = entries.id`, so a per-entry delete is a rowid lookup.
 const INSERT_FTS_SQL = "INSERT INTO entries_fts (rowid, entry_id, name, description, tags, hints, content) VALUES (?, ?, ?, ?, ?, ?, ?)";
+/**
+ * `index_meta` key stamped when a delete took a row out of `entries_fts`.
+ *
+ * FTS5 cannot take a deleted row out of a contentless table's BM25 totals (its
+ * row count, and the token counts the average document length comes from), so
+ * every removal or replacement leaves them one row too high and an updated
+ * index scores differently from a fresh one (#1048). SQLite has no command that
+ * recomputes them (`delete` and `rebuild` are refused on a contentless table),
+ * so the next `akm index` rebuilds the table from `entries`
+ * ({@link rebuildFtsIfTotalsStale}).
+ */
+const FTS_TOTALS_STALE_META = "ftsTotalsStale";
+/** The content-bearing table older SQLite gets subtracts a deleted row itself. */
+function isContentlessFts(db) {
+    return isContentlessFtsDdl(readTableSql(db, "entries_fts"));
+}
 const ftsMutationStatementsByDb = new WeakMap();
 function getFtsMutationStatements(db) {
     const existing = ftsMutationStatementsByDb.get(db);
@@ -29,6 +47,7 @@ function getFtsMutationStatements(db) {
         return existing;
     const statements = {
         deleteOne: db.prepare("DELETE FROM entries_fts WHERE rowid = ?"),
+        markTotalsStale: db.prepare(`INSERT OR IGNORE INTO index_meta (key, value) VALUES ('${FTS_TOTALS_STALE_META}', '1')`),
         insert: db.prepare(INSERT_FTS_SQL),
         upsertFragmentSource: db.prepare("INSERT INTO entry_fragments (entry_id, safe_markdown) VALUES (?, ?) ON CONFLICT(entry_id) DO UPDATE SET safe_markdown = excluded.safe_markdown"),
         deleteFragmentSource: db.prepare("DELETE FROM entry_fragments WHERE entry_id = ?"),
@@ -36,6 +55,11 @@ function getFtsMutationStatements(db) {
     ftsMutationStatementsByDb.set(db, statements);
     return statements;
 }
+/** A delete that removed a row leaves the table's BM25 totals too high until it is rebuilt. */
+function noteRemoval(statements, removed) {
+    if (removed.changes > 0)
+        statements.markTotalsStale.run();
+}
 /**
  * Replace one entry's derived FTS row, and its fragment source when the scan
  * read Markdown, inside the caller's transaction.
@@ -43,7 +67,7 @@ function getFtsMutationStatements(db) {
 export function replaceFtsEntry(db, entryId, entry, fragmentContent) {
     const fields = buildSearchFields(entry);
     const statements = getFtsMutationStatements(db);
-    statements.deleteOne.run(entryId);
+    noteRemoval(statements, statements.deleteOne.run(entryId));
     statements.insert.run(entryId, entryId, fields.name, fields.description, fields.tags, fields.hints, fields.content);
     if (fragmentContent === undefined) {
         // Metadata-only re-upserts and re-keys deserialize the public document
@@ -61,7 +85,7 @@ export function deleteFtsEntries(db, entryIds) {
     for (let i = 0; i < entryIds.length; i += SQLITE_CHUNK_SIZE) {
         const chunk = entryIds.slice(i, i + SQLITE_CHUNK_SIZE);
         const placeholders = chunk.map(() => "?").join(",");
-        db.prepare(`DELETE FROM entries_fts WHERE rowid IN (${placeholders})`).run(...chunk);
+        noteRemoval(getFtsMutationStatements(db), db.prepare(`DELETE FROM entries_fts WHERE rowid IN (${placeholders})`).run(...chunk));
         db.prepare(`DELETE FROM entry_fragments WHERE entry_id IN (${placeholders})`).run(...chunk);
     }
 }
@@ -143,7 +167,9 @@ function materializeIndexedMarkdownFragment(fragment, fragments, parentChars) {
  */
 export function rebuildFts(db) {
     db.transaction(() => {
-        db.exec("DELETE FROM entries_fts");
+        // `delete-all` also resets the BM25 totals, which a plain DELETE leaves as they were (#1048).
+        db.exec(isContentlessFts(db) ? "INSERT INTO entries_fts(entries_fts) VALUES('delete-all')" : "DELETE FROM entries_fts");
+        deleteMeta(db, FTS_TOTALS_STALE_META);
         // Keyset pages, so a large index is never held in memory at once.
         const page = db.prepare("SELECT id, document_json FROM entries WHERE id > ? ORDER BY id LIMIT 500");
         const insertStmt = db.prepare(INSERT_FTS_SQL);
@@ -171,3 +197,18 @@ export function rebuildFts(db) {
         }
     })();
 }
+/**
+ * Rebuild `entries_fts` from `entries` when rows have left it since its BM25
+ * totals were last taken (#1048): about a second at 25,000 entries. Returns
+ * whether it did.
+ */
+export function rebuildFtsIfTotalsStale(db) {
+    if (getMeta(db, FTS_TOTALS_STALE_META) === undefined)
+        return false;
+    if (!isContentlessFts(db)) {
+        deleteMeta(db, FTS_TOTALS_STALE_META);
+        return false;
+    }
+    rebuildFts(db);
+    return true;
+}

package/dist/storage/repositories/index-schema.js

@@ -25,7 +25,7 @@ import path from "node:path";
 import { ConfigError } from "../../core/errors.js";
 import { warn } from "../../core/warn.js";
 import { sha256Hex } from "../../runtime.js";
-import { CANONICAL_ENTRY_SCHEMA_SQL, CANONICAL_INDEX_DB_VERSION, entriesFtsDdl, isContentlessFtsDdl, missingEntryColumns, readTableSql, supportsContentlessDelete, tableExists, } from "./index-entry-schema.js";
+import { CANONICAL_ENTRY_SCHEMA_SQL, CANONICAL_INDEX_DB_VERSION, entriesFtsDdl, isContentlessFtsDdl, missingEntryColumns, readTableSql, retiredEntryColumns, supportsContentlessDelete, tableExists, } from "./index-entry-schema.js";
 import { rebuildFts } from "./index-fts-repository.js";
 import { rebuildAllEntryLinks } from "./index-links-repository.js";
 import { getMeta, setMeta } from "./index-meta-repository.js";
@@ -67,11 +67,13 @@ const REGISTRY_INDEX_CACHE_DDL = `
     ON registry_index_cache(fetched_at);
 `;
 /**
- * An `entries` table missing a required column cannot be read or written by
- * this release (the last such change was v20→v21, which removed the
- * transitional `entry_key`/`dir_path`/... columns and made `item_ref` the
- * key). Recreate only the tables keyed by `entries.id` — their ids are about
- * to be re-minted, so the rows would dangle anyway. The LLM enrichment cache
+ * An `entries` table missing a required column, or still carrying a retired
+ * one, cannot be read or written by this release (the last such change was
+ * v20→v21, which removed the transitional `entry_key`/`dir_path`/... columns
+ * and made `item_ref` the key). Layouts 18–20 carried the current columns
+ * beside the retired ones, so only the retired ones give them away.
+ * Recreate only the tables keyed by `entries.id` — their ids are about to be
+ * re-minted, so the rows would dangle anyway. The LLM enrichment cache
  * (keyed by ref) is kept. The LLM entity-graph tables are unconditionally
  * dropped elsewhere in this file regardless of this recreation (retired
  * 0.9.17-alpha.9), not kept. The next index run re-walks every source.
@@ -80,9 +82,13 @@ function ensureEntriesLayout(db) {
     if (!tableExists(db, "entries"))
         return;
     const missing = missingEntryColumns(db);
-    if (missing.length === 0)
+    const retired = retiredEntryColumns(db);
+    if (missing.length === 0 && retired.length === 0)
         return;
-    warn(`Index database entries table predates the ${missing.join(", ")} column${missing.length === 1 ? "" : "s"} — ` +
+    const why = missing.length > 0
+        ? `predates the ${missing.join(", ")} column${missing.length === 1 ? "" : "s"}`
+        : `still has the retired ${retired.join(", ")} column${retired.length === 1 ? "" : "s"}`;
+    warn(`Index database entries table ${why} — ` +
         "recreating the entries-keyed tables (entries, full-text, embeddings, utility scores); the " +
         "LLM enrichment cache is kept. The next index run re-walks every source.");
     db.transaction(() => {

package/docs/reference/cli.md

@@ -1587,17 +1587,27 @@ preserves it byte-for-byte.
 
 ### feedback
 
-Record positive or negative feedback for any indexed bundle asset.
+Record positive or negative feedback for any indexed bundle asset. Record
+`--negative` only when the asset's content is wrong or stale, and say what is
+wrong and what it should say; a note that simply did not fit your task is not
+negative feedback, so record nothing for it.
 `akm feedback <ref> --negative --reason "<what is wrong and what should change>"`
 flags the asset: it ranks lower right away, and the next improve run may repair
 its description, title or `when_to_use` from your reason. Improve does not
-rewrite an asset's text. To correct a wrong fact there, attach the exact fix
-with `--replace`, `--with` and `--source`: akm checks that each `--replace`
-text appears exactly once and that the frontmatter still parses, records nothing
-if either check fails, and queues the edit as a `feedback` proposal for review.
-`--positive` records that an asset helped (it raises its ranking) and does not
-trigger a rewrite. Both signals update the asset's
-utility score right away, so highly-rated assets rank higher in search results.
+rewrite an asset's text. Once you have verified the correct fact, attach the
+exact fix with `--replace`, `--with` and `--source`: akm checks that each
+`--replace` text appears exactly once and that the frontmatter still parses,
+records nothing if either check fails, and queues the edit as a `feedback`
+proposal for review.
+To mark the asset's history, with or without a text fix, add `--superseded-by
+<ref>` (another asset replaces it) or `--outdated` (it describes a past state
+and no single asset replaces it), with `--reason` and `--source`. The same single
+proposal sets the asset's `beliefState` (`superseded`, or `deprecated`) and, for
+`--superseded-by`, adds the successor's ref to its `supersededBy` list, by
+editing only those lines of the frontmatter. `--positive` records that an asset
+helped (it raises its ranking) and does not trigger a rewrite. Both signals
+update the asset's utility score right away, so highly-rated assets rank higher
+in search results.
 
 ```sh
 akm feedback scripts/deploy.sh --positive
@@ -1605,20 +1615,23 @@ akm feedback agents/reviewer --negative
 akm feedback memories/deployment-notes --positive
 akm feedback env/prod --positive
 akm feedback skills/code-review --positive --reason "Worked perfectly for PR reviews"
-akm feedback skills/code-review --negative --failure-mode outdated --reason "references a removed flag"
+akm feedback skills/code-review --negative --reason "references a removed flag"
 akm feedback skills/code-review --negative --reason "flaky" --tag slice:train --tag team:platform
 akm feedback knowledge/opencode-server --negative --reason "the default port is 4096, not 8000" --replace "port 8000" --with "port 4096" --source "https://opencode.ai/docs/server/"
+akm feedback knowledge/setup-v1 --negative --reason "the v2 guide replaces it" --superseded-by knowledge/setup-v2 --source "knowledge/setup-v2"
+akm feedback knowledge/api-v1 --negative --reason "describes the retired v1 API" --outdated --source "https://example.com/changelog"
 ```
 
 | Flag | Description |
 | --- | --- |
 | `--positive` | Record that an asset helped: it raises its ranking and does not trigger a rewrite |
 | `--negative` | Flag the asset: it ranks lower right away, and the next improve run may repair its frontmatter from `--reason` |
-| `--reason` | What is wrong with the asset's content and what should change; not for `akm` command errors. Attached to the feedback event (required for negative feedback by default, and always with `--replace`) |
+| `--reason` | What is wrong with the asset's content and what should change; not for `akm` command errors. Attached to the feedback event (required for negative feedback by default, and always with a fix: `--replace`, `--superseded-by` or `--outdated`) |
 | `--replace <text>` | Exact text to correct, copied verbatim from the asset file; it must appear exactly once. Repeatable, each paired in order with a `--with`. Negative feedback only |
 | `--with <text>` | The corrected text for the matching `--replace`. Use `--with=<text>` for a value that starts with `-` |
-| `--source <where>` | The URL, command or file that shows the correct fact. Required with `--replace`; shown to the reviewer with the proposal |
-| `--failure-mode` | Structured failure-mode taxonomy for negative feedback: `incorrect`, `outdated`, `dangerous`, `incomplete`, `redundant`. Stored alongside `--reason` in event metadata for the distill pipeline. |
+| `--source <where>` | The URL, command or file that shows the correct fact. Required with `--replace`, `--superseded-by` and `--outdated`; shown to the reviewer with the proposal |
+| `--superseded-by <ref>` | The ref of the asset that replaces this one. The proposal sets `beliefState: superseded` and adds the ref, as its `bundle//conceptId`, to `supersededBy`; `contradicted` and `archived` stay, a ref already listed is not added again, and a scalar `supersededBy` becomes a list. The ref must be indexed and must not be the asset itself, or nothing is recorded; nor is anything when the asset already says all this (the fix changes nothing). Negative feedback only; may be combined with `--replace`/`--with`, not with `--outdated`; markdown assets only |
+| `--outdated` | The asset describes a past state and no single asset replaces it. The proposal sets `beliefState: deprecated`, unless the asset already says `superseded`, `contradicted` or `archived`. Negative feedback only; may be combined with `--replace`/`--with`, not with `--superseded-by`; markdown assets only |
 | `--tag` | Tag to attach to the feedback (repeatable, e.g. `--tag slice:train --tag team:platform`) |
 | `--applied-to <ref>` | Credit a `lessons/<name>` lesson that helped resolve this task. When combined with `--positive`, appends this feedback ref to the target lesson's `lessonStrength[]` frontmatter array (dedup, idempotent). A non-lesson target, or a missing `--positive`, produces a warning rather than silently doing nothing. |
 
@@ -2522,8 +2535,12 @@ feedback in the last 30 days newer than the stage's last ledger attempt, or for
 an explicit ref scope. A positive or note-only signal never plans one, so
 improve does not rewrite an asset from a positive signal. Distill keeps its own
 trigger: a memory with feedback of any kind (a signal or a note) in that window,
-newer than distill's last attempt. Two fallback lanes pick refs with no such
-feedback: high salience (content-scored refs at or above
+newer than distill's last attempt. It skips a memory flagged wrong and not
+edited since (a negative feedback in that window judged the body it still has,
+or, recorded without that body's hash, is newer than the file's last write),
+and a memory whose only feedback in that window is positive with no reason or
+note, unless the ref is explicit. Two fallback lanes pick refs
+with no such feedback: high salience (content-scored refs at or above
 `improve.salience.salienceThreshold`, default `0.75`, that were never reflected,
 capped at 10% of the limit, at least one ref) and, in a strategy that enables
 `proactiveMaintenance`, refs due for a revisit. They only select and score refs
@@ -2763,6 +2780,7 @@ harvest" branch on `skipReasons`, `warnings`, or `sessionsProcessed` /
 | `engineKind` | `"llm"`, `"sdk"`, or `"agent"` — the kind of runner `engine` resolved to. Same absence condition as `engine`. |
 | `skipReasons` | Per-`skipReason` count across `sessions[]` (e.g. `{ "llm_unavailable": 25 }`). Present only when `sessionsSkipped > 0`. |
 | `warnings` | Includes one aggregate line per infrastructure skip reason that fired (`llm_unavailable`, `read_failed`, `exception`, `locked_concurrent`) — e.g. `25 of 25 sessions skipped: llm_unavailable (engine "default")` — so an engine outage is visible without inspecting `sessions[]`. Session-content skips (`already_extracted`, `too_short`, `triaged_out`) are counted in `skipReasons` but never produce a warning line. |
+| `sessions[].warnings` | One line per candidate the model wrote that the output contract refuses, as `<type>:<name> dropped: <reason>` — a lesson without a `when_to_use` of 15 characters, a description under 20, a name that is not a kebab-case slug — and one per candidate held back by the improve ledger. A session whose every candidate was dropped has `candidateCount: 0` and no `rationaleIfEmpty`, so this is where the loss shows. |
 
 #### proposal new
 
@@ -3081,9 +3099,10 @@ passed on its current content is accepted (unless its target changed since it
 was minted — that one is auto-rejected as `stale-target`); an empty diff is
 rejected; a proposal that reflect or distill deferred for review is left for a
 person; everything else goes to the judgment tier when one is enabled, and
-is otherwise left for review. A reflect revision that changes the body is
-deferred for review even when its judge passes it. Default mode stages
-decisions (queue mode); pass `--promote` to actually accept.
+is otherwise left for review. A reflect revision that changes the body, and
+every distill lesson or knowledge promotion, is deferred for review even when
+its judge passes it. Default mode stages decisions (queue mode); pass
+`--promote` to actually accept.
 
 ```sh
 akm proposal drain --dry-run                        # Preview without writing

package/docs/reference/configuration.md

@@ -110,8 +110,11 @@ distill quality-gate judges do too unless the judge's engine sets
 `reasoning_effort` when set. Backend support: llama.cpp direct honors both forms
 (`reasoning_effort` from build ≥ b10644); vLLM honors
 `chat_template_kwargs`; Bifrost drops `chat_template_kwargs` and passes
-`reasoning_effort` through, so also set `reasoningEffort: "none"` behind it; a
-strict hosted API may 400 on unrecognized keys. Both fields are AKM-owned, not
+`reasoning_effort` through, so also set `reasoningEffort: "none"` behind it. A
+strict hosted API that rejects the two fields (OpenAI answers 400 `Unknown
+parameter: 'chat_template_kwargs'`) gets one retry without both, and AKM stops
+sending them to that endpoint and model for the rest of the process, as it
+does for `response_format` below. Both fields are AKM-owned, not
 settable via `extraParams`. A response with reasoning tokens despite
 `enableThinking: false` triggers a runtime warning and the `akm health`
 `thinking-control` advisory.
@@ -467,7 +470,11 @@ guidance. When enabled, engine selection is judgment → triage → strategy →
 
 `processes.reflect.qualityGate` and `processes.distill.qualityGate` control
 each process's LLM-as-judge quality gate. Each is on unless it sets
-`enabled: false`, and each follows only its own switch. The judge is the
+`enabled: false`, and each follows only its own switch. A reflect revision the
+judge passes is staged for the triage drain to accept; a distill lesson it
+passes is deferred for a person (reason `distill-review`), which the drain and
+its judgment tier leave alone. With the distill gate off nothing is judged, and
+the drain decides. The judge is the
 process's own engine when that is an LLM engine, or the `defaults.llmEngine`
 engine when an agent generates. `engine`, `model`, `timeoutMs` and `llm` give the gate a judge of its own,
 resolved over the process's settings the way `triage.judgment` resolves over
@@ -745,12 +752,11 @@ or malformed response keeps the fused order.
 
 ## Feedback
 
-`feedback` shapes the `akm feedback` taxonomy:
+`feedback` configures `akm feedback`:
 
 | Key | Purpose |
 | --- | --- |
-| `feedback.requireReason` | Whether `akm feedback --negative` without `--reason`/`--failure-mode` is a hard error. **Defaults to `true`** when unset — set `false` to downgrade the check to a warning instead |
-| `feedback.allowedFailureModes` | Restrict `--failure-mode` values accepted by `akm feedback`. Curated set (also the default when unset): `incorrect`, `outdated`, `dangerous`, `incomplete`, `redundant` |
+| `feedback.requireReason` | Whether `akm feedback --negative` without `--reason` is a hard error. **Defaults to `true`** when unset — set `false` to downgrade the check to a warning instead |
 
 ## Bundles and write target
 

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

@@ -159,7 +159,7 @@ the set of types the code actually emits at HEAD (verified against every
 | `curate` | `akm curate <prompt>` | `query`, `itemCount`, `itemRefs` |
 | `show` | `akm show <ref>` | `ref`, `type`, `name` |
 | `select` | `akm show` after a search returning the same ref | `ref`, `query`, `searchTs`, `rankPosition` |
-| `feedback` | `akm feedback <ref>` | `signal` (positive/negative), `reason`, `failureMode`, `tags`, `fix` (`source` and the number of replacements, when an exact fix was attached) |
+| `feedback` | `akm feedback <ref>` | `signal` (positive/negative), `reason`, `tags`, `fix` (`source`, the number of replacements and, for `--superseded-by` or `--outdated`, the `beliefState` the proposal leaves and the `supersededBy` ref, when a fix was attached), `contentHash` (sha256 of the asset's body, without its frontmatter, as it stood when the feedback was given: it lets reflect mark feedback given on an earlier version of the text, and the loop's distill pass tell that a memory flagged wrong still has it; left out for an env or secret file and when the file cannot be read) |
 | `sync` | `akm sync` | `name`, `message`, `ok` |
 | `index_db_vacuumed` | `akm index` VACUUMed index.db, after an index layout migration or because more than half its pages were free | `pagesBefore`, `pagesAfter`, `freelistRatioBefore` |
 | `stash_synced` | `akm improve`'s internal auto-sync pass (the `sync.push` feature), **distinct from** the `akm sync` command above | `committed`, `pushed`, `skipped`, `reason`, `attributed` (paths the run wrote and staged), `unattributed` (in-scope paths that went dirty during the run without the run writing them — left for their author) |
@@ -188,14 +188,14 @@ 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`); `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`); `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 |
 | `reflect_completed` | Reflect phase produced a proposal | `ref` |
 | `improve_reflect_outcome` | Per-asset reflect result | `ref`, `ok`, `durationMs`, `reason` |
 | `propose_invoked` | `akm proposal new` | `ref` |
-| `distill_invoked` | Distill phase inside the `akm improve`/`akm proposal new` pipeline. **`akm distill` is not a CLI command** — there is no standalone verb by that name | `ref`, outcome |
+| `distill_invoked` | Distill phase inside the `akm improve`/`akm proposal new` pipeline. **`akm distill` is not a CLI command** — there is no standalone verb by that name | `ref`, outcome (`queued`, `skipped` with a `skipReason` such as `lesson_exists` or `conflict_noop`, `llm_failed`, `validation_failed`, `quality_rejected`, `review_needed`) |
 | `extract_invoked` | `akm proposal extract --type <harness>` / `--auto`, or improve-stage session extraction | `outcome`, `sessionId`, `harness` |
 | `extract_triaged` | The pre-LLM extract triage gate evaluated at least one session | `evaluated`, `passed`, `triagedOut`, `sourceRun` (aggregated) |
 | `schema_repair_invoked` | The schema-repair pass inside `akm improve` (`runSchemaRepairPass`) attempts to patch missing frontmatter on an asset that failed schema validation. **There is no `akm lint --repair` flag** — `lint` has `--fix`/`--auto-fix`, unrelated to this event | `ref`, outcome |

package/package.json

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

package/schemas/akm-config.json

@@ -595,13 +595,6 @@
       "properties": {
         "requireReason": {
           "type": "boolean"
-        },
-        "allowedFailureModes": {
-          "type": "array",
-          "items": {
-            "type": "string",
-            "minLength": 1
-          }
         }
       },
       "additionalProperties": true
@@ -2274,13 +2267,6 @@
           "properties": {
             "requireReason": {
               "type": "boolean"
-            },
-            "allowedFailureModes": {
-              "type": "array",
-              "items": {
-                "type": "string",
-                "minLength": 1
-              }
             }
           },
           "additionalProperties": true