akm-cli 0.9.26-alpha.1 → 0.9.26

package/dist/commands/feedback-cli.js

@@ -2,13 +2,17 @@
 // 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 fs from "node:fs";
+import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { parse as yamlParse, stringify as yamlStringify } from "yaml";
 import { defineJsonCommand, output, parseAllFlagValues } from "../cli/shared.js";
+import { assetPathForName, stashDirFor } from "../core/asset/asset-placement.js";
 import { makeBundleRef, parseBundleRef } from "../core/asset/asset-ref.js";
-import { assembleAsset } from "../core/asset/asset-serialize.js";
-import { parseFrontmatter, parseFrontmatterBlock } from "../core/asset/frontmatter.js";
-import { conceptIdFromTypeName, parseRefInput } from "../core/asset/resolve-ref.js";
-import { isWithin, writeFileAtomic } from "../core/common.js";
-import { FEEDBACK_FAILURE_MODES, loadConfig } from "../core/config/config.js";
+import { assembleAsset, serializeFrontmatter } from "../core/asset/asset-serialize.js";
+import { parseFrontmatter, parseFrontmatterBlock, spliceFrontmatterLine } from "../core/asset/frontmatter.js";
+import { conceptIdFromTypeName, parseRefInput, typeNameFromConceptId } from "../core/asset/resolve-ref.js";
+import { isWithin, resolveStashDir, safeRealpath, writeFileAtomic } from "../core/common.js";
+import { loadConfig } from "../core/config/config.js";
 import { NotFoundError, UsageError } from "../core/errors.js";
 import { appendEvent } from "../core/events.js";
 import { resolveMutationTarget } from "../core/mutation-target.js";
@@ -23,6 +27,9 @@ import { resolveSourcesForOrigin } from "../registry/origin-resolve.js";
 import { closeDatabase, openExistingDatabase } from "../storage/repositories/index-connection.js";
 import { findEntryIdByRef, getEntryFilePathById, getItemRefById, } from "../storage/repositories/index-entries-repository.js";
 import { applyFeedbackToUtilityScore } from "../storage/repositories/index-utility-repository.js";
+import { contentHash } from "./improve/content-hash.js";
+import { readEdgeList } from "./improve/memory/memory-belief.js";
+import { createProposal } from "./proposal/repository.js";
 // ── Tag validation ────────────────────────────────────────────────────────────
 const TAG_KEY_RE = /^[a-z_][a-z0-9_]*$/;
 function validateFeedbackTags(raw) {
@@ -185,15 +192,235 @@ function recordFeedbackUsage(indexDb, entryId, durableEntryRef, signal, metadata
     });
     return { utilityResult, rankingUpdateApplied, rankingUpdateSkippedReason };
 }
+// ── Judged text ──────────────────────────────────────────────────────────────
+/**
+ * The body hash of the text a piece of feedback judges: the asset's file as it
+ * stands when the feedback is given. `undefined` when the file cannot be read.
+ * Reflect compares it with the asset's current body to tell feedback given on
+ * an earlier version of the text. An env or secret file is never read.
+ */
+function judgedTextHash(itemRef, filePath) {
+    try {
+        const type = typeNameFromConceptId(parseBundleRef(itemRef).conceptId)?.type;
+        if (!filePath || type === "env" || type === "secret")
+            return undefined;
+        return contentHash(fs.readFileSync(filePath, "utf8"), "body");
+    }
+    catch {
+        return undefined;
+    }
+}
+// ── Exact fixes ──────────────────────────────────────────────────────────────
+/** 1-based numbers of the lines on which `needle` starts. */
+function startLines(text, needle) {
+    const lines = [];
+    for (let at = text.indexOf(needle); at !== -1; at = text.indexOf(needle, at + 1)) {
+        lines.push(text.slice(0, at).split("\n").length);
+    }
+    return lines;
+}
+/**
+ * Apply `--replace`/`--with` pairs in order. Each `--replace` text must appear
+ * exactly once in the text as it stands at that point, so the edit can only
+ * land where the caller meant it.
+ */
+export function applyExactReplacements(text, pairs, file) {
+    let out = text;
+    pairs.forEach((pair, i) => {
+        const label = `--replace #${i + 1}`;
+        if (!pair.old)
+            throw new UsageError(`${label} is empty.`, "INVALID_FLAG_VALUE");
+        const lines = startLines(out, pair.old);
+        if (lines.length === 0) {
+            throw new UsageError(`${label} was not found in ${file}.`, "INVALID_FLAG_VALUE", "Copy the text verbatim from the file, including whitespace and punctuation.");
+        }
+        if (lines.length > 1) {
+            throw new UsageError(`${label} appears ${lines.length} times in ${file} (lines ${lines.join(", ")}).`, "INVALID_FLAG_VALUE", "Include more of the surrounding text so it appears once.");
+        }
+        const at = out.indexOf(pair.old);
+        out = out.slice(0, at) + pair.new + out.slice(at + pair.old.length);
+    });
+    return out;
+}
+/** A fix may change the frontmatter's values, but it must still parse as YAML. */
+function assertFrontmatterStillParses(before, after, file) {
+    if (!parseFrontmatterBlock(before))
+        return;
+    const block = parseFrontmatterBlock(after);
+    let problem;
+    if (!block) {
+        problem = "the frontmatter block is gone";
+    }
+    else if (block.frontmatter.trim()) {
+        try {
+            const data = yamlParse(block.frontmatter);
+            if (typeof data !== "object" || data === null || Array.isArray(data))
+                problem = "it is no longer a mapping";
+        }
+        catch (err) {
+            problem = (err instanceof Error ? err.message : String(err)).split("\n")[0];
+        }
+    }
+    if (problem) {
+        throw new UsageError(`The fix breaks the frontmatter of ${file}: ${problem}.`, "INVALID_FLAG_VALUE", 'Quote a value that contains ": ", or leave the frontmatter alone.');
+    }
+}
+/**
+ * Refuse a fix that a proposal could not apply to the asset's file. A proposal
+ * writes the file `createProposal` computes from the ref's type and name under
+ * the bundle's root. For an asset indexed anywhere else (a git bundle's
+ * `tasks/README.md` is `knowledge/tasks/README`) nothing is there: accepting
+ * the proposal would create a second file and leave the real one unfixed.
+ */
+export function assertProposalWritesFile(itemRef, root, filePath) {
+    const { type, name } = parseRefInput(itemRef);
+    const typeDir = stashDirFor(type);
+    const writes = typeDir === undefined ? undefined : assetPathForName(type, path.join(path.resolve(root), typeDir), name);
+    if (writes !== undefined && safeRealpath(writes) === safeRealpath(filePath))
+        return;
+    throw new UsageError(`akm cannot queue a fix for ${itemRef}: its file is ${filePath}, but a proposal would write ${writes ?? `no file (akm has no directory for "${type}" assets)`}. Edit the file directly.`, "INVALID_PROPOSAL");
+}
+/**
+ * The durable ref of the asset `--superseded-by` names. It must be indexed and
+ * must not be the asset itself, or nothing is recorded.
+ */
+function resolveSuccessorRef(db, input, itemRef) {
+    const parsed = parseBundleRef(input);
+    const id = findEntryIdByRef(db, makeBundleRef(parsed.bundle, parsed.conceptId), parsed.bundle);
+    const successor = id === undefined ? null : getItemRefById(db, id);
+    if (!successor) {
+        throw new UsageError(`--superseded-by ${input} is not in the index.`, "INVALID_FLAG_VALUE", "Run 'akm search' to find the asset that replaces it, then 'akm index' if it was recently added.");
+    }
+    if (successor === itemRef) {
+        throw new UsageError(`--superseded-by ${input} is the asset itself.`, "INVALID_FLAG_VALUE");
+    }
+    return successor;
+}
+/** The frontmatter of `text` as a YAML mapping: `{}` when it has none (or only comments), `undefined` when it is not valid YAML or not a mapping. */
+function frontmatterMapping(text) {
+    const block = parseFrontmatterBlock(text);
+    if (!block?.frontmatter.trim())
+        return {};
+    try {
+        const data = (yamlParse(block.frontmatter) ?? {});
+        return typeof data === "object" && data !== null && !Array.isArray(data)
+            ? data
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * What `mark` sets on frontmatter `data`, `{}` when it already says so. The rules
+ * of `writeSupersededEdge`: a ref already listed is not added again,
+ * `contradicted` and `archived` stay, and a scalar `supersededBy` joins the list.
+ * `--outdated` also leaves `superseded`, which says more than `deprecated`.
+ */
+function historyMarkChanges(data, mark) {
+    const state = data.beliefState;
+    if ("outdated" in mark) {
+        return state === "deprecated" || state === "superseded" || state === "contradicted" || state === "archived"
+            ? {}
+            : { beliefState: "deprecated" };
+    }
+    const existing = readEdgeList(data.supersededBy);
+    return {
+        ...(state === "superseded" || state === "contradicted" || state === "archived"
+            ? {}
+            : { beliefState: "superseded" }),
+        ...(existing.includes(mark.supersededBy) ? {} : { supersededBy: [...existing, mark.supersededBy] }),
+    };
+}
+/** Index of the top-level `key:` line inside the frontmatter block of `lines`, or -1. */
+function topLevelKeyLine(lines, key) {
+    const close = lines.findIndex((line, i) => i > 0 && line.trim() === "---");
+    if (lines[0]?.trim() !== "---" || close === -1)
+        return -1;
+    return lines.findIndex((line, i) => i > 0 && i < close && line.startsWith(`${key}:`));
+}
+/** Put a one-line `beliefState` in the frontmatter of `text`: in place of its line, or just before the closing fence. */
+function setBeliefState(text, state) {
+    const lines = text.split("\n");
+    const at = topLevelKeyLine(lines, "beliefState");
+    if (at === -1)
+        return spliceFrontmatterLine(text, `beliefState: ${state}`) ?? text;
+    lines[at] = `beliefState: ${state}`;
+    return lines.join("\n");
+}
+/** Put the `supersededBy` list `list`, whose last item is `ref`, in the frontmatter of `text`. */
+function setSupersededBy(text, list, ref) {
+    const item = (value) => `- ${yamlStringify(value, { lineWidth: 0 }).trimEnd()}`;
+    const whole = ["supersededBy:", ...list.map((value) => `  ${item(value)}`)];
+    const lines = text.split("\n");
+    const at = topLevelKeyLine(lines, "supersededBy");
+    if (at === -1)
+        return whole.reduce((out, line) => spliceFrontmatterLine(out, line) ?? out, text);
+    // The item lines of a block list, which may have blank lines and comments between them.
+    const items = [];
+    for (let i = at + 1; i < lines.length && /^\s*(-(\s|$)|#|$)/.test(lines[i]); i++) {
+        if (/^\s*-(\s|$)/.test(lines[i]))
+            items.push(i);
+    }
+    if (items.length > 0 && /^supersededBy:\s*(#.*)?$/.test(lines[at])) {
+        // A block list: the new item follows the last one, indented like the first.
+        const indent = /^\s*/.exec(lines[items[0]])?.[0] ?? "";
+        lines.splice(items[items.length - 1] + 1, 0, `${indent}${item(ref)}`);
+    }
+    else {
+        // A flow list, a scalar or no value: this one key is written out as a block list.
+        lines.splice(at, 1, ...whole);
+    }
+    return lines.join("\n");
+}
+/**
+ * Mark an asset's history in the frontmatter of its text, as a proposal's content:
+ * `{ supersededBy }` sets `beliefState: superseded` and adds the ref to the
+ * `supersededBy` list, `{ outdated }` sets `beliefState: deprecated`. Only those
+ * two keys change, by line edits that keep every other byte (comments, quoting,
+ * key order, line endings, the body). When a line edit does not give exactly the
+ * intended frontmatter (an unusual spelling of a key), the frontmatter is
+ * written out again instead. Returns `raw` when it already says what the mark sets.
+ */
+export function applyHistoryMark(raw, mark, file) {
+    const crlf = raw.includes("\r\n");
+    const text = crlf ? raw.replace(/\r\n/g, "\n") : raw;
+    const data = frontmatterMapping(text);
+    if (!data) {
+        throw new UsageError(`The frontmatter of ${file} is not a valid YAML mapping, so akm cannot mark it.`, "INVALID_FLAG_VALUE", "Fix the frontmatter first.");
+    }
+    const changes = historyMarkChanges(data, mark);
+    if (Object.keys(changes).length === 0)
+        return raw;
+    let out = text;
+    if (changes.beliefState !== undefined)
+        out = setBeliefState(out, changes.beliefState);
+    if (changes.supersededBy !== undefined && "supersededBy" in mark) {
+        out = setSupersededBy(out, changes.supersededBy, mark.supersededBy);
+    }
+    const intended = { ...data, ...changes };
+    if (!isDeepStrictEqual(frontmatterMapping(out), intended)) {
+        const block = parseFrontmatterBlock(text);
+        out = `---\n${serializeFrontmatter(intended)}\n---\n${block ? block.content : text}`;
+    }
+    return crlf ? out.replace(/\n/g, "\r\n") : out;
+}
 // ── Command definition ────────────────────────────────────────────────────────
 export const feedbackCommand = defineJsonCommand({
     meta: {
         name: "feedback",
         description: "Record positive or negative feedback for any indexed bundle asset.\n\n" +
             '`akm feedback <ref> --negative --reason "<what is wrong and what should change>"` flags\n' +
-            "the asset for review: the next improve run proposes a fix based on your reason, so be\n" +
-            "specific. `--positive` records that an asset helped (it raises its ranking) and does not\n" +
-            "trigger a rewrite.\n\n" +
+            "the asset: the next improve run may repair its description, title or when_to_use from\n" +
+            "your reason, but it does not rewrite the text. To correct a wrong fact in the text, attach\n" +
+            'the exact fix: --replace "<exact current text>" --with "<corrected text>" --source "<URL,\n' +
+            'command or file that shows it>" (repeat --replace/--with for several edits; use --with=...\n' +
+            "for a value that starts with -). akm checks that each --replace text appears exactly once\n" +
+            "and queues the edit as a proposal for review. To mark the asset's history instead, add\n" +
+            "--superseded-by <ref> (the asset that replaces it) or --outdated (it describes a past\n" +
+            "state and nothing replaces it), with --reason and --source: the same proposal sets its\n" +
+            "beliefState and, for --superseded-by, adds the ref to supersededBy. `--positive` records\n" +
+            "that an asset helped (it raises its ranking) and does not trigger a rewrite.\n\n" +
             "Both signals adjust the asset's usefulness score right away, in the same\n" +
             "process: positive feedback raises it, negative lowers it, and recent\n" +
             "feedback counts for more than old feedback. No reindex is needed — the new\n" +
@@ -211,18 +438,33 @@ export const feedbackCommand = defineJsonCommand({
         },
         negative: {
             type: "boolean",
-            description: "Flag the asset for review: the next improve run proposes a fix from --reason (also lowers its ranking immediately, no reindex needed).",
+            description: "Flag the asset: lowers its ranking immediately (no reindex needed), and the next improve run may repair its frontmatter from --reason. Attach --replace/--with/--source to correct its text, or --superseded-by/--outdated to mark its history.",
             default: false,
         },
         reason: {
             type: "string",
-            description: "What is wrong with the asset's content and what should change; the next improve run proposes a fix from it, so be specific (required for negative feedback by default). Not for akm command errors.",
+            description: "What is wrong with the asset's content and what should change, specifically (required for negative feedback by default). Not for akm command errors.",
         },
-        "failure-mode": {
+        replace: {
             type: "string",
-            description: "Structured failure-mode taxonomy for negative feedback. " +
-                `Accepted values: ${FEEDBACK_FAILURE_MODES.join(", ")}. ` +
-                "Stored alongside --reason in event metadata for aggregation by the distill pipeline.",
+            description: "Exact text to correct, copied verbatim from the asset file; it must appear exactly once (repeatable, each paired with a --with in order). Negative feedback only.",
+        },
+        with: {
+            type: "string",
+            description: "Corrected text for the matching --replace (repeatable, in the same order).",
+        },
+        source: {
+            type: "string",
+            description: "Where the correct fact comes from: a URL, command or file. Required with --replace, --superseded-by and --outdated.",
+        },
+        "superseded-by": {
+            type: "string",
+            description: "Ref of the asset that replaces this one. The fix sets beliefState: superseded and adds the ref to supersededBy (contradicted and archived stay). The ref must be indexed and not this asset. Negative feedback on a markdown asset only; may be combined with --replace/--with.",
+        },
+        outdated: {
+            type: "boolean",
+            description: "The asset describes a past state and no single asset replaces it. The fix sets beliefState: deprecated (superseded, contradicted and archived stay). Negative feedback on a markdown asset only; may be combined with --replace/--with, not with --superseded-by.",
+            default: false,
         },
         tag: {
             type: "string",
@@ -250,16 +492,36 @@ export const feedbackCommand = defineJsonCommand({
         }
         const signal = args.positive ? "positive" : "negative";
         const reason = args.reason;
-        // F-3 / #384: Validate --failure-mode against the curated enum.
-        const failureMode = args["failure-mode"]?.trim() || undefined;
-        if (failureMode) {
-            if (args.positive) {
-                throw new UsageError("--failure-mode is only valid for negative feedback.", "INVALID_FLAG_VALUE", "Remove --failure-mode or switch to --negative.");
+        // A fix: an exact edit of the asset's text (each --replace pairs with a --with, in order),
+        // a mark of its history (--superseded-by or --outdated), or both.
+        const replaces = parseAllFlagValues("--replace");
+        const withs = parseAllFlagValues("--with");
+        const fixSource = args.source?.trim() || undefined;
+        const fixPairs = replaces.map((old, i) => ({ old, new: withs[i] ?? "" }));
+        const supersededBy = args["superseded-by"];
+        const outdated = args.outdated === true;
+        const hasMark = supersededBy !== undefined || outdated;
+        if (replaces.length > 0 || withs.length > 0 || fixSource !== undefined || hasMark) {
+            if (!args.negative) {
+                throw new UsageError("--replace, --with, --source, --superseded-by and --outdated are only for negative feedback.", "INVALID_FLAG_VALUE");
             }
-            const cfg = loadConfig();
-            const allowedModes = cfg.feedback?.allowedFailureModes ?? FEEDBACK_FAILURE_MODES;
-            if (allowedModes.length > 0 && !allowedModes.includes(failureMode)) {
-                throw new UsageError(`Invalid --failure-mode "${failureMode}". Accepted values: ${allowedModes.join(", ")}.`, "INVALID_FLAG_VALUE", `Use one of: ${allowedModes.join(", ")}`);
+            if (supersededBy !== undefined && outdated) {
+                throw new UsageError("--superseded-by names the asset that replaces this one and --outdated says none does; use one.", "INVALID_FLAG_VALUE");
+            }
+            if (parseAllFlagValues("--superseded-by").length > 1) {
+                throw new UsageError("--superseded-by takes one ref.", "INVALID_FLAG_VALUE");
+            }
+            if (supersededBy !== undefined && !supersededBy.trim()) {
+                throw new UsageError("--superseded-by needs the ref of the asset that replaces this one.", "MISSING_REQUIRED_ARGUMENT");
+            }
+            if (replaces.length !== withs.length || (replaces.length === 0 && !hasMark)) {
+                throw new UsageError(`Each --replace needs one --with (got ${replaces.length} --replace and ${withs.length} --with).`, "INVALID_FLAG_VALUE");
+            }
+            if (!fixSource) {
+                throw new UsageError("A fix needs --source: the URL, command or file that shows the correct fact.", "MISSING_REQUIRED_ARGUMENT");
+            }
+            if (!reason?.trim()) {
+                throw new UsageError("A fix needs --reason: say what is wrong.", "MISSING_REQUIRED_ARGUMENT");
             }
         }
         if (args.negative === true && !reason?.trim()) {
@@ -268,12 +530,11 @@ export const feedbackCommand = defineJsonCommand({
             const cfg = loadConfig();
             const requireReason = cfg.feedback?.requireReason ?? true; // Default: true (F-3 / #384)
             if (requireReason) {
-                throw new UsageError("Negative feedback requires --reason: the next improve run proposes a fix from it, so say what is wrong and what should change. " +
-                    "Use --failure-mode for a curated taxonomy or --reason for free text. " +
-                    "Set feedback.requireReason: false in akm.json to downgrade to a warning.", "MISSING_REQUIRED_ARGUMENT", `Hint: akm feedback ${ref} --negative --reason "<what is wrong and what should change>" [--failure-mode incorrect|outdated|dangerous|incomplete|redundant]`);
+                throw new UsageError("Negative feedback requires --reason: say what is wrong and what should change. " +
+                    "Set feedback.requireReason: false in akm.json to downgrade to a warning.", "MISSING_REQUIRED_ARGUMENT", `Hint: akm feedback ${ref} --negative --reason "<what is wrong and what should change>"`);
             }
             else {
-                warn("Warning: negative feedback without --reason gives the next improve run nothing to base a fix on.");
+                warn("Warning: negative feedback without --reason says nothing about what is wrong.");
             }
         }
         const rawTags = parseAllFlagValues("--tag");
@@ -281,10 +542,8 @@ export const feedbackCommand = defineJsonCommand({
         const metadataObj = {
             signal,
             ...(reason?.trim() ? { reason: reason.trim() } : {}),
-            ...(failureMode ? { failureMode } : {}),
             ...(validatedTags.length > 0 ? { tags: validatedTags } : {}),
         };
-        const metadataStr = Object.keys(metadataObj).length > 1 ? JSON.stringify(metadataObj) : undefined;
         // Feedback only needs the index to exist, not to be current. A stale index
         // is fine — the ref lookup works against any populated DB. We do NOT call
         // ensureIndex here: it either blocks (3+ min inline reindex) or spawns a
@@ -309,6 +568,7 @@ export const feedbackCommand = defineJsonCommand({
         let rankingUpdateApplied = false;
         let rankingUpdateSkippedReason;
         let durableRef = ref;
+        let fix;
         const db = openExistingDatabase();
         try {
             const config = loadConfig();
@@ -338,6 +598,51 @@ export const feedbackCommand = defineJsonCommand({
             if (!itemRef)
                 throw new UsageError(`Indexed ref "${ref}" has no durable item ref.`, "INVALID_PROPOSAL");
             durableRef = itemRef;
+            const filePath = getEntryFilePathById(db, entryId);
+            const textHash = judgedTextHash(itemRef, filePath);
+            if (textHash)
+                metadataObj.contentHash = textHash;
+            if (fixPairs.length > 0 || hasMark) {
+                // Checked before anything is recorded, so a fix that does not apply leaves no trace.
+                if (!filePath || !fs.existsSync(filePath)) {
+                    throw new NotFoundError(`The file for ${itemRef} is missing on disk.`, "ASSET_NOT_FOUND");
+                }
+                const assetRef = parseRefInput(itemRef);
+                const resolved = resolveMutationTarget(config, assetRef, undefined, { requireWritable: true });
+                if (!isWithin(filePath, resolved.target.source.path)) {
+                    throw new UsageError(`${itemRef} is outside bundle "${resolved.target.source.name}".`);
+                }
+                assertProposalWritesFile(itemRef, resolved.target.source.path, filePath);
+                let mark;
+                if (hasMark) {
+                    if (assetRef.type === "env" || assetRef.type === "secret" || !filePath.toLowerCase().endsWith(".md")) {
+                        throw new UsageError(`--superseded-by and --outdated mark the frontmatter of a markdown asset, and ${itemRef} is not one.`, "INVALID_FLAG_VALUE");
+                    }
+                    mark =
+                        supersededBy !== undefined
+                            ? { supersededBy: resolveSuccessorRef(db, supersededBy.trim(), itemRef) }
+                            : { outdated: true };
+                }
+                const before = fs.readFileSync(filePath, "utf8");
+                let after = applyExactReplacements(before, fixPairs, filePath);
+                if (mark)
+                    after = applyHistoryMark(after, mark, filePath);
+                if (after === before)
+                    throw new UsageError("The fix changes nothing.", "INVALID_FLAG_VALUE");
+                assertFrontmatterStillParses(before, after, filePath);
+                // What the proposal leaves the asset saying, for the output and the event.
+                const marked = mark && {
+                    beliefState: String(parseFrontmatter(after).data.beliefState),
+                    ...("supersededBy" in mark ? { supersededBy: mark.supersededBy } : {}),
+                };
+                fix = {
+                    content: after,
+                    target: { source: resolved.target.source.name, root: resolved.target.source.path },
+                    ...(marked ? { marked } : {}),
+                };
+                metadataObj.fix = { source: fixSource, replacements: fixPairs.length, ...marked };
+            }
+            const metadataStr = Object.keys(metadataObj).length > 1 ? JSON.stringify(metadataObj) : undefined;
             const recordResult = recordFeedbackUsage(db, entryId, itemRef, signal, metadataStr);
             utilityResult = recordResult.utilityResult;
             rankingUpdateApplied = recordResult.rankingUpdateApplied;
@@ -351,6 +656,16 @@ export const feedbackCommand = defineJsonCommand({
             ref: durableRef,
             metadata: metadataObj,
         });
+        const fixProposal = fix && reason?.trim() && fixSource
+            ? createProposal(resolveStashDir(), {
+                ref: durableRef,
+                itemRef: durableRef,
+                target: fix.target,
+                source: "feedback",
+                payload: { content: fix.content },
+                feedback: { reason: reason.trim(), source: fixSource },
+            })
+            : undefined;
         // F-5 / #386: When a high-utility asset crosses below the review threshold,
         // auto-create a review-needed escalation proposal so a human can confirm
         // whether the negative feedback is valid before the asset falls out of
@@ -368,7 +683,6 @@ export const feedbackCommand = defineJsonCommand({
                         previousUtility: utilityResult.previousUtility,
                         nextUtility: utilityResult.nextUtility,
                         reason: reason?.trim() ?? null,
-                        failureMode: failureMode ?? null,
                     },
                 });
             }
@@ -414,11 +728,20 @@ export const feedbackCommand = defineJsonCommand({
             ref,
             signal,
             reason: reason?.trim() ?? null,
-            failureMode: failureMode ?? null,
             tags: validatedTags,
             rankingUpdate: rankingUpdateApplied
                 ? { applied: true }
                 : { applied: false, reason: rankingUpdateSkippedReason ?? "unknown" },
+            ...(fixProposal
+                ? {
+                    fix: {
+                        proposalId: fixProposal.id,
+                        replacements: fixPairs.length,
+                        source: fixSource,
+                        ...fix?.marked,
+                    },
+                }
+                : {}),
             ...(appliedToResult
                 ? { appliedTo: { ref: appliedToResult.lessonRef, lessonStrength: appliedToResult.strength } }
                 : {}),

package/dist/commands/improve/distill.js

@@ -13,8 +13,10 @@
  * unscoped input stays flat.
  */
 import fs from "node:fs";
+import path from "node:path";
 import distillKnowledgeSystemPrompt from "../../assets/prompts/distill-knowledge-system.md" with { type: "text" };
 import distillLessonSystemPrompt from "../../assets/prompts/distill-lesson-system.md" with { type: "text" };
+import { assetPathForName, stashDirFor } from "../../core/asset/asset-placement.js";
 import { assembleAsset, assembleAssetFromString, serializeFrontmatterQuoted } from "../../core/asset/asset-serialize.js";
 import { parseFrontmatter, writeSalienceToFrontmatter } from "../../core/asset/frontmatter.js";
 import { stripMarkdownFences } from "../../core/asset/markdown.js";
@@ -253,6 +255,31 @@ const DISABLED_MESSAGE = "distill is disabled in config; enable processes.distil
 function emitDistill(run, meta) {
     appendEvent({ eventType: "distill_invoked", ref: run.ledgerRef, metadata: { ...meta, ...run.eligMeta } }, run.options.eventsCtx);
 }
+/**
+ * End a distill with no proposal and no failure: reported as `skipped`, which the improve loop
+ * leaves in the ledger as unchanged, as it does a reflect that changed nothing.
+ */
+function skipDistill(run, proposalRef, kind, skipReason, message) {
+    emitDistill(run, {
+        outcome: "skipped",
+        proposalRef,
+        proposalKind: kind,
+        skipReason,
+        message,
+        ...exclusionMeta(run, false),
+    });
+    return {
+        schemaVersion: 1,
+        ok: true,
+        outcome: "skipped",
+        inputRef: run.inputRef,
+        proposalRef,
+        proposalKind: kind,
+        skipReason,
+        message,
+        ...exclusionMeta(run, true),
+    };
+}
 /** The exclusion diagnostics for an event (count only) or a result (count + fully-filtered). */
 function exclusionMeta(run, forResult) {
     if (!run.exclusion)
@@ -332,6 +359,11 @@ async function distill(run, targetKind, kind, outputRef, feedbackEvents) {
         stampInputSalience(run);
         return promoted;
     }
+    // A lesson already at the target ref is left as it is: the proposal would overwrite it, and all 5 recorded
+    // overwrites were rejected. Checked before the call, which it would waste.
+    if (kind === "lesson" && lessonExists(run, outputRef)) {
+        return skipDistill(run, outputRef, kind, "lesson_exists", `${outputRef} already exists; distill does not overwrite a lesson.`);
+    }
     const feedback = feedbackEvents.slice(-20).map((event) => ({
         ts: event.ts,
         eventType: event.eventType,
@@ -388,6 +420,19 @@ async function distill(run, targetKind, kind, outputRef, feedbackEvents) {
         descriptionSwapped: assembled.descriptionSwapped,
     });
 }
+/** Whether a file already holds the lesson `ref` in the stash the proposal would be filed in. */
+function lessonExists(run, ref) {
+    const { type, name } = parseRefInput(ref);
+    const typeDir = stashDirFor(type);
+    if (!typeDir)
+        return false;
+    try {
+        return fs.statSync(assetPathForName(type, path.join(run.stash, typeDir), name)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
 /** Turn the response into validated content: structured JSON or markdown, then lesson repairs and lint. */
 function assembleDistilledContent(run, raw, kind, outputRef) {
     const structured = parseEmbeddedJsonResponse(raw);
@@ -432,7 +477,7 @@ function qualityGateEnabled(run) {
     return run.profile.processes?.distill?.qualityGate?.enabled ?? true;
 }
 /**
- * Judge the distilled content, then queue it. A rejected, uncertain or
+ * Judge the distilled content, then queue it for review. A rejected, uncertain or
  * source-contradicting result is recorded instead (see {@link writeQualityRejection}).
  */
 async function judgeAndQueue(run, out) {
@@ -495,7 +540,21 @@ async function judgeAndQueue(run, out) {
         ...(run.options.eligibilitySource ? { eligibilitySource: run.options.eligibilitySource } : {}),
         // The ledger keys the attempt by the input, not the output.
         attemptedRefs: [run.ledgerRef],
-    }, { judged });
+    }, 
+    // A pass goes to a person, never to the triage drain or its judgment tier. Staged precision was 2 of 12 on
+    // 2026-10-05: ten of the staged lessons restated their memory, claimed what it does not say, or filed a dated
+    // status as a lesson, and no judge score separated them from the two good ones. The judge's evidence stays on
+    // the decision for the reviewer. With the gate off nothing was judged, and the drain decides as before.
+    judged
+        ? {
+            review: {
+                reason: "distill-review",
+                gate: "quality-gate",
+                ...(judged.criteria ? { scores: judged.criteria } : {}),
+                judgeReason: judged.reason,
+            },
+        }
+        : {});
     persistOutputEncodingSalience(run, out.ref, content);
     const swapped = out.descriptionSwapped ? { descriptionSwapped: out.descriptionSwapped } : {};
     emitDistill(run, {

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 { pushRecentError } from "./preparation.js";
+import { hasOnlyBarePositiveFeedback, isFlaggedSinceLastEdit, pushRecentError } from "./preparation.js";
 import { recordNoOp, resetConsecutiveNoOps } from "./salience.js";
 import { attributeStage, errMessage } from "./stage.js";
 export function prepareImproveLoopEnv(args) {
@@ -196,6 +196,8 @@ async function runLoopReflectPass(planned, env, tally) {
     }, env.eventsCtx);
     recordPlasticity(env, planned, reason === "no_change" ? "noop" : result.ok ? "changed" : undefined);
 }
+const FLAGGED_WRONG_REASON = "flagged wrong since its last edit";
+const BARE_POSITIVE_REASON = "only positive feedback, without a reason";
 async function runLoopDistillPass(planned, refType, isDistillOnly, env, tally) {
     const { options, primaryStashDir, improveProfile, resolvedPlan } = env;
     const distillSkip = shouldSkipRef(planned.ref, "distill", improveProfile);
@@ -217,6 +219,19 @@ async function runLoopDistillPass(planned, refType, isDistillOnly, env, tally) {
         return;
     if (env.distillCooledRefs.has(planned.ref) && !explicitRefScope)
         return;
+    // A memory flagged wrong and not edited since is no source for a lesson. The attempt goes in the
+    // ledger so the ref waits for newer feedback; an explicit `--scope` ref still runs.
+    if (!explicitRefScope && isFlaggedSinceLastEdit(planned, env.eventsCtx)) {
+        recordLoopAttempt(planned, env, "distill", "unchanged", FLAGGED_WRONG_REASON);
+        return recordSkip(tally, planned.ref, FLAGGED_WRONG_REASON, { env, reason: "distill_flagged_wrong" });
+    }
+    // A memory whose only recent feedback is a positive with no reason or note gives the writer nothing to distil:
+    // 10 of the 11 lessons made from one were rejected. The ledger holds it until newer feedback; an explicit `--scope`
+    // ref still runs.
+    if (!explicitRefScope && hasOnlyBarePositiveFeedback(planned, env.eventsCtx)) {
+        recordLoopAttempt(planned, env, "distill", "unchanged", BARE_POSITIVE_REASON);
+        return recordSkip(tally, planned.ref, BARE_POSITIVE_REASON, { env, reason: "distill_positive_without_reason" });
+    }
     const result = await attributeStage(resolvedPlan, "distill", () => env.distillFn({
         ref: planned.ref,
         ...(planned.itemRef ? { itemRef: planned.itemRef } : {}),

package/dist/commands/improve/memory/memory-belief.js

@@ -17,7 +17,7 @@ import { mutateFrontmatter } from "../../../core/asset/frontmatter.js";
  * An edge value as a list. A scalar string is live data (the indexer accepts
  * it), so it is promoted rather than dropped on the next write.
  */
-function readEdgeList(value) {
+export function readEdgeList(value) {
     if (Array.isArray(value))
         return value.filter((v) => typeof v === "string" && v.trim().length > 0);
     if (typeof value === "string" && value.trim())