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

package/dist/commands/feedback-cli.js

@@ -2,14 +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 { parse as yamlParse } from "yaml";
+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, resolveStashDir, 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";
@@ -24,6 +27,8 @@ 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_]*$/;
@@ -187,6 +192,24 @@ 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) {
@@ -242,6 +265,146 @@ function assertFrontmatterStillParses(before, after, file) {
         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: {
@@ -253,8 +416,11 @@ export const feedbackCommand = defineJsonCommand({
             '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. `--positive` records that an asset helped\n" +
-            "(it raises its ranking) and does not trigger a rewrite.\n\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" +
@@ -272,7 +438,7 @@ export const feedbackCommand = defineJsonCommand({
         },
         negative: {
             type: "boolean",
-            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.",
+            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: {
@@ -289,13 +455,16 @@ export const feedbackCommand = defineJsonCommand({
         },
         source: {
             type: "string",
-            description: "Where the correct fact comes from: a URL, command or file. Required with --replace.",
+            description: "Where the correct fact comes from: a URL, command or file. Required with --replace, --superseded-by and --outdated.",
         },
-        "failure-mode": {
+        "superseded-by": {
             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: "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",
@@ -323,28 +492,29 @@ 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.");
-            }
-            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(", ")}`);
-            }
-        }
-        // An exact fix for the asset's text: each --replace pairs with a --with, in order.
+        // 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] ?? "" }));
-        if (replaces.length > 0 || withs.length > 0 || fixSource !== undefined) {
+        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 and --source are only for negative feedback.", "INVALID_FLAG_VALUE");
+                throw new UsageError("--replace, --with, --source, --superseded-by and --outdated are only for negative feedback.", "INVALID_FLAG_VALUE");
+            }
+            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 (replaces.length === 0 || replaces.length !== withs.length) {
+            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) {
@@ -361,8 +531,7 @@ export const feedbackCommand = defineJsonCommand({
             const requireReason = cfg.feedback?.requireReason ?? true; // Default: true (F-3 / #384)
             if (requireReason) {
                 throw new UsageError("Negative feedback requires --reason: 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]`);
+                    "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 says nothing about what is wrong.");
@@ -373,11 +542,8 @@ export const feedbackCommand = defineJsonCommand({
         const metadataObj = {
             signal,
             ...(reason?.trim() ? { reason: reason.trim() } : {}),
-            ...(failureMode ? { failureMode } : {}),
             ...(validatedTags.length > 0 ? { tags: validatedTags } : {}),
-            ...(fixPairs.length > 0 ? { fix: { source: fixSource, replacements: fixPairs.length } } : {}),
         };
-        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
@@ -432,23 +598,51 @@ export const feedbackCommand = defineJsonCommand({
             if (!itemRef)
                 throw new UsageError(`Indexed ref "${ref}" has no durable item ref.`, "INVALID_PROPOSAL");
             durableRef = itemRef;
-            if (fixPairs.length > 0) {
+            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.
-                const filePath = getEntryFilePathById(db, entryId);
                 if (!filePath || !fs.existsSync(filePath)) {
                     throw new NotFoundError(`The file for ${itemRef} is missing on disk.`, "ASSET_NOT_FOUND");
                 }
-                const resolved = resolveMutationTarget(config, parseRefInput(itemRef), undefined, { requireWritable: true });
+                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");
-                const after = applyExactReplacements(before, fixPairs, filePath);
+                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);
-                fix = { content: after, target: { source: resolved.target.source.name, root: resolved.target.source.path } };
+                // 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;
@@ -489,7 +683,6 @@ export const feedbackCommand = defineJsonCommand({
                         previousUtility: utilityResult.previousUtility,
                         nextUtility: utilityResult.nextUtility,
                         reason: reason?.trim() ?? null,
-                        failureMode: failureMode ?? null,
                     },
                 });
             }
@@ -535,12 +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 } } : {}),
+            ...(fixProposal
+                ? {
+                    fix: {
+                        proposalId: fixProposal.id,
+                        replacements: fixPairs.length,
+                        source: fixSource,
+                        ...fix?.marked,
+                    },
+                }
+                : {}),
             ...(appliedToResult
                 ? { appliedTo: { ref: appliedToResult.lessonRef, lessonStrength: appliedToResult.strength } }
                 : {}),

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

@@ -92,7 +92,7 @@ export const PAIR_JUDGE_JSON_SCHEMA = {
         reason: { type: "string", maxLength: 400 },
     },
 };
-const PAIR_CHECK_JSON_SCHEMA = {
+export const PAIR_CHECK_JSON_SCHEMA = {
     type: "object",
     required: ["missing"],
     additionalProperties: false,

package/dist/commands/improve/consolidate.js

@@ -93,7 +93,9 @@ export function isHotCapturedMemory(filePath) {
 /**
  * Structured-output schema for a plan. Promote-only: merge/delete/contradict
  * were removed in 0.9.17-alpha.1 (`e82eec811`) after running in production —
- * they cost thousands of completion tokens.
+ * they cost thousands of completion tokens. Every property is required, as a
+ * strict structured-output provider needs: an empty `description` keeps the
+ * memory's own, a null `confidence` is none.
  */
 export const CONSOLIDATE_PLAN_JSON_SCHEMA = {
     type: "object",
@@ -105,15 +107,23 @@ export const CONSOLIDATE_PLAN_JSON_SCHEMA = {
             description: "Ordered list of promote operations the planner proposes.",
             items: {
                 type: "object",
-                required: ["op", "ref", "knowledgeRef", "reason"],
+                required: ["op", "ref", "knowledgeRef", "reason", "description", "confidence"],
                 additionalProperties: false,
                 properties: {
                     op: { type: "string", enum: ["promote"] },
                     ref: { type: "string", minLength: 1 },
                     knowledgeRef: { type: "string", minLength: 1 },
                     reason: { type: "string", minLength: 1, maxLength: 200 },
-                    description: { type: "string" },
-                    confidence: { type: "number", minimum: 0, maximum: 1 },
+                    description: {
+                        type: "string",
+                        description: "One sentence describing the new knowledge asset; an empty string keeps the memory's own.",
+                    },
+                    confidence: {
+                        type: ["number", "null"],
+                        minimum: 0,
+                        maximum: 1,
+                        description: "Certainty in [0, 1] that the operation is correct and safe; null when unsure.",
+                    },
                 },
             },
         },

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";
@@ -70,9 +72,13 @@ export function deriveLessonRef(inputRef) {
     return `lessons/${safeScope ? `${safeScope}/` : ""}${clean(`${parsed.type}-${parts.join("-")}`)}-lesson`;
 }
 // ── Output contract ──────────────────────────────────────────────────────────
+//
+// The client sends a response schema `strict: true`, and a strict provider
+// (OpenAI's) rejects an object whose `required` leaves out any of its
+// properties, so every property is required and "none" is an empty array (#1046).
 export const DISTILL_LESSON_JSON_SCHEMA = {
     type: "object",
-    required: ["description", "when_to_use", "body"],
+    required: ["description", "when_to_use", "body", "tags"],
     additionalProperties: false,
     properties: {
         description: {
@@ -93,13 +99,13 @@ export const DISTILL_LESSON_JSON_SCHEMA = {
         tags: {
             type: "array",
             items: { type: "string" },
-            description: "Optional tag list. Empty array is allowed; the post-processor drops it if empty.",
+            description: "Tag list. Use an empty array for none; the post-processor drops it if empty.",
         },
     },
 };
 export const DISTILL_KNOWLEDGE_JSON_SCHEMA = {
     type: "object",
-    required: ["description", "body"],
+    required: ["description", "body", "tags", "sources"],
     additionalProperties: false,
     properties: {
         description: { type: "string", minLength: 1, description: "One-line summary of the knowledge asset." },
@@ -111,12 +117,12 @@ export const DISTILL_KNOWLEDGE_JSON_SCHEMA = {
         tags: {
             type: "array",
             items: { type: "string" },
-            description: "Optional tag list. Empty array is allowed; the post-processor drops it if empty.",
+            description: "Tag list. Use an empty array for none; the post-processor drops it if empty.",
         },
         sources: {
             type: "array",
             items: { type: "string" },
-            description: "Optional list of source refs the knowledge was distilled from.",
+            description: "Source refs the knowledge was distilled from. Use an empty array for none.",
         },
     },
 };
@@ -253,6 +259,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 +363,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 +424,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 +481,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 +544,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, {