akm-cli 0.9.26-alpha.2 → 0.9.26

package/dist/commands/improve/reflect.js

@@ -38,6 +38,7 @@ import { isJsonSchemaKnownUnsupported, LlmCallError } from "../../llm/client.js"
 import { baseFailureFields, enoentHintMessage, isEnoentFailure } from "../agent/agent-support.js";
 import { isValidDescription } from "../proposal/validators/proposal-quality-validators.js";
 import { CHARS_PER_TOKEN, DEFAULT_CONTEXT_LENGTH_TOKENS } from "./consolidate/chunking.js";
+import { contentHash } from "./content-hash.js";
 import { findAssetFilePath } from "./eligibility.js";
 import { resolveImproveExecution } from "./execution.js";
 import { recordLedgerAttempt } from "./ledger.js";
@@ -46,19 +47,29 @@ import { loadRetrievalQueries, runRetrievalRegressionGate } from "./retrieval-ga
 import { callStageOnce, errMessage, mintProposal, noticeSet, rejectedProposalContext, resolveQualityGateJudge, runReflectQualityJudge, } from "./stage.js";
 const MAX_FEEDBACK_LINES = 10;
 const MAX_GLOBAL_FEEDBACK_LINES = 20;
+/** Ends a feedback line whose event judged text the asset no longer has. */
+const EARLIER_TEXT_MARK = " (given on an earlier version of the text)";
 function readOnlyEventsContext(ctx) {
     return ctx?.db ? ctx : { ...(ctx ?? {}), readOnly: true };
 }
-/** Recent `feedback` lines for `ref` (or across all assets without one). Best-effort. */
-function readRecentFeedback(ref, eventsCtx) {
+/**
+ * Recent `feedback` lines for `ref` (or across all assets without one). Given the
+ * asset's current content, a line whose event recorded the hash of a different
+ * body is marked. Best-effort.
+ */
+function readRecentFeedback(ref, eventsCtx, assetContent) {
     try {
         const events = readEvents({ type: "feedback", ...(ref ? { ref } : {}) }, readOnlyEventsContext(eventsCtx)).events;
+        const bodyHash = assetContent === undefined ? undefined : contentHash(assetContent, "body");
         return events.slice(-(ref ? MAX_FEEDBACK_LINES : MAX_GLOBAL_FEEDBACK_LINES)).map((event) => {
             const md = event.metadata ?? {};
             const signal = typeof md.signal === "string" ? md.signal : "?";
             const note = typeof md.reason === "string" ? md.reason : typeof md.note === "string" ? md.note : "";
             const details = note ? `[${signal}] ${note}` : `[${signal}]`;
-            return !ref && event.ref ? `${event.ref} ${details}` : details;
+            const line = !ref && event.ref ? `${event.ref} ${details}` : details;
+            return bodyHash !== undefined && typeof md.contentHash === "string" && md.contentHash !== bodyHash
+                ? `${line}${EARLIER_TEXT_MARK}`
+                : line;
         });
     }
     catch {
@@ -636,7 +647,7 @@ function computeReflectContentBudgetChars(promptInput, runnerSpec) {
 /** Every read-only prompt input, shared by dispatch and `--show-prompt`. */
 function gatherReflectPromptSources(options, stash, parsedRef, assetContent) {
     return {
-        feedback: readRecentFeedback(options.ref ? (options.itemRef ?? options.ref) : undefined, options.eventsCtx),
+        feedback: readRecentFeedback(options.ref ? (options.itemRef ?? options.ref) : undefined, options.eventsCtx, assetContent),
         schemaHints: buildSchemaHints(parsedRef?.type ?? "", assetContent),
         rejectedProposals: rejectedProposalContext(stash, options.ref, options.ctx, options.eventsCtx),
         standardsContext: resolveStandardsContext(options.ref, stash),

package/dist/commands/proposal/repository.js

@@ -13,12 +13,13 @@ import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
 import { parse as parseYaml } from "yaml";
 import { ensureAkmMarkdownType } from "../../core/asset/akm-markdown.js";
 import { assetPathForName, placementTypes, stashDirFor } from "../../core/asset/asset-placement.js";
 import { isBundleSlug, parseBundleRef } from "../../core/asset/asset-ref.js";
 import { assembleAsset, serializeFrontmatter } from "../../core/asset/asset-serialize.js";
-import { carryForwardBookkeepingFrontmatter, parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { carryForwardBookkeepingFrontmatter, parseFrontmatter, replaceFrontmatterBlocks, } from "../../core/asset/frontmatter.js";
 import { conceptIdFromTypeName, parseRefInput } from "../../core/asset/resolve-ref.js";
 import { loadConfig } from "../../core/config/config.js";
 import { ConfigError, NotFoundError, rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
@@ -883,8 +884,17 @@ function isPlainRecord(value) {
  * Stamp provenance onto a promoted asset's frontmatter: bare top-level
  * `generated` and `verified` (as OKF v0.2 spells them; `verified` accumulates),
  * and `sources` under `provenance:`, since a bare `sources:` is the wiki
- * citation-string convention. An existing frontmatter block keeps its raw body
- * bytes.
+ * citation-string convention.
+ *
+ * Source preservation: an existing frontmatter block is edited as text and not
+ * written out again through the YAML serializer, which rewraps long values,
+ * requotes and drops comments in lines the stamp never touched. The blocks of
+ * the keys the stamp sets (`generated`, `verified`, `provenance`) are removed
+ * wherever they were and written again, serialized, as the last lines of the
+ * frontmatter; every other byte, the body included, stays as written. The
+ * edited text is parsed back to confirm it holds exactly the intended mapping;
+ * when it does not (an indented `---` inside a block scalar), the frontmatter is
+ * written out again instead, as it always used to be.
  */
 function stampProposalProvenance(content, proposal, gateDecision, ctx, nowIsoStr) {
     const parsed = parseFrontmatter(content);
@@ -917,9 +927,15 @@ function stampProposalProvenance(content, proposal, gateDecision, ctx, nowIsoStr
         fm.provenance = provenance;
     else
         delete fm.provenance;
-    return parsed.frontmatter !== null
-        ? `---\n${serializeFrontmatter(fm)}\n---\n${parsed.content}`
-        : assembleAsset(fm, parsed.content);
+    if (parsed.frontmatter === null)
+        return assembleAsset(fm, parsed.content);
+    const stamped = { generated: fm.generated, verified: fm.verified };
+    if (fm.provenance !== undefined)
+        stamped.provenance = fm.provenance;
+    const edited = replaceFrontmatterBlocks(content, ["generated", "verified", "provenance"], serializeFrontmatter(stamped).split("\n"));
+    if (edited !== null && isDeepStrictEqual(parseFrontmatter(edited).data, fm))
+        return edited;
+    return `---\n${serializeFrontmatter(fm)}\n---\n${parsed.content}`;
 }
 /**
  * Validate, stamp and write an accepted proposal into its bound target, then

package/dist/core/asset/akm-markdown.js

@@ -1,11 +1,12 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { isDeepStrictEqual } from "node:util";
 import { parse as parseYaml } from "yaml";
 import { localDateStamp } from "../common.js";
 import { UsageError } from "../errors.js";
 import { serializeFrontmatter } from "./asset-serialize.js";
-import { parseFrontmatterBlock, spliceFrontmatterLine } from "./frontmatter.js";
+import { parseFrontmatterBlock, replaceFrontmatterLine, spliceFrontmatterLine } from "./frontmatter.js";
 /**
  * Ensure an AKM-authored Markdown concept is also a conformant OKF concept.
  *
@@ -20,12 +21,18 @@ import { parseFrontmatterBlock, spliceFrontmatterLine } from "./frontmatter.js";
  * re-stamp on every write (which would churn timestamps and manufacture
  * needless diffs in git-backed bundles).
  *
- * Source preservation: when the type already matches and the ONLY change is
- * adding `updated`, the line is spliced into the original block textually —
- * round-tripping through the YAML serializer would drop user-authored
- * comments and normalize formatting just to contribute one field. Only a
- * document whose `type` must actually be corrected takes the re-serialize
- * path (as it always has).
+ * Source preservation: whenever the frontmatter block parses, it is edited as
+ * text and never round-tripped through the YAML serializer, which rewraps long
+ * values, reorders keys and drops comments — changes nobody made, shown to the
+ * reviewer of what may be a one-line correction. A missing `type` and a
+ * missing `updated` are each added as one line before the closing `---`, in
+ * that order; a wrong `type` is replaced on its own line. Every other byte —
+ * comments, wrapping, quoting, key order, line endings, the body — is kept as
+ * written. The edited text is parsed back to confirm it holds exactly the
+ * intended mapping; when it does not (a `type` value that spans several lines,
+ * a flow-style `{…}` block), the document is re-serialized instead, as it
+ * always used to be. A document with no frontmatter block gets a new one;
+ * malformed YAML throws.
  */
 export function ensureAkmMarkdownType(content, type, now = new Date()) {
     const block = parseFrontmatterBlock(content);
@@ -45,19 +52,36 @@ export function ensureAkmMarkdownType(content, type, now = new Date()) {
         throw new UsageError("AKM Markdown frontmatter must be a YAML mapping.", "INVALID_FLAG_VALUE");
     }
     const data = parsed;
+    const updated = localDateStamp(now);
     const needsUpdated = !("updated" in data);
-    if (data.type === type) {
-        if (!needsUpdated)
-            return content;
-        const spliced = spliceFrontmatterLine(content, `updated: ${localDateStamp(now)}`);
-        if (spliced !== null)
-            return spliced;
-        // Unreachable in practice (parseFrontmatterBlock succeeded above), but a
-        // re-serialized document beats a non-conformant one.
+    if (data.type === type && !needsUpdated)
+        return content;
+    let edited = content;
+    if (data.type !== type) {
+        edited =
+            "type" in data
+                ? replaceFrontmatterLine(edited, "type", `type: ${type}`)
+                : spliceFrontmatterLine(edited, `type: ${type}`);
     }
+    if (edited !== null && needsUpdated)
+        edited = spliceFrontmatterLine(edited, `updated: ${updated}`);
+    const intended = needsUpdated ? { ...data, type, updated } : { ...data, type };
+    if (edited !== null && parsesTo(edited, intended))
+        return edited;
+    // The text edit could not be done safely, but a re-serialized document
+    // beats a non-conformant one.
     const { type: _priorType, ...rest } = data;
     const next = { type, ...rest };
     if (needsUpdated)
-        next.updated = localDateStamp(now);
+        next.updated = updated;
     return `---\n${serializeFrontmatter(next)}\n---\n${block.content}`;
 }
+/** True when the frontmatter of `text` parses to exactly `intended`. */
+function parsesTo(text, intended) {
+    try {
+        return isDeepStrictEqual(parseYaml(parseFrontmatterBlock(text)?.frontmatter ?? ""), intended);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/core/asset/frontmatter.js

@@ -196,17 +196,77 @@ function countLines(text) {
  * frontmatter: round-tripping the mapping through the YAML serializer drops
  * comments and normalizes formatting, which is unacceptable for a write that
  * only needs to contribute one line. Shared by `ensureAkmMarkdownType`
- * (stamping `updated:` on write) and lint's `--fix` for `missing-updated`.
+ * (adding `type:` and `updated:` on write) and lint's `--fix` for
+ * `missing-updated`. The new line takes the block's own line ending.
  */
 export function spliceFrontmatterLine(raw, line) {
-    const lines = raw.split(/\r?\n/);
-    if (lines[0]?.trim() !== "---")
+    // Alternating [line, eol, line, eol, …, line]: joining the parts back
+    // reproduces `raw` byte for byte, CRLF and all.
+    const parts = raw.split(/(\r?\n)/);
+    if (parts[0]?.trim() !== "---")
         return null;
-    const closeIdx = lines.findIndex((l, i) => i > 0 && l.trim() === "---");
-    if (closeIdx === -1)
+    const closeAt = parts.findIndex((part, i) => i > 0 && part.trim() === "---");
+    if (closeAt === -1)
+        return null;
+    parts.splice(closeAt, 0, line, parts[1]);
+    return parts.join("");
+}
+/**
+ * Replace the top-level `key:` line of an existing frontmatter block with
+ * `line`, leaving every other byte untouched — the counterpart to
+ * {@link spliceFrontmatterLine} for correcting a field's value in place.
+ *
+ * Only that one physical line is replaced, so a value that continues onto
+ * further lines (a block sequence, a folded scalar) would be left dangling:
+ * the caller must check that the result still parses to what it meant. Returns
+ * null when `raw` has no well-formed block or no such line.
+ */
+export function replaceFrontmatterLine(raw, key, line) {
+    const parts = raw.split(/(\r?\n)/);
+    if (parts[0]?.trim() !== "---")
+        return null;
+    const closeAt = parts.findIndex((part, i) => i > 0 && part.trim() === "---");
+    if (closeAt === -1)
         return null;
-    lines.splice(closeIdx, 0, line);
-    return lines.join("\n");
+    const at = parts.findIndex((part, i) => i > 0 && i < closeAt && part.match(/^(\w[\w-]*):(?:[ \t]|$)/)?.[1] === key);
+    if (at === -1)
+        return null;
+    parts[at] = line;
+    return parts.join("");
+}
+/**
+ * Replace the top-level blocks of `keys` in an existing frontmatter block with
+ * `lines`, leaving every other byte untouched — the counterpart to
+ * {@link spliceFrontmatterLine} for a write that owns whole keys, such as the
+ * provenance stamp's `generated`, `verified` and `provenance`.
+ *
+ * A key's block is its `key:` line and the lines directly under it that
+ * continue it: indented lines and `- ` items. Every such block is removed
+ * wherever it sits, and `lines` are added just before the closing `---`, in the
+ * block's own line ending. A block with a blank line or a comment inside it is
+ * not removed whole, so the caller must check that the result still parses to
+ * what it meant. Returns null when `raw` has no well-formed block.
+ */
+export function replaceFrontmatterBlocks(raw, keys, lines) {
+    const parts = raw.split(/(\r?\n)/);
+    if (parts[0]?.trim() !== "---")
+        return null;
+    const closeAt = parts.findIndex((part, i) => i > 0 && part.trim() === "---");
+    if (closeAt === -1)
+        return null;
+    const kept = [];
+    for (let i = 2; i < closeAt; i += 2) {
+        const key = parts[i].match(/^(\w[\w-]*):(?:[ \t]|$)/)?.[1];
+        if (key === undefined || !keys.includes(key)) {
+            kept.push(parts[i], parts[i + 1]);
+            continue;
+        }
+        // One of the keys: drop its line and the lines that continue it.
+        while (i + 2 < closeAt && /^(?:[ \t]|-(?:[ \t]|$))/.test(parts[i + 2]))
+            i += 2;
+    }
+    const added = lines.flatMap((line) => [line, parts[1]]);
+    return [parts[0], parts[1], ...kept, ...added, ...parts.slice(closeAt)].join("");
 }
 /**
  * Strip one layer of matching quotes — frontmatter list items are often quoted

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

@@ -59,7 +59,7 @@ import { WorkflowConfigSchema } from "./schema/workflow.js";
 export { EmbeddingConnectionConfigSchema } from "./schema/embedding.js";
 export { EngineConfigSchema, EnginesSchema, LlmConnectionConfigSchema, LlmProfileConfigSchema } from "./schema/engines.js";
 export { ExperimentalConfigSchema } from "./schema/experimental.js";
-export { FEEDBACK_FAILURE_MODES, FeedbackConfigSchema } from "./schema/feedback.js";
+export { FeedbackConfigSchema } from "./schema/feedback.js";
 export { ImproveConfigSchema } from "./schema/improve.js";
 export { ConsolidateProcessConfigSchema, DistillProcessConfigSchema, ExtractProcessConfigSchema, ImproveProcessConfigSchema, ImproveProfileConfigSchema, MemoryInferenceProcessConfigSchema, ProactiveMaintenanceProcessConfigSchema, ReflectProcessConfigSchema, TriageProcessConfigSchema, ValidationProcessConfigSchema, } from "./schema/improve-processes.js";
 export { IndexConfigSchema, IndexPassConfigSchema } from "./schema/index-config.js";

package/dist/core/config/config.js

@@ -23,10 +23,6 @@ import { getConfigPath } from "../paths.js";
 import { warn, warnOnce } from "../warn.js";
 // Canonical harness-id source of truth (#565) — runtime value re-export.
 export { VALID_HARNESS_IDS } from "./config-types.js";
-// ── Feedback failure-mode constants (F-3 / #384) ────────────────────────────
-// Canonical taxonomy lives in the schema/validator layer; re-exported here so
-// existing `../core/config/config` import sites keep working.
-export { FEEDBACK_FAILURE_MODES } from "./config-schema.js";
 // ── Defaults ────────────────────────────────────────────────────────────────
 export const DEFAULT_CONFIG = {
     configVersion: "0.9.0",

package/dist/core/config/schema/feedback.js

@@ -2,30 +2,13 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
- * Feedback taxonomy + `feedback` config section. Extracted verbatim from the
- * former `config-schema.ts` monolith — no behavior change.
+ * `feedback` config section. The retired `allowedFailureModes` key (it went
+ * with `akm feedback --failure-mode`) is tolerated as an unknown key.
  */
 import { z } from "zod";
-import { nonEmptyString } from "./primitives.js";
-// ── Feedback failure modes (F-3 / #384) ─────────────────────────────────────
-/**
- * Curated taxonomy of failure modes for negative feedback.
- *
- * Structured failure modes enable aggregation across feedback events so the
- * distill pipeline can detect that "5 assets failed for the same reason" and
- * act on it — free-text strings about the same issue are not aggregatable.
- */
-export const FEEDBACK_FAILURE_MODES = [
-    "incorrect", // Factually wrong or logically flawed content
-    "outdated", // Correct at some point but now stale
-    "dangerous", // Could cause harm if followed (security, safety)
-    "incomplete", // Missing key steps, context, or caveats
-    "redundant", // Duplicates another asset without adding value
-];
 // ── Feedback ────────────────────────────────────────────────────────────────
 export const FeedbackConfigSchema = z
     .object({
     requireReason: z.boolean().optional(),
-    allowedFailureModes: z.array(nonEmptyString).optional(),
 })
     .passthrough();

package/dist/scripts/akm-migrate-node.js

@@ -35845,8 +35845,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

package/dist/scripts/akm-migrate.js

@@ -35173,8 +35173,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

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
@@ -3081,9 +3098,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

@@ -467,7 +467,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 +749,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.26",
   "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